@byokit/openclaw 0.19.0 → 0.21.0

package/dist/helpers.js

@@ -0,0 +1,72 @@
+// 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}:/;
+/** 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 {
+    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 { account: saved.account, 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/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

@@ -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,16 @@ 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>;
+    /** 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. */
@@ -208,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';
@@ -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';
@@ -21,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';
@@ -448,6 +450,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;
@@ -697,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),
@@ -724,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) });
@@ -833,6 +851,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 +1087,31 @@ 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);
+    }
+    /** 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),
@@ -1226,6 +1270,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. */
@@ -1300,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 () => {
@@ -1310,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);
@@ -1347,6 +1397,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,
         });
@@ -1356,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.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,11 +1,13 @@
 // 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';
 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;
@@ -163,26 +165,41 @@ 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}"`);
-        if (spec.delegates) {
+        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 || 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))
             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 picked = spec.model === undefined ? undefined : account(spec.model);
+        const system = [helper?.persona ?? spec.system, output?.prompt].filter(Boolean).join('\n\n');
+        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`);
-        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 +208,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).
@@ -253,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)
@@ -325,8 +342,10 @@ 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 || 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
                 // the engine would otherwise fail the run only after admitting it. An explicit provider/model is strict on

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);