@cadraos/sdk 0.3.14-p46.3 → 0.3.14

package/dist/chat/index.d.cts

@@ -874,6 +874,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). */
@@ -1863,6 +1873,12 @@ 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
+     * may take up to 60 s while every other call keeps the 30 s default).
+     */
+    timeoutMs?: number;
 }
 /**
  * HTTP Client class
@@ -1894,6 +1910,7 @@ declare class HttpClient {
     post<T>(path: string, body?: unknown, options?: {
         idempotencyKey?: string;
         skipRetry?: boolean;
+        timeoutMs?: number;
     }): Promise<T>;
     /**
      * PATCH request
@@ -2521,6 +2538,133 @@ interface RemoteAgentExecuteResponse {
     streamUrl: string;
 }
 
+/**
+ * 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;
+}
+
 /**
  * Base Resource API
  *
@@ -2549,6 +2693,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
@@ -3828,6 +3973,11 @@ interface KanbanCard {
     configVersion?: number;
     /** Arbitrary shared context carried across transitions. */
     sharedContext?: Record<string, unknown>;
+    /**
+     * p46 (P46-002): the card's id in an external host (a Jira issue key).
+     * Absent on native / crm / yobo cards.
+     */
+    externalRef?: string;
     /**
      * Execution UUID of the card's current/last run, if any.
      *
@@ -3890,6 +4040,18 @@ interface CreateCardInput {
      * in the lifecycle's initial lane.
      */
     lane?: string;
+    /**
+     * p46 (P46-002): the card's id in an EXTERNAL host (a Jira issue key, e.g.
+     * `CAD-231`). Optional. When set, a card is created at most ONCE per
+     * `(boardConfigUuid, externalRef)`: a repeat create returns the existing card
+     * and dispatches nothing. Hosts that don't store it simply ignore it.
+     */
+    externalRef?: string;
+    /**
+     * p46 (P46-002): opaque host facts stored with the card (Jira `statusId`,
+     * `mover`, `detached`, …). Passed through to `adapter.createCard` untouched.
+     */
+    externalMeta?: Record<string, unknown>;
 }
 /**
  * Input for transitioning a card to another lane.
@@ -4168,6 +4330,65 @@ 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);
+ * ```
+ */
+
+/**
+ * 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
  *
@@ -4312,6 +4533,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
      *

package/dist/chat/index.d.ts

@@ -874,6 +874,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). */
@@ -1863,6 +1873,12 @@ 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
+     * may take up to 60 s while every other call keeps the 30 s default).
+     */
+    timeoutMs?: number;
 }
 /**
  * HTTP Client class
@@ -1894,6 +1910,7 @@ declare class HttpClient {
     post<T>(path: string, body?: unknown, options?: {
         idempotencyKey?: string;
         skipRetry?: boolean;
+        timeoutMs?: number;
     }): Promise<T>;
     /**
      * PATCH request
@@ -2521,6 +2538,133 @@ interface RemoteAgentExecuteResponse {
     streamUrl: string;
 }
 
+/**
+ * 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;
+}
+
 /**
  * Base Resource API
  *
@@ -2549,6 +2693,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
@@ -3828,6 +3973,11 @@ interface KanbanCard {
     configVersion?: number;
     /** Arbitrary shared context carried across transitions. */
     sharedContext?: Record<string, unknown>;
+    /**
+     * p46 (P46-002): the card's id in an external host (a Jira issue key).
+     * Absent on native / crm / yobo cards.
+     */
+    externalRef?: string;
     /**
      * Execution UUID of the card's current/last run, if any.
      *
@@ -3890,6 +4040,18 @@ interface CreateCardInput {
      * in the lifecycle's initial lane.
      */
     lane?: string;
+    /**
+     * p46 (P46-002): the card's id in an EXTERNAL host (a Jira issue key, e.g.
+     * `CAD-231`). Optional. When set, a card is created at most ONCE per
+     * `(boardConfigUuid, externalRef)`: a repeat create returns the existing card
+     * and dispatches nothing. Hosts that don't store it simply ignore it.
+     */
+    externalRef?: string;
+    /**
+     * p46 (P46-002): opaque host facts stored with the card (Jira `statusId`,
+     * `mover`, `detached`, …). Passed through to `adapter.createCard` untouched.
+     */
+    externalMeta?: Record<string, unknown>;
 }
 /**
  * Input for transitioning a card to another lane.
@@ -4168,6 +4330,65 @@ 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);
+ * ```
+ */
+
+/**
+ * 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
  *
@@ -4312,6 +4533,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
      *