@workser/runtime 0.0.0-stage → 0.1.0

package/dist/contract/actions.d.ts

@@ -0,0 +1,73 @@
+/**
+ * COMPUTER ACTIONS — one list for every place an AI agent works a computer
+ * (workforce standardization phase 5): the owner's own computer (`desktop`),
+ * the project's cloud computer and the cloud browser.
+ *
+ * Each action has one id, one argument schema, and says:
+ *   - which places can do it,
+ *   - whether it changes anything (the owner may be asked first),
+ *   - whether the owner's computer can do it behind their windows, without
+ *     taking their screen. Jev decides background or screen; this only says
+ *     what is possible. Background is preferred so the person keeps their
+ *     screen.
+ *
+ * Actions are general: no per-app recipes. Jev finds an app's specifics on
+ * screen.
+ *
+ * A tool a model calls is named by place and action, `<prefix>_<action>`
+ * (`computer_click_at`, `browser_open_url`, `desktop_type`), so one run that
+ * holds both a cloud computer and a cloud browser never has two tools of the
+ * same name. Every older name (the desktop planner's steps, the local
+ * runner's `desktop_action`, the cloud computer's and both cloud browser
+ * tool sets, Jev's operations) is an alias: `resolveComputerTool` reads any
+ * of them.
+ */
+import type { RunPlace } from './types.js';
+/** The places that work a computer. */
+export type ActionPlace = Extract<RunPlace, 'desktop' | 'cloud_computer' | 'cloud_browser'>;
+export declare const ACTION_PLACES: readonly ActionPlace[];
+export type ComputerActionId = 'open_app' | 'open_url' | 'click' | 'click_at' | 'type' | 'set_value' | 'press' | 'scroll' | 'select' | 'hover' | 'drag' | 'menu' | 'look' | 'read' | 'wait' | 'wait_for' | 'clipboard_read' | 'clipboard_write' | 'fill_secret' | 'record_clip';
+export interface ComputerAction {
+    id: ComputerActionId;
+    description: string;
+    places: readonly ActionPlace[];
+    /** Changes something (types, clicks, opens): approval rules may apply. */
+    side_effect: boolean;
+    /** The owner's computer can do it behind their windows, without their screen. */
+    background: boolean;
+    /** JSON Schema for the arguments. */
+    input_schema: Record<string, unknown>;
+}
+export declare const COMPUTER_ACTIONS: Readonly<Record<ComputerActionId, ComputerAction>>;
+export declare const COMPUTER_ACTION_IDS: ComputerActionId[];
+/** The tool name a model calls: `computer_click_at`, `browser_open_url`, `desktop_type`. */
+export declare function computerToolName(place: ActionPlace, action: ComputerActionId): string;
+/** Older names, read as an action at a place. A bare desktop planner step name is read in `resolveComputerTool`. */
+export declare const COMPUTER_TOOL_ALIASES: Readonly<Record<string, {
+    place: ActionPlace | null;
+    action: ComputerActionId;
+}>>;
+export interface ResolvedComputerTool {
+    /** null: a name with no place (a Jev operation, or a bare action id). */
+    place: ActionPlace | null;
+    action: ComputerActionId;
+    /** The name was an older one. */
+    alias: boolean;
+}
+/**
+ * Any name a computer action has gone by, read as one action. `input` is
+ * needed only for the local runner's `desktop_action`, which names the
+ * action in its arguments. Null: not a computer action (files, shell, apps).
+ */
+export declare function resolveComputerTool(name: string, input?: Record<string, unknown> | null): ResolvedComputerTool | null;
+/**
+ * Arguments in the list's shape, from any older shape: keys as a string
+ * ("cmd+s") or array, Jev's SCROLL_UP/SCROLL_DOWN, `element`/`selector` for
+ * the target, `application`/`uri` for an app.
+ */
+export declare function normalizeActionInput(action: ComputerActionId, input: Record<string, unknown> | null | undefined, name?: string): Record<string, unknown>;
+/**
+ * Whether this action can run without the owner's screen at this place. The
+ * cloud computer and the cloud browser are never the owner's screen.
+ */
+export declare function runsWithoutOwnerScreen(action: ComputerActionId, place: ActionPlace): boolean;

package/dist/contract/actions.js

@@ -0,0 +1,217 @@
+export const ACTION_PLACES = ['desktop', 'cloud_computer', 'cloud_browser'];
+const obj = (properties, required = []) => ({
+    type: 'object',
+    properties,
+    ...(required.length ? { required } : {}),
+    additionalProperties: false,
+});
+const str = (description) => ({ type: 'string', description });
+const num = (description) => ({ type: 'number', description });
+/** What to act on: an element id from the last look/read, or its words. */
+const TARGET = str('The element to act on: its id from the last look or read, or its visible label');
+const APP = str('The app it is in (the owner\'s computer); omit for the front window');
+const ALL = ['desktop', 'cloud_computer', 'cloud_browser'];
+export const COMPUTER_ACTIONS = {
+    open_app: {
+        id: 'open_app', description: 'Open an app, or bring it forward.', places: ['desktop', 'cloud_computer'],
+        side_effect: true, background: true, input_schema: obj({ app: str('The app\'s name'), target: str('A file or address to open in it') }, ['app']),
+    },
+    open_url: {
+        id: 'open_url', description: 'Open a web address.', places: ALL,
+        side_effect: true, background: true, input_schema: obj({ url: str('The address') }, ['url']),
+    },
+    click: {
+        id: 'click', description: 'Click an element.', places: ['desktop', 'cloud_browser'],
+        side_effect: true, background: true, input_schema: obj({ target: TARGET, app: APP, double: { type: 'boolean' }, right: { type: 'boolean' } }, ['target']),
+    },
+    click_at: {
+        id: 'click_at', description: 'Click a point on the screen.', places: ['desktop', 'cloud_computer'],
+        // A point is on the screen: behind the owner's windows it has no meaning.
+        side_effect: true, background: false, input_schema: obj({ x: num('Pixels from the left'), y: num('Pixels from the top'), double: { type: 'boolean' } }, ['x', 'y']),
+    },
+    type: {
+        id: 'type', description: 'Type text, into an element or where the cursor is.', places: ALL,
+        side_effect: true, background: true, input_schema: obj({ text: str('What to type'), target: TARGET, app: APP, submit: { type: 'boolean', description: 'Press Enter after' } }, ['text']),
+    },
+    set_value: {
+        id: 'set_value', description: 'Set a field\'s value directly.', places: ['desktop', 'cloud_browser'],
+        side_effect: true, background: true, input_schema: obj({ target: TARGET, value: str('The value'), app: APP }, ['target', 'value']),
+    },
+    press: {
+        id: 'press', description: 'Press keys together, like ["cmd", "s"].', places: ALL,
+        side_effect: true, background: true, input_schema: obj({ keys: { type: 'array', items: { type: 'string' }, minItems: 1 }, app: APP }, ['keys']),
+    },
+    scroll: {
+        id: 'scroll', description: 'Scroll a window or element.', places: ALL,
+        side_effect: false, background: true,
+        input_schema: obj({ direction: { type: 'string', enum: ['up', 'down', 'left', 'right'] }, amount: { type: 'number', minimum: 1, maximum: 20 }, target: TARGET, app: APP }, ['direction']),
+    },
+    select: {
+        id: 'select', description: 'Choose an option in a list.', places: ['desktop', 'cloud_browser'],
+        side_effect: true, background: true, input_schema: obj({ target: TARGET, value: str('The option'), app: APP }, ['target', 'value']),
+    },
+    hover: {
+        id: 'hover', description: 'Point at an element without clicking.', places: ['desktop'],
+        side_effect: false, background: true, input_schema: obj({ target: TARGET, app: APP }, ['target']),
+    },
+    drag: {
+        id: 'drag', description: 'Drag from one element or point to another.', places: ['desktop'],
+        side_effect: true, background: true, input_schema: obj({ from: TARGET, to: TARGET, app: APP }, ['from', 'to']),
+    },
+    menu: {
+        id: 'menu', description: 'Choose a menu item by its path, like ["File", "Export…"].', places: ['desktop'],
+        side_effect: true, background: true, input_schema: obj({ path: { type: 'array', items: { type: 'string' }, minItems: 1 }, app: APP }, ['path']),
+    },
+    look: {
+        id: 'look', description: 'See the screen or one window (a picture).', places: ALL,
+        side_effect: false, background: true, input_schema: obj({ app: APP, window: str('Which window') }),
+    },
+    read: {
+        id: 'read', description: 'Read a window\'s or page\'s text and elements.', places: ALL,
+        side_effect: false, background: true, input_schema: obj({ app: APP, target: TARGET }),
+    },
+    wait: {
+        id: 'wait', description: 'Wait a few seconds.', places: ALL,
+        side_effect: false, background: true, input_schema: obj({ seconds: { type: 'number', minimum: 0, maximum: 60 } }, ['seconds']),
+    },
+    wait_for: {
+        id: 'wait_for', description: 'Wait until something shows up.', places: ['desktop', 'cloud_browser'],
+        side_effect: false, background: true, input_schema: obj({ text: str('Words to wait for'), target: TARGET, seconds: { type: 'number', minimum: 1, maximum: 120 } }),
+    },
+    clipboard_read: {
+        id: 'clipboard_read', description: 'Read the clipboard.', places: ['desktop'],
+        // The clipboard is the owner's: there is only one, shared with them.
+        side_effect: false, background: false, input_schema: obj({}),
+    },
+    clipboard_write: {
+        id: 'clipboard_write', description: 'Put text on the clipboard.', places: ['desktop'],
+        side_effect: true, background: false, input_schema: obj({ text: str('The text') }, ['text']),
+    },
+    fill_secret: {
+        id: 'fill_secret', description: 'Type a saved sign-in into the focused field, without seeing it.', places: ['cloud_computer', 'cloud_browser'],
+        side_effect: true, background: true,
+        input_schema: obj({ name: str('The saved sign-in'), field: { type: 'string', enum: ['username', 'password', 'totp', 'value'] } }, ['name', 'field']),
+    },
+    record_clip: {
+        id: 'record_clip', description: 'Record a short clip of the screen.', places: ['desktop', 'cloud_computer'],
+        side_effect: false, background: false, input_schema: obj({ seconds: { type: 'number', minimum: 1, maximum: 120 } }),
+    },
+};
+export const COMPUTER_ACTION_IDS = Object.keys(COMPUTER_ACTIONS);
+const PREFIX = { desktop: 'desktop', cloud_computer: 'computer', cloud_browser: 'browser' };
+/** The tool name a model calls: `computer_click_at`, `browser_open_url`, `desktop_type`. */
+export function computerToolName(place, action) {
+    return `${PREFIX[place]}_${action}`;
+}
+/** Older names, read as an action at a place. A bare desktop planner step name is read in `resolveComputerTool`. */
+export const COMPUTER_TOOL_ALIASES = {
+    // The cloud computer's names before the list.
+    computer_open: { place: 'cloud_computer', action: 'open_app' },
+    computer_click: { place: 'cloud_computer', action: 'click_at' },
+    computer_screenshot: { place: 'cloud_computer', action: 'look' },
+    computer_observe_ax: { place: 'cloud_computer', action: 'read' },
+    // The cloud browser (both tool sets).
+    browser_open: { place: 'cloud_browser', action: 'open_url' },
+    browser_navigate: { place: 'cloud_browser', action: 'open_url' },
+    browser_screenshot: { place: 'cloud_browser', action: 'look' },
+    browser_get_content: { place: 'cloud_browser', action: 'read' },
+    browser_press_keys: { place: 'cloud_browser', action: 'press' },
+    browser_fill_form: { place: 'cloud_browser', action: 'set_value' },
+    fill_login: { place: 'cloud_browser', action: 'fill_secret' },
+    // The desktop: planner steps that are another action's twin, and the local runner.
+    look_window: { place: 'desktop', action: 'look' },
+    record_session: { place: 'desktop', action: 'record_clip' },
+    desktop_see: { place: 'desktop', action: 'look' },
+    // Jev's operations (any place).
+    CLICK: { place: null, action: 'click' },
+    TYPE_TEXT: { place: null, action: 'type' },
+    SELECT: { place: null, action: 'select' },
+    KEY_PRESS: { place: null, action: 'press' },
+    SCROLL_DOWN: { place: null, action: 'scroll' },
+    SCROLL_UP: { place: null, action: 'scroll' },
+    NAVIGATE: { place: null, action: 'open_url' },
+    OPEN_APP: { place: null, action: 'open_app' },
+    WAIT: { place: null, action: 'wait' },
+};
+const isAction = (value) => typeof value === 'string' && Object.prototype.hasOwnProperty.call(COMPUTER_ACTIONS, value);
+/**
+ * Any name a computer action has gone by, read as one action. `input` is
+ * needed only for the local runner's `desktop_action`, which names the
+ * action in its arguments. Null: not a computer action (files, shell, apps).
+ */
+export function resolveComputerTool(name, input) {
+    if (typeof name !== 'string' || !name)
+        return null;
+    if (name === 'desktop_action') {
+        const action = input?.action;
+        return isAction(action) ? { place: 'desktop', action, alias: true } : null;
+    }
+    const alias = COMPUTER_TOOL_ALIASES[name];
+    if (alias)
+        return { ...alias, alias: true };
+    for (const place of ACTION_PLACES) {
+        const prefix = `${PREFIX[place]}_`;
+        if (name.startsWith(prefix)) {
+            const action = name.slice(prefix.length);
+            if (isAction(action) && COMPUTER_ACTIONS[action].places.includes(place))
+                return { place, action, alias: false };
+        }
+    }
+    // A bare id: the desktop planner's own step names are the action ids.
+    if (isAction(name))
+        return { place: null, action: name, alias: false };
+    return null;
+}
+/**
+ * Arguments in the list's shape, from any older shape: keys as a string
+ * ("cmd+s") or array, Jev's SCROLL_UP/SCROLL_DOWN, `element`/`selector` for
+ * the target, `application`/`uri` for an app.
+ */
+export function normalizeActionInput(action, input, name) {
+    const out = { ...(input ?? {}) };
+    if (action === 'press' && out.keys !== undefined) {
+        const keys = out.keys;
+        out.keys = Array.isArray(keys)
+            ? keys.map(String)
+            : String(keys).split('+').map((one) => one.trim()).filter(Boolean);
+    }
+    if (action === 'scroll' && out.direction === undefined) {
+        if (name === 'SCROLL_UP')
+            out.direction = 'up';
+        if (name === 'SCROLL_DOWN')
+            out.direction = 'down';
+    }
+    if (out.target === undefined) {
+        const element = out.element ?? out.selector;
+        if (element !== undefined) {
+            out.target = String(element);
+            delete out.element;
+            delete out.selector;
+        }
+    }
+    if (action === 'open_app') {
+        if (out.app === undefined && out.application !== undefined) {
+            out.app = out.application;
+            delete out.application;
+        }
+        if (out.target === undefined && out.uri !== undefined) {
+            out.target = out.uri;
+            delete out.uri;
+        }
+    }
+    if (action === 'open_url' && out.url === undefined && typeof out.target === 'string') {
+        out.url = out.target;
+        delete out.target;
+    }
+    return out;
+}
+/**
+ * Whether this action can run without the owner's screen at this place. The
+ * cloud computer and the cloud browser are never the owner's screen.
+ */
+export function runsWithoutOwnerScreen(action, place) {
+    if (place !== 'desktop')
+        return true;
+    return COMPUTER_ACTIONS[action].background;
+}
+//# sourceMappingURL=actions.js.map

package/dist/contract/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../src/contract/actions.ts"],"names":[],"mappings":"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"}

package/dist/contract/catalog.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The run event catalog: every event a runner may send, and what it must
+ * carry. Pure and dependency-free: this file is the source of truth in
+ * `@workser/runtime`, and core-api keeps a generated copy of it (plan Phase 0).
+ *
+ * TWO GATES, ON PURPOSE
+ * ---------------------
+ * - A runner (`v1/runner/runs/:id/events`) is strict: an unknown type or a
+ *   malformed payload is refused, so a screen never has to guess what an event
+ *   means.
+ * - The service engine (`internal/runs/:id/events`) is lenient: it already
+ *   sends ~30 types, some built at runtime, and refusing one would lose a live
+ *   run's history. Unknown types are accepted and counted (`unknownLegacyType`)
+ *   so the catalog can grow to cover them before that gate tightens.
+ */
+export declare const RUNNER_PROTOCOL_VERSION = 1;
+/** Largest event payload we keep, serialised. Bigger outputs go to files. */
+export declare const MAX_EVENT_DATA_BYTES: number;
+/** Largest batch a runner may send in one call. */
+export declare const MAX_EVENT_BATCH = 100;
+type FieldType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+interface FieldRule {
+    type: FieldType;
+    required?: boolean;
+    oneOf?: readonly string[];
+    maxLength?: number;
+}
+type Shape = Record<string, FieldRule>;
+/**
+ * What each event means, for the people reading it on a screen:
+ *
+ * - run.*        the run's life. Terminal ones end the stream.
+ * - step.*       one thing the agent did (a command, an edit, a tool call).
+ * - message*     what the agent said; `.delta` streams it as it is written.
+ * - file/diff    what changed on disk.
+ * - check.result a done-check (tests, typecheck, deck validates, numbers match).
+ * - preview.ready a URL the owner can open.
+ * - handoff.*    a sub-job this run asked for started or ended (core-api
+ *                writes these on the parent; `run.completed.result` is the
+ *                child's typed answer).
+ * - usage        tokens and cost as the runner saw them; billing uses the
+ *                gateway's own figure, never this one.
+ * - log          plain lines for the details view.
+ */
+export declare const RUN_EVENT_CATALOG: Readonly<Record<string, Shape>>;
+/** Events that end a run. The stream closes after it delivers one. */
+export declare const TERMINAL_EVENT_TYPES: ReadonlySet<string>;
+/**
+ * Types the service engine sends today that aren't runner events. Accepted on
+ * the lenient gate without being counted as unknown.
+ */
+export declare const LEGACY_EVENT_TYPES: ReadonlySet<string>;
+export interface RunnerEventInput {
+    event_id: string;
+    seq: number;
+    type: string;
+    data?: unknown;
+}
+/** `reason` is set when `ok` is false. (One shape: the repo builds without strictNullChecks, where a union wouldn't narrow.) */
+export interface EventCheck {
+    ok: boolean;
+    reason?: string;
+}
+/** Is this a well-formed runner event? The strict gate. */
+export declare function checkRunnerEvent(event: RunnerEventInput): EventCheck;
+/** The lenient gate: only the envelope is checked. */
+export declare function checkLegacyEvent(event: {
+    event_id?: unknown;
+    event_type?: unknown;
+    seq?: unknown;
+}): EventCheck;
+/** A type neither in the catalog nor in the known legacy list. */
+export declare function unknownLegacyType(type: string): boolean;
+/**
+ * The run status a runner event moves the run to, or null when it doesn't.
+ * Status only moves forward: a terminal run never changes again.
+ */
+export declare function statusForRunnerEvent(type: string): 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | null;
+/** When `ok`: `fresh` and `nextCursor`. When not: `expected` and `reason`. */
+export interface BatchSeqCheck {
+    ok: boolean;
+    fresh?: RunnerEventInput[];
+    nextCursor?: number;
+    expected?: number;
+    reason?: string;
+}
+/**
+ * Check a runner batch against the run's cursor (the last seq accepted).
+ *
+ * Events at or below the cursor are retries and are dropped here — their
+ * `event_id` is checked against the stored row by the caller. What remains
+ * must continue the cursor exactly: `cursor+1, cursor+2, …`. A gap means the
+ * runner lost an event, and it is told where to resend from rather than
+ * having the hole papered over.
+ */
+export declare function checkBatchSeq(cursor: number, events: RunnerEventInput[]): BatchSeqCheck;
+export {};