fengming 0.3.9 → 0.3.11

package/docs/gateway/openresponses-http-api.md

@@ -1,347 +0,0 @@
----
-summary: "Expose an OpenResponses-compatible /v1/responses HTTP endpoint from the Gateway"
-read_when:
-  - Integrating clients that speak the OpenResponses API
-  - You want item-based inputs, client tool calls, or SSE events
-title: "OpenResponses API"
----
-
-FengMing's Gateway can serve an OpenResponses-compatible `POST /v1/responses` endpoint.
-
-This endpoint is **disabled by default**. Enable it in config first.
-
-- `POST /v1/responses`
-- Same port as the Gateway (WS + HTTP multiplex): `http://<gateway-host>:<port>/v1/responses`
-
-Under the hood, requests are executed as a normal Gateway agent run (same codepath as
-`fengming agent`), so routing/permissions/config match your Gateway.
-
-## Authentication, security, and routing
-
-Operational behavior matches [OpenAI Chat Completions](/gateway/openai-http-api):
-
-- use the matching Gateway HTTP auth path:
-  - shared-secret auth (`gateway.auth.mode="token"` or `"password"`): `Authorization: Bearer <token-or-password>`
-  - trusted-proxy auth (`gateway.auth.mode="trusted-proxy"`): identity-aware proxy headers from a configured trusted proxy source; same-host loopback proxies require explicit `gateway.auth.trustedProxy.allowLoopback = true`
-  - trusted-proxy local direct fallback: same-host callers with no `Forwarded`, `X-Forwarded-*`, or `X-Real-IP` headers can use `gateway.auth.password` / `FENGMING_GATEWAY_PASSWORD`
-  - private-ingress open auth (`gateway.auth.mode="none"`): no auth header
-- treat the endpoint as full operator access for the gateway instance
-- for shared-secret auth modes (`token` and `password`), ignore narrower bearer-declared `x-fengming-scopes` values and restore the normal full operator defaults
-- for trusted identity-bearing HTTP modes (for example trusted proxy auth or `gateway.auth.mode="none"`), honor `x-fengming-scopes` when present and otherwise fall back to the normal operator default scope set
-- select agents with `model: "fengming"`, `model: "fengming/default"`, `model: "fengming/<agentId>"`, or `x-fengming-agent-id`
-- use `x-fengming-model` when you want to override the selected agent's backend model
-- use `x-fengming-session-key` for explicit session routing
-- use `x-fengming-message-channel` when you want a non-default synthetic ingress channel context
-
-Auth matrix:
-
-- `gateway.auth.mode="token"` or `"password"` + `Authorization: Bearer ...`
-  - proves possession of the shared gateway operator secret
-  - ignores narrower `x-fengming-scopes`
-  - restores the full default operator scope set:
-    `operator.admin`, `operator.approvals`, `operator.pairing`,
-    `operator.read`, `operator.talk.secrets`, `operator.write`
-  - treats chat turns on this endpoint as owner-sender turns
-- trusted identity-bearing HTTP modes (for example trusted proxy auth, or `gateway.auth.mode="none"` on private ingress)
-  - honor `x-fengming-scopes` when the header is present
-  - fall back to the normal operator default scope set when the header is absent
-  - only lose owner semantics when the caller explicitly narrows scopes and omits `operator.admin`
-
-Enable or disable this endpoint with `gateway.http.endpoints.responses.enabled`.
-
-The same compatibility surface also includes:
-
-- `GET /v1/models`
-- `GET /v1/models/{id}`
-- `POST /v1/embeddings`
-- `POST /v1/chat/completions`
-
-For the canonical explanation of how agent-target models, `fengming/default`, embeddings pass-through, and backend model overrides fit together, see [OpenAI Chat Completions](/gateway/openai-http-api#agent-first-model-contract) and [Model list and agent routing](/gateway/openai-http-api#model-list-and-agent-routing).
-
-## Session behavior
-
-By default the endpoint is **stateless per request** (a new session key is generated each call).
-
-If the request includes an OpenResponses `user` string, the Gateway derives a stable session key
-from it, so repeated calls can share an agent session.
-
-## Request shape (supported)
-
-The request follows the OpenResponses API with item-based input. Current support:
-
-- `input`: string or array of item objects.
-- `instructions`: merged into the system prompt.
-- `tools`: client tool definitions (function tools).
-- `tool_choice`: filter or require client tools.
-- `stream`: enables SSE streaming.
-- `max_output_tokens`: best-effort output limit (provider dependent).
-- `temperature`: best-effort sampling temperature forwarded to the provider. Ignored by the ChatGPT-based Codex Responses backend, which uses fixed server-side sampling.
-- `top_p`: best-effort nucleus sampling forwarded to the provider. Same Codex Responses caveat as `temperature`.
-- `user`: stable session routing.
-
-Accepted but **currently ignored**:
-
-- `max_tool_calls`
-- `reasoning`
-- `metadata`
-- `store`
-- `truncation`
-
-Supported:
-
-- `previous_response_id`: FengMing reuses the earlier response session when the request stays within the same agent/user/requested-session scope.
-
-## Items (input)
-
-### `message`
-
-Roles: `system`, `developer`, `user`, `assistant`.
-
-- `system` and `developer` are appended to the system prompt.
-- The most recent `user` or `function_call_output` item becomes the "current message."
-- Earlier user/assistant messages are included as history for context.
-
-### `function_call_output` (turn-based tools)
-
-Send tool results back to the model:
-
-```json
-{
-  "type": "function_call_output",
-  "call_id": "call_123",
-  "output": "{\"temperature\": \"72F\"}"
-}
-```
-
-### `reasoning` and `item_reference`
-
-Accepted for schema compatibility but ignored when building the prompt.
-
-## Tools (client-side function tools)
-
-Provide tools with `tools: [{ type: "function", function: { name, description?, parameters? } }]`.
-
-If the agent decides to call a tool, the response returns a `function_call` output item.
-You then send a follow-up request with `function_call_output` to continue the turn.
-
-## Images (`input_image`)
-
-Supports base64 or URL sources:
-
-```json
-{
-  "type": "input_image",
-  "source": { "type": "url", "url": "https://example.com/image.png" }
-}
-```
-
-Allowed MIME types (current): `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/heic`, `image/heif`.
-Max size (current): 10MB.
-
-## Files (`input_file`)
-
-Supports base64 or URL sources:
-
-```json
-{
-  "type": "input_file",
-  "source": {
-    "type": "base64",
-    "media_type": "text/plain",
-    "data": "SGVsbG8gV29ybGQh",
-    "filename": "hello.txt"
-  }
-}
-```
-
-Allowed MIME types (current): `text/plain`, `text/markdown`, `text/html`, `text/csv`,
-`application/json`, `application/pdf`.
-
-Max size (current): 5MB.
-
-Current behavior:
-
-- File content is decoded and added to the **system prompt**, not the user message,
-  so it stays ephemeral (not persisted in session history).
-- Decoded file text is wrapped as **untrusted external content** before it is added,
-  so file bytes are treated as data, not trusted instructions.
-- The injected block uses explicit boundary markers like
-  `<<<EXTERNAL_UNTRUSTED_CONTENT id="...">>>` /
-  `<<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>` and includes a
-  `Source: External` metadata line.
-- This file-input path intentionally omits the long `SECURITY NOTICE:` banner to
-  preserve prompt budget; the boundary markers and metadata still stay in place.
-- PDFs are parsed for text first. If little text is found, the first pages are
-  rasterized into images and passed to the model, and the injected file block uses
-  the placeholder `[PDF content rendered to images]`.
-
-PDF parsing is provided by the bundled `document-extract` plugin, which uses
-`clawpdf` and its packaged PDFium WebAssembly runtime for text extraction and
-page rendering.
-
-URL fetch defaults:
-
-- `files.allowUrl`: `true`
-- `images.allowUrl`: `true`
-- `maxUrlParts`: `8` (total URL-based `input_file` + `input_image` parts per request)
-- Requests are guarded (DNS resolution, private IP blocking, redirect caps, timeouts).
-- Optional hostname allowlists are supported per input type (`files.urlAllowlist`, `images.urlAllowlist`).
-  - Exact host: `"cdn.example.com"`
-  - Wildcard subdomains: `"*.assets.example.com"` (does not match apex)
-  - Empty or omitted allowlists mean no hostname allowlist restriction.
-- To disable URL-based fetches entirely, set `files.allowUrl: false` and/or `images.allowUrl: false`.
-
-## File + image limits (config)
-
-Defaults can be tuned under `gateway.http.endpoints.responses`:
-
-```json5
-{
-  gateway: {
-    http: {
-      endpoints: {
-        responses: {
-          enabled: true,
-          maxBodyBytes: 20000000,
-          maxUrlParts: 8,
-          files: {
-            allowUrl: true,
-            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],
-            allowedMimes: [
-              "text/plain",
-              "text/markdown",
-              "text/html",
-              "text/csv",
-              "application/json",
-              "application/pdf",
-            ],
-            maxBytes: 5242880,
-            maxChars: 200000,
-            maxRedirects: 3,
-            timeoutMs: 10000,
-            pdf: {
-              maxPages: 4,
-              maxPixels: 4000000,
-              minTextChars: 200,
-            },
-          },
-          images: {
-            allowUrl: true,
-            urlAllowlist: ["images.example.com"],
-            allowedMimes: [
-              "image/jpeg",
-              "image/png",
-              "image/gif",
-              "image/webp",
-              "image/heic",
-              "image/heif",
-            ],
-            maxBytes: 10485760,
-            maxRedirects: 3,
-            timeoutMs: 10000,
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-Defaults when omitted:
-
-- `maxBodyBytes`: 20MB
-- `maxUrlParts`: 8
-- `files.maxBytes`: 5MB
-- `files.maxChars`: 200k
-- `files.maxRedirects`: 3
-- `files.timeoutMs`: 10s
-- `files.pdf.maxPages`: 4
-- `files.pdf.maxPixels`: 4,000,000
-- `files.pdf.minTextChars`: 200
-- `images.maxBytes`: 10MB
-- `images.maxRedirects`: 3
-- `images.timeoutMs`: 10s
-- HEIC/HEIF `input_image` sources are accepted when a system converter is available and are normalized to JPEG before provider delivery. Supported converters are macOS `sips`, ImageMagick, GraphicsMagick, or ffmpeg.
-
-Security note:
-
-- URL allowlists are enforced before fetch and on redirect hops.
-- Allowlisting a hostname does not bypass private/internal IP blocking.
-- For internet-exposed gateways, apply network egress controls in addition to app-level guards.
-  See [Security](/gateway/security).
-
-## Streaming (SSE)
-
-Set `stream: true` to receive Server-Sent Events (SSE):
-
-- `Content-Type: text/event-stream`
-- Each event line is `event: <type>` and `data: <json>`
-- Stream ends with `data: [DONE]`
-
-Event types currently emitted:
-
-- `response.created`
-- `response.in_progress`
-- `response.output_item.added`
-- `response.content_part.added`
-- `response.output_text.delta`
-- `response.output_text.done`
-- `response.content_part.done`
-- `response.output_item.done`
-- `response.completed`
-- `response.failed` (on error)
-
-## Usage
-
-`usage` is populated when the underlying provider reports token counts.
-FengMing normalizes common OpenAI-style aliases before those counters reach
-downstream status/session surfaces, including `input_tokens` / `output_tokens`
-and `prompt_tokens` / `completion_tokens`.
-
-## Errors
-
-Errors use a JSON object like:
-
-```json
-{ "error": { "message": "...", "type": "invalid_request_error" } }
-```
-
-Common cases:
-
-- `401` missing/invalid auth
-- `400` invalid request body
-- `405` wrong method
-
-## Examples
-
-Non-streaming:
-
-```bash
-curl -sS http://127.0.0.1:18789/v1/responses \
-  -H 'Authorization: Bearer YOUR_TOKEN' \
-  -H 'Content-Type: application/json' \
-  -H 'x-fengming-agent-id: main' \
-  -d '{
-    "model": "fengming",
-    "input": "hi"
-  }'
-```
-
-Streaming:
-
-```bash
-curl -N http://127.0.0.1:18789/v1/responses \
-  -H 'Authorization: Bearer YOUR_TOKEN' \
-  -H 'Content-Type: application/json' \
-  -H 'x-fengming-agent-id: main' \
-  -d '{
-    "model": "fengming",
-    "stream": true,
-    "input": "hi"
-  }'
-```
-
-## Related
-
-- [OpenAI chat completions](/gateway/openai-http-api)
-- [OpenAI](/providers/openai)

package/docs/gateway/openshell.md

@@ -1,316 +0,0 @@
----
-summary: "Use OpenShell as a managed sandbox backend for FengMing agents"
-title: OpenShell
-read_when:
-  - You want cloud-managed sandboxes instead of local Docker
-  - You are setting up the OpenShell plugin
-  - You need to choose between mirror and remote workspace modes
----
-
-OpenShell is a managed sandbox backend for FengMing. Instead of running Docker
-containers locally, FengMing delegates sandbox lifecycle to the `openshell` CLI,
-which provisions remote environments with SSH-based command execution.
-
-The OpenShell plugin reuses the same core SSH transport and remote filesystem
-bridge as the generic [SSH backend](/gateway/sandboxing#ssh-backend). It adds
-OpenShell-specific lifecycle (`sandbox create/get/delete`, `sandbox ssh-config`)
-and an optional `mirror` workspace mode.
-
-## Prerequisites
-
-- OpenShell plugin installed (`fengming plugins install @fengming/openshell-sandbox`)
-- The `openshell` CLI installed and on `PATH` (or set a custom path via
-  `plugins.entries.openshell.config.command`)
-- An OpenShell account with sandbox access
-- FengMing Gateway running on the host
-
-## Quick start
-
-1. Install and enable the plugin, then set the sandbox backend:
-
-```bash
-fengming plugins install @fengming/openshell-sandbox
-```
-
-```json5
-{
-  agents: {
-    defaults: {
-      sandbox: {
-        mode: "all",
-        backend: "openshell",
-        scope: "session",
-        workspaceAccess: "rw",
-      },
-    },
-  },
-  plugins: {
-    entries: {
-      openshell: {
-        enabled: true,
-        config: {
-          from: "fengming",
-          mode: "remote",
-        },
-      },
-    },
-  },
-}
-```
-
-2. Restart the Gateway. On the next agent turn, FengMing creates an OpenShell
-   sandbox and routes tool execution through it.
-
-3. Verify:
-
-```bash
-fengming sandbox list
-fengming sandbox explain
-```
-
-## Workspace modes
-
-This is the most important decision when using OpenShell.
-
-### `mirror`
-
-Use `plugins.entries.openshell.config.mode: "mirror"` when you want the **local
-workspace to stay canonical**.
-
-Behavior:
-
-- Before `exec`, FengMing syncs the local workspace into the OpenShell sandbox.
-- After `exec`, FengMing syncs the remote workspace back to the local workspace.
-- File tools still operate through the sandbox bridge, but the local workspace
-  remains the source of truth between turns.
-
-Best for:
-
-- You edit files locally outside FengMing and want those changes visible in the
-  sandbox automatically.
-- You want the OpenShell sandbox to behave as much like the Docker backend as
-  possible.
-- You want the host workspace to reflect sandbox writes after each exec turn.
-
-Tradeoff: extra sync cost before and after each exec.
-
-### `remote`
-
-Use `plugins.entries.openshell.config.mode: "remote"` when you want the
-**OpenShell workspace to become canonical**.
-
-Behavior:
-
-- When the sandbox is first created, FengMing seeds the remote workspace from
-  the local workspace once.
-- After that, `exec`, `read`, `write`, `edit`, and `apply_patch` operate
-  directly against the remote OpenShell workspace.
-- FengMing does **not** sync remote changes back into the local workspace.
-- Prompt-time media reads still work because file and media tools read through
-  the sandbox bridge.
-
-Best for:
-
-- The sandbox should live primarily on the remote side.
-- You want lower per-turn sync overhead.
-- You do not want host-local edits to silently overwrite remote sandbox state.
-
-<Warning>
-If you edit files on the host outside FengMing after the initial seed, the remote sandbox does **not** see those changes. Use `fengming sandbox recreate` to re-seed.
-</Warning>
-
-### Choosing a mode
-
-|                          | `mirror`                   | `remote`                  |
-| ------------------------ | -------------------------- | ------------------------- |
-| **Canonical workspace**  | Local host                 | Remote OpenShell          |
-| **Sync direction**       | Bidirectional (each exec)  | One-time seed             |
-| **Per-turn overhead**    | Higher (upload + download) | Lower (direct remote ops) |
-| **Local edits visible?** | Yes, on next exec          | No, until recreate        |
-| **Best for**             | Development workflows      | Long-running agents, CI   |
-
-## Configuration reference
-
-All OpenShell config lives under `plugins.entries.openshell.config`:
-
-| Key                       | Type                     | Default       | Description                                           |
-| ------------------------- | ------------------------ | ------------- | ----------------------------------------------------- |
-| `mode`                    | `"mirror"` or `"remote"` | `"mirror"`    | Workspace sync mode                                   |
-| `command`                 | `string`                 | `"openshell"` | Path or name of the `openshell` CLI                   |
-| `from`                    | `string`                 | `"fengming"`  | Sandbox source for first-time create                  |
-| `gateway`                 | `string`                 | —             | OpenShell gateway name (`--gateway`)                  |
-| `gatewayEndpoint`         | `string`                 | —             | OpenShell gateway endpoint URL (`--gateway-endpoint`) |
-| `policy`                  | `string`                 | —             | OpenShell policy ID for sandbox creation              |
-| `providers`               | `string[]`               | `[]`          | Provider names to attach when sandbox is created      |
-| `gpu`                     | `boolean`                | `false`       | Request GPU resources                                 |
-| `autoProviders`           | `boolean`                | `true`        | Pass `--auto-providers` during sandbox create         |
-| `remoteWorkspaceDir`      | `string`                 | `"/sandbox"`  | Primary writable workspace inside the sandbox         |
-| `remoteAgentWorkspaceDir` | `string`                 | `"/agent"`    | Agent workspace mount path (for read-only access)     |
-| `timeoutSeconds`          | `number`                 | `120`         | Timeout for `openshell` CLI operations                |
-
-Sandbox-level settings (`mode`, `scope`, `workspaceAccess`) are configured under
-`agents.defaults.sandbox` as with any backend. See
-[Sandboxing](/gateway/sandboxing) for the full matrix.
-
-## Examples
-
-### Minimal remote setup
-
-```json5
-{
-  agents: {
-    defaults: {
-      sandbox: {
-        mode: "all",
-        backend: "openshell",
-      },
-    },
-  },
-  plugins: {
-    entries: {
-      openshell: {
-        enabled: true,
-        config: {
-          from: "fengming",
-          mode: "remote",
-        },
-      },
-    },
-  },
-}
-```
-
-### Mirror mode with GPU
-
-```json5
-{
-  agents: {
-    defaults: {
-      sandbox: {
-        mode: "all",
-        backend: "openshell",
-        scope: "agent",
-        workspaceAccess: "rw",
-      },
-    },
-  },
-  plugins: {
-    entries: {
-      openshell: {
-        enabled: true,
-        config: {
-          from: "fengming",
-          mode: "mirror",
-          gpu: true,
-          providers: ["openai"],
-          timeoutSeconds: 180,
-        },
-      },
-    },
-  },
-}
-```
-
-### Per-agent OpenShell with custom gateway
-
-```json5
-{
-  agents: {
-    defaults: {
-      sandbox: { mode: "off" },
-    },
-    list: [
-      {
-        id: "researcher",
-        sandbox: {
-          mode: "all",
-          backend: "openshell",
-          scope: "agent",
-          workspaceAccess: "rw",
-        },
-      },
-    ],
-  },
-  plugins: {
-    entries: {
-      openshell: {
-        enabled: true,
-        config: {
-          from: "fengming",
-          mode: "remote",
-          gateway: "lab",
-          gatewayEndpoint: "https://lab.example",
-          policy: "strict",
-        },
-      },
-    },
-  },
-}
-```
-
-## Lifecycle management
-
-OpenShell sandboxes are managed through the normal sandbox CLI:
-
-```bash
-# List all sandbox runtimes (Docker + OpenShell)
-fengming sandbox list
-
-# Inspect effective policy
-fengming sandbox explain
-
-# Recreate (deletes remote workspace, re-seeds on next use)
-fengming sandbox recreate --all
-```
-
-For `remote` mode, **recreate is especially important**: it deletes the canonical
-remote workspace for that scope. The next use seeds a fresh remote workspace from
-the local workspace.
-
-For `mirror` mode, recreate mainly resets the remote execution environment because
-the local workspace remains canonical.
-
-### When to recreate
-
-Recreate after changing any of these:
-
-- `agents.defaults.sandbox.backend`
-- `plugins.entries.openshell.config.from`
-- `plugins.entries.openshell.config.mode`
-- `plugins.entries.openshell.config.policy`
-
-```bash
-fengming sandbox recreate --all
-```
-
-## Security hardening
-
-OpenShell pins the workspace root fd and rechecks sandbox identity before each
-read, so symlink swaps or a remounted workspace cannot redirect reads out of
-the intended remote workspace.
-
-## Current limitations
-
-- Sandbox browser is not supported on the OpenShell backend.
-- `sandbox.docker.binds` does not apply to OpenShell.
-- Docker-specific runtime knobs under `sandbox.docker.*` apply only to the Docker
-  backend.
-
-## How it works
-
-1. FengMing calls `openshell sandbox create` (with `--from`, `--gateway`,
-   `--policy`, `--providers`, `--gpu` flags as configured).
-2. FengMing calls `openshell sandbox ssh-config <name>` to get SSH connection
-   details for the sandbox.
-3. Core writes the SSH config to a temp file and opens an SSH session using the
-   same remote filesystem bridge as the generic SSH backend.
-4. In `mirror` mode: sync local to remote before exec, run, sync back after exec.
-5. In `remote` mode: seed once on create, then operate directly on the remote
-   workspace.
-
-## Related
-
-- [Sandboxing](/gateway/sandboxing) -- modes, scopes, and backend comparison
-- [Sandbox vs Tool Policy vs Elevated](/gateway/sandbox-vs-tool-policy-vs-elevated) -- debugging blocked tools
-- [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools) -- per-agent overrides
-- [Sandbox CLI](/cli/sandbox) -- `fengming sandbox` commands