@aexhq/sdk 0.20.0 → 0.22.0

package/dist/_contracts/index.d.ts

@@ -10,6 +10,7 @@ export * from "./event-envelope.js";
 export * from "./connection-ticket.js";
 export * from "./event-stream-client.js";
 export * from "./run-unit.js";
+export * from "./run-trace.js";
 export * from "./runtime-manifest.js";
 export * from "./runtime-security-profile.js";
 export * from "./run-record.js";

package/dist/_contracts/index.js

@@ -10,6 +10,7 @@ export * from "./event-envelope.js";
 export * from "./connection-ticket.js";
 export * from "./event-stream-client.js";
 export * from "./run-unit.js";
+export * from "./run-trace.js";
 export * from "./runtime-manifest.js";
 export * from "./runtime-security-profile.js";
 export * from "./run-record.js";

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

@@ -106,6 +106,29 @@ export type AgentsMdRef = AssetRef;
 export declare function isAgentsMdAssetRef(ref: AgentsMdRef): ref is AssetRef;
 export type FileRef = AssetRef;
 export declare function isFileAssetRef(ref: FileRef): ref is AssetRef;
+/**
+ * The default mount DIRECTORY a `File` unzips into when the caller does not set
+ * `mountPath`. `/workspace` is also the agent's default working directory, so a
+ * file handed with no `mountPath` lands directly in the agent's cwd (e.g.
+ * `/workspace/source-video-subtitles.srt`).
+ */
+export declare const DEFAULT_FILE_MOUNT_PATH = "/workspace";
+/**
+ * A `mountPath` is an ABSOLUTE container directory under the workspace. It must
+ * start with `/`, contain no `..`/`.` traversal or NUL/backslash, and stay
+ * within {@link MOUNT_PATH_MAX_LENGTH}. The managed runtime rebases it under the
+ * workspace root, so a path outside `/workspace` is clamped there — the pattern
+ * just rejects obviously-malformed input at the SDK/BFF boundary. A trailing
+ * slash is allowed (it is a directory) but not required.
+ */
+export declare const MOUNT_PATH_PATTERN: RegExp;
+export declare const MOUNT_PATH_MAX_LENGTH = 512;
+/**
+ * Validate a `File.mountPath` (an absolute container directory). Shared by the
+ * SDK `File` builders and the BFF asset-ref parser so both reject the same
+ * malformed input. Throws with `field` context on failure.
+ */
+export declare function assertValidMountPath(value: string, field: string): void;
 /**
  * Parse a `SkillRef` from untrusted input. Used by the BFF run parser
  * and by the operations module when deserialising API responses. Only

package/dist/_contracts/run-config.js

@@ -99,6 +99,45 @@ export function isAgentsMdAssetRef(ref) {
 export function isFileAssetRef(ref) {
     return ref.kind === "asset";
 }
+/**
+ * The default mount DIRECTORY a `File` unzips into when the caller does not set
+ * `mountPath`. `/workspace` is also the agent's default working directory, so a
+ * file handed with no `mountPath` lands directly in the agent's cwd (e.g.
+ * `/workspace/source-video-subtitles.srt`).
+ */
+export const DEFAULT_FILE_MOUNT_PATH = "/workspace";
+/**
+ * A `mountPath` is an ABSOLUTE container directory under the workspace. It must
+ * start with `/`, contain no `..`/`.` traversal or NUL/backslash, and stay
+ * within {@link MOUNT_PATH_MAX_LENGTH}. The managed runtime rebases it under the
+ * workspace root, so a path outside `/workspace` is clamped there — the pattern
+ * just rejects obviously-malformed input at the SDK/BFF boundary. A trailing
+ * slash is allowed (it is a directory) but not required.
+ */
+export const MOUNT_PATH_PATTERN = /^\/(?:[^/\0\\]+\/?)*$/;
+export const MOUNT_PATH_MAX_LENGTH = 512;
+/**
+ * Validate a `File.mountPath` (an absolute container directory). Shared by the
+ * SDK `File` builders and the BFF asset-ref parser so both reject the same
+ * malformed input. Throws with `field` context on failure.
+ */
+export function assertValidMountPath(value, field) {
+    if (value.length === 0 || value.length > MOUNT_PATH_MAX_LENGTH) {
+        throw new Error(`${field} must be 1..${MOUNT_PATH_MAX_LENGTH} chars`);
+    }
+    if (!value.startsWith("/")) {
+        throw new Error(`${field} must be an absolute path starting with '/'`);
+    }
+    if (value.includes("\0") || value.includes("\\")) {
+        throw new Error(`${field} must not contain NUL or backslash`);
+    }
+    if (value.split("/").some((seg) => seg === "..")) {
+        throw new Error(`${field} must not contain '..' traversal segments`);
+    }
+    if (!MOUNT_PATH_PATTERN.test(value)) {
+        throw new Error(`${field} must match ${MOUNT_PATH_PATTERN.source}`);
+    }
+}
 /**
  * Parse a `SkillRef` from untrusted input. Used by the BFF run parser
  * and by the operations module when deserialising API responses. Only
@@ -162,8 +201,11 @@ export function parseAssetRefFields(record, path) {
         throw new Error(`${path}.name must be a non-empty string (<= 128 chars)`);
     }
     const mountPath = record.mountPath;
-    if (mountPath !== undefined && (typeof mountPath !== "string" || mountPath.length === 0)) {
-        throw new Error(`${path}.mountPath, when provided, must be a non-empty string`);
+    if (mountPath !== undefined) {
+        if (typeof mountPath !== "string") {
+            throw new Error(`${path}.mountPath, when provided, must be a string`);
+        }
+        assertValidMountPath(mountPath, `${path}.mountPath`);
     }
     return {
         kind: "asset",

package/dist/_contracts/run-custody.js

@@ -397,7 +397,7 @@ function visitCustodyValue(input, path, findings) {
 }
 function scanStringValue(value, path, findings) {
     for (const pattern of forbiddenStringPatterns) {
-        if (pattern.regex.test(value)) {
+        if (matchesForbiddenPattern(pattern, value)) {
             findings.push(Object.freeze({
                 path,
                 reason: pattern.reason,
@@ -406,11 +406,39 @@ function scanStringValue(value, path, findings) {
         }
     }
 }
+/**
+ * A pattern fires on a value if its `regex` matches AND — when the pattern
+ * carries an `accept` predicate — at least one matched run is accepted by it.
+ * The predicate lets a shape-matched run be VETOED per-match (the entropy
+ * catch-all uses it to skip content-addressed hashes and low-entropy slugs that
+ * its coarse regex would otherwise flag); shape-only patterns have no predicate.
+ */
+function matchesForbiddenPattern(pattern, value) {
+    if (!pattern.accept) {
+        return pattern.regex.test(value);
+    }
+    const scan = pattern.regex.global ? pattern.regex : new RegExp(pattern.regex.source, `${pattern.regex.flags}g`);
+    scan.lastIndex = 0;
+    let match;
+    while ((match = scan.exec(value)) !== null) {
+        if (pattern.accept(match[0])) {
+            return true;
+        }
+        if (match.index === scan.lastIndex) {
+            scan.lastIndex++;
+        }
+    }
+    return false;
+}
 const forbiddenStringPatterns = Object.freeze([
     { reason: "bearer_token", regex: /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/i },
     {
         reason: "provider_key",
-        regex: /\b(?:sk-(?:ant|proj|live|test|deepseek|openai)|xox[baprs]-|AIza)[A-Za-z0-9_-]{8,}/i
+        // Prefixed provider keys (`sk-…`, Slack `xox*-…`, Google `AIza…`). The bare
+        // `sk-` body is intentionally generic so an unrecognised vendor's `sk-` key
+        // (e.g. DeepSeek `sk-<hex>`, OpenRouter `sk-or-…`) is still caught by shape,
+        // not left to the narrowed entropy catch-all below.
+        regex: /\b(?:sk-[A-Za-z0-9_-]{16,}|xox[baprs]-[A-Za-z0-9-]{8,}|AIza[A-Za-z0-9_-]{8,})/i
     },
     { reason: "signed_url", regex: /[?&](?:X-Amz-Signature|X-Amz-Credential|X-Amz-Algorithm|AWSAccessKeyId)=/i },
     { reason: "object_store_key", regex: /(^|[\s"'`])(?:runs|assets)\/[^?<#\s"'`]+/i },
@@ -419,8 +447,71 @@ const forbiddenStringPatterns = Object.freeze([
         reason: "private_resource_handle",
         regex: /\b(?:machine|session|agent|file|skill|env|resource|handle|token_hash|bearer_hash)[_:-][A-Za-z0-9][A-Za-z0-9_-]{7,}\b/i
     },
-    { reason: "high_entropy_token", regex: /\b(?=[A-Za-z0-9_-]{40,}\b)(?=.*[A-Za-z])(?=.*\d)[A-Za-z0-9_-]{40,}\b/ }
+    {
+        reason: "high_entropy_token",
+        // Catch-all for an unrecognised opaque secret blob. The candidate run
+        // EXCLUDES `_` (so `SCREAMING_SNAKE` env names and `slug_with_words` URL
+        // segments split instead of fusing into a phantom 40-char run — the live
+        // false positive was `ted_season_2_peacock_official_discussion_thread` in
+        // web-search result text and a fetched URL), and the `accept` predicate
+        // vetoes content-addressed hashes (md5/sha1/sha256 digests — the platform's
+        // OWN asset filenames) and low-entropy / single-class runs so only genuine
+        // opaque secrets remain. Slash-bearing secrets (signed URLs, connection
+        // strings, `Bearer …`) are covered by the named patterns above.
+        regex: /\b[A-Za-z0-9-]{40,}\b/,
+        accept: isHighEntropySecretRun
+    }
 ]);
+/** A content-addressed hash (md5/sha1/sha256 hex digest) — the platform's own
+ * asset filenames and content references. Exempt from the entropy catch-all so
+ * a captured output named after its sha256 (or a hash echoed in tool-result
+ * text) is not misclassified as a leaked secret. */
+const CONTENT_HASH_RUN = /^(?:[0-9a-f]{32}|[0-9a-f]{40}|[0-9a-f]{64})$/i;
+/**
+ * Decide whether a coarse `[A-Za-z0-9-]{40,}` run is a genuine opaque secret.
+ * Rejects content-addressed hashes, then requires both character-class
+ * diversity (≥2 of lower/upper/digit) and high Shannon entropy — the property
+ * that separates an opaque key blob from a long dictionary-ish identifier. A
+ * real prefixless secret (base64url/alnum-mixed) clears both gates; a hash, a
+ * hyphenated slug, or a single-class run does not.
+ */
+function isHighEntropySecretRun(run) {
+    if (CONTENT_HASH_RUN.test(run)) {
+        return false;
+    }
+    if (!/[A-Za-z]/.test(run) || !/\d/.test(run)) {
+        return false;
+    }
+    if (highEntropyCharClassCount(run) < 2) {
+        return false;
+    }
+    return highEntropyShannonBits(run) >= 3.0;
+}
+function highEntropyCharClassCount(value) {
+    let count = 0;
+    if (/[a-z]/.test(value))
+        count++;
+    if (/[A-Z]/.test(value))
+        count++;
+    if (/[0-9]/.test(value))
+        count++;
+    return count;
+}
+function highEntropyShannonBits(value) {
+    if (value.length === 0) {
+        return 0;
+    }
+    const counts = new Map();
+    for (const char of value) {
+        counts.set(char, (counts.get(char) ?? 0) + 1);
+    }
+    let bits = 0;
+    for (const count of counts.values()) {
+        const p = count / value.length;
+        bits -= p * Math.log2(p);
+    }
+    return bits;
+}
 function isForbiddenCustodyFieldName(key) {
     return /^(apiKey|secretValue|bearerHash|signedUrl|objectStoreKey|objectKey|vaultId|providerResponseBody|responseBody|privateResourceHandle|resourceHandle|rawBody)$/i.test(key);
 }

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

@@ -0,0 +1,105 @@
+/**
+ * Typed decoders for a `listEvents(runId)` stream.
+ *
+ * `listEvents` returns the loose {@link RunEvent} wire shape: `type` at the top
+ * level, but the tool name at `data.name`, the call args at `data.arguments`,
+ * assistant text at `data.text`, and — the awkward part — a `TOOL_CALL_RESULT`
+ * carries no name, so a consumer must correlate each result back to its
+ * `TOOL_CALL_START` by `data.id` (the tool-call id). Every consumer ended up
+ * re-implementing that correlation; these helpers do it once, typed and pure.
+ *
+ * They are total and side-effect-free: pass the array `listEvents` returns and
+ * get back structured traces. Unknown event types are ignored (forward-compat),
+ * a result with no matching start surfaces as an orphan (never dropped silently),
+ * and timing falls back gracefully when a `recordedAt` is absent.
+ *
+ * Pairs with {@link Run.usage}: while a run executes `Run.usage` is empty — the
+ * per-turn token counts live ONLY in the `aex.usage` CUSTOM events — so
+ * {@link summarizeRunUsage} reconstructs the running total from the same stream.
+ */
+import type { UsageSummary } from "./runtime-types.js";
+/**
+ * One decoded tool call: the `TOOL_CALL_START` and its correlated
+ * `TOOL_CALL_RESULT` (when present), with timing. `result` is undefined while a
+ * call is still in flight (the start has arrived but not the result), so a
+ * mid-run decode shows in-progress calls honestly rather than dropping them.
+ */
+export interface ToolCallTrace {
+    /** The tool-call id (`data.id`) that pairs the start with its result. */
+    readonly id: string;
+    /** The tool name (from the `TOOL_CALL_START`). */
+    readonly name: string;
+    /** The call arguments (`data.arguments`), or `{}` when absent. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** The id of the assistant message that issued the call, when present. */
+    readonly messageId?: string;
+    /** Event sequence of the `TOOL_CALL_START` (ordering within the run). */
+    readonly startSeq?: number;
+    /** ISO-8601 time of the `TOOL_CALL_START`, when the event carried one. */
+    readonly startedAt?: string;
+    /** The correlated result; undefined while the call is still in flight. */
+    readonly result?: ToolCallResult;
+    /** Result wall-clock minus start wall-clock (ms); undefined if either time is missing. */
+    readonly durationMs?: number;
+}
+/** The result half of a {@link ToolCallTrace}, decoded from `TOOL_CALL_RESULT`. */
+export interface ToolCallResult {
+    /** True when the tool reported an error (`data.isError`). */
+    readonly isError: boolean;
+    /** The tool's result content, passed through verbatim (`data.content`). */
+    readonly content: unknown;
+    /** Event sequence of the `TOOL_CALL_RESULT`. */
+    readonly seq?: number;
+    /** ISO-8601 time of the `TOOL_CALL_RESULT`, when the event carried one. */
+    readonly recordedAt?: string;
+}
+/** One assistant text block, decoded from a `TEXT_MESSAGE_CONTENT` event. */
+export interface AssistantTextEntry {
+    readonly text: string;
+    readonly messageId?: string;
+    readonly seq?: number;
+    readonly recordedAt?: string;
+}
+/**
+ * A decoded view of a run's event stream: the correlated tool calls, the
+ * aggregate token usage, and the assistant text — everything a consumer
+ * previously hand-decoded from `listEvents`.
+ */
+export interface RunTrace {
+    readonly toolCalls: readonly ToolCallTrace[];
+    readonly usage: UsageSummary;
+    readonly text: readonly AssistantTextEntry[];
+}
+/** The loose event shape these decoders read — the {@link RunEvent} subset they touch. */
+interface TraceEvent {
+    readonly type: string;
+    readonly seq?: number;
+    readonly recordedAt?: string;
+    readonly data?: unknown;
+    readonly [key: string]: unknown;
+}
+/**
+ * Decode a `listEvents` stream into correlated tool-call traces, in start order.
+ *
+ * Each `TOOL_CALL_START` opens a trace keyed by `data.id`; the matching
+ * `TOOL_CALL_RESULT` (same `data.id`) fills in `result` + `durationMs`. A result
+ * whose id never had a start is surfaced as an orphan trace (empty `name`, no
+ * `args`) rather than dropped, so a partial/mis-ordered stream never hides a
+ * result. Pure — no I/O, input is not mutated.
+ */
+export declare function decodeToolCalls(events: readonly TraceEvent[]): readonly ToolCallTrace[];
+/**
+ * Sum the per-turn `aex.usage` CUSTOM events into one {@link UsageSummary} —
+ * the running token total a customer otherwise hand-sums while watching a run.
+ * `totalTokens` is the sum of input + output tokens. Pure.
+ */
+export declare function summarizeRunUsage(events: readonly TraceEvent[]): UsageSummary;
+/** Decode the assistant text blocks (`TEXT_MESSAGE_CONTENT`) in stream order. Pure. */
+export declare function decodeAssistantText(events: readonly TraceEvent[]): readonly AssistantTextEntry[];
+/**
+ * Decode a whole `listEvents` stream in one pass: correlated tool calls,
+ * aggregate {@link UsageSummary}, and assistant text. Convenience over the three
+ * focused decoders; pure.
+ */
+export declare function summarizeRunTrace(events: readonly TraceEvent[]): RunTrace;
+export {};

package/dist/_contracts/run-trace.js

@@ -0,0 +1,174 @@
+/**
+ * Typed decoders for a `listEvents(runId)` stream.
+ *
+ * `listEvents` returns the loose {@link RunEvent} wire shape: `type` at the top
+ * level, but the tool name at `data.name`, the call args at `data.arguments`,
+ * assistant text at `data.text`, and — the awkward part — a `TOOL_CALL_RESULT`
+ * carries no name, so a consumer must correlate each result back to its
+ * `TOOL_CALL_START` by `data.id` (the tool-call id). Every consumer ended up
+ * re-implementing that correlation; these helpers do it once, typed and pure.
+ *
+ * They are total and side-effect-free: pass the array `listEvents` returns and
+ * get back structured traces. Unknown event types are ignored (forward-compat),
+ * a result with no matching start surfaces as an orphan (never dropped silently),
+ * and timing falls back gracefully when a `recordedAt` is absent.
+ *
+ * Pairs with {@link Run.usage}: while a run executes `Run.usage` is empty — the
+ * per-turn token counts live ONLY in the `aex.usage` CUSTOM events — so
+ * {@link summarizeRunUsage} reconstructs the running total from the same stream.
+ */
+const CUSTOM_USAGE_NAME = "aex.usage";
+/** snake_case `aex.usage` field → the camelCase {@link UsageSummary} field. */
+const USAGE_FIELD_MAP = {
+    input_tokens: "inputTokens",
+    output_tokens: "outputTokens",
+    cache_read_input_tokens: "cacheReadInputTokens",
+    cache_creation_input_tokens: "cacheCreationInputTokens"
+};
+/**
+ * Decode a `listEvents` stream into correlated tool-call traces, in start order.
+ *
+ * Each `TOOL_CALL_START` opens a trace keyed by `data.id`; the matching
+ * `TOOL_CALL_RESULT` (same `data.id`) fills in `result` + `durationMs`. A result
+ * whose id never had a start is surfaced as an orphan trace (empty `name`, no
+ * `args`) rather than dropped, so a partial/mis-ordered stream never hides a
+ * result. Pure — no I/O, input is not mutated.
+ */
+export function decodeToolCalls(events) {
+    const order = [];
+    const byId = new Map();
+    for (const event of events) {
+        const data = asRecord(event.data);
+        if (event.type === "TOOL_CALL_START") {
+            const id = asString(data.id);
+            if (id === undefined)
+                continue;
+            const trace = {
+                id,
+                name: asString(data.name) ?? "",
+                args: asRecord(data.arguments)
+            };
+            const messageId = asString(data.messageId);
+            if (messageId !== undefined)
+                trace.messageId = messageId;
+            if (typeof event.seq === "number")
+                trace.startSeq = event.seq;
+            if (typeof event.recordedAt === "string")
+                trace.startedAt = event.recordedAt;
+            if (!byId.has(id))
+                order.push(id);
+            byId.set(id, trace);
+            continue;
+        }
+        if (event.type === "TOOL_CALL_RESULT") {
+            const id = asString(data.id);
+            if (id === undefined)
+                continue;
+            const result = {
+                isError: data.isError === true,
+                content: data.content ?? null
+            };
+            if (typeof event.seq === "number")
+                result.seq = event.seq;
+            if (typeof event.recordedAt === "string")
+                result.recordedAt = event.recordedAt;
+            let trace = byId.get(id);
+            if (trace === undefined) {
+                // Orphan result (no matching start) — surface it, never drop it.
+                trace = { id, name: "", args: {} };
+                order.push(id);
+                byId.set(id, trace);
+            }
+            trace.result = result;
+            const duration = durationMs(trace.startedAt, result.recordedAt);
+            if (duration !== undefined)
+                trace.durationMs = duration;
+            continue;
+        }
+    }
+    return order.map((id) => byId.get(id));
+}
+/**
+ * Sum the per-turn `aex.usage` CUSTOM events into one {@link UsageSummary} —
+ * the running token total a customer otherwise hand-sums while watching a run.
+ * `totalTokens` is the sum of input + output tokens. Pure.
+ */
+export function summarizeRunUsage(events) {
+    const totals = { inputTokens: 0, outputTokens: 0, cacheReadInputTokens: 0, cacheCreationInputTokens: 0 };
+    let seen = false;
+    for (const event of events) {
+        if (event.type !== "CUSTOM")
+            continue;
+        const data = asRecord(event.data);
+        if (asString(data.name) !== CUSTOM_USAGE_NAME)
+            continue;
+        const value = asRecord(data.value);
+        for (const [snake, camel] of Object.entries(USAGE_FIELD_MAP)) {
+            const n = value[snake];
+            if (typeof n === "number" && Number.isFinite(n)) {
+                totals[camel] += n;
+                seen = true;
+            }
+        }
+    }
+    if (!seen)
+        return {};
+    return {
+        inputTokens: totals.inputTokens,
+        outputTokens: totals.outputTokens,
+        cacheReadInputTokens: totals.cacheReadInputTokens,
+        cacheCreationInputTokens: totals.cacheCreationInputTokens,
+        totalTokens: totals.inputTokens + totals.outputTokens
+    };
+}
+/** Decode the assistant text blocks (`TEXT_MESSAGE_CONTENT`) in stream order. Pure. */
+export function decodeAssistantText(events) {
+    const out = [];
+    for (const event of events) {
+        if (event.type !== "TEXT_MESSAGE_CONTENT")
+            continue;
+        const data = asRecord(event.data);
+        const text = asString(data.text);
+        if (text === undefined)
+            continue;
+        const entry = { text };
+        const messageId = asString(data.messageId);
+        if (messageId !== undefined)
+            entry.messageId = messageId;
+        if (typeof event.seq === "number")
+            entry.seq = event.seq;
+        if (typeof event.recordedAt === "string")
+            entry.recordedAt = event.recordedAt;
+        out.push(entry);
+    }
+    return out;
+}
+/**
+ * Decode a whole `listEvents` stream in one pass: correlated tool calls,
+ * aggregate {@link UsageSummary}, and assistant text. Convenience over the three
+ * focused decoders; pure.
+ */
+export function summarizeRunTrace(events) {
+    return {
+        toolCalls: decodeToolCalls(events),
+        usage: summarizeRunUsage(events),
+        text: decodeAssistantText(events)
+    };
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function durationMs(start, end) {
+    if (start === undefined || end === undefined)
+        return undefined;
+    const a = Date.parse(start);
+    const b = Date.parse(end);
+    if (!Number.isFinite(a) || !Number.isFinite(b))
+        return undefined;
+    const delta = b - a;
+    return delta >= 0 ? delta : undefined;
+}
+//# sourceMappingURL=run-trace.js.map

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

@@ -62,6 +62,21 @@ export interface RuntimeManifest {
      * resolves against this exact map.
      */
     readonly envVars: Readonly<Record<string, string>>;
+    /**
+     * The resolved in-container mount DIRECTORY of each submitted `File`, so the
+     * caller can learn where a handed file landed. `mountPath` is the validated
+     * directory the archive unzipped into (the SDK default is `/workspace`); a
+     * single file lands at `<mountPath>/<realFilename>`, a folder lands its entries
+     * under `<mountPath>/`. Empty when the run carried no files.
+     */
+    readonly mountedFiles: readonly MountedFileManifest[];
+}
+/** One submitted `File`'s resolved mount directory (surfaced on the Run record). */
+export interface MountedFileManifest {
+    /** The file's storage slug (`FileRef.name`). */
+    readonly name: string;
+    /** Absolute container directory the file unzipped into (defaults to `/workspace`). */
+    readonly mountPath: string;
 }
 /**
  * Managed-runner container paths. Kept here so the BFF, worker, and
@@ -96,6 +111,15 @@ export interface BuildRuntimeManifestInput {
      * (or a future bypass) can't poison the manifest.
      */
     readonly customerEnvVars?: Readonly<Record<string, string>> | undefined;
+    /**
+     * The validated submission's `files` refs. Each resolves to one
+     * {@link MountedFileManifest} entry surfacing the resolved mount directory
+     * (the SDK default is `/workspace`). Absent / non-array ⇒ no mounted files.
+     */
+    readonly files?: readonly {
+        readonly name?: unknown;
+        readonly mountPath?: unknown;
+    }[] | undefined;
 }
 /**
  * Build the runtime manifest for a single submission. Pure function:

package/dist/_contracts/runtime-manifest.js

@@ -53,6 +53,13 @@ export function runtimePathsFor(provider) {
  * need the submission parser.
  */
 const AEX_PREFIX = "AEX_";
+/**
+ * Default mount DIRECTORY for a `File` with no explicit `mountPath`. Mirrors
+ * `DEFAULT_FILE_MOUNT_PATH` in `run-config.ts`; duplicated here so this module
+ * stays self-contained (tree-shakeable) — the same reason {@link AEX_PREFIX}
+ * is inlined rather than imported from the submission parser.
+ */
+const DEFAULT_FILE_MOUNT_PATH = "/workspace";
 /**
  * Build the runtime manifest for a single submission. Pure function:
  * same input → same output → safe to call from the BFF response path
@@ -82,6 +89,13 @@ export function buildRuntimeManifest(input) {
         customerEnvVars[key] = value;
     }
     const envVars = Object.freeze({ ...aexEnvVars, ...customerEnvVars });
+    const mountedFiles = [];
+    for (const f of Array.isArray(input.files) ? input.files : []) {
+        if (typeof f.name !== "string" || f.name.length === 0)
+            continue;
+        const mountPath = typeof f.mountPath === "string" && f.mountPath.length > 0 ? f.mountPath : DEFAULT_FILE_MOUNT_PATH;
+        mountedFiles.push(Object.freeze({ name: f.name, mountPath }));
+    }
     return Object.freeze({
         provider: input.provider,
         skillsRoot: paths.skillsRoot,
@@ -92,7 +106,8 @@ export function buildRuntimeManifest(input) {
         readme: paths.readme,
         runtimeJson: paths.runtimeJson,
         runtimeEnv: paths.runtimeEnv,
-        envVars
+        envVars,
+        mountedFiles: Object.freeze(mountedFiles)
     });
 }
 //# sourceMappingURL=runtime-manifest.js.map

package/dist/_contracts/runtime-types.d.ts

@@ -16,7 +16,24 @@ export interface Run {
     readonly createdAt?: string;
     readonly updatedAt?: string;
     readonly terminalAt?: string | null;
+    /**
+     * The run's EXECUTION start (ISO-8601) — when the agent actually began
+     * running, distinct from {@link createdAt} (submission/accept time). Present
+     * from the moment the run starts executing and throughout its live duration;
+     * absent before it starts and after the run's live object is torn down (a
+     * terminal run also carries {@link terminalAt} and {@link costTelemetry}
+     * durations).
+     */
+    readonly startedAt?: string;
     readonly errorMessage?: string | null;
+    /**
+     * Aggregate token usage. NOTE: mid-run this is NOT populated — detailed
+     * token counts live ONLY in the per-turn `aex.usage` CUSTOM events on the
+     * event stream until the run settles. To follow token/cost progress while a
+     * run executes, decode the event stream with `summarizeRunTrace(events)`
+     * (its `usage` totals the `aex.usage` events). Settled cost/usage rides
+     * {@link costTelemetry}.
+     */
     readonly usage?: UsageSummary;
     readonly costTelemetry?: import("./run-cost.js").RunCostTelemetry;
     readonly runtimeManifest?: import("./runtime-manifest.js").RuntimeManifest;

package/dist/_contracts/submission.js

@@ -1526,9 +1526,8 @@ function parseFiles(input) {
             throw new Error(`submission.files duplicate assetId: ${fields.assetId}`);
         }
         seenAssetId.add(fields.assetId);
-        if (fields.mountPath !== undefined && !fields.mountPath.startsWith("/")) {
-            throw new Error(`${path}.mountPath must start with '/' if provided`);
-        }
+        // mountPath is validated as an absolute container directory by
+        // parseAssetRefFields → assertValidMountPath (above), so no extra check here.
         return fields.mountPath !== undefined
             ? { kind: "asset", assetId: fields.assetId, name: fields.name, mountPath: fields.mountPath }
             : { kind: "asset", assetId: fields.assetId, name: fields.name };