@aexhq/sdk 0.38.1 → 0.40.0

package/dist/_contracts/submission.d.ts

@@ -1,4 +1,4 @@
-import type { AgentsMdRef, FileRef, McpServerRef, SkillToolRef, ToolRef } from "./run-config.js";
+import type { AgentsMdRef, FileRef, McpServerRef, ResolvedSkillRef, SkillRef, ToolRef } from "./run-config.js";
 import { type RuntimeSize } from "./runtime-sizes.js";
 import { type RunModel } from "./models.js";
 import { type RuntimeSecurityProfileName } from "./runtime-security-profile.js";
@@ -207,10 +207,9 @@ export declare function optionalPositiveNumber(input: unknown, field: string): n
  * only the non-secret half; bearer headers travel in
  * `secrets.mcpServers` keyed by `name`.
  *
- * `tools` is the union of builtin tool names, custom `ToolRef` bundles, and
- * skill-tools (`{ kind:"skill", … }`); parsing splits them into `tools`,
- * `builtinTools`, and `skillTools`. Skill bundles are content-addressed asset
- * refs snapshotted into the run-owned prefix before dispatch.
+ * `tools` is the union of builtin tool names and custom `ToolRef` bundles;
+ * parsing splits them into `tools` and `builtinTools`. Skills are a SEPARATE
+ * first-class input on `skills` (by-name refs), NOT part of `tools`.
  */
 export interface PlatformSubmission {
     readonly model: RunModel;
@@ -218,13 +217,21 @@ export interface PlatformSubmission {
     readonly prompt: readonly string[];
     readonly tools?: readonly ToolRef[];
     /**
-     * Skill-tools: skills re-expressed as synthetic no-arg load-tools. Derived
-     * from the `tools` union at parse time (the `{ kind:"skill", … }` members),
-     * like {@link builtinTools}. Each becomes a model-visible tool whose call
-     * returns the skill's `SKILL.md` body; the bundle is eagerly staged to
-     * `/workspace/skills/<name>/`.
+     * Workspace skills referenced BY NAME (`{ kind:"skill", name }`). This is the
+     * public ingress shape the SDK sends and the ONLY skill field the idempotency
+     * hash covers. The platform resolves each name to the workspace skill's
+     * current bytes at submit time; a re-upload under the same name changes what
+     * later runs see (the name-only ref, and therefore the hash, is unchanged).
      */
-    readonly skillTools?: readonly SkillToolRef[];
+    readonly skills?: readonly SkillRef[];
+    /**
+     * BOOT-RECORD-ONLY, trusted resolution of {@link skills}. The BFF resolver
+     * fills this (name → current `assetId` + `description`) before persisting the
+     * boot record; the in-container re-parse and manifest/materialize layers read
+     * it. Rejected on public ingress (only accepted under a trusted re-parse) and
+     * NOT part of the idempotency hash — it is derived, like sealed secrets.
+     */
+    readonly resolvedSkills?: readonly ResolvedSkillRef[];
     readonly agentsMd: readonly AgentsMdRef[];
     readonly files: readonly FileRef[];
     readonly mcpServers: readonly McpServerRef[];
@@ -268,9 +275,26 @@ export interface PlatformSubmission {
     /**
      * Assistant-output granularity. `buffered` (the default) emits one event per
      * assistant message; `stream` emits the agent's per-token text deltas as they
-     * arrive. Buffered is quieter and cheaper; stream suits live typing UIs.
+     * arrive, THEN a final coalesced block. Streaming is CAPABILITY-GATED: it is
+     * only honored for a streamable provider (see {@link STREAMABLE_SHAPES}) and a
+     * `stream` mode on a non-streamable provider is rejected at parse
+     * ({@link assertStreamableOutputMode}) — no silent downgrade.
      */
     readonly outputMode?: OutputMode;
+    /**
+     * Structured-output policy. `{ kind: 'text' }` (default) is free-form; a
+     * `{ kind: 'json_schema', … }` requests provider-native constrained decode.
+     * The run's typed outcome is then `decoded | refused` — no untyped path yields
+     * a hallucinated object. Fail-closed for a provider lacking the capability.
+     */
+    readonly responseFormat?: ResponseFormat;
+    /**
+     * Declarative HITL write-gate: the platform parks the session
+     * `awaiting_approval` BEFORE dispatching any listed tool, holding for an
+     * `approve()`/`deny()`. Structural — independent of model prose. Empty/absent
+     * ⇒ no gate.
+     */
+    readonly approvalGate?: ApprovalGate;
     /**
      * Platform-injection controls. The platform prepends a small system
      * prompt (see `platformSystemPrompt`) ahead of `system` to explain
@@ -384,6 +408,15 @@ export interface RunLimits {
      * single source of truth for that wire→boot name mapping.
      */
     readonly maxSpendUsd?: number;
+    /**
+     * Maximum number of agent ITERATIONS (turns) the run may take before the
+     * platform parks it terminal. A positive integer; omitted ⇒ the platform
+     * default (`RUN_DEFAULT_MAX_TURNS`). Previously a bare server literal absent
+     * from both the public contract and the limits SSoT — now a settable dial.
+     * Only shape/positivity are validated here; clamping to the ceiling is the
+     * resolver's job.
+     */
+    readonly maxTurns?: number;
 }
 /**
  * Per-run machine/capacity intent. v1 exposes only `spot`: opt the run into
@@ -418,6 +451,13 @@ export type PlatformRunSubmissionInput = Omit<PlatformRunSubmissionRequest, "wor
     readonly timeout?: string;
 };
 export interface ParseRunSubmissionOptions {
+    /**
+     * Set by the in-container re-parse of the boot record (`aws-compose.ts`) to
+     * accept trusted-only fields the BFF resolver wrote after ingress — currently
+     * `submission.resolvedSkills`. On the public ingress path this stays `false`
+     * so a caller can never inject a resolved skill (asset + description).
+     */
+    readonly trustedReparse?: boolean;
 }
 export declare function parseRunSubmissionRequest(input: unknown, options?: ParseRunSubmissionOptions): PlatformRunSubmissionRequest;
 /**
@@ -483,11 +523,61 @@ export declare function parseRunProvider(input: unknown): RunProvider;
 export declare function enforceCredentialSecretPolicy(secrets: PlatformInlineSecrets, provider: RunProvider, opts?: {
     readonly inheritsFromParent?: boolean;
 }): void;
-export declare function parseSubmission(input: unknown): PlatformSubmission;
+export declare function parseSubmission(input: unknown, options?: {
+    readonly trustedReparse?: boolean;
+}): PlatformSubmission;
 /** Assistant-output granularity values. Buffered is the platform default. */
 export declare const OUTPUT_MODES: readonly ["buffered", "stream"];
 export type OutputMode = (typeof OUTPUT_MODES)[number];
 export declare const DEFAULT_OUTPUT_MODE: OutputMode;
+/**
+ * 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 declare const STREAMABLE_SHAPES: readonly ["anthropic", "openai_chat"];
+export type StreamableShape = (typeof STREAMABLE_SHAPES)[number];
+/** True when a provider has a streaming producer wired (a {@link STREAMABLE_SHAPES} shape). */
+export declare function isStreamableProvider(provider: RunProvider): boolean;
+/**
+ * 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 declare function assertStreamableOutputMode(outputMode: OutputMode | undefined, provider: RunProvider): void;
+/** Response-format kinds: free-form `text` (default) or provider-native `json_schema`. */
+export declare const RESPONSE_FORMAT_KINDS: readonly ["text", "json_schema"];
+export type ResponseFormatKind = (typeof RESPONSE_FORMAT_KINDS)[number];
+/**
+ * Structured-output policy. `{ kind: 'text' }` is free-form; `{ kind:
+ * 'json_schema', schema, strict?, name? }` requests provider-native constrained
+ * decode against `schema` (a JSON Schema object).
+ */
+export type ResponseFormat = {
+    readonly kind: "text";
+} | {
+    readonly kind: "json_schema";
+    readonly schema: JsonValue;
+    readonly strict?: boolean;
+    readonly name?: string;
+};
+/**
+ * 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 declare function parseResponseFormat(input: unknown): ResponseFormat | undefined;
+/** Declarative HITL write-gate: park `awaiting_approval` before any listed tool. */
+export interface ApprovalGate {
+    readonly tools: readonly string[];
+}
+/**
+ * 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 declare function parseApprovalGate(input: unknown): ApprovalGate | undefined;
 /**
  * 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
@@ -499,7 +589,7 @@ export declare const DEFAULT_OUTPUT_MODE: OutputMode;
  * Order mirrors `HANDS_TOOLS`. A builtin tool reference (a bare string in
  * `submission.tools`) must be a member of this set.
  */
-export declare const BUILTIN_TOOL_NAMES: readonly ["bash", "read_file", "write_file", "edit_file", "grep", "glob", "head", "tail", "todo_write", "subagent", "subagent_result", "web_fetch", "web_search", "bash_output", "bash_kill", "code_execution", "wait", "git"];
+export declare const BUILTIN_TOOL_NAMES: readonly ["bash", "read_file", "write_file", "edit_file", "grep", "glob", "head", "tail", "todo_write", "subagent", "subagent_result", "web_fetch", "web_search", "bash_output", "bash_kill", "code_execution", "wait", "git", "ls", "stat", "wc"];
 export type BuiltinToolName = (typeof BUILTIN_TOOL_NAMES)[number];
 /**
  * Typo-safe accessors for the closed builtin tool set: each key maps to the
@@ -529,12 +619,51 @@ export declare const BuiltinTools: {
     readonly code_execution: "code_execution";
     readonly wait: "wait";
     readonly git: "git";
+    readonly ls: "ls";
+    readonly stat: "stat";
+    readonly wc: "wc";
 };
 /**
  * The default builtin tool set injected when `includeBuiltinTools !== false`.
  * It is the complete closed builtin set.
  */
 export declare const DEFAULT_BUILTIN_TOOLS: readonly BuiltinToolName[];
+/**
+ * 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 declare 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 declare const SKILLS_TOOL_DEFINITION: {
+    readonly name: "skills";
+    readonly description: string;
+    readonly input_schema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly action: {
+                readonly type: "string";
+                readonly enum: readonly ["list", "load"];
+                readonly description: "'list' all skills, or 'load' one by name.";
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly description: "Skill name to load (required when action='load').";
+            };
+        };
+        readonly required: readonly ["action"];
+        readonly additionalProperties: false;
+    };
+};
 /**
  * Resolve the set of builtin tool NAMES a submission injects, deduplicated and
  * in {@link BUILTIN_TOOL_NAMES} order.
@@ -548,3 +677,17 @@ export declare const DEFAULT_BUILTIN_TOOLS: readonly BuiltinToolName[];
  * union is validated ⊆ the closed set so an invalid name can never leak through.
  */
 export declare function resolveBuiltinToolNames(includeBuiltinTools: boolean | undefined, toolRefs?: readonly string[]): readonly BuiltinToolName[];
+/**
+ * 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 declare 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 declare function parseSkills(input: unknown): readonly SkillRef[];