@orcha-ai/runtime-bridge 0.1.38 → 0.1.40

package/README.md

@@ -1,384 +1,104 @@
 # Orcha Runtime Bridge
 
-Runtime Node package that keeps Codex, OpenClaw, Claude Code, and other
-agent runtimes outside the Python API process.
+Bridge connects a user's device and discovers Codex, Claude Code and configured OpenClaw agents. Cloud Node Runtime infrastructure is managed separately in `cloud-agent-runtime/` and the Runtime Nodes page.
 
-The bridge owns Orcha's first-party ACP adapter. It does not depend on a
-third-party ACP package: JSON-RPC framing, request ids, notifications,
-runtime permission requests, and process lifecycle are implemented under
-`src/acp/`.
+## Connect a device
 
-In production the Runtime Node actively connects to Orcha over WebSocket. The
-computer running Codex/OpenClaw/Claude does not need to expose an inbound port.
-
-Managed sandbox execution is fail-closed: before registering targets as available it
-runs the bundled Linux Bubblewrap broker probe. Every prompt/dispatch is bound
-to a control-plane `runId` and frozen sandbox policy, and the actual Runtime
-process is started by the broker inside an empty-root namespace. Missing
-Bubblewrap, `prlimit`, Egress Proxy, trusted workspace, or a failed escape probe
-keeps the node visible for diagnostics but unavailable for dispatch. It never
-falls back to spawning Codex/OpenClaw/Claude directly on the host.
-
-The broker does not mount `/usr/local` or other operator directories by
-default. Install runtime CLIs under a dedicated immutable directory, list it in
-`ORCHA_RUNTIME_TRUSTED_TOOLCHAIN_ROOTS`, and repeat it in each target's
-`toolchainRoots`. This keeps the executable surface explicit and avoids
-exposing unrelated host installations or credentials.
-
-## Install
+1. Open **智能体 → 添加智能体 → 从我的设备添加** in the current tenant.
+2. Install or update the npm package on the computer with your agents installed. Node.js 22.19 or newer is required.
+3. Copy and run the one-time connection command. Bridge starts in the background; the terminal can be closed.
+4. Select discovered agents, confirm names and local directories, then add.
 
 ```bash
-npm install -g @orcha-ai/runtime-bridge
+npm install -g @orcha-ai/runtime-bridge@latest
+orcha-runtime-bridge connect --url https://orcha.example.com --pair-code ONE_TIME_CODE
 ```
 
-Runtime Bridge requires Node.js 22.19 or newer. Managed sandbox execution also
-requires Linux with Bubblewrap, `prlimit`, `ip`, and `socat`. External Runtime
-Nodes execute operator-configured agents directly on Linux, macOS, or Windows.
-An OpenClaw Gateway must separately satisfy its host version's requirements.
-
-Run it with:
+The code expires after 10 minutes and is consumed once. The device belongs to the signed-in user and tenant. Imported agents are private by default and use existing sharing settings. Shared users still execute on the owner's device.
 
-```bash
-orcha-runtime-bridge
-```
-
-You can also run without a global install:
+For subsequent connections, omit the consumed code:
 
 ```bash
-npx @orcha-ai/runtime-bridge
+orcha-runtime-bridge connect --url https://orcha.example.com
 ```
 
-## Build And Pack
+`connect` exchanges the one-time code in the foreground, then starts the existing daemon manager with the saved profile. The code and device credential are not passed to the background command. Reconnecting an already running device returns its existing process; stop it first before replacing its pairing.
 
-The bridge is plain Node.js ESM. The build step bundles and minifies the runtime
-CLI into `bin/orcha-runtime-bridge.js`, then prepares a clean release directory.
+Manage the device from any terminal directory with the same server address:
 
 ```bash
-npm run build
-npm run pack:local
+orcha-runtime-bridge status --url https://orcha.example.com
+orcha-runtime-bridge reload --url https://orcha.example.com
+orcha-runtime-bridge stop --url https://orcha.example.com
+orcha-runtime-bridge start --url https://orcha.example.com
 ```
 
-`npm run build` writes `dist/package`. `npm run pack:local` creates the local
-npm tarball under `dist/`. The release package includes the minified `bin/`
-runtime, the bundled `openclaw-plugin/`, `README.md`, and `.env.example`; it does not publish `src/`, build
-scripts, test scripts, or the local `.env` file.
+The server-specific PID and log files live beside the device profile under `~/.orcha/devices/`; `--pid-file` and `--log-file` override them. `status` reports the local process state; the Orcha page reports whether the device is online. Use `connect --foreground --url ...` for diagnosis after stopping its background process. Closing the terminal does not stop the daemon; shutting down the computer does. This command does not install an OS login/startup service. Legacy env-configured `start/status/reload/stop --env-file ...` keep their existing behavior.
 
-### 0.1.38 Release
+The credential and local launch configuration live under `~/.orcha/devices/<server-hash>.json`, written atomically with mode 0600. A new pairing for the same server replaces that local profile. Disconnect the previous device in Orcha to revoke its credential. Discovery does not upload vendor credentials, command paths, environment maps or transcripts.
 
-Updates the Runtime Node registration handshake to `orcha-runtime-node.v2`.
-Deploy this release with the Orcha backend that accepts v2; that backend rejects
-older Bridge clients using v1. The standalone execution protocol remains
-`orcha.runtime-execution/v1`.
+Remote deployments require HTTPS; HTTP is allowed only on loopback. Bridge opens an outbound WebSocket to `/api/agent-runtime-bridge/ws`. The device needs no inbound port. The reverse proxy must forward WebSocket upgrades to the Runtime Gateway.
 
-The npm Bridge package is released separately from the managed Runtime container
-images. After publishing, upgrade each external Runtime Node's installed package
-and reload its Bridge process using the existing env file as described in
-[Background Process](#background-process).
+## Discovery and execution
 
-After `npm run check`, `npm test`, and `npm run pack:local` succeed, publish the
-prepared tarball from this directory:
+Discovery checks executables in absolute PATH entries and runs fixed probes:
 
-```bash
-npm publish ./dist/orcha-ai-runtime-bridge-0.1.38.tgz --access public --registry=https://registry.npmjs.org
-```
+- Codex: `--version`, `login status`.
+- Claude Code: `--version`, `auth status` (JSON is the default).
+- OpenClaw: `--version`, `agents list --json`, `health --json`.
 
-### 0.1.37 Release
+Missing installations are absent; failed probes are explicit errors. Login and Gateway setup happen locally. Discovery does not install applications, sign in, run a model prompt or scan the entire disk. Detection does not guarantee vendor quota or future model calls.
 
-Packages task-scoped Orcha MCP access for delegated Codex and OpenClaw group
-members, including credential refresh, operation reattachment, cancellation,
-and session cleanup. The tarball includes the bundled OpenClaw Gateway plugin;
-install and configure it as described in [Delegated group member tools](#delegated-group-member-tools).
-Local adapter fixtures cover these integrations; a real OpenClaw Gateway has
-not yet been verified.
+Codex/Claude Code use a user-selected existing local directory. OpenClaw keeps its existing agent ID and directory; its private session key uses that ID, not Orcha's generated Agent code. Core cannot supply arbitrary launch commands. Every selection and directory is validated before one atomic profile update. Core serializes imports by locking the device credential to prevent duplicate Agents.
 
-### 0.1.36 Release
+Codex device targets use `exec --skip-git-repo-check --json` so ordinary directories work as well as Git repositories. Existing device profiles created without this flag need their Codex target arguments updated locally and Bridge reloaded; updating the npm package alone does not rewrite saved profiles.
 
-Packages the goal-verification changes committed on August 25–26, 2026.
-Each verification check requires a positive integer `requiredMatches` and
-counts distinct successful tool call IDs. Results report `requiredMatches`,
-`observedMatches`, and `toolCallIds` instead of the previous single `toolCallId`.
-Callers and result consumers must use these fields when upgrading from 0.1.35.
+Targets are namespaced by device code and candidate digest. Chat, group delegation, workflow dispatch and recovery are pinned to that device; an offline or revoked device never falls back to a different computer. External execution uses the local CLI's own permissions, not Orcha's cloud Docker Sandbox.
 
-## Configure
+The automated discovery path is exercised on macOS/Linux. On Windows, use WSL with the CLIs installed there; native `.cmd`/`.bat` launchers are not supported by the shell-free process adapter.
 
-```bash
-cp .env.example .env
-# Edit .env and fill ORCHA_RUNTIME_ORCHA_URL / ORCHA_RUNTIME_NODE_TOKEN / targets.
-orcha-runtime-bridge
-```
-
-## Background Process
+Official probe references: [Codex CLI](https://developers.openai.com/codex/cli/reference/), [Claude Code CLI](https://code.claude.com/docs/en/cli-reference), [OpenClaw agents](https://docs.openclaw.ai/cli/agents).
 
-The CLI has a small built-in process manager. It does not require pm2,
-forever, or any third-party package.
+## Protocol and cutover
 
-```bash
-# Start in the background.
-orcha-runtime-bridge start --env-file /etc/orcha/runtime-node.env
+The existing `orcha-runtime-node.v2` transport negotiates `devices/discover` and `devices/configure` alongside execution/session methods. Existing Node and ServiceToken records are reused. Core checks ownership, exact node/candidate identity, target namespace and the returned selections before creating Agents.
 
-# Check status.
-orcha-runtime-bridge status --env-file /etc/orcha/runtime-node.env
+Legacy manual external-node registration is rejected. Platform service tokens create only cloud Node Runtime nodes. Arbitrary `runtimeTargetCode` is no longer an Agent creation path. The explicit cleanup procedure is in [智能体管理与构建](../docs/新文档/05-智能体/01-智能体管理与构建.md).
 
-# Reload after editing the env file or upgrading the package.
-orcha-runtime-bridge reload --env-file /etc/orcha/runtime-node.env
-
-# Stop.
-orcha-runtime-bridge stop --env-file /etc/orcha/runtime-node.env
-```
-
-`start` writes the process id to `ORCHA_RUNTIME_PID_FILE` and redirects stdout
-and stderr to `ORCHA_RUNTIME_LOG_FILE`. Both paths can be set in the env file or
-overridden on the command line:
-
-```bash
-orcha-runtime-bridge start \
-  --env-file /etc/orcha/runtime-node.env \
-  --pid-file /var/run/orcha-runtime-bridge.pid \
-  --log-file /var/log/orcha-runtime-bridge.log
-```
-
-Running `orcha-runtime-bridge` with no command still runs in the foreground,
-which is the right mode for systemd, Docker, launchd, and supervised services.
-
-The built-in daemon keeps Runtime Bridge logs for 3 days by default. It cleans
-`ORCHA_RUNTIME_LOG_FILE` on start and then once per hour, using each JSON log
-line's `ts` field. Non-JSON lines and lines without a parseable timestamp are
-kept. Configure with:
-
-```bash
-ORCHA_RUNTIME_LOG_RETENTION_DAYS=3
-ORCHA_RUNTIME_LOG_CLEANUP_INTERVAL_MS=3600000
-```
-
-The bridge loads environment variables from `ORCHA_RUNTIME_ENV_FILE` when it is
-set. Otherwise it reads `.env` from the current working directory. Real process
-environment variables always win over values from the file.
-
-Runtime Node mode reconnects to Orcha automatically. `ORCHA_RUNTIME_RECONNECT_MS`
-controls the delay between attempts, and `ORCHA_RUNTIME_CONNECT_TIMEOUT_MS`
-controls how long one WebSocket handshake may wait before the node closes it and
-tries again.
-
-The node connects to:
-
-- `WS /api/agent-runtime-bridge/ws`
-
-and receives Orcha RPC frames for:
-
-- `agents/create`
-- `agents/dispatch`
-- `sessions/prompt`
-- `sessions/policy`
-- `sessions/cancel`
-- `permissions/respond`
-
-Runtime targets are configured with `ORCHA_RUNTIME_TARGETS_JSON`.
-
-ACP runtimes complete a JSON-RPC `initialize` handshake before a session is
-created. `ORCHA_RUNTIME_INITIALIZE_TIMEOUT_MS` controls that handshake only
-(30 seconds by default); it is independent from the task/prompt timeout. A
-target can override it with `"initializeTimeoutMs"`. Target processes use
-`cwd`, then `workspace`, then the request workspace as their working directory.
-
-Start the bundled Egress Proxy as a separate supervised process before the
-Runtime Bridge. In production use separate protected environment files: the
-proxy file contains only its socket, token, and limits; the bridge file contains
-the Node identity plus the matching proxy socket/token. The proxy accepts
-`ORCHA_RUNTIME_EGRESS_PROXY_SOCKET` and `ORCHA_RUNTIME_EGRESS_PROXY_TOKEN`, and
-listens only on that Unix Socket.
-
-```bash
-orcha-runtime-egress-proxy --env-file /etc/orcha/runtime-egress.env
-orcha-runtime-bridge start --env-file /etc/orcha/runtime-node.env
-```
-
-The proxy must run under its own OS account in production. The bridge uses its
-admin token only to create and revoke short-lived Run-bound grants; sandboxed
-commands receive only the individual grant credential. A node whose proxy or
-escape probe is unavailable remains registered for diagnostics but cannot
-receive work.
-
-```json
-{
-  "codex": {
-    "type": "cli",
-    "command": "/opt/orcha-runtime-tools/bin/codex",
-    "toolchainRoots": ["/opt/orcha-runtime-tools"],
-    "args": ["exec", "--json"],
-    "promptMode": "stdin",
-    "outputMode": "json-lines",
-    "workspace": "/workspaces/project-a"
-  },
-  "openclaw": {
-    "type": "openclaw",
-    "command": "openclaw",
-    "workspace": "/workspaces/project-a",
-    "maxSessions": 1,
-    "releaseAfterPrompt": true,
-    "sessionIdleTtlMs": 60000,
-    "mcpServers": []
-  },
-  "custom-acp": {
-    "type": "stdio-acp",
-    "command": "node",
-    "args": ["/path/to/runtime.js"],
-    "framing": "line"
-  }
-}
-```
-
-External Runtime Nodes call the agents configured by the node operator directly.
-They do not require a Bridge-managed process sandbox and remain dispatchable on
-Linux, macOS, and Windows. Keep target commands, workspaces, credentials, and OS
-permissions under the operator's control.
-
-If a request references a missing target, the bridge returns
-`RUNTIME_TARGET_NOT_FOUND`. The built-in `echo` adapter is available only when
-you explicitly configure a target with `"type": "echo"`.
-
-Target types:
-
-- `stdio-acp`: spawn a runtime process and speak Orcha ACP over stdio JSON-RPC.
-- `openclaw`: built-in `openclaw acp --session ...` command adapter.
-- `cli`: run an independent CLI per prompt and wrap stdout as session updates.
-- `echo`: local test adapter.
-
-For `cli` targets, `agents/dispatch` requests are treated as task execution and
-emit only final text by default. Direct `sessions/prompt` requests keep normal
-streaming text for interactive chat. Set `"dispatchFinalTextOnly": false` on a
-target to opt out for task execution, or `"finalTextOnly": true` as the target
-default when a request does not provide its own text-streaming policy.
-
-For ACP-compatible targets (`stdio-acp`, `acp`, and `openclaw`), task dispatch
-is treated as one-shot execution and releases the runtime process after each
-completed prompt by default. Direct `sessions/prompt` requests keep the normal
-target lifecycle. Set `"dispatchReleaseAfterPrompt": false` on a target only
-when task dispatch should intentionally reuse the same ACP process.
-
-Generic ACP-compatible targets receive `mcpServers` in `session/new`. When
-omitted in target config, the bridge sends an empty array. OpenClaw targets
-always receive an empty `mcpServers` array, because the field is required by the
-ACP schema while OpenClaw bridge mode requires actual MCP servers to be
-configured on the OpenClaw gateway or agent instead.
-
-### Delegated group member tools
-
-Group delegation uses one independent `runId`, session, and correlation for
-each member task. Its task-scoped Orcha MCP credential grants only that member's
-authorized capabilities. It is kept in memory and refreshed by attaching to the
-existing operation. Lost operations fail explicitly; the Bridge never starts a
-second prompt to simulate recovery. Permission changes cancel the old task;
-native authorization or input pauses are not automatically approved or resumed.
-
-For a Codex CLI target, the adapter adds a required HTTP MCP server through
-per-process `-c` configuration and a private loopback proxy. Codex receives a
-temporary proxy credential through `ORCHA_TASK_MCP_TOKEN`; upstream credentials
-remain in Bridge memory. This does not edit the operator's Codex configuration.
-This adapter requires a direct external Runtime Node; its loopback transport is
-not supported inside a Bridge-managed sandbox. See [Codex MCP configuration](https://developers.openai.com/codex/mcp).
-
-OpenClaw requires the bundled Gateway tool plugin. Build the Bridge, then install
-the **built** plugin directory on the OpenClaw host:
+## Build and validate
 
 ```bash
+npm ci
+npm run check
+npm test
 npm run build
-openclaw plugins install /absolute/path/to/runtime-bridge/dist/package/openclaw-plugin
-```
-
-Configure `plugins.entries.orcha-runtime` on that Gateway, preserving other
-installed plugin entries and allowlists:
-
-```json
-{
-  "enabled": true,
-  "config": { "allowedOrchaMcpUrl": "https://orcha.example.com/api/mcp/orcha" }
-}
-```
-
-If plugin or tool allowlists are configured, permit `orcha-runtime` and its four
-`orcha_` tools for the intended OpenClaw Agent. The plugin binds tools only to
-the trusted host `agentId` and task `sessionKey`; ordinary sessions receive none.
-Its manifest declares all four tools and activates the binding route at startup.
-Follow the host's [plugin installation](https://docs.openclaw.ai/cli/plugins/install)
-and [runtime verification](https://docs.openclaw.ai/plugins/building-plugins) steps,
-including loading the new code in the running Gateway. Pin and verify the actual
-host version before enabling dispatch; this package does not claim a tested
-OpenClaw version range yet.
-
-Add these fields to the existing OpenClaw Runtime Target:
-
-```json
-{
-  "type": "openclaw",
-  "command": "openclaw",
-  "mcpBridgeUrl": "http://127.0.0.1:18789/plugins/orcha-runtime/mcp-bindings",
-  "mcpBridgeTokenEnv": "ORCHA_OPENCLAW_GATEWAY_TOKEN"
-}
 ```
 
-Set `ORCHA_OPENCLAW_GATEWAY_TOKEN` in the Bridge host environment to the Gateway
-authentication credential. The binding URL must reach that same Gateway. Orcha's
-Agent code must match the OpenClaw Agent id. Do not configure a shared fixed
-`--session`: delegated sessions use `agent:<agentCode>:delegation-<runId>`.
-The Gateway credential authorizes binding management; each tool call uses the
-separate, short-lived member credential supplied by Core. Missing configuration,
-rejected credentials, or a lost binding produces an explicit task failure.
-Bindings expire and are released on completion, failure, or cancellation.
+Build produces `bin/orcha-runtime-bridge.js` and the clean npm package in `dist/package`, including the OpenClaw plugin. Bridge is distributed through npm; backend images do not bundle a separate browser download.
 
-`npm test` verifies both adapters with local protocol fixtures. An optional real
-Codex check performs a model call using the installed CLI's login and a temporary
-MCP server:
+Version 0.1.40 ships the OpenClaw native Orcha Channel adapter and bundled Gateway plugin, including channel delivery, active messages/files and authorized background runs. Bridge and the bundled plugin now share the release version. It retains the device pairing and ordinary-directory Codex execution from 0.1.39 and keeps `orcha-runtime-node.v2` unchanged. Deploying Orcha does not publish npm or upgrade connected devices automatically. Build and validate the release tarball before publishing:
 
 ```bash
-ORCHA_TEST_REAL_CODEX=/absolute/path/to/codex node --test --test-name-pattern='installed Codex' scripts/check-group-members.js
+npm run pack:local
+npm publish ./dist/orcha-ai-runtime-bridge-0.1.40.tgz --access public --registry=https://registry.npmjs.org
 ```
 
-Fixture tests do not replace a real OpenClaw Gateway tool call or full group
-acceptance on the configured nodes. This repository does not install the plugin
-or change credentials on remote hosts.
-
-OpenClaw targets use request metadata `agentCode` as the local OpenClaw agent
-id, producing sessions like `agent:<agentCode>:<sessionId>`. When `agentCode`
-is missing, the bridge falls back to a plain `orcha-<sessionId>` session.
-
-OpenClaw may start browser processes under the hood, so the bridge applies
-stricter defaults for this target type:
+After updating the npm package on a device, run `orcha-runtime-bridge reload --url ...` to switch the existing background process to the installed version. The earlier manually downloaded foreground process must be stopped before connecting with npm to avoid duplicate connections.
 
-- `maxSessions`: defaults to `1` for OpenClaw.
-- `releaseAfterPrompt`: defaults to `true` for OpenClaw, stopping the runtime
-  process after each prompt.
-- `sessionIdleTtlMs`: defaults to `60000` for OpenClaw.
+For native OpenClaw Channel use, also update the bundled OpenClaw plugin using the host's supported plugin update/reload procedure; updating Bridge alone does not update an installed Gateway plugin. Create a binding in the Orcha Agent's **消息通道** tab, merge its generated `channels.orcha.accounts` configuration into OpenClaw, and retain the existing Gateway/MCP binding configuration below. Existing ACP/CLI targets without a native binding continue using their configured execution path. Native Channel progress is currently final-result-only; real OpenClaw host/model acceptance remains required before production use.
 
-Session capacity belongs to the Runtime Target, not to an Agent. The bridge
-reports each target's configured capacity, busy sessions, reclaimable idle
-sessions, in-flight reservations, and currently available sessions on every
-heartbeat. Orcha selects a compatible node from that live capacity; the bridge
-still performs the final atomic reservation before starting a runtime.
+Tests cover discovery errors, paths, public-field filtering, immutable commands, exact OpenClaw IDs, atomic configuration, capacity, reconnect, MCP lifecycle and cancellation. The live Codex model test is opt-in; fixtures do not certify a real vendor account or OpenClaw Gateway version.
 
-Global lifecycle knobs:
+## Delegated group member tools
 
-```bash
-ORCHA_RUNTIME_SESSION_IDLE_TTL_MS=600000
-ORCHA_RUNTIME_SESSION_CLEANUP_INTERVAL_MS=60000
-ORCHA_RUNTIME_MAX_SESSIONS_PER_TARGET=8
-ORCHA_RUNTIME_OPENCLAW_SESSION_IDLE_TTL_MS=60000
-ORCHA_RUNTIME_OPENCLAW_MAX_SESSIONS=1
-```
-
-Supported stdio framing:
-
-- `line`: one JSON-RPC frame per line.
-- `content-length`: `Content-Length: N` headers, compatible with LSP-style stdio transports.
+Codex supports task-scoped Orcha MCP through the existing local transport adapter. OpenClaw additionally requires the bundled Gateway plugin, a trusted binding endpoint and Gateway authentication. Discovery/import does not install the plugin or configure these credentials. Claude Code's delegated dynamic MCP adapter remains unsupported and returns an explicit error.
 
-Local HTTP server mode is only for development smoke tests:
+For OpenClaw, install the built plugin, set `plugins.entries.orcha-runtime.enabled` to `true` and its `config.allowedOrchaMcpUrl` to the Orcha MCP URL. Preserve existing plugins and allowlists, permit the `orcha_` tools for the local Agent, then follow the host version's plugin reload procedure:
 
 ```bash
-ORCHA_RUNTIME_MODE=server npm start
+openclaw plugins install /absolute/path/to/runtime-bridge/dist/package/openclaw-plugin
 ```
 
-For systemd or Docker deployments, point `ORCHA_RUNTIME_ENV_FILE` at the file
-managed by the host:
+Advanced local target configuration retains `mcpBridgeUrl` (the Gateway `/plugins/orcha-runtime/mcp-bindings` route) and `mcpBridgeTokenEnv` (the existing local environment variable holding Gateway authentication). Configure these in the connected device profile while Bridge is stopped, then reconnect. Tokens stay on the device. Orcha's per-run MCP credential is separate and short-lived. The binding uses the discovered local Agent ID; grants are task-scoped and released on termination. Missing configuration, rejected credentials or a lost binding fails explicitly.
 
-```bash
-ORCHA_RUNTIME_ENV_FILE=/etc/orcha/runtime-node.env npm start
-```
+The env-configured `run`/`start` commands and HTTP adapter remain for adapter development. They do not authorize legacy manual external nodes to register with current Core; user devices use `connect` or `start --url` with a saved pairing.