@aexhq/sdk 0.38.1 → 0.40.0

package/dist/_contracts/models.js

@@ -1,3 +1,4 @@
+import { suggest } from "./suggest.js";
 /**
  * Source of truth for the closed model set: each canonical model id maps to the
  * upstream providers that can serve it and the **provider-native** model string
@@ -149,6 +150,38 @@ export function resolveProviderModelId(model, provider) {
     }
     return native;
 }
+/**
+ * The single model→provider resolver shared by the SDK and the CLI, wrapping
+ * {@link providersForModel} with the forward-compat unknown-model allowance:
+ *
+ *   - `provider` given: it is honored. If `model` is a KNOWN id, the provider
+ *     must serve it (else throw). If `model` is UNKNOWN, it is allowed through
+ *     so a slightly-old client can still run a newly-launched model (the server
+ *     arbitrates).
+ *   - `provider` omitted: a known model resolves to its DEFAULT provider (first
+ *     declared). An UNKNOWN model with no provider throws a `did you mean?`
+ *     hint — you must name a provider to run a model this client doesn't know.
+ *
+ * Returns the resolved {@link RunProvider}.
+ */
+export function resolveModelProvider(model, provider) {
+    const providers = providersForModel(model);
+    if (provider !== undefined) {
+        if (providers.length > 0 && !providers.includes(provider)) {
+            throw new Error(`model ${JSON.stringify(model)} is not available for provider ${provider}; ` +
+                `available: ${providers.join(", ")}`);
+        }
+        return provider;
+    }
+    const inferred = providers[0];
+    if (inferred === undefined) {
+        const hint = suggest(model, RUN_MODELS);
+        throw new Error(`${JSON.stringify(model)} is not a known model id` +
+            (hint ? ` (did you mean ${JSON.stringify(hint)}?)` : "") +
+            "; pass provider explicitly to run it");
+    }
+    return inferred;
+}
 export function isRunModel(input) {
     return typeof input === "string" && RUN_MODELS.includes(input);
 }

package/dist/_contracts/operations.d.ts

@@ -1,6 +1,7 @@
 import type { HttpClient } from "./http.js";
+import type { AexEvent } from "./event-envelope.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, ChildRunRef, FileRecord, Output, OutputLink, OutputLinkOptions, OutputFileDownload, OutputFileSelector, OutputFileType, OutputQuery, OutputText, ReadOutputTextOptions, Run, 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
@@ -39,7 +40,29 @@ export declare function listRuns(http: HttpClient, query?: RunListQuery): Promis
 export interface IdempotencyOptions {
     readonly idempotencyKey?: string;
 }
+/**
+ * Resolve a caller-supplied idempotency key to the value that ships on the
+ * request. FAIL-FAST: an empty or whitespace-only key THROWS
+ * {@link RunConfigValidationError} — a footgun that silently disabled dedup
+ * (`?? generate()` kept `''`, then a downstream truthy header-drop shipped no
+ * `Idempotency-Key`). An absent key generates a fresh one; a real key is
+ * returned verbatim. The single choke point every send/create/run entry uses.
+ */
+export declare function resolveIdempotencyKey(key?: string): string;
 export declare function createSession(http: HttpClient, request: SessionCreateRequest, options?: IdempotencyOptions): Promise<Session>;
+/** The result of a non-blocking {@link submit}: the run id + the created session. */
+export interface SubmitResult {
+    readonly runId: string;
+    readonly session: Session;
+}
+/**
+ * Fire-and-forget submit — create the session and post its first turn WITHOUT
+ * awaiting the turn to settle (the honest counterpart to await-settle `run()`).
+ * Returns the `runId` immediately; observe the run via a `webhook`, the event
+ * stream, or by re-opening the session. Mirrors {@link createSession}'s
+ * idempotency handling.
+ */
+export declare function submit(http: HttpClient, request: SessionCreateRequest, options?: IdempotencyOptions): Promise<SubmitResult>;
 export declare function getSession(http: HttpClient, sessionId: string): Promise<Session>;
 export declare function listSessions(http: HttpClient, query?: SessionListQuery): Promise<SessionListPage>;
 export declare function sendSessionMessage(http: HttpClient, sessionId: string, request: SessionMessageRequest, options?: IdempotencyOptions): Promise<SessionMessageAccepted>;
@@ -47,6 +70,16 @@ export declare function listSessionMessages(http: HttpClient, sessionId: string,
 export declare function suspendSession(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted>;
 export declare function cancelSession(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted>;
 export declare function resumeSession(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted>;
+/**
+ * Request the HITL write-gate: park the session `awaiting_approval` before its
+ * next gated action (mirrors {@link suspendSession}). Imperative counterpart to
+ * the declarative submission-time `approvalGate`.
+ */
+export declare function requestApproval(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted>;
+/** Approve an `awaiting_approval` session so the held turn resumes (→ running). */
+export declare function approveSession(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted>;
+/** Deny an `awaiting_approval` session so the held turn is cancelled (→ cancelled). */
+export declare function denySession(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted>;
 export declare function deleteSession(http: HttpClient, sessionId: string, options?: IdempotencyOptions): Promise<SessionStateChangeAccepted | void>;
 export declare function listSessionEvents(http: HttpClient, sessionId: string): Promise<readonly SessionEvent[]>;
 export declare function listSessionOutputs(http: HttpClient, sessionId: string, query?: OutputQuery): Promise<readonly Output[]>;
@@ -57,7 +90,7 @@ export declare function getSessionCoordinatorTicket(http: HttpClient, sessionId:
  * pages and returns the FULL accumulated list, preserving the prior single-call
  * contract for callers (download/*, CLI, streamEvents polling).
  */
-export declare function listRunEvents(http: HttpClient, runId: string): Promise<readonly RunEvent[]>;
+export declare function listRunEvents(http: HttpClient, runId: string): Promise<readonly AexEvent[]>;
 /** A coordinator WS connection grant minted by the hosted API's ticket broker. */
 export interface CoordinatorTicket {
     readonly wsUrl: string;
@@ -94,6 +127,13 @@ export declare const READ_OUTPUT_TEXT_DEFAULT_BYTES = 50000;
  * selector lists the run's outputs to resolve the id; an id selector skips that.
  */
 export declare function readOutputText(http: HttpClient, runId: string, selector: OutputFileSelector, options?: ReadOutputTextOptions): Promise<OutputText>;
+/**
+ * List a run's subagent CHILD runs (`GET /runs/:id/children`). Each row is a
+ * {@link ChildRunRef} whose `id` resolves through the run facade (getRun /
+ * events / outputs) — so every child the platform hands you is resolvable. An
+ * empty array means the run spawned no children.
+ */
+export declare function listRunChildren(http: HttpClient, runId: string): Promise<readonly ChildRunRef[]>;
 export declare function cancelRun(http: HttpClient, runId: string): Promise<void>;
 export declare function deleteRun(http: HttpClient, runId: string): Promise<void>;
 /**
@@ -146,6 +186,14 @@ export declare function getBillingLedger(http: HttpClient, query?: BillingLedger
  */
 export declare function getWebhookSigningSecret(http: HttpClient): Promise<WebhookSigningSecret>;
 export declare function filterOutputs(outputs: readonly Output[], query: OutputQuery): readonly Output[];
+/**
+ * The single filename-matcher for cross-run / per-session output SEARCH. A
+ * string is a case-insensitive SUBSTRING match; a RegExp is tested as given (and
+ * reset to `lastIndex = 0` so a reused `/g` regex is safe). Sharing this SSoT is
+ * what closes the T16 crash class: `searchOutputs` no longer assumes `filename`
+ * is a string and passes a RegExp into `escapeRegExp(...).replace(...)`.
+ */
+export declare function toFilenameMatcher(filename: string | RegExp): (name: string) => boolean;
 export declare function classifyOutput(output: Pick<Output, "filename" | "contentType">): OutputFileType;
 export declare function normalizeOutputLinkExpiresIn(input?: OutputLinkOptions["expiresIn"]): number;
 /**
@@ -197,6 +245,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

@@ -1,6 +1,7 @@
 import { strToU8, zipSync } from "fflate";
+import { randomUUID } from "node:crypto";
 import { normalizeRunUnit } from "./run-unit.js";
-import { RunStateError } from "./sdk-errors.js";
+import { RunConfigValidationError, RunStateError } from "./sdk-errors.js";
 import { assertRunRecordArchivePublicSafeV1, buildRunRecordDownloadManifestV1 } from "./run-record.js";
 /**
  * The single source of truth for SDK<->BFF transport. The SDK class
@@ -83,8 +84,41 @@ export async function listRuns(http, query) {
     }
     return changed ? { ...page, runs } : page;
 }
+/**
+ * Resolve a caller-supplied idempotency key to the value that ships on the
+ * request. FAIL-FAST: an empty or whitespace-only key THROWS
+ * {@link RunConfigValidationError} — a footgun that silently disabled dedup
+ * (`?? generate()` kept `''`, then a downstream truthy header-drop shipped no
+ * `Idempotency-Key`). An absent key generates a fresh one; a real key is
+ * returned verbatim. The single choke point every send/create/run entry uses.
+ */
+export function resolveIdempotencyKey(key) {
+    if (key === undefined) {
+        return `aex-idem-${randomUUID()}`;
+    }
+    if (typeof key !== "string" || key.trim().length === 0) {
+        throw new RunConfigValidationError("idempotencyKey must be a non-empty, non-whitespace string", {
+            field: "idempotencyKey",
+            value: key
+        });
+    }
+    return key;
+}
+/**
+ * Fail-closed idempotency header builder. An EMPTY string throws (defense in
+ * depth alongside {@link resolveIdempotencyKey}) rather than silently dropping
+ * the header and proceeding non-idempotent; an absent key yields no header.
+ */
 function idempotencyHeaders(options) {
-    return options?.idempotencyKey ? { "Idempotency-Key": options.idempotencyKey } : undefined;
+    if (options?.idempotencyKey === undefined)
+        return undefined;
+    if (typeof options.idempotencyKey !== "string" || options.idempotencyKey.trim().length === 0) {
+        throw new RunConfigValidationError("idempotencyKey must be a non-empty, non-whitespace string", {
+            field: "idempotencyKey",
+            value: options.idempotencyKey
+        });
+    }
+    return { "Idempotency-Key": options.idempotencyKey };
 }
 export async function createSession(http, request, options) {
     const headers = idempotencyHeaders(options);
@@ -95,6 +129,17 @@ export async function createSession(http, request, options) {
     });
     return unwrapSession(result);
 }
+/**
+ * Fire-and-forget submit — create the session and post its first turn WITHOUT
+ * awaiting the turn to settle (the honest counterpart to await-settle `run()`).
+ * Returns the `runId` immediately; observe the run via a `webhook`, the event
+ * stream, or by re-opening the session. Mirrors {@link createSession}'s
+ * idempotency handling.
+ */
+export async function submit(http, request, options) {
+    const session = await createSession(http, request, options);
+    return { runId: session.sessionId ?? session.id, session };
+}
 export async function getSession(http, sessionId) {
     const result = await http.request(`/api/sessions/${encodeURIComponent(sessionId)}`);
     return unwrapSession(result);
@@ -141,6 +186,25 @@ export async function resumeSession(http, sessionId, options) {
     const headers = idempotencyHeaders(options);
     return http.request(`/api/sessions/${encodeURIComponent(sessionId)}/resume`, { method: "POST", ...(headers ? { headers } : {}) });
 }
+/**
+ * Request the HITL write-gate: park the session `awaiting_approval` before its
+ * next gated action (mirrors {@link suspendSession}). Imperative counterpart to
+ * the declarative submission-time `approvalGate`.
+ */
+export async function requestApproval(http, sessionId, options) {
+    const headers = idempotencyHeaders(options);
+    return http.request(`/api/sessions/${encodeURIComponent(sessionId)}/request-approval`, { method: "POST", ...(headers ? { headers } : {}) });
+}
+/** Approve an `awaiting_approval` session so the held turn resumes (→ running). */
+export async function approveSession(http, sessionId, options) {
+    const headers = idempotencyHeaders(options);
+    return http.request(`/api/sessions/${encodeURIComponent(sessionId)}/approve`, { method: "POST", ...(headers ? { headers } : {}) });
+}
+/** Deny an `awaiting_approval` session so the held turn is cancelled (→ cancelled). */
+export async function denySession(http, sessionId, options) {
+    const headers = idempotencyHeaders(options);
+    return http.request(`/api/sessions/${encodeURIComponent(sessionId)}/deny`, { method: "POST", ...(headers ? { headers } : {}) });
+}
 export async function deleteSession(http, sessionId, options) {
     const headers = idempotencyHeaders(options);
     return http.request(`/api/sessions/${encodeURIComponent(sessionId)}`, { method: "DELETE", ...(headers ? { headers } : {}) });
@@ -212,7 +276,7 @@ export async function findOutput(http, runId, query) {
         return null;
     if (matches.length === 1)
         return matches[0];
-    throw new RunStateError("findOutput: output query matched multiple files", {
+    throw new RunStateError("outputs.findOne: output query matched multiple files", {
         runId,
         matches: matches.map((output) => output.filename ?? output.id)
     });
@@ -260,7 +324,7 @@ export function resolveOutputFileSelector(outputs, selector, runId) {
     if (isPathSelector(selector)) {
         const target = normalizeOutputLookupPath(selector.path);
         if (!target) {
-            throw new RunStateError("downloadOutput: output path must be non-empty", { runId, path: selector.path });
+            throw new RunStateError("outputs.download: output path must be non-empty", { runId, path: selector.path });
         }
         const matches = outputs.filter((output) => {
             if (typeof output.filename !== "string")
@@ -274,15 +338,15 @@ export function resolveOutputFileSelector(outputs, selector, runId) {
         if (matches.length === 1)
             return matches[0];
         if (matches.length > 1) {
-            throw new RunStateError(`downloadOutput: output path "${selector.path}" matched multiple files`, { runId, path: selector.path, matches: matches.map((output) => output.filename ?? output.id) });
+            throw new RunStateError(`outputs.download: output path "${selector.path}" matched multiple files`, { runId, path: selector.path, matches: matches.map((output) => output.filename ?? output.id) });
         }
-        throw new RunStateError(`downloadOutput: output path "${selector.path}" was not found`, {
+        throw new RunStateError(`outputs.download: output path "${selector.path}" was not found`, {
             runId,
             path: selector.path
         });
     }
     if (typeof selector?.id !== "string" || selector.id.length === 0) {
-        throw new RunStateError("downloadOutput: selector must include an output id or path", { runId });
+        throw new RunStateError("outputs.download: selector must include an output id or path", { runId });
     }
     return { ...selector, id: selector.id };
 }
@@ -387,6 +451,18 @@ function grepLines(text, pattern) {
         .filter((line) => test(line))
         .join("\n");
 }
+/**
+ * List a run's subagent CHILD runs (`GET /runs/:id/children`). Each row is a
+ * {@link ChildRunRef} whose `id` resolves through the run facade (getRun /
+ * events / outputs) — so every child the platform hands you is resolvable. An
+ * empty array means the run spawned no children.
+ */
+export async function listRunChildren(http, runId) {
+    const result = await http.request(`/api/runs/${encodeURIComponent(runId)}/children`);
+    return Array.isArray(result)
+        ? result
+        : result.children;
+}
 export async function cancelRun(http, runId) {
     await http.request(`/api/runs/${encodeURIComponent(runId)}/cancel`, { method: "POST" });
 }
@@ -522,6 +598,23 @@ function normalizeOutputLookupPath(path) {
 export function filterOutputs(outputs, query) {
     return outputs.filter((output) => outputMatchesQuery(output, query));
 }
+/**
+ * The single filename-matcher for cross-run / per-session output SEARCH. A
+ * string is a case-insensitive SUBSTRING match; a RegExp is tested as given (and
+ * reset to `lastIndex = 0` so a reused `/g` regex is safe). Sharing this SSoT is
+ * what closes the T16 crash class: `searchOutputs` no longer assumes `filename`
+ * is a string and passes a RegExp into `escapeRegExp(...).replace(...)`.
+ */
+export function toFilenameMatcher(filename) {
+    if (typeof filename === "string") {
+        const needle = filename.toLowerCase();
+        return (name) => name.toLowerCase().includes(needle);
+    }
+    return (name) => {
+        filename.lastIndex = 0;
+        return filename.test(name);
+    };
+}
 export function classifyOutput(output) {
     const contentType = normalizeContentType(output.contentType);
     if (contentType) {
@@ -902,6 +995,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/run-record.d.ts

@@ -1,6 +1,7 @@
 import type { RunCostTelemetry } from "./run-cost.js";
 import { type CustodyManifestV1, type CustodyRedactionFinding } from "./run-custody.js";
-import type { Run, RunEvent, Output } from "./runtime-types.js";
+import type { AexEvent } from "./event-envelope.js";
+import type { Run, Output } from "./runtime-types.js";
 import type { PlatformSubmission } from "./submission.js";
 export declare const RUN_RECORD_SCHEMA_VERSION: "aex.run-record.v1";
 export declare const RUN_RECORD_MANIFEST_SCHEMA_VERSION: "aex.run-record.manifest.v1";
@@ -22,7 +23,7 @@ export interface RunRecordMetadataV1 {
 }
 export interface RunRecordEventsV1 {
     /** Typed `channel: "event"` records in the SDK `events/events.jsonl` export. */
-    readonly typed: readonly RunEvent[];
+    readonly typed: readonly AexEvent[];
 }
 export interface RunRecordV1 {
     readonly schemaVersion: typeof RUN_RECORD_SCHEMA_VERSION;