@narrative.io/data-collaboration-sdk-ts 4.0.0 → 4.2.0

package/build/agents/types.d.ts

@@ -41,6 +41,27 @@ export interface ToolSpec {
     /** Defaults to true. Leave true in production. */
     strict?: boolean;
 }
+/** How hard a model should think, for models that take an effort scale. */
+export type ThinkingEffortLevel = "low" | "medium" | "high";
+/**
+ * What a model should do about thinking. Models differ in which form they take:
+ * one accepts an effort level, another a token budget, some both. A setting is
+ * only valid against the model it is sent to, and one the model cannot honour is
+ * a 400 rather than a silent downgrade.
+ *
+ * Omit the field entirely to get the model's own behaviour.
+ *
+ * Reasoning comes back as `reasoning` content blocks on the assistant turn,
+ * ahead of the answer. Some models return their working as words; others return
+ * only a signature.
+ */
+export type ThinkingSetting = "disabled" | {
+    type: "effort";
+    level: ThinkingEffortLevel;
+} | {
+    type: "budget";
+    budget_tokens: number;
+};
 export interface ConversationDefaults {
     model: AgentModel;
     data_plane_id: string;
@@ -49,6 +70,18 @@ export interface ConversationDefaults {
     max_iterations?: number;
     max_tokens?: number;
     temperature?: number;
+    /**
+     * Whether the model should reason before answering, and how hard.
+     *
+     * A token budget must be at least 1024 and smaller than `max_tokens`:
+     * thinking is spent from the same output budget as the answer, so a budget
+     * that fills it leaves nothing to answer with.
+     *
+     * Cannot be combined with `tool_choice: { kind: "specific_tool" }` on a run.
+     * A forced tool stops the model reasoning, so that combination is refused
+     * rather than half-honoured.
+     */
+    thinking?: ThinkingSetting;
     output_format_schema?: JsonSchemaObject;
     mcp_servers?: McpServerConfig[];
     tools?: ToolSpec[];
@@ -104,6 +137,8 @@ export interface RunConfigOverride {
     max_iterations?: number;
     max_tokens?: number;
     temperature?: number;
+    /** Shadows the conversation's setting for this run only. See {@link ConversationDefaults.thinking}. */
+    thinking?: ThinkingSetting;
     output_format_schema?: JsonSchemaObject;
     mcp_servers?: McpServerConfig[];
     tools?: ToolSpec[];
@@ -149,6 +184,11 @@ export interface LiveRunTurn {
     turn_index: number;
     role: AgentMessageRole;
     content_blocks: ContentBlock[];
+    /**
+     * Same meaning as on a committed message, but empty while the turn is still
+     * streaming: the answer is resolved when the run finalizes.
+     */
+    final_answer_from?: BlockId[];
 }
 /**
  * The conversation's current, still-mutating state. Always present on a run
@@ -202,9 +242,17 @@ export interface RunResponse {
     live: RunLiveProgress;
 }
 export type AgentMessageRole = "user" | "assistant" | "tool";
+/**
+ * Identifier a block was produced under, e.g. `b_c08cf800_02` — the first eight
+ * characters of the inference job's id and the block's position in that
+ * response. Present on blocks the platform produced; absent on blocks a caller
+ * sent, and on turns stored before ids existed.
+ */
+export type BlockId = string;
 export interface TextContentBlock {
     type: "text";
     text: string;
+    id?: BlockId;
 }
 export interface ToolUseContentBlock {
     type: "tool_use";
@@ -212,14 +260,43 @@ export interface ToolUseContentBlock {
     /** Fully-aliased wire name (`{alias}-{tool_name}` for MCP, bare for caller-declared). */
     name: string;
     arguments: Record<string, unknown>;
+    id?: BlockId;
 }
 export interface ToolResultContentBlock {
     type: "tool_result";
     tool_use_id: ToolUseId;
     content: ContentBlock[];
     is_error: boolean;
+    id?: BlockId;
+}
+/**
+ * The model's own working, on an assistant turn where the run asked for
+ * thinking. Comes first in the turn, ahead of the answer.
+ *
+ * `text` is optional and often absent: some models return their reasoning as
+ * words, others return only a `signature` and keep the words to themselves. A
+ * block with no `text` still means the model reasoned — and that those tokens
+ * were billed — so don't read its absence as "nothing happened".
+ *
+ * `signature` is issued by the provider and opaque: not a hash you can verify
+ * or a token you can decode. Send the block back unchanged to continue a turn
+ * as the model left it, or drop it — a continuation without reasoning blocks is
+ * accepted.
+ */
+export interface ReasoningContentBlock {
+    type: "reasoning";
+    text?: string;
+    signature: string;
+    id?: BlockId;
 }
-export type ContentBlock = TextContentBlock | ToolUseContentBlock | ToolResultContentBlock;
+/** Reasoning the provider encrypted rather than returning. Nothing to display; kept so a turn can be replayed whole. */
+export interface RedactedReasoningContentBlock {
+    type: "redacted_reasoning";
+    /** Base64 of the encrypted reasoning. */
+    data: string;
+    id?: BlockId;
+}
+export type ContentBlock = TextContentBlock | ToolUseContentBlock | ToolResultContentBlock | ReasoningContentBlock | RedactedReasoningContentBlock;
 export interface MessageDto {
     id: string;
     sequence_no: number;
@@ -227,6 +304,18 @@ export interface MessageDto {
     content_blocks: ContentBlock[];
     run_id: RunId;
     created_at: string;
+    /**
+     * Ids of the blocks this turn's answer was taken from — always text blocks
+     * that are present in `content_blocks`, and empty on a turn that answered
+     * nothing (a tool-call turn, a user's message, a turn still streaming).
+     *
+     * Render the reply from these rather than from every text block: with
+     * thinking on, a model may narrate its working as ordinary text before
+     * answering, and that narration is persisted deliberately. Use
+     * {@link answerTextBlocks}, which also handles turns stored before ids
+     * existed.
+     */
+    final_answer_from?: BlockId[];
 }
 export interface ListMessagesResponse {
     current_version: ConversationVersion;
@@ -243,3 +332,29 @@ export interface AgentRfcError {
 }
 export declare const TERMINAL_RUN_STATUSES: ReadonlyArray<RunStatus>;
 export declare function isTerminalRunStatus(status: RunStatus): boolean;
+/** Narrows to a reasoning block, whose `text` may still be absent. */
+export declare function isReasoningBlock(block: ContentBlock): block is ReasoningContentBlock;
+/**
+ * The text blocks of a turn that make up its reply — what to render as the
+ * assistant's message.
+ *
+ * Two shapes of turn exist and both are live, so which blocks count depends on
+ * whether the platform produced this turn:
+ *
+ *  - **A turn with block ids** is one we produced. Its reply is exactly the
+ *    blocks named by `final_answer_from`, which is empty while the turn is
+ *    still streaming and on turns that answer nothing (a tool-call turn). Empty
+ *    means *render nothing yet* — not "fall back to everything" — because such
+ *    a turn may also hold the model's working as ordinary text, and that
+ *    narration is not the reply.
+ *  - **A turn without block ids** is a caller's message or a turn stored before
+ *    ids existed. There is no pointer to consult, so its reply is every text
+ *    block, which is how these turns have always rendered.
+ *
+ * Ids the pointer names but the turn doesn't contain are ignored rather than
+ * trusted, so a malformed pointer renders nothing instead of throwing.
+ */
+export declare function answerTextBlocks(turn: {
+    content_blocks: ContentBlock[];
+    final_answer_from?: BlockId[];
+}): TextContentBlock[];

package/build/agents/types.js

@@ -20,3 +20,36 @@ export const TERMINAL_RUN_STATUSES = [
 export function isTerminalRunStatus(status) {
     return TERMINAL_RUN_STATUSES.includes(status);
 }
+// ---------- Reading a turn ----------
+/** Narrows to a reasoning block, whose `text` may still be absent. */
+export function isReasoningBlock(block) {
+    return block.type === "reasoning";
+}
+/**
+ * The text blocks of a turn that make up its reply — what to render as the
+ * assistant's message.
+ *
+ * Two shapes of turn exist and both are live, so which blocks count depends on
+ * whether the platform produced this turn:
+ *
+ *  - **A turn with block ids** is one we produced. Its reply is exactly the
+ *    blocks named by `final_answer_from`, which is empty while the turn is
+ *    still streaming and on turns that answer nothing (a tool-call turn). Empty
+ *    means *render nothing yet* — not "fall back to everything" — because such
+ *    a turn may also hold the model's working as ordinary text, and that
+ *    narration is not the reply.
+ *  - **A turn without block ids** is a caller's message or a turn stored before
+ *    ids existed. There is no pointer to consult, so its reply is every text
+ *    block, which is how these turns have always rendered.
+ *
+ * Ids the pointer names but the turn doesn't contain are ignored rather than
+ * trusted, so a malformed pointer renders nothing instead of throwing.
+ */
+export function answerTextBlocks(turn) {
+    const textBlocks = turn.content_blocks.filter((b) => b.type === "text");
+    const produced = turn.content_blocks.some((b) => b.id !== undefined);
+    if (!produced)
+        return textBlocks;
+    const named = new Set(turn.final_answer_from ?? []);
+    return textBlocks.filter((b) => b.id !== undefined && named.has(b.id));
+}

package/build/agents/types.test-d.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Type-level coverage for `src/agents/types.ts`. These assertions are checked by
+ * `tsc` (the file is picked up by tsconfig `include` and is not matched by the
+ * `**\/*.test.ts` exclude), so a broken assertion is a compile error at build
+ * time — jest never runs this file. Runtime helpers (`isTerminalRunStatus`,
+ * `TERMINAL_RUN_STATUSES`) are covered separately in `tests/Agents.test.ts`.
+ */
+import type { AgentModel, ContentBlock, ConversationDefaults, CreateConversationRequest, CreateRunRequest, LiveRunTurn, MessageDto, ReasoningContentBlock, RedactedReasoningContentBlock, RunConfigOverride, RunPayload, TextContentBlock, ToolChoice, ToolResultContentBlock, ToolUseContentBlock } from "./types";
+type IsAssignable<T, U> = T extends U ? true : false;
+type AssertTrue<T extends true> = T;
+type AssertFalse<T extends false> = T;
+type IsDeclaredModel<M extends string> = [Extract<AgentModel, M>] extends [
+    never
+] ? false : true;
+export type HasSonnet50 = AssertTrue<IsDeclaredModel<"anthropic.claude-sonnet-5.0">>;
+export type HasOpus47 = AssertTrue<IsDeclaredModel<"anthropic.claude-opus-4.7">>;
+export type HasOpus48 = AssertTrue<IsDeclaredModel<"anthropic.claude-opus-4.8">>;
+export type HasSonnet46 = AssertTrue<IsDeclaredModel<"anthropic.claude-sonnet-4.6">>;
+export type HasHaiku45 = AssertTrue<IsDeclaredModel<"anthropic.claude-haiku-4.5">>;
+export type HasGpt41 = AssertTrue<IsDeclaredModel<"openai.gpt-4.1">>;
+export type RejectsUndeclaredModel = AssertFalse<IsDeclaredModel<"anthropic.claude-opus-9.9">>;
+export type RejectsMisspelledModel = AssertFalse<IsDeclaredModel<"anthropic.claude-sonet-5.0">>;
+export type UserMessageIsPayload = AssertTrue<IsAssignable<{
+    kind: "user_message";
+    text: "hi";
+}, RunPayload>>;
+export type ToolOutputsIsPayload = AssertTrue<IsAssignable<{
+    kind: "tool_outputs";
+    outputs: [{
+        tool_use_id: "t";
+        content: "ok";
+    }];
+}, RunPayload>>;
+export type UnknownKindIsNotPayload = AssertFalse<IsAssignable<{
+    kind: "assistant_message";
+    text: "hi";
+}, RunPayload>>;
+export type UserMessageNeedsText = AssertFalse<IsAssignable<{
+    kind: "user_message";
+}, RunPayload>>;
+export type AutoIsToolChoice = AssertTrue<IsAssignable<{
+    kind: "auto";
+}, ToolChoice>>;
+export type AnyIsToolChoice = AssertTrue<IsAssignable<{
+    kind: "any";
+}, ToolChoice>>;
+export type SpecificToolIsToolChoice = AssertTrue<IsAssignable<{
+    kind: "specific_tool";
+    name: "lookup";
+}, ToolChoice>>;
+export type SpecificToolWithAlias = AssertTrue<IsAssignable<{
+    kind: "specific_tool";
+    name: "lookup";
+    mcp_alias: "gh";
+}, ToolChoice>>;
+export type SpecificToolNeedsName = AssertFalse<IsAssignable<{
+    kind: "specific_tool";
+}, ToolChoice>>;
+export type TextIsContentBlock = AssertTrue<IsAssignable<{
+    type: "text";
+    text: "hello";
+}, ContentBlock>>;
+export type UnknownTypeIsNotContentBlock = AssertFalse<IsAssignable<{
+    type: "image";
+    url: "x";
+}, ContentBlock>>;
+type NarrowText = Extract<ContentBlock, {
+    type: "text";
+}>;
+export type NarrowTextToBlock = AssertTrue<IsAssignable<NarrowText, TextContentBlock>>;
+export type NarrowBlockToText = AssertTrue<IsAssignable<TextContentBlock, NarrowText>>;
+type NarrowToolUse = Extract<ContentBlock, {
+    type: "tool_use";
+}>;
+export type NarrowsToToolUseBlock = AssertTrue<IsAssignable<NarrowToolUse, ToolUseContentBlock>>;
+type NarrowToolResult = Extract<ContentBlock, {
+    type: "tool_result";
+}>;
+export type NarrowsToToolResultBlock = AssertTrue<IsAssignable<NarrowToolResult, ToolResultContentBlock>>;
+export type CreateConversationNeedsDefaults = AssertFalse<IsAssignable<{
+    name: "c";
+}, CreateConversationRequest>>;
+export type MinimalCreateConversation = AssertTrue<IsAssignable<{
+    defaults: {
+        model: "anthropic.claude-opus-4.8";
+        data_plane_id: "dp";
+        execution_cluster: "shared";
+    };
+}, CreateConversationRequest>>;
+export type DefaultsNeedModel = AssertFalse<IsAssignable<{
+    data_plane_id: "dp";
+    execution_cluster: "shared";
+}, ConversationDefaults>>;
+export type BadExecutionCluster = AssertFalse<IsAssignable<{
+    model: "anthropic.claude-opus-4.8";
+    data_plane_id: "dp";
+    execution_cluster: "gpu";
+}, ConversationDefaults>>;
+type RequiredDefaults = {
+    model: "anthropic.claude-opus-5.0";
+    data_plane_id: "dp";
+    execution_cluster: "shared";
+};
+type Defaults<T> = RequiredDefaults & T;
+export type ThinkingIsOptional = AssertTrue<IsAssignable<RequiredDefaults, ConversationDefaults>>;
+export type DisabledIsASetting = AssertTrue<IsAssignable<Defaults<{
+    thinking: "disabled";
+}>, ConversationDefaults>>;
+export type EffortIsASetting = AssertTrue<IsAssignable<Defaults<{
+    thinking: {
+        type: "effort";
+        level: "high";
+    };
+}>, ConversationDefaults>>;
+export type BudgetIsASetting = AssertTrue<IsAssignable<Defaults<{
+    thinking: {
+        type: "budget";
+        budget_tokens: 4096;
+    };
+}>, ConversationDefaults>>;
+export type BadEffortLevelRejected = AssertFalse<IsAssignable<Defaults<{
+    thinking: {
+        type: "effort";
+        level: "extreme";
+    };
+}>, ConversationDefaults>>;
+export type UnknownVocabularyRejected = AssertFalse<IsAssignable<Defaults<{
+    thinking: {
+        type: "telepathy";
+    };
+}>, ConversationDefaults>>;
+export type BareStringRejected = AssertFalse<IsAssignable<Defaults<{
+    thinking: "high";
+}>, ConversationDefaults>>;
+export type BudgetWithoutTokensRejected = AssertFalse<IsAssignable<Defaults<{
+    thinking: {
+        type: "budget";
+    };
+}>, ConversationDefaults>>;
+export type EffortWithoutLevelRejected = AssertFalse<IsAssignable<Defaults<{
+    thinking: {
+        type: "effort";
+    };
+}>, ConversationDefaults>>;
+export type OverrideTakesThinking = AssertTrue<IsAssignable<{
+    thinking: {
+        type: "effort";
+        level: "low";
+    };
+}, RunConfigOverride>>;
+export type OverrideRejectsBadThinking = AssertFalse<IsAssignable<{
+    thinking: {
+        type: "effort";
+        level: "maximum";
+    };
+}, RunConfigOverride>>;
+export type MinimalCreateRun = AssertTrue<IsAssignable<{
+    client_op_id: "op";
+    expected_version: 0;
+    payload: {
+        kind: "user_message";
+        text: "hi";
+    };
+}, CreateRunRequest>>;
+export type CreateRunNeedsPayload = AssertFalse<IsAssignable<{
+    client_op_id: "op";
+    expected_version: 0;
+}, CreateRunRequest>>;
+export type LegacyTextBlockStillAssignable = AssertTrue<IsAssignable<{
+    type: "text";
+    text: "hi";
+}, ContentBlock>>;
+export type IdentifiedTextBlockAssignable = AssertTrue<IsAssignable<{
+    type: "text";
+    text: "hi";
+    id: "b_c08cf800_01";
+}, ContentBlock>>;
+export type ReasoningWithoutTextAssignable = AssertTrue<IsAssignable<{
+    type: "reasoning";
+    signature: "c2ln";
+}, ReasoningContentBlock>>;
+export type ReasoningWithTextAssignable = AssertTrue<IsAssignable<{
+    type: "reasoning";
+    signature: "c2ln";
+    text: "working it out";
+}, ReasoningContentBlock>>;
+export type ReasoningWithoutSignatureRejected = AssertFalse<IsAssignable<{
+    type: "reasoning";
+    text: "no signature";
+}, ReasoningContentBlock>>;
+export type ReasoningIsAContentBlock = AssertTrue<IsAssignable<ReasoningContentBlock, ContentBlock>>;
+export type RedactedReasoningIsAContentBlock = AssertTrue<IsAssignable<RedactedReasoningContentBlock, ContentBlock>>;
+export type UnknownBlockTypeRejected = AssertFalse<IsAssignable<{
+    type: "vibes";
+}, ContentBlock>>;
+export type LegacyMessageStillAssignable = AssertTrue<IsAssignable<{
+    id: "m1";
+    sequence_no: 1;
+    role: "assistant";
+    content_blocks: [{
+        type: "text";
+        text: "4";
+    }];
+    run_id: "r1";
+    created_at: "2026-07-30T00:00:00Z";
+}, MessageDto>>;
+export type MessageWithPointerAssignable = AssertTrue<IsAssignable<{
+    id: "m1";
+    sequence_no: 2;
+    role: "assistant";
+    content_blocks: [
+        {
+            type: "reasoning";
+            signature: "c2ln";
+            id: "b_1_00";
+        },
+        {
+            type: "text";
+            text: "{}";
+            id: "b_1_01";
+        }
+    ];
+    run_id: "r1";
+    created_at: "2026-07-30T00:00:00Z";
+    final_answer_from: ["b_1_01"];
+}, MessageDto>>;
+export type LegacyLiveTurnStillAssignable = AssertTrue<IsAssignable<{
+    turn_index: 0;
+    role: "assistant";
+    content_blocks: [];
+}, LiveRunTurn>>;
+export {};

package/build/agents/types.test-d.js

@@ -0,0 +1 @@
+export {};

package/build/mcp-connections/index.d.ts

@@ -6,7 +6,10 @@ import type { CreateMcpConnectionRequest, ListMcpConnectionsResponse, McpConnect
  * can reference it by id via `mcp_servers[].connection_id`. Tokens are never returned by the API.
  *
  * The OAuth callback (`GET /mcp-connections/callback`) is a browser redirect, not an SDK call, so
- * it is intentionally not wrapped here.
+ * it is intentionally not wrapped here. It only stores the authorization code and redirects; the
+ * app then calls {@link McpConnectionsApi.completeMcpConnection} to finish, authenticated as the
+ * user who began the flow. Because the callback is public, it is not allowed to complete anything
+ * itself — otherwise a `state` alone could turn another user's consent into a stored token.
  */
 export declare class McpConnectionsApi extends BaseApi {
     /**
@@ -21,6 +24,20 @@ export declare class McpConnectionsApi extends BaseApi {
      * `authorization_url` the user must visit to consent.
      */
     createMcpConnection(request: CreateMcpConnectionRequest): Promise<McpConnectionCreatedResponse>;
+    /**
+     * Completes a connection begun with {@link McpConnectionsApi.createMcpConnection}, once the user
+     * has consented and the OAuth callback has stored the authorization code. Exchanges that code and
+     * validates the connection with a `tools/list` call before storing the tokens.
+     *
+     * Must be called with the credentials of the user who began the flow — the `state` on its own is
+     * not enough.
+     * @param {string} state - The one-time `state` the OAuth callback forwarded to the app.
+     * @returns {Promise<McpConnectionSummary>} The connection's status view, normally `connected`.
+     * Rejects with 404 if the connection does not exist or belongs to another user; 400 if the
+     * `state` is unknown or expired, the authorization code has not arrived yet, or the token
+     * exchange or validation failed.
+     */
+    completeMcpConnection(state: string): Promise<McpConnectionSummary>;
     /**
      * Fetches one of the calling user's connections.
      * @param {string} connectionId - The connection id.

package/build/mcp-connections/index.js

@@ -6,7 +6,10 @@ const resourceName = "mcp-connections";
  * can reference it by id via `mcp_servers[].connection_id`. Tokens are never returned by the API.
  *
  * The OAuth callback (`GET /mcp-connections/callback`) is a browser redirect, not an SDK call, so
- * it is intentionally not wrapped here.
+ * it is intentionally not wrapped here. It only stores the authorization code and redirects; the
+ * app then calls {@link McpConnectionsApi.completeMcpConnection} to finish, authenticated as the
+ * user who began the flow. Because the callback is public, it is not allowed to complete anything
+ * itself — otherwise a `state` alone could turn another user's consent into a stored token.
  */
 export class McpConnectionsApi extends BaseApi {
     /**
@@ -25,6 +28,22 @@ export class McpConnectionsApi extends BaseApi {
     async createMcpConnection(request) {
         return await this.post(resourceName, request);
     }
+    /**
+     * Completes a connection begun with {@link McpConnectionsApi.createMcpConnection}, once the user
+     * has consented and the OAuth callback has stored the authorization code. Exchanges that code and
+     * validates the connection with a `tools/list` call before storing the tokens.
+     *
+     * Must be called with the credentials of the user who began the flow — the `state` on its own is
+     * not enough.
+     * @param {string} state - The one-time `state` the OAuth callback forwarded to the app.
+     * @returns {Promise<McpConnectionSummary>} The connection's status view, normally `connected`.
+     * Rejects with 404 if the connection does not exist or belongs to another user; 400 if the
+     * `state` is unknown or expired, the authorization code has not arrived yet, or the token
+     * exchange or validation failed.
+     */
+    async completeMcpConnection(state) {
+        return await this.post(`${resourceName}/complete`, { state });
+    }
     /**
      * Fetches one of the calling user's connections.
      * @param {string} connectionId - The connection id.

package/build/mcp-connections/types.d.ts

@@ -7,6 +7,9 @@ export interface McpConnectionCreatedResponse {
     connection_id: string;
     authorization_url: string;
 }
+export interface CompleteMcpConnectionRequest {
+    state: string;
+}
 export interface McpConnectionSummary {
     connection_id: string;
     server_url: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/data-collaboration-sdk-ts",
-	"version": "4.0.0",
+	"version": "4.2.0",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",