@workser/runtime 0.0.0-stage → 0.1.0

package/dist/contract/types.d.ts

@@ -0,0 +1,311 @@
+/**
+ * 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.
+ */
+/** Which kind of worker runs the job. */
+export type RunLane = 'service' | 'workbench' | 'computer';
+/** Where the work happens. */
+export type RunPlace = 'service' | 'desktop' | 'sandbox' | 'cloud_computer' | 'cloud_browser';
+export type RunStatus = 'QUEUED' | 'STARTING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
+/** `GET v1/runner/runs/:id` — what a runner needs to start or resume. */
+export interface RunBrief {
+    protocol: number;
+    run: {
+        id: string;
+        status: RunStatus;
+        agent_id: string;
+        session_id: string;
+        project_id: string | null;
+        project_task_id: string | null;
+        lane: RunLane | null;
+        place: RunPlace | null;
+        kind: string | null;
+        /** Credits this run may spend, as a decimal string (bigint on the server). */
+        budget_credits: string | null;
+        parent_run_id: string | null;
+        input: Record<string, unknown>;
+        /**
+         * The engine session an earlier runner of this run had (its last
+         * `engine.session` event), so a restart can reattach. Null when none.
+         */
+        resume?: RunResume | null;
+    };
+    cursors: {
+        /** Last event seq core-api stored for this runner. Send from +1. */
+        runner_seq: number;
+        /** Last event position in the run's log. */
+        event_pos: number;
+        /** Last command position. */
+        command_pos: number;
+    };
+    /**
+     * The business's company brain (core-api migration 247): the prompt section
+     * every job follows, and the never rules with a check. Absent from an older
+     * core-api, or when the run belongs to no project.
+     */
+    company_brain?: {
+        block: string;
+        never_rules: Array<{
+            id: string;
+            text: string;
+            guard: Record<string, unknown>;
+        }>;
+    } | null;
+}
+/** Where an earlier runner of this run left its engine session. */
+export interface RunResume {
+    engine: string;
+    session_id: string;
+    workdir: string;
+}
+/** `POST v1/runs/:id/runner` — handing a run to a runner. */
+export interface AttachRunnerResult {
+    run_id: string;
+    /** Shown once. Good for this run only. */
+    token: string;
+    expires_at: string;
+    protocol: number;
+}
+/** What core-api tells a runner. */
+export type RunnerCommandKind = 'cancel' | 'pause' | 'resume' | 'answer' | 'approval' | 'message';
+/**
+ * One command. `payload` by kind:
+ * - cancel:   { reason }
+ * - pause / resume: {}
+ * - answer:   { approval_id, answer }        (a reply to a question)
+ * - approval: { approval_id, decision: 'approved' | 'denied', auto? }
+ * - message:  { text }                        (the owner said something mid-run)
+ */
+export interface RunnerCommand {
+    pos: number;
+    kind: RunnerCommandKind;
+    payload: RunnerCommandPayload;
+    created_at: string;
+}
+export interface RunnerCommandPayload {
+    reason?: string;
+    approval_id?: string;
+    answer?: string;
+    decision?: 'approved' | 'denied';
+    auto?: boolean;
+    text?: string;
+    [key: string]: unknown;
+}
+/** Things a runner may ask the owner. Credentials are never asked this way. */
+export type AskKind = 'question' | 'permission' | 'spend';
+/** `POST v1/runner/runs/:id/asks` body. */
+export interface Ask {
+    kind: AskKind;
+    title: string;
+    message: string;
+    /** For a multiple-choice question. The reply must be one of these. */
+    choices?: string[];
+    action_summary?: string;
+    /** Hashed server-side to fingerprint the action; never stored. */
+    payload?: Record<string, unknown>;
+    timeout_seconds?: number;
+}
+export interface AskResult {
+    approval_id: string;
+    status: 'pending' | 'approved' | 'denied' | 'expired';
+    auto_approved: boolean;
+    expires_at: string | null;
+}
+/** A file or result another run can use, passed by reference, never copied. */
+export interface ArtifactRef {
+    artifact_id: string;
+    name?: string;
+    kind?: 'file' | 'diff' | 'test_report' | 'screenshot' | 'media' | 'data';
+    mime_type?: string;
+    version?: number;
+}
+/** A done-check's outcome (tests, typecheck, deck validates, numbers match). */
+export interface CheckResult {
+    name: string;
+    status: 'pass' | 'fail' | 'skip';
+    detail?: string;
+}
+/** Tokens and cost as a runner saw them. Billing uses the gateway's figure. */
+export interface Usage {
+    model?: string;
+    tokens_in?: number;
+    tokens_out?: number;
+    cost_usd?: number;
+}
+/**
+ * One agent asking another for a sub-job. The contract, not a chat message:
+ * what done means, what goes in, what must come back, and what it may spend.
+ */
+export interface Handoff {
+    goal: string;
+    /** Who does it. Default: the same agent as the parent. Same org always. */
+    agent_id?: string;
+    inputs: {
+        artifacts?: ArtifactRef[];
+        /** Small typed values. Anything large goes in as an artifact. */
+        data?: Record<string, unknown>;
+    };
+    /** What the child must return, e.g. a JSON Schema for `HandoffResult.data`. */
+    expected: {
+        description: string;
+        schema?: Record<string, unknown>;
+        artifacts?: string[];
+    };
+    /** Carved from the parent's budget; never more than it has left. */
+    budget_credits?: number;
+    /** ISO time the parent stops waiting. */
+    deadline?: string;
+    /** Who approves the child's risky actions. */
+    approval_policy?: 'ask_owner' | 'inherit' | 'auto';
+    place?: RunPlace;
+    lane?: RunLane;
+}
+export interface HandoffResult {
+    child_run_id: string;
+    status: 'completed' | 'failed' | 'cancelled';
+    summary?: string;
+    data?: Record<string, unknown>;
+    artifacts?: ArtifactRef[];
+    error?: string;
+}
+/** `GET v1/projects/:projectId/runs/stream` first frame, one row per run. */
+export interface ProjectRunRow {
+    id: string;
+    status: RunStatus;
+    lane: RunLane | null;
+    place: RunPlace | null;
+    kind: string | null;
+    project_task_id: string | null;
+    parent_run_id: string | null;
+    waiting_on: string | null;
+    event_pos: number;
+    created_at: string;
+    updated_at: string;
+    completed_at: string | null;
+}
+export interface ProjectSnapshot {
+    project_id: string;
+    runs: ProjectRunRow[];
+}
+/** A `run.summary` frame: one meaningful event of one run, trimmed. */
+export interface ProjectRunSummary {
+    run_id: string;
+    pos: number;
+    type: string;
+    at: string;
+    data: Record<string, unknown>;
+}
+/** An event as streamed by `GET v1/runs/:id/events`. */
+export interface RunEventFrame {
+    event_id: string;
+    type: string;
+    /** The writer's own number. Not an order. */
+    seq: number;
+    /** The run's order, assigned by core-api. Resume after this. */
+    pos: number;
+    data: Record<string, unknown>;
+}
+/** `POST v1/runner/runs/:id/events` reply. */
+export interface RunnerBatchResult {
+    accepted: number;
+    duplicates: number;
+    cursor: number;
+}
+/** `POST v1/runner/runs/:id/heartbeat` reply. */
+export interface HeartbeatResult {
+    status: RunStatus | null;
+    runner_seq: number;
+    command_pos: number;
+}
+/** `POST v1/runner/runs/:id/artifacts/uploads` — where to PUT the bytes. */
+export interface UploadGrant {
+    upload_url: string;
+    /** Pass back to `registerArtifact`. Always under this run's own prefix. */
+    storage_key: string;
+    expires_in: number;
+}
+/** What `registerArtifact` sends. */
+export interface RegisterArtifact {
+    name: string;
+    storage_key: string;
+    kind?: ArtifactRef['kind'];
+    mime_type?: string;
+    size_bytes?: number;
+    /** Hex SHA-256 of the bytes; core-api checks it when it can read the file. */
+    sha256?: string;
+    /** The version this replaces, when another run wrote the current one. */
+    supersedes?: string;
+    description?: string;
+}
+/** A file in the project store, as a runner sees it. */
+export interface ProjectFile extends ArtifactRef {
+    project_id: string;
+    writer_run_id: string | null;
+    sha256: string | null;
+    size_bytes: number | null;
+    supersedes_id: string | null;
+    created_at: string;
+    /** Short-lived; only on `getArtifact`. */
+    download_url?: string;
+    expires_in?: number;
+}
+/** `POST v1/runner/runs/:id/handoffs` answer. */
+export interface HandoffCreated {
+    child_run_id: string;
+    depth: number;
+    budget_credits: number | null;
+    status: RunStatus;
+}
+/** `GET v1/runner/runs/:id/handoffs/:childId`. */
+export interface HandoffStatus {
+    child_run_id: string;
+    status: RunStatus;
+    handoff: Handoff & {
+        goal_hash?: string;
+    };
+    /** Set once the child has ended. */
+    result: HandoffResult | null;
+}
+/** One tool a runner may call: a name, what it does, its arguments. Never a secret. */
+export interface RunnerTool {
+    /** `request_subjob`, `email_send`, or `composio.<SLUG>`. */
+    name: string;
+    source: 'workser' | 'composio';
+    description: string;
+    /** Changes something outside the job: the owner is asked first. */
+    side_effect: boolean;
+    /** Moves money: say `amount_usd`; over the owner's limit a spend yes is needed. */
+    spends: boolean;
+    input_schema: Record<string, unknown>;
+}
+export interface RunnerToolList {
+    tools: RunnerTool[];
+    /** Dollars above which a spending call needs the owner's yes. */
+    ask_before_paying_usd: number;
+}
+export interface ToolCall {
+    arguments?: Record<string, unknown>;
+    /** The approved `permission` ask for exactly this call. */
+    approval_id?: string;
+    /** Spending tools: how much. */
+    amount_usd?: number;
+    /** The approved `spend` ask, when the amount is over the limit. */
+    spend_approval_id?: string;
+}
+/**
+ * `ok` with the tool's answer, or `approval_required`: wait for the owner's
+ * answer (an `approval` command), then call again with the id in
+ * `approval_id` (permission) or `spend_approval_id` (spend).
+ */
+export interface ToolCallResult {
+    status: 'ok' | 'approval_required';
+    result?: unknown;
+    approval_id?: string;
+    kind?: 'permission' | 'spend';
+    message?: string;
+    /** The result holds an outside message (a sign-in code): do not keep it in the job record or saved state. */
+    private_output?: boolean;
+}

package/dist/contract/types.js

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/contract/types.js.map

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

package/dist/engine/engine.d.ts

@@ -0,0 +1,39 @@
+import type { RunBrief, RunnerCommand } from '../contract/types.js';
+import type { Place } from '../place/place.js';
+/**
+ * The thing that thinks: the agent loop (our OpenCode fork first). It gets the
+ * brief and a Place, and reports everything it does through `emit`, which the
+ * runner turns into run events.
+ */
+export interface Engine {
+    /** A short name for `run.started`, e.g. `opencode`. */
+    readonly name: string;
+    start(brief: RunBrief, place: Place, emit: EngineEmit): Promise<EngineSession>;
+    /** Pick up a session saved by `EngineSession.save()` after a pause or restart. */
+    resume(state: EngineSessionState, place: Place, emit: EngineEmit): Promise<EngineSession>;
+}
+/** One running job. */
+export interface EngineSession {
+    /** A new message from the owner, mid-run. */
+    send(message: string): Promise<void>;
+    /** A command from core-api: an answer, a decision, pause, resume. Stop comes through `stop`. */
+    answer(command: RunnerCommand): Promise<void>;
+    /** Stop as soon as it is safe; the promise ends when it has. */
+    stop(reason?: string): Promise<void>;
+    /** Everything needed to resume later. Small; large state lives on the Place. */
+    save(): Promise<EngineSessionState>;
+    /** Ends with how the job ended. */
+    readonly done: Promise<EngineOutcome>;
+}
+export type EngineEmit = (type: string, data?: Record<string, unknown>) => void;
+export interface EngineSessionState {
+    engine: string;
+    version: number;
+    data: Record<string, unknown>;
+}
+export interface EngineOutcome {
+    status: 'completed' | 'failed' | 'cancelled';
+    summary?: string;
+    error_kind?: string;
+    message?: string;
+}

package/dist/engine/engine.js

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

package/dist/engine/engine.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @workser/runtime — the run contract every Workser runner, screen and service
+ * speaks. See README.md for runner protocol v1.
+ */
+export * from './contract/index.js';
+export * from './runner/index.js';
+export * from './client/index.js';
+export type * from './place/place.js';
+export type * from './engine/engine.js';
+export { SseParser, connectSse, type SseMessage } from './internal/sse.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @workser/runtime — the run contract every Workser runner, screen and service
+ * speaks. See README.md for runner protocol v1.
+ */
+export * from './contract/index.js';
+export * from './runner/index.js';
+export * from './client/index.js';
+export { SseParser, connectSse } from './internal/sse.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAGlC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAmB,MAAM,mBAAmB,CAAC"}

package/dist/internal/async-queue.d.ts

@@ -0,0 +1,14 @@
+/** A push-to-pull bridge: callbacks push, an async iterator pulls. */
+export declare class AsyncQueue<T> implements AsyncIterableIterator<T> {
+    private readonly onReturn;
+    private readonly items;
+    private readonly waiters;
+    private ended;
+    private failure;
+    constructor(onReturn?: () => void);
+    push(item: T): void;
+    end(error?: unknown): void;
+    next(): Promise<IteratorResult<T>>;
+    return(): Promise<IteratorResult<T>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+}

package/dist/internal/async-queue.js

@@ -0,0 +1,53 @@
+/** A push-to-pull bridge: callbacks push, an async iterator pulls. */
+export 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;
+    }
+}
+//# sourceMappingURL=async-queue.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"async-queue.js","sourceRoot":"","sources":["../../src/internal/async-queue.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,MAAM,OAAO,UAAU;IAMQ;IALZ,KAAK,GAAQ,EAAE,CAAC;IAChB,OAAO,GAA+C,EAAE,CAAC;IAClE,KAAK,GAAG,KAAK,CAAC;IACd,OAAO,GAAY,IAAI,CAAC;IAEhC,YAA6B,WAAuB,GAAG,EAAE,CAAC,SAAS;QAAtC,aAAQ,GAAR,QAAQ,CAA8B;IAAG,CAAC;IAEvE,IAAI,CAAC,IAAO;QACV,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACpC,IAAI,MAAM;YAAE,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;;YAC5C,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED,GAAG,CAAC,KAAe;QACjB,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO;QACvB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,KAAK;YAAE,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QAChC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5C,MAAM,CAAC,EAAE,KAAK,EAAE,SAAkB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IAED,IAAI;QACF,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QAChC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7E,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC;gBAC3B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;gBACpB,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC/B,CAAC;YACD,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,SAAkB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,CAAC;QACD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,GAAG,EAAE,CAAC;QACX,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,SAAkB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,CAAC,MAAM,CAAC,aAAa,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/internal/sse.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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`).
+ */
+export interface SseMessage {
+    /** The `event:` field, `message` when absent. */
+    event: string;
+    data: string;
+    /** The last `id:` seen on this connection, carried forward per the spec. */
+    id: string;
+    /** A `retry:` the server asked for, in ms, when this message carried one. */
+    retry?: number;
+}
+/** Incremental parser: feed it text chunks, get whole messages back. */
+export declare class SseParser {
+    private buffer;
+    private data;
+    private event;
+    private lastId;
+    private retry;
+    private sawCr;
+    /** Parse one chunk. A message split across chunks is held until complete. */
+    push(chunk: string): SseMessage[];
+    private line;
+    private dispatch;
+}
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export interface SseConnectOptions {
+    fetch: FetchLike;
+    /** Built fresh for every (re)connect, so the cursor can move. */
+    url: () => string;
+    headers: () => Record<string, string>;
+    signal: AbortSignal;
+    onMessage: (message: SseMessage) => void;
+    /** First wait before reconnecting, doubled per failure up to `maxDelayMs`. */
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    /** Called on a failed connect or a dropped stream. Return false to stop. */
+    onError?: (error: unknown) => boolean | void;
+    /** A response status that means "stop, don't retry" (e.g. 401, 403, 404). */
+    fatalStatuses?: number[];
+}
+/**
+ * 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 declare function connectSse(options: SseConnectOptions): Promise<void>;
+export declare class SseHttpError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;