@workser/runtime 0.0.0-stage → 0.1.0

package/dist/cjs/contract/catalog.js

@@ -0,0 +1,335 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGACY_EVENT_TYPES = exports.TERMINAL_EVENT_TYPES = exports.RUN_EVENT_CATALOG = exports.MAX_EVENT_BATCH = exports.MAX_EVENT_DATA_BYTES = exports.RUNNER_PROTOCOL_VERSION = void 0;
+exports.checkRunnerEvent = checkRunnerEvent;
+exports.checkLegacyEvent = checkLegacyEvent;
+exports.unknownLegacyType = unknownLegacyType;
+exports.statusForRunnerEvent = statusForRunnerEvent;
+exports.checkBatchSeq = checkBatchSeq;
+exports.RUNNER_PROTOCOL_VERSION = 1;
+/** Largest event payload we keep, serialised. Bigger outputs go to files. */
+exports.MAX_EVENT_DATA_BYTES = 64 * 1024;
+/** Largest batch a runner may send in one call. */
+exports.MAX_EVENT_BATCH = 100;
+const text = (maxLength = 20_000, required = true) => ({
+    type: 'string',
+    required,
+    maxLength,
+});
+const id = (required = true) => text(120, required);
+/**
+ * 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.
+ */
+exports.RUN_EVENT_CATALOG = {
+    'run.started': { engine: text(80, false), place: text(40, false) },
+    'run.paused': { reason: text(500, false) },
+    'run.resumed': {},
+    // `result`: the typed answer a handoff's parent asked for (`Handoff.expected`).
+    'run.completed': { summary: text(20_000, false), result: { type: 'object' } },
+    'run.failed': { error_kind: text(80, false), message: text(4_000, false) },
+    'run.cancelled': { reason: text(500, false) },
+    // A person stopped the job before it read some messages sent into it (its
+    // unacked `message` commands). Core writes it on Stop; nothing new starts.
+    // `messages`: [{ pos, text (≤500 chars), author (name or null) }], oldest first.
+    'run.messages_unseen': {
+        count: { type: 'number', required: true },
+        messages: { type: 'array', required: true },
+    },
+    // A session-mode job finished a turn and is waiting for the next message.
+    'run.idle': { summary: text(20_000, false), turn: { type: 'number' } },
+    // A reply turned into a job (reply-or-job contract §2c): the AI agent called
+    // `begin_job`, or the safety net saw an action, a computer, a fan-out, a
+    // helper or a long run. Core makes it a job once (migration 300).
+    'run.became_job': {
+        reason: { type: 'string', required: true, oneOf: ['begin_job', 'action', 'computer', 'fan_out', 'long', 'helper', 'owner'] },
+        title: text(500, false),
+        eta: text(200, false),
+    },
+    // The engine's own session, so a later runner can reattach to it
+    // (core-api puts the latest into the brief as `run.resume`).
+    'engine.session': { engine: text(80), session_id: text(200), workdir: text(1_000) },
+    // The agent is waiting on a person (`owner`) or on an approval it raised.
+    // `run.resumed` says it carried on.
+    'run.waiting': {
+        on: { type: 'string', required: true, oneOf: ['owner', 'approval'] },
+        ask_id: id(false),
+    },
+    'step.started': {
+        step_id: id(),
+        title: text(500),
+        tool: text(120, false),
+        input: { type: 'object' },
+        // The sub-job this step handed work to, and the step it is nested under.
+        child_run_id: id(false),
+        parent_step_id: id(false),
+    },
+    // Live output of a long step. Throttle to about one a second per step.
+    'step.progress': {
+        step_id: id(),
+        text: text(2_000, false),
+        pct: { type: 'number' },
+        stdout_tail: text(2_000, false),
+    },
+    // The agent's to-do list changed (`write_todos`): the whole list, every time.
+    'plan.updated': {
+        todos: { type: 'array', required: true },
+    },
+    'step.completed': {
+        step_id: id(),
+        status: { type: 'string', required: true, oneOf: ['ok', 'error', 'skipped'] },
+        output: { type: 'object' },
+        error: text(4_000, false),
+        duration_ms: { type: 'number' },
+    },
+    message: {
+        message_id: id(false),
+        role: {
+            type: 'string',
+            required: true,
+            oneOf: ['assistant', 'user', 'system'],
+        },
+        text: text(),
+    },
+    'message.delta': { message_id: id(), text: text() },
+    'file.changed': {
+        path: text(1_000),
+        change: {
+            type: 'string',
+            required: true,
+            oneOf: ['added', 'modified', 'deleted', 'renamed'],
+        },
+    },
+    'diff.ready': {
+        files: { type: 'number', required: true },
+        additions: { type: 'number' },
+        deletions: { type: 'number' },
+    },
+    'check.result': {
+        name: text(200),
+        status: {
+            type: 'string',
+            required: true,
+            oneOf: ['pass', 'fail', 'skip'],
+        },
+        detail: text(8_000, false),
+    },
+    'preview.ready': { url: text(2_000) },
+    // Written by core-api on the PARENT when a handoff starts and ends.
+    'handoff.created': { child_run_id: id(), goal: text(2_000, false) },
+    'handoff.finished': {
+        child_run_id: id(),
+        status: {
+            type: 'string',
+            required: true,
+            oneOf: ['completed', 'failed', 'cancelled'],
+        },
+    },
+    usage: {
+        model: text(200, false),
+        tokens_in: { type: 'number' },
+        tokens_out: { type: 'number' },
+        cost_usd: { type: 'number' },
+    },
+    log: {
+        level: {
+            type: 'string',
+            required: true,
+            oneOf: ['debug', 'info', 'warn', 'error'],
+        },
+        text: text(),
+    },
+};
+/** Events that end a run. The stream closes after it delivers one. */
+exports.TERMINAL_EVENT_TYPES = new Set([
+    'run.completed',
+    'run.failed',
+    'run.cancelled',
+]);
+/**
+ * Types the service engine sends today that aren't runner events. Accepted on
+ * the lenient gate without being counted as unknown.
+ */
+exports.LEGACY_EVENT_TYPES = new Set([
+    'browser.live',
+    'composio.authorization',
+    'computer.busy',
+    'computer.ready',
+    'computer.requested',
+    'computer.viewer.available',
+    'computer.viewer.unavailable',
+    'connector.execution.receipt',
+    'run.capabilities_attached',
+    'run.inference_overridden',
+    'run.limit_reached',
+    'run.llm_call',
+    'run.model_fallback',
+    'run.running',
+    'run.starting',
+    'run.tool_call',
+    'run.tool_refused',
+    'run.training_loaded',
+    'setup.change',
+    'ui.card',
+    'workser_computer.conversation.gate',
+    'workser_computer.route.selected',
+]);
+/** Is this a well-formed runner event? The strict gate. */
+function checkRunnerEvent(event) {
+    if (!event || typeof event !== 'object') {
+        return { ok: false, reason: 'An event must be an object.' };
+    }
+    if (typeof event.event_id !== 'string' || !event.event_id || event.event_id.length > 40) {
+        return { ok: false, reason: 'event_id must be a string of 1–40 characters.' };
+    }
+    if (!Number.isInteger(event.seq) || event.seq < 1) {
+        return { ok: false, reason: 'seq must be a positive whole number.' };
+    }
+    const shape = exports.RUN_EVENT_CATALOG[event.type];
+    if (!shape) {
+        return { ok: false, reason: `Unknown event type "${String(event.type)}".` };
+    }
+    const data = event.data ?? {};
+    if (typeof data !== 'object' || Array.isArray(data) || data === null) {
+        return { ok: false, reason: `${event.type}: data must be an object.` };
+    }
+    const size = byteLength(data);
+    if (size > exports.MAX_EVENT_DATA_BYTES) {
+        return {
+            ok: false,
+            reason: `${event.type}: data is ${size} bytes; the limit is ${exports.MAX_EVENT_DATA_BYTES}. Put large output in a file.`,
+        };
+    }
+    for (const [field, rule] of Object.entries(shape)) {
+        const value = data[field];
+        if (value === undefined || value === null) {
+            if (rule.required) {
+                return { ok: false, reason: `${event.type}: "${field}" is required.` };
+            }
+            continue;
+        }
+        const actual = Array.isArray(value) ? 'array' : typeof value;
+        if (actual !== rule.type) {
+            return {
+                ok: false,
+                reason: `${event.type}: "${field}" must be ${rule.type}, got ${actual}.`,
+            };
+        }
+        if (rule.type === 'number' && !Number.isFinite(value)) {
+            return { ok: false, reason: `${event.type}: "${field}" must be finite.` };
+        }
+        if (rule.oneOf && !rule.oneOf.includes(value)) {
+            return {
+                ok: false,
+                reason: `${event.type}: "${field}" must be one of ${rule.oneOf.join(', ')}.`,
+            };
+        }
+        if (rule.maxLength && value.length > rule.maxLength) {
+            return {
+                ok: false,
+                reason: `${event.type}: "${field}" is longer than ${rule.maxLength} characters.`,
+            };
+        }
+    }
+    return { ok: true };
+}
+/** The lenient gate: only the envelope is checked. */
+function checkLegacyEvent(event) {
+    if (typeof event.event_type !== 'string' || !event.event_type || event.event_type.length > 80) {
+        return { ok: false, reason: 'event_type must be a string of 1–80 characters.' };
+    }
+    if (typeof event.event_id !== 'string' || !event.event_id || event.event_id.length > 40) {
+        return { ok: false, reason: 'event_id must be a string of 1–40 characters.' };
+    }
+    if (!Number.isInteger(event.seq)) {
+        return { ok: false, reason: 'seq must be a whole number.' };
+    }
+    return { ok: true };
+}
+/** A type neither in the catalog nor in the known legacy list. */
+function unknownLegacyType(type) {
+    return !exports.RUN_EVENT_CATALOG[type] && !exports.LEGACY_EVENT_TYPES.has(type);
+}
+/**
+ * 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.
+ */
+function statusForRunnerEvent(type) {
+    switch (type) {
+        case 'run.started':
+        case 'run.resumed':
+            return 'RUNNING';
+        case 'run.completed':
+            return 'COMPLETED';
+        case 'run.failed':
+            return 'FAILED';
+        case 'run.cancelled':
+            return 'CANCELLED';
+        default:
+            return null;
+    }
+}
+/**
+ * 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.
+ */
+function checkBatchSeq(cursor, events) {
+    const sorted = [...events].sort((a, b) => a.seq - b.seq);
+    const fresh = sorted.filter((one) => one.seq > cursor);
+    let expected = cursor + 1;
+    for (const one of fresh) {
+        if (one.seq !== expected) {
+            return {
+                ok: false,
+                expected,
+                reason: one.seq < expected
+                    ? `seq ${one.seq} appears twice in this batch.`
+                    : `seq ${one.seq} skips ahead; expected ${expected}. Resend from ${expected}.`,
+            };
+        }
+        expected += 1;
+    }
+    return { ok: true, fresh, nextCursor: expected - 1 };
+}
+// TextEncoder, not Buffer: the same file runs in browsers and in core-api.
+const encoder = new TextEncoder();
+function byteLength(value) {
+    try {
+        return encoder.encode(JSON.stringify(value)).length;
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}

package/dist/cjs/contract/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./catalog.js"), exports);
+__exportStar(require("./ordered-feed.js"), exports);
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./actions.js"), exports);

package/dist/cjs/contract/ordered-feed.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrderedFeed = exports.FEED_PAGE = void 0;
+exports.FEED_PAGE = 500;
+class OrderedFeed {
+    fetchAfter;
+    emit;
+    onError;
+    last;
+    chain = Promise.resolve();
+    closed = false;
+    constructor(start, fetchAfter, emit, onError = () => undefined) {
+        this.fetchAfter = fetchAfter;
+        this.emit = emit;
+        this.onError = onError;
+        this.last = Math.max(0, Math.floor(start || 0));
+    }
+    /** The position of the last row emitted. */
+    get cursor() {
+        return this.last;
+    }
+    /**
+     * Replay everything after the start cursor. Call once, right after creating.
+     *
+     * `show`, when given, hides replayed rows it rejects while still moving the
+     * cursor past them — for the old `after_seq` resume, which skipped rows by
+     * the writer's own number. Live rows are never filtered.
+     */
+    start(show) {
+        return this.enqueue(() => this.drain(undefined, show));
+    }
+    /** A live row. Emitted in order; a skip ahead reads the gap first. */
+    offer(row) {
+        return this.enqueue(async () => {
+            const pos = row.pos;
+            if (pos == null || pos <= this.last)
+                return;
+            if (pos > this.last + 1) {
+                await this.drain(pos);
+                if (pos <= this.last)
+                    return;
+            }
+            this.push(row);
+        });
+    }
+    /** Read anything after the cursor that live delivery didn't bring. */
+    catchUp() {
+        return this.enqueue(() => this.drain());
+    }
+    /** Stop emitting. Pending work finishes silently. */
+    close() {
+        this.closed = true;
+    }
+    push(row, show) {
+        if (this.closed || row.pos == null || row.pos <= this.last)
+            return;
+        this.last = row.pos;
+        if (show && !show(row))
+            return;
+        this.emit(row);
+    }
+    /** Emit stored rows after the cursor, up to `until` when given. */
+    async drain(until, show) {
+        for (;;) {
+            if (this.closed)
+                return;
+            const rows = await this.fetchAfter(this.last, exports.FEED_PAGE);
+            for (const row of rows) {
+                if (row.pos == null)
+                    continue;
+                if (until !== undefined && row.pos > until)
+                    return;
+                this.push(row, show);
+            }
+            if (rows.length < exports.FEED_PAGE)
+                return;
+        }
+    }
+    enqueue(work) {
+        const next = this.chain.then(async () => {
+            if (this.closed)
+                return;
+            try {
+                await work();
+            }
+            catch (error) {
+                this.onError(error);
+            }
+        });
+        this.chain = next;
+        return next;
+    }
+}
+exports.OrderedFeed = OrderedFeed;

package/dist/cjs/contract/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * The shapes a run is made of, as core-api sends and accepts them.
+ *
+ * One shape per thing, with optional fields, rather than tagged unions:
+ * core-api builds without strictNullChecks, where a union doesn't narrow, and
+ * the same types are used on both sides of the wire.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/engine/engine.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectSse = exports.SseParser = void 0;
+/**
+ * @workser/runtime — the run contract every Workser runner, screen and service
+ * speaks. See README.md for runner protocol v1.
+ */
+__exportStar(require("./contract/index.js"), exports);
+__exportStar(require("./runner/index.js"), exports);
+__exportStar(require("./client/index.js"), exports);
+var sse_js_1 = require("./internal/sse.js");
+Object.defineProperty(exports, "SseParser", { enumerable: true, get: function () { return sse_js_1.SseParser; } });
+Object.defineProperty(exports, "connectSse", { enumerable: true, get: function () { return sse_js_1.connectSse; } });

package/dist/cjs/internal/async-queue.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncQueue = void 0;
+/** A push-to-pull bridge: callbacks push, an async iterator pulls. */
+class AsyncQueue {
+    onReturn;
+    items = [];
+    waiters = [];
+    ended = false;
+    failure = null;
+    constructor(onReturn = () => undefined) {
+        this.onReturn = onReturn;
+    }
+    push(item) {
+        if (this.ended)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter)
+            waiter({ value: item, done: false });
+        else
+            this.items.push(item);
+    }
+    end(error) {
+        if (this.ended)
+            return;
+        this.ended = true;
+        if (error)
+            this.failure = error;
+        for (const waiter of this.waiters.splice(0)) {
+            waiter({ value: undefined, done: true });
+        }
+    }
+    next() {
+        const item = this.items.shift();
+        if (item !== undefined)
+            return Promise.resolve({ value: item, done: false });
+        if (this.ended) {
+            if (this.failure) {
+                const error = this.failure;
+                this.failure = null;
+                return Promise.reject(error);
+            }
+            return Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise((resolve) => this.waiters.push(resolve));
+    }
+    return() {
+        this.end();
+        this.onReturn();
+        return Promise.resolve({ value: undefined, done: true });
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}
+exports.AsyncQueue = AsyncQueue;