nodmix 2026.5.25

package/docs/concepts/oauth.md

@@ -0,0 +1,198 @@
+---
+summary: "OAuth in Nodmix: token exchange, storage, and multi-account patterns"
+read_when:
+  - You want to understand Nodmix OAuth end-to-end
+  - You hit token invalidation / logout issues
+  - You want Claude CLI or OAuth auth flows
+  - You want multiple accounts or profile routing
+title: "OAuth"
+---
+
+Nodmix supports "subscription auth" via OAuth for providers that offer it
+(notably **OpenAI Codex (ChatGPT OAuth)**). For Anthropic, the practical split
+is now:
+
+- **Anthropic API key**: normal Anthropic API billing
+- **Anthropic Claude CLI / subscription auth inside Nodmix**: Anthropic staff
+  told us this usage is allowed again
+
+OpenAI Codex OAuth is explicitly supported for use in external tools like
+Nodmix. This page explains:
+
+For Anthropic in production, API key auth is the safer recommended path.
+
+- how the OAuth **token exchange** works (PKCE)
+- where tokens are **stored** (and why)
+- how to handle **multiple accounts** (profiles + per-session overrides)
+
+Nodmix also supports **provider plugins** that ship their own OAuth or API-key
+flows. Run them via:
+
+```bash
+nodmix models auth login --provider <id>
+```
+
+## The token sink (why it exists)
+
+OAuth providers commonly mint a **new refresh token** during login/refresh flows. Some providers (or OAuth clients) can invalidate older refresh tokens when a new one is issued for the same user/app.
+
+Practical symptom:
+
+- you log in via Nodmix _and_ via Claude Code / Codex CLI → one of them randomly gets "logged out" later
+
+To reduce that, Nodmix treats `auth-profiles.json` as a **token sink**:
+
+- the runtime reads credentials from **one place**
+- we can keep multiple profiles and route them deterministically
+- external CLI reuse is provider-specific: Codex CLI can bootstrap an empty
+  `openai-codex:default` profile, but once Nodmix has a local OAuth profile,
+  the local refresh token is canonical. If that local refresh token is rejected,
+  Nodmix can use a usable same-account Codex CLI token as a runtime-only
+  fallback; other integrations can remain externally managed and re-read their
+  CLI auth store
+- status and startup paths that already know the configured provider set scope
+  external CLI discovery to that set, so an unrelated CLI login store is not
+  probed for a single-provider setup
+
+## Storage (where tokens live)
+
+Secrets are stored in agent auth stores:
+
+- Auth profiles (OAuth + API keys + optional value-level refs): `~/.nodmix/agents/<agentId>/agent/auth-profiles.json`
+- Legacy compatibility file: `~/.nodmix/agents/<agentId>/agent/auth.json`
+  (static `api_key` entries are scrubbed when discovered)
+
+Legacy import-only file (still supported, but not the main store):
+
+- `~/.nodmix/credentials/oauth.json` (imported into `auth-profiles.json` on first use)
+
+All of the above also respect `$NODMIX_STATE_DIR` (state dir override). Full reference: [/gateway/configuration](/gateway/configuration-reference#auth-storage)
+
+For static secret refs and runtime snapshot activation behavior, see [Secrets Management](/gateway/secrets).
+
+When a secondary agent has no local auth profile, Nodmix uses read-through
+inheritance from the default/main agent store. It does not clone the main
+agent's `auth-profiles.json` on read. OAuth refresh tokens are especially
+sensitive: normal copy flows skip them by default because some providers rotate
+or invalidate refresh tokens after use. Configure a separate OAuth login for an
+agent when it needs an independent account.
+
+## Anthropic legacy token compatibility
+
+<Warning>
+Anthropic's public Claude Code docs say direct Claude Code use stays within
+Claude subscription limits, and Anthropic staff told us Nodmix-style Claude
+CLI usage is allowed again. Nodmix therefore treats Claude CLI reuse and
+`claude -p` usage as sanctioned for this integration unless Anthropic
+publishes a new policy.
+
+For Anthropic's current direct-Claude-Code plan docs, see [Using Claude Code
+with your Pro or Max
+plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
+and [Using Claude Code with your Team or Enterprise
+plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/).
+
+If you want other subscription-style options in Nodmix, see [OpenAI
+Codex](/providers/openai), [Qwen Cloud Coding
+Plan](/providers/qwen), [MiniMax Coding Plan](/providers/minimax),
+and [Z.AI / GLM Coding Plan](/providers/glm).
+</Warning>
+
+Nodmix also exposes Anthropic setup-token as a supported token-auth path, but it now prefers Claude CLI reuse and `claude -p` when available.
+
+## Anthropic Claude CLI migration
+
+Nodmix supports Anthropic Claude CLI reuse again. If you already have a local
+Claude login on the host, onboarding/configure can reuse it directly.
+
+## OAuth exchange (how login works)
+
+Nodmix's interactive login flows are implemented in `@earendil-works/pi-ai` and wired into the wizards/commands.
+
+### Anthropic setup-token
+
+Flow shape:
+
+1. start Anthropic setup-token or paste-token from Nodmix
+2. Nodmix stores the resulting Anthropic credential in an auth profile
+3. model selection stays on `anthropic/...`
+4. existing Anthropic auth profiles remain available for rollback/order control
+
+### OpenAI Codex (ChatGPT OAuth)
+
+OpenAI Codex OAuth is explicitly supported for use outside the Codex CLI, including Nodmix workflows.
+
+Flow shape (PKCE):
+
+1. generate PKCE verifier/challenge + random `state`
+2. open `https://auth.openai.com/oauth/authorize?...`
+3. try to capture callback on `http://127.0.0.1:1455/auth/callback`
+4. if callback can't bind (or you're remote/headless), paste the redirect URL/code
+5. exchange at `https://auth.openai.com/oauth/token`
+6. extract `accountId` from the access token and store `{ access, refresh, expires, accountId }`
+
+Wizard path is `nodmix onboard` → auth choice `openai-codex`.
+
+## Refresh + expiry
+
+Profiles store an `expires` timestamp.
+
+At runtime:
+
+- if `expires` is in the future → use the stored access token
+- if expired → refresh (under a file lock) and overwrite the stored credentials
+- if a secondary agent reads an inherited main-agent OAuth profile, refresh
+  writes back to the main agent store instead of copying the refresh token into
+  the secondary agent store
+- exception: some external CLI credentials stay externally managed; Nodmix
+  re-reads those CLI auth stores instead of spending copied refresh tokens.
+  Codex CLI bootstrap is intentionally narrower: it seeds an empty
+  `openai-codex:default` profile, then Nodmix-owned refreshes keep the local
+  profile canonical. If the local Codex refresh fails and Codex CLI has a
+  usable token for the same account, Nodmix may use that token for the current
+  runtime request without writing it back to `auth-profiles.json`.
+
+The refresh flow is automatic; you generally don't need to manage tokens manually.
+
+## Multiple accounts (profiles) + routing
+
+Two patterns:
+
+### 1) Preferred: separate agents
+
+If you want "personal" and "work" to never interact, use isolated agents (separate sessions + credentials + workspace):
+
+```bash
+nodmix agents add work
+nodmix agents add personal
+```
+
+Then configure auth per-agent (wizard) and route chats to the right agent.
+
+### 2) Advanced: multiple profiles in one agent
+
+`auth-profiles.json` supports multiple profile IDs for the same provider.
+
+Pick which profile is used:
+
+- globally via config ordering (`auth.order`)
+- per-session via `/model ...@<profileId>`
+
+Example (session override):
+
+- `/model Opus@anthropic:work`
+
+How to see what profile IDs exist:
+
+- `nodmix channels list --json` (shows `auth[]`)
+
+Related docs:
+
+- [Model failover](/concepts/model-failover) (rotation + cooldown rules)
+- [Slash commands](/tools/slash-commands) (command surface)
+
+## Related
+
+- [Authentication](/gateway/authentication) - model provider auth overview
+- [Secrets](/gateway/secrets) - credential storage and SecretRef
+- [Configuration Reference](/gateway/configuration-reference#auth-storage) - auth config keys

package/docs/concepts/openclaw-sdk.md

@@ -0,0 +1,323 @@
+---
+summary: "Public Nodmix App SDK for external apps, scripts, dashboards, CI jobs, and IDE extensions"
+title: "Nodmix App SDK"
+sidebarTitle: "App SDK"
+read_when:
+  - You are building an external app, script, dashboard, CI job, or IDE extension that talks to Nodmix
+  - You are choosing between the App SDK and the Plugin SDK
+  - You are integrating with Gateway agent runs, sessions, events, approvals, models, or tools
+---
+
+The **Nodmix App SDK** is the public client API for apps outside the
+Nodmix process. Use `@nodmix/sdk` when a script, dashboard, CI job, IDE
+extension, or other external app wants to connect to the Gateway, start agent
+runs, stream events, wait for results, cancel work, or inspect Gateway
+resources.
+
+<Note>
+  The App SDK is different from the [Plugin SDK](/plugins/sdk-overview).
+  `@nodmix/sdk` talks to the Gateway from outside Nodmix.
+  `nodmix/plugin-sdk/*` is only for plugins that run inside Nodmix and
+  register providers, channels, tools, hooks, or trusted runtimes.
+</Note>
+
+## What ships today
+
+`@nodmix/sdk` ships with:
+
+| Surface                   | Status  | What it does                                                                      |
+| ------------------------- | ------- | --------------------------------------------------------------------------------- |
+| `Nodmix`                | Ready   | Main client entry point. Owns transport, connection, requests, and events.        |
+| `GatewayClientTransport`  | Ready   | WebSocket transport backed by the Gateway client.                                 |
+| `oc.agents`               | Ready   | Lists, creates, updates, deletes, and gets agent handles.                         |
+| `Agent.run()`             | Ready   | Starts a Gateway `agent` run and returns a `Run`.                                 |
+| `oc.runs`                 | Ready   | Creates, gets, waits for, cancels, and streams runs.                              |
+| `Run.events()`            | Ready   | Streams normalized per-run events with replay for fast runs.                      |
+| `Run.wait()`              | Ready   | Calls `agent.wait` and returns a stable `RunResult`.                              |
+| `Run.cancel()`            | Ready   | Calls `sessions.abort` by run id, with session key when available.                |
+| `oc.sessions`             | Ready   | Creates, resolves, sends to, patches, compacts, and gets session handles.         |
+| `Session.send()`          | Ready   | Calls `sessions.send` and returns a `Run`.                                        |
+| `oc.tasks`                | Ready   | Lists, reads, and cancels Gateway task ledger entries.                            |
+| `oc.models`               | Ready   | Calls `models.list` and the current `models.authStatus` status RPC.               |
+| `oc.tools`                | Ready   | Lists, scopes, and invokes Gateway tools through the policy pipeline.             |
+| `oc.artifacts`            | Ready   | Lists, gets, and downloads Gateway transcript artifacts.                          |
+| `oc.approvals`            | Ready   | Lists and resolves exec approvals through Gateway approval RPCs.                  |
+| `oc.environments`         | Partial | Lists Gateway-local and node environment candidates; create/delete are not wired. |
+| `oc.rawEvents()`          | Ready   | Exposes raw Gateway events for advanced consumers.                                |
+| `normalizeGatewayEvent()` | Ready   | Converts raw Gateway events into the stable SDK event shape.                      |
+
+The SDK also exports the core types used by those surfaces:
+`AgentRunParams`, `RunResult`, `RunStatus`, `NodmixEvent`,
+`NodmixEventType`, `GatewayEvent`, `NodmixTransport`,
+`GatewayRequestOptions`, `SessionCreateParams`, `SessionSendParams`,
+`ArtifactSummary`, `ArtifactQuery`, `ArtifactsListResult`,
+`ArtifactsGetResult`, `ArtifactsDownloadResult`,
+`TaskSummary`, `TaskStatus`, `TasksListParams`, `TasksListResult`,
+`TasksGetResult`, `TasksCancelResult`, `RuntimeSelection`,
+`EnvironmentSelection`, `WorkspaceSelection`, `ApprovalMode`, and related
+result types.
+
+## Connect to a Gateway
+
+Create a client with an explicit Gateway URL, or inject a custom transport for
+tests and embedded app runtimes.
+
+```typescript
+import { Nodmix } from "@nodmix/sdk";
+
+const oc = new Nodmix({
+  url: "ws://127.0.0.1:18789",
+  token: process.env.NODMIX_GATEWAY_TOKEN,
+  requestTimeoutMs: 30_000,
+});
+
+await oc.connect();
+```
+
+`new Nodmix({ gateway: "ws://..." })` is equivalent to `url`. The
+`gateway: "auto"` option is accepted by the constructor, but automatic Gateway
+discovery is not a separate SDK feature yet; pass `url` when the app does not
+already know how to discover the Gateway.
+
+For tests, pass an object that implements `NodmixTransport`:
+
+```typescript
+const oc = new Nodmix({
+  transport: {
+    async request(method, params) {
+      return { method, params };
+    },
+    async *events() {},
+  },
+});
+```
+
+## Run an agent
+
+Use `oc.agents.get(id)` when the app wants an agent handle, then call
+`agent.run()`.
+
+```typescript
+const agent = await oc.agents.get("main");
+
+const run = await agent.run({
+  input: "Review this pull request and suggest the smallest safe fix.",
+  model: "openai/gpt-5.5",
+  sessionKey: "main",
+  timeoutMs: 30_000,
+});
+
+for await (const event of run.events()) {
+  const data = event.data as { delta?: unknown };
+  if (event.type === "assistant.delta" && typeof data.delta === "string") {
+    process.stdout.write(data.delta);
+  }
+}
+
+const result = await run.wait({ timeoutMs: 120_000 });
+console.log(result.status);
+```
+
+Provider-qualified model refs such as `openai/gpt-5.5` are split into Gateway
+`provider` and `model` overrides. `timeoutMs` stays milliseconds in the SDK and
+is converted to Gateway timeout seconds for the `agent` RPC.
+
+`run.wait()` uses the Gateway `agent.wait` RPC. A wait deadline that expires
+while the run is still active returns `status: "accepted"` instead of pretending
+the run itself timed out. Runtime timeouts, aborted runs, and cancelled runs are
+normalized into `timed_out` or `cancelled`.
+
+## Create and reuse sessions
+
+Use sessions when the app wants durable transcript state.
+
+```typescript
+const session = await oc.sessions.create({
+  agentId: "main",
+  label: "release-review",
+});
+
+const run = await session.send("Prepare release notes from the current diff.");
+await run.wait();
+```
+
+`Session.send()` calls `sessions.send` and returns a `Run`. Session handles also
+support:
+
+```typescript
+await session.abort(run.id);
+await session.patch({ label: "renamed-session" });
+await session.compact({ maxLines: 200 });
+```
+
+## Stream events
+
+The SDK normalizes raw Gateway events into a stable `NodmixEvent` envelope:
+
+```typescript
+type NodmixEvent = {
+  version: 1;
+  id: string;
+  ts: number;
+  type: NodmixEventType;
+  runId?: string;
+  sessionId?: string;
+  sessionKey?: string;
+  taskId?: string;
+  agentId?: string;
+  data: unknown;
+  raw?: GatewayEvent;
+};
+```
+
+Common event types include:
+
+| Event type            | Source Gateway event                        |
+| --------------------- | ------------------------------------------- |
+| `run.started`         | `agent` lifecycle start                     |
+| `run.completed`       | `agent` lifecycle end                       |
+| `run.failed`          | `agent` lifecycle error                     |
+| `run.cancelled`       | Aborted/cancelled lifecycle end             |
+| `run.timed_out`       | Timeout lifecycle end                       |
+| `assistant.delta`     | Assistant streaming delta                   |
+| `assistant.message`   | Assistant message                           |
+| `thinking.delta`      | Thinking or plan stream                     |
+| `tool.call.started`   | Tool/item/command start                     |
+| `tool.call.delta`     | Tool/item/command update                    |
+| `tool.call.completed` | Tool/item/command completion                |
+| `tool.call.failed`    | Tool/item/command failure or blocked status |
+| `approval.requested`  | Exec or plugin approval request             |
+| `approval.resolved`   | Exec or plugin approval resolution          |
+| `session.created`     | `sessions.changed` create                   |
+| `session.updated`     | `sessions.changed` update                   |
+| `session.compacted`   | `sessions.changed` compaction               |
+| `task.updated`        | Task update events                          |
+| `artifact.updated`    | Patch stream events                         |
+| `raw`                 | Any event without a stable SDK mapping yet  |
+
+`Run.events()` filters events to one run id and replays already-seen events for
+fast runs. That means the documented flow is safe:
+
+```typescript
+const run = await agent.run("Summarize the latest session.");
+
+for await (const event of run.events()) {
+  if (event.type === "run.completed") {
+    break;
+  }
+}
+```
+
+For app-wide streams, use `oc.events()`. For raw Gateway frames, use
+`oc.rawEvents()`.
+
+## Models, tools, artifacts, and approvals
+
+Model helpers map to current Gateway methods:
+
+```typescript
+await oc.models.list();
+await oc.models.status({ probe: false }); // calls models.authStatus
+```
+
+Tool helpers expose the Gateway catalog, effective tool view, and direct
+Gateway tool invocation. `oc.tools.invoke()` returns a typed envelope instead
+of throwing for policy or approval refusals.
+
+```typescript
+await oc.tools.list();
+await oc.tools.effective({ sessionKey: "main" });
+await oc.tools.invoke("tool-name", {
+  args: { input: "value" },
+  sessionKey: "main",
+  confirm: false,
+  idempotencyKey: "tool-call-1",
+});
+```
+
+Artifact helpers expose the Gateway artifact projection for session, run, or
+task context. Each call requires one explicit `sessionKey`, `runId`, or
+`taskId` scope:
+
+```typescript
+const { artifacts } = await oc.artifacts.list({ sessionKey: "main" });
+const first = artifacts[0];
+
+if (first) {
+  const { artifact } = await oc.artifacts.get(first.id, { sessionKey: "main" });
+  const download = await oc.artifacts.download(artifact.id, { sessionKey: "main" });
+  console.log(download.encoding, download.url);
+}
+```
+
+Approval helpers use the exec approval RPCs:
+
+```typescript
+const approvals = await oc.approvals.list();
+await oc.approvals.respond("approval-id", { decision: "approve" });
+```
+
+Task helpers use the durable task ledger that also backs `nodmix tasks`:
+
+```typescript
+const tasks = await oc.tasks.list({ status: "running", sessionKey: "agent:main:main" });
+const task = await oc.tasks.get(tasks.tasks[0].id);
+await oc.tasks.cancel(task.task.id, { reason: "user stopped task" });
+```
+
+Environment helpers expose read-only Gateway-local and node discovery:
+
+```typescript
+const { environments } = await oc.environments.list();
+await oc.environments.status(environments[0].id);
+```
+
+## Explicitly unsupported today
+
+The SDK includes names for the product model we want, but it does not silently
+pretend Gateway RPCs exist. These calls currently throw explicit unsupported
+errors:
+
+```typescript
+await oc.environments.create({});
+await oc.environments.delete("environment-id");
+```
+
+Per-run `workspace`, `runtime`, `environment`, and `approvals` fields are typed
+as future shape, but the current Gateway does not support those overrides on
+the `agent` RPC. If callers pass them, the SDK throws before submitting the run
+so work does not accidentally execute with default workspace, runtime,
+environment, or approval behavior.
+
+## App SDK vs Plugin SDK
+
+Use the App SDK when code lives outside Nodmix:
+
+- Node scripts that start or observe agent runs
+- CI jobs that call a Gateway
+- dashboards and admin panels
+- IDE extensions
+- external bridges that do not need to become channel plugins
+- integration tests with fake or real Gateway transports
+
+Use the Plugin SDK when code runs inside Nodmix:
+
+- provider plugins
+- channel plugins
+- tool or lifecycle hooks
+- agent harness plugins
+- trusted runtime helpers
+
+App SDK code should import from `@nodmix/sdk`. Plugin code should import from
+documented `nodmix/plugin-sdk/*` subpaths. Do not mix the two contracts.
+
+## Related
+
+- [Nodmix App SDK API design](/reference/nodmix-sdk-api-design)
+- [Gateway RPC reference](/reference/rpc)
+- [Agent loop](/concepts/agent-loop)
+- [Agent runtimes](/concepts/agent-runtimes)
+- [Sessions](/concepts/session)
+- [Background tasks](/automation/tasks)
+- [ACP agents](/tools/acp-agents)
+- [Plugin SDK overview](/plugins/sdk-overview)

package/docs/concepts/parallel-specialist-lanes.md

@@ -0,0 +1,127 @@
+---
+summary: "Run parallel specialist agents without clogging shared model and tool capacity"
+title: "Parallel specialist lanes"
+sidebarTitle: "Specialist lanes"
+read_when:
+  - You route group chats to dedicated agents
+  - You want parallel work without one long task blocking every chat
+  - You are designing a multi-agent operations setup
+status: active
+---
+
+Parallel specialist lanes let one Gateway route different chats or rooms to
+different agents, while keeping the user experience fast. The trick is to treat
+parallelism as a scarce-resource design problem, not just as "more agents".
+
+## First principles
+
+A specialist lane only improves throughput when it reduces contention for the
+real bottlenecks:
+
+- **Session locks**: only one run should mutate a given session at a time.
+- **Global model capacity**: all visible chat runs still share provider limits.
+- **Tool capacity**: shell, browser, network, and repository work can be slower
+  than the model turn itself.
+- **Context budget**: long transcripts make every future turn slower and less
+  focused.
+- **Ownership ambiguity**: duplicate agents doing the same job waste capacity.
+
+Nodmix already serializes runs per session and caps global parallelism through
+the [command queue](/concepts/queue). Specialist lanes add policy on top:
+which agent owns which work, what stays in chat, and what becomes background
+work.
+
+## Recommended rollout
+
+### Phase 1: lane contracts + background heavy work
+
+Give every lane a written contract in its workspace and system prompt:
+
+- **Purpose**: the work this lane owns.
+- **Non-goals**: work it should hand off instead of attempting.
+- **Chat budget**: quick answers stay in chat; long tasks should acknowledge
+  briefly, then run in a background sub-agent or task.
+- **Handoff rule**: when another lane owns the work, say where it should go and
+  provide a compact handoff summary.
+- **Tool-risk rule**: prefer the smallest tool surface that can do the job.
+
+This is the cheapest phase and fixes most clogging: one coding job no longer
+turns the research lane into molasses, and each chat keeps its own context clean.
+
+### Phase 2: priority and concurrency controls
+
+Tune queue and model capacity around the business value of each lane:
+
+```json5
+{
+  agents: {
+    defaults: {
+      maxConcurrent: 4,
+      subagents: { maxConcurrent: 8, delegationMode: "prefer" },
+    },
+  },
+  messages: {
+    queue: {
+      mode: "collect",
+      debounceMs: 1000,
+      cap: 20,
+      drop: "summarize",
+    },
+  },
+}
+```
+
+Use direct/personal chats and production-ops agents for high-priority work. Let
+research, drafting, and batch coding move to background tasks when the system is
+busy.
+
+### Phase 3: coordinator / traffic controller
+
+Add a small coordinator pattern once multiple lanes are active:
+
+- Track active lane tasks and owners.
+- Detect duplicate requests across groups.
+- Route handoff summaries between lanes.
+- Surface only blockers, completed results, and decisions the human must make.
+
+Do not start here. A coordinator without lane contracts just coordinates chaos.
+
+## Minimal lane contract template
+
+```md
+# Lane contract
+
+## Owns
+
+- <job this lane is responsible for>
+
+## Does not own
+
+- <work to hand off>
+
+## Chat budget
+
+- Answer quick questions directly.
+- For multi-step, slow, or tool-heavy work: acknowledge briefly, spawn/background
+  the work, then return the result when complete.
+
+## Handoff
+
+If another lane owns the request, reply with:
+
+- target lane
+- objective
+- relevant context
+- exact next action
+
+## Tool posture
+
+Use the smallest tool surface that can complete the task. Avoid broad shell or
+network work unless this lane explicitly owns it.
+```
+
+## Related
+
+- [Multi-agent routing](/concepts/multi-agent)
+- [Command queue](/concepts/queue)
+- [Sub-agents](/tools/subagents)