fengming 0.3.9 → 0.3.11

package/docs/fengming-agent-runtime.md

@@ -1,82 +0,0 @@
----
-summary: "Developer workflow for FengMing agent runtime: build, test, and live validation"
-title: "FengMing agent runtime workflow"
-read_when:
-  - Working on FengMing agent runtime code or tests
-  - Running agent-runtime lint, typecheck, and live test flows
----
-
-A sane workflow for working on the FengMing agent runtime in FengMing.
-
-## Type checking and linting
-
-- Default local gate: `pnpm check`
-- Build gate: `pnpm build` when the change can affect build output, packaging, or lazy-loading/module boundaries
-- Full landing gate for agent-runtime changes: `pnpm check && pnpm test`
-
-## Running Agent Runtime Tests
-
-Run the agent-runtime test set directly with Vitest:
-
-```bash
-pnpm test \
-  "src/agents/agent-*.test.ts" \
-  "src/agents/embedded-agent-*.test.ts" \
-  "src/agents/agent-tools*.test.ts" \
-  "src/agents/agent-settings.test.ts" \
-  "src/agents/agent-tool-definition-adapter*.test.ts" \
-  "src/agents/agent-hooks/**/*.test.ts"
-```
-
-To include the live provider exercise:
-
-```bash
-FENGMING_LIVE_TEST=1 pnpm test src/agents/embedded-agent-runner-extraparams.live.test.ts
-```
-
-This covers the main agent runtime unit suites:
-
-- `src/agents/agent-*.test.ts`
-- `src/agents/embedded-agent-*.test.ts`
-- `src/agents/agent-tools*.test.ts`
-- `src/agents/agent-settings.test.ts`
-- `src/agents/agent-tool-definition-adapter.test.ts`
-- `src/agents/agent-hooks/*.test.ts`
-
-## Manual testing
-
-Recommended flow:
-
-- Run the gateway in dev mode:
-  - `pnpm gateway:dev`
-- Trigger the agent directly:
-  - `pnpm fengming agent --message "Hello" --thinking low`
-- Use the TUI for interactive debugging:
-  - `pnpm tui`
-
-For tool call behavior, prompt for a `read` or `exec` action so you can see tool streaming and payload handling.
-
-## Clean slate reset
-
-State lives under the FengMing state directory. Default is `~/.fengming`. If `FENGMING_STATE_DIR` is set, use that directory instead.
-
-To reset everything:
-
-- `fengming.json` for config
-- `agents/<agentId>/agent/auth-profiles.json` for model auth profiles (API keys + OAuth)
-- `credentials/` for provider/channel state that still lives outside the auth profile store
-- `agents/<agentId>/sessions/` for agent session history
-- `agents/<agentId>/sessions/sessions.json` for the session index
-- `sessions/` if legacy paths exist
-- `workspace/` if you want a blank workspace
-
-If you only want to reset sessions, delete `agents/<agentId>/sessions/` for that agent. If you want to keep auth, leave `agents/<agentId>/agent/auth-profiles.json` and any provider state under `credentials/` in place.
-
-## References
-
-- [Testing](/help/testing)
-- [Getting Started](/start/getting-started)
-
-## Related
-
-- [FengMing agent runtime architecture](/agent-runtime-architecture)

package/docs/gateway/authentication.md

@@ -1,256 +0,0 @@
----
-summary: "Model authentication: OAuth, API keys, Claude CLI reuse, and Anthropic setup-token"
-read_when:
-  - Debugging model auth or OAuth expiry
-  - Documenting authentication or credential storage
-title: "Authentication"
----
-
-<Note>
-This page is the **model provider** authentication reference (API keys, OAuth, Claude CLI reuse, and Anthropic setup-token). For **gateway connection** authentication (token, password, trusted-proxy), see [Configuration](/gateway/configuration) and [Trusted Proxy Auth](/gateway/trusted-proxy-auth).
-</Note>
-
-FengMing supports OAuth and API keys for model providers. For always-on gateway
-hosts, API keys are usually the most predictable option. Subscription/OAuth
-flows are also supported when they match your provider account model.
-
-See [/concepts/oauth](/concepts/oauth) for the full OAuth flow and storage
-layout.
-For SecretRef-based auth (`env`/`file`/`exec` providers), see [Secrets Management](/gateway/secrets).
-For credential eligibility/reason-code rules used by `models status --probe`, see
-[Auth Credential Semantics](/auth-credential-semantics).
-
-## Recommended setup (API key, any provider)
-
-If you're running a long-lived gateway, start with an API key for your chosen
-provider.
-For Anthropic specifically, API key auth is still the most predictable server
-setup, but FengMing also supports reusing a local Claude CLI login.
-
-1. Create an API key in your provider console.
-2. Put it on the **gateway host** (the machine running `fengming gateway`).
-
-```bash
-export <PROVIDER>_API_KEY="..."
-fengming models status
-```
-
-3. If the Gateway runs under systemd/launchd, prefer putting the key in
-   `~/.fengming/.env` so the daemon can read it:
-
-```bash
-cat >> ~/.fengming/.env <<'EOF'
-<PROVIDER>_API_KEY=...
-EOF
-```
-
-Then restart the daemon (or restart your Gateway process) and re-check:
-
-```bash
-fengming models status
-fengming doctor
-```
-
-If you'd rather not manage env vars yourself, onboarding can store
-API keys for daemon use: `fengming onboard`.
-
-See [Help](/help) for details on env inheritance (`env.shellEnv`,
-`~/.fengming/.env`, systemd/launchd).
-
-## Anthropic: Claude CLI and token compatibility
-
-Anthropic setup-token auth is still available in FengMing as a supported token
-path. Anthropic staff has since told us that FengMing-style Claude CLI usage is
-allowed again, so FengMing treats Claude CLI reuse and `claude -p` usage as
-sanctioned for this integration unless Anthropic publishes a new policy. When
-Claude CLI reuse is available on the host, that is now the preferred path.
-
-For long-lived gateway hosts, an Anthropic API key is still the most predictable
-setup. If you want to reuse an existing Claude login on the same host, use the
-Anthropic Claude CLI path in onboarding/configure.
-
-Recommended host setup for Claude CLI reuse:
-
-```bash
-# Run on the gateway host
-claude auth login
-claude auth status --text
-fengming models auth login --provider anthropic --method cli --set-default
-```
-
-This is a two-step setup:
-
-1. Log Claude Code itself into Anthropic on the gateway host.
-2. Tell FengMing to switch Anthropic model selection to the local `claude-cli`
-   backend and store the matching FengMing auth profile.
-
-If `claude` is not on `PATH`, either install Claude Code first or set
-`agents.defaults.cliBackends.claude-cli.command` to the real binary path.
-
-Manual token entry (any provider; writes `auth-profiles.json` + updates config):
-
-```bash
-fengming models auth paste-token --provider openrouter
-```
-
-`auth-profiles.json` stores credentials only. The canonical shape is:
-
-```json
-{
-  "version": 1,
-  "profiles": {
-    "openrouter:default": {
-      "type": "api_key",
-      "provider": "openrouter",
-      "key": "OPENROUTER_API_KEY"
-    }
-  }
-}
-```
-
-FengMing expects the canonical `version` + `profiles` shape at runtime. If an older install still has a flat file such as `{ "openrouter": { "apiKey": "..." } }`, run `fengming doctor --fix` to rewrite it as an `openrouter:default` API-key profile; doctor keeps a `.legacy-flat.*.bak` copy beside the original. Endpoint details such as `baseUrl`, `api`, model ids, headers, and timeouts belong under `models.providers.<id>` in `fengming.json` or `models.json`, not in `auth-profiles.json`.
-
-External auth routes such as Bedrock `auth: "aws-sdk"` are also not credentials. If you want a named Bedrock route, put `auth.profiles.<id>.mode: "aws-sdk"` in `fengming.json`; do not write `type: "aws-sdk"` into `auth-profiles.json`. `fengming doctor --fix` moves legacy AWS SDK markers from the credential store into config metadata.
-
-Auth profile refs are also supported for static credentials:
-
-- `api_key` credentials can use `keyRef: { source, provider, id }`
-- `token` credentials can use `tokenRef: { source, provider, id }`
-- OAuth-mode profiles do not support SecretRef credentials; if `auth.profiles.<id>.mode` is set to `"oauth"`, SecretRef-backed `keyRef`/`tokenRef` input for that profile is rejected.
-
-Automation-friendly check (exit `1` when expired/missing, `2` when expiring):
-
-```bash
-fengming models status --check
-```
-
-Live auth probes:
-
-```bash
-fengming models status --probe
-```
-
-Notes:
-
-- Probe rows can come from auth profiles, env credentials, or `models.json`.
-- If explicit `auth.order.<provider>` omits a stored profile, probe reports
-  `excluded_by_auth_order` for that profile instead of trying it.
-- If auth exists but FengMing cannot resolve a probeable model candidate for
-  that provider, probe reports `status: no_model`.
-- Rate-limit cooldowns can be model-scoped. A profile cooling down for one
-  model can still be usable for a sibling model on the same provider.
-
-Optional ops scripts (systemd/Termux) are documented here:
-[Auth monitoring scripts](/help/scripts#auth-monitoring-scripts)
-
-## Anthropic note
-
-The Anthropic `claude-cli` backend is supported again.
-
-- Anthropic staff told us this FengMing integration path is allowed again.
-- FengMing therefore treats Claude CLI reuse and `claude -p` usage as sanctioned
-  for Anthropic-backed runs unless Anthropic publishes a new policy.
-- Anthropic API keys remain the most predictable choice for long-lived gateway
-  hosts and explicit server-side billing control.
-
-## Checking model auth status
-
-```bash
-fengming models status
-fengming doctor
-```
-
-## API key rotation behavior (gateway)
-
-Some providers support retrying a request with alternative keys when an API call
-hits a provider rate limit.
-
-- Priority order:
-  - `FENGMING_LIVE_<PROVIDER>_KEY` (single override)
-  - `<PROVIDER>_API_KEYS`
-  - `<PROVIDER>_API_KEY`
-  - `<PROVIDER>_API_KEY_*`
-- Google providers also include `GOOGLE_API_KEY` as an additional fallback.
-- The same key list is deduplicated before use.
-- FengMing retries with the next key only for rate-limit errors (for example
-  `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent
-requests`, `ThrottlingException`, `concurrency limit reached`, or
-  `workers_ai ... quota limit exceeded`).
-- Non-rate-limit errors are not retried with alternate keys.
-- If all keys fail, the final error from the last attempt is returned.
-
-## Removing provider auth while the gateway is running
-
-When provider auth is removed through the Gateway control plane, FengMing deletes
-the saved auth profiles for that provider and aborts active chat or agent runs
-whose selected model provider matches the removed provider. The aborted runs emit
-the normal chat cancellation and lifecycle events with
-`stopReason: "auth-revoked"`, so connected clients can show that the run was
-stopped because credentials were removed.
-
-Removing saved auth does not revoke keys at the provider. Rotate or revoke the
-key in the provider dashboard when you need provider-side invalidation.
-
-## Controlling which credential is used
-
-### During login (CLI)
-
-Use `fengming models auth login --provider <id> --profile-id <profileId>` for
-providers that support named auth profiles during login.
-
-```bash
-fengming models auth login --provider openai --profile-id openai:ritsuko
-fengming models auth login --provider openai --profile-id openai:lain
-```
-
-This is the easiest way to keep multiple OAuth logins for the same provider
-separate inside one agent.
-
-### Per-session (chat command)
-
-Use `/model <alias-or-id>@<profileId>` to pin a specific provider credential for the current session (example profile ids: `anthropic:default`, `anthropic:work`).
-
-Use `/model` (or `/model list`) for a compact picker; use `/model status` for the full view (candidates + next auth profile, plus provider endpoint details when configured).
-
-### Per-agent (CLI override)
-
-Set an explicit auth profile order override for an agent (stored in that agent's `auth-state.json`):
-
-```bash
-fengming models auth order get --provider anthropic
-fengming models auth order set --provider anthropic anthropic:default
-fengming models auth order clear --provider anthropic
-```
-
-Use `--agent <id>` to target a specific agent; omit it to use the configured default agent.
-When you debug order issues, `fengming models status --probe` shows omitted
-stored profiles as `excluded_by_auth_order` instead of silently skipping them.
-When you debug cooldown issues, remember that rate-limit cooldowns can be tied
-to one model id rather than the whole provider profile.
-
-If you change auth order or profile pinning for a chat that is already running,
-send `/new` or `/reset` in that chat to start a fresh session. Existing
-sessions can keep their current model/profile selection until reset.
-
-## Troubleshooting
-
-### "No credentials found"
-
-If the Anthropic profile is missing, configure an Anthropic API key on the
-**gateway host** or set up the Anthropic setup-token path, then re-check:
-
-```bash
-fengming models status
-```
-
-### Token expiring/expired
-
-Run `fengming models status` to confirm which profile is expiring. If an
-Anthropic token profile is missing or expired, refresh that setup via
-setup-token or migrate to an Anthropic API key.
-
-## Related
-
-- [Secrets management](/gateway/secrets)
-- [Remote access](/gateway/remote)
-- [Auth storage](/concepts/oauth)

package/docs/gateway/background-process.md

@@ -1,147 +0,0 @@
----
-summary: "Background exec execution and process management"
-read_when:
-  - Adding or modifying background exec behavior
-  - Debugging long-running exec tasks
-title: "Background exec and process tool"
----
-
-FengMing runs shell commands through the `exec` tool and keeps long-running tasks in memory. The `process` tool manages those background sessions.
-
-## exec tool
-
-Key parameters:
-
-- `command` (required)
-- `yieldMs` (default 10000): auto-background after this delay
-- `background` (bool): background immediately
-- `timeout` (seconds, default `tools.exec.timeoutSec`): kill the process after this timeout; set `timeout: 0` only to disable the exec process timeout for that call
-- `elevated` (bool): run outside the sandbox if elevated mode is enabled/allowed (`gateway` by default, or `node` when the exec target is `node`)
-- Need a real TTY? Set `pty: true`.
-- `workdir`, `env`
-
-Behavior:
-
-- Foreground runs return output directly.
-- When backgrounded (explicit or timeout), the tool returns `status: "running"` + `sessionId` and a short tail.
-- Background and `yieldMs` runs inherit `tools.exec.timeoutSec` unless the call provides an explicit `timeout`.
-- Output is kept in memory until the session is polled or cleared.
-- If the `process` tool is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
-- Spawned exec commands receive `FENGMING_SHELL=exec` for context-aware shell/profile rules.
-- For long-running work that starts now, start it once and rely on automatic
-  completion wake when it is enabled and the command emits output or fails.
-- If automatic completion wake is unavailable, or you need quiet-success
-  confirmation for a command that exited cleanly without output, use `process`
-  to confirm completion.
-- Do not emulate reminders or delayed follow-ups with `sleep` loops or repeated
-  polling; use cron for future work.
-
-## Child process bridging
-
-When spawning long-running child processes outside the exec/process tools (for example, CLI respawns or gateway helpers), attach the child-process bridge helper so termination signals are forwarded and listeners are detached on exit/error. This avoids orphaned processes on systemd and keeps shutdown behavior consistent across platforms.
-
-Environment overrides:
-
-- `FENGMING_BASH_YIELD_MS`: default yield (ms)
-- `FENGMING_BASH_MAX_OUTPUT_CHARS`: in-memory output cap (chars)
-- `FENGMING_BASH_PENDING_MAX_OUTPUT_CHARS`: pending stdout/stderr cap per stream (chars)
-- `FENGMING_BASH_JOB_TTL_MS`: TTL for finished sessions (ms, bounded to 1m–3h)
-- `FENGMING_PROCESS_INPUT_WAIT_IDLE_MS`: idle-output threshold before writable background sessions are marked as likely waiting for input (default 15000 ms)
-
-Config (preferred):
-
-- `tools.exec.backgroundMs` (default 10000)
-- `tools.exec.timeoutSec` (default 1800)
-- `tools.exec.cleanupMs` (default 1800000)
-- `tools.exec.notifyOnExit` (default true): enqueue a system event + request heartbeat when a backgrounded exec exits.
-- `tools.exec.notifyOnExitEmptySuccess` (default false): when true, also enqueue completion events for successful backgrounded runs that produced no output.
-
-## process tool
-
-Actions:
-
-- `list`: running + finished sessions
-- `poll`: drain new output for a session (also reports exit status)
-- `log`: read the aggregated output and show input recovery hints (supports `offset` + `limit`)
-- `write`: send stdin (`data`, optional `eof`)
-- `send-keys`: send explicit key tokens or bytes to a PTY-backed session
-- `submit`: send Enter / carriage return to a PTY-backed session
-- `paste`: send literal text, optionally wrapped in bracketed paste mode
-- `kill`: terminate a background session
-- `clear`: remove a finished session from memory
-- `remove`: kill if running, otherwise clear if finished
-
-Notes:
-
-- Only backgrounded sessions are listed/persisted in memory.
-- Sessions are lost on process restart (no disk persistence).
-- Session logs are only saved to chat history if you run `process poll/log` and the tool result is recorded.
-- `process` is scoped per agent; it only sees sessions started by that agent.
-- Use `poll` / `log` for status, logs, quiet-success confirmation, or
-  completion confirmation when automatic completion wake is unavailable.
-- Use `log` before recovering an interactive CLI so the current transcript,
-  stdin state, and input-wait hint are visible together.
-- Use `write` / `send-keys` / `submit` / `paste` / `kill` when you need input
-  or intervention.
-- `process list` includes a derived `name` (command verb + target) for quick scans.
-- `process list`, `poll`, and `log` report `waitingForInput` only
-  when the session still has writable stdin and has been idle longer than the
-  input-wait threshold.
-- `process log` uses line-based `offset`/`limit`.
-- When both `offset` and `limit` are omitted, it returns the last 200 lines and includes a paging hint.
-- When `offset` is provided and `limit` is omitted, it returns from `offset` to the end (not capped to 200).
-- Polling is for on-demand status, not wait-loop scheduling. If the work should
-  happen later, use cron instead.
-
-## Examples
-
-Run a long task and poll later:
-
-```json
-{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }
-```
-
-```json
-{ "tool": "process", "action": "poll", "sessionId": "<id>" }
-```
-
-Inspect an interactive session before sending input:
-
-```json
-{ "tool": "process", "action": "log", "sessionId": "<id>" }
-```
-
-Start immediately in background:
-
-```json
-{ "tool": "exec", "command": "npm run build", "background": true }
-```
-
-Send stdin:
-
-```json
-{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }
-```
-
-Send PTY keys:
-
-```json
-{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }
-```
-
-Submit current line:
-
-```json
-{ "tool": "process", "action": "submit", "sessionId": "<id>" }
-```
-
-Paste literal text:
-
-```json
-{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
-```
-
-## Related
-
-- [Exec tool](/tools/exec)
-- [Exec approvals](/tools/exec-approvals)