@aexhq/sdk 0.21.0 → 0.22.1

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

@@ -445,7 +445,16 @@ const forbiddenStringPatterns = Object.freeze([
     { reason: "vault_id", regex: /\b(?:vault|vlt|secret)[_:-][A-Za-z0-9][A-Za-z0-9_-]{7,}\b/i },
     {
         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
+        // `<keyword><sep><id>` opaque handles (`session_a1B2c3D4e5`, `file_9f8e7d…`).
+        // The keyword set overlaps ordinary English (agent/file/skill/resource/…), so
+        // the bare shape also matched documentation prose that simply chains those
+        // words with `_`/`-` (`agent_decision_failure`, `file_grounded`,
+        // `session_handoff_contract`, `agent-judgment` — read straight out of a
+        // skill-pack doc in tool-result text). The `accept` predicate keeps the shape
+        // but requires the id segment to look minted rather than spelled — i.e. carry
+        // a digit — so genuine handles stay flagged while dictionary-word prose does not.
+        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,
+        accept: isMintedResourceHandle
     },
     {
         reason: "high_entropy_token",
@@ -487,6 +496,20 @@ function isHighEntropySecretRun(run) {
     }
     return highEntropyShannonBits(run) >= 3.0;
 }
+/**
+ * Decide whether a `<keyword><sep><id>` shape-match is a genuinely minted private
+ * handle rather than dictionary-word prose. The id segment (everything after the
+ * first `_`/`-`/`:`) must carry a digit — the property that separates a minted
+ * opaque handle (`session_a1B2c3D4e5`, `file_9f8e7d6c5b4a`, `machine_1234567890`)
+ * from a chain of English words (`agent_decision_failure`, `file_grounded`). This
+ * mirrors `isHighEntropySecretRun`'s letter+digit requirement: a prefixless secret
+ * blob and a minted handle both carry digits; prose does not.
+ */
+function isMintedResourceHandle(match) {
+    const separatorIndex = match.search(/[_:-]/);
+    const id = match.slice(separatorIndex + 1);
+    return /\d/.test(id);
+}
 function highEntropyCharClassCount(value) {
     let count = 0;
     if (/[a-z]/.test(value))

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 };

package/dist/cli.mjs

@@ -350,6 +350,25 @@ var SKILL_BUNDLE_LIMITS = {
   defaultDirMode: 493
 };
 var ASSET_ID_PATTERN = /^asset_[A-Za-z0-9_-]{8,128}$/;
+var MOUNT_PATH_PATTERN = /^\/(?:[^/\0\\]+\/?)*$/;
+var MOUNT_PATH_MAX_LENGTH = 512;
+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}`);
+  }
+}
 function parseSkillRef(input, path) {
   if (input === null || typeof input !== "object" || Array.isArray(input)) {
     throw new Error(`${path} must be a SkillRef object`);
@@ -401,8 +420,11 @@ function parseAssetRefFields(record, path) {
     throw new Error(`${path}.name must be a non-empty string (<= 128 chars)`);
   }
   const mountPath = record.mountPath;
-  if (mountPath !== void 0 && (typeof mountPath !== "string" || mountPath.length === 0)) {
-    throw new Error(`${path}.mountPath, when provided, must be a non-empty string`);
+  if (mountPath !== void 0) {
+    if (typeof mountPath !== "string") {
+      throw new Error(`${path}.mountPath, when provided, must be a string`);
+    }
+    assertValidMountPath(mountPath, `${path}.mountPath`);
   }
   return {
     kind: "asset",
@@ -879,7 +901,16 @@ var forbiddenStringPatterns = Object.freeze([
   { reason: "vault_id", regex: /\b(?:vault|vlt|secret)[_:-][A-Za-z0-9][A-Za-z0-9_-]{7,}\b/i },
   {
     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
+    // `<keyword><sep><id>` opaque handles (`session_a1B2c3D4e5`, `file_9f8e7d…`).
+    // The keyword set overlaps ordinary English (agent/file/skill/resource/…), so
+    // the bare shape also matched documentation prose that simply chains those
+    // words with `_`/`-` (`agent_decision_failure`, `file_grounded`,
+    // `session_handoff_contract`, `agent-judgment` — read straight out of a
+    // skill-pack doc in tool-result text). The `accept` predicate keeps the shape
+    // but requires the id segment to look minted rather than spelled — i.e. carry
+    // a digit — so genuine handles stay flagged while dictionary-word prose does not.
+    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,
+    accept: isMintedResourceHandle
   },
   {
     reason: "high_entropy_token",
@@ -909,6 +940,11 @@ function isHighEntropySecretRun(run) {
   }
   return highEntropyShannonBits(run) >= 3;
 }
+function isMintedResourceHandle(match) {
+  const separatorIndex = match.search(/[_:-]/);
+  const id = match.slice(separatorIndex + 1);
+  return /\d/.test(id);
+}
 function highEntropyCharClassCount(value) {
   let count = 0;
   if (/[a-z]/.test(value))

package/dist/cli.mjs.sha256

@@ -1 +1 @@
-d05e5e074b577553d20fa3680f834b7941fe0cb7692c0a743975fcf36c4ec9b5  cli.mjs
+84dede6ed017defb49617f6f799912364125363867fa9ca8054150ebc0446286  cli.mjs

package/dist/client.js

@@ -820,18 +820,12 @@ async function prepareFiles(files, uploader) {
                 hash: bundle.contentHash,
                 contentType: "application/zip"
             });
-            refs.push(bundle.mountPath !== undefined
-                ? {
-                    kind: "asset",
-                    assetId: uploaded.assetId,
-                    name: bundle.name,
-                    mountPath: bundle.mountPath
-                }
-                : {
-                    kind: "asset",
-                    assetId: uploaded.assetId,
-                    name: bundle.name
-                });
+            refs.push({
+                kind: "asset",
+                assetId: uploaded.assetId,
+                name: bundle.name,
+                mountPath: bundle.mountPath
+            });
             continue;
         }
         refs.push(ref);