@byokit/openclaw 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## 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.

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, DelegatedRun, DelegatedEvent, RunSpec, OutputSchema, SchemaOutput, RunUsage, ThinkingAsked, ThinkingReport, ThinkingUsed, SignInOptions, SignInView, TelegramChannel, ToolHost, ToolSpec, } from './types.ts';
+export type { Account, AccountId, AccountPick, AccountRef, Approval, CallOptions, ChannelChat, ChannelMessage, Considered, Decision, Defaults, ModelInfo, MoveResult, PickWhy, Room, RoomSpan, RunSelection, SignInState, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, LearningCapture, LearningMode, Member, PlanWindow, Route, RunEnd, RunEvent, RunFrame, RunRef, 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,6 +64,8 @@ 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;

package/dist/kit.js

@@ -18,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';
@@ -442,6 +442,10 @@ 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).
@@ -948,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')
@@ -976,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();
@@ -1311,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,

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

@@ -4,14 +4,33 @@ 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;
@@ -32,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,7 +158,7 @@ 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}--`)))
@@ -351,8 +419,25 @@ export function createRuns(ctx) {
             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

@@ -80,6 +80,8 @@ export interface RunSpec<S extends OutputSchema | undefined = OutputSchema | und
     register?: boolean;
 }
 export type RunEvent = {
+    seq: number;
+} & ({
     type: 'started';
 } | {
     type: 'thinking';
@@ -103,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 = {

package/package.json

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