antpath 0.10.15 → 0.11.4

package/dist/_shared/operations.js

@@ -12,12 +12,6 @@ import { iterateSse } from "./sse.js";
  * `references/development-principles.md` (Agent-first surface design,
  * Concrete rule 3).
  */
-export async function submitRun(http, request) {
-    return http.request("/api/runs", {
-        method: "POST",
-        body: JSON.stringify(request)
-    });
-}
 export async function getRun(http, runId) {
     const result = await http.request(`/api/runs/${encodeURIComponent(runId)}`);
     return hasRun(result) ? result.run : result;
@@ -27,7 +21,7 @@ export async function getRun(http, runId) {
  * parsed submission inputs, attempts, indexed events (with
  * pagination cursor for large runs), raw-event Storage manifest,
  * outputs, capture failures, proxy-call audit, pinned skills,
- * provider skills, transient skills.
+ * provider skills, inline skills.
  *
  * Backed by the same `GET /api/runs/:runId` endpoint that
  * `getRun` calls; this variant just narrows the return type to
@@ -222,22 +216,22 @@ export async function downloadRunArchive(http, runId) {
     return response;
 }
 // ===========================================================================
-// Flat (Skill / McpServer / Blueprint) operations
+// Run submission operations (Skill / McpServer / Blueprint composition)
 // ===========================================================================
-export async function submitRunFlat(http, request) {
+export async function submitRun(http, request) {
     return http.request("/api/runs", {
         method: "POST",
         body: JSON.stringify(request)
     });
 }
 /**
- * Multipart variant of `submitRunFlat` for runs that carry transient
+ * Multipart variant of `submitRun` for runs that carry transient
  * (per-run) skill bundles and/or transient AgentsMd content.
  *
  * The JSON submission travels as the `submission` part; each
- * `TransientSkillRef.slot` in `request.submission.skills` MUST be
+ * `InlineSkillRef.slot` in `request.submission.skills` MUST be
  * mirrored by exactly one `skill:<slot>` part with the bundle bytes.
- * Each `TransientAgentsMdRef.slot` in `request.submission.agentsMd`
+ * Each `InlineAgentsMdRef.slot` in `request.submission.agentsMd`
  * MUST be mirrored by exactly one `agentsmd:<slot>` part with the
  * markdown text.
  *
@@ -246,12 +240,12 @@ export async function submitRunFlat(http, request) {
  *
  * At least one of `bundles` or `agentsMdParts` must be non-empty.
  */
-export async function submitRunFlatMultipart(http, request, bundles, agentsMdParts, fileParts) {
+export async function submitRunMultipart(http, request, bundles, agentsMdParts, fileParts) {
     const hasBundles = Array.isArray(bundles) && bundles.length > 0;
     const hasAgentsMd = Array.isArray(agentsMdParts) && agentsMdParts.length > 0;
     const hasFiles = Array.isArray(fileParts) && fileParts.length > 0;
     if (!hasBundles && !hasAgentsMd && !hasFiles) {
-        throw new Error("submitRunFlatMultipart: bundles, agentsMdParts, or fileParts must be non-empty");
+        throw new Error("submitRunMultipart: bundles, agentsMdParts, or fileParts must be non-empty");
     }
     const form = new FormData();
     // Submission rides as a typed JSON Blob so the BFF reads
@@ -261,10 +255,10 @@ export async function submitRunFlatMultipart(http, request, bundles, agentsMdPar
     const seen = new Set();
     for (const bundle of bundles) {
         if (typeof bundle.slot !== "string" || !bundle.slot) {
-            throw new Error("submitRunFlatMultipart: each bundle must have a non-empty slot id");
+            throw new Error("submitRunMultipart: each bundle must have a non-empty slot id");
         }
         if (seen.has(bundle.slot)) {
-            throw new Error(`submitRunFlatMultipart: duplicate transient skill slot "${bundle.slot}"`);
+            throw new Error(`submitRunMultipart: duplicate inline skill slot "${bundle.slot}"`);
         }
         seen.add(bundle.slot);
         const blob = toBlob(bundle.bytes, "application/zip");
@@ -272,11 +266,11 @@ export async function submitRunFlatMultipart(http, request, bundles, agentsMdPar
     }
     for (const part of agentsMdParts ?? []) {
         if (typeof part.slot !== "string" || !part.slot) {
-            throw new Error("submitRunFlatMultipart: each agentsMd part must have a non-empty slot id");
+            throw new Error("submitRunMultipart: each agentsMd part must have a non-empty slot id");
         }
         const partKey = `agentsmd:${part.slot}`;
         if (seen.has(partKey)) {
-            throw new Error(`submitRunFlatMultipart: duplicate agentsMd slot "${part.slot}"`);
+            throw new Error(`submitRunMultipart: duplicate agentsMd slot "${part.slot}"`);
         }
         seen.add(partKey);
         const blob = new Blob([part.content], { type: "text/plain" });
@@ -284,11 +278,11 @@ export async function submitRunFlatMultipart(http, request, bundles, agentsMdPar
     }
     for (const part of fileParts ?? []) {
         if (typeof part.slot !== "string" || !part.slot) {
-            throw new Error("submitRunFlatMultipart: each file part must have a non-empty slot id");
+            throw new Error("submitRunMultipart: each file part must have a non-empty slot id");
         }
         const partKey = `file:${part.slot}`;
         if (seen.has(partKey)) {
-            throw new Error(`submitRunFlatMultipart: duplicate file slot "${part.slot}"`);
+            throw new Error(`submitRunMultipart: duplicate file slot "${part.slot}"`);
         }
         seen.add(partKey);
         const blob = toBlob(part.bytes, "application/zip");

package/dist/_shared/provider-proxy-url.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Per-run Antpath provider proxy URL + bearer minting types.
+ *
+ * The provider proxy is the second of Antpath's two
+ * runtime-independent proxies (the other is the MCP proxy in
+ * `./mcp-proxy-url.ts`). It sits between the self-hosted runner and
+ * the customer's provider API — today that's DeepSeek's
+ * Anthropic-compatible endpoint, but the route is namespaced so
+ * additional providers slot in without a wire-format change.
+ *
+ * The runner container sees only `ANTHROPIC_BASE_URL=<proxy-url>` and
+ * `ANTHROPIC_AUTH_TOKEN=<scoped-bearer>`; the real provider key + base
+ * URL stay in the run Vault bundle. See
+ * `references/deepseek-runtime-mcp-plan.md` (Provider proxy +
+ * Security requirements).
+ */
+import type { RunProvider } from "./submission.js";
+/**
+ * Platform-reserved key under which the per-run provider proxy bearer
+ * is folded into the Vault bundle. Distinct from
+ * `__antpath_proxy_token` (customer-declared HTTP proxy) and
+ * `__antpath_mcp_proxy_token` (MCP proxy) so the three capabilities
+ * are revoked independently. The shared `parseInlineSecrets` rejects
+ * any inbound submission whose `secrets` carries a key with the
+ * `__antpath_` prefix; only the BFF mutates this after the parser.
+ */
+export declare const PROVIDER_PROXY_BEARER_BUNDLE_KEY = "__antpath_provider_proxy_token";
+/**
+ * Output of the per-run provider proxy bearer mint. Same primitive
+ * (high-entropy random + peppered SHA-256) as the customer-proxy +
+ * MCP-proxy mints; persisted in dedicated columns / Vault keys so
+ * the three capabilities don't share a fate.
+ */
+export interface MintedProviderProxyBearer {
+    readonly plaintext: string;
+    readonly hash: string;
+    readonly expiresAt: Date;
+}
+/**
+ * DeepSeek's documented Anthropic-compatibility endpoint. Used by the
+ * provider proxy as the default upstream when the customer does not
+ * supply `secrets.deepseek.baseUrl`. Subject to DeepSeek's own
+ * upstream changes — see `references/deepseek-runtime-mcp-plan.md`
+ * (Source facts to re-check).
+ */
+export declare const DEEPSEEK_ANTHROPIC_COMPAT_DEFAULT_BASE_URL = "https://api.deepseek.com/anthropic";
+/**
+ * Canonical URL path of the per-run provider proxy endpoint. The BFF
+ * route lives at `/api/runs/[runId]/provider-proxy/[providerName]`;
+ * the runner / runtime receives the absolute URL from
+ * {@link buildProviderProxyUrl}.
+ */
+export declare function providerProxyPath(runId: string, provider: RunProvider): string;
+/**
+ * Build the absolute per-run, per-provider proxy URL. `baseUrl` is the
+ * configured Antpath API plane root (e.g. `https://api.antpath.ai`);
+ * the function strips any trailing slash and appends the canonical
+ * provider proxy path.
+ */
+export declare function buildProviderProxyUrl(args: {
+    readonly baseUrl: string;
+    readonly runId: string;
+    readonly provider: RunProvider;
+}): string;

package/dist/_shared/provider-proxy-url.js

@@ -0,0 +1,73 @@
+/**
+ * Per-run Antpath provider proxy URL + bearer minting types.
+ *
+ * The provider proxy is the second of Antpath's two
+ * runtime-independent proxies (the other is the MCP proxy in
+ * `./mcp-proxy-url.ts`). It sits between the self-hosted runner and
+ * the customer's provider API — today that's DeepSeek's
+ * Anthropic-compatible endpoint, but the route is namespaced so
+ * additional providers slot in without a wire-format change.
+ *
+ * The runner container sees only `ANTHROPIC_BASE_URL=<proxy-url>` and
+ * `ANTHROPIC_AUTH_TOKEN=<scoped-bearer>`; the real provider key + base
+ * URL stay in the run Vault bundle. See
+ * `references/deepseek-runtime-mcp-plan.md` (Provider proxy +
+ * Security requirements).
+ */
+/**
+ * Platform-reserved key under which the per-run provider proxy bearer
+ * is folded into the Vault bundle. Distinct from
+ * `__antpath_proxy_token` (customer-declared HTTP proxy) and
+ * `__antpath_mcp_proxy_token` (MCP proxy) so the three capabilities
+ * are revoked independently. The shared `parseInlineSecrets` rejects
+ * any inbound submission whose `secrets` carries a key with the
+ * `__antpath_` prefix; only the BFF mutates this after the parser.
+ */
+export const PROVIDER_PROXY_BEARER_BUNDLE_KEY = "__antpath_provider_proxy_token";
+/**
+ * DeepSeek's documented Anthropic-compatibility endpoint. Used by the
+ * provider proxy as the default upstream when the customer does not
+ * supply `secrets.deepseek.baseUrl`. Subject to DeepSeek's own
+ * upstream changes — see `references/deepseek-runtime-mcp-plan.md`
+ * (Source facts to re-check).
+ */
+export const DEEPSEEK_ANTHROPIC_COMPAT_DEFAULT_BASE_URL = "https://api.deepseek.com/anthropic";
+/**
+ * Canonical URL path of the per-run provider proxy endpoint. The BFF
+ * route lives at `/api/runs/[runId]/provider-proxy/[providerName]`;
+ * the runner / runtime receives the absolute URL from
+ * {@link buildProviderProxyUrl}.
+ */
+export function providerProxyPath(runId, provider) {
+    if (!runId || typeof runId !== "string") {
+        throw new Error("providerProxyPath: runId must be a non-empty string");
+    }
+    if (provider !== "anthropic" && provider !== "deepseek") {
+        throw new Error(`providerProxyPath: unsupported provider ${JSON.stringify(provider)}`);
+    }
+    return `/api/runs/${encodeURIComponent(runId)}/provider-proxy/${provider}`;
+}
+/**
+ * Build the absolute per-run, per-provider proxy URL. `baseUrl` is the
+ * configured Antpath API plane root (e.g. `https://api.antpath.ai`);
+ * the function strips any trailing slash and appends the canonical
+ * provider proxy path.
+ */
+export function buildProviderProxyUrl(args) {
+    if (!args.baseUrl || typeof args.baseUrl !== "string") {
+        throw new Error("buildProviderProxyUrl: baseUrl must be a non-empty string");
+    }
+    let parsedBase;
+    try {
+        parsedBase = new URL(args.baseUrl);
+    }
+    catch {
+        throw new Error(`buildProviderProxyUrl: baseUrl is not a valid URL: ${args.baseUrl}`);
+    }
+    if (parsedBase.protocol !== "https:" && parsedBase.protocol !== "http:") {
+        throw new Error(`buildProviderProxyUrl: baseUrl protocol must be http or https (got ${parsedBase.protocol})`);
+    }
+    const trimmedBase = `${parsedBase.origin}${parsedBase.pathname.replace(/\/+$/, "")}`;
+    return `${trimmedBase}${providerProxyPath(args.runId, args.provider)}`;
+}
+//# sourceMappingURL=provider-proxy-url.js.map

package/dist/_shared/proxy-validation.d.ts

@@ -14,6 +14,6 @@ export declare function validateProxyAuth(endpoints: readonly PlatformProxyEndpo
  * caller is hand-rolling networking.
  */
 export declare function buildPlatformAllowedHosts(input: {
-    readonly dashboardBaseUrl: string;
+    readonly baseUrl: string;
     readonly extraHosts?: readonly string[];
 }): readonly string[];

package/dist/_shared/proxy-validation.js

@@ -37,10 +37,10 @@ export function validateProxyAuth(endpoints, auth) {
 export function buildPlatformAllowedHosts(input) {
     const result = [];
     try {
-        result.push(new URL(input.dashboardBaseUrl).host);
+        result.push(new URL(input.baseUrl).host);
     }
     catch {
-        throw new Error("buildPlatformAllowedHosts: dashboardBaseUrl must be an absolute URL");
+        throw new Error("buildPlatformAllowedHosts: baseUrl must be an absolute URL");
     }
     for (const host of input.extraHosts ?? []) {
         if (!result.includes(host))

package/dist/_shared/run-unit.d.ts

@@ -19,36 +19,16 @@
  * `rawEventPages` (manifest only; bytes downloaded out-of-band so the
  * detail response stays bounded). The archive zip carries the bytes.
  */
-import type { JsonValue, PlatformCleanupPolicy, PlatformFlatSubmission, PlatformProxyEndpoint, PlatformTemplateSubmission } from "./submission.js";
+import type { JsonValue, PlatformCleanupPolicy, PlatformSubmission, PlatformProxyEndpoint } from "./submission.js";
 /**
- * Parsed view of `runs.template_snapshot` jsonb. Two historical shapes
- * coexist in storage:
- *
- *   - `kind: "flat"` (current): {kind:"flat", submission, cleanup?}
- *     written by `insertRunWithSkillSnapshots` for all new runs.
- *   - legacy template-shaped: {template, executionPayloadSecretId,
- *     variables?, cleanup?} written by `insertRun` before the flat
- *     pivot.
- *
- * The parser tolerates both and returns a discriminated union so
- * consumers branch mechanically. New work targets `kind: "flat"`.
- *
- * Note on legacy redaction: historic template-shaped snapshots have
- * `system` and `messages` replaced with `"[redacted]"` by
- * `redactTemplateForMetadata`. That redaction predates the raw-event /
- * raw-input policy update and we do not retroactively un-redact data we
- * never stored. Flat-shape snapshots are verbatim.
+ * Parsed view of `runs.template_snapshot` jsonb. Stored shape is
+ * `{kind:"submission", submission, cleanup?}` written by
+ * `insertRunWithSkillSnapshots` for all runs.
  */
-export type RunUnitSubmission = RunUnitFlatSubmission | RunUnitTemplateSubmission;
+export type RunUnitSubmission = RunUnitFlatSubmission;
 export interface RunUnitFlatSubmission {
-    readonly kind: "flat";
-    readonly submission: PlatformFlatSubmission;
-    readonly cleanup?: PlatformCleanupPolicy;
-}
-export interface RunUnitTemplateSubmission {
-    readonly kind: "template";
-    readonly template: PlatformTemplateSubmission;
-    readonly variables?: Record<string, JsonValue>;
+    readonly kind: "submission";
+    readonly submission: PlatformSubmission;
     readonly cleanup?: PlatformCleanupPolicy;
 }
 export interface RunUnitAttempt {
@@ -157,7 +137,7 @@ export interface RunUnitProviderSkill {
     readonly skillId: string;
     readonly version?: string;
 }
-export interface RunUnitTransientSkill {
+export interface RunUnitInlineSkill {
     readonly id: string;
     readonly slotId: string;
     readonly skillName: string;
@@ -190,17 +170,24 @@ export interface RunUnit {
     readonly proxyCalls: RunUnitProxyCallPage;
     readonly skillSnapshots: readonly RunUnitSkillSnapshot[];
     readonly providerSkills: readonly RunUnitProviderSkill[];
-    readonly transientSkills: readonly RunUnitTransientSkill[];
+    readonly inlineSkills: readonly RunUnitInlineSkill[];
+    /**
+     * Per-run, per-provider runtime manifest — derived from the validated
+     * submission + the chosen provider (`buildRuntimeManifest`). Tells
+     * SDK consumers where antpath placed things in-container and what
+     * env vars the agent will see. Undefined on responses from BFFs
+     * that predate Phase 2 of the runtime-environment rollout.
+     */
+    readonly runtimeManifest?: import("./runtime-manifest.js").RuntimeManifest;
 }
 /**
- * Parse a `runs.template_snapshot` jsonb payload into the typed
- * discriminated union. Tolerates both flat and legacy template shapes;
- * never throws on minor unknown keys so we can forward-compat with
- * worker-side enrichment.
+ * Parse a `runs.template_snapshot` jsonb payload into the typed flat
+ * submission. Never throws on minor unknown keys so we can
+ * forward-compat with worker-side enrichment.
  *
  * Returns a typed shape even for malformed snapshots — the worst case
- * is `{kind: "flat", submission: {model: "", ...}}` with empty defaults
- * — because the dashboard must still render *something* for a buggy
- * historical row rather than 500ing the whole detail page.
+ * is `{kind: "submission", submission: {model: "", ...}}` with empty
+ * defaults — because the dashboard must still render *something* for a
+ * buggy historical row rather than 500ing the whole detail page.
  */
 export declare function parseRunUnitSubmission(input: unknown): RunUnitSubmission;

package/dist/_shared/run-unit.js

@@ -24,29 +24,25 @@ import { parseMcpServerRef, parseSkillRef } from "./blueprint.js";
 // Submission parser
 // ---------------------------------------------------------------------------
 /**
- * Parse a `runs.template_snapshot` jsonb payload into the typed
- * discriminated union. Tolerates both flat and legacy template shapes;
- * never throws on minor unknown keys so we can forward-compat with
- * worker-side enrichment.
+ * Parse a `runs.template_snapshot` jsonb payload into the typed flat
+ * submission. Never throws on minor unknown keys so we can
+ * forward-compat with worker-side enrichment.
  *
  * Returns a typed shape even for malformed snapshots — the worst case
- * is `{kind: "flat", submission: {model: "", ...}}` with empty defaults
- * — because the dashboard must still render *something* for a buggy
- * historical row rather than 500ing the whole detail page.
+ * is `{kind: "submission", submission: {model: "", ...}}` with empty
+ * defaults — because the dashboard must still render *something* for a
+ * buggy historical row rather than 500ing the whole detail page.
  */
 export function parseRunUnitSubmission(input) {
     if (!input || typeof input !== "object" || Array.isArray(input)) {
         return fallbackFlat();
     }
     const value = input;
-    if (value.kind === "flat") {
+    if (value.kind === "submission") {
         return parseFlatProjection(value);
     }
-    if (isRecord(value.template)) {
-        return parseTemplateProjection(value);
-    }
-    // Snapshot exists but matches neither shape — surface as an empty
-    // flat submission so consumers can still render lifecycle bits.
+    // Snapshot exists but does not match the flat shape — surface as an
+    // empty flat submission so consumers can still render lifecycle bits.
     return fallbackFlat();
 }
 function parseFlatProjection(value) {
@@ -69,36 +65,14 @@ function parseFlatProjection(value) {
             : {})
     };
     return {
-        kind: "flat",
+        kind: "submission",
         submission,
         ...(cleanup ? { cleanup } : {})
     };
 }
-function parseTemplateProjection(value) {
-    const templateRaw = value.template;
-    const template = {
-        name: typeof templateRaw.name === "string" ? templateRaw.name : "",
-        model: typeof templateRaw.model === "string" ? templateRaw.model : "",
-        templateHash: typeof templateRaw.templateHash === "string" ? templateRaw.templateHash : "",
-        messages: toStringArray(templateRaw.messages),
-        ...(typeof templateRaw.system === "string" ? { system: templateRaw.system } : {}),
-        ...(isJsonRecord(templateRaw.metadata) ? { metadata: templateRaw.metadata } : {}),
-        ...(parseEnvironment(templateRaw.environment)
-            ? { environment: parseEnvironment(templateRaw.environment) }
-            : {})
-    };
-    const variables = isJsonRecord(value.variables) ? value.variables : undefined;
-    const cleanup = parseCleanup(value.cleanup);
-    return {
-        kind: "template",
-        template,
-        ...(variables ? { variables } : {}),
-        ...(cleanup ? { cleanup } : {})
-    };
-}
 function fallbackFlat() {
     return {
-        kind: "flat",
+        kind: "submission",
         submission: {
             model: "",
             prompt: [],
@@ -140,7 +114,7 @@ function toSkillRefArray(value) {
     const out = [];
     for (let i = 0; i < value.length; i++) {
         try {
-            out.push(parseSkillRef(value[i], `submission.skills[${i}]`, { allowTransient: true }));
+            out.push(parseSkillRef(value[i], `submission.skills[${i}]`));
         }
         catch {
             // Skip malformed entries rather than failing the whole detail
@@ -195,7 +169,22 @@ function parseEnvironment(value) {
             env.packages = pkgs;
         }
     }
-    return env.networking || env.packages
+    // Lenient pass-through for envVars stored in already-validated
+    // snapshots. The strict parser in submission.ts enforces shape /
+    // size / reserved-prefix rules at submission time; here we just
+    // accept whatever shape was persisted.
+    if (isRecord(value.envVars)) {
+        const out = {};
+        for (const [k, v] of Object.entries(value.envVars)) {
+            if (typeof v === "string") {
+                out[k] = v;
+            }
+        }
+        if (Object.keys(out).length > 0) {
+            env.envVars = out;
+        }
+    }
+    return env.networking || env.packages || env.envVars
         ? env
         : undefined;
 }
@@ -204,14 +193,9 @@ function parseCleanup(value) {
         return undefined;
     }
     const session = value.session;
-    const claudeSession = value.claudeSession;
-    const out = {};
     if (session === "retain" || session === "delete") {
-        out.session = session;
-    }
-    if (claudeSession === "retain" || claudeSession === "delete") {
-        out.claudeSession = claudeSession;
+        return { session };
     }
-    return out.session || out.claudeSession ? out : undefined;
+    return undefined;
 }
 //# sourceMappingURL=run-unit.js.map

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;