@byokit/openclaw 0.19.0 → 0.21.0

package/dist/testing/fake-gateway.js

@@ -281,15 +281,45 @@ export function fakeGateway(script, o) {
         for (const waiter of run.waiters.splice(0))
             waiter(result);
     };
-    const emitRun = (run, stream, data) => emit('agent', { runId: run.runId, seq: run.seq++, stream, ts: Date.now(), data });
-    /** The `agent` handler: the run's scripted turn, its `[tool NAME {json}]` calls through the real bridge. */
-    const startRun = (params, bridgeSock) => {
+    const emitRun = (run, stream, data) => {
+        emit('agent', { runId: run.runId, seq: run.seq++, stream, ts: Date.now(), data });
+        const child = run.child;
+        if (child)
+            child.relay = child.relay.then(() => bridgeRequest(child.sock, { kind: 'delegation-event',
+                event: { runId: run.runId, sessionKey: run.sessionKey, stream, data } })).catch(() => { });
+    };
+    /**
+     * A native `sessions_send` as the engine and plugin play it: the parent's dispatch is tracked before it goes, then the
+     * exact target session runs as an engine-created child and the receipt names its run (delegated admission, 5.8).
+     */
+    const nativeSend = async (run, parentRunId, input, callId, sock) => {
+        const ids = { key: run.sessionKey, runId: parentRunId, callId };
+        const prepared = await bridgeRequest(sock, { kind: 'delegation-prepare', ...ids, tool: 'sessions_send', input });
+        if (prepared.allow === false)
+            return { isError: true, output: String(prepared.reason) };
+        const sessionKey = String(input.sessionKey);
+        const agentId = /^agent:([^:]+):/.exec(sessionKey)?.[1];
+        // Like the pin: a send reaches only a session that already exists (its agent's main excepted).
+        const child = agentId && (sessions.has(`${agentId}\n${sessionKey}`) || sessionKey === `agent:${agentId}:main`)
+            ? startRun({ agentId, sessionKey, message: input.message }, sock, true) : undefined;
+        const details = child ? { status: 'accepted', runId: child.runId, sessionKey }
+            : { status: 'error', error: `No session found: ${sessionKey}`, sessionKey };
+        await bridgeRequest(sock, { kind: 'delegation-receipt', ...ids, result: { details } });
+        return { isError: !child, output: JSON.stringify(details) };
+    };
+    /** The `agent` handler: the run's scripted turn, its `[tool NAME {json}]` calls through the real bridge. An
+     * engine-created `child` names its own run on the bridge, as the plugin does with the engine's run id. */
+    const startRun = (params, bridgeSock, child = false) => {
         if (params.agentId != null && !agents.has(String(params.agentId)))
             throw new Error(`unknown agent: ${params.agentId}`);
         // Like the engine: the provider/model the run is called on, its own override or the member's (here openai).
         const run = { runId: randomUUID(), agentId: String(params.agentId ?? 'main'), sessionKey: String(params.sessionKey ?? ''), seq: 0,
             provider: String(params.provider ?? 'openai'), model: String(params.model ?? 'gpt-5.1'), waiters: [] };
         runs.set(run.runId, run);
+        if (child) {
+            run.child = { sock: bridgeSock, relay: Promise.resolve() };
+            emitRun(run, 'lifecycle', { phase: 'start' });
+        }
         const session = sessionOf(run.agentId, run.sessionKey);
         session.provider = run.provider;
         session.model = run.model;
@@ -309,13 +339,17 @@ export function fakeGateway(script, o) {
                     let isError = false;
                     if (bridgeSock && !(builtin && table?.gateBuiltins === false)) {
                         try {
-                            const gate = await bridgeRequest(bridgeSock, { kind: 'gate', key: run.sessionKey, tool: call.name, input: call.input });
+                            const owner = child ? { runId: run.runId } : {};
+                            const gate = await bridgeRequest(bridgeSock, { kind: 'gate', key: run.sessionKey, tool: call.name, input: call.input, ...owner });
                             if (!gate.allow) {
                                 isError = true;
                                 output = String(gate.reason ?? 'blocked');
                             }
+                            else if (builtin && call.name === 'sessions_send') {
+                                ({ isError, output } = await nativeSend(run, child ? run.runId : String(params.idempotencyKey ?? ''), call.input, toolCallId, bridgeSock));
+                            }
                             else if (!builtin) {
-                                const done = await bridgeRequest(bridgeSock, { kind: 'call', key: run.sessionKey, permit: gate.permit, tool: call.name, input: call.input });
+                                const done = await bridgeRequest(bridgeSock, { kind: 'call', key: run.sessionKey, permit: gate.permit, tool: call.name, input: call.input, ...owner });
                                 isError = done.ok !== true;
                                 output = String(done.ok === true ? done.text : done.reason);
                             }
@@ -332,7 +366,14 @@ export function fakeGateway(script, o) {
                 append(session, { role: 'assistant', content: [{ type: 'text', text }] });
                 // The engine sums the run's usage (zero buckets omitted); the fake counts characters.
                 run.usage = { input: message.length, output: text.length, total: message.length + text.length };
-                setTimeout(() => finish(run, { status: 'ok', terminalReply: { text } }), ABORT_WINDOW_MS);
+                setTimeout(() => {
+                    if (run.result || !child)
+                        return finish(run, { status: 'ok', terminalReply: { text } });
+                    // A child's lifecycle end, as the engine streams it: `hit the limit` plays the model's usage-limit error.
+                    const error = /hit the limit/i.test(message) ? 'You have hit your ChatGPT usage limit (plus plan). Try again in ~30 min.' : undefined;
+                    emitRun(run, 'lifecycle', error ? { phase: 'error', error } : { phase: 'end' });
+                    finish(run, error ? { status: 'error', error } : { status: 'ok', terminalReply: { text } });
+                }, ABORT_WINDOW_MS);
             })();
         }, 0);
         return { runId: run.runId, status: 'accepted' };

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,11 +32,28 @@ export interface RunRef {
         runId: string;
     };
 }
-export type DelegatedRun = RunRef & Required<Pick<RunRef, 'runId' | 'agentId' | 'parent' | 'root'>>;
+/** 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;
+};
+/** An admitted engine-created child (5.8): `tools` is the app-tool subset it may call (the parent's, narrowed). */
+export type DelegatedRun = RunRef & Required<Pick<RunRef, 'runId' | 'agentId' | 'parent' | 'root'>> & {
+    tools: string[];
+};
+/** A delegated child's lifecycle (5.8.3 S3): `admitted`, its engine `event`s, then one `ended` whose `reason` is
+ * `terminal` (finished), `error` (`message`), `resting` (its helper's account hit its limit and rests `until`) or
+ * `cancelled` (aborted by the kit or the engine, or its admission ended). */
 export type DelegatedEvent = {
     type: 'admitted' | 'event' | 'ended';
     run: DelegatedRun;
-    reason?: 'terminal' | 'cancelled';
+    reason?: 'terminal' | 'error' | 'resting' | 'cancelled';
+    until?: number;
+    message?: string;
     event?: {
         stream: string;
         data?: Record<string, unknown>;
@@ -77,6 +95,9 @@ export interface RunSpec<S extends OutputSchema | undefined = OutputSchema | und
     tools?: string[];
     /** Exact target engine agent IDs and their app-tool subsets; does not share credentials. */
     delegates?: Record<string, string[]>;
+    /** The member's ensured helpers (5.8.3) this run may hand work to, and their app-tool subsets: an exact native send to
+     * `agent:<the helper's agent>:h-<helper>:<rest>` is admitted as that helper's run (RunRef.helper). */
+    helperDelegates?: Record<string, string[]>;
     register?: boolean;
 }
 export type RunEvent = {
@@ -181,6 +202,7 @@ export type Approval = {
     source: 'gate' | 'exec' | 'plugin' | 'question';
     member: Member;
     sessionKey?: string;
+    helper?: string;
     tool?: string;
     summary: string;
     input?: unknown;

package/package.json

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