@aexhq/sdk 0.46.5-canary → 0.50.0

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

@@ -1,373 +0,0 @@
-/**
- * Session-request config and composition refs for the public SDK/CLI surface.
- *
- * Public composition concepts:
- *
- *   - `SkillRef` is the PUBLIC wire-level reference to a workspace skill: just
- *     `{ kind:"skill", name }`. The binding is BY NAME and mutable — the session
- *     resolves the name to the workspace skill's current bytes at submit time.
- *     It travels in `submission.skills` (NOT `submission.tools`).
- *
- *   - `McpServerRef` is the non-secret part of an MCP server declaration:
- *     `name` and `url`. Bearer / cookie / per-request headers travel in
- *     the session's vaulted `secrets.mcpServers` block keyed by the same
- *     `name`, and never enter the hashed submission payload or the
- *     session snapshot.
- *
- *   - `SessionRequestConfig` is the credential-free set of session parameters that
- *     can be persisted to disk (e.g. `aex start --config session.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, type PlatformEnvironment } from "./submission.js";
-import { type ModelName } from "./models.js";
-import type { RuntimeSize } from "./runtime-sizes.js";
-import { ASSET_ID_PATTERN, MOUNT_PATH_MAX_LENGTH, MOUNT_PATH_PATTERN, assertValidMountPath } from "./schemas/asset-ref.js";
-import { MCP_SERVER_NAME_PATTERN, REMOTE_MCP_STDIO_REJECTED_MESSAGE, rejectStdioMcpShape } from "./schemas/mcp-server.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;
-/**
- * Provider-safe submitted tool name. Tool names share the same lowercase
- * kebab/underscore envelope as skills. Submission parsing rejects `__`
- * 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>;
-/**
- * One honest envelope for every file, skill, tool, or instruction archive that
- * the managed runtime mounts. Raw asset storage is a broader concept and may
- * have a different quota; these limits describe usable runtime inputs.
- */
-export declare const ASSET_ARCHIVE_LIMITS: {
-    /**
-     * 16 MiB. Sized to the SHARED api Lambda (512 MB) that `GetObject`s and
-     * DEFLATE-decompresses every pinned archive on every submit, NOT to the
-     * single-tenant sandbox. Raisable once that preflight moves off shared infra.
-     */
-    readonly maxCompressedBytes: number;
-    readonly maxDecompressedBytes: number;
-    readonly maxEntries: 1000;
-    readonly maxMetadataBytes: number;
-};
-/** Skill-specific authoring constraints layered on the shared asset envelope. */
-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;
-    /** Single-entry path length cap: `PATH_MAX`, the only real ceiling. */
-    readonly maxPathLength: 4096;
-    /** Stored file mode for ordinary files. */
-    readonly defaultFileMode: 420;
-    /** Stored directory mode. */
-    readonly defaultDirMode: 493;
-};
-/**
- * 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 session resolves the name to the workspace skill's CURRENT bytes
- * at submit time (a re-upload under the same name changes what later sessions see).
- */
-export interface SkillRef {
-    readonly kind: "skill";
-    readonly name: string;
-}
-/**
- * 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;
-}
-type ToolJsonPrimitive = string | number | boolean | null;
-type ToolJsonValue = ToolJsonPrimitive | ToolJsonValue[] | {
-    readonly [key: string]: ToolJsonValue;
-};
-export type ToolInputSchema = {
-    readonly [key: string]: ToolJsonValue;
-};
-/**
- * User-supplied executable tool bundle. The bytes are addressed by the same
- * content-addressed asset ref used by Skills/Files, while the provider-visible
- * manifest rides as value-free metadata on the submission.
- */
-export interface ToolRef extends AssetRef {
-    readonly description: string;
-    readonly input_schema: ToolInputSchema;
-    readonly entry: string;
-}
-/** Content-hash format: `sha256:<64 lowercase hex>`. */
-export { CANONICAL_SHA256_DIGEST_PATTERN as INLINE_CONTENT_HASH_PATTERN } from "./canonical-sha256.js";
-/**
- * Checks the `AssetRef` discriminator on an already typed file reference.
- *
- * This compatibility predicate is not full validation for an untrusted value;
- * use the owning parser when the complete asset-ref shape must be validated.
- */
-export declare function isAssetRef(ref: 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.
- *
- * Declared in `schemas/asset-ref.ts` next to the schema that enforces it — this
- * module imports that one, so it cannot live here without a cycle.
- */
-export { ASSET_ID_PATTERN };
-export type FileRef = AssetRef;
-/** @deprecated Use `isAssetRef`. This direct alias remains for public compatibility. */
-export declare const isFileAssetRef: typeof isAssetRef;
-/**
- * The default mount DIRECTORY a `File` unzips into when the caller does not set
- * `mountPath`. `/workspace` is also the agent's default working directory, so a
- * file handed with no `mountPath` lands directly in the agent's cwd (e.g.
- * `/workspace/source-video-subtitles.srt`).
- */
-export declare const DEFAULT_FILE_MOUNT_PATH = "/workspace";
-/**
- * A `mountPath` is an ABSOLUTE container directory under the workspace, and
- * {@link assertValidMountPath} is the assert the SDK `File` builders and the BFF
- * asset-ref parser share so both reject the same malformed input.
- *
- * All three are declared in `schemas/asset-ref.ts`, next to the schema that
- * enforces them — this module imports that one, so they cannot live here without
- * a cycle.
- */
-export { MOUNT_PATH_PATTERN, MOUNT_PATH_MAX_LENGTH, assertValidMountPath };
-/**
- * Common parser for any `kind: "asset"` ref (file / tool bundle).
- */
-export declare function parseAssetRefFields(record: Record<string, unknown>, path: string): AssetRef;
-/**
- * Manifest entry persisted in `skill_bundles.manifest` and in session-owned
- * snapshots. `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` (PATH_MAX, 4096)
- *   - NUL bytes
- *
- * There is deliberately NO nesting-depth cap (review-2026-07-25 plan 04): traversal is
- * already dead structurally via the segment rules above, so a depth limit refused
- * legitimate layouts while protecting nothing.
- */
-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 parseSkillBundleEntry(input: {
-    readonly path: string;
-    readonly size: number;
-    readonly mode?: number;
-}): SkillBundleEntry;
-/** @deprecated Use {@link parseSkillBundleEntry}; this compatibility wrapper is identical. */
-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 workspace instructions or file uploads instead.
- *
- * Returns a canonical manifest with totals computed.
- */
-export declare function parseSkillBundleManifest(input: ReadonlyArray<{
-    readonly path: string;
-    readonly size: number;
-    readonly mode?: number;
-}>): SkillBundleManifest;
-/** @deprecated Use {@link parseSkillBundleManifest}; this compatibility wrapper is identical. */
-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.
- *
- * Declared in `schemas/mcp-server.ts` alongside the shape gate that raises it.
- */
-export { REMOTE_MCP_STDIO_REJECTED_MESSAGE };
-/**
- * The non-secret half of an MCP server declaration. This is what enters
- * the hashed submission, the session 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;
-}
-/** Declared in `schemas/mcp-server.ts`, next to the schema that enforces it. */
-export { MCP_SERVER_NAME_PATTERN };
-/**
- * A session-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 SessionConfigMcpServer extends McpServerRef {
-    readonly headers?: Readonly<Record<string, string>>;
-}
-/**
- * Parse the non-secret half of an MCP server declaration mounted at `path`.
- *
- * SSRF guard at the parser boundary (C4) — the platform MCP proxy relies on
- * this validation; each branch of {@link denyReasonForMcpHost} maps to an SSRF
- * regression test case.
- */
-export declare function parseMcpServerRef(input: unknown, path: string): McpServerRef;
-export { rejectStdioMcpShape };
-/**
- * Plain JSON accepted by `aex start --config <path>`. This is not a
- * platform object; it is only the non-secret session parameters that the CLI folds
- * into the normal `submit` request.
- */
-export interface SessionRequestConfig {
-    readonly model: ModelName;
-    readonly system?: string;
-    readonly prompt: string | readonly string[];
-    readonly mcpServers?: readonly SessionConfigMcpServer[];
-    readonly environment?: PlatformEnvironment;
-    /** Managed runtime size preset (see {@link RuntimeSize}). */
-    readonly runtimeSize?: RuntimeSize;
-    /** Session deadline as a duration string (`"1h"`, `"30m"`); bounded [1m, 8h] server-side. */
-    readonly timeout?: string;
-    readonly metadata?: Readonly<Record<string, JsonValue>>;
-}
-/**
- * Parse a session request config from JSON. Defensive — used by the host CLI to
- * load `--config session.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 parseSessionRequestConfig(input: unknown): SessionRequestConfig;
-/**
- * Result of splitting a session config into the non-secret submission and the
- * secret MCP-headers bundle. The SDK calls this just before posting to
- * /api/sessions: the `submission` half is what the BFF hashes for idempotency, the
- * `mcpServerSecrets` half is what enters session-scoped custody.
- *
- * `prompt` is normalised to `readonly string[]` (single-string callers
- * get wrapped in a length-1 array) so the wire payload, the hosted API,
- * and the audit log don't have to re-handle two shapes.
- */
-export interface NormalisedSessionRequestConfig {
-    readonly model: ModelName;
-    readonly system?: string;
-    readonly prompt: readonly string[];
-    readonly mcpServers: readonly McpServerRef[];
-    readonly environment?: PlatformEnvironment;
-    readonly metadata?: Readonly<Record<string, JsonValue>>;
-    /**
-     * MCP servers whose session-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 normaliseSessionRequestConfig(config: SessionRequestConfig): NormalisedSessionRequestConfig;