@aexhq/sdk 0.13.7 → 0.13.8

package/dist/_contracts/operations.js

@@ -1,7 +1,6 @@
 import { strToU8, zipSync } from "fflate";
 import { RunStateError } from "./sdk-errors.js";
 import { assertRunRecordArchivePublicSafeV1, buildRunRecordDownloadManifestV1 } from "./run-record.js";
-import { runArtifactRel } from "./run-artifacts.js";
 /**
  * The single source of truth for SDK<->BFF transport. The SDK class
  * AND the CLI subcommands both call these functions; neither
@@ -32,12 +31,29 @@ export async function getRun(http, runId) {
 export async function getRunUnit(http, runId) {
     return http.request(`/api/runs/${encodeURIComponent(runId)}`);
 }
-export async function listRunEvents(http, runId, options = {}) {
-    const query = options.channel && options.channel !== "event"
-        ? { channel: options.channel }
-        : {};
-    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/events`, {}, query);
-    return result.events;
+// Bound the transparent pager: the read route caps each page at 1000, so this
+// admits up to ~1e6 events before bailing — past any real run, but bounded so a
+// server that never clears `nextCursor` can't loop forever.
+const LIST_EVENTS_PAGE_BUDGET = 1000;
+/**
+ * List a run's events. The read endpoint is PAGED (bounded per response so a
+ * long run can't return an unbounded body); this follows `nextCursor` across
+ * pages and returns the FULL accumulated list, preserving the prior single-call
+ * contract for callers (download/*, CLI, streamEvents polling).
+ */
+export async function listRunEvents(http, runId) {
+    const path = `/api/runs/${encodeURIComponent(runId)}/events`;
+    const all = [];
+    let cursor;
+    for (let page = 0; page < LIST_EVENTS_PAGE_BUDGET; page++) {
+        const query = cursor !== undefined ? { cursor: String(cursor) } : {};
+        const result = await http.request(path, {}, query);
+        all.push(...result.events);
+        if (typeof result.nextCursor !== "number")
+            break;
+        cursor = result.nextCursor;
+    }
+    return all;
 }
 /**
  * Mint a short-lived coordinator WS ticket via the workspace-token-gated
@@ -52,14 +68,6 @@ export async function listOutputs(http, runId) {
     const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/outputs`);
     return result.outputs;
 }
-/**
- * List the run's platform diagnostics (the `logs` namespace). Legacy stored
- * filenames are normalized to canonical public namespaces.
- */
-export async function listLogs(http, runId) {
-    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/logs`);
-    return result.logs.map((log) => typeof log.filename === "string" ? { ...log, filename: runArtifactRel(log.filename) } : log);
-}
 export async function createOutputLink(http, runId, outputId) {
     return http.request(`/api/runs/${encodeURIComponent(runId)}/outputs/${encodeURIComponent(outputId)}/link`, { method: "POST" });
 }
@@ -123,7 +131,7 @@ export async function whoami(http) {
 }
 /**
  * Download each artifact's bytes into a zip-file map keyed by
- * `<zipPrefix><relative-path>`, fetched from the `outputs` or `logs`
+ * `<zipPrefix><relative-path>`, fetched from the `outputs`
  * download route. Best-effort: a per-artifact fetch failure records an
  * `errors[]` entry rather than aborting the rest, so the failure is
  * surfaced (never silent) while a partially-available run still yields a
@@ -141,7 +149,7 @@ async function collectArtifactBytes(http, runId, items, zipPrefix, namespace) {
                 path: `${zipPrefix}${rel}`,
                 bytes: new Uint8Array(await response.arrayBuffer()),
                 ...(item.contentType !== undefined ? { contentType: item.contentType } : {}),
-                ...(namespace === "outputs" ? { customerContent: true } : {})
+                customerContent: true
             });
             captured.push({
                 id: item.id,
@@ -159,28 +167,6 @@ async function collectArtifactBytes(http, runId, items, zipPrefix, namespace) {
 function eventsJsonl(events) {
     return strToU8(events.map((event) => JSON.stringify(event)).join("\n"));
 }
-async function tryListOptionalRunEvents(http, runId, channel) {
-    try {
-        const events = await listRunEvents(http, runId, { channel });
-        if (channel === "log") {
-            return events.length > 0 && events.every(isLogChannelEvent)
-                ? { status: "present", events }
-                : { status: "unavailable", events: [] };
-        }
-        return hasUnifiedStreamEvidence(events)
-            ? { status: "present", events }
-            : { status: "unavailable", events: [] };
-    }
-    catch {
-        return { status: "unavailable", events: [] };
-    }
-}
-function isLogChannelEvent(event) {
-    return event.channel === "log";
-}
-function hasUnifiedStreamEvidence(events) {
-    return events.some((event) => event.channel === "log" || event.channel === "event");
-}
 function isPathSelector(selector) {
     return Boolean(selector && typeof selector === "object" && "path" in selector);
 }
@@ -188,50 +174,37 @@ function normalizeOutputLookupPath(path) {
     return path.replace(/\\/g, "/").replace(/^\/+/, "");
 }
 /**
- * Download EVERYTHING about a run as one zip, organised into the four
+ * Download EVERYTHING public about a run as one zip, organised into the three
  * namespace folders:
  *
  *   metadata/run.json     — the run record.
  *   events/events.jsonl   — typed event-channel records.
- *   events/logs.jsonl     — log-channel records, when the API serves them.
- *   events/all.jsonl      — full unified stream, when the API serves it.
  *   outputs/<rel>         — the run's deliverables.
- *   logs/<rel>            — platform diagnostics.
  *   manifest.json         — `RunRecordManifestV1`.
  */
 export async function download(http, runId) {
-    const [run, events, logEvents, allEvents, outputs, logItems] = await Promise.all([
+    const [run, events, outputs] = await Promise.all([
         getRun(http, runId),
         listRunEvents(http, runId),
-        tryListOptionalRunEvents(http, runId, "log"),
-        tryListOptionalRunEvents(http, runId, "all"),
-        listOutputs(http, runId),
-        listLogs(http, runId)
+        listOutputs(http, runId)
     ]);
     const out = await collectArtifactBytes(http, runId, outputs, "outputs/", "outputs");
-    const logs = await collectArtifactBytes(http, runId, logItems, "logs/", "logs");
     const submissionSnapshot = extractSubmissionSnapshot(run);
     const costTelemetry = extractCostTelemetry(run);
     const manifest = buildRunRecordDownloadManifestV1({
         runId,
         outputs: out.captured,
-        logs: logs.captured,
-        errors: [...out.errors, ...logs.errors],
+        errors: out.errors,
         typedEventCount: events.length,
         ...(submissionSnapshot ? { submission: { status: "present" } } : {}),
-        ...(costTelemetry ? { cost: { status: "present" } } : {}),
-        logEvents: { status: logEvents.status, recordCount: logEvents.events.length },
-        allEvents: { status: allEvents.status, recordCount: allEvents.events.length }
+        ...(costTelemetry ? { cost: { status: "present" } } : {})
     });
     return zipEntries([
         jsonEntry("metadata/run.json", run),
         ...(submissionSnapshot ? [jsonEntry("metadata/submission.json", submissionSnapshot)] : []),
         ...(costTelemetry ? [jsonEntry("metadata/cost.json", costTelemetry)] : []),
         jsonlEntry("events/events.jsonl", events),
-        ...(logEvents.status === "present" ? [jsonlEntry("events/logs.jsonl", logEvents.events)] : []),
-        ...(allEvents.status === "present" ? [jsonlEntry("events/all.jsonl", allEvents.events)] : []),
         ...out.entries,
-        ...logs.entries,
         jsonEntry("manifest.json", manifest)
     ]);
 }
@@ -248,35 +221,13 @@ export async function downloadOutputs(http, runId) {
         jsonEntry("manifest.json", { runId, namespace: "outputs", outputs: captured, errors })
     ]);
 }
-/**
- * Download only the platform diagnostics (the `logs` namespace). Zip
- * layout: `<rel>` per file plus a `manifest.json`
- * (`{ runId, namespace: "logs", logs[], errors[] }`).
- */
-export async function downloadLogs(http, runId) {
-    const logItems = await listLogs(http, runId);
-    const { entries, captured, errors } = await collectArtifactBytes(http, runId, logItems, "", "logs");
-    return zipEntries([
-        ...entries,
-        jsonEntry("manifest.json", { runId, namespace: "logs", logs: captured, errors })
-    ]);
-}
 /**
  * Download only the event archive (the `events` namespace). Always includes
- * typed `events.jsonl`; includes `logs.jsonl` / `all.jsonl` when the deployed
- * event API proves those channel exports are available.
+ * typed `events.jsonl`.
  */
 export async function downloadEvents(http, runId) {
-    const [events, logEvents, allEvents] = await Promise.all([
-        listRunEvents(http, runId),
-        tryListOptionalRunEvents(http, runId, "log"),
-        tryListOptionalRunEvents(http, runId, "all")
-    ]);
-    return zipEntries([
-        jsonlEntry("events.jsonl", events),
-        ...(logEvents.status === "present" ? [jsonlEntry("logs.jsonl", logEvents.events)] : []),
-        ...(allEvents.status === "present" ? [jsonlEntry("all.jsonl", allEvents.events)] : [])
-    ]);
+    const events = await listRunEvents(http, runId);
+    return zipEntries([jsonlEntry("events.jsonl", events)]);
 }
 /**
  * Download only the run record (the `metadata` namespace) as a zip

package/dist/_contracts/proxy-protocol.d.ts

@@ -9,7 +9,40 @@
  * the new version.
  */
 export declare const PROXY_PROTOCOL_VERSION: "1";
+/**
+ * Streaming named-proxy protocol. A client that sends `"2"` in
+ * {@link PROXY_PROTOCOL_HEADER} opts into the streamed response path: the
+ * Worker pipes the upstream body back unbuffered (no base64, no
+ * `arrayBuffer()` in the ~128MB isolate) and carries the envelope metadata
+ * in the `x-aex-proxy-*` response headers below instead of a JSON envelope.
+ *
+ * Additive: `"1"` stays valid and keeps the buffered
+ * {@link ProxyResponseEnvelope}. Old runners keep working; new runners
+ * stream. The version is on the request header so the Worker can serve
+ * both shapes without a coordinated CLI/BFF release.
+ */
+export declare const PROXY_PROTOCOL_VERSION_V2: "2";
 export declare const PROXY_PROTOCOL_HEADER = "x-aex-proxy-protocol";
+/**
+ * Response headers for the streamed (v2) named-proxy path. The Worker sets
+ * these BEFORE it starts streaming the upstream body, so the client can
+ * reconstruct the same fields the v1 {@link ProxyResponseEnvelope} carried
+ * without buffering. All values are plain strings; numeric fields are
+ * decimal, booleans are `"true"`/`"false"`.
+ */
+export declare const PROXY_RESP_STATUS_HEADER = "x-aex-proxy-status";
+export declare const PROXY_RESP_MODE_HEADER = "x-aex-proxy-effective-mode";
+/**
+ * `"true"` when the cap forced truncation, `"false"` when the full body
+ * fit, `"unknown"` when the upstream omitted `content-length` and the body
+ * happened to reach the cap (can't distinguish exact-fit from over-cap
+ * without buffering). See the streaming byte-cap note in proxy-routes.ts.
+ */
+export declare const PROXY_RESP_TRUNCATED_HEADER = "x-aex-proxy-truncated";
+export declare const PROXY_RESP_REMAINING_CALLS_HEADER = "x-aex-proxy-remaining-calls";
+export declare const PROXY_RESP_REMAINING_BYTES_HEADER = "x-aex-proxy-remaining-bytes";
+/** JSON object of lowercase upstream header names → values (mode-filtered). */
+export declare const PROXY_RESP_UPSTREAM_HEADERS_HEADER = "x-aex-proxy-upstream-headers";
 /**
  * Default `User-Agent` the proxy attaches to every outbound request when
  * the caller did not supply one via `allowHeaders`. Some upstreams reject
@@ -115,8 +148,8 @@ export interface ProxyEndpointPolicy {
 export interface BuildProxyIndexFileInput {
     readonly runId: string;
     /**
-     * Dashboard host that serves `/api/runs/:runId/proxy/:endpointName`
-     * (the BFF proxy route). Distinct from the api Worker host. When unset
+     * Worker host that serves `/api/runs/:runId/proxy/:endpointName`.
+     * When unset
      * (or empty) the run has no reachable proxy plane and `proxyBaseUrl`
      * resolves to `null`.
      */

package/dist/_contracts/proxy-protocol.js

@@ -1,6 +1,6 @@
 // Wire format between the in-container runtime bridge (mounted at
 // `/mnt/session/uploads/aex/aex`, invoked through `node`) and
-// the dashboard BFF proxy route
+// the Worker-owned named proxy route
 // (`POST /api/runs/:runId/proxy/:endpointName`).
 //
 // This module is the single source of truth for the request shape, the
@@ -18,7 +18,40 @@
  * the new version.
  */
 export const PROXY_PROTOCOL_VERSION = "1";
+/**
+ * Streaming named-proxy protocol. A client that sends `"2"` in
+ * {@link PROXY_PROTOCOL_HEADER} opts into the streamed response path: the
+ * Worker pipes the upstream body back unbuffered (no base64, no
+ * `arrayBuffer()` in the ~128MB isolate) and carries the envelope metadata
+ * in the `x-aex-proxy-*` response headers below instead of a JSON envelope.
+ *
+ * Additive: `"1"` stays valid and keeps the buffered
+ * {@link ProxyResponseEnvelope}. Old runners keep working; new runners
+ * stream. The version is on the request header so the Worker can serve
+ * both shapes without a coordinated CLI/BFF release.
+ */
+export const PROXY_PROTOCOL_VERSION_V2 = "2";
 export const PROXY_PROTOCOL_HEADER = "x-aex-proxy-protocol";
+/**
+ * Response headers for the streamed (v2) named-proxy path. The Worker sets
+ * these BEFORE it starts streaming the upstream body, so the client can
+ * reconstruct the same fields the v1 {@link ProxyResponseEnvelope} carried
+ * without buffering. All values are plain strings; numeric fields are
+ * decimal, booleans are `"true"`/`"false"`.
+ */
+export const PROXY_RESP_STATUS_HEADER = "x-aex-proxy-status";
+export const PROXY_RESP_MODE_HEADER = "x-aex-proxy-effective-mode";
+/**
+ * `"true"` when the cap forced truncation, `"false"` when the full body
+ * fit, `"unknown"` when the upstream omitted `content-length` and the body
+ * happened to reach the cap (can't distinguish exact-fit from over-cap
+ * without buffering). See the streaming byte-cap note in proxy-routes.ts.
+ */
+export const PROXY_RESP_TRUNCATED_HEADER = "x-aex-proxy-truncated";
+export const PROXY_RESP_REMAINING_CALLS_HEADER = "x-aex-proxy-remaining-calls";
+export const PROXY_RESP_REMAINING_BYTES_HEADER = "x-aex-proxy-remaining-bytes";
+/** JSON object of lowercase upstream header names → values (mode-filtered). */
+export const PROXY_RESP_UPSTREAM_HEADERS_HEADER = "x-aex-proxy-upstream-headers";
 /**
  * Default `User-Agent` the proxy attaches to every outbound request when
  * the caller did not supply one via `allowHeaders`. Some upstreams reject

package/dist/_contracts/run-artifacts.d.ts

@@ -1,29 +1,31 @@
 /**
  * Single source of truth for a run's artifact namespaces.
  *
- * Every run stores its artifacts under two sibling prefixes:
+ * Every run stores public outputs and internal diagnostics under separate
+ * prefixes:
  *
- *   runs/<runId>/outputs/<rel>   — the run's real deliverables.
- *   runs/<runId>/logs/<rel>      — platform diagnostics (`runtime/`,
- *                                  `host/`, `provider-proxy/`,
- *                                  `control-plane/`).
+ *   runs/<runId>/outputs/<rel>              — the run's real deliverables.
+ *   runs/<runId>/internal/logs/<rel>        — platform diagnostics
+ *                                             (`runtime/`, `host/`,
+ *                                             `provider-proxy/`,
+ *                                             `control-plane/`).
  *
  * The runner uploads every file with a workspace-relative path and the
  * server decides the namespace from that path's prefix, so the split is
  * owned here — the runner does not need to know about it. Diagnostics
  * reach the upload route as workspace dotdirs (`.runtime-logs/...`,
- * `.host-logs/...`, etc.); the stored path uses canonical log namespaces.
- * Legacy diagnostic prefixes are normalized on read/write compatibility paths.
+ * `.host-logs/...`, etc.) or runtime-managed home-directory state; the stored
+ * path uses canonical log namespaces.
  */
 export declare const RUN_OUTPUTS_PREFIX = "outputs";
-export declare const RUN_LOGS_PREFIX = "logs";
+export declare const RUN_INTERNAL_LOGS_PREFIX = "internal/logs";
 /**
  * Relative-path prefixes that mark a stored artifact as a platform diagnostic
  * rather than a run deliverable. Dotted forms are upload-time paths; legacy
  * forms are accepted so old records normalize to the canonical namespace.
  */
 export declare const RUN_LOG_REL_PREFIXES: readonly [".runtime-logs/", ".host-logs/", ".provider-proxy/", ".control-plane/", ".anthropic-debug/", ".goose-logs/", ".fly-logs/", "runtime/", "host/", "provider-proxy/", "control-plane/", "anthropic-debug/", "goose-logs/", "fly-logs/"];
-/** True when a workspace-relative artifact path belongs to the `logs` namespace. */
+/** True when a workspace-relative artifact path belongs to the internal logs namespace. */
 export declare function isRunLogRelPath(rel: string): boolean;
 /**
  * The artifact's path relative to its namespace prefix as stored. Diagnostics
@@ -33,7 +35,7 @@ export declare function isRunLogRelPath(rel: string): boolean;
 export declare function runArtifactRel(rel: string): string;
 /**
  * Storage key for a run artifact uploaded with relative path `rel`, routing
- * diagnostics into `logs/` and everything else into `outputs/`.
+ * diagnostics into `internal/logs/` and everything else into `outputs/`.
  */
 export declare function runArtifactKey(runId: string, rel: string): string;
 /** The `assets` namespace under a run's prefix. */

package/dist/_contracts/run-artifacts.js

@@ -1,22 +1,24 @@
 /**
  * Single source of truth for a run's artifact namespaces.
  *
- * Every run stores its artifacts under two sibling prefixes:
+ * Every run stores public outputs and internal diagnostics under separate
+ * prefixes:
  *
- *   runs/<runId>/outputs/<rel>   — the run's real deliverables.
- *   runs/<runId>/logs/<rel>      — platform diagnostics (`runtime/`,
- *                                  `host/`, `provider-proxy/`,
- *                                  `control-plane/`).
+ *   runs/<runId>/outputs/<rel>              — the run's real deliverables.
+ *   runs/<runId>/internal/logs/<rel>        — platform diagnostics
+ *                                             (`runtime/`, `host/`,
+ *                                             `provider-proxy/`,
+ *                                             `control-plane/`).
  *
  * The runner uploads every file with a workspace-relative path and the
  * server decides the namespace from that path's prefix, so the split is
  * owned here — the runner does not need to know about it. Diagnostics
  * reach the upload route as workspace dotdirs (`.runtime-logs/...`,
- * `.host-logs/...`, etc.); the stored path uses canonical log namespaces.
- * Legacy diagnostic prefixes are normalized on read/write compatibility paths.
+ * `.host-logs/...`, etc.) or runtime-managed home-directory state; the stored
+ * path uses canonical log namespaces.
  */
 export const RUN_OUTPUTS_PREFIX = "outputs";
-export const RUN_LOGS_PREFIX = "logs";
+export const RUN_INTERNAL_LOGS_PREFIX = "internal/logs";
 /**
  * Relative-path prefixes that mark a stored artifact as a platform diagnostic
  * rather than a run deliverable. Dotted forms are upload-time paths; legacy
@@ -38,7 +40,7 @@ export const RUN_LOG_REL_PREFIXES = [
     "goose-logs/",
     "fly-logs/"
 ];
-/** True when a workspace-relative artifact path belongs to the `logs` namespace. */
+/** True when a workspace-relative artifact path belongs to the internal logs namespace. */
 export function isRunLogRelPath(rel) {
     return RUN_LOG_REL_PREFIXES.some((prefix) => rel.startsWith(prefix));
 }
@@ -80,10 +82,10 @@ export function runArtifactRel(rel) {
 }
 /**
  * Storage key for a run artifact uploaded with relative path `rel`, routing
- * diagnostics into `logs/` and everything else into `outputs/`.
+ * diagnostics into `internal/logs/` and everything else into `outputs/`.
  */
 export function runArtifactKey(runId, rel) {
-    const namespace = isRunLogRelPath(rel) ? RUN_LOGS_PREFIX : RUN_OUTPUTS_PREFIX;
+    const namespace = isRunLogRelPath(rel) ? RUN_INTERNAL_LOGS_PREFIX : RUN_OUTPUTS_PREFIX;
     return `runs/${runId}/${namespace}/${runArtifactRel(rel)}`;
 }
 /** The `assets` namespace under a run's prefix. */

package/dist/_contracts/run-config.d.ts

@@ -61,6 +61,13 @@ export declare const SKILL_NAME_PATTERN: RegExp;
 export declare const SKILL_BUNDLE_LIMITS: {
     /** Compressed (.zip) ceiling. */
     readonly maxCompressedBytes: number;
+    /**
+     * Hard ceiling for the direct-to-storage (presigned PUT) upload path, where
+     * bytes never transit the hosted API so its memory/request-payload limits no
+     * longer cap the bundle. Kept well under the object store's 5 GiB single-PUT
+     * limit; objects above this would need S3 multipart, which is out of scope.
+     */
+    readonly maxBytes: number;
     /** Sum of uncompressed file sizes. */
     readonly maxDecompressedBytes: number;
     /** Number of regular file entries (directories don't count). */

package/dist/_contracts/run-config.js

@@ -65,6 +65,13 @@ export const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,127}$/;
 export const SKILL_BUNDLE_LIMITS = {
     /** Compressed (.zip) ceiling. */
     maxCompressedBytes: 10 * 1024 * 1024,
+    /**
+     * Hard ceiling for the direct-to-storage (presigned PUT) upload path, where
+     * bytes never transit the hosted API so its memory/request-payload limits no
+     * longer cap the bundle. Kept well under the object store's 5 GiB single-PUT
+     * limit; objects above this would need S3 multipart, which is out of scope.
+     */
+    maxBytes: 2 * 1024 * 1024 * 1024,
     /** Sum of uncompressed file sizes. */
     maxDecompressedBytes: 50 * 1024 * 1024,
     /** Number of regular file entries (directories don't count). */
@@ -419,26 +426,41 @@ export function rejectStdioMcpShape(record) {
     }
 }
 /**
- * Reasons an MCP server URL should be refused at parse time. Returns null
- * when the URL is acceptable. Hostnames are lowercased; numeric ranges
- * are checked literally so the catch covers both names ("localhost") and
- * IP literals ("127.0.0.1") symmetrically.
+ * Reasons an IP-literal host should be refused. Returns null when the
+ * literal is a routable public address (or not an IP literal at all — name
+ * resolution is the caller's concern). Single source of truth for the
+ * numeric-range deny-list so the shared MCP parser, the Worker BYOK proxy
+ * handlers, and `submission.parseProxyBaseUrl` classify the same bytes.
  *
- * Surface tracked by server-side SSRF regression coverage.
+ * `host` is the already-bracket-stripped, lowercased hostname.
+ *
+ * NOTE — residual DNS-rebind gap: this denies IP *literals* only. A name
+ * that resolves to a private/metadata IP is NOT caught here (we don't
+ * resolve at parse time). Closing that requires resolve-then-pin at egress;
+ * that pinning is deferred. The host's outbound fetch still refuses RFC1918
+ * at connect, but not loopback/169.254/CGNAT/ULA — which is exactly why the
+ * literal checks below exist as defense in depth.
  */
-function denyReasonForMcpHost(parsed) {
-    // `new URL("https://[fe80::1]/").hostname` returns `[fe80::1]` WITH
-    // the brackets on Node 22; strip them so the IPv6 checks match either
-    // shape symmetrically.
-    const host = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
-    // Loopback name (covers `localhost` + `localhost.localdomain` etc.)
-    if (host === "localhost" || host.endsWith(".localhost")) {
-        return "must not target a loopback hostname";
-    }
-    // Loopback IPv4 (127.0.0.0/8)
-    if (/^127(?:\.[0-9]+){3}$/.test(host)) {
-        return "must not target loopback IPv4 (127.0.0.0/8)";
-    }
+function denyReasonForHostIp(host) {
+    // IPv4-mapped / IPv4-compatible IPv6 literals decode to an embedded IPv4 —
+    // classify that IPv4 so a mapped form can't smuggle a private target. Two
+    // shapes reach us: the dotted-quad form a caller may type (`::ffff:127.0.0.1`)
+    // and the hex form `new URL().hostname` normalises it to (`::ffff:7f00:1`),
+    // where the two trailing hextets ARE the four IPv4 octets.
+    const mappedDotted = /^::(?:ffff:)?(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(host);
+    if (mappedDotted) {
+        return denyReasonForV4(mappedDotted[1]);
+    }
+    const mappedHex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
+    if (mappedHex) {
+        const hi = Number.parseInt(mappedHex[1], 16);
+        const lo = Number.parseInt(mappedHex[2], 16);
+        const dotted = `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+        return denyReasonForV4(dotted);
+    }
+    const v4 = denyReasonForV4(host);
+    if (v4)
+        return v4;
     // Loopback IPv6 (::1 in any acceptable form)
     if (host === "::1" || host === "0:0:0:0:0:0:0:1") {
         return "must not target loopback IPv6 (::1)";
@@ -447,20 +469,67 @@ function denyReasonForMcpHost(parsed) {
     if (/^fe[89ab][0-9a-f]?:/.test(host)) {
         return "must not target link-local IPv6 (fe80::/10)";
     }
+    // Unique-local IPv6 (fc00::/7 — fc00:: through fdff::), the IPv6
+    // equivalent of RFC1918 private space.
+    if (/^f[cd][0-9a-f]{0,2}:/.test(host)) {
+        return "must not target unique-local IPv6 (fc00::/7)";
+    }
+    return null;
+}
+/**
+ * IPv4-literal deny-list. Returns null when `host` is not a dotted-quad or
+ * is a routable public IPv4. Split out of {@link denyReasonForHostIp} so the
+ * IPv4-mapped IPv6 branch reuses the exact same ranges.
+ */
+function denyReasonForV4(host) {
+    if (!/^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host))
+        return null;
+    const octets = host.split(".").map((o) => Number.parseInt(o, 10));
+    if (octets.some((o) => o > 255))
+        return null;
+    const [a, b] = octets;
+    // Loopback IPv4 (127.0.0.0/8)
+    if (a === 127)
+        return "must not target loopback IPv4 (127.0.0.0/8)";
     // Link-local / metadata IPv4 (169.254.0.0/16 — includes 169.254.169.254)
-    if (/^169\.254\.[0-9]+\.[0-9]+$/.test(host)) {
+    if (a === 169 && b === 254) {
         return "must not target link-local IPv4 (169.254.0.0/16) — cloud metadata range";
     }
+    // CGNAT shared address space (100.64.0.0/10) — runners NAT through it, so
+    // an upstream there can reach sibling tenants / the runner host.
+    if (a === 100 && b >= 64 && b <= 127) {
+        return "must not target CGNAT IPv4 (100.64.0.0/10)";
+    }
     // RFC1918 private ranges (10/8, 172.16/12, 192.168/16) — defense in depth.
-    if (/^10\.[0-9]+\.[0-9]+\.[0-9]+$/.test(host)) {
+    if (a === 10)
         return "must not target RFC1918 IPv4 (10.0.0.0/8)";
-    }
-    if (/^172\.(1[6-9]|2[0-9]|3[01])\.[0-9]+\.[0-9]+$/.test(host)) {
+    if (a === 172 && b >= 16 && b <= 31)
         return "must not target RFC1918 IPv4 (172.16.0.0/12)";
-    }
-    if (/^192\.168\.[0-9]+\.[0-9]+$/.test(host)) {
+    if (a === 192 && b === 168)
         return "must not target RFC1918 IPv4 (192.168.0.0/16)";
+    return null;
+}
+/**
+ * Reasons an MCP server URL should be refused at parse time. Returns null
+ * when the URL is acceptable. Hostnames are lowercased; numeric ranges
+ * are checked literally so the catch covers both names ("localhost") and
+ * IP literals ("127.0.0.1") symmetrically. The numeric-range checks
+ * delegate to {@link denyReasonForHostIp} (shared with the Worker proxy).
+ *
+ * Surface tracked by server-side SSRF regression coverage.
+ */
+function denyReasonForMcpHost(parsed) {
+    // `new URL("https://[fe80::1]/").hostname` returns `[fe80::1]` WITH
+    // the brackets on Node 22; strip them so the IPv6 checks match either
+    // shape symmetrically.
+    const host = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    // Loopback name (covers `localhost` + `localhost.localdomain` etc.)
+    if (host === "localhost" || host.endsWith(".localhost")) {
+        return "must not target a loopback hostname";
     }
+    const ipDenial = denyReasonForHostIp(host);
+    if (ipDenial)
+        return ipDenial;
     // Port constraint: https must be on 443 (defense in depth — non-standard
     // https ports often indicate internal services). http allowance keeps
     // the existing local-dev pattern (e.g. host.docker.internal:8787) usable.

package/dist/_contracts/run-custody.d.ts

@@ -12,7 +12,7 @@ export declare const CUSTODY_SECRET_CLASSES: readonly ["provider_api_key", "mcp_
 export type CustodySecretClass = (typeof CUSTODY_SECRET_CLASSES)[number];
 export declare const CUSTODY_RESOURCE_CLASSES: readonly ["runtime_machine", "native_provider_session", "native_provider_resource", "provider_asset", "proxy_token", "execution_secret", "event_archive", "run_output", "run_log", "run_asset"];
 export type CustodyResourceClass = (typeof CUSTODY_RESOURCE_CLASSES)[number];
-export declare const CUSTODY_EXPOSURE_SURFACES: readonly ["aex_vault", "aex_kv", "fly_machine_env", "fly_machine_file", "provider_vault", "provider_session", "dashboard_proxy", "api_provider_proxy", "api_mcp_proxy", "run_artifact_store", "coordinator_event_archive"];
+export declare const CUSTODY_EXPOSURE_SURFACES: readonly ["aex_vault", "aex_kv", "host_env", "host_file", "provider_vault", "provider_session", "dashboard_proxy", "api_provider_proxy", "api_mcp_proxy", "run_artifact_store", "coordinator_event_archive"];
 export type CustodyExposureSurface = (typeof CUSTODY_EXPOSURE_SURFACES)[number];
 export declare const CUSTODY_EXPOSURE_ACCESS_KINDS: readonly ["stored", "injected", "proxied", "replicated", "observed", "unknown"];
 export type CustodyExposureAccessKind = (typeof CUSTODY_EXPOSURE_ACCESS_KINDS)[number];
@@ -24,7 +24,7 @@ export declare const CUSTODY_CLEANUP_STATUSES: readonly ["succeeded", "partial",
 export type CustodyCleanupStatus = (typeof CUSTODY_CLEANUP_STATUSES)[number];
 export declare const CUSTODY_EVIDENCE_SOURCES: readonly ["run_row", "runtime_manifest", "terminal_event", "cleanup_step", "output_capture", "proxy_audit", "provider_cleanup_summary"];
 export type CustodyEvidenceSource = (typeof CUSTODY_EVIDENCE_SOURCES)[number];
-export declare const CUSTODY_MANIFEST_EXCLUDED_VALUE_CLASSES: readonly ["raw_secret_values", "bearer_hashes", "provider_response_bodies", "signed_urls", "r2_object_keys", "vault_ids", "private_resource_handles"];
+export declare const CUSTODY_MANIFEST_EXCLUDED_VALUE_CLASSES: readonly ["raw_secret_values", "bearer_hashes", "provider_response_bodies", "signed_urls", "object_store_keys", "vault_ids", "private_resource_handles"];
 export type CustodyManifestExcludedValueClass = (typeof CUSTODY_MANIFEST_EXCLUDED_VALUE_CLASSES)[number];
 export declare const CUSTODY_TOMBSTONE_MANIFEST_STATUSES: readonly ["written", "not_written", "write_failed", "purged"];
 export type CustodyTombstoneManifestStatus = (typeof CUSTODY_TOMBSTONE_MANIFEST_STATUSES)[number];
@@ -198,7 +198,7 @@ export interface CustodyManifestWriteResult {
 export interface CustodyManifestWriter {
     writeCustodyManifest(input: CustodyManifestInput): Promise<CustodyManifestWriteResult>;
 }
-export type CustodyRedactionReason = "forbidden_field_name" | "bearer_token" | "provider_key" | "signed_url" | "r2_object_key" | "vault_id" | "private_resource_handle" | "high_entropy_token";
+export type CustodyRedactionReason = "forbidden_field_name" | "bearer_token" | "provider_key" | "signed_url" | "object_store_key" | "vault_id" | "private_resource_handle" | "high_entropy_token";
 export interface CustodyRedactionFinding {
     readonly path: string;
     readonly reason: CustodyRedactionReason;

package/dist/_contracts/run-custody.js

@@ -27,8 +27,8 @@ export const CUSTODY_RESOURCE_CLASSES = [
 export const CUSTODY_EXPOSURE_SURFACES = [
     "aex_vault",
     "aex_kv",
-    "fly_machine_env",
-    "fly_machine_file",
+    "host_env",
+    "host_file",
     "provider_vault",
     "provider_session",
     "dashboard_proxy",
@@ -84,7 +84,7 @@ export const CUSTODY_MANIFEST_EXCLUDED_VALUE_CLASSES = [
     "bearer_hashes",
     "provider_response_bodies",
     "signed_urls",
-    "r2_object_keys",
+    "object_store_keys",
     "vault_ids",
     "private_resource_handles"
 ];
@@ -413,7 +413,7 @@ const forbiddenStringPatterns = Object.freeze([
         regex: /\b(?:sk-(?:ant|proj|live|test|deepseek|openai)|xox[baprs]-|AIza)[A-Za-z0-9_-]{8,}/i
     },
     { reason: "signed_url", regex: /[?&](?:X-Amz-Signature|X-Amz-Credential|X-Amz-Algorithm|AWSAccessKeyId)=/i },
-    { reason: "r2_object_key", regex: /(^|[\s"'`])(?:runs|assets)\/[^?<#\s"'`]+/i },
+    { reason: "object_store_key", regex: /(^|[\s"'`])(?:runs|assets)\/[^?<#\s"'`]+/i },
     { reason: "vault_id", regex: /\b(?:vault|vlt|secret)[_:-][A-Za-z0-9][A-Za-z0-9_-]{7,}\b/i },
     {
         reason: "private_resource_handle",
@@ -422,7 +422,7 @@ const forbiddenStringPatterns = Object.freeze([
     { reason: "high_entropy_token", regex: /\b(?=[A-Za-z0-9_-]{40,}\b)(?=.*[A-Za-z])(?=.*\d)[A-Za-z0-9_-]{40,}\b/ }
 ]);
 function isForbiddenCustodyFieldName(key) {
-    return /^(apiKey|secretValue|bearerHash|signedUrl|r2Key|objectKey|vaultId|providerResponseBody|responseBody|privateResourceHandle|resourceHandle|rawBody)$/i.test(key);
+    return /^(apiKey|secretValue|bearerHash|signedUrl|objectStoreKey|objectKey|vaultId|providerResponseBody|responseBody|privateResourceHandle|resourceHandle|rawBody)$/i.test(key);
 }
 function assertSafeIdentifier(value, field) {
     assertNonEmptyString(value, field);