@symerian/symi 3.0.21 → 3.0.22

package/docs/providers/vercel-ai-gateway.md

@@ -1,50 +0,0 @@
----
-title: "Vercel AI Gateway"
-summary: "Vercel AI Gateway setup (auth + model selection)"
-read_when:
-  - You want to use Vercel AI Gateway with Symi
-  - You need the API key env var or CLI auth choice
----
-
-# Vercel AI Gateway
-
-The [Vercel AI Gateway](https://vercel.com/ai-gateway) provides a unified API to access hundreds of models through a single endpoint.
-
-- Provider: `vercel-ai-gateway`
-- Auth: `AI_GATEWAY_API_KEY`
-- API: Anthropic Messages compatible
-
-## Quick start
-
-1. Set the API key (recommended: store it for the Gateway):
-
-```bash
-symi onboard --auth-choice ai-gateway-api-key
-```
-
-2. Set a default model:
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "vercel-ai-gateway/anthropic/claude-opus-4.6" },
-    },
-  },
-}
-```
-
-## Non-interactive example
-
-```bash
-symi onboard --non-interactive \
-  --mode local \
-  --auth-choice ai-gateway-api-key \
-  --ai-gateway-api-key "$AI_GATEWAY_API_KEY"
-```
-
-## Environment note
-
-If the Gateway runs as a daemon (launchd/systemd), make sure `AI_GATEWAY_API_KEY`
-is available to that process (for example, in `~/.symi/.env` or via
-`env.shellEnv`).

package/docs/providers/vllm.md

@@ -1,92 +0,0 @@
----
-summary: "Run Symi with vLLM (OpenAI-compatible local server)"
-read_when:
-  - You want to run Symi against a local vLLM server
-  - You want OpenAI-compatible /v1 endpoints with your own models
-title: "vLLM"
----
-
-# vLLM
-
-vLLM can serve open-source (and some custom) models via an **OpenAI-compatible** HTTP API. Symi can connect to vLLM using the `openai-completions` API.
-
-Symi can also **auto-discover** available models from vLLM when you opt in with `VLLM_API_KEY` (any value works if your server doesn’t enforce auth) and you do not define an explicit `models.providers.vllm` entry.
-
-## Quick start
-
-1. Start vLLM with an OpenAI-compatible server.
-
-Your base URL should expose `/v1` endpoints (e.g. `/v1/models`, `/v1/chat/completions`). vLLM commonly runs on:
-
-- `http://127.0.0.1:8000/v1`
-
-2. Opt in (any value works if no auth is configured):
-
-```bash
-export VLLM_API_KEY="vllm-local"
-```
-
-3. Select a model (replace with one of your vLLM model IDs):
-
-```json5
-{
-  agents: {
-    defaults: {
-      model: { primary: "vllm/your-model-id" },
-    },
-  },
-}
-```
-
-## Model discovery (implicit provider)
-
-When `VLLM_API_KEY` is set (or an auth profile exists) and you **do not** define `models.providers.vllm`, Symi will query:
-
-- `GET http://127.0.0.1:8000/v1/models`
-
-…and convert the returned IDs into model entries.
-
-If you set `models.providers.vllm` explicitly, auto-discovery is skipped and you must define models manually.
-
-## Explicit configuration (manual models)
-
-Use explicit config when:
-
-- vLLM runs on a different host/port.
-- You want to pin `contextWindow`/`maxTokens` values.
-- Your server requires a real API key (or you want to control headers).
-
-```json5
-{
-  models: {
-    providers: {
-      vllm: {
-        baseUrl: "http://127.0.0.1:8000/v1",
-        apiKey: "${VLLM_API_KEY}",
-        api: "openai-completions",
-        models: [
-          {
-            id: "your-model-id",
-            name: "Local vLLM Model",
-            reasoning: false,
-            input: ["text"],
-            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-            contextWindow: 128000,
-            maxTokens: 8192,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-## Troubleshooting
-
-- Check the server is reachable:
-
-```bash
-curl http://127.0.0.1:8000/v1/models
-```
-
-- If requests fail with auth errors, set a real `VLLM_API_KEY` that matches your server configuration, or configure the provider explicitly under `models.providers.vllm`.

package/docs/providers/xiaomi.md

@@ -1,64 +0,0 @@
----
-summary: "Use Xiaomi MiMo (mimo-v2-flash) with Symi"
-read_when:
-  - You want Xiaomi MiMo models in Symi
-  - You need XIAOMI_API_KEY setup
-title: "Xiaomi MiMo"
----
-
-# Xiaomi MiMo
-
-Xiaomi MiMo is the API platform for **MiMo** models. It provides REST APIs compatible with
-OpenAI and Anthropic formats and uses API keys for authentication. Create your API key in
-the [Xiaomi MiMo console](https://platform.xiaomimimo.com/#/console/api-keys). Symi uses
-the `xiaomi` provider with a Xiaomi MiMo API key.
-
-## Model overview
-
-- **mimo-v2-flash**: 262144-token context window, Anthropic Messages API compatible.
-- Base URL: `https://api.xiaomimimo.com/anthropic`
-- Authorization: `Bearer $XIAOMI_API_KEY`
-
-## CLI setup
-
-```bash
-symi onboard --auth-choice xiaomi-api-key
-# or non-interactive
-symi onboard --auth-choice xiaomi-api-key --xiaomi-api-key "$XIAOMI_API_KEY"
-```
-
-## Config snippet
-
-```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/anthropic",
-        api: "anthropic-messages",
-        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,
-          },
-        ],
-      },
-    },
-  },
-}
-```
-
-## Notes
-
-- Model ref: `xiaomi/mimo-v2-flash`.
-- The provider is injected automatically when `XIAOMI_API_KEY` is set (or an auth profile exists).
-- See [/concepts/model-providers](/concepts/model-providers) for provider rules.

package/docs/providers/zai.md

@@ -1,38 +0,0 @@
----
-summary: "Use Z.AI (GLM models) with Symi"
-read_when:
-  - You want Z.AI / GLM models in Symi
-  - You need a simple ZAI_API_KEY setup
-title: "Z.AI"
----
-
-# 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. Symi uses the `zai` provider
-with a Z.AI API key.
-
-## CLI setup
-
-```bash
-symi onboard --auth-choice zai-api-key
-# or non-interactive
-symi onboard --zai-api-key "$ZAI_API_KEY"
-```
-
-## Config snippet
-
-```json5
-{
-  env: { ZAI_API_KEY: "sk-..." },
-  agents: { defaults: { model: { primary: "zai/glm-5" } } },
-}
-```
-
-## Notes
-
-- GLM models are available as `zai/<model>` (example: `zai/glm-5`).
-- `tool_stream` is enabled by default for Z.AI tool-call streaming. Set
-  `agents.defaults.models["zai/<model>"].params.tool_stream` to `false` to disable it.
-- See [/providers/glm](/providers/glm) for the model family overview.
-- Z.AI uses Bearer auth with your API key.

package/docs/refactor/exec-host.md

@@ -1,316 +0,0 @@
----
-summary: "Refactor plan: exec host routing, node approvals, and headless runner"
-read_when:
-  - Designing exec host routing or exec approvals
-  - Implementing node runner + UI IPC
-  - Adding exec host security modes and slash commands
-title: "Exec Host Refactor"
----
-
-# Exec host refactor plan
-
-## Goals
-
-- Add `exec.host` + `exec.security` to route execution across **sandbox**, **gateway**, and **node**.
-- Keep defaults **safe**: no cross-host execution unless explicitly enabled.
-- Split execution into a **headless runner service** with optional UI (macOS app) via local IPC.
-- Provide **per-agent** policy, allowlist, ask mode, and node binding.
-- Support **ask modes** that work _with_ or _without_ allowlists.
-- Cross-platform: Unix socket + token auth (macOS/Linux/Windows parity).
-
-## Non-goals
-
-- No legacy allowlist migration or legacy schema support.
-- No PTY/streaming for node exec (aggregated output only).
-- No new network layer beyond the existing Bridge + Gateway.
-
-## Decisions (locked)
-
-- **Config keys:** `exec.host` + `exec.security` (per-agent override allowed).
-- **Elevation:** keep `/elevated` as an alias for gateway full access.
-- **Ask default:** `on-miss`.
-- **Approvals store:** `~/.symi/exec-approvals.json` (JSON, no legacy migration).
-- **Runner:** headless system service; UI app hosts a Unix socket for approvals.
-- **Node identity:** use existing `nodeId`.
-- **Socket auth:** Unix socket + token (cross-platform); split later if needed.
-- **Node host state:** `~/.symi/node.json` (node id + pairing token).
-- **macOS exec host:** run `system.run` inside the macOS app; node host service forwards requests over local IPC.
-- **No XPC helper:** stick to Unix socket + token + peer checks.
-
-## Key concepts
-
-### Host
-
-- `sandbox`: Docker exec (current behavior).
-- `gateway`: exec on gateway host.
-- `node`: exec on node runner via Bridge (`system.run`).
-
-### Security mode
-
-- `deny`: always block.
-- `allowlist`: allow only matches.
-- `full`: allow everything (equivalent to elevated).
-
-### Ask mode
-
-- `off`: never ask.
-- `on-miss`: ask only when allowlist does not match.
-- `always`: ask every time.
-
-Ask is **independent** of allowlist; allowlist can be used with `always` or `on-miss`.
-
-### Policy resolution (per exec)
-
-1. Resolve `exec.host` (tool param → agent override → global default).
-2. Resolve `exec.security` and `exec.ask` (same precedence).
-3. If host is `sandbox`, proceed with local sandbox exec.
-4. If host is `gateway` or `node`, apply security + ask policy on that host.
-
-## Default safety
-
-- Default `exec.host = sandbox`.
-- Default `exec.security = deny` for `gateway` and `node`.
-- Default `exec.ask = on-miss` (only relevant if security allows).
-- If no node binding is set, **agent may target any node**, but only if policy allows it.
-
-## Config surface
-
-### Tool parameters
-
-- `exec.host` (optional): `sandbox | gateway | node`.
-- `exec.security` (optional): `deny | allowlist | full`.
-- `exec.ask` (optional): `off | on-miss | always`.
-- `exec.node` (optional): node id/name to use when `host=node`.
-
-### Config keys (global)
-
-- `tools.exec.host`
-- `tools.exec.security`
-- `tools.exec.ask`
-- `tools.exec.node` (default node binding)
-
-### Config keys (per agent)
-
-- `agents.list[].tools.exec.host`
-- `agents.list[].tools.exec.security`
-- `agents.list[].tools.exec.ask`
-- `agents.list[].tools.exec.node`
-
-### Alias
-
-- `/elevated on` = set `tools.exec.host=gateway`, `tools.exec.security=full` for the agent session.
-- `/elevated off` = restore previous exec settings for the agent session.
-
-## Approvals store (JSON)
-
-Path: `~/.symi/exec-approvals.json`
-
-Purpose:
-
-- Local policy + allowlists for the **execution host** (gateway or node runner).
-- Ask fallback when no UI is available.
-- IPC credentials for UI clients.
-
-Proposed schema (v1):
-
-```json
-{
-  "version": 1,
-  "socket": {
-    "path": "~/.symi/exec-approvals.sock",
-    "token": "base64-opaque-token"
-  },
-  "defaults": {
-    "security": "deny",
-    "ask": "on-miss",
-    "askFallback": "deny"
-  },
-  "agents": {
-    "agent-id-1": {
-      "security": "allowlist",
-      "ask": "on-miss",
-      "allowlist": [
-        {
-          "pattern": "~/Projects/**/bin/rg",
-          "lastUsedAt": 0,
-          "lastUsedCommand": "rg -n TODO",
-          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
-        }
-      ]
-    }
-  }
-}
-```
-
-Notes:
-
-- No legacy allowlist formats.
-- `askFallback` applies only when `ask` is required and no UI is reachable.
-- File permissions: `0600`.
-
-## Runner service (headless)
-
-### Role
-
-- Enforce `exec.security` + `exec.ask` locally.
-- Execute system commands and return output.
-- Emit Bridge events for exec lifecycle (optional but recommended).
-
-### Service lifecycle
-
-- Launchd/daemon on macOS; system service on Linux/Windows.
-- Approvals JSON is local to the execution host.
-- UI hosts a local Unix socket; runners connect on demand.
-
-## UI integration (macOS app)
-
-### IPC
-
-- Unix socket at `~/.symi/exec-approvals.sock` (0600).
-- Token stored in `exec-approvals.json` (0600).
-- Peer checks: same-UID only.
-- Challenge/response: nonce + HMAC(token, request-hash) to prevent replay.
-- Short TTL (e.g., 10s) + max payload + rate limit.
-
-### Ask flow (macOS app exec host)
-
-1. Node service receives `system.run` from gateway.
-2. Node service connects to the local socket and sends the prompt/exec request.
-3. App validates peer + token + HMAC + TTL, then shows dialog if needed.
-4. App executes the command in UI context and returns output.
-5. Node service returns output to gateway.
-
-If UI missing:
-
-- Apply `askFallback` (`deny|allowlist|full`).
-
-### Diagram (SCI)
-
-```
-Agent -> Gateway -> Bridge -> Node Service (TS)
-                         |  IPC (UDS + token + HMAC + TTL)
-                         v
-                     Mac App (UI + TCC + system.run)
-```
-
-## Node identity + binding
-
-- Use existing `nodeId` from Bridge pairing.
-- Binding model:
-  - `tools.exec.node` restricts the agent to a specific node.
-  - If unset, agent can pick any node (policy still enforces defaults).
-- Node selection resolution:
-  - `nodeId` exact match
-  - `displayName` (normalized)
-  - `remoteIp`
-  - `nodeId` prefix (>= 6 chars)
-
-## Eventing
-
-### Who sees events
-
-- System events are **per session** and shown to the agent on the next prompt.
-- Stored in the gateway in-memory queue (`enqueueSystemEvent`).
-
-### Event text
-
-- `Exec started (node=<id>, id=<runId>)`
-- `Exec finished (node=<id>, id=<runId>, code=<code>)` + optional output tail
-- `Exec denied (node=<id>, id=<runId>, <reason>)`
-
-### Transport
-
-Option A (recommended):
-
-- Runner sends Bridge `event` frames `exec.started` / `exec.finished`.
-- Gateway `handleBridgeEvent` maps these into `enqueueSystemEvent`.
-
-Option B:
-
-- Gateway `exec` tool handles lifecycle directly (synchronous only).
-
-## Exec flows
-
-### Sandbox host
-
-- Existing `exec` behavior (Docker or host when unsandboxed).
-- PTY supported in non-sandbox mode only.
-
-### Gateway host
-
-- Gateway process executes on its own machine.
-- Enforces local `exec-approvals.json` (security/ask/allowlist).
-
-### Node host
-
-- Gateway calls `node.invoke` with `system.run`.
-- Runner enforces local approvals.
-- Runner returns aggregated stdout/stderr.
-- Optional Bridge events for start/finish/deny.
-
-## Output caps
-
-- Cap combined stdout+stderr at **200k**; keep **tail 20k** for events.
-- Truncate with a clear suffix (e.g., `"… (truncated)"`).
-
-## Slash commands
-
-- `/exec host=<sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>`
-- Per-agent, per-session overrides; non-persistent unless saved via config.
-- `/elevated on|off|ask|full` remains a shortcut for `host=gateway security=full` (with `full` skipping approvals).
-
-## Cross-platform story
-
-- The runner service is the portable execution target.
-- UI is optional; if missing, `askFallback` applies.
-- Windows/Linux support the same approvals JSON + socket protocol.
-
-## Implementation phases
-
-### Phase 1: config + exec routing
-
-- Add config schema for `exec.host`, `exec.security`, `exec.ask`, `exec.node`.
-- Update tool plumbing to respect `exec.host`.
-- Add `/exec` slash command and keep `/elevated` alias.
-
-### Phase 2: approvals store + gateway enforcement
-
-- Implement `exec-approvals.json` reader/writer.
-- Enforce allowlist + ask modes for `gateway` host.
-- Add output caps.
-
-### Phase 3: node runner enforcement
-
-- Update node runner to enforce allowlist + ask.
-- Add Unix socket prompt bridge to macOS app UI.
-- Wire `askFallback`.
-
-### Phase 4: events
-
-- Add node → gateway Bridge events for exec lifecycle.
-- Map to `enqueueSystemEvent` for agent prompts.
-
-### Phase 5: UI polish
-
-- Mac app: allowlist editor, per-agent switcher, ask policy UI.
-- Node binding controls (optional).
-
-## Testing plan
-
-- Unit tests: allowlist matching (glob + case-insensitive).
-- Unit tests: policy resolution precedence (tool param → agent override → global).
-- Integration tests: node runner deny/allow/ask flows.
-- Bridge event tests: node event → system event routing.
-
-## Open risks
-
-- UI unavailability: ensure `askFallback` is respected.
-- Long-running commands: rely on timeout + output caps.
-- Multi-node ambiguity: error unless node binding or explicit node param.
-
-## Related docs
-
-- [Exec tool](/tools/exec)
-- [Exec approvals](/tools/exec-approvals)
-- [Nodes](/nodes)
-- [Elevated mode](/tools/elevated)

package/docs/refactor/outbound-session-mirroring.md

@@ -1,83 +0,0 @@
----
-title: Outbound Session Mirroring Refactor (Issue #1520)
-description: Track outbound session mirroring refactor notes, decisions, tests, and open items.
----
-
-# Outbound Session Mirroring Refactor (Issue #1520)
-
-## Status
-
-- In progress.
-- Core + plugin channel routing updated for outbound mirroring.
-- Gateway send now derives target session when sessionKey is omitted.
-
-## Context
-
-Outbound sends were mirrored into the _current_ agent session (tool session key) rather than the target channel session. Inbound routing uses channel/peer session keys, so outbound responses landed in the wrong session and first-contact targets often lacked session entries.
-
-## Goals
-
-- Mirror outbound messages into the target channel session key.
-- Create session entries on outbound when missing.
-- Keep thread/topic scoping aligned with inbound session keys.
-- Cover core channels plus bundled extensions.
-
-## Implementation Summary
-
-- New outbound session routing helper:
-  - `src/infra/outbound/outbound-session.ts`
-  - `resolveOutboundSessionRoute` builds target sessionKey using `buildAgentSessionKey` (dmScope + identityLinks).
-  - `ensureOutboundSessionEntry` writes minimal `MsgContext` via `recordSessionMetaFromInbound`.
-- `runMessageAction` (send) derives target sessionKey and passes it to `executeSendAction` for mirroring.
-- `message-tool` no longer mirrors directly; it only resolves agentId from the current session key.
-- Plugin send path mirrors via `appendAssistantMessageToSessionTranscript` using the derived sessionKey.
-- Gateway send derives a target session key when none is provided (default agent), and ensures a session entry.
-
-## Thread/Topic Handling
-
-- Slack: replyTo/threadId -> `resolveThreadSessionKeys` (suffix).
-- Telegram: topic IDs map to `chatId:topic:<id>` via `buildTelegramGroupPeerId`.
-
-## Extensions Covered
-
-- Matrix, MS Teams, Mattermost, BlueBubbles, Nextcloud Talk, Zalo, Zalo Personal, Nostr, Tlon.
-- Notes:
-  - Mattermost targets now strip `@` for DM session key routing.
-  - Zalo Personal uses DM peer kind for 1:1 targets (group only when `group:` is present).
-  - BlueBubbles group targets strip `chat_*` prefixes to match inbound session keys.
-  - Slack auto-thread mirroring matches channel ids case-insensitively.
-  - Gateway send lowercases provided session keys before mirroring.
-
-## Decisions
-
-- **Gateway send session derivation**: if `sessionKey` is provided, use it. If omitted, derive a sessionKey from target + default agent and mirror there.
-- **Session entry creation**: always use `recordSessionMetaFromInbound` with `Provider/From/To/ChatType/AccountId/Originating*` aligned to inbound formats.
-- **Target normalization**: outbound routing uses resolved targets (post `resolveChannelTarget`) when available.
-- **Session key casing**: canonicalize session keys to lowercase on write and during migrations.
-
-## Tests Added/Updated
-
-- `src/infra/outbound/outbound-session.test.ts`
-  - Slack thread session key.
-  - Telegram topic session key.
-- `src/agents/tools/message-tool.test.ts`
-  - Derives agentId from session key (no sessionKey passed through).
-- `src/gateway/server-methods/send.test.ts`
-  - Derives session key when omitted and creates session entry.
-
-## Open Items / Follow-ups
-
-- Voice-call plugin uses custom `voice:<phone>` session keys. Outbound mapping is not standardized here; if message-tool should support voice-call sends, add explicit mapping.
-- Confirm if any external plugin uses non-standard `From/To` formats beyond the bundled set.
-
-## Files Touched
-
-- `src/infra/outbound/outbound-session.ts`
-- `src/infra/outbound/outbound-send-service.ts`
-- `src/infra/outbound/message-action-runner.ts`
-- `src/agents/tools/message-tool.ts`
-- `src/gateway/server-methods/send.ts`
-- Tests in:
-  - `src/infra/outbound/outbound-session.test.ts`
-  - `src/agents/tools/message-tool.test.ts`
-  - `src/gateway/server-methods/send.test.ts`