@cadraos/sdk 0.3.14-p46.4 → 0.3.15

package/dist/index.d.ts

@@ -62,6 +62,13 @@ interface RequestOptions {
     skipRetry?: boolean;
     /** Idempotency key */
     idempotencyKey?: string;
+    /**
+     * Per-request timeout in milliseconds. Overrides the client-wide
+     * `config.timeout` for this call only (p93 AIF-010: a paid AI-function run
+     * waits for the server's route ceiling while every other call keeps the
+     * 30 s default).
+     */
+    timeoutMs?: number;
 }
 /**
  * HTTP Client class
@@ -71,6 +78,8 @@ declare class HttpClient {
     private tokenRefreshAttempts;
     private readonly maxTokenRefreshAttempts;
     constructor(config: HttpClientConfig);
+    /** The client-wide request timeout (ms) this client was configured with. */
+    get timeoutMs(): number;
     /**
      * Get authorization header value
      */
@@ -93,6 +102,7 @@ declare class HttpClient {
     post<T>(path: string, body?: unknown, options?: {
         idempotencyKey?: string;
         skipRetry?: boolean;
+        timeoutMs?: number;
     }): Promise<T>;
     /**
      * PATCH request
@@ -1146,6 +1156,16 @@ interface ToolResultEvent {
     result: unknown;
     /** Duration in milliseconds */
     durationMs: number;
+    /**
+     * CAD-243: true when the tool call FAILED (the producer stamps
+     * `isError: true` + `status: 'failed'` on a thrown tool call). Absent on
+     * older producers — consumers then fall back to the result shape.
+     */
+    isError?: boolean;
+    /** CAD-243: producer verdict, `'failed'` for a failed call. */
+    status?: string;
+    /** CAD-243: error text for a failed call. */
+    error?: string;
     /** See {@link ToolCallEvent.forwardedFrom} */
     forwardedFrom?: string;
     /** See {@link ToolCallEvent.sourceExecutionId} (CAD-87 S1-001). */
@@ -1529,6 +1549,140 @@ interface StreamingConfig {
     sseRetryIntervalMs?: number;
 }
 
+/**
+ * AI function types (p93 — specs §4 run contract, D27 discovery, §6.5 run reads).
+ *
+ * An AI function is a published prompt in the Cadra Prompts library that makes
+ * ONE direct AI-provider call (never an agent). Callers reference it by its
+ * `functionKey` (unique per org), by prompt uuid, or — for platform features —
+ * by slot key.
+ */
+/** Output kind of an AI function. */
+type AiFunctionOutputKind = 'text' | 'json' | 'image';
+/** Parameter (prompt variable) types — specs D10 + D26d. */
+type AiFunctionParameterType = 'string' | 'text' | 'number' | 'boolean' | 'enum' | 'image';
+/** A value passed for one parameter. `image` parameters take an artifact uuid (string). */
+type AiFunctionVariableValue = string | number | boolean;
+/** Parameters (variables) for one run, keyed by parameter name. */
+type AiFunctionVariables = Record<string, AiFunctionVariableValue>;
+/** How a run names its function (§4). */
+type AiFunctionRef = {
+    slot: string;
+} | {
+    functionKey: string;
+} | {
+    promptUuid: string;
+};
+/** One declared parameter of a function's live (golden) version — D27a. */
+interface AiFunctionParameter {
+    name: string;
+    type: AiFunctionParameterType;
+    required: boolean;
+    defaultValue?: AiFunctionVariableValue;
+    maxLength?: number;
+    options?: string[];
+    description?: string;
+}
+/**
+ * The discovery "index" entry for one callable function — D27a. Built from the
+ * golden version snapshot; never carries prompt or system text.
+ */
+interface AiFunctionDescriptor {
+    functionKey: string;
+    title: string;
+    description?: string | null;
+    outputKind: AiFunctionOutputKind;
+    /** The live (golden) version number. */
+    liveVersion: number;
+    parameters: AiFunctionParameter[];
+    /** JSON schema of the output, for `json` functions. */
+    outputSchema?: Record<string, unknown> | null;
+}
+/** Who paid for a run (D4). */
+type AiFunctionBilledTo = 'own_key' | 'credits' | 'platform_funded';
+/** Runtime params a slot may accept per run (D26d3). */
+interface AiFunctionRuntimeParams {
+    aspect_ratio?: string;
+    image_size?: string;
+}
+/** Options for the object form `run(ref, { variables, … })`. */
+interface AiFunctionRunOptions {
+    /** Parameters for this run (sent as `variables`). */
+    variables: AiFunctionVariables;
+    /** Pin a published version number (D3d). Skips the client-side check. */
+    version?: number;
+    /** Idempotency key (uuid). Generated when omitted (D15). */
+    idempotencyKey?: string;
+    /** Slot runtime params (D26d3). */
+    params?: AiFunctionRuntimeParams;
+    /** `false` skips the client-side parameter check (D27c). Default true. */
+    validate?: boolean;
+}
+/** Options for the shorthand `run('function_key', parameters, opts)`. */
+type AiFunctionRunShorthandOptions = Omit<AiFunctionRunOptions, 'variables'>;
+/** Image produced by an `image` function. Over HTTP only `url` (presigned, 1 h) is set. */
+interface AiFunctionImage {
+    mimeType: string;
+    url?: string;
+    bytes?: Uint8Array;
+}
+/** Output of a run, by kind (§4). `TOutput` types `json`. */
+type AiFunctionOutput<TOutput = unknown> = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'json';
+    json: TOutput;
+} | {
+    type: 'image';
+    images: AiFunctionImage[];
+};
+/** Token and billing usage of a run (§4). */
+interface AiFunctionUsage {
+    promptTokens: number;
+    completionTokens: number;
+    imageCount: number;
+    billedTo: AiFunctionBilledTo;
+}
+/** Result of a successful run (§4). */
+interface AiFunctionRunResult<TOutput = unknown> {
+    /** = the run's execution uuid (usage-ledger executionUuid). */
+    executionId: string;
+    functionUuid: string;
+    version: number;
+    output: AiFunctionOutput<TOutput>;
+    usage: AiFunctionUsage;
+    latencyMs: number;
+}
+/** Run status as reported by run reads (D12; `abandoned` is computed on read). */
+type AiFunctionRunStatus = 'running' | 'succeeded' | 'failed_provider' | 'failed_timeout' | 'refused_billing' | 'failed_output' | 'failed_delivery' | 'abandoned';
+/** Safe projection of one of the caller org's own runs (§6.5). */
+interface AiFunctionRun {
+    executionId: string;
+    ref: {
+        slot?: string;
+        functionKey?: string;
+        promptUuid?: string;
+    };
+    version: number | null;
+    status: AiFunctionRunStatus;
+    errorCode: string | null;
+    promptTokens: number | null;
+    completionTokens: number | null;
+    imageCount: number | null;
+    latencyMs: number | null;
+    billedTo: AiFunctionBilledTo | null;
+    createdAt: string;
+    finishedAt: string | null;
+}
+/** Why a parameter failed the client-side check (D27c). */
+type AiFunctionParameterIssueCode = 'missing' | 'type' | 'option' | 'too_long' | 'unknown';
+/** One client-side parameter problem (D27c). */
+interface AiFunctionParameterIssue {
+    name: string;
+    code: AiFunctionParameterIssueCode;
+}
+
 /**
  * Base Resource API
  *
@@ -1557,6 +1711,7 @@ declare abstract class BaseResourceAPI {
     protected httpPost<T>(path: string, body?: unknown, options?: {
         idempotencyKey?: string;
         skipRetry?: boolean;
+        timeoutMs?: number;
     }): Promise<T>;
     /**
      * HTTP PATCH request helper
@@ -3254,6 +3409,81 @@ declare class RemoteRunnersAPI extends BaseResourceAPI {
     list(options?: RemoteRunnerListOptions): Promise<PaginatedResponse<RemoteRunner>>;
 }
 
+/**
+ * AI Functions API (p93 AIF-010 — specs §9, D27).
+ *
+ * @example
+ * ```typescript
+ * // Discover what the org can call, and with which parameters
+ * const functions = await client.aiFunctions.list();
+ * const fn = await client.aiFunctions.get('summarise_ticket');
+ *
+ * // Call it — parameters are checked against the live version before sending
+ * const result = await client.aiFunctions.run('summarise_ticket', { ticket_text: '…' });
+ * if (result.output.type === 'text') console.log(result.output.text);
+ * ```
+ */
+
+/**
+ * How long the client waits for a paid run. It tracks cadra-web
+ * `AI_FUNCTION_ROUTE_MAX_MS` (300 s, the Vercel `maxDuration` of the run
+ * routes) plus 10 s, so the server always answers first — with the result or
+ * with its own `failed_timeout` — and the client never abandons a run the
+ * server is still finishing. A larger client-wide `timeout` wins.
+ * (Was 60 s, from the old p93 D6 route budget.)
+ */
+declare const AI_FUNCTION_RUN_TIMEOUT_MS = 310000;
+/** Descriptors used by the client-side check are cached per client for 60 s (D27c). */
+declare const AI_FUNCTION_DESCRIPTOR_TTL_MS = 60000;
+/**
+ * Check `variables` against a descriptor's parameters (D27c). Returns the issues,
+ * in parameter order, then unknown names. Empty array = OK.
+ */
+declare function checkAiFunctionParameters(parameters: AiFunctionParameter[], variables: AiFunctionVariables): AiFunctionParameterIssue[];
+/**
+ * AI Functions API
+ */
+declare class AiFunctionsAPI extends BaseResourceAPI {
+    private readonly descriptorCache;
+    constructor(http: HttpClient);
+    /**
+     * List the functions this org can call — the index (D27a). Each entry carries
+     * the live version's typed parameters; never prompt text.
+     */
+    list(): Promise<AiFunctionDescriptor[]>;
+    /**
+     * Get one function's descriptor by key (D27a).
+     * `NotFoundError` (`FUNCTION_NOT_FOUND`) / `ConflictError` (`FUNCTION_NOT_PUBLISHED`).
+     */
+    get(functionKey: string): Promise<AiFunctionDescriptor>;
+    /**
+     * Read one of this org's own runs (safe projection, §6.5).
+     */
+    getRun(executionId: string): Promise<AiFunctionRun>;
+    /** Forget cached descriptors (one key, or all). */
+    clearDescriptorCache(functionKey?: string): void;
+    /**
+     * Run an AI function — one paid provider call.
+     *
+     * - `run('function_key', parameters, opts?)` — shorthand for `{ functionKey }`.
+     * - `run({ functionKey | promptUuid | slot }, { variables, version?, idempotencyKey?, params?, validate? })`.
+     *
+     * For a `functionKey` ref without a pinned `version`, parameters are checked
+     * against the live version first (D27c); a problem throws
+     * `AiFunctionParameterError` and NO run request is sent. Paid runs are never
+     * auto-retried; an idempotency key is generated when omitted.
+     *
+     * @throws AiFunctionParameterError — client-side check failed (nothing sent)
+     * @throws AiFunctionDuplicateError — 409 `DUPLICATE_REQUEST`
+     * @throws AiFunctionChargedError — the run was metered but its output failed (`details.charged`)
+     */
+    run<TOutput = unknown>(functionKey: string, parameters: AiFunctionVariables, opts?: AiFunctionRunShorthandOptions): Promise<AiFunctionRunResult<TOutput>>;
+    run<TOutput = unknown>(ref: AiFunctionRef, options: AiFunctionRunOptions): Promise<AiFunctionRunResult<TOutput>>;
+    private cacheDescriptor;
+    private getCachedDescriptor;
+    private mapRunError;
+}
+
 /**
  * Cadra Client
  *
@@ -3398,6 +3628,10 @@ declare class CadraClient {
      * Remote runner operations (list)
      */
     readonly remoteRunners: RemoteRunnersAPI;
+    /**
+     * AI function operations (list, get, run, getRun) — p93
+     */
+    readonly aiFunctions: AiFunctionsAPI;
     /**
      * Create a new AI SaaS client
      *
@@ -3449,6 +3683,14 @@ declare class CadraError extends Error {
     readonly details?: Record<string, unknown>;
     /** Request ID from server (for debugging) */
     readonly requestId?: string;
+    /**
+     * The server's own `error.code` exactly as sent on the wire (e.g.
+     * `FUNCTION_NOT_PUBLISHED`, `DUPLICATE_REQUEST`, `VARIABLE_TYPE`).
+     * Populated by `parseApiError` for EVERY status. `code` keeps its historic
+     * per-class values (`conflict`, `server_error`, `validation_error`, …) for
+     * compatibility; branch on `serverCode` when you need the precise reason.
+     */
+    serverCode?: string;
     constructor(message: string, code: string, status: number, details?: Record<string, unknown>, requestId?: string);
 }
 /**
@@ -3525,4 +3767,40 @@ declare class NetworkError extends CadraError {
     constructor(message?: string, details?: Record<string, unknown>);
 }
 
-export { CadraClient as AISaaSClient, type CadraClientOptions as AISaaSClientOptions, CadraError as AISaaSError, type Agent, type AgentConfig, type AgentConfigUpdateInput, type AgentExecution, type AgentListOptions, type AgentStatus, type AgentType, type AgentUpdateInput, type Artifact, type ArtifactDownloadOptions, type ArtifactListOptions, type ArtifactType, type ArtifactUploadInput, type AttachmentUploadUrlInput, type AttachmentUploadUrlResponse, AuthenticationError, AuthorizationError, CadraClient, type CadraClientOptions, CadraError, type CollectImagesOptions, type CompleteEvent, ConflictError, type ConnectionChangeEvent, type DelegationCompletedEvent, type DelegationStartedEvent, type ErrorEvent, type ExecuteInput, type ExecuteOptions, type ExecuteResponse, type ExecuteToolDirectRequest, type ExecuteToolDirectResponse, type ExecutionLog, type ExecutionStatus, type ExecutionStreamController, type ExecutionStreamControllerOptions, type ExtractContext, type ImageData, type ImageEvent, type JSONSchema, type ListOptions, NetworkError, NotFoundError, type PaginatedResponse, type PaginationInfo, type PausedEvent, type PlanEvent, type ProgressEvent, RateLimitError, type RemoteAgent, type RemoteAgentCreateInput, type RemoteAgentExecuteResponse, type RemoteAgentExecutionTargetKind, type RemoteAgentListOptions, type RemoteAgentStatus, type RemoteAgentUpdateInput, type RemoteAgentVisibility, type RemoteRunner, type RemoteRunnerListOptions, type SendMessageInput, ServerError, type Session, type SessionArtifact, type SessionArtifactListOptions, type SessionArtifactType, type SessionArtifactVariantType, type SessionCreateInput, type SessionHistory, type SessionListOptions, type SessionMessage, type SignedUrlResponse, type Skill, type SkillDetails, type SkillExecuteInput, type SkillExecution, type SkillListOptions, type SkillTool, type SkillUpdateInput, type SkillVariable, type StartedEvent, type StreamController, type StreamEventMap, type StreamImagesResult, type TeamMemberRef, type TextDeltaEvent, TimeoutError, type TokenUsage, type Tool, type ToolCallEvent, type ToolConfigUpdateInput, type ToolExecution, type ToolListOptions, type ToolResultEvent, type ToolUpdateInput, type ToolValidationResult, ValidationError, collectImagesFromStream, deriveImagesFromToolCalls, extractImagesFromExecutionOutput, extractImagesFromResult };
+/**
+ * AI function errors (p93 AIF-010, specs §9 + D27c).
+ *
+ * All extend the existing hierarchy so `instanceof CadraError` (and, where it
+ * applies, `ConflictError` / `ValidationError`) keeps working.
+ */
+
+/**
+ * 409 `DUPLICATE_REQUEST`: a run with the same idempotency key already exists.
+ * No provider call was made. A retry after `abandoned` or a failure needs a NEW key.
+ */
+declare class AiFunctionDuplicateError extends ConflictError {
+    /** The existing run's execution id. */
+    readonly executionId?: string;
+    /** The existing run's status (`running`, a terminal status, or `abandoned`). */
+    readonly runStatus?: string;
+    constructor(message: string, details?: Record<string, unknown>, requestId?: string);
+}
+/**
+ * The provider answered 2xx and the run WAS metered, but the output then failed
+ * (`OUTPUT_INVALID`, `DELIVERY_FAILED` — `details.charged: true`). Never retry
+ * automatically: a retry is a second paid call.
+ */
+declare class AiFunctionChargedError extends CadraError {
+    constructor(source: CadraError);
+}
+/**
+ * The client-side parameter check failed (D27c). No run request was sent.
+ * Also a `ValidationError`, with one `errors[]` entry per issue.
+ */
+declare class AiFunctionParameterError extends ValidationError {
+    readonly functionKey: string;
+    readonly issues: AiFunctionParameterIssue[];
+    constructor(functionKey: string, issues: AiFunctionParameterIssue[]);
+}
+
+export { CadraClient as AISaaSClient, type CadraClientOptions as AISaaSClientOptions, CadraError as AISaaSError, AI_FUNCTION_DESCRIPTOR_TTL_MS, AI_FUNCTION_RUN_TIMEOUT_MS, type Agent, type AgentConfig, type AgentConfigUpdateInput, type AgentExecution, type AgentListOptions, type AgentStatus, type AgentType, type AgentUpdateInput, type AiFunctionBilledTo, AiFunctionChargedError, type AiFunctionDescriptor, AiFunctionDuplicateError, type AiFunctionImage, type AiFunctionOutput, type AiFunctionOutputKind, type AiFunctionParameter, AiFunctionParameterError, type AiFunctionParameterIssue, type AiFunctionParameterIssueCode, type AiFunctionParameterType, type AiFunctionRef, type AiFunctionRun, type AiFunctionRunOptions, type AiFunctionRunResult, type AiFunctionRunShorthandOptions, type AiFunctionRunStatus, type AiFunctionRuntimeParams, type AiFunctionUsage, type AiFunctionVariableValue, type AiFunctionVariables, AiFunctionsAPI, type Artifact, type ArtifactDownloadOptions, type ArtifactListOptions, type ArtifactType, type ArtifactUploadInput, type AttachmentUploadUrlInput, type AttachmentUploadUrlResponse, AuthenticationError, AuthorizationError, CadraClient, type CadraClientOptions, CadraError, type CollectImagesOptions, type CompleteEvent, ConflictError, type ConnectionChangeEvent, type DelegationCompletedEvent, type DelegationStartedEvent, type ErrorEvent, type ExecuteInput, type ExecuteOptions, type ExecuteResponse, type ExecuteToolDirectRequest, type ExecuteToolDirectResponse, type ExecutionLog, type ExecutionStatus, type ExecutionStreamController, type ExecutionStreamControllerOptions, type ExtractContext, type ImageData, type ImageEvent, type JSONSchema, type ListOptions, NetworkError, NotFoundError, type PaginatedResponse, type PaginationInfo, type PausedEvent, type PlanEvent, type ProgressEvent, RateLimitError, type RemoteAgent, type RemoteAgentCreateInput, type RemoteAgentExecuteResponse, type RemoteAgentExecutionTargetKind, type RemoteAgentListOptions, type RemoteAgentStatus, type RemoteAgentUpdateInput, type RemoteAgentVisibility, type RemoteRunner, type RemoteRunnerListOptions, type SendMessageInput, ServerError, type Session, type SessionArtifact, type SessionArtifactListOptions, type SessionArtifactType, type SessionArtifactVariantType, type SessionCreateInput, type SessionHistory, type SessionListOptions, type SessionMessage, type SignedUrlResponse, type Skill, type SkillDetails, type SkillExecuteInput, type SkillExecution, type SkillListOptions, type SkillTool, type SkillUpdateInput, type SkillVariable, type StartedEvent, type StreamController, type StreamEventMap, type StreamImagesResult, type TeamMemberRef, type TextDeltaEvent, TimeoutError, type TokenUsage, type Tool, type ToolCallEvent, type ToolConfigUpdateInput, type ToolExecution, type ToolListOptions, type ToolResultEvent, type ToolUpdateInput, type ToolValidationResult, ValidationError, checkAiFunctionParameters, collectImagesFromStream, deriveImagesFromToolCalls, extractImagesFromExecutionOutput, extractImagesFromResult };

package/dist/index.js

@@ -61,6 +61,14 @@ var CadraError = class extends Error {
   details;
   /** Request ID from server (for debugging) */
   requestId;
+  /**
+   * The server's own `error.code` exactly as sent on the wire (e.g.
+   * `FUNCTION_NOT_PUBLISHED`, `DUPLICATE_REQUEST`, `VARIABLE_TYPE`).
+   * Populated by `parseApiError` for EVERY status. `code` keeps its historic
+   * per-class values (`conflict`, `server_error`, `validation_error`, …) for
+   * compatibility; branch on `serverCode` when you need the precise reason.
+   */
+  serverCode;
   constructor(message, code, status, details, requestId) {
     super(message);
     this.name = "CadraError";
@@ -138,6 +146,12 @@ function parseApiError(status, body, requestId) {
   const message = errorBody?.error?.message ?? "An error occurred";
   const code = errorBody?.error?.code ?? "unknown_error";
   const details = errorBody?.error?.details;
+  const serverCode = typeof errorBody?.error?.code === "string" ? errorBody.error.code : void 0;
+  const error = buildApiError(status, message, code, details, requestId);
+  if (serverCode !== void 0) error.serverCode = serverCode;
+  return error;
+}
+function buildApiError(status, message, code, details, requestId) {
   switch (status) {
     case 400:
     case 422: {
@@ -173,6 +187,42 @@ function parseApiError(status, body, requestId) {
   }
 }
 
+// src/errors/ai-function-errors.ts
+var AiFunctionDuplicateError = class extends ConflictError {
+  /** The existing run's execution id. */
+  executionId;
+  /** The existing run's status (`running`, a terminal status, or `abandoned`). */
+  runStatus;
+  constructor(message, details, requestId) {
+    super(message, details, requestId);
+    this.name = "AiFunctionDuplicateError";
+    this.serverCode = "DUPLICATE_REQUEST";
+    this.executionId = typeof details?.executionId === "string" ? details.executionId : void 0;
+    this.runStatus = typeof details?.status === "string" ? details.status : void 0;
+  }
+};
+var AiFunctionChargedError = class extends CadraError {
+  constructor(source) {
+    super(source.message, source.code, source.status, source.details, source.requestId);
+    this.name = "AiFunctionChargedError";
+    this.serverCode = source.serverCode;
+  }
+};
+var AiFunctionParameterError = class extends ValidationError {
+  functionKey;
+  issues;
+  constructor(functionKey, issues) {
+    super(
+      `Invalid parameters for AI function "${functionKey}": ` + issues.map((i) => `${i.name} (${i.code})`).join(", "),
+      issues.map((i) => ({ field: i.name, message: i.code })),
+      { functionKey, issues }
+    );
+    this.name = "AiFunctionParameterError";
+    this.functionKey = functionKey;
+    this.issues = issues;
+  }
+};
+
 // src/utils/retry.ts
 var DEFAULT_RETRY_CONFIG = {
   maxRetries: 3,
@@ -237,6 +287,10 @@ var HttpClient = class {
   constructor(config) {
     this.config = config;
   }
+  /** The client-wide request timeout (ms) this client was configured with. */
+  get timeoutMs() {
+    return this.config.timeout;
+  }
   /**
    * Get authorization header value
    */
@@ -291,7 +345,8 @@ var HttpClient = class {
         headers["Idempotency-Key"] = options.idempotencyKey;
       }
       const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+      const timeoutMs = options.timeoutMs ?? this.config.timeout;
+      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
       try {
         const doFetch = this.config.fetch ?? fetch;
         const response = await doFetch(url, {
@@ -327,7 +382,7 @@ var HttpClient = class {
       } catch (error) {
         clearTimeout(timeoutId);
         if (error instanceof Error && error.name === "AbortError") {
-          throw new TimeoutError(`Request timed out after ${this.config.timeout}ms`);
+          throw new TimeoutError(`Request timed out after ${options.timeoutMs ?? this.config.timeout}ms`);
         }
         if (error instanceof TypeError && error.message.includes("fetch")) {
           throw new NetworkError(`Network error: ${error.message}`);
@@ -359,7 +414,8 @@ var HttpClient = class {
       path,
       body,
       idempotencyKey: options?.idempotencyKey,
-      skipRetry: options?.skipRetry
+      skipRetry: options?.skipRetry,
+      timeoutMs: options?.timeoutMs
     });
   }
   /**
@@ -1118,6 +1174,10 @@ var ExecutionStreamControllerImpl = class {
           toolName,
           result: data.result,
           durationMs: data.durationMs ?? 0,
+          // CAD-243: pass the producer's failure verdict through.
+          ...data.isError === true ? { isError: true } : {},
+          ...typeof data.status === "string" ? { status: data.status } : {},
+          ...typeof data.error === "string" ? { error: data.error } : {},
           forwardedFrom: event.data._forwardedFrom,
           // CAD-87 S1-001 EventIdentity → (execId, seq) reducer dedup (S1-003).
           sourceExecutionId: data.sourceExecutionId ?? data.executionId,
@@ -3356,6 +3416,156 @@ var RemoteRunnersAPI = class extends BaseResourceAPI {
   }
 };
 
+// src/resources/ai-functions.ts
+var AI_FUNCTION_RUN_TIMEOUT_MS = 31e4;
+var AI_FUNCTION_DESCRIPTOR_TTL_MS = 6e4;
+function checkAiFunctionParameters(parameters, variables) {
+  const issues = [];
+  const declared = /* @__PURE__ */ new Set();
+  for (const p of parameters) {
+    declared.add(p.name);
+    const has = Object.prototype.hasOwnProperty.call(variables, p.name);
+    const value = has ? variables[p.name] : void 0;
+    if (value === void 0 || value === null) {
+      if (p.required) issues.push({ name: p.name, code: "missing" });
+      continue;
+    }
+    switch (p.type) {
+      case "number":
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+          issues.push({ name: p.name, code: "type" });
+        }
+        break;
+      case "boolean":
+        if (typeof value !== "boolean") issues.push({ name: p.name, code: "type" });
+        break;
+      case "enum":
+        if (typeof value !== "string") issues.push({ name: p.name, code: "type" });
+        else if (p.options && !p.options.includes(value)) {
+          issues.push({ name: p.name, code: "option" });
+        }
+        break;
+      case "string":
+      case "text":
+        if (typeof value !== "string") issues.push({ name: p.name, code: "type" });
+        else if (typeof p.maxLength === "number" && value.length > p.maxLength) {
+          issues.push({ name: p.name, code: "too_long" });
+        }
+        break;
+      case "image":
+        if (typeof value !== "string") issues.push({ name: p.name, code: "type" });
+        break;
+    }
+  }
+  for (const name of Object.keys(variables)) {
+    if (!declared.has(name)) issues.push({ name, code: "unknown" });
+  }
+  return issues;
+}
+var AiFunctionsAPI = class extends BaseResourceAPI {
+  descriptorCache = /* @__PURE__ */ new Map();
+  constructor(http) {
+    super(http, "/api/v1/ai-functions");
+  }
+  /**
+   * List the functions this org can call — the index (D27a). Each entry carries
+   * the live version's typed parameters; never prompt text.
+   */
+  async list() {
+    const data = await this.httpGet("");
+    const functions = Array.isArray(data) ? data : data?.functions ?? [];
+    for (const d of functions) this.cacheDescriptor(d);
+    return functions;
+  }
+  /**
+   * Get one function's descriptor by key (D27a).
+   * `NotFoundError` (`FUNCTION_NOT_FOUND`) / `ConflictError` (`FUNCTION_NOT_PUBLISHED`).
+   */
+  async get(functionKey) {
+    const data = await this.httpGet(
+      `/${encodeURIComponent(functionKey)}`
+    );
+    const descriptor = data && typeof data === "object" && "function" in data && !("functionKey" in data) ? data.function : data;
+    this.cacheDescriptor(descriptor, functionKey);
+    return descriptor;
+  }
+  /**
+   * Read one of this org's own runs (safe projection, §6.5).
+   */
+  async getRun(executionId) {
+    return this.httpGet(`/runs/${encodeURIComponent(executionId)}`);
+  }
+  /** Forget cached descriptors (one key, or all). */
+  clearDescriptorCache(functionKey) {
+    if (functionKey) this.descriptorCache.delete(functionKey);
+    else this.descriptorCache.clear();
+  }
+  async run(refOrKey, parametersOrOptions, shorthandOpts) {
+    let ref;
+    let options;
+    if (typeof refOrKey === "string") {
+      ref = { functionKey: refOrKey };
+      options = { ...shorthandOpts ?? {}, variables: parametersOrOptions };
+    } else {
+      ref = refOrKey;
+      options = parametersOrOptions;
+    }
+    const variables = options.variables ?? {};
+    const functionKey = "functionKey" in ref ? ref.functionKey : void 0;
+    const shouldCheck = functionKey !== void 0 && options.version === void 0 && options.validate !== false;
+    if (shouldCheck) {
+      const descriptor = await this.getCachedDescriptor(functionKey);
+      const issues = checkAiFunctionParameters(descriptor.parameters, variables);
+      if (issues.length > 0) {
+        throw new AiFunctionParameterError(functionKey, issues);
+      }
+    }
+    const body = {
+      ref,
+      variables,
+      version: options.version,
+      idempotencyKey: options.idempotencyKey ?? generateExecutionId(),
+      params: options.params
+    };
+    try {
+      return await this.httpPost("/run", body, {
+        skipRetry: true,
+        timeoutMs: Math.max(AI_FUNCTION_RUN_TIMEOUT_MS, this.http.timeoutMs ?? 0)
+      });
+    } catch (error) {
+      throw this.mapRunError(error, functionKey);
+    }
+  }
+  // ── internals ──────────────────────────────────────────────────────────────
+  cacheDescriptor(descriptor, key) {
+    if (!descriptor || typeof descriptor !== "object") return;
+    const cacheKey = key ?? descriptor.functionKey;
+    if (!cacheKey) return;
+    this.descriptorCache.set(cacheKey, {
+      descriptor,
+      expiresAt: Date.now() + AI_FUNCTION_DESCRIPTOR_TTL_MS
+    });
+  }
+  async getCachedDescriptor(functionKey) {
+    const hit = this.descriptorCache.get(functionKey);
+    if (hit && hit.expiresAt > Date.now()) return hit.descriptor;
+    return this.get(functionKey);
+  }
+  mapRunError(error, functionKey) {
+    if (!(error instanceof CadraError)) return error;
+    if (error.serverCode === "DUPLICATE_REQUEST") {
+      return new AiFunctionDuplicateError(error.message, error.details, error.requestId);
+    }
+    if (error.details?.charged === true) {
+      return new AiFunctionChargedError(error);
+    }
+    if (functionKey && error.serverCode?.startsWith("VARIABLE_")) {
+      this.descriptorCache.delete(functionKey);
+    }
+    return error;
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.cadraos.com";
 var DEFAULT_TIMEOUT = 3e4;
@@ -3402,6 +3612,10 @@ var CadraClient = class {
    * Remote runner operations (list)
    */
   remoteRunners;
+  /**
+   * AI function operations (list, get, run, getRun) — p93
+   */
+  aiFunctions;
   /**
    * Create a new AI SaaS client
    *
@@ -3491,6 +3705,7 @@ var CadraClient = class {
     this.kanban = new KanbanAPI(this.httpClient, getStreamConfig);
     this.remoteAgents = new RemoteAgentsAPI(this.httpClient, getStreamConfig);
     this.remoteRunners = new RemoteRunnersAPI(this.httpClient);
+    this.aiFunctions = new AiFunctionsAPI(this.httpClient);
   }
   /**
    * Validate client options
@@ -3513,6 +3728,6 @@ var CadraClient = class {
   }
 };
 
-export { CadraClient as AISaaSClient, CadraError as AISaaSError, AuthenticationError, AuthorizationError, CadraClient, CadraError, ConflictError, NetworkError, NotFoundError, RateLimitError, ServerError, TimeoutError, ValidationError, collectImagesFromStream, deriveImagesFromToolCalls, extractImagesFromExecutionOutput, extractImagesFromResult };
+export { CadraClient as AISaaSClient, CadraError as AISaaSError, AI_FUNCTION_DESCRIPTOR_TTL_MS, AI_FUNCTION_RUN_TIMEOUT_MS, AiFunctionChargedError, AiFunctionDuplicateError, AiFunctionParameterError, AiFunctionsAPI, AuthenticationError, AuthorizationError, CadraClient, CadraError, ConflictError, NetworkError, NotFoundError, RateLimitError, ServerError, TimeoutError, ValidationError, checkAiFunctionParameters, collectImagesFromStream, deriveImagesFromToolCalls, extractImagesFromExecutionOutput, extractImagesFromResult };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map