fengming 0.3.10 → 0.3.11

package/docs/concepts/typebox.md

@@ -1,309 +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 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`, `agent`, `agent.wait`, `system-event`, `logs.tail` | side-effects need `idempotencyKey` |
-| Chat       | `chat.history`, `chat.send`, `chat.abort`                  | WebChat uses these                 |
-| Sessions   | `sessions.list`, `sessions.patch`, `sessions.delete`       | session admin                      |
-| Automation | `wake`, `cron.list`, `cron.run`, `cron.runs`               | wake + cron control                |
-| Nodes      | `node.list`, `node.invoke`, `node.pair.*`                  | Gateway WS + node actions          |
-| Events     | `tick`, `presence`, `agent`, `chat`, `health`, `shutdown`  | server push                        |
-
-Authoritative advertised **discovery** inventory lives in
-`src/gateway/server-methods-list.ts` (`listGatewayMethods`, `GATEWAY_EVENTS`).
-
-## Where the schemas live
-
-- Source: `packages/gateway-protocol/src/schema.ts`
-- Runtime validators (AJV): `packages/gateway-protocol/src/index.ts`
-- Advertised feature/discovery registry: `src/gateway/server-methods-list.ts`
-- Server handshake + method dispatch: `src/gateway/server.impl.ts`
-- Node client: `src/gateway/client.ts`
-- Generated JSON Schema: `dist/protocol.schema.json`
-- Generated Swift models: `apps/macos/Sources/FengMingProtocol/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.
-- **Feature discovery**: the Gateway sends a conservative `features.methods`
-  and `features.events` list in `hello-ok` from `listGatewayMethods()` and
-  `GATEWAY_EVENTS`.
-- That discovery list is not a generated dump of every callable helper in
-  `coreGatewayHandlers`; some helper RPCs are implemented in
-  `src/gateway/server-methods/*.ts` without being enumerated in the advertised
-  feature list.
-
-## Example frames
-
-Connect (first message):
-
-```json
-{
-  "type": "req",
-  "id": "c1",
-  "method": "connect",
-  "params": {
-    "minProtocol": 3,
-    "maxProtocol": 4,
-    "client": {
-      "id": "fengming-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": 4,
-    "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: 4,
-        maxProtocol: 4,
-        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 `packages/gateway-protocol/src/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 `packages/gateway-protocol/src/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 `listGatewayMethods` input in
-`src/gateway/server-methods-list.ts`.
-
-If the method is callable by operator or node clients, also classify it in
-`src/gateway/method-scopes.ts` so scope enforcement and `hello-ok` feature
-advertising stay aligned.
-
-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, `GATEWAY_PROTOCOL_VERSION`, and `GATEWAY_MIN_PROTOCOL_VERSION`
-
-Unknown frame types are preserved as raw payloads for forward compatibility.
-
-## Versioning + compatibility
-
-- `PROTOCOL_VERSION` lives in `packages/gateway-protocol/src/version.ts`.
-- Clients send `minProtocol` + `maxProtocol`; the server rejects ranges that
-  do not include its current protocol.
-- 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`).
-- `agent` accepts optional `internalEvents` for runtime-generated orchestration context
-  (for example subagent/cron task completion handoff); treat this as internal API surface.
-
-## 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/fengming/fengming/main/dist/protocol.schema.json](https://raw.githubusercontent.com/fengming/fengming/main/dist/protocol.schema.json)
-
-## When you change schemas
-
-1. Update the TypeBox schemas.
-2. Register the method/event in `src/gateway/server-methods-list.ts`.
-3. Update `src/gateway/method-scopes.ts` when the new RPC needs operator or
-   node scope classification.
-4. Run `pnpm protocol:check`.
-5. Commit the regenerated schema + Swift models.
-
-## Related
-
-- [Rich output protocol](/reference/rich-output-protocol)
-- [RPC adapters](/reference/rpc)

package/docs/concepts/typing-indicators.md

@@ -1,88 +0,0 @@
----
-summary: "When FengMing shows typing indicators and how to tune them"
-read_when:
-  - Changing typing indicator behavior or defaults
-title: "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**, FengMing 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 starts when the heartbeat run begins if the
-  resolved heartbeat target is a typing-capable chat and typing is not 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
-
-Set the agent-level default:
-
-```json5
-{
-  agents: {
-    defaults: {
-      typingMode: "thinking",
-      typingIntervalSeconds: 6,
-    },
-  },
-}
-```
-
-Override mode or cadence per session:
-
-```json5
-{
-  session: {
-    typingMode: "message",
-    typingIntervalSeconds: 4,
-  },
-}
-```
-
-## Notes
-
-- `message` mode won't show typing for silent-only replies when the whole
-  payload is the exact silent token (for example `NO_REPLY` / `no_reply`,
-  matched case-insensitively).
-- `thinking` only fires if the run streams reasoning (`reasoningLevel: "stream"`).
-  If the model doesn't emit reasoning deltas, typing won't start.
-- Heartbeat typing is a liveness signal for the resolved delivery target. It
-  starts at heartbeat run start instead of following `message` or `thinking`
-  stream timing. Set `typingMode: "never"` to disable it.
-- Heartbeats do not show typing when `target: "none"`, when the target cannot
-  be resolved, when chat delivery is disabled for the heartbeat, or when the
-  channel does not support typing.
-- `typingIntervalSeconds` controls the **refresh cadence**, not the start time.
-  The default is 6 seconds.
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Presence" href="/concepts/presence" icon="signal">
-    How the Gateway tracks connected clients and surfaces them in the macOS Instances tab.
-  </Card>
-  <Card title="Streaming and chunking" href="/concepts/streaming" icon="bars-staggered">
-    Outbound streaming behavior, chunk boundaries, and channel-specific delivery.
-  </Card>
-</CardGroup>

package/docs/concepts/usage-tracking.md

@@ -1,66 +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"
----
-
-## What it is
-
-- Pulls provider usage/quota directly from their usage endpoints.
-- No estimated costs; only the provider-reported windows.
-- Human-readable status output is normalized to `X% left`, even when an
-  upstream API reports consumed quota, remaining quota, or only raw counts.
-- Session-level `/status` and `session_status` can fall back to the latest
-  transcript usage entry when the live session snapshot is sparse. That
-  fallback fills missing token/cache counters, can recover the active runtime
-  model label, and prefers the larger prompt-oriented total when session
-  metadata is missing or smaller. Existing nonzero live values still win.
-
-## 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 as a normalized `X% left` window.
-- `/usage off|tokens|full` in chats: per-response usage footer (OAuth shows tokens only).
-- `/usage cost` in chats: local cost summary aggregated from FengMing session logs.
-- CLI: `fengming status --usage` prints a full per-provider breakdown.
-- CLI: `fengming 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.
-  - JSON usage falls back to `stats`; `stats.cached` is normalized into
-    `cacheRead`.
-- **OpenAI Codex**: OAuth tokens in auth profiles (accountId used when present).
-- **MiniMax**: API key or MiniMax OAuth auth profile. FengMing treats
-  `minimax`, `minimax-cn`, and `minimax-portal` as the same MiniMax quota
-  surface, prefers stored MiniMax OAuth when present, and otherwise falls back
-  to `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`, or `MINIMAX_API_KEY`.
-  Usage polling derives the Coding Plan host from `models.providers.minimax-portal.baseUrl`
-  or `models.providers.minimax.baseUrl` when configured, and otherwise uses the
-  MiniMax CN host.
-  MiniMax's raw `usage_percent` / `usagePercent` fields mean **remaining**
-  quota, so FengMing inverts them before display; count-based fields win when
-  present.
-  - Coding-plan window labels come from provider hours/minutes fields when
-    present, then fall back to the `start_time` / `end_time` span.
-  - If the coding-plan endpoint returns `model_remains`, FengMing prefers the
-    chat-model entry, derives the window label from timestamps when explicit
-    `window_hours` / `window_minutes` fields are absent, and includes the model
-    name in the plan label.
-- **Xiaomi MiMo**: API key via env/config/auth store (`XIAOMI_API_KEY`).
-- **z.ai**: API key via env/config/auth store.
-
-Usage is hidden when no usable provider usage auth can be resolved. Providers
-can supply plugin-specific usage auth logic; otherwise FengMing falls back to
-matching OAuth/API-key credentials from auth profiles, environment variables,
-or config.
-
-## Related
-
-- [Token use and costs](/reference/token-use)
-- [API usage and costs](/reference/api-usage-costs)
-- [Prompt caching](/reference/prompt-caching)

package/docs/date-time.md

@@ -1,126 +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"
----
-
-FengMing 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 (second precision):
-
-```
-[Provider ... Mon 2026-01-05 16:26:34 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 Sun 2026-01-18 00:19:42 PST] hello
-```
-
-**User timezone:**
-
-```
-[WhatsApp +1555 Sun 2026-01-18 00:19:42 CST] hello
-```
-
-**Elapsed time enabled:**
-
-```
-[WhatsApp +1555 +30s Sun 2026-01-18T05:19:00Z] follow-up
-```
-
-## System prompt: current date and 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"`, FengMing 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
-- Discord: UTC ISO timestamps
-- 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,90 +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 FengMing
-title: "Node + tsx crash"
----
-
-# Node + tsx "\_\_name is not a function" crash
-
-## Summary
-
-Running FengMing via Node with `tsx` fails at startup with:
-
-```
-[fengming] 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), `fengming status` and `gateway:watch` worked.
-
-## Workarounds
-
-- Use Bun for dev scripts (current temporary revert).
-- Use `tsgo` for repo type checking, then run the built output:
-
-  ```bash
-  pnpm tsgo
-  node fengming.mjs status
-  ```
-
-- Historical note: `tsc` was used here while debugging this Node/tsx issue, but repo type-check lanes now use `tsgo`.
-- 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.
-
-## Related
-
-- [Node.js install](/install/node)
-- [Gateway troubleshooting](/gateway/troubleshooting)