@symerian/symi 3.0.21 → 3.0.22

package/docs/concepts/typebox.md

@@ -1,289 +0,0 @@
----
-summary: "TypeBox schemas as the single source of truth for the gateway protocol"
-read_when:
-  - Updating protocol schemas or codegen
-title: "TypeBox"
----
-
-# TypeBox as protocol source of truth
-
-Last updated: 2026-01-10
-
-TypeBox is a TypeScript-first schema library. We use it to define the **Gateway
-WebSocket protocol** (handshake, request/response, server events). Those schemas
-drive **runtime validation**, **JSON Schema export**, and **Swift codegen** for
-the macOS app. One source of truth; everything else is generated.
-
-If you want the higher-level protocol context, start with
-[Gateway architecture](/concepts/architecture).
-
-## Mental model (30 seconds)
-
-Every Gateway WS message is one of three frames:
-
-- **Request**: `{ type: "req", id, method, params }`
-- **Response**: `{ type: "res", id, ok, payload | error }`
-- **Event**: `{ type: "event", event, payload, seq?, stateVersion? }`
-
-The first frame **must** be a `connect` request. After that, clients can call
-methods (e.g. `health`, `send`, `chat.send`) and subscribe to events (e.g.
-`presence`, `tick`, `agent`).
-
-Connection flow (minimal):
-
-```
-Client                    Gateway
-  |---- req:connect -------->|
-  |<---- res:hello-ok --------|
-  |<---- event:tick ----------|
-  |---- req:health ---------->|
-  |<---- res:health ----------|
-```
-
-Common methods + events:
-
-| Category  | Examples                                                  | Notes                              |
-| --------- | --------------------------------------------------------- | ---------------------------------- |
-| Core      | `connect`, `health`, `status`                             | `connect` must be first            |
-| Messaging | `send`, `poll`, `agent`, `agent.wait`                     | side-effects need `idempotencyKey` |
-| Chat      | `chat.history`, `chat.send`, `chat.abort`, `chat.inject`  | WebChat uses these                 |
-| Sessions  | `sessions.list`, `sessions.patch`, `sessions.delete`      | session admin                      |
-| Nodes     | `node.list`, `node.invoke`, `node.pair.*`                 | Gateway WS + node actions          |
-| Events    | `tick`, `presence`, `agent`, `chat`, `health`, `shutdown` | server push                        |
-
-Authoritative list lives in `src/gateway/server.ts` (`METHODS`, `EVENTS`).
-
-## Where the schemas live
-
-- Source: `src/gateway/protocol/schema.ts`
-- Runtime validators (AJV): `src/gateway/protocol/index.ts`
-- Server handshake + method dispatch: `src/gateway/server.ts`
-- Node client: `src/gateway/client.ts`
-- Generated JSON Schema: `dist/protocol.schema.json`
-- Generated Swift models: `apps/macos/Sources/SymiProtocol/GatewayModels.swift`
-
-## Current pipeline
-
-- `pnpm protocol:gen`
-  - writes JSON Schema (draft‑07) to `dist/protocol.schema.json`
-- `pnpm protocol:gen:swift`
-  - generates Swift gateway models
-- `pnpm protocol:check`
-  - runs both generators and verifies the output is committed
-
-## How the schemas are used at runtime
-
-- **Server side**: every inbound frame is validated with AJV. The handshake only
-  accepts a `connect` request whose params match `ConnectParams`.
-- **Client side**: the JS client validates event and response frames before
-  using them.
-- **Method surface**: the Gateway advertises the supported `methods` and
-  `events` in `hello-ok`.
-
-## Example frames
-
-Connect (first message):
-
-```json
-{
-  "type": "req",
-  "id": "c1",
-  "method": "connect",
-  "params": {
-    "minProtocol": 2,
-    "maxProtocol": 2,
-    "client": {
-      "id": "symi-macos",
-      "displayName": "macos",
-      "version": "1.0.0",
-      "platform": "macos 15.1",
-      "mode": "ui",
-      "instanceId": "A1B2"
-    }
-  }
-}
-```
-
-Hello-ok response:
-
-```json
-{
-  "type": "res",
-  "id": "c1",
-  "ok": true,
-  "payload": {
-    "type": "hello-ok",
-    "protocol": 2,
-    "server": { "version": "dev", "connId": "ws-1" },
-    "features": { "methods": ["health"], "events": ["tick"] },
-    "snapshot": {
-      "presence": [],
-      "health": {},
-      "stateVersion": { "presence": 0, "health": 0 },
-      "uptimeMs": 0
-    },
-    "policy": { "maxPayload": 1048576, "maxBufferedBytes": 1048576, "tickIntervalMs": 30000 }
-  }
-}
-```
-
-Request + response:
-
-```json
-{ "type": "req", "id": "r1", "method": "health" }
-```
-
-```json
-{ "type": "res", "id": "r1", "ok": true, "payload": { "ok": true } }
-```
-
-Event:
-
-```json
-{ "type": "event", "event": "tick", "payload": { "ts": 1730000000 }, "seq": 12 }
-```
-
-## Minimal client (Node.js)
-
-Smallest useful flow: connect + health.
-
-```ts
-import { WebSocket } from "ws";
-
-const ws = new WebSocket("ws://127.0.0.1:18789");
-
-ws.on("open", () => {
-  ws.send(
-    JSON.stringify({
-      type: "req",
-      id: "c1",
-      method: "connect",
-      params: {
-        minProtocol: 3,
-        maxProtocol: 3,
-        client: {
-          id: "cli",
-          displayName: "example",
-          version: "dev",
-          platform: "node",
-          mode: "cli",
-        },
-      },
-    }),
-  );
-});
-
-ws.on("message", (data) => {
-  const msg = JSON.parse(String(data));
-  if (msg.type === "res" && msg.id === "c1" && msg.ok) {
-    ws.send(JSON.stringify({ type: "req", id: "h1", method: "health" }));
-  }
-  if (msg.type === "res" && msg.id === "h1") {
-    console.log("health:", msg.payload);
-    ws.close();
-  }
-});
-```
-
-## Worked example: add a method end‑to‑end
-
-Example: add a new `system.echo` request that returns `{ ok: true, text }`.
-
-1. **Schema (source of truth)**
-
-Add to `src/gateway/protocol/schema.ts`:
-
-```ts
-export const SystemEchoParamsSchema = Type.Object(
-  { text: NonEmptyString },
-  { additionalProperties: false },
-);
-
-export const SystemEchoResultSchema = Type.Object(
-  { ok: Type.Boolean(), text: NonEmptyString },
-  { additionalProperties: false },
-);
-```
-
-Add both to `ProtocolSchemas` and export types:
-
-```ts
-  SystemEchoParams: SystemEchoParamsSchema,
-  SystemEchoResult: SystemEchoResultSchema,
-```
-
-```ts
-export type SystemEchoParams = Static<typeof SystemEchoParamsSchema>;
-export type SystemEchoResult = Static<typeof SystemEchoResultSchema>;
-```
-
-2. **Validation**
-
-In `src/gateway/protocol/index.ts`, export an AJV validator:
-
-```ts
-export const validateSystemEchoParams = ajv.compile<SystemEchoParams>(SystemEchoParamsSchema);
-```
-
-3. **Server behavior**
-
-Add a handler in `src/gateway/server-methods/system.ts`:
-
-```ts
-export const systemHandlers: GatewayRequestHandlers = {
-  "system.echo": ({ params, respond }) => {
-    const text = String(params.text ?? "");
-    respond(true, { ok: true, text });
-  },
-};
-```
-
-Register it in `src/gateway/server-methods.ts` (already merges `systemHandlers`),
-then add `"system.echo"` to `METHODS` in `src/gateway/server.ts`.
-
-4. **Regenerate**
-
-```bash
-pnpm protocol:check
-```
-
-5. **Tests + docs**
-
-Add a server test in `src/gateway/server.*.test.ts` and note the method in docs.
-
-## Swift codegen behavior
-
-The Swift generator emits:
-
-- `GatewayFrame` enum with `req`, `res`, `event`, and `unknown` cases
-- Strongly typed payload structs/enums
-- `ErrorCode` values and `GATEWAY_PROTOCOL_VERSION`
-
-Unknown frame types are preserved as raw payloads for forward compatibility.
-
-## Versioning + compatibility
-
-- `PROTOCOL_VERSION` lives in `src/gateway/protocol/schema.ts`.
-- Clients send `minProtocol` + `maxProtocol`; the server rejects mismatches.
-- The Swift models keep unknown frame types to avoid breaking older clients.
-
-## Schema patterns and conventions
-
-- Most objects use `additionalProperties: false` for strict payloads.
-- `NonEmptyString` is the default for IDs and method/event names.
-- The top-level `GatewayFrame` uses a **discriminator** on `type`.
-- Methods with side effects usually require an `idempotencyKey` in params
-  (example: `send`, `poll`, `agent`, `chat.send`).
-
-## Live schema JSON
-
-Generated JSON Schema is in the repo at `dist/protocol.schema.json`. The
-published raw file is typically available at:
-
-- [https://raw.githubusercontent.com/symi/symi/main/dist/protocol.schema.json](https://raw.githubusercontent.com/symi/symi/main/dist/protocol.schema.json)
-
-## When you change schemas
-
-1. Update the TypeBox schemas.
-2. Run `pnpm protocol:check`.
-3. Commit the regenerated schema + Swift models.

package/docs/concepts/typing-indicators.md

@@ -1,68 +0,0 @@
----
-summary: "When Symi shows typing indicators and how to tune them"
-read_when:
-  - Changing typing indicator behavior or defaults
-title: "Typing Indicators"
----
-
-# Typing indicators
-
-Typing indicators are sent to the chat channel while a run is active. Use
-`agents.defaults.typingMode` to control **when** typing starts and `typingIntervalSeconds`
-to control **how often** it refreshes.
-
-## Defaults
-
-When `agents.defaults.typingMode` is **unset**, Symi keeps the legacy behavior:
-
-- **Direct chats**: typing starts immediately once the model loop begins.
-- **Group chats with a mention**: typing starts immediately.
-- **Group chats without a mention**: typing starts only when message text begins streaming.
-- **Heartbeat runs**: typing is disabled.
-
-## Modes
-
-Set `agents.defaults.typingMode` to one of:
-
-- `never` — no typing indicator, ever.
-- `instant` — start typing **as soon as the model loop begins**, even if the run
-  later returns only the silent reply token.
-- `thinking` — start typing on the **first reasoning delta** (requires
-  `reasoningLevel: "stream"` for the run).
-- `message` — start typing on the **first non-silent text delta** (ignores
-  the `NO_REPLY` silent token).
-
-Order of “how early it fires”:
-`never` → `message` → `thinking` → `instant`
-
-## Configuration
-
-```json5
-{
-  agent: {
-    typingMode: "thinking",
-    typingIntervalSeconds: 6,
-  },
-}
-```
-
-You can override mode or cadence per session:
-
-```json5
-{
-  session: {
-    typingMode: "message",
-    typingIntervalSeconds: 4,
-  },
-}
-```
-
-## Notes
-
-- `message` mode won’t show typing for silent-only replies (e.g. the `NO_REPLY`
-  token used to suppress output).
-- `thinking` only fires if the run streams reasoning (`reasoningLevel: "stream"`).
-  If the model doesn’t emit reasoning deltas, typing won’t start.
-- Heartbeats never show typing, regardless of mode.
-- `typingIntervalSeconds` controls the **refresh cadence**, not the start time.
-  The default is 6 seconds.

package/docs/concepts/usage-tracking.md

@@ -1,35 +0,0 @@
----
-summary: "Usage tracking surfaces and credential requirements"
-read_when:
-  - You are wiring provider usage/quota surfaces
-  - You need to explain usage tracking behavior or auth requirements
-title: "Usage Tracking"
----
-
-# Usage tracking
-
-## What it is
-
-- Pulls provider usage/quota directly from their usage endpoints.
-- No estimated costs; only the provider-reported windows.
-
-## Where it shows up
-
-- `/status` in chats: emoji‑rich status card with session tokens + estimated cost (API key only). Provider usage shows for the **current model provider** when available.
-- `/usage off|tokens|full` in chats: per-response usage footer (OAuth shows tokens only).
-- `/usage cost` in chats: local cost summary aggregated from Symi session logs.
-- CLI: `symi status --usage` prints a full per-provider breakdown.
-- CLI: `symi channels list` prints the same usage snapshot alongside provider config (use `--no-usage` to skip).
-- macOS menu bar: “Usage” section under Context (only if available).
-
-## Providers + credentials
-
-- **Anthropic (Claude)**: OAuth tokens in auth profiles.
-- **GitHub Copilot**: OAuth tokens in auth profiles.
-- **Gemini CLI**: OAuth tokens in auth profiles.
-- **Antigravity**: OAuth tokens in auth profiles.
-- **OpenAI Codex**: OAuth tokens in auth profiles (accountId used when present).
-- **MiniMax**: API key (coding plan key; `MINIMAX_CODE_PLAN_KEY` or `MINIMAX_API_KEY`); uses the 5‑hour coding plan window.
-- **z.ai**: API key via env/config/auth store.
-
-Usage is hidden if no matching OAuth/API credentials exist.

package/docs/date-time.md

@@ -1,127 +0,0 @@
----
-summary: "Date and time handling across envelopes, prompts, tools, and connectors"
-read_when:
-  - You are changing how timestamps are shown to the model or users
-  - You are debugging time formatting in messages or system prompt output
-title: "Date and Time"
----
-
-# Date & Time
-
-Symi defaults to **host-local time for transport timestamps** and **user timezone only in the system prompt**.
-Provider timestamps are preserved so tools keep their native semantics (current time is available via `session_status`).
-
-## Message envelopes (local by default)
-
-Inbound messages are wrapped with a timestamp (minute precision):
-
-```
-[Provider ... 2026-01-05 16:26 PST] message text
-```
-
-This envelope timestamp is **host-local by default**, regardless of the provider timezone.
-
-You can override this behavior:
-
-```json5
-{
-  agents: {
-    defaults: {
-      envelopeTimezone: "local", // "utc" | "local" | "user" | IANA timezone
-      envelopeTimestamp: "on", // "on" | "off"
-      envelopeElapsed: "on", // "on" | "off"
-    },
-  },
-}
-```
-
-- `envelopeTimezone: "utc"` uses UTC.
-- `envelopeTimezone: "local"` uses the host timezone.
-- `envelopeTimezone: "user"` uses `agents.defaults.userTimezone` (falls back to host timezone).
-- Use an explicit IANA timezone (e.g., `"America/Chicago"`) for a fixed zone.
-- `envelopeTimestamp: "off"` removes absolute timestamps from envelope headers.
-- `envelopeElapsed: "off"` removes elapsed time suffixes (the `+2m` style).
-
-### Examples
-
-**Local (default):**
-
-```
-[WhatsApp +1555 2026-01-18 00:19 PST] hello
-```
-
-**User timezone:**
-
-```
-[WhatsApp +1555 2026-01-18 00:19 CST] hello
-```
-
-**Elapsed time enabled:**
-
-```
-[WhatsApp +1555 +30s 2026-01-18T05:19Z] follow-up
-```
-
-## System prompt: Current Date & Time
-
-If the user timezone is known, the system prompt includes a dedicated
-**Current Date & Time** section with the **time zone only** (no clock/time format)
-to keep prompt caching stable:
-
-```
-Time zone: America/Chicago
-```
-
-When the agent needs the current time, use the `session_status` tool; the status
-card includes a timestamp line.
-
-## System event lines (local by default)
-
-Queued system events inserted into agent context are prefixed with a timestamp using the
-same timezone selection as message envelopes (default: host-local).
-
-```
-System: [2026-01-12 12:19:17 PST] Model switched.
-```
-
-### Configure user timezone + format
-
-```json5
-{
-  agents: {
-    defaults: {
-      userTimezone: "America/Chicago",
-      timeFormat: "auto", // auto | 12 | 24
-    },
-  },
-}
-```
-
-- `userTimezone` sets the **user-local timezone** for prompt context.
-- `timeFormat` controls **12h/24h display** in the prompt. `auto` follows OS prefs.
-
-## Time format detection (auto)
-
-When `timeFormat: "auto"`, Symi inspects the OS preference (macOS/Windows)
-and falls back to locale formatting. The detected value is **cached per process**
-to avoid repeated system calls.
-
-## Tool payloads + connectors (raw provider time + normalized fields)
-
-Channel tools return **provider-native timestamps** and add normalized fields for consistency:
-
-- `timestampMs`: epoch milliseconds (UTC)
-- `timestampUtc`: ISO 8601 UTC string
-
-Raw provider fields are preserved so nothing is lost.
-
-- Slack: epoch-like strings from the API
-- Telegram/WhatsApp: provider-specific numeric/ISO timestamps
-
-If you need local time, convert it downstream using the known timezone.
-
-## Related docs
-
-- [System Prompt](/concepts/system-prompt)
-- [Timezones](/concepts/timezone)
-- [Messages](/concepts/messages)

package/docs/debug/node-issue.md

@@ -1,85 +0,0 @@
----
-summary: Node + tsx "__name is not a function" crash notes and workarounds
-read_when:
-  - Debugging Node-only dev scripts or watch mode failures
-  - Investigating tsx/esbuild loader crashes in Symi
-title: "Node + tsx Crash"
----
-
-# Node + tsx "\_\_name is not a function" crash
-
-## Summary
-
-Running Symi via Node with `tsx` fails at startup with:
-
-```
-[symi] Failed to start CLI: TypeError: __name is not a function
-    at createSubsystemLogger (.../src/logging/subsystem.ts:203:25)
-    at .../src/agents/auth-profiles/constants.ts:25:20
-```
-
-This began after switching dev scripts from Bun to `tsx` (commit `2871657e`, 2026-01-06). The same runtime path worked with Bun.
-
-## Environment
-
-- Node: v25.x (observed on v25.3.0)
-- tsx: 4.21.0
-- OS: macOS (repro also likely on other platforms that run Node 25)
-
-## Repro (Node-only)
-
-```bash
-# in repo root
-node --version
-pnpm install
-node --import tsx src/entry.ts status
-```
-
-## Minimal repro in repo
-
-```bash
-node --import tsx scripts/repro/tsx-name-repro.ts
-```
-
-## Node version check
-
-- Node 25.3.0: fails
-- Node 22.22.0 (Homebrew `node@22`): fails
-- Node 24: not installed here yet; needs verification
-
-## Notes / hypothesis
-
-- `tsx` uses esbuild to transform TS/ESM. esbuild’s `keepNames` emits a `__name` helper and wraps function definitions with `__name(...)`.
-- The crash indicates `__name` exists but is not a function at runtime, which implies the helper is missing or overwritten for this module in the Node 25 loader path.
-- Similar `__name` helper issues have been reported in other esbuild consumers when the helper is missing or rewritten.
-
-## Regression history
-
-- `2871657e` (2026-01-06): scripts changed from Bun to tsx to make Bun optional.
-- Before that (Bun path), `symi status` and `gateway:watch` worked.
-
-## Workarounds
-
-- Use Bun for dev scripts (current temporary revert).
-- Use Node + tsc watch, then run compiled output:
-
-  ```bash
-  pnpm exec tsc --watch --preserveWatchOutput
-  node --watch symi.mjs status
-  ```
-
-- Confirmed locally: `pnpm exec tsc -p tsconfig.json` + `node symi.mjs status` works on Node 25.
-- Disable esbuild keepNames in the TS loader if possible (prevents `__name` helper insertion); tsx does not currently expose this.
-- Test Node LTS (22/24) with `tsx` to see if the issue is Node 25–specific.
-
-## References
-
-- [https://opennext.js.org/cloudflare/howtos/keep_names](https://opennext.js.org/cloudflare/howtos/keep_names)
-- [https://esbuild.github.io/api/#keep-names](https://esbuild.github.io/api/#keep-names)
-- [https://github.com/evanw/esbuild/issues/1031](https://github.com/evanw/esbuild/issues/1031)
-
-## Next steps
-
-- Repro on Node 22/24 to confirm Node 25 regression.
-- Test `tsx` nightly or pin to earlier version if a known regression exists.
-- If reproduces on Node LTS, file a minimal repro upstream with the `__name` stack trace.

package/docs/diagnostics/flags.md

@@ -1,91 +0,0 @@
----
-summary: "Diagnostics flags for targeted debug logs"
-read_when:
-  - You need targeted debug logs without raising global logging levels
-  - You need to capture subsystem-specific logs for support
-title: "Diagnostics Flags"
----
-
-# Diagnostics Flags
-
-Diagnostics flags let you enable targeted debug logs without turning on verbose logging everywhere. Flags are opt-in and have no effect unless a subsystem checks them.
-
-## How it works
-
-- Flags are strings (case-insensitive).
-- You can enable flags in config or via an env override.
-- Wildcards are supported:
-  - `telegram.*` matches `telegram.http`
-  - `*` enables all flags
-
-## Enable via config
-
-```json
-{
-  "diagnostics": {
-    "flags": ["telegram.http"]
-  }
-}
-```
-
-Multiple flags:
-
-```json
-{
-  "diagnostics": {
-    "flags": ["telegram.http", "gateway.*"]
-  }
-}
-```
-
-Restart the gateway after changing flags.
-
-## Env override (one-off)
-
-```bash
-SYMI_DIAGNOSTICS=telegram.http,telegram.payload
-```
-
-Disable all flags:
-
-```bash
-SYMI_DIAGNOSTICS=0
-```
-
-## Where logs go
-
-Flags emit logs into the standard diagnostics log file. By default:
-
-```
-/tmp/symi/symi-YYYY-MM-DD.log
-```
-
-If you set `logging.file`, use that path instead. Logs are JSONL (one JSON object per line). Redaction still applies based on `logging.redactSensitive`.
-
-## Extract logs
-
-Pick the latest log file:
-
-```bash
-ls -t /tmp/symi/symi-*.log | head -n 1
-```
-
-Filter for Telegram HTTP diagnostics:
-
-```bash
-rg "telegram http error" /tmp/symi/symi-*.log
-```
-
-Or tail while reproducing:
-
-```bash
-tail -f /tmp/symi/symi-$(date +%F).log | rg "telegram http error"
-```
-
-For remote gateways, you can also use `symi logs --follow` (see [/cli/logs](/cli/logs)).
-
-## Notes
-
-- If `logging.level` is set higher than `warn`, these logs may be suppressed. Default `info` is fine.
-- Flags are safe to leave enabled; they only affect log volume for the specific subsystem.
-- Use [/logging](/logging) to change log destinations, levels, and redaction.