@byokit/openclaw 0.5.1 → 0.6.1

package/dist/config.js

@@ -1,5 +1,6 @@
 import { dirname, join } from 'node:path';
 import { routes } from "./routes.js";
+import { MEMBER_ID, KEY_PREFIX, keyAgentId } from "./members.js";
 const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const merge = (a, b) => {
     for (const [k, v] of Object.entries(b))
@@ -58,6 +59,24 @@ export function reconcileConfig(saved, o) {
             ...routes().filter(route => route.offer && route.plugin).map(route => route.plugin)])];
     c.plugins.entries ??= {};
     c.plugins.entries[o.pluginId] = merge(c.plugins.entries[o.pluginId] ?? {}, { hooks: { timeouts: { before_tool_call: 200_000 } } });
+    if (o.browser) {
+        // Replace, never merge caller-controlled profiles/targets. The dead default fails closed without our hook.
+        c.browser = { enabled: true, defaultProfile: 'byokit-none', evaluateEnabled: false,
+            tabCleanup: { enabled: false }, ssrfPolicy: { dangerouslyAllowPrivateNetwork: true },
+            profiles: { 'byokit-none': { cdpUrl: 'http://127.0.0.1:1', attachOnly: true }, ...o.browser.profiles } };
+        c.plugins.allow = [...new Set([...c.plugins.allow, 'browser'])];
+        c.plugins.entries.browser = { enabled: true };
+        c.plugins.entries[o.pluginId].hooks.allowConversationAccess = true;
+        c.tools ??= {};
+        const browserTools = [...new Set([...(c.tools.alsoAllow ?? []), 'browser', 'request_sign_in', ...o.browser.tools])];
+        // The stock schema rejects allow + alsoAllow in one scope; an explicit closed allow must absorb additions.
+        if (Array.isArray(c.tools.allow)) {
+            c.tools.allow = [...new Set([...c.tools.allow, ...browserTools])];
+            delete c.tools.alsoAllow;
+        }
+        else
+            c.tools.alsoAllow = browserTools;
+    }
     c.security ??= {};
     c.security.installPolicy = { enabled: true, exec: {
             source: 'exec', command: process.execPath, args: [o.policyPath],
@@ -69,8 +88,119 @@ export function reconcileConfig(saved, o) {
         } };
     return c;
 }
+/** Caller-owned task namespaces, including the engine key-agent rewrite; never an entire member. */
+export function appRecoveryPrefixes(ownership) {
+    if (ownership === undefined)
+        return [];
+    const invalid = () => new Error('invalid appOwnedSessions.keyPrefixes: use agent:<member>:<task-prefix>, never the main session');
+    const prefixes = ownership?.keyPrefixes;
+    if (!Array.isArray(prefixes))
+        throw invalid();
+    return [...new Set(prefixes.flatMap(prefix => {
+            const match = typeof prefix === 'string' && /^agent:([a-z0-9-]+):(.*)$/.exec(prefix);
+            if (!match || `agent:${match[1]}:main`.startsWith(prefix))
+                throw invalid();
+            return MEMBER_ID.test(match[1]) && !match[1].startsWith(KEY_PREFIX)
+                ? [prefix, `agent:${keyAgentId(match[1])}:${match[2]}`] : [prefix];
+        }))];
+}
+/** A closed explicit global allow is required, not a group deny or an OS sandbox claim. Every nested
+ * agent, delegate and provider policy must stay inside it. The runtime also checks tools.effective. */
+export function browserToolPolicySafe(config, tools) {
+    const safe = new Set(['browser', 'request_sign_in', ...tools]);
+    const allowed = (value) => Array.isArray(value) && value.every(t => typeof t === 'string' && safe.has(t));
+    if (!object(config) || !object(config.tools) || !allowed(config.tools.allow) || !config.tools.allow.length)
+        return false;
+    const visit = (value) => {
+        if (Array.isArray(value))
+            return value.every(visit);
+        if (!object(value))
+            return true;
+        for (const [key, child] of Object.entries(value)) {
+            if (key === 'tools') {
+                if (!object(child))
+                    return false;
+                if (child.profile !== undefined || (child.allow !== undefined && !allowed(child.allow))
+                    || (child.alsoAllow !== undefined && !allowed(child.alsoAllow)))
+                    return false;
+            }
+            if (!visit(child))
+                return false;
+        }
+        // byProvider entries are tool policies too, not named `tools`.
+        if (object(value.byProvider) && Object.values(value.byProvider).some(p => !object(p) || p.profile !== undefined
+            || (p.allow !== undefined && !allowed(p.allow)) || (p.alsoAllow !== undefined && !allowed(p.alsoAllow))))
+            return false;
+        return true;
+    };
+    return visit(config);
+}
+// The pinned config.get redacts the entire token-bearing CDP URL. Only an applied, stable host-owned
+// config snapshot can substitute its exact endpoint; an arbitrary masked/changed URL never counts as an ack.
+export function browserProfileAcknowledged(profile, owned, endpoint, snapshot, stableFile) {
+    if (!object(profile) || !object(owned) || profile.attachOnly !== true || owned.attachOnly !== true
+        || owned.cdpUrl !== endpoint || !stableFile || typeof snapshot.configRevisionHash !== 'string'
+        || !snapshot.configRevisionHash || snapshot.configRevisionHash !== snapshot.appliedConfigHash)
+        return false;
+    return profile.cdpUrl === endpoint || profile.cdpUrl === '__OPENCLAW_REDACTED__';
+}
+// A failed resume is not permission for engine recovery. Only a fresh exact kit run may replace it.
+export function browserSessionMayRun(requests, key, registeredRun = false) {
+    return !requests.some(r => r.sessionKey === key && (r.state !== 'settled'
+        || (r.settled?.resume && (r.settled.resume.state !== 'failed' || !registeredRun))));
+}
 export function memoryLimited(config, member) {
     const c = config;
     const entry = c.agents?.entries?.[member];
     return (entry?.memory ?? c.memory)?.search?.provider === 'none';
 }
+const KEY_SEGMENT = /^[A-Za-z0-9_-]+$/;
+const UNSAFE_SEGMENT = new Set(['__proto__', 'constructor', 'prototype']);
+/** One dotted path, validated at the boundary: a caller-supplied walk must never reach a prototype. */
+export function configKeyPath(key) {
+    const segments = typeof key === 'string' && key.length ? key.split('.') : [];
+    if (!segments.length || segments.some(part => !KEY_SEGMENT.test(part) || UNSAFE_SEGMENT.has(part)))
+        throw new Error(`invalid config key: ${String(key)}`);
+    return segments;
+}
+/** The value at one dotted path, or undefined when it is absent. A copy, so a caller cannot hold kit state. */
+export function readConfigKey(config, segments) {
+    let node = config;
+    for (const segment of segments) {
+        if (!object(node) || !(segment in node))
+            return undefined;
+        node = node[segment];
+    }
+    return structuredClone(node);
+}
+/** Writes one dotted path, creating only the missing objects on the way, and returns the value it replaced.
+ * undefined removes the key, and with it the empty objects this call created, so a removal restores the file it
+ * read. Every other key keeps its place, so one narrow set stays one narrow set. */
+export function writeConfigKey(config, segments, value) {
+    const chain = [config], created = [];
+    for (const segment of segments.slice(0, -1)) {
+        const parent = chain[chain.length - 1];
+        if (parent[segment] === undefined) {
+            parent[segment] = {};
+            created.push(true);
+        }
+        else if (!object(parent[segment]))
+            throw new Error(`config key is not an object: ${segments.join('.')}`);
+        else
+            created.push(false);
+        chain.push(parent[segment]);
+    }
+    const leaf = chain[chain.length - 1], last = segments[segments.length - 1];
+    const previous = readConfigKey(leaf, [last]);
+    if (value !== undefined) {
+        leaf[last] = structuredClone(value);
+        return previous;
+    }
+    delete leaf[last];
+    for (let depth = chain.length - 1; depth > 0; depth--) {
+        if (!created[depth - 1] || Object.keys(chain[depth]).length)
+            break;
+        delete chain[depth - 1][segments[depth - 1]];
+    }
+    return previous;
+}

package/dist/day-usage.d.ts

@@ -0,0 +1,76 @@
+import { type AgentUsageReading } from './usage.ts';
+import type { SessionsUsageParams } from '@openclaw/gateway-protocol';
+import type { Member } from './types.ts';
+export type EngineStartedKind = 'workshop-review';
+export type EngineStartedCharge = {
+    chargeId: string;
+    member: Member;
+    kind: EngineStartedKind;
+    state: 'counted' | 'reported-missing' | 'pending' | 'interrupted';
+    startedAt: number;
+    endedAt?: number;
+    outcome?: 'nothing' | 'proposed' | 'applied' | 'failed';
+    provider: string;
+    model: string;
+    billing: 'subscription' | 'api' | 'local' | 'unknown';
+    authProfileId?: string;
+    tokens?: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        reasoningTokens?: number;
+        total: number;
+    };
+    tokenSource: 'engine-reported';
+    cost: {
+        state: 'missing';
+    };
+    bootId: string;
+    seq: number;
+    origin?: {
+        sessionKey: string;
+        runId?: string;
+    };
+};
+export type AgentDayUsage = {
+    member: Member;
+    window: {
+        startMs: number;
+        endMs: number;
+    } & ({
+        mode: 'utc';
+    } | {
+        mode: 'time-zone';
+        timeZone: string;
+    });
+    transcripts: Omit<AgentUsageReading, 'window'> & {
+        window: {
+            startDate: string;
+            endDate: string;
+        } & ({
+            mode: 'utc';
+        } | {
+            mode: 'time-zone';
+            timeZone: string;
+        });
+    };
+    engineStarted: {
+        state: 'available' | 'unavailable';
+        coverageSince?: number;
+        charges: EngineStartedCharge[];
+        unreadableLines: number;
+    };
+    coverage: 'transcripts+workshop-review';
+    complete: boolean;
+    knownTotalTokens?: number;
+};
+/** Only accept the kit's bounded, content-free RPC result; malformed facts make the reading unavailable. */
+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: {
+    callDynamic(method: string, params?: unknown): Promise<unknown>;
+    call(method: 'sessions.usage', params: SessionsUsageParams): Promise<unknown>;
+}, member: Member, window: AgentDayUsage['window']): Promise<AgentDayUsage>;

package/dist/day-usage.js

@@ -0,0 +1,104 @@
+// Portable additive day reader. No host files, pricing guesses or side totals for persisted turns.
+import { agentUsageOf } from "./usage.js";
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const count = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+const text = (v) => typeof v === 'string' && v.length > 0 && v.length <= 512;
+const integer = (v) => count(v) && Number.isSafeInteger(v);
+function dates(window) {
+    if (!integer(window.startMs) || !integer(window.endMs) || window.startMs > window.endMs)
+        throw new Error('Invalid usage window');
+    if (window.mode !== 'utc' && window.mode !== 'time-zone')
+        throw new Error('Gateway timezone is unsupported');
+    const zone = window.mode === 'utc' ? 'UTC' : window.timeZone;
+    const formatter = new Intl.DateTimeFormat('en-CA', { timeZone: zone, year: 'numeric', month: '2-digit', day: '2-digit' });
+    const day = (at) => {
+        const p = Object.fromEntries(formatter.formatToParts(at).map(p => [p.type, p.value]));
+        return `${p.year}-${p.month}-${p.day}`;
+    };
+    return { startDate: day(window.startMs), endDate: day(window.endMs) };
+}
+/** Only accept the kit's bounded, content-free RPC result; malformed facts make the reading unavailable. */
+export function engineStartedOf(raw, member, window) {
+    const unavailable = { state: 'unavailable', charges: [], unreadableLines: 0, complete: false };
+    if (!object(raw) || raw.agentId !== member || raw.startMs !== window.startMs || raw.endMs !== window.endMs || raw.state !== 'available' ||
+        !Array.isArray(raw.facts) || !integer(raw.unreadableLines) || !count(raw.coverageSince) || typeof raw.complete !== 'boolean')
+        return unavailable;
+    const phases = new Map();
+    for (const fact of raw.facts) {
+        if (!object(fact) || fact.v !== 1 || fact.agentId !== member || fact.kind !== 'workshop-review' ||
+            !['started', 'ended'].includes(String(fact.phase)) || !text(fact.chargeId) || !text(fact.bootId) ||
+            !text(fact.provider) || !text(fact.model) || !integer(fact.seq) || fact.seq < 1 || !count(fact.at) || !count(fact.startedAt) ||
+            (fact.authProfileId !== undefined && !text(fact.authProfileId)) ||
+            (fact.outcome !== undefined && !['nothing', 'proposed', 'applied', 'failed'].includes(String(fact.outcome))))
+            return unavailable;
+        const key = `${fact.chargeId}\0${fact.phase}`;
+        const previous = phases.get(key);
+        if (previous && JSON.stringify(previous) !== JSON.stringify(fact))
+            return unavailable;
+        phases.set(key, fact);
+    }
+    const ids = new Set([...phases.values()].map(f => f.chargeId));
+    const charges = [];
+    for (const id of ids) {
+        const ended = phases.get(`${id}\0ended`), started = phases.get(`${id}\0started`);
+        if (ended && started && ['agentId', 'bootId', 'kind', 'provider', 'model', 'authProfileId', 'startedAt'].some(k => started[k] !== ended[k]))
+            return unavailable;
+        const fact = ended ?? started;
+        const at = ended ? fact.at : fact.startedAt;
+        if (at < window.startMs || at > window.endMs)
+            continue;
+        let tokens;
+        if (object(fact.usage) && count(fact.usage.total) && ['input', 'output', 'cacheRead', 'cacheWrite', 'reasoningTokens'].every(k => fact.usage[k] === undefined || count(fact.usage[k]))) {
+            tokens = { total: fact.usage.total };
+            for (const k of ['input', 'output', 'cacheRead', 'cacheWrite', 'reasoningTokens'])
+                if (count(fact.usage[k]))
+                    tokens[k] = fact.usage[k];
+        }
+        const charge = { chargeId: id, member, kind: 'workshop-review', state: ended ? (tokens ? 'counted' : 'reported-missing') :
+                fact.bootId === raw.liveBootId ? 'pending' : 'interrupted', startedAt: fact.startedAt,
+            provider: fact.provider, model: fact.model, billing: 'unknown', tokenSource: 'engine-reported',
+            cost: { state: 'missing' }, bootId: fact.bootId, seq: fact.seq };
+        if (ended)
+            charge.endedAt = fact.at;
+        if (fact.outcome !== undefined)
+            charge.outcome = fact.outcome;
+        if (fact.authProfileId !== undefined)
+            charge.authProfileId = fact.authProfileId;
+        if (tokens && ended)
+            charge.tokens = tokens;
+        if (object(fact.origin) && text(fact.origin.sessionKey) && (fact.origin.runId === undefined || text(fact.origin.runId)))
+            charge.origin = { sessionKey: fact.origin.sessionKey, ...(fact.origin.runId ? { runId: fact.origin.runId } : {}) };
+        charges.push(charge);
+    }
+    charges.sort((a, b) => (a.endedAt ?? a.startedAt) - (b.endedAt ?? b.startedAt) || a.chargeId.localeCompare(b.chargeId));
+    return { state: 'available', coverageSince: raw.coverageSince, charges, unreadableLines: raw.unreadableLines,
+        complete: raw.complete && raw.unreadableLines === 0 && window.startMs >= raw.coverageSince && charges.every(c => c.state === 'counted') };
+}
+/** Read the transcript and Workshop terms independently. A failed term never becomes zero. */
+export async function readAgentDayUsage(client, member, window) {
+    if (!/^[a-z][a-z0-9-]{0,31}$/.test(member))
+        throw new Error('Invalid member');
+    const day = dates(window);
+    const [transcriptRaw, ledgerRaw] = await Promise.all([
+        client.call('sessions.usage', { agentId: member, ...day, mode: window.mode === 'utc' ? 'utc' : 'specific',
+            ...(window.mode === 'time-zone' ? { timeZone: window.timeZone } : {}), groupBy: 'instance', limit: 1 }).catch(() => undefined),
+        client.callDynamic('byokit.usage.engineStarted', { agentId: member, startMs: window.startMs, endMs: window.endMs }).catch(() => undefined),
+    ]);
+    const transcripts = { ...agentUsageOf(transcriptRaw, member, day), window: { ...day,
+            ...(window.mode === 'utc' ? { mode: 'utc' } : { mode: 'time-zone', timeZone: window.timeZone }) } };
+    // The pinned RPC reports calendar-day totals, not arbitrary millisecond slices. Never claim an exact partial-day total.
+    const clock = new Intl.DateTimeFormat('en-GB', { timeZone: window.mode === 'utc' ? 'UTC' : window.timeZone,
+        hour: '2-digit', minute: '2-digit', second: '2-digit', hourCycle: 'h23' });
+    if (clock.format(window.startMs) !== '00:00:00' || window.startMs % 1000 !== 0 ||
+        clock.format(window.endMs) !== '23:59:59' || window.endMs % 1000 !== 999) {
+        transcripts.state = 'unavailable';
+        delete transcripts.totals;
+    }
+    const { complete, ...engineStarted } = engineStartedOf(ledgerRaw, member, window);
+    const result = { member, window, transcripts, engineStarted, coverage: 'transcripts+workshop-review',
+        complete: complete && transcripts.state === 'available' };
+    if (transcripts.totals && engineStarted.state === 'available')
+        result.knownTotalTokens = transcripts.totals.totalTokens +
+            engineStarted.charges.reduce((n, c) => n + (c.state === 'counted' ? c.tokens.total : 0), 0);
+    return result;
+}

package/dist/device.d.ts

@@ -1,6 +1,8 @@
+import type { BrowserDevice, SignInRefusedWhy } from './browser.ts';
 import type { DeviceLink } from '@byokit/link';
+import type { RouteView } from './routes.ts';
 import { type AccountView } from './words.ts';
-import type { Approval, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, KitState, Route, RunEnd, OutputSchema, SchemaOutput, RunEvent, SignInView } from './types.ts';
+import type { Approval, Decision, GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult, KitState, RunEnd, OutputSchema, SchemaOutput, RunEvent, SignInView } from './types.ts';
 export type { GatewayEventName, GatewayEventPayload, GatewayMethod, GatewayParams, GatewayResult } from './types.ts';
 export type { Approval, Decision, KitState, PlanWindow, Route, RunEnd, RunEvent, RunUsage, SignInView, OutputSchema, SchemaOutput } from './types.ts';
 /** One `oc.events` frame: a member's Gateway event, typed by name, or an approval add/resolve (7.2). */
@@ -13,6 +15,12 @@ export type OpenClawLinkEvent = {
     event: 'approval';
     change: 'added' | 'resolved';
     approval: Approval;
+} | {
+    event: 'byokit.browser';
+    payload: {
+        member: string;
+        kind: 'state' | 'signin';
+    };
 };
 /** One `oc.sessions` row: `sessions.list` filtered to the member's `agent:<member>:` keys. */
 export type SessionRow = {
@@ -55,9 +63,25 @@ export declare class LinkRefused extends Error {
     readonly sealed = true;
     constructor(message: string);
 }
+export declare class BrowserRefused extends LinkRefused {
+    readonly why: SignInRefusedWhy;
+    constructor(why: SignInRefusedWhy);
+}
+export type SignInNotice = {
+    source: 'signin';
+    id: string;
+    gen: number;
+    member: string;
+    site: string;
+};
+/** A sealed hint, never an authorization or a lease. Re-fetch signIns() before taking any action. */
+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): {
+    browser: BrowserDevice;
     state(): Promise<DeviceState>;
-    routes(): Promise<Route[]>;
+    routes(): Promise<RouteView[]>;
     signIn: {
         start(p: string, via: 'browser' | 'code'): Promise<SignInView>;
         view(p: string): Promise<AccountView>;
@@ -79,6 +103,12 @@ export declare function openclawDevice(link: DeviceLink): {
     registerNotices(seed: Uint8Array): Promise<void>;
     openNotice(data: Record<string, unknown>, seed: Uint8Array): Approval | null;
     call<M extends GatewayMethod>(method: M, params: GatewayParams<M>): Promise<GatewayResult<M>>;
+    callDynamic(method: string, params?: unknown): Promise<unknown>;
 };
 export { openNotice } from './notices.ts';
+export { readAgentUsage, agentUsageOf } from './usage.ts';
+export { readAgentDayUsage } from './day-usage.ts';
+export type { AgentDayUsage, EngineStartedCharge, EngineStartedKind } from './day-usage.ts';
+export type { AgentUsageReading, LedgerUsageTotals, UsageCache, 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';
 export { stateWords, toAccountView, words, type AccountView, type WordKey } from './words.ts';

package/dist/device.js

@@ -1,8 +1,6 @@
-// The device side (7.2): portable — browsers, React Native, Node; no node:* or Node-only imports may reach here
-// (test/portable.test.ts guards it). Only type imports from @byokit/link; the seal crypto bundles cleanly.
-import { boxKeyPairFromSeed } from '@byokit/seal';
+import { openBoxFromSeed, boxKeyPairFromSeed } from '@byokit/seal';
 import { toAccountView } from "./words.js";
-import { b64urlEncode, openNotice } from "./notices.js";
+import { b64urlDecode, b64urlEncode, openNotice } from "./notices.js";
 /**
  * The host ended a stream with its own words (e.g. a refusal). Portable twin of link's PublicLinkError:
  * same shape ({ code: 'failed', sealed: true }) so a screen can show .message the same way. A device-side
@@ -16,6 +14,10 @@ export class LinkRefused extends Error {
         this.name = 'LinkRefused';
     }
 }
+export class BrowserRefused extends LinkRefused {
+    why;
+    constructor(why) { super(`Sign-in refused: ${why}`); this.why = why; }
+}
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 /**
  * Newline-delimited JSON frames off a link stream, in order. A host end with an error becomes a
@@ -115,8 +117,223 @@ function liveStream(open) {
         },
     };
 }
+/** A sealed hint, never an authorization or a lease. Re-fetch signIns() before taking any action. */
+export function openSignInNotice(data, seed) {
+    if (data.v !== 1 || typeof data.sealed !== 'string' || !(seed instanceof Uint8Array) || seed.length !== 32)
+        return null;
+    const bundle = b64urlDecode(data.sealed);
+    const bytes = bundle && openBoxFromSeed(bundle, seed);
+    if (!bytes)
+        return null;
+    try {
+        const v = JSON.parse(new TextDecoder().decode(bytes));
+        if (!isRecord(v) || v.source !== 'signin' || typeof v.id !== 'string' || !Number.isSafeInteger(v.gen)
+            || typeof v.member !== 'string' || typeof v.site !== 'string')
+            return null;
+        return { source: 'signin', id: v.id, gen: v.gen, member: v.member, site: v.site };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        bytes.fill(0);
+    }
+}
+function decodeBrowserFrame(value) {
+    if (!isRecord(value) || typeof value.jpeg !== 'string' || value.jpeg.length > 8 * 1024 * 1024
+        || !Number.isSafeInteger(value.seq) || !Number.isSafeInteger(value.w) || !Number.isSafeInteger(value.h)
+        || value.w < 1 || value.h < 1 || typeof value.at !== 'number' || !Number.isFinite(value.at))
+        throw new LinkRefused('Invalid browser frame');
+    const jpeg = b64urlDecode(value.jpeg);
+    if (!jpeg)
+        throw new LinkRefused('Invalid browser frame');
+    return { seq: value.seq, w: value.w, h: value.h, at: value.at, jpeg };
+}
+/** Transient streams bypass link's durable request/answer cache: no lease nonce or frame is persisted. */
+export function browserDevice(link) {
+    const call = async (op, args = {}) => {
+        const it = liveStream(() => link.stream(`oc.browser.${op}`, args))[Symbol.asyncIterator]();
+        try {
+            const reply = await it.next();
+            if (!reply.done && isRecord(reply.value) && typeof reply.value.refused === 'string')
+                throw new BrowserRefused(reply.value.refused);
+            if (reply.done || !isRecord(reply.value) || !('value' in reply.value))
+                throw new LinkRefused('Browser request ended');
+            return reply.value.value;
+        }
+        finally {
+            await it.return?.();
+        }
+    };
+    return {
+        state: member => call('state', { member }),
+        signIns: () => call('signins'),
+        takeover: (id, gen, o) => call('takeover', { id, gen, ...o }),
+        confirmOrigin: async (lease, origin) => { await call('confirmorigin', { lease, origin }); },
+        done: lease => call('done', { lease }),
+        notNow: (id, gen) => call('notnow', { id, gen }),
+        reopen: (id, gen) => call('reopen', { id, gen }),
+        retry: (id, gen) => call('retry', { id, gen }),
+        cancel: (id, gen) => call('cancel', { id, gen }),
+        forget: async (member, site) => { await call('forget', { member, site }); },
+        thumbnail: async (source) => {
+            const result = await call('thumb', { source });
+            return result.state === 'ok' ? { state: 'ok', frame: decodeBrowserFrame(result.frame) } : result;
+        },
+        live: (source, o) => {
+            let stream;
+            let closed = false;
+            let ended = false;
+            let inputBusy = false;
+            let inputBytes = 0;
+            const inputs = [];
+            let text = '';
+            let frame;
+            let state = { source, mode: o?.lease ? 'control' : 'observe', phase: 'connecting' };
+            const frameWaiters = new Set();
+            const stateWaiters = new Set();
+            const wake = () => {
+                for (const w of [...frameWaiters, ...stateWaiters])
+                    w();
+                frameWaiters.clear();
+                stateWaiters.clear();
+            };
+            const close = () => {
+                closed = ended = true;
+                frame = undefined;
+                state = undefined;
+                text = '';
+                inputs.length = 0;
+                inputBytes = 0;
+                stream?.end('closed');
+                wake();
+            };
+            const finish = (error) => {
+                if (closed || ended)
+                    return;
+                ended = true;
+                frame = undefined;
+                text = '';
+                inputs.length = 0;
+                inputBytes = 0;
+                state = { source, mode: o?.lease ? 'control' : 'observe',
+                    phase: error === 'unreachable' ? 'reconnecting' : error ? 'failed' : 'ended',
+                    ...(error === 'removed' ? { why: 'revoked' } : {}) };
+                wake();
+            };
+            const flushInput = async () => {
+                if (inputBusy || !stream || closed || ended)
+                    return;
+                inputBusy = true;
+                try {
+                    while (inputs.length && !closed && !ended) {
+                        const value = inputs.shift();
+                        await stream.write(value);
+                        if (!closed && !ended)
+                            inputBytes -= new TextEncoder().encode(value).byteLength;
+                    }
+                }
+                catch {
+                    finish('failed');
+                    stream.end('failed');
+                }
+                finally {
+                    inputBusy = false;
+                }
+            };
+            const decoder = new TextDecoder();
+            void link.stream('oc.browser.live', { source, mode: o?.lease ? 'control' : 'observe', ...o }).then(s => {
+                if (closed) {
+                    s.end();
+                    return;
+                }
+                stream = s;
+                s.onData = chunk => {
+                    if (closed || ended)
+                        return;
+                    try {
+                        text += decoder.decode(chunk, { stream: true });
+                        if (text.length > 9 * 1024 * 1024)
+                            throw new Error();
+                        let at;
+                        while ((at = text.indexOf('\n')) >= 0) {
+                            const v = JSON.parse(text.slice(0, at));
+                            text = text.slice(at + 1);
+                            if (!isRecord(v))
+                                throw new Error();
+                            if ('frame' in v)
+                                frame = decodeBrowserFrame(v.frame);
+                            else if (isRecord(v.state)) {
+                                state = v.state;
+                                if (state.phase !== 'live')
+                                    frame = undefined;
+                                if (state.phase === 'ended' || state.phase === 'failed') {
+                                    ended = true;
+                                    inputs.length = 0;
+                                    inputBytes = 0;
+                                }
+                            }
+                            else
+                                throw new Error();
+                        }
+                        wake();
+                    }
+                    catch {
+                        finish('failed');
+                        s.end('failed');
+                    }
+                };
+                s.onEnd = finish;
+            }, () => finish('failed'));
+            const channel = (take, waiters) => ({
+                [Symbol.asyncIterator]() {
+                    return {
+                        async next() {
+                            for (;;) {
+                                if (closed)
+                                    return { value: undefined, done: true };
+                                const value = take();
+                                if (value !== undefined)
+                                    return { value, done: false };
+                                if (ended)
+                                    return { value: undefined, done: true };
+                                await new Promise(resolve => waiters.add(resolve));
+                            }
+                        },
+                        async return() { close(); return { value: undefined, done: true }; },
+                    };
+                },
+            });
+            return {
+                states: channel(() => { const s = state; state = undefined; return s; }, stateWaiters),
+                frames: channel(() => { const f = frame; frame = undefined; return f; }, frameWaiters),
+                input: i => {
+                    // Ordered, bounded memory-only input while online. Never replay secret input after a drop.
+                    if (closed || ended || !o?.lease)
+                        return;
+                    if (!stream) {
+                        finish('failed');
+                        return;
+                    }
+                    const value = `${JSON.stringify(i)}\n`;
+                    const bytes = new TextEncoder().encode(value).byteLength;
+                    if (inputBytes + bytes > 65536) {
+                        finish('failed');
+                        stream.end('failed');
+                        return;
+                    }
+                    inputs.push(value);
+                    inputBytes += bytes;
+                    void flushInput();
+                },
+                close,
+            };
+        },
+    };
+}
 export function openclawDevice(link) {
     return {
+        browser: browserDevice(link),
         state: () => link.request('oc.state'),
         routes: () => link.request('oc.routes'),
         signIn: {
@@ -186,10 +403,13 @@ export function openclawDevice(link) {
             await link.request('oc.notices.register', { boxPublicKey: b64urlEncode(boxKeyPairFromSeed(seed).publicKey) });
         },
         openNotice,
+        callDynamic: (method, params) => link.request('oc.call', { method, params }),
         call: (method, params) => link.request('oc.call', { method, params }),
     };
 }
 // Portable, re-exported by ./device (7.3).
 export { openNotice } from "./notices.js";
+export { readAgentUsage, agentUsageOf } from "./usage.js";
+export { readAgentDayUsage } from "./day-usage.js";
 // The kit's sentences, so a phone or browser shows the same words the computer does (5.14).
 export { stateWords, toAccountView, words } from "./words.js";