@byokit/openclaw 0.5.1 → 0.6.2

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

package/dist/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,13 +15,20 @@ 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 = {
     sessionKey: string;
     [k: string]: unknown;
 };
-type EndFrame<T = unknown> = {
+/** The frame `oc.run`'s stream ends with: the run's `RunEnd`, beside its events. */
+export type DeviceEndFrame<T = unknown> = {
     type: 'end';
     end: RunEnd<T>;
 };
@@ -55,9 +64,26 @@ export declare class LinkRefused extends Error {
     readonly sealed = true;
     constructor(message: string);
 }
-export declare function openclawDevice(link: DeviceLink): {
+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;
+/** `openclawDevice`'s device surface: every `oc.*` op the computer answers, typed. */
+export type OpenClawDevice = {
+    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>;
@@ -66,7 +92,7 @@ export declare function openclawDevice(link: DeviceLink): {
     };
     signOut(p: string): Promise<void>;
     sessions(): Promise<SessionRow[]>;
-    run<const S extends OutputSchema | undefined = undefined>(message: string, o?: DeviceRunOptions<S>): AsyncIterable<RunEvent | EndFrame<SchemaOutput<S>>>;
+    run<const S extends OutputSchema | undefined = undefined>(message: string, o?: DeviceRunOptions<S>): AsyncIterable<RunEvent | DeviceEndFrame<SchemaOutput<S>>>;
     steer(k: string, t: string, o?: {
         auth?: 'apiKey';
     }): Promise<void>;
@@ -79,6 +105,13 @@ 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 declare function openclawDevice(link: DeviceLink): OpenClawDevice;
 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';