@byokit/openclaw 0.18.3 → 0.20.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## 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.
+
 ## 0.18.3 (2026-10-19)
 
 - A signed-in Claude Code login is an account in the kit's account list, and its Claude CLI route's models are listed under it.

package/README.md

@@ -390,6 +390,8 @@ apps can offer them when the app or person opts in, labelled API key (billed per
 `local`) so the app can label what is billed. Proxy routes, compatibility aliases, local runtimes stay off. Native Claude Code sign-in is offered by default. The kit re-checks the installed Claude login at each setup detection and, once it is signed in, restarts the engine onto it. A plan key (OpenCode Go: `kit.addAccount(member, { authChoice: 'opencode-go' }, on)`) asks for `Plan key`; `paste` it and the engine live-tests it before `done`. A paired device starts the same sign-in with either `via` and pastes the key over the sealed link, which keeps it on the host. A run reaches the pinned engine's static Go models (default `opencode-go/deepseek-v4-pro`); the kit keeps OpenCode Go's `x-opencode-session` header on every request, the setup probe included. A live-only Go model such as Muse needs no app config: the kit registers the plan's live catalog with each model's API, so `run({ model: 'opencode-go/muse-spark-1.3-contributor' })` runs on the account (or with `auth: 'apiKey'` on a Go key); an app that sets `config.models.providers['opencode-go'].models` keeps its own list. A choice the pinned Gateway cannot set up has readiness `no_upstream_flow` and is never offered. Pass the accounts the app offers in `KitOptions.offered` (the provider, auth choice or alias each route carries, e.g. `'openrouter'`); the kit allow-lists the plugin of every route those name, so an opted-in sign-in is not blocked. An app can still name a plugin directly in `config.plugins.allow`, and pass the route's `choice` explicitly to `kit.signIn()`.
 Offered provider plugins are allowed by default alongside the app's plugin ids. A route whose provider plugin ships outside the engine (Z.AI's GLM Coding Plan, for one) has readiness `needs_plugin` until the app calls `await kit.installPlugin(route.needs.plugin)`: it installs that plugin into the kit's own engine at exactly the engine's version and pinned npm integrity, keeps it allowed across restarts, and rejects `PluginInstallError` (`code` `version` or `integrity`) with nothing installed on a mismatch. Discovery never installs.
 
+Composio uses its hosted MCP endpoint with the pinned OpenClaw engine's native OAuth client; BYOKit does not maintain a Composio app/tool list or install a separate plugin. `beginComposioSignIn()` configures `https://connect.composio.dev/mcp` for Streamable HTTP OAuth and returns `{ url }`; open it in the browser, then call `completeComposioSignIn()` to wait for OpenClaw's callback and token exchange. OpenClaw stores the OAuth credentials in its engine-owned SQLite state; when the app supplies `authSeal`, the kit seals that state at rest with other engine data. `signOutComposio()` invokes native MCP logout. Composio usage is billed under the person's own Composio plan.
+
 ## API at a glance
 
 Entries:
@@ -401,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 |
@@ -440,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/engine.d.ts

@@ -62,6 +62,14 @@ export declare class Engine {
         output: string;
     }>;
     private get path();
+    private runOwned;
+    private composioMcpLogin?;
+    private composioMcpContext;
+    beginComposioMcpLogin(): Promise<{
+        url: string;
+    }>;
+    completeComposioMcpLogin(): Promise<void>;
+    signOutComposio(): Promise<void>;
     private get claudeFolder();
     doctorContext(): {
         entry: string;

package/dist/engine.js

@@ -341,6 +341,115 @@ export class Engine {
         });
     }
     get path() { return ['/usr/bin', '/bin', ...this.o.enginePath ?? []].join(':'); }
+    async runOwned(binary, args, env, timeoutMs, input) {
+        return new Promise((resolve, reject) => {
+            const child = spawn(binary, args, { cwd: this.root, env, stdio: ['pipe', 'pipe', 'pipe'] });
+            let output = '', timedOut = false;
+            this.started.add(child);
+            const keep = (chunk) => { output = (output + chunk.toString()).slice(-65_536); };
+            child.stdout.on('data', keep);
+            child.stderr.on('data', keep);
+            const timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, timeoutMs);
+            child.once('error', error => { clearTimeout(timer); this.started.forget(child); reject(error); });
+            child.once('close', code => { clearTimeout(timer); this.started.forget(child); resolve({ code: timedOut ? null : code, output }); });
+            child.stdin.end(input);
+        });
+    }
+    composioMcpLogin;
+    composioMcpContext() {
+        const { entry, env: inherited } = this.doctorContext();
+        const home = join(this.root, 'home');
+        return { entry, env: { ...inherited, HOME: home, XDG_CONFIG_HOME: join(home, '.config'),
+                XDG_DATA_HOME: join(home, '.local/share'), XDG_STATE_HOME: join(home, '.local/state') } };
+    }
+    beginComposioMcpLogin() {
+        if (this.composioMcpLogin)
+            throw new Error('Composio MCP sign-in is already pending.');
+        const { entry, env } = this.composioMcpContext();
+        const child = spawn(process.execPath, [entry, 'mcp', 'login', 'composio'], {
+            cwd: join(this.root, 'home'), env, stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        this.started.add(child);
+        let output = '', urlFound = false;
+        let resolveUrl, rejectUrl;
+        let resolveDone;
+        const url = new Promise((resolve, reject) => { resolveUrl = resolve; rejectUrl = reject; });
+        const done = new Promise(resolve => { resolveDone = resolve; });
+        const timer = setTimeout(() => { child.kill('SIGKILL'); rejectUrl(new Error('OpenClaw MCP login did not return an authorization URL.')); }, 30_000);
+        const capture = (chunk) => {
+            output = (output + chunk.toString()).slice(-65_536);
+            const raw = output.match(/https:\/\/[^\s"'<>]+/)?.[0];
+            if (!raw || urlFound)
+                return;
+            try {
+                const parsed = new URL(raw);
+                if (parsed.protocol !== 'https:' || !['connect.composio.dev', 'login.composio.dev'].includes(parsed.hostname)
+                    || parsed.username || parsed.password)
+                    throw new Error('OpenClaw returned an unsafe Composio OAuth URL.');
+                urlFound = true;
+                clearTimeout(timer);
+                resolveUrl(parsed.href);
+            }
+            catch (error) {
+                clearTimeout(timer);
+                rejectUrl(error);
+                child.kill('SIGKILL');
+            }
+        };
+        child.stdout.on('data', capture);
+        child.stderr.on('data', capture);
+        child.once('error', error => {
+            clearTimeout(timer);
+            rejectUrl(error);
+            this.started.forget(child);
+            if (this.composioMcpLogin?.done === done && !urlFound)
+                this.composioMcpLogin = undefined;
+            resolveDone({ code: null, output });
+        });
+        child.once('close', code => {
+            clearTimeout(timer);
+            this.started.forget(child);
+            if (!urlFound) {
+                rejectUrl(new Error(`OpenClaw MCP login exited before authorization URL (exit ${code}).`));
+                if (this.composioMcpLogin?.done === done)
+                    this.composioMcpLogin = undefined;
+            }
+            resolveDone({ code, output });
+        });
+        this.composioMcpLogin = { url, done, child };
+        return url.then(value => ({ url: value }));
+    }
+    async completeComposioMcpLogin() {
+        const pending = this.composioMcpLogin;
+        if (!pending)
+            throw new Error('No Composio MCP sign-in is pending.');
+        try {
+            await pending.url;
+            let timer;
+            const timedOut = new Promise(resolve => { timer = setTimeout(() => resolve(null), 10 * 60_000); timer.unref(); });
+            const result = await Promise.race([pending.done, timedOut]);
+            clearTimeout(timer);
+            if (!result) {
+                pending.child.kill('SIGKILL');
+                await pending.done;
+                throw new Error('Composio MCP sign-in timed out.');
+            }
+            if (result.code !== 0)
+                throw new Error(`Composio MCP sign-in did not complete (OpenClaw exit ${result.code}).`);
+        }
+        finally {
+            if (this.composioMcpLogin?.done === pending.done)
+                this.composioMcpLogin = undefined;
+        }
+    }
+    async signOutComposio() {
+        if (this.composioMcpLogin)
+            throw new Error('Cannot sign out while Composio MCP sign-in is pending.');
+        const { entry, env } = this.composioMcpContext();
+        const result = await this.runOwned(process.execPath, [entry, 'mcp', 'logout', 'composio'], env, 30_000);
+        if (result.code !== 0)
+            throw new Error(`Composio MCP sign-out failed (OpenClaw exit ${result.code}).`);
+    }
     // The engine's own Claude folder: the fallback login writes it and, only with claudeFallback, the gateway reads it.
     get claudeFolder() { return join(this.root, 'home', '.claude'); }
     doctorContext() {
@@ -350,7 +459,8 @@ export class Engine {
                 OPENCLAW_STATE_DIR: join(this.root, 'state'), OPENCLAW_CONFIG_PATH: join(this.root, 'openclaw.json'),
                 // Upstream eagerly imports/refreshes Codex OAuth. Only the CLI may see the person's login.
                 CODEX_HOME: join(home, '.codex'),
-                XDG_CACHE_HOME: join(home, '.cache'), ...this.claudeFallback ? { CLAUDE_CONFIG_DIR: this.claudeFolder } : {},
+                XDG_CACHE_HOME: join(home, '.cache'),
+                ...this.claudeFallback ? { CLAUDE_CONFIG_DIR: this.claudeFolder } : {},
                 TMPDIR: join(this.root, 'tmp'), npm_config_cache: join(this.root, 'npm-cache'), npm_config_userconfig: join(this.root, 'npmrc'),
                 OPENCLAW_NO_RESPAWN: '1', OPENCLAW_SKIP_CHANNELS: '1', OPENCLAW_DISABLE_BONJOUR: '1',
                 OPENCLAW_EXEC_SHELL_SNAPSHOT: '0', OPENCLAW_LOAD_SHELL_ENV: '0', OPENCLAW_GATEWAY_TOKEN: this.token,
@@ -679,6 +789,7 @@ export class Engine {
         await this.starting?.catch(() => { });
         const child = this.child;
         await this.started.terminate(delay);
+        this.composioMcpLogin = undefined;
         if (child && child.exitCode === null && child.signalCode === null)
             throw new Error('engine did not stop; credential store still in use');
         this.child = undefined;

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,8 +130,21 @@ 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. */
+    beginComposioSignIn(): Promise<{
+        url: string;
+    }>;
+    /** Wait for OpenClaw's native MCP OAuth callback and token exchange to finish. */
+    completeComposioSignIn(): Promise<void>;
+    /** Clear the engine-owned native MCP OAuth credential for Composio. */
+    signOutComposio(): Promise<void>;
     /** B7 (5.7): install one external provider plugin a `needs_plugin` route names into this kit's own engine, at its
      * pin; resolves once the restarted gateway lists it enabled at that version. Discovery never installs. Serialized:
      * concurrent installs would race the allow-list update and double-spawn the installer into one engine tree. */

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),
@@ -1089,6 +1098,17 @@ export class OpenClawKit {
     routes() {
         return routeTable({ plugins: installedPlugins(this.engine.root) });
     }
+    /** Start Composio's hosted MCP OAuth flow through the pinned engine; return the URL for the app to open. */
+    async beginComposioSignIn() {
+        await this.patchConfig({ mcp: { servers: { composio: {
+                        url: 'https://connect.composio.dev/mcp', transport: 'streamable-http', auth: 'oauth', enabled: true,
+                    } } } });
+        return this.engine.beginComposioMcpLogin();
+    }
+    /** Wait for OpenClaw's native MCP OAuth callback and token exchange to finish. */
+    completeComposioSignIn() { return this.engine.completeComposioMcpLogin(); }
+    /** Clear the engine-owned native MCP OAuth credential for Composio. */
+    signOutComposio() { return this.engine.signOutComposio(); }
     /** B7 (5.7): install one external provider plugin a `needs_plugin` route names into this kit's own engine, at its
      * pin; resolves once the restarted gateway lists it enabled at that version. Discovery never installs. Serialized:
      * concurrent installs would race the allow-list update and double-spawn the installer into one engine tree. */
@@ -1215,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. */
@@ -1336,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.18.3",
+  "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",