nodmix 2026.5.25

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

@@ -0,0 +1,347 @@
+---
+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"
+---
+
+Nodmix'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
+`nodmix 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` / `NODMIX_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-nodmix-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-nodmix-scopes` when present and otherwise fall back to the normal operator default scope set
+- select agents with `model: "nodmix"`, `model: "nodmix/default"`, `model: "nodmix/<agentId>"`, or `x-nodmix-agent-id`
+- use `x-nodmix-model` when you want to override the selected agent's backend model
+- use `x-nodmix-session-key` for explicit session routing
+- use `x-nodmix-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-nodmix-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-nodmix-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, `nodmix/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`: Nodmix 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 the
+Node-friendly `pdfjs-dist` legacy build (no worker). The modern PDF.js build
+expects browser workers/DOM globals, so it is not used in the Gateway.
+
+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 and normalized to JPEG before provider delivery.
+
+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.
+Nodmix 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-nodmix-agent-id: main' \
+  -d '{
+    "model": "nodmix",
+    "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-nodmix-agent-id: main' \
+  -d '{
+    "model": "nodmix",
+    "stream": true,
+    "input": "hi"
+  }'
+```
+
+## Related
+
+- [OpenAI chat completions](/gateway/openai-http-api)
+- [OpenAI](/providers/openai)

package/docs/gateway/openshell.md

@@ -0,0 +1,316 @@
+---
+summary: "Use OpenShell as a managed sandbox backend for Nodmix 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 Nodmix. Instead of running Docker
+containers locally, Nodmix 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 (`nodmix plugins install @nodmix/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
+- Nodmix Gateway running on the host
+
+## Quick start
+
+1. Install and enable the plugin, then set the sandbox backend:
+
+```bash
+nodmix plugins install @nodmix/openshell-sandbox
+```
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        mode: "all",
+        backend: "openshell",
+        scope: "session",
+        workspaceAccess: "rw",
+      },
+    },
+  },
+  plugins: {
+    entries: {
+      openshell: {
+        enabled: true,
+        config: {
+          from: "nodmix",
+          mode: "remote",
+        },
+      },
+    },
+  },
+}
+```
+
+2. Restart the Gateway. On the next agent turn, Nodmix creates an OpenShell
+   sandbox and routes tool execution through it.
+
+3. Verify:
+
+```bash
+nodmix sandbox list
+nodmix 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`, Nodmix syncs the local workspace into the OpenShell sandbox.
+- After `exec`, Nodmix 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 Nodmix 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, Nodmix 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.
+- Nodmix 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 Nodmix after the initial seed, the remote sandbox does **not** see those changes. Use `nodmix 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`                 | `"nodmix"`  | 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: "nodmix",
+          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: "nodmix",
+          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: "nodmix",
+          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)
+nodmix sandbox list
+
+# Inspect effective policy
+nodmix sandbox explain
+
+# Recreate (deletes remote workspace, re-seeds on next use)
+nodmix 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
+nodmix 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. Nodmix calls `openshell sandbox create` (with `--from`, `--gateway`,
+   `--policy`, `--providers`, `--gpu` flags as configured).
+2. Nodmix 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) -- `nodmix sandbox` commands