@modelrelay/sdk 5.3.0 → 8.0.0

package/dist/index.d.cts

@@ -1,6 +1,7 @@
-import { A as ApiKey, R as RetryConfig, M as MetricsCallbacks, T as TraceCallbacks, a as RequestContext, b as TokenProvider, C as CustomerTokenRequest, c as CustomerToken, G as GetOrCreateCustomerTokenRequest, P as ProviderId, d as ModelId, I as InputItem, O as OutputFormat, e as Tool, f as ToolChoice, Z as ZodLikeSchema, g as ResponseEvent, h as Response$1, S as StructuredJSONEvent, F as FieldError, i as RetryMetadata, j as TransportErrorKind, k as ToolRegistry, l as ToolExecutionResult, m as TierCode, n as SecretKey, o as ModelRelayKeyOptions, p as ModelRelayOptions } from './tools-bCt1QwNk.cjs';
-export { ba as APICheckoutSession, b9 as APICustomerRef, bd as APIKey, bc as APIResponsesResponse, bb as APIUsage, ak as BillingProvider, aj as BillingProviders, aT as Citation, aL as CodeExecConfig, ay as ContentPart, ax as ContentPartType, aw as ContentPartTypes, al as CustomerMetadata, D as DEFAULT_BASE_URL, a7 as DEFAULT_CLIENT_HEADER, a8 as DEFAULT_CONNECT_TIMEOUT_MS, a9 as DEFAULT_REQUEST_TIMEOUT_MS, b8 as DeepPartial, aO as FunctionCall, b6 as FunctionCallDelta, aI as FunctionTool, aU as HttpRequestMetrics, aA as InputItemType, az as InputItemTypes, aS as JSONSchemaFormat, a2 as JsonSchemaOptions, ac as KnownStopReason, b3 as MessageDeltaData, av as MessageRole, au as MessageRoles, b2 as MessageStartData, b4 as MessageStopData, am as ModelRelayBaseOptions, an as ModelRelayTokenOptions, ao as ModelRelayTokenProviderOptions, aa as NonEmptyArray, aR as OutputFormatType, aQ as OutputFormatTypes, aD as OutputItem, aC as OutputItemType, aB as OutputItemTypes, at as Project, b1 as ResponseEventType, a5 as RetryOptions, a6 as SDK_VERSION, a3 as Schema, ad as StopReason, ab as StopReasons, aV as StreamFirstTokenMetrics, b7 as StructuredJSONRecordType, ai as SubscriptionStatusKind, ah as SubscriptionStatuses, ap as TokenType, aW as TokenUsageMetrics, X as ToolArgsError, aP as ToolCall, N as ToolCallAccumulator, b5 as ToolCallDelta, aN as ToolChoiceType, aM as ToolChoiceTypes, a4 as ToolHandler, aF as ToolType, aE as ToolTypes, aq as Usage, as as UsageSummary, aJ as WebSearchConfig, aH as WebToolIntent, aG as WebToolIntents, aK as XSearchConfig, af as asModelId, ae as asProviderId, ag as asTierCode, J as assistantMessageWithToolCalls, z as createAssistantMessage, L as createFunctionCall, q as createFunctionTool, r as createFunctionToolFromSchema, a0 as createRetryMessages, B as createSystemMessage, K as createToolCall, ar as createUsage, y as createUserMessage, s as createWebTool, a1 as executeWithRetry, x as firstToolCall, Y as formatToolErrorForModel, $ as getRetryableErrors, _ as hasRetryableErrors, w as hasToolCalls, aX as mergeMetrics, aY as mergeTrace, b0 as modelToString, a$ as normalizeModelId, aZ as normalizeStopReason, U as parseToolArgs, W as parseToolArgsRaw, H as respondToToolCall, a_ as stopReasonToString, t as toolChoiceAuto, v as toolChoiceNone, u as toolChoiceRequired, E as toolResultMessage, V as tryParseToolArgs, Q as zodToJsonSchema } from './tools-bCt1QwNk.cjs';
-import { c as components, $ as $defs, o as operations, p as paths, w as webhooks } from './api-7TVb2cnl.cjs';
+import { A as ApiKey, R as RetryConfig, M as MetricsCallbacks, T as TraceCallbacks, a as RequestContext, b as TokenProvider, C as CustomerTokenRequest, c as CustomerToken, G as GetOrCreateCustomerTokenRequest, P as ProviderId, d as ModelId, I as InputItem, O as OutputFormat, e as Tool, f as ToolChoice, Z as ZodLikeSchema, g as ToolCall, h as Response$1, i as ResponseEvent, S as StructuredJSONEvent, F as FieldError, j as RetryMetadata, k as TransportErrorKind, l as ToolRegistry, m as ToolExecutionResult, n as TierCode, o as AnySchema, p as SecretKey, q as ModelRelayKeyOptions, r as ModelRelayOptions } from './tools-DHCGz_lx.cjs';
+export { bf as APICheckoutSession, be as APICustomerRef, bi as APIKey, bh as APIResponsesResponse, bg as APIUsage, at as BillingProvider, as as BillingProviders, aY as Citation, aR as CodeExecConfig, aH as ContentPart, aG as ContentPartType, aF as ContentPartTypes, au as CustomerMetadata, D as DEFAULT_BASE_URL, ag as DEFAULT_CLIENT_HEADER, ah as DEFAULT_CONNECT_TIMEOUT_MS, ai as DEFAULT_REQUEST_TIMEOUT_MS, bd as DeepPartial, aU as FunctionCall, bb as FunctionCallDelta, aP as FunctionTool, aZ as HttpRequestMetrics, a9 as InferSchema, aJ as InputItemType, aI as InputItemTypes, aX as JSONSchemaFormat, a8 as JsonSchemaOptions, al as KnownStopReason, b8 as MessageDeltaData, aE as MessageRole, aD as MessageRoles, b7 as MessageStartData, b9 as MessageStopData, av as ModelRelayBaseOptions, aw as ModelRelayTokenOptions, ax as ModelRelayTokenProviderOptions, aj as NonEmptyArray, aW as OutputFormatType, aV as OutputFormatTypes, aM as OutputItem, aL as OutputItemType, aK as OutputItemTypes, aC as Project, b6 as ResponseEventType, ad as RetryOptions, af as SDK_VERSION, am as StopReason, ak as StopReasons, a_ as StreamFirstTokenMetrics, bc as StructuredJSONRecordType, ar as SubscriptionStatusKind, aq as SubscriptionStatuses, ay as TokenType, a$ as TokenUsageMetrics, a2 as ToolArgsError, ae as ToolArgsResult, a0 as ToolCallAccumulator, ba as ToolCallDelta, aT as ToolChoiceType, aS as ToolChoiceTypes, ac as ToolHandler, aO as ToolType, aN as ToolTypes, aa as TypedFunctionTool, ab as TypedToolCall, az as Usage, aB as UsageSummary, aQ as XSearchConfig, ao as asModelId, an as asProviderId, ap as asTierCode, K as assistantMessageWithToolCalls, B as createAssistantMessage, N as createFunctionCall, s as createFunctionTool, a6 as createRetryMessages, E as createSystemMessage, L as createToolCall, t as createTypedTool, aA as createUsage, z as createUserMessage, a7 as executeWithRetry, y as firstToolCall, a3 as formatToolErrorForModel, W as getAllToolCalls, $ as getAssistantText, a5 as getRetryableErrors, V as getToolArgs, U as getToolArgsRaw, Q as getToolName, X as getTypedToolCall, Y as getTypedToolCalls, a4 as hasRetryableErrors, x as hasToolCalls, b0 as mergeMetrics, b1 as mergeTrace, b5 as modelToString, b4 as normalizeModelId, b2 as normalizeStopReason, _ as parseTypedToolCall, J as respondToToolCall, b3 as stopReasonToString, u as toolChoiceAuto, w as toolChoiceNone, v as toolChoiceRequired, H as toolResultMessage, a1 as zodToJsonSchema } from './tools-DHCGz_lx.cjs';
+import { c as components, $ as $defs, o as operations, p as paths, w as webhooks } from './api-CdHqjsU_.cjs';
+import { z } from 'zod';
 
 interface RequestOptions {
     method?: string;
@@ -130,6 +131,7 @@ type ResponsesRequest = {
 type WireResponsesRequest = {
     provider?: ProviderId;
     model?: ModelId;
+    state_id?: string;
     input: InputItem[];
     output_format?: OutputFormat;
     max_output_tokens?: number;
@@ -351,10 +353,32 @@ declare class ResponseBuilder {
     private readonly options;
     constructor(body?: Partial<WireResponsesRequest>, options?: ResponsesRequestOptions);
     private with;
-    /** @returns A new builder with the provider set. */
-    provider(provider: ProviderId): ResponseBuilder;
-    /** @returns A new builder with the model set. */
-    model(model: ModelId): ResponseBuilder;
+    /**
+     * Set the provider for this request.
+     *
+     * Accepts either a string or ProviderId for convenience.
+     *
+     * @example
+     * ```typescript
+     * .provider("anthropic")  // String works
+     * .provider(asProviderId("anthropic"))  // ProviderId also works
+     * ```
+     */
+    provider(provider: string | ProviderId): ResponseBuilder;
+    /**
+     * Set the model for this request.
+     *
+     * Accepts either a string or ModelId for convenience.
+     *
+     * @example
+     * ```typescript
+     * .model("claude-sonnet-4-5")  // String works
+     * .model(asModelId("claude-sonnet-4-5"))  // ModelId also works
+     * ```
+     */
+    model(model: string | ModelId): ResponseBuilder;
+    /** @returns A new builder with state-scoped tool state. */
+    stateId(stateId: string): ResponseBuilder;
     /** @returns A new builder with the full input array replaced. */
     input(items: InputItem[]): ResponseBuilder;
     /** @returns A new builder with the input item appended. */
@@ -417,6 +441,86 @@ declare class ResponseBuilder {
     streamTotalTimeoutMs(timeoutMs: number): ResponseBuilder;
     /** @returns A new builder with the abort signal set. */
     signal(signal: AbortSignal): ResponseBuilder;
+    /**
+     * Add an assistant message with tool calls from a previous response.
+     *
+     * This is useful for continuing a conversation after handling tool calls.
+     *
+     * @example
+     * ```typescript
+     * const response = await mr.responses.create(request);
+     * if (hasToolCalls(response)) {
+     *   const toolCalls = response.output[0].toolCalls!;
+     *   const results = await registry.executeAll(toolCalls);
+     *
+     *   const followUp = await mr.responses.create(
+     *     mr.responses.new()
+     *       .model("claude-sonnet-4-5")
+     *       .user("What's the weather in Paris?")
+     *       .assistantToolCalls(toolCalls)
+     *       .toolResults(results.map(r => ({ id: r.toolCallId, result: r.result })))
+     *       .build()
+     *   );
+     * }
+     * ```
+     */
+    assistantToolCalls(toolCalls: ToolCall[], content?: string): ResponseBuilder;
+    /**
+     * Add tool results to the conversation.
+     *
+     * @example
+     * ```typescript
+     * .toolResults([
+     *   { id: "call_123", result: { temp: 72 } },
+     *   { id: "call_456", result: "File contents here" },
+     * ])
+     * ```
+     */
+    toolResults(results: Array<{
+        id: string;
+        result: unknown;
+    }>): ResponseBuilder;
+    /**
+     * Add a single tool result to the conversation.
+     *
+     * @example
+     * ```typescript
+     * .toolResult("call_123", { temp: 72, unit: "fahrenheit" })
+     * ```
+     */
+    toolResult(toolCallId: string, result: unknown): ResponseBuilder;
+    /**
+     * Continue from a previous response that contains tool calls.
+     *
+     * This is the most ergonomic way to continue a conversation after handling tools.
+     * It automatically adds the assistant's tool call message and your tool results.
+     *
+     * @example
+     * ```typescript
+     * const response = await mr.responses.create(request);
+     *
+     * if (hasToolCalls(response)) {
+     *   const toolCalls = response.output[0].toolCalls!;
+     *   const results = await registry.executeAll(toolCalls);
+     *
+     *   const followUp = await mr.responses.create(
+     *     mr.responses.new()
+     *       .model("claude-sonnet-4-5")
+     *       .tools(myTools)
+     *       .user("What's the weather in Paris?")
+     *       .continueFrom(response, results.map(r => ({
+     *         id: r.toolCallId,
+     *         result: r.result,
+     *       })))
+     *       .build()
+     *   );
+     * }
+     * ```
+     */
+    continueFrom(response: Response$1, toolResults: Array<{
+        id: string;
+        result: unknown;
+    }>): ResponseBuilder;
     /** @returns A finalized, immutable request payload. */
     build(): ResponsesRequest;
 }
@@ -656,7 +760,7 @@ declare const WorkflowKinds: {
 };
 type WorkflowKindIntent = (typeof WorkflowKinds)["WorkflowIntent"];
 type WorkflowKind = WorkflowKindIntent;
-declare const WorkflowNodeTypesLite: {
+declare const WorkflowNodeTypesIntent: {
     readonly LLM: "llm";
     readonly JoinAll: "join.all";
     readonly JoinAny: "join.any";
@@ -664,7 +768,7 @@ declare const WorkflowNodeTypesLite: {
     readonly TransformJSON: "transform.json";
     readonly MapFanout: "map.fanout";
 };
-type WorkflowNodeTypeLite = (typeof WorkflowNodeTypesLite)[keyof typeof WorkflowNodeTypesLite];
+type WorkflowNodeTypeIntent = (typeof WorkflowNodeTypesIntent)[keyof typeof WorkflowNodeTypesIntent];
 type WorkflowIntentConditionSource = "node_output" | "node_status";
 type WorkflowIntentConditionOp = "equals" | "matches" | "exists";
 type WorkflowIntentCondition = {
@@ -679,7 +783,7 @@ type WorkflowIntentTransformValue = {
 };
 type WorkflowIntentNode = {
     id: NodeId$1;
-    type: WorkflowNodeTypeLite;
+    type: WorkflowNodeTypeIntent;
     depends_on?: ReadonlyArray<NodeId$1>;
     model?: string;
     system?: string;
@@ -702,17 +806,26 @@ type WorkflowIntentNode = {
     object?: Record<string, WorkflowIntentTransformValue>;
     merge?: Array<WorkflowIntentTransformValue>;
 };
-type WorkflowOutputRefLiteV1 = {
+type WorkflowOutputRefIntentV1 = {
     name: OutputName$1;
     from: NodeId$1;
     pointer?: string;
 };
-type WorkflowSpecLiteV1 = {
+type WorkflowInputDeclIntentV1 = {
+    name: string;
+    type?: string;
+    required?: boolean;
+    description?: string;
+    default?: unknown;
+};
+type WorkflowSpecIntentV1 = {
     kind: WorkflowKindIntent;
     name?: string;
     model?: string;
+    max_parallelism?: number;
+    inputs?: ReadonlyArray<WorkflowInputDeclIntentV1>;
     nodes: ReadonlyArray<WorkflowIntentNode>;
-    outputs: ReadonlyArray<WorkflowOutputRefLiteV1>;
+    outputs: ReadonlyArray<WorkflowOutputRefIntentV1>;
 };
 type RunStatusV0 = "running" | "waiting" | "succeeded" | "failed" | "canceled";
 type PayloadInfoV0$1 = {
@@ -720,7 +833,7 @@ type PayloadInfoV0$1 = {
     sha256: string;
     included: boolean;
 };
-type RunEventTypeV0 = "run_compiled" | "run_started" | "run_completed" | "run_failed" | "run_canceled" | "node_llm_call" | "node_tool_call" | "node_tool_result" | "node_waiting" | "node_started" | "node_succeeded" | "node_failed" | "node_output_delta" | "node_output";
+type RunEventTypeV0 = "run_compiled" | "run_started" | "run_completed" | "run_failed" | "run_canceled" | "node_llm_call" | "node_tool_call" | "node_tool_result" | "node_waiting" | "node_user_ask" | "node_user_answer" | "node_started" | "node_succeeded" | "node_failed" | "node_output_delta" | "node_output";
 type NodeErrorV0$1 = {
     code?: string;
     message: string;
@@ -784,6 +897,25 @@ type NodeWaitingV0$1 = {
     pending_tool_calls: PendingToolCallV0$1[];
     reason: string;
 };
+type UserAskOptionV0 = {
+    label: string;
+    description?: string;
+};
+type NodeUserAskV0 = {
+    step: number;
+    request_id: string;
+    tool_call: ToolCallWithArgumentsV0$1;
+    question: string;
+    options?: UserAskOptionV0[];
+    allow_freeform: boolean;
+};
+type NodeUserAnswerV0 = {
+    step: number;
+    request_id: string;
+    tool_call: ToolCallV0$1;
+    answer: string;
+    is_freeform: boolean;
+};
 type RunEventBaseV0 = {
     envelope_version: "v2";
     run_id: RunId$1;
@@ -846,6 +978,16 @@ type RunEventNodeWaitingV0 = RunEventBaseV0 & {
     node_id: NodeId$1;
     waiting: NodeWaitingV0$1;
 };
+type RunEventNodeUserAskV0 = RunEventBaseV0 & {
+    type: "node_user_ask";
+    node_id: NodeId$1;
+    user_ask: NodeUserAskV0;
+};
+type RunEventNodeUserAnswerV0 = RunEventBaseV0 & {
+    type: "node_user_answer";
+    node_id: NodeId$1;
+    user_answer: NodeUserAnswerV0;
+};
 type RunEventNodeOutputDeltaV0 = RunEventBaseV0 & {
     type: "node_output_delta";
     node_id: NodeId$1;
@@ -856,7 +998,7 @@ type RunEventNodeOutputV0 = RunEventBaseV0 & {
     node_id: NodeId$1;
     output: PayloadArtifactV0$1;
 };
-type RunEventV0 = RunEventRunCompiledV0 | RunEventRunStartedV0 | RunEventRunCompletedV0 | RunEventRunFailedV0 | RunEventRunCanceledV0 | RunEventNodeLLMCallV0 | RunEventNodeToolCallV0 | RunEventNodeToolResultV0 | RunEventNodeWaitingV0 | RunEventNodeStartedV0 | RunEventNodeSucceededV0 | RunEventNodeFailedV0 | RunEventNodeOutputDeltaV0 | RunEventNodeOutputV0;
+type RunEventV0 = RunEventRunCompiledV0 | RunEventRunStartedV0 | RunEventRunCompletedV0 | RunEventRunFailedV0 | RunEventRunCanceledV0 | RunEventNodeLLMCallV0 | RunEventNodeToolCallV0 | RunEventNodeToolResultV0 | RunEventNodeWaitingV0 | RunEventNodeUserAskV0 | RunEventNodeUserAnswerV0 | RunEventNodeStartedV0 | RunEventNodeSucceededV0 | RunEventNodeFailedV0 | RunEventNodeOutputDeltaV0 | RunEventNodeOutputV0;
 
 type NodeStatusV0 = "pending" | "running" | "waiting" | "succeeded" | "failed" | "canceled";
 type RunsToolResultsRequest = {
@@ -955,6 +1097,16 @@ type RunsCreateOptions = {
     sessionId?: string;
     idempotencyKey?: string;
     input?: Record<string, unknown>;
+    modelOverride?: string;
+    modelOverrides?: {
+        nodes?: Record<string, string>;
+        fanoutSubnodes?: Array<{
+            parentId: string;
+            subnodeId: string;
+            model: string;
+        }>;
+    };
+    stream?: boolean;
     signal?: AbortSignal;
     headers?: Record<string, string>;
     timeoutMs?: number;
@@ -1015,7 +1167,20 @@ declare class RunsClient {
         trace?: TraceCallbacks;
     });
     private applyCustomerHeader;
-    create(spec: WorkflowSpecLiteV1, options?: RunsCreateOptions): Promise<RunsCreateResponse>;
+    create(spec: WorkflowSpecIntentV1, options?: RunsCreateOptions): Promise<RunsCreateResponse>;
+    /**
+     * Starts a workflow run using a precompiled plan hash.
+     *
+     * Use workflows.compile() to compile a workflow spec and obtain a plan_hash,
+     * then use this method to start runs without re-compiling each time.
+     * This is useful for workflows that are run repeatedly with the same structure
+     * but different inputs.
+     *
+     * The plan_hash must have been compiled in the current server session;
+     * if the server has restarted since compilation, the plan will not be found
+     * and you'll need to recompile.
+     */
+    createFromPlan(planHash: PlanHash$1, options?: RunsCreateOptions): Promise<RunsCreateResponse>;
     runEventSchemaV0(options?: {
         signal?: AbortSignal;
         headers?: Record<string, string>;
@@ -1162,6 +1327,14 @@ declare class PathEscapeError extends ModelRelayError {
         resolvedPath: string;
     });
 }
+/**
+ * Error thrown when the agent exceeds its maximum turn limit without completing.
+ * This means the model kept requesting tool calls for more turns than allowed.
+ */
+declare class AgentMaxTurnsError extends ModelRelayError {
+    readonly maxTurns: number;
+    constructor(maxTurns: number);
+}
 declare function parseErrorResponse(response: Response, retries?: RetryMetadata): Promise<ModelRelayError>;
 
 type WorkflowsCompileOptions = {
@@ -1207,7 +1380,7 @@ declare class WorkflowsClient {
         metrics?: MetricsCallbacks;
         trace?: TraceCallbacks;
     });
-    compile(spec: WorkflowSpecLiteV1, options?: WorkflowsCompileOptions): Promise<WorkflowsCompileResult>;
+    compile(spec: WorkflowSpecIntentV1, options?: WorkflowsCompileOptions): Promise<WorkflowsCompileResult>;
 }
 
 /**
@@ -1304,6 +1477,64 @@ declare class ImagesClient {
     unpin(imageId: string): Promise<ImagePinResponse>;
 }
 
+type StateHandleCreateRequest = components["schemas"]["StateHandleCreateRequest"];
+type StateHandleResponse = components["schemas"]["StateHandleResponse"];
+type StateHandleListResponse = components["schemas"]["StateHandleListResponse"];
+/** Maximum allowed TTL for a state handle (1 year in seconds). */
+declare const MAX_STATE_HANDLE_TTL_SECONDS = 31536000;
+declare class StateHandlesClient {
+    private readonly http;
+    private readonly auth;
+    constructor(http: HTTPClient, auth: AuthClient);
+    /** Make an authenticated request to the state handles API. */
+    private request;
+    create(request?: StateHandleCreateRequest): Promise<StateHandleResponse>;
+    list(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<StateHandleListResponse>;
+    delete(stateId: string): Promise<void>;
+}
+
+type ContextManagementStrategy = "truncate" | "summarize";
+interface ContextTruncateInfo {
+    readonly model: ModelId;
+    readonly originalMessages: number;
+    readonly keptMessages: number;
+    readonly maxHistoryTokens: number;
+    readonly reservedOutputTokens?: number;
+}
+interface ContextManagerOptions {
+    strategy?: ContextManagementStrategy;
+    maxHistoryTokens?: number;
+    reserveOutputTokens?: number;
+    onTruncate?: (info: ContextTruncateInfo) => void;
+}
+interface ContextPrepareOptions extends ContextManagerOptions {
+    model?: ModelId;
+}
+interface ModelContextWindow {
+    contextWindow: number;
+    maxOutputTokens?: number;
+}
+type ModelContextResolver = (modelId: ModelId) => Promise<ModelContextWindow | null>;
+type ModelListClient = {
+    http: {
+        json: <T>(path: string, options?: {
+            method?: string;
+        }) => Promise<T>;
+    };
+};
+declare function createModelContextResolver(client: ModelListClient): ModelContextResolver;
+declare class ContextManager {
+    private readonly resolveModelContext;
+    private readonly defaults;
+    constructor(resolveModelContext: ModelContextResolver, defaults?: ContextManagerOptions);
+    prepare(input: InputItem[], options?: ContextPrepareOptions): Promise<InputItem[]>;
+}
+declare function prepareInputWithContext(input: InputItem[], options: ContextPrepareOptions, resolveModelContext: ModelContextResolver): Promise<InputItem[]>;
+declare function truncateInputByTokens(input: InputItem[], maxHistoryTokens: number): InputItem[];
+
 /**
  * Session types for multi-turn conversations.
  *
@@ -1417,12 +1648,16 @@ interface SessionRunResult {
     readonly pendingTools?: SessionPendingToolCall[];
     /** Error message (when status is 'error'). */
     readonly error?: string;
-    /** The run ID from the server. */
-    readonly runId: RunId$1;
+    /** The original error that caused the failure (when status is 'error'). */
+    readonly cause?: Error;
+    /** The response object for responses-based runs. */
+    readonly response?: Response$1;
+    /** The run ID from the server (when using /runs). */
+    readonly runId?: RunId$1;
     /** Token and call usage. */
     readonly usage: SessionUsageSummary;
-    /** All events from this run. */
-    readonly events: RunEventV0[];
+    /** All events from this run (when using /runs). */
+    readonly events?: RunEventV0[];
 }
 /**
  * Session type discriminator.
@@ -1485,16 +1720,22 @@ type LocalSessionPersistence = "memory" | "file" | "sqlite";
 interface LocalSessionOptions {
     /** Tool registry for handling tool calls. */
     toolRegistry?: ToolRegistry;
+    /** Optional context manager for input truncation or summarization. */
+    contextManager?: ContextManager;
     /** Default model for runs (can be overridden per-run). */
     defaultModel?: ModelId;
     /** Default provider for runs (can be overridden per-run). */
     defaultProvider?: ProviderId;
     /** Default tools for runs (merged with per-run tools). */
     defaultTools?: Tool[];
+    /** System prompt to prepend to all conversations. */
+    systemPrompt?: string;
     /** Persistence mode (default: 'memory'). */
     persistence?: LocalSessionPersistence;
-    /** Storage path for file/sqlite persistence (default: ~/.modelrelay/sessions/). */
+    /** Storage path for file/sqlite persistence (default: ~/.modelrelay/sessions or ~/.modelrelay/sessions.sqlite). */
     storagePath?: string;
+    /** Custom conversation store (overrides persistence/storagePath). */
+    conversationStore?: ConversationStore;
     /** Session ID to use (default: generate new). */
     sessionId?: SessionId;
     /** Session metadata. */
@@ -1548,7 +1789,7 @@ interface RemoteSessionInfo {
 /**
  * Serialized session state for persistence.
  */
-interface SessionState {
+interface ConversationState {
     id: SessionId;
     messages: SessionMessage[];
     artifacts: Record<string, unknown>;
@@ -1557,13 +1798,13 @@ interface SessionState {
     updatedAt: string;
 }
 /**
- * Interface for session storage backends.
+ * Interface for conversation storage backends.
  */
-interface SessionStore {
-    /** Load a session by ID. Returns null if not found. */
-    load(id: SessionId): Promise<SessionState | null>;
-    /** Save a session state. */
-    save(state: SessionState): Promise<void>;
+interface ConversationStore {
+    /** Load a conversation by ID. Returns null if not found. */
+    load(id: SessionId): Promise<ConversationState | null>;
+    /** Save a conversation state. */
+    save(state: ConversationState): Promise<void>;
     /** Delete a session by ID. */
     delete(id: SessionId): Promise<void>;
     /** List all session IDs. */
@@ -1763,21 +2004,17 @@ declare class LocalSession implements Session {
     private readonly client;
     private readonly store;
     private readonly toolRegistry?;
+    private readonly contextManager?;
     private readonly defaultModel?;
     private readonly defaultProvider?;
     private readonly defaultTools?;
+    private readonly systemPrompt?;
     private readonly metadata;
-    private readonly resolveModelContext;
     private messages;
     private artifacts;
-    private nextSeq;
     private createdAt;
     private updatedAt;
-    private currentRunId?;
-    private currentNodeId?;
-    private currentWaiting?;
-    private currentEvents;
-    private currentUsage;
+    private pendingLoop?;
     private constructor();
     /**
      * Create a new local session.
@@ -1803,34 +2040,11 @@ declare class LocalSession implements Session {
     close(): Promise<void>;
     /**
      * Sync this local session's messages to a remote session.
-     *
-     * This uploads all local messages to the remote session, enabling
-     * cross-device access and server-side backup. Messages are synced
-     * in order and the remote session's history will contain all local
-     * messages after sync completes.
-     *
-     * @param remoteSession - The remote session to sync to
-     * @param options - Optional sync configuration
-     * @returns Sync result with message count
-     *
-     * @example
-     * ```typescript
-     * // Create local session and work offline
-     * const local = LocalSession.create(client, { ... });
-     * await local.run("Implement the feature");
-     *
-     * // Later, sync to remote for backup/sharing
-     * const remote = await RemoteSession.create(client);
-     * const result = await local.syncTo(remote, {
-     *   onProgress: (synced, total) => console.log(`${synced}/${total}`),
-     * });
-     * ```
      */
     syncTo(remoteSession: RemoteSession, options?: SessionSyncOptions): Promise<SessionSyncResult>;
-    private addMessage;
-    private buildInput;
-    private processRunEvents;
-    private executeTools;
+    private buildContextOptions;
+    private prepareInput;
+    private replaceHistory;
     private persist;
 }
 /**
@@ -2081,6 +2295,220 @@ declare class TiersClient {
     checkout(tierId: string, request: TierCheckoutRequest): Promise<TierCheckoutSession>;
 }
 
+type PluginId = string & {
+    readonly __brand: "PluginId";
+};
+type PluginUrl = string & {
+    readonly __brand: "PluginUrl";
+};
+type PluginCommandName = string & {
+    readonly __brand: "PluginCommandName";
+};
+type PluginAgentName = string & {
+    readonly __brand: "PluginAgentName";
+};
+declare const PluginToolNames: {
+    readonly FS_READ_FILE: "fs.read_file";
+    readonly FS_LIST_FILES: "fs.list_files";
+    readonly FS_SEARCH: "fs.search";
+    readonly FS_EDIT: "fs.edit";
+    readonly BASH: "bash";
+    readonly WRITE_FILE: "write_file";
+    readonly USER_ASK: "user.ask";
+};
+type PluginToolName = (typeof PluginToolNames)[keyof typeof PluginToolNames];
+declare const OrchestrationModes: {
+    readonly DAG: "dag";
+    readonly Dynamic: "dynamic";
+};
+type OrchestrationMode = (typeof OrchestrationModes)[keyof typeof OrchestrationModes];
+type PluginManifest = {
+    name?: string;
+    description?: string;
+    version?: string;
+    commands?: PluginCommandName[];
+    agents?: PluginAgentName[];
+};
+type PluginCommand = {
+    name: PluginCommandName;
+    prompt: string;
+    agentRefs?: PluginAgentName[];
+    tools?: PluginToolName[];
+};
+type PluginAgent = {
+    name: PluginAgentName;
+    systemPrompt: string;
+    description?: string;
+    tools?: PluginToolName[];
+};
+type Plugin = {
+    id: PluginId;
+    url: PluginUrl;
+    manifest: PluginManifest;
+    commands: Record<string, PluginCommand>;
+    agents: Record<string, PluginAgent>;
+    rawFiles: Record<string, string>;
+    ref: PluginGitHubRef;
+    loadedAt: Date;
+};
+type PluginGitHubRef = {
+    owner: string;
+    repo: string;
+    ref: string;
+    path?: string;
+};
+type PluginRunConfig = {
+    model?: string | ModelId;
+    converterModel?: string | ModelId;
+    orchestrationMode?: OrchestrationMode;
+    userTask: string;
+    toolRegistry?: ToolRegistry;
+    runOptions?: RunsCreateOptions;
+};
+type PluginRunResult = {
+    runId: RunId$1;
+    status: RunStatusV0;
+    outputs?: Record<string, unknown>;
+    costSummary?: Record<string, unknown>;
+    events: RunEventV0[];
+};
+type PluginLoaderOptions = {
+    fetch?: typeof fetch;
+    apiBaseUrl?: string;
+    rawBaseUrl?: string;
+    cacheTtlMs?: number;
+    now?: () => Date;
+};
+type PluginConverterOptions = {
+    converterModel?: string | ModelId;
+};
+type PluginsClientOptions = {
+    fetch?: typeof fetch;
+    apiBaseUrl?: string;
+    rawBaseUrl?: string;
+    cacheTtlMs?: number;
+    now?: () => Date;
+};
+declare const PluginOrchestrationErrorCodes: {
+    readonly InvalidPlan: "INVALID_PLAN";
+    readonly UnknownAgent: "UNKNOWN_AGENT";
+    readonly MissingDescription: "MISSING_DESCRIPTION";
+    readonly UnknownTool: "UNKNOWN_TOOL";
+    readonly InvalidDependency: "INVALID_DEPENDENCY";
+    readonly InvalidToolConfig: "INVALID_TOOL_CONFIG";
+};
+type PluginOrchestrationErrorCode = (typeof PluginOrchestrationErrorCodes)[keyof typeof PluginOrchestrationErrorCodes];
+declare class PluginOrchestrationError extends Error {
+    readonly code: PluginOrchestrationErrorCode;
+    constructor(code: PluginOrchestrationErrorCode, message: string);
+}
+declare const orchestrationPlanSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"orchestration.plan.v1">;
+    max_parallelism: z.ZodOptional<z.ZodNumber>;
+    steps: z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        depends_on: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        agents: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            reason: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            id: string;
+            reason: string;
+        }, {
+            id: string;
+            reason: string;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        agents: {
+            id: string;
+            reason: string;
+        }[];
+        id?: string | undefined;
+        depends_on?: string[] | undefined;
+    }, {
+        agents: {
+            id: string;
+            reason: string;
+        }[];
+        id?: string | undefined;
+        depends_on?: string[] | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    kind: "orchestration.plan.v1";
+    steps: {
+        agents: {
+            id: string;
+            reason: string;
+        }[];
+        id?: string | undefined;
+        depends_on?: string[] | undefined;
+    }[];
+    max_parallelism?: number | undefined;
+}, {
+    kind: "orchestration.plan.v1";
+    steps: {
+        agents: {
+            id: string;
+            reason: string;
+        }[];
+        id?: string | undefined;
+        depends_on?: string[] | undefined;
+    }[];
+    max_parallelism?: number | undefined;
+}>;
+type OrchestrationPlan = z.infer<typeof orchestrationPlanSchema>;
+declare class PluginLoader {
+    private readonly fetchFn;
+    private readonly apiBaseUrl;
+    private readonly rawBaseUrl;
+    private readonly cacheTtlMs;
+    private readonly now;
+    private readonly cache;
+    constructor(options?: PluginLoaderOptions);
+    load(sourceUrl: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Plugin>;
+    private listMarkdownFiles;
+    private rawUrl;
+    private fetchText;
+    private fetchJson;
+}
+declare class PluginConverter {
+    private readonly responses;
+    private readonly http;
+    private readonly auth;
+    private readonly converterModel;
+    constructor(responses: ResponsesClient, http: HTTPClient, auth: AuthClient, options?: PluginConverterOptions);
+    toWorkflow(plugin: Plugin, commandName: string, task: string): Promise<WorkflowSpecIntentV1>;
+    toWorkflowDynamic(plugin: Plugin, commandName: string, task: string): Promise<WorkflowSpecIntentV1>;
+}
+declare class PluginRunner {
+    private readonly runs;
+    constructor(runs: RunsClient);
+    run(spec: WorkflowSpecIntentV1, config: PluginRunConfig): Promise<PluginRunResult>;
+    wait(runId: RunId$1, config: PluginRunConfig): Promise<PluginRunResult>;
+}
+declare class PluginsClient {
+    private readonly loader;
+    private readonly converter;
+    private readonly runner;
+    private readonly responses;
+    private readonly http;
+    private readonly auth;
+    constructor(deps: {
+        responses: ResponsesClient;
+        http: HTTPClient;
+        auth: AuthClient;
+        runs: RunsClient;
+        options?: PluginsClientOptions;
+    });
+    load(url: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Plugin>;
+    run(plugin: Plugin, command: string, config: PluginRunConfig): Promise<PluginRunResult>;
+    quickRun(pluginUrl: string, command: string, userTask: string, config?: Omit<PluginRunConfig, "userTask">): Promise<PluginRunResult>;
+}
+
 declare class CustomerResponsesClient {
     private readonly base;
     private readonly customerId;
@@ -2101,6 +2529,151 @@ declare class CustomerScopedModelRelay {
     constructor(responses: ResponsesClient, customerId: string, baseUrl: string);
 }
 
+/**
+ * Fluent tool builder for defining tools with Zod schemas and handlers.
+ *
+ * This provides a more ergonomic way to define tools compared to using
+ * createFunctionTool and ToolRegistry separately.
+ */
+
+/**
+ * Fluent builder for defining tools with Zod schemas.
+ *
+ * Tools defined with this builder include both the JSON Schema for the API
+ * and the handler function for execution, providing a single source of truth.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ *
+ * const tools = new ToolBuilder()
+ *   .add(
+ *     "get_weather",
+ *     "Get current weather for a location",
+ *     z.object({ location: z.string().describe("City name") }),
+ *     async (args) => ({ temp: 72, unit: "fahrenheit" })
+ *   )
+ *   .add(
+ *     "read_file",
+ *     "Read a file from disk",
+ *     z.object({ path: z.string().describe("File path") }),
+ *     async (args) => fs.readFile(args.path, "utf-8")
+ *   );
+ *
+ * // Get the tool registry for use with LocalSession or mr.agent()
+ * const registry = tools.registry();
+ *
+ * // Get tool definitions for use with ResponseBuilder
+ * const defs = tools.definitions();
+ * ```
+ */
+declare class ToolBuilder {
+    private entries;
+    /**
+     * Add a tool with a Zod schema and handler.
+     *
+     * The handler receives parsed and validated arguments matching the schema.
+     *
+     * @param name - Tool name (must be unique)
+     * @param description - Human-readable description of what the tool does
+     * @param schema - Zod schema for the tool's parameters
+     * @param handler - Function to execute when the tool is called
+     * @returns this for chaining
+     *
+     * @example
+     * ```typescript
+     * tools.add(
+     *   "search_web",
+     *   "Search the web for information",
+     *   z.object({
+     *     query: z.string().describe("Search query"),
+     *     maxResults: z.number().optional().describe("Max results to return"),
+     *   }),
+     *   async (args) => {
+     *     // args is typed as { query: string; maxResults?: number }
+     *     return await searchAPI(args.query, args.maxResults);
+     *   }
+     * );
+     * ```
+     */
+    add<S extends AnySchema, R>(name: string, description: string, schema: S, handler: (args: S extends {
+        parse(data: unknown): infer T;
+    } ? T : unknown, call: ToolCall) => R | Promise<R>): this;
+    /**
+     * Get tool definitions for use with ResponseBuilder.tools().
+     *
+     * @example
+     * ```typescript
+     * const response = await mr.responses.create(
+     *   mr.responses.new()
+     *     .model("claude-sonnet-4-5")
+     *     .tools(tools.definitions())
+     *     .user("What's the weather in Paris?")
+     *     .build()
+     * );
+     * ```
+     */
+    definitions(): Tool[];
+    /**
+     * Get a ToolRegistry with all handlers registered.
+     *
+     * The handlers are wrapped to validate arguments against the schema
+     * before invoking the user's handler. If validation fails, a
+     * ToolArgsError is thrown (which ToolRegistry marks as retryable).
+     *
+     * Note: For mr.agent(), pass the ToolBuilder directly instead of calling
+     * registry(). The agent method extracts both definitions and registry.
+     *
+     * @example
+     * ```typescript
+     * const registry = tools.registry();
+     *
+     * // Use with LocalSession (also pass definitions via defaultTools)
+     * const session = mr.sessions.createLocal({
+     *   toolRegistry: registry,
+     *   defaultTools: tools.definitions(),
+     *   defaultModel: "claude-sonnet-4-5",
+     * });
+     * ```
+     */
+    registry(): ToolRegistry;
+    /**
+     * Get both definitions and registry.
+     *
+     * Useful when you need both for manual tool handling.
+     *
+     * @example
+     * ```typescript
+     * const { definitions, registry } = tools.build();
+     *
+     * const response = await mr.responses.create(
+     *   mr.responses.new()
+     *     .model("claude-sonnet-4-5")
+     *     .tools(definitions)
+     *     .user("What's the weather?")
+     *     .build()
+     * );
+     *
+     * if (hasToolCalls(response)) {
+     *   const results = await registry.executeAll(response.output[0].toolCalls!);
+     *   // ...
+     * }
+     * ```
+     */
+    build(): {
+        definitions: Tool[];
+        registry: ToolRegistry;
+    };
+    /**
+     * Get the number of tools defined.
+     */
+    get size(): number;
+    /**
+     * Check if a tool is defined.
+     */
+    has(name: string): boolean;
+}
+
 declare class CustomerTokenProvider implements TokenProvider {
     private readonly auth;
     private readonly req;
@@ -2253,9 +2826,11 @@ type WorkflowIntentEdge = {
 type WorkflowIntentBuilderState = {
     readonly name?: string;
     readonly model?: string;
+    readonly maxParallelism?: number;
+    readonly inputs?: ReadonlyArray<WorkflowInputDeclIntentV1>;
     readonly nodes: ReadonlyArray<WorkflowIntentNode>;
     readonly edges: ReadonlyArray<WorkflowIntentEdge>;
-    readonly outputs: ReadonlyArray<WorkflowOutputRefLiteV1>;
+    readonly outputs: ReadonlyArray<WorkflowOutputRefIntentV1>;
 };
 declare class WorkflowIntentBuilder {
     private readonly state;
@@ -2263,6 +2838,8 @@ declare class WorkflowIntentBuilder {
     private with;
     name(name: string): WorkflowIntentBuilder;
     model(model: string): WorkflowIntentBuilder;
+    maxParallelism(n: number): WorkflowIntentBuilder;
+    inputs(decls: ReadonlyArray<WorkflowInputDeclIntentV1>): WorkflowIntentBuilder;
     node(node: WorkflowIntentNode): WorkflowIntentBuilder;
     llm(id: NodeId$1, configure?: (node: LLMNodeBuilder) => LLMNodeBuilder): WorkflowIntentBuilder;
     joinAll(id: NodeId$1): WorkflowIntentBuilder;
@@ -2282,7 +2859,7 @@ declare class WorkflowIntentBuilder {
     }): WorkflowIntentBuilder;
     edge(from: NodeId$1, to: NodeId$1): WorkflowIntentBuilder;
     output(name: OutputName$1, from: NodeId$1, pointer?: string): WorkflowIntentBuilder;
-    build(): WorkflowSpecLiteV1;
+    build(): WorkflowSpecIntentV1;
 }
 declare class LLMNodeBuilder {
     private readonly node;
@@ -2355,7 +2932,7 @@ type ParallelOptions = {
 declare function parallel(steps: WorkflowIntentNode[], options?: ParallelOptions): WorkflowIntentBuilder;
 
 declare const WORKFLOWS_COMPILE_PATH = "/workflows/compile";
-type WorkflowsCompileRequest = WorkflowSpecLiteV1;
+type WorkflowsCompileRequest = WorkflowSpecIntentV1;
 
 type NDJSONDelayStep = {
     delayMs: number;
@@ -2377,6 +2954,62 @@ declare function parseApiKey(raw: string): ApiKey;
 declare function parseSecretKey(raw: string): SecretKey;
 declare function isSecretKey(key: ApiKey): key is SecretKey;
 
+type ToolLoopUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    llmCalls: number;
+    toolCalls: number;
+};
+type ToolLoopComplete = {
+    status: "complete";
+    output: string;
+    response: Response$1;
+    usage: ToolLoopUsage;
+    input: InputItem[];
+    turnsUsed: number;
+};
+type ToolLoopWaiting = {
+    status: "waiting_for_tools";
+    pendingToolCalls: ToolCall[];
+    response: Response$1;
+    usage: ToolLoopUsage;
+    input: InputItem[];
+    turnsUsed: number;
+};
+type ToolLoopOutcome = ToolLoopComplete | ToolLoopWaiting;
+type ToolLoopConfig = {
+    client: ResponsesClient;
+    input: InputItem[];
+    tools?: Tool[];
+    registry?: ToolRegistry;
+    maxTurns?: number;
+    requestOptions?: ResponsesRequestOptions;
+    buildRequest?: (builder: ResponseBuilder) => ResponseBuilder;
+};
+declare function runToolLoop(config: ToolLoopConfig): Promise<ToolLoopOutcome>;
+
+declare const USER_ASK_TOOL_NAME = "user.ask";
+type UserAskOption = {
+    label: string;
+    description?: string;
+};
+type UserAskArgs = {
+    question: string;
+    options?: UserAskOption[];
+    allow_freeform?: boolean;
+};
+type UserAskResponse = {
+    answer: string;
+    is_freeform: boolean;
+};
+declare function createUserAskTool(): Tool;
+declare function isUserAskToolCall(call: ToolCall): boolean;
+declare function parseUserAskArgs(call: ToolCall): UserAskArgs;
+declare function serializeUserAskResult(result: UserAskResponse): string;
+declare function userAskResultFreeform(answer: string): string;
+declare function userAskResultChoice(answer: string): string;
+
 /**
  * Tool runner for executing client-side tools in workflow runs.
  *
@@ -2400,6 +3033,8 @@ interface ToolRunnerOptions {
     onAfterExecute?: (result: ToolExecutionResult) => void | Promise<void>;
     /** Called when results are successfully submitted (optional). */
     onSubmitted?: (runId: RunId$1, count: number, status: RunStatusV0) => void | Promise<void>;
+    /** Called when a user.ask tool needs a response (optional). */
+    onUserAsk?: (pending: PendingToolCallV0$1, args: UserAskArgs) => Promise<UserAskResponse | string> | UserAskResponse | string;
     /** Called when an error occurs during execution (optional). */
     onError?: (error: Error, pending?: PendingToolCallV0$1) => void | Promise<void>;
 }
@@ -2445,6 +3080,7 @@ declare class ToolRunner {
     private readonly onBeforeExecute?;
     private readonly onAfterExecute?;
     private readonly onSubmitted?;
+    private readonly onUserAsk?;
     private readonly onError?;
     constructor(options: ToolRunnerOptions);
     /**
@@ -2537,15 +3173,15 @@ declare namespace index$1 {
 }
 
 /**
- * Workflow.lite.v1 types with clean naming (no Workflow prefix).
+ * Workflow intent types with clean naming (no Workflow prefix).
  *
  * @example
  * ```typescript
  * import { workflow } from "@modelrelay/sdk";
  *
- * const spec: workflow.SpecLiteV1 = {
+ * const spec: workflow.SpecIntentV1 = {
  *   kind: workflow.KindIntent,
- *   nodes: [{ id: "my_node", type: workflow.NodeTypesLite.LLM, user: "hello" }],
+ *   nodes: [{ id: "my_node", type: workflow.NodeTypesIntent.LLM, user: "hello" }],
  *   outputs: [],
  * };
  * ```
@@ -2557,9 +3193,9 @@ type RunId = RunId$1;
 type PlanHash = PlanHash$1;
 
 type Kind = WorkflowKind;
-type SpecLiteV1 = WorkflowSpecLiteV1;
+type SpecIntentV1 = WorkflowSpecIntentV1;
 type IntentNode = WorkflowIntentNode;
-type OutputRefLiteV1 = WorkflowOutputRefLiteV1;
+type OutputRefIntentV1 = WorkflowOutputRefIntentV1;
 type Condition = WorkflowIntentCondition;
 type ConditionOp = WorkflowIntentConditionOp;
 type ConditionSource = WorkflowIntentConditionSource;
@@ -2595,7 +3231,7 @@ type PayloadInfoV0 = PayloadInfoV0$1;
 type PayloadArtifactV0 = PayloadArtifactV0$1;
 type StreamEventKind = StreamEventKind$1;
 declare const KindIntent: "workflow";
-declare const NodeTypesLite: {
+declare const NodeTypesIntent: {
     readonly LLM: "llm";
     readonly JoinAll: "join.all";
     readonly JoinAny: "join.any";
@@ -2603,7 +3239,7 @@ declare const NodeTypesLite: {
     readonly TransformJSON: "transform.json";
     readonly MapFanout: "map.fanout";
 };
-type NodeTypeLite = (typeof NodeTypesLite)[keyof typeof NodeTypesLite];
+type NodeTypeIntent = (typeof NodeTypesIntent)[keyof typeof NodeTypesIntent];
 
 type index_Condition = Condition;
 type index_ConditionOp = ConditionOp;
@@ -2638,17 +3274,17 @@ type index_NodeLLMCallV0 = NodeLLMCallV0;
 type index_NodeOutputDeltaV0 = NodeOutputDeltaV0;
 type index_NodeToolCallV0 = NodeToolCallV0;
 type index_NodeToolResultV0 = NodeToolResultV0;
-type index_NodeTypeLite = NodeTypeLite;
-declare const index_NodeTypesLite: typeof NodeTypesLite;
+type index_NodeTypeIntent = NodeTypeIntent;
+declare const index_NodeTypesIntent: typeof NodeTypesIntent;
 type index_NodeWaitingV0 = NodeWaitingV0;
 type index_OutputName = OutputName;
-type index_OutputRefLiteV1 = OutputRefLiteV1;
+type index_OutputRefIntentV1 = OutputRefIntentV1;
 type index_PayloadArtifactV0 = PayloadArtifactV0;
 type index_PayloadInfoV0 = PayloadInfoV0;
 type index_PendingToolCallV0 = PendingToolCallV0;
 type index_PlanHash = PlanHash;
 type index_RunId = RunId;
-type index_SpecLiteV1 = SpecLiteV1;
+type index_SpecIntentV1 = SpecIntentV1;
 type index_StatusV0 = StatusV0;
 type index_StreamEventKind = StreamEventKind;
 type index_TokenUsageV0 = TokenUsageV0;
@@ -2662,11 +3298,11 @@ declare const index_parsePlanHash: typeof parsePlanHash;
 declare const index_parseRunId: typeof parseRunId;
 declare const index_workflowIntent: typeof workflowIntent;
 declare namespace index {
-  export { type index_Condition as Condition, type index_ConditionOp as ConditionOp, type index_ConditionSource as ConditionSource, type index_EventBaseV0 as EventBaseV0, type index_EventNodeFailedV0 as EventNodeFailedV0, type index_EventNodeLLMCallV0 as EventNodeLLMCallV0, type index_EventNodeOutputDeltaV0 as EventNodeOutputDeltaV0, type index_EventNodeOutputV0 as EventNodeOutputV0, type index_EventNodeStartedV0 as EventNodeStartedV0, type index_EventNodeSucceededV0 as EventNodeSucceededV0, type index_EventNodeToolCallV0 as EventNodeToolCallV0, type index_EventNodeToolResultV0 as EventNodeToolResultV0, type index_EventNodeWaitingV0 as EventNodeWaitingV0, type index_EventRunCanceledV0 as EventRunCanceledV0, type index_EventRunCompiledV0 as EventRunCompiledV0, type index_EventRunCompletedV0 as EventRunCompletedV0, type index_EventRunFailedV0 as EventRunFailedV0, type index_EventRunStartedV0 as EventRunStartedV0, type index_EventTypeV0 as EventTypeV0, type index_EventV0 as EventV0, type index_IntentNode as IntentNode, type index_Kind as Kind, index_KindIntent as KindIntent, index_LLMNodeBuilder as LLMNodeBuilder, index_LLM_TEXT_OUTPUT as LLM_TEXT_OUTPUT, index_LLM_USER_MESSAGE_TEXT as LLM_USER_MESSAGE_TEXT, type index_NodeErrorV0 as NodeErrorV0, type index_NodeId as NodeId, type index_NodeLLMCallV0 as NodeLLMCallV0, type index_NodeOutputDeltaV0 as NodeOutputDeltaV0, type index_NodeToolCallV0 as NodeToolCallV0, type index_NodeToolResultV0 as NodeToolResultV0, type index_NodeTypeLite as NodeTypeLite, index_NodeTypesLite as NodeTypesLite, type index_NodeWaitingV0 as NodeWaitingV0, type index_OutputName as OutputName, type index_OutputRefLiteV1 as OutputRefLiteV1, type index_PayloadArtifactV0 as PayloadArtifactV0, type index_PayloadInfoV0 as PayloadInfoV0, type index_PendingToolCallV0 as PendingToolCallV0, type index_PlanHash as PlanHash, type index_RunId as RunId, type index_SpecLiteV1 as SpecLiteV1, type index_StatusV0 as StatusV0, type index_StreamEventKind as StreamEventKind, type index_TokenUsageV0 as TokenUsageV0, type index_ToolCallV0 as ToolCallV0, type index_ToolCallWithArgumentsV0 as ToolCallWithArgumentsV0, index_WorkflowIntentBuilder as WorkflowIntentBuilder, index_parseNodeId as parseNodeId, index_parseOutputName as parseOutputName, index_parsePlanHash as parsePlanHash, index_parseRunId as parseRunId, index_workflowIntent as workflowIntent };
+  export { type index_Condition as Condition, type index_ConditionOp as ConditionOp, type index_ConditionSource as ConditionSource, type index_EventBaseV0 as EventBaseV0, type index_EventNodeFailedV0 as EventNodeFailedV0, type index_EventNodeLLMCallV0 as EventNodeLLMCallV0, type index_EventNodeOutputDeltaV0 as EventNodeOutputDeltaV0, type index_EventNodeOutputV0 as EventNodeOutputV0, type index_EventNodeStartedV0 as EventNodeStartedV0, type index_EventNodeSucceededV0 as EventNodeSucceededV0, type index_EventNodeToolCallV0 as EventNodeToolCallV0, type index_EventNodeToolResultV0 as EventNodeToolResultV0, type index_EventNodeWaitingV0 as EventNodeWaitingV0, type index_EventRunCanceledV0 as EventRunCanceledV0, type index_EventRunCompiledV0 as EventRunCompiledV0, type index_EventRunCompletedV0 as EventRunCompletedV0, type index_EventRunFailedV0 as EventRunFailedV0, type index_EventRunStartedV0 as EventRunStartedV0, type index_EventTypeV0 as EventTypeV0, type index_EventV0 as EventV0, type index_IntentNode as IntentNode, type index_Kind as Kind, index_KindIntent as KindIntent, index_LLMNodeBuilder as LLMNodeBuilder, index_LLM_TEXT_OUTPUT as LLM_TEXT_OUTPUT, index_LLM_USER_MESSAGE_TEXT as LLM_USER_MESSAGE_TEXT, type index_NodeErrorV0 as NodeErrorV0, type index_NodeId as NodeId, type index_NodeLLMCallV0 as NodeLLMCallV0, type index_NodeOutputDeltaV0 as NodeOutputDeltaV0, type index_NodeToolCallV0 as NodeToolCallV0, type index_NodeToolResultV0 as NodeToolResultV0, type index_NodeTypeIntent as NodeTypeIntent, index_NodeTypesIntent as NodeTypesIntent, type index_NodeWaitingV0 as NodeWaitingV0, type index_OutputName as OutputName, type index_OutputRefIntentV1 as OutputRefIntentV1, type index_PayloadArtifactV0 as PayloadArtifactV0, type index_PayloadInfoV0 as PayloadInfoV0, type index_PendingToolCallV0 as PendingToolCallV0, type index_PlanHash as PlanHash, type index_RunId as RunId, type index_SpecIntentV1 as SpecIntentV1, type index_StatusV0 as StatusV0, type index_StreamEventKind as StreamEventKind, type index_TokenUsageV0 as TokenUsageV0, type index_ToolCallV0 as ToolCallV0, type index_ToolCallWithArgumentsV0 as ToolCallWithArgumentsV0, index_WorkflowIntentBuilder as WorkflowIntentBuilder, index_parseNodeId as parseNodeId, index_parseOutputName as parseOutputName, index_parsePlanHash as parsePlanHash, index_parseRunId as parseRunId, index_workflowIntent as workflowIntent };
 }
 
 /**
- * In-memory session store.
+ * In-memory conversation store.
  *
  * Session data is lost when the process exits. Use for:
  * - Development/testing
@@ -2677,14 +3313,14 @@ declare namespace index {
  */
 
 /**
- * In-memory implementation of SessionStore.
+ * In-memory implementation of ConversationStore.
  *
  * All operations are synchronous but wrapped in promises for interface compatibility.
  */
-declare class MemorySessionStore implements SessionStore {
+declare class MemoryConversationStore implements ConversationStore {
     private readonly sessions;
-    load(id: SessionId): Promise<SessionState | null>;
-    save(state: SessionState): Promise<void>;
+    load(id: SessionId): Promise<ConversationState | null>;
+    save(state: ConversationState): Promise<void>;
     delete(id: SessionId): Promise<void>;
     list(): Promise<SessionId[]>;
     close(): Promise<void>;
@@ -2695,9 +3331,48 @@ declare class MemorySessionStore implements SessionStore {
     get size(): number;
 }
 /**
- * Create a new in-memory session store.
+ * Create a new in-memory conversation store.
+ */
+declare function createMemoryConversationStore(): MemoryConversationStore;
+
+/**
+ * File-based conversation store (Node.js/Bun only).
+ */
+
+declare class FileConversationStore implements ConversationStore {
+    private readonly storagePath?;
+    constructor(storagePath?: string);
+    load(id: SessionId): Promise<ConversationState | null>;
+    save(state: ConversationState): Promise<void>;
+    delete(id: SessionId): Promise<void>;
+    list(): Promise<SessionId[]>;
+    close(): Promise<void>;
+    private resolveSessionPath;
+    private resolveSessionDir;
+}
+declare function createFileConversationStore(storagePath?: string): FileConversationStore;
+
+/**
+ * SQLite-backed conversation store (Node.js/Bun only).
  */
-declare function createMemorySessionStore(): MemorySessionStore;
+
+declare class SqliteConversationStore implements ConversationStore {
+    private readonly storagePath?;
+    private db?;
+    private initPromise?;
+    private statements?;
+    constructor(storagePath?: string);
+    load(id: SessionId): Promise<ConversationState | null>;
+    save(state: ConversationState): Promise<void>;
+    delete(id: SessionId): Promise<void>;
+    list(): Promise<SessionId[]>;
+    close(): Promise<void>;
+    private ensureInitialized;
+    private getStatements;
+    private initialize;
+    private resolveDbPath;
+}
+declare function createSqliteConversationStore(storagePath?: string): SqliteConversationStore;
 
 declare class ModelRelay {
     readonly responses: ResponsesClient;
@@ -2706,7 +3381,9 @@ declare class ModelRelay {
     readonly images: ImagesClient;
     readonly auth: AuthClient;
     readonly sessions: SessionsClient;
+    readonly stateHandles: StateHandlesClient;
     readonly tiers: TiersClient;
+    readonly plugins: PluginsClient;
     readonly baseUrl: string;
     /** @internal HTTP client for internal use by session sync */
     readonly http: HTTPClient;
@@ -2714,6 +3391,138 @@ declare class ModelRelay {
     static fromApiKey(apiKey: string, options?: Omit<ModelRelayKeyOptions, "key">): ModelRelay;
     constructor(options: ModelRelayOptions);
     forCustomer(customerId: string): CustomerScopedModelRelay;
+    /** Default maximum turns for agent loops. */
+    static readonly DEFAULT_MAX_TURNS = 100;
+    /**
+     * Use this for maxTurns to disable the turn limit.
+     * Use with caution as this can lead to infinite loops and runaway API costs.
+     */
+    static readonly NO_TURN_LIMIT: number;
+    /**
+     * Simple chat completion with system and user prompt.
+     *
+     * Returns the full Response object for access to usage, model, etc.
+     *
+     * @example
+     * ```typescript
+     * const response = await mr.chat("claude-sonnet-4-5", "Hello!");
+     * console.log(response.output);
+     * console.log(response.usage);
+     * ```
+     *
+     * @example With system prompt
+     * ```typescript
+     * const response = await mr.chat("claude-sonnet-4-5", "Explain quantum computing", {
+     *   system: "You are a physics professor",
+     * });
+     * ```
+     */
+    chat(model: string | ModelId, prompt: string, options?: {
+        system?: string;
+        customerId?: string;
+    } & ResponsesRequestOptions): Promise<Response$1>;
+    /**
+     * Simple prompt that returns just the text response.
+     *
+     * The most ergonomic way to get a quick answer.
+     *
+     * @example
+     * ```typescript
+     * const answer = await mr.ask("claude-sonnet-4-5", "What is 2 + 2?");
+     * console.log(answer); // "4"
+     * ```
+     *
+     * @example With system prompt
+     * ```typescript
+     * const haiku = await mr.ask("claude-sonnet-4-5", "Write about the ocean", {
+     *   system: "You are a poet who only writes haikus",
+     * });
+     * ```
+     */
+    ask(model: string | ModelId, prompt: string, options?: {
+        system?: string;
+        customerId?: string;
+    } & ResponsesRequestOptions): Promise<string>;
+    /**
+     * Run an agentic tool loop to completion.
+     *
+     * Runs API calls in a loop until the model stops calling tools
+     * or maxTurns is reached.
+     *
+     * @example
+     * ```typescript
+     * import { z } from "zod";
+     *
+     * const tools = mr.tools()
+     *   .add("read_file", "Read a file", z.object({ path: z.string() }), async (args) => {
+     *     return fs.readFile(args.path, "utf-8");
+     *   })
+     *   .add("write_file", "Write a file", z.object({ path: z.string(), content: z.string() }), async (args) => {
+     *     await fs.writeFile(args.path, args.content);
+     *     return "File written successfully";
+     *   });
+     *
+     * const result = await mr.agent("claude-sonnet-4-5", {
+     *   tools,
+     *   prompt: "Read config.json and add a version field",
+     * });
+     *
+     * console.log(result.output);  // Final text response
+     * console.log(result.usage);   // Total tokens used
+     * ```
+     *
+     * @example With system prompt and maxTurns
+     * ```typescript
+     * const result = await mr.agent("claude-sonnet-4-5", {
+     *   tools,
+     *   prompt: "Refactor the auth module",
+     *   system: "You are a senior TypeScript developer",
+     *   maxTurns: 50, // or ModelRelay.NO_TURN_LIMIT for unlimited
+     * });
+     * ```
+     */
+    agent(model: string | ModelId, options: {
+        tools: ToolBuilder;
+        prompt: string;
+        system?: string;
+        maxTurns?: number;
+    }): Promise<{
+        output: string;
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+            totalTokens: number;
+            llmCalls: number;
+            toolCalls: number;
+        };
+        response: Response$1;
+    }>;
+    /**
+     * Creates a fluent tool builder for defining tools with Zod schemas.
+     *
+     * @example
+     * ```typescript
+     * import { z } from "zod";
+     *
+     * const tools = mr.tools()
+     *   .add("get_weather", "Get current weather", z.object({ location: z.string() }), async (args) => {
+     *     return { temp: 72, unit: "fahrenheit" };
+     *   })
+     *   .add("read_file", "Read a file", z.object({ path: z.string() }), async (args) => {
+     *     return fs.readFile(args.path, "utf-8");
+     *   });
+     *
+     * // Use with agent (pass ToolBuilder directly)
+     * const result = await mr.agent("claude-sonnet-4-5", {
+     *   tools,
+     *   prompt: "What's the weather in Paris?",
+     * });
+     *
+     * // Or get tool definitions for manual use
+     * const toolDefs = tools.definitions();
+     * ```
+     */
+    tools(): ToolBuilder;
 }
 
-export { APIError, ApiKey, type AttemptRecord, AuthClient, type AuthHeaders, type ChainOptions, ConfigError, CustomerResponsesClient, CustomerScopedModelRelay, CustomerToken, CustomerTokenProvider, CustomerTokenRequest, type ErrorCategory, type ErrorCode, ErrorCodes, FieldError, GetOrCreateCustomerTokenRequest, type HandleWaitingResult, type ImageData, type ImagePinResponse, type ImageRequest, type ImageResponse, type ImageResponseFormat, type ImageUsage, ImagesClient, InputItem, type JSONPointer, JoinOutput, JoinOutputPath, LLMInput, LLMInputContentItemPath, LLMInputFirstMessageText, LLMInputMessagePath, LLMInputPath, LLMInputSystemText, LLMInputUserText, LLMNodeBuilder, LLMOutput, LLMOutputContentItemPath, LLMOutputContentPath, LLMOutputPath, LLMOutputText, LLM_TEXT_OUTPUT, LLM_USER_MESSAGE_TEXT, type ListSessionsOptions, type ListSessionsResponse, LocalSession, type LocalSessionOptions, type LocalSessionPersistence, MemorySessionStore, MetricsCallbacks, type MockFetchCall, type MockFetchResponder, ModelId, ModelRelay, ModelRelayError, ModelRelayKeyOptions, ModelRelayOptions, type NDJSONDelayStep, type NodeErrorV0$1 as NodeErrorV0, type NodeId$1 as NodeId, OutputFormat, type OutputName$1 as OutputName, type ParallelOptions, PathEscapeError, type PayloadInfoV0$1 as PayloadInfoV0, type PlanHash$1 as PlanHash, type PriceInterval, ProviderId, type RemoteSessionInfo, type RemoteSessionOptions, RequestContext, Response$1 as Response, ResponseEvent, ResponsesClient, ResponsesStream, RetryConfig, type RetryHandler, RetryMetadata, type RunEventTypeV0, type RunEventV0, type RunId$1 as RunId, type RunStatusV0, RunsClient, RunsEventStream, SecretKey, type Session, type SessionArtifacts, type SessionContextManagement, type SessionContextTruncateInfo, type SessionId, type SessionMessage, type SessionPendingToolCall, type SessionRunOptions, type SessionRunResult, type SessionRunStatus, type SessionState, type SessionStore, type SessionSyncOptions, type SessionSyncResult, type SessionType, type SessionUsageSummary, SessionsClient, StreamProtocolError, StreamTimeoutError, type StreamTimeoutKind, StructuredDecodeError, type StructuredErrorKind, StructuredExhaustedError, StructuredJSONEvent, StructuredJSONStream, type StructuredOptions, type StructuredResult, type Tier, type TierCheckoutRequest, type TierCheckoutSession, TierCode, type TierModel, TiersClient, TokenProvider, Tool, ToolArgumentError, ToolChoice, ToolExecutionResult, ToolRegistry, ToolRunner, type ToolRunnerOptions, TraceCallbacks, TransportError, TransportErrorKind, type ValidationIssue, WORKFLOWS_COMPILE_PATH, WorkflowIntentBuilder, type WorkflowIntentBuilderState, type WorkflowKind, WorkflowKinds, WorkflowNodeTypesLite as WorkflowNodeTypes, WorkflowNodeTypesLite, WorkflowValidationError, type WorkflowValidationIssue, WorkflowsClient, type WorkflowsCompileOptions, type WorkflowsCompileRequest, type WorkflowsCompileResponse, type WorkflowsCompileResult, ZodLikeSchema, asSessionId, buildDelayedNDJSONResponse, buildNDJSONResponse, chain, createAccessTokenAuth, createApiKeyAuth, createLocalSession, createMemorySessionStore, createMockFetchQueue, createToolRunner, defaultRetryHandler, defaultTierModelId, generateSessionId, index$1 as generated, isSecretKey, llm, outputFormatFromZod, parallel, parseApiKey, parseErrorResponse, parseNodeId, parseOutputName, parsePlanHash, parseRunId, parseSecretKey, validateWithZod, index as workflow, workflowIntent };
+export { APIError, AgentMaxTurnsError, ApiKey, type AttemptRecord, AuthClient, type AuthHeaders, type ChainOptions, ConfigError, type ContextManagementStrategy, ContextManager, type ContextManagerOptions, type ContextPrepareOptions, type ContextTruncateInfo, type ConversationState, type ConversationStore, CustomerResponsesClient, CustomerScopedModelRelay, CustomerToken, CustomerTokenProvider, CustomerTokenRequest, type ErrorCategory, type ErrorCode, ErrorCodes, FieldError, FileConversationStore, GetOrCreateCustomerTokenRequest, type HandleWaitingResult, type ImageData, type ImagePinResponse, type ImageRequest, type ImageResponse, type ImageResponseFormat, type ImageUsage, ImagesClient, InputItem, type JSONPointer, JoinOutput, JoinOutputPath, LLMInput, LLMInputContentItemPath, LLMInputFirstMessageText, LLMInputMessagePath, LLMInputPath, LLMInputSystemText, LLMInputUserText, LLMNodeBuilder, LLMOutput, LLMOutputContentItemPath, LLMOutputContentPath, LLMOutputPath, LLMOutputText, LLM_TEXT_OUTPUT, LLM_USER_MESSAGE_TEXT, type ListSessionsOptions, type ListSessionsResponse, LocalSession, type LocalSessionOptions, type LocalSessionPersistence, MAX_STATE_HANDLE_TTL_SECONDS, MemoryConversationStore, MetricsCallbacks, type MockFetchCall, type MockFetchResponder, type ModelContextResolver, type ModelContextWindow, ModelId, ModelRelay, ModelRelayError, ModelRelayKeyOptions, ModelRelayOptions, type NDJSONDelayStep, type NodeErrorV0$1 as NodeErrorV0, type NodeId$1 as NodeId, type OrchestrationMode, OrchestrationModes, type OrchestrationPlan, OutputFormat, type OutputName$1 as OutputName, type ParallelOptions, PathEscapeError, type PayloadInfoV0$1 as PayloadInfoV0, type PlanHash$1 as PlanHash, type Plugin, type PluginAgent, type PluginAgentName, type PluginCommand, type PluginCommandName, PluginConverter, type PluginConverterOptions, type PluginGitHubRef, type PluginId, PluginLoader, type PluginLoaderOptions, type PluginManifest, PluginOrchestrationError, type PluginOrchestrationErrorCode, PluginOrchestrationErrorCodes, type PluginRunConfig, type PluginRunResult, PluginRunner, type PluginToolName, PluginToolNames, type PluginUrl, PluginsClient, type PluginsClientOptions, type PriceInterval, ProviderId, type RemoteSessionInfo, type RemoteSessionOptions, RequestContext, Response$1 as Response, ResponseEvent, ResponsesClient, ResponsesStream, RetryConfig, type RetryHandler, RetryMetadata, type RunEventTypeV0, type RunEventV0, type RunId$1 as RunId, type RunStatusV0, RunsClient, RunsEventStream, SecretKey, type Session, type SessionArtifacts, type SessionContextManagement, type SessionContextTruncateInfo, type SessionId, type SessionMessage, type SessionPendingToolCall, type SessionRunOptions, type SessionRunResult, type SessionRunStatus, type SessionSyncOptions, type SessionSyncResult, type SessionType, type SessionUsageSummary, SessionsClient, SqliteConversationStore, type StateHandleCreateRequest, type StateHandleListResponse, type StateHandleResponse, StreamProtocolError, StreamTimeoutError, type StreamTimeoutKind, StructuredDecodeError, type StructuredErrorKind, StructuredExhaustedError, StructuredJSONEvent, StructuredJSONStream, type StructuredOptions, type StructuredResult, type Tier, type TierCheckoutRequest, type TierCheckoutSession, TierCode, type TierModel, TiersClient, TokenProvider, Tool, ToolArgumentError, ToolBuilder, ToolCall, ToolChoice, ToolExecutionResult, type ToolLoopComplete, type ToolLoopConfig, type ToolLoopOutcome, type ToolLoopUsage, type ToolLoopWaiting, ToolRegistry, ToolRunner, type ToolRunnerOptions, TraceCallbacks, TransportError, TransportErrorKind, USER_ASK_TOOL_NAME, type UserAskArgs, type UserAskOption, type UserAskResponse, type ValidationIssue, WORKFLOWS_COMPILE_PATH, WorkflowIntentBuilder, type WorkflowIntentBuilderState, type WorkflowKind, WorkflowKinds, WorkflowNodeTypesIntent as WorkflowNodeTypes, WorkflowNodeTypesIntent, WorkflowValidationError, type WorkflowValidationIssue, WorkflowsClient, type WorkflowsCompileOptions, type WorkflowsCompileRequest, type WorkflowsCompileResponse, type WorkflowsCompileResult, ZodLikeSchema, asSessionId, buildDelayedNDJSONResponse, buildNDJSONResponse, chain, createAccessTokenAuth, createApiKeyAuth, createFileConversationStore, createLocalSession, createMemoryConversationStore, createMockFetchQueue, createModelContextResolver, createSqliteConversationStore, createToolRunner, createUserAskTool, defaultRetryHandler, defaultTierModelId, generateSessionId, index$1 as generated, isSecretKey, isUserAskToolCall, llm, outputFormatFromZod, parallel, parseApiKey, parseErrorResponse, parseNodeId, parseOutputName, parsePlanHash, parseRunId, parseSecretKey, parseUserAskArgs, prepareInputWithContext, runToolLoop, serializeUserAskResult, truncateInputByTokens, userAskResultChoice, userAskResultFreeform, validateWithZod, index as workflow, workflowIntent };