antpath 0.10.15 → 0.11.4

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

package/dist/_shared/runtime-manifest.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Runtime manifest: the per-run, per-provider description of where
+ * antpath places things inside the agent container, plus the merged
+ * env-var bag delivered via `RUNTIME.env` / `RUNTIME.json`.
+ *
+ * Two consumers, one source of truth:
+ *
+ *   1. The dashboard BFF computes a manifest at submitRun-response
+ *      time (from the validated submission + the chosen provider)
+ *      and echoes it on the wire as `Run.runtimeManifest`. The SDK
+ *      exposes it as `RunRef.runtimeManifest` so caller code (broll's
+ *      dispatcher, anyone rendering catalog markdown pre-submission)
+ *      can substitute path strings without guessing.
+ *
+ *   2. The worker uses the same builder + the same `renderRuntimeEnv`
+ *      / `renderRuntimeJson` helpers to materialise the two RUNTIME
+ *      files mounted into every session, so the in-container view
+ *      and the SDK-side view are byte-for-byte the same set of
+ *      keys/values.
+ *
+ * Manifest values are derived: the BFF and worker both compute them
+ * from the same input (provider + customer envVars). Nothing is
+ * persisted separately — the source of truth for the customer half
+ * remains `submission.environment.envVars` on the run row; the antpath
+ * half is constant for a given provider+SDK-version pair.
+ */
+/**
+ * Set of providers whose runtime contract antpath models. Today only
+ * `"anthropic"` ships; the field is on the manifest so forward-compat
+ * consumers can branch on it without us having to silently change
+ * what `runtimeManifest` means when we add a second provider.
+ */
+export type RuntimeProvider = "anthropic";
+/**
+ * The in-container paths the agent and skill code reference at
+ * runtime. All fields are absolute, all reflect Anthropic Managed
+ * Agents' session-mount rebase rule (every `mount_path` lands under
+ * `/mnt/session/uploads/` regardless of the leading slash) — see
+ * `references/architecture-decisions.md`.
+ *
+ * `skillsRoot` is the location of Skills API-registered bundles, which
+ * the runtime auto-discovers under `/workspace/skills/<name>/` —
+ * empirically a separate root from the session-resource mounts, NOT
+ * under `/mnt/session/uploads/`.
+ */
+export interface RuntimeManifest {
+    readonly provider: RuntimeProvider;
+    /** Where Skills-API-registered bundles auto-discover (Anthropic). */
+    readonly skillsRoot: string;
+    /** Parent dir of File mounts: `<filesRoot>/<f_id>/<rel-path>`. */
+    readonly filesRoot: string;
+    /** Parent dir of non-SKILL.md asset mounts: `<assetsRoot>/<skl_id>/<rel-path>`. */
+    readonly assetsRoot: string;
+    /** Absolute path the agent writes output files into for capture. */
+    readonly outputsRoot: string;
+    /** Absolute path of the in-container antpath CLI (invoke via `node`). */
+    readonly antpathCli: string;
+    /** Absolute path of the per-run proxy-endpoints manifest. */
+    readonly indexJson: string;
+    /** Absolute path of the always-mounted antpath runtime contract README. */
+    readonly readme: string;
+    /** Absolute path of the machine-readable manifest mirror. */
+    readonly runtimeJson: string;
+    /** Absolute path of the POSIX-shell-sourceable runtime env file. */
+    readonly runtimeEnv: string;
+    /**
+     * Merged env-var bag: antpath-set runtime keys (with reserved
+     * `ANTPATH_` prefix) plus customer-supplied `environment.envVars`.
+     * Both `RUNTIME.env` and `RUNTIME.json` are rendered from this
+     * exact map; `__KEY__` substitution in agent-facing markdown
+     * resolves against this exact map.
+     */
+    readonly envVars: Readonly<Record<string, string>>;
+}
+/**
+ * Anthropic Managed Agents container paths. Kept here so the BFF and
+ * the worker render identical values; the worker's `proxy-bootstrap`
+ * constants are validated against these by a regression test
+ * (`packages/shared/test/runtime-manifest.test.ts`).
+ *
+ * Path facts (each verified at least once by a live session, locked
+ * in `references/architecture-decisions.md`):
+ *   - Session resources mount under `/mnt/session/uploads/` (rebase).
+ *   - Skills API places bundles under `/workspace/skills/<name>/`
+ *     — a SEPARATE root from session-resource mounts.
+ *   - Files API mounts file_ids at the requested mount_path, also
+ *     rebased — antpath threads them under `<filesRoot>/<f_id>/<rel>`.
+ *   - Only `/mnt/session/outputs` files are auto-registered with the
+ *     Files API for terminal-time capture.
+ */
+declare const ANTHROPIC_PATHS: Readonly<{
+    readonly skillsRoot: "/workspace/skills";
+    readonly filesRoot: "/mnt/session/uploads/antpath/files";
+    readonly assetsRoot: "/mnt/session/uploads/antpath/assets";
+    readonly outputsRoot: "/mnt/session/outputs";
+    readonly antpathCli: "/mnt/session/uploads/antpath/antpath";
+    readonly indexJson: "/mnt/session/uploads/antpath/index.json";
+    readonly readme: "/mnt/session/uploads/antpath/SKILLS.md";
+    readonly runtimeJson: "/mnt/session/uploads/antpath/RUNTIME.json";
+    readonly runtimeEnv: "/mnt/session/uploads/antpath/RUNTIME.env";
+}>;
+/**
+ * Container paths exposed for a given provider. Today only
+ * `"anthropic"` is recognised; calling with anything else throws so
+ * forward-compat surfaces the missing provider entry instead of
+ * silently emitting Anthropic paths.
+ */
+export declare function runtimePathsFor(provider: RuntimeProvider): typeof ANTHROPIC_PATHS;
+export interface BuildRuntimeManifestInput {
+    readonly provider: RuntimeProvider;
+    /**
+     * Customer-supplied `environment.envVars` from the validated
+     * submission. Keys with the reserved `ANTPATH_` prefix are
+     * filtered out defensively — the strict submission parser already
+     * rejects them, but defence-in-depth means a malformed snapshot
+     * (or a future bypass) can't poison the manifest.
+     */
+    readonly customerEnvVars?: Readonly<Record<string, string>> | undefined;
+}
+/**
+ * Build the runtime manifest for a single submission. Pure function:
+ * same input → same output → safe to call from the BFF response path
+ * and from the worker bootstrap path with identical results.
+ */
+export declare function buildRuntimeManifest(input: BuildRuntimeManifestInput): RuntimeManifest;
+/**
+ * Render the RUNTIME.env file mounted into every session. POSIX-shell
+ * sourceable (`source /mnt/session/uploads/antpath/RUNTIME.env`).
+ * Values are double-quoted with `"`, `\`, `$`, and backtick escaped
+ * so any UTF-8 string survives a `source` invocation. Lines are LF
+ * (Unix), no trailing CR — the container is Linux regardless of
+ * caller platform.
+ *
+ * Output order: antpath keys first (in stable order from
+ * `buildRuntimeManifest`), then customer keys in insertion order.
+ * The same ordering is preserved in RUNTIME.json.
+ */
+export declare function renderRuntimeEnv(manifest: RuntimeManifest): string;
+/**
+ * Render the RUNTIME.json file mounted into every session. Stable
+ * canonical JSON (2-space indent, key order matches the manifest)
+ * so the file is reviewable as a tracked artifact when captured into
+ * a run's output archive.
+ */
+export declare function renderRuntimeJson(manifest: RuntimeManifest): string;
+/**
+ * Pattern matched by `substituteRuntimePlaceholders`. A placeholder is
+ * `__KEY__` where `KEY` matches POSIX shell key rules (uppercase, digits,
+ * underscores, starting with a letter or underscore). The literal form
+ * is deliberately conservative — no `{{ }}` templating, no expressions,
+ * no escape syntax. If a customer needs the literal string `__KEY__` in
+ * agent-facing markdown, they avoid the matching key in their envVars
+ * map.
+ */
+export declare const RUNTIME_PLACEHOLDER_PATTERN: RegExp;
+/**
+ * Substitute `__KEY__` placeholders in agent-facing markdown against
+ * the manifest's envVars map. Fail-fast on unknown keys: the function
+ * throws `RuntimePlaceholderError` naming the offending key + filePath
+ * so the worker can surface a lint-style failure at materialization
+ * time, before the agent ever sees the file.
+ *
+ * Pure function; safe to call from the BFF, the worker materializer,
+ * or tests. The two callers in production are:
+ *
+ *   - Worker materialization: rewrite SKILL.md / AGENTS.md / .md
+ *     entries inside skill, file, and AgentsMd bundles before they
+ *     mount or upload.
+ *   - SDK / customer code: customers can apply the same helper in
+ *     their dispatcher when they want to render templates locally
+ *     before uploading. The merged envVars map is `runtimeManifest.envVars`.
+ *
+ * @param content   The text to rewrite.
+ * @param envVars   Map of allowed placeholder keys → values. Typically
+ *                  `runtimeManifest.envVars` from `buildRuntimeManifest`.
+ * @param filePath  Optional path of the source file, included in the
+ *                  error message when a placeholder is unresolved.
+ *                  Helps the customer locate the offending line.
+ */
+export declare function substituteRuntimePlaceholders(content: string, envVars: Readonly<Record<string, string>>, filePath?: string): string;
+/**
+ * Thrown by `substituteRuntimePlaceholders` when a `__KEY__` token in
+ * agent-facing markdown does not resolve against the merged env-var
+ * map. Surfaced at run materialization, before the run reaches the
+ * agent — the customer fixes the typo at the SDK call site, no
+ * tokens are spent on a misrouted run.
+ */
+export declare class RuntimePlaceholderError extends Error {
+    constructor(message: string);
+}
+export {};