@mirasim/computer-use 0.0.0-stage → 0.1.0-rc.3

package/dist/platform/macos/scroll-pages.d.ts

@@ -0,0 +1 @@
+export declare const MAX_SCROLL_PAGES = 60;

package/dist/platform/macos/scroll-pages.js

@@ -0,0 +1 @@
+const o=60;export{o as MAX_SCROLL_PAGES};

package/dist/platform/macos/scroll-verb.d.ts

@@ -0,0 +1,5 @@
+import type { ActResult } from '../types.ts';
+import type { ElementActs } from './act-element.ts';
+import type { AxWindow } from './elements.ts';
+import type { MouseHost } from './mouse.ts';
+export declare function scrollVerb(host: MouseHost, acts: ElementActs, frame: AxWindow, a: Record<string, any>): Promise<ActResult>;

package/dist/platform/macos/scroll-verb.js

@@ -0,0 +1 @@
+import{AxRequestError as $}from"./ax-client.js";import{MAX_SCROLL_PAGES as v}from"./scroll-pages.js";const x=20,b=400,k=20;async function _(s,p,i,e,n,r,a){if(n!=="up"&&n!=="down")return null;try{const t=await s.call("scrollpage",{pid:s.pid(),...p?{key:p}:{},...i,direction:n,pages:a?v:r});if(!t.moved)return{ok:!0,note:`${e} is already at the ${n==="down"?"end":"start"} \u2014 it did not move. Do not repeat this scroll; read what is here, or scroll the other way`};const u=`${t.applied} page${t.applied===1?"":"s"}`,c=!a&&t.applied<r?` (asked for ${r}, the area ended after ${t.applied})`:"";return{ok:!0,note:a?`scrolled ${e} to the ${a} \u2014 ${u} through the app's own scrolling area, so the pointer never moved and nothing had to come forward`:`scrolled ${u} ${n} in ${e}${c} \u2014 through the app's own scrolling area, so the pointer never moved`,journal:{rung:"axpage",pages:t.applied,delta:Math.round(t.delta*100)/100,unit:t.unit}}}catch(t){if(t instanceof $&&["no_scroll_area","no_element","unsupported"].includes(t.code))return null;throw t}}async function E(s,p,i,e){let n={x:i.x+i.w/2,y:i.y+i.h/2},r="the window";if(typeof e.ref=="string"&&e.ref){const o=p.resolve(e.ref,e.name);if(!("key"in o))return o;const d=s.rectOf(e.ref);if(!d)return{ok:!1,note:`${o.role} "${o.name}" has no frame on this walk, so there is nowhere to scroll \u2014 observe and name a listed element`};n={x:d.x+d.w/2,y:d.y+d.h/2},r=`${o.role} "${o.name}"`}const a={x:Math.round(n.x),y:Math.round(n.y)},t=s.pid(),u=s.call,c=Math.min(Math.max(Math.trunc(Number(e.count))||1,1),k);if(e.to&&Number(e.count)>1)return{ok:!1,note:`scroll takes to:'${e.to}' or count, not both \u2014 to:'${e.to}' already goes as far as the window scrolls; drop one`};const h=e.to?b:x*c,l=e.to==="top"?"up":e.to==="bottom"?"down":String(e.direction??"down"),f=await _(s,typeof e.ref=="string"&&e.ref?String(e.ref):null,a,r,l,c,e.to);if(f)return f;const g=l==="down"?h:l==="up"?-h:0,m=l==="right"?h:l==="left"?-h:0;try{await u("scroll",{pid:t,...a,dy:g,dx:m})}catch(o){if(o instanceof $&&o.code==="no_window")return{ok:!1,note:`${o.message} \u2014 a wheel event lands on whatever is under the point, so scrolling ${r} needs it uncovered there: explain the foreground and pointer effects, obtain user permission, then activate and retry`};throw o}const w=`at ${r}'s centre`,y=c>1?` ${c} screens`:"";return{ok:!0,note:e.to?`posted a long wheel burst ${l} ${w} (not a verified jump-to-${e.to}); used system pointer input and requested cursor restoration without app activation \u2014 observe whether the content scrolled`:`posted wheel input${y} ${l} ${w}; requested cursor restoration without app activation \u2014 observe whether the content scrolled`}}export{E as scrollVerb};

package/dist/platform/macos/select-text-verb.d.ts

@@ -0,0 +1,8 @@
+import type { ActResult, VerbSpec } from "../types.ts";
+import type { ElementActs } from "./act-element.ts";
+export declare const SELECT_TEXT_VERB: VerbSpec;
+export declare function selectTextVerb(acts: ElementActs, ref: unknown, name: unknown, o: {
+    want: string;
+    near: string;
+    caret: string;
+}): Promise<ActResult>;

package/dist/platform/macos/select-text-verb.js

@@ -0,0 +1 @@
+import{Type as a}from"typebox";import{AxRequestError as h}from"./ax-client.js";const v={kind:"select_text",schema:a.Object({kind:a.Literal("select_text"),ref:a.String({description:"The text field or text area to select inside (from the latest observe())"}),name:a.Optional(a.String({description:"Visible name of that element \u2014 identity check + fallback locator"})),text:a.Optional(a.String({description:"The exact text to select (copy it verbatim from what you read); omit it to place the caret at the start / end of the field with caret alone"})),near:a.Optional(a.String({description:"Nearby text that tells one occurrence from another; the match closest to it wins"})),caret:a.Optional(a.Union([a.Literal("select"),a.Literal("before"),a.Literal("after")],{description:"select (default) leaves it selected \u2014 keys then replaces it; before / after place the caret there instead"}))},{description:"Select part of a text field's value, or place the caret in it, so keys edits exactly that \u2014 set_text always replaces the whole field."})};function m(n,l,f,e){return Math.max(0,f-(n+l),n-(f+e))}async function O(n,l,f,e){const o=n.resolve(l,f);if(!("key"in o))return o;const i=n.what(o,l);if(!e.want){if(e.caret==="select")return{ok:!1,note:"select_text needs the text to select, or caret:'before' / caret:'after' alone to place the caret at the start / end of the field"};let t="";try{t=String((await n.call("value",{key:o.key})).value??"")}catch(r){if(r instanceof h&&r.code==="stale_key")return n.staleRef(l)}const p=e.caret==="after"?t.length:0;try{await n.call("selectrange",{key:o.key,start:p,length:0})}catch(r){if(r instanceof h&&r.code==="stale_key")return n.staleRef(l);if(r instanceof h&&r.code==="ax_error")return{ok:!1,note:`${i} will not take a caret (AXError ${r.ax??"?"}) \u2014 click it to focus it instead`};throw r}return{ok:!0,note:`caret placed at the ${e.caret==="after"?"end":"start"} of ${i} \u2014 keys and type go there now`}}let c;try{c=String((await n.call("value",{key:o.key})).value??"")}catch(t){if(t instanceof h&&t.code==="stale_key")return n.staleRef(l);c=""}if(!c)return{ok:!1,note:`${i} has no readable text value \u2014 select_text works on text fields and text areas; act on one of those, or use click`};const s=[];let d=c.indexOf(e.want);for(;d!==-1;)s.push(d),d=c.indexOf(e.want,d+1);if(!s.length)return{ok:!1,note:`"${e.want}" is not in ${i} \u2014 read it with text() and copy it exactly, whitespace included`};let k=s[0],w=0;if(e.near){const t=c.indexOf(e.near);if(t===-1)return{ok:!1,note:`"${e.near}" is not in ${i}, so it cannot pick between the ${s.length} matches for "${e.want}" \u2014 drop near, or give text that really sits beside the one you mean`};let p=1/0;for(const[r,y]of s.entries()){const u=m(y,e.want.length,t,e.near.length);u<p&&(p=u,k=y,w=r)}}const $=e.caret==="after"?k+e.want.length:k,g=e.caret==="select"?e.want.length:0;try{await n.call("selectrange",{key:o.key,start:$,length:g})}catch(t){if(t instanceof h&&t.code==="stale_key")return n.staleRef(l);if(t instanceof h&&t.code==="ax_error")return{ok:!1,note:`${i} will not take a selection (AXError ${t.ax??"?"}) \u2014 the app does not expose one for this control; set_text replaces its whole value instead`};throw t}const x=s.length>1?` (match ${w+1} of ${s.length}${e.near?`, the one nearest "${e.near}"`:", the first"})`:"";return e.caret==="select"?{ok:!0,note:`selected "${e.want}" in ${i}${x} \u2014 keys now replaces exactly this (set_text still replaces the whole field)`}:{ok:!0,note:`caret placed ${e.caret} "${e.want}" in ${i}${x} \u2014 keys now types there (set_text still replaces the whole field)`}}export{v as SELECT_TEXT_VERB,O as selectTextVerb};

package/dist/platform/macos/type-verb.d.ts

@@ -0,0 +1,5 @@
+import type { ActResult, VerbSpec } from "../types.ts";
+import type { AxCall } from "./act-element.ts";
+export declare const TYPE_VERB: VerbSpec;
+export declare const TYPE_AFTER_KEY_MS = 250;
+export declare function typeVerb(call: AxCall, pid: number, appName: string, text: string, lastKeyAt?: number): Promise<ActResult>;

package/dist/platform/macos/type-verb.js

@@ -0,0 +1 @@
+import{Type as h}from"typebox";const g={kind:"type",schema:h.Object({kind:h.Literal("type"),text:h.String({description:"Text to type, character by character"})},{description:"Type text with key events at the app's keyboard focus \u2014 for a field that takes typed input only (a file being renamed, a search field that filters as you type). set_text fills a field by ref; type is for where that does not stick. Focus the field first (click, or select_text with caret)."})},l=250;async function u(r,d,f){const{typedKey:i,typedValue:t,typedRange:o}=f;if(!i||typeof t!="string"||!o)return{note:"unverified \u2014 the target field, original text or selection could not be read before input"};const{start:e,length:n}=o;if(!Number.isSafeInteger(e)||!Number.isSafeInteger(n)||e<0||n<0||e>t.length||n>t.length-e)return{note:"unverified \u2014 the original selection was outside the readable text"};const a=t.slice(0,e)+d+t.slice(e+n);try{const s=Date.now()+200;for(;;){const{value:c}=await r("textvalue",{key:i});if(typeof c!="string")break;if(Date.now()>=s)return c===a&&a===t?{note:"unverified \u2014 the expected text was already present before input, so read-back cannot establish whether the keys took effect"}:{verified:c===a,note:c===a?"matched \u2014 the same field reads back exactly the expected text after inserting or replacing the original selection":"content differs \u2014 the same field does not read back the expected text; automatic correction or formatting may change it. This does not establish where the keys landed; inspect it with text() before editing further, and do not automatically replay the input"};await new Promise(p=>setTimeout(p,Math.min(50,s-Date.now())))}}catch{}return{note:"unverified \u2014 the original target field could not be read after input; inspect it before editing further, and do not automatically replay the input"}}async function m(r,d,f,i,t=0){if(!i)return{ok:!1,note:"type needs text"};const o=t?Math.max(0,Date.now()-t):Number.POSITIVE_INFINITY,e=o<l?Math.ceil(l-o):0;e&&await new Promise(s=>setTimeout(s,e));const n=await r("type",{pid:d,text:i}),a=await u(r,i,n??{});return{ok:!0,...a,note:`posted ${n?.postedCount??i.length} characters at ${f}'s keyboard focus with key events`+(e?`, after ${e} ms for the key before it to finish moving the focus \u2014 a field that commits on Enter hands it on asynchronously, and a character posted into that gap is lost with no error`:"")+`; ${a.note}`}}export{l as TYPE_AFTER_KEY_MS,g as TYPE_VERB,m as typeVerb};

package/dist/platform/ownership.d.ts

@@ -0,0 +1,20 @@
+import type { OwnershipResource } from "./types.ts";
+export interface OwnershipProvider {
+    claim(group: string, resources: OwnershipResource[]): Promise<void>;
+    release(group: string): Promise<void>;
+    releaseAll(): Promise<void>;
+    trackProcess?(pid: number): Promise<void>;
+}
+export declare class OwnershipBusyError extends Error {
+    constructor(resource: string);
+}
+export declare class ComputerUseOwnership implements OwnershipProvider {
+    private readonly owner;
+    private db;
+    private database;
+    private gone;
+    claim(group: string, resources: OwnershipResource[]): Promise<void>;
+    release(group: string): Promise<void>;
+    releaseAll(): Promise<void>;
+    trackProcess(pid: number): Promise<void>;
+}

package/dist/platform/ownership.js

@@ -0,0 +1 @@
+import{randomUUID as c}from"node:crypto";import{mkdirSync as p}from"node:fs";import{join as a}from"node:path";import{sharedHome as d}from"./home.js";class u extends Error{constructor(r){super(`Resource ${r} is in use by another runtime. Nothing was dispatched. Use a different target, or wait for its owner to finish and release it; do not reset another session.`),this.name="OwnershipBusyError"}}function n(E){try{return process.kill(E,0),!0}catch(r){return r.code!=="ESRCH"}}class N{owner=c();db=null;async database(){if(this.db)return this.db;const r=a(d(),"ownership");p(r,{recursive:!0,mode:448});const{DatabaseSync:t}=await import("node:sqlite"),e=new t(a(r,"claims.sqlite"));e.exec("PRAGMA busy_timeout=1000; CREATE TABLE IF NOT EXISTS claims (resource TEXT NOT NULL, owner TEXT NOT NULL, group_id TEXT NOT NULL, pid INTEGER NOT NULL, mode TEXT NOT NULL, PRIMARY KEY(resource, owner, group_id)); CREATE TABLE IF NOT EXISTS executors (owner TEXT NOT NULL, runtime INTEGER NOT NULL, pid INTEGER NOT NULL, PRIMARY KEY(owner, pid))");const o=e.prepare("SELECT owner,runtime,pid FROM executors").all();for(const s of o)!n(s.runtime)&&!n(s.pid)&&e.prepare("DELETE FROM executors WHERE owner=? AND pid=?").run(s.owner,s.pid);return this.db=e,e}gone(r,t,e){return n(e)?!1:!r.prepare("SELECT pid FROM executors WHERE owner=?").all(t).some(s=>n(s.pid))}async claim(r,t){const e=await this.database();e.exec("BEGIN IMMEDIATE");try{for(const o of t){const s=e.prepare("SELECT owner,pid,mode FROM claims WHERE resource=? AND owner<>?").all(o.key,this.owner);for(const i of s)if(this.gone(e,i.owner,i.pid))e.prepare("DELETE FROM claims WHERE owner=?").run(i.owner),e.prepare("DELETE FROM executors WHERE owner=?").run(i.owner);else if(o.mode==="exclusive"||i.mode==="exclusive")throw new u(o.key);e.prepare("INSERT INTO claims VALUES (?,?,?,?,?) ON CONFLICT(resource,owner,group_id) DO UPDATE SET mode=CASE WHEN claims.mode='exclusive' THEN 'exclusive' ELSE excluded.mode END").run(o.key,this.owner,r,process.pid,o.mode)}e.exec("COMMIT")}catch(o){throw e.exec("ROLLBACK"),o}}async release(r){this.db?.prepare("DELETE FROM claims WHERE owner=? AND group_id=?").run(this.owner,r)}async releaseAll(){this.db&&(this.db.prepare("DELETE FROM claims WHERE owner=?").run(this.owner),this.db.close(),this.db=null)}async trackProcess(r){(await this.database()).prepare("INSERT OR IGNORE INTO executors VALUES (?,?,?)").run(this.owner,process.pid,r)}}export{N as ComputerUseOwnership,u as OwnershipBusyError};

package/dist/platform/platform-package.d.ts

@@ -0,0 +1 @@
+export declare function platformPackageHelper(file: string): string | null;

package/dist/platform/platform-package.js

@@ -0,0 +1 @@
+import{createRequire as e}from"node:module";function o(r){try{return e(import.meta.url).resolve(`@mirasim/computer-use-${process.platform}-${process.arch}/${r}`)}catch{return null}}export{o as platformPackageHelper};

package/dist/platform/preview.d.ts

@@ -0,0 +1,39 @@
+import type { PreviewFrame, PreviewTarget } from "./types.ts";
+export interface PublishedTarget extends PreviewTarget {
+    updatedAt: number;
+    taskId: string | null;
+}
+export interface PreviewOutput {
+    targets(targets: PublishedTarget[]): void;
+    frame(ref: TargetRef, frame: PreviewFrame): void;
+    status(ref: TargetRef, status: {
+        unavailable: string | null;
+        icon?: string;
+    }): void;
+}
+export interface TargetRef {
+    kind: PreviewTarget["kind"];
+    targetId: string;
+}
+export declare class PreviewService {
+    private readonly out;
+    private readonly env;
+    private readonly targets;
+    private readonly streams;
+    private readonly revokedAt;
+    private taskTags;
+    private watched;
+    private maxSize;
+    private timer;
+    private ticker;
+    private closed;
+    constructor(out: PreviewOutput, env?: NodeJS.ProcessEnv);
+    setTaskId(id: string | null): void;
+    publish(target: PreviewTarget, at: number): void;
+    revoke(apps: string[]): void;
+    watch(refs: TargetRef[], maxSize?: number): void;
+    private sync;
+    private drop;
+    private schedule;
+    close(): void;
+}

package/dist/platform/preview.js

@@ -0,0 +1 @@
+import{createPreviewStream as c}from"./registry.js";const n=16,d=250,o=h=>`${h.kind}:${h.targetId}`;class u{out;env;targets=new Map;streams=new Map;revokedAt=new Map;taskTags=[{at:0,id:null}];watched=new Set;maxSize=2560;timer=null;ticker=null;closed=!1;constructor(t,s=process.env){this.out=t,this.env=s}setTaskId(t){this.taskTags[this.taskTags.length-1]?.id!==t&&(this.taskTags.push({at:Date.now(),id:t}),this.taskTags=this.taskTags.slice(-4))}publish(t,s){if(this.closed||t.capture.type==="macos"&&s<=(this.revokedAt.get(t.capture.app)??-1))return;const e=o(t),a=this.targets.get(e);if(a&&a.updatedAt>s)return;this.targets.delete(e);const i=[...this.taskTags].reverse().find(r=>r.at<=s)?.id??null;for(this.targets.set(e,{...t,pointer:t.pointer??a?.pointer,updatedAt:s,taskId:i});this.targets.size>n;)this.drop(this.targets.keys().next().value);this.schedule(),this.sync()}revoke(t){for(const s of t)this.revokedAt.set(s,Date.now());for(const[s,e]of this.targets)e.capture.type==="macos"&&t.includes(e.capture.app)&&this.drop(s);this.schedule()}watch(t,s){typeof s=="number"&&s>=64&&(this.maxSize=Math.min(Math.round(s),4096)),this.watched=new Set(t.map(o)),this.sync()}sync(){if(!this.closed){for(const[t,s]of this.streams)(!this.watched.has(t)||!this.targets.has(t))&&(s.dispose(),this.streams.delete(t));for(const t of this.watched){const s=this.targets.get(t);if(!s||this.streams.has(t))continue;const e={kind:s.kind,targetId:s.targetId},i=c(s,{frame:r=>{this.streams.get(t)===i&&this.out.frame(e,r)},status:r=>{this.streams.get(t)===i&&this.out.status(e,r)},gone:()=>{this.streams.get(t)===i&&(this.drop(t),this.schedule())}},this.maxSize,this.env);this.streams.set(t,i),i.tick().catch(()=>{})}this.streams.size&&!this.ticker?(this.ticker=setInterval(()=>{for(const t of this.streams.values())t.tick().catch(()=>{})},d),this.ticker.unref()):!this.streams.size&&this.ticker&&(clearInterval(this.ticker),this.ticker=null)}}drop(t){this.targets.delete(t),this.streams.get(t)?.dispose(),this.streams.delete(t)}schedule(){this.timer||this.closed||(this.timer=setTimeout(()=>{this.timer=null,this.closed||this.out.targets([...this.targets.values()])},20),this.timer.unref())}close(){this.closed=!0,this.timer&&clearTimeout(this.timer),this.ticker&&clearInterval(this.ticker);for(const t of this.streams.values())t.dispose();this.streams.clear()}}export{u as PreviewService};

package/dist/platform/profile.d.ts

@@ -0,0 +1,20 @@
+import type { ComputerUseDriver } from "./driver.ts";
+import type { ComputerUseToolSpec, UserConsent } from "./types.ts";
+import type { BrowserConfigOptions } from "./browser/config.ts";
+import { type OwnershipProvider } from './ownership.ts';
+export interface Profile {
+    driver: ComputerUseDriver;
+    drivers: ComputerUseDriver[];
+    tools: ComputerUseToolSpec[];
+}
+export interface ProfileOptions {
+    ownership?: OwnershipProvider;
+    driver?: string;
+    cdpUrl?: string;
+    browser?: BrowserConfigOptions;
+    diagnostics?: boolean;
+    consent?: UserConsent;
+    docsDelivered?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function resolveProfile(opts?: ProfileOptions): Profile;

package/dist/platform/profile.js

@@ -0,0 +1 @@
+import{createDriver as m}from"./registry.js";import{createComputerUseTools as v}from"./tools/index.js";import{ComputerUseOwnership as l}from"./ownership.js";function p(r={}){const o=r.env??process.env,n=(r.driver??o.COMPUTER_USE_PLATFORMS??"browser").split(",").map(e=>e.trim()).filter(Boolean).map(e=>m(e,{cdpUrl:r.cdpUrl,browser:r.browser,...r.consent?{consent:r.consent}:{},env:o})),c=n[0],i=r.diagnostics??o.COMPUTER_USE_DIAGNOSTICS==="1",t=n.map(e=>({driver:e})),d=r.docsDelivered??o.COMPUTER_USE_REPL_DOCS_DELIVERED==="1",s=r.ownership??new l;for(const e of n)e.onExecutorStart=s.trackProcess?.bind(s);return{driver:c,drivers:n,tools:v(t,{diagnostics:i,docsDelivered:d,ownership:s})}}export{p as resolveProfile};

package/dist/platform/registry.d.ts

@@ -0,0 +1,12 @@
+import type { ComputerUseDriver } from "./driver.ts";
+import type { BrowserConfigOptions } from "./browser/config.ts";
+import type { PreviewSink, PreviewStream, PreviewTarget, UserConsent } from "./types.ts";
+export type DriverOptions = {
+    cdpUrl?: string;
+    browser?: BrowserConfigOptions;
+    bundle?: string;
+    consent?: UserConsent;
+    env?: NodeJS.ProcessEnv;
+};
+export declare function createDriver(id: string, opts?: DriverOptions): ComputerUseDriver;
+export declare function createPreviewStream(target: PreviewTarget, sink: PreviewSink, maxSize: number, env?: NodeJS.ProcessEnv): PreviewStream;

package/dist/platform/registry.js

@@ -0,0 +1 @@
+import{BrowserDriver as i}from"./browser/driver.js";import{ElectronDriver as t}from"./electron/driver.js";import{MacosDriver as v}from"./macos/driver.js";import{WindowsDriver as w}from"./windows/driver.js";import{CdpPreviewStream as m}from"./chromium/preview-stream.js";import{MacosPreviewStream as a}from"./macos/preview-stream.js";const o={browser:e=>new i(e.cdpUrl,void 0,e.browser,e.env),electron:e=>new t({cdpUrl:e.cdpUrl,env:e.env}),macos:e=>new v({bundle:e.bundle,env:e.env,consent:e.consent}),windows:e=>new w({env:e.env,consent:e.consent})};function b(e,n={}){const r=o[e];if(!r)throw new Error(`unknown driver "${e}" (available: ${Object.keys(o).join(", ")})`);return r(n)}function D(e,n,r,c=process.env){return e.capture.type==="macos"?new a(e,n,r,c):new m(e,n,r)}export{b as createDriver,D as createPreviewStream};

package/dist/platform/tools/api-contract.d.ts

@@ -0,0 +1,33 @@
+import type { ActResult, ToolResult } from "../types.ts";
+export declare const fnName: (kind: string) => string;
+type ActionOutcome = "verified" | "dispatched" | "blocked" | "uncertain";
+export interface JournalLine {
+    i: number;
+    kind: string;
+    target: string;
+    ok: boolean;
+    note: string;
+    outcome?: ActionOutcome;
+    ms?: number;
+}
+export interface RunLedger {
+    charge(kind: string): void;
+    push(kind: string, target: string, ok: boolean, note: string, read?: boolean, outcome?: ActionOutcome): void;
+    attach(part: ToolResult["content"][number]): void;
+    round?: WriteRound;
+}
+export interface WriteRound {
+    fields: number;
+    verified: number;
+    ended: string | null;
+}
+export interface ApiHooks {
+    onRefs?(refs: string[]): void;
+    onTarget?(ref: string): void;
+    beforeAction?(kind: string, args: Record<string, unknown>): Promise<void>;
+}
+export declare function noteOf(res: ActResult): string;
+export declare function options<T>(verb: string, value: unknown, shape: string): T;
+export declare const firstText: (r: ToolResult) => string;
+export declare const firstLine: (r: ToolResult) => string;
+export {};

package/dist/platform/tools/api-contract.js

@@ -0,0 +1,3 @@
+const o={open_url:"openUrl",select_option:"selectOption",select_text:"selectText",launch_app:"launchApp",ax_action:"axAction",run_js:"runJs",text_gone:"textGone"},p=n=>o[n]??n.replace(/_(\w)/g,(t,e)=>e.toUpperCase());function i(n){return(n.note??"").split(`
+`)[0]??""}function s(n,t,e){if(t==null)return{};if(typeof t=="object"&&!Array.isArray(t))return t;throw new Error(`${n} takes an options object, not ${typeof t=="string"?JSON.stringify(t):String(t)} \u2014 ${e}`)}const r=n=>n.content.find(t=>t.type==="text")?.text??"",c=n=>r(n).split(`
+`)[0]??"";export{c as firstLine,r as firstText,p as fnName,i as noteOf,s as options};

package/dist/platform/tools/api-expect.d.ts

@@ -0,0 +1,3 @@
+import type { ComputerUseDriver } from "../driver.ts";
+import { type RunLedger } from "./api-contract.ts";
+export declare function expectVerb(driver: ComputerUseDriver, ledger: () => RunLedger, value: (target: unknown) => Promise<string>): (raw: unknown) => Promise<boolean>;

package/dist/platform/tools/api-expect.js

@@ -0,0 +1 @@
+import{options as h}from"./api-contract.js";function b(a,i,w){return async f=>{const e=h("expect",f,"expect({text:'Saved', ms:3000}) or expect({value:field, equals:'draft', ms:3000})"),d=new Set(["text","control","url","value","equals","ms"]);if(Object.keys(e).some(t=>!d.has(t)))throw new Error("expect received an unknown option");const u=["text","control","url","value"].filter(t=>e[t]!==void 0);if(u.length!==1)throw new Error("expect needs exactly one of text, control, url, or value");const n=u[0];if(n==="value"?typeof e.equals!="string":typeof e[n]!="string"||!e[n])throw new Error("expect needs a nonempty condition string, or a value target with equals:string");if(e.ms!==void 0&&(typeof e.ms!="number"||!Number.isFinite(e.ms)||e.ms<0||e.ms>16e3))throw new Error("expect ms must be between 0 and 16000");const r=Number(e.ms??3e3);i().charge("expect"),a.noteContentRead();const s=n==="value"?"field value":`${n} ${JSON.stringify(e[n])}`;let o=!1;try{if(n==="value"){const t=Date.now()+r;do{let l;try{const c=Math.max(1,t-Date.now()),p=await Promise.race([w(e.value),new Promise((x,m)=>{l=setTimeout(()=>m(new Error("value read timed out")),c)})]);if(a.valueMatches(p,e.equals)){o=!0;break}}finally{clearTimeout(l)}if(Date.now()>=t)break;await new Promise(c=>setTimeout(c,Math.min(100,t-Date.now())))}while(Date.now()<=t)}else{const t=String(e[n]);o=(n==="text"?await a.waitForText(t,!1,r):n==="control"?await a.waitForControl(t,!1,r):await a.waitForUrl(t,!1,r)).ok}}catch(t){throw i().push("expect",s,!1,`verification unavailable: ${t.message}; do not replay the preceding action`,!0,"uncertain"),t}if(i().push("expect",s,o,o?"condition verified":"condition was not verified; subsequent steps stopped, preceding action was not replayed",!0,o?"verified":"uncertain"),!o)throw new Error(`Expectation failed for ${s}. Observe the result before deciding whether any earlier action can be retried.`);return!0}}export{b as expectVerb};

package/dist/platform/tools/api-run.d.ts

@@ -0,0 +1,6 @@
+import type { JournalLine } from "./api-contract.ts";
+export declare function verbGate(onRefusal: (note: string) => void): (<T extends Record<string, unknown>>(fns: T) => T) & {
+    drain(): Promise<void>;
+};
+export declare function stringify(v: unknown): string;
+export declare function renderJournal(journal: JournalLine[]): string[];

package/dist/platform/tools/api-run.js

@@ -0,0 +1 @@
+function p(t){let e=null,r=null;return Object.assign(l=>Object.fromEntries(Object.entries(l).map(([i,u])=>{if(i==="log"||typeof u!="function")return[i,u];const h=u;return[i,(...f)=>{if(e){const c=`${i} was started while ${e} was still running \u2014 verbs run one at a time, because the surface has one focus and one caret. Two chains in flight put their input wherever the LAST one clicked. Await each verb before the next.`;throw t(c),new Error(c)}e=i;let o;try{o=h(...f)}catch(c){throw e=null,c}if(!(o instanceof Promise))return e=null,o;const a=o.finally(()=>{e=null,r=null});return r=a,a.catch(()=>{}),a}]})),{async drain(){for(;r;)await r}})}function g(t){if(typeof t=="string")return t;try{return JSON.stringify(t)??String(t)}catch{return String(t)}}const s=12;function w(t){const e=n=>`  ${n.i}. ${n.kind}${n.target?` ${n.target}`:""}${n.ok?"":" FAILED"}${n.outcome?` [${n.outcome}]`:""}${n.note?`: ${n.note}`:""}`;if(t.length<=s*2)return t.map(e);const r=t.length-s*2;return[...t.slice(0,s).map(e),`  \u2026 ${r} steps not listed \u2026`,...t.slice(-s).map(e)]}export{w as renderJournal,g as stringify,p as verbGate};

package/dist/platform/tools/api-target.d.ts

@@ -0,0 +1,22 @@
+import type { ComputerUseDriver } from "../driver.ts";
+import type { ToolResult } from "../types.ts";
+import { type FindScope, type Handle } from "./find-target.ts";
+import type { RunLedger, ApiHooks } from "./api-contract.ts";
+export declare function createTargeting(driver: ComputerUseDriver, ledger: () => RunLedger, hooks: ApiHooks, firstLine: (r: ToolResult) => string): {
+    findByName: (name: string, scope?: FindScope) => Promise<Handle | null>;
+    findWithMiss: (name: string, scope?: FindScope) => Promise<{
+        h: Handle | null;
+        miss: string;
+    }>;
+    asPoint: (t: unknown) => {
+        x: number;
+        y: number;
+    } | null;
+    resolve: (t: unknown, opts?: {
+        write?: boolean;
+    }) => Promise<{
+        ref: string;
+        name?: string;
+    }>;
+    requireFocus: (t: unknown) => Promise<void>;
+};

package/dist/platform/tools/api-target.js

@@ -0,0 +1 @@
+import{nearMissNote as y,rankByName as d,tiedOthers as b}from"./find-target.js";function T(i,p,c,E){const l=async(r,t={})=>(await w(r,t)).h,w=async(r,t={})=>{const{elements:e,groups:a,partial:s,covered:o}=await i.readElements();c.onRefs?.(e.map(h=>h.ref));const n=d(e,r,t,a);if(n)return{h:n,miss:""};const f=o&&d(o.elements,r,t),m=o&&f?`no actionable match \u2014 ${f.role??"control"} "${f.name}" (${f.ref}) is here but \xAB${o.elements.find(h=>h.ref===f.ref)?.coveredBy||o.by}\xBB covers it: dismiss that overlay first (find('close') reaches its close control when the page marks one; an unmarked one shows only in a screenshot), `+(i.scrollsInto?`or scroll({into:'${f.ref}'}) to bring it clear, `:"or scroll until the control sits clear of it, ")+"then find again":y(e,r,t,await g(r),a);return{h:n,miss:s?`${m} \u2014 but this read was PARTIAL (${s}), so it may be in the part not read; find again, or narrow with within:`:m}},g=async r=>{const t=r.trim().toLowerCase();if(!t)return!1;try{return(await i.readTextForWait()).toLowerCase().includes(t)}catch{return!1}},$=r=>{const t=r;return t&&typeof t=="object"&&typeof t.x=="number"&&typeof t.y=="number"?{x:t.x,y:t.y}:null},u=async(r,t={})=>{if(typeof r=="string"){if(c.onTarget?.(r),!i.knownRef(r))throw new Error(i.staleRefNote(r));return{ref:r}}if(r==null)throw new Error(`the target is ${r} \u2014 a find() that matched nothing answers null, and its line above says why`);let e=r;if(typeof e.ref!="string")throw new Error("a target must be a find() handle, a ref string, or a point {x, y} read off a screenshot");if(c.onTarget?.(e.ref),e.nearGroup){const o=await l(e.name,e.scope);if(!o||o.nearGroup!==e.nearGroup)throw new Error(`"${e.name}" is no longer in group "${e.nearGroup}" \u2014 observe() before acting`);e=o,c.onTarget?.(e.ref)}const a=t.write?b(e):[];if(a.length){const o=[{ref:e.ref,name:e.name,role:"",id:e.id},...a].map(n=>`${n.ref}${n.id?` (${n.id})`:""}`).join(", ");throw new Error(`"${e.name}" names ${a.length+1} controls of the same role and nothing tells them apart (${o}) \u2014 this write would be a guess. Narrow it: find('${e.name}', {within}) or {near}, or observe() and act by ref.`)}if(i.knownRef(e.ref))return{ref:e.ref,name:e.name};const s=await l(e.name,e.scope??{});if(!s)throw new Error(`"${e.name}" is no longer on the surface (its ref ${e.ref} is gone)`);if(e.matches===1&&(s.matches??1)>1)throw new Error(`"${e.name}" now matches ${s.matches} controls and its own ref ${e.ref} is gone, so re-resolving it would be a guess \u2014 observe() and act by ref, or narrow it: find('${e.name}', {role, within, visible})`);return{ref:s.ref,name:s.name}};return{findByName:l,findWithMiss:w,asPoint:$,resolve:u,requireFocus:async r=>{const{ref:t,name:e}=await u(r),a=Date.now()+200;for(;;){const{elements:s}=await i.readElements(),o=s.filter(n=>/(^|[,\s])focused([,\s]|$)/.test(n.state));if(!s.some(n=>n.ref===t))throw new Error(`focus: ${t} is not in the current observation \u2014 observe() and name a listed control`);if(o.length===1){const n=o[0];if(n.ref===t)return;throw new Error(`the keyboard focus is on ${n.ref} ${n.role}${n.name?` "${n.name}"`:""}, not on ${t}${e?` "${e}"`:""} \u2014 nothing was pressed. click it, set_text it, or select_text with a caret to focus it first, then send the key`)}if(Date.now()>=a)throw new Error(`focus could not be verified for ${t} \u2014 this surface reports ${o.length?"multiple focused elements":"no focused element"}; nothing was pressed. Observe and explicitly focus the intended control before sending a guarded key. Omit focus only when you deliberately want to send to the surface's current focus without verification.`);await new Promise(n=>setTimeout(n,50))}}}}export{T as createTargeting};

package/dist/platform/tools/api-wait.d.ts

@@ -0,0 +1,3 @@
+import type { ComputerUseDriver } from "../driver.ts";
+import { type RunLedger } from "./api-contract.ts";
+export declare function waitVerb(driver: ComputerUseDriver, ledger: () => RunLedger): (raw?: unknown) => Promise<boolean>;

package/dist/platform/tools/api-wait.js

@@ -0,0 +1 @@
+import{noteOf as g,options as u}from"./api-contract.js";const w=6e4;function p(o,i){return async(l={})=>{const t=u("wait",l,"wait({}) waits for the content to stop changing; wait({ms:2000}) sleeps; wait({text}) / ({control}) / ({text_gone}) / ({control_gone}) / ({url}) / ({url_gone}) / ({loaded:true}) wait for a condition");i().charge("wait"),o.noteAction("wait",t);const n=typeof t.text=="string"?t.text:typeof t.text_gone=="string"?t.text_gone:null,e=typeof t.control=="string"?t.control:typeof t.control_gone=="string"?t.control_gone:null,r=typeof t.url=="string"?t.url:typeof t.url_gone=="string"?t.url_gone:null,a=r!==null?await o.waitForUrl(r,typeof t.url_gone=="string",t.ms):t.loaded?await o.waitForLoad(t.ms):e!==null?await o.waitForControl(e,typeof t.control_gone=="string",t.ms):n!==null?await o.waitForText(n,typeof t.text_gone=="string",t.ms):typeof t.ms=="number"?await new Promise(s=>setTimeout(()=>s({ok:!0}),Math.min(Number(t.ms),w))):await o.waitSettled();return i().push("wait",r??e??n??(t.loaded?"loaded":String(t.ms??"")),a.ok,g(a)),a.ok}}export{p as waitVerb};

package/dist/platform/tools/api.d.ts

@@ -0,0 +1,7 @@
+import type { ComputerUseDriver } from "../driver.ts";
+import type { VerbSpec } from "../types.ts";
+import { fnName, noteOf, type ApiHooks, type JournalLine, type RunLedger, type WriteRound } from "./api-contract.ts";
+export { fnName, noteOf, type ApiHooks, type JournalLine, type RunLedger, type WriteRound };
+export declare function isReadVerb(kind: string, args: Record<string, unknown>, verbs: readonly VerbSpec[]): boolean;
+export declare function createComputerUseApi(driver: ComputerUseDriver, ledger: () => RunLedger, hooks?: ApiHooks): Record<string, unknown>;
+export { renderJournal, stringify, verbGate } from "./api-run.ts";

package/dist/platform/tools/api.js

@@ -0,0 +1 @@
+import{STATE_CHANGING_ACTIONS as B}from"../driver.js";import{withoutBlankOptionals as G}from"./normalize.js";import{ambiguityNote as L,findScope as D,scopeLabel as U}from"./find-target.js";import{argComplaint as q}from"./validate.js";import{createTargeting as F}from"./api-target.js";import{waitVerb as H}from"./api-wait.js";import{expectVerb as W}from"./api-expect.js";import{checkShotPath as J,saveShot as Y}from"./shot-file.js";import{fnName as E,firstLine as x,firstText as O,noteOf as S,options as g}from"./api-contract.js";const z=600,j=150;function K(r,c,w){return r==="menu"&&!c.path||w.some($=>$.kind===r&&$.readOnly)}function ie(r,c,w={}){const $=r.extraVerbs(),V=new Map($.map(e=>[e.kind,e.schema])),C=[...V.keys()],{findWithMiss:v,asPoint:N,resolve:y,requireFocus:M}=F(r,c,w,x);let T=null;const k=(e,t)=>{const n=V.get(e);if(!n)return null;const o=G({kind:e,...t},n);return q(n,E(e),o)},R=async(e,t,n,o=!1)=>{c().charge(e);const s=k(e,t);if(s)throw c().push(e,n,!1,s,!1,"blocked"),new Error(s);const i=K(e,t,$);if(!i)try{await w.beforeAction?.(e,t)}catch(u){throw c().push(e,n,!1,u.message,!1,"blocked"),u}i||r.noteAction(e,t),i?r.noteContentRead():T=e,i||await r.ensureSettleBaseline(e);let a;try{a=e==="focus"?await r.focusTarget(String(t.target??"")):await r.perform(e,t)}catch(u){throw c().push(e,n,!1,`${u.message}; outcome unknown \u2014 observe before retrying`,i,i?void 0:"uncertain"),u}a.ok&&r.publishPreview(i?void 0:e,t);const l=(o||e==="type")&&a.ok&&a.verified===!1,f=e==="set_text"&&a.ok&&a.verified===void 0?`${S(a)||"write dispatched"}; read-back unavailable \u2014 the value was not verified`:S(a),m=a.mayHaveActed||a.verified===!1?"uncertain":a.ok?a.verified===!0?"verified":"dispatched":"blocked";c().push(e,n,a.ok&&!l,f,i,i?void 0:m);const p=c().round;if(p&&a.ok&&(e==="set_text"?(p.fields+=1,a.verified===!0&&(p.verified+=1)):p.ended=`${e}${t.chord?` ${String(t.chord)}`:""}${n?` ${n}`:""}`),!a.ok)throw new Error(`${e}${n?` ${n}`:""} failed: ${a.note??"no reason given"}`);if(l){const u=new Error(`${e==="type"?"type":"setText"} ${n}: ${a.note??"the field did not retain the requested text"}. The write was dispatched, but verification failed; subsequent actions were not run. `+(e==="type"?"Observe the focused field before continuing.":"Use setTextBestEffort only when you intend to handle a mismatched value yourself."));throw u.name="WriteVerificationError",u}return a},A=async(e,t,n,o)=>{const s=g("setText",o,"setText(target, text, {ifValue:previousValue})");if(Object.keys(s).some(f=>f!=="ifValue")||s.ifValue!==void 0&&typeof s.ifValue!="string")throw new Error("setText's only option is ifValue:string");const{ref:i,name:a}=await y(e,{write:!0});if(s.ifValue!==void 0&&(c().charge("precondition"),!r.readValue||!r.valueMatches(await r.readValue(i),s.ifValue))){const f="The field no longer matches ifValue, or cannot be read. Nothing was written; observe and reconcile the edit.";throw c().push("set_text",i,!1,f,!1,"blocked"),new Error(f)}return(await R("set_text",{ref:i,...a?{name:a}:{},text:String(t??"")},i,n)).verified},h=async(e,t,n)=>{const o=await R(e,t,n);return"value"in o?o.value:o.note||(n?`${e} ${n}`:e)},d=(e,t,n,o)=>async()=>{c().charge(e),r.noteContentRead();const s=await o();return r.publishPreview(),c().push(e,t,!0,n(s)),s},_=(e,t,n)=>async(...o)=>{if(o.length)throw new Error(`${e}() takes no arguments \u2014 ${t}`);return n()},I={observe:async(e={})=>{const t=g("observe",e,"observe() lists every element; observe({screenshot: true}) also attaches the picture"),n=Object.keys(t).filter(b=>b!=="screenshot");if(n.length)throw new Error(`observe() does not take ${n.join(", ")} \u2014 it already answers with EVERY element, on screen and beyond it (each one off-viewport carries \`offscreen: true\`); narrow it by filtering the array it returns. Its one option is screenshot: true.`);c().charge("observe");const{url:o,title:s,elements:i,groups:a,headings:l,partial:f,coverage:m,target:p}=await r.readElements();w.onRefs?.(i.map(b=>b.ref));let u="";if(t.screenshot){c().charge("screenshot");const b=await r.observeImage();for(const P of b.content)P.type==="image"&&(c().attach(P),u=" + image");u||(u=` (no image \u2014 ${x(b)})`)}return c().push("observe","",!0,`${i.length} elements${u}`),{url:o,title:s,elements:i,coverage:m,...p?{target:p}:{},...a?.length?{groups:a}:{},...l?.length?{headings:l}:{},...f?{partial:f}:{}}},find:async(e,t={})=>{c().charge("find");const n=D(t,r.readsOffscreen);let{h:o,miss:s}=await v(String(e??""),n);if(!o&&B.has(T??"")){T=null;for(let i=0;!o&&i<z;i+=j)await new Promise(a=>setTimeout(a,j)),{h:o,miss:s}=await v(String(e??""),n)}return c().push("find",`${String(e??"")}${U(n)}`,!0,o?L(o):s),o},text:_("text","it returns the surface's whole readable text",d("text","",e=>`${e.length} chars`,()=>r.readText())),value:async e=>{if(!r.readValue)throw new Error("value() is not supported on this platform \u2014 text() reads the whole surface instead");const t=await y(e);return d("value",t.ref,n=>`${n.length} chars`,()=>r.readValue(t.ref))()},page:async(e={})=>{const t=g("page",e,"page() reads the whole page and page({ref}) one node \u2014 to NAVIGATE, openUrl({url})");if(!r.readPage)throw new Error("page reading is not supported on this platform \u2014 use text()");if(t.ref&&!r.knownRef(t.ref))throw new Error(r.staleRefNote(t.ref));const n=d("page",t.ref??t.node??"",o=>x(o),()=>r.readPage(t));return O(await n())},screenshot:async(e={})=>{const{path:t,...n}=g("screenshot",e,"screenshot() takes the viewport; screenshot({ref}) / ({region}) / ({fullPage:true}) narrow it");if(n.ref&&!r.knownRef(n.ref))throw new Error(r.staleRefNote(n.ref));if(t!==void 0&&typeof t!="string")throw new Error("screenshot path must be a string");t&&J(t,r.screenshotMimeType);const o=!!(n.ref||n.region||n.fullPage||n.padding!==void 0);let s=null;const i=f=>s?`saved ${s.path}`:`no image \u2014 ${x(f)}`,l=await d("screenshot",n.ref??(n.fullPage?"full page":n.region?"region":""),i,async()=>{const f=await r.observeImage(o?{scope:n}:{}),m=f.content.find(p=>p.type==="image");return m&&m.type==="image"&&(s=Y(m.data,m.mimeType,t||void 0)),f})();for(const f of l.content)f.type==="image"&&c().attach(f);return s?{...s,note:x(l),...l.details.capture?{capture:l.details.capture}:{}}:{path:null,note:i(l)}},diagnostics:async(e={})=>{const t=g("diagnostics",e,"diagnostics() reads every channel, diagnostics({id}) one of them");return O(await d("diagnostics",t.id??"",x,async()=>r.readDiagnostics(t))())},targets:_("targets","it lists every surface there is",d("targets","",e=>`${e.length} targets`,()=>r.listTargets())),click:async(e,t={})=>{const n=N(e);if(n)return h("click",{...n,...t},`${n.x},${n.y}`);const{ref:o,name:s}=await y(e,{write:!0});return h("click",{ref:o,...s?{name:s}:{},...t},o)},hover:async e=>{const t=N(e);if(t)return h("hover",{...t},`${t.x},${t.y}`);const{ref:n,name:o}=await y(e);return h("hover",{ref:n,...o?{name:o}:{}},n)},setText:(e,t,n)=>A(e,t,!0,n),setTextBestEffort:(e,t,n)=>A(e,t,!1,n),keys:async(e,t,n)=>{const o=typeof t=="object"&&t!==null?t:n,s=typeof t=="number"?t:void 0;return o?.focus!==void 0&&await M(o.focus),h("keys",{chord:String(e??""),...s?{count:s}:{}},String(e??""))},scroll:async(e={})=>{const t=g("scroll",e,"scroll({direction:'down'}) or scroll({to:'bottom'})");if(t.into!==void 0){const n=typeof t.into=="string"?t.into:t.into?.ref;if(typeof n!="string")throw new Error("scroll({into}) takes a ref string or a find() handle");if(!r.scrollsInto)throw new Error("scroll({into}) is not available on this platform \u2014 scroll by direction, count or to:");const o=["direction","count","to","ref"].filter(i=>t[i]!==void 0);if(o.length)throw new Error(`scroll({into}) moves to one control and takes nothing else \u2014 drop ${o.join(", ")}`);w.onTarget?.(n);const s=await h("scroll",{into:n},n);return await r.readElements().catch(()=>{}),s}return typeof t.ref=="string"&&w.onTarget?.(t.ref),h("scroll",{...t},String(t.ref??t.direction??t.to??""))},wait:H(r,c),expect:W(r,c,async e=>{if(!r.readValue)throw new Error("This platform cannot read field values");const{ref:t}=await y(e);return r.readValue(t)}),focus:async e=>h("focus",{target:String(e??"")},String(e??"")),log:(...e)=>{c().charge("log"),c().push("log","",!0,e.map(Q).join(" ").slice(0,200))},act:async(e,t={})=>{if(typeof t.ref=="string"&&(w.onTarget?.(t.ref),!r.knownRef(t.ref)))throw new Error(r.staleRefNote(t.ref));return h(String(e??""),{...t},String(t.ref??""))}};for(const e of C)I[E(e)]=async(t={})=>{const n=g(E(e),t,`pass its arguments as an object, e.g. ${E(e)}({\u2026})`),o=n.ref!==void 0?await y(n.ref,{write:!0}):null;return h(e,{...n,...o?{ref:o.ref}:{}},String(n.ref??""))};return I}import{renderJournal as le,stringify as he,verbGate as pe}from"./api-run.js";import{stringify as Q}from"./api-run.js";export{ie as createComputerUseApi,E as fnName,K as isReadVerb,S as noteOf,le as renderJournal,he as stringify,pe as verbGate};

package/dist/platform/tools/find-target.d.ts

@@ -0,0 +1,54 @@
+export type Handle = {
+    ref: string;
+    name: string;
+    role?: string;
+    matches?: number;
+    others?: Array<{
+        ref: string;
+        name: string;
+        role: string;
+        id?: string;
+    }>;
+    id?: string;
+    scope?: FindScope;
+    nearGroup?: string;
+    incidental?: boolean;
+    byValue?: boolean;
+    byShortName?: boolean;
+};
+export interface FindScope {
+    role?: string;
+    within?: string;
+    visible?: boolean;
+    near?: string;
+}
+interface Named {
+    ref: string;
+    name: string;
+    role: string;
+    id?: string;
+    state?: string;
+    offscreen?: boolean;
+    rect: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+type NamedGroup = {
+    label: string;
+    members: string[];
+};
+export declare function rankByName(elements: Named[], name: string, scope?: FindScope, groups?: NamedGroup[]): Handle | null;
+export declare function findScope(opts: unknown, readsOffscreen: boolean): FindScope;
+export declare function scopeLabel(scope: FindScope): string;
+export declare function nearMissNote(elements: Named[], name: string, scope?: FindScope, inText?: boolean, groups?: NamedGroup[]): string;
+export declare function tiedOthers(h: Handle): Array<{
+    ref: string;
+    name: string;
+    role: string;
+    id?: string;
+}>;
+export declare function ambiguityNote(h: Handle): string;
+export {};

package/dist/platform/tools/find-target.js

@@ -0,0 +1 @@
+const O=3;function L(e){const n=/(?:^|,)\s*filled:([^,]*)/.exec(e.state??"");if(!n)return null;const t=n[1].trim();return t?{text:t.replace(/…$/,""),cut:/…$/.test(t)}:null}function N(e){const n=o=>o.rect.w*o.rect.h,t=(o,s)=>{const r=s.rect.x+s.rect.w/2,h=s.rect.y+s.rect.h/2;return n(s)<=n(o)&&o.rect.x<=r&&r<=o.rect.x+o.rect.w&&o.rect.y<=h&&h<=o.rect.y+o.rect.h},i=new Map;for(const o of e){const s=o.name.trim().toLowerCase();(i.get(s)??i.set(s,[]).get(s)).push(o)}const a=new Set;for(const o of i.values())if(!(o.length<2))for(const s of o)for(const r of o)s!==r&&t(s,r)&&a.add(s);return a.size?e.filter(o=>!a.has(o)):e}const S=3;function A(e,n){const t=e.trim().toLowerCase();return t.length<S||t.length>=n.length||!n.startsWith(t)?!1:/[^\p{L}\p{N}]/u.test(n.charAt(t.length))}function v(e,n,t=[]){if(!n)return;const i=n.trim().toLowerCase(),a=e.filter(s=>s.label.trim().toLowerCase()===i);if(!a.length&&t.some(s=>s.name.trim().toLowerCase()===i))return;const o=a.length?a:e.filter(s=>s.label.toLowerCase().includes(i));if(o.length>1)throw new Error(`near: "${n}" names ${o.length} groups \u2014 use a more specific group label or observe() and act by ref`);return o[0]}function E(e,n,t={},i=[]){const a=n.trim().toLowerCase(),o=v(i,t.near,e),s=o?new Set(o.members):null,r=I(e,t).filter(l=>!s||s.has(l.ref)),h=r.filter(l=>l.name.trim().toLowerCase()===a||(l.id??"").trim().toLowerCase()===a),d=h.length?[]:r.filter(l=>l.name.toLowerCase().includes(a)).sort((l,m)=>l.name.length-m.name.length),f=d.filter(l=>!G(l.name,a)),w=h.length||f.length?[]:r.filter(l=>A(l.name,a)).sort((l,m)=>m.name.trim().length-l.name.trim().length),g=h.length||f.length||w.length?[]:r.filter(l=>{const m=L(l);return!!m&&(m.cut?m.text.toLowerCase().startsWith(a):m.text.toLowerCase()===a)}),$=h.length||f.length||w.length||g.length?[]:r.filter(l=>L(l)?.text.toLowerCase().includes(a)).sort((l,m)=>(L(l)?.text.length??0)-(L(m)?.text.length??0)),y=!h.length&&!f.length&&w.length>0,c=!h.length&&!f.length&&!y&&(g.length>0||$.length>0),u=!h.length&&!f.length&&!y&&!c&&d.length>0,p=h.length?h:f.length?f:w.length?w:g.length?g:$.length?$:d,x=p.filter(l=>l.role!=="text"),C=N(T(x.length?x:p,e,o?void 0:t.near)),b=C[0];return b?{ref:b.ref,name:b.name,role:b.role,matches:C.length,...o?{nearGroup:o.label}:{},...b.id?{id:b.id}:{},others:C.slice(1,4).map(l=>({ref:l.ref,name:l.name,role:l.role,...l.id?{id:l.id}:{}})),...u?{incidental:!0}:{},...c?{byValue:!0}:{},...y?{byShortName:!0}:{},...t.role||t.within||t.visible||t.near?{scope:t}:{}}:null}function I(e,n){let t=e;if(n.role){const i=n.role.trim().toLowerCase();t=t.filter(a=>a.role.toLowerCase()===i)}if(n.visible&&(t=t.filter(i=>!i.offscreen)),n.within){const i=e.find(a=>a.ref===n.within)?.rect;if(!i)throw new Error(`within: ${n.within} is not in the current observation \u2014 observe() and use a ref it lists`);t=t.filter(a=>{const o=a.rect.x+a.rect.w/2,s=a.rect.y+a.rect.h/2;return o>=i.x&&o<=i.x+i.w&&s>=i.y&&s<=i.y+i.h})}return t}function T(e,n,t){if(!t)return e;const i=t.trim().toLowerCase(),a=n.find(r=>r.name.trim().toLowerCase()===i)??n.find(r=>r.name.toLowerCase().includes(i));if(!a)throw new Error(`near: nothing on the surface is named "${t}", so it cannot pick between the matches \u2014 read the surface with text() and name something that is really beside the one you mean`);const o=r=>({x:r.x+r.w/2,y:r.y+r.h/2}),s=o(a.rect);return[...e].sort((r,h)=>{const d=o(r.rect),f=o(h.rect);return Math.hypot(d.x-s.x,d.y-s.y)-Math.hypot(f.x-s.x,f.y-s.y)})}function j(e,n){if(e==null)return{};if(typeof e!="object")throw new Error(`find's second argument is an options object: {role, within${n?", visible":""}, near}`);const t=e,i=typeof t.within=="string"?t.within:t.within&&typeof t.within=="object"&&typeof t.within.ref=="string"?t.within.ref:void 0;if(t.within!==void 0&&i===void 0)throw new Error("find's `within` must be a ref string or a find() handle");if(t.visible&&!n)throw new Error("find's `visible` narrows nothing on this platform \u2014 its read never contains an off-screen control, so every match find returns is already on screen. Drop it; to reach what is scrolled out, scroll first, then find");return{...typeof t.role=="string"&&t.role.trim()?{role:t.role.trim()}:{},...i?{within:i}:{},...t.visible?{visible:!0}:{},...typeof t.near=="string"&&t.near.trim()?{near:t.near.trim()}:{}}}function _(e){const n=[...e.role?[`role:${e.role}`]:[],...e.within?[`within:${e.within}`]:[],...e.visible?["visible"]:[],...e.near?[`near:${e.near}`]:[]];return n.length?` {${n.join(", ")}}`:""}const k=6,M=40;function G(e,n){return e.length>M&&e.length>k*n.length}function R(e,n,t={},i=!1,a=[]){const o=n.trim().toLowerCase(),s=v(a,t.near,e);if(s)return`no matching control in group "${s.label}" \u2014 nothing outside this group's members was considered; observe() to check its controls`;const r=i?" \u2014 but the surface's TEXT carries it, so it IS here and is not a control: nothing to act on, read it with text(), or use it to scope another find (near:'\u2026')":"",h=e.filter(c=>c.name.trim()&&c.role!=="text");if(!h.length)return`no match \u2014 this surface lists no named controls at all${r}`;if(t.role||t.visible||t.within){const c=E(e,n,{});if(c)return`no match under ${t.role?`role:'${t.role}'`:t.visible?"visible:true":`within:${t.within}`} \u2014 without it the name finds ${c.ref} (${c.name.slice(0,40)}); widen the scope or name the control the surface actually carries`}const d=c=>c.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(u=>u.length>1),f=d(o);if(!f.length)return`no match${r}`;const w=h.map(c=>{const u=new Set(d(c.name)),p=f.filter(x=>u.has(x)).length;return{e:c,score:p/f.length}}).filter(c=>c.score>=.34).sort((c,u)=>u.score-c.score||c.e.name.length-u.e.name.length),g=new Set,$=w.filter(c=>{const u=`${c.e.role}\0${c.e.name.trim().toLowerCase()}`;return g.has(u)?!1:(g.add(u),!0)}).slice(0,3);return $.length?`no match \u2014 closest by name: ${$.map(c=>`${c.e.role} "${c.e.name.slice(0,40)}"`).join(", ")}${r}`:`no match \u2014 nothing among the ${h.length} named controls is close to it${r}`}function D(e){const n=e.scope??{};if((e.matches??1)<2||!e.others?.length)return[];if(!e.nearGroup&&n.near)return[];const t=e.name.trim().toLowerCase();return e.others.filter(i=>i.name.trim().toLowerCase()===t&&i.role===e.role)}function H(e){const n=e.matches??1,t=e.nearGroup?` (in group "${e.nearGroup}")`:"";if(e.incidental){const r=n>1?` (${n} such matches)`:"";return`${e.ref} \u2014 nothing here is NAMED that${r}; the closest is the word inside \xAB${e.name.slice(0,60)}${e.name.length>60?"\u2026":""}\xBB, which is probably not the control you meant \u2014 name it as the surface spells it, or observe() and pick a ref`}if(e.byShortName){const r=n>1?` (${n} such matches)`:"";return`${e.ref} \u2014 the surface spells it \xAB${e.name}\xBB${r}, which is where your name STARTS; the rest of what you asked for was matched against nothing. Controls relabel themselves as a flow progresses, so check this is the one you meant`}if(e.byValue){const r=n>1?` (${n} such matches)`:"";return`${e.ref} \u2014 matched by the VALUE it holds, not by a name${r}: ${e.name?`its own name is "${e.name}"`:"it has no name of its own"}. A file row and a filled field are the usual shape`}if(n<=1)return e.ref+t;const i=r=>r.id&&r.id.toLowerCase()!==r.name.trim().toLowerCase()?` \u27E8id: ${r.id}\u27E9`:"",a=(e.others??[]).map(r=>`${r.ref} "${r.name}"${i(r)}`).join(", "),o=n-1-(e.others?.length??0),s=e.id||(e.others??[]).some(r=>r.id)?", or name one of their ids \u2014 exact, and never translated":"";return`${e.ref}${i(e)}${t} \u2014 1 of ${n} matching "${e.name}" (also ${a}${o>0?`, +${o} more`:""}); name it more precisely if that is the wrong one${s}`}export{H as ambiguityNote,j as findScope,R as nearMissNote,E as rankByName,_ as scopeLabel,D as tiedOthers};

package/dist/platform/tools/index.d.ts

@@ -0,0 +1,8 @@
+import { type ComputerUseToolSpec } from "../types.ts";
+import { type PlatformSlice } from "./repl.ts";
+import type { OwnershipProvider } from '../ownership.ts';
+export declare function createComputerUseTools(mounted: PlatformSlice | PlatformSlice[], opts?: {
+    diagnostics?: boolean;
+    docsDelivered?: boolean;
+    ownership?: OwnershipProvider;
+}): ComputerUseToolSpec[];

package/dist/platform/tools/index.js

@@ -0,0 +1 @@
+import{SurfaceGoneError as p,SurfaceUnreadableError as f,spec as l,text as i}from"../types.js";import{withoutBlankOptionals as m}from"./normalize.js";import{createReplTools as d}from"./repl.js";import{argComplaint as h}from"./validate.js";function g(e,r){const c=e.execute.bind(e);return l({...e,async execute(u){const t=r.epoch,o=r.p.then(async()=>{if(t!==r.epoch)return i("This queued call was cancelled by a runtime reset; bind fresh handles before continuing.",{error:"runtime_reset"});const a=m(u,e.parameters),n=h(e.parameters,e.name,a);if(n)return i(n,{error:"bad_arguments"});try{return await c(a)}catch(s){if(s instanceof p)return i(s.message,{error:"surface_gone"});if(s instanceof f)return i(s.message,{error:"surface_unreadable"});throw s}});return r.p=o.then(()=>{},()=>{}),o}})}function v(e,r={}){const c=Array.isArray(e)?e:[e];for(const{driver:n}of c)r.diagnostics&&n.supportsDiagnostics&&n.enableDiagnostics();const[u,t]=d(c,{docsDelivered:r.docsDelivered,ownership:r.ownership}),o={p:Promise.resolve(),epoch:0},a=t.execute.bind(t);return t.execute=async n=>(o.epoch++,a(n)),[g(u,o),t]}export{v as createComputerUseTools};

package/dist/platform/tools/normalize.d.ts

@@ -0,0 +1,2 @@
+import type { TSchema } from "typebox";
+export declare function withoutBlankOptionals(params: unknown, schema: TSchema): unknown;

package/dist/platform/tools/normalize.js

@@ -0,0 +1 @@
+function c(e){if(typeof e=="string")return e.trim()==="";if(typeof e!="object"||e===null||Array.isArray(e))return!1;const n=Object.values(e);return n.length>0&&n.every(t=>t===0)}function f(e,n){const t=Object.entries(n.properties??{}).filter(([,r])=>r.const!==void 0);return t.length>0&&t.every(([r,i])=>e[r]===i.const)}function l(e,n){if(n.anyOf)return n.anyOf.filter(r=>f(e,r));const t=Object.entries(n.properties??{}).filter(([r,i])=>i.anyOf&&!(r in e)).flatMap(([,r])=>r.anyOf.filter(i=>f(e,i)));return[n,...t]}function s(e,n){if(typeof e!="object"||e===null||Array.isArray(e))return;const t=e;for(const r of l(t,n)){const i=r.required??[];for(const[o,u]of Object.entries(r.properties??{}))o in t&&(!i.includes(o)&&c(t[o])?delete t[o]:s(t[o],u))}}function y(e,n){if(typeof e!="object"||e===null)return e;const t=structuredClone(e);return s(t,n),t}export{y as withoutBlankOptionals};

package/dist/platform/tools/repl-budget.d.ts

@@ -0,0 +1,8 @@
+import { type ToolResult } from "../types.ts";
+export declare const MAX_ACTIONS = 100;
+export declare const MAX_MS = 60000;
+export declare const SYNC_MAX_MS = 10000;
+export declare const RETURN_CAP = 12000;
+export declare const MAX_REF_OWNERS = 4000;
+export type Render = "full" | "brief" | "none";
+export declare function trimObservation(r: ToolResult, render: Render): ToolResult;

package/dist/platform/tools/repl-budget.js

@@ -0,0 +1,4 @@
+import"../types.js";const f=100,x=6e4,_=1e4,d=12e3,u=4e3;function A(t,o){if(o==="full")return t;const n=t.content.find(e=>e.type==="text");if(!n||n.type!=="text")return t;const p=n.text.split(`
+`),i=o==="brief"?t.details.headLines:t.details.actionLines??t.details.ledgerLines;if(i===void 0)return t;const s=p.slice(0,Number(i)),c=Array.isArray(t.details.keep)?t.details.keep:[],a=new Set(s);for(const e of c)e.split(`
+`).every(l=>a.has(l))||s.push(e);return n.text=s.join(`
+`),t.content=t.content.filter(e=>e.type!=="image"),t.details.observation=o,t}export{f as MAX_ACTIONS,x as MAX_MS,u as MAX_REF_OWNERS,d as RETURN_CAP,_ as SYNC_MAX_MS,A as trimObservation};

package/dist/platform/tools/repl-code.d.ts

@@ -0,0 +1 @@
+export declare function prepareCode(src: string): string;

package/dist/platform/tools/repl-code.js

@@ -0,0 +1,4 @@
+import{parse as d}from"acorn";function r(n,s){switch(n.type){case"Identifier":s.push(n.name);break;case"ObjectPattern":for(const t of n.properties)r(t.type==="RestElement"?t.argument:t.value,s);break;case"ArrayPattern":for(const t of n.elements)t&&r(t,s);break;case"AssignmentPattern":r(n.left,s);break;case"RestElement":r(n.argument,s);break}}function u(n){const s=d(n,{ecmaVersion:"latest",sourceType:"script",allowAwaitOutsideFunction:!0,allowReturnOutsideFunction:!0}),t=[],i=[],l=e=>n.slice(e.start,e.end);for(const e of s.body)if(e.type==="VariableDeclaration"){const c=e.declarations.map(a=>(r(a.id,t),`(${l(a.id)} = ${a.init?l(a.init):"undefined"})`));i.push({start:e.start,end:e.end,text:`${c.join(", ")};`})}else(e.type==="FunctionDeclaration"||e.type==="ClassDeclaration")&&e.id&&(t.push(e.id.name),i.push({start:e.end,end:e.end,text:";"}),i.push({start:e.start,end:e.start,text:`${e.id.name} = `}));let o=n;for(const e of i.sort((c,a)=>a.start-c.start))o=o.slice(0,e.start)+e.text+o.slice(e.end);return`${t.length?`var ${[...new Set(t)].join(", ")};
+`:""}(async () => {
+${o}
+})()`}export{u as prepareCode};

package/dist/platform/tools/repl-docs.d.ts

@@ -0,0 +1,5 @@
+import type { ComputerUseDriver } from "../driver.ts";
+export declare const REPL_DESCRIPTION: string;
+export declare const RESET_DESCRIPTION: string;
+export declare function apiReference(driver: ComputerUseDriver): string;
+export declare function platformReference(driver: ComputerUseDriver): string;

package/dist/platform/tools/repl-docs.js

@@ -0,0 +1,4 @@
+import{fnName as u}from"./api.js";const w="Run JavaScript in this session's PERSISTENT runtime to look at and act on the GUI \u2014 web pages in a browser, Electron apps and native macOS / Windows apps, whichever this server mounts \u2014 the one tool for both. The code is an async function body: `await` every verb, `return` a value to get it back as JSON, and top-level const/let/function declarations SURVIVE to later calls \u2014 keep handles and collected data in them instead of re-reading. Surfaces (tabs / windows / apps) are HANDLES and EVERY verb lives on one \u2014 there are no top-level verbs. Bind first: computer.surface('<id or title>') names one, computer.surface() alone takes the only surface when there is just one, computer.surfaces() lists them. Then w.observe() w.find(name) w.click(t) w.setText(t, text) w.keys(chord, n) w.scroll({\u2026}) w.wait({\u2026}) w.text() w.page({\u2026}) w.screenshot({\u2026}) and this platform's own verbs, each switching to that surface as needed; a ref read on one surface is refused on another. Bind ONCE \u2014 keep the handle in a top-level variable and later calls reuse it. The first bound operation claims the target across calls; await w.release() when its task is done. Another runtime's claim refuses input before dispatch. The first result carries the full API reference (computer.help() returns it again) \u2014 use only what it documents. One verb at a time (one focus, one caret): a failed action or expect() throws and stops the run; wait() instead returns false on timeout, so check it or use expect() for a required condition. The result is the step journal plus one observation of the surface it acted on. Per call: 100 actions, 60 s. No require/import/fetch/process/timers. Before using an operation that may affect the user's foreground, real pointer, keyboard focus or system clipboard (including automatic fallback), explain its target and effects and obtain permission unless existing permission covers them. Do not silently escalate a background operation; inspect computer.help() for platform-specific effects. Before sending a message or publishing a post, let the user confirm its content and recipients or destination, unless they already approved those exact details.",m=`Reset computer_repl's persistent JavaScript runtime: every binding \u2014 handles, variables, functions \u2014 is discarded, and the next computer_repl call starts fresh and returns the API reference again. Nothing on the surfaces changes: no tab, window or app is closed. This runtime's target ownership is released after any active call stops. Use it only when the runtime is wedged or its state is wrong, never as a way to "start over" on the screen.`;function p(e,a){const o=a,s=Object.keys(o.properties??{}).filter(t=>t!=="kind"),n=new Set(o.required??[]),r=t=>n.has(t)?t:`${t}?`,h=s.filter(t=>t!=="ref"&&t!=="name").map(t=>o.properties?.[t]?.description).find(Boolean),i=o.description??h??"",c=/^.*?[.!?](?=\s+[A-Z(`]|$)/s.exec(i)?.[0]??i,d=s.filter(t=>t==="ref"||t==="name").flatMap(t=>o.properties?.[t]?.description?[`    ${r(t)}: ${o.properties[t].description}`]:[]);return[`  w.${u(e)}({${s.map(r).join(", ")}})${c?` \u2014 ${c.trim()}`:""}`,...d,...n.has("ref")&&s.includes("name")?["    name does not replace the required ref."]:[]].join(`
+`)}function l(e){const a=e.extraVerbs();return{head:["API reference \u2014 computer_repl (this text comes once per session; computer.help() returns it again)","","Everything is async \u2014 the verbs AND computer.surfaces() / computer.surface(\u2026): await each. A verb that","fails THROWS with the reason, which stops the run; the journal in the result says what ran. Refs (e12)","come from observe()/find() and stay valid until the surface changes; never invent one, and never carry one in from","another session \u2014 a fresh session re-mints them, so the same e12 names a different element. A target `t` is "+"a find() handle, a ref string, or a point {x, y} read off a screenshot"+".","","Bind a surface first \u2014 every verb below is a method on the handle it returns, never a name of its own:",'  await computer.surfaces()     \u2192 [handle] \u2014 every surface (tab / window / app) as {id, kind, title, active}; `id` is an opaque key, what the platform knows the surface by lives in `title` (macOS: "TextEdit (com.apple.TextEdit) \u2014 Untitled"; Windows: the window title, then the program name \u2014 "Untitled - Notepad \u2014 Notepad")',"  await computer.surface(name)  \u2192 handle \u2014 by id, by whole title, or by a piece of the title; several matches or none is a refusal that lists the candidates, never a guess",'  await computer.surface()      \u2192 handle \u2014 the ONE surface, when there is only one. Not "whatever is in front": with more than one open it refuses and lists them, so a script always says which it meant',"  Bind once per surface and keep the handle in a top-level declaration \u2014 it stays valid for later calls, and re-binding costs a read each time.","  A browser tab marked unloaded:true is still discoverable. Using its handle restores that exact tab in the background after acquiring ownership; merely listing tabs never reloads it.",""],reads:[...e.interactionNotes(),"Reads (return data to your code; none of them is shown to you except through `return` or computer.log):",e.readsOffscreen?"  w.observe({screenshot?}) \u2192 {url, title, elements:[{ref, role, name, state, rect, offscreen?}], groups?, headings?, partial?, coverage, target?} \u2014 every control, viewport and beyond; filter the array rather than asking it to narrow. `rect` {x, y, w, h} is the control's box \u2014 compare boxes to answer layout questions (which row a control sits on, whether it moved) without a screenshot. `groups` is the page's OWN labelling of those controls \u2014 [{label, members:[ref]}] over that same set, off-viewport members included \u2014 present where the author wrote one, and the only place some facts exist (a feed labels each post's button row with its counts, bookmarks included, which no control name and no page text carries). `headings` (web surfaces) is [{name, level, rect}] for the page's headings, never listed as controls \u2014 the fixed point to measure a control's box against, since a click can scroll the container under every control in a card. `partial` (a reason) says the read stopped before covering the surface, so what it did not list may still be there. screenshot:true also attaches the picture of the same screen (one call, two reads), for when you need to SEE where something is":"  w.observe({screenshot?}) \u2192 {url, title, elements:[{ref, role, name, state, rect}], coverage} \u2014 every control the window SHOWS (`rect` {x, y, w, h} is its box \u2014 compare boxes to answer layout questions without a screenshot); one scrolled out of view is counted in the observation and never listed, so no ref names it until a scroll brings it in; filter the array rather than asking it to narrow. screenshot:true also attaches the picture of the same screen","    coverage reports exact {offscreen, covered, capped, modal?} counts (null when unreported) even when repeated context notes are omitted. Electron target reports the CDP endpoint, windowId and, when its user agent carries them, the app's own name/version; never infer the app version from the tool or helper path.","  w.find(name, {role?, within?, "+(e.readsOffscreen?"visible?, ":"")+"near?}) \u2192 {ref, name, matches, others, incidental?} | null \u2014 by visible name, "+(e.readsOffscreen?"whole surface":"everything the window shows \u2014 NOT what is scrolled out of it, which this platform's read does not contain")+" (an exact name beats a partial one, a partial the query is most of beats one it is only a fragment of, and a control beats a text label); a handle that re-resolves itself when used, so a loop survives a re-render; `matches` says how many controls carried the name and `others` names the runners-up, so an ambiguous name is visible BEFORE you act on the pick; `incidental: true` says NOTHING here is NAMED that and the pick is only a long name that happens to contain the word \u2014 the one `matches: 1` not to trust; narrow it with role (button / textbox / \u2026), within (a ref or handle \u2014 matches inside that element's box, e.g. one sheet or one message)"+(e.readsOffscreen?" visible (on screen only)":"")+" and near (a labelled group restricts candidates to its members; otherwise prefer the control closest to the named element). Duplicate group labels or same-named controls within a group still need disambiguation","  w.text()                 \u2192 the surface's full readable text",...e.readValue?["  w.value(t)               \u2192 ONE control's whole value as a string \u2014 a long field, a clipped label, the text you are about to edit. The listing shows a value cut to what a line holds; this is the rest of it, for one element, where text() re-reads the entire surface"]:[],...e.readPage?["  w.page({ref?, depth?, node?}) \u2192 the content tree as text, with a completeness receipt on its first line"]:[],"  w.screenshot({ref?, padding?|region:{x,y,width,height}?|fullPage?, path?}) \u2192 {path, host, width, height, note, capture?} \u2014 the image is attached to this result for you to see AND written to a file the code can keep: to `path` (absolute, never overwrites an existing file, extension must match the surface's format \u2014 .jpg on web surfaces, .png on macOS and Windows) or else to a rolling temp directory; `host` names the machine the path is on; no image \u2192 {path: null, note: why}. ref is a ref string and crops to a visible element's box; padding keeps its surroundings. fullPage is web-only. On macOS and Windows, ref/region preserve native detail; region uses FULL screenshot pixels, so take a full screenshot first. Windows padding and crop bounds use physical pixels; macOS padding uses full-screenshot pixels when available, otherwise window points. capture reports the window, crop, units, pointsPerPixel, and toFullScreenshot (null without a full screenshot or when window geometry changed). Windows refuses a region based on old window geometry; take a new full screenshot. Convert crop pixel p to full screenshot coordinates with toFullScreenshot.origin + p * toFullScreenshot.scale on each axis. A crop never changes point-action coordinates; use a current mapping or act by ref.",...e.supportsDiagnostics?[`  w.diagnostics({id?})     \u2192 ${e.diagnosticsAbout.empty} \u2014 the newest 20, with the ones new since your last read marked "new"`]:[],"  computer.log(\u2026)               \u2192 a line in the journal; the one member that is not on a surface",""],actions:["Actions (every one is w.verb(\u2026) on a bound handle, which switches to that surface first):","  w.click(t, {button?, count?})   w.hover(t)","  w.setText(t, text) \u2014 replace the target field's ENTIRE value, even after selectText; never a selection/caret edit. Returns true when read-back matches; throws WriteVerificationError on mismatch, stopping the run unless caught.","  w.setTextBestEffort(t, text) \u2014 the same whole-field replacement, returning true/false without throwing on mismatch. Both return undefined when read-back is unavailable; that is not verification.","    click and hover also take a POINT \u2014 w.click({x, y}) \u2014 in the coordinates of the last screenshot, for a control you","    can see and cannot name. It checks no identity (no stale-ref gate, no name, no surface check) and so acts on","    whatever is at that spot NOW: take observe({screenshot: true}) and read the coordinates off that picture.","    click / hover / keys / scroll / focus answer with what they did, as text \u2014 the same note the journal shows, e.g. which","    rung a click ended on. A verb that FAILS throws instead, so a returned string always describes something that happened.","  w.keys(chord, count?, {focus?})  e.g. w.keys('Enter'), w.keys('Backspace', 3), w.keys('Enter', {focus: field}) \u2014 one key or chord, never a text string. setText replaces a whole field; use the platform's paste/type verb to edit at a selection or caret.","    keys go wherever the surface has the keyboard focus. Pass focus: <target> to REQUIRE it be there: if it is not,","    nothing is pressed, including when focus is unknown or ambiguous. Omit focus only to send without that check. Focusing stays explicit (click / setText / selectText with a caret).","  w.scroll({direction?: up|down|left|right, count?: screens (default 1), to?: top|bottom, ref?})   w.wait({} | {ms} | {text} | {text_gone} | {control} | {control_gone} | {url} | {url_gone} | {loaded}) \u2192 ok","    count covers that many screens in ONE call \u2014 the note says how far it actually got, which is less once the end is reached;","    count and to: are refused together, since to: already goes as far as the surface scrolls.","    Browser/Electron list scrollable regions with refs. With several regions, pass ref:<region or a control inside it>; a bare scroll refuses and lists the choices. ref:'window' explicitly scrolls the page. Reaching an edge never switches to another region.",...e.scrollsInto?["    w.scroll({into: t}) instead brings ONE control (a ref or a find() handle) to the middle of the viewport and says whether anything still covers it. It takes a covered control's ref too \u2014 the way out from under a sticky header or a bottom strip that a screen of scrolling overshoots."]:[],"    a wait polls until the condition holds or it times out, and says which: {text\u2026} searches the readable text,",'    {control\u2026} the CONTROLS by name ("until the Stop button is gone" \u2014 the honest way to wait out a long answer),',"    {url}/{url_gone} where the surface IS (substring, so a query string needs no spelling out), and {loaded:true} that","    the DOCUMENT finished. Reach for it before reporting that a page has nothing on it: a document that never finishes","    reads as an empty page and no content condition can tell you which it was. It is NOT rendered \u2014 a single-page app","    reaches loaded with nothing drawn yet (measured), so follow it with the CONTENT wait, which is w.wait({}):",'    it polls until the readable text stops changing, so it is the one "the page is ready" condition that needs no word',"    from the page and no knowledge of the site. Use it after a navigation, a tab switch inside a page, or a search \u2014 a","    single-page app mounts its rows well after {loaded}, and an observation taken before that reads as an empty page.","    Also after a click that REDRAWS content (a chart, a list) and before you screenshot or read it: the control's own state","    updates at once, the content a beat later, so a read straight after the click can pair the new button with the old view.","    Every condition takes ms as its OWN polling budget (default 16s): w.wait({text:'Done', ms:3000}) gives up in three seconds,","    give or take the one read already in flight when it runs out \u2014 on a heavy surface a single read is seconds, and the result says so when that happened.","    wait() returns true/false; awaiting it alone does NOT stop on timeout. Use expect() for a required postcondition, or check the result: if (!await w.wait({...})) throw new Error('condition not met');","    which is what a GUESS at the wording is worth \u2014 an unguarded guess that no page ever matches costs the full 16s.","  w.focus() \u2014 select w as the target for this runtime; target selection is not an OS-activation guarantee (see platform interaction notes)","  w.release() \u2014 release this target and its input resources for other sessions. Claims span calls until release, reset, turn end or process exit. Observe again before acting after handoff; old refs are invalidated. Separate windows can still share app/account/document state; ownership does not isolate those or a human editor.","  w.expect({text, control, url, value, equals, ms}) \u2014 verify exactly ONE condition; value takes a ref/find handle and equals:string. Read-only polling, default 3000 ms, maximum 16000 ms. Returns true when verified; otherwise throws before subsequent steps. It never repeats the preceding action. Use it to verify save/submit results, not screen-change verdicts.","  w.setText(t, text, {ifValue:previousValue}) \u2014 optional precondition: refuse before writing if the field changed or cannot be read. This is a checked precondition, not an atomic transaction with a human or another app.","Action journal evidence: [verified] confirms the stated value/condition; [dispatched] only confirms delivery; [blocked] means no dispatch; [uncertain] may already have acted. Never replay an uncertain send/submit/delete; inspect its actual result first."],extras:[...a.length?["  This platform's verbs \u2014 each returns what it did as text (the journal keeps only its first line, so a listing is read from the return value):","    In these signatures, ? marks an optional property; every unmarked property is required. Omit the ? in JavaScript calls.",...a.map(s=>p(s.kind,s.schema))]:[],...a.some(s=>s.kind==="select_option")?["    selectOption example: const choice = await w.find('Priority', {role:'combobox'}); if (!choice || choice.matches !== 1 || choice.incidental) throw new Error('Priority is missing or ambiguous'); await w.selectOption({ref:choice.ref, option:'High'});"]:[],...a.some(s=>s.kind==="run_js")?['    runJs is the exception: it returns the VALUE the code produced, whole (the journal shows a short preview); an exception thrown in the page comes back as the string "threw: \u2026" instead of stopping the run.']:[],...a.some(s=>s.kind==="download")?[`    download also returns a VALUE: const watch = await w.download(); await w.click(await w.find('Download')); const result = await w.download({id:watch.id}); return result; result.downloads carries the actual path, filename, host and state. Read/upload only complete receipts. Query the same ID after a timeout; several candidates mean ambiguous, never the newest file. Re-arming this tab ends its previous collection; stop:true explicitly ends collection without canceling any download. On this session's own tabs a page's save dialog (showSaveFilePicker) never opens: its file arrives as a download marked source "save-picker".`]:[]],tail:["  w.act(kind, {\u2026}) \u2014 any verb by its wire name, arguments forwarded whole; returns its text like the platform verbs","","Observation changes use + for added controls, - for removed controls, and ~ for a surviving ref whose state or label changed. Scope and grouping explanations repeat only when their context changes; observe() still returns the complete available data.","The changed/frozen verdict compares this run's end with the previous run's end: a run whose last action puts the","surface back where it started reads as unchanged \u2014 return your own intermediate observe() results when you need proof.","","Rules that are enforced, not advised:","  \xB7 one verb in flight \u2014 a second one before the first resolves is refused by name (one focus, one caret)","  \xB7 a ref read on surface A is refused on surface B \u2014 act on it through A's handle","  \xB7 a handle whose surface is gone throws: re-acquire with computer.surfaces()","  \xB7 100 actions and 60 s per call; reads, find(), waits, verification and computer.log() also spend this budget","  \xB7 nothing outside this API exists: no require, import, fetch, process, timers, console","","Persistence: top-level const/let/var/function/class declarations live until computer_repl_reset. Keep a","handle in one and reuse it; collect results in a variable across calls; return only what you need.","Batch at verified task boundaries, with room for observation and recovery. A helper's nested verbs also count: a loop of 35 find/setText/expect sequences exceeds 100 actions. Split it into smaller calls.","Keep a top-level checkpoint after each confirmed stage. After an uncertain save/submit, inspect or expect its result before resuming; replaying the whole batch can submit twice. A dispatched checkpoint is not proof of success. Reset or runtime restart loses checkpoints, so recover from surface facts then.","Returned values are capped at 12000 characters and a cut JSON value is not parseable. Read a large result once into a top-level variable, return a small slice per call, and check the final count/identity; do not re-read or replay the task to retrieve the next slice."]}}function g(e){const a=l(e);return[...a.head,...a.reads,...a.actions,...a.extras,...a.tail].join(`
+`)}function v(e){const a=l(e);return[`Reaching a second platform: ${e.platform} \u2014 everything else in the reference above still holds, and these are the reads and verbs that are its own.`,"",...a.reads,...a.extras].join(`
+`)}export{w as REPL_DESCRIPTION,m as RESET_DESCRIPTION,g as apiReference,v as platformReference};

package/dist/platform/tools/repl-state.d.ts

@@ -0,0 +1,21 @@
+import type { ComputerUseDriver } from "../driver.ts";
+import type { TargetInfo } from "../types.ts";
+export interface PlatformSlice {
+    driver: ComputerUseDriver;
+}
+export interface Slice extends PlatformSlice {
+    id: string;
+    api: Record<string, unknown>;
+    docsDue: boolean;
+    lastMiss: string | null;
+}
+export type SurfaceHandle = Record<string, unknown> & {
+    id: string;
+    kind: string;
+    title: string;
+    own?: boolean;
+};
+export type MountedTarget = TargetInfo & {
+    slice: Slice;
+    inner: string;
+};

package/dist/platform/tools/repl.d.ts

@@ -0,0 +1,8 @@
+import { type ComputerUseToolSpec } from "../types.ts";
+import { type OwnershipProvider } from "../ownership.ts";
+import type { PlatformSlice } from "./repl-state.ts";
+export type { PlatformSlice } from "./repl-state.ts";
+export declare function createReplTools(mounted: PlatformSlice[], opts?: {
+    docsDelivered?: boolean;
+    ownership?: OwnershipProvider;
+}): ComputerUseToolSpec[];