@byokit/openclaw 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## 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.
+- SECURITY: helper requests fail closed with a typed `HelperError` before any engine request: an invalid id or persona, caller `system` text on a helper run, an account the member does not hold, a removed account (never moved to another sign-in), a session key outside the helper, a helper key run without `helper`, or `move` of a helper key. A helper gains no tool, builtin or session-key prefix the member's run would not.
+
 ## 0.19.0 (2026-10-19)
 
 - FEAT: connect Composio through the pinned engine's native MCP OAuth flow, with browser URL handoff and native sign-out.

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`, `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 |
@@ -442,11 +448,65 @@ durably revokes its recorded subtree, closes parked gates/active calls, then ask
 revokes its subtree. An engine resume with a different run ID, or a dispatch with no retained receipt, is not
 silently granted authority. No prefix grants or `allowOnce` bypass are used.
 
-**Per-helper account binding is not included:** targets retain their own existing engine credentials, persona,
-workspace and history. This option never copies credentials or gives helpers another person's account. Legacy
+**Targets keep their own sign-in:** a target retains its own engine credentials, persona, workspace and history; a
+member's own helpers run on the member's account (below). This option never copies credentials or gives helpers
+another person's account. Legacy
 in-flight jobs may retain their exact old session keys and approval owners; all new helper work uses the new
 mapping. Never copy agent SQLite or replay old sent actions. See the [binding contract](../../docs/runtime-kits.md#native-delegated-tool-admission-opt-in).
 
+## Helpers on a member's account
+
+A member can keep several helpers, each with its own persona and its own conversations, all on one account the
+member already signed in. Nothing is copied and nobody signs in again: a helper's runs go to the engine agent that
+already holds that account, under the helper's own session keys, with the helper's persona as the system text.
+
+```ts
+import { OpenClawKit, HelperError } from '@byokit/openclaw';
+
+declare const kit: OpenClawKit;
+const research = await kit.ensureHelper('umer', 'research', { account: 'openai', persona: 'You are Umer\'s research helper.' });
+// research.sessionPrefix === 'agent:umer:h-research:'
+const end = await kit.run({ member: 'umer', helper: 'research', sessionKey: `${research.sessionPrefix}main`,
+  message: 'Summarise the notes' });
+try {
+  await kit.run({ member: 'umer', helper: 'ghost', sessionKey: 'agent:umer:h-ghost:main', message: 'hi' });
+} catch (e) {
+  if (e instanceof HelperError) console.log(e.code, end.ok); // 'unknown_helper', before any request
+}
+```
+
+`account` is one of `kit.accounts(member)`, the API-key lane (`'<provider>.key'`) included; a key-lane helper's run
+names that account, as any paid run does. A helper's run is bound to its account (pick, rests and locks apply), and
+`RunRef.helper` names it on `ToolHost.gate` and `call`; its approvals are the member's. The persona is the run's whole
+system text: a helper run refuses `system`. Refusals are a typed `HelperError` before any engine request: `invalid`
+(ids, persona, `system`), `unknown_account`, `bound` (another account), `unknown_helper` (not ensured, or its account
+was removed: never moved to another sign-in) and `session` (a key outside the helper, a helper key without `helper`,
+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

@@ -0,0 +1,28 @@
+import { type Binding } from './accounts.ts';
+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 {
+    readonly code: HelperErrorCode;
+    constructor(code: HelperErrorCode, message: string);
+}
+export declare function createHelpers(ctx: {
+    root: string;
+    list(member: Member): Promise<Account[]>;
+}): {
+    ensure(member: Member, helper: string, o: {
+        account: AccountId;
+        persona: string;
+    }): Promise<Helper>;
+    resolve(member: Member, helper: string): {
+        account: AccountId;
+        agentId: string;
+        binding: Binding;
+        persona: string;
+    };
+};