@byokit/openclaw 0.5.0 → 0.6.1

package/dist/link.js

@@ -1,24 +1,31 @@
 // Host-side link adapter (7.1): typed, member-checked ops over @byokit/link, sealed approval push
 // via the relay (7.3). Node only.
 import { randomUUID } from 'node:crypto';
+import { sealBox } from '@byokit/seal';
 import { readFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { WebSocketServer } from 'ws';
 import { PublicLinkError, } from '@byokit/link';
 import { reach } from '@byokit/reach';
 import { ENGINE_VERSION } from "./constants.js";
-import { b64urlDecode, sealNotice } from "./notices.js";
+import { b64urlDecode, b64urlEncode, sealNotice } from "./notices.js";
 import { routeFor } from "./routes.js";
 import { authStatus } from "./auth-status.js";
 import { outputSchema } from "./output.js";
 import { signedInProviders } from "./runs.js";
 import { stateWords, words } from "./words.js";
-const VIEW_OPS = new Set(['oc.state', 'oc.routes', 'oc.signin.view', 'oc.sessions', 'oc.approvals', 'oc.events']);
+const VIEW_OPS = new Set(['oc.state', 'oc.routes', 'oc.signin.view', 'oc.sessions', 'oc.approvals', 'oc.events',
+    'oc.browser.state', 'oc.browser.signins', 'oc.browser.thumb']);
 // This kit's own version, read once from its package.json (beside src/ and dist/ alike).
 const KIT_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const THINKING = new Set(['off', 'low', 'medium', 'high']);
 const refused = () => new PublicLinkError(words('link.notAllowed'));
+const BROWSER_REFUSALS = new Set(['stale', 'not-found', 'held-by-other', 'lease-expired', 'not-control',
+    'not-lease-holder', 'confirm-site', 'already-open', 'insecure-remote', 'unsupported']);
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const browserTag = (event) => event === 'byokit.browser';
+const browserEvent = (event, payload) => event === 'byokit.browser' && isRecord(payload) && typeof payload.member === 'string'
+    && (payload.kind === 'state' || payload.kind === 'signin');
 const memberKey = (member, sessionKey) => sessionKey.startsWith(`agent:${member}:`);
 function memberSessions(result, member) {
     const rows = Array.isArray(result) ? result : isRecord(result) && Array.isArray(result.sessions) ? result.sessions : [];
@@ -50,22 +57,140 @@ function runOptions(args) {
         ...(tools === undefined ? {} : { tools: [...tools] }),
     };
 }
+function browserInput(value) {
+    if (!isRecord(value))
+        return false;
+    const finite = (key) => typeof value[key] === 'number' && Number.isFinite(value[key]);
+    if (value.kind === 'text')
+        return typeof value.text === 'string' && value.text.length <= 16384;
+    if (value.kind === 'nav')
+        return ['back', 'forward', 'reload'].includes(value.action);
+    if (value.kind === 'key')
+        return ['down', 'up'].includes(value.type)
+            && typeof value.key === 'string' && value.key.length <= 128
+            && (value.code === undefined || (typeof value.code === 'string' && value.code.length <= 128))
+            && (value.modifiers === undefined || (Number.isInteger(value.modifiers) && value.modifiers >= 0 && value.modifiers <= 15));
+    return value.kind === 'pointer' && ['move', 'down', 'up', 'wheel'].includes(value.type)
+        && finite('x') && finite('y') && (value.button === undefined || ['left', 'right', 'middle'].includes(value.button))
+        && (value.dx === undefined || finite('dx')) && (value.dy === undefined || finite('dy'));
+}
 export function openclawLink(kit, o) {
     const passThrough = o.passThrough ?? (() => false);
+    // The host lifecycle extension is supplied by the browser host. Without it control fails closed.
+    const browser = () => {
+        if (!kit.browser)
+            throw refused();
+        return kit.browser;
+    };
+    const leases = new Map();
+    const memberSource = (value, member) => {
+        if (!isRecord(value) || value.member !== member)
+            throw refused();
+        if (value.kind === 'browser')
+            return { kind: 'browser', member };
+        if (value.kind === 'desktop' && ['host', 'node', 'environment'].includes(value.source))
+            return { kind: 'desktop', member, source: value.source };
+        throw refused();
+    };
+    const control = () => {
+        if (typeof kit.browser?.revokeGrant !== 'function')
+            throw refused();
+    };
+    const ownedLease = (value, member, grant) => {
+        control();
+        if (!isRecord(value) || typeof value.requestId !== 'string')
+            throw refused();
+        const held = leases.get(value.requestId);
+        if (!held || held.grant !== grant.id || held.lease.nonce !== value.nonce || held.lease.epoch !== value.epoch
+            || held.lease.gen !== value.gen || !browser().signIns(member).some(r => r.id === value.requestId))
+            throw refused();
+        return held.lease;
+    };
     // Grants that have called, so sealed pushes and push actions can check the member (7.3).
     const seen = new Map();
+    const expiry = new Map();
     // Devices that registered a box key, by grant id.
     const boxes = new Map();
     // One sign-in drive per member+provider, plus the latest view even after it ends.
     const drives = new Map();
     const latest = new Map();
     const memberOf = (grant) => {
+        if (revoked.has(grant.id) || (grant.expires !== undefined && grant.expires <= Date.now()))
+            throw refused();
         seen.set(grant.id, grant);
+        clearTimeout(expiry.get(grant.id));
+        if (grant.expires !== undefined) {
+            const timer = setTimeout(() => {
+                const current = seen.get(grant.id);
+                if (current?.expires !== undefined && current.expires > Date.now())
+                    memberOf(current);
+                else
+                    void revoke(grant.id).catch(() => { });
+            }, Math.min(grant.expires - Date.now(), 2 ** 31 - 1));
+            timer.unref();
+            expiry.set(grant.id, timer);
+        }
         const member = o.memberOf(grant);
         if (member === undefined)
             throw refused();
         return member;
     };
+    const viewers = new Map();
+    const revoked = new Set();
+    const revocations = new Map();
+    const revoke = (grant) => {
+        const pending = revocations.get(grant);
+        if (pending)
+            return pending;
+        revoked.add(grant);
+        clearTimeout(expiry.get(grant));
+        expiry.delete(grant);
+        for (const [id, held] of leases)
+            if (held.grant === grant)
+                leases.delete(id);
+        for (const close of viewers.get(grant) ?? [])
+            close();
+        viewers.delete(grant);
+        boxes.delete(grant);
+        seen.delete(grant);
+        let cleanup;
+        try {
+            cleanup = kit.browser?.revokeGrant?.(grant) ?? Promise.resolve();
+        }
+        catch {
+            cleanup = Promise.reject(refused());
+        }
+        const result = cleanup.catch(() => { throw refused(); });
+        revocations.set(grant, result);
+        return result;
+    };
+    const pushSignIn = async (member) => {
+        if (!o.relay || !kit.browser)
+            return;
+        for (const request of kit.browser.signIns(member)) {
+            if (request.state !== 'waiting')
+                continue;
+            for (const [id, box] of boxes) {
+                const grant = seen.get(id);
+                if (!grant || o.memberOf(grant) !== member || (grant.expires !== undefined && grant.expires <= Date.now()))
+                    continue;
+                const plain = new TextEncoder().encode(JSON.stringify({ source: 'signin', id: request.id, gen: request.gen, member, site: request.site }));
+                try {
+                    await o.relay.notify({ id: request.id, title: words('browser.signin.notice'), to: [id],
+                        data: { v: 1, sealed: b64urlEncode(sealBox(plain, box)) } }, { includeContent: true });
+                }
+                finally {
+                    plain.fill(0);
+                }
+            }
+        }
+    };
+    if (o.relay)
+        kit.onEvent('*', (payload, event) => {
+            const p = isRecord(payload) ? payload : {};
+            if (browserEvent(event, p) && p.kind === 'signin')
+                void pushSignIn(p.member).catch(() => { });
+        });
     const pushApproval = async (approval) => {
         if (!o.relay)
             return;
@@ -122,6 +247,69 @@ export function openclawLink(kit, o) {
         if (grant.role === 'view' && !VIEW_OPS.has(req.op))
             throw refused();
         const args = isRecord(req.args) ? req.args : {};
+        if (req.op.startsWith('oc.browser.')) {
+            // Keyed answers may be persisted by @byokit/link. Lease nonces and JPEGs are transient only.
+            if (req.key !== undefined)
+                throw refused();
+            const host = browser();
+            const action = req.op.slice('oc.browser.'.length);
+            if (action === 'state') {
+                if (args.member !== member)
+                    throw refused();
+                return host.state(member);
+            }
+            if (action === 'signins')
+                return host.signIns(member);
+            if (action === 'thumb') {
+                const source = memberSource(args.source, member);
+                if (source.kind === 'desktop')
+                    return { state: 'unsupported' };
+                const result = await host.thumbnail(source, { grant: grant.id });
+                return result.state === 'ok' ? { state: 'ok', frame: { ...result.frame, jpeg: b64urlEncode(result.frame.jpeg) } } : result;
+            }
+            control();
+            if (action === 'done' || action === 'confirmorigin') {
+                const lease = ownedLease(args.lease, member, grant);
+                if (action === 'done')
+                    return host.done(lease);
+                if (typeof args.origin !== 'string')
+                    throw refused();
+                host.confirmOrigin(lease, args.origin);
+                return null;
+            }
+            if (action === 'forget') {
+                if (args.member !== member || typeof args.site !== 'string')
+                    throw refused();
+                await host.forget(member, args.site, { grant: grant.id });
+                return null;
+            }
+            if (typeof args.id !== 'string' || !Number.isSafeInteger(args.gen) || args.gen < 1)
+                throw refused();
+            const request = host.signIns(member).find(r => r.id === args.id);
+            if (!request)
+                throw refused();
+            if (request.state === 'held' && leases.get(request.id)?.grant !== grant.id)
+                throw refused();
+            const by = { grant: grant.id };
+            if (action === 'takeover') {
+                if (args.confirmSite !== undefined && typeof args.confirmSite !== 'string')
+                    throw refused();
+                const lease = await host.takeover(args.id, args.gen, { ...by,
+                    ...(typeof args.confirmSite === 'string' ? { confirmSite: args.confirmSite } : {}) });
+                memberOf(grant); // revocation during the asynchronous takeover must not publish a new lease
+                leases.set(args.id, { grant: grant.id, lease });
+                return lease;
+            }
+            if (action === 'notnow')
+                return host.notNow(args.id, args.gen, by);
+            if (action === 'reopen')
+                return host.reopen(args.id, args.gen, by);
+            if (action === 'retry')
+                return host.retry(args.id, args.gen, by);
+            if (action === 'cancel')
+                return host.cancel(args.id, args.gen, by);
+            throw refused();
+        }
         switch (req.op) {
             case 'oc.state': {
                 // signedIn: the providers the device member is usably signed in to (an expired or unfinished sign-in is not),
@@ -131,7 +319,7 @@ export function openclawLink(kit, o) {
                     ...(signedIn ? { signedIn } : {}) };
             }
             case 'oc.routes':
-                return kit.routes().filter((route) => route.offer);
+                return kit.routes(); // Discovery is not authorization or default eligibility.
             case 'oc.signin.start': {
                 if (typeof args.provider !== 'string' || (args.via !== 'browser' && args.via !== 'code'))
                     throw new Error('oc.signin.start needs { provider, via: browser|code }');
@@ -229,6 +417,13 @@ export function openclawLink(kit, o) {
             case 'oc.call': {
                 if (typeof args.method !== 'string')
                     throw new Error('oc.call needs { method, params }');
+                if (kit.browser && (args.method === 'browser.request' || args.method.startsWith('terminal.') || args.method === 'tools.invoke'))
+                    throw refused();
+                if (args.method === 'byokit.usage.engineStarted') {
+                    if (!isRecord(args.params) || args.params.agentId !== member)
+                        throw refused();
+                    return await kit.callDynamic(args.method, args.params);
+                }
                 if (!passThrough(args.method, grant))
                     throw refused();
                 return await kit.call(args.method, args.params);
@@ -239,6 +434,135 @@ export function openclawLink(kit, o) {
     };
     const stream = async (s, req, grant) => {
         const member = memberOf(grant);
+        if (req.op.startsWith('oc.browser.') && req.op !== 'oc.browser.live') {
+            try {
+                const value = await handle({ op: req.op, args: req.args }, grant);
+                await s.write(`${JSON.stringify({ value })}\n`);
+                s.end();
+            }
+            catch (error) {
+                const why = error instanceof Error && 'why' in error ? error.why : undefined;
+                if (typeof why === 'string' && BROWSER_REFUSALS.has(why)) {
+                    await s.write(`${JSON.stringify({ refused: why })}\n`).catch(() => { });
+                    s.end();
+                }
+                else
+                    s.end(words('link.notAllowed'));
+            }
+            return;
+        }
+        if (req.op === 'oc.browser.live') {
+            const args = isRecord(req.args) ? req.args : {};
+            const source = memberSource(args.source, member);
+            if (args.mode !== 'observe' && args.mode !== 'control')
+                throw refused();
+            if (source.kind === 'desktop') {
+                if (args.mode !== 'observe' || args.lease !== undefined)
+                    throw refused();
+                await s.write(`${JSON.stringify({ state: { source, mode: 'observe', phase: 'failed', why: 'unsupported' } })}\n`);
+                s.end();
+                return;
+            }
+            const lease = args.mode === 'control' ? (grant.role === 'control' ? ownedLease(args.lease, member, grant) : undefined) : undefined;
+            if (args.mode === 'control' && !lease)
+                throw refused();
+            if (args.mode === 'observe' && args.lease !== undefined)
+                throw refused();
+            if (args.maxWidth !== undefined && (!Number.isSafeInteger(args.maxWidth) || args.maxWidth < 1 || args.maxWidth > 4096))
+                throw refused();
+            let ended = false;
+            let busy = false;
+            let acceptingFrames = false;
+            let nextState;
+            let nextFrame;
+            let viewer;
+            // One in-flight write + latest state/frame: slow viewers cannot grow a JPEG queue.
+            const flush = async () => {
+                if (busy || ended)
+                    return;
+                busy = true;
+                try {
+                    while (!ended && (nextState !== undefined || nextFrame !== undefined)) {
+                        const value = nextState ?? nextFrame;
+                        if (nextState !== undefined)
+                            nextState = undefined;
+                        else
+                            nextFrame = undefined;
+                        await s.write(`${JSON.stringify(value)}\n`);
+                        if (isRecord(value) && isRecord(value.state) && ['ended', 'failed'].includes(value.state.phase)) {
+                            close();
+                            s.end();
+                        }
+                    }
+                }
+                catch {
+                    close();
+                }
+                finally {
+                    busy = false;
+                }
+            };
+            const close = () => {
+                if (ended)
+                    return;
+                ended = true;
+                nextState = nextFrame = undefined;
+                viewer?.close();
+            };
+            const revokeViewer = () => { close(); s.end(words('link.notAllowed')); };
+            const active = viewers.get(grant.id) ?? new Set();
+            active.add(revokeViewer);
+            viewers.set(grant.id, active);
+            s.onEnd = () => { close(); active.delete(revokeViewer); };
+            let text = '';
+            const decoder = new TextDecoder();
+            s.onData = (chunk) => {
+                if (ended)
+                    return;
+                try {
+                    if (!lease || grant.role !== 'control' || (grant.expires !== undefined && grant.expires <= Date.now()))
+                        throw refused();
+                    text += decoder.decode(chunk, { stream: true });
+                    if (text.length > 65536)
+                        throw refused();
+                    let at;
+                    while ((at = text.indexOf('\n')) >= 0) {
+                        const input = JSON.parse(text.slice(0, at));
+                        text = text.slice(at + 1);
+                        if (!browserInput(input))
+                            throw refused();
+                        ownedLease(lease, member, grant);
+                        viewer?.input(input);
+                    }
+                }
+                catch {
+                    close();
+                    s.end(words('link.notAllowed'));
+                }
+            };
+            try {
+                viewer = browser().live(source, { grant: grant.id, ...(lease ? { lease } : {}),
+                    ...(typeof args.maxWidth === 'number' ? { maxWidth: args.maxWidth } : {}) }, {
+                    state: state => { if (!ended) {
+                        acceptingFrames = state.phase === 'live';
+                        nextState = { state };
+                        nextFrame = undefined;
+                        void flush();
+                    } },
+                    frame: frame => { if (!ended && acceptingFrames) {
+                        nextFrame = { frame: { ...frame, jpeg: b64urlEncode(frame.jpeg) } };
+                        void flush();
+                    } },
+                });
+                if (ended)
+                    viewer.close();
+            }
+            catch {
+                close();
+                s.end(words('link.notAllowed'));
+            }
+            return;
+        }
         if (req.op === 'oc.run') {
             if (grant.role === 'view')
                 throw refused();
@@ -271,6 +595,11 @@ export function openclawLink(kit, o) {
         if (req.op === 'oc.events') {
             const offEvent = kit.onEvent('*', (payload, event) => {
                 const record = payload;
+                if (browserTag(event)) {
+                    if (browserEvent(event, record) && record.member === member)
+                        void s.write(`${JSON.stringify({ event: 'byokit.browser', payload: { member, kind: record.kind } })}\n`).catch(() => { });
+                    return;
+                }
                 const agent = record?.agentId;
                 const key = record?.sessionKey;
                 if (agent !== member && !(typeof key === 'string' && memberKey(member, key)))
@@ -287,7 +616,7 @@ export function openclawLink(kit, o) {
         }
         throw refused();
     };
-    return { handle, stream, allow: () => true, onAction };
+    return { handle, stream, allow: () => true, onAction, onGrantRemoved: grant => revoke(grant.id) };
 }
 // ponytail: this ~40-line serve() wiring is deliberately duplicated per runtime kit (D3);
 // extract it into a shared package when a third runtime kit appears.

package/dist/routes.d.ts

@@ -1,10 +1,21 @@
 import type { Route } from './types.ts';
-/** The pin's auth-choice table. `provider` is the id a person's account is known by (the doc's matrix), which for
- *  MiniMax's portal routes is the account-visible `minimax`, not the wizard's internal `minimax-portal`. `plugin` is
- *  the bundled plugin needed for that route to start (5.6); the kit allows offered routes, and the app allows any
- *  unoffered route it explicitly uses. Only the pin's bundled provider contracts are
- *  listed: install-catalog plugins (external providers needing their own install) are not contracted by the pin and
- *  are deliberately absent. */
-export declare function routes(): Route[];
-/** The route an app should use: only an offered route counts; API billing is never picked as a fallback. */
+export type RouteFacts = {
+    platform?: 'node' | 'browser' | 'rn';
+    host?: boolean;
+    binaries?: readonly string[];
+    plugins?: readonly string[];
+    clients?: readonly string[];
+};
+export type RouteView = Route & {
+    readiness: NonNullable<Route['readiness']>;
+};
+/** Every choice, including external dependencies and providers without a wizard choice.
+ * `offerPolicy` is eligibility; legacy boolean `offer` additionally requires readiness.
+ * No facts means the kit's Node host with bundled plugins, not installed external plugins or CLIs.
+ * External installs belong to the explicit host operation; discovery never performs one.
+ */
+export declare function routes(facts?: RouteFacts): RouteView[];
+/** Retain explicit legacy selectors alongside corrected discovery metadata. A native CLI selector still
+ * reaches engine detection (which checks its own login); it does not make an unavailable route default.
+ * API billing is never picked as a fallback. */
 export declare function routeFor(provider: string, via: 'browser' | 'code'): Route | undefined;

package/dist/routes.js

@@ -1,16 +1,49 @@
-// Route labels: data, not code (D12). One entry per auth choice in the pinned tarball's provider contracts (O6).
+// Complete pinned discovery. No credential reads, plugin installation or live qualification.
 import routesJson from './routes.json' with { type: 'json' };
 const table = routesJson;
-/** The pin's auth-choice table. `provider` is the id a person's account is known by (the doc's matrix), which for
- *  MiniMax's portal routes is the account-visible `minimax`, not the wizard's internal `minimax-portal`. `plugin` is
- *  the bundled plugin needed for that route to start (5.6); the kit allows offered routes, and the app allows any
- *  unoffered route it explicitly uses. Only the pin's bundled provider contracts are
- *  listed: install-catalog plugins (external providers needing their own install) are not contracted by the pin and
- *  are deliberately absent. */
-export function routes() {
-    return table;
+/** Every choice, including external dependencies and providers without a wizard choice.
+ * `offerPolicy` is eligibility; legacy boolean `offer` additionally requires readiness.
+ * No facts means the kit's Node host with bundled plugins, not installed external plugins or CLIs.
+ * External installs belong to the explicit host operation; discovery never performs one.
+ */
+export function routes(facts = {}) {
+    const platform = facts.platform ?? 'node';
+    return table.map(route => {
+        let readiness = 'ready';
+        let why;
+        if (route.upstream?.flow === 'absent') {
+            readiness = 'no_upstream_flow';
+            why = route.reason;
+        }
+        else if (route.platforms?.[platform] === 'no') {
+            readiness = 'unsupported_platform';
+            why = `Not supported on ${platform}.`;
+        }
+        else if (route.platforms?.[platform] === 'host' && !facts.host) {
+            readiness = 'needs_host';
+            why = 'Needs the linked engine host.';
+        }
+        else if (route.needs?.binary && !facts.binaries?.includes(route.needs.binary)) {
+            readiness = 'needs_binary';
+            why = `Needs ${route.needs.binary} in the isolated HOME.`;
+        }
+        else if (route.needs?.plugin && !facts.plugins?.includes(route.needs.plugin)) {
+            readiness = 'needs_plugin';
+            why = `Needs plugin ${route.needs.plugin}; discovery does not install it.`;
+        }
+        else if (route.needs?.client && !facts.clients?.includes(route.needs.client)) {
+            readiness = 'needs_client';
+            why = `Needs host client registration ${route.needs.client}.`;
+        }
+        return { ...route, readiness, ...(why ? { why } : {}),
+            offer: route.offerPolicy === 'default' && route.billing === 'subscription' && readiness === 'ready' };
+    });
 }
-/** The route an app should use: only an offered route counts; API billing is never picked as a fallback. */
+/** Retain explicit legacy selectors alongside corrected discovery metadata. A native CLI selector still
+ * reaches engine detection (which checks its own login); it does not make an unavailable route default.
+ * API billing is never picked as a fallback. */
 export function routeFor(provider, via) {
-    return table.find((route) => route.offer && route.provider === provider && route.via === via);
+    return table.find(route => route.billing === 'subscription' && route.offerPolicy === 'default'
+        && ((route.offer && route.provider === provider && route.via === via)
+            || (route.legacy?.provider === provider && route.legacy.via === via)));
 }