@byokit/openclaw 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 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.
+- SECURITY: a helper key is entered only on this path, never through `delegates` or a key prefix. A target that is not a helper key, a helper on another member's or account's agent, a helper never ensured, or one the run was not given is refused before dispatch with a typed `HelperError` code in the parent's tool result; a helper whose account is removed or rebound since admission ends its children's admission at their next gate or call, its unspent permits included.
+- FIX: an OpenRouter API key with funds accepts and runs the model the person chooses (pay-as-you-go, no plan check). Before, `addKey` refused every `model` on the OpenRouter key route with `{ status: 'not_included', reason: 'model' }` (only the OpenCode Go route took a model) and `models()` listed nothing for it; now the key's own OpenRouter live catalog decides, `models()` lists it as `openrouter/<id>` (one prefix, and the engine's canonical id for a Google preview), and only the chosen model is registered with the engine.
+
 ## 0.20.0 (2026-10-19)
 
 - FEAT: `ensureHelper(member, helper, { account, persona })` gives a member several helpers, each with its own persona and its own sessions (`agent:<member>:h-<helper>:…`) on one account the member already signed in, the API-key lane included: runs go to the engine agent already holding that account, so no credential is copied and no sign-in starts. `run({ helper })` speaks as that helper with its persona as the system text; `RunRef.helper` names it on `ToolHost.gate` and `call`, and its approvals stay the member's.

package/README.md

@@ -174,11 +174,17 @@ for entry, checking, success and failure states, using the kit's `key.*` words.
 To use the saved key for one run, pass `auth: 'apiKey'`. The key lives in the member's separate
 `byokit-key-<member>` agent and workspace, with `copyToAgents: false` and only that key in its local auth order.
 List the route's models with `kit.models('ana', { authChoice: 'opencode-go' })` after a key is saved; this reads the
-live catalog. Before a key exists it returns `[]` and queries no agent. Only available key-lane
+live catalog. Before a key exists it returns `[]` (a failed catalog probe with no saved key for the provider is read as
+empty; with one it is an error) and runs no engine discovery. Only available key-lane
 models can be saved; the ordinary member's sign-ins never supply the list. Pass a full catalog id, e.g.
 `model: 'opencode-go/muse-spark-1.3-contributor'`, to `addKey` to save it as the lane's default after activation.
-Model listing and selection are Go-only: other key routes list no models, and a `model` on them returns `not_included`/`model`
-before activation.
+Model listing and selection belong to the live-catalog routes, OpenCode Go and OpenRouter. An OpenRouter key is
+pay-as-you-go with no plan, so it takes any model its own live catalog lists, named `openrouter/<id>`, e.g.
+`model: 'openrouter/deepseek/deepseek-v4.1-flash-1017'`; an id already beginning with its own provider keeps one
+prefix (`openrouter/auto`). A Google preview id is named and saved as the canonical id the engine keeps
+(`openrouter/google/gemini-3.1-flash-lite-preview` becomes `openrouter/google/gemini-3.1-flash-lite`); the add
+registers that one model with the engine. Other key routes list no models, and a `model` on them returns
+`not_included`/`model` before activation.
 An unknown model returns `{ status: 'not_included', reason: 'model' }` and clears the replacement.
 Before success, `addKey` waits for catalog registration and prepares the new key agent's full-catalog owner once.
 For a live-catalog provider, a chosen model must also be in the engine's registered `models.providers[provider].models`
@@ -403,7 +409,7 @@ Entries:
 
 | Export | What it does |
 | --- | --- |
-| `OpenClawKit` (`.`) | Prepares, starts, supervises and stops the engine. `call` / `callDynamic` pass through to the Gateway, `onEvent` listens. Helpers: `ensureMember`, `ensureHelper`, `routes`, `providers`, `signedIn`, `signIn`, `signOut`, `removeKey`, `migrateRetainedLogin`, `confirmRetainedLogin`, `toolNames`, `run`, `steer`, `abort`, `approvals`, `onApproval`, `decide`, `allowOnce`, `disallowOnce`, `patchConfig`, `getConfigKey`, `setConfigKey`, `memoryLimited`, `doctorContext` |
+| `OpenClawKit` (`.`) | Prepares, starts, supervises and stops the engine. `call` / `callDynamic` pass through to the Gateway, `onEvent` listens. Helpers: `ensureMember`, `ensureHelper`, `adoptHelperSession`, `routes`, `providers`, `signedIn`, `signIn`, `signOut`, `removeKey`, `migrateRetainedLogin`, `confirmRetainedLogin`, `toolNames`, `run`, `steer`, `abort`, `approvals`, `onApproval`, `decide`, `allowOnce`, `disallowOnce`, `patchConfig`, `getConfigKey`, `setConfigKey`, `memoryLimited`, `doctorContext` |
 | `ENGINE_VERSION`, `PROTOCOL_VERSION`, `OPERATOR_SCOPES` (`.`) | The pinned engine version, its protocol and the operator scopes the kit connects with |
 | `KitOptions`, `RunSpec`, `RunEvent`, `RunEnd`, `RunUsage`, `PlanWindow`, `Route`, `Approval`, `Decision`, `ToolSpec`, `ToolHost`, `KitState`, ... (`.`) | Public types (docs/runtime-kits.md §5.2) |
 | `GatewayMethods`, `GatewayMethod`, `GatewayParams`, `GatewayResult`, `GatewayEventName`, `GatewayEventPayload` (`.`) | The generated pass-through tables, so an app can write its own generic wrapper over `call` / `onEvent` once |
@@ -478,6 +484,29 @@ was removed: never moved to another sign-in) and `session` (a key outside the he
 or `move` of one). Helpers share their account's engine agent (its id and workspace files); a helper gains no tool,
 builtin or key prefix the member's run would not. See [Helpers](../../docs/runtime-kits.md#583-helpers).
 
+A run hands work to the member's helpers with `helperDelegates: { writer: ['report'] }` (on the native delegated path
+above, builtin gating on): the engine's own `sessions_send` to the exact key `agent:<writer's agent>:h-writer:<rest>`
+(`timeoutSeconds: 0`) is admitted from its receipt as writer's run, `RunRef.helper: 'writer'` on every gate and call.
+A target that is not a helper key, a helper on another account, one never ensured, or one the run was not given is
+refused before dispatch; the parent's tool result reads `session: …`, `bound: …` or `unknown_helper: …`.
+`abort(rootSessionKey)` revokes the children, and a helper whose account is removed loses them at their next call. The
+child runs without the helper's persona (a native send carries no system text).
+
+Conversations from before helpers (plain member sessions) move into a helper with
+`kit.adoptHelperSession({ member, sessionKey }, helper)`: the whole transcript forks to
+`agent:<member>:h-<helper>:<tail>` on the helper's account agent, the old session goes, and nothing is sent to the
+model. The result is `move`'s `MoveResult` with `session` set to the helper key to run on. A conversation still in
+flight (a live run, a parked approval or an admitted delegated child under it) is refused `busy` and keeps its exact
+old key and approval owner until it settles, so adopt again later; a target key already taken is refused and leaves
+both. A helper key, another member's key or a helper never ensured is a typed `HelperError` (`session`,
+`unknown_helper`).
+
+`kit.onEvent('byokit.delegated', fn)` follows each helper child start to finish: `admitted` (with `run.helper` and
+`run.tools`, its app-tool subset), the engine's events, then one `ended` whose `reason` is `terminal`, `cancelled` (an
+abort, or its admission ended), `error` (with `message`) or `resting`: the model's usage limit ended it, and the kit
+rests the helper's account `until` the stated reset, as a kit run's resting end does. An approval raised by a helper's
+run names it in `Approval.helper`.
+
 ## Owned browser (unqualified handoff)
 
 `browser: { executablePath, members }` opts into isolated member Chromium profiles. It requires a closed

package/dist/accounts.d.ts

@@ -1,6 +1,8 @@
 import { createLocks } from './locks.ts';
 import { type RouteView } from './routes.ts';
 import type { Account, AccountId, AccountPick, Defaults, GatewayTransport, Member, ModelInfo, MoveResult, Room, RunSelection, SignInOptions, SignInView } from './types.ts';
+export declare const kitId: (provider: string, id: string) => string;
+export declare const engineId: (provider: string, model: string, rows: readonly unknown[] | undefined) => string;
 export declare const modelsOf: (provider: string, answer: unknown) => ModelInfo[];
 export declare const modelsOfAccount: (row: Pick<Account, 'provider' | 'state'>, answer: unknown) => ModelInfo[];
 type IndexEntry = {
@@ -89,7 +91,7 @@ export declare function createAccounts(ctx: {
         agent?: string;
     }>;
     rest(member: Member, id: AccountId, until: number): Promise<void>;
-    move(member: Member, sessionKey: string, to: AccountId): Promise<MoveResult>;
+    move(member: Member, sessionKey: string, to: AccountId, intoTail?: string): Promise<MoveResult>;
     remove(member: Member, id: AccountId): Promise<void>;
 };
 export {};

package/dist/accounts.js

@@ -16,6 +16,21 @@ import { KEY_PREFIX, MEMBER_ID, NEW_MEMBER_ID, keyAgentId, untilListed, untilUnl
 import { routes, routeFor } from './routes.js';
 import { words } from './words.js';
 const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+// A provider-local engine model id as the kit's `provider/model` reference; an id already prefixed with its own
+// provider is left alone.
+export const kitId = (provider, id) => providerOf(id) === provider.toLowerCase() ? id : `${provider}/${id}`;
+// The engine's provider-local id for a kit `provider/model` reference, resolved against that provider's rows.
+export const engineId = (provider, model, rows) => {
+    for (const row of rows ?? []) {
+        if (!record(row) || typeof row.id !== 'string')
+            continue;
+        if (row.provider !== undefined && String(row.provider).toLowerCase() !== provider.toLowerCase())
+            continue;
+        if (kitId(provider, row.id) === model)
+            return row.id;
+    }
+    return model.slice(model.indexOf('/') + 1);
+};
 // `models.list { agentId, view: 'all' }` rows of the account's provider, mapped to `provider/model`. The pin
 // reports no per-plan availability, so `why: 'plan'` only comes from a run ending `plan`, never from here.
 export const modelsOf = (provider, answer) => {
@@ -27,7 +42,7 @@ export const modelsOf = (provider, answer) => {
             continue;
         if (typeof candidate.id !== 'string' || !candidate.id || typeof candidate.name !== 'string')
             continue;
-        const id = candidate.id.includes('/') ? candidate.id : `${candidate.provider}/${candidate.id}`;
+        const id = kitId(candidate.provider, candidate.id);
         if (providerOf(id) !== provider.toLowerCase())
             continue;
         const available = candidate.available === undefined
@@ -792,8 +807,9 @@ export function createAccounts(ctx) {
     // before any lock. Same agent: nothing moves, the next run names the account. Otherwise, under both agents' locks and
     // on the row read again there, the source's whole transcript forks into `agent:<target>:<tail>` (never `chat.history`
     // plus `chat.inject`, which drop tool rows), then the source is deleted only if it is still the session read. A
-    // refused fork leaves the source untouched; a refused delete leaves both, the new key live.
-    async function move(member, sessionKey, to) {
+    // refused fork leaves the source untouched; a refused delete leaves both, the new key live. `intoTail` (a helper's
+    // adoption, 5.8.3) forks it under another tail on the target, the same agent included.
+    async function move(member, sessionKey, to, intoTail) {
         check(member);
         const failed = (code, message, live) => ({ ok: false, code, message, ...(live === undefined ? {} : { live }) });
         const { agentId: memberAgent } = await ctx.ensure(member);
@@ -801,7 +817,7 @@ export function createAccounts(ctx) {
         const { row, entry } = await entryOf(member, to);
         const tail = sessionKey.slice(sessionKey.indexOf(':', 'agent:'.length) + 1);
         const from = `agent:${source}:${tail}`;
-        const into = `agent:${entry.agent}:${tail}`;
+        const into = `agent:${entry.agent}:${intoTail ?? tail}`;
         const read = async () => {
             const listed = await ctx.request('sessions.list', { agentId: source, search: from });
             const found = (Array.isArray(listed.sessions) ? listed.sessions : [])
@@ -816,7 +832,7 @@ export function createAccounts(ctx) {
             return first.refused;
         if (row.state !== 'ready')
             return failed('start_failed', words('move.notReady', { name: row.name }));
-        if (entry.agent === source)
+        if (into === from)
             return { ok: true, session: into };
         return ctx.locks.exclusive([source, entry.agent], async () => {
             const again = await read();
@@ -829,13 +845,18 @@ export function createAccounts(ctx) {
                 return failed('start_failed', words('move.taken', { name: row.name }));
             // The session's model when the target lists it, else the target's first available; the read takes no shared
             // hold (this move holds the target exclusively). With no answer the fork keeps the parent's own selection.
-            const models = await ctx.request('models.list', { agentId: entry.agent, view: 'all' })
-                .then((answer) => modelsOfAccount(row, answer), () => []);
+            const answer = await ctx.request('models.list', { agentId: entry.agent, view: 'all' }).catch(() => undefined);
+            const models = answer === undefined ? [] : modelsOfAccount(row, answer);
+            const sessionProvider = typeof session.modelProvider === 'string' ? session.modelProvider.toLowerCase() : undefined;
             const current = typeof session.model !== 'string' ? undefined
-                : (typeof session.modelProvider === 'string' && !session.model.includes('/') ? `${session.modelProvider}/${session.model}` : session.model).toLowerCase();
+                : (sessionProvider === undefined ? session.model : kitId(sessionProvider, session.model)).toLowerCase();
             const model = models.find((m) => m.id.toLowerCase() === current)?.id ?? models.find((m) => m.available)?.id;
+            const rows = record(answer) && Array.isArray(answer.models) ? answer.models : [];
+            const local = model === undefined ? undefined : engineId(row.provider, model, rows);
+            const ref = model === undefined || local === undefined ? undefined
+                : providerOf(model) === row.provider ? `${row.provider}/${local}` : model;
             try {
-                await ctx.request('sessions.create', { agentId: entry.agent, key: into, parentSessionKey: from, fork: true, ...(model ? { model } : {}) });
+                await ctx.request('sessions.create', { agentId: entry.agent, key: into, parentSessionKey: from, fork: true, ...(ref ? { model: ref } : {}) });
             }
             catch (error) {
                 return failed('start_failed', (error instanceof Error ? error.message : String(error)).slice(0, 200));

package/dist/approvals.js

@@ -1,5 +1,6 @@
 // Native approvals: exec.approval.*, plugin.approval.* and question.* surfaced through the same Approval shape (5.9, O5).
 import { randomBytes } from 'node:crypto';
+import { helperOf } from './helpers.js';
 import { MEMBER_ID } from './members.js';
 const strip = (a) => {
     const { native, ...approval } = a;
@@ -27,7 +28,8 @@ function attribute(payload, memberOf) {
     const fromAgent = agent ? memberOf(agent) : undefined;
     const fromKey = key ? memberOf(key) : undefined;
     const member = fromAgent ?? fromKey ?? asString(detail.member) ?? '';
-    return { member, ...(key ? { sessionKey: key } : {}) };
+    const helper = key ? helperOf(key) : undefined; // a helper's run asks as the member, owned by that helper (5.8.3)
+    return { member, ...(key ? { sessionKey: key } : {}), ...(helper ? { helper } : {}) };
 }
 /** Exec policy modes (`off|on-miss|always`) ride in `request.ask`; they are not something a person said (B8). */
 const POLICY_MODES = new Set(['off', 'on-miss', 'always']);
@@ -71,7 +73,7 @@ export class Approvals {
             const id = asString(payload.id) ?? randomBytes(12).toString('base64url');
             if (this.approvals.has(id))
                 return;
-            const { member, sessionKey } = attribute(payload, this.memberOf);
+            const { member, sessionKey, helper } = attribute(payload, this.memberOf);
             const detail = isRecord(payload.request) ? payload.request : payload;
             const now = Date.now();
             const approval = {
@@ -79,6 +81,7 @@ export class Approvals {
                 source,
                 member,
                 ...(sessionKey ? { sessionKey } : {}),
+                ...(helper ? { helper } : {}),
                 ...(asString(detail.tool) ?? asString(detail.toolName) ? { tool: (asString(detail.tool) ?? asString(detail.toolName)) } : {}),
                 summary: summaryOf(source, payload),
                 ...('questions' in detail ? { input: detail.questions } : {}),

package/dist/bridge.js

@@ -5,6 +5,7 @@ import { createServer } from 'node:net';
 import { rm } from 'node:fs/promises';
 import { provider } from '@byokit/accounts';
 import { words } from './words.js';
+import { HelperError } from './helpers.js';
 /** Newline-framed JSON, one request per connection; anything larger is not a gate request. */
 const FRAME_CAP = 1_000_000;
 /**
@@ -334,7 +335,8 @@ export class Bridge {
                     this.deny(socket, 'invalid delegation message');
             }
             catch (error) {
-                this.deny(socket, error instanceof Error ? error.message : 'delegation unavailable');
+                // A typed helper refusal (5.8.3) reaches the parent's tool result with its code.
+                this.deny(socket, error instanceof HelperError ? `${error.code}: ${error.message}` : error instanceof Error ? error.message : 'delegation unavailable');
             }
             return;
         }
@@ -392,6 +394,7 @@ export class Bridge {
                 source: 'gate',
                 member: run.member,
                 sessionKey: run.sessionKey,
+                ...(run.helper !== undefined ? { helper: run.helper } : {}),
                 tool,
                 summary: result.ask.summary,
                 input,
@@ -441,6 +444,10 @@ export class Bridge {
             return this.reply(socket, { ok: false, reason: 'this call was not allowed' });
         const runId = typeof message.runId === 'string' ? message.runId : undefined;
         this.owners.set(socket, { key, runId });
+        // Resolved before the permit is spent: a delegated run whose admission ended (its helper removed) loses its permits.
+        const delegated = await this.delegations?.resolve(key, runId);
+        if (this.stopped || socket.destroyed)
+            return;
         const wanted = JSON.stringify(input);
         const permit = message.permit;
         if (typeof permit === 'string') {
@@ -462,9 +469,6 @@ export class Bridge {
         }
         if (!this.host)
             return this.reply(socket, { ok: false, reason: "can't run this action right now" });
-        const delegated = await this.delegations?.resolve(key, runId);
-        if (this.stopped || socket.destroyed)
-            return;
         const run = delegated?.ref ?? this.runs.get(key) ?? { sessionKey: key, member: this.memberOf(key) ?? '' };
         // The plugin destroys its socket when the run aborts (run abort, hook timeout); without this the host's
         // sandboxed command keeps running after the tool is gone.

package/dist/constants.d.ts

@@ -1,4 +1,5 @@
 export declare const ENGINE_VERSION = "2026.8.35";
 export declare const PROTOCOL_VERSION = 4;
 export declare const LIVE_CATALOGS: string[];
+export declare const REGISTERED_CATALOGS: string[];
 export declare const OPERATOR_SCOPES: readonly ['operator.read', 'operator.write', 'operator.admin', 'operator.approvals', 'operator.questions', 'operator.pairing', 'operator.talk'];

package/dist/constants.js

@@ -2,8 +2,12 @@
 // `needs-update`, never silently run.
 export const ENGINE_VERSION = '2026.8.35';
 export const PROTOCOL_VERSION = 4;
-// Providers whose live catalog the kit registers (5.6); key choice uses the same catalog hook.
-export const LIVE_CATALOGS = ['opencode-go'];
+// Providers whose live catalog lists and checks a key's chosen model (5.6), through the catalog hook. OpenRouter is
+// pay-as-you-go: its key takes any model its own catalog lists, with no plan to include it.
+export const LIVE_CATALOGS = ['opencode-go', 'openrouter'];
+// Live catalogs the kit registers whole. The engine canonicalizes Google preview ids on config write, so OpenRouter's
+// list collides with itself (`google/x-preview` and `google/x`); an OpenRouter add registers only the chosen model.
+export const REGISTERED_CATALOGS = ['opencode-go'];
 export const OPERATOR_SCOPES = [
     'operator.read',
     'operator.write',

package/dist/delegations.d.ts

@@ -3,6 +3,7 @@ type Grant = {
     ref: DelegatedRun;
     tools: string[];
     delegates: Record<string, string[]>;
+    helpers?: Record<string, string[]>;
     sourceKey: string;
 };
 export declare class Delegations {
@@ -16,6 +17,11 @@ export declare class Delegations {
         file: string;
         tools: ReadonlySet<string>;
         memberOf(agent: string): string | undefined;
+        helper(member: string, helper: string): {
+            agentId: string;
+            account: string;
+        };
+        rest(member: string, account: string, until: number): Promise<void>;
         request: GatewayTransport['request'];
         emit(e: DelegatedEvent): void;
         revoke(key: string, runId: string): void;
@@ -23,14 +29,16 @@ export declare class Delegations {
     private readonly o;
     private load;
     private save;
-    validate(delegates: Record<string, string[]>): void;
-    register(ref: RunRef, runId: string, tools: readonly string[] | undefined, delegates: Record<string, string[]>, sourceKey?: string): () => void;
+    validate(delegates: Record<string, string[]>, member?: string, helpers?: Record<string, string[]>): void;
+    register(ref: RunRef, runId: string, tools: readonly string[] | undefined, delegates: Record<string, string[]>, sourceKey?: string, helpers?: Record<string, string[]>): () => void;
     list(): DelegatedRun[];
     has(key: string, runId: string): boolean;
     prepare(m: Record<string, any>): boolean;
     receipt(m: Record<string, any>): void;
     resolve(key: string, runId?: string): Promise<Grant | undefined>;
+    private bound;
     event(event: Record<string, any>): void;
+    private ended;
     private end;
     reconcile(): Promise<void>;
     abort(key: string): Promise<void>;

package/dist/delegations.js

@@ -1,6 +1,10 @@
 // Native receipts, never session-prefix authority. Persist identity/tool policy only, not prompts or credentials.
 import { existsSync, readFileSync } from 'node:fs';
 import { atomic } from './engine-patches.js';
+import { classify } from './classify.js';
+import { HELPER_ID, HelperError, helperOf } from './helpers.js';
+// A resting end whose message names no time rests the account this long, as a kit run's does (runs.ts).
+const REST_MS = 300_000;
 const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const agentOf = (key) => /^agent:([^:]+):.+/.exec(key)?.[1];
 const actionKey = (m) => JSON.stringify([m.key, m.runId, m.callId]);
@@ -34,7 +38,7 @@ export class Delegations {
         for (const notify of this.changed)
             notify();
     }
-    validate(delegates) {
+    validate(delegates, member, helpers) {
         if (!object(delegates) || Object.keys(delegates).length > 64)
             throw new Error('invalid delegates');
         for (const [agent, tools] of Object.entries(delegates)) {
@@ -42,12 +46,21 @@ export class Delegations {
                 || tools.some(t => !this.o.tools.has(t)))
                 throw new Error(`invalid delegate: ${agent}`);
         }
+        if (helpers === undefined)
+            return;
+        if (!object(helpers) || Object.keys(helpers).length > 64)
+            throw new HelperError('invalid', 'invalid helper delegates');
+        for (const [helper, tools] of Object.entries(helpers)) {
+            if (!HELPER_ID.test(helper) || !Array.isArray(tools) || tools.some(t => !this.o.tools.has(t)))
+                throw new HelperError('invalid', `invalid helper delegate: ${helper}`);
+            this.o.helper(member, helper); // never ensured, or its account gone: unknown_helper
+        }
     }
-    register(ref, runId, tools, delegates, sourceKey = ref.sessionKey) {
+    register(ref, runId, tools, delegates, sourceKey = ref.sessionKey, helpers) {
         this.load();
-        this.validate(delegates);
+        this.validate(delegates, ref.member, helpers);
         const root = { ref: { ...ref, runId, root: { sessionKey: ref.sessionKey, runId } },
-            tools: [...tools ?? this.o.tools], delegates: structuredClone(delegates), sourceKey };
+            tools: [...tools ?? this.o.tools], delegates: structuredClone(delegates), ...(helpers ? { helpers: structuredClone(helpers) } : {}), sourceKey };
         this.roots.set(runId, root);
         return () => { if (this.roots.get(runId) === root)
             this.roots.delete(runId); };
@@ -68,17 +81,30 @@ export class Delegations {
         if (!send && m.tool !== 'sessions_spawn')
             throw new Error('unsupported delegation tool');
         const agent = send ? typeof m.input.sessionKey === 'string' && agentOf(m.input.sessionKey) : m.input.agentId;
-        if (typeof agent !== 'string' || !Object.hasOwn(parent.delegates, agent)
-            || (send && (m.input.timeoutSeconds !== 0 || m.input.label !== undefined))
+        // A helper's session is entered only on the helper path, so a run naming the helper always speaks there (5.8.3).
+        const helper = send && typeof agent === 'string' ? helperOf(m.input.sessionKey) : undefined;
+        if ((send && (m.input.timeoutSeconds !== 0 || m.input.label !== undefined))
             || (!send && m.input.runtime !== undefined && m.input.runtime !== 'subagent'))
             throw new Error('delegation target or mode refused');
+        if (helper !== undefined) {
+            const bound = this.o.helper(parent.ref.member, helper).agentId; // never ensured: unknown_helper
+            if (bound !== agent)
+                throw new HelperError('bound', `refused: helper ${helper} runs on another account`);
+            if (!Object.hasOwn(parent.helpers ?? {}, helper))
+                throw new HelperError('session', `refused: this run may not hand work to helper ${helper}`);
+        }
+        else if (typeof agent !== 'string' || !Object.hasOwn(parent.delegates, agent)) {
+            if (Object.keys(parent.helpers ?? {}).length)
+                throw new HelperError('session', `refused: "${String(m.input.sessionKey ?? agent)}" is not a helper session`);
+            throw new Error('delegation target or mode refused');
+        }
         for (const [id, p] of this.pending)
             if (p.expires < Date.now())
                 this.pending.delete(id);
         if (this.pending.size + this.children.size >= 1024)
             throw new Error('delegated run journal is full');
-        this.pending.set(actionKey(m), { parent: structuredClone(parent), agent,
-            ...(send ? { key: m.input.sessionKey } : {}), expires: Date.now() + 60_000 });
+        this.pending.set(actionKey(m), { parent: structuredClone(parent), agent: agent,
+            ...(send ? { key: m.input.sessionKey } : {}), ...(helper !== undefined ? { helper } : {}), expires: Date.now() + 60_000 });
         this.save();
         return true;
     }
@@ -96,15 +122,20 @@ export class Delegations {
             this.save();
             return;
         }
-        const member = this.o.memberOf(p.agent);
+        // A helper child is the parent member's, attributed to that helper (RunRef.helper), on the helper's own agent.
+        const member = p.helper !== undefined ? (this.bound(p.parent.ref.member, p.helper, p.agent) ? p.parent.ref.member : undefined)
+            : this.o.memberOf(p.agent);
         if (!member) {
             this.save();
             return;
         }
-        const ref = { sessionKey: key, member, runId: d.runId, agentId: p.agent,
-            parent: { sessionKey: p.parent.ref.sessionKey, runId: p.parent.ref.runId }, root: p.parent.ref.root };
-        const grant = { ref, delegates: p.parent.delegates, sourceKey: p.parent.sourceKey,
-            tools: p.parent.tools.filter(t => p.parent.delegates[p.agent].includes(t)) };
+        const allowed = p.helper !== undefined ? p.parent.helpers[p.helper] : p.parent.delegates[p.agent];
+        const tools = p.parent.tools.filter(t => allowed.includes(t));
+        const ref = { sessionKey: key, member, ...(p.helper !== undefined ? { helper: p.helper } : {}), runId: d.runId, agentId: p.agent,
+            parent: { sessionKey: p.parent.ref.sessionKey, runId: p.parent.ref.runId }, root: p.parent.ref.root, tools };
+        const grant = { ref, delegates: p.parent.delegates,
+            ...(p.parent.helpers && ref.member === p.parent.ref.member ? { helpers: p.parent.helpers } : {}),
+            sourceKey: p.parent.sourceKey, tools };
         // A steered/already-admitted run keeps its original parent and cannot acquire a broader grant.
         if (this.children.has(ref.runId)) {
             this.save();
@@ -132,7 +163,21 @@ export class Delegations {
                 check();
             });
         }
-        return get();
+        const grant = get();
+        // A helper removed or rebound since admission ends its runs' admission (5.8.3: never moved to another sign-in).
+        if (grant?.ref.helper !== undefined && !this.bound(grant.ref.member, grant.ref.helper, grant.ref.agentId)) {
+            this.end(grant, { reason: 'cancelled' });
+            return undefined;
+        }
+        return grant;
+    }
+    bound(member, helper, agent) {
+        try {
+            return this.o.helper(member, helper).agentId === agent;
+        }
+        catch {
+            return false;
+        }
     }
     event(event) {
         this.load();
@@ -150,20 +195,40 @@ export class Delegations {
             return;
         this.o.emit({ type: 'event', run: structuredClone(grant.ref), event: { stream: event.stream, data: event.data } });
         if (event.stream === 'lifecycle' && ['end', 'error'].includes(event.data?.phase))
-            this.end(grant);
+            void this.ended(grant, event.data);
+    }
+    // The engine's lifecycle end, mapped: an abort is `cancelled`; an error is `error`, or `resting` when the model's limit
+    // ended a helper's run, which rests the helper's account as a kit run's resting end does (5.15 Runs step 7).
+    async ended(grant, data) {
+        if (data.aborted === true)
+            return this.end(grant, { reason: 'cancelled' });
+        if (data.phase !== 'error')
+            return this.end(grant, { reason: 'terminal' });
+        const message = typeof data.error === 'string' ? data.error : '';
+        const failed = classify(message);
+        const { member, helper } = grant.ref;
+        if (failed.kind !== 'resting' || helper === undefined)
+            return this.end(grant, { reason: 'error', message });
+        this.children.delete(grant.ref.runId); // ended now: a later gate or event finds no admission
+        const until = failed.until ?? Date.now() + REST_MS;
+        try {
+            await this.o.rest(member, this.o.helper(member, helper).account, until);
+        }
+        catch { /* its account is gone: the run still ended resting */ }
+        this.end(grant, { reason: 'resting', until, message });
     }
-    end(grant) {
+    end(grant, end) {
         this.children.delete(grant.ref.runId);
         this.save();
         this.o.revoke(grant.ref.sessionKey, grant.ref.runId);
-        this.o.emit({ type: 'ended', run: structuredClone(grant.ref), reason: 'terminal' });
+        this.o.emit({ type: 'ended', run: structuredClone(grant.ref), ...end });
     }
     async reconcile() {
         for (const ref of this.list()) {
             const end = await this.o.request('agent.wait', { runId: ref.runId, timeoutMs: 1 });
             const grant = this.children.get(ref.runId);
             if (grant && ['ok', 'error'].includes(end.status ?? ''))
-                this.end(grant);
+                this.end(grant, { reason: end.status === 'ok' ? 'terminal' : 'error' });
         }
     }
     async abort(key) {

package/dist/helpers.d.ts

@@ -3,6 +3,8 @@ import type { Account, AccountId, Helper, Member } from './types.ts';
 export declare const HELPER_ID: RegExp;
 /** A session key tail of some helper: only a run naming that helper speaks there. */
 export declare const HELPER_TAIL: RegExp;
+/** The helper an engine key `agent:<agent>:h-<helper>:<rest>` belongs to, from its tail; undefined for any other key. */
+export declare const helperOf: (key: string) => string | undefined;
 export type HelperErrorCode = 'invalid' | 'unknown_account' | 'bound' | 'unknown_helper' | 'session';
 /** A refused helper request, before any run: `code` says which rule refused it. */
 export declare class HelperError extends Error {
@@ -18,6 +20,7 @@ export declare function createHelpers(ctx: {
         persona: string;
     }): Promise<Helper>;
     resolve(member: Member, helper: string): {
+        account: AccountId;
         agentId: string;
         binding: Binding;
         persona: string;

package/dist/helpers.js

@@ -9,6 +9,8 @@ import { KEY_PREFIX, MEMBER_ID } from './members.js';
 export const HELPER_ID = /^[a-z][a-z0-9-]{0,15}$/;
 /** A session key tail of some helper: only a run naming that helper speaks there. */
 export const HELPER_TAIL = /^h-[a-z][a-z0-9-]{0,15}:/;
+/** The helper an engine key `agent:<agent>:h-<helper>:<rest>` belongs to, from its tail; undefined for any other key. */
+export const helperOf = (key) => /^agent:[^:]+:h-([a-z][a-z0-9-]{0,15}):/.exec(key)?.[1];
 const PERSONA_MAX = 8192;
 /** A refused helper request, before any run: `code` says which rule refused it. */
 export class HelperError extends Error {
@@ -63,7 +65,7 @@ export function createHelpers(ctx) {
             const entry = saved && loadIndex(ctx.root, member).file.accounts[saved.account];
             if (!saved || entry?.agent !== saved.agent)
                 throw new HelperError('unknown_helper', `unknown helper: ${String(helper)}`);
-            return { agentId: saved.agent, persona: saved.persona,
+            return { account: saved.account, agentId: saved.agent, persona: saved.persona,
                 binding: saved.agent === member ? { agentId: member } : { agentId: saved.agent, id: saved.account } };
         },
     };

package/dist/keys.d.ts

@@ -37,9 +37,11 @@ export declare function createKeys(ctx: ActivationCtx & {
     indexLane(member: Member, route: RouteView): Promise<void>;
     dropLane(member: Member, provider?: string): Promise<void>;
     backfillLane(member: Member, model: string | undefined): Promise<void>;
-    /** The provider config headers a live-catalog key's calls and probes must carry (`null` clears them),
+    /** The provider config headers a Go key's calls and probes must carry (`null` clears them),
      *  written through the kit's own config patch. The Go workspace header is the one user. */
     setProviderHeaders(provider: string, headers: Record<string, string> | null): Promise<void>;
+    /** Adds catalog rows to the engine's `models.providers[provider].models`, serialized with catalog sync. */
+    registerModels(provider: string, rows: Record<string, unknown>[]): Promise<void>;
 }): {
     models: (member: Member, o: {
         authChoice: string;

package/dist/keys.js

@@ -4,8 +4,8 @@ import { openCodeWorkspaces } from '@byokit/accounts/opencode-go';
 import { activate } from './activation.js';
 import { keyAgentId, MEMBER_ID, KEY_PREFIX, untilListed } from './members.js';
 import { providerOf } from './pick.js';
-import { modelsOf } from './accounts.js';
-import { LIVE_CATALOGS } from './constants.js';
+import { kitId, modelsOf } from './accounts.js';
+import { LIVE_CATALOGS, REGISTERED_CATALOGS } from './constants.js';
 export function createKeys(ctx) {
     // Serialize key replacement and key runs, so an in-flight run never sees a half-installed replacement.
     const tails = new Map();
@@ -47,7 +47,7 @@ export function createKeys(ctx) {
     };
     const registered = async (provider, model) => {
         const { config } = await ctx.request('config.get');
-        return Boolean(config?.models?.providers?.[provider]?.models?.some((m) => `${provider}/${m.id}` === model));
+        return Boolean(config?.models?.providers?.[provider]?.models?.some((m) => kitId(provider, m.id) === model));
     };
     const errorReason = (error, sent) => {
         if (transient(error))
@@ -58,19 +58,46 @@ export function createKeys(ctx) {
         return ['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'ETIMEDOUT', 'CLIENT_TIMEOUT', 'NETWORK_ERROR'].includes(e?.code ?? '')
             || e?.name === 'TimeoutError' ? 'network' : 'engine';
     };
+    // The engine writes a Google preview id without its `-preview` suffix, so the kit names the id it keeps.
+    const canonical = (id) => id.startsWith('google/') && id.endsWith('-preview')
+        ? id.slice(0, -'-preview'.length) : id;
+    const canonicalModel = (model) => {
+        const at = model.indexOf('/');
+        return at < 0 ? model : `${model.slice(0, at)}/${canonical(model.slice(at + 1))}`;
+    };
+    // The live catalog's rows, as the engine registers them (provider-local ids, deduped by the id it keeps).
+    const catalog = async (member, provider) => {
+        await ctx.ensure(member);
+        const answer = await ctx.request('byokit.catalog', { provider });
+        if (!answer.ok) {
+            if (answer.reason !== 'no-key')
+                throw new Error('Model catalog is unavailable.');
+            return [];
+        }
+        const rows = (answer.models ?? []).map((m) => ({ ...m, id: canonical(String(m.id)) }));
+        return [...new Map(rows.map((m) => [String(m.id), m])).values()];
+    };
+    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))
             return [];
-        await ctx.ensure(member);
-        const catalog = await ctx.request('byokit.catalog', { provider: route.provider });
-        if (catalog.ok)
-            return modelsOf(route.provider, { models: catalog.models?.map((m) => ({ ...m, provider: route.provider })) });
-        if (catalog.reason !== 'no-key')
-            throw new Error('Model catalog is unavailable.');
-        return [];
+        try {
+            return listed(route.provider, await catalog(member, route.provider));
+        }
+        catch (error) {
+            // The engine answers `failed` when no agent holds a key: a lane without the provider's profile lists nothing,
+            // a saved one is a real failure.
+            const held = await ctx.request('models.authStatus', { agentId: keyAgentId(member) }).then((answer) => {
+                const rows = answer.providers ?? [];
+                return rows.some((row) => (typeof row === 'string' ? row : row?.provider) === route.provider);
+            }, () => undefined);
+            if (held !== false)
+                throw error;
+            return [];
+        }
     };
     return {
         models,
@@ -87,13 +114,14 @@ export function createKeys(ctx) {
                 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)))
                     return failure('not_included', 'model');
-                // A workspace names a live-catalog login's own workspace only; another route takes no header, and a
+                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
                 // refusal here leaves the member's lanes untouched (it lands before any prepare or activation).
                 let orgId = typeof o.orgId === 'string' ? o.orgId.trim() : '';
                 if (orgId) {
                     if (orgId.length > 256)
                         return failure('invalid', 'auth');
-                    if (!LIVE_CATALOGS.includes(route.provider))
+                    if (route.provider !== 'opencode-go')
                         return failure('not_included', 'model');
                 }
                 else if (route.provider === 'opencode-go') {
@@ -157,7 +185,7 @@ export function createKeys(ctx) {
                             await ctx.setProviderHeaders(route.provider, { 'x-opencode-org-id': orgId });
                             wroteHeader = true;
                         }
-                        else if (LIVE_CATALOGS.includes(route.provider)) {
+                        else if (route.provider === 'opencode-go') {
                             await ctx.setProviderHeaders(route.provider, null);
                             wroteHeader = true;
                         }
@@ -172,7 +200,8 @@ export function createKeys(ctx) {
                             return abandon(probeResult(result.status));
                         if (result.late)
                             return abandon(failure('retry', 'busy'));
-                        if (o.model !== undefined && !(await models(member, o)).some((m) => m.id === o.model && m.available))
+                        const rows = model === undefined ? [] : await catalog(member, route.provider);
+                        if (model !== undefined && !listed(route.provider, rows).some((m) => m.id === model && m.available))
                             return abandon(failure('not_included', 'model'));
                         // Prepare before publishing the ready marker: failed preparation remains unusable even if clear fails.
                         try {
@@ -183,9 +212,12 @@ export function createKeys(ctx) {
                         }
                         if (ac.signal.aborted)
                             return abandon(cancelled());
-                        if (o.model !== undefined && LIVE_CATALOGS.includes(route.provider) && !(await registered(route.provider, o.model)))
+                        // A live catalog the kit does not register whole (OpenRouter) registers the chosen model alone.
+                        if (model !== undefined && !REGISTERED_CATALOGS.includes(route.provider))
+                            await ctx.registerModels(route.provider, rows.filter((m) => kitId(route.provider, String(m.id)) === model)).catch(() => { });
+                        if (model !== undefined && LIVE_CATALOGS.includes(route.provider) && !(await registered(route.provider, model)))
                             return abandon(failure('retry', 'model'));
-                        if (!(await control(member, 'seal', undefined, o.model)).ok)
+                        if (!(await control(member, 'seal', undefined, model)).ok)
                             return abandon(failure('retry', 'engine'));
                         await ctx.indexLane(member, route);
                         return { status: 'ok' };
@@ -241,7 +273,7 @@ export function createKeys(ctx) {
                 if (cleared?.ok !== true && cleared?.absent !== true)
                     refused();
                 // A workspace header the removed key named must not outlive it; the next add names its own (or none).
-                if (o.provider !== undefined && LIVE_CATALOGS.includes(o.provider))
+                if (o.provider === 'opencode-go')
                     await ctx.setProviderHeaders(o.provider, null).catch(() => { throw new Error('The key could not be removed.'); });
                 await ctx.dropLane(member, o.provider);
             });

package/dist/kit.d.ts

@@ -135,6 +135,11 @@ export declare class OpenClawKit {
         account: AccountId;
         persona: string;
     }): Promise<Helper>;
+    /** Adopt a legacy conversation of the member into one of its helpers (5.8.3, S4): its whole transcript forks to
+     * `agent:<member>:h-<helper>:<tail>` on the helper's account agent (as `move` does), then the old session goes.
+     * One still in flight (a live run, a parked approval or an admitted delegated child under it) is refused `busy`
+     * and keeps its exact old key until it settles; nothing is replayed and no approval changes owner. */
+    adoptHelperSession(ref: RunRef, helper: string): Promise<MoveResult>;
     private signInCtx;
     routes(): RouteView[];
     /** Start Composio's hosted MCP OAuth flow through the pinned engine; return the URL for the app to open. */
@@ -214,6 +219,7 @@ export declare class OpenClawKit {
     private backfillKeyLane;
     private prepareKeyOwner;
     private syncCatalogs;
+    private registerModels;
     migrateRetainedLogin(member: Member, source: RetainedLogin): Promise<'staged' | 'nothing' | 'failed'>;
     confirmRetainedLogin(member: Member, source: RetainedLogin): Promise<boolean>;
     private runs;

package/dist/kit.js

@@ -5,7 +5,7 @@ import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { isDeepStrictEqual } from 'node:util';
 import { fileURLToPath } from 'node:url';
-import { PROTOCOL_VERSION, LIVE_CATALOGS } from './constants.js';
+import { PROTOCOL_VERSION, REGISTERED_CATALOGS } from './constants.js';
 import { atomic } from './engine-patches.js';
 import { Approvals } from './approvals.js';
 import { Bridge } from './bridge.js';
@@ -22,6 +22,7 @@ import { confirmRetainedLogin as confirmLogin, migrateRetainedLogin as migrateLo
 import { createRuns, RunReplay, signedInProviders } from './runs.js';
 import { authStatus, createAuthStatus } from './auth-status.js';
 import { outputSchema } from './output.js';
+import { words } from './words.js';
 import { createKeys } from './keys.js';
 import { routes as routeTable } from './routes.js';
 import { installedPlugins, pinnedSpec, recordPlugin, PluginInstallError } from './plugins.js';
@@ -699,7 +700,12 @@ export class OpenClawKit {
             ensure: (member) => this.ensureMember(member),
             authConfig: () => this.authSnapshot(),
             restarted: (authBefore, signal) => this.restarted(authBefore, signal),
-            setProviderHeaders: (provider, headers) => this.patchConfig({ models: { providers: { [provider]: { headers: headers ?? null } } } }) });
+            setProviderHeaders: (provider, headers) => this.patchConfig({ models: { providers: { [provider]: { headers: headers ?? null } } } }),
+            registerModels: (provider, rows) => {
+                const done = this.catalogs.then(() => this.registerModels(provider, rows));
+                this.catalogs = done.catch(() => { });
+                return done;
+            } });
         const slot = {};
         this.approvalsCtl = new Approvals({
             request: (method, params, co) => this.request()(method, params, co),
@@ -726,6 +732,16 @@ export class OpenClawKit {
         } : o.host;
         this.delegations = new Delegations({ file: join(this.engine.root, 'delegated-runs.json'), tools: new Set(this.toolNames()),
             memberOf: agent => this.memberOf(agent), request: (method, params, options) => this.request()(method, params, options),
+            helper: (member, helper) => {
+                if (!this.helpersCtl)
+                    throw new Error('gateway not ready');
+                return this.helpersCtl.resolve(member, helper);
+            },
+            rest: async (member, account, until) => {
+                if (!this.accountsCtl)
+                    throw new Error('gateway not ready');
+                await this.accountsCtl.rest(member, account, until);
+            },
             emit: payload => { for (const fn of this.listeners)
                 fn({ event: 'byokit.delegated', payload }); },
             revoke: (key, runId) => this.bridge.revoke(key, runId) });
@@ -1077,6 +1093,25 @@ export class OpenClawKit {
             return Promise.reject(new Error('gateway not ready'));
         return this.helpersCtl.ensure(member, helper, o);
     }
+    /** Adopt a legacy conversation of the member into one of its helpers (5.8.3, S4): its whole transcript forks to
+     * `agent:<member>:h-<helper>:<tail>` on the helper's account agent (as `move` does), then the old session goes.
+     * One still in flight (a live run, a parked approval or an admitted delegated child under it) is refused `busy`
+     * and keeps its exact old key until it settles; nothing is replayed and no approval changes owner. */
+    async adoptHelperSession(ref, helper) {
+        if (!this.accountsCtl || !this.helpersCtl)
+            throw new Error('gateway not ready');
+        const tailOf = (key) => key.slice(key.indexOf(':', 'agent:'.length) + 1);
+        const tail = tailOf(String(ref.sessionKey));
+        if (!String(ref.sessionKey).startsWith(`agent:${ref.member}:`) || HELPER_TAIL.test(tail))
+            throw new HelperError('session', `refused: "${String(ref.sessionKey)}" is not a legacy session of member "${String(ref.member)}"`);
+        const { account } = this.helpersCtl.resolve(ref.member, helper);
+        const owns = (key) => key !== undefined && tailOf(key) === tail && this.memberOf(key) === ref.member;
+        if (this.approvals(ref.member).some((a) => owns(a.sessionKey))
+            || this.delegatedRuns().some((r) => owns(r.parent.sessionKey) || owns(r.root.sessionKey)))
+            return { ok: false, code: 'busy', message: words('move.busy') };
+        const moved = await this.accountsCtl.move(ref.member, ref.sessionKey, account, `h-${helper}:${tail}`);
+        return moved.ok ? { ok: true, session: `agent:${ref.member}:h-${helper}:${tail}` } : moved;
+    }
     // sign-in (5.7): every body here is the module's, with this kit's transport, members and ports.
     signInCtx() {
         return { request: (method, params, o) => this.request()(method, params, o),
@@ -1311,7 +1346,7 @@ export class OpenClawKit {
     // Live provider catalogs (5.6): registers each live model with its api from the provider's catalog data, so
     // embedded runs resolve it. Serialized and in the background; a failure is logged and keeps the registered list.
     syncCatalogs() {
-        for (const provider of LIVE_CATALOGS) {
+        for (const provider of REGISTERED_CATALOGS) {
             if (this.o.config?.models?.providers?.[provider]?.models !== undefined)
                 continue;
             this.catalogs = this.catalogs.then(async () => {
@@ -1321,18 +1356,22 @@ export class OpenClawKit {
                         this.o.log?.(`catalog sync ${provider}: ${answer.reason ?? 'failed'}`);
                     return;
                 }
-                const { config } = await this.request()('config.get');
-                const registered = config?.models?.providers?.[provider]?.models ?? [];
-                const byId = new Map(registered.map((m) => [m.id, m]));
-                for (const m of answer.models ?? [])
-                    byId.set(m.id, m);
-                const models = [...byId.values()];
-                if (!isDeepStrictEqual(models, registered))
-                    await this.patchConfig({ models: { providers: { [provider]: { models } } } });
+                await this.registerModels(provider, answer.models ?? []);
             }).catch(() => { if (this.current.phase === 'ready')
                 this.o.log?.(`catalog sync ${provider}: failed`); });
         }
     }
+    // Merges catalog rows into the registered list by id; an unchanged list is never rewritten.
+    async registerModels(provider, rows) {
+        const { config } = await this.request()('config.get');
+        const registered = config?.models?.providers?.[provider]?.models ?? [];
+        const byId = new Map(registered.map((m) => [m.id, m]));
+        for (const m of rows)
+            byId.set(m.id, m);
+        const models = [...byId.values()];
+        if (!isDeepStrictEqual(models, registered))
+            await this.patchConfig({ models: { providers: { [provider]: { models } } } });
+    }
     migrateRetainedLogin(member, source) {
         return migrateLogin({ root: this.engine.root, prepare: () => this.prepare(), doctor: () => this.engine.doctor(120_000),
             seal: this.o.authSeal, log: this.o.log, withStore: (task) => this.engine.withAuthStore(task) }, member, source);
@@ -1368,7 +1407,7 @@ export class OpenClawKit {
         return (this.o.tools ?? []).map((t) => t.name);
     }
     async run(spec, on) {
-        if (spec.delegates && this.o.gateBuiltins === false)
+        if ((spec.delegates || spec.helperDelegates) && this.o.gateBuiltins === false)
             throw new Error('delegation requires builtin gating');
         if (this.o.browser) {
             if (!await this.checkBrowserTools())

package/dist/runs.js

@@ -7,6 +7,7 @@ import { outputSchema } from './output.js';
 import { words } from './words.js';
 import { classify } from './classify.js';
 import { providerOf } from './pick.js';
+import { engineId } from './accounts.js';
 import { catalogModelOf, clampThinking, levelsOf } from './thinking.js';
 // The gateway gives up on a silent run after an hour; we wait ten minutes longer for the reply frame itself.
 const WAIT_MS = 3_600_000;
@@ -172,10 +173,10 @@ export function createRuns(ctx) {
         const helper = spec.helper === undefined ? undefined : ctx.helpers.resolve(spec.member, spec.helper);
         if (helper ? !spec.sessionKey.startsWith(`agent:${spec.member}:h-${spec.helper}:`) : HELPER_TAIL.test(tail))
             throw new HelperError('session', `refused: "${spec.sessionKey}" is not a session of ${helper ? `helper "${spec.helper}"` : 'this run'}`);
-        if (spec.delegates) {
+        if (spec.delegates || spec.helperDelegates) {
             if (spec.register === false || !ctx.delegations)
                 throw new Error('delegation requires a registered run');
-            ctx.delegations.validate(spec.delegates);
+            ctx.delegations.validate(spec.delegates ?? {}, spec.member, spec.helperDelegates);
         }
         // Same validation as the pin's NonEmptyString; preserve the caller's bytes (including whitespace).
         if (spec.idempotencyKey !== undefined && (typeof spec.idempotencyKey !== 'string' || !spec.idempotencyKey.length))
@@ -183,9 +184,16 @@ export function createRuns(ctx) {
         const idempotencyKey = spec.idempotencyKey ?? randomUUID();
         const output = preparedOutput ?? (spec.schema === undefined ? undefined : outputSchema(spec.schema));
         const system = [helper?.persona ?? spec.system, output?.prompt].filter(Boolean).join('\n\n');
-        const picked = spec.model === undefined ? undefined : account(spec.model);
+        let catalogs;
+        const accountOf = async (model) => {
+            const picked = account(model);
+            catalogs ??= ctx.request('config.get', {}).then((answer) => answer.config?.models?.providers);
+            const providers = await catalogs;
+            return { provider: picked.provider, model: engineId(picked.provider, model, providers?.[picked.provider]?.models) };
+        };
+        const picked = spec.model === undefined ? undefined : await accountOf(spec.model);
         for (const need of spec.needs ?? [])
-            account(need);
+            await accountOf(need);
         for (const tool of spec.tools ?? [])
             if (!ctx.tools.has(tool))
                 throw new Error(`refused: "${tool}" is not one of this kit's tools`);
@@ -262,7 +270,7 @@ export function createRuns(ctx) {
                     if (!ready)
                         return { ok: false, kind: 'signed-out', message: `${pick.account.name} is not signed in` };
                     return await start(spec, on, { agentId: agent, sessionKey, idempotencyKey, system,
-                        picked: pick.model ? account(pick.model) : undefined, output, chosen: pick }); // '' = no override
+                        picked: pick.model ? await accountOf(pick.model) : undefined, output, chosen: pick }); // '' = no override
                 }
                 finally {
                     if (ctx.routes.get(spec.sessionKey) === route)
@@ -335,7 +343,8 @@ export function createRuns(ctx) {
         });
         try {
             const ref = { sessionKey, member: spec.member, ...(spec.helper !== undefined ? { helper: spec.helper } : {}) };
-            releaseDelegation = spec.delegates ? ctx.delegations.register(ref, idempotencyKey, spec.tools, spec.delegates, spec.sessionKey) : undefined;
+            releaseDelegation = spec.delegates || spec.helperDelegates
+                ? ctx.delegations.register(ref, idempotencyKey, spec.tools, spec.delegates ?? {}, spec.sessionKey, spec.helperDelegates) : undefined;
             release = spec.register !== false ? ctx.bridge.register(ref, spec.tools, idempotencyKey) : undefined;
             if (picked && !chosen) {
                 // The picked account must be the one called: check it is signed in for this member before the run, since

package/dist/signin.js

@@ -4,7 +4,6 @@ import { randomUUID } from 'node:crypto';
 import { createServer } from 'node:http';
 import { activate, LATE_RESTART } from './activation.js';
 import { authStatus } from './auth-status.js';
-import { LIVE_CATALOGS } from './constants.js';
 import { routes } from './routes.js';
 import { signedInProviders } from './runs.js';
 import { words } from './words.js';
@@ -301,13 +300,13 @@ export function signIn(ctx, member, o, on) {
                 if (!apiKey)
                     return { state: 'failed', via, why: signal.aborted ? 'declined' : 'expired' };
                 secret = apiKey.trim() || undefined;
-                // A live-catalog key can act for several workspaces, and the Go gateway refuses every call until one is
+                // A Go key can act for several workspaces, and the Go gateway refuses every call until one is
                 // named (403 Workspace selection is required): the engine carries the workspace only from its provider
                 // config headers, so resolve it here the way the kit's key lane does, and write the header before the
                 // activation so the activation probe itself carries it. One workspace is used unasked; several ask here,
                 // answered through the same paste (an id or an exact name); a key the console refuses (a workspace-bound
                 // service key) needs none; a listing that cannot be read fails the sign-in before anything changes.
-                if (secret && keyRoute && LIVE_CATALOGS.includes(keyRoute.provider) && ctx.setProviderHeaders && ctx.listWorkspaces) {
+                if (secret && keyRoute?.provider === 'opencode-go' && ctx.setProviderHeaders && ctx.listWorkspaces) {
                     let workspaces;
                     try {
                         workspaces = await ctx.listWorkspaces(secret, signal);

package/dist/testing/fake-gateway.js

@@ -281,15 +281,45 @@ export function fakeGateway(script, o) {
         for (const waiter of run.waiters.splice(0))
             waiter(result);
     };
-    const emitRun = (run, stream, data) => emit('agent', { runId: run.runId, seq: run.seq++, stream, ts: Date.now(), data });
-    /** The `agent` handler: the run's scripted turn, its `[tool NAME {json}]` calls through the real bridge. */
-    const startRun = (params, bridgeSock) => {
+    const emitRun = (run, stream, data) => {
+        emit('agent', { runId: run.runId, seq: run.seq++, stream, ts: Date.now(), data });
+        const child = run.child;
+        if (child)
+            child.relay = child.relay.then(() => bridgeRequest(child.sock, { kind: 'delegation-event',
+                event: { runId: run.runId, sessionKey: run.sessionKey, stream, data } })).catch(() => { });
+    };
+    /**
+     * A native `sessions_send` as the engine and plugin play it: the parent's dispatch is tracked before it goes, then the
+     * exact target session runs as an engine-created child and the receipt names its run (delegated admission, 5.8).
+     */
+    const nativeSend = async (run, parentRunId, input, callId, sock) => {
+        const ids = { key: run.sessionKey, runId: parentRunId, callId };
+        const prepared = await bridgeRequest(sock, { kind: 'delegation-prepare', ...ids, tool: 'sessions_send', input });
+        if (prepared.allow === false)
+            return { isError: true, output: String(prepared.reason) };
+        const sessionKey = String(input.sessionKey);
+        const agentId = /^agent:([^:]+):/.exec(sessionKey)?.[1];
+        // Like the pin: a send reaches only a session that already exists (its agent's main excepted).
+        const child = agentId && (sessions.has(`${agentId}\n${sessionKey}`) || sessionKey === `agent:${agentId}:main`)
+            ? startRun({ agentId, sessionKey, message: input.message }, sock, true) : undefined;
+        const details = child ? { status: 'accepted', runId: child.runId, sessionKey }
+            : { status: 'error', error: `No session found: ${sessionKey}`, sessionKey };
+        await bridgeRequest(sock, { kind: 'delegation-receipt', ...ids, result: { details } });
+        return { isError: !child, output: JSON.stringify(details) };
+    };
+    /** The `agent` handler: the run's scripted turn, its `[tool NAME {json}]` calls through the real bridge. An
+     * engine-created `child` names its own run on the bridge, as the plugin does with the engine's run id. */
+    const startRun = (params, bridgeSock, child = false) => {
         if (params.agentId != null && !agents.has(String(params.agentId)))
             throw new Error(`unknown agent: ${params.agentId}`);
         // Like the engine: the provider/model the run is called on, its own override or the member's (here openai).
         const run = { runId: randomUUID(), agentId: String(params.agentId ?? 'main'), sessionKey: String(params.sessionKey ?? ''), seq: 0,
             provider: String(params.provider ?? 'openai'), model: String(params.model ?? 'gpt-5.1'), waiters: [] };
         runs.set(run.runId, run);
+        if (child) {
+            run.child = { sock: bridgeSock, relay: Promise.resolve() };
+            emitRun(run, 'lifecycle', { phase: 'start' });
+        }
         const session = sessionOf(run.agentId, run.sessionKey);
         session.provider = run.provider;
         session.model = run.model;
@@ -309,13 +339,17 @@ export function fakeGateway(script, o) {
                     let isError = false;
                     if (bridgeSock && !(builtin && table?.gateBuiltins === false)) {
                         try {
-                            const gate = await bridgeRequest(bridgeSock, { kind: 'gate', key: run.sessionKey, tool: call.name, input: call.input });
+                            const owner = child ? { runId: run.runId } : {};
+                            const gate = await bridgeRequest(bridgeSock, { kind: 'gate', key: run.sessionKey, tool: call.name, input: call.input, ...owner });
                             if (!gate.allow) {
                                 isError = true;
                                 output = String(gate.reason ?? 'blocked');
                             }
+                            else if (builtin && call.name === 'sessions_send') {
+                                ({ isError, output } = await nativeSend(run, child ? run.runId : String(params.idempotencyKey ?? ''), call.input, toolCallId, bridgeSock));
+                            }
                             else if (!builtin) {
-                                const done = await bridgeRequest(bridgeSock, { kind: 'call', key: run.sessionKey, permit: gate.permit, tool: call.name, input: call.input });
+                                const done = await bridgeRequest(bridgeSock, { kind: 'call', key: run.sessionKey, permit: gate.permit, tool: call.name, input: call.input, ...owner });
                                 isError = done.ok !== true;
                                 output = String(done.ok === true ? done.text : done.reason);
                             }
@@ -332,7 +366,14 @@ export function fakeGateway(script, o) {
                 append(session, { role: 'assistant', content: [{ type: 'text', text }] });
                 // The engine sums the run's usage (zero buckets omitted); the fake counts characters.
                 run.usage = { input: message.length, output: text.length, total: message.length + text.length };
-                setTimeout(() => finish(run, { status: 'ok', terminalReply: { text } }), ABORT_WINDOW_MS);
+                setTimeout(() => {
+                    if (run.result || !child)
+                        return finish(run, { status: 'ok', terminalReply: { text } });
+                    // A child's lifecycle end, as the engine streams it: `hit the limit` plays the model's usage-limit error.
+                    const error = /hit the limit/i.test(message) ? 'You have hit your ChatGPT usage limit (plus plan). Try again in ~30 min.' : undefined;
+                    emitRun(run, 'lifecycle', error ? { phase: 'error', error } : { phase: 'end' });
+                    finish(run, error ? { status: 'error', error } : { status: 'ok', terminalReply: { text } });
+                }, ABORT_WINDOW_MS);
             })();
         }, 0);
         return { runId: run.runId, status: 'accepted' };

package/dist/types.d.ts

@@ -41,11 +41,19 @@ export type Helper = {
     agentId: string;
     sessionPrefix: string;
 };
-export type DelegatedRun = RunRef & Required<Pick<RunRef, 'runId' | 'agentId' | 'parent' | 'root'>>;
+/** An admitted engine-created child (5.8): `tools` is the app-tool subset it may call (the parent's, narrowed). */
+export type DelegatedRun = RunRef & Required<Pick<RunRef, 'runId' | 'agentId' | 'parent' | 'root'>> & {
+    tools: string[];
+};
+/** A delegated child's lifecycle (5.8.3 S3): `admitted`, its engine `event`s, then one `ended` whose `reason` is
+ * `terminal` (finished), `error` (`message`), `resting` (its helper's account hit its limit and rests `until`) or
+ * `cancelled` (aborted by the kit or the engine, or its admission ended). */
 export type DelegatedEvent = {
     type: 'admitted' | 'event' | 'ended';
     run: DelegatedRun;
-    reason?: 'terminal' | 'cancelled';
+    reason?: 'terminal' | 'error' | 'resting' | 'cancelled';
+    until?: number;
+    message?: string;
     event?: {
         stream: string;
         data?: Record<string, unknown>;
@@ -87,6 +95,9 @@ export interface RunSpec<S extends OutputSchema | undefined = OutputSchema | und
     tools?: string[];
     /** Exact target engine agent IDs and their app-tool subsets; does not share credentials. */
     delegates?: Record<string, string[]>;
+    /** The member's ensured helpers (5.8.3) this run may hand work to, and their app-tool subsets: an exact native send to
+     * `agent:<the helper's agent>:h-<helper>:<rest>` is admitted as that helper's run (RunRef.helper). */
+    helperDelegates?: Record<string, string[]>;
     register?: boolean;
 }
 export type RunEvent = {
@@ -191,6 +202,7 @@ export type Approval = {
     source: 'gate' | 'exec' | 'plugin' | 'question';
     member: Member;
     sessionKey?: string;
+    helper?: string;
     tool?: string;
     summary: string;
     input?: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "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",