@aexhq/sdk 0.38.1 → 0.40.0

package/dist/_contracts/submission.js

@@ -1,4 +1,4 @@
-import { TOOL_NAME_PATTERN, normaliseSkillBundlePath, parseAssetRefFields, parseMcpServerRef } from "./run-config.js";
+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 { parseRuntimeSecurityProfile } from "./runtime-security-profile.js";
@@ -554,7 +554,6 @@ export function parseRunSubmissionRequest(input, options = {}) {
         assertNoSecretBearingFields(fieldValue, [key]);
     }
     const provider = parseRunProvider(value.provider);
-    void options;
     const runtimeSize = parseRuntimeSize(value.runtimeSize);
     const timeoutMs = parseRunTimeout(value.timeout);
     const webhook = parseRunWebhook(value.webhook);
@@ -562,8 +561,13 @@ export function parseRunSubmissionRequest(input, options = {}) {
     const machine = parseRunMachine(value.machine);
     const secrets = parseInlineSecrets(value.secrets);
     enforceCredentialSecretPolicy(secrets, provider);
-    const submission = parseSubmission(value.submission);
+    const submission = parseSubmission(value.submission, {
+        trustedReparse: options.trustedReparse === true
+    });
     assertRunModelMatchesProvider(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);
     crossValidateSecretEnvAndValues(submission.secretEnv, secrets.envSecrets);
     // mcpServers names must agree across the submission half and the
     // secrets half — every secrets.mcpServers[i].name MUST resolve to a
@@ -647,7 +651,7 @@ export function parseRunLimits(input) {
         return undefined;
     }
     const value = requireRecord(input, "limits");
-    const allowed = new Set(["maxConcurrentChildRuns", "maxSubagentDepth", "maxSpendUsd"]);
+    const allowed = new Set(["maxConcurrentChildRuns", "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(", ")}`);
@@ -659,16 +663,23 @@ export function parseRunLimits(input) {
     // NUMBER, not a positive int. Clamping to the workspace/platform ceiling is the
     // resolver's job; here we only enforce shape + positivity.
     const maxSpendUsd = optionalPositiveNumber(value.maxSpendUsd, "limits.maxSpendUsd");
+    // maxTurns is an ITERATION count — a positive safe integer. Clamp to the ceiling
+    // 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,
     // parseEnvironment). The resolver supplies platform defaults for absent fields.
-    if (maxConcurrentChildRuns === undefined && maxSubagentDepth === undefined && maxSpendUsd === undefined) {
+    if (maxConcurrentChildRuns === undefined &&
+        maxSubagentDepth === undefined &&
+        maxSpendUsd === undefined &&
+        maxTurns === undefined) {
         return undefined;
     }
     return {
         ...(maxConcurrentChildRuns !== undefined ? { maxConcurrentChildRuns } : {}),
         ...(maxSubagentDepth !== undefined ? { maxSubagentDepth } : {}),
-        ...(maxSpendUsd !== undefined ? { maxSpendUsd } : {})
+        ...(maxSpendUsd !== undefined ? { maxSpendUsd } : {}),
+        ...(maxTurns !== undefined ? { maxTurns } : {})
     };
 }
 /**
@@ -746,13 +757,15 @@ export function enforceCredentialSecretPolicy(secrets, provider, opts) {
         throw new Error(`secrets.apiKeys["${provider}"] is required`);
     }
 }
-export function parseSubmission(input) {
+export function parseSubmission(input, options = {}) {
     const value = requireRecord(input, "submission.submission");
     const allowed = new Set([
         "model",
         "system",
         "prompt",
         "tools",
+        "skills",
+        "resolvedSkills",
         "agentsMd",
         "files",
         "mcpServers",
@@ -763,6 +776,8 @@ export function parseSubmission(input) {
         "outputs",
         "includeBuiltinTools",
         "outputMode",
+        "responseFormat",
+        "approvalGate",
         "platform"
     ]);
     for (const key of Object.keys(value)) {
@@ -773,7 +788,9 @@ export function parseSubmission(input) {
     const model = parseRunModel(value.model, "submission.model");
     const system = optionalString(value.system, "submission.system");
     const prompt = parsePrompt(value.prompt);
-    const { tools, skillTools, builtinTools } = parseTools(value.tools);
+    const { tools, builtinTools } = parseTools(value.tools);
+    const skills = parseSkills(value.skills);
+    const resolvedSkills = parseResolvedSkills(value.resolvedSkills, options.trustedReparse === true);
     const agentsMd = parseAgentsMd(value.agentsMd);
     const files = parseFiles(value.files);
     const mcpServers = parseMcpServers(value.mcpServers);
@@ -784,13 +801,16 @@ export function parseSubmission(input) {
     const outputs = parseOutputs(value.outputs);
     const includeBuiltinTools = parseIncludeBuiltinTools(value.includeBuiltinTools);
     const outputMode = parseOutputMode(value.outputMode);
+    const responseFormat = parseResponseFormat(value.responseFormat);
+    const approvalGate = parseApprovalGate(value.approvalGate);
     const platform = parsePlatformConfig(value.platform);
     return {
         model,
         ...(system ? { system } : {}),
         prompt,
         tools,
-        ...(skillTools.length > 0 ? { skillTools } : {}),
+        ...(skills.length > 0 ? { skills } : {}),
+        ...(resolvedSkills.length > 0 ? { resolvedSkills } : {}),
         agentsMd,
         files,
         mcpServers,
@@ -802,6 +822,8 @@ export function parseSubmission(input) {
         ...(includeBuiltinTools !== undefined ? { includeBuiltinTools } : {}),
         ...(builtinTools.length > 0 ? { builtinTools } : {}),
         ...(outputMode !== undefined ? { outputMode } : {}),
+        ...(responseFormat !== undefined ? { responseFormat } : {}),
+        ...(approvalGate !== undefined ? { approvalGate } : {}),
         ...(platform ? { platform } : {})
     };
 }
@@ -863,6 +885,127 @@ function parseOutputMode(input) {
     }
     return input;
 }
+// ---------------------------------------------------------------------------
+// Streaming capability model — WS9. `outputMode:'stream'` is capability-gated.
+// ---------------------------------------------------------------------------
+/**
+ * The provider wire-SHAPES that have a real per-token streaming producer. This
+ * const is the contracts-side SSoT, pinned EQUAL to the platform's shape SSoT by
+ * a cross-repo parity test so streaming can never be promised for a shape
+ * nothing feeds.
+ */
+export const STREAMABLE_SHAPES = ["anthropic", "openai_chat"];
+/**
+ * Each provider's wire shape, or `null` when it has no streaming producer wired
+ * yet. `stream` output is only honored for a provider whose shape is streamable.
+ */
+const PROVIDER_STREAM_SHAPE = {
+    anthropic: "anthropic",
+    deepseek: "openai_chat",
+    openai: "openai_chat",
+    gemini: null,
+    mistral: "openai_chat",
+    openrouter: "openai_chat",
+    doubao: "openai_chat",
+    "doubao-cn": "openai_chat"
+};
+/** True when a provider has a streaming producer wired (a {@link STREAMABLE_SHAPES} shape). */
+export function isStreamableProvider(provider) {
+    return PROVIDER_STREAM_SHAPE[provider] !== null;
+}
+function streamableProviders() {
+    return Object.keys(PROVIDER_STREAM_SHAPE).filter(isStreamableProvider);
+}
+/**
+ * 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.
+ */
+export function assertStreamableOutputMode(outputMode, provider) {
+    if (outputMode === "stream" && !isStreamableProvider(provider)) {
+        throw new Error(`submission.outputMode 'stream' is not supported for provider ${provider}; ` +
+            `streaming is available for: ${streamableProviders().join(", ")}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Structured-output (schema-decode) policy — WS10.
+// ---------------------------------------------------------------------------
+/** Response-format kinds: free-form `text` (default) or provider-native `json_schema`. */
+export const RESPONSE_FORMAT_KINDS = ["text", "json_schema"];
+/**
+ * Parse the optional `submission.responseFormat`. Mirrors {@link parseOutputMode}
+ * / {@link OUTPUT_MODES}: absent ⇒ undefined; a bad `kind` or unknown subfield is
+ * rejected (fail-fast). `json_schema` requires a JSON-object `schema`.
+ */
+export function parseResponseFormat(input) {
+    if (input === undefined || input === null)
+        return undefined;
+    const value = requireRecord(input, "submission.responseFormat");
+    const kind = value.kind;
+    if (typeof kind !== "string" || !RESPONSE_FORMAT_KINDS.includes(kind)) {
+        throw new Error(`submission.responseFormat.kind must be one of ${RESPONSE_FORMAT_KINDS.join(", ")}`);
+    }
+    if (kind === "text") {
+        for (const key of Object.keys(value)) {
+            if (key !== "kind") {
+                throw new Error(`submission.responseFormat.${key} is not allowed when kind is 'text'`);
+            }
+        }
+        return { kind: "text" };
+    }
+    const allowed = new Set(["kind", "schema", "strict", "name"]);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            throw new Error(`submission.responseFormat.${key} is not an allowed field; permitted: ${[...allowed].join(", ")}`);
+        }
+    }
+    if (!isRecord(value.schema) || !isJsonValue(value.schema)) {
+        throw new Error("submission.responseFormat.schema must be a JSON-serializable object");
+    }
+    const schema = value.schema;
+    if (value.strict !== undefined && typeof value.strict !== "boolean") {
+        throw new Error("submission.responseFormat.strict must be a boolean");
+    }
+    const name = optionalString(value.name, "submission.responseFormat.name");
+    return {
+        kind: "json_schema",
+        schema,
+        ...(value.strict !== undefined ? { strict: value.strict } : {}),
+        ...(name !== undefined ? { name } : {})
+    };
+}
+/**
+ * Parse the optional `submission.approvalGate`. Absent / empty tool list ⇒
+ * undefined (no gate). Tool names are deduped; the strict allow-list mirrors the
+ * sibling parsers.
+ */
+export function parseApprovalGate(input) {
+    if (input === undefined || input === null)
+        return undefined;
+    const value = requireRecord(input, "submission.approvalGate");
+    for (const key of Object.keys(value)) {
+        if (key !== "tools") {
+            throw new Error(`submission.approvalGate.${key} is not an allowed field; permitted: tools`);
+        }
+    }
+    if (!Array.isArray(value.tools)) {
+        throw new Error("submission.approvalGate.tools must be an array of tool names");
+    }
+    const seen = new Set();
+    const tools = [];
+    value.tools.forEach((entry, index) => {
+        if (typeof entry !== "string" || entry.length === 0) {
+            throw new Error(`submission.approvalGate.tools[${index}] must be a non-empty string`);
+        }
+        if (!seen.has(entry)) {
+            seen.add(entry);
+            tools.push(entry);
+        }
+    });
+    if (tools.length === 0)
+        return undefined;
+    return { tools };
+}
 /**
  * The CLOSED set of builtin tool NAMES the managed runtime can inject — one per
  * machine tool the hands implement. This list is the single source of truth for
@@ -892,7 +1035,10 @@ export const BUILTIN_TOOL_NAMES = [
     "bash_kill",
     "code_execution",
     "wait",
-    "git"
+    "git",
+    "ls",
+    "stat",
+    "wc"
 ];
 /**
  * Typo-safe accessors for the closed builtin tool set: each key maps to the
@@ -921,13 +1067,51 @@ export const BuiltinTools = {
     bash_kill: "bash_kill",
     code_execution: "code_execution",
     wait: "wait",
-    git: "git"
+    git: "git",
+    ls: "ls",
+    stat: "stat",
+    wc: "wc"
 };
 /**
  * The default builtin tool set injected when `includeBuiltinTools !== false`.
  * It is the complete closed builtin set.
  */
 export const DEFAULT_BUILTIN_TOOLS = BUILTIN_TOOL_NAMES;
+// ---------------------------------------------------------------------------
+// The default `skills` meta-tool
+// ---------------------------------------------------------------------------
+/**
+ * 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
+ * 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
+ * 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 " +
+        "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.",
+    input_schema: {
+        type: "object",
+        properties: {
+            action: { type: "string", enum: ["list", "load"], description: "'list' all skills, or 'load' one by name." },
+            name: { type: "string", description: "Skill name to load (required when action='load')." }
+        },
+        required: ["action"],
+        additionalProperties: false
+    }
+};
 /**
  * Resolve the set of builtin tool NAMES a submission injects, deduplicated and
  * in {@link BUILTIN_TOOL_NAMES} order.
@@ -1159,20 +1343,20 @@ function parsePrompt(input) {
     return parts;
 }
 /**
- * Parse the `submission.tools` union: each entry is one of THREE shapes —
+ * Parse the `submission.tools` union: each entry is one of TWO shapes —
  *   (a) a BARE STRING: a builtin tool reference (validated against
  *       {@link BUILTIN_TOOL_NAMES}).
  *   (b) `{ kind:"asset", … }`: a custom tool bundle ({@link ToolRef}).
- *   (c) `{ kind:"skill", assetId, name, description }`: a skill re-expressed as
- *       a synthetic no-arg load-tool ({@link SkillToolRef}).
- * Returns the three groups split: `tools` (custom bundles), `skillTools`
- * (skill-tools), and `builtinTools` (the deduped builtin-name references, in
- * {@link BUILTIN_TOOL_NAMES} order). Tool `name`s and `assetId`s are deduped
- * across ALL object kinds so a name/asset names at most one tool.
+ * Returns the two groups split: `tools` (custom bundles) and `builtinTools`
+ * (the deduped builtin-name references, in {@link BUILTIN_TOOL_NAMES} order).
+ * Tool `name`s and `assetId`s are deduped so a name/asset names at most one tool.
+ *
+ * Skills are NO LONGER a tool kind: a `{ kind:"skill" }` entry here is rejected
+ * with a redirect to `submission.skills` (see {@link parseSkills}).
  */
 function parseTools(input) {
     if (input === undefined) {
-        return { tools: [], skillTools: [], builtinTools: [] };
+        return { tools: [], builtinTools: [] };
     }
     if (!Array.isArray(input)) {
         throw new Error("submission.tools must be an array of builtin tool names or ToolRef objects");
@@ -1181,7 +1365,6 @@ function parseTools(input) {
     const seenAssetIds = new Set();
     const seenBuiltins = new Set();
     const tools = [];
-    const skillTools = [];
     input.forEach((item, index) => {
         const path = `submission.tools[${index}]`;
         // A bare string is a builtin tool reference (e.g. BuiltinTools.web_search).
@@ -1194,41 +1377,11 @@ function parseTools(input) {
             return;
         }
         const raw = requireRecord(item, path);
-        // A skill-tool is a synthetic no-arg load-tool: { kind:"skill", assetId,
-        // name, description }. Its call returns the skill's SKILL.md body; it carries
-        // no input_schema / entry (unlike a custom ToolRef).
+        // Skills are a separate first-class input now. A skill ref must not ride the
+        // tools union — point the caller at submission.skills instead of silently
+        // dropping or mis-binding it.
         if (raw.kind === "skill") {
-            for (const key of Object.keys(raw)) {
-                if (key !== "kind" && key !== "assetId" && key !== "name" && key !== "description") {
-                    throw new Error(`${path}.${key} is not an allowed field for a skill tool; permitted: kind, assetId, name, description`);
-                }
-            }
-            const skillFields = parseAssetRefFields({ kind: "asset", assetId: raw.assetId, name: raw.name }, path);
-            if (!TOOL_NAME_PATTERN.test(skillFields.name)) {
-                throw new Error(`${path}.name must match ${TOOL_NAME_PATTERN.source}`);
-            }
-            if (skillFields.name.includes("__")) {
-                throw new Error(`${path}.name must not contain "__"; that separator is reserved for MCP tools`);
-            }
-            if (seenNames.has(skillFields.name)) {
-                throw new Error(`submission.tools duplicate name: ${skillFields.name}`);
-            }
-            seenNames.add(skillFields.name);
-            if (seenAssetIds.has(skillFields.assetId)) {
-                throw new Error(`submission.tools duplicate assetId: ${skillFields.assetId}`);
-            }
-            seenAssetIds.add(skillFields.assetId);
-            const skillDescription = requireString(raw.description, `${path}.description`);
-            if (skillDescription.trim().length === 0 || skillDescription.length > 2048) {
-                throw new Error(`${path}.description must be non-empty and <= 2048 chars`);
-            }
-            skillTools.push({
-                kind: "skill",
-                assetId: skillFields.assetId,
-                name: skillFields.name,
-                description: skillDescription
-            });
-            return;
+            throw new Error(`${path} is a skill ref; skills go in submission.skills (by name), not submission.tools`);
         }
         for (const key of Object.keys(raw)) {
             if (key !== "kind" &&
@@ -1280,7 +1433,118 @@ function parseTools(input) {
         });
     });
     const builtinTools = BUILTIN_TOOL_NAMES.filter((name) => seenBuiltins.has(name));
-    return { tools, skillTools, builtinTools };
+    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
+ * `list` payload and the submit-time resolution fan-out.
+ */
+export const SKILLS_MAX = 64;
+/**
+ * Parse `submission.skills`: an array of PUBLIC by-name skill refs
+ * (`{ kind:"skill", name }`). Validates each `name` against
+ * {@link SKILL_NAME_PATTERN}, rejects the `__` MCP separator and the reserved
+ * skills names, dedups by name, and bounds the list at {@link SKILLS_MAX}.
+ */
+export function parseSkills(input) {
+    if (input === undefined || input === null) {
+        return [];
+    }
+    if (!Array.isArray(input)) {
+        throw new Error("submission.skills must be an array of { kind:'skill', name } refs");
+    }
+    if (input.length > SKILLS_MAX) {
+        throw new Error(`submission.skills exceeds the ${SKILLS_MAX}-skill limit (got ${input.length})`);
+    }
+    const seen = new Set();
+    return input.map((item, index) => {
+        const path = `submission.skills[${index}]`;
+        const raw = requireRecord(item, path);
+        for (const key of Object.keys(raw)) {
+            if (key !== "kind" && key !== "name") {
+                throw new Error(`${path}.${key} is not an allowed field for a skill ref; permitted: kind, name`);
+            }
+        }
+        if (raw.kind !== "skill") {
+            throw new Error(`${path}.kind must be 'skill' (got ${JSON.stringify(raw.kind)})`);
+        }
+        const name = requireString(raw.name, `${path}.name`);
+        assertValidSkillName(name, `${path}.name`);
+        if (seen.has(name)) {
+            throw new Error(`submission.skills duplicate name: ${name}`);
+        }
+        seen.add(name);
+        return { kind: "skill", name };
+    });
+}
+/**
+ * Parse `submission.resolvedSkills`: the BOOT-RECORD-ONLY resolved refs
+ * (`{ kind:"skill", assetId, name, description }`) the BFF resolver writes.
+ * REJECTED on the public ingress path (`trusted === false`) so a caller can
+ * never inject an asset + description; only the in-container trusted re-parse
+ * (`trustedReparse: true`) accepts them.
+ */
+function parseResolvedSkills(input, trusted) {
+    if (input === undefined || input === null) {
+        return [];
+    }
+    if (!trusted) {
+        throw new Error("submission.resolvedSkills is a platform-internal (boot-record) field and may not be set by callers; " +
+            "reference workspace skills by name via submission.skills");
+    }
+    if (!Array.isArray(input)) {
+        throw new Error("submission.resolvedSkills must be an array of resolved skill refs");
+    }
+    if (input.length > SKILLS_MAX) {
+        throw new Error(`submission.resolvedSkills exceeds the ${SKILLS_MAX}-skill limit (got ${input.length})`);
+    }
+    const seenNames = new Set();
+    const seenAssetIds = new Set();
+    return input.map((item, index) => {
+        const path = `submission.resolvedSkills[${index}]`;
+        const raw = requireRecord(item, path);
+        for (const key of Object.keys(raw)) {
+            if (key !== "kind" && key !== "assetId" && key !== "name" && key !== "description") {
+                throw new Error(`${path}.${key} is not an allowed field for a resolved skill ref; permitted: kind, assetId, name, description`);
+            }
+        }
+        if (raw.kind !== "skill") {
+            throw new Error(`${path}.kind must be 'skill' (got ${JSON.stringify(raw.kind)})`);
+        }
+        const fields = parseAssetRefFields({ kind: "asset", assetId: raw.assetId, name: raw.name }, path);
+        assertValidSkillName(fields.name, `${path}.name`);
+        if (seenNames.has(fields.name)) {
+            throw new Error(`submission.resolvedSkills duplicate name: ${fields.name}`);
+        }
+        seenNames.add(fields.name);
+        if (seenAssetIds.has(fields.assetId)) {
+            throw new Error(`submission.resolvedSkills duplicate assetId: ${fields.assetId}`);
+        }
+        seenAssetIds.add(fields.assetId);
+        const description = requireString(raw.description, `${path}.description`);
+        if (description.trim().length === 0 || description.length > 2048) {
+            throw new Error(`${path}.description must be non-empty and <= 2048 chars`);
+        }
+        return { kind: "skill", assetId: fields.assetId, name: fields.name, description };
+    });
+}
+/**
+ * Shared skill-name gate for {@link parseSkills} / {@link parseResolvedSkills}
+ * (and mirrored SDK-side in `Skill`): pattern + `__` MCP separator + reserved
+ * names (`skills`, `skill`).
+ */
+function assertValidSkillName(name, field) {
+    if (!SKILL_NAME_PATTERN.test(name)) {
+        throw new Error(`${field} must match ${SKILL_NAME_PATTERN.source}`);
+    }
+    if (name.includes("__")) {
+        throw new Error(`${field} must not contain "__"; that separator is reserved for MCP tools`);
+    }
+    if (SKILL_RESERVED_NAMES.has(name)) {
+        throw new Error(`${field} must not be a reserved skills name (${[...SKILL_RESERVED_NAMES].join(", ")})`);
+    }
 }
 function parseAgentsMd(input) {
     if (input === undefined)

package/dist/_contracts/suggest.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared "did you mean?" suggester — the SSoT for near-miss enum hints across
+ * the SDK and the CLI. Previously this lived only in the CLI, so the SDK could
+ * not emit a fuzzy model/provider hint even though the docs promised one.
+ */
+/**
+ * The closest candidate to `input` by a unique case-insensitive prefix match,
+ * else by Levenshtein distance (≤ 2), else `undefined`. Ties break by
+ * declaration order. Used on an invalid `--model` / `--provider` /
+ * `--runtime-size` (and the SDK's unknown-model throw) to turn a flat rejection
+ * into a fix hint.
+ */
+export declare function suggest(input: string, candidates: readonly string[]): string | undefined;
+/** Levenshtein edit distance between two strings (rolling two-row DP). */
+export declare function levenshtein(a: string, b: string): number;

package/dist/_contracts/suggest.js

@@ -0,0 +1,54 @@
+/**
+ * Shared "did you mean?" suggester — the SSoT for near-miss enum hints across
+ * the SDK and the CLI. Previously this lived only in the CLI, so the SDK could
+ * not emit a fuzzy model/provider hint even though the docs promised one.
+ */
+/**
+ * The closest candidate to `input` by a unique case-insensitive prefix match,
+ * else by Levenshtein distance (≤ 2), else `undefined`. Ties break by
+ * declaration order. Used on an invalid `--model` / `--provider` /
+ * `--runtime-size` (and the SDK's unknown-model throw) to turn a flat rejection
+ * into a fix hint.
+ */
+export function suggest(input, candidates) {
+    const needle = input.trim();
+    if (!needle)
+        return undefined;
+    // Unique case-insensitive prefix match first (cheap + intuitive).
+    const lower = needle.toLowerCase();
+    const prefixHits = candidates.filter((c) => c.toLowerCase().startsWith(lower));
+    if (prefixHits.length === 1)
+        return prefixHits[0];
+    // Else nearest by edit distance, ties broken by declaration order.
+    let best;
+    let bestDist = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const dist = levenshtein(needle, candidate);
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = candidate;
+        }
+    }
+    return bestDist <= 2 ? best : undefined;
+}
+/** Levenshtein edit distance between two strings (rolling two-row DP). */
+export function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    let prev = Array.from({ length: n + 1 }, (_, j) => j);
+    let curr = new Array(n + 1);
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n];
+}
+//# sourceMappingURL=suggest.js.map

package/dist/asset-upload.d.ts

@@ -1,7 +1,7 @@
 /**
  * Asset materialization for the SDK run / session path.
  *
- * Every inline skill-tool / `Tool` / `AgentsMd` / `File` draft is materialized
+ * Every inline `Skill` / `Tool` / `AgentsMd` / `File` draft is materialized
  * to the hosted API's content-addressable asset store before the session
  * starts, so the wire submission carries only storage-neutral refs.
  *
@@ -19,6 +19,7 @@
  *   3. POST /assets/finalize → confirms the object exists (HEAD only).
  *
  */
+import type { ByteSink } from "./canonical-zip.js";
 /**
  * Subset of `HttpClient` needed by the asset uploader. Defined as a
  * structural type so tests can supply a thin stub without dragging in
@@ -32,6 +33,10 @@ export type AssetFetch = (input: string, init?: RequestInit) => Promise<{
     readonly ok: boolean;
     readonly status: number;
     text(): Promise<string>;
+    /** Present on real `fetch` Responses; used to read a multipart part's ETag. */
+    readonly headers?: {
+        get(name: string): string | null;
+    };
 }>;
 export interface UploadAssetArgs {
     readonly http: AssetsHttpClient;
@@ -58,3 +63,24 @@ export interface UploadedAsset {
  * and the runner re-checks on download.
  */
 export declare function uploadAsset(args: UploadAssetArgs): Promise<UploadedAsset>;
+/** Default multipart part size — 16 MiB covers the 100 GiB cap within S3's 10 000-part limit. */
+export declare const DEFAULT_MULTIPART_PART_SIZE: number;
+/** Default in-flight part concurrency. */
+export declare const DEFAULT_MULTIPART_CONCURRENCY = 4;
+/**
+ * Drives the canonical-zip framer, pushing every zip byte into `sink` in order.
+ * Called TWICE (pass 1 hash, pass 2 upload); the framer is deterministic so both
+ * passes emit byte-identical streams.
+ */
+export type ZipStreamDriver = (sink: ByteSink) => Promise<void>;
+export interface UploadAssetStreamArgs {
+    readonly http: AssetsHttpClient;
+    /** Re-openable, deterministic canonical-zip stream driver (pass-1 hash == pass-2 bytes). */
+    readonly drive: ZipStreamDriver;
+    readonly contentType?: string;
+    readonly fetch?: AssetFetch;
+    readonly partSize?: number;
+    readonly partConcurrency?: number;
+}
+/** Stream a large asset to the content store via the two-pass multipart flow. */
+export declare function uploadAssetMultipart(args: UploadAssetStreamArgs): Promise<UploadedAsset>;