@byokit/openclaw 0.19.0 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 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

@@ -403,7 +403,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`, `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 +442,42 @@ 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).
+
 ## Owned browser (unqualified handoff)
 
 `browser: { executablePath, members }` opts into isolated member Chromium profiles. It requires a closed

package/dist/helpers.d.ts

@@ -0,0 +1,25 @@
+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;
+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): {
+        agentId: string;
+        binding: Binding;
+        persona: string;
+    };
+};

package/dist/helpers.js

@@ -0,0 +1,70 @@
+// Helpers (5.8.3): a member's personas on one account the member already signed in. A helper is its own session
+// namespace `agent:<member>:h-<helper>:` run on the agent holding that account, with its own persona as the run's system
+// text: the pin shares no sign-in between agents (a shared agentDir is refused, authInheritance is global), so no agent
+// is made and nothing is copied. Its record is a kit-owned file; the engine is never asked.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadIndex } from './accounts.js';
+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}:/;
+const PERSONA_MAX = 8192;
+/** A refused helper request, before any run: `code` says which rule refused it. */
+export class HelperError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'HelperError';
+        this.code = code;
+    }
+}
+export function createHelpers(ctx) {
+    const valid = (member, helper) => typeof member === 'string' && MEMBER_ID.test(member)
+        && !member.startsWith(KEY_PREFIX) && typeof helper === 'string' && HELPER_ID.test(helper);
+    const path = (member, helper) => join(ctx.root, 'helpers', member, `${helper}.json`);
+    const read = (member, helper) => {
+        try {
+            const saved = JSON.parse(readFileSync(path(member, helper), 'utf8'));
+            return saved?.v === 1 && typeof saved.account === 'string' && typeof saved.agent === 'string'
+                && typeof saved.persona === 'string' ? saved : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const view = (member, helper, saved) => ({ member, helper, account: saved.account, agentId: saved.agent, sessionPrefix: `agent:${member}:h-${helper}:` });
+    return {
+        async ensure(member, helper, o) {
+            const persona = o?.persona;
+            // The persona is the helper's whole system text: bounded, plain text (newlines and tabs only).
+            if (!valid(member, helper) || typeof persona !== 'string' || !persona.trim() || persona.length > PERSONA_MAX
+                || /[\u0000-\u0008\u000b-\u001f\u007f]/.test(persona))
+                throw new HelperError('invalid', `invalid helper: ${String(member)}/${String(helper)}`);
+            if (!(await ctx.list(member)).some((row) => row.id === o.account))
+                throw new HelperError('unknown_account', `unknown account: ${String(o.account)}`);
+            const agent = loadIndex(ctx.root, member).file.accounts[o.account]?.agent;
+            if (!agent)
+                throw new HelperError('unknown_account', `unknown account: ${o.account}`);
+            const before = read(member, helper);
+            if (before && (before.account !== o.account || before.agent !== agent))
+                throw new HelperError('bound', `helper ${helper} uses another account`);
+            const saved = { v: 1, account: o.account, agent, persona };
+            const file = path(member, helper);
+            mkdirSync(join(file, '..'), { recursive: true, mode: 0o700 });
+            writeFileSync(`${file}.tmp`, JSON.stringify(saved), { mode: 0o600 });
+            renameSync(`${file}.tmp`, file);
+            return view(member, helper, saved);
+        },
+        // A run's helper, fail closed: ensured by this kit, on an account the member's index still names on the same agent.
+        // A removed account leaves the helper unusable; it never moves to another sign-in.
+        resolve(member, helper) {
+            const saved = valid(member, helper) ? read(member, helper) : undefined;
+            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,
+                binding: saved.agent === member ? { agentId: member } : { agentId: saved.agent, id: saved.account } };
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.ts';
-export type { Account, AccountId, AccountPick, AccountRef, Approval, CallOptions, ChannelChat, ChannelMessage, Considered, Decision, Defaults, ModelInfo, MoveResult, PickWhy, Room, RoomSpan, RunSelection, SignInState, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, LearningCapture, LearningMode, Member, PlanWindow, Route, RunEnd, RunEvent, RunFrame, RunRef, DelegatedRun, DelegatedEvent, RunSpec, OutputSchema, SchemaOutput, RunUsage, ThinkingAsked, ThinkingReport, ThinkingUsed, SignInOptions, SignInView, TelegramChannel, ToolHost, ToolSpec, } from './types.ts';
+export type { Account, AccountId, AccountPick, AccountRef, Approval, CallOptions, ChannelChat, ChannelMessage, Considered, Decision, Defaults, ModelInfo, MoveResult, PickWhy, Room, RoomSpan, RunSelection, SignInState, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, LearningCapture, LearningMode, Member, PlanWindow, Route, RunEnd, RunEvent, RunFrame, RunRef, Helper, DelegatedRun, DelegatedEvent, RunSpec, OutputSchema, SchemaOutput, RunUsage, ThinkingAsked, ThinkingReport, ThinkingUsed, SignInOptions, SignInView, TelegramChannel, ToolHost, ToolSpec, } from './types.ts';
 export type { GatewayMethods } from './generated/methods.ts';
 export type { JsonValue } from './output.ts';
 export type { RouteFacts, RouteView } from './routes.ts';
@@ -7,6 +7,7 @@ export { OpenClawKit, type KitOptions, type RetainedLogin } from './kit.ts';
 export type { AddKeyHandle, AddKeyResult, KeyFailureReason } from './keys.ts';
 export { stateWords, toAccountView, words, type AccountView, type WordKey } from './words.ts';
 export { chooseAccount, consider, resolveSelection, type RoomOf } from './pick.ts';
+export { HelperError, type HelperErrorCode } from './helpers.ts';
 export { AuthStoreUnreadableError, AuthStoreSealSizeError } from './auth-store.ts';
 export { EngineAlreadyRunningError } from './engine-status.ts';
 export { PluginInstallError, type PluginInstallFailure } from './plugins.ts';

package/dist/index.js

@@ -4,6 +4,7 @@ export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.j
 export { OpenClawKit } from './kit.js';
 export { stateWords, toAccountView, words } from './words.js';
 export { chooseAccount, consider, resolveSelection } from './pick.js';
+export { HelperError } from './helpers.js';
 export { AuthStoreUnreadableError, AuthStoreSealSizeError } from './auth-store.js';
 export { EngineAlreadyRunningError } from './engine-status.js';
 export { PluginInstallError } from './plugins.js';

package/dist/kit.d.ts

@@ -2,7 +2,7 @@ import type { SealingAdapter } from '@byokit/secrets';
 import { type AddKeyHandle } from './keys.ts';
 import { type RouteView } from './routes.ts';
 import type { BrowserHost, BrowserOptions } from './browser.ts';
-import type { Account, AccountId, AccountPick, Approval, CallOptions, Decision, Defaults, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, KitState, KitEventName, KitEventPayload, LearningCapture, LearningMode, Member, ModelInfo, MoveResult, Room, RunEnd, RunEvent, RunRef, RunSelection, RunSpec, OutputSchema, SchemaOutput, SignInOptions, SignInView, ChannelChat, TelegramChannel, ToolHost, ToolSpec } from './types.ts';
+import type { Account, AccountId, AccountPick, Approval, CallOptions, Decision, Defaults, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, Hello, Helper, KitState, KitEventName, KitEventPayload, LearningCapture, LearningMode, Member, ModelInfo, MoveResult, Room, RunEnd, RunEvent, RunRef, RunSelection, RunSpec, OutputSchema, SchemaOutput, SignInOptions, SignInView, ChannelChat, TelegramChannel, ToolHost, ToolSpec } from './types.ts';
 export type KitOptions = {
     stateDir: string;
     authSeal?: SealingAdapter;
@@ -68,6 +68,7 @@ export declare class OpenClawKit {
     attach(member: Member, runId: string, fromSeq: number, signal: AbortSignal): AsyncIterable<import("./types.ts").RunFrame>;
     private installs;
     private accountsCtl?;
+    private helpersCtl?;
     private readonly bridge;
     private readonly delegations;
     private readonly keys;
@@ -129,6 +130,11 @@ export declare class OpenClawKit {
         agentId: string;
         workspace: string;
     }>;
+    /** One of the member's helpers (5.8.3): its own persona and sessions on the member's `account`, no new sign-in. */
+    ensureHelper(member: Member, helper: string, o: {
+        account: AccountId;
+        persona: string;
+    }): Promise<Helper>;
     private signInCtx;
     routes(): RouteView[];
     /** Start Composio's hosted MCP OAuth flow through the pinned engine; return the URL for the app to open. */

package/dist/kit.js

@@ -14,6 +14,7 @@ import { Engine, canonicalStateDir, refusedOnly } from './engine.js';
 import { AuthStoreSealSizeError } from './auth-store.js';
 import { gatewayTransport } from './transport.js';
 import { createMembers } from './members.js';
+import { createHelpers, HELPER_TAIL, HelperError } from './helpers.js';
 import { createAccounts, memberOfAccount } from './accounts.js';
 import { createLocks } from './locks.js';
 import { keyAgentId, KEY_PREFIX, MEMBER_ID } from './members.js';
@@ -448,6 +449,7 @@ export class OpenClawKit {
     }
     installs = Promise.resolve();
     accountsCtl;
+    helpersCtl;
     // One bridge and one approval surface per kit: listeners and run registrations survive reconnects (B3).
     // Only the socket itself is per-connection. Approvals always reaches the live transport through this.request().
     bridge;
@@ -833,6 +835,7 @@ export class OpenClawKit {
                 ensure: (member) => this.ensureMember(member), locks: this.locks,
                 signIn: (agentId, o, on, fresh) => startSignIn({ ...this.signInCtx(), ensure: async () => ({ agentId }), fresh }, agentId, o, on),
                 routes: this.routeMap, log: this.o.log, reseal: () => this.engine.authStore.reseal() });
+            this.helpersCtl = createHelpers({ root: this.engine.root, list: (member) => this.accounts(member) });
             // The fail-closed tool bridge feeds the kit's single Approval surface (5.9, O5).
             await Promise.race([this.bridge.start(), exit]);
             this.off.push(transport.onEvent((e) => this.approvalsCtl.handleEvent(e)));
@@ -1068,6 +1071,12 @@ export class OpenClawKit {
         await attaching;
         return result;
     }
+    /** One of the member's helpers (5.8.3): its own persona and sessions on the member's `account`, no new sign-in. */
+    ensureHelper(member, helper, o) {
+        if (!this.helpersCtl)
+            return Promise.reject(new Error('gateway not ready'));
+        return this.helpersCtl.ensure(member, helper, o);
+    }
     // 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),
@@ -1226,6 +1235,8 @@ export class OpenClawKit {
     move(ref, to) {
         if (!this.accountsCtl)
             return Promise.reject(new Error('gateway not ready'));
+        if (HELPER_TAIL.test(String(ref.sessionKey).replace(/^agent:[^:]+:/, '')))
+            return Promise.reject(new HelperError('session', 'refused: a helper\'s session stays on its account'));
         return this.accountsCtl.move(ref.member, ref.sessionKey, to);
     }
     /** Sign in one more account: on the member agent while it holds none of the provider, else on a new sealed agent. */
@@ -1347,6 +1358,7 @@ export class OpenClawKit {
             bridge: { register: (run, tools, runId) => this.bridge.register(run, tools && this.o.browser ? [...tools, 'request_sign_in'] : tools, runId) },
             tools: new Set(this.toolNames()), delegations: this.delegations,
             ...(this.accountsCtl ? { accounts: this.accountsCtl } : {}),
+            ...(this.helpersCtl ? { helpers: this.helpersCtl } : {}),
             locks: this.locks,
             routes: this.routeMap,
         });

package/dist/runs.d.ts

@@ -1,4 +1,5 @@
 import type { Bridge } from './bridge.ts';
+import { type createHelpers } from './helpers.ts';
 import type { Delegations } from './delegations.ts';
 import type { createAccounts } from './accounts.ts';
 import type { createLocks } from './locks.ts';
@@ -40,6 +41,7 @@ export declare function createRuns(ctx: {
     }>;
     bridge: Pick<Bridge, 'register'>;
     delegations?: Delegations;
+    helpers?: Pick<ReturnType<typeof createHelpers>, 'resolve'>;
     tools: ReadonlySet<string>;
     accounts?: Pick<ReturnType<typeof createAccounts>, 'bind' | 'keyRefusal' | 'pick' | 'rest'>;
     locks?: ReturnType<typeof createLocks>;

package/dist/runs.js

@@ -1,6 +1,7 @@
 // Runs: one Gateway run per spec, streamed through typed events, ending in a classified RunEnd (5.8, O8).
 import { randomUUID } from 'node:crypto';
 import { setTimeout as delay } from 'node:timers/promises';
+import { HELPER_TAIL, HelperError } from './helpers.js';
 import { authStatus } from './auth-status.js';
 import { outputSchema } from './output.js';
 import { words } from './words.js';
@@ -163,6 +164,14 @@ export function createRuns(ctx) {
         // of one of the member's account agents is the member's too; binding below checks the index names it.
         if (!spec.sessionKey.startsWith(`agent:${spec.member}:`) && !(ctx.accounts && !keyAgent && spec.sessionKey.startsWith(`agent:${spec.member}--`)))
             throw new Error(`refused: "${spec.sessionKey}" is not a session of member "${spec.member}"`);
+        const tail = spec.sessionKey.slice(spec.sessionKey.indexOf(':', 'agent:'.length) + 1);
+        // A helper (5.8.3) speaks only under `agent:<member>:h-<helper>:`, with its persona as the whole system text, and
+        // only a run naming that helper speaks there. Refused before any request.
+        if (spec.helper !== undefined && (!ctx.helpers || keyAgent || spec.system !== undefined))
+            throw new HelperError('invalid', `refused: helper ${String(spec.helper)} runs on its own account with its own persona`);
+        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.register === false || !ctx.delegations)
                 throw new Error('delegation requires a registered run');
@@ -173,16 +182,16 @@ export function createRuns(ctx) {
             throw new Error('refused: idempotencyKey must be a non-empty string');
         const idempotencyKey = spec.idempotencyKey ?? randomUUID();
         const output = preparedOutput ?? (spec.schema === undefined ? undefined : outputSchema(spec.schema));
-        const system = [spec.system, output?.prompt].filter(Boolean).join('\n\n');
+        const system = [helper?.persona ?? spec.system, output?.prompt].filter(Boolean).join('\n\n');
         const picked = spec.model === undefined ? undefined : account(spec.model);
         for (const need of spec.needs ?? [])
             account(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`);
-        const tail = spec.sessionKey.slice(spec.sessionKey.indexOf(':', 'agent:'.length) + 1);
         // Runs step 1 (5.15): every run first finds the account its session is bound to, the API-key lane included.
-        const binding = ctx.accounts ? await ctx.accounts.bind(spec.member, spec.sessionKey) : undefined;
+        // A helper is bound to the agent whose sign-in it reads, as a conversation held there is.
+        const binding = helper?.binding ?? (ctx.accounts ? await ctx.accounts.bind(spec.member, spec.sessionKey) : undefined);
         // Step 2 on the API-key lane: its own lane binding continues; any other binding is refused.
         if (keyAgent && ctx.accounts && binding) {
             const message = await ctx.accounts.keyRefusal(spec.member, binding);
@@ -191,7 +200,7 @@ export function createRuns(ctx) {
         }
         // A run that waited for its agent's lock across a move (5.15) binds again under it: a changed binding means its
         // session went to another account, so it ends before any event and the caller's retry lands there.
-        const moved = async () => !!binding && (await ctx.accounts.bind(spec.member, spec.sessionKey))?.agentId !== binding.agentId;
+        const moved = async () => !helper && !!binding && (await ctx.accounts.bind(spec.member, spec.sessionKey))?.agentId !== binding.agentId;
         const movedEnd = { ok: false, kind: 'other', message: words('run.moved') };
         // Step 3: with `account` and `needs` both absent, on a key no account agent holds (or an API-key run, which binds only
         // to its lane), exactly the run on the agent it always was (a bound key under its shared lock).
@@ -325,8 +334,9 @@ export function createRuns(ctx) {
             }
         });
         try {
-            releaseDelegation = spec.delegates ? ctx.delegations.register({ sessionKey, member: spec.member }, idempotencyKey, spec.tools, spec.delegates, spec.sessionKey) : undefined;
-            release = spec.register !== false ? ctx.bridge.register({ sessionKey, member: spec.member }, spec.tools, idempotencyKey) : undefined;
+            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;
+            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
                 // the engine would otherwise fail the run only after admitting it. An explicit provider/model is strict on

package/dist/types.d.ts

@@ -19,6 +19,7 @@ export interface ToolSpec {
 export interface RunRef {
     sessionKey: string;
     member: Member;
+    helper?: string;
     meta?: unknown;
     runId?: string;
     agentId?: string;
@@ -31,6 +32,15 @@ export interface RunRef {
         runId: string;
     };
 }
+/** One of a member's helpers (5.8.3): its own persona and sessions (`sessionPrefix`) on `account`, run by `agentId`, the
+ * engine agent already holding that sign-in. */
+export type Helper = {
+    member: Member;
+    helper: string;
+    account: AccountId;
+    agentId: string;
+    sessionPrefix: string;
+};
 export type DelegatedRun = RunRef & Required<Pick<RunRef, 'runId' | 'agentId' | 'parent' | 'root'>>;
 export type DelegatedEvent = {
     type: 'admitted' | 'event' | 'ended';

package/package.json

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