nodmix 2026.5.25

package/docs/providers/xiaomi.md

@@ -0,0 +1,188 @@
+---
+summary: "Use Xiaomi MiMo models with Nodmix"
+read_when:
+  - You want Xiaomi MiMo models in Nodmix
+  - You need XIAOMI_API_KEY setup
+title: "Xiaomi MiMo"
+---
+
+Xiaomi MiMo is the API platform for **MiMo** models. Nodmix includes a bundled `xiaomi` plugin that registers both an OpenAI-compatible chat provider and a speech (TTS) provider against the same `XIAOMI_API_KEY`.
+
+| Property        | Value                                    |
+| --------------- | ---------------------------------------- |
+| Provider id     | `xiaomi`                                 |
+| Plugin          | bundled, `enabledByDefault: true`        |
+| Auth env var    | `XIAOMI_API_KEY`                         |
+| Onboarding flag | `--auth-choice xiaomi-api-key`           |
+| Direct CLI flag | `--xiaomi-api-key <key>`                 |
+| Contracts       | chat completions + `speechProviders`     |
+| API             | OpenAI-compatible (`openai-completions`) |
+| Base URL        | `https://api.xiaomimimo.com/v1`          |
+| Default model   | `xiaomi/mimo-v2-flash`                   |
+| TTS default     | `mimo-v2.5-tts`, voice `mimo_default`    |
+
+## Getting started
+
+<Steps>
+  <Step title="Get an API key">
+    Create an API key in the [Xiaomi MiMo console](https://platform.xiaomimimo.com/#/console/api-keys).
+  </Step>
+  <Step title="Run onboarding">
+    ```bash
+    nodmix onboard --auth-choice xiaomi-api-key
+    ```
+
+    Or pass the key directly:
+
+    ```bash
+    nodmix onboard --auth-choice xiaomi-api-key --xiaomi-api-key "$XIAOMI_API_KEY"
+    ```
+
+  </Step>
+  <Step title="Verify the model is available">
+    ```bash
+    nodmix models list --provider xiaomi
+    ```
+  </Step>
+</Steps>
+
+## Built-in catalog
+
+| Model ref              | Input       | Context   | Max output | Reasoning | Notes         |
+| ---------------------- | ----------- | --------- | ---------- | --------- | ------------- |
+| `xiaomi/mimo-v2-flash` | text        | 262,144   | 8,192      | No        | Default model |
+| `xiaomi/mimo-v2-pro`   | text        | 1,048,576 | 32,000     | Yes       | Large context |
+| `xiaomi/mimo-v2-omni`  | text, image | 262,144   | 32,000     | Yes       | Multimodal    |
+
+<Tip>
+The default model ref is `xiaomi/mimo-v2-flash`. The provider is injected automatically when `XIAOMI_API_KEY` is set or an auth profile exists.
+</Tip>
+
+## Text-to-speech
+
+The bundled `xiaomi` plugin also registers Xiaomi MiMo as a speech provider for
+`messages.tts`. It calls Xiaomi's chat-completions TTS contract with the text as
+an `assistant` message and optional style guidance as a `user` message.
+
+| Property | Value                                    |
+| -------- | ---------------------------------------- |
+| TTS id   | `xiaomi` (`mimo` alias)                  |
+| Auth     | `XIAOMI_API_KEY`                         |
+| API      | `POST /v1/chat/completions` with `audio` |
+| Default  | `mimo-v2.5-tts`, voice `mimo_default`    |
+| Output   | MP3 by default; WAV when configured      |
+
+```json5
+{
+  messages: {
+    tts: {
+      auto: "always",
+      provider: "xiaomi",
+      providers: {
+        xiaomi: {
+          apiKey: "xiaomi_api_key",
+          model: "mimo-v2.5-tts",
+          voice: "mimo_default",
+          format: "mp3",
+          style: "Bright, natural, conversational tone.",
+        },
+      },
+    },
+  },
+}
+```
+
+Supported built-in voices include `mimo_default`, `default_zh`, `default_en`,
+`Mia`, `Chloe`, `Milo`, and `Dean`. `mimo-v2-tts` is supported for older MiMo
+TTS accounts; the default uses the current MiMo-V2.5 TTS model. For voice-note
+targets such as Feishu and Telegram, Nodmix transcodes Xiaomi output to 48kHz
+Opus with `ffmpeg` before delivery.
+
+## Config example
+
+```json5
+{
+  env: { XIAOMI_API_KEY: "your-key" },
+  agents: { defaults: { model: { primary: "xiaomi/mimo-v2-flash" } } },
+  models: {
+    mode: "merge",
+    providers: {
+      xiaomi: {
+        baseUrl: "https://api.xiaomimimo.com/v1",
+        api: "openai-completions",
+        apiKey: "XIAOMI_API_KEY",
+        models: [
+          {
+            id: "mimo-v2-flash",
+            name: "Xiaomi MiMo V2 Flash",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 262144,
+            maxTokens: 8192,
+          },
+          {
+            id: "mimo-v2-pro",
+            name: "Xiaomi MiMo V2 Pro",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 1048576,
+            maxTokens: 32000,
+          },
+          {
+            id: "mimo-v2-omni",
+            name: "Xiaomi MiMo V2 Omni",
+            reasoning: true,
+            input: ["text", "image"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 262144,
+            maxTokens: 32000,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+<AccordionGroup>
+  <Accordion title="Auto-injection behavior">
+    The `xiaomi` provider is injected automatically when `XIAOMI_API_KEY` is set in your environment or an auth profile exists. You do not need to manually configure the provider unless you want to override model metadata or the base URL.
+  </Accordion>
+
+  <Accordion title="Model details">
+    - **mimo-v2-flash** — lightweight and fast, ideal for general-purpose text tasks. No reasoning support.
+    - **mimo-v2-pro** — supports reasoning with a 1M token context window for long-document workloads.
+    - **mimo-v2-omni** — reasoning-enabled multimodal model that accepts both text and image inputs.
+
+    <Note>
+    All models use the `xiaomi/` prefix (for example `xiaomi/mimo-v2-pro`).
+    </Note>
+
+  </Accordion>
+
+  <Accordion title="Troubleshooting">
+    - If models do not appear, confirm `XIAOMI_API_KEY` is set and valid.
+    - When the Gateway runs as a daemon, ensure the key is available to that process (for example in `~/.nodmix/.env` or via `env.shellEnv`).
+
+    <Warning>
+    Keys set only in your interactive shell are not visible to daemon-managed gateway processes. Use `~/.nodmix/.env` or `env.shellEnv` config for persistent availability.
+    </Warning>
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+  <Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
+    Full Nodmix configuration reference.
+  </Card>
+  <Card title="Xiaomi MiMo console" href="https://platform.xiaomimimo.com" icon="arrow-up-right-from-square">
+    Xiaomi MiMo dashboard and API key management.
+  </Card>
+</CardGroup>

package/docs/providers/zai.md

@@ -0,0 +1,203 @@
+---
+summary: "Use Z.AI (GLM models) with Nodmix"
+read_when:
+  - You want Z.AI / GLM models in Nodmix
+  - You need a simple ZAI_API_KEY setup
+title: "Z.AI"
+---
+
+Z.AI is the API platform for **GLM** models. It provides REST APIs for GLM and uses API keys
+for authentication. Create your API key in the Z.AI console. Nodmix uses the `zai` provider
+with a Z.AI API key.
+
+- Provider: `zai`
+- Auth: `ZAI_API_KEY`
+- API: Z.AI Chat Completions (Bearer auth)
+
+## Getting started
+
+<Tabs>
+  <Tab title="Auto-detect endpoint">
+    **Best for:** most users. Nodmix detects the matching Z.AI endpoint from the key and applies the correct base URL automatically.
+
+    <Steps>
+      <Step title="Run onboarding">
+        ```bash
+        nodmix onboard --auth-choice zai-api-key
+        ```
+      </Step>
+      <Step title="Set a default model">
+        ```json5
+        {
+          env: { ZAI_API_KEY: "sk-..." },
+          agents: { defaults: { model: { primary: "zai/glm-5.1" } } },
+        }
+        ```
+      </Step>
+      <Step title="Verify the model is listed">
+        ```bash
+        nodmix models list --all --provider zai
+        ```
+      </Step>
+    </Steps>
+
+  </Tab>
+
+  <Tab title="Explicit regional endpoint">
+    **Best for:** users who want to force a specific Coding Plan or general API surface.
+
+    <Steps>
+      <Step title="Pick the right onboarding choice">
+        ```bash
+        # Coding Plan Global (recommended for Coding Plan users)
+        nodmix onboard --auth-choice zai-coding-global
+
+        # Coding Plan CN (China region)
+        nodmix onboard --auth-choice zai-coding-cn
+
+        # General API
+        nodmix onboard --auth-choice zai-global
+
+        # General API CN (China region)
+        nodmix onboard --auth-choice zai-cn
+        ```
+      </Step>
+      <Step title="Set a default model">
+        ```json5
+        {
+          env: { ZAI_API_KEY: "sk-..." },
+          agents: { defaults: { model: { primary: "zai/glm-5.1" } } },
+        }
+        ```
+      </Step>
+      <Step title="Verify the model is listed">
+        ```bash
+        nodmix models list --all --provider zai
+        ```
+      </Step>
+    </Steps>
+
+  </Tab>
+</Tabs>
+
+## Built-in catalog
+
+Nodmix ships the bundled `zai` provider catalog in the plugin manifest, so read-only
+listing can show known GLM rows without loading provider runtime:
+
+```bash
+nodmix models list --all --provider zai
+```
+
+The manifest-backed catalog currently includes:
+
+| Model ref            | Notes         |
+| -------------------- | ------------- |
+| `zai/glm-5.1`        | Default model |
+| `zai/glm-5`          |               |
+| `zai/glm-5-turbo`    |               |
+| `zai/glm-5v-turbo`   |               |
+| `zai/glm-4.7`        |               |
+| `zai/glm-4.7-flash`  |               |
+| `zai/glm-4.7-flashx` |               |
+| `zai/glm-4.6`        |               |
+| `zai/glm-4.6v`       |               |
+| `zai/glm-4.5`        |               |
+| `zai/glm-4.5-air`    |               |
+| `zai/glm-4.5-flash`  |               |
+| `zai/glm-4.5v`       |               |
+
+<Tip>
+GLM models are available as `zai/<model>` (example: `zai/glm-5`). The default bundled model ref is `zai/glm-5.1`.
+</Tip>
+
+## Advanced configuration
+
+<AccordionGroup>
+  <Accordion title="Forward-resolving unknown GLM-5 models">
+    Unknown `glm-5*` ids still forward-resolve on the bundled provider path by
+    synthesizing provider-owned metadata from the `glm-4.7` template when the id
+    matches the current GLM-5 family shape.
+  </Accordion>
+
+  <Accordion title="Tool-call streaming">
+    `tool_stream` is enabled by default for Z.AI tool-call streaming. To disable it:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          models: {
+            "zai/<model>": {
+              params: { tool_stream: false },
+            },
+          },
+        },
+      },
+    }
+    ```
+
+  </Accordion>
+
+  <Accordion title="Thinking and preserved thinking">
+    Z.AI thinking follows Nodmix's `/think` controls. With thinking off,
+    Nodmix sends `thinking: { type: "disabled" }` to avoid responses that
+    spend the output budget on `reasoning_content` before visible text.
+
+    Preserved thinking is opt-in because Z.AI requires the full historical
+    `reasoning_content` to be replayed, which increases prompt tokens. Enable it
+    per model:
+
+    ```json5
+    {
+      agents: {
+        defaults: {
+          models: {
+            "zai/glm-5.1": {
+              params: { preserveThinking: true },
+            },
+          },
+        },
+      },
+    }
+    ```
+
+    When enabled and thinking is on, Nodmix sends
+    `thinking: { type: "enabled", clear_thinking: false }` and replays prior
+    `reasoning_content` for the same OpenAI-compatible transcript.
+
+    Advanced users can still override the exact provider payload with
+    `params.extra_body.thinking`.
+
+  </Accordion>
+
+  <Accordion title="Image understanding">
+    The bundled Z.AI plugin registers image understanding.
+
+    | Property      | Value       |
+    | ------------- | ----------- |
+    | Model         | `glm-4.6v`  |
+
+    Image understanding is auto-resolved from the configured Z.AI auth — no
+    additional config is needed.
+
+  </Accordion>
+
+  <Accordion title="Auth details">
+    - Z.AI uses Bearer auth with your API key.
+    - The `zai-api-key` onboarding choice auto-detects the matching Z.AI endpoint from the key prefix.
+    - Use the explicit regional choices (`zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn`) when you want to force a specific API surface.
+
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="GLM model family" href="/providers/glm" icon="microchip">
+    Model family overview for GLM.
+  </Card>
+  <Card title="Model selection" href="/concepts/model-providers" icon="layers">
+    Choosing providers, model refs, and failover behavior.
+  </Card>
+</CardGroup>

package/docs/refactor/access.md

@@ -0,0 +1,9 @@
+---
+summary: "Redirect to /refactor/ingress-core"
+read_when:
+  - Changing channel ingress, sender access, command authorization, or access-group handling
+title: "Channel access cleanup"
+sidebarTitle: "Channel access cleanup"
+---
+
+The channel access cleanup plan now lives in [Ingress core deletion plan](/refactor/ingress-core).

package/docs/refactor/acp.md

@@ -0,0 +1,298 @@
+---
+summary: "Migration plan for making ACP session and ACPX process ownership explicit"
+read_when:
+  - Refactoring ACP session lifecycle or ACPX process cleanup
+  - Debugging ACPX orphan processes, PID reuse, or multi-gateway cleanup safety
+  - Changing sessions_list visibility for spawned ACP or subagent sessions
+  - Designing ownership metadata for background tasks, ACP sessions, or process leases
+title: "ACP lifecycle refactor"
+sidebarTitle: "ACP lifecycle refactor"
+---
+
+ACP lifecycle currently works, but too much of it is inferred after the fact.
+Process cleanup reconstructs ownership from PIDs, command strings, wrapper
+paths, and the live process table. Session visibility reconstructs ownership
+from session-key strings plus secondary `sessions.list({ spawnedBy })` lookups.
+That makes narrow fixes possible, but it also makes edge cases easy to miss:
+PID reuse, quoted commands, adapter grandchildren, multi-gateway state roots,
+`cancel` versus `close`, and `tree` versus `all` visibility all become separate
+places to rediscover the same ownership rules.
+
+This refactor makes ownership first-class. The goal is not a new ACP product
+surface; it is a safer internal contract for the existing ACP and ACPX behavior.
+
+## Goals
+
+- Cleanup never signals a process unless current live evidence matches an
+  Nodmix-owned lease.
+- `cancel`, `close`, and startup reaping have distinct lifecycle intents.
+- `sessions_list`, `sessions_history`, `sessions_send`, and status checks use
+  the same requester-owned session model.
+- Multi-gateway installs cannot reap each other's ACPX wrappers.
+- Old ACPX session records keep working during migration.
+- The runtime remains plugin-owned; core does not learn ACPX package details.
+
+## Non-goals
+
+- Replacing ACPX or changing the public `/acp` command surface.
+- Moving vendor-specific ACP adapter behavior into core.
+- Requiring users to manually clean state before upgrading.
+- Making `cancel` close reusable ACP sessions.
+
+## Target Model
+
+### Gateway Instance Identity
+
+Each Gateway process should have a stable runtime instance id:
+
+```ts
+type GatewayInstanceId = string;
+```
+
+It can be generated on Gateway startup and persisted in state for the life of
+that install. It is not a security secret; it is an ownership discriminator used
+to avoid confusing one Gateway's ACP processes with another Gateway's processes.
+
+### ACP Session Ownership
+
+Every spawned ACP session should have normalized ownership metadata:
+
+```ts
+type AcpSessionOwner = {
+  sessionKey: string;
+  spawnedBy?: string;
+  parentSessionKey?: string;
+  ownerSessionKey: string;
+  agentId: string;
+  backend: "acpx";
+  gatewayInstanceId: GatewayInstanceId;
+  createdAt: number;
+};
+```
+
+The Gateway should return these fields on session rows where they are known.
+Visibility filtering should be a pure check over row metadata:
+
+```ts
+canSeeSessionRow({
+  row,
+  requesterSessionKey,
+  visibility,
+  a2aPolicy,
+});
+```
+
+That removes hidden secondary `sessions.list({ spawnedBy })` calls from
+visibility checks. A spawned cross-agent ACP child is requester-owned because
+the row says so, not because a second query happens to find it.
+
+### ACPX Process Leases
+
+Every generated wrapper launch should create a lease record:
+
+```ts
+type AcpxProcessLease = {
+  leaseId: string;
+  gatewayInstanceId: GatewayInstanceId;
+  sessionKey: string;
+  wrapperRoot: string;
+  wrapperPath: string;
+  rootPid: number;
+  processGroupId?: number;
+  commandHash: string;
+  startedAt: number;
+  state: "open" | "closing" | "closed" | "lost";
+};
+```
+
+The wrapper process should receive the lease id and gateway instance id in its
+environment:
+
+```sh
+NODMIX_ACPX_LEASE_ID=...
+NODMIX_GATEWAY_INSTANCE_ID=...
+```
+
+When the platform allows it, verification should prefer live process metadata
+that cannot be confused by command quoting:
+
+- root PID still exists
+- live wrapper path is under `wrapperRoot`
+- process group matches the lease when available
+- environment contains the expected lease id when readable
+- command hash or executable path matches the lease
+
+If the live process cannot be verified, cleanup fails closed.
+
+## Lifecycle Controller
+
+Introduce one ACPX lifecycle controller that owns process leases and cleanup
+policy:
+
+```ts
+interface AcpxLifecycleController {
+  ensureSession(input: AcpRuntimeEnsureInput): Promise<AcpRuntimeHandle>;
+  cancelTurn(handle: AcpRuntimeHandle): Promise<void>;
+  closeSession(input: {
+    handle: AcpRuntimeHandle;
+    discardPersistentState?: boolean;
+    reason?: string;
+  }): Promise<void>;
+  reapStartupOrphans(): Promise<void>;
+  verifyOwnedTree(lease: AcpxProcessLease): Promise<OwnedProcessTree | null>;
+}
+```
+
+`cancelTurn` requests turn cancellation only. It must not reap reusable wrapper
+or adapter processes.
+
+`closeSession` is allowed to reap, but only after loading the session record,
+loading the lease, and verifying the live process tree still belongs to that
+lease.
+
+`reapStartupOrphans` starts from open leases in state. It may use the process
+table to find descendants, but it should not scan arbitrary ACP-looking
+commands first and then decide they are probably ours.
+
+## Wrapper Contract
+
+Generated wrappers should stay small. They should:
+
+- start the adapter in a process group where supported
+- forward normal termination signals to the process group
+- detect parent death
+- on parent death, send SIGTERM, then keep the wrapper alive until the SIGKILL
+  fallback runs
+- report root PID and process group id back to the lifecycle controller when
+  that is available
+
+Wrappers should not decide session policy. They only enforce local process-tree
+cleanup for their own adapter group.
+
+## Session Visibility Contract
+
+Visibility should use normalized row ownership:
+
+```ts
+type SessionVisibilityInput = {
+  requesterSessionKey: string;
+  row: {
+    key: string;
+    agentId: string;
+    ownerSessionKey?: string;
+    spawnedBy?: string;
+    parentSessionKey?: string;
+  };
+  visibility: "self" | "tree" | "agent" | "all";
+  a2aPolicy: AgentToAgentPolicy;
+};
+```
+
+Rules:
+
+- `self`: only the requester session.
+- `tree`: requester session plus rows owned by or spawned from the requester.
+- `all`: all same-agent rows, a2a-allowed cross-agent rows, and requester-owned
+  spawned cross-agent rows even when general a2a is disabled.
+- `agent`: same agent only, unless an explicit owner relationship says the row
+  belongs to the requester.
+
+This makes `tree` and `all` monotonic: `all` must not hide an owned child that
+`tree` would show.
+
+## Migration Plan
+
+### Phase 1: Add Identity And Leases
+
+- Add `gatewayInstanceId` to Gateway state.
+- Add an ACPX lease store under the ACPX state directory.
+- Write a lease before spawning a generated wrapper.
+- Store `leaseId` on new ACPX session records.
+- Keep existing PID and command fields for old records.
+
+### Phase 2: Lease-First Cleanup
+
+- Change close cleanup to load `leaseId` first.
+- Verify live process ownership against the lease before signaling.
+- Keep the current root PID and wrapper-root fallback only for legacy records.
+- Mark leases `closed` after verified cleanup.
+- Mark leases `lost` when the process is gone before cleanup.
+
+### Phase 3: Lease-First Startup Reaping
+
+- Startup reaping scans open leases.
+- For each lease, verify the root process and collect descendants.
+- Reap verified trees children-first.
+- Expire old `closed` and `lost` leases with a bounded retention window.
+- Keep command-marker scanning only as a temporary legacy fallback, guarded by
+  wrapper root and Gateway instance where possible.
+
+### Phase 4: Session Ownership Rows
+
+- Add ownership metadata to Gateway session rows.
+- Teach ACPX, subagent, background-task, and session-store writers to populate
+  `ownerSessionKey` or `spawnedBy`.
+- Convert session visibility checks to use row metadata.
+- Remove visibility-time secondary `sessions.list({ spawnedBy })` lookups.
+
+### Phase 5: Remove Legacy Heuristics
+
+After one release window:
+
+- stop relying on stored root command strings for non-legacy ACPX cleanup
+- remove command-marker startup scans
+- remove visibility fallback list lookups
+- keep defensive fail-closed behavior for missing or unverifiable leases
+
+## Tests
+
+Add two table-driven suites.
+
+Process lifecycle simulator:
+
+- PID reused by unrelated process
+- PID reused by another Gateway's wrapper root
+- stored wrapper command is shell-quoted, live `ps` command is not
+- adapter child exits, grandchild remains in the process group
+- parent death SIGTERM fallback reaches SIGKILL
+- process listing unavailable
+- stale lease with missing process
+- startup orphan with wrapper, adapter child, and grandchild
+
+Session visibility matrix:
+
+- `self`, `tree`, `agent`, `all`
+- a2a enabled and disabled
+- same-agent row
+- cross-agent row
+- requester-owned spawned cross-agent ACP row
+- sandboxed requester clamped to `tree`
+- list, history, send, and status actions
+
+The important invariant: a requester-owned spawned child is visible wherever
+the configured visibility includes the requester session tree, and `all` is not
+less capable than `tree`.
+
+## Compatibility Notes
+
+Old session records may not have `leaseId`. They should use the legacy
+fail-closed cleanup path:
+
+- require a live root process
+- require wrapper-root ownership when a generated wrapper is expected
+- require command agreement for non-wrapper roots
+- never signal based only on stale stored PID metadata
+
+If a legacy record cannot be verified, leave it alone. Startup lease cleanup and
+the next release window should eventually retire the fallback.
+
+## Success Criteria
+
+- Closing an old or stale ACPX session cannot kill another Gateway's process.
+- Parent death does not leave stubborn adapter grandchildren running.
+- `cancel` aborts the active turn without closing reusable sessions.
+- `sessions_list` can show requester-owned cross-agent ACP children under both
+  `tree` and `all`.
+- Startup cleanup is driven by leases, not broad command-string scans.
+- The focused process and visibility matrix tests cover every edge case that
+  previously required one-off review fixes.