@byokit/openclaw 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## 0.6.2 (2026-10-05)
+
+FIX: The browser broker now holds its CDP endpoint back until Chromium's initial tab exists, so `/json/list` can never serve an empty browser to an attaching engine on a cold or slow start; a browser that never lists a tab fails the launch honestly instead.
+- Remove the fake Gateway's own happy-path self-tests for default member/auth and the device-code wizard script from `test/fake.test.ts`. They asserted the synthetic fixture's own response shapes and exact number of progress pulls, not product behaviour. Member creation, caching and validation, device-code sign-in through `kit.signIn`/`kit.signedIn`, `health` pass-through and sign-out remain covered by the shared public consumer contract (`src/testing/contract.ts`) and the packed Chromium journey in `examples/openclaw-kit/e2e.test.ts`. Every negative, cancellation, denial, gate, drop and refusal assertion is kept unchanged, and no test was added.
+- The quickstart's example output is what the example actually prints today: the offered-route list was stale
+  (it still showed `anthropic-cli` and a browser `setup-token` and missed `opencode-go`). The block is now the
+  real output of the runnable fake-Gateway example, followed by a "read next" pointer to the run contract, the
+  kit example and SECURITY.md.
+FIX: The sealed credential store now seals credential state only — the complete `state` tree plus config/credential paths under `home` — instead of the whole engine home, so a real signed-in home with tool caches no longer produces a sealed payload past the runtime string limit and aborts boot. Regenerable caches, transcripts and logs (`home/.cache`, `home/.npm`, and the `sessions`/`log`/`cache`/`.tmp`/`history.jsonl` subtrees of `.codex`, the `projects`/`todos`/`shell-snapshots`/`statsig`/`file-history`/`history.jsonl` subtrees of `.claude`) stay on disk unsealed; unknown `home` paths stay sealed. The sealed payload is built exactly once and verified by decrypting the sealed bytes. Existing `v: 1` snapshots still restore completely and re-seal once as `v: 2` with a log line; no credential is ever dropped.
+- Every type an entry hands a caller is now nameable from that entry, and none of them carries `any`.
+  `.` exports `GatewayMethods`, `RouteView`, `RouteFacts`, `JsonValue`, `UsageClient` and `DayUsageClient`;
+  `./device` exports `OpenClawDevice` and `DeviceEndFrame`; `./link` exports `OpenClawLinkOptions`,
+  `OpenClawLinkHost`, `OpenClawServeOptions` and `OpenClawServeHandle`; `./testing` exports `FakeGateway`,
+  `FakeHandler`, `FakeParams` and `StubRequest`, types `fakeGateway`'s script per method, and records each
+  stubbed request as a typed `StubRequest` instead of `any`. An app can write its own generic wrapper over
+  `call` and annotate what `routes()`, `openclawDevice()` and `openclawLink()` return without a cast. The
+  Gateway slots the pinned engine does not declare stay `unknown` and are listed per release in
+  `src/generated/report.json`; the README now says so beside the API table.
+
 ## 0.6.1 (2026-10-04)
 
 FIX: Let apps declare `appOwnedSessions.keyPrefixes` before Gateway startup so caller-requeued task sessions do not also receive an engine-started recovery turn. Preserve session history, policy gates, API-key session mapping and stock recovery for other namespaces.

package/README.md

@@ -288,17 +288,23 @@ 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.","usage":{"input":10,"output":16,"total":26}}
-route: openai                     subscription browser
-route: openai-device-code         subscription code
-route: xai-oauth                  subscription code
+route: setup-token                subscription setup_token
 route: github-copilot             subscription code
 route: github-copilot-enterprise  subscription code
 route: minimax-global-oauth       subscription code
 route: minimax-cn-oauth           subscription code
-route: anthropic-cli              subscription browser
-route: setup-token                subscription browser
+route: openai                     subscription browser
+route: openai-device-code         subscription code
+route: opencode-go                subscription plan_key
+route: xai-oauth                  subscription code
 ```
 
+The block above is the whole quickstart: copy it into a `.mts` file next to your app's
+`node_modules` and `node` it. No engine, no account, no network. Then read
+[the run contract](../../docs/runtime-kits.md#58-runs-members-and-streams) for retries and
+streams, [`examples/openclaw-kit`](../../examples/openclaw-kit) for a whole app, and
+[SECURITY.md](SECURITY.md) before you store anything the engine returns.
+
 Subscription sign-ins are offered by default. API-billed routes remain in `kit.routes()` with `offer: false`;
 apps can offer them when the app or person opts in, labelled API key (billed per use). Each `Route` carries `billing` (`subscription`, `api` or
 `local`) so the app can label what is billed. Proxy routes, compatibility aliases, local runtimes stay off. Native Claude Code sign-in is offered by default. The pinned Gateway guides only some routes; other choices need manual paste or key entry. For an opted-in route, allow its `plugin` id
@@ -319,12 +325,23 @@ Entries:
 | `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`, `getConfigKey`, `setConfigKey`, `memoryLimited`, `doctorContext` |
 | `ENGINE_VERSION`, `PROTOCOL_VERSION`, `OPERATOR_SCOPES` (`.`) | The pinned engine version, its protocol and the operator scopes the kit connects with |
 | `KitOptions`, `RunSpec`, `RunEvent`, `RunEnd`, `RunUsage`, `PlanWindow`, `Route`, `Approval`, `Decision`, `ToolSpec`, `ToolHost`, `KitState`, ... (`.`) | Public types (docs/runtime-kits.md §5.2) |
-| `openclawDevice(link)` (`./device`) | Portable client: state, routes, sign-in, runs, steer, abort, approvals, events, sealed notices, pass-through `call` |
+| `GatewayMethods`, `GatewayMethod`, `GatewayParams`, `GatewayResult`, `GatewayEventName`, `GatewayEventPayload` (`.`) | The generated pass-through tables, so an app can write its own generic wrapper over `call` / `onEvent` once |
+| `RouteView`, `RouteFacts`, `JsonValue`, `UsageClient`, `DayUsageClient` (`.`) | The types `routes()`, `routes(facts)` and the usage readers return or take, nameable without a cast |
+| `openclawDevice(link)` (`./device`) | Portable client: state, routes, sign-in, runs, steer, abort, approvals, events, sealed notices, pass-through `call`. `OpenClawDevice` and `DeviceEndFrame` name what it returns |
 | `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` |
-| `openclawLink(kit, o)` (`./link`) | `handle` / `stream` / `allow` for a `@byokit/link` `Host`, checked per member, plus `onAction` for relay push actions |
-| `serve(o)` (`./link`) | Binds the link host per reach and returns its URLs |
-| `fakeGateway`, `openclawContract`, `startModelStub`, `useModelStub` (`./testing`) | In-memory Gateway, the contract suite and the scripted model for tests |
+| `openclawLink(kit, o)` (`./link`) | `handle` / `stream` / `allow` for a `@byokit/link` `Host`, checked per member, plus `onAction` for relay push actions. `OpenClawLinkOptions` / `OpenClawLinkHost` name both sides |
+| `serve(o)` (`./link`) | Binds the link host per reach and returns its URLs (`OpenClawServeOptions` / `OpenClawServeHandle`) |
+| `fakeGateway`, `openclawContract`, `startModelStub`, `useModelStub` (`./testing`) | In-memory Gateway, the contract suite and the scripted model for tests. `fakeGateway`'s script is typed per method (`FakeScript`, `FakeHandler`), and a recorded `StubCall` carries a typed `StubRequest` |
+
+### What the pass-through cannot type
+
+Every method and event the pin publishes has a real type: `kit.call('sessions.list', params)` is checked in and
+returns the engine's declared result, with no cast. For the slots the pin itself leaves undeclared the table stays
+`unknown`, and `src/generated/report.json` names every one of them per release. On `openclaw@2026.8.1` that is 301
+of 393 methods' params and 192 of their results, plus 21 of 55 event payloads; the other slots are not missing from
+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.
 
 ## Owned browser (unqualified handoff)
 
@@ -419,8 +436,9 @@ Route data follows the shared account-route vocabulary (D18 in [`docs/runtime-ki
 
 The pinned engine has no supported hook for sealing OAuth profile writes. Its `auth-profiles` loader stores
 credential JSON in agent SQLite databases and a shared state database, and doctor imports leave migration
-archives. `authSeal` therefore protects the complete isolated `state` and `home` directories, including SQLite
-journals. It uses the injected `SealingAdapter` from `@byokit/secrets`. `osKeyringSeal()` automatically
+archives. `authSeal` therefore protects credential state — the complete isolated `state` tree plus
+config/credential paths under `home`, including SQLite journals — while regenerable tool caches,
+transcripts and logs stay on disk unsealed. It uses the injected `SealingAdapter` from `@byokit/secrets`. `osKeyringSeal()` automatically
 uses a persistent private file key for new stores when no non-interactive keyring is available.
 Opening follows the saved envelope's mode. A locked or unresponsive keyring-only store leaves
 `kit.state.phase === 'locked'`: `prepare()` and `start()` resolve, show `stateWords(kit.state)` for
@@ -461,7 +479,8 @@ every retained sealed migration archive before retiring an automatic key. Rotate
 separately; dual-wrap rotation retains old wrapping keys for backups.
 
 Without `authSeal`, engine credentials remain plaintext. With it, successful `prepare()` and `stop()` leave
-only a sealed snapshot, `auth-store.sealed`, for those directories. The adapter authenticates the snapshot
+only a sealed snapshot, `auth-store.sealed`, for the sealed credential paths; regenerable caches stay on
+disk unsealed. The adapter authenticates the snapshot
 before any restoration; a wrong key, tampering, or a missing adapter rejects. Files restored for the engine
 have mode 0600 and directories 0700. File symlinks are sealed only when their fully resolved targets are
 regular files inside the isolated engine root; they restore as regular files at the link paths. Outside-root,
@@ -474,7 +493,8 @@ inspection or a rewritten command line), another host is alive, or shutdown time
 `{ phase: 'failed', why: 'engine-already-running' }`; show `stateWords(kit.state)` and retry after the other
 session stops. Failed-start cleanup and `stop()` on an instance with no ownership preserve the other
 writer's pid, lock, sealed snapshot and live state.
-Sealing copies the whole store through memory, so startup and stop cost grows with session history.
+The sealed payload is built once and verified by decrypting the sealed bytes, so startup and stop cost
+grows with credential state, not session history.
 
 The migration doctor temporarily opens the same store and reseals it even when import fails. Once the gateway
 verifies every provider, `confirmRetainedLogin()` removes the explicitly passed legacy source and writes only

package/SECURITY.md

@@ -37,7 +37,7 @@ the replacement decrypts to identical contents. Other sealing failures still rej
 | Gateway token | `openclaw/token` | Random 32-byte bearer secret; newly created file is 0600. Treat it as operator access. |
 | Device identity | `openclaw/device.json` | Ed25519 private key stored as **unencrypted PKCS#8 PEM** in JSON, newly created 0600. The transport accepts both kit and legacy paired shapes without rewriting. Theft can impersonate the operator identity. |
 | Provider profiles | `openclaw/state/` and `openclaw/home/`, including agent/shared SQLite databases, journals and migration JSON | Access/refresh tokens or API keys are **plaintext while running**; without `authSeal` they also remain plaintext while stopped. Migration stages `auth-profiles.json` at 0600 in a newly created 0700 directory. Theft may authorize provider calls and refresh. |
-| Sealed credential snapshot | `openclaw/auth-store.sealed` and retired `*.sealed` archives | With host-injected `authSeal`, authenticates and encrypts the complete state/home trees while stopped. Key security belongs to the adapter/host; an older authentic snapshot can be replayed. |
+| Sealed credential snapshot | `openclaw/auth-store.sealed` and retired `*.sealed` archives | With host-injected `authSeal`, authenticates and encrypts credential state (the complete `state` tree plus config/credential paths under `home`) while stopped; regenerable caches stay on disk unsealed. Key security belongs to the adapter/host; an older authentic snapshot can be replayed. |
 | Saved configuration, logs and sessions | `openclaw/openclaw.json`, `logs/`, engine state | May contain app-supplied keys, prompts, tool inputs, sign-in URLs/codes or provider diagnostics. Treat the whole tree as secret. Engine stdout/stderr is appended to a newly created 0600 log; it is not a guaranteed credential-redaction layer. |
 | Notice seed and decrypted approvals | Device app storage and memory | The app stores the 32-byte seed; the kit receives it only for key derivation/decryption. Seed theft exposes notices for its box key. |
 
@@ -48,8 +48,8 @@ collects regular files and file symlinks whose fully resolved targets are regula
 files within the isolated engine root; links restore as regular files at the link
 paths. Outside-root, dangling and directory links, sockets, FIFOs and devices are
 skipped without reading their contents. Collected POSIX modes are normalized;
-other paths still need host protection. Skipped entries are not preserved in the
-snapshot and are removed with the live trees after successful sealing. Never use a shared/writable tree or point
+other paths still need host protection. Excluded caches are not preserved in the
+snapshot and stay on disk unsealed after successful sealing; other skipped entries are not preserved in the snapshot. Never use a shared/writable tree or point
 the kit at another product's state. Review existing permissions before adopting a
 tree; use an OS-protected app directory, encrypted disk and restricted backups.
 Do not log `doctorContext().env`, transport arguments, auth records or sign-in
@@ -57,8 +57,8 @@ callbacks. JavaScript strings and engine memory are not reliably zeroized.
 
 The engine needs plaintext credentials and PEM during operation. With `authSeal`
 (a host-injected `SealingAdapter` from `@byokit/secrets`), `src/auth-store.ts` seals
-all of state/home, including SQLite journals, on successful `prepare()` and after
-the engine exits on `stop()`. It verifies the adapter round-trip, writes via an
+credential state — the complete `state` tree plus config/credential paths under `home`, including SQLite journals — on successful `prepare()` and after
+the engine exits on `stop()`, while regenerable caches stay on disk unsealed. It verifies the adapter round-trip, writes via an
 exclusive temporary file, fsyncs/renames the snapshot and verifies it again before
 removing live plaintext. `start()` authenticates and validates snapshot paths before
 restoring files. Missing/wrong keys or tampering reject without plaintext fallback.
@@ -69,7 +69,7 @@ orderly shutdown. An abrupt host exit can leave live plaintext; the next prepare
 seals leftovers only after the orphan writer has exited. Interrupted restore or
 removal recovers from the authenticated snapshot. A sealing failure retains
 recoverable files and rejects; the host must resolve it and retry. Snapshot size
-and memory cost grow with the complete state/home trees. Keys, gateway token,
+and memory cost grow with sealed credential state; the payload is built once and excluded caches never enter it. Keys, gateway token,
 device PEM, inline config secrets, logs, install/cache files and app workspaces
 are outside this seal. OS-keyring or host-key adapters must keep the key separate
 from state/backups. There is no rollback protection. File removal cannot erase old

package/dist/auth-store.d.ts

@@ -1,4 +1,6 @@
 import type { SealingAdapter } from '@byokit/secrets';
+/** True for the regenerable cache paths the collector never seals; tests assert these are all that stay at rest. */
+export declare function cached(name: string): boolean;
 export declare class AuthStore {
     private active;
     private owned;
@@ -20,6 +22,10 @@ export declare class AuthStore {
     private release;
     private read;
     private collect;
+    /** Remove the live credential trees: `state` entirely (it is all credential state, including the
+     *  runtime entries the collector skips), and in `home` exactly the sealed paths — regenerable caches
+     *  and the directories still holding them are left in place. */
+    private remove;
     private persist;
     private restore;
     archives(): Promise<void>;

package/dist/auth-store.js

@@ -1,6 +1,8 @@
 // The pin persists OAuth JSON in both shared and agent SQLite. There is no public persistence hook.
-// Seal the complete isolated stores, including journals, only after their writer has exited.
-import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, closeSync, fsyncSync, openSync } from 'node:fs';
+// Seal only credential state — the engine's complete `state` tree plus every config/credential path in
+// `home` — never the regenerable tool caches, transcripts and logs a signed-in home accumulates.
+// Sealing those too once produced a snapshot past the runtime string limit and aborted boot.
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync, closeSync, fsyncSync, openSync } from 'node:fs';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { EngineAlreadyRunningError, pidAlive as live } from "./engine-status.js";
 const encoder = new TextEncoder();
@@ -45,13 +47,27 @@ function put(path, bytes) {
         rmSync(tmp, { force: true });
     }
 }
+// Credential state is what restores a working signed-in session. Regenerable tool caches, transcripts
+// and logs never do: the XDG cache and npm cache homes the kit's engine environment pins, plus the
+// transcript/log/cache subtrees of the Codex and Claude Code CLIs it runs in `home`. Unknown paths stay
+// sealed — a credential location we do not know about must fail loudly, never drop silently.
+const HOME_CACHES = {
+    home: ['.cache', '.npm'],
+    'home/.codex': ['sessions', 'log', 'cache', '.tmp', 'history.jsonl'],
+    'home/.claude': ['projects', 'todos', 'shell-snapshots', 'statsig', 'file-history', 'history.jsonl'],
+};
+/** True for the regenerable cache paths the collector never seals; tests assert these are all that stay at rest. */
+export function cached(name) {
+    const parent = name.includes('/') ? name.slice(0, name.lastIndexOf('/')) : '';
+    return (HOME_CACHES[parent] ?? []).includes(name.slice(name.lastIndexOf('/') + 1));
+}
 function safePath(path) {
     return typeof path === 'string' && /^(state|home)(\/[^/]+)*$/.test(path)
         && !path.split('/').some((part) => part === '.' || part === '..' || part.includes('\\') || part.includes('\0'));
 }
 function snapshot(text) {
     const s = JSON.parse(text);
-    if (s?.v !== 1 || !Array.isArray(s.dirs) || !Array.isArray(s.files))
+    if ((s?.v !== 1 && s?.v !== 2) || !Array.isArray(s.dirs) || !Array.isArray(s.files))
         throw new Error('invalid sealed credential store');
     const paths = new Set();
     for (const path of s.dirs) {
@@ -169,10 +185,12 @@ export class AuthStore {
         return saved;
     }
     collect() {
-        const s = { v: 1, dirs: [], files: [] };
+        const s = { v: 2, dirs: [], files: [] };
         const root = realpathSync(this.o.root);
         const walk = (path) => {
             const name = relative(this.o.root, path).split('\\').join('/');
+            if (cached(name))
+                return; // tool caches are never credential state; skipping a directory skips its subtree
             const stat = lstatSync(path);
             if (stat.isDirectory()) {
                 chmodSync(path, 0o700);
@@ -208,31 +226,56 @@ export class AuthStore {
                 walk(join(this.o.root, dir));
         return s;
     }
+    /** Remove the live credential trees: `state` entirely (it is all credential state, including the
+     *  runtime entries the collector skips), and in `home` exactly the sealed paths — regenerable caches
+     *  and the directories still holding them are left in place. */
+    remove(s) {
+        rmSync(join(this.o.root, 'state'), { recursive: true, force: true });
+        for (const [path] of s.files)
+            if (path.startsWith('home/'))
+                rmSync(join(this.o.root, path), { force: true });
+        for (const path of [...s.dirs].sort((a, b) => b.split('/').length - a.split('/').length)) {
+            if (!path.startsWith('home/'))
+                continue;
+            try {
+                rmdirSync(join(this.o.root, path));
+            }
+            catch (error) {
+                const code = error.code;
+                if (code !== 'ENOTEMPTY' && code !== 'ENOENT')
+                    throw error; // a directory still holding caches stays
+            }
+        }
+    }
     async persist() {
         if (!this.o.seal)
             return;
         // Always authenticate an earlier snapshot before considering a leftover live store after a crash.
         const previous = await this.read();
         if (previous && (existsSync(this.cleanup) || existsSync(this.restoring))) {
-            for (const dir of ['state', 'home'])
-                rmSync(join(this.o.root, dir), { recursive: true, force: true });
+            this.remove(previous);
             removeMarker(this.cleanup);
             removeMarker(this.restoring);
             this.o.log?.('interrupted credential transition recovered');
         }
-        const hasLive = ['state', 'home'].some((dir) => existsSync(join(this.o.root, dir)));
-        if (!hasLive && previous)
+        const saved = this.collect();
+        // Live trees with nothing sealable are debris (crash leftovers, or only the caches a previous stop
+        // left in place) — keep the sealed credentials instead of replacing them with an empty snapshot.
+        // A running engine always leaves files behind (its SQLite stores), so a genuine sign-out still re-seals.
+        if (!saved.files.length && previous)
             return;
-        const text = JSON.stringify(this.collect());
-        const sealed = this.o.seal.encryptString(text);
-        if (this.o.seal.decryptString(Buffer.from(sealed)) !== text)
+        // The payload is built exactly once; verification decrypts the sealed bytes and compares to it.
+        const payload = JSON.stringify(saved);
+        const sealed = this.o.seal.encryptString(payload);
+        if (this.o.seal.decryptString(Buffer.from(sealed)) !== payload)
             throw new Error('credential seal verification failed');
         put(this.file, sealed);
-        if (this.o.seal.decryptString(readFileSync(this.file)) !== text)
+        if (this.o.seal.decryptString(readFileSync(this.file)) !== payload)
             throw new Error('credential seal verification failed');
+        if (previous?.v === 1)
+            this.o.log?.('sealed credential store re-sealed: tool caches no longer sealed');
         put(this.cleanup, encoder.encode('1'));
-        for (const dir of ['state', 'home'])
-            rmSync(join(this.o.root, dir), { recursive: true, force: true });
+        this.remove(saved);
         removeMarker(this.cleanup);
     }
     async restore() {

package/dist/browser/broker.js

@@ -668,10 +668,23 @@ export async function launchBroker(o) {
         await send('Browser.getVersion');
         await send('Browser.setDownloadBehavior', { behavior: 'deny', eventsEnabled: false });
         await send('Target.setDiscoverTargets', { discover: true });
-        const result = await send('Target.getTargets');
-        for (const t of result.targetInfos)
-            targets.set(t.targetId, t);
-        lastAgent = result.targetInfos.find(t => t.type === 'page')?.targetId;
+        // Chromium creates the initial tab after the pipe already answers, so a cold start can list zero
+        // page targets here. Never expose the endpoint before the agent tab exists: a discovery /json/list
+        // would honestly report an empty browser and break every engine that lists targets at attach.
+        const tabUntil = Date.now() + 30_000;
+        let pages = [];
+        for (;;) {
+            const result = await send('Target.getTargets');
+            for (const t of result.targetInfos)
+                targets.set(t.targetId, t);
+            pages = result.targetInfos.filter(t => t.type === 'page');
+            if (pages.length > 0 || Date.now() >= tabUntil)
+                break;
+            await new Promise(resolve => setTimeout(resolve, 25));
+        }
+        lastAgent = pages[0]?.targetId;
+        if (!lastAgent)
+            throw failure();
         await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', () => resolve()); });
         port = server.address().port;
     }

package/dist/day-usage.d.ts

@@ -69,8 +69,10 @@ export type AgentDayUsage = {
 export declare function engineStartedOf(raw: unknown, member: Member, window: AgentDayUsage['window']): AgentDayUsage['engineStarted'] & {
     complete: boolean;
 };
-/** Read the transcript and Workshop terms independently. A failed term never becomes zero. */
-export declare function readAgentDayUsage(client: {
+/** What `readAgentDayUsage` needs from a reader: the kit's `call` plus its own string-typed RPC. */
+export type DayUsageClient = {
     callDynamic(method: string, params?: unknown): Promise<unknown>;
     call(method: 'sessions.usage', params: SessionsUsageParams): Promise<unknown>;
-}, member: Member, window: AgentDayUsage['window']): Promise<AgentDayUsage>;
+};
+/** Read the transcript and Workshop terms independently. A failed term never becomes zero. */
+export declare function readAgentDayUsage(client: DayUsageClient, member: Member, window: AgentDayUsage['window']): Promise<AgentDayUsage>;

package/dist/device.d.ts

@@ -27,7 +27,8 @@ export type SessionRow = {
     sessionKey: string;
     [k: string]: unknown;
 };
-type EndFrame<T = unknown> = {
+/** The frame `oc.run`'s stream ends with: the run's `RunEnd`, beside its events. */
+export type DeviceEndFrame<T = unknown> = {
     type: 'end';
     end: RunEnd<T>;
 };
@@ -78,7 +79,8 @@ export type SignInNotice = {
 export declare function openSignInNotice(data: Record<string, unknown>, seed: Uint8Array): SignInNotice | null;
 /** Transient streams bypass link's durable request/answer cache: no lease nonce or frame is persisted. */
 export declare function browserDevice(link: DeviceLink): BrowserDevice;
-export declare function openclawDevice(link: DeviceLink): {
+/** `openclawDevice`'s device surface: every `oc.*` op the computer answers, typed. */
+export type OpenClawDevice = {
     browser: BrowserDevice;
     state(): Promise<DeviceState>;
     routes(): Promise<RouteView[]>;
@@ -90,7 +92,7 @@ export declare function openclawDevice(link: DeviceLink): {
     };
     signOut(p: string): Promise<void>;
     sessions(): Promise<SessionRow[]>;
-    run<const S extends OutputSchema | undefined = undefined>(message: string, o?: DeviceRunOptions<S>): AsyncIterable<RunEvent | EndFrame<SchemaOutput<S>>>;
+    run<const S extends OutputSchema | undefined = undefined>(message: string, o?: DeviceRunOptions<S>): AsyncIterable<RunEvent | DeviceEndFrame<SchemaOutput<S>>>;
     steer(k: string, t: string, o?: {
         auth?: 'apiKey';
     }): Promise<void>;
@@ -105,6 +107,7 @@ export declare function openclawDevice(link: DeviceLink): {
     call<M extends GatewayMethod>(method: M, params: GatewayParams<M>): Promise<GatewayResult<M>>;
     callDynamic(method: string, params?: unknown): Promise<unknown>;
 };
+export declare function openclawDevice(link: DeviceLink): OpenClawDevice;
 export { openNotice } from './notices.ts';
 export { readAgentUsage, agentUsageOf } from './usage.ts';
 export { readAgentDayUsage } from './day-usage.ts';

package/dist/index.d.ts

@@ -1,11 +1,14 @@
 export { ENGINE_VERSION, OPERATOR_SCOPES, PROTOCOL_VERSION } from './constants.ts';
 export type { Approval, CallOptions, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, GatewayTransport, GateResult, Hello, KitState, KitEventName, KitEventPayload, BrowserPing, Member, PlanWindow, Route, RunEnd, RunEvent, RunRef, RunSpec, OutputSchema, SchemaOutput, RunUsage, SignInOptions, SignInView, 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';
 export { OpenClawKit, type KitOptions, type RetainedLogin } from './kit.ts';
 export type { AddKeyResult } from './keys.ts';
 export { stateWords, toAccountView, words, type AccountView, type WordKey } from './words.ts';
 export { EngineAlreadyRunningError } from './engine-status.ts';
 export { readAgentDayUsage } from './day-usage.ts';
-export type { AgentDayUsage, EngineStartedCharge, EngineStartedKind } from './day-usage.ts';
+export type { AgentDayUsage, DayUsageClient, EngineStartedCharge, EngineStartedKind } from './day-usage.ts';
 export { readAgentUsage, agentUsageOf } from './usage.ts';
-export type { AgentUsageReading, LedgerUsageTotals, UsageCache, UsageWindow } from './usage.ts';
+export type { AgentUsageReading, LedgerUsageTotals, UsageCache, UsageClient, UsageWindow } from './usage.ts';
 export type { LiveSource, BrowserState, SignInMethodHint, SignInReason, SignInChoice, SettledState, SettledReason, ResumeState, NeedSignIn, TakeoverLease, LiveViewState, LiveFrame, LiveInput, ThumbnailResult, SignInRefusedWhy, BrowserOptions, SiteVerifier, BrowserHost, BrowserDevice } from './browser.ts';

package/dist/link.d.ts

@@ -5,23 +5,31 @@ import { type ServeIngress, type Via } from '@byokit/reach';
 import type { PushAction, RelayClient } from '@byokit/relay';
 import type { OpenClawKit } from './kit.ts';
 import type { Member } from './types.ts';
-export declare function openclawLink(kit: OpenClawKit & {
-    browser?: BrowserHost;
-}, o: {
+/** `openclawLink`'s options: which member a grant acts for, the D8 pass-through predicate, sealed relay push. */
+export type OpenClawLinkOptions = {
     memberOf: (grant: Grant) => Member | undefined;
     passThrough?: (method: string, grant: Grant) => boolean;
     relay?: RelayClient;
-}): Pick<HostOptions, 'handle' | 'stream' | 'allow' | 'onGrantRemoved'> & {
+};
+/** What `openclawLink` hands the link host: its request/stream handlers plus the kit's push entry point. */
+export type OpenClawLinkHost = Pick<HostOptions, 'handle' | 'stream' | 'allow' | 'onGrantRemoved'> & {
     onAction(a: PushAction): Promise<unknown>;
 };
-export declare function serve(o: {
+export declare function openclawLink(kit: OpenClawKit & {
+    browser?: BrowserHost;
+}, o: OpenClawLinkOptions): OpenClawLinkHost;
+/** `serve`'s options: the link host to accept on, and the ingress to publish or replace. */
+export type OpenClawServeOptions = {
     host: Host;
     port: number;
     via?: Via;
     previous?: ServeIngress;
     http?: (req: IncomingMessage, res: ServerResponse) => void;
-}): Promise<{
+};
+/** The running ingress: its urls, the entry that reaches the engine, and an orderly close. */
+export type OpenClawServeHandle = {
     urls: string[];
     ingress?: ServeIngress;
     close(): Promise<void>;
-}>;
+};
+export declare function serve(o: OpenClawServeOptions): Promise<OpenClawServeHandle>;

package/dist/link.js

@@ -618,8 +618,6 @@ export function openclawLink(kit, o) {
     };
     return { handle, stream, allow: () => true, onAction, onGrantRemoved: grant => revoke(grant.id) };
 }
-// ponytail: this ~40-line serve() wiring is deliberately duplicated per runtime kit (D3);
-// extract it into a shared package when a third runtime kit appears.
 export async function serve(o) {
     const r = await reach({ port: o.port, via: o.via, previous: o.previous });
     const server = createServer(o.http ??

package/dist/testing/contract.js

@@ -10,8 +10,7 @@ import assert from 'node:assert/strict';
 import { PROTOCOL_VERSION } from "../constants.js";
 import { GATEWAY_CAPS } from "../transport.js";
 import { releaseStub, stubHolding } from "./model-stub.js";
-// The generated method table arrives with O2; until then kit.call's typed surface accepts no method names, so the
-// suite drives pass-through through this string-typed view of the same runtime path.
+/** The contract drives pass-through by method name, so results arrive untyped and are narrowed per case. */
 const call = (kit, method, params) => kit.call(method, params);
 const REQUIRED_METHODS = [
     'agent', 'agent.wait', 'agents.create', 'agents.list', 'chat.abort', 'config.get', 'config.patch',

package/dist/testing/fake-gateway.d.ts

@@ -1,9 +1,16 @@
-import type { GatewayTransport } from '../types.ts';
+import type { GatewayMethod, GatewayParams, GatewayTransport } from '../types.ts';
 import type { KitOptions } from '../kit.ts';
-type Handler = (params: any, bridgeSock: string) => unknown;
-/** Pre-registered handlers for `fakeGateway(script)`, on top of the defaults (a same-name entry replaces one). */
-export type FakeScript = Record<string, Handler>;
-export declare function fakeGateway(script?: FakeScript): {
+/** A scripted handler's params: the generated type when the pin publishes one, else the raw params object. */
+export type FakeParams<M extends GatewayMethod> = unknown extends GatewayParams<M> ? Record<string, unknown> : GatewayParams<M>;
+/** A scripted handler for one method, with that method's params typed. */
+export type FakeHandler<M extends GatewayMethod = GatewayMethod> = (params: FakeParams<M>, bridgeSock: string) => unknown;
+/** Pre-registered handlers for `fakeGateway(script)`, on top of the defaults (a same-name entry replaces one).
+ * Only methods the pinned engine publishes are scriptable, exactly as `kit.call` and `kit.callDynamic` divide them. */
+export type FakeScript = {
+    [M in GatewayMethod]?: FakeHandler<M>;
+};
+/** The fake's control surface: the transport to hand a kit, the calls it saw, and its triggers. */
+export type FakeGateway = {
     factory: NonNullable<KitOptions['transport']>;
     calls: {
         method: string;
@@ -12,8 +19,8 @@ export declare function fakeGateway(script?: FakeScript): {
     emit(event: string, payload?: unknown): void;
     failNext(method: string, message: string): void;
     drop(why: string): void;
-    handle(method: string, fn: Handler): void;
+    handle(method: string, fn: FakeHandler): void;
 } & {
     transport: GatewayTransport;
 };
-export {};
+export declare function fakeGateway(script?: FakeScript): FakeGateway;

package/dist/testing/fake-gateway.js

@@ -245,12 +245,12 @@ export function fakeGateway(script) {
         'openclaw.setup.activate': (p) => {
             if (p.kind !== 'api-key')
                 throw new Error('only the API-key setup path is simulated');
-            const route = routes().find((r) => r.choice === p.authChoice && r.keyEntry);
+            const route = routes().find((r) => r.choice === String(p.authChoice) && r.keyEntry);
             if (!route)
                 return { ok: false, status: 'unavailable' };
             const model = `${route.provider}/fake-key-model`;
-            keys.set(p.agentId, { provider: route.provider, key: p.apiKey, model, sealed: false });
-            signInAgent(p.agentId, route.provider);
+            keys.set(String(p.agentId), { provider: route.provider, key: String(p.apiKey), model, sealed: false });
+            signInAgent(String(p.agentId), route.provider);
             return { ok: true, status: 'ok', modelRef: model };
         },
         'openclaw.setup.auth.start': (p) => {
@@ -325,14 +325,15 @@ export function fakeGateway(script) {
         'exec.approval.request': (p) => {
             const id = String(p.id ?? `exec-${randomUUID()}`);
             const now = Date.now();
+            const plan = isPlainObject(p.systemRunPlan) ? p.systemRunPlan : {};
             emit('exec.approval.requested', {
                 approvalKind: 'exec', id, createdAtMs: now, expiresAtMs: now + 180_000,
                 request: {
                     command: p.command,
                     // Like the real engine, which normalizes the exec policy mode into request.ask (B8).
                     ask: p.ask ?? 'on-miss',
-                    agentId: p.agentId ?? p.systemRunPlan?.agentId,
-                    sessionKey: p.sessionKey ?? p.systemRunPlan?.sessionKey,
+                    agentId: p.agentId ?? plan.agentId,
+                    sessionKey: p.sessionKey ?? plan.sessionKey,
                 },
             });
             return { id };
@@ -366,6 +367,7 @@ export function fakeGateway(script) {
     };
     for (const [method, handler] of Object.entries(defaults))
         handlers.set(method, handler);
+    // A script handler is already per-method typed; the loose internal map only dispatches it.
     for (const [method, handler] of Object.entries(script ?? {}))
         handlers.set(method, handler);
     const dispatch = async (method, params, bridgeSock) => {
@@ -377,7 +379,7 @@ export function fakeGateway(script) {
         const handler = handlers.get(method);
         if (!handler)
             throw new Error(`unknown method: ${method}`);
-        return await handler(params ?? {}, bridgeSock);
+        return await handler(isPlainObject(params) ? params : {}, bridgeSock);
     };
     const hello = () => ({
         protocol: PROTOCOL_VERSION,

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-export { fakeGateway, type FakeScript } from './fake-gateway.ts';
+export { fakeGateway, type FakeGateway, type FakeHandler, type FakeParams, type FakeScript } from './fake-gateway.ts';
 export { fakeBrowserHost, createBrowserHostFake, browserHostContract, memorySignInStore, type FakeBrowserHost, type FakeBrowserHostOptions, type BrowserFixture } from './browser.ts';
 export { openclawContract, type ContractFixture } from './contract.ts';
-export { STUB_USAGE, 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, type StubRequest } from './model-stub.ts';

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

@@ -1,8 +1,21 @@
 import type { OpenClawKit } from '../kit.ts';
+export type StubRequest = {
+    model?: unknown;
+    input?: unknown;
+    messages?: {
+        role?: string;
+        content?: unknown;
+        name?: unknown;
+        tool_call_id?: unknown;
+    }[];
+    stream_options?: {
+        include_usage?: boolean;
+    };
+};
 export type StubCall = {
     authorization: string;
     path: string;
-    body: any;
+    body: StubRequest;
 };
 /** The token usage every stub reply reports when asked (`stream_options.include_usage`), per model call. */
 export declare const STUB_USAGE: {

package/dist/testing/model-stub.js

@@ -58,7 +58,8 @@ export const releaseStub = (key, reply = '') => {
         }
 };
 export const stubHolding = (key) => (key ? holds.has(key) : holds.size > 0);
-const words = (m) => typeof m?.content === 'string' ? m.content : Array.isArray(m?.content) ? m.content.map((c) => c.text ?? '').join('') : '';
+const words = (m) => typeof m?.content === 'string' ? m.content : Array.isArray(m?.content)
+    ? m.content.map((c) => (typeof c?.text === 'string' ? c.text : '')).join('') : '';
 export function startModelStub(script = [], o = {}) {
     const calls = [];
     const queue = [...script];
@@ -97,7 +98,7 @@ export function startModelStub(script = [], o = {}) {
         const phrased = (text) => /hit the limit|no helpers in plan|sign me out|ask permission/i.test(text);
         const lastUser = [...users].reverse().find((m) => structural(words(m)))
             ?? [...users].reverse().find((m) => phrased(words(m)))
-            ?? users.at(-1);
+            ?? users.at(-1) ?? {};
         const said = words(lastUser);
         const anchor = messages.lastIndexOf(lastUser);
         const results = anchor < 0 ? [] : messages.slice(anchor + 1).filter((m) => m.role === 'tool');
@@ -113,7 +114,7 @@ export function startModelStub(script = [], o = {}) {
         if (said.startsWith(routingMarker)) {
             const options = [...said.matchAll(/^- ([a-z0-9-]+):/gm)].map((m) => m[1]);
             const pick = /\[route ([a-z0-9-]+|\?)\]/.exec(said)?.[1] ?? 'chief';
-            return plain(res, body, JSON.stringify(Object.fromEntries(options.map((o) => [o, pick === '?' ? 1 / options.length : o === pick ? 0.9 : 0.1 / (options.length - 1)]))));
+            return plain(res, body.model, JSON.stringify(Object.fromEntries(options.map((o) => [o, pick === '?' ? 1 / options.length : o === pick ? 0.9 : 0.1 / (options.length - 1)]))));
         }
         if (/sign me out/i.test(said)) {
             res.writeHead(401, { 'content-type': 'application/json' });
@@ -167,21 +168,18 @@ export function startModelStub(script = [], o = {}) {
         });
     });
 }
-const plain = (res, body, text) => {
+const plain = (res, model, text) => {
     const id = randomUUID();
     res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' });
-    const chunk = (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 chunk = (delta, finish = null) => res.write(`data: ${JSON.stringify({ id, object: 'chat.completion.chunk', created: Math.floor(Date.now() / 1000), model, choices: [{ index: 0, delta, finish_reason: finish }] })}\n\n`);
     chunk({ role: 'assistant', content: text });
     chunk({}, 'stop');
     res.end('data: [DONE]\n\n');
 };
 // provider id 'byokit-stub', model 'test': the stub becomes every agent's primary model.
 export async function useModelStub(kit, stub) {
-    // The generated method table arrives with O2; until then kit.call's typed surface accepts no method names, so
-    // configure through this string-typed view of the same runtime path.
-    const call = kit.call.bind(kit);
-    const current = await call('config.get');
-    await call('config.patch', { baseHash: current.hash, raw: JSON.stringify({
+    const current = await kit.call('config.get', {});
+    await kit.call('config.patch', { baseHash: current.hash, raw: JSON.stringify({
             models: { providers: { 'byokit-stub': {
                         baseUrl: stub.url, apiKey: 'byokit-stub', api: 'openai-completions',
                         models: [{ id: 'test', name: 'Test', reasoning: true, input: ['text'],

package/dist/usage.d.ts

@@ -46,6 +46,8 @@ export type AgentUsageReading = {
 /** Normalize an explicitly agent-scoped UTC response. No missing datum is replaced with zero. */
 export declare function agentUsageOf(raw: unknown, member: Member, window: UsageWindow, receivedAt?: number): AgentUsageReading;
 /** Works with kit.call or the portable device.call; retains the complete existing pass-through. RPC errors reject. */
-export declare function readAgentUsage(client: {
+/** What `readAgentUsage` needs from a reader: the kit (`call`) or a device (`callDynamic` + `call`) both fit. */
+export type UsageClient = {
     call(method: 'sessions.usage', params: SessionsUsageParams, options?: CallOptions): Promise<unknown>;
-}, member: Member, window: UsageWindow, options?: CallOptions): Promise<AgentUsageReading>;
+};
+export declare function readAgentUsage(client: UsageClient, member: Member, window: UsageWindow, options?: CallOptions): Promise<AgentUsageReading>;

package/dist/usage.js

@@ -53,7 +53,6 @@ export function agentUsageOf(raw, member, window, receivedAt = Date.now()) {
     result.totals = totals;
     return result;
 }
-/** Works with kit.call or the portable device.call; retains the complete existing pass-through. RPC errors reject. */
 export async function readAgentUsage(client, member, window, options) {
     validate(member, window);
     const raw = await client.call('sessions.usage', { agentId: member, startDate: window.startDate, endDate: window.endDate, mode: 'utc', groupBy: 'instance', limit: 1 }, options);

package/package.json

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