@byokit/openclaw 0.16.6 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.18.0 (2026-10-18)
+
+- Reattach a paired device to a live-kit run by its existing idempotency key: sequenced replay then live events, a bounded journal with typed truncation, and grant-member isolation. Device disconnect does not interrupt the run; engine-restart reconstruction is not included.
+
+## 0.17.0 (2026-10-18)
+
+- Add opt-in `RunSpec.delegates` for native `sessions_send`/`sessions_spawn` app-tool admission and typed delegated events, retained exact receipts and subtree cancellation. Targets retain their own accounts; helper/person account sharing is not included.
+- SECURITY: Delegated authority requires a trusted native parent/tool-call receipt and exact child run/session identity; target tools intersect the parent subset, builtins remain gated, unknown children fail closed, and cancellation revokes parked and active calls before awaiting engine cleanup.
+
 ## 0.16.6 (2026-10-18)
 
 - SECURITY: Run `openai-codex/<model>` through the installed Codex CLI on the ChatGPT subscription using the pinned engine's supported CLI backend; keep engine state isolated and prevent the engine from importing or refreshing the installed Codex login.

package/README.md

@@ -422,6 +422,29 @@ of 394 methods' params and 193 of their results, plus 21 of 55 event payloads; t
 the kit, they are not published by the engine, and typing them here would be a guess that does not match the
 gateway. `callDynamic` stays the same shape for a method the pin never declared.
 
+## Native delegated runs (opt-in)
+
+Pass `delegates: { scout: ['report'] }` on `kit.run` to permit native delegation to that exact engine agent with
+that app-tool subset. Ensure the target member first and configure the engine's own A2A/visibility/subagent policy;
+this option does not enable engine tools or bypass `host.gate`. The parent subset narrows descendants too.
+Tracked `sessions_send` requires an explicit full `sessionKey` and `timeoutSeconds: 0`; tracked `sessions_spawn`
+requires an explicit allowed `agentId` and native runtime (not ACP). Unknown children fail closed.
+
+`kit.delegatedRuns()` lists admitted children. `kit.onEvent('byokit.delegated', fn)` reports admission, native streams
+and terminal observations with exact `runId`, `agentId`, `member`, `sessionKey`, `parent` and `root` identity.
+The same identity reaches `ToolHost`; each delegated action has its own gate/approval. Tool arguments/results
+are omitted from this event surface. An accepted native dispatch is not finished work or proof of delivery.
+
+Admitted exact run IDs survive parent settlement and are reconciled on reconnect/start. `abort(rootSessionKey)`
+durably revokes its recorded subtree, closes parked gates/active calls, then asks the engine to abort; a child key
+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
+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).
+
 ## Owned browser (unqualified handoff)
 
 `browser: { executablePath, members }` opts into isolated member Chromium profiles. It requires a closed

package/dist/bridge.d.ts

@@ -1,3 +1,4 @@
+import type { Delegations } from './delegations.ts';
 import type { Approval, ChannelMessage, Decision, Member, RunRef, ToolHost, ToolSpec } from './types.ts';
 /**
  * Asks must expire before the plugin's 195 s gate timeout, or the run gets a generic block while the approval
@@ -42,6 +43,8 @@ export declare class Bridge {
     private server?;
     private closing;
     private readonly sockets;
+    private readonly owners;
+    private readonly delegations?;
     private readonly runs;
     private readonly live;
     private readonly permits;
@@ -51,6 +54,7 @@ export declare class Bridge {
     private stopped;
     constructor(o: {
         path: string;
+        delegations?: Delegations;
         host?: ToolHost;
         tools: ReadonlySet<string>;
         permitted: (tool: string) => boolean;
@@ -64,6 +68,7 @@ export declare class Bridge {
     });
     start(): Promise<void>;
     stop(): void;
+    revoke(key: string, runId: string): void;
     isRegisteredRun(key: string, runId?: string): boolean;
     /** Register one run; release revokes only this exact registration, even when sessions overlap. */
     register(run: RunRef, tools?: readonly string[], runId?: string): () => void;

package/dist/bridge.js

@@ -74,6 +74,8 @@ export class Bridge {
     server;
     closing = Promise.resolve();
     sockets = new Set();
+    owners = new Map();
+    delegations;
     runs = new Map();
     // Every live registration per session key, each with its run's subset of the app's tools (RunSpec.tools; none: all
     // of them). Runs sharing a key share the narrowest: a tool must be in every live subset.
@@ -85,6 +87,7 @@ export class Bridge {
     stopped = false;
     constructor(o) {
         this.path = o.path;
+        this.delegations = o.delegations;
         this.host = o.host;
         this.tools = o.tools;
         this.permitted = o.permitted;
@@ -107,7 +110,7 @@ export class Bridge {
         rmSync(this.path, { force: true });
         const server = createServer(socket => {
             this.sockets.add(socket);
-            socket.once('close', () => this.sockets.delete(socket));
+            socket.once('close', () => { this.sockets.delete(socket); this.owners.delete(socket); });
             this.serve(socket);
         });
         this.server = server;
@@ -142,6 +145,27 @@ export class Bridge {
             this.closing = new Promise(resolve => server.close(() => resolve()))
                 .then(() => rm(this.path, { force: true }).catch(() => { }));
     }
+    revoke(key, runId) {
+        for (const entry of this.live.get(key) ?? [])
+            if (entry.runId === runId)
+                entry.runId = undefined;
+        for (const [id, p] of this.parked)
+            if (p.run.sessionKey === key && p.run.runId === runId) {
+                clearTimeout(p.timer);
+                this.parked.delete(id);
+                this.onAskGone(id);
+                p.socket.destroy();
+            }
+        for (const [socket, owner] of this.owners)
+            if (owner.key === key && owner.runId === runId)
+                socket.destroy();
+        for (const [id, p] of this.permits)
+            if (p.key === key && p.runId === runId)
+                this.permits.delete(id);
+        for (let i = this.tickets.length - 1; i >= 0; i--)
+            if (this.tickets[i].key === key && this.tickets[i].runId === runId)
+                this.tickets.splice(i, 1);
+    }
     isRegisteredRun(key, runId) {
         return !this.stopped && typeof runId === 'string' && !!runId
             && (this.live.get(key) ?? []).some(entry => entry.runId === runId);
@@ -206,17 +230,17 @@ export class Bridge {
             return;
         }
         if (this.permitted(tool)) {
-            this.reply(socket, { allow: true, permit: this.mint(key, tool, input) });
+            this.reply(socket, { allow: true, permit: this.mint(key, tool, input, this.owners.get(socket)?.runId) });
             return;
         }
-        this.tickets.push({ key, tool, input: JSON.stringify(input) });
+        this.tickets.push({ key, tool, input: JSON.stringify(input), runId: this.owners.get(socket)?.runId });
         while (this.tickets.length > 1024)
             this.tickets.shift();
         this.reply(socket, { allow: true });
     }
-    mint(key, tool, input) {
+    mint(key, tool, input, runId) {
         const permit = randomBytes(16).toString('hex');
-        this.permits.set(permit, { permit, key, tool, input: JSON.stringify(input) });
+        this.permits.set(permit, { permit, key, tool, input: JSON.stringify(input), runId });
         // Single-use entries are consumed on the next call; evict the oldest if the plugin never calls back.
         while (this.permits.size > 1024)
             this.permits.delete(this.permits.keys().next().value);
@@ -287,22 +311,51 @@ export class Bridge {
             catch { /* the app's handler, not the engine's */ }
             return;
         }
+        if (message.kind.startsWith('delegation-') && this.delegations) {
+            try {
+                if (message.kind === 'delegation-prepare') {
+                    if (typeof message.key !== 'string' || typeof message.runId !== 'string'
+                        || (!this.isRegisteredRun(message.key, message.runId) && !this.delegations.has(message.key, message.runId)))
+                        return this.deny(socket, 'unknown delegation parent');
+                    this.reply(socket, { tracked: this.delegations.prepare(message) });
+                }
+                else if (message.kind === 'delegation-receipt') {
+                    this.delegations.receipt(message);
+                    this.reply(socket, { ok: true });
+                }
+                else if (message.kind === 'delegation-event' && isRecord(message.event)) {
+                    this.delegations.event(message.event);
+                    this.reply(socket, { ok: true });
+                }
+                else
+                    this.deny(socket, 'invalid delegation message');
+            }
+            catch (error) {
+                this.deny(socket, error instanceof Error ? error.message : 'delegation unavailable');
+            }
+            return;
+        }
         if (message.kind === 'gate')
-            return void this.gate(socket, message);
+            return void this.gate(socket, message).catch(() => this.deny(socket, 'run unavailable'));
         if (message.kind === 'call')
-            return void this.call(socket, message);
+            return void this.call(socket, message).catch(() => this.reply(socket, { ok: false, reason: 'run unavailable' }));
         return this.deny(socket, 'not a gate request');
     }
-    gate(socket, message) {
+    async gate(socket, message) {
         const key = message.key;
         const tool = message.tool;
         const input = message.input;
         if (typeof key !== 'string' || typeof tool !== 'string' || !isRecord(input)) {
             return this.deny(socket, 'not a gate request');
         }
-        const run = this.runs.get(key);
+        const runId = typeof message.runId === 'string' ? message.runId : undefined;
+        this.owners.set(socket, { key, runId });
+        const delegated = await this.delegations?.resolve(key, runId);
+        if (this.stopped || socket.destroyed)
+            return;
+        const run = delegated?.ref ?? (!runId || this.isRegisteredRun(key, runId) ? this.runs.get(key) : undefined);
         if (run)
-            return void this.gateRun(socket, run, tool, input);
+            return void this.gateRun(socket, run, tool, input, delegated?.tools);
         const armed = this.armed;
         if (armed && Date.now() < armed.until && key.startsWith(armed.keyPrefix) && tool === armed.tool &&
             (!armed.input || armed.input(input))) {
@@ -314,11 +367,11 @@ export class Bridge {
         }
         return this.deny(socket, 'unknown run');
     }
-    async gateRun(socket, run, tool, input) {
+    async gateRun(socket, run, tool, input, subset) {
         if (!this.host)
             return this.deny(socket, "can't check this action right now");
         // An app tool outside the run's own subset never reaches the host; builtins stay with the gate.
-        if (this.tools.has(tool) && (this.live.get(run.sessionKey) ?? []).some((e) => e.tools && !e.tools.has(tool)))
+        if (this.tools.has(tool) && ((subset && !subset.includes(tool)) || (this.live.get(run.sessionKey) ?? []).some((e) => e.tools && !e.tools.has(tool))))
             return this.deny(socket, 'this tool is not available in this run');
         let result;
         try {
@@ -327,7 +380,7 @@ export class Bridge {
         catch {
             return this.deny(socket, "can't check this action right now");
         }
-        if (this.stopped)
+        if (this.stopped || socket.destroyed)
             return;
         if ('ask' in result) {
             const now = Date.now();
@@ -383,11 +436,13 @@ export class Bridge {
         // Only the app's own tools run through host.call; a builtin never calls back.
         if (!this.tools.has(tool))
             return this.reply(socket, { ok: false, reason: 'this call was not allowed' });
+        const runId = typeof message.runId === 'string' ? message.runId : undefined;
+        this.owners.set(socket, { key, runId });
         const wanted = JSON.stringify(input);
         const permit = message.permit;
         if (typeof permit === 'string') {
             const p = this.permits.get(permit);
-            if (!p || p.key !== key || p.tool !== tool || p.input !== wanted) {
+            if (!p || p.key !== key || p.runId !== runId || p.tool !== tool || p.input !== wanted) {
                 return this.reply(socket, { ok: false, reason: 'this call was not allowed' });
             }
             this.permits.delete(permit);
@@ -397,14 +452,17 @@ export class Bridge {
             // key + tool + input, so no run registration is needed (N10: allowOnce admits unregistered keys).
             if (this.permitted(tool))
                 return this.reply(socket, { ok: false, reason: 'this call was not allowed' });
-            const ticket = this.tickets.findIndex((t) => t.key === key && t.tool === tool && t.input === wanted);
+            const ticket = this.tickets.findIndex((t) => t.key === key && t.runId === runId && t.tool === tool && t.input === wanted);
             if (ticket < 0)
                 return this.reply(socket, { ok: false, reason: 'this call was not allowed' });
             this.tickets.splice(ticket, 1);
         }
         if (!this.host)
             return this.reply(socket, { ok: false, reason: "can't run this action right now" });
-        const run = this.runs.get(key) ?? { sessionKey: key, member: this.memberOf(key) ?? '' };
+        const delegated = await this.delegations?.resolve(key, runId);
+        if (this.stopped || socket.destroyed)
+            return;
+        const run = delegated?.ref ?? this.runs.get(key) ?? { sessionKey: key, member: this.memberOf(key) ?? '' };
         // The plugin destroys its socket when the run aborts (run abort, hook timeout); without this the host's
         // sandboxed command keeps running after the tool is gone.
         const controller = new AbortController();

package/dist/delegations.d.ts

@@ -0,0 +1,38 @@
+import type { DelegatedEvent, DelegatedRun, GatewayTransport, RunRef } from './types.ts';
+type Grant = {
+    ref: DelegatedRun;
+    tools: string[];
+    delegates: Record<string, string[]>;
+    sourceKey: string;
+};
+export declare class Delegations {
+    private loaded;
+    private roots;
+    private children;
+    private pending;
+    private changed;
+    private early;
+    constructor(privateOptions: {
+        file: string;
+        tools: ReadonlySet<string>;
+        memberOf(agent: string): string | undefined;
+        request: GatewayTransport['request'];
+        emit(e: DelegatedEvent): void;
+        revoke(key: string, runId: string): void;
+    });
+    private readonly o;
+    private load;
+    private save;
+    validate(delegates: Record<string, string[]>): void;
+    register(ref: RunRef, runId: string, tools: readonly string[] | undefined, delegates: Record<string, string[]>, sourceKey?: string): () => void;
+    list(): DelegatedRun[];
+    has(key: string, runId: string): boolean;
+    prepare(m: Record<string, any>): boolean;
+    receipt(m: Record<string, any>): void;
+    resolve(key: string, runId?: string): Promise<Grant | undefined>;
+    event(event: Record<string, any>): void;
+    private end;
+    reconcile(): Promise<void>;
+    abort(key: string): Promise<void>;
+}
+export {};

package/dist/delegations.js

@@ -0,0 +1,204 @@
+// Native receipts, never session-prefix authority. Persist identity/tool policy only, not prompts or credentials.
+import { existsSync, readFileSync } from 'node:fs';
+import { atomic } from './engine-patches.js';
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const agentOf = (key) => /^agent:([^:]+):.+/.exec(key)?.[1];
+const actionKey = (m) => JSON.stringify([m.key, m.runId, m.callId]);
+export class Delegations {
+    loaded = false;
+    roots = new Map();
+    children = new Map();
+    pending = new Map();
+    changed = new Set();
+    early = new Map();
+    constructor(privateOptions) { this.o = privateOptions; }
+    o;
+    load() {
+        if (this.loaded)
+            return;
+        if (existsSync(this.o.file)) {
+            const saved = JSON.parse(readFileSync(this.o.file, 'utf8'));
+            if (saved.version !== 1 || !Array.isArray(saved.children) || !Array.isArray(saved.pending))
+                throw new Error('invalid delegated run journal');
+            this.children = new Map(saved.children);
+            this.pending = new Map(saved.pending);
+        }
+        this.loaded = true;
+    }
+    save() {
+        for (const [key, p] of this.pending)
+            if (p.expires < Date.now())
+                this.pending.delete(key);
+        const bytes = JSON.stringify({ version: 1, children: [...this.children], pending: [...this.pending] });
+        atomic(this.o.file, bytes);
+        for (const notify of this.changed)
+            notify();
+    }
+    validate(delegates) {
+        if (!object(delegates) || Object.keys(delegates).length > 64)
+            throw new Error('invalid delegates');
+        for (const [agent, tools] of Object.entries(delegates)) {
+            if (!/^[a-z][a-z0-9-]{0,63}$/.test(agent) || !this.o.memberOf(agent) || !Array.isArray(tools)
+                || tools.some(t => !this.o.tools.has(t)))
+                throw new Error(`invalid delegate: ${agent}`);
+        }
+    }
+    register(ref, runId, tools, delegates, sourceKey = ref.sessionKey) {
+        this.load();
+        this.validate(delegates);
+        const root = { ref: { ...ref, runId, root: { sessionKey: ref.sessionKey, runId } },
+            tools: [...tools ?? this.o.tools], delegates: structuredClone(delegates), sourceKey };
+        this.roots.set(runId, root);
+        return () => { if (this.roots.get(runId) === root)
+            this.roots.delete(runId); };
+    }
+    list() { this.load(); return [...this.children.values()].map(g => structuredClone(g.ref)); }
+    has(key, runId) {
+        this.load();
+        return (this.roots.get(runId) ?? this.children.get(runId))?.ref.sessionKey === key;
+    }
+    prepare(m) {
+        this.load();
+        const parent = this.roots.get(m.runId) ?? this.children.get(m.runId);
+        if (!parent || parent.ref.sessionKey !== m.key)
+            return false;
+        if (typeof m.callId !== 'string' || !m.callId || !object(m.input))
+            throw new Error('delegation identity unavailable');
+        const send = m.tool === 'sessions_send';
+        if (!send && m.tool !== 'sessions_spawn')
+            throw new Error('unsupported delegation tool');
+        const agent = send ? typeof m.input.sessionKey === 'string' && agentOf(m.input.sessionKey) : m.input.agentId;
+        if (typeof agent !== 'string' || !Object.hasOwn(parent.delegates, agent)
+            || (send && (m.input.timeoutSeconds !== 0 || m.input.label !== undefined))
+            || (!send && m.input.runtime !== undefined && m.input.runtime !== 'subagent'))
+            throw new Error('delegation target or mode refused');
+        for (const [id, p] of this.pending)
+            if (p.expires < Date.now())
+                this.pending.delete(id);
+        if (this.pending.size + this.children.size >= 1024)
+            throw new Error('delegated run journal is full');
+        this.pending.set(actionKey(m), { parent: structuredClone(parent), agent,
+            ...(send ? { key: m.input.sessionKey } : {}), expires: Date.now() + 60_000 });
+        this.save();
+        return true;
+    }
+    receipt(m) {
+        this.load();
+        const id = actionKey(m), p = this.pending.get(id);
+        if (!p)
+            return;
+        this.pending.delete(id);
+        const d = m.result?.details;
+        const key = d?.childSessionKey ?? d?.sessionKey;
+        if (p.expires < Date.now() || !object(d) || !['accepted', 'ok', 'queued'].includes(d.status)
+            || typeof d.runId !== 'string' || !d.runId || typeof key !== 'string' || agentOf(key) !== p.agent
+            || (p.key !== undefined && p.key !== key)) {
+            this.save();
+            return;
+        }
+        const member = this.o.memberOf(p.agent);
+        if (!member) {
+            this.save();
+            return;
+        }
+        const ref = { sessionKey: key, member, runId: d.runId, agentId: p.agent,
+            parent: { sessionKey: p.parent.ref.sessionKey, runId: p.parent.ref.runId }, root: p.parent.ref.root };
+        const grant = { ref, delegates: p.parent.delegates, sourceKey: p.parent.sourceKey,
+            tools: p.parent.tools.filter(t => p.parent.delegates[p.agent].includes(t)) };
+        // A steered/already-admitted run keeps its original parent and cannot acquire a broader grant.
+        if (this.children.has(ref.runId)) {
+            this.save();
+            return;
+        }
+        this.children.set(ref.runId, grant);
+        this.save();
+        this.o.emit({ type: 'admitted', run: structuredClone(ref) });
+        for (const event of this.early.get(ref.runId) ?? [])
+            this.event(event);
+        this.early.delete(ref.runId);
+    }
+    async resolve(key, runId) {
+        this.load();
+        if (!runId)
+            return undefined;
+        const get = () => { const g = this.children.get(runId); return g?.ref.sessionKey === key ? g : undefined; };
+        if (!get() && [...this.pending.values()].some(p => p.expires > Date.now())) {
+            await new Promise(resolve => {
+                const done = () => { clearTimeout(timer); this.changed.delete(check); resolve(); };
+                const check = () => { if (get() || !this.pending.size)
+                    done(); };
+                const timer = setTimeout(done, 5_000);
+                this.changed.add(check);
+                check();
+            });
+        }
+        return get();
+    }
+    event(event) {
+        this.load();
+        const grant = this.children.get(event.runId);
+        if (!grant) {
+            if (this.pending.size && typeof event.runId === 'string' && this.early.size < 64) {
+                const events = this.early.get(event.runId) ?? [];
+                if (events.length < 32)
+                    events.push(event);
+                this.early.set(event.runId, events);
+            }
+            return;
+        }
+        if (event.sessionKey !== grant.ref.sessionKey)
+            return;
+        this.o.emit({ type: 'event', run: structuredClone(grant.ref), event: { stream: event.stream, data: event.data } });
+        if (event.stream === 'lifecycle' && ['end', 'error'].includes(event.data?.phase))
+            this.end(grant);
+    }
+    end(grant) {
+        this.children.delete(grant.ref.runId);
+        this.save();
+        this.o.revoke(grant.ref.sessionKey, grant.ref.runId);
+        this.o.emit({ type: 'ended', run: structuredClone(grant.ref), reason: 'terminal' });
+    }
+    async reconcile() {
+        for (const ref of this.list()) {
+            const end = await this.o.request('agent.wait', { runId: ref.runId, timeoutMs: 1 });
+            const grant = this.children.get(ref.runId);
+            if (grant && ['ok', 'error'].includes(end.status ?? ''))
+                this.end(grant);
+        }
+    }
+    async abort(key) {
+        this.load();
+        const ids = new Set();
+        for (const g of [...this.roots.values(), ...this.children.values()])
+            if (g.ref.sessionKey === key || g.ref.parent?.sessionKey === key || g.ref.root.sessionKey === key || g.sourceKey === key)
+                ids.add(g.ref.runId);
+        for (;;) {
+            const size = ids.size;
+            for (const g of this.children.values())
+                if (ids.has(g.ref.parent.runId))
+                    ids.add(g.ref.runId);
+            if (ids.size === size)
+                break;
+        }
+        let removed = false;
+        for (const [id, p] of this.pending)
+            if (ids.has(p.parent.ref.runId) || p.parent.ref.sessionKey === key || p.parent.ref.root.sessionKey === key || p.parent.sourceKey === key) {
+                this.pending.delete(id);
+                removed = true;
+            }
+        if (!ids.size && !removed)
+            return;
+        const cancelled = [...this.children.values()].filter(g => ids.has(g.ref.runId));
+        const revoked = [...this.roots.values(), ...cancelled].filter(g => ids.has(g.ref.runId));
+        for (const id of ids)
+            this.roots.delete(id);
+        for (const g of cancelled)
+            this.children.delete(g.ref.runId);
+        this.save(); // revoke durably before any awaited transport call
+        for (const g of revoked)
+            this.o.revoke(g.ref.sessionKey, g.ref.runId);
+        for (const g of cancelled)
+            this.o.emit({ type: 'ended', run: structuredClone(g.ref), reason: 'cancelled' });
+        await Promise.all(cancelled.map(g => this.o.request('chat.abort', { sessionKey: g.ref.sessionKey, runId: g.ref.runId })));
+    }
+}

package/dist/device.d.ts

@@ -2,9 +2,9 @@ import type { BrowserDevice, SignInRefusedWhy } from './browser.ts';
 import type { DeviceLink } from '@byokit/pair';
 import type { RouteView } from './routes.ts';
 import { type AccountView } from './words.ts';
-import type { Approval, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, KitState, RunEnd, OutputSchema, SchemaOutput, RunEvent, SignInView, AccountRef } from './types.ts';
+import type { Approval, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, KitState, RunEnd, OutputSchema, SchemaOutput, RunEvent, RunFrame, SignInView, AccountRef } from './types.ts';
 export type { GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult } from './types.ts';
-export type { Approval, Decision, KitState, PlanWindow, Route, RunEnd, RunEvent, RunUsage, SignInView, OutputSchema, SchemaOutput } from './types.ts';
+export type { Approval, Decision, KitState, PlanWindow, Route, RunEnd, RunEvent, RunFrame, RunUsage, SignInView, OutputSchema, SchemaOutput } from './types.ts';
 /** One `oc.events` frame: a member's Gateway event, typed by name, or an approval add/resolve (7.2). */
 export type OpenClawLinkEvent = {
     [E in GatewayEventName]: {
@@ -30,11 +30,13 @@ export type SessionRow = {
 /** The frame `oc.run`'s stream ends with: the run's `RunEnd`, beside its events. */
 export type DeviceEndFrame<T = unknown> = {
     type: 'end';
+    seq: number;
     end: RunEnd<T>;
 };
 /** `oc.run`'s options beside the message: the member's own session, account, and the kit's run options. */
 export type DeviceRunOptions<S extends OutputSchema | undefined = OutputSchema | undefined> = {
     schema?: S;
+    idempotencyKey?: string;
     sessionKey?: string;
     account?: AccountRef | 'default' | 'auto';
     needs?: string[];
@@ -96,6 +98,9 @@ export type OpenClawDevice = {
     signOut(p: string): Promise<void>;
     sessions(): Promise<SessionRow[]>;
     run<const S extends OutputSchema | undefined = undefined>(message: string, o?: DeviceRunOptions<S>): AsyncIterable<DeviceRunEvent | DeviceEndFrame<SchemaOutput<S>>>;
+    attach(runId: string, o: {
+        fromSeq: number;
+    }): AsyncIterable<RunFrame>;
     steer(k: string, t: string, o?: {
         auth?: 'apiKey';
     }): Promise<void>;

package/dist/device.js

@@ -361,8 +361,9 @@ export function openclawDevice(link) {
             await link.request('oc.signout', { provider: p });
         },
         sessions: () => link.request('oc.sessions'),
+        attach: (runId, o) => liveStream(() => link.stream('oc.attach', { runId, fromSeq: o.fromSeq })),
         run: (message, o) => {
-            const inner = liveStream(() => link.stream('oc.run', { message, ...(o?.sessionKey ? { sessionKey: checkKey(o.sessionKey) } : {}),
+            const inner = liveStream(() => link.stream('oc.run', { message, ...(o?.idempotencyKey !== undefined ? { idempotencyKey: o.idempotencyKey } : {}), ...(o?.sessionKey ? { sessionKey: checkKey(o.sessionKey) } : {}),
                 ...(o?.account !== undefined ? { account: o.account } : {}),
                 ...(o?.needs !== undefined ? { needs: o.needs } : {}),
                 ...(o?.model !== undefined ? { model: o.model } : {}), ...(o?.system !== undefined ? { system: o.system } : {}),

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, RunRef, 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, 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';

package/dist/kit.d.ts

@@ -64,9 +64,12 @@ export declare class OpenClawKit {
     private members?;
     private readonly locks;
     private readonly routeMap;
+    private readonly runReplay;
+    attach(member: Member, runId: string, fromSeq: number, signal: AbortSignal): AsyncIterable<import("./types.ts").RunFrame>;
     private installs;
     private accountsCtl?;
     private readonly bridge;
+    private readonly delegations;
     private readonly keys;
     private readonly admission;
     private readonly approvalsCtl;
@@ -207,6 +210,7 @@ export declare class OpenClawKit {
     steer(sessionKey: string, text: string, o?: {
         auth?: 'apiKey';
     }): Promise<void>;
+    delegatedRuns(): import('./types.ts').DelegatedRun[];
     abort(sessionKey: string, o?: {
         auth?: 'apiKey';
     }): Promise<void>;

package/dist/kit.js

@@ -9,6 +9,7 @@ import { PROTOCOL_VERSION, LIVE_CATALOGS } from './constants.js';
 import { atomic } from './engine-patches.js';
 import { Approvals } from './approvals.js';
 import { Bridge } from './bridge.js';
+import { Delegations } from './delegations.js';
 import { Engine, canonicalStateDir, refusedOnly } from './engine.js';
 import { AuthStoreSealSizeError } from './auth-store.js';
 import { gatewayTransport } from './transport.js';
@@ -17,7 +18,7 @@ import { createAccounts, memberOfAccount } from './accounts.js';
 import { createLocks } from './locks.js';
 import { keyAgentId, KEY_PREFIX, MEMBER_ID } from './members.js';
 import { confirmRetainedLogin as confirmLogin, migrateRetainedLogin as migrateLogin } from './migrate.js';
-import { createRuns, signedInProviders } from './runs.js';
+import { createRuns, RunReplay, signedInProviders } from './runs.js';
 import { authStatus, createAuthStatus } from './auth-status.js';
 import { outputSchema } from './output.js';
 import { createKeys } from './keys.js';
@@ -441,11 +442,16 @@ export class OpenClawKit {
     members;
     locks = createLocks();
     routeMap = new Map();
+    runReplay = new RunReplay();
+    attach(member, runId, fromSeq, signal) {
+        return this.runReplay.attach(member, runId, fromSeq, signal);
+    }
     installs = Promise.resolve();
     accountsCtl;
     // 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;
+    delegations;
     keys;
     admission;
     approvalsCtl;
@@ -716,7 +722,12 @@ export class OpenClawKit {
                 return o.host.call(run, tool, input, signal);
             },
         } : o.host;
-        this.bridge = new Bridge({ path: this.engine.bridgeSock, host, tools: new Set([...this.toolNames(), ...(o.browser ? ['request_sign_in'] : [])]),
+        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),
+            emit: payload => { for (const fn of this.listeners)
+                fn({ event: 'byokit.delegated', payload }); },
+            revoke: (key, runId) => this.bridge.revoke(key, runId) });
+        this.bridge = new Bridge({ path: this.engine.bridgeSock, delegations: this.delegations, host, tools: new Set([...this.toolNames(), ...(o.browser ? ['request_sign_in'] : [])]),
             ...(o.browser ? { browserCapabilities: () => [...this.browserCapabilities],
                 beforeAgentRun: async (key, runId) => {
                     // No action-id submission proof or redispatch claim. Open and unproven resumes are always refused.
@@ -825,6 +836,7 @@ export class OpenClawKit {
             // 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)));
+            await this.delegations.reconcile();
             this.failures = 0;
             this.reachedReady = true;
             this.setState({ phase: 'ready' });
@@ -940,6 +952,8 @@ export class OpenClawKit {
         });
     }
     closed(why) {
+        if (why === 'engine exited')
+            this.runReplay.clear();
         // A first start's loop owns an engine exit until it reaches ready; other closes are the transport client's to retry.
         if (this.startRun && !this.reachedReady) {
             if (why === 'engine exited')
@@ -968,6 +982,7 @@ export class OpenClawKit {
         return delay(retryAt - Date.now(), undefined, { signal });
     }
     async stop() {
+        this.runReplay.clear();
         this.stopping = true;
         this.reachedReady = false;
         this.startRun?.abort();
@@ -1303,10 +1318,11 @@ export class OpenClawKit {
     confirmRetainedLogin(member, source) {
         return confirmLogin({ ...this.signInCtx(), seal: this.o.authSeal, log: this.o.log }, member, source);
     }
-    // runs (5.8): the facade owns no run state; every call delegates to the O8 module
+    // runs (5.8): the facade retains the live journal; every dispatch delegates to the O8 module
     // with this kit's live transport, member table and bridge (spec item O9).
     runs() {
         return createRuns({
+            replay: this.runReplay,
             request: (method, params, o) => this.request()(method, params, o),
             authStatus: this.admission.read,
             invalidateAuth: this.admission.invalidate,
@@ -1318,7 +1334,7 @@ export class OpenClawKit {
             },
             ensure: (member) => this.ensureMember(member),
             bridge: { register: (run, tools, runId) => this.bridge.register(run, tools && this.o.browser ? [...tools, 'request_sign_in'] : tools, runId) },
-            tools: new Set(this.toolNames()),
+            tools: new Set(this.toolNames()), delegations: this.delegations,
             ...(this.accountsCtl ? { accounts: this.accountsCtl } : {}),
             locks: this.locks,
             routes: this.routeMap,
@@ -1329,6 +1345,8 @@ export class OpenClawKit {
         return (this.o.tools ?? []).map((t) => t.name);
     }
     async run(spec, on) {
+        if (spec.delegates && this.o.gateBuiltins === false)
+            throw new Error('delegation requires builtin gating');
         if (this.o.browser) {
             if (!await this.checkBrowserTools())
                 return { ok: false, kind: 'other', message: 'browser tool policy refused' };
@@ -1372,8 +1390,10 @@ export class OpenClawKit {
     async steer(sessionKey, text, o) {
         return this.runs().steer(this.runKey(sessionKey, o), text);
     }
+    delegatedRuns() { return this.delegations.list(); }
     async abort(sessionKey, o) {
-        return this.runs().abort(this.runKey(sessionKey, o));
+        const key = this.runKey(sessionKey, o);
+        await Promise.all([this.delegations.abort(key), this.runs().abort(key)]);
     }
     // approvals (5.9)
     approvals(member) {

package/dist/link.js

@@ -30,8 +30,9 @@ function memberSessions(result, owns) {
 }
 /** `oc.run`'s run options, type-checked; the kit's own checks (account, tool names) still apply. */
 function runOptions(args) {
-    const { message, model, account, needs, auth, system, images, thinking, tools, schema } = args;
+    const { message, idempotencyKey, model, account, needs, auth, system, images, thinking, tools, schema } = args;
     const ok = typeof message === 'string'
+        && (idempotencyKey === undefined || typeof idempotencyKey === 'string' && idempotencyKey.length > 0)
         && (model === undefined || typeof model === 'string')
         && (account === undefined || typeof account === 'string')
         && (needs === undefined || (Array.isArray(needs) && needs.every((n) => typeof n === 'string')))
@@ -46,6 +47,7 @@ function runOptions(args) {
         outputSchema(schema);
     return {
         message: message,
+        ...(idempotencyKey === undefined ? {} : { idempotencyKey: idempotencyKey }),
         ...(schema === undefined ? {} : { schema: schema }),
         ...(model === undefined ? {} : { model: model }),
         ...(account === undefined ? {} : { account: account }),
@@ -561,6 +563,31 @@ export function openclawLink(kit, o) {
             }
             return;
         }
+        if (req.op === 'oc.attach') {
+            if (grant.role === 'view')
+                throw refused();
+            const args = isRecord(req.args) ? req.args : {};
+            if (typeof args.runId !== 'string' || !args.runId.length || !Number.isSafeInteger(args.fromSeq) || args.fromSeq < 0)
+                throw refused();
+            const controller = new AbortController();
+            let frames;
+            try {
+                frames = kit.attach(member, args.runId, args.fromSeq, controller.signal);
+            }
+            catch {
+                throw refused();
+            }
+            s.onEnd = () => controller.abort();
+            try {
+                for await (const frame of frames)
+                    await s.write(`${JSON.stringify(frame)}\n`);
+                s.end();
+            }
+            finally {
+                controller.abort();
+            }
+            return;
+        }
         if (req.op === 'oc.run') {
             if (grant.role === 'view')
                 throw refused();
@@ -579,8 +606,9 @@ export function openclawLink(kit, o) {
                 tail = tail.then(() => s.write(`${JSON.stringify(frame)}\n`)).catch(() => { });
             };
             try {
-                const end = await kit.run({ member, sessionKey, ...options }, (e) => send(e));
-                send({ type: 'end', end });
+                let seq = 0;
+                const end = await kit.run({ member, sessionKey, ...options }, (e) => { seq = e.seq; send(e); });
+                send({ type: 'end', seq: seq + 1, end });
                 await tail;
                 s.end();
             }

package/dist/runs.d.ts

@@ -1,16 +1,36 @@
 import type { Bridge } from './bridge.ts';
+import type { Delegations } from './delegations.ts';
 import type { createAccounts } from './accounts.ts';
 import type { createLocks } from './locks.ts';
 import { authStatus } from './auth-status.ts';
 import { outputSchema, type OutputSchema, type SchemaOutput } from './output.ts';
-import type { GatewayTransport, Member, RunEnd, RunEvent, RunSpec } from './types.ts';
+import type { GatewayTransport, Member, RunEnd, RunEvent, RunFrame, RunSpec } from './types.ts';
 export declare const USABLE: Set<string>;
 /**
  * The providers a `models.authStatus` answer shows usable (the rule a picked account is checked by), lowercased and
  * unique; undefined while the engine has no prepared status (unknown, not none).
  */
 export declare function signedInProviders(status: unknown): string[] | undefined;
+type Journal = {
+    member: Member;
+    frames: Exclude<RunFrame, {
+        type: 'truncated';
+    }>[];
+    done: boolean;
+    wake: Set<() => void>;
+};
+/** Live-kit only: bounded history, with readers pulling by cursor rather than growing per-reader queues. */
+export declare class RunReplay {
+    private readonly runs;
+    begin(member: Member, id: string): Journal | undefined;
+    push(row: Journal | undefined, frame: Exclude<RunFrame, {
+        type: 'truncated';
+    }>): void;
+    clear(): void;
+    attach(member: Member, id: string, fromSeq: number, signal: AbortSignal): AsyncIterable<RunFrame>;
+}
 export declare function createRuns(ctx: {
+    replay?: RunReplay;
     request: GatewayTransport['request'];
     authStatus?: (agentId: string, refresh: boolean, native: boolean) => ReturnType<typeof authStatus>;
     invalidateAuth?: () => void;
@@ -19,6 +39,7 @@ export declare function createRuns(ctx: {
         agentId: string;
     }>;
     bridge: Pick<Bridge, 'register'>;
+    delegations?: Delegations;
     tools: ReadonlySet<string>;
     accounts?: Pick<ReturnType<typeof createAccounts>, 'bind' | 'keyRefusal' | 'pick' | 'rest'>;
     locks?: ReturnType<typeof createLocks>;
@@ -30,3 +51,4 @@ export declare function createRuns(ctx: {
     steer(k: string, t: string): Promise<void>;
     abort(k: string): Promise<void>;
 };
+export {};

package/dist/runs.js

@@ -71,6 +71,74 @@ function account(model) {
         throw new Error(`refused: "${model}" is not a provider/model reference`);
     return { provider, model: model.slice(model.indexOf('/') + 1) }; // the engine lowercases ids
 }
+/** Live-kit only: bounded history, with readers pulling by cursor rather than growing per-reader queues. */
+export class RunReplay {
+    runs = new Map();
+    begin(member, id) {
+        if (this.runs.has(id))
+            return undefined; // engine-cache retry must not replace the original stream
+        const row = { member, frames: [], done: false, wake: new Set() };
+        this.runs.set(id, row);
+        return row;
+    }
+    push(row, frame) {
+        if (!row)
+            return;
+        row.frames.push(frame);
+        if (row.frames.length > 32)
+            row.frames.shift();
+        row.done = frame.type === 'end';
+        for (const wake of row.wake)
+            wake();
+        if (row.done) {
+            const completed = [...this.runs].filter(([, r]) => r.done);
+            for (const [id] of completed.slice(0, -128))
+                this.runs.delete(id);
+        }
+    }
+    clear() {
+        for (const row of this.runs.values())
+            for (const wake of row.wake)
+                wake();
+        this.runs.clear();
+    }
+    attach(member, id, fromSeq, signal) {
+        const row = this.runs.get(id);
+        if (row && row.member !== member)
+            throw new Error('foreign run');
+        const runs = this.runs;
+        return (async function* () {
+            let cursor = fromSeq;
+            while (!signal.aborted) {
+                if (!row || runs.get(id) !== row) {
+                    yield { type: 'truncated', reason: 'not-found' };
+                    return;
+                }
+                const firstSeq = row.frames[0]?.seq ?? 1;
+                const lastSeq = row.frames.at(-1)?.seq ?? 0;
+                if (cursor < firstSeq - 1 || cursor > lastSeq) {
+                    yield { type: 'truncated', reason: 'truncated', firstSeq };
+                    return;
+                }
+                const next = row.frames.find(f => f.seq > cursor);
+                if (next) {
+                    cursor = next.seq;
+                    yield next;
+                    if (next.type === 'end')
+                        return;
+                    continue;
+                }
+                if (row.done)
+                    return;
+                await new Promise(resolve => {
+                    const wake = () => { row.wake.delete(wake); signal.removeEventListener('abort', wake); resolve(); };
+                    row.wake.add(wake);
+                    signal.addEventListener('abort', wake, { once: true });
+                });
+            }
+        })();
+    }
+}
 export function createRuns(ctx) {
     // The plan window the engine last read for the run's provider: `models.authStatus` answers from its cache without
     // blocking. Nothing reported, or no answer in time, is no window.
@@ -90,11 +158,16 @@ export function createRuns(ctx) {
             ctx.invalidateAuth?.();
         return { ok: false, ...classified, message };
     };
-    const run = async (spec, on, keyAgent, preparedOutput) => {
+    const execute = async (spec, on, keyAgent, preparedOutput) => {
         // Member boundary first: a member never speaks in another member's session, refused before any request. A key
         // 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) {
+            if (spec.register === false || !ctx.delegations)
+                throw new Error('delegation requires a registered run');
+            ctx.delegations.validate(spec.delegates);
+        }
         // 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');
@@ -213,7 +286,8 @@ export function createRuns(ctx) {
     };
     const start = async (spec, on, t) => {
         const { agentId, sessionKey, idempotencyKey, system, picked, output, chosen } = t;
-        const release = spec.register !== false ? ctx.bridge.register({ sessionKey, member: spec.member }, spec.tools, idempotencyKey) : undefined;
+        let release;
+        let releaseDelegation;
         let last;
         let runId = ''; // gateway events for other runs carry a real runId and never match the empty one
         let ended = false;
@@ -251,6 +325,8 @@ 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;
             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
@@ -340,10 +416,28 @@ export function createRuns(ctx) {
             ended = true;
             unsubscribe();
             release?.();
+            releaseDelegation?.();
         }
     };
+    const replay = ctx.replay ?? new RunReplay();
     return {
-        run,
+        run: async (spec, on, keyAgent, preparedOutput) => {
+            if (spec.idempotencyKey !== undefined && (typeof spec.idempotencyKey !== 'string' || !spec.idempotencyKey.length))
+                throw new Error('refused: idempotencyKey must be a non-empty string');
+            const id = spec.idempotencyKey ?? randomUUID();
+            const row = replay.begin(spec.member, id);
+            let seq = 0;
+            const emit = (e) => { const event = { ...e, seq: ++seq }; replay.push(row, event); on?.(event); };
+            try {
+                const end = await execute({ ...spec, idempotencyKey: id }, emit, keyAgent, preparedOutput);
+                replay.push(row, { type: 'end', seq: ++seq, end });
+                return end;
+            }
+            catch (error) {
+                replay.push(row, { type: 'end', seq: ++seq, end: failure(error instanceof Error ? error.message : String(error)) });
+                throw error;
+            }
+        },
         steer: (k, t) => ctx.request('sessions.steer', { sessionKey: ctx.routes.get(k)?.session ?? k, message: t }),
         abort: async (k) => { await ctx.request('chat.abort', { sessionKey: ctx.routes.get(k)?.session ?? k }); },
     };

package/dist/types.d.ts

@@ -20,7 +20,27 @@ export interface RunRef {
     sessionKey: string;
     member: Member;
     meta?: unknown;
+    runId?: string;
+    agentId?: string;
+    parent?: {
+        sessionKey: string;
+        runId: string;
+    };
+    root?: {
+        sessionKey: string;
+        runId: string;
+    };
 }
+export type DelegatedRun = RunRef & Required<Pick<RunRef, 'runId' | 'agentId' | 'parent' | 'root'>>;
+export type DelegatedEvent = {
+    type: 'admitted' | 'event' | 'ended';
+    run: DelegatedRun;
+    reason?: 'terminal' | 'cancelled';
+    event?: {
+        stream: string;
+        data?: Record<string, unknown>;
+    };
+};
 export type GateResult = {
     allow: true;
 } | {
@@ -55,9 +75,13 @@ export interface RunSpec<S extends OutputSchema | undefined = OutputSchema | und
     /** Explicit paid key choice. Uses a separate member-owned agent and separate session history. */
     auth?: 'apiKey';
     tools?: string[];
+    /** Exact target engine agent IDs and their app-tool subsets; does not share credentials. */
+    delegates?: Record<string, string[]>;
     register?: boolean;
 }
 export type RunEvent = {
+    seq: number;
+} & ({
     type: 'started';
 } | {
     type: 'thinking';
@@ -81,6 +105,15 @@ export type RunEvent = {
     input?: Record<string, unknown>;
     output?: unknown;
     error?: boolean;
+});
+export type RunFrame = RunEvent | {
+    type: 'end';
+    seq: number;
+    end: RunEnd;
+} | {
+    type: 'truncated';
+    reason: 'truncated' | 'not-found';
+    firstSeq?: number;
 };
 /** Token usage of one run as the engine totals it (every model call of the run, compaction included). */
 export type RunUsage = {
@@ -282,8 +315,8 @@ export type BrowserPing = {
     member: Member;
     kind: 'state' | 'signin';
 };
-export type KitEventName = GatewayEventName | 'byokit.browser';
-export type KitEventPayload<E extends KitEventName> = E extends 'byokit.browser' ? BrowserPing : GatewayEventPayload<Extract<E, GatewayEventName>>;
+export type KitEventName = GatewayEventName | 'byokit.browser' | 'byokit.delegated';
+export type KitEventPayload<E extends KitEventName> = E extends 'byokit.delegated' ? DelegatedEvent : E extends 'byokit.browser' ? BrowserPing : GatewayEventPayload<Extract<E, GatewayEventName>>;
 export type { GatewayMethod, GatewayParams, GatewayResult } from './generated/methods.ts';
 export type { GatewayEventName, GatewayEventPayload } from './generated/events.ts';
 export type AccountId = string;

package/package.json

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

package/plugin/index.js

@@ -15,6 +15,7 @@ const Kind = Symbol.for('TypeBox.Kind');
 const table = JSON.parse(readFileSync(new URL('./tools.json', import.meta.url), 'utf8'));
 const RUN_PARAM = table.runParam;
 const PERMIT_PARAM = table.permitParam;
+const RUN_ID_PARAM = `${RUN_PARAM}_id`;
 const TOOLS = new Map(table.tools.map((t) => [t.name, t]));
 // Absent (a table from before the flag) reads as true: fail closed.
 const GATE_BUILTINS = table.gateBuiltins !== false;
@@ -131,8 +132,8 @@ function bridgeRequest(message, { timeoutMs, signal } = {}) {
   });
 }
 
-async function gate(key, tool, input, signal) {
-  const reply = await bridgeRequest({ kind: 'gate', key, tool, input }, { timeoutMs: 195_000, signal });
+async function gate(key, tool, input, signal, runId) {
+  const reply = await bridgeRequest({ kind: 'gate', key, tool, input, runId }, { timeoutMs: 195_000, signal });
   return reply && typeof reply === 'object' ? reply : { allow: false, reason: "can't check this action right now" };
 }
 
@@ -151,6 +152,21 @@ export default {
   },
   register(api) {
     registerCodex(api);
+    api.on('after_tool_call', async (event, ctx) => {
+      if (!['sessions_send', 'sessions_spawn'].includes(event.toolName)) return;
+      const d = event.result?.details;
+      await bridgeRequest({ kind: 'delegation-receipt', key: ctx?.sessionKey, runId: ctx?.runId ?? event.runId,
+        callId: ctx?.toolCallId ?? event.toolCallId,
+        result: { details: d && { status: d.status, runId: d.runId, sessionKey: d.sessionKey, childSessionKey: d.childSessionKey } } });
+    });
+    api.registerAgentEventSubscription?.({ id: 'byokit-delegated-events', handle(event) {
+      if (!['assistant', 'tool', 'thinking', 'lifecycle'].includes(event.stream)) return;
+      const data = Object.fromEntries(['text', 'name', 'phase', 'toolCallId', 'isError', 'progressTokens', 'aborted', 'error', 'provider', 'model']
+        .filter(key => ['string', 'number', 'boolean'].includes(typeof event.data?.[key]))
+        .map(key => [key, event.data[key]]));
+      void bridgeRequest({ kind: 'delegation-event', event: { runId: event.runId, sessionKey: event.sessionKey,
+        stream: event.stream, data } }).catch(() => {});
+    } });
     if (api.registerGatewayMethod) { registerKeys(api); registerUsage(api); registerAccounts(api); registerCatalog(api); }
     if (BROWSER) {
       if (typeof api.registerAgentToolResultMiddleware !== 'function') throw new Error('browser result protection unavailable');
@@ -189,13 +205,15 @@ export default {
           const input = { ...(params ?? {}) };
           const run = input[RUN_PARAM];
           const permit = input[PERMIT_PARAM];
+          const runId = input[RUN_ID_PARAM];
           delete input[RUN_PARAM];
           delete input[PERMIT_PARAM];
+          delete input[RUN_ID_PARAM];
           // The run key is always required; the permit only rides along when the gate minted one (N1).
           if (typeof run !== 'string') {
             throw new Error('this tool needs approval before it runs');
           }
-          const call = { kind: 'call', key: run, tool: spec.name, input };
+          const call = { kind: 'call', key: run, runId, tool: spec.name, input };
           if (typeof permit === 'string') call.permit = permit;
           let reply;
           try {
@@ -247,7 +265,7 @@ export default {
       }
       let decision;
       try {
-        decision = await gate(key, event.toolName, params, ctx?.abortSignal);
+        decision = await gate(key, event.toolName, params, ctx?.abortSignal, ctx?.runId ?? event.runId);
       } catch (error) {
         return { block: true, blockReason: error instanceof Error ? error.message : "can't check this action right now" };
       }
@@ -257,6 +275,13 @@ export default {
           blockReason: typeof decision.reason === 'string' ? decision.reason : "can't check this action right now",
         };
       }
+      if (builtin && ['sessions_send', 'sessions_spawn'].includes(event.toolName)) {
+        try {
+          const prepared = await bridgeRequest({ kind: 'delegation-prepare', key, runId: ctx?.runId ?? event.runId,
+            callId: ctx?.toolCallId ?? event.toolCallId, tool: event.toolName, input: params });
+          if (prepared.allow === false) return { block: true, blockReason: prepared.reason };
+        } catch { return { block: true, blockReason: 'delegation admission unavailable' }; }
+      }
       if (builtin) return BROWSER && event.toolName === 'browser' ? { params } : undefined;
       // The bridge mints a permit for permitted tools and admits the rest ticket-side; either way the run key
       // rides along and execute sends back only what the gate gave it (N1).
@@ -264,6 +289,7 @@ export default {
         params: {
           ...params,
           [RUN_PARAM]: key,
+          ...(typeof (ctx?.runId ?? event.runId) === 'string' ? { [RUN_ID_PARAM]: ctx?.runId ?? event.runId } : {}),
           ...(typeof decision.permit === 'string' ? { [PERMIT_PARAM]: decision.permit } : {}),
         },
       };