fengming 0.3.9 → 0.3.11

package/docs/concepts/oauth.md

@@ -1,198 +0,0 @@
----
-summary: "OAuth in FengMing: token exchange, storage, and multi-account patterns"
-read_when:
-  - You want to understand FengMing 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"
----
-
-FengMing 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 FengMing**: Anthropic staff
-  told us this usage is allowed again
-
-OpenAI Codex OAuth is explicitly supported for use in external tools like
-FengMing. 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)
-
-FengMing also supports **provider plugins** that ship their own OAuth or API-key
-flows. Run them via:
-
-```bash
-fengming 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 FengMing _and_ via Claude Code / Codex CLI → one of them randomly gets "logged out" later
-
-To reduce that, FengMing 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:default` profile, but once FengMing has a local OAuth profile,
-  the local refresh token is canonical. If that local refresh token is rejected,
-  FengMing 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): `~/.fengming/agents/<agentId>/agent/auth-profiles.json`
-- Legacy compatibility file: `~/.fengming/agents/<agentId>/agent/auth.json`
-  (static `api_key` entries are scrubbed when discovered)
-
-Legacy import-only file (still supported, but not the main store):
-
-- `~/.fengming/credentials/oauth.json` (imported into `auth-profiles.json` on first use)
-
-All of the above also respect `$FENGMING_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, FengMing 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 FengMing-style Claude
-CLI usage is allowed again. FengMing 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 FengMing, see [OpenAI
-Codex](/providers/openai), [Qwen Cloud Coding
-Plan](/providers/qwen), [MiniMax Coding Plan](/providers/minimax),
-and [Z.AI / GLM Coding Plan](/providers/zai).
-</Warning>
-
-FengMing 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
-
-FengMing 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)
-
-FengMing's interactive login flows are implemented in `fengming/plugin-sdk/llm` and wired into the wizards/commands.
-
-### Anthropic setup-token
-
-Flow shape:
-
-1. start Anthropic setup-token or paste-token from FengMing
-2. FengMing 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 FengMing 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 `fengming onboard` → auth choice `openai`.
-
-## 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; FengMing
-  re-reads those CLI auth stores instead of spending copied refresh tokens.
-  Codex CLI bootstrap is intentionally narrower: it seeds an empty
-  `openai:default` profile, then FengMing-owned refreshes keep the local
-  profile canonical. If the local Codex refresh fails and Codex CLI has a
-  usable token for the same account, FengMing 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
-fengming agents add work
-fengming 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:
-
-- `fengming 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/parallel-specialist-lanes.md

@@ -1,127 +0,0 @@
----
-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.
-
-FengMing 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)

package/docs/concepts/personal-agent-benchmark-pack.md

@@ -1,74 +0,0 @@
----
-summary: "Local qa-channel scenarios for privacy-preserving personal assistant workflow checks."
-read_when:
-  - Running local personal agent reliability checks
-  - Extending the repo-backed QA scenario catalog
-  - Verifying reminder, reply, memory, redaction, safe tool followthrough, task status, share-safe diagnostics, proof-backed completion claims, and failure recovery
-title: "Personal agent benchmark pack"
----
-
-The Personal Agent Benchmark Pack is a small repo-backed QA scenario pack for
-local personal assistant workflows. It is not a generic model benchmark and it
-does not require a new runner. The pack reuses the private QA stack described in
-[QA overview](/concepts/qa-e2e-automation), the synthetic
-[QA channel](/channels/qa-channel), and the existing `qa/scenarios` markdown
-catalog.
-
-The first pack is intentionally narrow:
-
-- fake personal reminders through local cron delivery
-- fake DM and thread reply routing through `qa-channel`
-- fake preference recall from the temporary QA workspace memory files
-- fake secret no-echo checks
-- safe read-backed tool followthrough after a short approval-style turn
-- approval denial stop behavior for a sensitive local read request
-- proof-backed task status reporting that keeps pending, blocked, and done separate
-- share-safe diagnostics artifacts that keep useful status while omitting raw personal content
-- proof-backed completion claims that avoid fake progress before local evidence exists
-- failure recovery that reports partial status and keeps retry boundaries clear
-
-## Scenarios
-
-The machine-readable pack metadata lives in
-`extensions/qa-lab/src/scenario-packs.ts`. Run the pack with
-`--pack personal-agent`:
-
-```bash
-FENGMING_ENABLE_PRIVATE_QA_CLI=1 pnpm fengming qa suite \
-  --provider-mode mock-openai \
-  --pack personal-agent \
-  --concurrency 1
-```
-
-`--pack` is additive with repeated `--scenario` flags. Explicit scenarios run
-first, then the pack scenarios run in `QA_PERSONAL_AGENT_SCENARIO_IDS` order with
-duplicates removed.
-
-The pack is designed for `qa-channel` with `mock-openai` or another local QA
-provider lane. It should not be pointed at live chat services or real personal
-accounts.
-
-## Privacy Model
-
-The scenarios use only fake users, fake preferences, fake secrets, and the
-temporary QA gateway workspace created by the suite. They must not read or write
-real FengMing user memory, sessions, credentials, launch agents, global configs,
-or live gateway state.
-
-Artifacts stay under the existing QA suite artifact directory and should be
-treated like test output. Redaction checks use fake markers so failures are safe
-to inspect and file in issues.
-
-## Extending The Pack
-
-Add new cases under `qa/scenarios/personal/`, then add the scenario id to
-`QA_PERSONAL_AGENT_SCENARIO_IDS`. Keep each case small, local, deterministic in
-`mock-openai`, and focused on one personal assistant behavior.
-
-Good follow-up candidates:
-
-- redacted trajectory export checks
-- local-only plugin workflow checks
-
-Avoid adding a new runner, plugin, dependency, live transport, or model judge
-until the scenario catalog has enough stable cases to justify that surface.

package/docs/concepts/presence.md

@@ -1,117 +0,0 @@
----
-summary: "How FengMing presence entries are produced, merged, and displayed"
-read_when:
-  - Debugging the Instances tab
-  - Investigating duplicate or stale instance rows
-  - Changing gateway WS connect or system-event beacons
-title: "Presence"
----
-
-FengMing "presence" is a lightweight, best-effort view of:
-
-- the **Gateway** itself, and
-- **clients connected to the Gateway** (mac app, WebChat, CLI, etc.)
-
-Presence is used primarily to render the macOS app's **Instances** tab and to
-provide quick operator visibility.
-
-## Presence fields (what shows up)
-
-Presence entries are structured objects with fields like:
-
-- `instanceId` (optional but strongly recommended): stable client identity (usually `connect.client.instanceId`)
-- `host`: human-friendly host name
-- `ip`: best-effort IP address
-- `version`: client version string
-- `deviceFamily` / `modelIdentifier`: hardware hints
-- `mode`: `ui`, `webchat`, `cli`, `backend`, `probe`, `test`, `node`, ...
-- `lastInputSeconds`: "seconds since last user input" (if known)
-- `reason`: `self`, `connect`, `node-connected`, `periodic`, ...
-- `ts`: last update timestamp (ms since epoch)
-
-## Producers (where presence comes from)
-
-Presence entries are produced by multiple sources and **merged**.
-
-### 1) Gateway self entry
-
-The Gateway always seeds a "self" entry at startup so UIs show the gateway host
-even before any clients connect.
-
-### 2) WebSocket connect
-
-Every WS client begins with a `connect` request. On successful handshake the
-Gateway upserts a presence entry for that connection.
-
-#### Why one-off CLI commands do not show up
-
-The CLI often connects for short, one-off commands. To avoid spamming the
-Instances list, `client.mode === "cli"` is **not** turned into a presence entry.
-
-### 3) `system-event` beacons
-
-Clients can send richer periodic beacons via the `system-event` method. The mac
-app uses this to report host name, IP, and `lastInputSeconds`.
-
-### 4) Node connects (role: node)
-
-When a node connects over the Gateway WebSocket with `role: node`, the Gateway
-upserts a presence entry for that node (same flow as other WS clients).
-
-## Merge + dedupe rules (why `instanceId` matters)
-
-Presence entries are stored in a single in-memory map:
-
-- Entries are keyed by a **presence key**.
-- The best key is a stable `instanceId` (from `connect.client.instanceId`) that survives restarts.
-- Keys are case-insensitive.
-
-If a client reconnects without a stable `instanceId`, it may show up as a
-**duplicate** row.
-
-## TTL and bounded size
-
-Presence is intentionally ephemeral:
-
-- **TTL:** entries older than 5 minutes are pruned
-- **Max entries:** 200 (oldest dropped first)
-
-This keeps the list fresh and avoids unbounded memory growth.
-
-## Remote/tunnel caveat (loopback IPs)
-
-When a client connects over an SSH tunnel / local port forward, the Gateway may
-see the remote address as `127.0.0.1`. To avoid overwriting a good client-reported
-IP, loopback remote addresses are ignored.
-
-## Consumers
-
-### macOS Instances tab
-
-The macOS app renders the output of `system-presence` and applies a small status
-indicator (Active/Idle/Stale) based on the age of the last update.
-
-## Debugging tips
-
-- To see the raw list, call `system-presence` against the Gateway.
-- If you see duplicates:
-  - confirm clients send a stable `client.instanceId` in the handshake
-  - confirm periodic beacons use the same `instanceId`
-  - check whether the connection-derived entry is missing `instanceId` (duplicates are expected)
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Typing indicators" href="/concepts/typing-indicators" icon="ellipsis">
-    When typing indicators are sent and how to tune them.
-  </Card>
-  <Card title="Streaming and chunking" href="/concepts/streaming" icon="bars-staggered">
-    Outbound streaming, chunking, and per-channel formatting.
-  </Card>
-  <Card title="Gateway architecture" href="/concepts/architecture" icon="diagram-project">
-    Gateway components and the WebSocket protocol that drives presence updates.
-  </Card>
-  <Card title="Gateway protocol" href="/gateway/protocol" icon="plug">
-    The wire protocol for `connect`, `system-event`, and `system-presence`.
-  </Card>
-</CardGroup>