Add hosted tools, fix toolChoice for Responses API, add previousResponseId

- HostedTool type and AgentTool union (FunctionTool | HostedTool) with type guards
- Built-in tool factories: webSearchTool, codeInterpreterTool, mcpTool, imageGenerationTool
- Fix toolChoice serialization for Responses API ({ type, function: { name } } → { type, name })
- Hosted tool defs pass through to Responses API; Chat Completions rejects with clear error
- Agent.tools and SessionConfig.tools widened to AgentTool[] (backward compatible)
- ModelRequest.previousResponseId / ModelResponse.responseId / RunResult.responseId
- AzureResponsesModel.store config (default false), gates previous_response_id forwarding
- 30 new unit tests, 7 integration tests (6 pass, 1 skip for model support)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tylergibbs1

src/azure/chat-completions-model.ts

@@ -1,4 +1,4 @@
-import { ContentFilterError, ModelError } from "../core/errors";
+import { ContentFilterError, ModelError, StratusError } from "../core/errors";
 import type {
 	FinishReason,
 	Model,
@@ -8,7 +8,7 @@ import type {
 	StreamEvent,
 	UsageInfo,
 } from "../core/model";
-import type { ChatMessage, ToolCall } from "../core/types";
+import type { ChatMessage, ToolCall, ToolDefinition } from "../core/types";
 import { resolveChatCompletionsUrl } from "./endpoint";
 import { parseSSE } from "./sse-parser";
 
@@ -161,7 +161,14 @@ export class AzureChatCompletionsModel implements Model {
 		}
 
 		if (request.tools && request.tools.length > 0) {
-			body.tools = request.tools;
+			for (const tool of request.tools) {
+				if (!("function" in tool)) {
+					throw new StratusError(
+						"Hosted tools (web_search, code_interpreter, mcp, image_generation) are not supported by the Chat Completions API. Use AzureResponsesModel instead.",
+					);
+				}
+			}
+			body.tools = request.tools as ToolDefinition[];
 		}
 
 		if (request.responseFormat) {

src/azure/responses-model.ts

@@ -13,6 +13,7 @@ import type {
 	ContentPart,
 	ResponseFormat,
 	ToolCall,
+	ToolChoice,
 	ToolDefinition,
 } from "../core/types";
 import { resolveResponsesUrl } from "./endpoint";
@@ -23,6 +24,7 @@ export interface AzureResponsesModelConfig {
 	apiKey: string;
 	deployment: string;
 	apiVersion?: string;
+	store?: boolean;
 }
 
 const DEFAULT_API_VERSION = "2025-04-01-preview";
@@ -31,10 +33,12 @@ export class AzureResponsesModel implements Model {
 	private readonly url: string;
 	private readonly apiKey: string;
 	private readonly deployment: string;
+	private readonly store: boolean;
 
 	constructor(config: AzureResponsesModelConfig) {
 		this.apiKey = config.apiKey;
 		this.deployment = config.deployment;
+		this.store = config.store ?? false;
 		this.url = resolveResponsesUrl(
 			config.endpoint,
 			config.apiVersion ?? DEFAULT_API_VERSION,
@@ -67,6 +71,7 @@ export class AzureResponsesModel implements Model {
 		const toolCalls = new Map<string, { callId: string; name: string; arguments: string }>();
 		let usage: UsageInfo | undefined;
 		let finishReason: FinishReason | undefined;
+		let responseId: string | undefined;
 
 		for await (const data of parseSSE(response.body)) {
 			let event: ResponsesStreamEvent;
@@ -124,6 +129,9 @@ export class AzureResponsesModel implements Model {
 				}
 				case "response.completed": {
 					const resp = event.response;
+					if (resp?.id) {
+						responseId = resp.id;
+					}
 					if (resp?.usage) {
 						usage = {
 							promptTokens: resp.usage.input_tokens,
@@ -156,6 +164,7 @@ export class AzureResponsesModel implements Model {
 				toolCalls: finalToolCalls,
 				usage,
 				finishReason,
+				responseId,
 			},
 		};
 	}
@@ -166,7 +175,7 @@ export class AzureResponsesModel implements Model {
 	): Record<string, unknown> {
 		const body: Record<string, unknown> = {
 			model: this.deployment,
-			store: false,
+			store: this.store,
 		};
 
 		const { instructions, input } = convertMessages(request.messages);
@@ -182,21 +191,32 @@ export class AzureResponsesModel implements Model {
 		}
 
 		if (request.tools && request.tools.length > 0) {
-			body.tools = request.tools.map(flattenToolDefinition);
+			body.tools = request.tools.map((def) => {
+				if (isFunctionToolDefinition(def)) {
+					return flattenToolDefinition(def);
+				}
+				// Hosted tool definitions pass through as-is
+				return def;
+			});
 		}
 
 		if (request.responseFormat) {
 			body.text = convertResponseFormat(request.responseFormat);
 		}
 
+		// Only send previous_response_id when store is enabled (API needs to persist responses)
+		if (this.store && request.previousResponseId) {
+			body.previous_response_id = request.previousResponseId;
+		}
+
 		const s = request.modelSettings;
 		if (s) {
 			if (s.temperature !== undefined) body.temperature = s.temperature;
 			if (s.topP !== undefined) body.top_p = s.topP;
 			if (s.maxTokens !== undefined) body.max_output_tokens = s.maxTokens;
 			if (s.maxCompletionTokens !== undefined)
 				body.max_output_tokens = s.maxCompletionTokens;
-			if (s.toolChoice !== undefined) body.tool_choice = s.toolChoice;
+			if (s.toolChoice !== undefined) body.tool_choice = convertToolChoice(s.toolChoice);
 			if (s.parallelToolCalls !== undefined) body.parallel_tool_calls = s.parallelToolCalls;
 			if (s.reasoningEffort !== undefined)
 				body.reasoning = { effort: s.reasoningEffort };
@@ -277,6 +297,7 @@ export class AzureResponsesModel implements Model {
 				toolCalls,
 				usage: json.usage ? parseResponsesUsage(json.usage) : undefined,
 				finishReason: "length",
+				responseId: json.id,
 			};
 		}
 
@@ -295,6 +316,7 @@ export class AzureResponsesModel implements Model {
 			toolCalls,
 			usage,
 			finishReason,
+			responseId: json.id,
 		};
 	}
 }
@@ -417,6 +439,21 @@ function convertUserContent(
 	});
 }
 
+function isFunctionToolDefinition(
+	def: ToolDefinition | Record<string, unknown>,
+): def is ToolDefinition {
+	return "function" in def && typeof (def as ToolDefinition).function === "object";
+}
+
+function convertToolChoice(
+	toolChoice: ToolChoice,
+): string | { type: string; name: string } {
+	if (typeof toolChoice === "string") return toolChoice;
+	// Chat Completions format: { type: "function", function: { name } }
+	// Responses API format: { type: "function", name }
+	return { type: toolChoice.type, name: toolChoice.function.name };
+}
+
 function flattenToolDefinition(
 	def: ToolDefinition,
 ): Record<string, unknown> {
@@ -459,6 +496,7 @@ function mapStatus(status: string | undefined): FinishReason {
 // --- Responses API types ---
 
 interface ResponsesApiResponse {
+	id?: string;
 	status: string;
 	output?: ResponsesOutputItem[];
 	usage?: ResponsesUsage;
@@ -504,4 +542,4 @@ type ResponsesStreamEvent =
 	| { type: "response.output_item.added"; item?: ResponsesStreamItem }
 	| { type: "response.function_call_arguments.delta"; item_id?: string; delta?: string }
 	| { type: "response.output_item.done"; item?: ResponsesStreamItem }
-	| { type: "response.completed"; response?: { status?: string; usage?: ResponsesUsage } };
+	| { type: "response.completed"; response?: { id?: string; status?: string; usage?: ResponsesUsage } };

src/core/agent.ts

@@ -4,6 +4,7 @@ import { type Handoff, handoff as normalizeHandoff } from "./handoff";
 import type { AgentHooks } from "./hooks";
 import type { Model } from "./model";
 import type { SubAgent } from "./subagent";
+import type { AgentTool } from "./hosted-tool";
 import type { FunctionTool } from "./tool";
 import type { ModelSettings, ResponseFormat, ToolUseBehavior } from "./types";
 import { zodToJsonSchema } from "./utils/zod";
@@ -16,7 +17,7 @@ export interface AgentConfig<TContext, TOutput = undefined> {
 	name: string;
 	instructions?: Instructions<TContext>;
 	model?: Model;
-	tools?: FunctionTool[];
+	tools?: AgentTool[];
 	subagents?: SubAgent[];
 	modelSettings?: ModelSettings;
 	responseFormat?: ResponseFormat;
@@ -33,7 +34,7 @@ export class Agent<TContext = unknown, TOutput = undefined> {
 	readonly name: string;
 	readonly instructions?: Instructions<TContext>;
 	readonly model?: Model;
-	readonly tools: FunctionTool[];
+	readonly tools: AgentTool[];
 	readonly subagents: SubAgent[];
 	readonly modelSettings?: ModelSettings;
 	readonly responseFormat?: ResponseFormat;

src/core/builtin-tools.ts

@@ -0,0 +1,82 @@
+import type { HostedTool } from "./hosted-tool";
+
+export interface WebSearchToolConfig {
+	userLocation?: {
+		type: "approximate";
+		city?: string;
+		state?: string;
+		country?: string;
+		region?: string;
+	};
+	searchContextSize?: "low" | "medium" | "high";
+}
+
+export function webSearchTool(config?: WebSearchToolConfig): HostedTool {
+	const definition: Record<string, unknown> = {
+		type: "web_search_preview",
+	};
+	if (config?.userLocation) {
+		definition.user_location = config.userLocation;
+	}
+	if (config?.searchContextSize) {
+		definition.search_context_size = config.searchContextSize;
+	}
+	return {
+		type: "hosted",
+		name: "web_search_preview",
+		definition,
+	};
+}
+
+export interface CodeInterpreterToolConfig {
+	container?: {
+		type: "auto" | string;
+	};
+}
+
+export function codeInterpreterTool(config?: CodeInterpreterToolConfig): HostedTool {
+	return {
+		type: "hosted",
+		name: "code_interpreter",
+		definition: {
+			type: "code_interpreter",
+			container: config?.container ?? { type: "auto" },
+		},
+	};
+}
+
+export interface McpToolConfig {
+	serverLabel: string;
+	serverUrl: string;
+	requireApproval?: "always" | "never" | { always?: string[]; never?: string[] };
+	headers?: Record<string, string>;
+}
+
+export function mcpTool(config: McpToolConfig): HostedTool {
+	const definition: Record<string, unknown> = {
+		type: "mcp",
+		server_label: config.serverLabel,
+		server_url: config.serverUrl,
+	};
+	if (config.requireApproval !== undefined) {
+		definition.require_approval = config.requireApproval;
+	}
+	if (config.headers) {
+		definition.headers = config.headers;
+	}
+	return {
+		type: "hosted",
+		name: `mcp:${config.serverLabel}`,
+		definition,
+	};
+}
+
+export function imageGenerationTool(): HostedTool {
+	return {
+		type: "hosted",
+		name: "image_generation",
+		definition: {
+			type: "image_generation",
+		},
+	};
+}

src/core/hosted-tool.ts

@@ -0,0 +1,17 @@
+import type { FunctionTool } from "./tool";
+
+export interface HostedTool {
+	type: "hosted";
+	name: string;
+	definition: Record<string, unknown>;
+}
+
+export type AgentTool = FunctionTool | HostedTool;
+
+export function isHostedTool(tool: AgentTool): tool is HostedTool {
+	return tool.type === "hosted";
+}
+
+export function isFunctionTool(tool: AgentTool): tool is FunctionTool {
+	return tool.type === "function";
+}

src/core/index.ts

@@ -13,6 +13,12 @@ export type { SessionConfig, SessionSnapshot } from "./session";
 export { tool, toolToDefinition } from "./tool";
 export type { FunctionTool, ToolExecuteOptions } from "./tool";
 
+export { isHostedTool, isFunctionTool } from "./hosted-tool";
+export type { HostedTool, AgentTool } from "./hosted-tool";
+
+export { webSearchTool, codeInterpreterTool, mcpTool, imageGenerationTool } from "./builtin-tools";
+export type { WebSearchToolConfig, CodeInterpreterToolConfig, McpToolConfig } from "./builtin-tools";
+
 export { TodoList, todoTool } from "./todo";
 export type { Todo, TodoStatus, TodoUpdateListener } from "./todo";
 

src/core/model.ts

@@ -2,9 +2,10 @@ import type { ChatMessage, ModelSettings, ResponseFormat, ToolCall, ToolDefiniti
 
 export interface ModelRequest {
 	messages: ChatMessage[];
-	tools?: ToolDefinition[];
+	tools?: (ToolDefinition | Record<string, unknown>)[];
 	modelSettings?: ModelSettings;
 	responseFormat?: ResponseFormat;
+	previousResponseId?: string;
 }
 
 export interface UsageInfo {
@@ -23,6 +24,7 @@ export interface ModelResponse {
 	toolCalls: ToolCall[];
 	usage?: UsageInfo;
 	finishReason?: FinishReason;
+	responseId?: string;
 }
 
 export type StreamEvent =

src/core/result.ts

@@ -11,6 +11,7 @@ export interface RunResultOptions<TOutput = undefined> {
 	finishReason?: FinishReason;
 	numTurns?: number;
 	totalCostUsd?: number;
+	responseId?: string;
 }
 
 export class RunResult<TOutput = undefined> {
@@ -22,6 +23,7 @@ export class RunResult<TOutput = undefined> {
 	readonly finishReason?: FinishReason;
 	readonly numTurns: number;
 	readonly totalCostUsd: number;
+	readonly responseId?: string;
 
 	constructor(opts: RunResultOptions<TOutput>) {
 		this.output = opts.output;
@@ -32,5 +34,6 @@ export class RunResult<TOutput = undefined> {
 		this.finishReason = opts.finishReason;
 		this.numTurns = opts.numTurns ?? 0;
 		this.totalCostUsd = opts.totalCostUsd ?? 0;
+		this.responseId = opts.responseId;
 	}
 }