@aexhq/sdk 0.13.6

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

@@ -0,0 +1,304 @@
+/**
+ * Run-request config and composition refs for the public SDK/CLI surface.
+ *
+ * Public composition concepts:
+ *
+ *   - `SkillRef` is the wire-level reference to a skill — either an
+ *     `skl_*` id pointing at a workspace-uploaded bundle, a
+ *     `{vendor, skillId, version}` reference to a provider built-in, or
+ *     a `{slot, name, contentHash}` reference to per-run bytes attached
+ *     as a multipart part on the submitRun call (and torn down at run
+ *     terminal). The three shapes are discriminated by `kind` so
+ *     consumers branch mechanically and providers can never accidentally
+ *     be looked up in `skill_bundles`. Transient refs do NOT round-trip
+ *     through JSON (bytes can't be serialised back); `parseRunRequestConfig`
+ *     therefore rejects them while the BFF multipart submission parser
+ *     accepts them.
+ *
+ *   - `McpServerRef` is the non-secret part of an MCP server declaration:
+ *     `name` and `url`. Bearer / cookie / per-request headers travel in
+ *     the run's vaulted `secrets.mcpServers` block keyed by the same
+ *     `name`, and never enter the hashed submission payload or the
+ *     run snapshot.
+ *
+ *   - `RunRequestConfig` is the credential-free set of run parameters that
+ *     can be persisted to disk (e.g. `aex run --config run.json`) or
+ *     returned from ordinary application helper functions. It excludes
+ *     `secrets`/`idempotencyKey`/`signal`; strings are already resolved at
+ *     the call site before submission.
+ *
+ *   - Skill bundle validation lives here so the SDK (zipping locally),
+ *     hosted API (server-side unzip + manifest extraction) and runtime
+ *     mount layer share a single source of truth for
+ *     the limits, the path normaliser, and the manifest invariants. The
+ *     DB CHECK constraints on `skill_bundles.manifest` mirror these.
+ *
+ * Keep this as the public source of truth for the SDK/CLI composition
+ * boundary.
+ */
+import type { JsonValue, PlatformProxyEndpoint, PlatformEnvironment } from "./submission.js";
+import type { RuntimeSize } from "./runtime-sizes.js";
+/**
+ * Mirrors the server-side CHECK constraint
+ * `skill_bundles_id_format_chk = check (id ~ '^skl_[A-Za-z0-9_-]{8,128}$')`
+ * on persisted skill bundles. Keep the two in lockstep.
+ */
+export declare const SKILL_ID_PATTERN: RegExp;
+/**
+ * Human-readable, workspace-scoped name. Lowercase, kebab-friendly,
+ * 1..128 chars. The DB enforces the length bound via
+ * `skill_bundles_name_len_chk`; this regex tightens the SDK/CLI input
+ * surface so callers fail at the boundary rather than in the BFF.
+ */
+export declare const SKILL_NAME_PATTERN: RegExp;
+/**
+ * Hard caps applied at upload time. The SDK enforces these before
+ * computing the zip hash so a clearly-too-big bundle never wastes
+ * bytes-on-the-wire; the BFF re-enforces server-side because the SDK
+ * is untrusted. Numbers are deliberately conservative for the MVP and
+ * can be tuned later; keep this object as the single tuning point.
+ */
+export declare const SKILL_BUNDLE_LIMITS: {
+    /** Compressed (.zip) ceiling. */
+    readonly maxCompressedBytes: number;
+    /** Sum of uncompressed file sizes. */
+    readonly maxDecompressedBytes: number;
+    /** Number of regular file entries (directories don't count). */
+    readonly maxFiles: 1000;
+    /** Maximum directory nesting depth — `a/b/c/d` has depth 4. */
+    readonly maxDepth: 16;
+    /** Single-entry path length cap. */
+    readonly maxPathLength: 512;
+    /** Stored file mode for ordinary files. */
+    readonly defaultFileMode: 420;
+    /** Stored directory mode. */
+    readonly defaultDirMode: 493;
+};
+export type SkillRef = ProviderSkillRef | AssetRef;
+/**
+ * Storage-neutral uploaded asset reference. Runtime materialization resolves
+ * `assetId` privately; public callers never name object-store paths.
+ */
+export interface AssetRef {
+    readonly kind: "asset";
+    readonly assetId: string;
+    readonly name: string;
+    readonly mountPath?: string;
+}
+export interface ProviderSkillRef {
+    readonly kind: "provider";
+    readonly vendor: "anthropic" | "custom";
+    readonly skillId: string;
+    readonly version?: string;
+}
+/** Content-hash format: `sha256:<64 lowercase hex>`. */
+export declare const INLINE_CONTENT_HASH_PATTERN: RegExp;
+export declare function isProviderSkillRef(ref: SkillRef): ref is ProviderSkillRef;
+export declare function isAssetRef(ref: SkillRef | AgentsMdRef | FileRef): ref is AssetRef;
+/**
+ * Asset ids are storage-neutral product ids. Current uploads derive the id from
+ * the content digest (`asset_<sha256hex>`), but callers must treat it as opaque.
+ */
+export declare const ASSET_ID_PATTERN: RegExp;
+export type AgentsMdRef = AssetRef;
+export declare function isAgentsMdAssetRef(ref: AgentsMdRef): ref is AssetRef;
+export type FileRef = AssetRef;
+export declare function isFileAssetRef(ref: FileRef): ref is AssetRef;
+/**
+ * Parse a `SkillRef` from untrusted input. Used by the BFF run parser
+ * and by the operations module when deserialising API responses. Only
+ * `kind: "asset"` and `kind: "provider"` are valid; all other historical
+ * wire shapes (including storage-specific refs) are rejected.
+ */
+export declare function parseSkillRef(input: unknown, path: string): SkillRef;
+/**
+ * Common parser for any `kind: "asset"` ref (skill / agentsMd / file).
+ */
+export declare function parseAssetRefFields(record: Record<string, unknown>, path: string): AssetRef;
+/**
+ * Manifest entry persisted in `skill_bundles.manifest` and
+ * `run_skill_snapshots.manifest`. `path` is forward-slash, relative,
+ * normalised. `mode` is the stored POSIX mode (sanitised, NOT the user's
+ * filesystem mode) — see `SKILL_BUNDLE_LIMITS.defaultFileMode`.
+ */
+export interface SkillBundleEntry {
+    readonly path: string;
+    readonly size: number;
+    readonly mode: number;
+}
+export interface SkillBundleManifest {
+    readonly entries: readonly SkillBundleEntry[];
+    /** Total uncompressed bytes (sum of `entries[i].size`). */
+    readonly totalSize: number;
+    /** Number of file entries. Equals `entries.length` by construction. */
+    readonly fileCount: number;
+}
+export declare class SkillBundleValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Reject input paths that try to escape the bundle root or smuggle
+ * platform-specific syntax. Returns the canonical forward-slash
+ * relative path; never returns paths starting or ending with `/`.
+ *
+ * Rejects:
+ *   - empty strings and pure whitespace
+ *   - absolute paths (`/foo`, `C:\foo`, `\\server\share`)
+ *   - backslash separators (Windows)
+ *   - `..` segments anywhere in the path
+ *   - `.` segments anywhere except a leading bare `.`
+ *   - paths whose length exceeds `SKILL_BUNDLE_LIMITS.maxPathLength`
+ *   - paths whose depth exceeds `SKILL_BUNDLE_LIMITS.maxDepth`
+ *   - NUL bytes
+ */
+export declare function normaliseSkillBundlePath(input: string): string;
+/**
+ * Validate one manifest entry: normalises the path, bounds the size,
+ * and sanitises the mode to one of {defaultFileMode, defaultDirMode}.
+ * The bundle is files-only, so any non-regular-file entry is rejected
+ * upstream by the caller (zip parser must skip symlinks, device files,
+ * etc. before reaching this function).
+ */
+export declare function validateSkillBundleEntry(input: {
+    readonly path: string;
+    readonly size: number;
+    readonly mode?: number;
+}): SkillBundleEntry;
+/**
+ * Validate a full **skill bundle** manifest. Enforces:
+ *   - entries is a non-empty array
+ *   - `SKILL.md` exists at the bundle root (this is what makes a
+ *     bundle a skill rather than a plain workspace file)
+ *   - file count <= maxFiles
+ *   - total uncompressed size <= maxDecompressedBytes
+ *   - per-entry validation (see `validateSkillBundleEntry`)
+ *   - no duplicate paths
+ *
+ * In this public surface, **skill** means "Claude Skill" — bundles without
+ * `SKILL.md` are not skills and must go
+ * through the `AgentsMd` or `File` upload concepts instead.
+ *
+ * Returns a canonical manifest with totals computed.
+ */
+export declare function validateSkillBundleManifest(input: ReadonlyArray<{
+    readonly path: string;
+    readonly size: number;
+    readonly mode?: number;
+}>): SkillBundleManifest;
+/**
+ * Returns true when the manifest carries a `SKILL.md` entry at the
+ * bundle root. The presence of this file is Anthropic's
+ * skill-auto-discovery signal — bundles that have it are treated as
+ * Claude skills and mounted accordingly; bundles that don't are still
+ * usable agent context (AGENTS.md, settings files, folders of helper
+ * data) but the agent won't pick them up via the skills mechanism.
+ *
+ * The check is intentionally a separate, callable predicate (rather
+ * than baked into `validateSkillBundleManifest`) so the storage and
+ * the attach layers can remain independent.
+ */
+export declare function hasSkillMdAtRoot(manifest: SkillBundleManifest): boolean;
+/**
+ * Remote MCP transports Aex accepts. Both are over HTTP — `http`
+ * is the streamable-HTTP transport, `sse` is the event-stream
+ * transport. `stdio` is explicitly NOT a value here: local-process
+ * MCP is not implemented.
+ */
+export declare const REMOTE_MCP_TRANSPORTS: readonly ["http", "sse"];
+export type RemoteMcpTransport = (typeof REMOTE_MCP_TRANSPORTS)[number];
+/**
+ * Canonical error string for any attempt to declare a stdio-shaped MCP
+ * server (`transport: "stdio"`, or a stdio-only field like `command` /
+ * `args` / `env`). Pinned in source so every surface — shared parser,
+ * SDK builder, CLI flag parser, dashboard form — surfaces the same
+ * message and a user can find it via grep.
+ */
+export declare const REMOTE_MCP_STDIO_REJECTED_MESSAGE = "stdio MCP servers are not supported by Aex. Aex supports remote MCP servers over HTTP/SSE only.";
+/**
+ * The non-secret half of an MCP server declaration. This is what enters
+ * the hashed submission, the run snapshot, and any audit log. `name`
+ * keys into `secrets.mcpServers` for the per-request headers.
+ *
+ * `transport` is optional on the wire — when omitted, the runtime is
+ * free to pick the default remote transport (`http`). When present, it
+ * MUST be one of {@link REMOTE_MCP_TRANSPORTS}; stdio is rejected at
+ * parse time.
+ */
+export interface McpServerRef {
+    readonly name: string;
+    readonly url: string;
+    readonly transport?: RemoteMcpTransport;
+}
+export declare const MCP_SERVER_NAME_PATTERN: RegExp;
+/**
+ * A run-config MCP entry. The user is free to supply headers inline; the SDK
+ * splits the call site cleanly at submission time so the Authorization (or
+ * other auth-bearing) header never enters the non-secret wire payload.
+ */
+export interface RunConfigMcpServer extends McpServerRef {
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export declare function parseMcpServerRef(input: unknown, path: string): McpServerRef;
+/**
+ * Throw the canonical stdio-rejected error if the record carries any
+ * stdio-only marker (`transport: "stdio"`, `command`, `args`, `env`).
+ * Used by both the shared parser and the SDK `McpServer.remote`
+ * builder so every entry point surfaces the same message.
+ */
+export declare function rejectStdioMcpShape(record: Record<string, unknown>): void;
+/**
+ * Plain JSON accepted by `aex run --config <path>`. This is not a
+ * platform object; it is only the non-secret run parameters that the CLI folds
+ * into the normal `submitRun` request.
+ */
+export interface RunRequestConfig {
+    readonly model: string;
+    readonly system?: string;
+    readonly prompt: string | readonly string[];
+    readonly skills?: readonly SkillRef[];
+    readonly mcpServers?: readonly RunConfigMcpServer[];
+    readonly environment?: PlatformEnvironment;
+    /** Managed runtime size preset (see {@link RuntimeSize}). */
+    readonly runtimeSize?: RuntimeSize;
+    /** Run deadline as a duration string (`"1h"`, `"30m"`); bounded [1m, 6h] server-side. */
+    readonly timeout?: string;
+    readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+}
+/**
+ * Parse a run request config from JSON. Defensive — used by the host CLI to
+ * load `--config run.json`. Throws with the JSON path that failed so
+ * a user can fix their file. Headers are preserved here and split out
+ * later by the SDK normalisation step.
+ */
+export declare function parseRunRequestConfig(input: unknown): RunRequestConfig;
+/**
+ * Result of splitting a run config into the non-secret submission and the
+ * secret MCP-headers bundle. The SDK calls this just before posting to
+ * /api/runs: the `submission` half is what the BFF hashes for idempotency, the
+ * `mcpServerSecrets` half is what enters run-scoped custody.
+ *
+ * `prompt` is normalised to `readonly string[]` (single-string callers
+ * get wrapped in a length-1 array) so the wire payload, the worker, and
+ * the audit log don't have to re-handle two shapes.
+ */
+export interface NormalisedRunRequestConfig {
+    readonly model: string;
+    readonly system?: string;
+    readonly prompt: readonly string[];
+    readonly skills: readonly SkillRef[];
+    readonly mcpServers: readonly McpServerRef[];
+    readonly environment?: PlatformEnvironment;
+    readonly proxyEndpoints?: readonly PlatformProxyEndpoint[];
+    readonly metadata?: Readonly<Record<string, JsonValue>>;
+    /**
+     * MCP servers whose run-config entry carried `headers`. Keyed by the `name`
+     * that appears in `mcpServers` so the BFF can pair them up.
+     */
+    readonly mcpServerSecrets: ReadonlyArray<{
+        readonly name: string;
+        readonly url: string;
+        readonly headers: Readonly<Record<string, string>>;
+    }>;
+}
+export declare function normaliseRunRequestConfig(config: RunRequestConfig): NormalisedRunRequestConfig;