@cabane/companion 0.6.227 → 0.6.229

package/README.md

@@ -158,7 +158,7 @@ An operator-managed sandbox can use the host-side `@cabane/companion/credential-
 
 Run the broker and its credential files under a host identity outside every sandbox UID mapping. Hold an exclusive process lock for the entire service lifetime, including shutdown: there must be exactly one renewal owner for each account file. The parent of an account file must be owned by that identity with mode `0700`; the file must be a regular, single-link `0600` file. Stop the service before importing or changing login state. `fileCredentialStore(path)` and `openBrokerCredentials(store)` read that state; share the resulting owner between every grant using the account. Renewal writes and fsyncs a replacement before releasing it. A failed persistence write refuses further use until the operator recovers the stored account.
 
-The account format is `{ mode, accessToken, refreshToken?, idToken?, expiresAt?, accountId? }`. `mode` is `claude-setup`, `claude-oauth`, `codex-oauth` or `github`. OAuth modes require a refresh token and an expiry in epoch milliseconds. A setup token never renews. Normal Claude OAuth renews inside the broker before expiry, or on one upstream 401; Codex renewal returns fresh placeholders to its client. Never place the real account file, a credential-store bind, or an alternate harness login inside the sandbox. Real OAuth compatibility must be verified with the installed harness and login mode; a successful setup-token turn proves nothing about OAuth renewal.
+The account format is `{ mode, accessToken, refreshToken?, idToken?, expiresAt?, accountId? }`. `mode` is `claude-setup`, `claude-oauth`, `codex-oauth` or `github`. OAuth modes require a refresh token and an expiry in epoch milliseconds. A setup token never renews. Normal Claude OAuth renews inside the broker before expiry, or on one upstream 401; Codex renewal returns fresh placeholders to its client. After a failed exchange the owner refuses renewal for a backoff window, 30 seconds doubling to 15 minutes, rather than retrying upstream on every request; a successful renewal clears it. Never place the real account file, a credential-store bind, or an alternate harness login inside the sandbox. Real OAuth compatibility must be verified with the installed harness and login mode; a successful setup-token turn proves nothing about OAuth renewal.
 
 Create the broker with `createCredentialBroker({ resolveIdentity, audit? })`. Its `server` handles model and git routes; bind it only to host loopback. Git's HTTP proxy requests are accepted only for the exact `http://github.com/` authority, then forwarded to fixed HTTPS GitHub upstreams. Arbitrary proxy destinations and CONNECT tunnels are refused. Its `githubServer` handles gh's `http_unix_socket` transport; authenticate that socket's peer too. Neither exposes a management endpoint. Call `grant({ identity, credentials, expiresAt })` only from the trusted host adapter. `credentials` maps `claude`, `codex` and `github` to their corresponding credential owners. The returned `token` is disposable; `revoke()` aborts active requests and removes its aliases. Teardown calls `revokeIdentity(identity)`; service shutdown calls `revokeAll()` and closes both servers. A restart creates fresh grants, so old placeholders stop working.
 
@@ -166,7 +166,7 @@ Scope the GitHub token on GitHub's side; the broker imposes no repository, branc
 
 Set `runner.brokeredCredentials: true` beside `runner.command` in the Companion config. This removes provider and GitHub credential variables from the launcher's environment, secret-store payload and device-grant payload before the wrapper receives them. The wrapper supplies `brokerClientConfiguration({ baseUrl, placeholder, githubSocket, codexConfig })`'s environment and generated configuration to the isolated home, and writes `await grant.codexAuth()` as its placeholder-only Codex `auth.json`. The helper preserves the supplied Codex settings while selecting the broker provider and HTTP Responses transport. Include its git configuration in the sandbox's global config and use its gh configuration there. For a GitHub-enabled box, provide `githubSocket`. The helper sets `GH_TOKEN` and preserves `github.com` in git's expanded remote so gh can resolve a tracked branch, without setting `GH_REPO`. The generated git config rewrites HTTPS URLs to an HTTP GitHub URL carrying only a placeholder, and sends that origin through the loopback broker using Git's per-origin `http.proxy`; the broker's upstream hop remains HTTPS. Install the entire generated config, replacing the previous generated file, rather than retaining an older rewrite. Do not bypass this proxy with `NO_PROXY` or a per-remote proxy override. For a model-only box, omit `githubSocket` or pass `null`; no GitHub environment is emitted and both git/gh config strings are empty, so an adapter can clear any previous generated routing. The wrapper must remove old credential mounts and alternate authentication helpers; this switch cannot inspect or secure an operator's filesystem mounts.
 
-The fixed upstream hosts are `api.anthropic.com`, `chatgpt.com`, `api.github.com` and `github.com`. Paths and request bodies pass through without a workflow policy, except for known credential-minting, credential-registering or disclosure endpoints: Claude CLI API-key creation and OAuth token exchange, ChatGPT session/token disclosure, and GitHub app-manifest conversion, installation/application token endpoints, legacy authorizations, SSH user/deploy-key registration, runner registration/removal/JIT credentials and OAuth/device token endpoints. These return new secrets the echo filter cannot know in advance, or register box-chosen credentials that would outlive the grant. This deny-list must be revisited when providers add credential-returning or credential-registering routes; it is not a guarantee against unknown endpoints or arbitrary encodings. Redirects are refused and responses are filtered for known credential echoes. Credential-free injection is restricted to Codex's designated `/backend-api/ps/mcp` route. Each upstream exchange is capped at ten minutes, and request bodies at 64 MiB.
+The fixed upstream hosts are `api.anthropic.com`, `chatgpt.com`, `api.github.com` and `github.com`. Paths and request bodies pass through without a workflow policy, except for known credential-minting, credential-registering or disclosure endpoints: Claude CLI API-key creation and OAuth token exchange, ChatGPT session/token disclosure, and GitHub app-manifest conversion, installation/application token endpoints, legacy authorizations, SSH user/deploy-key registration, runner registration/removal/JIT credentials and OAuth/device token endpoints. These return new secrets the echo filter cannot know in advance, or register box-chosen credentials that would outlive the grant. This deny-list must be revisited when providers add credential-returning or credential-registering routes; it is not a guarantee against unknown endpoints or arbitrary encodings. Redirects are refused and responses are filtered for known credential echoes. Credential-free injection is restricted to Codex's designated `/backend-api/ps/mcp` route. Each upstream exchange, streams included, is capped at ten minutes by default (`requestTimeoutMs` on `createCredentialBroker`), and request bodies at 64 MiB.
 
 Arbitrary room secrets and other MCP credentials still follow their existing delivery contract. This API does not protect SSH keys or offer general secret injection into arbitrary HTTP destinations. Claude's feature flags fall back to defaults when their direct requests use placeholders. Before enabling a sandbox deployment, verify actual socket ownership, PID/namespace reuse, service UID separation, grant revocation, concurrent renewal and restart, required client operations, and a canary extraction attempt from inside the real sandbox. A successful unit test or package installation does not establish that host boundary.
 

package/dist/cli.js

@@ -2822,8 +2822,10 @@ var init_pump = __esm({
 
 // packages/agent-runtime/src/turn-control/prompt-guidance.ts
 function turnControlPromptGuidance(prefix) {
-  const controls = TURN_CONTROL_TOOLS.map((name) => `\`${prefix}${name}\` (${MEANINGS[name]})`);
-  return `The turn tools are: ${controls.join("; ")}. Read a tool's description before calling it. A peer response is ordinary conversation speech; your reply is the answer.`;
+  return [
+    "Turn tools (read each description before calling):",
+    ...TURN_CONTROL_TOOLS.map((name) => `- \`${prefix}${name}\` \u2014 ${MEANINGS[name]}.`)
+  ].join("\n");
 }
 var MEANINGS;
 var init_prompt_guidance = __esm({
@@ -2832,8 +2834,8 @@ var init_prompt_guidance = __esm({
     init_descriptions();
     MEANINGS = {
       answer: "declare the text you write next as your answer",
-      open_exchange: "put a question, go-ahead or request to a person",
-      cancel_wake: "cancel your own armed wake in this conversation",
+      open_exchange: "ask a person for a decision, approval or action",
+      cancel_wake: "cancel your scheduled return to this conversation",
       skip_turn: "end without posting a reply",
       wake_me: "schedule your own return; when it fires, say what you came back to check",
       withdraw_exchange: "withdraw an open exchange in this conversation with a reason"
@@ -2848,15 +2850,14 @@ var init_addendum = __esm({
     "use strict";
     init_prompt_guidance();
     CLAUDE_CODE_ADDENDUM = [
-      "On this harness the Cabane tools register under MCP prefixes. The workspace tools are",
-      "`mcp__cabane__query`, `mcp__cabane__mutate` and `mcp__cabane__describe`; the ancillary",
-      "tools are `mcp__cabane__read_binary`, `mcp__cabane__upload`, `mcp__cabane__begin_upload`,",
-      "`mcp__cabane__finalize_upload`, and `mcp__cabane__mint_render_token`.",
-      turnControlPromptGuidance("mcp__cabane_companion__"),
-      "Where this prompt names a tool by its bare verb, call",
-      "the prefixed form from your tool list. Your harness's own tools (shell, local file",
-      "read/edit) keep their ordinary names and act on the local machine only."
-    ].join(" ");
+      "- Workspace tools: `mcp__cabane__query`, `mcp__cabane__mutate`, `mcp__cabane__describe`.",
+      "- File tools: `mcp__cabane__read_binary`, `mcp__cabane__upload`, `mcp__cabane__begin_upload`, `mcp__cabane__finalize_upload`.",
+      "- Page verification: `mcp__cabane__mint_render_token`.",
+      "- Where these instructions use a bare tool name, call its prefixed form from the tool list.",
+      "- Host tools such as the shell and local file editor keep their ordinary names and act on the local device.",
+      "",
+      turnControlPromptGuidance("mcp__cabane_companion__")
+    ].join("\n");
   }
 });
 
@@ -3704,17 +3705,14 @@ var init_addendum2 = __esm({
     "use strict";
     init_prompt_guidance();
     OPENCODE_ADDENDUM = [
-      "Every tool here goes by its plain name: the workspace tools are `query`, `mutate` and",
-      "`describe`.",
-      turnControlPromptGuidance(""),
-      "The ancillary tools are `read_binary`, `upload`, `begin_upload`,",
-      "`finalize_upload`, `mint_render_token`; and the host tools are plain verbs too (`bash`,",
-      "`read`, `edit`). Mind the collision: a bare `read` or `edit` is the HOST tool, acting on the",
-      "local machine \u2014 a workspace read is `query` with the operation name `files.read`. The",
-      "collision runs the other way too: `read` is a host tool here AND `files.read` is an",
-      "operation name, so keep the bare verb and the dotted name apart. If a tool ever appears with",
-      "an `mcp__\u2026__` prefix, that prefix is not part of its name here."
-    ].join(" ");
+      "- Workspace tools: `query`, `mutate`, `describe`.",
+      "- File tools: `read_binary`, `upload`, `begin_upload`, `finalize_upload`.",
+      "- Page verification: `mint_render_token`.",
+      "- Call tools by their plain names here, without an `mcp__\u2026__` prefix.",
+      "- Host tools such as `bash`, `read` and `edit` act on the local device. To read a workspace file, call `query` with the operation `files.read`.",
+      "",
+      turnControlPromptGuidance("")
+    ].join("\n");
   }
 });
 
@@ -4447,23 +4445,14 @@ var init_addendum3 = __esm({
     "use strict";
     init_prompt_guidance();
     CODEX_ADDENDUM = [
-      "Codex surfaces MCP tools under qualified names, and on some versions defers them. The",
-      "workspace tools are `mcp__cabane__query`, `mcp__cabane__mutate` and",
-      "`mcp__cabane__describe` \u2014 if they aren't in your visible tool list, locate them in",
-      "the deferred-tool inventory and invoke those exact qualified names; never conclude the",
-      "workspace is",
-      "absent without attempting discovery and invocation, and if a call fails, report the recorded",
-      "error.",
-      turnControlPromptGuidance("mcp__cabane_companion__"),
-      // Every ancillary tool is written as Codex's own tool list shows it — qualified — so the sentence
-      // instructing exact qualified names doesn't contradict itself. The bare `query` / `mutate` below
-      // stay: that sentence is about operation names, after the qualified forms are given.
-      "The ancillary tools are `mcp__cabane__read_binary`, `mcp__cabane__upload`,",
-      "`mcp__cabane__begin_upload`, `mcp__cabane__finalize_upload` and",
-      "`mcp__cabane__mint_render_token` \u2014 all possibly deferred too.",
-      "There is no Cabane `read`/`write`/`search` tool \u2014 those are",
-      "operation NAMES you pass to `query` / `mutate`."
-    ].join(" ");
+      "- Workspace tools: `mcp__cabane__query`, `mcp__cabane__mutate`, `mcp__cabane__describe`.",
+      "- File tools: `mcp__cabane__read_binary`, `mcp__cabane__upload`, `mcp__cabane__begin_upload`, `mcp__cabane__finalize_upload`.",
+      "- Page verification: `mcp__cabane__mint_render_token`.",
+      "- Codex may defer MCP tools. If a listed tool is missing, search the deferred-tool inventory and call the matching tool by its exact name. Report discovery or call failures with the recorded error.",
+      "- Names such as `files.read` are operations passed to `query` or `mutate`, not separate tools.",
+      "",
+      turnControlPromptGuidance("mcp__cabane_companion__")
+    ].join("\n");
   }
 });
 

package/dist/credential-broker.js

@@ -176,6 +176,7 @@ function refuse(res, route, body, status = 403) {
 function createCredentialBroker(options) {
   const now = options.now ?? Date.now;
   const upstream = options.fetch ?? fetch;
+  const requestTimeoutMs = options.requestTimeoutMs ?? 6e5;
   const grants = /* @__PURE__ */ new Set();
   const byToken = /* @__PURE__ */ new Map();
   function revoke(grant) {
@@ -233,7 +234,7 @@ function createCredentialBroker(options) {
       grant.active.add(abort);
       const signal = AbortSignal.any([
         abort.signal,
-        AbortSignal.timeout(Math.max(1, Math.min(6e5, grant.expiresAt - now())))
+        AbortSignal.timeout(Math.max(1, Math.min(requestTimeoutMs, grant.expiresAt - now())))
       ]);
       res.once("close", () => abort?.abort());
       body ??= await readBody(req);
@@ -490,6 +491,8 @@ var OAUTH = {
     clientId: "app_EMoamEEZ73f0CkXaXp7hrann"
   }
 };
+var REFRESH_BACKOFF_MS = 3e4;
+var REFRESH_BACKOFF_MAX_MS = 9e5;
 async function openBrokerCredentials(store, ports = {}) {
   let account;
   try {
@@ -501,6 +504,8 @@ async function openBrokerCredentials(store, ports = {}) {
   const now = ports.now ?? Date.now;
   let pending;
   let poisoned = false;
+  let failures = 0;
+  let retryAt = 0;
   const secrets = /* @__PURE__ */ new Set();
   function remember(value) {
     for (const secret of [value.accessToken, value.refreshToken, value.idToken]) {
@@ -568,9 +573,12 @@ async function openBrokerCredentials(store, ports = {}) {
         throw new BrokerError("persistence_failed");
       }
       account = next;
+      failures = 0;
+      retryAt = 0;
       return account;
     } catch (error) {
       if (error instanceof BrokerError) throw error;
+      retryAt = now() + Math.min(REFRESH_BACKOFF_MAX_MS, REFRESH_BACKOFF_MS * 2 ** failures++);
       throw new BrokerError("refresh_failed");
     }
   }
@@ -584,6 +592,7 @@ async function openBrokerCredentials(store, ports = {}) {
       if (!account.mode.endsWith("-oauth") || rejectedAccessToken !== void 0 && rejectedAccessToken !== account.accessToken || rejectedAccessToken === void 0 && (account.expiresAt ?? 0) > now() + 6e4) {
         return account;
       }
+      if (now() < retryAt) throw new BrokerError("refresh_failed");
       pending = renew();
       try {
         return await pending;

package/dist/runtime.js

@@ -3016,28 +3016,29 @@ import {
 // packages/agent-runtime/src/turn-control/prompt-guidance.ts
 var MEANINGS = {
   answer: "declare the text you write next as your answer",
-  open_exchange: "put a question, go-ahead or request to a person",
-  cancel_wake: "cancel your own armed wake in this conversation",
+  open_exchange: "ask a person for a decision, approval or action",
+  cancel_wake: "cancel your scheduled return to this conversation",
   skip_turn: "end without posting a reply",
   wake_me: "schedule your own return; when it fires, say what you came back to check",
   withdraw_exchange: "withdraw an open exchange in this conversation with a reason"
 };
 function turnControlPromptGuidance(prefix) {
-  const controls = TURN_CONTROL_TOOLS.map((name) => `\`${prefix}${name}\` (${MEANINGS[name]})`);
-  return `The turn tools are: ${controls.join("; ")}. Read a tool's description before calling it. A peer response is ordinary conversation speech; your reply is the answer.`;
+  return [
+    "Turn tools (read each description before calling):",
+    ...TURN_CONTROL_TOOLS.map((name) => `- \`${prefix}${name}\` \u2014 ${MEANINGS[name]}.`)
+  ].join("\n");
 }
 
 // packages/agent-runtime/src/claude-code/addendum.ts
 var CLAUDE_CODE_ADDENDUM = [
-  "On this harness the Cabane tools register under MCP prefixes. The workspace tools are",
-  "`mcp__cabane__query`, `mcp__cabane__mutate` and `mcp__cabane__describe`; the ancillary",
-  "tools are `mcp__cabane__read_binary`, `mcp__cabane__upload`, `mcp__cabane__begin_upload`,",
-  "`mcp__cabane__finalize_upload`, and `mcp__cabane__mint_render_token`.",
-  turnControlPromptGuidance("mcp__cabane_companion__"),
-  "Where this prompt names a tool by its bare verb, call",
-  "the prefixed form from your tool list. Your harness's own tools (shell, local file",
-  "read/edit) keep their ordinary names and act on the local machine only."
-].join(" ");
+  "- Workspace tools: `mcp__cabane__query`, `mcp__cabane__mutate`, `mcp__cabane__describe`.",
+  "- File tools: `mcp__cabane__read_binary`, `mcp__cabane__upload`, `mcp__cabane__begin_upload`, `mcp__cabane__finalize_upload`.",
+  "- Page verification: `mcp__cabane__mint_render_token`.",
+  "- Where these instructions use a bare tool name, call its prefixed form from the tool list.",
+  "- Host tools such as the shell and local file editor keep their ordinary names and act on the local device.",
+  "",
+  turnControlPromptGuidance("mcp__cabane_companion__")
+].join("\n");
 
 // packages/agent-runtime/src/mcp-secret-env.ts
 function headersAsEnvReferences(server) {
@@ -3763,17 +3764,14 @@ var claudeCodeAdapter = createClaudeCodeAdapter();
 
 // packages/agent-runtime/src/opencode/addendum.ts
 var OPENCODE_ADDENDUM = [
-  "Every tool here goes by its plain name: the workspace tools are `query`, `mutate` and",
-  "`describe`.",
-  turnControlPromptGuidance(""),
-  "The ancillary tools are `read_binary`, `upload`, `begin_upload`,",
-  "`finalize_upload`, `mint_render_token`; and the host tools are plain verbs too (`bash`,",
-  "`read`, `edit`). Mind the collision: a bare `read` or `edit` is the HOST tool, acting on the",
-  "local machine \u2014 a workspace read is `query` with the operation name `files.read`. The",
-  "collision runs the other way too: `read` is a host tool here AND `files.read` is an",
-  "operation name, so keep the bare verb and the dotted name apart. If a tool ever appears with",
-  "an `mcp__\u2026__` prefix, that prefix is not part of its name here."
-].join(" ");
+  "- Workspace tools: `query`, `mutate`, `describe`.",
+  "- File tools: `read_binary`, `upload`, `begin_upload`, `finalize_upload`.",
+  "- Page verification: `mint_render_token`.",
+  "- Call tools by their plain names here, without an `mcp__\u2026__` prefix.",
+  "- Host tools such as `bash`, `read` and `edit` act on the local device. To read a workspace file, call `query` with the operation `files.read`.",
+  "",
+  turnControlPromptGuidance("")
+].join("\n");
 
 // packages/agent-runtime/src/opencode/events.ts
 function asRecord(v) {
@@ -4433,23 +4431,14 @@ var opencodeAdapter = createOpencodeAdapter();
 
 // packages/agent-runtime/src/codex/addendum.ts
 var CODEX_ADDENDUM = [
-  "Codex surfaces MCP tools under qualified names, and on some versions defers them. The",
-  "workspace tools are `mcp__cabane__query`, `mcp__cabane__mutate` and",
-  "`mcp__cabane__describe` \u2014 if they aren't in your visible tool list, locate them in",
-  "the deferred-tool inventory and invoke those exact qualified names; never conclude the",
-  "workspace is",
-  "absent without attempting discovery and invocation, and if a call fails, report the recorded",
-  "error.",
-  turnControlPromptGuidance("mcp__cabane_companion__"),
-  // Every ancillary tool is written as Codex's own tool list shows it — qualified — so the sentence
-  // instructing exact qualified names doesn't contradict itself. The bare `query` / `mutate` below
-  // stay: that sentence is about operation names, after the qualified forms are given.
-  "The ancillary tools are `mcp__cabane__read_binary`, `mcp__cabane__upload`,",
-  "`mcp__cabane__begin_upload`, `mcp__cabane__finalize_upload` and",
-  "`mcp__cabane__mint_render_token` \u2014 all possibly deferred too.",
-  "There is no Cabane `read`/`write`/`search` tool \u2014 those are",
-  "operation NAMES you pass to `query` / `mutate`."
-].join(" ");
+  "- Workspace tools: `mcp__cabane__query`, `mcp__cabane__mutate`, `mcp__cabane__describe`.",
+  "- File tools: `mcp__cabane__read_binary`, `mcp__cabane__upload`, `mcp__cabane__begin_upload`, `mcp__cabane__finalize_upload`.",
+  "- Page verification: `mcp__cabane__mint_render_token`.",
+  "- Codex may defer MCP tools. If a listed tool is missing, search the deferred-tool inventory and call the matching tool by its exact name. Report discovery or call failures with the recorded error.",
+  "- Names such as `files.read` are operations passed to `query` or `mutate`, not separate tools.",
+  "",
+  turnControlPromptGuidance("mcp__cabane_companion__")
+].join("\n");
 
 // packages/agent-runtime/src/codex/events.ts
 function asRecord3(v) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cabane/companion",
-  "version": "0.6.227",
+  "version": "0.6.229",
   "type": "module",
   "description": "The Cabane Companion (headless): connect an agent on your machine to your Cabane workspace as a responder — drive work against your own codebase, files, and MCP servers without putting any of it in Cabane.",
   "license": "UNLICENSED",