@byokit/openclaw 0.5.1 → 0.6.2

package/CHANGELOG.md

@@ -2,9 +2,62 @@
 
 ## Unreleased
 
-## 0.5.1 (2026-10-02)
-
-- The README points to the shared account-route vocabulary (D18); `routes()` still returns today's table.
+## 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.
+FEAT: Add the internal pipe-only browser broker with fenced private targets, lease-bound live sessions and exact-origin site-data clearing. Sign-in handoff remains unprotected until parked-session protection is qualified.
+FIX: Launch each broker's Chromium with its own short mode-0700 temp directory under the caller's temp directory, removed on close, instead of using the profile path as TMPDIR; deep app profile paths overflowed Chromium's singleton socket path and aborted startup.
+FIX: A controlling viewer ignores frames from a previous target and drops input until the current private target has delivered its first image, so popup switches cannot map input with stale coordinates.
+FIX: The broker's browser endpoint and `/json/version` now use Chromium's canonical `/devtools/browser/<id>?token=` shape, so the pinned engine's CDP discovery finds `/json/list` instead of failing with HTTP 404; token, host and origin guards are unchanged and the old bare path is refused.
+FIX: Chromium's sandbox stays on; a launch refused for no usable sandbox (for example where unprivileged user namespaces are disabled) now fails with typed `BrowserSandboxUnavailable` instead of a generic failure, and is never retried unsandboxed. Startup stderr is used only in memory for that check.
+FIX: Wire opt-in member browsers to the shipped bridge and stock engine, with a dead default profile, member-pinned browser actions, kit browser invalidation events and scoped browser-engine checks. Sign-in handoff remains `handoff-unprotected`; no recovery-protection or automatic resume redispatch claim is made.
+SECURITY: Register the published awaited OpenClaw/Codex tool-result middleware, scrub owned broker capabilities before live model feedback, recheck session admission per result, and terminate on refusal or unavailable protection. Transcript hooks are supplementary; actual full privacy/recovery qualification remains pending.
+FIX: Honor the stock allow/alsoAllow schema, create model-free audit sessions for effective-tool checks, and acknowledge redacted CDP profiles only against an unchanged exact host-owned endpoint and matching applied-source revisions.
+FIX: Explicitly clear hostile node selection across the stock hook's shallow parameter merge; browser proof fixtures distinguish normal model completion from successful tool execution.
+SECURITY: A definite failed sign-in resume no longer permits arbitrary recovery turns: replacement requires a fresh live kit registration matching the exact engine run id and session, revoked on release or bridge shutdown. Source controls cover parked and every unproved resume state; actual engine qualification remains pending. Reconnect keeps tool subsets but revokes submission authority, and waits for old Unix socket teardown before rebinding; shutdown cancels outstanding calls.
+SECURITY: Browser use requires a closed explicit safe tool policy across every engine agent, account agent and delegate; unsafe and unknown effective tools refuse every browser, model-facing profile management/evaluation is blocked before app approval, and raw agent/plugin/config policy mutations require the guarded config path.
+- FEAT: Portable types for the browser sign-in handoff and live view (`NeedSignIn`, `BrowserState`, `LiveViewState`, `BrowserHost`, `BrowserDevice` and friends) from `.` and `./device`, per spec 5.17. Types only: no runtime ships yet, and handoff stays refused until parked sessions are protected.
+- Allow the internal browser host to attach newly created owned-member browsers and replace exact owned endpoints with stale-identity guards, private-target cleanup barriers and read-only versioned bindings for guarded configuration publication. Request bounded thumbnails through the owned viewer. Production sign-in handoff remains blocked pending qualification.
+- Add the internal browser handoff host, durable settlement and conservative resume bookkeeping, with offline synthetic fixtures. Production sign-in remains blocked pending recovery-protection qualification.
+- Add member-scoped browser sign-in actions, private browser live view and portable device helpers. Browser frames and lease capabilities travel on transient encrypted streams, outside durable link answer caches; control requires the host's immediate grant-revocation seam. Watching or reconnecting never dispatches a model run.
+- FIX: Preserve browser reply and event order when messages arrive together, so page evaluation can receive its initial context instead of waiting indefinitely.
+SECURITY: Ship a content-addressed bundled-engine patch manifest and the pinned OpenClaw MIT notice. Fully verified read-only sibling engine sets replace in-place installation; base and existing set bytes are never changed, even when shared Gateways are live. `KitState.patchSet` and `why: 'engine-patch'` expose provenance; rollback selects verified stock offline, while stock drift may need registry access. The initial patch set is empty.
+- `getConfigKey` / `setConfigKey` read and write exactly one dotted config key in the file `prepare()` owns, so an app can narrow-read and restore a value (for example `skills.workshop.autonomous.mode`) around a boot without a whole `config.get`, whose result redacts token-bearing values. Only that key changes, the write is atomic in `prepare()`'s exact shape and happens only when the bytes change, and `undefined` removes the key.
+FEAT: Add portable `readAgentDayUsage` / `AgentDayUsage` readings that combine fresh retained transcripts with durable Gateway Skill Workshop review charges. UTC/IANA windows, pending/interrupted/missing usage and conservative completeness let callers keep unknown budgets unknown. The original partial usage API is unchanged; other detached kinds and the worker bundle remain uncovered.
+FIX: Persist detached Workshop review usage, including reported usage on failed outcomes, without double-counting memory flushes, recovery resumes or run results. Per-boot/month attempt counters, fsynced launch and clean-stop records, phase deduplication and bounded month reads preserve failure holes and crash incompleteness.
+SECURITY: The bundled checksum-pinned Gateway Workshop patch and operator-read usage RPC write/read accounting identities, times and reported counters only, never prompts, outputs, tool arguments or credentials. Device reads stay member-scoped and never access host files; unknown costs and unverified billing identity are not guessed.
+FIX: `stop()` now signals only the pids the kit itself spawned and never a process group, so shutdown no longer reaches processes the kit never started. Every spawn is recorded when it starts and dropped when it exits; the gateway is left to shut its own sessions down on its own SIGTERM.
+- Unreleased source dependency metadata: pin @byokit/seal 0.3.0 and @byokit/relay 0.5.2; this package's existing version is not republished. Previously published consumer metadata remains unchanged.
+- SECURITY: Sensitive subscription sign-in tokens stay out of sign-in views and results, including engine errors, links and codes after token entry.
+- FIX: Subscription setup-token sign-in now answers sensitive wizard text steps from the existing paste channel, once per step, with cancellation and timeout preserved. API key (billed per use) entry still requires explicit selection.
+
+## 0.6.0 (2026-10-02)
+
+- Portable `readAgentUsage` / `agentUsageOf` expose explicit-agent UTC retained-transcript totals with raw responses, cache freshness and missing-price counters preserved. Coverage stays partial: stock-engine detached Workshop reviews are absent, and unavailable data never becomes zero; complete internal-turn accounting is not claimed.
+- FIX: Host runs can reuse a caller-stable per-dispatch `idempotencyKey` after a lost connection instead of starting a second engine run. Omission keeps fresh UUIDs. Document the pinned engine's gateway-wide, bounded, in-memory cache and honest in-flight replay limits; this is not exactly-once across engine restarts.
+
+FIX: Generate complete pinned route discovery: 91 auth choices and five cloud/CLI providers, including external plugin dependencies, plan-key entry, service grouping and corrected provider/billing labels. `routes()` computes readiness without reading credentials or installing plugins; legacy boolean `offer` is ready default subscriptions only, with `offerPolicy` retaining eligibility. Missing plugins, binaries, client registrations and choiceless wizard flows remain visible, not falsely usable. Explicit API/local/endpoint routes never become default billing; endpoint billing requires host input. Full discovery also reaches the existing phone/web link without hiding unavailable rows. Existing choice IDs, legacy explicit browser/code selectors, native Claude activation guards and ChatGPT pairing are retained; corrected manifest provider IDs and semantic `via` values replace inaccurate discovery labels. Listing an API or unavailable route never authorizes a sign-in or makes it a default.
+
+- The README points to the shared account-route vocabulary (D18); pinned route discovery is not proof of additional implemented authentication flows.
 - FIX: ChatGPT sign-in now interrupts abandoned wizard/paste waits on gateway disconnect and reconfirms a new, usable OAuth profile for the selected member through the reconnected engine. Recovery is bounded and fails closed for unknown, missing, pre-existing or unrelated credentials, cancellation and expiry. A synchronous cleanup error during reconnect no longer suppresses the terminal sign-in view.
 
 ## 0.5.0 (2026-10-01)

package/README.md

@@ -25,6 +25,26 @@ under your `stateDir` (a few minutes, needs the network once), and later starts
 phone page that pairs, signs in with ChatGPT, runs and answers approvals, see
 [`examples/openclaw-kit`](../../examples/openclaw-kit).
 
+## Bundled engine provenance
+
+`engine/patches.json` declares the exact upstream tarball integrity, commit, unique edits and before/after file
+hashes. The Gateway Workshop review patch writes content-free, durable usage facts only when the kit sets its
+accounting environment. The separately bundled worker and all other detached kinds remain uncovered.
+The full upstream MIT notice ships in [engine/OPENCLAW-LICENSE](engine/OPENCLAW-LICENSE).
+
+Each `prepare()` verifies the **entire** selected engine tree, including unpatched files. The kit installs stock
+into a private temporary tree, clones verified stock for a changed set, then publishes read-only sibling trees
+under `<engineDir>.sets/`. It never patches, reinstalls or deletes the base `<engineDir>/node_modules` or any
+published set, even when a shared Gateway is running. `doctorContext().entry` points at the selected set after
+prepare; `<stateDir>/openclaw/engine-set` records that selection. `kit.state.patchSet` is its content-addressed
+patch id (`null` after a provenance failure); a refusal is `why: 'engine-patch'` with a typed error code.
+
+Rollback selects a verified stock or older set; known sets and offline clones require no registry access.
+Drift leaves the old bytes untouched and builds a replacement sibling; rebuilding stock may need the registry.
+Pre-change kits still run the untouched base install. No garbage collection: each retained set can occupy about
+889 MB on this pin (reflinks may reduce physical storage). Whole-tree verification also adds preparation I/O;
+read-only modes protect against accidental writes, not a malicious host app that owns the files.
+
 ## Quickstart
 
 Start the engine, add a member, sign them in with a subscription, run a message (typechecked; running it installs
@@ -56,6 +76,32 @@ console.log(end);
 await kit.stop();
 ```
 
+For a host run that may be retried after a lost connection, mint and persist an action key **once**, then reuse
+that key and the same run inputs:
+
+```ts
+import type { OpenClawKit } from '@byokit/openclaw';
+
+async function dispatch(kit: OpenClawKit, taskId: string, attempt: number, message: string) {
+  const actionKey = `task:${taskId}:attempt:${attempt}:${crypto.randomUUID()}`;
+  // Persist actionKey with this dispatch before calling; a new action/attempt gets a new nonce.
+  const spec = { member: 'umer', sessionKey: `agent:umer:task:${taskId}`, message, idempotencyKey: actionKey };
+  return kit.run(spec); // reconnect retry: kit.run(spec), not another dispatch()/new actionKey
+}
+```
+
+Omitting `idempotencyKey` preserves a fresh UUID per call. Supplied keys are non-empty strings passed unchanged.
+**Not exactly-once:** engine 2026.8.1 caches `agent` keys gateway-wide, across agents and sessions, without comparing
+inputs. A collision silently returns the first run's result/error; a task id alone is not a safe key. Reconnects
+retain the in-memory cache; engine process restarts lose it. Inactive entries expire after five minutes (60-second
+cleanup tick), or earlier under the 1,000-entry cache limit; active and pending accepted runs are exempt.
+An in-flight replay waits on the original run but cannot replay old events or subscribe to its final response:
+text may be a capped 4096-character terminal snapshot, usage stays absent, and capped JSON may fail schema
+validation. A completed cached replay can return full text/usage. The helper never sends another `agent` request
+just to read a final result: on cache eviction that would start another run. Apps still own durable task/effect
+recovery. Typed `kit.call('agent', ...)` remains exact upstream pass-through. Details and real-engine proof are
+in [the run contract](../../docs/runtime-kits.md#58-runs-members-and-streams).
+
 Device approval can take longer than two minutes. The kit waits through the engine's advertised code lifetime
 (`expiresInMinutes` on the pin, or `expires_in` seconds when supplied), including progress pulls. If the engine
 supplies no lifetime, it owns the deadline. Ordinary wizard requests keep their 120-second timeout.
@@ -63,6 +109,13 @@ supplies no lifetime, it owns the deadline. Ordinary wizard requests keep their
 `done` returns a typed `SignInView`: `why: 'expired'` for an expired code, `why: 'declined'` for cancellation,
 with a plain sentence in `error`. `SignInOptions` is exported from the host entry.
 
+For a subscription setup-token or any sensitive wizard text step, pass the token once through the same
+`signIn.paste(token)` channel and clear the input afterwards. The kit displays only a fixed entry label;
+subsequent wizard errors, links and codes are withheld, and failures use a fixed message rather than
+engine text that could echo the token. It is sent only as this member's wizard answer, never in views,
+results or kit logs. Ordinary browser paste and typed `kit.call('wizard.next', …)` pass-through are unchanged.
+API key (billed per use) entry still requires explicit selection; there is no subscription-to-key fallback.
+
 To choose which of a member's accounts a run uses, pass `model: 'provider/model'` in the run spec (for example
 `'openai/gpt-5.1'`, where `provider` is an id `kit.providers(member)` lists). That provider is the one called and billed for this run only, with no fallback to another
 provider or model. If the member isn't signed in to it, the run ends `{ ok: false, kind: 'signed-out' }` and the
@@ -94,6 +147,71 @@ ends ok carries `usage` (the engine's token total for the run, and `costUsd` whe
 `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.
 
+### Observed per-agent ledger usage (not complete engine spend)
+
+```ts
+import { readAgentUsage } from '@byokit/openclaw/usage'; // portable; kit or device client
+import type { OpenClawKit } from '@byokit/openclaw';
+
+async function showUsage(kit: OpenClawKit) {
+  const reading = await readAgentUsage(kit, 'umer', { startDate: '2026-10-02', endDate: '2026-10-02' });
+  // Caller decides whether partial coverage is acceptable; never turn unavailable totals into zero.
+  if (reading.state === 'available') console.log(reading.totals);
+}
+```
+
+`agentUsageOf(raw, member, window)` also normalizes an existing explicitly agent-scoped UTC response. Full raw
+RPC data is retained; existing typed `call` pass-through is unchanged. Windows are inclusive UTC calendar days.
+`receivedAt`, result-assembly `updatedAt` and `cache.refreshedAt` are separate: receiving cached data does not
+refresh it. The engine response cache lasts 30 seconds; pending/stale/unknown data leaves `totals` absent.
+An absent agent row is unavailable, not proof of zero usage. Reset/deletion/retention can reduce counters.
+
+**Coverage is always `retained-transcripts-only`.** Stock 2026.8.1's detached Skill Workshop reviews are omitted
+from its ledger; actual crash-recovery resumes and threshold memory flushes are counted through persisted
+transcripts, never through a second side total. This reader cannot enforce a complete all-turn budget. The app owns budget,
+share and unavailable/partial-data policy. Do not add run results to these totals: they already overlap. Engine
+cost fields are price counters, not a bill or subscription quota; zero cost with `missingCostEntries > 0` is
+unknown cost, and tokens never establish subscription plan weights. No billing conversion is performed.
+
+### Day readings including Gateway Workshop reviews
+
+```ts
+import { readAgentDayUsage } from '@byokit/openclaw/day-usage'; // also exported by . and ./device
+
+async function dayBudget(kitOrDevice: Parameters<typeof readAgentDayUsage>[0]) {
+  const startMs = Date.parse('2026-10-02');
+  const day = await readAgentDayUsage(kitOrDevice, 'umer', {
+    startMs, endMs: startMs + 86_400_000 - 1, mode: 'utc',
+  });
+  return day.knownTotalTokens !== undefined && day.knownTotalTokens > 190 ? 'over'
+    : day.complete ? 'under' : 'unknown'; // policy is the caller's
+}
+```
+
+This additive reader leaves `readAgentUsage` unchanged. Coverage is **retained transcripts + Gateway Workshop
+reviews**, not all engine spend. Reviews crossing midnight land on their ended day. UTC and IANA
+`{ mode: 'time-zone', timeZone: 'America/New_York' }` apply to both terms; Gateway-local zones are refused.
+The engine transcript RPC reports calendar days: use complete inclusive days in that zone. A partial-day window
+leaves the transcript term unavailable rather than inventing a millisecond total.
+
+Review facts carry only run/session/agent/model/profile ids, times, outcomes and reported tokens. Their cost is
+always `missing`; billing stays `unknown` without verified selected-route identity, never inferred from a provider.
+Missing usage is `reported-missing`, a live start is `pending`, and an old boot's start is `interrupted`; none means
+zero. Facts deduplicate by charge and phase. `knownTotalTokens` is the sum of reported counters only and is absent
+when either source is unavailable. `complete: false` is a budget-policy unknown, not permission to proceed.
+
+The append-only `openclaw/usage/` ledger survives session reset, engine replacement and restart. Start records are
+fsynced before spawning, using an accounting UUID separate from unchanged pid/start-time ownership. Month attempt
+counters and failures survive clean stop; holes, missing counters, corrupt lines and overlapping crash boots keep
+windows incomplete permanently. Reads open only requested UTC months plus boot records. No rotation yet.
+Device reads use the operator-read plugin RPC, never host files; the link adapter restricts it to the granted member.
+As with the existing transcript reader, the app must explicitly allow member-scoped `sessions.usage` pass-through.
+
+Uncovered: worker-bundle work, skill collection review, history scans, slug generation, active-memory recall,
+out-of-turn compaction and one-shot helper completions. Do not add `RunEnd.usage`, memory flush or recovery totals
+again: they already overlap retained transcripts. Offline scripted-provider tests verify seven Gateway accounting
+cases; they do not establish live subscription quota, provider bills or universal coverage.
+
 For a validated JSON answer, pass a literal `schema`. The result's `data` is inferred from that schema:
 
 ```ts
@@ -170,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
@@ -198,15 +322,78 @@ 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`, `toolNames`, `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`, `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)
+
+`browser: { executablePath, members }` opts into isolated member Chromium profiles. It requires a closed
+explicit tool allowlist and keeps `request_sign_in` refused: protected production handoff is not qualified.
+Public live view/thumbnail APIs are model-free; source tests alone do not prove private/restart protection.
+The opt-in physical fixture retains raw JPEG/control inputs before decoding, pipe chunk order, complete
+synthetic provider bodies and authoritative SQLite transcripts, including failures.
+
+## One config key, narrowed
+
+`patchConfig` is the only whole-config writer, and it can only start from `config.get`, whose result redacts
+token-bearing values: an app cannot read one key through it and write it back unchanged. For a single key, use the
+narrow pair over the config file the engine loads at boot:
+
+```ts
+import { OpenClawKit } from '@byokit/openclaw';
+
+const kit = new OpenClawKit({ stateDir: './openclaw-state' });
+
+kit.getConfigKey('skills.workshop.autonomous.mode');            // value, or undefined
+kit.setConfigKey('skills.workshop.autonomous.mode', 'off');      // returns the value it replaced
+kit.setConfigKey('skills.workshop.autonomous.mode', undefined); // remove it again
+```
+
+One dotted path of `[A-Za-z0-9_-]` segments; prototype-reaching segments are refused. Only that key changes (every
+other key keeps its order, an unchanged value writes no bytes, and removing a key takes the empty objects it created
+back out), the write is atomic in `prepare()`'s exact shape, and the engine applies it at its next boot. Narrow a key
+your app does **not** also pass in `KitOptions.config`: that option is merged over the saved file on every boot and
+wins. Don't interleave a narrow set with `patchConfig`, which rewrites the whole config through the Gateway.
+
+## App-owned task recovery
+
+If your app requeues interrupted tasks itself, declare their namespaces **before starting the kit**:
+
+```ts
+import { OpenClawKit } from '@byokit/openclaw';
+
+const kit = new OpenClawKit({
+  stateDir: './openclaw-state',
+  appOwnedSessions: { keyPrefixes: ['agent:m1:crewhouse:'] },
+  // tools and host as usual
+});
+```
+
+Matching task sessions are excluded from the bundled engine's automatic restart continuation; your app
+continues the same session key with `kit.run`. Prefixes must start with `agent:<member>:` and must not cover
+that member's `main` key. The kit also covers a public member's isolated API-key session rewrite. Omitted/empty
+keeps stock recovery, including its existing retry accounting; no histories or recovery markers are deleted,
+no tool gate is bypassed, and cron behavior is unchanged. Changing ownership requires an engine restart.
+This option does not decide whether an interrupted external action is safe to retry; your app still owns
+that decision. It needs the published kit's bundled engine patch, not a separately installed stock CLI.
 
 ## Phones and browsers
 
@@ -249,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
@@ -291,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,
@@ -304,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
@@ -344,6 +534,6 @@ frozen (docs/runtime-kits.md §5).
 
 ## License
 
-Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](../../NOTICE).
+Apache-2.0. See [LICENSE](LICENSE); the bundled engine's MIT text is [engine/OPENCLAW-LICENSE](engine/OPENCLAW-LICENSE).
 
 Claude: `anthropic-cli` uses your own unmodified Claude Code login on this machine (provider `claude-cli`, plugin `anthropic`; subscription billing), with login kept in Claude Code under the kit’s isolated `HOME=<stateDir>/openclaw/home` and `CLAUDE_CONFIG_DIR=<stateDir>/openclaw/home/.claude`; sign in there with `claude auth login`, then call `signIn`. Activation live-tests the route; native sign-out is through Claude Code. `apiKey` is explicit API billing (“API key (billed per use)”, `offer: false`): `signIn` asks for the key through `paste`, then engine activation verifies it. The kit never imports Claude credentials or implements direct Claude.ai OAuth; [Anthropic’s terms](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use) apply.

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() {
@@ -252,7 +295,7 @@ export class AuthStore {
         removeMarker(this.restoring);
     }
     async archives() {
-        const ignored = new Set([resolve(this.o.engineDir), ...['npm-cache', 'install-home', 'tmp', 'plugin', 'workspaces'].map((d) => resolve(this.o.root, d))]);
+        const ignored = new Set([resolve(this.o.engineDir), resolve(`${this.o.engineDir}.sets`), ...['npm-cache', 'install-home', 'tmp', 'plugin', 'workspaces'].map((d) => resolve(this.o.root, d))]);
         const walk = async (dir) => {
             for (const entry of readdirSync(dir, { withFileTypes: true })) {
                 const path = join(dir, entry.name);

package/dist/bridge.d.ts

@@ -24,6 +24,7 @@ export declare function writePlugin(dir: string, o: {
     tools: ToolSpec[];
     paramPrefix: string;
     gateBuiltins: boolean;
+    browser?: boolean;
 }): void;
 export declare class Bridge {
     private readonly path;
@@ -33,7 +34,11 @@ export declare class Bridge {
     private readonly approvalTimeoutMs;
     private readonly onAsk;
     private readonly onAskGone;
+    private readonly beforeAgentRun?;
+    private readonly browserCapabilities?;
     private server?;
+    private closing;
+    private readonly sockets;
     private readonly runs;
     private readonly live;
     private readonly permits;
@@ -49,11 +54,14 @@ export declare class Bridge {
         approvalTimeoutMs: number;
         onAsk(a: Approval): void;
         onAskGone(id: string): void;
+        beforeAgentRun?: (key: string, runId?: string) => Promise<boolean>;
+        browserCapabilities?: () => readonly string[];
     });
     start(): Promise<void>;
     stop(): 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;
+    isRegisteredRun(key: string, runId?: string): boolean;
+    /** Register one run; release revokes only this exact registration, even when sessions overlap. */
+    register(run: RunRef, tools?: readonly string[], runId?: string): () => void;
     unregister(sessionKey: string): void;
     allowOnce(rule: {
         keyPrefix: string;