@workser/runtime 0.0.0-stage → 0.1.0

package/dist/contract/catalog.js

@@ -0,0 +1,328 @@
+/**
+ * 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 const RUNNER_PROTOCOL_VERSION = 1;
+/** Largest event payload we keep, serialised. Bigger outputs go to files. */
+export const MAX_EVENT_DATA_BYTES = 64 * 1024;
+/** Largest batch a runner may send in one call. */
+export const 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.
+ */
+export const 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. */
+export const 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.
+ */
+export const 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. */
+export 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 = 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 > MAX_EVENT_DATA_BYTES) {
+        return {
+            ok: false,
+            reason: `${event.type}: data is ${size} bytes; the limit is ${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. */
+export 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. */
+export function unknownLegacyType(type) {
+    return !RUN_EVENT_CATALOG[type] && !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.
+ */
+export 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.
+ */
+export 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;
+    }
+}
+//# sourceMappingURL=catalog.js.map

package/dist/contract/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../src/contract/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAEzC,6EAA6E;AAC7E,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,GAAG,IAAI,CAAC;AAE9C,mDAAmD;AACnD,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC;AAWnC,MAAM,IAAI,GAAG,CAAC,SAAS,GAAG,MAAM,EAAE,QAAQ,GAAG,IAAI,EAAa,EAAE,CAAC,CAAC;IAChE,IAAI,EAAE,QAAQ;IACd,QAAQ;IACR,SAAS;CACV,CAAC,CAAC;AACH,MAAM,EAAE,GAAG,CAAC,QAAQ,GAAG,IAAI,EAAa,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAE/D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAoC;IAChE,aAAa,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE;IAClE,YAAY,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE;IAC1C,aAAa,EAAE,EAAE;IACjB,gFAAgF;IAChF,eAAe,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;IAC7E,YAAY,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE;IAC1E,eAAe,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE;IAC7C,0EAA0E;IAC1E,2EAA2E;IAC3E,iFAAiF;IACjF,qBAAqB,EAAE;QACrB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;QACzC,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE;KAC5C;IACD,0EAA0E;IAC1E,UAAU,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;IACtE,6EAA6E;IAC7E,yEAAyE;IACzE,kEAAkE;IAClE,gBAAgB,EAAE;QAChB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE;QAC5H,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC;QACvB,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC;KACtB;IACD,iEAAiE;IACjE,6DAA6D;IAC7D,gBAAgB,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE;IAEnF,0EAA0E;IAC1E,oCAAoC;IACpC,aAAa,EAAE;QACb,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE;QACpE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC;KAClB;IAED,cAAc,EAAE;QACd,OAAO,EAAE,EAAE,EAAE;QACb,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC;QAChB,IAAI,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC;QACtB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QACzB,yEAAyE;QACzE,YAAY,EAAE,EAAE,CAAC,KAAK,CAAC;QACvB,cAAc,EAAE,EAAE,CAAC,KAAK,CAAC;KAC1B;IACD,uEAAuE;IACvE,eAAe,EAAE;QACf,OAAO,EAAE,EAAE,EAAE;QACb,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC;QACxB,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QACvB,WAAW,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC;KAChC;IACD,8EAA8E;IAC9E,cAAc,EAAE;QACd,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE;KACzC;IACD,gBAAgB,EAAE;QAChB,OAAO,EAAE,EAAE,EAAE;QACb,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE;QAC7E,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC1B,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC;QACzB,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;KAChC;IAED,OAAO,EAAE;QACP,UAAU,EAAE,EAAE,CAAC,KAAK,CAAC;QACrB,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC;SACvC;QACD,IAAI,EAAE,IAAI,EAAE;KACb;IACD,eAAe,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;IAEnD,cAAc,EAAE;QACd,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC;QACjB,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,CAAC;SACnD;KACF;IACD,YAAY,EAAE;QACZ,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE;QACzC,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC7B,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;KAC9B;IACD,cAAc,EAAE;QACd,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;QACf,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC;QACD,MAAM,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC;KAC3B;IACD,eAAe,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE;IACrC,oEAAoE;IACpE,iBAAiB,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE;IACnE,kBAAkB,EAAE;QAClB,YAAY,EAAE,EAAE,EAAE;QAClB,MAAM,EAAE;YACN,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,WAAW,CAAC;SAC5C;KACF;IACD,KAAK,EAAE;QACL,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC;QACvB,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC7B,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QAC9B,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;KAC7B;IACD,GAAG,EAAE;QACH,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC;SAC1C;QACD,IAAI,EAAE,IAAI,EAAE;KACb;CACF,CAAC;AAEF,sEAAsE;AACtE,MAAM,CAAC,MAAM,oBAAoB,GAAwB,IAAI,GAAG,CAAC;IAC/D,eAAe;IACf,YAAY;IACZ,eAAe;CAChB,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC;IAC7D,cAAc;IACd,wBAAwB;IACxB,eAAe;IACf,gBAAgB;IAChB,oBAAoB;IACpB,2BAA2B;IAC3B,6BAA6B;IAC7B,6BAA6B;IAC7B,2BAA2B;IAC3B,0BAA0B;IAC1B,mBAAmB;IACnB,cAAc;IACd,oBAAoB;IACpB,aAAa;IACb,cAAc;IACd,eAAe;IACf,kBAAkB;IAClB,qBAAqB;IACrB,cAAc;IACd,SAAS;IACT,oCAAoC;IACpC,iCAAiC;CAClC,CAAC,CAAC;AAeH,2DAA2D;AAC3D,MAAM,UAAU,gBAAgB,CAAC,KAAuB;IACtD,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,6BAA6B,EAAE,CAAC;IAC9D,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QACxF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,+CAA+C,EAAE,CAAC;IAChF,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,sCAAsC,EAAE,CAAC;IACvE,CAAC;IACD,MAAM,KAAK,GAAG,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,uBAAuB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IAC9E,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;IAC9B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QACrE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,2BAA2B,EAAE,CAAC;IACzE,CAAC;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,IAAI,GAAG,oBAAoB,EAAE,CAAC;QAChC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,aAAa,IAAI,wBAAwB,oBAAoB,+BAA+B;SAClH,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,KAAK,GAAI,IAAgC,CAAC,KAAK,CAAC,CAAC;QACvD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAC1C,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAClB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,MAAM,KAAK,gBAAgB,EAAE,CAAC;YACzE,CAAC;YACD,SAAS;QACX,CAAC;QACD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC;QAC7D,IAAI,MAAM,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;YACzB,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,MAAM,KAAK,aAAa,IAAI,CAAC,IAAI,SAAS,MAAM,GAAG;aACzE,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAe,CAAC,EAAE,CAAC;YAChE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,MAAM,KAAK,mBAAmB,EAAE,CAAC;QAC5E,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAe,CAAC,EAAE,CAAC;YACxD,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,MAAM,KAAK,oBAAoB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;aAC7E,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,IAAK,KAAgB,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YAChE,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,MAAM,KAAK,oBAAoB,IAAI,CAAC,SAAS,cAAc;aACjF,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,gBAAgB,CAAC,KAIhC;IACC,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QAC9F,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,iDAAiD,EAAE,CAAC;IAClF,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;QACxF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,+CAA+C,EAAE,CAAC;IAChF,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACjC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,6BAA6B,EAAE,CAAC;IAC9D,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACnE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAY;IAEZ,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,aAAa,CAAC;QACnB,KAAK,aAAa;YAChB,OAAO,SAAS,CAAC;QACnB,KAAK,eAAe;YAClB,OAAO,WAAW,CAAC;QACrB,KAAK,YAAY;YACf,OAAO,QAAQ,CAAC;QAClB,KAAK,eAAe;YAClB,OAAO,WAAW,CAAC;QACrB;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAWD;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAc,EACd,MAA0B;IAE1B,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,GAAG,MAAM,CAAC,CAAC;IACvD,IAAI,QAAQ,GAAG,MAAM,GAAG,CAAC,CAAC;IAC1B,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,IAAI,GAAG,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;YACzB,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,QAAQ;gBACR,MAAM,EACJ,GAAG,CAAC,GAAG,GAAG,QAAQ;oBAChB,CAAC,CAAC,OAAO,GAAG,CAAC,GAAG,+BAA+B;oBAC/C,CAAC,CAAC,OAAO,GAAG,CAAC,GAAG,0BAA0B,QAAQ,iBAAiB,QAAQ,GAAG;aACnF,CAAC;QACJ,CAAC;QACD,QAAQ,IAAI,CAAC,CAAC;IAChB,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,GAAG,CAAC,EAAE,CAAC;AACvD,CAAC;AAED,2EAA2E;AAC3E,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAElC,SAAS,UAAU,CAAC,KAAc;IAChC,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,iBAAiB,CAAC;IAClC,CAAC;AACH,CAAC"}

package/dist/contract/index.d.ts

@@ -0,0 +1,4 @@
+export * from './catalog.js';
+export * from './ordered-feed.js';
+export * from './types.js';
+export * from './actions.js';

package/dist/contract/index.js

@@ -0,0 +1,5 @@
+export * from './catalog.js';
+export * from './ordered-feed.js';
+export * from './types.js';
+export * from './actions.js';
+//# sourceMappingURL=index.js.map

package/dist/contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}

package/dist/contract/ordered-feed.d.ts

@@ -0,0 +1,56 @@
+/**
+ * One subscriber's view of a positioned log (run events, runner commands):
+ * everything after its cursor, in order, once each, with nothing missing.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The old stream replayed history, THEN subscribed to live events. Anything
+ * written while the history query ran fell between the two and was never
+ * shown. And live delivery across instances is a pointer read back from the
+ * database, so two events can arrive out of order, and a pointer lost while
+ * the listener reconnects is lost for good.
+ *
+ * The feed fixes all three by trusting only the database's order (`pos`):
+ * - live rows are OFFERED from the moment the subscriber exists, and wait
+ *   behind the history replay rather than racing it;
+ * - a row that skips ahead makes the feed read the missing range first;
+ * - `catchUp()` (called on a timer) reads anything a lost pointer hid.
+ *
+ * Holes in `pos` are fine: position N+1 never commits before N has committed
+ * or rolled back (migration 239), so "everything after my cursor" read after
+ * seeing N+1 is complete.
+ */
+export interface Positioned {
+    pos: number | null;
+}
+export type FetchAfter<T> = (after: number, limit: number) => Promise<T[]>;
+export declare const FEED_PAGE = 500;
+export declare class OrderedFeed<T extends Positioned> {
+    private readonly fetchAfter;
+    private readonly emit;
+    private readonly onError;
+    private last;
+    private chain;
+    private closed;
+    constructor(start: number, fetchAfter: FetchAfter<T>, emit: (row: T) => void, onError?: (error: unknown) => void);
+    /** The position of the last row emitted. */
+    get cursor(): number;
+    /**
+     * 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?: (row: T) => boolean): Promise<void>;
+    /** A live row. Emitted in order; a skip ahead reads the gap first. */
+    offer(row: T): Promise<void>;
+    /** Read anything after the cursor that live delivery didn't bring. */
+    catchUp(): Promise<void>;
+    /** Stop emitting. Pending work finishes silently. */
+    close(): void;
+    private push;
+    /** Emit stored rows after the cursor, up to `until` when given. */
+    private drain;
+    private enqueue;
+}

package/dist/contract/ordered-feed.js

@@ -0,0 +1,91 @@
+export const FEED_PAGE = 500;
+export 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, 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 < 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;
+    }
+}
+//# sourceMappingURL=ordered-feed.js.map

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

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