@aexhq/sdk 0.46.5-canary → 0.51.0

package/dist/retry.d.ts

@@ -1,70 +0,0 @@
-/**
- * Built-in transport resilience for the aex SDK.
- *
- * There is ONE retry policy in this repo and it lives in `@aexhq/contracts`
- * (`HTTP_RETRY_POLICY` / `withHttpRetry` in `http.ts`), shared verbatim by the
- * SDK, the `aex` CLI, and the direct-to-storage asset uploader. This module is
- * the SDK's naming of that policy plus the provider-fault decoding that has no
- * home in the transport.
- *
- * The policy: an eligible request that fails with an HTTP 429 (rate limited), a
- * 500/502/503/504 (server hiccup), a 529 (upstream overloaded), or a network
- * error is retried with BOUNDED exponential backoff + full jitter, honoring the
- * server's `Retry-After` header when present, inside a wall-clock budget.
- * Non-retryable 4xx responses (400/401/403/404/…) fail fast.
- *
- * Safe reads (GET/HEAD/OPTIONS) are eligible directly. Any mutation is eligible
- * only when it carries a stable `Idempotency-Key`; all other mutations get
- * exactly one transport attempt.
- *
- * When retries are exhausted on a rate-limit / overloaded status the wrapper
- * surfaces an {@link AexRateLimitError} — a structured, non-leaky throttle error
- * carrying the parsed `retryAfterMs`, the attempt count, and (when the runtime
- * supplies it) an upstream {@link ProviderFault}. All other exhausted retries
- * fall through to the transport's usual `AexApiError` / network rejection.
- */
-import { isRateLimited, resolveHttpRetryPolicy, withHttpRetry, type ProviderFault } from "./_contracts/index.js";
-export { isRateLimited };
-export { AexRateLimitError } from "./_contracts/index.js";
-export type { ProviderFault } from "./_contracts/index.js";
-/**
- * `RETRYABLE_STATUS` — statuses that are transient and worth retrying for an
- * eligible request. `RATE_LIMIT_STATUS` — the subset the platform / upstream
- * provider uses to say "slow down" (429 rate-limit, 503 unavailable, 529
- * overloaded); when retries for one of these run out the wrapper raises an
- * `AexRateLimitError`. Both are `retry-core.ts`'s sets under the SDK's names.
- */
-export { RATE_LIMIT_HTTP_STATUS as RATE_LIMIT_STATUS, RETRYABLE_HTTP_STATUS as RETRYABLE_STATUS } from "./_contracts/internal.js";
-/**
- * Tunes the built-in retry loop. All fields are optional; omit the whole
- * `retry` option (or pass `retry: false` on the client) to accept the defaults
- * or turn the loop off entirely. The SDK's name for the repo-wide
- * `HttpRetryOptions`.
- */
-export type { HttpRetryOptions as RetryOptions } from "./_contracts/index.js";
-/** Resolve caller options over the one shared policy, clamping to sane bounds. */
-export declare const resolveRetryConfig: typeof resolveHttpRetryPolicy;
-/**
- * Wrap a `FetchLike` with the one shared bounded-retry loop. `retry === false`
- * disables the layer entirely.
- */
-export declare const withRetry: typeof withHttpRetry;
-export type { HttpRetryDeps as RetryDeps } from "./_contracts/index.js";
-export { computeRetryBackoffDelayMs as computeBackoffDelayMs, isRateLimitHttpStatus as isRateLimitStatus, isRetryableHttpStatus as isRetryableStatus, tryParseRetryAfterMs as parseRetryAfterMs } from "./_contracts/internal.js";
-/** True when a {@link ProviderFault} represents a "back off and retry" signal. */
-export declare function isThrottleFault(fault: ProviderFault): boolean;
-/**
- * Best-effort compatibility parse of an unknown provider error. Canonical
- * Session and RUN_ERROR fields are validated by `@aexhq/contracts`; this helper
- * remains tolerant only for callers decoding documented historical raw-provider
- * shapes:
- *
- *   1. The canonical `{ provider?, kind, status?, retryAfterMs?, message? }`
- *      (optionally nested under a `providerFault` key), OR
- *   2. A raw upstream error `{ type: "rate_limit_error" | "overloaded_error"
- *      | ..., message?, retry_after? | retryAfter? }` — `type` maps to `kind`
- *      and `retry_after` (seconds) maps to `retryAfterMs`.
- *
- * Returns `undefined` when the value carries no recognizable fault.
- */
-export declare function parseProviderFault(value: unknown): ProviderFault | undefined;

package/dist/retry.js

@@ -1,155 +0,0 @@
-/**
- * Built-in transport resilience for the aex SDK.
- *
- * There is ONE retry policy in this repo and it lives in `@aexhq/contracts`
- * (`HTTP_RETRY_POLICY` / `withHttpRetry` in `http.ts`), shared verbatim by the
- * SDK, the `aex` CLI, and the direct-to-storage asset uploader. This module is
- * the SDK's naming of that policy plus the provider-fault decoding that has no
- * home in the transport.
- *
- * The policy: an eligible request that fails with an HTTP 429 (rate limited), a
- * 500/502/503/504 (server hiccup), a 529 (upstream overloaded), or a network
- * error is retried with BOUNDED exponential backoff + full jitter, honoring the
- * server's `Retry-After` header when present, inside a wall-clock budget.
- * Non-retryable 4xx responses (400/401/403/404/…) fail fast.
- *
- * Safe reads (GET/HEAD/OPTIONS) are eligible directly. Any mutation is eligible
- * only when it carries a stable `Idempotency-Key`; all other mutations get
- * exactly one transport attempt.
- *
- * When retries are exhausted on a rate-limit / overloaded status the wrapper
- * surfaces an {@link AexRateLimitError} — a structured, non-leaky throttle error
- * carrying the parsed `retryAfterMs`, the attempt count, and (when the runtime
- * supplies it) an upstream {@link ProviderFault}. All other exhausted retries
- * fall through to the transport's usual `AexApiError` / network rejection.
- */
-import { isRateLimited, parseProviderFault as parseCanonicalProviderFault, resolveHttpRetryPolicy, withHttpRetry } from "./_contracts/index.js";
-// The rate-limit guard AND the rate-limit error are SINGLE-SOURCED in
-// `@aexhq/contracts`, so the wire→exception factory (`apiErrorFromResponse`) and
-// the retry policy raise the SAME class recognised by the SAME `isRateLimited` —
-// no split-brain, no subclass mirror.
-export { isRateLimited };
-export { AexRateLimitError } from "./_contracts/index.js";
-/**
- * `RETRYABLE_STATUS` — statuses that are transient and worth retrying for an
- * eligible request. `RATE_LIMIT_STATUS` — the subset the platform / upstream
- * provider uses to say "slow down" (429 rate-limit, 503 unavailable, 529
- * overloaded); when retries for one of these run out the wrapper raises an
- * `AexRateLimitError`. Both are `retry-core.ts`'s sets under the SDK's names.
- */
-export { RATE_LIMIT_HTTP_STATUS as RATE_LIMIT_STATUS, RETRYABLE_HTTP_STATUS as RETRYABLE_STATUS } from "./_contracts/internal.js";
-/** Resolve caller options over the one shared policy, clamping to sane bounds. */
-export const resolveRetryConfig = resolveHttpRetryPolicy;
-/**
- * Wrap a `FetchLike` with the one shared bounded-retry loop. `retry === false`
- * disables the layer entirely.
- */
-export const withRetry = withHttpRetry;
-// The retryable/rate-limit status predicates, the RFC 7231 `Retry-After` parse
-// (integer seconds OR HTTP-date), and the AWS-style full-jitter exponential
-// backoff are all `retry-core.ts`'s. Re-exported under the SDK's names — never
-// re-implemented, which is how the CLI and the SDK drifted in the first place.
-export { computeRetryBackoffDelayMs as computeBackoffDelayMs, isRateLimitHttpStatus as isRateLimitStatus, isRetryableHttpStatus as isRetryableStatus, tryParseRetryAfterMs as parseRetryAfterMs } from "./_contracts/internal.js";
-const THROTTLE_KINDS = new Set([
-    "rate_limit",
-    "overloaded",
-    "quota_exceeded",
-    "unavailable"
-]);
-/** True when a {@link ProviderFault} represents a "back off and retry" signal. */
-export function isThrottleFault(fault) {
-    return THROTTLE_KINDS.has(fault.kind);
-}
-/**
- * Best-effort compatibility parse of an unknown provider error. Canonical
- * Session and RUN_ERROR fields are validated by `@aexhq/contracts`; this helper
- * remains tolerant only for callers decoding documented historical raw-provider
- * shapes:
- *
- *   1. The canonical `{ provider?, kind, status?, retryAfterMs?, message? }`
- *      (optionally nested under a `providerFault` key), OR
- *   2. A raw upstream error `{ type: "rate_limit_error" | "overloaded_error"
- *      | ..., message?, retry_after? | retryAfter? }` — `type` maps to `kind`
- *      and `retry_after` (seconds) maps to `retryAfterMs`.
- *
- * Returns `undefined` when the value carries no recognizable fault.
- */
-export function parseProviderFault(value) {
-    if (value === null || typeof value !== "object")
-        return undefined;
-    const record = value;
-    const nested = record.providerFault ?? record.provider_fault;
-    if (nested !== undefined && nested !== value) {
-        const fromNested = parseProviderFault(nested);
-        if (fromNested)
-            return fromNested;
-    }
-    try {
-        return parseCanonicalProviderFault(record);
-    }
-    catch {
-        // Continue into the deliberately narrow historical raw-provider decoder.
-    }
-    const kind = legacyFaultKind(record.kind ?? record.type ?? record.code);
-    if (kind === undefined)
-        return undefined;
-    const provider = typeof record.provider === "string" ? record.provider : undefined;
-    const status = coerceStatus(record.status ?? record.statusCode ?? record.httpStatus);
-    const retryAfterMs = record.retryAfterMs !== undefined
-        ? coerceRetryDelay(record.retryAfterMs, 1)
-        : record.retry_after_ms !== undefined
-            ? coerceRetryDelay(record.retry_after_ms, 1)
-            : record.retryAfter !== undefined
-                ? coerceRetryDelay(record.retryAfter, 1000)
-                : coerceRetryDelay(record.retry_after, 1000);
-    const message = typeof record.message === "string" ? record.message : undefined;
-    return {
-        kind,
-        ...(provider !== undefined ? { provider } : {}),
-        ...(status !== undefined ? { status } : {}),
-        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
-        ...(message !== undefined ? { message } : {})
-    };
-}
-const LEGACY_FAULT_KINDS = {
-    rate_limit: "rate_limit",
-    rate_limit_error: "rate_limit",
-    overloaded: "overloaded",
-    overloaded_error: "overloaded",
-    quota_exceeded: "quota_exceeded",
-    quota_exceeded_error: "quota_exceeded",
-    insufficient_quota: "quota_exceeded",
-    unavailable: "unavailable",
-    api_error: "unavailable",
-    timeout_error: "unavailable",
-    provider_error: "provider_error",
-    authentication_error: "provider_error",
-    invalid_request_error: "provider_error",
-    "429": "rate_limit",
-    "529": "overloaded"
-};
-function legacyFaultKind(raw) {
-    if (typeof raw !== "string")
-        return undefined;
-    return LEGACY_FAULT_KINDS[raw.trim().toLowerCase()];
-}
-function coerceStatus(raw) {
-    if (typeof raw === "number" && Number.isFinite(raw))
-        return raw;
-    if (typeof raw === "string" && /^\d+$/.test(raw.trim()))
-        return Number(raw.trim());
-    return undefined;
-}
-/** Coerce a numeric delay using the unit declared by its field name. */
-function coerceRetryDelay(raw, multiplier) {
-    const value = typeof raw === "number" && Number.isFinite(raw)
-        ? raw
-        : typeof raw === "string" && /^\d+$/.test(raw.trim())
-            ? Number(raw.trim())
-            : undefined;
-    if (value === undefined || value < 0)
-        return undefined;
-    const milliseconds = value * multiplier;
-    return Number.isSafeInteger(milliseconds) ? milliseconds : undefined;
-}
-//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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"}

package/dist/secret.d.ts

@@ -1,65 +0,0 @@
-import { SecretString } from "./_contracts/index.js";
-/**
- * Non-secret wire shape for one `secretEnv` entry. A workspace ref carries the
- * handle (hashable, resolved server-side); an ephemeral secret carries only a
- * value-free placeholder — the value is split into the vaulted secrets channel
- * and excluded from the idempotency hash.
- */
-export type SecretEnvSubmissionEntry = {
-    readonly ref: string;
-} | {
-    readonly ephemeral: true;
-};
-/**
- * A secret with the SAME lifecycle semantic as `File` / `Instructions`:
- * EPHEMERAL per-session by default, or a reference to a persisted workspace
- * secret created explicitly through `aex.workspace.secrets.set(...)`.
- *
- *   - `Secret.value(v)` — EPHEMERAL per-session: the value is vaulted when the session is created and
- *     excluded from the idempotency hash; only a `{ ephemeral: true }`
- *     placeholder rides the (hashed) submission. Deleted when the session finishes.
- *     Clean, no workspace dependency. ≙ `File.fromBytes(...)` (a draft).
- *   - `Secret.ref(handle)` — WORKSPACE: only the handle rides the submission;
- *     the value is resolved server-side from the workspace secret store. No
- *     value ever travels.
- *
- * The SDK splits each `Secret` BEFORE the wire payload is built (exactly how
- * `McpServer` splits `headers` into `secrets.mcpServers`): the env-var name keys
- * `submission.secretEnv[name] = toSubmissionEntry()`, and for ephemeral values
- * `secrets.envSecrets[name] = toSecretValue()`.
- */
-export declare class Secret {
-    #private;
-    readonly kind: "value" | "ref";
-    /** Workspace handle (ref kind only); `undefined` for ephemeral values. */
-    readonly handle: string | undefined;
-    /** Internal constructor. Use `Secret.value(...)` or `Secret.ref(...)`. */
-    private constructor();
-    /** Ephemeral per-session value. Vaulted when the session is created; never in the spec/hash; gone at terminal. */
-    static value(value: string | SecretString): Secret;
-    /** Reference a workspace secret by handle; resolved server-side when the session is created. */
-    static ref(handle: string): Secret;
-    /** Non-secret wire entry for `submission.secretEnv[<envName>]`. */
-    toSubmissionEntry(): SecretEnvSubmissionEntry;
-    /** Raw value for the vaulted `secrets.envSecrets[<envName>]` (ephemeral only); `undefined` for refs. */
-    toSecretValue(): string | undefined;
-    /** Redacted — never prints the value. */
-    toString(): string;
-    /** Redacted — never serialises the value. */
-    toJSON(): unknown;
-}
-/**
- * Split `secretEnv: Record<envName, Secret>` into the value-free declarations
- * (`submission.secretEnv`) and the per-session vaulted values
- * (`secrets.envSecrets`). Secret declarations ride
- * the hashed submission, ephemeral values ride the secrets channel
- * (hash-excluded). Refs contribute only a declaration.
- *
- * Throws on a non-`Secret` value or an env var name that won't match the
- * platform's `SECRET_ENV_NAME_PATTERN`, so the caller gets a precise error at
- * the call site instead of an HTTP 400 a round-trip later.
- */
-export declare function splitSecretEnv(secretEnv: Readonly<Record<string, Secret>> | undefined): {
-    declarations: Record<string, SecretEnvSubmissionEntry>;
-    values: Record<string, string>;
-};

package/dist/secret.js

@@ -1,110 +0,0 @@
-import { SECRET_ENV_NAME_PATTERN, SECRET_HANDLE_PATTERN, SecretString } from "./_contracts/index.js";
-/**
- * A secret with the SAME lifecycle semantic as `File` / `Instructions`:
- * EPHEMERAL per-session by default, or a reference to a persisted workspace
- * secret created explicitly through `aex.workspace.secrets.set(...)`.
- *
- *   - `Secret.value(v)` — EPHEMERAL per-session: the value is vaulted when the session is created and
- *     excluded from the idempotency hash; only a `{ ephemeral: true }`
- *     placeholder rides the (hashed) submission. Deleted when the session finishes.
- *     Clean, no workspace dependency. ≙ `File.fromBytes(...)` (a draft).
- *   - `Secret.ref(handle)` — WORKSPACE: only the handle rides the submission;
- *     the value is resolved server-side from the workspace secret store. No
- *     value ever travels.
- *
- * The SDK splits each `Secret` BEFORE the wire payload is built (exactly how
- * `McpServer` splits `headers` into `secrets.mcpServers`): the env-var name keys
- * `submission.secretEnv[name] = toSubmissionEntry()`, and for ephemeral values
- * `secrets.envSecrets[name] = toSecretValue()`.
- */
-export class Secret {
-    kind;
-    /** Workspace handle (ref kind only); `undefined` for ephemeral values. */
-    handle;
-    #value;
-    /** Internal constructor. Use `Secret.value(...)` or `Secret.ref(...)`. */
-    constructor(args) {
-        if (!args || typeof args !== "object") {
-            throw new Error("Secret: args is required");
-        }
-        if (args.kind === "ref") {
-            if (typeof args.handle !== "string" || !SECRET_HANDLE_PATTERN.test(args.handle)) {
-                throw new Error(`Secret.ref: handle must match ${SECRET_HANDLE_PATTERN.source}`);
-            }
-            this.kind = "ref";
-            this.handle = args.handle;
-            this.#value = undefined;
-            return;
-        }
-        this.kind = "value";
-        this.handle = undefined;
-        this.#value = args.value;
-    }
-    /** Ephemeral per-session value. Vaulted when the session is created; never in the spec/hash; gone at terminal. */
-    static value(value) {
-        const wrapped = value instanceof SecretString ? value : new SecretString(value, "secret");
-        if (!wrapped.unwrap()) {
-            throw new Error("Secret.value: value must be a non-empty string");
-        }
-        return new Secret({ kind: "value", value: wrapped });
-    }
-    /** Reference a workspace secret by handle; resolved server-side when the session is created. */
-    static ref(handle) {
-        return new Secret({ kind: "ref", handle });
-    }
-    /** Non-secret wire entry for `submission.secretEnv[<envName>]`. */
-    toSubmissionEntry() {
-        if (this.kind === "ref") {
-            return { ref: this.handle };
-        }
-        return { ephemeral: true };
-    }
-    /** Raw value for the vaulted `secrets.envSecrets[<envName>]` (ephemeral only); `undefined` for refs. */
-    toSecretValue() {
-        if (this.kind === "ref") {
-            return undefined;
-        }
-        return this.#value?.unwrap();
-    }
-    /** Redacted — never prints the value. */
-    toString() {
-        return this.kind === "ref" ? `Secret.ref(${this.handle})` : "Secret.value([REDACTED])";
-    }
-    /** Redacted — never serialises the value. */
-    toJSON() {
-        return this.kind === "ref" ? { kind: "ref", handle: this.handle } : { kind: "value", value: "[REDACTED]" };
-    }
-}
-/**
- * Split `secretEnv: Record<envName, Secret>` into the value-free declarations
- * (`submission.secretEnv`) and the per-session vaulted values
- * (`secrets.envSecrets`). Secret declarations ride
- * the hashed submission, ephemeral values ride the secrets channel
- * (hash-excluded). Refs contribute only a declaration.
- *
- * Throws on a non-`Secret` value or an env var name that won't match the
- * platform's `SECRET_ENV_NAME_PATTERN`, so the caller gets a precise error at
- * the call site instead of an HTTP 400 a round-trip later.
- */
-export function splitSecretEnv(secretEnv) {
-    const declarations = {};
-    const values = {};
-    if (!secretEnv) {
-        return { declarations, values };
-    }
-    for (const [envName, secret] of Object.entries(secretEnv)) {
-        if (!(secret instanceof Secret)) {
-            throw new TypeError(`secretEnv[${envName}] must be a Secret built via Secret.value(...) or Secret.ref(...)`);
-        }
-        if (!SECRET_ENV_NAME_PATTERN.test(envName)) {
-            throw new Error(`secretEnv key ${JSON.stringify(envName)} must be a valid env var name matching ${SECRET_ENV_NAME_PATTERN.source}`);
-        }
-        declarations[envName] = secret.toSubmissionEntry();
-        const value = secret.toSecretValue();
-        if (value !== undefined) {
-            values[envName] = value;
-        }
-    }
-    return { declarations, values };
-}
-//# sourceMappingURL=secret.js.map

package/dist/secret.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"secret.js","sourceRoot":"","sources":["../src/secret.ts"],"names":[],"mappings":"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"}

package/dist/session-validate.d.ts

@@ -1,100 +0,0 @@
-import { SessionConfigValidationError, type ApprovalGate, type PlatformNetworking, type PlatformPackageInput, type ResponseFormat, type SessionRuntime, type SubmissionAssets, type WorkspaceFileRecord, type WorkspaceInstructionRecord, type WorkspaceSkillRecord, type WorkspaceToolRecord } from "./_contracts/index.js";
-import type { SessionCreateOptions, SessionEnvironmentOptions, SessionInput, SessionOverrides, SessionSendOptions, SessionStartOptions, StartSessionOptions } from "./client-types.js";
-type ExactKeys<Shape, Keys extends PropertyKey> = [
-    Exclude<keyof Shape, Keys>
-] extends [never] ? [Exclude<Keys, keyof Shape>] extends [never] ? true : false : false;
-/** Package-private compile-time proof that a runtime tuple's key set equals the public shape. */
-export type ExactKeySet<Shape, Keys extends readonly PropertyKey[]> = ExactKeys<Shape, Keys[number]>;
-type Assert<T extends true> = T;
-declare const SESSION_CREATE_KEYS: readonly ["model", "system", "assets", "mcpServers", "fileCapture", "builtinTools", "outputMode", "responseFormat", "approvalGate", "metadata", "idempotencyKey", "environment", "runtime", "overrides", "webhook"];
-type SessionCreateKeysAreExact = Assert<ExactKeySet<SessionCreateOptions, typeof SESSION_CREATE_KEYS>>;
-declare const SESSION_START_KEYS: readonly ["model", "system", "assets", "mcpServers", "fileCapture", "builtinTools", "outputMode", "responseFormat", "approvalGate", "metadata", "idempotencyKey", "environment", "runtime", "overrides", "webhook", "message", "deleteAfter", "messageIdempotencyKey", "stream"];
-type SessionStartKeysAreExact = Assert<ExactKeySet<SessionStartOptions, typeof SESSION_START_KEYS>>;
-declare const START_CONTROL_KEYS: readonly ["timeoutMs", "webSocketFactory", "idleTimeoutMs", "pingIntervalMs", "throwOnFailure"];
-type StartControlKeysAreExact = Assert<ExactKeySet<StartSessionOptions, typeof START_CONTROL_KEYS>>;
-declare const SESSION_SEND_KEYS: readonly ["webSocketFactory", "idleTimeoutMs", "pingIntervalMs", "idempotencyKey"];
-type SessionSendKeysAreExact = Assert<ExactKeySet<SessionSendOptions, typeof SESSION_SEND_KEYS>>;
-type SessionStreamOptions = Omit<SessionSendOptions, "idempotencyKey">;
-declare const SESSION_STREAM_KEYS: readonly ["webSocketFactory", "idleTimeoutMs", "pingIntervalMs"];
-type SessionStreamKeysAreExact = Assert<ExactKeySet<SessionStreamOptions, typeof SESSION_STREAM_KEYS>>;
-declare const SESSION_OVERRIDE_KEYS: readonly ["idleTtl", "timeout", "maxSpendUsd", "maxTurns"];
-type SessionOverrideKeysAreExact = Assert<ExactKeySet<SessionOverrides, typeof SESSION_OVERRIDE_KEYS>>;
-declare const SESSION_RUNTIME_KEYS: readonly ["kind", "size"];
-type SessionRuntimeKeysAreExact = Assert<ExactKeySet<SessionRuntime, typeof SESSION_RUNTIME_KEYS>>;
-type FileCaptureOptions = NonNullable<SessionCreateOptions["fileCapture"]>;
-declare const FILE_CAPTURE_KEYS: readonly ["allowedDirs", "deniedDirs", "captureTimeoutMs", "maxFileBytes", "maxTotalBytes", "maxFiles"];
-type FileCaptureKeysAreExact = Assert<ExactKeySet<FileCaptureOptions, typeof FILE_CAPTURE_KEYS>>;
-type SessionWebhookOptions = NonNullable<SessionCreateOptions["webhook"]>;
-declare const SESSION_WEBHOOK_KEYS: readonly ["url"];
-type SessionWebhookKeysAreExact = Assert<ExactKeySet<SessionWebhookOptions, typeof SESSION_WEBHOOK_KEYS>>;
-declare const SESSION_ENVIRONMENT_KEYS: readonly ["networking", "packages", "variables", "secrets"];
-type SessionEnvironmentKeysAreExact = Assert<ExactKeySet<SessionEnvironmentOptions, typeof SESSION_ENVIRONMENT_KEYS>>;
-declare const PLATFORM_NETWORKING_KEYS: readonly ["mode", "allowedHosts"];
-type PlatformNetworkingKeysAreExact = Assert<ExactKeySet<PlatformNetworking, typeof PLATFORM_NETWORKING_KEYS>>;
-declare const PLATFORM_PACKAGE_INPUT_KEYS: readonly ["name", "version"];
-type PlatformPackageInputKeysAreExact = Assert<ExactKeySet<PlatformPackageInput, typeof PLATFORM_PACKAGE_INPUT_KEYS>>;
-type TextResponseFormat = Extract<ResponseFormat, {
-    readonly kind: "text";
-}>;
-declare const TEXT_RESPONSE_FORMAT_KEYS: readonly ["kind"];
-type TextResponseFormatKeysAreExact = Assert<ExactKeySet<TextResponseFormat, typeof TEXT_RESPONSE_FORMAT_KEYS>>;
-type JsonSchemaResponseFormat = Extract<ResponseFormat, {
-    readonly kind: "json_schema";
-}>;
-declare const JSON_SCHEMA_RESPONSE_FORMAT_KEYS: readonly ["kind", "schema", "strict", "name"];
-type JsonSchemaResponseFormatKeysAreExact = Assert<ExactKeySet<JsonSchemaResponseFormat, typeof JSON_SCHEMA_RESPONSE_FORMAT_KEYS>>;
-declare const APPROVAL_GATE_KEYS: readonly ["tools"];
-type ApprovalGateKeysAreExact = Assert<ExactKeySet<ApprovalGate, typeof APPROVAL_GATE_KEYS>>;
-declare const ASSET_CATEGORY_KEYS: readonly ["files", "skills", "tools", "instructions"];
-type AssetCategoryKeysAreExact = Assert<ExactKeySet<SubmissionAssets, typeof ASSET_CATEGORY_KEYS>>;
-declare const ASSET_ITEM_KEYS: {
-    readonly files: readonly ["kind", "resourceId", "version", "assetId", "contentHash", "createdAt", "updatedAt", "sizeBytes", "contentType", "name", "mountPath"];
-    readonly skills: readonly ["kind", "resourceId", "version", "assetId", "contentHash", "createdAt", "updatedAt", "sizeBytes", "contentType", "name", "description"];
-    readonly tools: readonly ["kind", "resourceId", "version", "assetId", "contentHash", "createdAt", "updatedAt", "sizeBytes", "contentType", "name", "description", "input_schema", "entry"];
-    readonly instructions: readonly ["kind", "resourceId", "version", "assetId", "contentHash", "createdAt", "updatedAt", "sizeBytes", "contentType", "name"];
-};
-type AssetFileKeysAreExact = Assert<ExactKeySet<WorkspaceFileRecord, typeof ASSET_ITEM_KEYS.files>>;
-type AssetSkillKeysAreExact = Assert<ExactKeySet<WorkspaceSkillRecord, typeof ASSET_ITEM_KEYS.skills>>;
-type AssetToolKeysAreExact = Assert<ExactKeySet<WorkspaceToolRecord, typeof ASSET_ITEM_KEYS.tools>>;
-type AssetInstructionKeysAreExact = Assert<ExactKeySet<WorkspaceInstructionRecord, typeof ASSET_ITEM_KEYS.instructions>>;
-export type SessionOptionKeyAssertions = readonly [
-    SessionCreateKeysAreExact,
-    SessionStartKeysAreExact,
-    StartControlKeysAreExact,
-    SessionSendKeysAreExact,
-    SessionStreamKeysAreExact,
-    SessionOverrideKeysAreExact,
-    SessionRuntimeKeysAreExact,
-    FileCaptureKeysAreExact,
-    SessionWebhookKeysAreExact,
-    SessionEnvironmentKeysAreExact,
-    PlatformNetworkingKeysAreExact,
-    PlatformPackageInputKeysAreExact,
-    TextResponseFormatKeysAreExact,
-    JsonSchemaResponseFormatKeysAreExact,
-    ApprovalGateKeysAreExact,
-    AssetCategoryKeysAreExact,
-    AssetFileKeysAreExact,
-    AssetSkillKeysAreExact,
-    AssetToolKeysAreExact,
-    AssetInstructionKeysAreExact
-];
-export type SessionConfigDiagnosticPolicy = {
-    readonly kind: "scalar";
-    readonly rejectedValues: readonly unknown[];
-} | {
-    readonly kind: "redacted";
-};
-/** Package-private catch-and-translate owner for canonical session validators. */
-export declare function validatedSessionConfig<T>(surface: string, field: string, message: string, validate: () => T, policy: SessionConfigDiagnosticPolicy): T;
-/**
- * Package-private factory for SDK validation errors. `details.field` is the only
- * stable machine-readable payload; messages are human guidance and may change.
- */
-export declare function configError(surface: string, field: string, message: string, cause?: Error): SessionConfigValidationError;
-export declare function normaliseSessionInput(input: SessionInput, surface: string, field: string): SessionInput;
-export declare function assertSupportedSessionFields(options: SessionCreateOptions, surface: string, allowStartFields: boolean): void;
-export declare function assertSupportedSessionSendOptions(options: unknown, surface: string, allowIdempotencyKey?: boolean): void;
-export declare function assertStartSessionOptions(options: unknown, surface: string): void;
-export declare function assertAllowedObjectFields(value: unknown, surface: string, field: string, allowed: readonly string[]): Record<string, unknown> | undefined;
-export {};