@tetral-ai/sdk 0.110.0-alpha.1

package/src/lib/parser.ts

@@ -0,0 +1,125 @@
+import type { Logger } from '../client';
+import { AnthropicError } from '../core/error';
+import {
+  ContentBlock,
+  JSONOutputFormat,
+  Message,
+  OutputConfig,
+  TextBlock,
+  MessageCreateParams,
+} from '../resources/messages/messages';
+
+// vendored from typefest just to make things look a bit nicer on hover
+type Simplify<T> = { [KeyType in keyof T]: T[KeyType] } & {};
+
+type AutoParseableOutputConfig = Omit<OutputConfig, 'format'> & {
+  format?: JSONOutputFormat | AutoParseableOutputFormat<any> | null;
+};
+
+export type ParseableMessageCreateParams = Simplify<
+  Omit<MessageCreateParams, 'output_config'> & {
+    output_config?: AutoParseableOutputConfig | null;
+  }
+>;
+
+export type ExtractParsedContentFromParams<Params extends ParseableMessageCreateParams> =
+  Params['output_config'] extends { format: AutoParseableOutputFormat<infer P> } ? P : null;
+
+export type AutoParseableOutputFormat<ParsedT> = JSONOutputFormat & {
+  parse(content: string): ParsedT;
+};
+
+export type ParsedMessage<ParsedT> = Message & {
+  content: Array<ParsedContentBlock<ParsedT>>;
+  parsed_output: ParsedT | null;
+};
+
+export type ParsedContentBlock<ParsedT> =
+  | (TextBlock & { parsed_output: ParsedT | null })
+  | Exclude<ContentBlock, TextBlock>;
+
+function getOutputFormat(
+  params: ParseableMessageCreateParams | null,
+): JSONOutputFormat | AutoParseableOutputFormat<any> | null | undefined {
+  return params?.output_config?.format;
+}
+
+export function maybeParseMessage<Params extends ParseableMessageCreateParams | null>(
+  message: Message,
+  params: Params,
+  opts: { logger: Logger },
+): ParsedMessage<ExtractParsedContentFromParams<NonNullable<Params>>> {
+  const outputFormat = getOutputFormat(params);
+  if (!params || !('parse' in (outputFormat ?? {}))) {
+    return {
+      ...message,
+      content: message.content.map((block) => {
+        if (block.type === 'text') {
+          const parsedBlock = Object.defineProperty({ ...block }, 'parsed_output', {
+            value: null,
+            enumerable: false,
+          }) as ParsedContentBlock<ExtractParsedContentFromParams<NonNullable<Params>>>;
+
+          return parsedBlock;
+        }
+        return block;
+      }),
+      parsed_output: null,
+    } as ParsedMessage<ExtractParsedContentFromParams<NonNullable<Params>>>;
+  }
+
+  return parseMessage(message, params, opts);
+}
+
+export function parseMessage<Params extends ParseableMessageCreateParams>(
+  message: Message,
+  params: Params,
+  opts: { logger: Logger },
+): ParsedMessage<ExtractParsedContentFromParams<Params>> {
+  let firstParsedOutput: ReturnType<typeof parseOutputFormat<Params>> | null = null;
+
+  const content: Array<ParsedContentBlock<ExtractParsedContentFromParams<Params>>> = message.content.map(
+    (block) => {
+      if (block.type === 'text') {
+        const parsedOutput = parseOutputFormat(params, block.text);
+
+        if (firstParsedOutput === null) {
+          firstParsedOutput = parsedOutput;
+        }
+
+        const parsedBlock = Object.defineProperty({ ...block }, 'parsed_output', {
+          value: parsedOutput,
+          enumerable: false,
+        }) as ParsedContentBlock<ExtractParsedContentFromParams<Params>>;
+        return parsedBlock;
+      }
+      return block;
+    },
+  );
+
+  return {
+    ...message,
+    content,
+    parsed_output: firstParsedOutput,
+  } as ParsedMessage<ExtractParsedContentFromParams<Params>>;
+}
+
+function parseOutputFormat<Params extends ParseableMessageCreateParams>(
+  params: Params,
+  content: string,
+): ExtractParsedContentFromParams<Params> | null {
+  const outputFormat = getOutputFormat(params);
+  if (outputFormat?.type !== 'json_schema') {
+    return null;
+  }
+
+  try {
+    if ('parse' in outputFormat) {
+      return outputFormat.parse(content);
+    }
+
+    return JSON.parse(content);
+  } catch (error) {
+    throw new AnthropicError(`Failed to parse structured output: ${error}`);
+  }
+}

package/src/lib/sessions/accumulate.ts

@@ -0,0 +1,129 @@
+import { AnthropicError } from '../../core/error';
+import type {
+  BetaManagedAgentsAgentMessageEvent,
+  BetaManagedAgentsStreamSessionEvents,
+} from '../../resources/beta/sessions/events';
+
+export type AccumulatedEvent = BetaManagedAgentsAgentMessageEvent;
+
+/**
+ * Fold one preview event into an `agent.message` snapshot. Returns a fresh
+ * snapshot — the `msg` argument is never mutated.
+ *
+ * - `event_start` opens the preview: a new snapshot with empty content is
+ *   returned (so `msg` may be `undefined`). Returns `undefined` when the
+ *   previewed event is not an `agent.message` — this helper only tracks
+ *   `agent.message` previews.
+ * - `event_delta` is folded into `msg`: a new `delta.index` inserts the
+ *   fragment as a fresh content entry; an existing index returns a copy with
+ *   that entry appended to. An unrecognised fragment type on an existing
+ *   index passes the entry through unchanged — deltas are best-effort and the
+ *   buffered final event is canonical — but is a compile-time error via the
+ *   exhaustiveness guard, matching `MessageStream#accumulateMessage`.
+ * - `agent.message` is the buffered final event: a copy of it is returned,
+ *   replacing whatever the preview had accumulated.
+ */
+export function accumulateManagedAgentsEvent<T extends AccumulatedEvent>(
+  accumulated: AccumulatedEvent | undefined,
+  event: T,
+): T;
+export function accumulateManagedAgentsEvent(
+  accumulated: AccumulatedEvent | undefined,
+  event: BetaManagedAgentsStreamSessionEvents,
+): AccumulatedEvent | undefined;
+export function accumulateManagedAgentsEvent(
+  accumulated: AccumulatedEvent | undefined,
+  event: BetaManagedAgentsStreamSessionEvents,
+): AccumulatedEvent | undefined {
+  switch (event.type) {
+    case 'event_start': {
+      if (event.event.type === 'agent.message') {
+        return { id: event.event.id, type: 'agent.message', content: [], processed_at: '' };
+      }
+
+      return accumulated;
+    }
+
+    case 'agent.message': {
+      return { ...event, content: event.content.map((block) => ({ ...block })) };
+    }
+
+    case 'event_delta': {
+      if (accumulated === undefined) {
+        throw new AnthropicError(`event_delta for ${event.event_id} received before its event_start`);
+      }
+
+      const idx = event.delta.index ?? 0;
+      const fragment = event.delta.content;
+
+      // Indices arrive in order — the first delta at a new index opens the slot.
+      // A gap means deltas arrived out of order or were mis-routed.
+      if (idx > accumulated.content.length) {
+        throw new AnthropicError(
+          `event_delta index ${idx} is beyond the end of content (length ${accumulated.content.length})`,
+        );
+      }
+
+      const existing = accumulated.content[idx];
+      if (existing === undefined) {
+        // New index: pass the fragment through as a fresh block.
+        return { ...accumulated, content: [...accumulated.content, { ...fragment }] };
+      }
+
+      let updated = existing;
+      switch (fragment.type) {
+        case 'text':
+          if (existing.type === 'text') {
+            updated = { ...existing, text: existing.text + fragment.text };
+          }
+          break;
+        default:
+          checkNever(fragment.type);
+      }
+
+      const content = accumulated.content.slice();
+      content[idx] = updated;
+      return { ...accumulated, content };
+    }
+    case 'user.message':
+    case 'user.interrupt':
+    case 'user.tool_confirmation':
+    case 'user.tool_result':
+    case 'user.custom_tool_result':
+    case 'user.define_outcome':
+    case 'agent.thinking':
+    case 'agent.tool_use':
+    case 'agent.tool_result':
+    case 'agent.custom_tool_use':
+    case 'agent.mcp_tool_use':
+    case 'agent.mcp_tool_result':
+    case 'agent.thread_message_received':
+    case 'agent.thread_message_sent':
+    case 'agent.thread_context_compacted':
+    case 'session.error':
+    case 'session.updated':
+    case 'session.deleted':
+    case 'session.status_running':
+    case 'session.status_idle':
+    case 'session.status_rescheduled':
+    case 'session.status_terminated':
+    case 'session.thread_created':
+    case 'session.thread_status_running':
+    case 'session.thread_status_idle':
+    case 'session.thread_status_rescheduled':
+    case 'session.thread_status_terminated':
+    case 'span.model_request_start':
+    case 'span.model_request_end':
+    case 'span.outcome_evaluation_start':
+    case 'span.outcome_evaluation_ongoing':
+    case 'span.outcome_evaluation_end':
+    case 'system.message':
+      return accumulated;
+    default:
+      checkNever(event);
+      return accumulated;
+  }
+}
+
+// Compile-time exhaustiveness guard.
+function checkNever(_x: never): void {}

package/src/lib/tools/BetaRunnableTool.ts

@@ -0,0 +1,130 @@
+import {
+  BetaMemoryTool20250818,
+  BetaTool,
+  BetaToolBash20241022,
+  BetaToolBash20250124,
+  BetaToolComputerUse20241022,
+  BetaToolComputerUse20250124,
+  BetaToolComputerUse20251124,
+  BetaToolResultContentBlockParam,
+  BetaToolTextEditor20241022,
+  BetaToolTextEditor20250124,
+  BetaToolTextEditor20250429,
+  BetaToolTextEditor20250728,
+  BetaToolUnion,
+  BetaToolUseBlock,
+} from '../../resources/beta';
+import type {
+  BetaManagedAgentsAgentCustomToolUseEvent,
+  BetaManagedAgentsAgentToolUseEvent,
+} from '../../resources/beta/sessions/events';
+import { ToolError } from './ToolError';
+
+export type Promisable<T> = T | Promise<T>;
+
+/**
+ * Tool types that can be implemented on the client.
+ * Excludes server-side tools like code execution, web search, and MCP toolsets.
+ */
+export type BetaClientRunnableToolType =
+  | BetaTool
+  | BetaMemoryTool20250818
+  | BetaToolBash20241022
+  | BetaToolBash20250124
+  | BetaToolComputerUse20241022
+  | BetaToolComputerUse20250124
+  | BetaToolComputerUse20251124
+  | BetaToolTextEditor20241022
+  | BetaToolTextEditor20250124
+  | BetaToolTextEditor20250429
+  | BetaToolTextEditor20250728;
+
+/**
+ * The tool-use that triggered a {@link BetaRunnableTool.run}:
+ *
+ * - from `client.beta.messages.toolRunner`, a Messages `tool_use` content block;
+ * - from `client.beta.sessions.events.toolRunner`, the `agent.tool_use` /
+ *   `agent.custom_tool_use` session event.
+ *
+ * The shapes overlap on the common fields (`id`, `name`, `input`), so code that
+ * only reads those works without narrowing; narrow on the shape (e.g. `'type' in
+ * x`) when you need surface-specific properties.
+ */
+export type BetaToolUse =
+  | BetaToolUseBlock
+  | BetaManagedAgentsAgentToolUseEvent
+  | BetaManagedAgentsAgentCustomToolUseEvent;
+
+export type BetaToolRunContext = {
+  /** The tool-use that triggered this run. See {@link BetaToolUse}. */
+  toolUse: BetaToolUse;
+  /**
+   * @deprecated Renamed to `toolUse`. Also note that for
+   * `client.beta.sessions.events.toolRunner` this is the `agent.tool_use` /
+   * `agent.custom_tool_use` *event*, not a Messages content block, despite the
+   * name — which is why it was renamed.
+   */
+  toolUseBlock: BetaToolUse;
+  signal?: AbortSignal | null | undefined;
+};
+
+// this type is just an extension of BetaTool with a run and parse method
+// that will be called by `toolRunner()` helpers
+export type BetaRunnableTool<Input = any> = BetaClientRunnableToolType & {
+  run: (
+    args: Input,
+    context?: BetaToolRunContext,
+  ) => Promisable<string | Array<BetaToolResultContentBlockParam>>;
+  parse: (content: unknown) => Input;
+  /**
+   * Optional cleanup hook for tools that hold process-level resources (e.g. a
+   * persistent shell). `SessionToolRunner` (`client.beta.sessions.events.toolRunner`)
+   * calls it once when iteration ends.
+   */
+  close?: () => Promisable<void>;
+};
+
+/**
+ * Resolve the registry key for a tool — the name the model addresses it by.
+ * MCP toolsets are keyed on `mcp_server_name`; every other tool on `name`.
+ * Shared so the tool-name lookup is identical across `toolRunner()` surfaces.
+ */
+export function toolName(tool: BetaToolUnion | BetaRunnableTool): string {
+  return 'name' in tool ? tool.name : tool.mcp_server_name;
+}
+
+/**
+ * Format a thrown value into tool-result content: a {@link ToolError} carries
+ * its own structured content, anything else becomes an `Error: <message>`
+ * string. Shared so every `toolRunner()` surface reports tool failures the
+ * same way to the model.
+ */
+export function toolErrorContent(e: unknown): string | Array<BetaToolResultContentBlockParam> {
+  return e instanceof ToolError ? e.content : `Error: ${e instanceof Error ? e.message : String(e)}`;
+}
+
+/** Outcome of {@link runRunnableTool}: the content to post back and whether it is an error. */
+export interface RunnableToolOutcome {
+  content: string | Array<BetaToolResultContentBlockParam>;
+  isError: boolean;
+}
+
+/**
+ * Run a {@link BetaRunnableTool} end-to-end: parse the raw input, invoke `run`,
+ * and format any thrown value via {@link toolErrorContent}. Shared so the
+ * parse → run → catch → format pipeline is identical across `toolRunner()`
+ * surfaces.
+ */
+export async function runRunnableTool(
+  tool: BetaRunnableTool,
+  rawInput: unknown,
+  context: BetaToolRunContext,
+): Promise<RunnableToolOutcome> {
+  try {
+    const input = tool.parse ? tool.parse(rawInput) : rawInput;
+    const content = await tool.run(input, context);
+    return { content, isError: false };
+  } catch (e) {
+    return { content: toolErrorContent(e), isError: true };
+  }
+}