@aexhq/sdk 0.13.6

package/dist/_contracts/run-unit.js

@@ -0,0 +1,215 @@
+/**
+ * RunUnit — the self-contained read shape of a run.
+ *
+ * One canonical struct that captures every non-secret artifact persisted
+ * for a single run: parsed submission inputs, status/lifecycle, attempts,
+ * indexed events, raw-event Storage manifest, outputs (+ capture
+ * failures), proxy-call audit log, pinned workspace skills, provider
+ * built-in skills, and transient (Anthropic Files) skill records.
+ *
+ * Wire contract for `GET /api/runs/:runId`, the per-run archive's
+ * `run.json`/`submission.json`/`caps.json`, and the SDK/CLI
+ * `client.runs.get(runId)` return type.
+ *
+ * Immutability: every field here is read-only. Edit endpoints do not
+ * exist by design.
+ *
+ * Raw event payloads are not embedded in this struct. They live in
+ * private object storage as gzipped JSONL pages and are listed via
+ * `rawEventPages` (manifest only; bytes downloaded out-of-band so the
+ * detail response stays bounded). The archive zip carries the bytes.
+ */
+import { parseMcpServerRef, parseSkillRef } from "./run-config.js";
+import { PLATFORM_PACKAGE_ECOSYSTEMS } from "./submission.js";
+// ---------------------------------------------------------------------------
+// Submission parser
+// ---------------------------------------------------------------------------
+/**
+ * Parse a legacy run 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: "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 === "submission") {
+        return parseFlatProjection(value);
+    }
+    // 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) {
+    const submissionRaw = isRecord(value.submission) ? value.submission : {};
+    const outputsRaw = isRecord(submissionRaw.outputs) ? submissionRaw.outputs : {};
+    const allowedDirs = toOptionalStringArray(outputsRaw.allowedDirs);
+    const deniedDirs = toOptionalStringArray(outputsRaw.deniedDirs);
+    const submission = {
+        model: typeof submissionRaw.model === "string" ? submissionRaw.model : "",
+        ...(typeof submissionRaw.system === "string" ? { system: submissionRaw.system } : {}),
+        prompt: toStringArray(submissionRaw.prompt),
+        skills: toSkillRefArray(submissionRaw.skills),
+        agentsMd: [],
+        files: [],
+        mcpServers: toMcpServerRefArray(submissionRaw.mcpServers),
+        ...(parseEnvironment(submissionRaw.environment)
+            ? { environment: parseEnvironment(submissionRaw.environment) }
+            : {}),
+        ...(parseSecurityProfile(submissionRaw.securityProfile)
+            ? { securityProfile: parseSecurityProfile(submissionRaw.securityProfile) }
+            : {}),
+        ...(isJsonRecord(submissionRaw.metadata) ? { metadata: submissionRaw.metadata } : {}),
+        ...(allowedDirs || deniedDirs
+            ? {
+                outputs: {
+                    ...(allowedDirs ? { allowedDirs } : {}),
+                    ...(deniedDirs ? { deniedDirs } : {})
+                }
+            }
+            : {})
+    };
+    return {
+        kind: "submission",
+        submission
+    };
+}
+function parseSecurityProfile(value) {
+    return value === "strict" || value === "standard" || value === "developer" ? value : undefined;
+}
+function fallbackFlat() {
+    return {
+        kind: "submission",
+        submission: {
+            model: "",
+            prompt: [],
+            skills: [],
+            agentsMd: [],
+            files: [],
+            mcpServers: []
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Coercion helpers — deliberately lenient. We never throw on a single
+// malformed sub-field; we collapse it to a safe default and keep going
+// so a dashboard read of a malformed snapshot still surfaces the rest.
+// ---------------------------------------------------------------------------
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isJsonRecord(value) {
+    return isRecord(value);
+}
+function toStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === "string");
+}
+function toOptionalStringArray(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        return undefined;
+    }
+    const filtered = value.filter((item) => typeof item === "string");
+    return filtered.length === 0 ? undefined : filtered;
+}
+function toSkillRefArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const out = [];
+    for (let i = 0; i < value.length; i++) {
+        try {
+            out.push(parseSkillRef(value[i], `submission.skills[${i}]`));
+        }
+        catch {
+            // Skip malformed entries rather than failing the whole detail
+            // read. Worker-side enrichment may add fields we don't recognise.
+        }
+    }
+    return out;
+}
+function toMcpServerRefArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const out = [];
+    for (let i = 0; i < value.length; i++) {
+        try {
+            out.push(parseMcpServerRef(value[i], `submission.mcpServers[${i}]`));
+        }
+        catch {
+            // ignore malformed
+        }
+    }
+    return out;
+}
+function parseEnvironment(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const env = {};
+    if (isRecord(value.networking)) {
+        const mode = value.networking.mode;
+        const allowedHosts = value.networking.allowedHosts;
+        if (mode === "limited" || mode === "open") {
+            env.networking = {
+                mode,
+                ...(Array.isArray(allowedHosts)
+                    ? { allowedHosts: toStringArray(allowedHosts) }
+                    : {})
+            };
+        }
+    }
+    if (Array.isArray(value.packages)) {
+        const pkgs = value.packages
+            .filter(isRecord)
+            .map((p) => {
+            const r = p;
+            if (typeof r.name !== "string")
+                return null;
+            // Snapshots persisted after the ecosystem split carry it verbatim;
+            // older snapshots (pre-split) default to `apt` to match the strict
+            // parser's unprefixed default.
+            const ecosystem = typeof r.ecosystem === "string" &&
+                PLATFORM_PACKAGE_ECOSYSTEMS.includes(r.ecosystem)
+                ? r.ecosystem
+                : "apt";
+            return {
+                name: r.name,
+                ...(typeof r.version === "string" ? { version: r.version } : {}),
+                ecosystem
+            };
+        })
+            .filter((p) => p !== null);
+        if (pkgs.length > 0) {
+            env.packages = pkgs;
+        }
+    }
+    // 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;
+}
+//# sourceMappingURL=run-unit.js.map

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

@@ -0,0 +1,114 @@
+/**
+ * Unified runner event schema. The managed runtime feeds one shape into
+ * the hosted aex event pipeline:
+ *
+ *   - **Goose Managed** — the per-run managed runtime 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 runtime-specific wire shapes — they only see
+ * `RunnerEvent`s.
+ *
+ * This is the public event contract consumed by SDK and CLI clients.
+ */
+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.aex.dev 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.aex.dev accepts and the size of the downstream Postgres / KV
+ * 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.aex.dev 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/_contracts/runner-event.js

@@ -0,0 +1,187 @@
+/**
+ * Unified runner event schema. The managed runtime feeds one shape into
+ * the hosted aex event pipeline:
+ *
+ *   - **Goose Managed** — the per-run managed runtime 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 runtime-specific wire shapes — they only see
+ * `RunnerEvent`s.
+ *
+ * This is the public event contract consumed by SDK and CLI clients.
+ */
+/**
+ * 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.aex.dev accepts and the size of the downstream Postgres / KV
+ * 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.aex.dev 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/_contracts/runtime-manifest.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Runtime manifest: the per-run, per-provider description of where
+ * aex places things inside the agent container, plus the merged
+ * env-var bag delivered via `RUNTIME.env` / `RUNTIME.json`.
+ *
+ * The hosted API computes a manifest at submitRun-response time
+ * (from the validated submission + the chosen provider) via
+ * {@link buildRuntimeManifest} and echoes it on the wire as
+ * `Run.runtimeManifest`, so caller code (anyone rendering catalog markdown
+ * pre-submission, or resolving aex's in-container path strings) doesn't
+ * have to guess.
+ * The managed runtime materialises the actual `RUNTIME.env` / `RUNTIME.json`
+ * files in-container from the same provider + envVars inputs, so the
+ * SDK-side view and the in-container view describe the same layout.
+ *
+ * Manifest values are derived, never persisted separately — the source
+ * of truth for the customer half remains `submission.environment.envVars`
+ * on the run row; the aex half is constant for a given
+ * provider+SDK-version pair.
+ */
+/**
+ * Set of providers whose runtime contract aex 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).
+ *
+ * `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 of the in-container aex runtime bridge (invoke via `node`). */
+    readonly aexCli: string;
+    /** Absolute path of the per-run proxy-endpoints manifest. */
+    readonly indexJson: string;
+    /** Absolute path of the always-mounted aex 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: aex-set runtime keys (with reserved
+     * `AEX_` 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>>;
+}
+/**
+ * Managed-runner container paths. Kept here so the BFF, worker, and
+ * in-container bridge render identical values; runtime bootstrap constants are
+ * validated against these by a regression test
+ * (`packages/contracts/test/runtime-manifest.test.ts`).
+ */
+declare const ANTHROPIC_PATHS: Readonly<{
+    readonly skillsRoot: "/workspace/skills";
+    readonly filesRoot: "/mnt/session/uploads/aex/files";
+    readonly assetsRoot: "/mnt/session/uploads/aex/assets";
+    readonly aexCli: "/mnt/session/uploads/aex/aex";
+    readonly indexJson: "/mnt/session/uploads/aex/index.json";
+    readonly readme: "/mnt/session/uploads/aex/SKILLS.md";
+    readonly runtimeJson: "/mnt/session/uploads/aex/RUNTIME.json";
+    readonly runtimeEnv: "/mnt/session/uploads/aex/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 `AEX_` 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;
+export {};