@aexhq/sdk 0.40.15 → 0.41.0

package/dist/_contracts/submission.js

@@ -1,6 +1,6 @@
-import { SKILL_NAME_PATTERN, SKILL_RESERVED_NAMES, TOOL_NAME_PATTERN, normaliseSkillBundlePath, parseAssetRefFields, parseMcpServerRef } from "./run-config.js";
-import { parseRunTimeout, parseRuntimeSize } from "./runtime-sizes.js";
-import { assertRunModelMatchesProvider, parseRunModel } from "./models.js";
+import { SKILL_NAME_PATTERN, SKILL_RESERVED_NAMES, TOOL_NAME_PATTERN, normaliseSkillBundlePath, parseAssetRefFields, parseMcpServerRef } from "./session-config.js";
+import { parseSessionTimeout, parseRuntimeSize } from "./runtime-sizes.js";
+import { assertModelNameMatchesProvider, parseModelName } from "./models.js";
 import { parseRuntimeSecurityProfile } from "./runtime-security-profile.js";
 /**
  * Reserved prefix for aex-set runtime env vars (`AEX_CLI`,
@@ -61,12 +61,12 @@ export function packageInstallString(pkg) {
     }
 }
 /**
- * Run-time provider selector. Aex exposes one customer interface
+ * SessionRecord-time provider selector. Aex exposes one customer interface
  * for every provider. All new submissions execute through the managed
  * runtime; provider selection only decides which upstream model route
  * the managed provider-proxy uses.
  */
-export const RUN_PROVIDERS = [
+export const PROVIDERS = [
     "anthropic",
     "deepseek",
     "openai",
@@ -76,7 +76,7 @@ export const RUN_PROVIDERS = [
     "doubao",
     "doubao-cn"
 ];
-export const DEFAULT_RUN_PROVIDER = "anthropic";
+export const DEFAULT_PROVIDER = "anthropic";
 /**
  * Symbol-style accessors for the closed provider set. Prefer these over raw
  * strings so an invalid token is a compile error, not a runtime 400 — e.g.
@@ -85,8 +85,8 @@ export const DEFAULT_RUN_PROVIDER = "anthropic";
  * submission field; name it explicitly with one of these constants rather than
  * relying on the model alone to determine routing.
  *
- * Every value mirrors {@link RUN_PROVIDERS} exactly; a unit test asserts
- * `Object.values(Providers)` deep-equals `RUN_PROVIDERS` so the two can never
+ * Every value mirrors {@link PROVIDERS} exactly; a unit test asserts
+ * `Object.values(Providers)` deep-equals `PROVIDERS` so the two can never
  * drift.
  */
 export const Providers = {
@@ -162,7 +162,7 @@ function parseEnvironment(input) {
  *     targets.
  *   - Bounded: max ENV_VARS_MAX_ENTRIES entries, max
  *     ENV_VARS_MAX_VALUE_BYTES per value, max ENV_VARS_MAX_TOTAL_BYTES
- *     overall. The caps stop a runaway customer from making the
+ *     overall. The caps stop a sessionaway customer from making the
  *     mounted RUNTIME files unbounded.
  *   - Values are arbitrary UTF-8 strings, EXCEPT NUL bytes are
  *     rejected (NUL terminates C-strings and breaks env-var
@@ -187,7 +187,7 @@ function parseEnvVars(input) {
             throw new Error(`submission.environment.envVars.${key} key must match /^[A-Z_][A-Z0-9_]*$/`);
         }
         if (key.startsWith(AEX_RESERVED_ENV_PREFIX)) {
-            throw new Error(`submission.environment.envVars.${key} uses reserved prefix "${AEX_RESERVED_ENV_PREFIX}" (set by aex runtime)`);
+            throw new Error(`submission.environment.envVars.${key} uses reserved prefix "${AEX_RESERVED_ENV_PREFIX}" (set by aex starttime)`);
         }
         const raw = value[key];
         if (typeof raw !== "string") {
@@ -318,7 +318,7 @@ export function crossValidateSecretEnvAndValues(secretEnv, envSecrets) {
 export function parseInlineSecrets(input) {
     // Absent/null secrets collapse to an empty bundle; the credential-policy gate
     // (enforceCredentialSecretPolicy) decides whether that is admissible for the
-    // run's mode (a run inheriting keys server-side may legitimately omit them).
+    // session's mode (a session inheriting keys server-side may legitimately omit them).
     if (input === undefined || input === null)
         return {};
     const value = requireRecord(input, "secrets");
@@ -345,7 +345,7 @@ export function parseInlineSecrets(input) {
 }
 /**
  * Parse the per-provider BYOK key map. Each key must name a known
- * {@link RunProvider}; each value must be a non-empty string. Returns
+ * {@link ProviderName}; each value must be a non-empty string. Returns
  * `undefined` for an absent or empty map so the spread above stays clean.
  */
 function parseApiKeys(input) {
@@ -354,8 +354,8 @@ function parseApiKeys(input) {
     const value = requireRecord(input, "secrets.apiKeys");
     const out = {};
     for (const [provider, key] of Object.entries(value)) {
-        if (!RUN_PROVIDERS.includes(provider)) {
-            throw new Error(`secrets.apiKeys["${provider}"] is not a known provider; permitted: ${RUN_PROVIDERS.join(", ")}`);
+        if (!PROVIDERS.includes(provider)) {
+            throw new Error(`secrets.apiKeys["${provider}"] is not a known provider; permitted: ${PROVIDERS.join(", ")}`);
         }
         if (typeof key !== "string" || key.length === 0) {
             throw new Error(`secrets.apiKeys["${provider}"] must be a non-empty string`);
@@ -522,7 +522,7 @@ function isJsonValue(input) {
     }
     return false;
 }
-export function parseRunSubmissionRequest(input, options = {}) {
+export function parseSessionSubmissionRequest(input, options = {}) {
     const value = requireRecord(input, "submission");
     const allowedTopLevelFields = new Set([
         "workspaceId",
@@ -553,18 +553,18 @@ export function parseRunSubmissionRequest(input, options = {}) {
         }
         assertNoSecretBearingFields(fieldValue, [key]);
     }
-    const provider = parseRunProvider(value.provider);
+    const provider = parseProviderName(value.provider);
     const runtimeSize = parseRuntimeSize(value.runtimeSize);
-    const timeoutMs = parseRunTimeout(value.timeout);
-    const webhook = parseRunWebhook(value.webhook);
-    const limits = parseRunLimits(value.limits);
-    const machine = parseRunMachine(value.machine);
+    const timeoutMs = parseSessionTimeout(value.timeout);
+    const webhook = parseSessionWebhook(value.webhook);
+    const limits = parseSessionLimits(value.limits);
+    const machine = parseSessionMachine(value.machine);
     const secrets = parseInlineSecrets(value.secrets);
     enforceCredentialSecretPolicy(secrets, provider);
     const submission = parseSubmission(value.submission, {
         trustedReparse: options.trustedReparse === true
     });
-    assertRunModelMatchesProvider(provider, submission.model);
+    assertModelNameMatchesProvider(provider, submission.model);
     // Fail-closed streaming: `outputMode:'stream'` on a non-streamable provider is
     // a hard reject at parse time (no silent downgrade).
     assertStreamableOutputMode(submission.outputMode, provider);
@@ -601,14 +601,14 @@ export function parseRunSubmissionRequest(input, options = {}) {
     };
 }
 /**
- * Parse + SSRF-shape-validate the optional per-run `webhook`. The URL must be
+ * Parse + SSRF-shape-validate the optional per-session `webhook`. The URL must be
  * https with no userinfo (a `user:pass@host` URL is rejected — credentials must
  * not ride in a callback URL). Unknown subfields are rejected so the strict
  * top-level allow-list extends to the nested object. Returns `undefined` when
  * absent. Delivery-time re-resolution + IP-deny checks live server-side; this
  * is the submit-time shape gate.
  */
-export function parseRunWebhook(input) {
+export function parseSessionWebhook(input) {
     if (input === undefined) {
         return undefined;
     }
@@ -636,28 +636,28 @@ export function parseRunWebhook(input) {
     return { url };
 }
 /**
- * Parse the optional per-run `limits` override. Mirrors {@link parseRunWebhook}:
+ * Parse the optional per-session `limits` override. Mirrors {@link parseSessionWebhook}:
  * absent ⇒ `undefined`; a non-object or any unknown subfield is rejected so the
  * strict top-level allow-list extends to the nested object. Each present field
  * is validated as a positive safe integer via {@link optionalPositiveInt}.
  *
  * This is a SHAPE/positivity gate only — it does NOT clamp to the workspace or
- * platform ceilings (that precedence lives in the resolver, `resolveRunLimits`).
+ * platform ceilings (that precedence lives in the resolver, `resolveSessionLimits`).
  * Only the present fields are returned; an all-absent override (e.g. `{}`)
  * collapses to `undefined` so it carries no signal onto the request.
  */
-export function parseRunLimits(input) {
+export function parseSessionLimits(input) {
     if (input === undefined) {
         return undefined;
     }
     const value = requireRecord(input, "limits");
-    const allowed = new Set(["maxConcurrentChildRuns", "maxSubagentDepth", "maxSpendUsd", "maxTurns"]);
+    const allowed = new Set(["maxConcurrentChildSessions", "maxSubagentDepth", "maxSpendUsd", "maxTurns"]);
     for (const key of Object.keys(value)) {
         if (!allowed.has(key)) {
             throw new Error(`limits.${key} is not an allowed field; permitted: ${[...allowed].join(", ")}`);
         }
     }
-    const maxConcurrentChildRuns = optionalPositiveInt(value.maxConcurrentChildRuns, "limits.maxConcurrentChildRuns");
+    const maxConcurrentChildSessions = optionalPositiveInt(value.maxConcurrentChildSessions, "limits.maxConcurrentChildSessions");
     const maxSubagentDepth = optionalPositiveInt(value.maxSubagentDepth, "limits.maxSubagentDepth");
     // maxSpendUsd is a USD amount (may be fractional, e.g. $2.50) so it is a positive
     // NUMBER, not a positive int. Clamping to the workspace/platform ceiling is the
@@ -667,32 +667,32 @@ export function parseRunLimits(input) {
     // is the resolver's job; here we enforce shape + positivity only.
     const maxTurns = optionalPositiveInt(value.maxTurns, "limits.maxTurns");
     // Collapse an all-absent override (e.g. `limits: {}`) to `undefined` so it never
-    // lands an empty object on the request — matches sibling parsers (parseRunWebhook,
+    // lands an empty object on the request — matches sibling parsers (parseSessionWebhook,
     // parseEnvironment). The resolver supplies platform defaults for absent fields.
-    if (maxConcurrentChildRuns === undefined &&
+    if (maxConcurrentChildSessions === undefined &&
         maxSubagentDepth === undefined &&
         maxSpendUsd === undefined &&
         maxTurns === undefined) {
         return undefined;
     }
     return {
-        ...(maxConcurrentChildRuns !== undefined ? { maxConcurrentChildRuns } : {}),
+        ...(maxConcurrentChildSessions !== undefined ? { maxConcurrentChildSessions } : {}),
         ...(maxSubagentDepth !== undefined ? { maxSubagentDepth } : {}),
         ...(maxSpendUsd !== undefined ? { maxSpendUsd } : {}),
         ...(maxTurns !== undefined ? { maxTurns } : {})
     };
 }
 /**
- * Boot-session budget fragment. The public submit surface names a run's spend
+ * Boot-session budget fragment. The public submit surface names a session's spend
  * cap `limits.maxSpendUsd`; the frozen boot session config the managed runtime
  * folds the loop against names the SAME USD value `budgetUsd` — the field the
- * session planner reads to enforce/terminate a run that would out-spend its cap.
+ * session planner reads to enforce/terminate a session that would out-spend its cap.
  * This is the single source of truth for that wire→boot name mapping so the two
  * layers can never drift.
  *
  * Returns a fragment safe to spread into `sessionConfig.limits`: `{ budgetUsd }`
- * when a cap is set, `{}` when none is (an absent cap stays absent — the run is
- * unbounded per-run, subject only to the run timeout + the per-workspace cap).
+ * when a cap is set, `{}` when none is (an absent cap stays absent — the session is
+ * unbounded per-session, subject only to the session timeout + the per-workspace cap).
  * Pure: same input ⇒ same output.
  */
 export function sessionBudgetLimits(limits) {
@@ -702,15 +702,15 @@ export function sessionBudgetLimits(limits) {
     return { budgetUsd: limits.maxSpendUsd };
 }
 /**
- * Parse the optional per-run `machine` capacity intent. Mirrors
- * {@link parseRunWebhook}: absent ⇒ `undefined`; a non-object or any unknown
+ * Parse the optional per-session `machine` capacity intent. Mirrors
+ * {@link parseSessionWebhook}: absent ⇒ `undefined`; a non-object or any unknown
  * subfield is rejected so the strict top-level allow-list extends to the nested
  * object. `spot` must be a boolean when present. A no-signal object (e.g.
  * `machine: {}`) collapses to `undefined` so it never lands an empty object on
  * the request. An explicit `spot` (true or false) is preserved verbatim. Only
  * shape is validated here — capacity selection is a runtime concern.
  */
-export function parseRunMachine(input) {
+export function parseSessionMachine(input) {
     if (input === undefined) {
         return undefined;
     }
@@ -729,23 +729,23 @@ export function parseRunMachine(input) {
     }
     return { spot: value.spot };
 }
-export function parseRunProvider(input) {
+export function parseProviderName(input) {
     if (input === undefined) {
-        return DEFAULT_RUN_PROVIDER;
+        return DEFAULT_PROVIDER;
     }
-    if (typeof input !== "string" || !RUN_PROVIDERS.includes(input)) {
-        throw new Error(`provider must be one of: ${RUN_PROVIDERS.join(", ")} (got ${JSON.stringify(input)})`);
+    if (typeof input !== "string" || !PROVIDERS.includes(input)) {
+        throw new Error(`provider must be one of: ${PROVIDERS.join(", ")} (got ${JSON.stringify(input)})`);
     }
     return input;
 }
 /**
  * Cross-check the supplied secrets bundle against the credential mode. BYOK
- * requires `secrets.apiKeys[provider]` (the key for the run's own `provider`).
- * Additional provider keys are optional (validated for shape only) so the run
+ * requires `secrets.apiKeys[provider]` (the key for the session's own `provider`).
+ * Additional provider keys are optional (validated for shape only) so the session
  * can supply keys for the other providers its subagents may use. MCP / proxy
  * endpoint auth carry across providers and are not checked here.
  *
- * A CHILD run (`inheritsFromParent`) is exempt from the own-key requirement: it
+ * A CHILD session (`inheritsFromParent`) is exempt from the own-key requirement: it
  * inherits its provider keys server-side from the parent's vaulted bundle, so
  * it need not carry any of its own. The server still verifies, at admission,
  * that the parent actually holds a key for the child's provider.
@@ -773,7 +773,7 @@ export function parseSubmission(input, options = {}) {
         "environment",
         "securityProfile",
         "metadata",
-        "outputs",
+        "fileCapture",
         "includeBuiltinTools",
         "outputMode",
         "responseFormat",
@@ -785,7 +785,7 @@ export function parseSubmission(input, options = {}) {
             throw new Error(`submission.${key} is not an allowed field; permitted: ${[...allowed].join(", ")}`);
         }
     }
-    const model = parseRunModel(value.model, "submission.model");
+    const model = parseModelName(value.model, "submission.model");
     const system = optionalString(value.system, "submission.system");
     const prompt = parsePrompt(value.prompt);
     const { tools, builtinTools } = parseTools(value.tools);
@@ -798,7 +798,7 @@ export function parseSubmission(input, options = {}) {
     const environment = parseEnvironment(value.environment);
     const securityProfile = parseRuntimeSecurityProfile(value.securityProfile);
     const metadata = optionalJsonRecord(value.metadata, "submission.metadata");
-    const outputs = parseOutputs(value.outputs);
+    const fileCapture = parseFileCapture(value.fileCapture);
     const includeBuiltinTools = parseIncludeBuiltinTools(value.includeBuiltinTools);
     const outputMode = parseOutputMode(value.outputMode);
     const responseFormat = parseResponseFormat(value.responseFormat);
@@ -818,7 +818,7 @@ export function parseSubmission(input, options = {}) {
         ...(environment ? { environment } : {}),
         ...(securityProfile ? { securityProfile } : {}),
         ...(metadata ? { metadata } : {}),
-        ...(outputs ? { outputs } : {}),
+        ...(fileCapture ? { fileCapture } : {}),
         ...(includeBuiltinTools !== undefined ? { includeBuiltinTools } : {}),
         ...(builtinTools.length > 0 ? { builtinTools } : {}),
         ...(outputMode !== undefined ? { outputMode } : {}),
@@ -919,7 +919,7 @@ function streamableProviders() {
 /**
  * Fail-closed streaming gate: `outputMode:'stream'` on a NON-streamable provider
  * throws (a HARD reject — no silent downgrade to buffered). Called by
- * {@link parseRunSubmissionRequest} once mode + provider are both known.
+ * {@link parseSessionSubmissionRequest} once mode + provider are both known.
  */
 export function assertStreamableOutputMode(outputMode, provider) {
     if (outputMode === "stream" && !isStreamableProvider(provider)) {
@@ -1084,21 +1084,21 @@ export const DEFAULT_BUILTIN_TOOLS = BUILTIN_TOOL_NAMES;
  * Fixed name of the single skills meta-tool. Deliberately NOT a member of
  * {@link BUILTIN_TOOL_NAMES} (that closed set is the customer-cherry-pickable
  * toggle surface, pinned equal to `HANDS_TOOLS`) — the skills tool is IMPLIED by
- * a run having ≥1 skill, not chosen, and is injected platform-side. Kept in
+ * a session having ≥1 skill, not chosen, and is injected platform-side. Kept in
  * lockstep with {@link SKILL_RESERVED_NAMES} so it can never be shadowed by a
  * custom tool or skill of the same name.
  */
 export const SKILLS_TOOL_NAME = "skills";
 /**
  * The single default `skills` meta-tool (list/load) the platform injects when a
- * run references ≥1 workspace skill. Shared by the platform tool composer and
+ * session references ≥1 workspace skill. Shared by the platform tool composer and
  * kept adjacent to the reserved-name guard so the model-visible contract and the
  * name reservation stay in one place. It replaces the former N per-skill no-arg
  * load-tools with one arg-taking dispatcher.
  */
 export const SKILLS_TOOL_DEFINITION = {
     name: "skills",
-    description: "List and load the workspace SKILLS available to this run. Call with {action:'list'} to see each skill's " +
+    description: "List and load the workspace SKILLS available to this session. Call with {action:'list'} to see each skill's " +
         "name + description (cheap; do this first). Call with {action:'load', name:'<skill>'} to read that skill's " +
         "full SKILL.md instructions into context before doing work the skill governs. A skill's supporting files are " +
         "already on disk under /workspace/skills/<name>/ — load pulls the instructions; read_file/bash read the rest.",
@@ -1144,43 +1144,43 @@ function parseIncludeBuiltinTools(input) {
     return input;
 }
 /**
- * Maximum number of output capture entries accepted per list.
+ * Maximum number of file capture entries accepted per list.
  *
  * 32 is enough room for the typical "one or two capture roots" pattern
  * plus a generous margin for legitimate multi-root use cases (per-tool
- * output directory + scratch state + logs, repeated across a few
+ * file directory + scratch state + logs, repeated across a few
  * subdirectories), without inviting abuse of the synthetic-turn path
  * the platform capture path drives at session terminal.
  */
-const MAX_OUTPUT_DIRS = 32;
+const MAX_FILE_CAPTURE_DIRS = 32;
 /**
- * Maximum byte length of a single output capture entry (after UTF-8
+ * Maximum byte length of a single file capture entry (after UTF-8
  * encoding). 512 bytes comfortably covers `/very/long/nested/path`
  * style entries without letting a misuse smuggle large blobs through
  * the field.
  */
-const MAX_OUTPUT_DIR_BYTES = 512;
-const MAX_OUTPUT_CAPTURE_TIMEOUT_MS = 6 * 60 * 60 * 1000;
-function parseOutputs(input) {
+const MAX_FILE_CAPTURE_DIR_BYTES = 512;
+const MAX_FILE_CAPTURE_TIMEOUT_MS = 6 * 60 * 60 * 1000;
+function parseFileCapture(input) {
     if (input === undefined || input === null) {
         return undefined;
     }
-    const value = requireRecord(input, "submission.outputs");
+    const value = requireRecord(input, "submission.fileCapture");
     const allowed = new Set(["allowedDirs", "deniedDirs", "captureTimeoutMs", "maxFileBytes", "maxTotalBytes", "maxFiles"]);
     for (const key of Object.keys(value)) {
         if (!allowed.has(key)) {
-            throw new Error(`submission.outputs.${key} is not an allowed field; permitted: ${[...allowed].join(", ")}`);
+            throw new Error(`submission.fileCapture.${key} is not an allowed field; permitted: ${[...allowed].join(", ")}`);
         }
     }
-    const allowedDirs = parseOutputAllowedDirs(value.allowedDirs);
-    const deniedDirs = parseOutputDeniedDirs(value.deniedDirs);
-    const captureTimeoutMs = parseOutputPositiveInteger(value.captureTimeoutMs, "submission.outputs.captureTimeoutMs", {
-        max: MAX_OUTPUT_CAPTURE_TIMEOUT_MS,
+    const allowedDirs = parseFileCaptureAllowedDirs(value.allowedDirs);
+    const deniedDirs = parseFileCaptureDeniedDirs(value.deniedDirs);
+    const captureTimeoutMs = parseFileCapturePositiveInteger(value.captureTimeoutMs, "submission.fileCapture.captureTimeoutMs", {
+        max: MAX_FILE_CAPTURE_TIMEOUT_MS,
         clamp: true
     });
-    const maxFileBytes = parseOutputPositiveInteger(value.maxFileBytes, "submission.outputs.maxFileBytes");
-    const maxTotalBytes = parseOutputPositiveInteger(value.maxTotalBytes, "submission.outputs.maxTotalBytes");
-    const maxFiles = parseOutputPositiveInteger(value.maxFiles, "submission.outputs.maxFiles");
+    const maxFileBytes = parseFileCapturePositiveInteger(value.maxFileBytes, "submission.fileCapture.maxFileBytes");
+    const maxTotalBytes = parseFileCapturePositiveInteger(value.maxTotalBytes, "submission.fileCapture.maxTotalBytes");
+    const maxFiles = parseFileCapturePositiveInteger(value.maxFiles, "submission.fileCapture.maxFiles");
     if (!allowedDirs && !deniedDirs && captureTimeoutMs === undefined && maxFileBytes === undefined && maxTotalBytes === undefined && maxFiles === undefined) {
         return undefined;
     }
@@ -1193,7 +1193,7 @@ function parseOutputs(input) {
         ...(maxFiles !== undefined ? { maxFiles } : {})
     };
 }
-function parseOutputPositiveInteger(input, field, options = {}) {
+function parseFileCapturePositiveInteger(input, field, options = {}) {
     if (input === undefined) {
         return undefined;
     }
@@ -1205,47 +1205,47 @@ function parseOutputPositiveInteger(input, field, options = {}) {
     }
     return input;
 }
-function parseOutputAllowedDirs(input) {
+function parseFileCaptureAllowedDirs(input) {
     if (input === undefined) {
         return undefined;
     }
     if (!Array.isArray(input)) {
-        throw new Error("submission.outputs.allowedDirs must be an array of absolute UNIX paths");
+        throw new Error("submission.fileCapture.allowedDirs must be an array of absolute UNIX paths");
     }
     if (input.length === 0) {
         // Treat an empty array as omission so the idempotency hash matches
         // the "no allowedDirs" case.
         return undefined;
     }
-    if (input.length > MAX_OUTPUT_DIRS) {
-        throw new Error(`submission.outputs.allowedDirs has ${input.length} entries; max is ${MAX_OUTPUT_DIRS}`);
+    if (input.length > MAX_FILE_CAPTURE_DIRS) {
+        throw new Error(`submission.fileCapture.allowedDirs has ${input.length} entries; max is ${MAX_FILE_CAPTURE_DIRS}`);
     }
     const seen = new Set();
     const normalised = [];
     for (let i = 0; i < input.length; i++) {
         const item = input[i];
         if (typeof item !== "string") {
-            throw new Error(`submission.outputs.allowedDirs[${i}] must be a string`);
+            throw new Error(`submission.fileCapture.allowedDirs[${i}] must be a string`);
         }
         if (item.length === 0) {
-            throw new Error(`submission.outputs.allowedDirs[${i}] must be a non-empty absolute UNIX path`);
+            throw new Error(`submission.fileCapture.allowedDirs[${i}] must be a non-empty absolute UNIX path`);
         }
         const bytes = new TextEncoder().encode(item).length;
-        if (bytes > MAX_OUTPUT_DIR_BYTES) {
-            throw new Error(`submission.outputs.allowedDirs[${i}] exceeds ${MAX_OUTPUT_DIR_BYTES} bytes (got ${bytes})`);
+        if (bytes > MAX_FILE_CAPTURE_DIR_BYTES) {
+            throw new Error(`submission.fileCapture.allowedDirs[${i}] exceeds ${MAX_FILE_CAPTURE_DIR_BYTES} bytes (got ${bytes})`);
         }
         if (!item.startsWith("/")) {
-            throw new Error(`submission.outputs.allowedDirs[${i}] must be an absolute UNIX path (start with '/')`);
+            throw new Error(`submission.fileCapture.allowedDirs[${i}] must be an absolute UNIX path (start with '/')`);
         }
         if (item.includes("\0")) {
-            throw new Error(`submission.outputs.allowedDirs[${i}] must not contain NUL bytes`);
+            throw new Error(`submission.fileCapture.allowedDirs[${i}] must not contain NUL bytes`);
         }
         if (item.includes("\n") || item.includes("\r")) {
-            throw new Error(`submission.outputs.allowedDirs[${i}] must not contain newline characters`);
+            throw new Error(`submission.fileCapture.allowedDirs[${i}] must not contain newline characters`);
         }
         const segments = item.split("/");
         if (segments.includes("..")) {
-            throw new Error(`submission.outputs.allowedDirs[${i}] must not contain '..' segments`);
+            throw new Error(`submission.fileCapture.allowedDirs[${i}] must not contain '..' segments`);
         }
         const collapsed = segments
             .filter((seg, idx) => seg.length > 0 || idx === 0)
@@ -1262,41 +1262,41 @@ function parseOutputAllowedDirs(input) {
     }
     return normalised;
 }
-function parseOutputDeniedDirs(input) {
+function parseFileCaptureDeniedDirs(input) {
     if (input === undefined) {
         return undefined;
     }
     if (!Array.isArray(input)) {
-        throw new Error("submission.outputs.deniedDirs must be an array of strings");
+        throw new Error("submission.fileCapture.deniedDirs must be an array of strings");
     }
     if (input.length === 0) {
         return undefined;
     }
-    if (input.length > MAX_OUTPUT_DIRS) {
-        throw new Error(`submission.outputs.deniedDirs has ${input.length} entries; max is ${MAX_OUTPUT_DIRS}`);
+    if (input.length > MAX_FILE_CAPTURE_DIRS) {
+        throw new Error(`submission.fileCapture.deniedDirs has ${input.length} entries; max is ${MAX_FILE_CAPTURE_DIRS}`);
     }
     const seen = new Set();
     const normalised = [];
     for (let i = 0; i < input.length; i++) {
         const item = input[i];
         if (typeof item !== "string") {
-            throw new Error(`submission.outputs.deniedDirs[${i}] must be a string`);
+            throw new Error(`submission.fileCapture.deniedDirs[${i}] must be a string`);
         }
         if (item.length === 0) {
-            throw new Error(`submission.outputs.deniedDirs[${i}] must be a non-empty pattern`);
+            throw new Error(`submission.fileCapture.deniedDirs[${i}] must be a non-empty pattern`);
         }
         const bytes = new TextEncoder().encode(item).length;
-        if (bytes > MAX_OUTPUT_DIR_BYTES) {
-            throw new Error(`submission.outputs.deniedDirs[${i}] exceeds ${MAX_OUTPUT_DIR_BYTES} bytes (got ${bytes})`);
+        if (bytes > MAX_FILE_CAPTURE_DIR_BYTES) {
+            throw new Error(`submission.fileCapture.deniedDirs[${i}] exceeds ${MAX_FILE_CAPTURE_DIR_BYTES} bytes (got ${bytes})`);
         }
         if (item.includes("\0")) {
-            throw new Error(`submission.outputs.deniedDirs[${i}] must not contain NUL bytes`);
+            throw new Error(`submission.fileCapture.deniedDirs[${i}] must not contain NUL bytes`);
         }
         if (item.includes("\n") || item.includes("\r")) {
-            throw new Error(`submission.outputs.deniedDirs[${i}] must not contain newline characters`);
+            throw new Error(`submission.fileCapture.deniedDirs[${i}] must not contain newline characters`);
         }
         if (item.split("/").includes("..")) {
-            throw new Error(`submission.outputs.deniedDirs[${i}] must not contain '..' segments`);
+            throw new Error(`submission.fileCapture.deniedDirs[${i}] must not contain '..' segments`);
         }
         let canonical = item;
         if (item.startsWith("/")) {
@@ -1436,9 +1436,9 @@ function parseTools(input) {
     return { tools, builtinTools };
 }
 /**
- * Upper bound on the number of workspace skills a single run may reference.
- * A run's skill list is a discovery surface, not a bulk-mount channel; 64 is
- * generous headroom over any realistic per-run set while capping the meta-tool
+ * Upper bound on the number of workspace skills a single session may reference.
+ * A session's skill list is a discovery surface, not a bulk-mount channel; 64 is
+ * generous headroom over any realistic per-session set while capping the meta-tool
  * `list` payload and the submit-time resolution fan-out.
  */
 export const SKILLS_MAX = 64;

package/dist/_contracts/{run-trace.d.ts → turn-trace.d.ts}

@@ -21,7 +21,7 @@ export interface AssistantTextEntry {
     readonly seq?: number;
     readonly recordedAt?: string;
 }
-export interface RunTrace {
+export interface TurnTrace {
     readonly toolCalls: readonly ToolCallTrace[];
     readonly usage: UsageSummary;
     readonly text: readonly AssistantTextEntry[];

package/dist/_contracts/webhook-verify.d.ts

@@ -1,5 +1,5 @@
 /**
- * Customer-side verification for aex run webhooks (Standard Webhooks scheme).
+ * Customer-side verification for aex start webhooks (Standard Webhooks scheme).
  *
  * aex signs every delivery HMAC-SHA256 over `${webhook-id}.${webhook-timestamp}.${rawBody}`
  * and sends three headers:

package/dist/_contracts/webhook-verify.js

@@ -1,5 +1,5 @@
 /**
- * Customer-side verification for aex run webhooks (Standard Webhooks scheme).
+ * Customer-side verification for aex start webhooks (Standard Webhooks scheme).
  *
  * aex signs every delivery HMAC-SHA256 over `${webhook-id}.${webhook-timestamp}.${rawBody}`
  * and sends three headers:

package/dist/agents-md.d.ts

@@ -5,10 +5,10 @@ import type { AgentsMdRef } from "./_contracts/index.js";
  * behaviour).
  *
  *   const rules = await AgentsMd.fromContent("# Be helpful", { name: "rules" });
- *   await client.run({ agentsMd: [rules], message: "..." });
+ *   await client.start({ agentsMd: [rules], message: "..." });
  *
- * `client.run` / `openSession` materializes the bytes to the hosted asset store
- * before the run lands. Asset deduplication handles repeated uploads automatically.
+ * `client.start` / `openSession` materializes the bytes to the hosted asset store
+ * before the session lands. Asset deduplication handles repeated uploads automatically.
  */
 export declare class AgentsMd {
     #private;
@@ -33,7 +33,7 @@ export declare class AgentsMd {
     }): Promise<AgentsMd>;
     /**
      * Internal: yield the draft's zipped bytes + metadata so
-     * `client.run` / `openSession` can upload it as an asset.
+     * `client.start` / `openSession` can upload it as an asset.
      */
     _takeDraftBundle(): {
         name: string;

package/dist/agents-md.js

@@ -7,10 +7,10 @@ import { strToU8, zipSync } from "fflate";
  * behaviour).
  *
  *   const rules = await AgentsMd.fromContent("# Be helpful", { name: "rules" });
- *   await client.run({ agentsMd: [rules], message: "..." });
+ *   await client.start({ agentsMd: [rules], message: "..." });
  *
- * `client.run` / `openSession` materializes the bytes to the hosted asset store
- * before the run lands. Asset deduplication handles repeated uploads automatically.
+ * `client.start` / `openSession` materializes the bytes to the hosted asset store
+ * before the session lands. Asset deduplication handles repeated uploads automatically.
  */
 export class AgentsMd {
     #ref;
@@ -59,7 +59,7 @@ export class AgentsMd {
     }
     /**
      * Internal: yield the draft's zipped bytes + metadata so
-     * `client.run` / `openSession` can upload it as an asset.
+     * `client.start` / `openSession` can upload it as an asset.
      */
     _takeDraftBundle() {
         if (this.#ref.kind !== "draft" || !this.#zipBytes) {
@@ -74,7 +74,7 @@ export class AgentsMd {
     toJSON() {
         if (this.#ref.kind === "draft") {
             throw new Error("AgentsMd: draft AgentsMd cannot be JSON-serialised — it only becomes a wire " +
-                "ref when aex.run / openSession uploads the bytes as an asset.");
+                "ref when aex.start / openSession uploads the bytes as an asset.");
         }
         return this.#ref;
     }

package/dist/agents-md.js.map

@@ -1 +1 @@
-{"version":3,"file":"agents-md.js","sourceRoot":"","sources":["../src/agents-md.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agents-md.js","sourceRoot":"","sources":["../src/agents-md.ts"],"names":[],"mappings":"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"}

package/dist/bundle.d.ts

@@ -3,7 +3,7 @@ import { type BundleSymlink, type ToolInputSchema } from "./_contracts/index.js"
  * In-memory skill bundle: a flat path -> bytes map and the
  * deterministically-zipped representation.
  *
- * The SDK runs only the cheap, safety-critical checks here
+ * The SDK sessions only the cheap, safety-critical checks here
  * (`validateSkillBundleEntry`: no `..`, no absolute paths, no Windows
  * backslashes, depth/length limits). The BFF re-canonicalises and
  * recomputes the canonical hash on receipt — SDK-side hashing is NOT

package/dist/bundle.js

@@ -65,7 +65,7 @@ export function bundleSkillFiles(files, meta) {
             "use AgentsMd.fromPath / File.fromPath instead.");
     }
     // Sort entries and pin every mtime to the epoch so the byte output is
-    // identical across machines and re-runs (the BFF re-canonicalises and
+    // identical across machines and re-sessions (the BFF re-canonicalises and
     // recomputes the canonical hash, so this is for retry-safety / debug
     // reproducibility rather than a wire-shape contract). The fidelity sidecar,
     // when present, is appended LAST so a metadata-free bundle is byte-identical.