fengming 0.3.9 → 0.3.11

package/docs/concepts/experimental-features.md

@@ -1,109 +0,0 @@
----
-summary: "What experimental flags mean in FengMing and which ones are currently documented"
-title: "Experimental features"
-read_when:
-  - You see an `.experimental` config key and want to know whether it is stable
-  - You want to try preview runtime features without confusing them with normal defaults
-  - You want one place to find the currently documented experimental flags
----
-
-Experimental features in FengMing are **opt-in preview surfaces**. They are
-behind explicit flags because they still need real-world mileage before they
-deserve a stable default or a long-lived public contract.
-
-Treat them differently from normal config:
-
-- Keep them **off by default** unless the related doc tells you to try one.
-- Expect **shape and behavior to change** faster than stable config.
-- Prefer the stable path first when one already exists.
-- If you are rolling FengMing out broadly, test experimental flags in a smaller
-  environment before baking them into a shared baseline.
-
-## Currently documented flags
-
-| Surface                  | Key                                                                                        | Use it when                                                                                                                       | More                                                                                          |
-| ------------------------ | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| Local model runtime      | `agents.defaults.experimental.localModelLean`, `agents.list[].experimental.localModelLean` | A smaller or stricter local backend chokes on FengMing's full default tool surface                                                | [Local Models](/gateway/local-models)                                                         |
-| Memory search            | `agents.defaults.memorySearch.experimental.sessionMemory`                                  | You want `memory_search` to index prior session transcripts and accept the extra storage/indexing cost                            | [Memory configuration reference](/reference/memory-config#session-memory-search-experimental) |
-| Codex harness            | `plugins.entries.codex.config.appServer.experimental.sandboxExecServer`                    | You want native Codex app-server 0.132.0 or newer to target an FengMing sandbox-backed exec-server instead of disabling Code Mode | [Codex harness reference](/plugins/codex-harness-reference#sandboxed-native-execution)        |
-| Structured planning tool | `tools.experimental.planTool`                                                              | You want the structured `update_plan` tool exposed for multi-step work tracking in compatible runtimes and UIs                    | [Gateway configuration reference](/gateway/config-tools#toolsexperimental)                    |
-
-## Local model lean mode
-
-`agents.defaults.experimental.localModelLean: true` is a pressure-release valve for weaker local-model setups. When it is on, FengMing drops three default tools — `browser`, `cron`, and `message` — from the agent's tool surface for every turn. Nothing else changes. Use `agents.list[].experimental.localModelLean` to enable or disable the same behavior for one configured agent.
-
-### Why these three tools
-
-These three tools have the largest descriptions and the most parameter shapes in the default FengMing runtime. On a small-context or stricter OpenAI-compatible backend that is the difference between:
-
-- Tool schemas fitting cleanly in the prompt vs. crowding out conversation history.
-- The model picking the right tool vs. emitting malformed tool calls because there are too many similar-looking schemas.
-- The Chat Completions adapter staying inside the server's structured-output limits vs. tripping a 400 on tool-call payload size.
-
-Removing them does not silently rewire FengMing — it just makes the tool list shorter. The model still has `read`, `write`, `edit`, `exec`, `apply_patch`, web search/fetch (when configured), memory, and session/agent tools available.
-
-### When to turn it on
-
-Enable lean mode when you have already proved the model can talk to the Gateway but full agent turns misbehave. The typical signal chain is:
-
-1. `fengming infer model run --gateway --model <ref> --prompt "Reply with exactly: pong"` succeeds.
-2. A normal agent turn fails with malformed tool calls, oversized prompts, or the model ignoring its tools.
-3. Toggling `localModelLean: true` clears the failure.
-
-### When to leave it off
-
-If your backend handles the full default runtime cleanly, leave this off. Lean mode is a workaround, not a default. It exists because some local stacks need a smaller tool surface to behave; hosted models and well-resourced local rigs do not.
-
-Lean mode also does not replace `tools.profile`, `tools.allow`/`tools.deny`, or the model `compat.supportsTools: false` escape hatch. If you need a permanent narrower tool surface for a specific agent, prefer those stable knobs over the experimental flag.
-
-### Enable
-
-```json5
-{
-  agents: {
-    defaults: {
-      experimental: {
-        localModelLean: true,
-      },
-    },
-  },
-}
-```
-
-For one agent only:
-
-```json5
-{
-  agents: {
-    list: [
-      {
-        id: "local",
-        model: "lmstudio/gemma-4-e4b-it",
-        experimental: {
-          localModelLean: true,
-        },
-      },
-    ],
-  },
-}
-```
-
-Restart the Gateway after changing the flag, then confirm the trimmed tool list with:
-
-```bash
-fengming status --deep
-```
-
-The deep status output lists the active agent tools; `browser`, `cron`, and `message` should be absent when lean mode is on.
-
-## Experimental does not mean hidden
-
-If a feature is experimental, FengMing should say so plainly in docs and in the
-config path itself. What it should **not** do is smuggle preview behavior into a
-stable-looking default knob and pretend that is normal. That's how config
-surfaces get messy.
-
-## Related
-
-- [Features](/concepts/features)
-- [Release channels](/install/development-channels)

package/docs/concepts/features.md

@@ -1,91 +0,0 @@
----
-summary: "FengMing capabilities across channels, routing, media, and UX."
-read_when:
-  - You want a full list of what FengMing supports
-title: "Features"
----
-
-## Highlights
-
-<Columns>
-  <Card title="Channels" icon="message-square" href="/channels">
-    Discord, iMessage, Signal, Slack, Telegram, WhatsApp, WebChat, and more with a single Gateway.
-  </Card>
-  <Card title="Plugins" icon="plug" href="/tools/plugin">
-    Bundled plugins add Matrix, Nextcloud Talk, Nostr, Twitch, Zalo, and more without separate installs in normal current releases.
-  </Card>
-  <Card title="Routing" icon="route" href="/concepts/multi-agent">
-    Multi-agent routing with isolated sessions.
-  </Card>
-  <Card title="Media" icon="image" href="/nodes/images">
-    Images, audio, video, documents, and image/video generation.
-  </Card>
-  <Card title="Apps and UI" icon="monitor" href="/web/control-ui">
-    Web Control UI and macOS companion app.
-  </Card>
-  <Card title="Mobile nodes" icon="smartphone" href="/nodes">
-    iOS and Android nodes with pairing, voice/chat, and rich device commands.
-  </Card>
-</Columns>
-
-## Full list
-
-**Channels:**
-
-- Built-in channels include Discord, Google Chat, iMessage, IRC, Signal, Slack, Telegram, WebChat, and WhatsApp
-- Bundled plugin channels include Feishu, LINE, Matrix, Mattermost, Microsoft Teams, Nextcloud Talk, Nostr, QQ Bot, Synology Chat, Tlon, Twitch, Zalo, and Zalo Personal
-- Optional separately installed channel plugins include Voice Call and third-party packages such as WeChat
-- Third-party channel plugins can extend the Gateway further, such as WeChat
-- Group chat support with mention-based activation
-- DM safety with allowlists and pairing
-
-**Agent:**
-
-- Embedded agent runtime with tool streaming
-- Multi-agent routing with isolated sessions per workspace or sender
-- Sessions: direct chats collapse into shared `main`; groups are isolated
-- Streaming and chunking for long responses
-
-**Auth and providers:**
-
-- 35+ model providers (Anthropic, OpenAI, Google, and more)
-- Subscription auth via OAuth (e.g. OpenAI Codex)
-- Custom and self-hosted provider support (vLLM, SGLang, Ollama, and any OpenAI-compatible or Anthropic-compatible endpoint)
-
-**Media:**
-
-- Images, audio, video, and documents in and out
-- Shared image generation and video generation capability surfaces
-- Voice note transcription
-- Text-to-speech with multiple providers
-
-**Apps and interfaces:**
-
-- WebChat and browser Control UI
-- macOS menu bar companion app
-- iOS node with pairing, Canvas, camera, screen recording, location, and voice
-- Android node with pairing, chat, voice, Canvas, camera, and device commands
-
-**Tools and automation:**
-
-- Browser automation, exec, sandboxing
-- Web search (Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily)
-- Cron jobs and heartbeat scheduling
-- Skills, plugins, and workflow pipelines (Lobster)
-
-## Related
-
-<CardGroup cols={2}>
-  <Card title="Experimental features" href="/concepts/experimental-features" icon="flask">
-    Opt-in features that have not yet shipped to the default surface.
-  </Card>
-  <Card title="Agent runtime" href="/concepts/agent" icon="robot">
-    Agent runtime model and how runs are dispatched.
-  </Card>
-  <Card title="Channels" href="/channels" icon="message-square">
-    Connect Telegram, WhatsApp, Discord, Slack, and more from one Gateway.
-  </Card>
-  <Card title="Plugins" href="/tools/plugin" icon="plug">
-    Bundled and third-party plugins that extend FengMing.
-  </Card>
-</CardGroup>

package/docs/concepts/fengming-sdk.md

@@ -1,323 +0,0 @@
----
-summary: "Public FengMing App SDK for external apps, scripts, dashboards, CI jobs, and IDE extensions"
-title: "FengMing App SDK"
-sidebarTitle: "App SDK"
-read_when:
-  - You are building an external app, script, dashboard, CI job, or IDE extension that talks to FengMing
-  - You are choosing between the App SDK and the Plugin SDK
-  - You are integrating with Gateway agent runs, sessions, events, approvals, models, or tools
----
-
-The **FengMing App SDK** is the public client API for apps outside the
-FengMing process. Use `@fengming/sdk` when a script, dashboard, CI job, IDE
-extension, or other external app wants to connect to the Gateway, start agent
-runs, stream events, wait for results, cancel work, or inspect Gateway
-resources.
-
-<Note>
-  The App SDK is different from the [Plugin SDK](/plugins/sdk-overview).
-  `@fengming/sdk` talks to the Gateway from outside FengMing.
-  `fengming/plugin-sdk/*` is only for plugins that run inside FengMing and
-  register providers, channels, tools, hooks, or trusted runtimes.
-</Note>
-
-## What ships today
-
-`@fengming/sdk` ships with:
-
-| Surface                   | Status  | What it does                                                                      |
-| ------------------------- | ------- | --------------------------------------------------------------------------------- |
-| `FengMing`                | Ready   | Main client entry point. Owns transport, connection, requests, and events.        |
-| `GatewayClientTransport`  | Ready   | WebSocket transport backed by the Gateway client.                                 |
-| `oc.agents`               | Ready   | Lists, creates, updates, deletes, and gets agent handles.                         |
-| `Agent.run()`             | Ready   | Starts a Gateway `agent` run and returns a `Run`.                                 |
-| `oc.runs`                 | Ready   | Creates, gets, waits for, cancels, and streams runs.                              |
-| `Run.events()`            | Ready   | Streams normalized per-run events with replay for fast runs.                      |
-| `Run.wait()`              | Ready   | Calls `agent.wait` and returns a stable `RunResult`.                              |
-| `Run.cancel()`            | Ready   | Calls `sessions.abort` by run id, with session key when available.                |
-| `oc.sessions`             | Ready   | Creates, resolves, sends to, patches, compacts, and gets session handles.         |
-| `Session.send()`          | Ready   | Calls `sessions.send` and returns a `Run`.                                        |
-| `oc.tasks`                | Ready   | Lists, reads, and cancels Gateway task ledger entries.                            |
-| `oc.models`               | Ready   | Calls `models.list` and the current `models.authStatus` status RPC.               |
-| `oc.tools`                | Ready   | Lists, scopes, and invokes Gateway tools through the policy pipeline.             |
-| `oc.artifacts`            | Ready   | Lists, gets, and downloads Gateway transcript artifacts.                          |
-| `oc.approvals`            | Ready   | Lists and resolves exec approvals through Gateway approval RPCs.                  |
-| `oc.environments`         | Partial | Lists Gateway-local and node environment candidates; create/delete are not wired. |
-| `oc.rawEvents()`          | Ready   | Exposes raw Gateway events for advanced consumers.                                |
-| `normalizeGatewayEvent()` | Ready   | Converts raw Gateway events into the stable SDK event shape.                      |
-
-The SDK also exports the core types used by those surfaces:
-`AgentRunParams`, `RunResult`, `RunStatus`, `FengMingEvent`,
-`FengMingEventType`, `GatewayEvent`, `FengMingTransport`,
-`GatewayRequestOptions`, `SessionCreateParams`, `SessionSendParams`,
-`ArtifactSummary`, `ArtifactQuery`, `ArtifactsListResult`,
-`ArtifactsGetResult`, `ArtifactsDownloadResult`,
-`TaskSummary`, `TaskStatus`, `TasksListParams`, `TasksListResult`,
-`TasksGetResult`, `TasksCancelResult`, `RuntimeSelection`,
-`EnvironmentSelection`, `WorkspaceSelection`, `ApprovalMode`, and related
-result types.
-
-## Connect to a Gateway
-
-Create a client with an explicit Gateway URL, or inject a custom transport for
-tests and embedded app runtimes.
-
-```typescript
-import { FengMing } from "@fengming/sdk";
-
-const oc = new FengMing({
-  url: "ws://127.0.0.1:18789",
-  token: process.env.FENGMING_GATEWAY_TOKEN,
-  requestTimeoutMs: 30_000,
-});
-
-await oc.connect();
-```
-
-`new FengMing({ gateway: "ws://..." })` is equivalent to `url`. The
-`gateway: "auto"` option is accepted by the constructor, but automatic Gateway
-discovery is not a separate SDK feature yet; pass `url` when the app does not
-already know how to discover the Gateway.
-
-For tests, pass an object that implements `FengMingTransport`:
-
-```typescript
-const oc = new FengMing({
-  transport: {
-    async request(method, params) {
-      return { method, params };
-    },
-    async *events() {},
-  },
-});
-```
-
-## Run an agent
-
-Use `oc.agents.get(id)` when the app wants an agent handle, then call
-`agent.run()`.
-
-```typescript
-const agent = await oc.agents.get("main");
-
-const run = await agent.run({
-  input: "Review this pull request and suggest the smallest safe fix.",
-  model: "openai/gpt-5.5",
-  sessionKey: "main",
-  timeoutMs: 30_000,
-});
-
-for await (const event of run.events()) {
-  const data = event.data as { delta?: unknown };
-  if (event.type === "assistant.delta" && typeof data.delta === "string") {
-    process.stdout.write(data.delta);
-  }
-}
-
-const result = await run.wait({ timeoutMs: 120_000 });
-console.log(result.status);
-```
-
-Provider-qualified model refs such as `openai/gpt-5.5` are split into Gateway
-`provider` and `model` overrides. `timeoutMs` stays milliseconds in the SDK and
-is converted to Gateway timeout seconds for the `agent` RPC.
-
-`run.wait()` uses the Gateway `agent.wait` RPC. A wait deadline that expires
-while the run is still active returns `status: "accepted"` instead of pretending
-the run itself timed out. Runtime timeouts, aborted runs, and cancelled runs are
-normalized into `timed_out` or `cancelled`.
-
-## Create and reuse sessions
-
-Use sessions when the app wants durable transcript state.
-
-```typescript
-const session = await oc.sessions.create({
-  agentId: "main",
-  label: "release-review",
-});
-
-const run = await session.send("Prepare release notes from the current diff.");
-await run.wait();
-```
-
-`Session.send()` calls `sessions.send` and returns a `Run`. Session handles also
-support:
-
-```typescript
-await session.abort(run.id);
-await session.patch({ label: "renamed-session" });
-await session.compact({ maxLines: 200 });
-```
-
-## Stream events
-
-The SDK normalizes raw Gateway events into a stable `FengMingEvent` envelope:
-
-```typescript
-type FengMingEvent = {
-  version: 1;
-  id: string;
-  ts: number;
-  type: FengMingEventType;
-  runId?: string;
-  sessionId?: string;
-  sessionKey?: string;
-  taskId?: string;
-  agentId?: string;
-  data: unknown;
-  raw?: GatewayEvent;
-};
-```
-
-Common event types include:
-
-| Event type            | Source Gateway event                        |
-| --------------------- | ------------------------------------------- |
-| `run.started`         | `agent` lifecycle start                     |
-| `run.completed`       | `agent` lifecycle end                       |
-| `run.failed`          | `agent` lifecycle error                     |
-| `run.cancelled`       | Aborted/cancelled lifecycle end             |
-| `run.timed_out`       | Timeout lifecycle end                       |
-| `assistant.delta`     | Assistant streaming delta                   |
-| `assistant.message`   | Assistant message                           |
-| `thinking.delta`      | Thinking or plan stream                     |
-| `tool.call.started`   | Tool/item/command start                     |
-| `tool.call.delta`     | Tool/item/command update                    |
-| `tool.call.completed` | Tool/item/command completion                |
-| `tool.call.failed`    | Tool/item/command failure or blocked status |
-| `approval.requested`  | Exec or plugin approval request             |
-| `approval.resolved`   | Exec or plugin approval resolution          |
-| `session.created`     | `sessions.changed` create                   |
-| `session.updated`     | `sessions.changed` update                   |
-| `session.compacted`   | `sessions.changed` compaction               |
-| `task.updated`        | Task update events                          |
-| `artifact.updated`    | Patch stream events                         |
-| `raw`                 | Any event without a stable SDK mapping yet  |
-
-`Run.events()` filters events to one run id and replays already-seen events for
-fast runs. That means the documented flow is safe:
-
-```typescript
-const run = await agent.run("Summarize the latest session.");
-
-for await (const event of run.events()) {
-  if (event.type === "run.completed") {
-    break;
-  }
-}
-```
-
-For app-wide streams, use `oc.events()`. For raw Gateway frames, use
-`oc.rawEvents()`.
-
-## Models, tools, artifacts, and approvals
-
-Model helpers map to current Gateway methods:
-
-```typescript
-await oc.models.list();
-await oc.models.status({ probe: false }); // calls models.authStatus
-```
-
-Tool helpers expose the Gateway catalog, effective tool view, and direct
-Gateway tool invocation. `oc.tools.invoke()` returns a typed envelope instead
-of throwing for policy or approval refusals.
-
-```typescript
-await oc.tools.list();
-await oc.tools.effective({ sessionKey: "main" });
-await oc.tools.invoke("tool-name", {
-  args: { input: "value" },
-  sessionKey: "main",
-  confirm: false,
-  idempotencyKey: "tool-call-1",
-});
-```
-
-Artifact helpers expose the Gateway artifact projection for session, run, or
-task context. Each call requires one explicit `sessionKey`, `runId`, or
-`taskId` scope:
-
-```typescript
-const { artifacts } = await oc.artifacts.list({ sessionKey: "main" });
-const first = artifacts[0];
-
-if (first) {
-  const { artifact } = await oc.artifacts.get(first.id, { sessionKey: "main" });
-  const download = await oc.artifacts.download(artifact.id, { sessionKey: "main" });
-  console.log(download.encoding, download.url);
-}
-```
-
-Approval helpers use the exec approval RPCs:
-
-```typescript
-const approvals = await oc.approvals.list();
-await oc.approvals.respond("approval-id", { decision: "approve" });
-```
-
-Task helpers use the durable task ledger that also backs `fengming tasks`:
-
-```typescript
-const tasks = await oc.tasks.list({ status: "running", sessionKey: "agent:main:main" });
-const task = await oc.tasks.get(tasks.tasks[0].id);
-await oc.tasks.cancel(task.task.id, { reason: "user stopped task" });
-```
-
-Environment helpers expose read-only Gateway-local and node discovery:
-
-```typescript
-const { environments } = await oc.environments.list();
-await oc.environments.status(environments[0].id);
-```
-
-## Explicitly unsupported today
-
-The SDK includes names for the product model we want, but it does not silently
-pretend Gateway RPCs exist. These calls currently throw explicit unsupported
-errors:
-
-```typescript
-await oc.environments.create({});
-await oc.environments.delete("environment-id");
-```
-
-Per-run `workspace`, `runtime`, `environment`, and `approvals` fields are typed
-as future shape, but the current Gateway does not support those overrides on
-the `agent` RPC. If callers pass them, the SDK throws before submitting the run
-so work does not accidentally execute with default workspace, runtime,
-environment, or approval behavior.
-
-## App SDK vs Plugin SDK
-
-Use the App SDK when code lives outside FengMing:
-
-- Node scripts that start or observe agent runs
-- CI jobs that call a Gateway
-- dashboards and admin panels
-- IDE extensions
-- external bridges that do not need to become channel plugins
-- integration tests with fake or real Gateway transports
-
-Use the Plugin SDK when code runs inside FengMing:
-
-- provider plugins
-- channel plugins
-- tool or lifecycle hooks
-- agent harness plugins
-- trusted runtime helpers
-
-App SDK code should import from `@fengming/sdk`. Plugin code should import from
-documented `fengming/plugin-sdk/*` subpaths. Do not mix the two contracts.
-
-## Related
-
-- [FengMing App SDK API design](/reference/fengming-sdk-api-design)
-- [Gateway RPC reference](/reference/rpc)
-- [Agent loop](/concepts/agent-loop)
-- [Agent runtimes](/concepts/agent-runtimes)
-- [Sessions](/concepts/session)
-- [Background tasks](/automation/tasks)
-- [ACP agents](/tools/acp-agents)
-- [Plugin SDK overview](/plugins/sdk-overview)