@byokit/openclaw 0.1.4 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+- Depends on @byokit/relay 0.3.1.
+- Depends on @byokit/reach 0.4.0.
+- Depends on @byokit/link 0.5.0.
+- FIX: (from @byokit/link 0.5.0) `decodeOffer()` reads legacy compact direct pairing codes with checksum, padding, bounds and expiry validation; new encodings keep the complete current format.
+## 0.2.1 (2026-09-30)
+
+- Dependency update: pins @byokit/link 0.5.0, @byokit/reach 0.4.0 and @byokit/relay 0.3.1.
+
+## 0.2.0 (2026-09-30)
+
+- Full run options over the link (v1 A6): `oc.run` and `openclawDevice(link).run(message, o)` forward `system`,
+  `images`, `thinking` and `tools`, each type-checked. `RunSpec.tools` is the run's subset of the app's tools
+  (`KitOptions.tools` names, listed by the new `kit.toolNames()`): the bridge refuses any other app tool before
+  `ToolHost.gate` sees it, engine builtins are unaffected, and a name the kit does not register is refused before the
+  engine is called (over the link, `link.notAllowed`). The pinned engine takes no per-run tool list, so the model
+  still sees every tool; the gate is the enforcement. Runs sharing a session key share the narrowest subset.
+- Structured tool events (v1 A7): a `tool` `RunEvent` carries the engine's `id` (its toolCallId) on both ends, the
+  call's `input` on `start`, and the engine's `output` and `error` on `end`.
+- Usage (v1 A8): `RunEnd.ok` carries `usage` (`input`, `output`, `cacheRead`, `cacheWrite`, `reasoning`, `total`,
+  `costUsd`), the engine's own total for the run from the `agent` request's final frame, and `planWindow`
+  (`{ provider, plan?, windows: { label, usedPercent, resetAt? }[] }`), the engine's cached read of the
+  subscription's quota for the run's provider. Each is present only when the engine reports it; nothing is estimated.
+  New types `RunUsage` and `PlanWindow` (`.`, `./device`).
+- Presence and version (v1 A12, device side): `oc.state` (`openclawDevice(link).state()`, typed `DeviceState`) adds
+  `version` (this kit), `engine` (`ENGINE_VERSION`) and `signedIn`, the providers the device's member is usably
+  signed in to (not an expired or unfinished sign-in), absent while the engine can't say.
+- FIX: a run ending no longer drops another live run's registration on the same session key (its tool calls then
+  failed as an unknown run); a key stays registered until its last run ends. `Bridge.register` returns the release.
+- FIX: the engine's `update`, `input_delta` and `review` tool phases no longer end a tool pair early; only `result`
+  (or `end`) does.
+- Testing: the fake Gateway's runs are engine-shaped (`toolCallId`, `args`, `result`, `isError`; an `accepted` frame
+  and, with `expectFinal`, a final frame with `agentMeta.usage`), and the model stub ends a reply asked
+  `stream_options.include_usage` with a `STUB_USAGE` chunk (exported from `./testing`). `GatewayTransport.request`
+  options take `expectFinal` and `onAccepted`.
+
 ## 0.1.4 (2026-09-30)
 
 - Depends on @byokit/relay 0.3.0.

package/README.md

@@ -54,6 +54,14 @@ provider or model. If the member isn't signed in to it, the run ends `{ ok: fals
 engine is never called. Leave `model` out to keep the engine's own choice. A specific sign-in (`@profile`) can't be
 picked per run: the pinned engine may still switch to another sign-in for the same provider.
 
+A run spec also takes `system`, `images` (`{ data, mimeType }[]`), `thinking` and `tools`, a subset of the app tools
+(`KitOptions.tools` names) this run may call; any other app tool is refused at the gate before `ToolHost.gate` sees
+it. Tool events carry the engine's call `id`, the `input` on `start` and the `output` and `error` on `end`. A run that
+ends ok carries `usage` (the engine's token total for the run, and `costUsd` when it priced the model) and
+`planWindow` (the subscription's quota windows as the engine last read them), each only when the engine reports it.
+`openclawDevice(link).run(message, o)` takes the same options over the link, and `state()` adds the kit and engine
+versions and the providers the device's member is signed in to.
+
 The same kit runs offline against the fake Gateway from `@byokit/openclaw/testing` (no engine, no network, no
 account), and lists the sign-in routes it offers:
 
@@ -89,7 +97,7 @@ Its output, run from this repo with Node:
 state: ready | protocol: 4
 event: {"type":"text","text":"fake: Say hello."}
 event: {"type":"text","text":"fake: Say hello."}
-end: {"ok":true,"text":"fake: Say hello."}
+end: {"ok":true,"text":"fake: Say hello.","usage":{"input":10,"output":16,"total":26}}
 route: openai                     subscription browser
 route: openai-device-code         subscription code
 route: xai-oauth                  subscription code
@@ -113,9 +121,9 @@ 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`, `migrateRetainedLogin`, `confirmRetainedLogin`, `run`, `steer`, `abort`, `approvals`, `onApproval`, `decide`, `allowOnce`, `disallowOnce`, `patchConfig`, `memoryLimited`, `doctorContext` |
+| `OpenClawKit` (`.`) | Prepares, starts, supervises and stops the engine. `call` / `callDynamic` pass through to the Gateway, `onEvent` listens. Helpers: `ensureMember`, `routes`, `providers`, `signedIn`, `signIn`, `signOut`, `migrateRetainedLogin`, `confirmRetainedLogin`, `toolNames`, `run`, `steer`, `abort`, `approvals`, `onApproval`, `decide`, `allowOnce`, `disallowOnce`, `patchConfig`, `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`, `Route`, `Approval`, `Decision`, `ToolSpec`, `ToolHost`, `KitState`, ... (`.`) | Public types (docs/runtime-kits.md §5.2) |
+| `KitOptions`, `RunSpec`, `RunEvent`, `RunEnd`, `RunUsage`, `PlanWindow`, `Route`, `Approval`, `Decision`, `ToolSpec`, `ToolHost`, `KitState`, ... (`.`) | Public types (docs/runtime-kits.md §5.2) |
 | `openclawDevice(link)` (`./device`) | Portable client: state, routes, sign-in, runs, steer, abort, approvals, events, sealed notices, pass-through `call` |
 | `LinkRefused`, `openNotice` (`./device`) | The host's own refusal as an error; opens a sealed approval notice |
 | `words`, `stateWords`, `toAccountView` (`.`, `./device`) | The kit's sentences, so a phone shows the words the computer does; `toAccountView` feeds `@byokit/ui-core`'s `phaseOf` |

package/dist/bridge.d.ts

@@ -35,6 +35,7 @@ export declare class Bridge {
     private readonly onAskGone;
     private server?;
     private readonly runs;
+    private readonly live;
     private readonly permits;
     private readonly tickets;
     private armed;
@@ -51,7 +52,8 @@ export declare class Bridge {
     });
     start(): Promise<void>;
     stop(): void;
-    register(run: RunRef): void;
+    /** Register one run; the returned release ends only this registration (the key stays while another run holds it). */
+    register(run: RunRef, tools?: readonly string[]): () => void;
     unregister(sessionKey: string): void;
     allowOnce(rule: {
         keyPrefix: string;

package/dist/bridge.js

@@ -69,6 +69,9 @@ export class Bridge {
     onAskGone;
     server;
     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.
+    live = new Map();
     permits = new Map();
     tickets = [];
     armed;
@@ -111,11 +114,28 @@ export class Bridge {
         this.server = undefined;
         void rm(this.path, { force: true }).catch(() => { });
     }
-    register(run) {
+    /** Register one run; the returned release ends only this registration (the key stays while another run holds it). */
+    register(run, tools) {
         this.runs.set(run.sessionKey, run);
+        const entry = tools ? { tools: new Set(tools) } : {};
+        const list = this.live.get(run.sessionKey);
+        if (list)
+            list.push(entry);
+        else
+            this.live.set(run.sessionKey, [entry]);
+        return () => {
+            const now = this.live.get(run.sessionKey);
+            const at = now?.indexOf(entry) ?? -1;
+            if (!now || at < 0)
+                return;
+            now.splice(at, 1);
+            if (!now.length)
+                this.unregister(run.sessionKey);
+        };
     }
     unregister(sessionKey) {
         this.runs.delete(sessionKey);
+        this.live.delete(sessionKey);
         for (const [permit, p] of this.permits)
             if (p.key === sessionKey)
                 this.permits.delete(permit);
@@ -235,6 +255,9 @@ export class Bridge {
     async gateRun(socket, run, tool, input) {
         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)))
+            return this.deny(socket, 'this tool is not available in this run');
         let result;
         try {
             result = await this.host.gate(run, tool, input, { builtin: !this.tools.has(tool) });

package/dist/device.d.ts

@@ -2,7 +2,7 @@ import type { DeviceLink } from '@byokit/link';
 import { type AccountView } from './words.ts';
 import type { Approval, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, KitState, Route, RunEnd, RunEvent, SignInView } from './types.ts';
 export type { GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult } from './types.ts';
-export type { Approval, Decision, KitState, Route, RunEnd, RunEvent, SignInView } from './types.ts';
+export type { Approval, Decision, KitState, PlanWindow, Route, RunEnd, RunEvent, RunUsage, SignInView } 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]: {
@@ -19,6 +19,26 @@ export type SessionRow = {
     sessionKey: string;
     [k: string]: unknown;
 };
+/** `oc.run`'s options beside the message: the member's own session, account, and the kit's run options. */
+export type DeviceRunOptions = {
+    sessionKey?: string;
+    model?: string;
+    system?: string;
+    images?: {
+        data: string;
+        mimeType: string;
+    }[];
+    thinking?: 'off' | 'low' | 'medium' | 'high';
+    tools?: string[];
+};
+/** `oc.state`: the engine phase and words, this kit's and the engine's versions, and the device member's sign-ins. */
+export type DeviceState = {
+    state: KitState;
+    words: string;
+    version: string;
+    engine: string;
+    signedIn?: string[];
+};
 /**
  * The host ended a stream with its own words (e.g. a refusal). Portable twin of link's PublicLinkError:
  * same shape ({ code: 'failed', sealed: true }) so a screen can show .message the same way. A device-side
@@ -30,10 +50,7 @@ export declare class LinkRefused extends Error {
     constructor(message: string);
 }
 export declare function openclawDevice(link: DeviceLink): {
-    state(): Promise<{
-        state: KitState;
-        words: string;
-    }>;
+    state(): Promise<DeviceState>;
     routes(): Promise<Route[]>;
     signIn: {
         start(p: string, via: 'browser' | 'code'): Promise<SignInView>;
@@ -43,10 +60,7 @@ export declare function openclawDevice(link: DeviceLink): {
     };
     signOut(p: string): Promise<void>;
     sessions(): Promise<SessionRow[]>;
-    run(message: string, o?: {
-        sessionKey?: string;
-        model?: string;
-    }): AsyncIterable<RunEvent | {
+    run(message: string, o?: DeviceRunOptions): AsyncIterable<RunEvent | {
         type: 'end';
         end: RunEnd;
     }>;

package/dist/device.js

@@ -138,7 +138,9 @@ export function openclawDevice(link) {
         sessions: () => link.request('oc.sessions'),
         run: (message, o) => {
             const inner = liveStream(() => link.stream('oc.run', { message, ...(o?.sessionKey ? { sessionKey: o.sessionKey } : {}),
-                ...(o?.model !== undefined ? { model: o.model } : {}) }));
+                ...(o?.model !== undefined ? { model: o.model } : {}), ...(o?.system !== undefined ? { system: o.system } : {}),
+                ...(o?.images !== undefined ? { images: o.images } : {}), ...(o?.thinking !== undefined ? { thinking: o.thinking } : {}),
+                ...(o?.tools !== undefined ? { tools: o.tools } : {}) }));
             let finished = false;
             return {
                 [Symbol.asyncIterator]() {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.ts';
-export type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, Member, Route, RunEnd, RunEvent, RunRef, RunSpec, SignInView, ToolHost, ToolSpec, } from './types.ts';
+export type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, RunUsage, SignInView, ToolHost, ToolSpec, } from './types.ts';
 export { OpenClawKit, type KitOptions, type RetainedLogin } from './kit.ts';
 export { stateWords, toAccountView, words, type AccountView, type WordKey } from './words.ts';

package/dist/kit.d.ts

@@ -85,6 +85,8 @@ export declare class OpenClawKit {
     migrateRetainedLogin(member: Member, source: RetainedLogin): Promise<'staged' | 'nothing' | 'failed'>;
     confirmRetainedLogin(member: Member, source: RetainedLogin): Promise<boolean>;
     private runs;
+    /** The app tool names (`KitOptions.tools`): the only names `RunSpec.tools` may carry. */
+    toolNames(): string[];
     run(spec: RunSpec, on?: (e: RunEvent) => void): Promise<RunEnd>;
     steer(sessionKey: string, text: string): Promise<void>;
     abort(sessionKey: string): Promise<void>;

package/dist/kit.js

@@ -611,8 +611,13 @@ export class OpenClawKit {
             },
             ensure: (member) => this.ensureMember(member),
             bridge: this.bridge,
+            tools: new Set(this.toolNames()),
         });
     }
+    /** The app tool names (`KitOptions.tools`): the only names `RunSpec.tools` may carry. */
+    toolNames() {
+        return (this.o.tools ?? []).map((t) => t.name);
+    }
     run(spec, on) {
         return this.runs().run(spec, on);
     }

package/dist/link.js

@@ -1,14 +1,20 @@
 // Host-side link adapter (7.1): typed, member-checked ops over @byokit/link, sealed approval push
 // via the relay (7.3). Node only.
 import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { WebSocketServer } from 'ws';
 import { PublicLinkError, } from '@byokit/link';
 import { reach } from '@byokit/reach';
+import { ENGINE_VERSION } from "./constants.js";
 import { b64urlDecode, sealNotice } from "./notices.js";
 import { routeFor } from "./routes.js";
+import { signedInProviders } from "./runs.js";
 import { stateWords, words } from "./words.js";
 const VIEW_OPS = new Set(['oc.state', 'oc.routes', 'oc.signin.view', 'oc.sessions', 'oc.approvals', 'oc.events']);
+// This kit's own version, read once from its package.json (beside src/ and dist/ alike).
+const KIT_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const THINKING = new Set(['off', 'low', 'medium', 'high']);
 const refused = () => new PublicLinkError(words('link.notAllowed'));
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const memberKey = (member, sessionKey) => sessionKey.startsWith(`agent:${member}:`);
@@ -16,6 +22,27 @@ function memberSessions(result, member) {
     const rows = Array.isArray(result) ? result : isRecord(result) && Array.isArray(result.sessions) ? result.sessions : [];
     return rows.filter((row) => isRecord(row) && typeof row.sessionKey === 'string' && memberKey(member, row.sessionKey));
 }
+/** `oc.run`'s run options, type-checked; the kit's own checks (account, tool names) still apply. */
+function runOptions(args) {
+    const { message, model, system, images, thinking, tools } = args;
+    const ok = typeof message === 'string'
+        && (model === undefined || typeof model === 'string')
+        && (system === undefined || typeof system === 'string')
+        && (images === undefined || (Array.isArray(images) && images.every((i) => isRecord(i) && typeof i.data === 'string' && typeof i.mimeType === 'string')))
+        && (thinking === undefined || (typeof thinking === 'string' && THINKING.has(thinking)))
+        && (tools === undefined || (Array.isArray(tools) && tools.every((t) => typeof t === 'string')));
+    if (!ok)
+        throw new Error('oc.run needs { message, sessionKey?, model?, system?, images?, thinking?, tools? }');
+    return {
+        message: message,
+        ...(model === undefined ? {} : { model: model }),
+        ...(system === undefined ? {} : { system: system }),
+        ...(images === undefined ? {} : { images: images
+                .map((i) => ({ data: i.data, mimeType: i.mimeType })) }),
+        ...(thinking === undefined ? {} : { thinking: thinking }),
+        ...(tools === undefined ? {} : { tools: [...tools] }),
+    };
+}
 export function openclawLink(kit, o) {
     const passThrough = o.passThrough ?? (() => false);
     // Grants that have called, so sealed pushes and push actions can check the member (7.3).
@@ -69,14 +96,29 @@ export function openclawLink(kit, o) {
         return null;
     };
     const endReason = (error) => error instanceof PublicLinkError ? error.message.slice(0, 200) : 'failed';
+    const signIns = async (member) => {
+        try {
+            const { agentId } = await kit.ensureMember(member);
+            const status = await kit.call('models.authStatus', { agentId }, { timeoutMs: 5_000 });
+            return signedInProviders(status);
+        }
+        catch {
+            return undefined;
+        }
+    };
     const handle = async (req, grant) => {
         const member = memberOf(grant);
         if (grant.role === 'view' && !VIEW_OPS.has(req.op))
             throw refused();
         const args = isRecord(req.args) ? req.args : {};
         switch (req.op) {
-            case 'oc.state':
-                return { state: kit.state, words: stateWords(kit.state) };
+            case 'oc.state': {
+                // signedIn: the providers the device member is usably signed in to (an expired or unfinished sign-in is not),
+                // only while the engine can say: absent is unknown, never "none".
+                const signedIn = kit.state.phase === 'ready' ? await signIns(member) : undefined;
+                return { state: kit.state, words: stateWords(kit.state), version: KIT_VERSION, engine: ENGINE_VERSION,
+                    ...(signedIn ? { signedIn } : {}) };
+            }
             case 'oc.routes':
                 return kit.routes().filter((route) => route.offer);
             case 'oc.signin.start': {
@@ -190,19 +232,21 @@ export function openclawLink(kit, o) {
             if (grant.role === 'view')
                 throw refused();
             const args = isRecord(req.args) ? req.args : {};
-            if (typeof args.message !== 'string' || (args.model !== undefined && typeof args.model !== 'string'))
-                throw new Error('oc.run needs { message, sessionKey?, model? }');
+            const options = runOptions(args);
             const sessionKey = args.sessionKey === undefined ? `agent:${member}:link:${randomUUID()}` : args.sessionKey;
             if (typeof sessionKey !== 'string' || !memberKey(member, sessionKey))
                 throw refused();
+            // A tool the kit does not register is not this device's to name.
+            const known = new Set(kit.toolNames());
+            if (options.tools?.some((tool) => !known.has(tool)))
+                throw refused();
             // Ordered frames over the paced stream: each write waits for the last.
             let tail = Promise.resolve();
             const send = (frame) => {
                 tail = tail.then(() => s.write(`${JSON.stringify(frame)}\n`)).catch(() => { });
             };
             try {
-                const end = await kit.run({ member, sessionKey, message: args.message,
-                    ...(args.model === undefined ? {} : { model: args.model }) }, (e) => send(e));
+                const end = await kit.run({ member, sessionKey, ...options }, (e) => send(e));
                 send({ type: 'end', end });
                 await tail;
                 s.end();

package/dist/runs.d.ts

@@ -1,12 +1,18 @@
 import type { Bridge } from './bridge.ts';
 import type { GatewayTransport, Member, RunEnd, RunEvent, RunSpec } from './types.ts';
+/**
+ * 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;
 export declare function createRuns(ctx: {
     request: GatewayTransport['request'];
     onEvent: GatewayTransport['onEvent'];
     ensure(member: Member): Promise<{
         agentId: string;
     }>;
-    bridge: Pick<Bridge, 'register' | 'unregister'>;
+    bridge: Pick<Bridge, 'register'>;
+    tools: ReadonlySet<string>;
 }): {
     run(spec: RunSpec, on?: (e: RunEvent) => void): Promise<RunEnd>;
     steer(k: string, t: string): Promise<void>;

package/dist/runs.js

@@ -1,13 +1,58 @@
 // 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 { classify } from "./classify.js";
 // The gateway gives up on a silent run after an hour; we wait ten minutes longer for the reply frame itself.
 const WAIT_MS = 3_600_000;
 const WAIT_CLIENT_MS = 3_610_000;
+// The `agent` request's final frame lands with the run's end; a run already over waits no longer than this for it.
+const FINAL_GRACE_MS = 5_000;
+const STATUS_MS = 5_000;
 const USABLE = new Set(['ok', 'expiring', 'static']);
 const usable = (row) => typeof row === 'string'
     || (Array.isArray(row.profiles) && row.profiles.length > 0 ? row.profiles.some((p) => USABLE.has(String(p?.status)))
         : row.status === undefined || USABLE.has(String(row.status)));
+/**
+ * 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 function signedInProviders(status) {
+    const auth = (status ?? {});
+    if (auth.unavailable || !Array.isArray(auth.providers))
+        return undefined;
+    const names = auth.providers.filter((row) => row && usable(row))
+        .map((row) => (typeof row === 'string' ? row : row.provider))
+        .filter((name) => typeof name === 'string' && name !== '');
+    return [...new Set(names.map((name) => name.toLowerCase()))];
+}
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const count = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+/**
+ * The run's usage off the `agent` final frame's `result.meta.agentMeta` (pin: `usage` summed over the run, zero
+ * buckets and all-zero usage omitted; `costUsd` only when the engine has a price). Undefined when it reports none.
+ */
+function usageOf(agentMeta) {
+    const u = isRecord(agentMeta.usage) ? agentMeta.usage : {};
+    const usage = {};
+    for (const [from, to] of [['input', 'input'], ['output', 'output'], ['cacheRead', 'cacheRead'], ['cacheWrite', 'cacheWrite'],
+        ['reasoningTokens', 'reasoning'], ['total', 'total']])
+        if (count(u[from]))
+            usage[to] = u[from];
+    if (count(agentMeta.costUsd))
+        usage.costUsd = agentMeta.costUsd;
+    return Object.keys(usage).length ? usage : undefined;
+}
+/** The provider's quota windows from a `models.authStatus` row's `usage`, only when it lists at least one. */
+function planOf(provider, row) {
+    const usage = row?.usage;
+    if (!isRecord(usage) || !Array.isArray(usage.windows))
+        return undefined;
+    const windows = usage.windows.filter((w) => isRecord(w) && typeof w.label === 'string' && typeof w.usedPercent === 'number' && Number.isFinite(w.usedPercent))
+        .map((w) => ({ label: w.label, usedPercent: w.usedPercent, ...(count(w.resetAt) ? { resetAt: w.resetAt } : {}) }));
+    if (!windows.length)
+        return undefined;
+    return { provider, ...(typeof usage.plan === 'string' ? { plan: usage.plan } : {}), windows };
+}
 /**
  * The account a run names, `provider/model`, split for the `agent` request's per-run `provider`/`model` override.
  * Refused before any request when malformed or when it carries an `@profile` pin: the pin only reaches the engine as
@@ -20,15 +65,28 @@ function account(model) {
     return { provider: model.slice(0, at).toLowerCase(), model: model.slice(at + 1) }; // the engine lowercases ids
 }
 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.
+    const planWindowOf = async (agentId, provider) => {
+        try {
+            const auth = await ctx.request('models.authStatus', { agentId }, { timeoutMs: STATUS_MS });
+            const row = (auth.providers ?? []).find((e) => typeof e !== 'string' && e?.provider === provider);
+            return planOf(provider, row);
+        }
+        catch {
+            return undefined;
+        }
+    };
     const run = async (spec, on) => {
         // Member boundary first: a member never speaks in another member's session, refused before any request.
         if (!spec.sessionKey.startsWith(`agent:${spec.member}:`))
             throw new Error(`refused: "${spec.sessionKey}" is not a session of member "${spec.member}"`);
         const picked = spec.model === undefined ? undefined : account(spec.model);
+        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 { agentId } = await ctx.ensure(spec.member);
-        const registered = spec.register !== false;
-        if (registered)
-            ctx.bridge.register({ sessionKey: spec.sessionKey, member: spec.member });
+        const release = spec.register !== false ? ctx.bridge.register({ sessionKey: spec.sessionKey, member: spec.member }, spec.tools) : undefined;
         let last = '';
         let runId = ''; // gateway events for other runs carry a real runId and never match the empty one
         let ended = false;
@@ -49,8 +107,17 @@ export function createRuns(ctx) {
                 on?.({ type: 'text', text: p.data.text });
             }
             else if (p.stream === 'tool' && typeof p.data?.name === 'string') {
-                // The real engine marks completion `phase: 'result'` (O11); anything but `start` ends the pair.
-                on?.({ type: 'tool', name: p.data.name, phase: p.data.phase === 'start' ? 'start' : 'end' });
+                // The real engine marks completion `phase: 'result'` (O11). Its `update`, `input_delta` and `review` phases
+                // are progress inside the pair, not its end.
+                const d = p.data;
+                const end = d.phase === 'result' || d.phase === 'end';
+                if (d.phase !== 'start' && !end)
+                    return;
+                on?.({ type: 'tool', name: d.name, phase: end ? 'end' : 'start',
+                    ...(typeof d.toolCallId === 'string' ? { id: d.toolCallId } : {}),
+                    ...(!end && isRecord(d.args) ? { input: d.args } : {}),
+                    ...(end && d.result !== undefined ? { output: d.result } : {}),
+                    ...(end && typeof d.isError === 'boolean' ? { error: d.isError } : {}) });
             }
         });
         try {
@@ -68,7 +135,17 @@ export function createRuns(ctx) {
                 if (!row || !usable(row))
                     return { ok: false, kind: 'signed-out', message: `${picked.provider} is not signed in for ${spec.member}` };
             }
-            const started = await ctx.request('agent', {
+            // One `agent` request: its interim `accepted` frame names the run, its final frame (after the run) carries the
+            // run's usage. The wait below still decides how the run ended.
+            let accepted;
+            const ack = new Promise((resolve) => { accepted = resolve; });
+            // The run id is taken as the accepted frame lands, so no event read after it is missed.
+            const onAccepted = (payload) => {
+                if (isRecord(payload) && typeof payload.runId === 'string')
+                    runId = payload.runId;
+                accepted(payload);
+            };
+            const final = ctx.request('agent', {
                 agentId,
                 sessionKey: spec.sessionKey,
                 message: spec.message,
@@ -77,13 +154,21 @@ export function createRuns(ctx) {
                 ...(spec.system ? { extraSystemPrompt: spec.system } : {}),
                 ...(spec.images ? { attachments: spec.images.map((image) => ({ mimeType: image.mimeType, content: image.data })) } : {}),
                 ...(spec.thinking ? { thinking: spec.thinking } : {}),
-            });
+            }, { expectFinal: true, timeoutMs: WAIT_CLIENT_MS, onAccepted });
+            final.catch(() => { }); // a late failure is the wait's to report
+            const started = await Promise.race([ack, final]);
             runId = started.runId;
             const result = await ctx.request('agent.wait', { runId, timeoutMs: WAIT_MS }, { timeoutMs: WAIT_CLIENT_MS });
             if (result.status === 'ok') {
                 const text = typeof result.terminalReply?.text === 'string' ? result.terminalReply.text : last;
                 on?.({ type: 'text', text }); // the final cumulative text
-                return { ok: true, text };
+                const done = await Promise.race([final.catch(() => undefined), delay(FINAL_GRACE_MS, undefined, { ref: false })]);
+                const meta = isRecord(done) && isRecord(done.result) && isRecord(done.result.meta) ? done.result.meta : {};
+                const agentMeta = isRecord(meta.agentMeta) ? meta.agentMeta : {};
+                const usage = usageOf(agentMeta);
+                const planWindow = typeof agentMeta.provider === 'string'
+                    ? await planWindowOf(agentId, agentMeta.provider.toLowerCase()) : undefined;
+                return { ok: true, text, ...(usage ? { usage } : {}), ...(planWindow ? { planWindow } : {}) };
             }
             if (result.stopReason === 'aborted' || (abortedByEngine && result.status !== 'ok'))
                 return { ok: false, aborted: true };
@@ -98,8 +183,7 @@ export function createRuns(ctx) {
         finally {
             ended = true;
             unsubscribe();
-            if (registered)
-                ctx.bridge.unregister(spec.sessionKey);
+            release?.();
         }
     };
     return {

package/dist/testing/fake-gateway.js

@@ -144,34 +144,65 @@ export function fakeGateway(script) {
     const startRun = (params, bridgeSock) => {
         if (params.agentId != null && !agents.has(String(params.agentId)))
             throw new Error(`unknown agent: ${params.agentId}`);
-        const run = { runId: randomUUID(), sessionKey: String(params.sessionKey ?? ''), seq: 0, waiters: [] };
+        // Like the engine: the provider/model the run is called on, its own override or the member's (here openai).
+        const run = { runId: randomUUID(), sessionKey: String(params.sessionKey ?? ''), seq: 0,
+            provider: String(params.provider ?? 'openai'), model: String(params.model ?? 'gpt-5.1'), waiters: [] };
         runs.set(run.runId, run);
         const message = String(params.message ?? '');
         const text = `fake: ${message}`;
         setTimeout(() => {
             void (async () => {
                 const table = bridgeSock ? pluginTable(bridgeSock) : undefined;
+                let n = 0;
                 for (const call of toolCalls(message)) {
-                    emitRun(run, 'tool', { name: call.name, phase: 'start' });
+                    const toolCallId = `call-${++n}`;
+                    emitRun(run, 'tool', { phase: 'start', name: call.name, toolCallId, args: call.input });
                     // As the plugin: an engine builtin is gated unless the app opted out, and an allowed one never calls back.
                     const builtin = !!table && !table.tools.some((t) => t.name === call.name);
+                    let output = `${call.name} ran`;
+                    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 });
-                            if (gate.allow && !builtin)
-                                await bridgeRequest(bridgeSock, { kind: 'call', key: run.sessionKey, permit: gate.permit, tool: call.name, input: call.input });
+                            if (!gate.allow) {
+                                isError = true;
+                                output = String(gate.reason ?? 'blocked');
+                            }
+                            else if (!builtin) {
+                                const done = await bridgeRequest(bridgeSock, { kind: 'call', key: run.sessionKey, permit: gate.permit, tool: call.name, input: call.input });
+                                isError = done.ok !== true;
+                                output = String(done.ok === true ? done.text : done.reason);
+                            }
                         }
                         catch { /* no bridge or refused: the tool pair still plays, nothing is called */ }
                     }
-                    // Completion rides `phase: 'result'` like the real engine (O11), not `'end'`.
-                    emitRun(run, 'tool', { name: call.name, phase: 'result' });
+                    // Completion rides `phase: 'result'` like the real engine (O11), not `'end'`, with its result.
+                    emitRun(run, 'tool', { phase: 'result', name: call.name, toolCallId, isError,
+                        result: { content: [{ type: 'text', text: output }] } });
                 }
                 emitRun(run, 'assistant', { 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);
             })();
         }, 0);
-        return { runId: run.runId };
+        return { runId: run.runId, status: 'accepted' };
     };
+    /** The `agent` request's final frame (pin): the run's end with `result.meta.agentMeta`, once the run is over. */
+    const finalOf = (runId) => new Promise((resolve) => {
+        const run = runs.get(runId);
+        const settle = (result) => {
+            const ok = result.status === 'ok';
+            resolve({ runId, status: ok ? 'ok' : 'error', summary: ok ? 'completed' : 'failed',
+                ...(ok ? {} : { stopReason: result.stopReason }),
+                result: { payloads: ok ? [{ text: result.terminalReply?.text }] : [],
+                    meta: { agentMeta: { provider: run.provider, model: run.model, ...(run.usage ? { usage: run.usage } : {}) } } } });
+        };
+        if (run.result)
+            settle(run.result);
+        else
+            run.waiters.push(settle);
+    });
     const defaults = {
         health: () => ({ ok: true, plugins: { loaded: [] } }),
         'agents.list': () => ({
@@ -339,10 +370,16 @@ export function fakeGateway(script) {
                     throw new Error(closedWhy());
                 return hello();
             },
-            request: async (method, params) => {
+            request: async (method, params, o) => {
                 if (!entry.open)
                     throw new Error(closedWhy());
-                return dispatch(method, params, sock);
+                const reply = await dispatch(method, params, sock);
+                // expectFinal: the interim accepted frame goes to onAccepted, the request settles with the final one.
+                if (!o?.expectFinal || !isPlainObject(reply) || reply.status !== 'accepted' || typeof reply.runId !== 'string'
+                    || !runs.has(reply.runId))
+                    return reply;
+                o.onAccepted?.(reply);
+                return finalOf(reply.runId);
             },
             onEvent: (fn) => (entry.events.add(fn), () => entry.events.delete(fn)),
             onClose: (fn) => (entry.closes.add(fn), () => entry.closes.delete(fn)),

package/dist/testing/index.d.ts

@@ -1,3 +1,3 @@
 export { fakeGateway, type FakeScript } from './fake-gateway.ts';
 export { openclawContract, type ContractFixture } from './contract.ts';
-export { startModelStub, useModelStub, releaseStub, stubHolding, toolCalls, type ModelStub, type ModelStubOptions, type StubCall } from './model-stub.ts';
+export { STUB_USAGE, startModelStub, useModelStub, releaseStub, stubHolding, toolCalls, type ModelStub, type ModelStubOptions, type StubCall } from './model-stub.ts';

package/dist/testing/index.js

@@ -1,4 +1,4 @@
 // The kit's fakes, contract suite and scripted model (5.11). Built in O7.
 export { fakeGateway } from "./fake-gateway.js";
 export { openclawContract } from "./contract.js";
-export { startModelStub, useModelStub, releaseStub, stubHolding, toolCalls } from "./model-stub.js";
+export { STUB_USAGE, startModelStub, useModelStub, releaseStub, stubHolding, toolCalls } from "./model-stub.js";

package/dist/testing/model-stub.d.ts

@@ -4,6 +4,12 @@ export type StubCall = {
     path: string;
     body: any;
 };
+/** The token usage every stub reply reports when asked (`stream_options.include_usage`), per model call. */
+export declare const STUB_USAGE: {
+    readonly prompt_tokens: 11;
+    readonly completion_tokens: 7;
+    readonly total_tokens: 18;
+};
 export type ModelStub = {
     port: number;
     url: string;

package/dist/testing/model-stub.js

@@ -10,10 +10,13 @@
 //   ask permission       hold the turn (after its tool calls) until `releaseStub` lets it finish
 //   [route ID]           asked who should take a request: ID, fairly sure; [route ?]: torn evenly; neither: Chief, sure
 //   anything else        reply `stub <bot>: done with "<the last line of the message>"`
+// Every scripted reply that asks `stream_options.include_usage` ends with a usage chunk of STUB_USAGE, as OpenAI does.
 // The bot id (`idPattern`, default /Your id is ([a-z0-9-]+)\./) is read from the system prompt, and routing
 // requests start with `routingMarker` (default '[routing]'); pass both explicitly to mirror another app's grammar.
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
+/** The token usage every stub reply reports when asked (`stream_options.include_usage`), per model call. */
+export const STUB_USAGE = { prompt_tokens: 11, completion_tokens: 7, total_tokens: 18 };
 /** The tool calls in the script, each with its arguments. Braces are balanced, so a script may nest. */
 export function toolCalls(text) {
     const out = [];
@@ -126,9 +129,14 @@ export function startModelStub(script = [], o = {}) {
         const id = randomUUID();
         res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' });
         const send = (delta, finish = null) => res.write(`data: ${JSON.stringify({ id, object: 'chat.completion.chunk', created: Math.floor(Date.now() / 1000), model: body.model, choices: [{ index: 0, delta, finish_reason: finish }] })}\n\n`);
+        const usage = () => {
+            if (body.stream_options?.include_usage === true)
+                res.write(`data: ${JSON.stringify({ id, object: 'chat.completion.chunk', created: Math.floor(Date.now() / 1000), model: body.model, choices: [], usage: STUB_USAGE })}\n\n`);
+        };
         if (next) {
             send({ role: 'assistant', tool_calls: [{ index: 0, id: `call_${id}`, type: 'function', function: { name: next.name, arguments: JSON.stringify(next.input) } }] });
             send({}, 'tool_calls');
+            usage();
             return void res.end('data: [DONE]\n\n');
         }
         let text = queue.length ? queue.shift() : done();
@@ -141,6 +149,7 @@ export function startModelStub(script = [], o = {}) {
         }
         send({ role: 'assistant', content: text });
         send({}, 'stop');
+        usage();
         res.end('data: [DONE]\n\n');
     });
     return new Promise((resolve) => {

package/dist/types.d.ts

@@ -34,6 +34,7 @@ export interface RunSpec extends RunRef {
     }[];
     thinking?: 'off' | 'low' | 'medium' | 'high';
     model?: string;
+    tools?: string[];
     register?: boolean;
 }
 export type RunEvent = {
@@ -43,10 +44,36 @@ export type RunEvent = {
     type: 'tool';
     name: string;
     phase: 'start' | 'end';
+    id?: string;
+    input?: Record<string, unknown>;
+    output?: unknown;
+    error?: boolean;
+};
+/** Token usage of one run as the engine totals it (every model call of the run, compaction included). */
+export type RunUsage = {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    reasoning?: number;
+    total?: number;
+    costUsd?: number;
+};
+/** A subscription's quota windows, as the engine last read them from the provider (never estimated by the kit). */
+export type PlanWindow = {
+    provider: string;
+    plan?: string;
+    windows: {
+        label: string;
+        usedPercent: number;
+        resetAt?: number;
+    }[];
 };
 export type RunEnd = {
     ok: true;
     text: string;
+    usage?: RunUsage;
+    planWindow?: PlanWindow;
 } | {
     ok: false;
     aborted: true;
@@ -109,6 +136,8 @@ export interface GatewayTransport {
     request(method: string, params?: unknown, o?: {
         timeoutMs?: number;
         signal?: AbortSignal;
+        expectFinal?: boolean;
+        onAccepted?: (payload: unknown) => void;
     }): Promise<unknown>;
     onEvent(fn: (e: {
         event: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/openclaw",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "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",
@@ -51,9 +51,9 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/link": "0.4.0",
-    "@byokit/relay": "0.3.0",
-    "@byokit/reach": "0.3.0",
+    "@byokit/link": "0.5.0",
+    "@byokit/relay": "0.3.1",
+    "@byokit/reach": "0.4.0",
     "@byokit/seal": "0.2.0",
     "@openclaw/gateway-client": "2026.8.1",
     "@openclaw/gateway-protocol": "2026.8.1",