@aexhq/sdk 0.38.1 → 0.39.0

package/README.md

@@ -10,7 +10,7 @@ The package ships:
 
 - `Aex` for sessions, one-shot runs, inspect, download, cancel, and delete.
 - `sessions` / `openSession()` for durable, resumable agent sessions.
-- Typed run primitives: `Models`, `Providers`, `Sizes`, `Tool` / `Tools` (skill-tools), `AgentsMd`, `File`, `McpServer`, and `Secret`.
+- Typed run primitives: `Models`, `Providers`, `Sizes`, `Skill`, `Tool` / `Tools`, `AgentsMd`, `File`, `McpServer`, and `Secret`.
 - A bundled `aex` CLI with the same run, status, events, outputs, download, cancel, delete, and whoami operations.
 
 ## Install

package/dist/_contracts/index.d.ts

@@ -1,7 +1,7 @@
 export * from "./provider-support.js";
 export * from "./models.js";
 export * from "./status.js";
-export { AEX_RESERVED_ENV_PREFIX, BUILTIN_TOOL_NAMES, BuiltinTools, DEFAULT_BUILTIN_TOOLS, DEFAULT_OUTPUT_MODE, DEFAULT_RUN_PROVIDER, ENV_VARS_MAX_ENTRIES, ENV_VARS_MAX_TOTAL_BYTES, ENV_VARS_MAX_VALUE_BYTES, OUTPUT_MODES, PLATFORM_PACKAGE_ECOSYSTEMS, Providers, RUN_PROVIDERS, SECRETS_KEY, SECRET_ENV_NAME_PATTERN, SECRET_HANDLE_PATTERN, crossValidateSecretEnvAndValues, packageInstallString, parseInlineSecrets, parseRunLimits, parseRunProvider, parseRunSubmissionRequest, parseRunWebhook, parseSubmission, resolveBuiltinToolNames } from "./submission.js";
+export { AEX_RESERVED_ENV_PREFIX, BUILTIN_TOOL_NAMES, BuiltinTools, DEFAULT_BUILTIN_TOOLS, DEFAULT_OUTPUT_MODE, DEFAULT_RUN_PROVIDER, ENV_VARS_MAX_ENTRIES, ENV_VARS_MAX_TOTAL_BYTES, ENV_VARS_MAX_VALUE_BYTES, OUTPUT_MODES, PLATFORM_PACKAGE_ECOSYSTEMS, Providers, RUN_PROVIDERS, SECRETS_KEY, SECRET_ENV_NAME_PATTERN, SECRET_HANDLE_PATTERN, SKILLS_MAX, SKILLS_TOOL_DEFINITION, SKILLS_TOOL_NAME, crossValidateSecretEnvAndValues, packageInstallString, parseInlineSecrets, parseRunLimits, parseRunProvider, parseRunSubmissionRequest, parseRunWebhook, parseSkills, parseSubmission, resolveBuiltinToolNames } from "./submission.js";
 export type { BuiltinToolName, JsonPrimitive, JsonValue, OutputMode, ParseRunSubmissionOptions, PlatformEnvironment, PlatformEnvironmentInput, PlatformInlineSecrets, PlatformInjectionConfig, PlatformMcpServerSecret, PlatformNetworking, PlatformOutputCaptureConfig, PlatformPackage, PlatformPackageEcosystem, PlatformPackageInput, PlatformRunSubmissionInput, PlatformRunSubmissionRequest, PlatformSecretEnvEntry, PlatformSubmission, RunLimits, RunMachine, RunProvider, RunWebhookSpec } from "./submission.js";
 export * from "./runtime-sizes.js";
 export * from "./runner-event.js";

package/dist/_contracts/index.js

@@ -1,7 +1,7 @@
 export * from "./provider-support.js";
 export * from "./models.js";
 export * from "./status.js";
-export { AEX_RESERVED_ENV_PREFIX, BUILTIN_TOOL_NAMES, BuiltinTools, DEFAULT_BUILTIN_TOOLS, DEFAULT_OUTPUT_MODE, DEFAULT_RUN_PROVIDER, ENV_VARS_MAX_ENTRIES, ENV_VARS_MAX_TOTAL_BYTES, ENV_VARS_MAX_VALUE_BYTES, OUTPUT_MODES, PLATFORM_PACKAGE_ECOSYSTEMS, Providers, RUN_PROVIDERS, SECRETS_KEY, SECRET_ENV_NAME_PATTERN, SECRET_HANDLE_PATTERN, crossValidateSecretEnvAndValues, packageInstallString, parseInlineSecrets, parseRunLimits, parseRunProvider, parseRunSubmissionRequest, parseRunWebhook, parseSubmission, resolveBuiltinToolNames } from "./submission.js";
+export { AEX_RESERVED_ENV_PREFIX, BUILTIN_TOOL_NAMES, BuiltinTools, DEFAULT_BUILTIN_TOOLS, DEFAULT_OUTPUT_MODE, DEFAULT_RUN_PROVIDER, ENV_VARS_MAX_ENTRIES, ENV_VARS_MAX_TOTAL_BYTES, ENV_VARS_MAX_VALUE_BYTES, OUTPUT_MODES, PLATFORM_PACKAGE_ECOSYSTEMS, Providers, RUN_PROVIDERS, SECRETS_KEY, SECRET_ENV_NAME_PATTERN, SECRET_HANDLE_PATTERN, SKILLS_MAX, SKILLS_TOOL_DEFINITION, SKILLS_TOOL_NAME, crossValidateSecretEnvAndValues, packageInstallString, parseInlineSecrets, parseRunLimits, parseRunProvider, parseRunSubmissionRequest, parseRunWebhook, parseSkills, parseSubmission, resolveBuiltinToolNames } from "./submission.js";
 export * from "./runtime-sizes.js";
 export * from "./runner-event.js";
 export * from "./event-envelope.js";

package/dist/_contracts/operations.d.ts

@@ -1,6 +1,6 @@
 import type { HttpClient } from "./http.js";
 import type { RunUnit } from "./run-unit.js";
-import type { AgentsMdRecord, BillingCheckoutRequest, BillingHostedSession, BillingLedgerPage, BillingLedgerQuery, BillingPortalRequest, BillingSummary, FileRecord, Output, OutputLink, OutputLinkOptions, OutputFileDownload, OutputFileSelector, OutputFileType, OutputQuery, OutputText, ReadOutputTextOptions, Run, RunEvent, RunListPage, RunListQuery, Session, SessionCreateRequest, SessionEvent, SessionListPage, SessionListQuery, SessionMessageAccepted, SessionMessageRequest, SessionMessagesPage, SessionMessagesQuery, SessionStateChangeAccepted, RunWebhookDelivery, SecretRecord, SecretReveal, WebhookSigningSecret, WhoAmI } from "./runtime-types.js";
+import type { AgentsMdRecord, BillingCheckoutRequest, BillingHostedSession, BillingLedgerPage, BillingLedgerQuery, BillingPortalRequest, BillingSummary, FileRecord, Output, OutputLink, OutputLinkOptions, OutputFileDownload, OutputFileSelector, OutputFileType, OutputQuery, OutputText, ReadOutputTextOptions, Run, RunEvent, RunListPage, RunListQuery, Session, SessionCreateRequest, SessionEvent, SessionListPage, SessionListQuery, SessionMessageAccepted, SessionMessageRequest, SessionMessagesPage, SessionMessagesQuery, SessionStateChangeAccepted, RunWebhookDelivery, SecretRecord, SecretReveal, SkillRecord, WebhookSigningSecret, WhoAmI } from "./runtime-types.js";
 import type { PlatformRunSubmissionInput } from "./submission.js";
 /**
  * The single source of truth for SDK<->BFF transport. The SDK class
@@ -197,6 +197,26 @@ export declare function rotateSecret(http: HttpClient, args: {
     readonly value: string;
 }): Promise<SecretRecord>;
 export declare function deleteSecret(http: HttpClient, name: string): Promise<void>;
+/** Result of an `upsertSkill`: the stored record + whether the bytes changed. */
+export interface SkillUpsertResult {
+    readonly skill: SkillRecord;
+    readonly updated: boolean;
+}
+/**
+ * Upsert a workspace skill by name — `PUT /skills/{name}`. The bundle bytes must
+ * already exist in the asset store (staged via presign/finalize before this
+ * call); the body carries only the metadata. Identical `contentHash` is a no-op
+ * (`updated:false`).
+ */
+export declare function upsertSkill(http: HttpClient, args: {
+    readonly name: string;
+    readonly contentHash: string;
+    readonly description: string;
+    readonly sizeBytes: number;
+}): Promise<SkillUpsertResult>;
+export declare function listSkills(http: HttpClient): Promise<readonly SkillRecord[]>;
+export declare function getSkill(http: HttpClient, name: string): Promise<SkillRecord>;
+export declare function deleteSkill(http: HttpClient, name: string): Promise<void>;
 export interface AssetUploadResult {
     readonly assetId: string;
     readonly contentHash: string;

package/dist/_contracts/operations.js

@@ -902,6 +902,49 @@ function unwrapSecret(result) {
     }
     return result;
 }
+/**
+ * Upsert a workspace skill by name — `PUT /skills/{name}`. The bundle bytes must
+ * already exist in the asset store (staged via presign/finalize before this
+ * call); the body carries only the metadata. Identical `contentHash` is a no-op
+ * (`updated:false`).
+ */
+export async function upsertSkill(http, args) {
+    const result = await http.request(`/api/skills/${encodeURIComponent(args.name)}`, {
+        method: "PUT",
+        body: JSON.stringify({
+            contentHash: args.contentHash,
+            description: args.description,
+            sizeBytes: args.sizeBytes
+        })
+    });
+    if (result && typeof result === "object" && "skill" in result) {
+        const wrapped = result;
+        return { skill: wrapped.skill, updated: wrapped.updated === true };
+    }
+    return { skill: result, updated: true };
+}
+export async function listSkills(http) {
+    const result = await http.request("/api/skills");
+    if (Array.isArray(result)) {
+        return result;
+    }
+    return result.skills;
+}
+export async function getSkill(http, name) {
+    const result = await http.request(`/api/skills/${encodeURIComponent(name)}`);
+    return unwrapSkill(result);
+}
+export async function deleteSkill(http, name) {
+    await http.request(`/api/skills/${encodeURIComponent(name)}`, {
+        method: "DELETE"
+    });
+}
+function unwrapSkill(result) {
+    if (result && typeof result === "object" && "skill" in result) {
+        return result.skill;
+    }
+    return result;
+}
 function hasRun(value) {
     return Boolean(value && typeof value === "object" && "run" in value);
 }

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

@@ -3,11 +3,16 @@
  *
  * Public composition concepts:
  *
- *   - `SkillToolRef` is the wire-level reference to a skill, re-expressed as a
- *     synthetic no-arg "load-tool" the model calls to pull in the skill's
- *     `SKILL.md` body. It carries the uploaded bundle's `assetId` (produced by
- *     the SDK upload path) plus the tool `name` + `description`, and travels in
- *     `submission.tools`.
+ *   - `SkillRef` is the PUBLIC wire-level reference to a workspace skill: just
+ *     `{ kind:"skill", name }`. The binding is BY NAME and mutable — the run
+ *     resolves the name to the workspace skill's current bytes at submit time.
+ *     It travels in `submission.skills` (NOT `submission.tools`).
+ *
+ *   - `ResolvedSkillRef` is the BFF-produced, boot-record-only resolution of a
+ *     `SkillRef`: `{ kind:"skill", assetId, name, description }`. It never
+ *     appears on the public ingress wire — the resolver fills it before
+ *     persisting the boot record so the in-container re-parse can read the
+ *     skill's asset + description without a DB round-trip.
  *
  *   - `McpServerRef` is the non-secret part of an MCP server declaration:
  *     `name` and `url`. Bearer / cookie / per-request headers travel in
@@ -52,6 +57,13 @@ export declare const SKILL_NAME_PATTERN: RegExp;
  * because SessionDO reserves that separator for MCP namespace routing.
  */
 export declare const TOOL_NAME_PATTERN: RegExp;
+/**
+ * Names reserved by the skills subsystem and therefore usable as neither a
+ * skill name nor a custom tool name. `skills` is the injected meta-tool (see
+ * {@link SKILLS_TOOL_NAME} in `submission.ts`); `skill` is its singular. Both
+ * the SDK factories and the BFF `parseSkills` / `parseTools` reject these.
+ */
+export declare const SKILL_RESERVED_NAMES: ReadonlySet<string>;
 /**
  * Hard caps applied at upload time. The SDK enforces these before
  * computing the zip hash so a clearly-too-big bundle never wastes
@@ -82,12 +94,25 @@ export declare const SKILL_BUNDLE_LIMITS: {
     readonly defaultDirMode: 493;
 };
 /**
- * A skill re-expressed as a TOOL. The model calls this no-arg load-tool to pull
- * the skill's `SKILL.md` body into context; the bundle's files are eagerly
- * staged to `/workspace/skills/<name>/`. It travels in `submission.tools`
- * alongside builtin names and custom {@link ToolRef}s.
+ * The PUBLIC wire reference to a workspace skill — by NAME, no bytes, no hash.
+ * This is what the SDK sends in `submission.skills` and what the idempotency
+ * hash covers. The run resolves the name to the workspace skill's CURRENT bytes
+ * at submit time (a re-upload under the same name changes what later runs see).
+ */
+export interface SkillRef {
+    readonly kind: "skill";
+    readonly name: string;
+}
+/**
+ * BFF-produced, BOOT-RECORD-ONLY resolution of a {@link SkillRef}. The submit-time
+ * resolver looks the name up in the workspace skill registry and fills in the
+ * current `assetId` + `description`; this is written to the boot record's trusted
+ * `submission.resolvedSkills` so the in-container re-parse and the manifest /
+ * materialize layers can stage the bundle without a DB round-trip. It NEVER
+ * appears on the public ingress wire (rejected by `parseSubmission` unless the
+ * caller is a trusted re-parse).
  */
-export interface SkillToolRef {
+export interface ResolvedSkillRef {
     readonly kind: "skill";
     readonly assetId: string;
     readonly name: string;

package/dist/_contracts/run-config.js

@@ -3,11 +3,16 @@
  *
  * Public composition concepts:
  *
- *   - `SkillToolRef` is the wire-level reference to a skill, re-expressed as a
- *     synthetic no-arg "load-tool" the model calls to pull in the skill's
- *     `SKILL.md` body. It carries the uploaded bundle's `assetId` (produced by
- *     the SDK upload path) plus the tool `name` + `description`, and travels in
- *     `submission.tools`.
+ *   - `SkillRef` is the PUBLIC wire-level reference to a workspace skill: just
+ *     `{ kind:"skill", name }`. The binding is BY NAME and mutable — the run
+ *     resolves the name to the workspace skill's current bytes at submit time.
+ *     It travels in `submission.skills` (NOT `submission.tools`).
+ *
+ *   - `ResolvedSkillRef` is the BFF-produced, boot-record-only resolution of a
+ *     `SkillRef`: `{ kind:"skill", assetId, name, description }`. It never
+ *     appears on the public ingress wire — the resolver fills it before
+ *     persisting the boot record so the in-container re-parse can read the
+ *     skill's asset + description without a DB round-trip.
  *
  *   - `McpServerRef` is the non-secret part of an MCP server declaration:
  *     `name` and `url`. Bearer / cookie / per-request headers travel in
@@ -53,6 +58,13 @@ export const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,127}$/;
  * because SessionDO reserves that separator for MCP namespace routing.
  */
 export const TOOL_NAME_PATTERN = SKILL_NAME_PATTERN;
+/**
+ * Names reserved by the skills subsystem and therefore usable as neither a
+ * skill name nor a custom tool name. `skills` is the injected meta-tool (see
+ * {@link SKILLS_TOOL_NAME} in `submission.ts`); `skill` is its singular. Both
+ * the SDK factories and the BFF `parseSkills` / `parseTools` reject these.
+ */
+export const SKILL_RESERVED_NAMES = new Set(["skills", "skill"]);
 // ---------------------------------------------------------------------------
 // Skill bundle limits (uploaded bundles)
 // ---------------------------------------------------------------------------

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

@@ -508,6 +508,28 @@ export interface FileRecord {
     readonly finalizedAt?: string | null;
     readonly [key: string]: unknown;
 }
+/**
+ * Wire-level metadata record for a workspace skill as returned by the BFF.
+ *
+ * Workspace skills are named, mutable, by-name-bound bundles: `skill.upload()`
+ * upserts one under a stable `name`; a run references it by that name and the
+ * platform resolves it to the CURRENT bytes at submit time. This record is
+ * METADATA ONLY — the bytes live in the content-addressed asset store keyed by
+ * `contentHash`. `version` bumps each time the bytes change under the name.
+ */
+export interface SkillRecord {
+    readonly id?: string;
+    readonly kind?: "skill";
+    readonly name: string;
+    readonly contentHash: string;
+    readonly description: string;
+    readonly sizeBytes?: number | null;
+    readonly version?: number;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly deletedAt?: string | null;
+    readonly [key: string]: unknown;
+}
 /**
  * Wire-level record for a workspace secret as returned by the BFF.
  *

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[];
@@ -418,6 +425,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,7 +497,9 @@ 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];
@@ -535,6 +551,42 @@ export declare const BuiltinTools: {
  * 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 +600,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[];