@vantran-se/openchamber-web 2.0.2 → 2.0.4

package/server/index.js

@@ -51,7 +51,13 @@ import {
   UPSTREAM_STALL_TIMEOUT_CONCURRENT_MS,
 } from './lib/event-stream/index.js';
 import { createFsSearchRuntime as createFsSearchRuntimeFactory } from './lib/fs/search.js';
-import { createOpenCodeLifecycleRuntime } from './lib/opencode/lifecycle.js';
+import {
+  createOpenCodeLifecycleControls,
+  createOpenCodeLifecycleRuntime,
+  createOpenCodeRecoveryCallbacks,
+  createOpenCodeServerComposition,
+} from './lib/opencode/lifecycle.js';
+import { createSharedOpenCodeServiceRuntime } from './lib/opencode/shared-service-runtime.js';
 import { createOpenCodeEnvRuntime } from './lib/opencode/env-runtime.js';
 import { providedLoginShellEnvSnapshot } from './lib/opencode/login-shell-env.js';
 import { resolveOpenCodeEnvConfig } from './lib/opencode/env-config.js';
@@ -655,6 +661,8 @@ const initialOpenCodeAuthState = hmrStateRuntime.resolveOpenCodeAuthFromState({
 });
 let openCodeAuthPassword = initialOpenCodeAuthState.openCodeAuthPassword;
 let openCodeAuthSource = initialOpenCodeAuthState.openCodeAuthSource;
+let openCodeConnectionAdapter = null;
+let sharedOpenCodeServiceRuntime = null;
 
 // Sync helper - call after modifying any HMR state variable
 const syncToHmrState = () => {
@@ -735,7 +743,23 @@ const openCodeAuthStateRuntime = createOpenCodeAuthStateRuntime({
   syncToHmrState,
 });
 
-const getOpenCodeAuthHeaders = (...args) => openCodeAuthStateRuntime.getOpenCodeAuthHeaders(...args);
+const getManagedOpenCodeAuthHeaders = (...args) => openCodeAuthStateRuntime.getOpenCodeAuthHeaders(...args);
+const getConnectionOpenCodeAuthHeaders = (...args) => (
+  openCodeConnectionAdapter?.getOpenCodeAuthHeaders(...args) ?? getManagedOpenCodeAuthHeaders(...args)
+);
+const getOpenCodeBaseUrl = () => openCodeConnectionAdapter?.getOpenCodeBaseUrl() ?? openCodeBaseUrl;
+const getOpenCodeConnectionKind = () => (
+  openCodeConnectionAdapter?.getOpenCodeConnectionKind() ?? 'managed-owned'
+);
+const ownsOpenCodeProcess = () => openCodeConnectionAdapter?.ownsOpenCodeProcess() ?? true;
+const setSharedOpenCodeConnection = (connection) => {
+  openCodeBaseUrl = connection.endpoint.url;
+  const parsedUrl = new URL(connection.endpoint.url);
+  const parsedPort = parsedUrl.port
+    ? Number.parseInt(parsedUrl.port, 10)
+    : (parsedUrl.protocol === 'https:' ? 443 : 80);
+  openCodePort = Number.isFinite(parsedPort) ? parsedPort : null;
+};
 const isOpenCodeConnectionSecure = (...args) => openCodeAuthStateRuntime.isOpenCodeConnectionSecure(...args);
 const ensureLocalOpenCodeServerPassword = (...args) => openCodeAuthStateRuntime.ensureLocalOpenCodeServerPassword(...args);
 
@@ -750,10 +774,12 @@ Object.defineProperties(openCodeNetworkState, {
 
 const openCodeNetworkRuntime = createOpenCodeNetworkRuntime({
   state: openCodeNetworkState,
-  getOpenCodeAuthHeaders,
+  getOpenCodeBaseUrl,
+  getOpenCodeAuthHeaders: getConnectionOpenCodeAuthHeaders,
   configuredOpenCodeHostname: ENV_CONFIGURED_OPENCODE_HOSTNAME,
 });
 
+const getOpenCodeAuthHeaders = (...args) => openCodeNetworkRuntime.getOpenCodeAuthHeaders(...args);
 const waitForReady = (...args) => openCodeNetworkRuntime.waitForReady(...args);
 const normalizeApiPrefix = (...args) => openCodeNetworkRuntime.normalizeApiPrefix(...args);
 const setDetectedOpenCodeApiPrefix = (...args) => openCodeNetworkRuntime.setDetectedOpenCodeApiPrefix(...args);
@@ -1113,7 +1139,7 @@ const serverUtilsRuntime = createServerUtilsRuntime({
   longRequestTimeoutMs: LONG_REQUEST_TIMEOUT_MS,
   getRuntime: () => ({
     openCodePort,
-    openCodeBaseUrl,
+    openCodeBaseUrl: getOpenCodeBaseUrl(),
     openCodeNotReadySince,
     isOpenCodeReady,
     isRestartingOpenCode,
@@ -1260,6 +1286,19 @@ Object.defineProperties(openCodeLifecycleState, {
   resolvedWslDistro: { get: () => resolvedWslDistro, set: (value) => { resolvedWslDistro = value; } },
 });
 
+const openCodeRecoveryCallbacks = createOpenCodeRecoveryCallbacks({
+  resetOpenCodeRuntimeProviders,
+  rebindUpstream: () => {
+    if (messageStreamRuntime) {
+      messageStreamRuntime.rebindUpstream();
+    } else {
+      globalMessageStreamHub.rebind();
+    }
+  },
+  interruptBusySessionsAfterRestart: () => sessionRuntime.interruptBusySessionsAfterRestart(),
+  broadcastUiNotification,
+});
+
 const openCodeLifecycleRuntime = createOpenCodeLifecycleRuntime({
   state: openCodeLifecycleState,
   env: {
@@ -1314,41 +1353,16 @@ const openCodeLifecycleRuntime = createOpenCodeLifecycleRuntime({
   // so the UI keeps receiving events instead of staying pinned to the old
   // process (#2638). The runtime is created later by the startup pipeline;
   // by the time any restart runs, it is assigned.
-  onOpenCodeRestarted: () => {
-    // A restart reloads plugins: provider ports, credentials and the provider
-    // list itself can all differ from what was cached.
-    resetOpenCodeRuntimeProviders();
-    try {
-      messageStreamRuntime?.rebindUpstream();
-    } catch (error) {
-      console.warn('Failed to rebind message stream after OpenCode restart:', error?.message ?? error);
-    }
-    try {
-      const { sessionIds } = sessionRuntime.interruptBusySessionsAfterRestart();
-      if (sessionIds.length > 0) {
-        const multiple = sessionIds.length > 1;
-        broadcastUiNotification({
-          title: multiple ? 'Chats interrupted' : 'Chat interrupted',
-          body: multiple
-            ? 'OpenCode restarted during running responses. Send a message in each chat to continue.'
-            : 'OpenCode restarted during a running response. Send a message to continue.',
-          tag: 'opencode-restart-interrupted',
-          kind: 'opencode-restart-interrupted',
-          sessionId: sessionIds[0],
-        });
-      }
-    } catch (error) {
-      console.warn('Failed to reconcile sessions after OpenCode restart:', error?.message ?? error);
-    }
-  },
+  onOpenCodeRestarted: () => openCodeRecoveryCallbacks.onManagedRestarted(),
   getManagedOpenCodeEnv: async () => (managedConfigRuntime ? managedConfigRuntime.buildManagedChildEnv() : {}),
 });
 
 const getOpenCodeCompatibility = async () => {
-  if (isExternalOpenCode || ENV_SKIP_OPENCODE_START) {
-    const base = ENV_CONFIGURED_OPENCODE_HOST?.origin || openCodeBaseUrl || `http://127.0.0.1:${openCodePort || ENV_EFFECTIVE_PORT}`;
+  if (getOpenCodeConnectionKind() !== 'managed-owned' || ENV_SKIP_OPENCODE_START) {
+    const base = ENV_CONFIGURED_OPENCODE_HOST?.origin || getOpenCodeBaseUrl() || `http://127.0.0.1:${openCodePort || ENV_EFFECTIVE_PORT}`;
     const version = await readExternalOpenCodeVersion(base, getOpenCodeAuthHeaders()).catch(() => null);
-    return describeOpenCodeCompatibility(version, 'external', false);
+    const installation = getOpenCodeConnectionKind() === 'shared-local' ? 'shared' : 'external';
+    return describeOpenCodeCompatibility(version, installation, false);
   }
   const binary = ensureOpencodeCliEnv();
   const installation = isBundledOpenCodeCliPath(binary) ? 'bundled' : 'managed';
@@ -1357,6 +1371,14 @@ const getOpenCodeCompatibility = async () => {
 };
 
 const getOpenCodeUpgradeCapability = () => {
+  if (getOpenCodeConnectionKind() === 'shared-local') {
+    return resolveOpenCodeUpgradeCapability({
+      isExternal: true,
+      hasManagedProcess: false,
+      activeBinary: null,
+      isBundledBinary: isBundledOpenCodeCliPath,
+    });
+  }
   const activeBinary = lastOpenCodeLaunchDiagnostics?.sourceBinary
     || lastOpenCodeLaunchDiagnostics?.binary
     || resolvedOpencodeBinary;
@@ -1368,12 +1390,19 @@ const getOpenCodeUpgradeCapability = () => {
   });
 };
 
-const restartOpenCode = (...args) => openCodeLifecycleRuntime.restartOpenCode(...args);
+const openCodeLifecycleControls = createOpenCodeLifecycleControls({
+  getKind: getOpenCodeConnectionKind,
+  restartLifecycle: (...args) => openCodeLifecycleRuntime.restartOpenCode(...args),
+  triggerLifecycleHealthCheck: (...args) => openCodeLifecycleRuntime.triggerHealthCheck(...args),
+  recoverShared: () => sharedOpenCodeServiceRuntime.recover(),
+  onSharedRecovered: openCodeRecoveryCallbacks.onSharedRecovered,
+});
+const restartOpenCode = (...args) => openCodeLifecycleControls.restart(...args);
 const waitForOpenCodeReady = (...args) => openCodeLifecycleRuntime.waitForOpenCodeReady(...args);
 const waitForAgentPresence = (...args) => openCodeLifecycleRuntime.waitForAgentPresence(...args);
 const refreshOpenCodeAfterConfigChange = (...args) => openCodeLifecycleRuntime.refreshOpenCodeAfterConfigChange(...args);
 const startHealthMonitoring = () => openCodeLifecycleRuntime.startHealthMonitoring(HEALTH_CHECK_INTERVAL);
-const triggerHealthCheck = () => openCodeLifecycleRuntime.triggerHealthCheck();
+const triggerHealthCheck = (...args) => openCodeLifecycleControls.triggerHealthCheck(...args);
 const scheduledTasksRuntime = createScheduledTasksRuntime({
   projectConfigRuntime,
   listProjects: async () => {
@@ -1595,9 +1624,19 @@ const ensureGlobalWatcherStarted = async () => {
   return globalWatcherStartPromise;
 };
 const bootstrapOpenCodeAtStartup = async (...args) => {
-  await openCodeLifecycleRuntime.bootstrapOpenCodeAtStartup(...args);
+  if (getOpenCodeConnectionKind() === 'shared-local') {
+    const connection = await sharedOpenCodeServiceRuntime.connect();
+    setSharedOpenCodeConnection(connection);
+    isOpenCodeReady = true;
+    isExternalOpenCode = true;
+    lastOpenCodeError = null;
+    openCodeNotReadySince = 0;
+    syncToHmrState();
+  } else {
+    await openCodeLifecycleRuntime.bootstrapOpenCodeAtStartup(...args);
+  }
   scheduleOpenCodeApiDetection();
-  if (openCodeLifecycleState.openCodeProcess && !openCodeLifecycleState.isExternalOpenCode) {
+  if (ownsOpenCodeProcess() && openCodeLifecycleState.openCodeProcess && !openCodeLifecycleState.isExternalOpenCode) {
     startHealthMonitoring();
   }
   // The global watcher used to start only for desktop notifications; the
@@ -1634,6 +1673,7 @@ const gracefulShutdownRuntime = createGracefulShutdownRuntime({
   contextObligatoryRuntime,
   messageQueueRuntime,
   sessionRuntime,
+  globalEventHub: globalMessageStreamHub,
   getHealthCheckInterval: () => healthCheckInterval,
   clearHealthCheckInterval: (value) => clearInterval(value),
   getTerminalRuntime: () => terminalRuntime,
@@ -1644,7 +1684,7 @@ const gracefulShutdownRuntime = createGracefulShutdownRuntime({
   setMessageStreamRuntime: (value) => {
     messageStreamRuntime = value;
   },
-  shouldSkipOpenCodeStop: () => ENV_SKIP_OPENCODE_START || isExternalOpenCode,
+  getOpenCodeConnectionKind,
   getOpenCodePort: () => openCodePort,
   getOpenCodeProcess: () => openCodeProcess,
   setOpenCodeProcess: (value) => {
@@ -1652,6 +1692,7 @@ const gracefulShutdownRuntime = createGracefulShutdownRuntime({
   },
   killProcessOnPort,
   waitForPortRelease,
+  disposeSharedOpenCodeService: () => sharedOpenCodeServiceRuntime?.dispose(),
   getServer: () => server,
   getUiAuthController: () => uiAuthController,
   setUiAuthController: (value) => {
@@ -1676,6 +1717,11 @@ const gracefulShutdown = (...args) => gracefulShutdownRuntime.gracefulShutdown(.
 
 async function main(options = {}) {
   beginGuestServiceHost();
+  const runtimeName = process.env.OPENCHAMBER_RUNTIME || 'web';
+  const lifecycleMode = options.openCodeLifecycleMode === 'managed'
+    || options.openCodeLifecycleMode === 'shared'
+    ? options.openCodeLifecycleMode
+    : undefined;
   const port = Number.isFinite(options.port) && options.port >= 0 ? Math.trunc(options.port) : DEFAULT_PORT;
   const host = typeof options.host === 'string' && options.host.length > 0 ? options.host : undefined;
   const effectiveBindHost = host
@@ -1687,7 +1733,6 @@ async function main(options = {}) {
     fsPromises,
     path,
     dataDir: OPENCHAMBER_DATA_DIR,
-    env: process.env,
     executeAction: (...args) => openChamberControlService.execute(...args),
     // A v2 tool call carries no directory, only the session it runs in.
     resolveSessionDirectory: (sessionID) => openChamberControlService.resolveSessionDirectory(sessionID),
@@ -1698,15 +1743,31 @@ async function main(options = {}) {
     // A pipe listener reports a string here, which has no address to bind back to.
     getActiveHost: () => server?.address?.()?.address ?? null,
   });
-  managedConfigRuntime = createManagedConfigRuntime({
-    fsPromises,
-    path,
-    dataDir: OPENCHAMBER_DATA_DIR,
-    env: process.env,
-    agentToolRuntime,
-    readSettings: () => readSettingsFromDiskMigrated(),
-    isAgentMemoryAvailable: isAgentMemoryFeatureAvailable,
+  const openCodeComposition = createOpenCodeServerComposition({
+    runtime: runtimeName,
+    configuredHost: ENV_CONFIGURED_OPENCODE_HOST,
+    lifecycleMode,
+    createSharedRuntime: () => {
+      const binary = ensureOpencodeCliEnv();
+      return createSharedOpenCodeServiceRuntime({
+        ensureOptions: binary ? { command: [binary, 'serve', '--service'] } : undefined,
+      });
+    },
+    createManagedPluginRuntime: () => createManagedConfigRuntime({
+      fsPromises,
+      path,
+      dataDir: OPENCHAMBER_DATA_DIR,
+      env: process.env,
+      agentToolRuntime,
+      readSettings: () => readSettingsFromDiskMigrated(),
+      isAgentMemoryAvailable: isAgentMemoryFeatureAvailable,
+    }),
+    getManagedBaseUrl: () => openCodeBaseUrl,
+    getManagedAuthHeaders: getManagedOpenCodeAuthHeaders,
   });
+  sharedOpenCodeServiceRuntime = openCodeComposition.sharedRuntime;
+  managedConfigRuntime = openCodeComposition.managedPluginRuntime;
+  openCodeConnectionAdapter = openCodeComposition.connection;
 
   // Pairing transports advertised to the create-device dialog. LAN reachability is
   // derived from the SERVER's actual bind (a wildcard bind → the machine's LAN IP;
@@ -1903,7 +1964,7 @@ async function main(options = {}) {
   const bootstrapResult = bootstrapRuntime.setupBaseRoutes(app, {
     process,
     openchamberVersion: OPENCHAMBER_VERSION,
-    runtimeName: process.env.OPENCHAMBER_RUNTIME || 'web',
+    runtimeName,
     serverStartedAt,
     gracefulShutdown,
     getHealthSnapshot: () => {
@@ -2199,7 +2260,6 @@ async function main(options = {}) {
     terminalRebindWindowMs: TERMINAL_INPUT_WS_REBIND_WINDOW_MS,
     terminalMaxRebindsPerWindow: TERMINAL_INPUT_WS_MAX_REBINDS_PER_WINDOW,
     setupProxy,
-    scheduleOpenCodeApiDetection,
     bootstrapOpenCodeAtStartup,
     triggerHealthCheck,
     staticRoutesRuntime,
@@ -2264,10 +2324,12 @@ async function main(options = {}) {
       scheduledTasks: scheduledTasksRuntime.getStatus(),
     }),
     isReady: () => isOpenCodeReady,
-    getManagedOpenCodePreflight: () => openCodeLifecycleRuntime.getManagedOpenCodePreflight(),
+    getManagedOpenCodePreflight: () => ownsOpenCodeProcess()
+      ? openCodeLifecycleRuntime.getManagedOpenCodePreflight()
+      : Promise.resolve(false),
     restartOpenCode: () => restartOpenCode(),
     getOpenCodeProcessInfo: () => {
-      const managed = Boolean((openCodeProcess || openCodePort) && !ENV_SKIP_OPENCODE_START && !isExternalOpenCode);
+      const managed = Boolean(ownsOpenCodeProcess() && (openCodeProcess || openCodePort) && !ENV_SKIP_OPENCODE_START && !isExternalOpenCode);
       // Only ever expose pid/port for a server WE manage. The Electron-side
       // killer kills by port (lsof + kill -KILL), so returning a port we don't
       // own — e.g. an external/desktop OpenCode on 4096 we attached to — would

package/server/lib/agent-tool/DOCUMENTATION.md

@@ -1,116 +1,55 @@
-# Managed OpenChamber Agent Tool
+# Managed OpenChamber agent tools
 
 ## Purpose
 
-This module exposes OpenChamber to agents as typed OpenCode custom tools. There
-are two, because controlling sessions and driving a page are separate intents
-the user can want independently:
-
-- `openchamber` — projects, sessions, worktrees, scheduled tasks, and showing
-  a file to the user (`file.open`). Enabled while the persisted
-  `agentControlToolEnabled` setting is not `false`.
-- `openchamber_web` — looking at and interacting with the page in OpenChamber's
-  browser panel. Enabled while `agentWebToolEnabled` is not `false`.
-
-Both default to on, are toggled in Settings → General → OpenCode CLI, and take
-effect in the running OpenCode within a couple of seconds — OpenChamber rewrites
-the managed config file OpenCode watches (see
-`lib/opencode/managed-config-file.js`). Installs where the user's own
-environment sets `OPENCODE_CONFIG` fall back to `OPENCODE_CONFIG_CONTENT` and
-still need a restart for a toggle. Each tool carries only its own actions and
-only the parameters those actions use, so turning one off removes its inputs
-from the schema rather than leaving them visible. The plugin is injected only
-when OpenChamber launches and owns the OpenCode process, and not at all when
-both settings are `false`.
-
-- The plugin accepts the action's inputs either inside `parameters` or beside
-  `action`, because models produce both shapes; an explicit `parameters` object
-  wins on a conflict. Rejecting the flattened shape turned a call that plainly
-  carried a `url` into "url is required", which reads as a broken tool rather
-  than a malformed call.
-
-## Runtime flow
-
-1. The OpenChamber HTTP listener binds and publishes its authoritative port.
-2. `materializePlugin()` writes the plugin under
-   `<openchamber-data-dir>/agent-tool/` and returns its directory; the managed
-   config layer lists that directory in `<data-dir>/opencode.managed.json` and
-   rewrites the file whenever a tool setting changes.
-3. `createChildEnv()` adds a random per-child token and the callback URL to the
-   managed OpenCode child environment. They are present even while every tool
-   is off, so a tool switched on later can call back without a restart. The URL
-   points at loopback, except when the listener is bound to one concrete
-   address (`--host <ip>`): that socket does not answer on loopback, so the URL
-   uses the bound address instead.
-4. The plugin calls `POST /api/openchamber/agent-tool` with its typed input and
-   the session id OpenCode gives the tool; OpenChamber resolves the session's
-   directory on its own side.
-5. The route delegates the fixed action allowlist directly to the shared
-   OpenChamber control service. The CLI uses the same service through its
-   authenticated HTTP adapter, so Goal Mode ordering, wait behavior,
-   partial-failure reporting, and scheduled-task contracts have one owner.
-6. Each action definition owns a short presentation title and a separate
-   agent-facing description. The generated schema uses the description to state
-   required inputs or one non-obvious behavior, while completed calls use the
-   short title in native tool metadata.
-
-## Agent context budget
-
-- The tool exposes one shared parameter object rather than repeating parameters
-  in a large per-action union. Action descriptions carry only required inputs,
-  defaults, or one non-obvious semantic detail.
-- The action schema carries `oneOf` and no `enum`. A node combining `enum` and
-  `oneOf` is valid JSON Schema, but some OpenAI-compatible gateways reject it
-  and answer with an empty completion instead of an error.
-- Obvious fields rely on their names and JSON types. Parameter descriptions are
-  reserved for formats, dependencies, scope, and behavior that cannot be safely
-  inferred from the field name.
-- Session dispatches do not wait by default. Agents are told to set `wait` only
-  when the user asks or the next step requires the completed result.
-- The tool exposes only agent-relevant actions
-  (`OPENCHAMBER_AGENT_TOOL_ACTIONS`): `schedule.status` stays CLI-only because
-  `schedule.list` already returns scheduler status, and enable/disable are one
-  `schedule.toggle` action driven by the `disabled` boolean.
-- The tool description frames intent: created sessions and scheduled tasks are
-  user-facing work the user follows up with. The agent must not decide on its
-  own to delegate parts of its current task, but an explicit user request to
-  create, send, or schedule always wins, even when it relates to the current
-  task (strict models otherwise read the old unconditional "never delegate" as
-  a hard ban and refused user-requested sends).
-- Optional behavior switches (`worktree`, `goal`, `agent`, `variant`, `wait`)
-  state their default and an explicit "only when the user asks" rule so agents
-  do not invent worktrees, goal mode, or waits the user never requested.
-- Detailed combination rules are enforced by the shared control service and
-  returned as actionable usage errors only after an invalid call. Per-action
-  examples and a repeated per-action parameter schema are intentionally omitted.
+This module exposes OpenChamber actions as typed OpenCode custom tools for Electron Desktop's managed OpenCode child.
+
+The main tools are:
+
+- `openchamber` for projects, sessions, worktrees, scheduled tasks, and `file.open`
+- `openchamber_web` for inspecting and interacting with the page in OpenChamber's browser panel
+
+Their persisted settings control whether each tool is present. Tool definitions include only the actions and inputs enabled for that tool.
+
+## Runtime boundary
+
+Electron Desktop owns the managed integration:
+
+1. `materializePlugin()` writes the generated plugin under `<openchamber-data-dir>/agent-tool/`.
+2. The managed OpenCode config lists that plugin directory.
+3. `createChildEnv()` gives the owned OpenCode child a random callback token and loopback callback URL.
+4. The plugin calls `POST /api/openchamber/agent-tool` with its typed input and OpenCode session ID.
+5. OpenChamber resolves the session directory and delegates the fixed action allowlist to the shared control service.
+
+The callback token stays in the managed child environment. It is never persisted, logged, returned to the UI, or written into the generated plugin.
+
+Ordinary Web does not install a plugin, publish callback registration, or advertise managed OpenChamber tools to the shared local OpenCode service. This keeps shared Web limited to sessions and live events. A valid `OPENCODE_HOST` is also outside managed-tool ownership, so OpenChamber does not guarantee tools on that endpoint.
+
+VS Code keeps its separate lifecycle. Hosted and Capacitor clients do not run tools themselves. They may connect to a Desktop-owned backend that has managed tools, but an ordinary Web backend does not add them.
+
+## Input contract
+
+The plugin accepts action inputs inside `parameters` or beside `action`. An explicit `parameters` object wins when both forms provide the same field.
+
+Each action definition has a short presentation title and a separate agent-facing description. The generated schema uses descriptions only for required inputs, defaults, or behavior that a field name cannot explain.
+
+The schema uses one shared parameter object with `oneOf` and no `enum`. Some OpenAI-compatible gateways reject a node that combines both and return an empty completion.
+
+Session dispatch does not wait by default. Optional switches such as `worktree`, `goal`, `agent`, `variant`, and `wait` state their defaults and tell the agent not to invent them.
 
 ## Security invariants
 
-- The callback accepts same-machine requests only and requires the current
-  per-child bearer token using a timing-safe comparison. Same-machine means a
-  loopback source, or, for a listener bound to one concrete address, a source
-  equal to that address: the OS sources a local connection to `<ip>` from
-  `<ip>`. A wildcard bind keeps the loopback-only rule, and another machine on
-  the network always arrives with its own address.
-- The token is never persisted, logged, returned to the UI, or written into
-  the materialized plugin.
-- The plugin adds the callback host to `NO_PROXY`/`no_proxy` inside the managed
-  child when it loads. Without that, an `HTTP_PROXY` in the child's environment
-  would receive a non-loopback callback, token included, because `fetch` has no
-  per-request way to skip the environment proxy.
-- Inputs map to a fixed action and parameter allowlist. There is no arbitrary
-  CLI, shell, route, or URL forwarding.
-- Session/worktree deletion and project-path registration are not exposed.
-- A cancelled turn aborts the session's in-flight actions. OpenCode 2 gives a
-  plugin tool no abort signal and the plugin's request stays open, so the
-  server tracks in-flight actions per session and `abortSession(sessionID)` is
-  called from the event dispatch in `server/index.js` when the stream reports
-  `session.idle` with `aborted: true`; the abort signal then reaches the
-  shared service as before. A dropped HTTP request still aborts as well.
+- The callback accepts same-machine requests only and requires the current managed-child bearer token with a timing-safe comparison.
+- A concrete listener address may accept a source equal to that address. A wildcard listener remains loopback-only.
+- The plugin adds its callback host to `NO_PROXY` and `no_proxy` in the managed child so an environment proxy cannot receive the callback token.
+- Inputs map to fixed tool, action, and parameter allowlists. There is no arbitrary CLI, shell, route, or URL forwarding.
+- Project-path registration and session or worktree deletion are not exposed.
+- A dropped callback request aborts its action.
+- OpenCode 2 does not give plugin tools an abort signal. The server therefore tracks actions by session and aborts them when the event stream reports an aborted `session.idle` transition.
 
 ## Result contract
 
-Every completed call returns JSON:
+Completed calls return JSON:
 
 ```json
 {
@@ -121,29 +60,10 @@ Every completed call returns JSON:
 }
 ```
 
-Command and operational failures use the same envelope with `ok: false` and
-an `error` object. OpenCode-level cancellation can still produce a native tool
-error state.
-
-## Runtime parity
-
-- Web and Desktop managed OpenCode: injected automatically.
-- External OpenCode selected with `OPENCODE_HOST` or skip-start: not injected,
-  because OpenChamber does not control that process environment.
-- VS Code: not injected; the extension owns a separate OpenCode lifecycle.
-- Hosted and Capacitor mobile clients use the server's managed OpenCode tool
-  when connected to such a server; no tool runs in the client runtime.
+Command and operational failures use the same envelope with `ok: false` and an `error` object. OpenCode-level cancellation can still produce a native tool error.
 
-## The calling tool is part of the request
+## Action resolution
 
-Each generated tool sends its own name with every callback. Models routinely
-drop the namespace their tool's name appears to supply — `openchamber_memory`
-asked for `memory.read` gets called as `read` — and resolving the bare name
-inside the calling tool's action set makes that unambiguous even where it is not
-globally (`delete` belongs to both schedule and memory).
+Each generated tool sends its own name with every callback. Action resolution stays within that tool's allowlist. For example, a bare `open` requested by a memory tool cannot drive the browser.
 
-Resolution never reaches outside the tool that asked: `open` from the memory
-tool fails rather than driving the browser. An unresolvable action answers with
-the actions that tool actually has, because an error that only says
-"unsupported" leaves the model to guess a second wrong name — which is exactly
-what happened before this existed.
+When an action name is invalid, the response lists the actions available to the calling tool. This lets the model correct the call without guessing across tool namespaces.