@narrative.io/data-collaboration-sdk-ts 2.101.0 → 2.102.0

package/build/agents/index.d.ts

@@ -0,0 +1,63 @@
+import { BaseApi } from "../base-api";
+import type { ConversationId, ConversationResponse, CreateConversationRequest, CreateRunRequest, ListMessagesResponse, RunId, RunResponse } from "./types";
+export * from "./types";
+/**
+ * @module AgentsApi
+ * @description Agent Conversations: long-lived conversations with pinned system
+ *   prompt + defaults, asynchronous runs that may pause for caller-declared
+ *   tool outputs, and a versioned delta-cursor message stream.
+ *
+ * @see https://docs.narrative.io/reference/architecture/agent-conversations
+ *
+ * @extends BaseApi
+ */
+export declare class AgentsApi extends BaseApi {
+    /**
+     * Create an agent conversation. `system_prompt` and `defaults.{tools,mcp_servers}`
+     * are pinned at creation; everything else in `defaults` is overridable per-run.
+     */
+    createAgentConversation(request: CreateConversationRequest): Promise<ConversationResponse>;
+    /**
+     * Read a conversation's metadata + current `version`. Always re-read this
+     * immediately before starting a run — `version` is the compare-and-swap
+     * token for `expected_version` and a stale value yields 409.
+     */
+    getAgentConversation(conversationId: ConversationId): Promise<ConversationResponse>;
+    /**
+     * Delta-read conversation messages with `sequence_no > since`. Use the
+     * returned `current_version` as the next call's `since` for gap-free reads.
+     */
+    listAgentConversationMessages(conversationId: ConversationId, options?: {
+        since?: number;
+    }): Promise<ListMessagesResponse>;
+    /**
+     * Start a new run on the conversation. Returns immediately with
+     * `status: "pending"` — poll {@link getAgentRun} until terminal.
+     *
+     * - Generate a fresh UUID for `client_op_id` per logical request (it's the
+     *   idempotency key; reusing one is only safe as a retry).
+     * - Set `expected_version` to the value just read from
+     *   {@link getAgentConversation} — mismatches return 409.
+     */
+    createAgentRun(conversationId: ConversationId, request: CreateRunRequest): Promise<RunResponse>;
+    /**
+     * Read a run's current state. Terminal states: `completed`,
+     * `requires_action`, `failed`. Stop polling on any of them.
+     */
+    getAgentRun(runId: RunId): Promise<RunResponse>;
+    /**
+     * Convenience: poll {@link getAgentRun} until terminal. Caller is responsible
+     * for selecting a reasonable backoff; defaults to 1.5s fixed interval with a
+     * 2-minute ceiling.
+     *
+     * Returns the terminal run. Throws on `failed` only if `throwOnFailed` is
+     * true; otherwise the caller inspects `run.status === "failed"`.
+     */
+    waitForAgentRun(runId: RunId, options?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+        onTick?: (run: RunResponse) => void;
+        throwOnFailed?: boolean;
+    }): Promise<RunResponse>;
+}

package/build/agents/index.js

@@ -0,0 +1,92 @@
+import { BaseApi } from "../base-api";
+export * from "./types";
+const conversationsResource = "agents/conversations";
+const runsResource = "agents/runs";
+/**
+ * @module AgentsApi
+ * @description Agent Conversations: long-lived conversations with pinned system
+ *   prompt + defaults, asynchronous runs that may pause for caller-declared
+ *   tool outputs, and a versioned delta-cursor message stream.
+ *
+ * @see https://docs.narrative.io/reference/architecture/agent-conversations
+ *
+ * @extends BaseApi
+ */
+export class AgentsApi extends BaseApi {
+    // -------------------- Conversations --------------------
+    /**
+     * Create an agent conversation. `system_prompt` and `defaults.{tools,mcp_servers}`
+     * are pinned at creation; everything else in `defaults` is overridable per-run.
+     */
+    async createAgentConversation(request) {
+        return await this.post(conversationsResource, request);
+    }
+    /**
+     * Read a conversation's metadata + current `version`. Always re-read this
+     * immediately before starting a run — `version` is the compare-and-swap
+     * token for `expected_version` and a stale value yields 409.
+     */
+    async getAgentConversation(conversationId) {
+        return await this.get(`${conversationsResource}/${conversationId}`);
+    }
+    /**
+     * Delta-read conversation messages with `sequence_no > since`. Use the
+     * returned `current_version` as the next call's `since` for gap-free reads.
+     */
+    async listAgentConversationMessages(conversationId, options) {
+        return await this.get(`${conversationsResource}/${conversationId}/messages`, options?.since !== undefined ? { since: options.since } : undefined);
+    }
+    // -------------------- Runs --------------------
+    /**
+     * Start a new run on the conversation. Returns immediately with
+     * `status: "pending"` — poll {@link getAgentRun} until terminal.
+     *
+     * - Generate a fresh UUID for `client_op_id` per logical request (it's the
+     *   idempotency key; reusing one is only safe as a retry).
+     * - Set `expected_version` to the value just read from
+     *   {@link getAgentConversation} — mismatches return 409.
+     */
+    async createAgentRun(conversationId, request) {
+        return await this.post(`${conversationsResource}/${conversationId}/runs`, request);
+    }
+    /**
+     * Read a run's current state. Terminal states: `completed`,
+     * `requires_action`, `failed`. Stop polling on any of them.
+     */
+    async getAgentRun(runId) {
+        return await this.get(`${runsResource}/${runId}`);
+    }
+    /**
+     * Convenience: poll {@link getAgentRun} until terminal. Caller is responsible
+     * for selecting a reasonable backoff; defaults to 1.5s fixed interval with a
+     * 2-minute ceiling.
+     *
+     * Returns the terminal run. Throws on `failed` only if `throwOnFailed` is
+     * true; otherwise the caller inspects `run.status === "failed"`.
+     */
+    async waitForAgentRun(runId, options = {}) {
+        const interval = options.intervalMs ?? 1500;
+        const timeout = options.timeoutMs ?? 120_000;
+        const deadline = Date.now() + timeout;
+        // terminal predicate kept local to avoid an extra import in consumers
+        const terminal = (s) => s === "completed" || s === "requires_action" || s === "failed";
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            if (options.signal?.aborted) {
+                throw new Error("waitForAgentRun aborted");
+            }
+            const run = await this.getAgentRun(runId);
+            options.onTick?.(run);
+            if (terminal(run.status)) {
+                if (options.throwOnFailed && run.status === "failed") {
+                    throw Object.assign(new Error(run.error?.message ?? "Agent run failed"), { run });
+                }
+                return run;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`waitForAgentRun timed out after ${timeout}ms`);
+            }
+            await new Promise((r) => setTimeout(r, interval));
+        }
+    }
+}

package/build/agents/types.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Agent Conversations API — types.
+ *
+ * Mirrors `/agents/conversations` and `/agents/runs` on the Narrative Data
+ * Collaboration Platform (RFC 7807 errors; OpenAI-Assistants-shaped semantics).
+ *
+ * Two tool dimensions:
+ *  - `mcp_servers[]` — server-side, resolved by the platform via MCP. Model sees
+ *    each tool as `{alias}-{name}`.
+ *  - `tools[]` — caller-declared. Dash-free names. When called, the run pauses
+ *    at `requires_action`; resume by posting a follow-up run with
+ *    `payload.kind: "tool_outputs"`.
+ */
+export type ConversationId = string;
+export type RunId = string;
+export type ClientOpId = string;
+export type ConversationVersion = number;
+export type ToolUseId = string;
+export type AgentModel = "anthropic.claude-haiku-4.5" | "anthropic.claude-sonnet-4.5" | "anthropic.claude-sonnet-4.6" | "anthropic.claude-opus-4.5" | "anthropic.claude-opus-4.6" | "openai.gpt-oss-120b" | "openai.gpt-4.1" | "openai.o4-mini" | (string & {});
+export type ExecutionCluster = "shared" | "dedicated";
+/** Subset of JSON Schema Draft 2020-12 accepted by Bedrock structured output. */
+export type JsonSchemaObject = Record<string, unknown>;
+export interface McpServerConfig {
+    /** 1–8 char `[a-zA-Z][a-zA-Z0-9]{0,7}` — namespace prefix for the server's tools. */
+    alias: string;
+    url: string;
+    description?: string;
+}
+export interface ToolSpec {
+    /** Caller-declared tools must NOT contain a dash. MCP tools' bare name. */
+    name: string;
+    description: string;
+    input_schema: JsonSchemaObject;
+    /** Defaults to true. Leave true in production. */
+    strict?: boolean;
+}
+export interface ConversationDefaults {
+    model: AgentModel;
+    data_plane_id: string;
+    execution_cluster: ExecutionCluster;
+    compute_pool_id?: string;
+    max_iterations?: number;
+    max_tokens?: number;
+    temperature?: number;
+    output_format_schema?: JsonSchemaObject;
+    mcp_servers?: McpServerConfig[];
+    tools?: ToolSpec[];
+}
+export interface CreateConversationRequest {
+    name?: string;
+    system_prompt?: string;
+    defaults: ConversationDefaults;
+}
+export interface ConversationResponse {
+    id: ConversationId;
+    company_id: number;
+    user_id: number;
+    name: string | null;
+    system_prompt: string | null;
+    defaults: ConversationDefaults;
+    version: ConversationVersion;
+    created_at: string;
+    updated_at: string;
+}
+export type RunStatus = "pending" | "running" | "completed" | "requires_action" | "failed";
+export interface UserMessagePayload {
+    kind: "user_message";
+    text: string;
+}
+export interface ToolOutput {
+    tool_use_id: ToolUseId;
+    /** Plain text. Serialize JSON results before sending. */
+    content: string;
+    is_error?: boolean;
+}
+export interface ToolOutputsPayload {
+    kind: "tool_outputs";
+    outputs: ToolOutput[];
+}
+export type RunPayload = UserMessagePayload | ToolOutputsPayload;
+export type ToolChoice = {
+    kind: "auto";
+} | {
+    kind: "any";
+} | {
+    kind: "specific_tool";
+    name: string;
+    /** Set when pinning an MCP-resolved tool; omit for caller-declared. */
+    mcp_alias?: string | null;
+};
+/** Sparse override applied per-run; lists replace wholesale. */
+export interface RunConfigOverride {
+    model?: AgentModel;
+    data_plane_id?: string;
+    execution_cluster?: ExecutionCluster;
+    compute_pool_id?: string;
+    max_iterations?: number;
+    max_tokens?: number;
+    temperature?: number;
+    output_format_schema?: JsonSchemaObject;
+    mcp_servers?: McpServerConfig[];
+    tools?: ToolSpec[];
+}
+export interface CreateRunRequest {
+    client_op_id: ClientOpId;
+    expected_version: ConversationVersion;
+    payload: RunPayload;
+    tool_choice?: ToolChoice;
+    config_override?: RunConfigOverride;
+}
+export interface PendingToolCall {
+    tool_use_id: ToolUseId;
+    /** Wire-form name. For caller-declared tools, dash-free. */
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface AgentInferenceUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+export interface RunError {
+    /** Stable incident code, e.g. "AgentLoopMaxIterationsExceeded". */
+    type: string;
+    message: string;
+    title?: string;
+    docs_url?: string;
+}
+export interface RunResponse {
+    id: RunId;
+    conversation_id: ConversationId;
+    company_id: number;
+    user_id: number;
+    client_op_id: ClientOpId;
+    status: RunStatus;
+    tool_choice?: ToolChoice;
+    effective_config: ConversationDefaults;
+    iterations_used?: number | null;
+    usage?: AgentInferenceUsage | null;
+    submitted_inference_job_ids: string[];
+    pending_tool_calls: PendingToolCall[];
+    final_text?: string | null;
+    error?: RunError | null;
+    started_at: string;
+    completed_at?: string | null;
+}
+export type AgentMessageRole = "user" | "assistant" | "tool";
+export interface TextContentBlock {
+    type: "text";
+    text: string;
+}
+export interface ToolUseContentBlock {
+    type: "tool_use";
+    tool_use_id: ToolUseId;
+    /** Fully-aliased wire name (`{alias}-{tool_name}` for MCP, bare for caller-declared). */
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface ToolResultContentBlock {
+    type: "tool_result";
+    tool_use_id: ToolUseId;
+    content: ContentBlock[];
+    is_error: boolean;
+}
+export type ContentBlock = TextContentBlock | ToolUseContentBlock | ToolResultContentBlock;
+export interface MessageDto {
+    id: string;
+    sequence_no: number;
+    role: AgentMessageRole;
+    content_blocks: ContentBlock[];
+    run_id: RunId;
+    created_at: string;
+}
+export interface ListMessagesResponse {
+    current_version: ConversationVersion;
+    messages: MessageDto[];
+}
+export interface AgentRfcError {
+    type?: string | null;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    log_id: string;
+    debug?: Record<string, unknown> | null;
+}
+export declare const TERMINAL_RUN_STATUSES: ReadonlyArray<RunStatus>;
+export declare function isTerminalRunStatus(status: RunStatus): boolean;

package/build/agents/types.js

@@ -0,0 +1,22 @@
+/**
+ * Agent Conversations API — types.
+ *
+ * Mirrors `/agents/conversations` and `/agents/runs` on the Narrative Data
+ * Collaboration Platform (RFC 7807 errors; OpenAI-Assistants-shaped semantics).
+ *
+ * Two tool dimensions:
+ *  - `mcp_servers[]` — server-side, resolved by the platform via MCP. Model sees
+ *    each tool as `{alias}-{name}`.
+ *  - `tools[]` — caller-declared. Dash-free names. When called, the run pauses
+ *    at `requires_action`; resume by posting a follow-up run with
+ *    `payload.kind: "tool_outputs"`.
+ */
+// Terminal states helper
+export const TERMINAL_RUN_STATUSES = [
+    "completed",
+    "requires_action",
+    "failed",
+];
+export function isTerminalRunStatus(status) {
+    return TERMINAL_RUN_STATUSES.includes(status);
+}

package/build/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./access-rules/";
 export * from "./access-tokens";
 export { resources } from "./access-tokens/types";
+export * from "./agents";
 export type { App } from "./apps";
 export * from "./attributes";
 export * from "./authentication";
@@ -55,6 +56,7 @@ export * from "./workflows";
 export * from "./workflows/types";
 import { AccessRulesApi } from "./access-rules/";
 import { AccessTokensApi } from "./access-tokens";
+import { AgentsApi } from "./agents";
 import { AppsApi } from "./apps";
 import { AttributeApi, AttributeApiV2 } from "./attributes";
 import { AuthenticationApi } from "./authentication";
@@ -87,6 +89,6 @@ import { WhoAmIApi } from "./whoami";
 import { WorkflowsApi } from "./workflows";
 declare class NarrativeApi extends BaseApi {
 }
-interface NarrativeApi extends BaseApi, HealthCheckApi, AccessTokensApi, DataPlaneApi, DatasetApi, RosettaStoneApi, AttributeApi, AttributeApiV2, PingApi, CompanyInfoApi, InstallationsApi, ConnectionsApi, UploadsApi, ResourceApi, NqlApi, DataStreamsApi, ForecastApi, ContractsApi, AuthenticationApi, MappingsApi, AccessRulesApi, AppsApi, SubscriptionsApi, JobsApi, QueriesApi, ViewsApi, ModelsApi, ModelTrainingApi, ModelInferenceApi, EncryptionMaterialApi, WhoAmIApi, WorkflowsApi, ComputePoolsApi {
+interface NarrativeApi extends BaseApi, HealthCheckApi, AccessTokensApi, DataPlaneApi, DatasetApi, RosettaStoneApi, AttributeApi, AttributeApiV2, PingApi, CompanyInfoApi, InstallationsApi, ConnectionsApi, UploadsApi, ResourceApi, NqlApi, DataStreamsApi, ForecastApi, ContractsApi, AuthenticationApi, MappingsApi, AccessRulesApi, AppsApi, SubscriptionsApi, JobsApi, QueriesApi, ViewsApi, ModelsApi, ModelTrainingApi, ModelInferenceApi, EncryptionMaterialApi, WhoAmIApi, WorkflowsApi, ComputePoolsApi, AgentsApi {
 }
 export { NarrativeApi };

package/build/index.js

@@ -2,6 +2,7 @@
 export * from "./access-rules/";
 export * from "./access-tokens";
 export { resources } from "./access-tokens/types";
+export * from "./agents";
 export * from "./attributes";
 export * from "./authentication";
 export * from "./base-api";
@@ -55,6 +56,7 @@ export * from "./workflows";
 export * from "./workflows/types";
 import { AccessRulesApi } from "./access-rules/";
 import { AccessTokensApi } from "./access-tokens";
+import { AgentsApi } from "./agents";
 import { AppsApi } from "./apps";
 import { AttributeApi, AttributeApiV2 } from "./attributes";
 import { AuthenticationApi } from "./authentication";
@@ -123,5 +125,6 @@ applyMixins(NarrativeApi, [
     WhoAmIApi,
     WorkflowsApi,
     ComputePoolsApi,
+    AgentsApi,
 ]);
 export { NarrativeApi };

package/build/nql/types.d.ts

@@ -287,11 +287,11 @@ export declare const NqlObj: z.ZodObject<{
             CALENDAR_MONTH: "CALENDAR_MONTH";
         }>;
     }, z.core.$strip>;
-    sort: z.ZodUndefined;
-    group: z.ZodUndefined;
-    having: z.ZodUndefined;
-    offset: z.ZodUndefined;
-    join: z.ZodUndefined;
+    sort: z.ZodOptional<z.ZodUndefined>;
+    group: z.ZodOptional<z.ZodUndefined>;
+    having: z.ZodOptional<z.ZodUndefined>;
+    offset: z.ZodOptional<z.ZodUndefined>;
+    join: z.ZodOptional<z.ZodUndefined>;
 }, z.core.$strip>;
 export type Nql = z.infer<typeof NqlObj>;
 export interface RelatedJob {

package/build/nql/types.js

@@ -120,9 +120,24 @@ export const NqlObj = z.object({
     from: NqlTableObject.array(),
     where: NqlWhereObj,
     limit: NqlBudgetObj,
-    sort: z.undefined().describe("Sort is not currently supported in NQL"),
-    group: z.undefined().describe("Group is not currently supported in NQL"),
-    having: z.undefined().describe("Having is not currently supported in NQL"),
-    offset: z.undefined().describe("Offset is not currently supported in NQL"),
-    join: z.undefined().describe("Join is not currently supported in NQL"),
+    sort: z
+        .undefined()
+        .describe("Sort is not currently supported in NQL")
+        .optional(),
+    group: z
+        .undefined()
+        .describe("Group is not currently supported in NQL")
+        .optional(),
+    having: z
+        .undefined()
+        .describe("Having is not currently supported in NQL")
+        .optional(),
+    offset: z
+        .undefined()
+        .describe("Offset is not currently supported in NQL")
+        .optional(),
+    join: z
+        .undefined()
+        .describe("Join is not currently supported in NQL")
+        .optional(),
 });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/data-collaboration-sdk-ts",
-	"version": "2.101.0",
+	"version": "2.102.0",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",
@@ -26,21 +26,21 @@
 	"license": "ISC",
 	"devDependencies": {
 		"@babel/core": "7.29.0",
-		"@babel/preset-env": "7.29.2",
+		"@babel/preset-env": "7.29.5",
 		"@babel/preset-typescript": "7.28.5",
-		"@biomejs/biome": "2.4.13",
-		"@commitlint/cli": "20.5.2",
-		"@commitlint/config-conventional": "20.5.0",
+		"@biomejs/biome": "2.4.15",
+		"@commitlint/cli": "21.0.1",
+		"@commitlint/config-conventional": "21.0.1",
 		"@types/jest": "30.0.0",
-		"babel-jest": "30.3.0",
-		"jest": "30.3.0",
+		"babel-jest": "30.4.1",
+		"jest": "30.4.2",
 		"lefthook": "2.1.6",
 		"ts-jest": "29.4.9"
 	},
 	"dependencies": {
 		"mande": "2.0.9",
-		"zod": "4.3.6",
-		"bignumber.js": "11.0.0"
+		"zod": "4.4.3",
+		"bignumber.js": "11.1.1"
 	},
 	"overrides": {
 		"semver@<7.5.2": "7.5.2"