@workser/runtime 0.0.0-stage → 0.1.0

package/dist/internal/sse.js

@@ -0,0 +1,164 @@
+/**
+ * Server-Sent Events over `fetch`, for Node 18+ and browsers alike.
+ *
+ * Not `EventSource`: it can't send an `Authorization` header (a runner's token
+ * has to go somewhere), it doesn't exist in Node, and its reconnect can't be
+ * told to resume from a cursor we choose. This follows the HTML spec's parsing
+ * rules (line endings, `data` joining, comments, `id`, `retry`).
+ */
+/** Incremental parser: feed it text chunks, get whole messages back. */
+export class SseParser {
+    buffer = '';
+    data = [];
+    event = '';
+    lastId = '';
+    retry;
+    sawCr = false;
+    /** Parse one chunk. A message split across chunks is held until complete. */
+    push(chunk) {
+        const out = [];
+        let text = chunk;
+        // A `\r\n` split across two chunks: the `\n` belongs to the `\r` already
+        // treated as a line end.
+        if (this.sawCr && text.startsWith('\n'))
+            text = text.slice(1);
+        this.sawCr = false;
+        this.buffer += text;
+        for (;;) {
+            const match = /\r\n|\r|\n/.exec(this.buffer);
+            if (!match)
+                break;
+            const line = this.buffer.slice(0, match.index);
+            const endsWithLoneCr = match[0] === '\r' && match.index + 1 === this.buffer.length;
+            this.buffer = this.buffer.slice(match.index + match[0].length);
+            if (endsWithLoneCr)
+                this.sawCr = true;
+            const message = this.line(line);
+            if (message)
+                out.push(message);
+        }
+        return out;
+    }
+    line(line) {
+        if (line === '')
+            return this.dispatch();
+        if (line.startsWith(':'))
+            return null; // a comment (servers use them as pings)
+        const colon = line.indexOf(':');
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1);
+        switch (field) {
+            case 'data':
+                this.data.push(value);
+                break;
+            case 'event':
+                this.event = value;
+                break;
+            case 'id':
+                if (!value.includes('\u0000'))
+                    this.lastId = value;
+                break;
+            case 'retry':
+                if (/^\d+$/.test(value))
+                    this.retry = Number(value);
+                break;
+            default:
+                break; // unknown fields are ignored
+        }
+        return null;
+    }
+    dispatch() {
+        const retry = this.retry;
+        this.retry = undefined;
+        if (this.data.length === 0) {
+            this.event = '';
+            return null;
+        }
+        const message = {
+            event: this.event || 'message',
+            data: this.data.join('\n'),
+            id: this.lastId,
+        };
+        if (retry !== undefined)
+            message.retry = retry;
+        this.data = [];
+        this.event = '';
+        return message;
+    }
+}
+/**
+ * Keep an SSE connection open until `signal` aborts: connect, parse, and on
+ * any drop reconnect with backoff. The caller's `url()` decides where to
+ * resume from, so reconnects continue rather than replay.
+ */
+export async function connectSse(options) {
+    const base = options.baseDelayMs ?? 500;
+    const max = options.maxDelayMs ?? 15_000;
+    const fatal = new Set(options.fatalStatuses ?? [401, 403, 404]);
+    let delay = base;
+    let serverRetry;
+    while (!options.signal.aborted) {
+        let failure = null;
+        try {
+            const response = await options.fetch(options.url(), {
+                headers: { Accept: 'text/event-stream', ...options.headers() },
+                signal: options.signal,
+            });
+            if (!response.ok || !response.body) {
+                const error = new SseHttpError(response.status);
+                if (fatal.has(response.status)) {
+                    options.onError?.(error);
+                    return;
+                }
+                throw error;
+            }
+            delay = base;
+            const parser = new SseParser();
+            const decoder = new TextDecoder();
+            const reader = response.body.getReader();
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                for (const message of parser.push(decoder.decode(value, { stream: true }))) {
+                    if (message.retry !== undefined)
+                        serverRetry = message.retry;
+                    options.onMessage(message);
+                }
+            }
+        }
+        catch (error) {
+            failure = error;
+        }
+        if (options.signal.aborted)
+            return;
+        if (failure && options.onError?.(failure) === false)
+            return;
+        await sleep(serverRetry ?? delay, options.signal);
+        delay = Math.min(delay * 2, max);
+    }
+}
+export class SseHttpError extends Error {
+    status;
+    constructor(status) {
+        super(`The stream answered ${status}.`);
+        this.status = status;
+        this.name = 'SseHttpError';
+    }
+}
+export function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve();
+        const timer = setTimeout(done, ms);
+        function done() {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', done);
+            resolve();
+        }
+        signal?.addEventListener('abort', done, { once: true });
+    });
+}
+//# sourceMappingURL=sse.js.map

package/dist/internal/sse.js.map

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

package/dist/place/place.d.ts

@@ -0,0 +1,81 @@
+import type { RunPlace } from '../contract/types.js';
+/**
+ * Where a run's work happens: the owner's desktop, an E2B sandbox, the
+ * project's cloud computer. An engine never touches a machine directly — it
+ * asks its Place, so the same engine loop can run on the machine itself or in
+ * our service while the machine only does the work.
+ */
+export interface Place {
+    /** What this place is and what it can do. */
+    info(): Promise<PlaceInfo>;
+    /** Run a command. Output streams through `onOutput`; the promise ends with the exit. */
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    readFile(path: string): Promise<Uint8Array>;
+    /** Creates parent folders as needed. */
+    writeFile(path: string, content: Uint8Array | string): Promise<void>;
+    /** Entries directly inside `path` (not recursive). */
+    list(path: string): Promise<PlaceEntry[]>;
+    /** `git status` of the working folder, parsed. */
+    gitStatus(cwd?: string): Promise<GitStatus>;
+    /** The diff against `base` (default: the run's starting point). */
+    gitDiff(options?: {
+        cwd?: string;
+        base?: string;
+        paths?: string[];
+    }): Promise<string>;
+    /** A URL the owner can open for a port a dev server listens on. */
+    previewUrl(port: number): Promise<string>;
+    /** Stop paying for the machine while keeping its disk. */
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    /** Save the machine's state so a later run can start from it. */
+    snapshot(label?: string): Promise<{
+        snapshot_id: string;
+    }>;
+}
+export interface PlaceInfo {
+    place: RunPlace;
+    /** The folder the run works in. */
+    root: string;
+    os: 'linux' | 'darwin' | 'windows';
+    /** e.g. ['git', 'node', 'python', 'ffmpeg', 'browser'] */
+    tools: string[];
+    canPause: boolean;
+    canSnapshot: boolean;
+}
+export interface ExecOptions {
+    cwd?: string;
+    /** Added to the place's own environment. Never a provider key. */
+    env?: Record<string, string>;
+    /** Kill the command after this long. */
+    timeoutMs?: number;
+    /** Text written to the command's stdin, then closed. */
+    stdin?: string;
+    onOutput?: (chunk: {
+        stream: 'stdout' | 'stderr';
+        text: string;
+    }) => void;
+    signal?: AbortSignal;
+}
+export interface ExecResult {
+    exitCode: number;
+    /** Kept to the last ~64 KB of each; the full output went through `onOutput`. */
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    durationMs: number;
+}
+export interface PlaceEntry {
+    name: string;
+    path: string;
+    type: 'file' | 'dir' | 'link';
+    size?: number;
+}
+export interface GitStatus {
+    branch: string | null;
+    clean: boolean;
+    files: Array<{
+        path: string;
+        change: 'added' | 'modified' | 'deleted' | 'renamed' | 'untracked';
+    }>;
+}

package/dist/place/place.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=place.js.map

package/dist/place/place.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"place.js","sourceRoot":"","sources":["../../src/place/place.ts"],"names":[],"mappings":""}

package/dist/runner/index.d.ts

@@ -0,0 +1,2 @@
+export { RunnerClient, RunnerError, type RunnerClientOptions, type RunJournal } from './runner-client.js';
+export type { JournalEvent } from './journal.js';

package/dist/runner/index.js

@@ -0,0 +1,2 @@
+export { RunnerClient, RunnerError } from './runner-client.js';
+//# sourceMappingURL=index.js.map

package/dist/runner/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runner/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAA6C,MAAM,oBAAoB,CAAC"}

package/dist/runner/journal.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The runner's disk journal: events emitted but not yet accepted by core-api,
+ * so a runner killed outright (SIGKILL, a laptop lid, a sandbox pulled) loses
+ * nothing. Node only — loaded lazily by `RunnerClient` when `journalPath` is
+ * set, so the SDK still runs in browsers.
+ *
+ * Format: one JSON event per line, exactly as it will be sent (same
+ * `event_id` and `seq`). A resend after a restart is therefore a retry to
+ * core-api, which accepts an identical event as a duplicate and stores it
+ * once. The file is appended on every emit, fsync'd before each send, and
+ * rewritten (temp file + rename, so a crash mid-write can't corrupt it) to
+ * what is still unsent after core-api accepts a batch.
+ */
+import type { RunnerEventInput } from '../contract/catalog.js';
+export interface JournalEvent extends RunnerEventInput {
+    data: Record<string, unknown>;
+}
+export declare class EventJournal {
+    private readonly fs;
+    private readonly path;
+    private readonly pathMod;
+    private dirty;
+    private constructor();
+    static open(path: string): Promise<EventJournal>;
+    /** Events saved by an earlier process, oldest first, one per event id. */
+    load(): JournalEvent[];
+    append(event: JournalEvent): void;
+    /** Make appended lines durable. Called before each send. */
+    sync(): void;
+    /** Replace the journal with what is still unsent. */
+    rewrite(events: JournalEvent[]): void;
+}

package/dist/runner/journal.js

@@ -0,0 +1,79 @@
+export class EventJournal {
+    fs;
+    path;
+    pathMod;
+    dirty = false;
+    constructor(fs, path, pathMod) {
+        this.fs = fs;
+        this.path = path;
+        this.pathMod = pathMod;
+    }
+    static async open(path) {
+        const fs = await import('node:fs');
+        const pathMod = await import('node:path');
+        fs.mkdirSync(pathMod.dirname(path), { recursive: true, mode: 0o700 });
+        if (!fs.existsSync(path))
+            fs.writeFileSync(path, '', { mode: 0o600 });
+        return new EventJournal(fs, path, pathMod);
+    }
+    /** Events saved by an earlier process, oldest first, one per event id. */
+    load() {
+        let raw = '';
+        try {
+            raw = this.fs.readFileSync(this.path, 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const byId = new Map();
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const event = JSON.parse(line);
+                if (typeof event?.event_id === 'string' && Number.isInteger(event.seq) && typeof event.type === 'string') {
+                    // A later line for the same id is a renumbering: it wins.
+                    byId.set(event.event_id, { ...event, data: event.data ?? {} });
+                }
+            }
+            catch {
+                // A torn last line (killed mid-append) is skipped; its event was never
+                // acknowledged to the caller as sent, and every earlier line is whole.
+            }
+        }
+        return [...byId.values()].sort((a, b) => a.seq - b.seq);
+    }
+    append(event) {
+        this.fs.appendFileSync(this.path, `${JSON.stringify(event)}\n`, { mode: 0o600 });
+        this.dirty = true;
+    }
+    /** Make appended lines durable. Called before each send. */
+    sync() {
+        if (!this.dirty)
+            return;
+        const fd = this.fs.openSync(this.path, 'r+');
+        try {
+            this.fs.fsyncSync(fd);
+        }
+        finally {
+            this.fs.closeSync(fd);
+        }
+        this.dirty = false;
+    }
+    /** Replace the journal with what is still unsent. */
+    rewrite(events) {
+        const temp = this.pathMod.join(this.pathMod.dirname(this.path), `.journal-${process.pid}-${Date.now()}.tmp`);
+        const body = events.map((event) => JSON.stringify(event)).join('\n');
+        const fd = this.fs.openSync(temp, 'w', 0o600);
+        try {
+            this.fs.writeSync(fd, body ? `${body}\n` : '');
+            this.fs.fsyncSync(fd);
+        }
+        finally {
+            this.fs.closeSync(fd);
+        }
+        this.fs.renameSync(temp, this.path);
+        this.dirty = false;
+    }
+}
+//# sourceMappingURL=journal.js.map

package/dist/runner/journal.js.map

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

package/dist/runner/runner-client.d.ts

@@ -0,0 +1,185 @@
+import { TERMINAL_EVENT_TYPES } from '../contract/catalog.js';
+import type { ArtifactRef, Ask, AskResult, Handoff, HandoffCreated, HandoffStatus, HeartbeatResult, ProjectFile, RegisterArtifact, RunBrief, RunnerCommand, RunnerToolList, ToolCall, ToolCallResult } from '../contract/types.js';
+import { type FetchLike } from '../internal/sse.js';
+import type { JournalEvent } from './journal.js';
+/**
+ * Where unsent events are kept until core-api accepts them. The default is
+ * the Node disk journal (`journalPath`); a runner whose machine is somewhere
+ * else (a Trigger.dev worker driving a remote sandbox) passes its own, e.g.
+ * one that keeps the file on that machine. `sync` runs before each send and
+ * may be async; `append` and `rewrite` must keep their order themselves.
+ */
+export interface RunJournal {
+    load(): JournalEvent[] | Promise<JournalEvent[]>;
+    append(event: JournalEvent): void;
+    sync(): void | Promise<void>;
+    rewrite(events: JournalEvent[]): void | Promise<void>;
+}
+export interface RunnerClientOptions {
+    /** core-api, e.g. `https://api.workser.ai`. */
+    baseUrl: string;
+    runId: string;
+    /** The `wsrn_` token from `POST v1/runs/:id/runner`. */
+    token: string;
+    fetch?: FetchLike;
+    /** How long an ordinary event may wait to be batched. Default 150 ms. */
+    flushMs?: number;
+    /** Heartbeat interval. Default 10 s; core-api closes a run after 3 min of silence. */
+    heartbeatMs?: number;
+    /** Something went wrong that the client handled (or couldn't). */
+    onError?: (error: RunnerError) => void;
+    /**
+     * Keep unsent events in this file (Node only). A runner killed outright
+     * resends them on its next start — same ids and seqs, so core-api stores
+     * each once. See `journal.ts`.
+     */
+    journalPath?: string;
+    /** A journal of your own instead of `journalPath` (see `RunJournal`). */
+    journal?: RunJournal;
+}
+export declare class RunnerError extends Error {
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined);
+}
+/**
+ * Everything a Workser runner does for its run (runner protocol v1):
+ *
+ *   const runner = new RunnerClient({ baseUrl, runId, token });
+ *   const brief = await runner.start();          // brief + heartbeat
+ *   runner.commands((cmd) => …);                 // stop, answers, decisions
+ *   runner.emit('run.started', { engine: 'opencode' });
+ *   runner.emit('step.started', { step_id: 's1', title: 'Run tests' });
+ *   await runner.finish('run.completed', { summary: 'Done.' });
+ *
+ * Events are numbered by the client, from the run's cursor, in the order they
+ * are emitted, and sent in batches. A resend is safe (core-api drops copies);
+ * a gap is answered with where to resend from, and the client does.
+ */
+export declare class RunnerClient {
+    private readonly options;
+    private readonly baseUrl;
+    private readonly fetchFn;
+    private readonly flushMs;
+    private readonly heartbeatMs;
+    private token;
+    private nextSeq;
+    private pending;
+    private flushTimer;
+    private flushing;
+    private heartbeatTimer;
+    private readonly abort;
+    private lastCommandPos;
+    private closed;
+    private journal;
+    constructor(options: RunnerClientOptions);
+    get runId(): string;
+    /** The brief, and where to continue numbering. */
+    brief(): Promise<RunBrief>;
+    /**
+     * Pick up what an earlier process emitted but never got accepted. They go
+     * first, with their own seqs; new events continue after the highest.
+     */
+    private recover;
+    /** Events still waiting to be accepted (a copy). */
+    get unsent(): number;
+    /** Read the brief and start heartbeating. */
+    start(): Promise<RunBrief>;
+    /**
+     * Queue one event. Checked against the catalog now, so a mistake throws
+     * here, in the runner's own code, not later in a batch.
+     */
+    emit(type: string, data?: Record<string, unknown>): void;
+    /** Send everything queued. Resolves when core-api has it (or it was given up on). */
+    flush(): Promise<void>;
+    /**
+     * Listen for commands. Resumes after the last one seen; on the first
+     * connect core-api starts at the oldest command not yet acked. Acks each
+     * command after `handler` resolves, unless `autoAck` is false.
+     */
+    commands(handler: (command: RunnerCommand) => void | Promise<void>, options?: {
+        autoAck?: boolean;
+    }): Promise<void>;
+    /** Mark a command done. */
+    ack(pos: number): Promise<boolean>;
+    /** Ask the owner. The answer arrives through `commands()`. */
+    ask(ask: Ask): Promise<AskResult>;
+    /**
+     * Put a file in the project's store: get an upload slot, PUT the bytes
+     * straight to storage, register it. Returns the stored file (its version
+     * counts up per name in the project). Large output belongs here, not in an
+     * event.
+     *
+     * `supersedes`: when another run wrote the current version of this name,
+     * name that version to replace it (otherwise core-api answers 409 — one
+     * writer per file at a time).
+     */
+    uploadFile(name: string, bytes: Uint8Array | ArrayBuffer | string | Blob | ReadableStream<Uint8Array>, options?: {
+        kind?: ArtifactRef['kind'];
+        mime?: string;
+        supersedes?: string;
+        description?: string;
+    }): Promise<ProjectFile>;
+    /** Register a file already PUT to an upload slot from `uploadFile`. */
+    registerArtifact(file: RegisterArtifact): Promise<ProjectFile>;
+    /** A file in this run's project, with a short-lived download URL. */
+    getArtifact(artifactId: string): Promise<ProjectFile>;
+    /**
+     * Ask for a sub-job (plan Phase 3). core-api checks it (same project,
+     * depth, budget, no loops) and makes the child run; when the child ends,
+     * this run gets a `resume` command carrying the `HandoffResult`.
+     */
+    handoff(handoff: Handoff): Promise<HandoffCreated>;
+    /** Where a sub-job this run asked for has got to. */
+    handoffStatus(childRunId: string): Promise<HandoffStatus>;
+    /** The tools this run may call (Workser's and the project's connected apps). */
+    listTools(): Promise<RunnerToolList>;
+    /**
+     * Call one tool by name. A side effect or a big spend comes back
+     * `approval_required` first; call again with the approval id once the
+     * owner has said yes (it arrives as an `approval` command).
+     */
+    callTool(name: string, call?: ToolCall): Promise<ToolCallResult>;
+    /** Tell core-api this runner is alive. */
+    heartbeat(): Promise<HeartbeatResult>;
+    /**
+     * The token this client holds now — after `rotateToken`, the new one. For
+     * the runner to hand the same key to its engine; never log it.
+     */
+    get currentToken(): string;
+    /** Swap to a fresh token for a long job. The old one stops working. */
+    rotateToken(): Promise<string>;
+    /** End the run: send the terminal event, flush, stop. */
+    finish(type: 'run.completed' | 'run.failed' | 'run.cancelled', data?: Record<string, unknown>, options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Flush what's queued (waiting at most `timeoutMs` — a runner that can't
+     * reach core-api must still be able to exit), then stop heartbeats and the
+     * command stream.
+     */
+    close(options?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    private scheduleFlush;
+    private startHeartbeat;
+    private drain;
+    /**
+     * core-api says the next seq it expects is `expected`, and that our batch
+     * was NOT stored (a gap, or seqs another writer already used). Batches are
+     * all-or-nothing and an identical resend is accepted as a duplicate, so a
+     * 409 never means "some of yours are stored": nothing we hold is dropped.
+     * Everything is renumbered from `expected`.
+     *
+     * It used to drop events below `expected` as "already stored". After a
+     * restart with a stale brief, those were the new runner's own events, never
+     * stored — `run.started` was lost that way (Phase 6 chaos test).
+     */
+    private realign;
+    /** A journal of the caller's own may be async: its failure never stops the sends. */
+    private rewriteJournal;
+    private url;
+    private request;
+    private report;
+}
+export { TERMINAL_EVENT_TYPES };