@byokit/openclaw 0.21.0 → 0.22.1

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 0.22.1 (2026-10-19)
+
+- FIX: a funded OpenRouter key now signs in and runs the model the person chooses. Before, `addKey` answered `{ status: 'not_included', reason: 'model' }` for every OpenRouter key, so apps showed a plan refusal and never reached the model: the pinned engine planned the key's live test on `openrouter/auto` but staged the route as the provider normalizes it, and refused the key as unavailable before sending it. A bundled engine patch now plans the test on the staged route; a key whose account has no credits (OpenRouter's HTTP 402) now answers `{ status: 'invalid', reason: 'billing' }`, never a plan refusal. An OpenRouter key pasted under OpenRouter's browser sign-in choice (`addKey(member, { authChoice: 'openrouter-oauth', apiKey })`) also takes OpenRouter's one key route (`openrouter-api-key`); a choice of a provider with exactly one key route billed alike maps the same way, and any other choice that takes no key throws its cause (`openai takes no API key: add the key with openai-api-key.`) instead of a plan refusal.
+
+## 0.22.0 (2026-10-19)
+
+- FEAT: a helper's delegated run is visible from start to finish on `onEvent('byokit.delegated')`: `admitted` carries `run.tools` (its app-tool subset, also on `delegatedRuns()`), and the one `ended` says why in `reason`: `terminal`, `cancelled` (a kit or engine abort, or ended admission), `error` (with the engine's `message`) or `resting`, where the model's usage limit ended a helper's run and the kit rests that helper's account `until` the stated reset, as a kit run's resting end does.
+- FEAT: `Approval.helper` names the helper whose run asks, for gate approvals and for native approvals on a helper's `agent:<agent>:h-<helper>:` key.
+- FEAT: `kit.adoptHelperSession({ member, sessionKey }, helper)` moves a conversation from before helpers into a helper: its whole transcript forks to `agent:<member>:h-<helper>:<tail>` on the helper's account agent and the old session is deleted, with no model request, credential or SQLite copy. A conversation still in flight (live run, parked approval or admitted delegated child) is refused `busy` and keeps its exact old key and approval owner until it settles.
+
 ## 0.21.0 (2026-10-19)
 
 - FEAT: `run({ helperDelegates: { writer: ['report'] } })` lets a run hand work to the member's own helpers: the engine's native `sessions_send` to the exact key `agent:<the helper's agent>:h-<helper>:<rest>`, on an ordinary account or the plan-key lane, is admitted from its receipt as that helper's delegated run (`RunRef.helper`), so its app-tool calls cross the same gate, approvals and tool subset as any delegated child. `abort(rootSessionKey)` revokes them.

package/README.md

@@ -32,6 +32,8 @@ hashes. The Gateway Workshop review patch writes content-free, durable usage fac
 accounting environment. The separately bundled worker and all other detached kinds remain uncovered.
 The Claude CLI route also uses the bundled [Tooling-name correction](../../docs/runtime-kits.md#516-bundled-engine-patches-and-engine-started-usage-d19);
 apps do not need consumer tool aliases.
+A key setup plan patch lets an OpenRouter API key activate: stock plans the key's live test on a route other than the
+one it stages and refuses every OpenRouter key before sending it.
 The full upstream MIT notice ships in [engine/OPENCLAW-LICENSE](engine/OPENCLAW-LICENSE).
 
 Each `prepare()` verifies the **entire** selected engine tree, including unpatched files. The kit installs stock
@@ -149,7 +151,10 @@ returns what that run would choose now, refusals included, without running. `ste
 
 For an owner who explicitly offers keys, `kit.addKey('ana', { authChoice: 'openai-api-key', apiKey })` is a thenable
 handle: `await` it for `{ status: 'ok' }` or `{ status: 'invalid' | 'not_included' | 'retry', reason }`, and call
-`cancel()` to stop a pending add (clears any partial key; settles `retry`/`busy`).
+`cancel()` to stop a pending add (clears any partial key; settles `retry`/`busy`). `authChoice` may also name another
+sign-in of a provider with exactly one key route billed alike (`openrouter-oauth` adds an `openrouter-api-key`); any
+other choice that takes no key (a subscription such as `openai`, a provider with several key routes, an unknown choice)
+throws its cause before anything is sent.
 `reason` is `auth` (provider refused the key) or `billing` (the provider's billing refused it; the kit words it and never passes
 provider text): both are `invalid`, and an unchanged key must not be retried. `empty` is a blank key, rejected locally before any
 provider call, also `invalid`. `model` is an unsupported route or unknown model (`not_included`), or a live model the engine did not

package/dist/keys.js

@@ -77,12 +77,28 @@ export function createKeys(ctx) {
         const rows = (answer.models ?? []).map((m) => ({ ...m, id: canonical(String(m.id)) }));
         return [...new Map(rows.map((m) => [String(m.id), m])).values()];
     };
+    // The key route a choice names: its own, or the only key route of the provider whose other sign-in it names, billed
+    // alike (an OpenRouter key pasted under `openrouter-oauth` is an `openrouter-api-key`). Anything else is the app's
+    // mistake, refused with its cause before anything is sent: never a plan refusal, never a subscription turned per-use.
+    const keyRoute = (authChoice) => {
+        const all = ctx.routes();
+        const named = all.find((r) => r.choice === authChoice);
+        if (!named)
+            throw new Error(`No sign-in is named ${authChoice}.`);
+        if (named.keyEntry)
+            return named;
+        const keyed = all.filter((r) => r.provider === named.provider && r.keyEntry);
+        if (keyed.length === 1 && keyed[0].billing === named.billing)
+            return keyed[0];
+        throw new Error(keyed.length ? `${authChoice} takes no API key: add the key with ${keyed.map((r) => r.choice).join(' or ')}.`
+            : `${authChoice} takes no API key.`);
+    };
     const listed = (provider, rows) => modelsOf(provider, { models: rows.map((m) => ({ ...m, provider })) });
     const models = async (member, o) => {
         if (!check(member))
             throw new Error('Choose your own member.');
-        const route = ctx.routes().find((r) => r.choice === o.authChoice && r.keyEntry && r.readiness === 'ready');
-        if (!route || !LIVE_CATALOGS.includes(route.provider))
+        const route = keyRoute(o.authChoice);
+        if (route.readiness !== 'ready' || !LIVE_CATALOGS.includes(route.provider))
             return [];
         try {
             return listed(route.provider, await catalog(member, route.provider));
@@ -111,8 +127,8 @@ export function createKeys(ctx) {
                     throw new Error('Choose your own member.');
                 if (!o.apiKey.trim())
                     return failure('invalid', 'empty');
-                const route = ctx.routes().find((r) => r.choice === o.authChoice && r.keyEntry && r.readiness === 'ready');
-                if (!route || (o.model !== undefined && !LIVE_CATALOGS.includes(route.provider)))
+                const route = keyRoute(o.authChoice);
+                if (route.readiness !== 'ready' || (o.model !== undefined && !LIVE_CATALOGS.includes(route.provider)))
                     return failure('not_included', 'model');
                 const model = o.model === undefined ? undefined : canonicalModel(o.model);
                 // A workspace names a Go login's own workspace only; another route takes no header, and a
@@ -193,7 +209,7 @@ export function createKeys(ctx) {
                         sent = true;
                         if (ac.signal.aborted)
                             return abandon(cancelled());
-                        const result = await activate(ctx, { kind: 'api-key', agentId, authChoice: o.authChoice, apiKey: o.apiKey }, { timeoutMs: 180_000, signal: ac.signal });
+                        const result = await activate(ctx, { kind: 'api-key', agentId, authChoice: route.choice, apiKey: o.apiKey }, { timeoutMs: 180_000, signal: ac.signal });
                         if (ac.signal.aborted)
                             return abandon(cancelled());
                         if (!result.ok && !result.late)

package/engine/patches.json

@@ -1,6 +1,6 @@
 {
   "v": 1,
-  "id": "a32effe777006347",
+  "id": "dcd1cf72add44075",
   "upstream": {
     "name": "openclaw",
     "version": "2026.8.35",
@@ -65,6 +65,17 @@
           "replace": "let systemPrompt = !skipsTurnPreparation ? backendResolved.transformSystemPrompt?.({\n\t\t\tconfig: params.config,\n\t\t\tworkspaceDir,\n\t\t\tprovider: params.provider,\n\t\t\tmodelId,\n\t\t\tmodelDisplay,\n\t\t\tagentId: sessionAgentId,\n\t\t\tsystemPrompt: builtSystemPrompt\n\t\t}) ?? builtSystemPrompt : builtSystemPrompt;\n\t\t// BYOKit: Claude wire names for the Tooling list (ch-cli-tool-prefix). The Claude wire catalog\n\t\t// exposes OpenClaw tools as mcp__openclaw__<name>, so the printed Tooling list on that route must\n\t\t// use those exact names. Every other route keeps the stock prompt byte-identical; already-prefixed\n\t\t// names are never prefixed again. Order, summaries and error semantics are unchanged.\n\t\tif (!skipsTurnPreparation && isClaudeCli && promptTools.length > 0) {\n\t\t\tconst byokitBareNames = new Set(promptTools.map((tool) => tool?.name).filter((name) => typeof name === \"string\" && name.length > 0 && !name.startsWith(\"mcp__openclaw__\")));\n\t\t\tif (byokitBareNames.size > 0) {\n\t\t\t\tconst byokitLines = systemPrompt.split(\"\\n\");\n\t\t\t\tlet byokitInTooling = false;\n\t\t\t\tlet byokitToolingArmed = false;\n\t\t\t\tfor (let byokitI = 0; byokitI < byokitLines.length; byokitI++) {\n\t\t\t\t\tconst byokitLine = byokitLines[byokitI];\n\t\t\t\t\tif (byokitLine.startsWith(\"## \")) {\n\t\t\t\t\t\tbyokitInTooling = byokitLine === \"## Tooling\";\n\t\t\t\t\t\tbyokitToolingArmed = false;\n\t\t\t\t\t} else if (byokitInTooling && !byokitToolingArmed) {\n\t\t\t\t\t\tif (byokitLine === \"Tools policy-filtered. Names case-sensitive; call exact.\") byokitToolingArmed = true;\n\t\t\t\t\t} else if (byokitInTooling && byokitToolingArmed && byokitLine.startsWith(\"- \")) {\n\t\t\t\t\t\tconst byokitMatch = /^- (\\S+?)(:.*)?$/.exec(byokitLine);\n\t\t\t\t\t\tif (byokitMatch && byokitBareNames.has(byokitMatch[1])) byokitLines[byokitI] = `- mcp__openclaw__${byokitMatch[1]}${byokitMatch[2] ?? \"\"}`;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tsystemPrompt = byokitLines.join(\"\\n\");\n\t\t\t}\n\t\t}\n"
         }
       ]
+    },
+    {
+      "path": "dist/setup-inference-Dpvv_U7x.js",
+      "before": "e38ba4aa4a31376a03609b8732fcd69026df17149849d15caa6a8a59a865d6d7",
+      "after": "71f7103b5f88db7e3b98433a54b05a5a18557d6e83385d09cddaabe053254823",
+      "edits": [
+        {
+          "find": "\t\t\treturn {\n\t\t\t\trunner: \"embedded\",\n\t\t\t\t...ref,\n\t\t\t\tmodelRef,\n\t\t\t\tagentDir: params.agentDir,\n\t\t\t\tconfig: preparedAuth.config,",
+          "replace": "\t\t\t// BYOKit: plan the route the engine stages. A provider-normalized starter (OpenRouter keeps its bare `auto` as\n\t\t\t// `openrouter/auto`) is planned as the staged route names it, so a key activation matches its staged route.\n\t\t\tconst byokitModelRef = canonicalizeSetupModelRef({\n\t\t\t\tcfg: preparedAuth.config,\n\t\t\t\traw: modelRef,\n\t\t\t\tdefaultProvider: ref.provider\n\t\t\t});\n\t\t\treturn {\n\t\t\t\trunner: \"embedded\",\n\t\t\t\t...parseRef(byokitModelRef),\n\t\t\t\tmodelRef: byokitModelRef,\n\t\t\t\tagentDir: params.agentDir,\n\t\t\t\tconfig: preparedAuth.config,"
+        }
+      ]
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "The OpenClaw runtime kit: the pinned engine's full operator surface with plain-words helpers for members, sign-in, runs and approvals.",
   "license": "Apache-2.0",
   "type": "module",