antpath 0.10.14 → 0.11.0

package/dist/_shared/runner-event.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Unified runner event schema. Both runtimes feed the same shape into
+ * the api.antpath.ai event pipeline:
+ *
+ *   - **Anthropic Native** — the `AnthropicSseInbox` Durable Object
+ *     consumes Anthropic's `/v1/messages/stream` SSE stream and uses
+ *     the Anthropic adapter to translate each event into one or more
+ *     `RunnerEvent`s.
+ *   - **Goose Managed** — the per-run runner image POSTs batches of
+ *     NDJSON events to `/runs/{id}/runner/events`; the Goose adapter
+ *     translates each event into one or more `RunnerEvent`s.
+ *
+ * The downstream subscribers (dashboard, SDK `streamEvents`, observable
+ * spans) never see the runtime-specific wire shapes — they only see
+ * `RunnerEvent`s. This is the cutover boundary that makes the dual
+ * runtime invisible to customers.
+ *
+ * See `references/platform-rebuild-2026.md` (Wire contracts →
+ * runner-event).
+ */
+import type { JsonValue } from "./submission.js";
+/**
+ * Schema version. Bump when the shape of `RunnerEvent`, its kind set,
+ * or the batch envelope changes. Subscribers gate on this so a future
+ * v2 wire shape can land behind a feature flag.
+ */
+export declare const RUNNER_EVENT_VERSION: 1;
+/**
+ * The set of event kinds emitted into the unified stream. Adapters
+ * fold runtime-specific events into one of these — anything that
+ * doesn't fit is mapped to `notification` so the data is captured
+ * even when no UI handler exists yet.
+ *
+ *   - `runtime_started`  — either runtime announced "ready" (Fly
+ *                          machine running goose; Anthropic session
+ *                          accepted the first turn).
+ *   - `assistant_text`   — model text delta.
+ *   - `tool_request`     — model emitted a tool_use / function call.
+ *   - `tool_response`    — tool result delivered back to the model.
+ *   - `skill_loaded`     — a skill was loaded (Anthropic Skills API
+ *                          ref OR a workspace folder mount).
+ *   - `file_uploaded`    — a file became available to the agent
+ *                          (Files API id OR workspace path).
+ *   - `notification`     — runtime/extension notification; catch-all
+ *                          for diagnostic data.
+ *   - `stream_error`     — stream-level error (non-fatal). Subscribers
+ *                          may surface this as a UI warning; the run
+ *                          continues unless `runtime_terminal` follows.
+ *   - `runtime_terminal` — the run reached a terminal state. The
+ *                          adapter MUST emit exactly one of these per
+ *                          run; subscribers gate on it for end-of-stream.
+ */
+export declare const RUNNER_EVENT_KINDS: readonly ["runtime_started", "assistant_text", "tool_request", "tool_response", "skill_loaded", "file_uploaded", "notification", "stream_error", "runtime_terminal"];
+export type RunnerEventKind = (typeof RUNNER_EVENT_KINDS)[number];
+/**
+ * One event in the unified stream. `seq` is monotonically increasing
+ * within a single run (the adapter is responsible for assigning seqs
+ * — no two events with the same `seq` for the same `runId`); `tMs` is
+ * a millisecond-resolution timestamp that is also monotonically
+ * non-decreasing within a single run (an event's `tMs` is never less
+ * than the previous event's `tMs`). `data` carries the runtime- and
+ * kind-specific payload, JSON-typed so the batch round-trips through
+ * the database column without ad-hoc serialization.
+ */
+export interface RunnerEvent {
+    readonly seq: number;
+    readonly tMs: number;
+    readonly kind: RunnerEventKind;
+    readonly data: Readonly<Record<string, JsonValue>>;
+}
+/**
+ * Batch envelope. The runner ships one or more events per POST so the
+ * inbox writes them atomically. `events` MUST be sorted by `seq`
+ * ascending; api.antpath.ai rejects malformed batches before touching
+ * Postgres.
+ */
+export interface RunnerEventBatch {
+    readonly v: typeof RUNNER_EVENT_VERSION;
+    readonly runId: string;
+    readonly events: readonly RunnerEvent[];
+}
+/**
+ * Maximum number of events per batch. Bounds the size of the body
+ * api.antpath.ai accepts and the size of the Durable Object write.
+ * Larger streams are split into multiple batches; the runner is
+ * responsible for chunking.
+ */
+export declare const RUNNER_EVENT_BATCH_MAX_EVENTS: 256;
+/**
+ * Validation outcome for an inbound batch. The `ok` branch returns
+ * the parsed batch with frozen events; the `error` branch returns the
+ * code + a short human message suitable for an HTTP 400 body. Codes
+ * are stable strings — the dashboard / SDK may branch on them.
+ */
+export type RunnerEventBatchValidation = {
+    readonly ok: true;
+    readonly batch: RunnerEventBatch;
+} | {
+    readonly ok: false;
+    readonly code: RunnerEventBatchValidationCode;
+    readonly message: string;
+};
+export declare const RUNNER_EVENT_BATCH_VALIDATION_CODES: readonly ["invalid_envelope", "version_mismatch", "missing_run_id", "empty_batch", "batch_too_large", "invalid_event", "seq_not_monotonic", "t_ms_not_monotonic"];
+export type RunnerEventBatchValidationCode = (typeof RUNNER_EVENT_BATCH_VALIDATION_CODES)[number];
+/**
+ * Parse + validate an inbound runner event batch (untrusted input).
+ * Used at the api.antpath.ai ingress so adapters never have to
+ * re-check the wire shape, and used by tests to assert the contract.
+ *
+ * Successful validation guarantees:
+ *   - top-level envelope matches {@link RunnerEventBatch}
+ *   - `v === RUNNER_EVENT_VERSION`
+ *   - `runId` is a non-empty string
+ *   - `events` is a non-empty array of at most
+ *     {@link RUNNER_EVENT_BATCH_MAX_EVENTS} entries
+ *   - each event is a {@link RunnerEvent} with a known `kind`
+ *   - `seq` is strictly increasing across the batch
+ *   - `tMs` is non-decreasing across the batch
+ */
+export declare function validateRunnerEventBatch(input: unknown): RunnerEventBatchValidation;

package/dist/_shared/runner-event.js

@@ -0,0 +1,193 @@
+/**
+ * Unified runner event schema. Both runtimes feed the same shape into
+ * the api.antpath.ai event pipeline:
+ *
+ *   - **Anthropic Native** — the `AnthropicSseInbox` Durable Object
+ *     consumes Anthropic's `/v1/messages/stream` SSE stream and uses
+ *     the Anthropic adapter to translate each event into one or more
+ *     `RunnerEvent`s.
+ *   - **Goose Managed** — the per-run runner image POSTs batches of
+ *     NDJSON events to `/runs/{id}/runner/events`; the Goose adapter
+ *     translates each event into one or more `RunnerEvent`s.
+ *
+ * The downstream subscribers (dashboard, SDK `streamEvents`, observable
+ * spans) never see the runtime-specific wire shapes — they only see
+ * `RunnerEvent`s. This is the cutover boundary that makes the dual
+ * runtime invisible to customers.
+ *
+ * See `references/platform-rebuild-2026.md` (Wire contracts →
+ * runner-event).
+ */
+/**
+ * Schema version. Bump when the shape of `RunnerEvent`, its kind set,
+ * or the batch envelope changes. Subscribers gate on this so a future
+ * v2 wire shape can land behind a feature flag.
+ */
+export const RUNNER_EVENT_VERSION = 1;
+/**
+ * The set of event kinds emitted into the unified stream. Adapters
+ * fold runtime-specific events into one of these — anything that
+ * doesn't fit is mapped to `notification` so the data is captured
+ * even when no UI handler exists yet.
+ *
+ *   - `runtime_started`  — either runtime announced "ready" (Fly
+ *                          machine running goose; Anthropic session
+ *                          accepted the first turn).
+ *   - `assistant_text`   — model text delta.
+ *   - `tool_request`     — model emitted a tool_use / function call.
+ *   - `tool_response`    — tool result delivered back to the model.
+ *   - `skill_loaded`     — a skill was loaded (Anthropic Skills API
+ *                          ref OR a workspace folder mount).
+ *   - `file_uploaded`    — a file became available to the agent
+ *                          (Files API id OR workspace path).
+ *   - `notification`     — runtime/extension notification; catch-all
+ *                          for diagnostic data.
+ *   - `stream_error`     — stream-level error (non-fatal). Subscribers
+ *                          may surface this as a UI warning; the run
+ *                          continues unless `runtime_terminal` follows.
+ *   - `runtime_terminal` — the run reached a terminal state. The
+ *                          adapter MUST emit exactly one of these per
+ *                          run; subscribers gate on it for end-of-stream.
+ */
+export const RUNNER_EVENT_KINDS = [
+    "runtime_started",
+    "assistant_text",
+    "tool_request",
+    "tool_response",
+    "skill_loaded",
+    "file_uploaded",
+    "notification",
+    "stream_error",
+    "runtime_terminal"
+];
+/**
+ * Maximum number of events per batch. Bounds the size of the body
+ * api.antpath.ai accepts and the size of the Durable Object write.
+ * Larger streams are split into multiple batches; the runner is
+ * responsible for chunking.
+ */
+export const RUNNER_EVENT_BATCH_MAX_EVENTS = 256;
+export const RUNNER_EVENT_BATCH_VALIDATION_CODES = [
+    "invalid_envelope",
+    "version_mismatch",
+    "missing_run_id",
+    "empty_batch",
+    "batch_too_large",
+    "invalid_event",
+    "seq_not_monotonic",
+    "t_ms_not_monotonic"
+];
+/**
+ * Parse + validate an inbound runner event batch (untrusted input).
+ * Used at the api.antpath.ai ingress so adapters never have to
+ * re-check the wire shape, and used by tests to assert the contract.
+ *
+ * Successful validation guarantees:
+ *   - top-level envelope matches {@link RunnerEventBatch}
+ *   - `v === RUNNER_EVENT_VERSION`
+ *   - `runId` is a non-empty string
+ *   - `events` is a non-empty array of at most
+ *     {@link RUNNER_EVENT_BATCH_MAX_EVENTS} entries
+ *   - each event is a {@link RunnerEvent} with a known `kind`
+ *   - `seq` is strictly increasing across the batch
+ *   - `tMs` is non-decreasing across the batch
+ */
+export function validateRunnerEventBatch(input) {
+    if (!isRecord(input)) {
+        return invalid("invalid_envelope", "batch must be a JSON object");
+    }
+    if (input.v !== RUNNER_EVENT_VERSION) {
+        return invalid("version_mismatch", `batch.v must equal ${RUNNER_EVENT_VERSION} (got ${JSON.stringify(input.v)})`);
+    }
+    if (typeof input.runId !== "string" || input.runId.length === 0) {
+        return invalid("missing_run_id", "batch.runId must be a non-empty string");
+    }
+    if (!Array.isArray(input.events) || input.events.length === 0) {
+        return invalid("empty_batch", "batch.events must be a non-empty array");
+    }
+    if (input.events.length > RUNNER_EVENT_BATCH_MAX_EVENTS) {
+        return invalid("batch_too_large", `batch.events has ${input.events.length} entries; max is ${RUNNER_EVENT_BATCH_MAX_EVENTS}`);
+    }
+    let lastSeq = Number.NEGATIVE_INFINITY;
+    let lastTMs = Number.NEGATIVE_INFINITY;
+    const events = [];
+    for (let i = 0; i < input.events.length; i++) {
+        const evt = input.events[i];
+        if (!isRecord(evt)) {
+            return invalid("invalid_event", `events[${i}] must be a JSON object`);
+        }
+        if (typeof evt.seq !== "number" ||
+            !Number.isFinite(evt.seq) ||
+            !Number.isInteger(evt.seq) ||
+            evt.seq < 0) {
+            return invalid("invalid_event", `events[${i}].seq must be a non-negative integer`);
+        }
+        if (typeof evt.tMs !== "number" ||
+            !Number.isFinite(evt.tMs) ||
+            !Number.isInteger(evt.tMs) ||
+            evt.tMs < 0) {
+            return invalid("invalid_event", `events[${i}].tMs must be a non-negative integer`);
+        }
+        if (typeof evt.kind !== "string" ||
+            !RUNNER_EVENT_KINDS.includes(evt.kind)) {
+            return invalid("invalid_event", `events[${i}].kind must be one of: ${RUNNER_EVENT_KINDS.join(", ")} (got ${JSON.stringify(evt.kind)})`);
+        }
+        if (!isRecord(evt.data)) {
+            return invalid("invalid_event", `events[${i}].data must be a JSON object`);
+        }
+        if (!isJsonRecord(evt.data)) {
+            return invalid("invalid_event", `events[${i}].data must be JSON-serializable`);
+        }
+        if (evt.seq <= lastSeq) {
+            return invalid("seq_not_monotonic", `events[${i}].seq=${evt.seq} must be strictly greater than the previous seq=${lastSeq}`);
+        }
+        if (evt.tMs < lastTMs) {
+            return invalid("t_ms_not_monotonic", `events[${i}].tMs=${evt.tMs} must be >= the previous tMs=${lastTMs}`);
+        }
+        lastSeq = evt.seq;
+        lastTMs = evt.tMs;
+        events.push({
+            seq: evt.seq,
+            tMs: evt.tMs,
+            kind: evt.kind,
+            data: Object.freeze({ ...evt.data })
+        });
+    }
+    return {
+        ok: true,
+        batch: { v: RUNNER_EVENT_VERSION, runId: input.runId, events: Object.freeze(events) }
+    };
+}
+function invalid(code, message) {
+    return { ok: false, code, message };
+}
+function isRecord(input) {
+    return typeof input === "object" && input !== null && !Array.isArray(input);
+}
+function isJsonRecord(input) {
+    for (const value of Object.values(input)) {
+        if (!isJsonValue(value))
+            return false;
+    }
+    return true;
+}
+function isJsonValue(input) {
+    if (input === null)
+        return true;
+    const t = typeof input;
+    if (t === "string" || t === "boolean")
+        return true;
+    if (t === "number")
+        return Number.isFinite(input);
+    if (Array.isArray(input))
+        return input.every(isJsonValue);
+    if (isRecord(input)) {
+        for (const v of Object.values(input)) {
+            if (!isJsonValue(v))
+                return false;
+        }
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=runner-event.js.map

package/dist/_shared/runner-job.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Per-run runner job for the Goose Managed runtime.
+ *
+ * The Goose Managed runtime runs a Goose CLI process inside a per-run
+ * Fly Machine. This module defines the substrate-independent surface
+ * the api.antpath.ai Workflow consumes: the lifecycle statuses, the
+ * spec the dispatcher hands to an executor, and the `RunnerJobExecutor`
+ * interface every substrate implements (Fly today; tests use an
+ * in-memory fake).
+ *
+ * The Anthropic Native runtime does NOT route through this surface —
+ * Anthropic hosts the runtime. Only providers whose runtime Antpath
+ * hosts (deepseek, openai, gemini, mistral, plus the customer opt-in
+ * `runtime: "managed"` for anthropic) consume the executor.
+ *
+ * See `references/platform-rebuild-2026.md` (Wire contracts → runner-job).
+ */
+import type { RunProvider } from "./submission.js";
+/**
+ * Runner-job lifecycle statuses, in the order the api.antpath.ai
+ * Workflow walks them. The shared list is the source of truth — keep
+ * the DB CHECK constraint on `provider_runtime_jobs.status` in
+ * lockstep.
+ */
+export declare const PROVIDER_RUNTIME_JOB_STATUSES: readonly ["queued", "provisioning", "running", "stopping", "terminated", "failed"];
+export type ProviderRuntimeJobStatus = (typeof PROVIDER_RUNTIME_JOB_STATUSES)[number];
+/**
+ * Substrate identifier — the executor implementation behind the job.
+ * `fly` is the only kind today; the platform-rebuild-2026 migration
+ * dropped the `railway` kind. Listed as a tuple so adding a new
+ * substrate is one line + a matching executor implementation.
+ */
+export declare const PROVIDER_RUNTIME_KINDS: readonly ["fly"];
+export type ProviderRuntimeKind = (typeof PROVIDER_RUNTIME_KINDS)[number];
+/**
+ * What the api.antpath.ai Workflow hands an executor to start a new
+ * runner job. The runner-image, env vars, region, and resource budget
+ * are decided ahead of time so the executor only has to call the
+ * substrate API.
+ */
+export interface RunnerJobSpec {
+    readonly runId: string;
+    readonly workspaceId: string;
+    readonly provider: RunProvider;
+    /**
+     * Container image reference (Docker registry name + sha256 digest).
+     * Pinned by the Workflow at provision time; not derived from the
+     * submission so customers cannot select an arbitrary image.
+     */
+    readonly image: string;
+    /**
+     * Environment variables the executor must set on the container.
+     * The Workflow injects:
+     *   - `ANTPATH_RUN_ID` + `ANTPATH_API_BASE` + `ANTPATH_RUNNER_TOKEN`
+     *     so the runner can call back to api.antpath.ai for manifests
+     *     and event POSTs.
+     *   - `ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` (or the
+     *     equivalent provider proxy URL + bearer) so Goose talks to
+     *     LiteLLM through the run-scoped proxy.
+     *   - `ANTPATH_MCP_BASE` if the submission carries MCP servers.
+     */
+    readonly env: Readonly<Record<string, string>>;
+    /**
+     * Hard ceiling on the substrate-side run duration. The runner image
+     * also enforces its own timeout; this is the last line of defence
+     * against a wedged container.
+     */
+    readonly maxRunDurationMs: number;
+    /**
+     * Substrate region (e.g. `"lhr"` for Fly London). Co-located with
+     * the LiteLLM gateway so the LLM call doesn't cross a region
+     * boundary inside the trust zone.
+     */
+    readonly region: string;
+    /**
+     * Optional resource budget. Each substrate maps these to its own
+     * machine sizing primitives (Fly: `vm.cpus` + `vm.memory_mb`).
+     * Omitting accepts the substrate default.
+     */
+    readonly resources?: {
+        readonly cpus: number;
+        readonly memoryMb: number;
+    };
+}
+/**
+ * Substrate-side identifiers for a started job. The Fly executor
+ * returns `appName` + `machineId`; tests with the in-memory fake
+ * return deterministic values. The handle MUST round-trip through
+ * Postgres (`provider_runtime_jobs.fly_app_name` /
+ * `.fly_machine_id`) so a restarted Worker can poll status without
+ * needing the in-memory executor state.
+ */
+export interface RunnerJobHandle {
+    readonly appName: string;
+    readonly machineId: string;
+}
+/**
+ * Optional resource metrics returned by `getStatus`. Surface what the
+ * substrate publishes; absent fields are reported as `undefined`. The
+ * Workflow forwards these into the `run_events` stream under the
+ * `notification` kind so dashboards have a cheap signal that the job
+ * is alive and within budget.
+ */
+export interface ResourceStats {
+    readonly cpuPercent?: number;
+    readonly memoryMb?: number;
+    readonly networkRxBytes?: number;
+    readonly networkTxBytes?: number;
+}
+export interface RunnerJobStatusSnapshot {
+    readonly status: ProviderRuntimeJobStatus;
+    readonly terminalErrorClass?: string;
+    readonly terminalErrorMessage?: string;
+    readonly resourceStats?: ResourceStats;
+}
+/**
+ * The substrate-independent runner-job surface. Implementations live
+ * in `apps/api/src/runtimes/goose/runners/<kind>/` (e.g.
+ * `runners/fly/`); test fakes live alongside.
+ *
+ * Method semantics:
+ *   - `start(spec)` provisions the runtime container and returns the
+ *     substrate-specific ids the Workflow should persist in
+ *     `provider_runtime_jobs`. MUST be idempotent under retry by
+ *     `spec.runId` — duplicate calls return the same ids.
+ *   - `getStatus(handle)` polls the substrate for the current status
+ *     plus any new terminal error info and optional resource metrics.
+ *   - `stop(handle)` initiates a graceful shutdown of the container.
+ *     Used on cancel, timeout, and at provider-terminal cleanup.
+ *     MUST be idempotent — operators may invoke it manually on a
+ *     stuck job. `graceMs` is an upper bound on the substrate's
+ *     SIGTERM → SIGKILL window.
+ *   - `tailLogs(handle, lines?)` returns the most recent stdout/err
+ *     bytes from the container (best-effort; substrates without log
+ *     retention may return `null`). Used by the dashboard "view logs"
+ *     button.
+ *   - `getConsoleUrl(handle)` returns a human-clickable URL into the
+ *     substrate console for on-call debugging. Optional — substrates
+ *     without a console simply omit the method.
+ */
+export interface RunnerJobExecutor {
+    start(spec: RunnerJobSpec): Promise<RunnerJobHandle>;
+    getStatus(handle: RunnerJobHandle): Promise<RunnerJobStatusSnapshot>;
+    stop(handle: RunnerJobHandle, opts?: {
+        readonly graceMs?: number;
+    }): Promise<void>;
+    tailLogs?(handle: RunnerJobHandle, lines?: number): Promise<string | null>;
+    getConsoleUrl?(handle: RunnerJobHandle): string;
+}
+/**
+ * Thrown when a submission selects a provider whose runtime is not
+ * yet implemented (e.g. a future provider added to RUN_PROVIDERS
+ * before its executor lands). Surfaced uniformly so the dashboard
+ * and the SDK render the same error code.
+ */
+export declare class RunnerRuntimeNotImplementedError extends Error {
+    readonly provider: RunProvider;
+    constructor(provider: RunProvider);
+}

package/dist/_shared/runner-job.js

@@ -0,0 +1,54 @@
+/**
+ * Per-run runner job for the Goose Managed runtime.
+ *
+ * The Goose Managed runtime runs a Goose CLI process inside a per-run
+ * Fly Machine. This module defines the substrate-independent surface
+ * the api.antpath.ai Workflow consumes: the lifecycle statuses, the
+ * spec the dispatcher hands to an executor, and the `RunnerJobExecutor`
+ * interface every substrate implements (Fly today; tests use an
+ * in-memory fake).
+ *
+ * The Anthropic Native runtime does NOT route through this surface —
+ * Anthropic hosts the runtime. Only providers whose runtime Antpath
+ * hosts (deepseek, openai, gemini, mistral, plus the customer opt-in
+ * `runtime: "managed"` for anthropic) consume the executor.
+ *
+ * See `references/platform-rebuild-2026.md` (Wire contracts → runner-job).
+ */
+/**
+ * Runner-job lifecycle statuses, in the order the api.antpath.ai
+ * Workflow walks them. The shared list is the source of truth — keep
+ * the DB CHECK constraint on `provider_runtime_jobs.status` in
+ * lockstep.
+ */
+export const PROVIDER_RUNTIME_JOB_STATUSES = [
+    "queued",
+    "provisioning",
+    "running",
+    "stopping",
+    "terminated",
+    "failed"
+];
+/**
+ * Substrate identifier — the executor implementation behind the job.
+ * `fly` is the only kind today; the platform-rebuild-2026 migration
+ * dropped the `railway` kind. Listed as a tuple so adding a new
+ * substrate is one line + a matching executor implementation.
+ */
+export const PROVIDER_RUNTIME_KINDS = ["fly"];
+/**
+ * Thrown when a submission selects a provider whose runtime is not
+ * yet implemented (e.g. a future provider added to RUN_PROVIDERS
+ * before its executor lands). Surfaced uniformly so the dashboard
+ * and the SDK render the same error code.
+ */
+export class RunnerRuntimeNotImplementedError extends Error {
+    provider;
+    constructor(provider) {
+        super(`runner runtime for provider "${provider}" is not implemented yet — ` +
+            `see references/platform-rebuild-2026.md (implementation phases)`);
+        this.name = "RunnerRuntimeNotImplementedError";
+        this.provider = provider;
+    }
+}
+//# sourceMappingURL=runner-job.js.map