Skip to content

fix onboarding runtime validation and first-start routing #444

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
vansin wants to merge 3 commits into from
Closed

fix onboarding runtime validation and first-start routing #444

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
98a33b0
fix(onboarding): fail early on missing runtime prerequisites
SmartFlowAITeam Jul 13, 2026
6808046
fix(onboarding): preserve runtime intent across launch paths
SmartFlowAITeam Jul 13, 2026
91e0b85
docs(onboarding): record round 2 isolated evidence
SmartFlowAITeam Jul 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions README.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,16 @@

---

## 30-second quickstart
## Quick Start

Requirements: Node.js >= 22.13.0, npm >= 10, and Bun >= 1.2.0. The Hub uses
`Bun.serve` / `bun:sqlite`, so Bun is required rather than optional:

```bash
curl -fsSL https://bun.sh/install | bash
# Open a new shell, then verify:
bun --version && bunx --version
```

```bash
# Install one global package
Expand Down Expand Up @@ -70,7 +79,7 @@ anet project restart # restart cwd nodes against the new version

Full cross-version migration reference: [Upgrade Guide](https://anet.sh/en/guide/upgrade).

<sub>Prereq: Node.js ≥ 22.13.0 (required by `@inquirer/prompts` and friends; older versions trip `EBADENGINE` warnings during install but still work).</sub>
<sub>On the first `anet node start`, the CLI fetches `agent-node` through `npx` when no global binary exists; a second global install is not required. SDK runtimes that require an API key block create/start when the key is blank, avoiding nodes that look online but cannot execute a task.</sub>

---

Expand Down Expand Up @@ -131,7 +140,7 @@ flowchart LR
H -.- DB[(SQLite<br/>~/.commhub)]
```

Node onboarding flow (0 to online in 30 seconds):
Node onboarding flow (elapsed time depends on first-run downloads and network speed):

```mermaid
flowchart LR
Expand Down Expand Up @@ -214,7 +223,7 @@ Apache-2.0, published to npm. `anet upgrade` bumps all four to `latest`.
| [`@sleep2agi/commhub-server`](https://www.npmjs.com/package/@sleep2agi/commhub-server) | MCP + REST + SSE hub (SQLite-backed) |
| [`@sleep2agi/agent-network-dashboard`](https://www.npmjs.com/package/@sleep2agi/agent-network-dashboard) | Web Dashboard — Next.js 16, 7 panels |

The CLI auto-fetches the hub and node packages on first use via `bunx` / `npx`; you only ever globally install one. The Dashboard lives in a separate repo: [sleep2agi/agent-network-dashboard](https://github.com/sleep2agi/agent-network-dashboard).
The CLI fetches the hub and node packages on first use via `bunx` / `npx`. You only globally install `agent-network`, but Bun itself must already be installed because it is the Hub runtime and is not installed automatically. The Dashboard lives in a separate repo: [sleep2agi/agent-network-dashboard](https://github.com/sleep2agi/agent-network-dashboard).

---

Expand Down Expand Up @@ -278,7 +287,7 @@ All four packages Apache 2.0, **Stable on npm `latest`**. Release cadence and fu

PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, branch naming, and the test matrix layout. By contributing you agree to the [Code of Conduct](./CODE_OF_CONDUCT.md).

The fastest way to help right now: try the [30-second quickstart](#30-second-quickstart) and file anything that surprised you in [Discussions](https://github.com/sleep2agi/agent-network/discussions) or [Issues](https://github.com/sleep2agi/agent-network/issues).
The fastest way to help right now: try the [Quick Start](#quick-start) and file anything that surprised you in [Discussions](https://github.com/sleep2agi/agent-network/discussions) or [Issues](https://github.com/sleep2agi/agent-network/issues).

---

Expand Down
19 changes: 14 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,16 @@

---

## 30 秒上手
## 快速上手

前置：Node.js >= 22.13.0、npm >= 10、Bun >= 1.2.0。Hub 使用
`Bun.serve` / `bun:sqlite`，所以 Bun 不是可选项：

```bash
curl -fsSL https://bun.sh/install | bash
# 重开终端后确认
bun --version && bunx --version
```

```bash
# 装一个全局包
Expand Down Expand Up @@ -70,7 +79,7 @@ anet project restart # 重启 cwd 节点接新版

完整跨版本迁移参考 [升级指南](https://anet.sh/guide/upgrade)。

<sub>前置：Node.js ≥ 22.13.0（`@inquirer/prompts` 等依赖要求；老版本会触发 `EBADENGINE` warnings，不影响安装）。</sub>
<sub>首次 `anet node start` 会在没有全局 `agent-node` 时通过 `npx` 拉取它；不需要手动安装第二个全局包。需要 API key 的 SDK runtime 会在 key 为空时阻止创建/启动，避免出现“在线但不能执行任务”的节点。</sub>

---

Expand Down Expand Up @@ -131,7 +140,7 @@ flowchart LR
H -.- DB[(SQLite<br/>~/.commhub)]
```

节点接入流程（从 0 到上线 30 秒）：
节点接入流程（实际耗时取决于首次下载和本机网络）：

```mermaid
flowchart LR
Expand Down Expand Up @@ -214,7 +223,7 @@ Apache-2.0，已发 npm。`anet upgrade` 一键全升 `latest`。
| [`@sleep2agi/commhub-server`](https://www.npmjs.com/package/@sleep2agi/commhub-server) | MCP + REST + SSE 通信中枢（SQLite 持久化） |
| [`@sleep2agi/agent-network-dashboard`](https://www.npmjs.com/package/@sleep2agi/agent-network-dashboard) | Web Dashboard —— Next.js 16，7 大面板 |

CLI 第一次用到 hub 和 node 时会自动用 `bunx` / `npx` 拉对应包，全局只需装一个 `agent-network`。Dashboard 是独立 repo：[sleep2agi/agent-network-dashboard](https://github.com/sleep2agi/agent-network-dashboard)。
CLI 第一次用到 hub 和 node 时会用 `bunx` / `npx` 拉对应包；全局只需安装 `agent-network`，但本机必须预装 Bun（Hub 的运行时，不会自动安装）。Dashboard 是独立 repo：[sleep2agi/agent-network-dashboard](https://github.com/sleep2agi/agent-network-dashboard)。

---

Expand Down Expand Up @@ -278,7 +287,7 @@ tests/ Docker 测试矩阵

欢迎 PR。环境搭建、分支命名、测试矩阵详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。提交即代表同意 [Code of Conduct](./CODE_OF_CONDUCT.md)。

最快帮上忙的方式：跑一遍上面的 [30 秒上手](#30-秒上手)，把任何"咦？"的地方发到 [Discussions](https://github.com/sleep2agi/agent-network/discussions) 或 [Issues](https://github.com/sleep2agi/agent-network/issues)。
最快帮上忙的方式：跑一遍上面的 [快速上手](#快速上手)，把任何"咦？"的地方发到 [Discussions](https://github.com/sleep2agi/agent-network/discussions) 或 [Issues](https://github.com/sleep2agi/agent-network/issues)。

---

Expand Down
14 changes: 14 additions & 0 deletions agent-network/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,16 @@ Install Bun if needed:
curl -fsSL https://bun.sh/install | bash
```

Open a new shell and verify both executables before starting the Hub:

```bash
bun --version
bunx --version
```

`anet hub start` checks this prerequisite before spawning anything and prints
the install command when it is missing. It never installs Bun automatically.

## Install

Stable:
Expand Down Expand Up @@ -102,6 +112,10 @@ anet node start my-bot
2. Provider preset: Anthropic, MiniMax, InternLM, Xiaomi MiMo, or `custom` (any Anthropic-compatible endpoint — used for DeepSeek / GLM / Kimi / OpenRouter etc.; codex-sdk for OpenAI Codex; grok-build-acp for xAI Grok).
3. API key and model settings.

For `claude-agent-sdk`, an empty provider key blocks node creation/start instead
of creating a node that can register but cannot answer. CLI-auth runtimes and
separately configured keyless runtimes keep their own authentication flows.

When the node starts successfully, look for:

```text
Expand Down
Loading
Loading