@byokit/openclaw 0.5.0 → 0.6.1

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 ## Unreleased
 
+## 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)
 
 - Dependency update: pins @byokit/relay 0.5.1.

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
@@ -198,7 +316,7 @@ 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` |
@@ -208,6 +326,58 @@ Entries:
 | `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 |
 
+## 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
 
 The host side serves member-checked ops over `@byokit/link`; the phone or browser uses the portable client:
@@ -243,6 +413,8 @@ The kit writes only under the `stateDir` the app passes. It spawns the engine wi
 (never `process.env`), reads no environment variables except `PATH` to find `npm`, and never bills an API behind the
 person's back (memory search is never a paid provider).
 
+Route data follows the shared account-route vocabulary (D18 in [`docs/runtime-kits.md`](../../docs/runtime-kits.md#21-account-routes-d18)): subscription routes are offered by default, and every other billing is used only when named. The full table of the pinned engine's auth choices is planned work; `routes()` returns today's table.
+
 ## Credential sealing and threat model
 
 The pinned engine has no supported hook for sealing OAuth profile writes. Its `auth-profiles` loader stores
@@ -342,6 +514,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/dist/auth-store.js

@@ -252,7 +252,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;

package/dist/bridge.js

@@ -41,7 +41,7 @@ export function writePlugin(dir, o) {
         id: o.id,
         name: 'BYOKit bridge',
         activation: { onStartup: true },
-        contracts: { tools: o.tools.map((t) => t.name) },
+        contracts: { tools: o.tools.map((t) => t.name), ...(o.browser ? { agentToolResultMiddleware: ['openclaw', 'codex'] } : {}) },
         configSchema: { type: 'object', additionalProperties: false },
     };
     const table = {
@@ -50,6 +50,7 @@ export function writePlugin(dir, o) {
         permitParam,
         // true: engine builtins (web_fetch, memory, ...) are gated too, not only the app's tools.
         gateBuiltins: o.gateBuiltins,
+        ...(o.browser ? { browser: true } : {}),
         tools: o.tools.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters })),
     };
     for (const [file, data] of [['openclaw.plugin.json', manifest], ['tools.json', table]]) {
@@ -67,7 +68,11 @@ export class Bridge {
     approvalTimeoutMs;
     onAsk;
     onAskGone;
+    beforeAgentRun;
+    browserCapabilities;
     server;
+    closing = Promise.resolve();
+    sockets = new Set();
     runs = new Map();
     // Every live registration per session key, each with its run's subset of the app's tools (RunSpec.tools; none: all
     // of them). Runs sharing a key share the narrowest: a tool must be in every live subset.
@@ -85,18 +90,28 @@ export class Bridge {
         this.approvalTimeoutMs = Math.min(o.approvalTimeoutMs, MAX_APPROVAL_TIMEOUT_MS);
         this.onAsk = o.onAsk;
         this.onAskGone = o.onAskGone;
+        this.beforeAgentRun = o.beforeAgentRun;
+        this.browserCapabilities = o.browserCapabilities;
     }
-    start() {
+    async start() {
         if (this.server)
-            return Promise.resolve();
+            return;
         this.stopped = false;
-        // A stale socket file from a crashed run is not a listener; a live one survives unlinking.
+        await this.closing;
+        if (this.stopped || this.server)
+            return;
+        // Old listener teardown must finish before it can unlink a newly rebound Unix socket.
         rmSync(this.path, { force: true });
-        this.server = createServer((socket) => this.serve(socket));
-        return new Promise((resolve, reject) => {
-            this.server.once('error', reject);
-            this.server.listen(this.path, () => {
-                this.server.removeListener('error', reject);
+        const server = createServer(socket => {
+            this.sockets.add(socket);
+            socket.once('close', () => this.sockets.delete(socket));
+            this.serve(socket);
+        });
+        this.server = server;
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(this.path, () => {
+                server.removeListener('error', reject);
                 resolve();
             });
         });
@@ -110,14 +125,28 @@ export class Bridge {
             this.onAskGone(id);
         }
         this.parked.clear();
-        this.server?.close();
+        // Tool subsets survive reconnect (B3); submission authority does not survive a lost engine transport.
+        for (const entries of this.live.values())
+            for (const entry of entries)
+                entry.runId = undefined;
+        // Preserve already-ended refusal replies; abort outstanding calls through their close signal (N7).
+        for (const socket of this.sockets)
+            if (!socket.writableEnded)
+                socket.destroy();
+        const server = this.server;
         this.server = undefined;
-        void rm(this.path, { force: true }).catch(() => { });
+        if (server)
+            this.closing = new Promise(resolve => server.close(() => resolve()))
+                .then(() => rm(this.path, { force: true }).catch(() => { }));
     }
-    /** Register one run; the returned release ends only this registration (the key stays while another run holds it). */
-    register(run, tools) {
+    isRegisteredRun(key, runId) {
+        return !this.stopped && typeof runId === 'string' && !!runId
+            && (this.live.get(key) ?? []).some(entry => entry.runId === runId);
+    }
+    /** Register one run; release revokes only this exact registration, even when sessions overlap. */
+    register(run, tools, runId) {
         this.runs.set(run.sessionKey, run);
-        const entry = tools ? { tools: new Set(tools) } : {};
+        const entry = { ...(tools ? { tools: new Set(tools) } : {}), runId };
         const list = this.live.get(run.sessionKey);
         if (list)
             list.push(entry);
@@ -225,6 +254,24 @@ export class Bridge {
         }
         if (!isRecord(message) || typeof message.kind !== 'string')
             return this.deny(socket, 'not a gate request');
+        if (message.kind === 'browser-capabilities') {
+            if (!this.browserCapabilities || this.stopped)
+                return this.deny(socket, 'browser unavailable');
+            try {
+                this.reply(socket, { capabilities: this.browserCapabilities() });
+            }
+            catch {
+                this.deny(socket, 'browser unavailable');
+            }
+            return;
+        }
+        if (message.kind === 'before-agent-run') {
+            if (typeof message.key !== 'string' || !message.key || !this.beforeAgentRun)
+                return this.deny(socket, 'run unavailable');
+            void this.beforeAgentRun(message.key, typeof message.runId === 'string' ? message.runId : undefined)
+                .then(allow => this.reply(socket, { allow }), () => this.deny(socket, 'run unavailable'));
+            return;
+        }
         if (message.kind === 'gate')
             return void this.gate(socket, message);
         if (message.kind === 'call')

package/dist/browser/broker.d.ts

@@ -0,0 +1,63 @@
+import type { Member } from '../types.ts';
+import type { LiveFrame, LiveInput } from '../browser.ts';
+export type BrokerOptions = {
+    executablePath: string;
+    profileDir: string;
+    member: Member;
+    onExit(code: number | null): void;
+};
+export type LeaseBinding = {
+    epoch: number;
+    nonce: string;
+    origin: string;
+    knownIdps: string[];
+};
+export type PrivateState = {
+    origin: string;
+    secure: boolean;
+    offOrigin: boolean;
+} | undefined;
+export type Broker = {
+    bindLease(l: LeaseBinding | null): void;
+    confirmOrigin(l: {
+        epoch: number;
+        nonce: string;
+    }, origin: string): boolean;
+    privateState(): PrivateState;
+    clearSite(origins: string[]): Promise<void>;
+    endpoint(): {
+        cdpUrl: string;
+    };
+    fence(on: boolean): Promise<void>;
+    agentTab(): string | undefined;
+    originOf(targetId: string): Promise<string>;
+    openPrivate(url: string): Promise<string>;
+    closePrivate(): Promise<void>;
+    probe(url: string, verify: (p: Probe) => Promise<boolean>, timeoutMs: number): Promise<'ok' | 'fail' | 'timeout'>;
+    attachViewer(o: {
+        lease?: {
+            epoch: number;
+            nonce: string;
+        };
+        maxWidth?: number;
+    }): ViewerSession;
+    navigateAgent(url: string | 'reload'): Promise<void>;
+    close(): Promise<void>;
+};
+export type Probe = {
+    url: string;
+    status: number;
+    exists(selector: string): Promise<boolean>;
+};
+export type ViewerSession = {
+    frames: AsyncIterable<LiveFrame>;
+    states: AsyncIterable<NonNullable<PrivateState>>;
+    input(i: LiveInput): void;
+    close(): void;
+};
+/** Chromium refused to start without its sandbox (e.g. unprivileged user namespaces disabled). The broker never runs it unsandboxed. */
+export declare class BrowserSandboxUnavailable extends Error {
+    readonly reason = "sandbox-unavailable";
+    constructor();
+}
+export declare function launchBroker(o: BrokerOptions): Promise<Broker>;