@workser/runtime 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Workser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @workser/runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The run contract every Workser runner, screen and service speaks.
+
+- **`@workser/runtime/contract`**: the run event catalog, with its checks and the resume-order rules (`OrderedFeed`), plus the types for briefs, commands, asks, handoffs, artifacts, checks and usage. core-api keeps a generated copy of the catalog and feed (`npm run sync:core-api`), so the server and every client agree on what an event is.
+- **`@workser/runtime/runner`**: `RunnerClient`, for a Workser runner driving one run from a desktop, a sandbox or a cloud computer.
+- **`@workser/runtime/client`**: `followRun` and `followProject`, for screens that watch runs live.
+- **`Place` and `Engine`**: the interfaces a runner plugs together. The *place* is where the work happens; the *engine* is the AI agent loop.
+
+It has no runtime dependencies and runs in Node 18+ and in browsers. It uses its own server-sent events (SSE) parser over `fetch`, not `EventSource`, because `EventSource` can't send a token.
+
+## Runner protocol v1
+
+1. **Attach.** Someone who can see the run calls `POST /v1/runs/:id/runner` with `{ place, lane }`. Our own services call `POST /v1/internal/runs/:id/runner` instead. The reply carries a `wsrn_` token, shown once. The token works for this one run only, and stops working when the run ends.
+2. **Brief.** `GET /v1/runner/runs/:id` returns the job and its cursors. Events are numbered from `cursors.runner_seq + 1`.
+3. **Commands.** `GET /v1/runner/runs/:id/commands` streams stop, pause, resume, answers and decisions. Reconnect with `?after=<last pos>`. On a first connect, the stream starts at the oldest command not yet acked.
+4. **Events.** `POST /v1/runner/runs/:id/events` with `{ events: [{ event_id, seq, type, data }] }`, up to 100 per call.
+   - `seq` numbers must follow each other with no gaps.
+   - Resending events that were already stored is safe.
+   - On a gap, core-api answers `409 { error: { code: 'event_gap', expected } }`. Resend from `expected`.
+5. **Heartbeat.** Send `POST …/heartbeat` about every 10 s. After three minutes of silence, core-api closes the run as `runner_lost`.
+6. **Asks and acks.**
+   - `POST …/asks` sends `{ kind: 'question' | 'permission' | 'spend', title, message, choices? }`. The owner's answer arrives as a command.
+   - Ack each command with `POST …/commands/:pos/ack` once you've acted on it.
+7. **Rotate.** For a long job, `POST …/token/rotate` returns a fresh token, and the old one stops working.
+8. **End.** Send `run.completed`, `run.failed` or `run.cancelled`. The token stops working.
+
+`RunnerClient` does steps 2–8 for you: numbering, batching (150 ms, or at once for `run.*` events), retries with backoff, resending after a gap, heartbeats, command resume and acks, and token rotation.
+
+## Example runner
+
+```ts
+import { RunnerClient } from '@workser/runtime/runner';
+
+const runner = new RunnerClient({
+  baseUrl: 'https://api.workser.ai',
+  runId: process.env.WORKSER_RUN_ID!,
+  token: process.env.WORKSER_RUNNER_TOKEN!,
+  onError: (error) => console.error(error.message),
+});
+
+const brief = await runner.start();
+let stopped = false;
+void runner.commands(async (command) => {
+  if (command.kind === 'cancel') stopped = true;
+});
+
+runner.emit('run.started', { engine: 'example', place: 'sandbox' });
+runner.emit('step.started', { step_id: 's1', title: 'Run the tests' });
+// … do the work, through a Place …
+runner.emit('step.completed', { step_id: 's1', status: 'ok' });
+runner.emit('check.result', { name: 'tests', status: 'pass' });
+
+if (stopped) await runner.finish('run.cancelled', { reason: 'Stopped by the owner' });
+else await runner.finish('run.completed', { summary: `Did: ${String(brief.run.input.task ?? 'the job')}` });
+```
+
+## Watching a run
+
+```ts
+import { followRun } from '@workser/runtime/client';
+
+for await (const event of followRun({ baseUrl, runId, headers: { Authorization: `Bearer ${key}` } })) {
+  render(event); // in order, once each; resumes after the last position on every reconnect
+}
+```
+
+## Working on this package
+
+- `npm test`: runs the tests with Node's test runner, with no network.
+- `npm run sync:core-api`: rewrites core-api's generated copies after any change to `src/contract/catalog.ts` or `src/contract/ordered-feed.ts`. A test fails when the copies drift.
+# workser-runtime-sdk

package/dist/cjs/client/follow.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.followRun = followRun;
+exports.followProject = followProject;
+const catalog_js_1 = require("../contract/catalog.js");
+const async_queue_js_1 = require("../internal/async-queue.js");
+const sse_js_1 = require("../internal/sse.js");
+/**
+ * One run's events, in order, once each, surviving drops: every reconnect
+ * resumes after the last position seen, and anything at or before it is
+ * dropped. Ends after the run's terminal event.
+ *
+ *   for await (const event of followRun({ baseUrl, runId, headers })) { … }
+ */
+function followRun(options) {
+    const base = options.baseUrl.replace(/\/+$/, '');
+    const abort = new AbortController();
+    options.signal?.addEventListener('abort', () => abort.abort(), { once: true });
+    const queue = new async_queue_js_1.AsyncQueue(() => abort.abort());
+    let last = Math.max(0, options.after ?? 0);
+    const url = options.url ??
+        ((after) => `${base}/v1/runs/${encodeURIComponent(options.runId)}/events${after > 0 ? `?after=${after}` : '?after=0'}`);
+    void (0, sse_js_1.connectSse)({
+        fetch: options.fetch ?? ((input, init) => fetch(input, init)),
+        signal: abort.signal,
+        url: () => url(last),
+        headers: () => options.headers ?? {},
+        onMessage: (message) => {
+            if (message.event === 'heartbeat')
+                return;
+            let frame;
+            try {
+                frame = JSON.parse(message.data);
+            }
+            catch {
+                return;
+            }
+            if (typeof frame.pos !== 'number' || frame.pos <= last)
+                return;
+            last = frame.pos;
+            queue.push(frame);
+            if (catalog_js_1.TERMINAL_EVENT_TYPES.has(frame.type)) {
+                queue.end();
+                abort.abort();
+            }
+        },
+        onError: (error) => {
+            options.onError?.(error);
+        },
+    }).then(() => queue.end(), (error) => queue.end(error));
+    return queue;
+}
+/**
+ * A project's runs, live: a `snapshot` on every (re)connect, then
+ * `summary` items. A summary at or before the position its run already
+ * showed is dropped, so a reconnect never repeats one.
+ */
+function followProject(options) {
+    const base = options.baseUrl.replace(/\/+$/, '');
+    const abort = new AbortController();
+    options.signal?.addEventListener('abort', () => abort.abort(), { once: true });
+    const queue = new async_queue_js_1.AsyncQueue(() => abort.abort());
+    const seen = new Map();
+    void (0, sse_js_1.connectSse)({
+        fetch: options.fetch ?? ((input, init) => fetch(input, init)),
+        signal: abort.signal,
+        url: options.url ??
+            (() => `${base}/v1/projects/${encodeURIComponent(options.projectId)}/runs/stream`),
+        headers: () => options.headers ?? {},
+        onMessage: (message) => {
+            if (message.event === 'heartbeat')
+                return;
+            let data;
+            try {
+                data = JSON.parse(message.data);
+            }
+            catch {
+                return;
+            }
+            if (message.event === 'snapshot') {
+                const snapshot = data;
+                for (const run of snapshot.runs ?? []) {
+                    seen.set(run.id, Math.max(seen.get(run.id) ?? 0, Number(run.event_pos) || 0));
+                }
+                queue.push({ type: 'snapshot', snapshot });
+                return;
+            }
+            if (message.event === 'run.summary') {
+                const summary = data;
+                if (typeof summary.pos !== 'number')
+                    return;
+                if (summary.pos <= (seen.get(summary.run_id) ?? 0))
+                    return;
+                seen.set(summary.run_id, summary.pos);
+                queue.push({ type: 'summary', summary });
+            }
+        },
+        onError: (error) => {
+            options.onError?.(error);
+        },
+    }).then(() => queue.end(), (error) => queue.end(error));
+    return queue;
+}

package/dist/cjs/client/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.followProject = exports.followRun = void 0;
+var follow_js_1 = require("./follow.js");
+Object.defineProperty(exports, "followRun", { enumerable: true, get: function () { return follow_js_1.followRun; } });
+Object.defineProperty(exports, "followProject", { enumerable: true, get: function () { return follow_js_1.followProject; } });

package/dist/cjs/contract/actions.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPUTER_TOOL_ALIASES = exports.COMPUTER_ACTION_IDS = exports.COMPUTER_ACTIONS = exports.ACTION_PLACES = void 0;
+exports.computerToolName = computerToolName;
+exports.resolveComputerTool = resolveComputerTool;
+exports.normalizeActionInput = normalizeActionInput;
+exports.runsWithoutOwnerScreen = runsWithoutOwnerScreen;
+exports.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'];
+exports.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 } }),
+    },
+};
+exports.COMPUTER_ACTION_IDS = Object.keys(exports.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`. */
+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`. */
+exports.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(exports.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).
+ */
+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 = exports.COMPUTER_TOOL_ALIASES[name];
+    if (alias)
+        return { ...alias, alias: true };
+    for (const place of exports.ACTION_PLACES) {
+        const prefix = `${PREFIX[place]}_`;
+        if (name.startsWith(prefix)) {
+            const action = name.slice(prefix.length);
+            if (isAction(action) && exports.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.
+ */
+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.
+ */
+function runsWithoutOwnerScreen(action, place) {
+    if (place !== 'desktop')
+        return true;
+    return exports.COMPUTER_ACTIONS[action].background;
+}