@byokit/openclaw 0.5.1 → 0.6.1

package/dist/runs.js

@@ -84,6 +84,10 @@ export function createRuns(ctx) {
         // Member boundary first: a member never speaks in another member's session, refused before any request.
         if (!spec.sessionKey.startsWith(`agent:${spec.member}:`))
             throw new Error(`refused: "${spec.sessionKey}" is not a session of member "${spec.member}"`);
+        // Same validation as the pin's NonEmptyString; preserve the caller's bytes (including whitespace).
+        if (spec.idempotencyKey !== undefined && (typeof spec.idempotencyKey !== 'string' || !spec.idempotencyKey.length))
+            throw new Error('refused: idempotencyKey must be a non-empty string');
+        const idempotencyKey = spec.idempotencyKey ?? randomUUID();
         const output = preparedOutput ?? (spec.schema === undefined ? undefined : outputSchema(spec.schema));
         const system = [spec.system, output?.prompt].filter(Boolean).join('\n\n');
         const picked = spec.model === undefined ? undefined : account(spec.model);
@@ -92,7 +96,7 @@ export function createRuns(ctx) {
                 throw new Error(`refused: "${tool}" is not one of this kit's tools`);
         const agentId = keyAgent ?? (await ctx.ensure(spec.member)).agentId;
         const sessionKey = keyAgent ? `agent:${keyAgent}:${spec.sessionKey.slice(`agent:${spec.member}:`.length)}` : spec.sessionKey;
-        const release = spec.register !== false ? ctx.bridge.register({ sessionKey, member: spec.member }, spec.tools) : undefined;
+        const release = spec.register !== false ? ctx.bridge.register({ sessionKey, member: spec.member }, spec.tools, idempotencyKey) : undefined;
         let last;
         let runId = ''; // gateway events for other runs carry a real runId and never match the empty one
         let ended = false;
@@ -155,7 +159,7 @@ export function createRuns(ctx) {
                 agentId,
                 sessionKey,
                 message: spec.message,
-                idempotencyKey: randomUUID(),
+                idempotencyKey,
                 ...(picked ?? {}),
                 ...(system ? { extraSystemPrompt: system } : {}),
                 ...(spec.images ? { attachments: spec.images.map((image) => ({ mimeType: image.mimeType, content: image.data })) } : {}),
@@ -166,6 +170,8 @@ export function createRuns(ctx) {
             runId = started.runId;
             const result = await ctx.request('agent.wait', { runId, timeoutMs: WAIT_MS }, { timeoutMs: WAIT_CLIENT_MS });
             if (result.status === 'ok') {
+                // A cached `in_flight` replay has no final subscription. Keep the existing wait/stream fallback:
+                // re-sending `agent` to fetch its final could dispatch again if the bounded cache was evicted.
                 const done = await Promise.race([final.catch(() => undefined), delay(FINAL_GRACE_MS, undefined, { ref: false })]);
                 ended = true; // no later stream event may supersede the final callback
                 const frame = isRecord(done) && isRecord(done.result) ? done.result : {};

package/dist/signin.d.ts

@@ -9,7 +9,7 @@ export type SignInCtx = {
 };
 /**
  * Drive the engine's provider-owned login. `on` sees every view the person watches; `done` resolves once, and
- * `paste` hands a returned browser address to a waiting wizard text step. Every exit short of done cancels this
+ * `paste` hands a returned browser address or sign-in token to a waiting wizard text step. Every exit short of done cancels this
  * session and its callback listener only.
  */
 export declare function signIn(ctx: SignInCtx, member: Member, o: SignInOptions, on: (v: SignInView) => void): {

package/dist/signin.js

@@ -19,7 +19,7 @@ const cut = (value) => (value instanceof Error ? value.message : String(value)).
 const pullOptions = (signal) => ({ timeoutMs: PULL_MS, signal });
 /**
  * Drive the engine's provider-owned login. `on` sees every view the person watches; `done` resolves once, and
- * `paste` hands a returned browser address to a waiting wizard text step. Every exit short of done cancels this
+ * `paste` hands a returned browser address or sign-in token to a waiting wizard text step. Every exit short of done cancels this
  * session and its callback listener only.
  */
 export function signIn(ctx, member, o, on) {
@@ -68,10 +68,15 @@ export function signIn(ctx, member, o, on) {
     let settle;
     let pasteIn;
     let returned;
+    // Once a secret step is seen, no later gateway prose, link or code is safe to display.
+    let sensitive = o.authChoice === 'setup-token' || o.authChoice === 'apiKey';
+    const secretFailure = () => o.authChoice === 'apiKey' ? 'API key activation failed' : 'Sign-in failed. Try again.';
     const done = new Promise((resolve) => { settle = resolve; });
     const say = (v) => {
         if (!over && !recovering && !signal.aborted)
-            on({ state: 'waiting', via, ...v });
+            on({ state: 'waiting', via, ...(sensitive
+                    ? { ...(v.prompt ? { prompt: v.prompt } : {}), ...(v.error ? { error: secretFailure() } : {}) }
+                    : v) });
     };
     const closeCallback = async () => {
         const held = server;
@@ -90,6 +95,8 @@ export function signIn(ctx, member, o, on) {
         returned = undefined;
         pasteIn = undefined;
         await closeCallback();
+        if (sensitive && view.state === 'failed' && view.why === 'failed')
+            view = { ...view, error: secretFailure() };
         on(view);
         settle(view);
     };
@@ -218,6 +225,10 @@ export function signIn(ctx, member, o, on) {
         const pull = () => ctx.request('wizard.next', { sessionId }, options());
         const answer = (step, value) => ctx.request('wizard.next', { sessionId, answer: { stepId: step.id, ...(value === undefined ? {} : { value }) } }, options());
         const waitForPaste = () => new Promise((resolve) => {
+            if (signal.aborted) {
+                resolve(undefined);
+                return;
+            }
             if (returned !== undefined) {
                 const text = returned;
                 returned = undefined;
@@ -255,7 +266,9 @@ export function signIn(ctx, member, o, on) {
             }
             const current = step;
             step = undefined;
-            if (current.deviceCode) {
+            if (current.type === 'text' && current.sensitive)
+                sensitive = true;
+            if (current.deviceCode && current.type !== 'text') {
                 stopApproval();
                 approval = true;
                 sawDeviceCode = true;
@@ -278,7 +291,9 @@ export function signIn(ctx, member, o, on) {
             }
             if (current.type !== 'progress')
                 stopApproval();
-            if (current.type === 'text' && !current.sensitive) {
+            if (current.type === 'text') {
+                if (current.sensitive)
+                    say({ prompt: 'Sign-in token' });
                 const value = await waitForPaste();
                 if (value === undefined)
                     return signal.aborted ? cancelled() : expired();

package/dist/testing/browser.d.ts

@@ -0,0 +1,50 @@
+import type { BrowserHost, BrowserOptions, LiveFrame, NeedSignIn } from '../browser.ts';
+import { type BrowserHostController, type HostBroker } from '../browser/host.ts';
+import { type SignInStore } from '../browser/store.ts';
+import type { Probe } from '../browser/verify.ts';
+export declare function memorySignInStore(): SignInStore;
+export type BrowserFixture = {
+    /** Set the synthetic address bar; no network call. */
+    navigate(member: string, origin: string): void;
+    authenticated(member: string, value: boolean): void;
+    frame(member: string, frame?: LiveFrame): void;
+    dropStreams(member: string): void;
+    advance(ms: number): Promise<void>;
+    resumeOutcome(value: 'accepted' | 'refused' | 'unknown' | 'throw'): void;
+    closePrivate(member: string, fn: (() => Promise<void>) | undefined): void;
+    probe(member: string, fn: ((p: Probe) => Promise<'ok' | 'fail' | 'timeout'>) | undefined): void;
+    readonly dispatches: {
+        member: string;
+        sessionKey: string;
+        idempotencyKey: string;
+        message: string;
+    }[];
+    readonly parked: {
+        member: string;
+        sessionKey: string;
+    }[];
+    readonly calls: string[];
+    broker(member: string): HostBroker;
+    inputCount(member: string): number;
+    privateOpen(member: string): boolean;
+    fenced(member: string): boolean;
+};
+export type FakeBrowserHost = BrowserHostController & {
+    readonly fixture: BrowserFixture;
+};
+export type FakeBrowserHostOptions = {
+    members?: string[];
+    options?: Partial<BrowserOptions>;
+    store?: SignInStore;
+    authorize?: (grant: string, member: string, control: boolean) => boolean;
+    ping?: (member: string, kind: 'state' | 'signin') => void;
+};
+export declare function fakeBrowserHost(o?: FakeBrowserHostOptions): Promise<FakeBrowserHost>;
+export declare const createBrowserHostFake: typeof fakeBrowserHost;
+/** Reusable public-host contract, fixture controls kept outside BrowserHost. Runs against any host adapter. */
+export declare function browserHostContract(f: {
+    host: BrowserHost;
+    raise(): Promise<NeedSignIn>;
+    signedIn(): void;
+    dispatches(): number;
+}): Promise<void>;

package/dist/testing/browser.js

@@ -0,0 +1,166 @@
+import { fixtureBrowserHost, secureOrigin } from "../browser/host.js";
+import { emptySignIns, validateSignIns } from "../browser/store.js";
+function channel() {
+    let pending;
+    let value;
+    let ended = false;
+    return {
+        push(next) { if (ended)
+            return; if (pending) {
+            const resolve = pending;
+            pending = undefined;
+            resolve({ done: false, value: next });
+        }
+        else
+            value = next; },
+        close() { ended = true; value = undefined; pending?.({ done: true, value: undefined }); pending = undefined; },
+        iterable: { [Symbol.asyncIterator]() {
+                return {
+                    next() {
+                        if (value !== undefined) {
+                            const next = value;
+                            value = undefined;
+                            return Promise.resolve({ done: false, value: next });
+                        }
+                        if (ended)
+                            return Promise.resolve({ done: true, value: undefined });
+                        return new Promise(resolve => { pending = resolve; });
+                    },
+                    return() { ended = true; pending?.({ done: true, value: undefined }); return Promise.resolve({ done: true, value: undefined }); },
+                };
+            } },
+    };
+}
+export function memorySignInStore() {
+    let data = emptySignIns();
+    return { read: () => structuredClone(data), write: next => { data = validateSignIns(next); } };
+}
+export async function fakeBrowserHost(o = {}) {
+    const members = o.members ?? ['ada'];
+    const states = new Map(members.map(member => [member, { origin: 'http://127.0.0.1:2820', privateOrigin: undefined,
+            fenced: false, signedIn: false, binding: undefined,
+            confirmed: new Set(), viewers: new Set(), inputs: 0,
+            closer: undefined, prober: undefined }]));
+    const get = (member) => { const s = states.get(member); if (!s)
+        throw new Error('unknown fixture member'); return s; };
+    const privateState = (member) => {
+        const s = get(member);
+        return s.privateOrigin ? { origin: s.privateOrigin, secure: secureOrigin(s.privateOrigin), offOrigin: !s.binding
+                || !(s.privateOrigin === s.binding.origin || s.binding.knownIdps.includes(s.privateOrigin) || s.confirmed.has(s.privateOrigin)) } : undefined;
+    };
+    const calls = [];
+    const dispatches = [];
+    const parked = [];
+    let now = Date.now();
+    let outcome = 'accepted';
+    let seq = 0;
+    const frame = () => ({ seq: ++seq, at: now, w: 1, h: 1, jpeg: Uint8Array.of(255, 216, 255, 217) });
+    const brokers = new Map(members.map(member => {
+        const s = get(member);
+        return [member, {
+                endpoint: () => ({ cdpUrl: 'ws://127.0.0.1:2820/devtools/browser?token=synthetic' }),
+                async fence(on) { calls.push(`${member}:fence:${on}`); s.fenced = on; },
+                agentTab: () => 'agent',
+                async originOf(target) { return target === 'private' ? s.privateOrigin ?? s.origin : s.origin; },
+                async openPrivate(url) { calls.push(`${member}:open`); s.privateOrigin = new URL(url).origin; return 'private'; },
+                async closePrivate() { calls.push(`${member}:close`); await s.closer?.(); s.privateOrigin = undefined; },
+                async probe(url, verify) {
+                    calls.push(`${member}:probe`);
+                    const p = { url, status: s.signedIn ? 200 : 401, exists: async () => s.signedIn };
+                    return s.prober ? s.prober(p) : await verify(p) ? 'ok' : 'fail';
+                },
+                attachViewer({ lease }) {
+                    const frames = channel();
+                    const liveStates = channel();
+                    const v = { frames, states: liveStates, lease, close: () => { frames.close(); liveStates.close(); s.viewers.delete(v); } };
+                    s.viewers.add(v);
+                    frames.push(frame());
+                    const state = privateState(member);
+                    if (lease && state)
+                        liveStates.push(state);
+                    return { frames: frames.iterable, states: liveStates.iterable,
+                        input(_i) {
+                            // Do not retain, log, event or echo input values, even in this fixture.
+                            const state = privateState(member);
+                            if (lease && s.binding?.epoch === lease.epoch && s.binding.nonce === lease.nonce && state?.secure && !state.offOrigin)
+                                s.inputs++;
+                        }, close: v.close };
+                },
+                async navigateAgent(url) { calls.push(`${member}:navigate`); if (url !== 'reload')
+                    s.origin = new URL(url).origin; },
+                async close() { s.viewers.forEach(v => v.close()); s.privateOrigin = undefined; },
+                bindLease(l) { calls.push(`${member}:bind:${l ? 'on' : 'off'}`); s.binding = l; s.confirmed.clear(); },
+                confirmOrigin(l, origin) {
+                    if (s.binding?.epoch !== l.epoch || s.binding.nonce !== l.nonce || s.privateOrigin !== origin)
+                        return false;
+                    s.confirmed.add(origin);
+                    const state = privateState(member);
+                    if (state)
+                        s.viewers.forEach(v => v.states.push(state));
+                    return true;
+                },
+                privateState: () => privateState(member),
+                async clearSite(origins) { if (s.fenced)
+                    throw new Error('fixture fenced'); calls.push(`${member}:clear:${origins.length}`); s.signedIn = false; },
+            }];
+    }));
+    const defaultVerifier = { origin: 'http://127.0.0.1:2820', url: 'http://127.0.0.1:2820/account', status: 200, selector: '#signed-in' };
+    const host = await fixtureBrowserHost({ brokers, store: o.store ?? memorySignInStore(),
+        options: { executablePath: '/synthetic/chromium', members, verifiers: [defaultVerifier], ...o.options },
+        authorize: o.authorize ?? ((grant, member, control) => members.includes(member) && (grant === 'control' || grant === 'other' || (!control && grant === 'view'))),
+        ping: o.ping,
+        park: async (member, sessionKey) => { parked.push({ member, sessionKey }); },
+        resume: async (input) => { dispatches.push(input); if (outcome === 'throw')
+            throw new Error('synthetic transport drop'); return outcome; },
+        siteOf: origin => new URL(origin).hostname,
+        now: () => now,
+    });
+    const fixture = {
+        navigate(member, origin) {
+            const s = get(member);
+            const exact = new URL(origin).origin;
+            if (s.privateOrigin)
+                s.privateOrigin = exact;
+            else
+                s.origin = exact;
+            const state = privateState(member);
+            if (state)
+                s.viewers.forEach(v => v.states.push(state));
+        },
+        authenticated(member, value) { get(member).signedIn = value; },
+        frame(member, value) { get(member).viewers.forEach(v => v.frames.push(value ?? frame())); },
+        dropStreams(member) { get(member).viewers.forEach(v => v.close()); },
+        async advance(ms) { now += ms; await host.sweep(); },
+        resumeOutcome(value) { outcome = value; },
+        closePrivate(member, fn) { get(member).closer = fn; },
+        probe(member, fn) { get(member).prober = fn; },
+        dispatches, parked, calls,
+        broker: member => { const broker = brokers.get(member); if (!broker)
+            throw new Error('unknown fixture member'); return broker; },
+        inputCount: member => get(member).inputs,
+        privateOpen: member => !!get(member).privateOrigin,
+        fenced: member => get(member).fenced,
+    };
+    return Object.assign(host, { fixture });
+}
+export const createBrowserHostFake = fakeBrowserHost;
+/** Reusable public-host contract, fixture controls kept outside BrowserHost. Runs against any host adapter. */
+export async function browserHostContract(f) {
+    const require = (value) => { if (!value)
+        throw new Error('browser host contract failed'); };
+    const r = await f.raise();
+    require(r.state === 'waiting');
+    require((await f.host.thumbnail({ kind: 'browser', member: r.member }, { grant: 'view' })).state === 'private');
+    const lease = await f.host.takeover(r.id, r.gen, { grant: 'control', confirmSite: r.site });
+    f.signedIn();
+    const settled = await f.host.done(lease);
+    require(settled.state === 'settled' && settled.settled?.state === 'verified' && !!settled.settled.resume?.key);
+    require(f.dispatches() === 1);
+    try {
+        await f.host.done(lease);
+    }
+    catch {
+        return;
+    }
+    throw new Error('browser host contract failed');
+}

package/dist/testing/index.d.ts

@@ -1,3 +1,4 @@
 export { fakeGateway, type FakeScript } from './fake-gateway.ts';
+export { fakeBrowserHost, createBrowserHostFake, browserHostContract, memorySignInStore, type FakeBrowserHost, type FakeBrowserHostOptions, type BrowserFixture } from './browser.ts';
 export { openclawContract, type ContractFixture } from './contract.ts';
 export { STUB_USAGE, startModelStub, useModelStub, releaseStub, stubHolding, toolCalls, type ModelStub, type ModelStubOptions, type StubCall } from './model-stub.ts';

package/dist/testing/index.js

@@ -1,4 +1,5 @@
 // The kit's fakes, contract suite and scripted model (5.11). Built in O7.
 export { fakeGateway } from "./fake-gateway.js";
+export { fakeBrowserHost, createBrowserHostFake, browserHostContract, memorySignInStore } from "./browser.js";
 export { openclawContract } from "./contract.js";
 export { STUB_USAGE, startModelStub, useModelStub, releaseStub, stubHolding, toolCalls } from "./model-stub.js";

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

@@ -30,6 +30,7 @@ export declare const stubHolding: (key?: string) => boolean;
 export type ModelStubOptions = {
     idPattern?: RegExp;
     routingMarker?: string;
+    onCall?: (call: StubCall) => void;
 };
 export declare function startModelStub(script?: string[], o?: ModelStubOptions): Promise<ModelStub>;
 export declare function useModelStub(kit: OpenClawKit, stub: ModelStub): Promise<void>;

package/dist/testing/model-stub.js

@@ -76,7 +76,9 @@ export function startModelStub(script = [], o = {}) {
             res.writeHead(400).end();
             return;
         }
-        calls.push({ authorization: String(req.headers.authorization ?? ''), path: req.url ?? '', body });
+        const call = { authorization: String(req.headers.authorization ?? ''), path: req.url ?? '', body };
+        calls.push(call);
+        o.onCall?.(call); // Fixture evidence is persisted before any response/hold awaits.
         if (req.url === '/api/embed' || req.url === '/api/embeddings') {
             res.writeHead(200, { 'content-type': 'application/json' });
             return res.end(JSON.stringify({

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { OutputSchema } from './output.ts';
+import type { GatewayEventName, GatewayEventPayload } from './generated/events.ts';
 export type { OutputSchema, SchemaOutput } from './output.ts';
 export type Member = string;
 export interface ToolSpec {
@@ -29,6 +30,9 @@ export interface ToolHost {
 }
 export interface RunSpec<S extends OutputSchema | undefined = OutputSchema | undefined> extends RunRef {
     message: string;
+    /** Stable per-dispatch action key; omit for a fresh UUID. Gateway-wide across agents/sessions for `agent`.
+     * Reuse only for the same input/attempt. In-memory bounded cache, not exactly-once across engine restarts. */
+    idempotencyKey?: string;
     schema?: S;
     system?: string;
     images?: {
@@ -121,8 +125,9 @@ export type Decision = {
 };
 export type KitState = {
     phase: 'stopped' | 'installing' | 'starting' | 'repairing' | 'ready' | 'restarting' | 'failed' | 'needs-update' | 'locked';
-    why?: 'install' | 'handshake' | 'exited' | 'port' | 'version' | 'engine-already-running';
+    why?: 'install' | 'handshake' | 'exited' | 'port' | 'version' | 'engine-already-running' | 'engine-patch';
     retryAt?: number;
+    patchSet?: string | null;
 };
 export type Hello = {
     protocol: number;
@@ -136,13 +141,48 @@ export type Route = {
     choice: string;
     provider: string;
     plugin: string;
-    billing: 'subscription' | 'api' | 'local';
+    billing: 'subscription' | 'api' | 'local' | 'free' | 'unknown';
     auth?: 'cli' | 'api_key' | 'token';
     terms?: 'allowed' | 'grey';
     termsUrl?: string;
-    via: 'browser' | 'code';
+    via: 'browser' | 'code' | 'paste' | 'key' | 'setup_token' | 'cli' | 'plan_key' | 'cloud' | 'local' | 'endpoint';
     prerequisite: string | null;
     offer: boolean;
+    id?: string;
+    name?: string;
+    company?: string;
+    aliases?: string[];
+    offerPolicy?: 'default' | 'explicit';
+    legacy?: {
+        provider: string;
+        via: 'browser' | 'code';
+    };
+    billingFrom?: 'source' | 'host';
+    group?: 'models' | 'services';
+    platforms?: {
+        node: 'yes' | 'host' | 'no';
+        browser: 'yes' | 'host' | 'no';
+        rn: 'yes' | 'host' | 'no';
+    };
+    needs?: {
+        binary?: string;
+        plugin?: string;
+        client?: string;
+    };
+    install?: {
+        npmSpec?: string;
+        clawhubSpec?: string;
+        minHostVersion?: string;
+    };
+    upstream?: {
+        surface: 'openclaw';
+        id: string;
+        method?: string;
+        revision: string;
+        flow: 'present' | 'absent';
+    };
+    readiness?: 'ready' | 'needs_binary' | 'needs_plugin' | 'needs_host' | 'needs_client' | 'unsupported_platform' | 'no_upstream_flow';
+    why?: string;
     reason: string;
     source: string;
     revision: string;
@@ -173,5 +213,12 @@ export type CallOptions = {
     timeoutMs?: number | null;
     signal?: AbortSignal;
 };
+/** Kit-owned invalidation only: no origin, URL, input value or lease secret. */
+export type BrowserPing = {
+    member: Member;
+    kind: 'state' | 'signin';
+};
+export type KitEventName = GatewayEventName | 'byokit.browser';
+export type KitEventPayload<E extends KitEventName> = E extends 'byokit.browser' ? BrowserPing : GatewayEventPayload<Extract<E, GatewayEventName>>;
 export type { GatewayMethod, GatewayParams, GatewayResult } from './generated/methods.ts';
 export type { GatewayEventName, GatewayEventPayload } from './generated/events.ts';

package/dist/usage-boots.d.ts

@@ -0,0 +1,8 @@
+export declare function appendUsageBoot(dir: string, record: {
+    bootId: string;
+} & ({
+    startedAt: number;
+} | {
+    failedAt: number;
+    spawned: false;
+})): void;

package/dist/usage-boots.js

@@ -0,0 +1,26 @@
+// Internal lifecycle records. Accounting UUIDs never participate in process ownership or liveness.
+import { closeSync, fsyncSync, openSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+export function appendUsageBoot(dir, record) {
+    let fd;
+    try {
+        fd = openSync(join(dir, 'boots.jsonl'), 'a', 0o600);
+        const line = Buffer.from(JSON.stringify(record) + '\n');
+        if (writeSync(fd, line) !== line.length)
+            throw new Error();
+        fsyncSync(fd);
+    }
+    catch {
+        throw new Error('Usage boot record could not be made durable');
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                throw new Error('Usage boot record could not be made durable');
+            }
+        }
+    }
+}

package/dist/usage.d.ts

@@ -0,0 +1,51 @@
+import type { SessionsUsageParams } from '@openclaw/gateway-protocol';
+import type { CallOptions, Member } from './types.ts';
+export type UsageWindow = {
+    startDate: string;
+    endDate: string;
+};
+/** Engine-reported counters. Price totals are not a bill, and zero with missingCostEntries is unknown cost. */
+export type LedgerUsageTotals = {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    totalCost: number;
+    inputCost: number;
+    outputCost: number;
+    cacheReadCost: number;
+    cacheWriteCost: number;
+    missingCostEntries: number;
+    missingCostByModel?: Record<string, number>;
+};
+export type UsageCache = {
+    status: 'fresh' | 'refreshing' | 'partial' | 'stale';
+    cachedFiles: number;
+    pendingFiles: number;
+    staleFiles: number;
+    refreshedAt?: number;
+};
+export type AgentUsageReading = {
+    member: Member;
+    window: UsageWindow & {
+        mode: 'utc';
+    };
+    receivedAt: number;
+    /** Result assembly time, not latest model call time. */
+    updatedAt?: number;
+    cache?: UsageCache;
+    /** Detached Workshop reviews are omitted; other internal turns only count when persisted. */
+    coverage: 'retained-transcripts-only';
+    state: 'available' | 'unavailable';
+    /** Observed ledger counters only. Absent on missing, malformed, refreshing or stale data. */
+    totals?: LedgerUsageTotals;
+    /** Complete original response, including session rows, day aggregates and unknown extensions. */
+    raw: unknown;
+};
+/** Normalize an explicitly agent-scoped UTC response. No missing datum is replaced with zero. */
+export declare function agentUsageOf(raw: unknown, member: Member, window: UsageWindow, receivedAt?: number): AgentUsageReading;
+/** Works with kit.call or the portable device.call; retains the complete existing pass-through. RPC errors reject. */
+export declare function readAgentUsage(client: {
+    call(method: 'sessions.usage', params: SessionsUsageParams, options?: CallOptions): Promise<unknown>;
+}, member: Member, window: UsageWindow, options?: CallOptions): Promise<AgentUsageReading>;

package/dist/usage.js

@@ -0,0 +1,61 @@
+const record = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const count = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+const buckets = ['input', 'output', 'cacheRead', 'cacheWrite', 'totalTokens', 'totalCost', 'inputCost', 'outputCost',
+    'cacheReadCost', 'cacheWriteCost', 'missingCostEntries'];
+function totalsOf(v) {
+    if (!record(v) || !buckets.every(k => count(v[k])))
+        return;
+    if (v.missingCostByModel !== undefined && (!record(v.missingCostByModel) || !Object.values(v.missingCostByModel).every(count)))
+        return;
+    return v;
+}
+function cacheOf(v) {
+    if (!record(v) || !['fresh', 'refreshing', 'partial', 'stale'].includes(String(v.status)) ||
+        !['cachedFiles', 'pendingFiles', 'staleFiles'].every(k => count(v[k])) ||
+        (v.refreshedAt !== undefined && !count(v.refreshedAt)))
+        return;
+    return v;
+}
+function validate(member, window) {
+    if (!/^[a-z][a-z0-9-]{0,31}$/.test(member))
+        throw new Error('Invalid member');
+    for (const day of [window.startDate, window.endDate]) {
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(day) || !Number.isFinite(Date.parse(day)) || new Date(day).toISOString().slice(0, 10) !== day)
+            throw new Error('Expected a valid YYYY-MM-DD calendar date');
+    }
+    if (window.startDate > window.endDate)
+        throw new Error('Usage startDate must not follow endDate');
+}
+/** Normalize an explicitly agent-scoped UTC response. No missing datum is replaced with zero. */
+export function agentUsageOf(raw, member, window, receivedAt = Date.now()) {
+    validate(member, window);
+    const result = { member, window: { ...window, mode: 'utc' }, receivedAt,
+        coverage: 'retained-transcripts-only', state: 'unavailable', raw };
+    if (!record(raw))
+        return result;
+    if (count(raw.updatedAt))
+        result.updatedAt = raw.updatedAt;
+    const cache = cacheOf(raw.cacheStatus);
+    if (cache)
+        result.cache = cache;
+    if (!cache || cache.status !== 'fresh' || cache.pendingFiles !== 0 || cache.staleFiles !== 0 ||
+        raw.startDate !== window.startDate || raw.endDate !== window.endDate || !record(raw.aggregates) ||
+        !Array.isArray(raw.aggregates.byAgent))
+        return result;
+    const agents = raw.aggregates.byAgent;
+    // An absent agent row is not evidence of a zero-use day. Do not read another agent's/global totals.
+    if (agents.length !== 1 || !record(agents[0]) || agents[0].agentId !== member)
+        return result;
+    const totals = totalsOf(agents[0].totals);
+    if (!totals)
+        return result;
+    result.state = 'available';
+    result.totals = totals;
+    return result;
+}
+/** Works with kit.call or the portable device.call; retains the complete existing pass-through. RPC errors reject. */
+export async function readAgentUsage(client, member, window, options) {
+    validate(member, window);
+    const raw = await client.call('sessions.usage', { agentId: member, startDate: window.startDate, endDate: window.endDate, mode: 'utc', groupBy: 'instance', limit: 1 }, options);
+    return agentUsageOf(raw, member, window);
+}

package/dist/words.json

@@ -17,6 +17,48 @@
     "signin.busy": "Another sign-in is already in progress. Finish or cancel it, then try again.",
     "signin.cancelled": "Sign-in cancelled. You can start again whenever you are ready.",
     "signin.expired": "The sign-in took too long. Start it again.",
+    "signin.title": "Sign in to {site}",
+    "signin.takeover": "Take over to sign in",
+    "signin.notNow": "Not now",
+    "signin.cancel": "Cancel sign-in",
+    "signin.reopen": "Continue signing in",
+    "signin.retry": "Try signing in again",
+    "signin.confirmOrigin": "Continue on {origin}",
+    "signin.done": "Done signing in",
+    "signin.confirmSite": "First time {name} signs in to {site}. Type the site name to continue.",
+    "signin.offOrigin": "You're now on {origin}, not {site}. Continue only if you expected this.",
+    "signin.agentNote": "{name} says: “{note}”",
+    "signin.waiting": "{name} needs you to sign in to {site}.",
+    "signin.parked": "Sign-in to {site} is waiting for you.",
+    "signin.checking": "Sign-in details entered",
+    "signin.verified": "Signed in to {site}",
+    "signin.stillSignedOut": "{site} still shows a sign-in page. Try again?",
+    "browser.signin.expired": "The sign-in request for {site} timed out.",
+    "browser.signin.cancelled": "Sign-in to {site} was cancelled.",
+    "browser.signin.notice": "A browser sign-in is waiting for you.",
+    "signin.originMismatch": "You finished on a different site than {site}, so {name} won't continue.",
+    "signin.browserGone": "{name}'s browser closed during sign-in.",
+    "signin.superseded": "A newer request replaced this one.",
+    "signin.runReplaced": "This task moved on, so the sign-in request was closed.",
+    "signin.resumeFailed": "Signed in, but {name} couldn't continue. Try again.",
+    "signin.resumeUnknown": "Signed in, but we can't tell whether {name} continued. Check the task before retrying.",
+    "signin.noVerifier": "Sign-in details entered for {site}. {name} can't confirm you're signed in.",
+    "signin.insecureRemote": "{site} isn't secure, so taking over to sign in is off.",
+    "signin.gate": "Waiting for the person to sign in to {site}.",
+    "signin.resume": "The person signed in to {site}. Continue the task.",
+    "signin.private": "Private while someone signs in",
+    "browser.recovering": "Reconnecting to {name}'s browser…",
+    "browser.blocked.noBrowser": "No browser is set up for {name}.",
+    "browser.blocked.exhausted": "{name}'s browser stopped and could not be restarted.",
+    "browser.blocked.detached": "{name}'s browser isn't connected.",
+    "browser.blocked.unsafe": "An agent here can run commands or read files, so the browser stays off.",
+    "browser.blocked.gateOff": "Browser handoff needs the tool gate on.",
+    "browser.blocked.unprotected": "Signing in for {name} isn't available yet.",
+    "live.reconnecting": "Reconnecting…",
+    "live.browser": "Browser live view",
+    "live.label": "Browser live view",
+    "live.ended": "Browser live view ended.",
+    "live.failed": "Browser live view couldn't connect.",
     "approval.ask": "{helper} wants to {summary}. Allow it?",
     "approval.expired": "Nobody answered in time, so this wasn't allowed.",
     "approval.notice": "Something is waiting for your yes.",