@modelrelay/sdk 5.1.0 → 8.0.0

package/dist/index.js

@@ -1,5 +1,6 @@
 import {
   APIError,
+  AgentMaxTurnsError,
   BillingProviders,
   ConfigError,
   ContentPartTypes,
@@ -26,7 +27,6 @@ import {
   ToolRegistry,
   ToolTypes,
   TransportError,
-  WebToolIntents,
   WorkflowValidationError,
   asModelId,
   asProviderId,
@@ -39,13 +39,20 @@ import {
   createRetryMessages,
   createSystemMessage,
   createToolCall,
+  createTypedTool,
   createUsage,
   createUserMessage,
-  createWebTool,
   executeWithRetry,
   firstToolCall,
   formatToolErrorForModel,
+  getAllToolCalls,
+  getAssistantText,
   getRetryableErrors,
+  getToolArgs,
+  getToolArgsRaw,
+  getToolName,
+  getTypedToolCall,
+  getTypedToolCalls,
   hasRetryableErrors,
   hasToolCalls,
   mergeMetrics,
@@ -54,17 +61,15 @@ import {
   normalizeModelId,
   normalizeStopReason,
   parseErrorResponse,
-  parseToolArgs,
-  parseToolArgsRaw,
+  parseTypedToolCall,
   respondToToolCall,
   stopReasonToString,
   toolChoiceAuto,
   toolChoiceNone,
   toolChoiceRequired,
   toolResultMessage,
-  tryParseToolArgs,
   zodToJsonSchema
-} from "./chunk-RVHKBQ7X.js";
+} from "./chunk-SJC7Q4NK.js";
 import {
   __export
 } from "./chunk-MLKGABMK.js";
@@ -154,6 +159,9 @@ var AuthClient = class {
     if (typeof request.ttlSeconds === "number") {
       payload.ttl_seconds = request.ttlSeconds;
     }
+    if (request.tierCode) {
+      payload.tier_code = request.tierCode;
+    }
     const apiResp = await this.http.json("/auth/customer-token", {
       method: "POST",
       body: payload,
@@ -209,7 +217,8 @@ var AuthClient = class {
     });
     return this.customerToken({
       customerExternalId: externalId,
-      ttlSeconds: request.ttlSeconds
+      ttlSeconds: request.ttlSeconds,
+      tierCode: request.tierCode
     });
   }
   /**
@@ -327,13 +336,38 @@ var ResponseBuilder = class _ResponseBuilder {
       patch.options ? { ...this.options, ...patch.options } : this.options
     );
   }
-  /** @returns A new builder with the provider set. */
+  /**
+   * 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) {
-    return this.with({ body: { provider } });
+    return this.with({ body: { provider: asProviderId(provider) } });
   }
-  /** @returns A new builder with the model set. */
+  /**
+   * 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) {
-    return this.with({ body: { model } });
+    return this.with({ body: { model: asModelId(model) } });
+  }
+  /** @returns A new builder with state-scoped tool state. */
+  stateId(stateId) {
+    const state_id = stateId.trim();
+    return this.with({ body: { state_id: state_id || void 0 } });
   }
   /** @returns A new builder with the full input array replaced. */
   input(items) {
@@ -481,6 +515,111 @@ var ResponseBuilder = class _ResponseBuilder {
   signal(signal) {
     return this.with({ options: { signal } });
   }
+  // =========================================================================
+  // Conversation Continuation Helpers
+  // =========================================================================
+  /**
+   * 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, content) {
+    return this.item(assistantMessageWithToolCalls(content ?? "", toolCalls));
+  }
+  /**
+   * Add tool results to the conversation.
+   *
+   * @example
+   * ```typescript
+   * .toolResults([
+   *   { id: "call_123", result: { temp: 72 } },
+   *   { id: "call_456", result: "File contents here" },
+   * ])
+   * ```
+   */
+  toolResults(results) {
+    let builder = this;
+    for (const r of results) {
+      const content = typeof r.result === "string" ? r.result : JSON.stringify(r.result);
+      builder = builder.item(toolResultMessage(r.id, content));
+    }
+    return builder;
+  }
+  /**
+   * Add a single tool result to the conversation.
+   *
+   * @example
+   * ```typescript
+   * .toolResult("call_123", { temp: 72, unit: "fahrenheit" })
+   * ```
+   */
+  toolResult(toolCallId, result) {
+    const content = typeof result === "string" ? result : JSON.stringify(result);
+    return this.item(toolResultMessage(toolCallId, content));
+  }
+  /**
+   * 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, toolResults) {
+    const toolCalls = [];
+    for (const item of response.output || []) {
+      if (item.toolCalls) {
+        toolCalls.push(...item.toolCalls);
+      }
+    }
+    if (toolCalls.length === 0) {
+      throw new ConfigError(
+        "continueFrom requires a response with tool calls"
+      );
+    }
+    const assistantText = getAssistantText(response);
+    return this.assistantToolCalls(toolCalls, assistantText).toolResults(
+      toolResults
+    );
+  }
   /** @returns A finalized, immutable request payload. */
   build() {
     const input = (this.body.input ?? []).slice();
@@ -490,6 +629,7 @@ var ResponseBuilder = class _ResponseBuilder {
     const body = {
       provider: this.body.provider,
       model: this.body.model,
+      state_id: this.body.state_id,
       input,
       output_format: this.body.output_format,
       max_output_tokens: this.body.max_output_tokens,
@@ -1806,7 +1946,7 @@ function parseOutputName(raw) {
 var WorkflowKinds = {
   WorkflowIntent: "workflow"
 };
-var WorkflowNodeTypesLite = {
+var WorkflowNodeTypesIntent = {
   LLM: "llm",
   JoinAll: "join.all",
   JoinAny: "join.any",
@@ -1876,6 +2016,25 @@ var nodeWaitingSchema = z.object({
   pending_tool_calls: z.array(pendingToolCallSchema).min(1),
   reason: z.string().min(1)
 }).strict();
+var userAskOptionSchema = z.object({
+  label: z.string().min(1),
+  description: z.string().optional()
+}).strict();
+var nodeUserAskSchema = z.object({
+  step: z.number().int().nonnegative(),
+  request_id: z.string().min(1),
+  tool_call: toolCallWithArgumentsSchema,
+  question: z.string().min(1),
+  options: z.array(userAskOptionSchema).optional(),
+  allow_freeform: z.boolean()
+}).strict();
+var nodeUserAnswerSchema = z.object({
+  step: z.number().int().nonnegative(),
+  request_id: z.string().min(1),
+  tool_call: toolCallSchema,
+  answer: z.string(),
+  is_freeform: z.boolean()
+}).strict();
 var baseSchema = {
   envelope_version: z.literal("v2").optional().default("v2"),
   run_id: z.string().min(1),
@@ -1927,6 +2086,18 @@ var runEventWireSchema = z.discriminatedUnion("type", [
     node_id: z.string().min(1),
     waiting: nodeWaitingSchema
   }).strict(),
+  z.object({
+    ...baseSchema,
+    type: z.literal("node_user_ask"),
+    node_id: z.string().min(1),
+    user_ask: nodeUserAskSchema
+  }).strict(),
+  z.object({
+    ...baseSchema,
+    type: z.literal("node_user_answer"),
+    node_id: z.string().min(1),
+    user_answer: nodeUserAnswerSchema
+  }).strict(),
   z.object({ ...baseSchema, type: z.literal("node_started"), node_id: z.string().min(1) }).strict(),
   z.object({ ...baseSchema, type: z.literal("node_succeeded"), node_id: z.string().min(1) }).strict(),
   z.object({
@@ -2020,6 +2191,10 @@ function parseRunEventV0(line) {
         return { ...base, type: "node_tool_result", node_id: parseNodeId(res.data.node_id), tool_result: res.data.tool_result };
       case "node_waiting":
         return { ...base, type: "node_waiting", node_id: parseNodeId(res.data.node_id), waiting: res.data.waiting };
+      case "node_user_ask":
+        return { ...base, type: "node_user_ask", node_id: parseNodeId(res.data.node_id), user_ask: res.data.user_ask };
+      case "node_user_answer":
+        return { ...base, type: "node_user_answer", node_id: parseNodeId(res.data.node_id), user_answer: res.data.user_answer };
       case "node_succeeded":
         return { ...base, type: "node_succeeded", node_id: parseNodeId(res.data.node_id) };
       case "node_failed":
@@ -2181,6 +2356,90 @@ var RunsClient = class {
     if (options.input) {
       payload.input = options.input;
     }
+    if (options.modelOverride?.trim()) {
+      payload.model_override = options.modelOverride.trim();
+    }
+    if (options.modelOverrides) {
+      const nodes = options.modelOverrides.nodes;
+      const fanoutSubnodes = options.modelOverrides.fanoutSubnodes;
+      if (nodes && Object.keys(nodes).length > 0 || fanoutSubnodes && fanoutSubnodes.length > 0) {
+        payload.model_overrides = {
+          nodes,
+          fanout_subnodes: fanoutSubnodes?.map((entry) => ({
+            parent_id: entry.parentId,
+            subnode_id: entry.subnodeId,
+            model: entry.model
+          }))
+        };
+      }
+    }
+    if (options.stream !== void 0) {
+      payload.stream = options.stream;
+    }
+    const out = await this.http.json(RUNS_PATH, {
+      method: "POST",
+      headers,
+      body: payload,
+      signal: options.signal,
+      apiKey: authHeaders.apiKey,
+      accessToken: authHeaders.accessToken,
+      timeoutMs: options.timeoutMs,
+      connectTimeoutMs: options.connectTimeoutMs,
+      retry: options.retry,
+      metrics,
+      trace,
+      context: { method: "POST", path: RUNS_PATH }
+    });
+    return { ...out, run_id: parseRunId(out.run_id), plan_hash: parsePlanHash(out.plan_hash) };
+  }
+  /**
+   * 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.
+   */
+  async createFromPlan(planHash, options = {}) {
+    const metrics = mergeMetrics(this.metrics, options.metrics);
+    const trace = mergeTrace(this.trace, options.trace);
+    const authHeaders = await this.auth.authForResponses();
+    const headers = { ...options.headers || {} };
+    this.applyCustomerHeader(headers, options.customerId);
+    const payload = { plan_hash: planHash };
+    if (options.sessionId?.trim()) {
+      payload.session_id = options.sessionId.trim();
+    }
+    if (options.idempotencyKey?.trim()) {
+      payload.options = { idempotency_key: options.idempotencyKey.trim() };
+    }
+    if (options.input) {
+      payload.input = options.input;
+    }
+    if (options.modelOverride?.trim()) {
+      payload.model_override = options.modelOverride.trim();
+    }
+    if (options.modelOverrides) {
+      const nodes = options.modelOverrides.nodes;
+      const fanoutSubnodes = options.modelOverrides.fanoutSubnodes;
+      if (nodes && Object.keys(nodes).length > 0 || fanoutSubnodes && fanoutSubnodes.length > 0) {
+        payload.model_overrides = {
+          nodes,
+          fanout_subnodes: fanoutSubnodes?.map((entry) => ({
+            parent_id: entry.parentId,
+            subnode_id: entry.subnodeId,
+            model: entry.model
+          }))
+        };
+      }
+    }
+    if (options.stream !== void 0) {
+      payload.stream = options.stream;
+    }
     const out = await this.http.json(RUNS_PATH, {
       method: "POST",
       headers,
@@ -2523,290 +2782,460 @@ var ImagesClient = class {
   }
 };
 
-// src/sessions/context_management.ts
-var DEFAULT_CONTEXT_BUFFER_TOKENS = 256;
-var CONTEXT_BUFFER_RATIO = 0.02;
-var MESSAGE_OVERHEAD_TOKENS = 6;
-var TOOL_CALL_OVERHEAD_TOKENS = 4;
-var CHARS_PER_TOKEN = 4;
-var IMAGE_TOKENS_LOW_DETAIL = 85;
-var IMAGE_TOKENS_HIGH_DETAIL = 1e3;
-var modelContextCache = /* @__PURE__ */ new WeakMap();
-function createModelContextResolver(client) {
-  return async (modelId) => {
-    const entry = getModelContextCacheEntry(client);
-    const key = String(modelId);
-    const cached = entry.byId.get(key);
-    if (cached !== void 0) {
-      return cached;
-    }
-    await populateModelContextCache(client, entry);
-    const resolved = entry.byId.get(key);
-    if (resolved === void 0) {
-      throw new ConfigError(
-        `Unknown model "${key}"; ensure the model exists in the ModelRelay catalog`
-      );
+// src/state_handles.ts
+var MAX_STATE_HANDLE_TTL_SECONDS = 31536e3;
+var STATE_HANDLES_PATH = "/state-handles";
+var StateHandlesClient = class {
+  constructor(http, auth) {
+    this.http = http;
+    this.auth = auth;
+  }
+  /** Make an authenticated request to the state handles API. */
+  async request(method, path, body) {
+    const auth = await this.auth.authForResponses();
+    return this.http.json(path, {
+      method,
+      body,
+      apiKey: auth.apiKey,
+      accessToken: auth.accessToken
+    });
+  }
+  async create(request = {}) {
+    if (request.ttl_seconds !== void 0) {
+      if (request.ttl_seconds <= 0) {
+        throw new Error("ttl_seconds must be positive");
+      }
+      if (request.ttl_seconds > MAX_STATE_HANDLE_TTL_SECONDS) {
+        throw new Error("ttl_seconds exceeds maximum (1 year)");
+      }
     }
-    return resolved;
-  };
-}
-async function buildSessionInputWithContext(messages, options, defaultModel, resolveModelContext) {
-  const strategy = options.contextManagement ?? "none";
-  if (strategy === "none") {
-    return messagesToInput(messages);
+    return this.request("POST", STATE_HANDLES_PATH, request);
   }
-  if (strategy === "summarize") {
-    throw new ConfigError("contextManagement 'summarize' is not implemented yet");
+  async list(params = {}) {
+    const { limit, offset } = params;
+    if (limit !== void 0 && (limit <= 0 || limit > 100)) {
+      throw new Error("limit must be between 1 and 100");
+    }
+    if (offset !== void 0 && offset < 0) {
+      throw new Error("offset must be non-negative");
+    }
+    const query = new URLSearchParams();
+    if (limit !== void 0) {
+      query.set("limit", String(limit));
+    }
+    if (offset !== void 0 && offset > 0) {
+      query.set("offset", String(offset));
+    }
+    const path = query.toString() ? `${STATE_HANDLES_PATH}?${query.toString()}` : STATE_HANDLES_PATH;
+    return this.request("GET", path);
   }
-  if (strategy !== "truncate") {
-    throw new ConfigError(`Unknown contextManagement strategy: ${strategy}`);
+  async delete(stateId) {
+    if (!stateId?.trim()) {
+      throw new Error("state_id is required");
+    }
+    await this.request("DELETE", `${STATE_HANDLES_PATH}/${stateId}`);
   }
-  const modelId = options.model ?? defaultModel;
-  if (!modelId) {
-    throw new ConfigError(
-      "model is required for context management; set options.model or a session defaultModel"
+};
+
+// src/tool_loop.ts
+var DEFAULT_MAX_TURNS = 100;
+async function runToolLoop(config) {
+  const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
+  if (!Number.isFinite(maxTurns) || maxTurns <= 0) {
+    throw new ConfigError("maxTurns must be a positive number");
+  }
+  const tools = config.tools ?? [];
+  const history = config.input.slice();
+  const usage = {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+    llmCalls: 0,
+    toolCalls: 0
+  };
+  for (let turn = 0; turn < maxTurns; turn += 1) {
+    let builder = config.client.new().input(history);
+    if (tools.length > 0) {
+      builder = builder.tools(tools);
+    }
+    if (config.buildRequest) {
+      builder = config.buildRequest(builder);
+    }
+    const response = await config.client.create(
+      builder.build(),
+      config.requestOptions
     );
+    usage.llmCalls += 1;
+    usage.inputTokens += response.usage.inputTokens;
+    usage.outputTokens += response.usage.outputTokens;
+    usage.totalTokens += response.usage.totalTokens;
+    const toolCalls = getAllToolCalls(response);
+    if (toolCalls.length === 0) {
+      const assistantText = getAssistantText(response);
+      if (assistantText) {
+        history.push(createAssistantMessage(assistantText));
+      }
+      return {
+        status: "complete",
+        output: assistantText,
+        response,
+        usage,
+        input: history,
+        turnsUsed: turn + 1
+      };
+    }
+    usage.toolCalls += toolCalls.length;
+    history.push(
+      assistantMessageWithToolCalls(getAssistantText(response), toolCalls)
+    );
+    if (!config.registry) {
+      return {
+        status: "waiting_for_tools",
+        pendingToolCalls: toolCalls,
+        response,
+        usage,
+        input: history,
+        turnsUsed: turn + 1
+      };
+    }
+    const results = await config.registry.executeAll(toolCalls);
+    history.push(...config.registry.resultsToMessages(results));
   }
-  const budget = await resolveHistoryBudget(
-    modelId,
-    options,
-    resolveModelContext
-  );
-  const truncated = truncateMessagesByTokens(
-    messages,
-    budget.maxHistoryTokens
-  );
-  if (options.onContextTruncate && truncated.length < messages.length) {
-    const info = {
-      model: modelId,
-      originalMessages: messages.length,
-      keptMessages: truncated.length,
-      maxHistoryTokens: budget.maxHistoryTokens,
-      reservedOutputTokens: budget.reservedOutputTokens
-    };
-    options.onContextTruncate(info);
-  }
-  return messagesToInput(truncated);
+  throw new AgentMaxTurnsError(maxTurns);
 }
-function messagesToInput(messages) {
-  return messages.map((m) => ({
-    type: m.type,
-    role: m.role,
-    content: m.content,
-    toolCalls: m.toolCalls,
-    toolCallId: m.toolCallId
-  }));
+
+// src/sessions/types.ts
+function asSessionId(value) {
+  return value;
 }
-function truncateMessagesByTokens(messages, maxHistoryTokens) {
-  const maxTokens = normalizePositiveInt(maxHistoryTokens, "maxHistoryTokens");
-  if (messages.length === 0) return [];
-  const tokensByIndex = messages.map((msg) => estimateTokensForMessage(msg));
-  const systemIndices = messages.map((msg, idx) => msg.role === "system" ? idx : -1).filter((idx) => idx >= 0);
-  let selectedSystem = [...systemIndices];
-  let systemTokens = sumTokens(tokensByIndex, selectedSystem);
-  while (systemTokens > maxTokens && selectedSystem.length > 1) {
-    selectedSystem.shift();
-    systemTokens = sumTokens(tokensByIndex, selectedSystem);
+function generateSessionId() {
+  return crypto.randomUUID();
+}
+
+// src/sessions/stores/memory_store.ts
+var MemoryConversationStore = class {
+  constructor() {
+    this.sessions = /* @__PURE__ */ new Map();
   }
-  if (systemTokens > maxTokens) {
-    throw new ConfigError(
-      "maxHistoryTokens is too small to fit the latest system message"
-    );
+  async load(id) {
+    const state = this.sessions.get(id);
+    if (!state) return null;
+    return structuredClone(state);
   }
-  const selected = new Set(selectedSystem);
-  let remaining = maxTokens - systemTokens;
-  for (let i = messages.length - 1; i >= 0; i -= 1) {
-    if (selected.has(i)) continue;
-    const tokens = tokensByIndex[i];
-    if (tokens <= remaining) {
-      selected.add(i);
-      remaining -= tokens;
-    }
+  async save(state) {
+    this.sessions.set(state.id, structuredClone(state));
   }
-  const result = messages.filter((_, idx) => selected.has(idx));
-  if (result.length === 0) {
-    throw new ConfigError("No messages fit within maxHistoryTokens");
+  async delete(id) {
+    this.sessions.delete(id);
   }
-  return result;
+  async list() {
+    return Array.from(this.sessions.keys());
+  }
+  async close() {
+    this.sessions.clear();
+  }
+  /**
+   * Get the number of sessions in the store.
+   * Useful for testing.
+   */
+  get size() {
+    return this.sessions.size;
+  }
+};
+function createMemoryConversationStore() {
+  return new MemoryConversationStore();
 }
-function estimateTokens(text) {
-  return Math.ceil(text.length / CHARS_PER_TOKEN);
+
+// src/sessions/stores/serialization.ts
+function serializeConversationState(state) {
+  return {
+    ...state,
+    messages: state.messages.map((message) => ({
+      ...message,
+      createdAt: message.createdAt.toISOString()
+    }))
+  };
 }
-function isImagePart(part) {
-  if (typeof part !== "object" || part === null) return false;
-  const p = part;
-  return p.type === "image" || p.type === "image_url";
+function deserializeConversationState(state) {
+  return {
+    ...state,
+    messages: state.messages.map((message) => ({
+      ...message,
+      createdAt: new Date(message.createdAt)
+    }))
+  };
 }
-function estimateImageTokens(part) {
-  const detail = part.detail ?? "auto";
-  if (detail === "low") return IMAGE_TOKENS_LOW_DETAIL;
-  return IMAGE_TOKENS_HIGH_DETAIL;
+
+// src/sessions/stores/file_store.ts
+var DEFAULT_SESSION_DIR = ".modelrelay/sessions";
+async function loadNodeDeps() {
+  try {
+    const fs = await import("fs/promises");
+    const path = await import("path");
+    const os = await import("os");
+    return { fs, path, os };
+  } catch (err) {
+    throw new ConfigError("file persistence requires a Node.js-compatible runtime");
+  }
 }
-function estimateTokensForMessage(message) {
-  const segments = [message.role];
-  let imageTokens = 0;
-  for (const part of message.content || []) {
-    if (part.type === "text" && part.text) {
-      segments.push(part.text);
-    } else if (isImagePart(part)) {
-      imageTokens += estimateImageTokens(part);
-    }
+var FileConversationStore = class {
+  constructor(storagePath) {
+    this.storagePath = storagePath;
   }
-  if (message.toolCalls) {
-    for (const call of message.toolCalls) {
-      if (call.function?.name) segments.push(call.function.name);
-      if (call.function?.arguments) segments.push(call.function.arguments);
+  async load(id) {
+    const { fs, path, os } = await loadNodeDeps();
+    const filePath = await this.resolveSessionPath(id, path, os);
+    try {
+      const raw = await fs.readFile(filePath, "utf8");
+      const parsed = JSON.parse(raw);
+      return deserializeConversationState(parsed);
+    } catch (err) {
+      if (isNotFoundError(err)) return null;
+      throw err;
     }
   }
-  if (message.toolCallId) {
-    segments.push(message.toolCallId);
+  async save(state) {
+    const { fs, path, os } = await loadNodeDeps();
+    const dirPath = await this.resolveSessionDir(path, os);
+    await fs.mkdir(dirPath, { recursive: true, mode: 448 });
+    const filePath = path.join(dirPath, `${state.id}.json`);
+    const payload = JSON.stringify(serializeConversationState(state), null, 2);
+    await fs.writeFile(filePath, payload, { mode: 384 });
   }
-  const textTokens = estimateTokens(segments.join("\n"));
-  const toolOverhead = message.toolCalls ? message.toolCalls.length * TOOL_CALL_OVERHEAD_TOKENS : 0;
-  return textTokens + MESSAGE_OVERHEAD_TOKENS + toolOverhead + imageTokens;
-}
-function normalizePositiveInt(value, label) {
-  if (!Number.isFinite(value) || value <= 0) {
-    throw new ConfigError(`${label} must be a positive number`);
+  async delete(id) {
+    const { fs, path, os } = await loadNodeDeps();
+    const filePath = await this.resolveSessionPath(id, path, os);
+    try {
+      await fs.unlink(filePath);
+    } catch (err) {
+      if (isNotFoundError(err)) return;
+      throw err;
+    }
   }
-  return Math.floor(value);
-}
-function sumTokens(tokensByIndex, indices) {
-  return indices.reduce((sum, idx) => sum + tokensByIndex[idx], 0);
-}
-async function resolveHistoryBudget(modelId, options, resolveModelContext) {
-  const reservedOutputTokens = options.reserveOutputTokens === void 0 ? void 0 : normalizeNonNegativeInt(
-    options.reserveOutputTokens,
-    "reserveOutputTokens"
-  );
-  if (options.maxHistoryTokens !== void 0) {
-    return {
-      maxHistoryTokens: normalizePositiveInt(
-        options.maxHistoryTokens,
-        "maxHistoryTokens"
-      ),
-      reservedOutputTokens
-    };
+  async list() {
+    const { fs, path, os } = await loadNodeDeps();
+    const dirPath = await this.resolveSessionDir(path, os);
+    try {
+      const entries = await fs.readdir(dirPath);
+      return entries.filter((entry) => path.extname(entry) === ".json").map((entry) => entry.replace(/\.json$/, ""));
+    } catch (err) {
+      if (isNotFoundError(err)) return [];
+      throw err;
+    }
   }
-  const model = await resolveModelContext(modelId);
-  if (!model) {
-    throw new ConfigError(
-      `Unknown model "${modelId}"; ensure the model exists in the ModelRelay catalog`
-    );
+  async close() {
   }
-  const contextWindow = normalizePositiveInt(model.contextWindow, "context_window");
-  const modelOutputTokens = model.maxOutputTokens === void 0 ? 0 : normalizeNonNegativeInt(model.maxOutputTokens, "max_output_tokens");
-  const effectiveReserve = reservedOutputTokens ?? modelOutputTokens;
-  const buffer = Math.max(
-    DEFAULT_CONTEXT_BUFFER_TOKENS,
-    Math.ceil(contextWindow * CONTEXT_BUFFER_RATIO)
-  );
-  const maxHistoryTokens = contextWindow - effectiveReserve - buffer;
-  if (maxHistoryTokens <= 0) {
-    throw new ConfigError(
-      "model context window is too small after reserving output tokens; set maxHistoryTokens explicitly"
-    );
+  async resolveSessionPath(id, path, os) {
+    const dirPath = await this.resolveSessionDir(path, os);
+    return path.join(dirPath, `${id}.json`);
   }
-  return {
-    maxHistoryTokens,
-    reservedOutputTokens: effectiveReserve
-  };
-}
-function normalizeNonNegativeInt(value, label) {
-  if (!Number.isFinite(value) || value < 0) {
-    throw new ConfigError(`${label} must be a non-negative number`);
+  async resolveSessionDir(path, os) {
+    if (this.storagePath && this.storagePath.trim()) {
+      return this.storagePath;
+    }
+    return path.join(os.homedir(), DEFAULT_SESSION_DIR);
   }
-  return Math.floor(value);
-}
-function getModelContextCacheEntry(client) {
-  const existing = modelContextCache.get(client);
-  if (existing) return existing;
-  const entry = { byId: /* @__PURE__ */ new Map() };
-  modelContextCache.set(client, entry);
-  return entry;
+};
+function createFileConversationStore(storagePath) {
+  return new FileConversationStore(storagePath);
 }
-async function populateModelContextCache(client, entry) {
-  if (!entry.listPromise) {
-    entry.listPromise = (async () => {
-      const response = await client.http.json("/models");
-      for (const model of response.models) {
-        entry.byId.set(String(model.model_id), {
-          contextWindow: model.context_window,
-          maxOutputTokens: model.max_output_tokens
-        });
-      }
-    })().finally(() => {
-      entry.listPromise = void 0;
-    });
-  }
-  await entry.listPromise;
+function isNotFoundError(err) {
+  return Boolean(
+    err && typeof err === "object" && "code" in err && err.code === "ENOENT"
+  );
 }
 
-// src/sessions/types.ts
-function asSessionId(value) {
-  return value;
+// src/sessions/stores/sqlite_store.ts
+var DEFAULT_DB_PATH = ".modelrelay/sessions.sqlite";
+async function loadNodeDeps2() {
+  try {
+    const path = await import("path");
+    const os = await import("os");
+    return { path, os };
+  } catch (err) {
+    throw new ConfigError("sqlite persistence requires a Node.js-compatible runtime");
+  }
 }
-function generateSessionId() {
-  return crypto.randomUUID();
+async function loadSqlite() {
+  try {
+    const mod = await import("better-sqlite3");
+    const Database = mod.default ?? mod;
+    if (typeof Database !== "function") {
+      throw new Error("better-sqlite3 export missing");
+    }
+    return Database;
+  } catch (err) {
+    throw new ConfigError(
+      "sqlite persistence requires the optional 'better-sqlite3' dependency"
+    );
+  }
 }
-
-// src/sessions/stores/memory_store.ts
-var MemorySessionStore = class {
-  constructor() {
-    this.sessions = /* @__PURE__ */ new Map();
+var SqliteConversationStore = class {
+  constructor(storagePath) {
+    this.storagePath = storagePath;
   }
   async load(id) {
-    const state = this.sessions.get(id);
-    if (!state) return null;
-    return structuredClone(state);
+    const statements = await this.getStatements();
+    const row = statements.get.get({ id });
+    if (!row) return null;
+    const parsed = {
+      id: row.id,
+      messages: JSON.parse(row.messages),
+      artifacts: JSON.parse(row.artifacts),
+      metadata: JSON.parse(row.metadata),
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt
+    };
+    return deserializeConversationState(parsed);
   }
   async save(state) {
-    this.sessions.set(state.id, structuredClone(state));
+    const statements = await this.getStatements();
+    const payload = serializeConversationState(state);
+    statements.save.run({
+      id: payload.id,
+      messages: JSON.stringify(payload.messages),
+      artifacts: JSON.stringify(payload.artifacts ?? {}),
+      metadata: JSON.stringify(payload.metadata ?? {}),
+      created_at: payload.createdAt,
+      updated_at: payload.updatedAt
+    });
   }
   async delete(id) {
-    this.sessions.delete(id);
+    const statements = await this.getStatements();
+    statements.delete.run({ id });
   }
   async list() {
-    return Array.from(this.sessions.keys());
+    const statements = await this.getStatements();
+    const rows = statements.list.all();
+    return rows.map((row) => row.id);
   }
   async close() {
-    this.sessions.clear();
+    if (this.db) {
+      this.db.close();
+      this.db = void 0;
+      this.statements = void 0;
+      this.initPromise = void 0;
+    }
+  }
+  async ensureInitialized() {
+    if (this.db) return;
+    if (!this.initPromise) {
+      this.initPromise = this.initialize();
+    }
+    await this.initPromise;
+  }
+  async getStatements() {
+    await this.ensureInitialized();
+    if (!this.statements) {
+      throw new Error("Database initialization failed");
+    }
+    return this.statements;
+  }
+  async initialize() {
+    const { path, os } = await loadNodeDeps2();
+    const Database = await loadSqlite();
+    const dbPath = this.resolveDbPath(path, os);
+    this.db = new Database(dbPath);
+    this.db.exec(`
+			CREATE TABLE IF NOT EXISTS conversations (
+				id TEXT PRIMARY KEY,
+				messages TEXT NOT NULL,
+				artifacts TEXT NOT NULL,
+				metadata TEXT NOT NULL,
+				created_at TEXT NOT NULL,
+				updated_at TEXT NOT NULL
+			)
+		`);
+    this.statements = {
+      get: this.db.prepare(
+        "SELECT id, messages, artifacts, metadata, created_at as createdAt, updated_at as updatedAt FROM conversations WHERE id = @id"
+      ),
+      save: this.db.prepare(
+        "INSERT INTO conversations (id, messages, artifacts, metadata, created_at, updated_at) VALUES (@id, @messages, @artifacts, @metadata, @created_at, @updated_at) ON CONFLICT(id) DO UPDATE SET messages = excluded.messages, artifacts = excluded.artifacts, metadata = excluded.metadata, updated_at = excluded.updated_at"
+      ),
+      delete: this.db.prepare("DELETE FROM conversations WHERE id = @id"),
+      list: this.db.prepare("SELECT id FROM conversations ORDER BY id")
+    };
   }
-  /**
-   * Get the number of sessions in the store.
-   * Useful for testing.
-   */
-  get size() {
-    return this.sessions.size;
+  resolveDbPath(path, os) {
+    if (this.storagePath && this.storagePath.trim()) {
+      return this.storagePath;
+    }
+    return path.join(os.homedir(), DEFAULT_DB_PATH);
   }
 };
-function createMemorySessionStore() {
-  return new MemorySessionStore();
+function createSqliteConversationStore(storagePath) {
+  return new SqliteConversationStore(storagePath);
+}
+
+// src/sessions/utils.ts
+function messagesToInput(messages) {
+  return messages.map((m) => ({
+    type: m.type,
+    role: m.role,
+    content: m.content,
+    toolCalls: m.toolCalls,
+    toolCallId: m.toolCallId
+  }));
+}
+function mergeTools(defaults, overrides) {
+  if (!defaults && !overrides) return void 0;
+  if (!defaults) return overrides;
+  if (!overrides) return defaults;
+  const merged = /* @__PURE__ */ new Map();
+  for (const tool of defaults) {
+    if (tool.type === "function" && tool.function) {
+      merged.set(tool.function.name, tool);
+    }
+  }
+  for (const tool of overrides) {
+    if (tool.type === "function" && tool.function) {
+      merged.set(tool.function.name, tool);
+    }
+  }
+  return Array.from(merged.values());
+}
+function emptyUsage() {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+    llmCalls: 0,
+    toolCalls: 0
+  };
+}
+function createRequestBuilder(config) {
+  return (builder) => {
+    let next = builder;
+    if (config.model) {
+      next = next.model(config.model);
+    }
+    if (config.provider) {
+      next = next.provider(config.provider);
+    }
+    if (config.customerId) {
+      next = next.customerId(config.customerId);
+    }
+    return next;
+  };
 }
 
 // src/sessions/local_session.ts
+var DEFAULT_MAX_TURNS2 = 100;
 var LocalSession = class _LocalSession {
   constructor(client, store, options, existingState) {
     this.type = "local";
     this.messages = [];
     this.artifacts = /* @__PURE__ */ new Map();
-    this.nextSeq = 1;
-    this.currentEvents = [];
-    this.currentUsage = {
-      inputTokens: 0,
-      outputTokens: 0,
-      totalTokens: 0,
-      llmCalls: 0,
-      toolCalls: 0
-    };
     this.client = client;
     this.store = store;
     this.toolRegistry = options.toolRegistry;
+    this.contextManager = options.contextManager;
     this.defaultModel = options.defaultModel;
     this.defaultProvider = options.defaultProvider;
     this.defaultTools = options.defaultTools;
+    this.systemPrompt = options.systemPrompt;
     this.metadata = options.metadata || {};
-    this.resolveModelContext = createModelContextResolver(client);
     if (existingState) {
       this.id = existingState.id;
       this.messages = existingState.messages.map((m) => ({
@@ -2814,7 +3243,6 @@ var LocalSession = class _LocalSession {
         createdAt: new Date(m.createdAt)
       }));
       this.artifacts = new Map(Object.entries(existingState.artifacts));
-      this.nextSeq = this.messages.length + 1;
       this.createdAt = new Date(existingState.createdAt);
       this.updatedAt = new Date(existingState.updatedAt);
     } else {
@@ -2831,7 +3259,11 @@ var LocalSession = class _LocalSession {
    * @returns A new LocalSession instance
    */
   static create(client, options = {}) {
-    const store = createStore(options.persistence || "memory", options.storagePath);
+    const store = createStore(
+      options.conversationStore,
+      options.persistence || "memory",
+      options.storagePath
+    );
     return new _LocalSession(client, store, options);
   }
   /**
@@ -2844,7 +3276,11 @@ var LocalSession = class _LocalSession {
    */
   static async resume(client, sessionId, options = {}) {
     const id = typeof sessionId === "string" ? asSessionId(sessionId) : sessionId;
-    const store = createStore(options.persistence || "memory", options.storagePath);
+    const store = createStore(
+      options.conversationStore,
+      options.persistence || "memory",
+      options.storagePath
+    );
     const state = await store.load(id);
     if (!state) {
       await store.close();
@@ -2856,106 +3292,147 @@ var LocalSession = class _LocalSession {
     return this.messages;
   }
   async run(prompt, options = {}) {
-    const userMessage = this.addMessage({
-      type: "message",
-      role: "user",
-      content: [{ type: "text", text: prompt }]
-    });
-    this.currentEvents = [];
-    this.currentUsage = {
-      inputTokens: 0,
-      outputTokens: 0,
-      totalTokens: 0,
-      llmCalls: 0,
-      toolCalls: 0
-    };
-    this.currentRunId = void 0;
-    this.currentNodeId = void 0;
-    this.currentWaiting = void 0;
+    this.pendingLoop = void 0;
+    this.messages.push(buildMessage(createUserMessage(prompt), this.messages.length + 1));
+    this.updatedAt = /* @__PURE__ */ new Date();
+    const baseInput = messagesToInput(this.messages);
+    const contextOptions = this.buildContextOptions(options);
     try {
-      const input = await this.buildInput(options);
+      const prepared = await this.prepareInput(baseInput, contextOptions);
       const tools = mergeTools(this.defaultTools, options.tools);
-      const spec = {
-        kind: "workflow",
-        name: `session-${this.id}-turn-${this.nextSeq}`,
-        model: options.model || this.defaultModel,
-        nodes: [
-          {
-            id: "main",
-            type: "llm",
-            input,
+      const modelId = options.model ?? this.defaultModel;
+      const providerId = options.provider ?? this.defaultProvider;
+      const requestOptions = options.signal ? { signal: options.signal } : {};
+      const outcome = await runToolLoop({
+        client: this.client.responses,
+        input: prepared,
+        tools,
+        registry: this.toolRegistry,
+        maxTurns: options.maxTurns ?? DEFAULT_MAX_TURNS2,
+        requestOptions,
+        buildRequest: createRequestBuilder({
+          model: modelId,
+          provider: providerId,
+          customerId: options.customerId
+        })
+      });
+      const cleanInput = stripSystemPrompt(outcome.input, this.systemPrompt);
+      this.replaceHistory(cleanInput);
+      await this.persist();
+      const usage = outcome.usage;
+      if (outcome.status === "waiting_for_tools") {
+        const pendingRequestOptions = { ...requestOptions };
+        delete pendingRequestOptions.signal;
+        this.pendingLoop = {
+          input: cleanInput,
+          usage,
+          remainingTurns: remainingTurns(
+            options.maxTurns ?? DEFAULT_MAX_TURNS2,
+            outcome.turnsUsed
+          ),
+          config: {
+            model: modelId,
+            provider: providerId,
             tools,
-            tool_execution: this.toolRegistry ? { mode: "client" } : void 0
+            customerId: options.customerId,
+            requestOptions: pendingRequestOptions,
+            contextOptions
           }
-        ],
-        outputs: [{ name: "result", from: "main" }]
+        };
+        return {
+          status: "waiting_for_tools",
+          pendingTools: mapPendingToolCalls(outcome.pendingToolCalls),
+          response: outcome.response,
+          usage
+        };
+      }
+      return {
+        status: "complete",
+        output: outcome.output,
+        response: outcome.response,
+        usage
       };
-      const run = await this.client.runs.create(spec, {
-        customerId: options.customerId
-      });
-      this.currentRunId = run.run_id;
-      return await this.processRunEvents(options.signal);
     } catch (err) {
       const error = err instanceof Error ? err : new Error(String(err));
       return {
         status: "error",
         error: error.message,
-        runId: this.currentRunId || parseRunId("unknown"),
-        usage: this.currentUsage,
-        events: this.currentEvents
+        cause: error,
+        usage: emptyUsage()
       };
     }
   }
   async submitToolResults(results) {
-    if (!this.currentRunId || !this.currentNodeId || !this.currentWaiting) {
+    if (!this.pendingLoop) {
       throw new Error("No pending tool calls to submit results for");
     }
-    await this.client.runs.submitToolResults(this.currentRunId, {
-      node_id: this.currentNodeId,
-      step: this.currentWaiting.step,
-      request_id: this.currentWaiting.request_id,
-      results: results.map((r) => ({
-        tool_call: {
-          id: r.toolCallId,
-          name: r.toolName
-        },
-        output: r.error ? `Error: ${r.error}` : typeof r.result === "string" ? r.result : JSON.stringify(r.result)
-      }))
+    const pending = this.pendingLoop;
+    this.pendingLoop = void 0;
+    if (pending.remainingTurns <= 0) {
+      throw new AgentMaxTurnsError(0);
+    }
+    const resultItems = results.map((result) => {
+      const content = result.error ? `Error: ${result.error}` : typeof result.result === "string" ? result.result : JSON.stringify(result.result);
+      return toolResultMessage(result.toolCallId, content);
     });
-    this.currentWaiting = void 0;
-    return await this.processRunEvents();
-  }
-  getArtifacts() {
-    return new Map(this.artifacts);
-  }
+    const baseInput = [...pending.input, ...resultItems];
+    try {
+      const prepared = await this.prepareInput(baseInput, pending.config.contextOptions);
+      const outcome = await runToolLoop({
+        client: this.client.responses,
+        input: prepared,
+        tools: pending.config.tools,
+        registry: this.toolRegistry,
+        maxTurns: pending.remainingTurns,
+        requestOptions: pending.config.requestOptions,
+        buildRequest: createRequestBuilder(pending.config)
+      });
+      const cleanInput = stripSystemPrompt(outcome.input, this.systemPrompt);
+      this.replaceHistory(cleanInput);
+      await this.persist();
+      const usage = mergeUsage(pending.usage, outcome.usage);
+      if (outcome.status === "waiting_for_tools") {
+        this.pendingLoop = {
+          input: cleanInput,
+          usage,
+          remainingTurns: remainingTurns(
+            pending.remainingTurns,
+            outcome.turnsUsed
+          ),
+          config: pending.config
+        };
+        return {
+          status: "waiting_for_tools",
+          pendingTools: mapPendingToolCalls(outcome.pendingToolCalls),
+          response: outcome.response,
+          usage
+        };
+      }
+      return {
+        status: "complete",
+        output: outcome.output,
+        response: outcome.response,
+        usage
+      };
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      return {
+        status: "error",
+        error: error.message,
+        cause: error,
+        usage: pending.usage
+      };
+    }
+  }
+  getArtifacts() {
+    return new Map(this.artifacts);
+  }
   async close() {
     await this.persist();
     await this.store.close();
   }
   /**
    * 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}`),
-   * });
-   * ```
    */
   async syncTo(remoteSession, options = {}) {
     const { onProgress, signal } = options;
@@ -2997,150 +3474,35 @@ var LocalSession = class _LocalSession {
   // ============================================================================
   // Private Methods
   // ============================================================================
-  addMessage(input, runId) {
-    const message = {
-      ...input,
-      seq: this.nextSeq++,
-      createdAt: /* @__PURE__ */ new Date(),
-      runId
-    };
-    this.messages.push(message);
-    this.updatedAt = /* @__PURE__ */ new Date();
-    return message;
-  }
-  async buildInput(options) {
-    return buildSessionInputWithContext(
-      this.messages,
-      options,
-      this.defaultModel,
-      this.resolveModelContext
-    );
-  }
-  async processRunEvents(signal) {
-    if (!this.currentRunId) {
-      throw new Error("No current run");
-    }
-    const eventStream = await this.client.runs.events(this.currentRunId, {
-      afterSeq: this.currentEvents.length
-    });
-    for await (const event of eventStream) {
-      if (signal?.aborted) {
-        return {
-          status: "canceled",
-          runId: this.currentRunId,
-          usage: this.currentUsage,
-          events: this.currentEvents
-        };
-      }
-      this.currentEvents.push(event);
-      switch (event.type) {
-        case "node_llm_call":
-          this.currentUsage = {
-            ...this.currentUsage,
-            llmCalls: this.currentUsage.llmCalls + 1,
-            inputTokens: this.currentUsage.inputTokens + (event.llm_call.usage?.input_tokens || 0),
-            outputTokens: this.currentUsage.outputTokens + (event.llm_call.usage?.output_tokens || 0),
-            totalTokens: this.currentUsage.totalTokens + (event.llm_call.usage?.total_tokens || 0)
-          };
-          break;
-        case "node_tool_call":
-          this.currentUsage = {
-            ...this.currentUsage,
-            toolCalls: this.currentUsage.toolCalls + 1
-          };
-          break;
-        case "node_waiting":
-          this.currentNodeId = event.node_id;
-          this.currentWaiting = event.waiting;
-          if (this.toolRegistry) {
-            const results = await this.executeTools(event.waiting.pending_tool_calls);
-            return await this.submitToolResults(results);
-          }
-          return {
-            status: "waiting_for_tools",
-            pendingTools: event.waiting.pending_tool_calls.map((tc) => ({
-              toolCallId: tc.tool_call.id,
-              name: tc.tool_call.name,
-              arguments: tc.tool_call.arguments
-            })),
-            runId: this.currentRunId,
-            usage: this.currentUsage,
-            events: this.currentEvents
-          };
-        case "run_completed":
-          const runState = await this.client.runs.get(this.currentRunId);
-          const output = extractTextOutput(runState.outputs || {});
-          if (output) {
-            this.addMessage(
-              {
-                type: "message",
-                role: "assistant",
-                content: [{ type: "text", text: output }]
-              },
-              this.currentRunId
-            );
-          }
-          await this.persist();
-          return {
-            status: "complete",
-            output,
-            runId: this.currentRunId,
-            usage: this.currentUsage,
-            events: this.currentEvents
-          };
-        case "run_failed":
-          return {
-            status: "error",
-            error: event.error.message,
-            runId: this.currentRunId,
-            usage: this.currentUsage,
-            events: this.currentEvents
-          };
-        case "run_canceled":
-          return {
-            status: "canceled",
-            error: event.error.message,
-            runId: this.currentRunId,
-            usage: this.currentUsage,
-            events: this.currentEvents
-          };
-      }
-    }
+  buildContextOptions(options) {
+    if (!this.contextManager) return null;
+    if (options.contextManagement === "none") return null;
     return {
-      status: "error",
-      error: "Run event stream ended unexpectedly",
-      runId: this.currentRunId,
-      usage: this.currentUsage,
-      events: this.currentEvents
+      model: options.model ?? this.defaultModel,
+      strategy: options.contextManagement,
+      maxHistoryTokens: options.maxHistoryTokens,
+      reserveOutputTokens: options.reserveOutputTokens,
+      onTruncate: options.onContextTruncate
     };
   }
-  async executeTools(pendingTools) {
-    if (!this.toolRegistry) {
-      throw new Error("No tool registry configured");
+  async prepareInput(input, contextOptions) {
+    let prepared = input;
+    if (this.systemPrompt) {
+      prepared = [createSystemMessage(this.systemPrompt), ...prepared];
     }
-    const results = [];
-    for (const pending of pendingTools) {
-      try {
-        const result = await this.toolRegistry.execute({
-          id: pending.tool_call.id,
-          type: "function",
-          function: {
-            name: pending.tool_call.name,
-            arguments: pending.tool_call.arguments
-          }
-        });
-        results.push(result);
-      } catch (err) {
-        const error = err instanceof Error ? err : new Error(String(err));
-        results.push({
-          toolCallId: pending.tool_call.id,
-          toolName: pending.tool_call.name,
-          result: null,
-          error: error.message
-        });
-      }
+    if (!this.contextManager || !contextOptions) {
+      return prepared;
     }
-    return results;
+    return this.contextManager.prepare(prepared, contextOptions);
+  }
+  replaceHistory(input) {
+    const now = /* @__PURE__ */ new Date();
+    this.messages = input.map((item, idx) => ({
+      ...item,
+      seq: idx + 1,
+      createdAt: now
+    }));
+    this.updatedAt = now;
   }
   async persist() {
     const state = {
@@ -3157,159 +3519,373 @@ var LocalSession = class _LocalSession {
     await this.store.save(state);
   }
 };
-function createStore(persistence, storagePath) {
+function createStore(custom, persistence, storagePath) {
+  if (custom) {
+    return custom;
+  }
   switch (persistence) {
     case "memory":
-      return createMemorySessionStore();
+      return createMemoryConversationStore();
     case "file":
-      throw new Error("File persistence not yet implemented");
+      return createFileConversationStore(storagePath);
     case "sqlite":
-      throw new Error("SQLite persistence not yet implemented");
+      return createSqliteConversationStore(storagePath);
     default:
       throw new Error(`Unknown persistence mode: ${persistence}`);
   }
 }
-function mergeTools(defaults, overrides) {
-  if (!defaults && !overrides) return void 0;
-  if (!defaults) return overrides;
-  if (!overrides) return defaults;
-  const merged = /* @__PURE__ */ new Map();
-  for (const tool of defaults) {
-    if (tool.type === "function" && tool.function) {
-      merged.set(tool.function.name, tool);
-    }
+function buildMessage(item, seq) {
+  return {
+    ...item,
+    seq,
+    createdAt: /* @__PURE__ */ new Date()
+  };
+}
+function stripSystemPrompt(input, systemPrompt) {
+  if (!systemPrompt || input.length === 0) {
+    return input;
   }
-  for (const tool of overrides) {
-    if (tool.type === "function" && tool.function) {
-      merged.set(tool.function.name, tool);
-    }
+  const [first, ...rest] = input;
+  if (first.role === "system" && first.content?.length === 1 && first.content[0].type === "text" && first.content[0].text === systemPrompt) {
+    return rest;
   }
-  return Array.from(merged.values());
+  return input;
 }
-function isOutputMessage(item) {
-  return typeof item === "object" && item !== null && "type" in item && typeof item.type === "string";
-}
-function isContentPiece(c) {
-  return typeof c === "object" && c !== null && "type" in c && typeof c.type === "string";
-}
-function hasOutputArray(obj) {
-  return "output" in obj && Array.isArray(obj.output);
-}
-function hasContentArray(obj) {
-  return "content" in obj && Array.isArray(obj.content);
-}
-function extractTextOutput(outputs) {
-  const result = outputs.result;
-  if (typeof result === "string") return result;
-  if (result && typeof result === "object") {
-    if (hasOutputArray(result)) {
-      const textParts = result.output.filter(
-        (item) => isOutputMessage(item) && item.type === "message" && item.role === "assistant"
-      ).flatMap(
-        (item) => (item.content || []).filter((c) => isContentPiece(c) && c.type === "text").map((c) => c.text ?? "")
-      ).filter((text) => text.length > 0);
-      if (textParts.length > 0) {
-        return textParts.join("\n");
-      }
-    }
-    if (hasContentArray(result)) {
-      const textParts = result.content.filter((c) => isContentPiece(c) && c.type === "text").map((c) => c.text ?? "").filter((text) => text.length > 0);
-      if (textParts.length > 0) {
-        return textParts.join("\n");
-      }
+function mapPendingToolCalls(calls) {
+  return calls.map((call) => {
+    if (!call.function?.name) {
+      throw new Error(`Tool call ${call.id} missing function name`);
     }
+    return {
+      toolCallId: call.id,
+      name: call.function.name,
+      arguments: call.function.arguments ?? "{}"
+    };
+  });
+}
+function remainingTurns(maxTurns, turnsUsed) {
+  if (maxTurns === Number.MAX_SAFE_INTEGER) {
+    return maxTurns;
   }
-  return void 0;
+  return Math.max(0, maxTurns - turnsUsed);
+}
+function mergeUsage(base, add) {
+  return {
+    inputTokens: base.inputTokens + add.inputTokens,
+    outputTokens: base.outputTokens + add.outputTokens,
+    totalTokens: base.totalTokens + add.totalTokens,
+    llmCalls: base.llmCalls + add.llmCalls,
+    toolCalls: base.toolCalls + add.toolCalls
+  };
 }
 function createLocalSession(client, options = {}) {
   return LocalSession.create(client, options);
 }
 
-// src/sessions/remote_session.ts
-var RemoteSession = class _RemoteSession {
-  constructor(client, http, sessionData, options = {}) {
-    this.type = "remote";
-    this.messages = [];
-    this.artifacts = /* @__PURE__ */ new Map();
-    this.nextSeq = 1;
-    this.pendingMessages = [];
-    this.currentEvents = [];
-    this.currentUsage = {
-      inputTokens: 0,
-      outputTokens: 0,
-      totalTokens: 0,
-      llmCalls: 0,
-      toolCalls: 0
-    };
-    this.client = client;
-    this.http = http;
-    this.id = asSessionId(sessionData.id);
-    this.metadata = sessionData.metadata;
-    this.customerId = sessionData.customer_id || options.customerId;
-    this.createdAt = new Date(sessionData.created_at);
-    this.updatedAt = new Date(sessionData.updated_at);
-    this.toolRegistry = options.toolRegistry;
-    this.defaultModel = options.defaultModel;
-    this.defaultProvider = options.defaultProvider;
-    this.defaultTools = options.defaultTools;
-    this.resolveModelContext = createModelContextResolver(client);
-    if ("messages" in sessionData && sessionData.messages) {
-      this.messages = sessionData.messages.map((m) => ({
-        type: "message",
-        role: m.role,
-        content: m.content,
-        seq: m.seq,
-        createdAt: new Date(m.created_at),
-        runId: m.run_id ? parseRunId(m.run_id) : void 0
-      }));
-      this.nextSeq = this.messages.length + 1;
+// src/context_manager.ts
+var DEFAULT_CONTEXT_BUFFER_TOKENS = 256;
+var CONTEXT_BUFFER_RATIO = 0.02;
+var MESSAGE_OVERHEAD_TOKENS = 6;
+var TOOL_CALL_OVERHEAD_TOKENS = 4;
+var CHARS_PER_TOKEN = 4;
+var IMAGE_TOKENS_LOW_DETAIL = 85;
+var IMAGE_TOKENS_HIGH_DETAIL = 1e3;
+var modelContextCache = /* @__PURE__ */ new WeakMap();
+function createModelContextResolver(client) {
+  return async (modelId) => {
+    const entry = getModelContextCacheEntry(client);
+    const key = String(modelId);
+    const cached = entry.byId.get(key);
+    if (cached !== void 0) {
+      return cached;
+    }
+    await populateModelContextCache(client, entry);
+    const resolved = entry.byId.get(key);
+    if (resolved === void 0) {
+      throw new ConfigError(
+        `Unknown model "${key}"; ensure the model exists in the ModelRelay catalog`
+      );
     }
+    return resolved;
+  };
+}
+var ContextManager = class {
+  constructor(resolveModelContext, defaults = {}) {
+    this.resolveModelContext = resolveModelContext;
+    this.defaults = defaults;
+  }
+  async prepare(input, options = {}) {
+    const merged = {
+      ...this.defaults,
+      ...options
+    };
+    return prepareInputWithContext(input, merged, this.resolveModelContext);
   }
-  /**
-   * Create a new remote session on the server.
-   *
-   * @param client - ModelRelay client
-   * @param options - Session configuration
-   * @returns A new RemoteSession instance
-   */
-  static async create(client, options = {}) {
-    const http = getHTTPClient(client);
-    const response = await http.request("/sessions", {
-      method: "POST",
-      body: {
-        customer_id: options.customerId,
-        metadata: options.metadata || {}
-      }
-    });
-    const data = await response.json();
-    return new _RemoteSession(client, http, data, options);
+};
+async function prepareInputWithContext(input, options, resolveModelContext) {
+  const strategy = options.strategy ?? "truncate";
+  if (strategy === "summarize") {
+    throw new ConfigError("context management 'summarize' is not implemented yet");
   }
-  /**
-   * Get an existing remote session by ID.
-   *
-   * @param client - ModelRelay client
-   * @param sessionId - ID of the session to retrieve
-   * @param options - Optional configuration (toolRegistry, defaults)
-   * @returns The RemoteSession instance
-   */
-  static async get(client, sessionId, options = {}) {
-    const http = getHTTPClient(client);
-    const id = typeof sessionId === "string" ? sessionId : String(sessionId);
-    const response = await http.request(`/sessions/${id}`, {
-      method: "GET"
-    });
-    const data = await response.json();
-    return new _RemoteSession(client, http, data, options);
+  if (strategy !== "truncate") {
+    throw new ConfigError(`Unknown context management strategy: ${strategy}`);
   }
-  /**
-   * List remote sessions.
-   *
-   * @param client - ModelRelay client
-   * @param options - List options
-   * @returns Paginated list of session info
-   */
-  static async list(client, options = {}) {
-    const http = getHTTPClient(client);
+  const budget = await resolveHistoryBudget(
+    options.model,
+    options,
+    resolveModelContext
+  );
+  const truncated = truncateInputByTokens(input, budget.maxHistoryTokens);
+  if (options.onTruncate && truncated.length < input.length) {
+    if (!options.model) {
+      throw new ConfigError(
+        "model is required for context management; set options.model"
+      );
+    }
+    const info = {
+      model: options.model,
+      originalMessages: input.length,
+      keptMessages: truncated.length,
+      maxHistoryTokens: budget.maxHistoryTokens,
+      reservedOutputTokens: budget.reservedOutputTokens
+    };
+    options.onTruncate(info);
+  }
+  return truncated;
+}
+function truncateInputByTokens(input, maxHistoryTokens) {
+  const maxTokens = normalizePositiveInt(maxHistoryTokens, "maxHistoryTokens");
+  if (input.length === 0) return [];
+  const tokensByIndex = input.map((msg) => estimateTokensForMessage(msg));
+  const systemIndices = input.map((msg, idx) => msg.role === "system" ? idx : -1).filter((idx) => idx >= 0);
+  let selectedSystem = [...systemIndices];
+  let systemTokens = sumTokens(tokensByIndex, selectedSystem);
+  while (systemTokens > maxTokens && selectedSystem.length > 1) {
+    selectedSystem.shift();
+    systemTokens = sumTokens(tokensByIndex, selectedSystem);
+  }
+  if (systemTokens > maxTokens) {
+    throw new ConfigError(
+      "maxHistoryTokens is too small to fit the latest system message"
+    );
+  }
+  const selected = new Set(selectedSystem);
+  let remaining = maxTokens - systemTokens;
+  for (let i = input.length - 1; i >= 0; i -= 1) {
+    if (selected.has(i)) continue;
+    const tokens = tokensByIndex[i];
+    if (tokens <= remaining) {
+      selected.add(i);
+      remaining -= tokens;
+    }
+  }
+  const result = input.filter((_, idx) => selected.has(idx));
+  if (result.length === 0) {
+    throw new ConfigError("No messages fit within maxHistoryTokens");
+  }
+  return result;
+}
+function estimateTokens(text) {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+function isImagePart(part) {
+  if (typeof part !== "object" || part === null) return false;
+  const p = part;
+  return p.type === "image" || p.type === "image_url";
+}
+function estimateImageTokens(part) {
+  const detail = part.detail ?? "auto";
+  if (detail === "low") return IMAGE_TOKENS_LOW_DETAIL;
+  return IMAGE_TOKENS_HIGH_DETAIL;
+}
+function estimateTokensForMessage(message) {
+  const segments = [message.role];
+  let imageTokens = 0;
+  for (const part of message.content || []) {
+    if (part.type === "text" && part.text) {
+      segments.push(part.text);
+    } else if (isImagePart(part)) {
+      imageTokens += estimateImageTokens(part);
+    }
+  }
+  if (message.toolCalls) {
+    for (const call of message.toolCalls) {
+      if (call.function?.name) segments.push(call.function.name);
+      if (call.function?.arguments) segments.push(call.function.arguments);
+    }
+  }
+  if (message.toolCallId) {
+    segments.push(message.toolCallId);
+  }
+  const textTokens = estimateTokens(segments.join("\n"));
+  const toolOverhead = message.toolCalls ? message.toolCalls.length * TOOL_CALL_OVERHEAD_TOKENS : 0;
+  return textTokens + MESSAGE_OVERHEAD_TOKENS + toolOverhead + imageTokens;
+}
+function normalizePositiveInt(value, label) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new ConfigError(`${label} must be a positive number`);
+  }
+  return Math.floor(value);
+}
+function sumTokens(tokensByIndex, indices) {
+  return indices.reduce((sum, idx) => sum + tokensByIndex[idx], 0);
+}
+async function resolveHistoryBudget(modelId, options, resolveModelContext) {
+  const reservedOutputTokens = options.reserveOutputTokens === void 0 ? void 0 : normalizeNonNegativeInt(
+    options.reserveOutputTokens,
+    "reserveOutputTokens"
+  );
+  if (options.maxHistoryTokens !== void 0) {
+    return {
+      maxHistoryTokens: normalizePositiveInt(
+        options.maxHistoryTokens,
+        "maxHistoryTokens"
+      ),
+      reservedOutputTokens
+    };
+  }
+  if (!modelId) {
+    throw new ConfigError(
+      "model is required for context management when maxHistoryTokens is not set"
+    );
+  }
+  const model = await resolveModelContext(modelId);
+  if (!model) {
+    throw new ConfigError(
+      `Unknown model "${modelId}"; ensure the model exists in the ModelRelay catalog`
+    );
+  }
+  const contextWindow = normalizePositiveInt(model.contextWindow, "context_window");
+  const modelOutputTokens = model.maxOutputTokens === void 0 ? 0 : normalizeNonNegativeInt(model.maxOutputTokens, "max_output_tokens");
+  const effectiveReserve = reservedOutputTokens ?? modelOutputTokens;
+  const buffer = Math.max(
+    DEFAULT_CONTEXT_BUFFER_TOKENS,
+    Math.ceil(contextWindow * CONTEXT_BUFFER_RATIO)
+  );
+  const maxHistoryTokens = contextWindow - effectiveReserve - buffer;
+  if (maxHistoryTokens <= 0) {
+    throw new ConfigError(
+      "model context window is too small after reserving output tokens; set maxHistoryTokens explicitly"
+    );
+  }
+  return {
+    maxHistoryTokens,
+    reservedOutputTokens: effectiveReserve
+  };
+}
+function normalizeNonNegativeInt(value, label) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new ConfigError(`${label} must be a non-negative number`);
+  }
+  return Math.floor(value);
+}
+function getModelContextCacheEntry(client) {
+  const existing = modelContextCache.get(client);
+  if (existing) return existing;
+  const entry = { byId: /* @__PURE__ */ new Map() };
+  modelContextCache.set(client, entry);
+  return entry;
+}
+async function populateModelContextCache(client, entry) {
+  if (!entry.listPromise) {
+    entry.listPromise = (async () => {
+      const response = await client.http.json("/models");
+      for (const model of response.models) {
+        entry.byId.set(model.model_id, {
+          contextWindow: model.context_window,
+          maxOutputTokens: model.max_output_tokens ?? void 0
+        });
+      }
+    })();
+  }
+  await entry.listPromise;
+}
+
+// src/sessions/remote_session.ts
+var RemoteSession = class _RemoteSession {
+  constructor(client, http, sessionData, options = {}) {
+    this.type = "remote";
+    this.messages = [];
+    this.artifacts = /* @__PURE__ */ new Map();
+    this.nextSeq = 1;
+    this.pendingMessages = [];
+    this.currentEvents = [];
+    this.currentUsage = {
+      inputTokens: 0,
+      outputTokens: 0,
+      totalTokens: 0,
+      llmCalls: 0,
+      toolCalls: 0
+    };
+    this.client = client;
+    this.http = http;
+    this.id = asSessionId(sessionData.id);
+    this.metadata = sessionData.metadata;
+    this.customerId = sessionData.customer_id || options.customerId;
+    this.createdAt = new Date(sessionData.created_at);
+    this.updatedAt = new Date(sessionData.updated_at);
+    this.toolRegistry = options.toolRegistry;
+    this.defaultModel = options.defaultModel;
+    this.defaultProvider = options.defaultProvider;
+    this.defaultTools = options.defaultTools;
+    this.resolveModelContext = createModelContextResolver(client);
+    if ("messages" in sessionData && sessionData.messages) {
+      this.messages = sessionData.messages.map((m) => ({
+        type: "message",
+        role: m.role,
+        content: m.content,
+        seq: m.seq,
+        createdAt: new Date(m.created_at),
+        runId: m.run_id ? parseRunId(m.run_id) : void 0
+      }));
+      this.nextSeq = this.messages.length + 1;
+    }
+  }
+  /**
+   * Create a new remote session on the server.
+   *
+   * @param client - ModelRelay client
+   * @param options - Session configuration
+   * @returns A new RemoteSession instance
+   */
+  static async create(client, options = {}) {
+    const http = client.http;
+    const response = await http.request("/sessions", {
+      method: "POST",
+      body: {
+        customer_id: options.customerId,
+        metadata: options.metadata || {}
+      }
+    });
+    const data = await response.json();
+    return new _RemoteSession(client, http, data, options);
+  }
+  /**
+   * Get an existing remote session by ID.
+   *
+   * @param client - ModelRelay client
+   * @param sessionId - ID of the session to retrieve
+   * @param options - Optional configuration (toolRegistry, defaults)
+   * @returns The RemoteSession instance
+   */
+  static async get(client, sessionId, options = {}) {
+    const http = client.http;
+    const id = typeof sessionId === "string" ? sessionId : String(sessionId);
+    const response = await http.request(`/sessions/${id}`, {
+      method: "GET"
+    });
+    const data = await response.json();
+    return new _RemoteSession(client, http, data, options);
+  }
+  /**
+   * List remote sessions.
+   *
+   * @param client - ModelRelay client
+   * @param options - List options
+   * @returns Paginated list of session info
+   */
+  static async list(client, options = {}) {
+    const http = client.http;
     const params = new URLSearchParams();
     if (options.limit) params.set("limit", String(options.limit));
     if (options.offset) params.set("offset", String(options.offset));
@@ -3337,7 +3913,7 @@ var RemoteSession = class _RemoteSession {
    * @param sessionId - ID of the session to delete
    */
   static async delete(client, sessionId) {
-    const http = getHTTPClient(client);
+    const http = client.http;
     const id = typeof sessionId === "string" ? sessionId : String(sessionId);
     await http.request(`/sessions/${id}`, {
       method: "DELETE"
@@ -3364,21 +3940,22 @@ var RemoteSession = class _RemoteSession {
     this.resetRunState();
     try {
       const input = await this.buildInput(options);
-      const tools = mergeTools2(this.defaultTools, options.tools);
+      const tools = mergeTools(this.defaultTools, options.tools);
+      const mainNodeId = parseNodeId("main");
       const spec = {
         kind: "workflow",
         name: `session-${this.id}-turn-${this.nextSeq}`,
         model: options.model || this.defaultModel,
         nodes: [
           {
-            id: "main",
+            id: mainNodeId,
             type: "llm",
             input,
             tools,
             tool_execution: this.toolRegistry ? { mode: "client" } : void 0
           }
         ],
-        outputs: [{ name: "result", from: "main" }]
+        outputs: [{ name: parseOutputName("result"), from: mainNodeId }]
       };
       const run = await this.client.runs.create(spec, {
         customerId: options.customerId || this.customerId,
@@ -3391,7 +3968,8 @@ var RemoteSession = class _RemoteSession {
       return {
         status: "error",
         error: error.message,
-        runId: this.currentRunId || parseRunId("unknown"),
+        cause: error,
+        runId: this.currentRunId,
         usage: { ...this.currentUsage },
         events: [...this.currentEvents]
       };
@@ -3470,10 +4048,25 @@ var RemoteSession = class _RemoteSession {
     return message;
   }
   async buildInput(options) {
-    return buildSessionInputWithContext(
-      this.messages,
-      options,
-      this.defaultModel,
+    const baseInput = messagesToInput(this.messages);
+    if (!options.contextManagement || options.contextManagement === "none") {
+      return baseInput;
+    }
+    const modelId = options.model ?? this.defaultModel;
+    if (!modelId) {
+      throw new ConfigError(
+        "model is required for context management; set options.model or a session defaultModel"
+      );
+    }
+    return prepareInputWithContext(
+      baseInput,
+      {
+        model: modelId,
+        strategy: options.contextManagement,
+        maxHistoryTokens: options.maxHistoryTokens,
+        reserveOutputTokens: options.reserveOutputTokens,
+        onTruncate: options.onContextTruncate
+      },
       this.resolveModelContext
     );
   }
@@ -3482,13 +4075,7 @@ var RemoteSession = class _RemoteSession {
     this.currentNodeId = void 0;
     this.currentWaiting = void 0;
     this.currentEvents = [];
-    this.currentUsage = {
-      inputTokens: 0,
-      outputTokens: 0,
-      totalTokens: 0,
-      llmCalls: 0,
-      toolCalls: 0
-    };
+    this.currentUsage = emptyUsage();
   }
   async processRunEvents(signal) {
     if (!this.currentRunId) {
@@ -3727,26 +4314,6 @@ var RemoteSession = class _RemoteSession {
     return text.trim() ? text : void 0;
   }
 };
-function getHTTPClient(client) {
-  return client.http;
-}
-function mergeTools2(defaults, overrides) {
-  if (!defaults && !overrides) return void 0;
-  if (!defaults) return overrides;
-  if (!overrides) return defaults;
-  const merged = /* @__PURE__ */ new Map();
-  for (const tool of defaults) {
-    if (tool.type === "function" && tool.function) {
-      merged.set(tool.function.name, tool);
-    }
-  }
-  for (const tool of overrides) {
-    if (tool.type === "function" && tool.function) {
-      merged.set(tool.function.name, tool);
-    }
-  }
-  return Array.from(merged.values());
-}
 
 // src/sessions/client.ts
 var SessionsClient = class {
@@ -3863,111 +4430,1487 @@ var SessionsClient = class {
       customerId: options.customerId
     });
   }
-  /**
-   * Delete a remote session.
-   *
-   * Requires a secret key.
-   *
-   * @param sessionId - ID of the session to delete
-   *
-   * @example
-   * ```typescript
-   * await client.sessions.delete("session-id");
-   * ```
-   */
-  async delete(sessionId) {
-    return RemoteSession.delete(this.modelRelay, sessionId);
+  /**
+   * Delete a remote session.
+   *
+   * Requires a secret key.
+   *
+   * @param sessionId - ID of the session to delete
+   *
+   * @example
+   * ```typescript
+   * await client.sessions.delete("session-id");
+   * ```
+   */
+  async delete(sessionId) {
+    return RemoteSession.delete(this.modelRelay, sessionId);
+  }
+};
+
+// src/tiers.ts
+function defaultTierModelId(tier) {
+  const def = tier.models.find((m) => m.is_default);
+  if (def) return def.model_id;
+  if (tier.models.length === 1) return tier.models[0].model_id;
+  return void 0;
+}
+var TiersClient = class {
+  constructor(http, cfg) {
+    this.http = http;
+    this.apiKey = cfg.apiKey ? parseApiKey(cfg.apiKey) : void 0;
+    this.hasSecretKey = this.apiKey ? isSecretKey(this.apiKey) : false;
+    this.hasAccessToken = !!cfg.accessToken?.trim();
+  }
+  ensureAuth() {
+    if (!this.apiKey && !this.hasAccessToken) {
+      throw new ConfigError(
+        "API key (mr_sk_*) or bearer token required for tier operations"
+      );
+    }
+  }
+  ensureSecretKey() {
+    if (!this.apiKey || !this.hasSecretKey) {
+      throw new ConfigError(
+        "Secret key (mr_sk_*) required for checkout operations"
+      );
+    }
+  }
+  /**
+   * List all tiers in the project.
+   */
+  async list() {
+    this.ensureAuth();
+    const response = await this.http.json("/tiers", {
+      method: "GET",
+      apiKey: this.apiKey
+    });
+    return response.tiers;
+  }
+  /**
+   * Get a tier by ID.
+   */
+  async get(tierId) {
+    this.ensureAuth();
+    if (!tierId?.trim()) {
+      throw new ConfigError("tierId is required");
+    }
+    const response = await this.http.json(`/tiers/${tierId}`, {
+      method: "GET",
+      apiKey: this.apiKey
+    });
+    return response.tier;
+  }
+  /**
+   * Create a Stripe checkout session for a tier (Stripe-first flow).
+   *
+   * This enables users to subscribe before authenticating. Stripe collects
+   * the customer's email during checkout. After checkout completes, a
+   * customer record is created with the email from Stripe. Your backend
+   * can map it to your app user and mint customer tokens as needed.
+   *
+   * Requires a secret key (mr_sk_*).
+   *
+   * @param tierId - The tier ID to create a checkout session for
+   * @param request - Checkout session request with redirect URLs
+   * @returns Checkout session with Stripe URL
+   */
+  async checkout(tierId, request) {
+    this.ensureSecretKey();
+    if (!tierId?.trim()) {
+      throw new ConfigError("tierId is required");
+    }
+    if (!request.success_url?.trim()) {
+      throw new ConfigError("success_url is required");
+    }
+    if (!request.cancel_url?.trim()) {
+      throw new ConfigError("cancel_url is required");
+    }
+    return await this.http.json(
+      `/tiers/${tierId}/checkout`,
+      {
+        method: "POST",
+        apiKey: this.apiKey,
+        body: request
+      }
+    );
+  }
+};
+
+// src/plugins.ts
+import { z as z2 } from "zod";
+
+// src/tools_user_ask.ts
+var USER_ASK_TOOL_NAME = "user.ask";
+var userAskSchema = {
+  type: "object",
+  properties: {
+    question: {
+      type: "string",
+      minLength: 1,
+      description: "The question to ask the user."
+    },
+    options: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          label: { type: "string", minLength: 1 },
+          description: { type: "string" }
+        },
+        required: ["label"]
+      },
+      description: "Optional multiple choice options."
+    },
+    allow_freeform: {
+      type: "boolean",
+      default: true,
+      description: "Allow user to type a custom response."
+    }
+  },
+  required: ["question"]
+};
+function createUserAskTool() {
+  return createFunctionTool(
+    USER_ASK_TOOL_NAME,
+    "Ask the user a clarifying question.",
+    userAskSchema
+  );
+}
+function isUserAskToolCall(call) {
+  return call.type === "function" && call.function?.name === USER_ASK_TOOL_NAME;
+}
+function parseUserAskArgs(call) {
+  const raw = getToolArgsRaw(call);
+  if (!raw) {
+    throw new ToolArgumentError({
+      message: "user.ask arguments required",
+      toolCallId: call.id,
+      toolName: USER_ASK_TOOL_NAME,
+      rawArguments: raw
+    });
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new ToolArgumentError({
+      message: "user.ask arguments must be valid JSON",
+      toolCallId: call.id,
+      toolName: USER_ASK_TOOL_NAME,
+      rawArguments: raw,
+      cause: err
+    });
+  }
+  const question = parsed.question?.trim?.() ?? "";
+  if (!question) {
+    throw new ToolArgumentError({
+      message: "user.ask question required",
+      toolCallId: call.id,
+      toolName: USER_ASK_TOOL_NAME,
+      rawArguments: raw
+    });
+  }
+  if (parsed.options?.length) {
+    for (const opt of parsed.options) {
+      if (!opt?.label?.trim?.()) {
+        throw new ToolArgumentError({
+          message: "user.ask options require label",
+          toolCallId: call.id,
+          toolName: USER_ASK_TOOL_NAME,
+          rawArguments: raw
+        });
+      }
+    }
+  }
+  return {
+    question,
+    options: parsed.options,
+    allow_freeform: parsed.allow_freeform
+  };
+}
+function serializeUserAskResult(result) {
+  const answer = result.answer?.trim?.() ?? "";
+  if (!answer) {
+    throw new ToolArgumentError({
+      message: "user.ask answer required",
+      toolCallId: "",
+      toolName: USER_ASK_TOOL_NAME,
+      rawArguments: ""
+    });
+  }
+  return JSON.stringify({ answer, is_freeform: result.is_freeform });
+}
+function userAskResultFreeform(answer) {
+  return serializeUserAskResult({ answer, is_freeform: true });
+}
+function userAskResultChoice(answer) {
+  return serializeUserAskResult({ answer, is_freeform: false });
+}
+
+// src/tools_runner.ts
+var ToolRunner = class {
+  constructor(options) {
+    this.registry = options.registry;
+    this.runsClient = options.runsClient;
+    this.customerId = options.customerId;
+    this.onBeforeExecute = options.onBeforeExecute;
+    this.onAfterExecute = options.onAfterExecute;
+    this.onSubmitted = options.onSubmitted;
+    this.onUserAsk = options.onUserAsk;
+    this.onError = options.onError;
+  }
+  /**
+   * Handles a node_waiting event by executing tools and submitting results.
+   *
+   * @param runId - The run ID
+   * @param nodeId - The node ID that is waiting
+   * @param waiting - The waiting state with pending tool calls
+   * @returns The submission response with accepted count and new status
+   *
+   * @example
+   * ```typescript
+   * for await (const event of client.runs.events(runId)) {
+   *   if (event.type === "node_waiting") {
+   *     const result = await runner.handleNodeWaiting(
+   *       runId,
+   *       event.node_id,
+   *       event.waiting
+   *     );
+   *     console.log(`Submitted ${result.accepted} results, status: ${result.status}`);
+   *   }
+   * }
+   * ```
+   */
+  async handleNodeWaiting(runId, nodeId, waiting) {
+    const results = [];
+    for (const pending of waiting.pending_tool_calls) {
+      try {
+        await this.onBeforeExecute?.(pending);
+        const toolCall = createToolCall(
+          pending.tool_call.id,
+          pending.tool_call.name,
+          pending.tool_call.arguments
+        );
+        let result;
+        if (pending.tool_call.name === USER_ASK_TOOL_NAME) {
+          if (!this.onUserAsk) {
+            throw new Error("user.ask requires onUserAsk handler");
+          }
+          const args = parseUserAskArgs(toolCall);
+          const response2 = await this.onUserAsk(pending, args);
+          const output = typeof response2 === "string" ? serializeUserAskResult({ answer: response2, is_freeform: true }) : serializeUserAskResult(response2);
+          result = {
+            toolCallId: pending.tool_call.id,
+            toolName: pending.tool_call.name,
+            result: output,
+            isRetryable: false
+          };
+        } else {
+          result = await this.registry.execute(toolCall);
+        }
+        results.push(result);
+        await this.onAfterExecute?.(result);
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        await this.onError?.(error, pending);
+        results.push({
+          toolCallId: pending.tool_call.id,
+          toolName: pending.tool_call.name,
+          result: null,
+          error: error.message
+        });
+      }
+    }
+    const response = await this.runsClient.submitToolResults(
+      runId,
+      {
+        node_id: nodeId,
+        step: waiting.step,
+        request_id: waiting.request_id,
+        results: results.map((r) => ({
+          tool_call: {
+            id: r.toolCallId,
+            name: r.toolName
+          },
+          output: r.error ? `Error: ${r.error}` : typeof r.result === "string" ? r.result : JSON.stringify(r.result)
+        }))
+      },
+      { customerId: this.customerId }
+    );
+    await this.onSubmitted?.(runId, response.accepted, response.status);
+    return {
+      accepted: response.accepted,
+      status: response.status,
+      results
+    };
+  }
+  /**
+   * Processes a stream of run events, automatically handling node_waiting events.
+   *
+   * This is the main entry point for running a workflow with client-side tools.
+   * It yields all events through (including node_waiting after handling).
+   *
+   * @param runId - The run ID to process
+   * @param events - AsyncIterable of run events (from RunsClient.events())
+   * @yields All run events, with node_waiting events handled automatically
+   *
+   * @example
+   * ```typescript
+   * const run = await client.runs.create(workflowSpec);
+   * const eventStream = client.runs.events(run.run_id);
+   *
+   * for await (const event of runner.processEvents(run.run_id, eventStream)) {
+   *   switch (event.type) {
+   *     case "node_started":
+   *       console.log(`Node ${event.node_id} started`);
+   *       break;
+   *     case "node_succeeded":
+   *       console.log(`Node ${event.node_id} succeeded`);
+   *       break;
+   *     case "run_succeeded":
+   *       console.log("Run completed!");
+   *       break;
+   *   }
+   * }
+   * ```
+   */
+  async *processEvents(runId, events) {
+    for await (const event of events) {
+      if (event.type === "node_waiting") {
+        const waitingEvent = event;
+        try {
+          await this.handleNodeWaiting(
+            runId,
+            waitingEvent.node_id,
+            waitingEvent.waiting
+          );
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          await this.onError?.(error);
+          throw error;
+        }
+      }
+      yield event;
+    }
+  }
+  /**
+   * Checks if a run event is a node_waiting event.
+   * Utility for filtering events when not using processEvents().
+   */
+  static isNodeWaiting(event) {
+    return event.type === "node_waiting";
+  }
+  /**
+   * Checks if a run status is terminal (succeeded, failed, or canceled).
+   * Utility for determining when to stop polling.
+   */
+  static isTerminalStatus(status) {
+    return status === "succeeded" || status === "failed" || status === "canceled";
+  }
+};
+function createToolRunner(options) {
+  return new ToolRunner(options);
+}
+
+// src/plugins.ts
+var PluginToolNames = {
+  FS_READ_FILE: "fs.read_file",
+  FS_LIST_FILES: "fs.list_files",
+  FS_SEARCH: "fs.search",
+  FS_EDIT: "fs.edit",
+  BASH: "bash",
+  WRITE_FILE: "write_file",
+  USER_ASK: "user.ask"
+};
+var OrchestrationModes = {
+  DAG: "dag",
+  Dynamic: "dynamic"
+};
+var PluginOrchestrationErrorCodes = {
+  InvalidPlan: "INVALID_PLAN",
+  UnknownAgent: "UNKNOWN_AGENT",
+  MissingDescription: "MISSING_DESCRIPTION",
+  UnknownTool: "UNKNOWN_TOOL",
+  InvalidDependency: "INVALID_DEPENDENCY",
+  InvalidToolConfig: "INVALID_TOOL_CONFIG"
+};
+var PluginOrchestrationError = class extends Error {
+  constructor(code, message) {
+    super(`plugin orchestration: ${message}`);
+    this.code = code;
+  }
+};
+var DEFAULT_PLUGIN_REF = "HEAD";
+var DEFAULT_CACHE_TTL_MS = 5 * 6e4;
+var DEFAULT_GITHUB_API_BASE = "https://api.github.com";
+var DEFAULT_GITHUB_RAW_BASE = "https://raw.githubusercontent.com";
+var defaultDynamicToolNames = [
+  PluginToolNames.FS_READ_FILE,
+  PluginToolNames.FS_LIST_FILES,
+  PluginToolNames.FS_SEARCH
+];
+var allowedToolSet = new Set(Object.values(PluginToolNames));
+var workflowIntentSchema = z2.object({
+  kind: z2.literal(WorkflowKinds.WorkflowIntent),
+  name: z2.string().optional(),
+  model: z2.string().optional(),
+  max_parallelism: z2.number().int().positive().optional(),
+  inputs: z2.array(
+    z2.object({
+      name: z2.string().min(1),
+      type: z2.string().optional(),
+      required: z2.boolean().optional(),
+      description: z2.string().optional(),
+      default: z2.unknown().optional()
+    })
+  ).optional(),
+  nodes: z2.array(
+    z2.object({
+      id: z2.string().min(1),
+      type: z2.enum([
+        WorkflowNodeTypesIntent.LLM,
+        WorkflowNodeTypesIntent.JoinAll,
+        WorkflowNodeTypesIntent.JoinAny,
+        WorkflowNodeTypesIntent.JoinCollect,
+        WorkflowNodeTypesIntent.TransformJSON,
+        WorkflowNodeTypesIntent.MapFanout
+      ]),
+      depends_on: z2.array(z2.string().min(1)).optional(),
+      model: z2.string().optional(),
+      system: z2.string().optional(),
+      user: z2.string().optional(),
+      input: z2.array(z2.unknown()).optional(),
+      stream: z2.boolean().optional(),
+      tools: z2.array(
+        z2.union([
+          z2.string(),
+          z2.object({}).passthrough()
+        ])
+      ).optional(),
+      tool_execution: z2.object({ mode: z2.enum(["server", "client", "agentic"]) }).optional(),
+      limit: z2.number().int().positive().optional(),
+      timeout_ms: z2.number().int().positive().optional(),
+      predicate: z2.object({}).passthrough().optional(),
+      items_from: z2.string().optional(),
+      items_from_input: z2.string().optional(),
+      items_pointer: z2.string().optional(),
+      items_path: z2.string().optional(),
+      subnode: z2.object({}).passthrough().optional(),
+      max_parallelism: z2.number().int().positive().optional(),
+      object: z2.record(z2.unknown()).optional(),
+      merge: z2.array(z2.unknown()).optional()
+    }).passthrough()
+  ).min(1),
+  outputs: z2.array(
+    z2.object({
+      name: z2.string().min(1),
+      from: z2.string().min(1),
+      pointer: z2.string().optional()
+    })
+  ).min(1)
+}).passthrough();
+var orchestrationPlanSchema = z2.object({
+  kind: z2.literal("orchestration.plan.v1"),
+  max_parallelism: z2.number().int().positive().optional(),
+  steps: z2.array(
+    z2.object({
+      id: z2.string().min(1).optional(),
+      depends_on: z2.array(z2.string().min(1)).optional(),
+      agents: z2.array(
+        z2.object({
+          id: z2.string().min(1),
+          reason: z2.string().min(1)
+        })
+      ).min(1)
+    }).strict()
+  ).min(1)
+}).strict();
+var PluginLoader = class {
+  constructor(options = {}) {
+    this.cache = /* @__PURE__ */ new Map();
+    this.fetchFn = options.fetch || globalThis.fetch;
+    if (!this.fetchFn) {
+      throw new ConfigError("fetch is required to load plugins");
+    }
+    this.apiBaseUrl = options.apiBaseUrl || DEFAULT_GITHUB_API_BASE;
+    this.rawBaseUrl = options.rawBaseUrl || DEFAULT_GITHUB_RAW_BASE;
+    this.cacheTtlMs = options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    this.now = options.now || (() => /* @__PURE__ */ new Date());
+  }
+  async load(sourceUrl, options = {}) {
+    const ref = parseGitHubPluginRef(sourceUrl);
+    const key = ref.canonical;
+    const cached = this.cache.get(key);
+    if (cached && cached.expiresAt > this.now().getTime()) {
+      return clonePlugin(cached.plugin);
+    }
+    const manifestCandidates = ["PLUGIN.md", "SKILL.md"];
+    let manifestPath = "";
+    let manifestMd = "";
+    for (const candidate of manifestCandidates) {
+      const path = joinRepoPath(ref.repoPath, candidate);
+      const url = this.rawUrl(ref, path);
+      const res = await this.fetchText(url, options.signal);
+      if (res.status === 404) {
+        continue;
+      }
+      if (!res.ok) {
+        throw new ConfigError(`fetch ${path}: ${res.statusText}`);
+      }
+      manifestPath = path;
+      manifestMd = res.body;
+      break;
+    }
+    if (!manifestPath) {
+      throw new ConfigError("plugin manifest not found");
+    }
+    const commandsDir = joinRepoPath(ref.repoPath, "commands");
+    const agentsDir = joinRepoPath(ref.repoPath, "agents");
+    const commandFiles = await this.listMarkdownFiles(ref, commandsDir, options.signal);
+    const agentFiles = await this.listMarkdownFiles(ref, agentsDir, options.signal);
+    const plugin = {
+      id: asPluginId(`${ref.owner}/${ref.repo}${ref.repoPath ? `/${ref.repoPath}` : ""}`),
+      url: asPluginUrl(ref.canonical),
+      manifest: parsePluginManifest(manifestMd),
+      commands: {},
+      agents: {},
+      rawFiles: { [manifestPath]: manifestMd },
+      ref: {
+        owner: ref.owner,
+        repo: ref.repo,
+        ref: ref.ref,
+        path: ref.repoPath || void 0
+      },
+      loadedAt: this.now()
+    };
+    for (const filePath of commandFiles) {
+      const res = await this.fetchText(this.rawUrl(ref, filePath), options.signal);
+      if (!res.ok) {
+        throw new ConfigError(`fetch ${filePath}: ${res.statusText}`);
+      }
+      const { tools, body } = parseMarkdownFrontMatter(res.body);
+      const name = asPluginCommandName(basename(filePath));
+      plugin.commands[String(name)] = {
+        name,
+        prompt: body,
+        agentRefs: extractAgentRefs(body),
+        tools
+      };
+      plugin.rawFiles[filePath] = res.body;
+    }
+    for (const filePath of agentFiles) {
+      const res = await this.fetchText(this.rawUrl(ref, filePath), options.signal);
+      if (!res.ok) {
+        throw new ConfigError(`fetch ${filePath}: ${res.statusText}`);
+      }
+      const { description, tools, body } = parseMarkdownFrontMatter(res.body);
+      const name = asPluginAgentName(basename(filePath));
+      plugin.agents[String(name)] = {
+        name,
+        systemPrompt: body,
+        description,
+        tools
+      };
+      plugin.rawFiles[filePath] = res.body;
+    }
+    plugin.manifest.commands = sortedKeys(Object.values(plugin.commands).map((c) => c.name));
+    plugin.manifest.agents = sortedKeys(Object.values(plugin.agents).map((a) => a.name));
+    this.cache.set(key, {
+      expiresAt: this.now().getTime() + this.cacheTtlMs,
+      plugin: clonePlugin(plugin)
+    });
+    return clonePlugin(plugin);
+  }
+  async listMarkdownFiles(ref, repoDir, signal) {
+    const path = `/repos/${ref.owner}/${ref.repo}/contents/${repoDir}`;
+    const url = `${this.apiBaseUrl}${path}?ref=${encodeURIComponent(ref.ref)}`;
+    const res = await this.fetchJson(url, signal);
+    if (res.status === 404) {
+      return [];
+    }
+    if (!res.ok) {
+      throw new ConfigError(`fetch ${repoDir}: ${res.statusText}`);
+    }
+    return res.body.filter((entry) => entry.type === "file" && entry.name.endsWith(".md")).map((entry) => entry.path);
+  }
+  rawUrl(ref, repoPath) {
+    const cleaned = repoPath.replace(/^\/+/, "");
+    return `${this.rawBaseUrl}/${ref.owner}/${ref.repo}/${ref.ref}/${cleaned}`;
+  }
+  async fetchText(url, signal) {
+    const res = await this.fetchFn(url, { signal });
+    const body = await res.text();
+    return { ok: res.ok, status: res.status, statusText: res.statusText, body };
+  }
+  async fetchJson(url, signal) {
+    const res = await this.fetchFn(url, { signal });
+    if (!res.ok) {
+      return {
+        ok: res.ok,
+        status: res.status,
+        statusText: res.statusText,
+        body: []
+      };
+    }
+    const body = await res.json();
+    return { ok: res.ok, status: res.status, statusText: res.statusText, body };
+  }
+};
+var PluginConverter = class {
+  constructor(responses, http, auth, options = {}) {
+    this.responses = responses;
+    this.http = http;
+    this.auth = auth;
+    this.converterModel = asModelId(options.converterModel || "claude-3-5-haiku-latest");
+  }
+  async toWorkflow(plugin, commandName, task) {
+    const command = resolveCommand(plugin, commandName);
+    const prompt = buildPluginConversionPrompt(plugin, command, task);
+    const schemaName = "workflow";
+    const result = await this.responses.object({
+      model: this.converterModel,
+      schema: workflowIntentSchema,
+      schemaName,
+      system: pluginToWorkflowSystemPrompt,
+      prompt
+    });
+    const spec = normalizeWorkflowIntent(result);
+    validateWorkflowTools(spec);
+    return spec;
+  }
+  async toWorkflowDynamic(plugin, commandName, task) {
+    const command = resolveCommand(plugin, commandName);
+    const { candidates, lookup } = buildOrchestrationCandidates(plugin, command);
+    const prompt = buildPluginOrchestrationPrompt(plugin, command, task, candidates);
+    const plan = await this.responses.object({
+      model: this.converterModel,
+      schema: orchestrationPlanSchema,
+      schemaName: "orchestration_plan",
+      system: pluginOrchestrationSystemPrompt,
+      prompt
+    });
+    validateOrchestrationPlan(plan, lookup);
+    const spec = buildDynamicWorkflowFromPlan(plugin, command, task, plan, lookup, this.converterModel);
+    if (specRequiresTools(spec)) {
+      await ensureModelSupportsTools(this.http, this.auth, this.converterModel);
+    }
+    validateWorkflowTools(spec);
+    return spec;
+  }
+};
+var PluginRunner = class {
+  constructor(runs) {
+    this.runs = runs;
+  }
+  async run(spec, config) {
+    const created = await this.runs.create(spec, config.runOptions);
+    return this.wait(created.run_id, config);
+  }
+  async wait(runId, config) {
+    const events = [];
+    const toolRegistry = config.toolRegistry;
+    const eventStream = await this.runs.events(runId, config.runOptions);
+    const runner = toolRegistry ? new ToolRunner({ registry: toolRegistry, runsClient: this.runs }) : null;
+    const stream = runner ? runner.processEvents(runId, eventStream) : eventStream;
+    let terminal = null;
+    for await (const event of stream) {
+      events.push(event);
+      if (event.type === "run_completed") {
+        terminal = "succeeded";
+        break;
+      }
+      if (event.type === "run_failed") {
+        terminal = "failed";
+        break;
+      }
+      if (event.type === "run_canceled") {
+        terminal = "canceled";
+        break;
+      }
+    }
+    const snapshot = await this.runs.get(runId, config.runOptions);
+    return {
+      runId: snapshot.run_id,
+      status: terminal || snapshot.status,
+      outputs: snapshot.outputs,
+      costSummary: snapshot.cost_summary,
+      events
+    };
+  }
+};
+var PluginsClient = class {
+  constructor(deps) {
+    this.responses = deps.responses;
+    this.http = deps.http;
+    this.auth = deps.auth;
+    this.loader = new PluginLoader(deps.options);
+    this.converter = new PluginConverter(deps.responses, deps.http, deps.auth);
+    this.runner = new PluginRunner(deps.runs);
+  }
+  load(url, options) {
+    return this.loader.load(url, options);
+  }
+  async run(plugin, command, config) {
+    const task = config.userTask?.trim();
+    if (!task) {
+      throw new ConfigError("userTask is required");
+    }
+    const mode = normalizeOrchestrationMode(config.orchestrationMode);
+    const converterModel = config.converterModel ? asModelId(String(config.converterModel)) : void 0;
+    const converter = converterModel ? new PluginConverter(this.responses, this.http, this.auth, {
+      converterModel
+    }) : this.converter;
+    let spec;
+    if (mode === OrchestrationModes.Dynamic) {
+      spec = await converter.toWorkflowDynamic(plugin, command, task);
+    } else {
+      spec = await converter.toWorkflow(plugin, command, task);
+    }
+    if (config.model) {
+      spec = { ...spec, model: String(config.model) };
+    }
+    return this.runner.run(spec, config);
+  }
+  async quickRun(pluginUrl, command, userTask, config = {}) {
+    const plugin = await this.load(pluginUrl);
+    return this.run(plugin, command, { ...config, userTask });
+  }
+};
+function normalizeOrchestrationMode(mode) {
+  if (!mode) return OrchestrationModes.DAG;
+  if (mode !== OrchestrationModes.DAG && mode !== OrchestrationModes.Dynamic) {
+    throw new ConfigError(`invalid orchestration mode: ${mode}`);
+  }
+  return mode;
+}
+function resolveCommand(plugin, commandName) {
+  const trimmed = commandName.trim();
+  if (!trimmed) {
+    throw new ConfigError("command is required");
+  }
+  const command = plugin.commands[trimmed];
+  if (!command) {
+    throw new ConfigError("unknown command");
+  }
+  return command;
+}
+var pluginToWorkflowSystemPrompt = `You convert a ModelRelay plugin (markdown files) into a single workflow JSON spec.
+
+Rules:
+- Output MUST be a single JSON object and MUST validate as workflow.
+- Do NOT output markdown, commentary, or code fences.
+- Use a DAG with parallelism when multiple agents are independent.
+- Use join.all to aggregate parallel branches and then a final synthesizer node.
+- Use depends_on for edges between nodes.
+- Bind node outputs using {{placeholders}} when passing data forward.
+- Tool contract:
+  - Target tools.v0 client tools (see docs/reference/tools.md).
+  - Workspace access MUST use these exact function tool names:
+    - ${Object.values(PluginToolNames).join(", ")}
+  - Prefer fs.* tools for reading/listing/searching the workspace (use bash only when necessary).
+  - Do NOT invent ad-hoc tool names (no repo.*, github.*, filesystem.*, etc.).
+  - All client tools MUST be represented as type="function" tools.
+  - Any node that includes tools MUST set tool_execution.mode="client".
+- Prefer minimal nodes needed to satisfy the task.
+`;
+var pluginOrchestrationSystemPrompt = `You plan which plugin agents to run based only on their descriptions.
+
+Rules:
+- Output MUST be a single JSON object that matches orchestration.plan.v1.
+- Do NOT output markdown, commentary, or code fences.
+- Select only from the provided agent IDs.
+- Prefer minimal agents needed to satisfy the user task.
+- Use multiple steps only when later agents must build on earlier results.
+- Each step can run agents in parallel.
+- Use "id" + "depends_on" if you need non-sequential step ordering.
+`;
+function buildPluginConversionPrompt(plugin, command, userTask) {
+  const out = [];
+  out.push(`PLUGIN_URL: ${plugin.url}`);
+  out.push(`COMMAND: ${command.name}`);
+  out.push("USER_TASK:");
+  out.push(userTask.trim());
+  out.push("");
+  out.push(`PLUGIN_MANIFEST:`);
+  out.push(JSON.stringify(plugin.manifest));
+  out.push("");
+  out.push(`COMMAND_MARKDOWN (commands/${command.name}.md):`);
+  out.push(command.prompt);
+  out.push("");
+  const agentNames = Object.keys(plugin.agents).sort();
+  if (agentNames.length) {
+    out.push("AGENTS_MARKDOWN:");
+    for (const name of agentNames) {
+      out.push(`---- agents/${name}.md ----`);
+      out.push(plugin.agents[name].systemPrompt);
+      out.push("");
+    }
+  }
+  return out.join("\n");
+}
+function buildOrchestrationCandidates(plugin, command) {
+  const names = command.agentRefs?.length ? command.agentRefs : Object.values(plugin.agents).map((agent) => agent.name);
+  if (!names.length) {
+    throw new PluginOrchestrationError(
+      PluginOrchestrationErrorCodes.InvalidPlan,
+      "no agents available for dynamic orchestration"
+    );
+  }
+  const lookup = /* @__PURE__ */ new Map();
+  const candidates = [];
+  for (const name of names) {
+    const agent = plugin.agents[String(name)];
+    if (!agent) {
+      throw new PluginOrchestrationError(
+        PluginOrchestrationErrorCodes.UnknownAgent,
+        `agent "${name}" not found`
+      );
+    }
+    const desc = agent.description?.trim();
+    if (!desc) {
+      throw new PluginOrchestrationError(
+        PluginOrchestrationErrorCodes.MissingDescription,
+        `agent "${name}" missing description`
+      );
+    }
+    lookup.set(String(name), agent);
+    candidates.push({ name, description: desc, agent });
+  }
+  return { candidates, lookup };
+}
+function buildPluginOrchestrationPrompt(plugin, command, userTask, candidates) {
+  const out = [];
+  if (plugin.manifest.name) {
+    out.push(`PLUGIN_NAME: ${plugin.manifest.name}`);
+  }
+  if (plugin.manifest.description) {
+    out.push(`PLUGIN_DESCRIPTION: ${plugin.manifest.description}`);
+  }
+  out.push(`COMMAND: ${command.name}`);
+  out.push("USER_TASK:");
+  out.push(userTask.trim());
+  out.push("");
+  if (command.prompt.trim()) {
+    out.push("COMMAND_MARKDOWN:");
+    out.push(command.prompt);
+    out.push("");
+  }
+  out.push("CANDIDATE_AGENTS:");
+  for (const c of candidates) {
+    out.push(`- id: ${c.name}`);
+    out.push(`  description: ${c.description}`);
+  }
+  return out.join("\n");
+}
+function validateOrchestrationPlan(plan, lookup) {
+  if (plan.max_parallelism && plan.max_parallelism < 1) {
+    throw new PluginOrchestrationError(
+      PluginOrchestrationErrorCodes.InvalidPlan,
+      "max_parallelism must be >= 1"
+    );
+  }
+  const stepIds = /* @__PURE__ */ new Map();
+  let hasExplicitDeps = false;
+  plan.steps.forEach((step, idx) => {
+    if (step.depends_on?.length) {
+      hasExplicitDeps = true;
+    }
+    if (step.id) {
+      const key = step.id.trim();
+      if (stepIds.has(key)) {
+        throw new PluginOrchestrationError(
+          PluginOrchestrationErrorCodes.InvalidPlan,
+          `duplicate step id "${key}"`
+        );
+      }
+      stepIds.set(key, idx);
+    }
+  });
+  if (hasExplicitDeps) {
+    plan.steps.forEach((step) => {
+      if (!step.id?.trim()) {
+        throw new PluginOrchestrationError(
+          PluginOrchestrationErrorCodes.InvalidPlan,
+          "step id required when depends_on is used"
+        );
+      }
+    });
+  }
+  const seen = /* @__PURE__ */ new Set();
+  plan.steps.forEach((step, idx) => {
+    if (!step.agents.length) {
+      throw new PluginOrchestrationError(
+        PluginOrchestrationErrorCodes.InvalidPlan,
+        `step ${idx + 1} must include at least one agent`
+      );
+    }
+    if (step.depends_on) {
+      for (const dep of step.depends_on) {
+        const depId = dep.trim();
+        const depIndex = depId ? stepIds.get(depId) : void 0;
+        if (!depId) {
+          throw new PluginOrchestrationError(
+            PluginOrchestrationErrorCodes.InvalidDependency,
+            `step ${idx + 1} has empty depends_on`
+          );
+        }
+        if (depIndex === void 0) {
+          throw new PluginOrchestrationError(
+            PluginOrchestrationErrorCodes.InvalidDependency,
+            `step ${idx + 1} depends on unknown step "${depId}"`
+          );
+        }
+        if (depIndex >= idx) {
+          throw new PluginOrchestrationError(
+            PluginOrchestrationErrorCodes.InvalidDependency,
+            `step ${idx + 1} depends on future step "${depId}"`
+          );
+        }
+      }
+    }
+    for (const agent of step.agents) {
+      const id = agent.id.trim();
+      if (!id) {
+        throw new PluginOrchestrationError(
+          PluginOrchestrationErrorCodes.InvalidPlan,
+          `step ${idx + 1} agent id required`
+        );
+      }
+      if (!lookup.has(id)) {
+        throw new PluginOrchestrationError(
+          PluginOrchestrationErrorCodes.UnknownAgent,
+          `unknown agent "${id}"`
+        );
+      }
+      if (!agent.reason?.trim()) {
+        throw new PluginOrchestrationError(
+          PluginOrchestrationErrorCodes.InvalidPlan,
+          `agent "${id}" must include a reason`
+        );
+      }
+      if (seen.has(id)) {
+        throw new PluginOrchestrationError(
+          PluginOrchestrationErrorCodes.InvalidPlan,
+          `agent "${id}" referenced more than once`
+        );
+      }
+      seen.add(id);
+    }
+  });
+}
+function buildDynamicWorkflowFromPlan(plugin, command, userTask, plan, lookup, model) {
+  const stepKeys = plan.steps.map((step, idx) => step.id?.trim() || `step_${idx + 1}`);
+  const stepOrder = new Map(stepKeys.map((key, idx) => [key, idx]));
+  const stepOutputs = /* @__PURE__ */ new Map();
+  const usedNodeIds = /* @__PURE__ */ new Set();
+  const nodes = [];
+  const hasExplicitDeps = plan.steps.some((step) => (step.depends_on?.length ?? 0) > 0);
+  for (let i = 0; i < plan.steps.length; i += 1) {
+    const step = plan.steps[i];
+    const stepKey = stepKeys[i];
+    const dependencyKeys = hasExplicitDeps ? step.depends_on || [] : i > 0 ? [stepKeys[i - 1]] : [];
+    const deps = dependencyKeys.map((raw) => {
+      const key = raw.trim();
+      const nodeId = stepOutputs.get(key);
+      if (!nodeId) {
+        throw new PluginOrchestrationError(
+          PluginOrchestrationErrorCodes.InvalidDependency,
+          `missing output for dependency "${key}"`
+        );
+      }
+      const depIndex = stepOrder.get(key);
+      if (depIndex === void 0 || depIndex >= i) {
+        throw new PluginOrchestrationError(
+          PluginOrchestrationErrorCodes.InvalidDependency,
+          `invalid dependency "${key}"`
+        );
+      }
+      return { stepId: key, nodeId };
+    });
+    const stepNodeIds = [];
+    for (const selection of step.agents) {
+      const agentName = selection.id.trim();
+      const agent = lookup.get(agentName);
+      if (!agent) {
+        throw new PluginOrchestrationError(
+          PluginOrchestrationErrorCodes.UnknownAgent,
+          `unknown agent "${agentName}"`
+        );
+      }
+      const nodeId = parseNodeId(formatAgentNodeId(agentName));
+      if (usedNodeIds.has(nodeId)) {
+        throw new PluginOrchestrationError(
+          PluginOrchestrationErrorCodes.InvalidPlan,
+          `duplicate node id "${nodeId}"`
+        );
+      }
+      const tools = buildToolRefs(agent, command);
+      const node = {
+        id: nodeId,
+        type: WorkflowNodeTypesIntent.LLM,
+        system: agent.systemPrompt.trim() || void 0,
+        user: buildDynamicAgentUserPrompt(command, userTask, deps),
+        depends_on: deps.length ? deps.map((d) => d.nodeId) : void 0,
+        tools: tools.length ? tools : void 0,
+        tool_execution: tools.length ? { mode: "client" } : void 0
+      };
+      nodes.push(node);
+      stepNodeIds.push(nodeId);
+      usedNodeIds.add(nodeId);
+    }
+    let outputNodeId = stepNodeIds[0];
+    if (stepNodeIds.length > 1) {
+      const joinId = parseNodeId(formatStepJoinNodeId(stepKey));
+      if (usedNodeIds.has(joinId)) {
+        throw new PluginOrchestrationError(
+          PluginOrchestrationErrorCodes.InvalidPlan,
+          `duplicate node id "${joinId}"`
+        );
+      }
+      nodes.push({
+        id: joinId,
+        type: WorkflowNodeTypesIntent.JoinAll,
+        depends_on: stepNodeIds
+      });
+      usedNodeIds.add(joinId);
+      outputNodeId = joinId;
+    }
+    stepOutputs.set(stepKey, outputNodeId);
+  }
+  const terminalOutputs = findTerminalOutputs(stepKeys, plan, stepOutputs, hasExplicitDeps);
+  const synthId = parseNodeId("orchestrator_synthesize");
+  const synthNode = {
+    id: synthId,
+    type: WorkflowNodeTypesIntent.LLM,
+    user: buildDynamicSynthesisPrompt(command, userTask, terminalOutputs),
+    depends_on: terminalOutputs
+  };
+  const spec = {
+    kind: WorkflowKinds.WorkflowIntent,
+    name: plugin.manifest.name?.trim() || command.name,
+    model: String(model),
+    max_parallelism: plan.max_parallelism,
+    nodes: [...nodes, synthNode],
+    outputs: [{ name: parseOutputName("result"), from: synthId }]
+  };
+  return spec;
+}
+function buildDynamicAgentUserPrompt(command, task, deps) {
+  const parts = [];
+  if (command.prompt.trim()) {
+    parts.push(command.prompt.trim());
+  }
+  parts.push("USER_TASK:");
+  parts.push(task.trim());
+  if (deps.length) {
+    parts.push("", "PREVIOUS_STEP_OUTPUTS:");
+    for (const dep of deps) {
+      parts.push(`- ${dep.stepId}: {{${dep.nodeId}}}`);
+    }
   }
-};
-
-// src/tiers.ts
-function defaultTierModelId(tier) {
-  const def = tier.models.find((m) => m.is_default);
-  if (def) return def.model_id;
-  if (tier.models.length === 1) return tier.models[0].model_id;
-  return void 0;
+  return parts.join("\n");
 }
-var TiersClient = class {
-  constructor(http, cfg) {
-    this.http = http;
-    this.apiKey = cfg.apiKey ? parseApiKey(cfg.apiKey) : void 0;
-    this.hasSecretKey = this.apiKey ? isSecretKey(this.apiKey) : false;
-    this.hasAccessToken = !!cfg.accessToken?.trim();
+function buildDynamicSynthesisPrompt(command, task, outputs) {
+  const parts = ["Synthesize the results and complete the task."];
+  if (command.prompt.trim()) {
+    parts.push("", "COMMAND:");
+    parts.push(command.prompt.trim());
   }
-  ensureAuth() {
-    if (!this.apiKey && !this.hasAccessToken) {
-      throw new ConfigError(
-        "API key (mr_sk_*) or bearer token required for tier operations"
-      );
+  parts.push("", "USER_TASK:");
+  parts.push(task.trim());
+  if (outputs.length) {
+    parts.push("", "RESULTS:");
+    for (const id of outputs) {
+      parts.push(`- {{${id}}}`);
     }
   }
-  ensureSecretKey() {
-    if (!this.apiKey || !this.hasSecretKey) {
-      throw new ConfigError(
-        "Secret key (mr_sk_*) required for checkout operations"
+  return parts.join("\n");
+}
+function buildToolRefs(agent, command) {
+  const names = agent.tools?.length ? agent.tools : command.tools?.length ? command.tools : defaultDynamicToolNames;
+  const unique = /* @__PURE__ */ new Set();
+  for (const name of names) {
+    if (!allowedToolSet.has(name)) {
+      throw new PluginOrchestrationError(
+        PluginOrchestrationErrorCodes.UnknownTool,
+        `unknown tool "${name}"`
       );
     }
+    unique.add(name);
   }
-  /**
-   * List all tiers in the project.
-   */
-  async list() {
-    this.ensureAuth();
-    const response = await this.http.json("/tiers", {
-      method: "GET",
-      apiKey: this.apiKey
-    });
-    return response.tiers;
+  return Array.from(unique.values());
+}
+function findTerminalOutputs(stepKeys, plan, outputs, explicit) {
+  if (!explicit) {
+    const lastKey = stepKeys[stepKeys.length - 1];
+    const out = outputs.get(lastKey);
+    return out ? [out] : [];
+  }
+  const depended = /* @__PURE__ */ new Set();
+  plan.steps.forEach((step) => {
+    (step.depends_on || []).forEach((dep) => depended.add(dep.trim()));
+  });
+  return stepKeys.filter((key) => !depended.has(key)).map((key) => outputs.get(key)).filter((value) => Boolean(value));
+}
+function formatAgentNodeId(name) {
+  const token = sanitizeNodeToken(name);
+  if (!token) {
+    throw new PluginOrchestrationError(
+      PluginOrchestrationErrorCodes.InvalidPlan,
+      "agent id must contain alphanumeric characters"
+    );
   }
-  /**
-   * Get a tier by ID.
-   */
-  async get(tierId) {
-    this.ensureAuth();
-    if (!tierId?.trim()) {
-      throw new ConfigError("tierId is required");
+  return `agent_${token}`;
+}
+function formatStepJoinNodeId(stepKey) {
+  const token = sanitizeNodeToken(stepKey);
+  if (!token) {
+    throw new PluginOrchestrationError(
+      PluginOrchestrationErrorCodes.InvalidPlan,
+      "step id must contain alphanumeric characters"
+    );
+  }
+  return token.startsWith("step_") ? `${token}_join` : `step_${token}_join`;
+}
+function sanitizeNodeToken(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) return "";
+  let out = "";
+  for (const ch of trimmed) {
+    if (/[a-zA-Z0-9]/.test(ch)) {
+      out += ch.toLowerCase();
+    } else {
+      out += "_";
     }
-    const response = await this.http.json(`/tiers/${tierId}`, {
+  }
+  out = out.replace(/_+/g, "_");
+  return out.replace(/^_+|_+$/g, "");
+}
+async function ensureModelSupportsTools(http, auth, model) {
+  const authHeaders = await auth.authForResponses();
+  const query = encodeURIComponent("tools");
+  const response = await http.json(
+    `/models?capability=${query}`,
+    {
       method: "GET",
-      apiKey: this.apiKey
-    });
-    return response.tier;
+      apiKey: authHeaders.apiKey,
+      accessToken: authHeaders.accessToken
+    }
+  );
+  const modelId = String(model).trim();
+  const found = response.models?.some((entry) => entry.model_id?.trim() === modelId);
+  if (!found) {
+    throw new PluginOrchestrationError(
+      PluginOrchestrationErrorCodes.InvalidToolConfig,
+      `model "${modelId}" does not support tool calling`
+    );
   }
-  /**
-   * Create a Stripe checkout session for a tier (Stripe-first flow).
-   *
-   * This enables users to subscribe before authenticating. Stripe collects
-   * the customer's email during checkout. After checkout completes, a
-   * customer record is created with the email from Stripe. Your backend
-   * can map it to your app user and mint customer tokens as needed.
-   *
-   * Requires a secret key (mr_sk_*).
-   *
-   * @param tierId - The tier ID to create a checkout session for
-   * @param request - Checkout session request with redirect URLs
-   * @returns Checkout session with Stripe URL
-   */
-  async checkout(tierId, request) {
-    this.ensureSecretKey();
-    if (!tierId?.trim()) {
-      throw new ConfigError("tierId is required");
+}
+function normalizeWorkflowIntent(spec) {
+  const validation = validateWithZod(workflowIntentSchema, spec);
+  if (!validation.success) {
+    throw new ConfigError("workflow intent validation failed");
+  }
+  validateWorkflowTools(spec);
+  return spec;
+}
+function validateWorkflowTools(spec) {
+  for (const node of spec.nodes) {
+    if (node.type !== WorkflowNodeTypesIntent.LLM || !node.tools?.length) {
+      continue;
+    }
+    const tools = node.tools || [];
+    let mode = node.tool_execution?.mode;
+    for (const tool of tools) {
+      if (typeof tool !== "string") {
+        throw new ConfigError(`plugin conversion only supports tools.v0 function tools`);
+      }
+      if (!allowedToolSet.has(tool)) {
+        throw new ConfigError(`unsupported tool "${tool}" (plugin conversion targets tools.v0)`);
+      }
+      mode = "client";
     }
-    if (!request.success_url?.trim()) {
-      throw new ConfigError("success_url is required");
+    if (mode && mode !== "client") {
+      throw new ConfigError(`tool_execution.mode must be "client" for plugin conversion`);
     }
-    if (!request.cancel_url?.trim()) {
-      throw new ConfigError("cancel_url is required");
+    node.tool_execution = { mode: "client" };
+  }
+}
+function parsePluginManifest(markdown) {
+  const trimmed = markdown.trim();
+  if (!trimmed) return {};
+  const frontMatter = parseManifestFrontMatter(trimmed);
+  if (frontMatter) return frontMatter;
+  const lines = splitLines(trimmed);
+  let name = "";
+  for (const line of lines) {
+    if (line.startsWith("# ")) {
+      name = line.slice(2).trim();
+      break;
     }
-    return await this.http.json(
-      `/tiers/${tierId}/checkout`,
-      {
-        method: "POST",
-        apiKey: this.apiKey,
-        body: request
+  }
+  let description = "";
+  if (name) {
+    let after = false;
+    for (const line of lines) {
+      const trimmedLine = line.trim();
+      if (trimmedLine.startsWith("# ")) {
+        after = true;
+        continue;
+      }
+      if (!after) continue;
+      if (!trimmedLine) continue;
+      if (trimmedLine.startsWith("## ")) break;
+      description = trimmedLine;
+      break;
+    }
+  }
+  return { name, description };
+}
+function parseManifestFrontMatter(markdown) {
+  const lines = splitLines(markdown);
+  if (!lines.length || lines[0].trim() !== "---") return null;
+  const end = lines.findIndex((line, idx) => idx > 0 && line.trim() === "---");
+  if (end === -1) return null;
+  const manifest = {};
+  let currentList = null;
+  for (const line of lines.slice(1, end)) {
+    const raw = line.trim();
+    if (!raw || raw.startsWith("#")) continue;
+    if (raw.startsWith("- ") && currentList) {
+      const item = raw.slice(2).trim();
+      if (item) {
+        if (currentList === "commands") {
+          manifest.commands = [...manifest.commands || [], asPluginCommandName(item)];
+        } else {
+          manifest.agents = [...manifest.agents || [], asPluginAgentName(item)];
+        }
+      }
+      continue;
+    }
+    currentList = null;
+    const [keyRaw, ...rest] = raw.split(":");
+    if (!keyRaw || rest.length === 0) continue;
+    const key = keyRaw.trim().toLowerCase();
+    const val = rest.join(":").trim().replace(/^['"]|['"]$/g, "");
+    if (key === "name") manifest.name = val;
+    if (key === "description") manifest.description = val;
+    if (key === "version") manifest.version = val;
+    if (key === "commands") currentList = "commands";
+    if (key === "agents") currentList = "agents";
+  }
+  manifest.commands = manifest.commands?.sort();
+  manifest.agents = manifest.agents?.sort();
+  return manifest;
+}
+function parseMarkdownFrontMatter(markdown) {
+  const trimmed = markdown.trim();
+  if (!trimmed.startsWith("---")) {
+    return { body: markdown };
+  }
+  const lines = splitLines(trimmed);
+  const endIdx = lines.findIndex((line, idx) => idx > 0 && line.trim() === "---");
+  if (endIdx === -1) {
+    return { body: markdown };
+  }
+  let description;
+  let tools;
+  let currentList = null;
+  const toolItems = [];
+  for (const line of lines.slice(1, endIdx)) {
+    const raw = line.trim();
+    if (!raw || raw.startsWith("#")) continue;
+    if (raw.startsWith("- ") && currentList === "tools") {
+      const item = raw.slice(2).trim();
+      if (item) toolItems.push(item);
+      continue;
+    }
+    currentList = null;
+    const [keyRaw, ...rest] = raw.split(":");
+    if (!keyRaw || rest.length === 0) continue;
+    const key = keyRaw.trim().toLowerCase();
+    const val = rest.join(":").trim().replace(/^['"]|['"]$/g, "");
+    if (key === "description") description = val;
+    if (key === "tools") {
+      if (!val) {
+        currentList = "tools";
+        continue;
       }
+      toolItems.push(...splitFrontMatterList(val));
+    }
+  }
+  if (toolItems.length) {
+    tools = toolItems.map((item) => parseToolName(item));
+  }
+  const body = lines.slice(endIdx + 1).join("\n").replace(/^[\n\r]+/, "");
+  return { description, tools, body };
+}
+function parseToolName(raw) {
+  const val = raw.trim();
+  if (!allowedToolSet.has(val)) {
+    throw new PluginOrchestrationError(
+      PluginOrchestrationErrorCodes.UnknownTool,
+      `unknown tool "${raw}"`
     );
   }
-};
+  return val;
+}
+function splitFrontMatterList(raw) {
+  const cleaned = raw.trim().replace(/^\[/, "").replace(/\]$/, "");
+  if (!cleaned) return [];
+  return cleaned.split(",").map((part) => part.trim().replace(/^['"]|['"]$/g, "")).filter(Boolean);
+}
+function extractAgentRefs(markdown) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  const lines = splitLines(markdown);
+  for (const line of lines) {
+    const lower = line.toLowerCase();
+    const idx = lower.indexOf("agents/");
+    if (idx === -1) continue;
+    if (!lower.includes(".md", idx)) continue;
+    let seg = line.slice(idx).trim();
+    seg = seg.replace(/^agents\//, "");
+    seg = seg.split(".md")[0];
+    seg = seg.replace(/[`* _]/g, "").trim();
+    if (!seg || seen.has(seg)) continue;
+    seen.add(seg);
+    out.push(asPluginAgentName(seg));
+  }
+  return out.sort();
+}
+function splitLines(input) {
+  return input.replace(/\r\n/g, "\n").split("\n");
+}
+function basename(path) {
+  const parts = path.split("/");
+  const last = parts[parts.length - 1] || "";
+  return last.replace(/\.md$/i, "");
+}
+function joinRepoPath(base, elem) {
+  const clean = (value) => value.replace(/^\/+|\/+$/g, "");
+  const b = clean(base || "");
+  const e = clean(elem || "");
+  if (!b) return e;
+  if (!e) return b;
+  return `${b}/${e}`;
+}
+function sortedKeys(items) {
+  return items.slice().sort();
+}
+function clonePlugin(plugin) {
+  return {
+    ...plugin,
+    manifest: { ...plugin.manifest },
+    commands: { ...plugin.commands },
+    agents: { ...plugin.agents },
+    rawFiles: { ...plugin.rawFiles },
+    loadedAt: new Date(plugin.loadedAt)
+  };
+}
+function asPluginId(value) {
+  const trimmed = value.trim();
+  if (!trimmed) throw new ConfigError("plugin id required");
+  return trimmed;
+}
+function asPluginUrl(value) {
+  const trimmed = value.trim();
+  if (!trimmed) throw new ConfigError("plugin url required");
+  return trimmed;
+}
+function asPluginCommandName(value) {
+  const trimmed = value.trim();
+  if (!trimmed) throw new ConfigError("plugin command name required");
+  return trimmed;
+}
+function asPluginAgentName(value) {
+  const trimmed = value.trim();
+  if (!trimmed) throw new ConfigError("plugin agent name required");
+  return trimmed;
+}
+function parseGitHubPluginRef(raw) {
+  let url = raw.trim();
+  if (!url) {
+    throw new ConfigError("source url required");
+  }
+  if (url.startsWith("git@github.com:")) {
+    url = `https://github.com/${url.replace("git@github.com:", "")}`;
+  }
+  if (!url.includes("://")) {
+    url = `https://${url}`;
+  }
+  const parsed = new URL(url);
+  const host = parsed.hostname.replace(/^www\./, "").toLowerCase();
+  if (host !== "github.com" && host !== "raw.githubusercontent.com") {
+    throw new ConfigError(`unsupported host: ${parsed.hostname}`);
+  }
+  let ref = parsed.searchParams.get("ref")?.trim() || "";
+  const parts = parsed.pathname.split("/").filter(Boolean);
+  if (parts.length < 2) {
+    throw new ConfigError("invalid github url: expected /owner/repo");
+  }
+  const owner = parts[0];
+  let repoPart = parts[1].replace(/\.git$/i, "");
+  const atIdx = repoPart.indexOf("@");
+  if (atIdx > 0 && atIdx < repoPart.length - 1) {
+    if (!ref) {
+      ref = repoPart.slice(atIdx + 1);
+    }
+    repoPart = repoPart.slice(0, atIdx);
+  }
+  const repo = repoPart;
+  let rest = parts.slice(2);
+  if (host === "github.com" && rest.length >= 2 && (rest[0] === "tree" || rest[0] === "blob")) {
+    if (!ref) {
+      ref = rest[1];
+    }
+    rest = rest.slice(2);
+  }
+  if (host === "raw.githubusercontent.com") {
+    if (!rest.length) {
+      throw new ConfigError("invalid raw github url");
+    }
+    if (!ref) {
+      ref = rest[0];
+    }
+    rest = rest.slice(1);
+  }
+  let repoPath = rest.join("/");
+  repoPath = repoPath.replace(/^\/+|\/+$/g, "");
+  if (/plugin\.md$/i.test(repoPath) || /skill\.md$/i.test(repoPath)) {
+    repoPath = repoPath.split("/").slice(0, -1).join("/");
+  }
+  if (/\.md$/i.test(repoPath)) {
+    const commandsIdx = repoPath.indexOf("/commands/");
+    if (commandsIdx >= 0) {
+      repoPath = repoPath.slice(0, commandsIdx);
+    }
+    const agentsIdx = repoPath.indexOf("/agents/");
+    if (agentsIdx >= 0) {
+      repoPath = repoPath.slice(0, agentsIdx);
+    }
+    repoPath = repoPath.replace(/^\/+|\/+$/g, "");
+  }
+  if (!ref) {
+    ref = DEFAULT_PLUGIN_REF;
+  }
+  const canonical = repoPath ? `github.com/${owner}/${repo}@${ref}/${repoPath}` : `github.com/${owner}/${repo}@${ref}`;
+  return { owner, repo, ref, repoPath, canonical };
+}
+function specRequiresTools(spec) {
+  for (const node of spec.nodes) {
+    if (node.type === WorkflowNodeTypesIntent.LLM && node.tools?.length) {
+      return true;
+    }
+    if (node.type === WorkflowNodeTypesIntent.MapFanout && node.subnode) {
+      const sub = node.subnode;
+      if (sub.tools?.length) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
 
 // src/http.ts
 var HTTPClient = class {
@@ -4357,21 +6300,176 @@ var CustomerResponsesClient = class {
       mergeCustomerOptions(this.customerId, options)
     );
   }
-  async streamTextDeltas(system, user, options = {}) {
-    return this.base.streamTextDeltasForCustomer(
-      this.customerId,
-      system,
-      user,
-      mergeCustomerOptions(this.customerId, options)
-    );
+  async streamTextDeltas(system, user, options = {}) {
+    return this.base.streamTextDeltasForCustomer(
+      this.customerId,
+      system,
+      user,
+      mergeCustomerOptions(this.customerId, options)
+    );
+  }
+};
+var CustomerScopedModelRelay = class {
+  constructor(responses, customerId, baseUrl) {
+    const normalized = normalizeCustomerId(customerId);
+    this.responses = new CustomerResponsesClient(responses, normalized);
+    this.customerId = normalized;
+    this.baseUrl = baseUrl;
+  }
+};
+
+// src/tool_builder.ts
+function formatZodError(error) {
+  if (error && typeof error === "object" && "issues" in error && Array.isArray(error.issues)) {
+    const issues = error.issues;
+    return issues.map((issue) => {
+      const path = Array.isArray(issue.path) ? issue.path.join(".") : "";
+      const msg = issue.message || "invalid";
+      return path ? `${path}: ${msg}` : msg;
+    }).join("; ");
+  }
+  return String(error);
+}
+var ToolBuilder = class {
+  constructor() {
+    this.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(name, description, schema, handler) {
+    const tool = createFunctionToolFromSchema(name, description, schema);
+    this.entries.push({
+      name,
+      description,
+      schema,
+      handler,
+      tool
+    });
+    return 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() {
+    return this.entries.map((e) => e.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() {
+    const reg = new ToolRegistry();
+    for (const entry of this.entries) {
+      const validatingHandler = async (args, call) => {
+        const result = entry.schema.safeParse(args);
+        if (!result.success) {
+          throw new ToolArgsError(
+            `Invalid arguments for tool '${entry.name}': ${formatZodError(result.error)}`,
+            call.id,
+            entry.name,
+            call.function?.arguments ?? ""
+          );
+        }
+        return entry.handler(result.data, call);
+      };
+      reg.register(entry.name, validatingHandler);
+    }
+    return reg;
+  }
+  /**
+   * 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() {
+    return {
+      definitions: this.definitions(),
+      registry: this.registry()
+    };
+  }
+  /**
+   * Get the number of tools defined.
+   */
+  get size() {
+    return this.entries.length;
   }
-};
-var CustomerScopedModelRelay = class {
-  constructor(responses, customerId, baseUrl) {
-    const normalized = normalizeCustomerId(customerId);
-    this.responses = new CustomerResponsesClient(responses, normalized);
-    this.customerId = normalized;
-    this.baseUrl = baseUrl;
+  /**
+   * Check if a tool is defined.
+   */
+  has(name) {
+    return this.entries.some((e) => e.name === name);
   }
 };
 
@@ -4550,6 +6648,12 @@ var WorkflowIntentBuilder = class _WorkflowIntentBuilder {
   model(model) {
     return this.with({ model: model.trim() });
   }
+  maxParallelism(n) {
+    return this.with({ maxParallelism: n });
+  }
+  inputs(decls) {
+    return this.with({ inputs: decls });
+  }
   node(node) {
     return this.with({ nodes: [...this.state.nodes, node] });
   }
@@ -4559,15 +6663,15 @@ var WorkflowIntentBuilder = class _WorkflowIntentBuilder {
     return this.node(configured.build());
   }
   joinAll(id) {
-    return this.node({ id, type: WorkflowNodeTypesLite.JoinAll });
+    return this.node({ id, type: WorkflowNodeTypesIntent.JoinAll });
   }
   joinAny(id, predicate) {
-    return this.node({ id, type: WorkflowNodeTypesLite.JoinAny, predicate });
+    return this.node({ id, type: WorkflowNodeTypesIntent.JoinAny, predicate });
   }
   joinCollect(id, options) {
     return this.node({
       id,
-      type: WorkflowNodeTypesLite.JoinCollect,
+      type: WorkflowNodeTypesIntent.JoinCollect,
       limit: options.limit,
       timeout_ms: options.timeoutMs,
       predicate: options.predicate
@@ -4576,7 +6680,7 @@ var WorkflowIntentBuilder = class _WorkflowIntentBuilder {
   transformJSON(id, object, merge) {
     return this.node({
       id,
-      type: WorkflowNodeTypesLite.TransformJSON,
+      type: WorkflowNodeTypesIntent.TransformJSON,
       object,
       merge
     });
@@ -4584,7 +6688,7 @@ var WorkflowIntentBuilder = class _WorkflowIntentBuilder {
   mapFanout(id, options) {
     return this.node({
       id,
-      type: WorkflowNodeTypesLite.MapFanout,
+      type: WorkflowNodeTypesIntent.MapFanout,
       items_from: options.itemsFrom,
       items_from_input: options.itemsFromInput,
       items_path: options.itemsPath,
@@ -4605,7 +6709,14 @@ var WorkflowIntentBuilder = class _WorkflowIntentBuilder {
       ...node,
       depends_on: node.depends_on ? [...node.depends_on] : void 0
     }));
-    const byId = new Map(nodes.map((node, idx) => [node.id, idx]));
+    const byId = /* @__PURE__ */ new Map();
+    for (let idx = 0; idx < nodes.length; idx++) {
+      const id = nodes[idx].id;
+      if (byId.has(id)) {
+        throw new Error(`duplicate node id "${id}"`);
+      }
+      byId.set(id, idx);
+    }
     for (const edge of this.state.edges) {
       const idx = byId.get(edge.to);
       if (idx === void 0) {
@@ -4621,6 +6732,8 @@ var WorkflowIntentBuilder = class _WorkflowIntentBuilder {
       kind: WorkflowKinds.WorkflowIntent,
       name: this.state.name,
       model: this.state.model,
+      max_parallelism: this.state.maxParallelism,
+      inputs: this.state.inputs,
       nodes,
       outputs: [...this.state.outputs]
     };
@@ -4628,7 +6741,7 @@ var WorkflowIntentBuilder = class _WorkflowIntentBuilder {
 };
 var LLMNodeBuilder = class {
   constructor(id) {
-    this.node = { id, type: WorkflowNodeTypesLite.LLM };
+    this.node = { id, type: WorkflowNodeTypesIntent.LLM };
   }
   system(text) {
     this.node.system = text;
@@ -4665,6 +6778,45 @@ var LLMNodeBuilder = class {
 function workflowIntent() {
   return new WorkflowIntentBuilder();
 }
+function llm(id, configure) {
+  const builder = new LLMNodeBuilder(parseNodeId(id));
+  const configured = configure ? configure(builder) : builder;
+  return configured.build();
+}
+function chain(steps, options) {
+  let builder = new WorkflowIntentBuilder();
+  if (options?.name) {
+    builder = builder.name(options.name);
+  }
+  if (options?.model) {
+    builder = builder.model(options.model);
+  }
+  for (const step of steps) {
+    builder = builder.node(step);
+  }
+  for (let i = 1; i < steps.length; i++) {
+    builder = builder.edge(steps[i - 1].id, steps[i].id);
+  }
+  return builder;
+}
+function parallel(steps, options) {
+  let builder = new WorkflowIntentBuilder();
+  const joinId = parseNodeId(options?.joinId ?? "join");
+  if (options?.name) {
+    builder = builder.name(options.name);
+  }
+  if (options?.model) {
+    builder = builder.model(options.model);
+  }
+  for (const step of steps) {
+    builder = builder.node(step);
+  }
+  builder = builder.joinAll(joinId);
+  for (const step of steps) {
+    builder = builder.edge(step.id, joinId);
+  }
+  return builder;
+}
 
 // src/testing.ts
 function buildNDJSONResponse(lines, headers = {}, status = 200) {
@@ -4732,154 +6884,6 @@ function createMockFetchQueue(responses) {
   return { fetch: fetchImpl, calls };
 }
 
-// src/tools_runner.ts
-var ToolRunner = class {
-  constructor(options) {
-    this.registry = options.registry;
-    this.runsClient = options.runsClient;
-    this.customerId = options.customerId;
-    this.onBeforeExecute = options.onBeforeExecute;
-    this.onAfterExecute = options.onAfterExecute;
-    this.onSubmitted = options.onSubmitted;
-    this.onError = options.onError;
-  }
-  /**
-   * Handles a node_waiting event by executing tools and submitting results.
-   *
-   * @param runId - The run ID
-   * @param nodeId - The node ID that is waiting
-   * @param waiting - The waiting state with pending tool calls
-   * @returns The submission response with accepted count and new status
-   *
-   * @example
-   * ```typescript
-   * for await (const event of client.runs.events(runId)) {
-   *   if (event.type === "node_waiting") {
-   *     const result = await runner.handleNodeWaiting(
-   *       runId,
-   *       event.node_id,
-   *       event.waiting
-   *     );
-   *     console.log(`Submitted ${result.accepted} results, status: ${result.status}`);
-   *   }
-   * }
-   * ```
-   */
-  async handleNodeWaiting(runId, nodeId, waiting) {
-    const results = [];
-    for (const pending of waiting.pending_tool_calls) {
-      try {
-        await this.onBeforeExecute?.(pending);
-        const toolCall = createToolCall(
-          pending.tool_call.id,
-          pending.tool_call.name,
-          pending.tool_call.arguments
-        );
-        const result = await this.registry.execute(toolCall);
-        results.push(result);
-        await this.onAfterExecute?.(result);
-      } catch (err) {
-        const error = err instanceof Error ? err : new Error(String(err));
-        await this.onError?.(error, pending);
-        results.push({
-          toolCallId: pending.tool_call.id,
-          toolName: pending.tool_call.name,
-          result: null,
-          error: error.message
-        });
-      }
-    }
-    const response = await this.runsClient.submitToolResults(
-      runId,
-      {
-        node_id: nodeId,
-        step: waiting.step,
-        request_id: waiting.request_id,
-        results: results.map((r) => ({
-          tool_call: {
-            id: r.toolCallId,
-            name: r.toolName
-          },
-          output: r.error ? `Error: ${r.error}` : typeof r.result === "string" ? r.result : JSON.stringify(r.result)
-        }))
-      },
-      { customerId: this.customerId }
-    );
-    await this.onSubmitted?.(runId, response.accepted, response.status);
-    return {
-      accepted: response.accepted,
-      status: response.status,
-      results
-    };
-  }
-  /**
-   * Processes a stream of run events, automatically handling node_waiting events.
-   *
-   * This is the main entry point for running a workflow with client-side tools.
-   * It yields all events through (including node_waiting after handling).
-   *
-   * @param runId - The run ID to process
-   * @param events - AsyncIterable of run events (from RunsClient.events())
-   * @yields All run events, with node_waiting events handled automatically
-   *
-   * @example
-   * ```typescript
-   * const run = await client.runs.create(workflowSpec);
-   * const eventStream = client.runs.events(run.run_id);
-   *
-   * for await (const event of runner.processEvents(run.run_id, eventStream)) {
-   *   switch (event.type) {
-   *     case "node_started":
-   *       console.log(`Node ${event.node_id} started`);
-   *       break;
-   *     case "node_succeeded":
-   *       console.log(`Node ${event.node_id} succeeded`);
-   *       break;
-   *     case "run_succeeded":
-   *       console.log("Run completed!");
-   *       break;
-   *   }
-   * }
-   * ```
-   */
-  async *processEvents(runId, events) {
-    for await (const event of events) {
-      if (event.type === "node_waiting") {
-        const waitingEvent = event;
-        try {
-          await this.handleNodeWaiting(
-            runId,
-            waitingEvent.node_id,
-            waitingEvent.waiting
-          );
-        } catch (err) {
-          const error = err instanceof Error ? err : new Error(String(err));
-          await this.onError?.(error);
-          throw error;
-        }
-      }
-      yield event;
-    }
-  }
-  /**
-   * Checks if a run event is a node_waiting event.
-   * Utility for filtering events when not using processEvents().
-   */
-  static isNodeWaiting(event) {
-    return event.type === "node_waiting";
-  }
-  /**
-   * Checks if a run status is terminal (succeeded, failed, or canceled).
-   * Utility for determining when to stop polling.
-   */
-  static isTerminalStatus(status) {
-    return status === "succeeded" || status === "failed" || status === "canceled";
-  }
-};
-function createToolRunner(options) {
-  return new ToolRunner(options);
-}
-
 // src/generated/index.ts
 var generated_exports = {};
 
@@ -4890,7 +6894,7 @@ __export(workflow_exports, {
   LLMNodeBuilder: () => LLMNodeBuilder,
   LLM_TEXT_OUTPUT: () => LLM_TEXT_OUTPUT,
   LLM_USER_MESSAGE_TEXT: () => LLM_USER_MESSAGE_TEXT,
-  NodeTypesLite: () => NodeTypesLite,
+  NodeTypesIntent: () => NodeTypesIntent,
   WorkflowIntentBuilder: () => WorkflowIntentBuilder,
   parseNodeId: () => parseNodeId,
   parseOutputName: () => parseOutputName,
@@ -4899,17 +6903,17 @@ __export(workflow_exports, {
   workflowIntent: () => workflowIntent
 });
 var KindIntent = WorkflowKinds.WorkflowIntent;
-var NodeTypesLite = {
-  LLM: WorkflowNodeTypesLite.LLM,
-  JoinAll: WorkflowNodeTypesLite.JoinAll,
-  JoinAny: WorkflowNodeTypesLite.JoinAny,
-  JoinCollect: WorkflowNodeTypesLite.JoinCollect,
-  TransformJSON: WorkflowNodeTypesLite.TransformJSON,
-  MapFanout: WorkflowNodeTypesLite.MapFanout
+var NodeTypesIntent = {
+  LLM: WorkflowNodeTypesIntent.LLM,
+  JoinAll: WorkflowNodeTypesIntent.JoinAll,
+  JoinAny: WorkflowNodeTypesIntent.JoinAny,
+  JoinCollect: WorkflowNodeTypesIntent.JoinCollect,
+  TransformJSON: WorkflowNodeTypesIntent.TransformJSON,
+  MapFanout: WorkflowNodeTypesIntent.MapFanout
 };
 
 // src/index.ts
-var ModelRelay = class _ModelRelay {
+var _ModelRelay = class _ModelRelay {
   static fromSecretKey(secretKey, options = {}) {
     return new _ModelRelay({ ...options, key: parseSecretKey(secretKey) });
   }
@@ -4958,22 +6962,187 @@ var ModelRelay = class _ModelRelay {
     });
     this.images = new ImagesClient(this.http, auth);
     this.sessions = new SessionsClient(this, this.http, auth);
+    this.stateHandles = new StateHandlesClient(this.http, auth);
     this.tiers = new TiersClient(this.http, { apiKey, accessToken });
+    this.plugins = new PluginsClient({
+      responses: this.responses,
+      http: this.http,
+      auth,
+      runs: this.runs
+    });
   }
   forCustomer(customerId) {
     return new CustomerScopedModelRelay(this.responses, customerId, this.baseUrl);
   }
+  /**
+   * 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",
+   * });
+   * ```
+   */
+  async chat(model, prompt, options = {}) {
+    const { system, customerId, ...reqOptions } = options;
+    let builder = this.responses.new().model(asModelId(model));
+    if (system) {
+      builder = builder.system(system);
+    }
+    builder = builder.user(prompt);
+    if (customerId) {
+      builder = builder.customerId(customerId);
+    }
+    return this.responses.create(builder.build(), reqOptions);
+  }
+  /**
+   * 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",
+   * });
+   * ```
+   */
+  async ask(model, prompt, options = {}) {
+    const response = await this.chat(model, prompt, options);
+    return extractAssistantText(response.output);
+  }
+  /**
+   * 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
+   * });
+   * ```
+   */
+  async agent(model, options) {
+    const { definitions, registry } = options.tools.build();
+    const maxTurns = options.maxTurns ?? _ModelRelay.DEFAULT_MAX_TURNS;
+    const modelId = asModelId(model);
+    const input = [];
+    if (options.system) {
+      input.push(createSystemMessage(options.system));
+    }
+    input.push(createUserMessage(options.prompt));
+    const outcome = await runToolLoop({
+      client: this.responses,
+      input,
+      tools: definitions,
+      registry,
+      maxTurns,
+      buildRequest: (builder) => builder.model(modelId)
+    });
+    if (outcome.status !== "complete") {
+      throw new ConfigError("agent tool loop requires a tool registry");
+    }
+    return {
+      output: outcome.output,
+      usage: outcome.usage,
+      response: outcome.response
+    };
+  }
+  /**
+   * 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() {
+    return new ToolBuilder();
+  }
 };
+// =========================================================================
+// Convenience Methods (Simple Case Simple)
+// =========================================================================
+/** Default maximum turns for agent loops. */
+_ModelRelay.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.
+ */
+_ModelRelay.NO_TURN_LIMIT = Number.MAX_SAFE_INTEGER;
+var ModelRelay = _ModelRelay;
 function resolveBaseUrl(override) {
   const base = override || DEFAULT_BASE_URL;
   return base.replace(/\/+$/, "");
 }
 export {
   APIError,
+  AgentMaxTurnsError,
   AuthClient,
   BillingProviders,
   ConfigError,
   ContentPartTypes,
+  ContextManager,
   CustomerResponsesClient,
   CustomerScopedModelRelay,
   CustomerTokenProvider,
@@ -4982,6 +7151,7 @@ export {
   DEFAULT_CONNECT_TIMEOUT_MS,
   DEFAULT_REQUEST_TIMEOUT_MS,
   ErrorCodes,
+  FileConversationStore,
   ImagesClient,
   InputItemTypes,
   JoinOutput,
@@ -5002,19 +7172,29 @@ export {
   LLM_TEXT_OUTPUT,
   LLM_USER_MESSAGE_TEXT,
   LocalSession,
-  MemorySessionStore,
+  MAX_STATE_HANDLE_TTL_SECONDS,
+  MemoryConversationStore,
   MessageRoles,
   ModelRelay,
   ModelRelayError,
+  OrchestrationModes,
   OutputFormatTypes,
   OutputItemTypes,
   PathEscapeError,
+  PluginConverter,
+  PluginLoader,
+  PluginOrchestrationError,
+  PluginOrchestrationErrorCodes,
+  PluginRunner,
+  PluginToolNames,
+  PluginsClient,
   ResponsesClient,
   ResponsesStream,
   RunsClient,
   RunsEventStream,
   SDK_VERSION,
   SessionsClient,
+  SqliteConversationStore,
   StopReasons,
   StreamProtocolError,
   StreamTimeoutError,
@@ -5025,18 +7205,19 @@ export {
   TiersClient,
   ToolArgsError,
   ToolArgumentError,
+  ToolBuilder,
   ToolCallAccumulator,
   ToolChoiceTypes,
   ToolRegistry,
   ToolRunner,
   ToolTypes,
   TransportError,
+  USER_ASK_TOOL_NAME,
   WORKFLOWS_COMPILE_PATH,
-  WebToolIntents,
   WorkflowIntentBuilder,
   WorkflowKinds,
-  WorkflowNodeTypesLite as WorkflowNodeTypes,
-  WorkflowNodeTypesLite,
+  WorkflowNodeTypesIntent as WorkflowNodeTypes,
+  WorkflowNodeTypesIntent,
   WorkflowValidationError,
   WorkflowsClient,
   asModelId,
@@ -5046,22 +7227,26 @@ export {
   assistantMessageWithToolCalls,
   buildDelayedNDJSONResponse,
   buildNDJSONResponse,
+  chain,
   createAccessTokenAuth,
   createApiKeyAuth,
   createAssistantMessage,
+  createFileConversationStore,
   createFunctionCall,
   createFunctionTool,
-  createFunctionToolFromSchema,
   createLocalSession,
-  createMemorySessionStore,
+  createMemoryConversationStore,
   createMockFetchQueue,
+  createModelContextResolver,
   createRetryMessages,
+  createSqliteConversationStore,
   createSystemMessage,
   createToolCall,
   createToolRunner,
+  createTypedTool,
   createUsage,
+  createUserAskTool,
   createUserMessage,
-  createWebTool,
   defaultRetryHandler,
   defaultTierModelId,
   executeWithRetry,
@@ -5069,16 +7254,26 @@ export {
   formatToolErrorForModel,
   generateSessionId,
   generated_exports as generated,
+  getAllToolCalls,
+  getAssistantText,
   getRetryableErrors,
+  getToolArgs,
+  getToolArgsRaw,
+  getToolName,
+  getTypedToolCall,
+  getTypedToolCalls,
   hasRetryableErrors,
   hasToolCalls,
   isSecretKey,
+  isUserAskToolCall,
+  llm,
   mergeMetrics,
   mergeTrace,
   modelToString,
   normalizeModelId,
   normalizeStopReason,
   outputFormatFromZod,
+  parallel,
   parseApiKey,
   parseErrorResponse,
   parseNodeId,
@@ -5086,15 +7281,20 @@ export {
   parsePlanHash,
   parseRunId,
   parseSecretKey,
-  parseToolArgs,
-  parseToolArgsRaw,
+  parseTypedToolCall,
+  parseUserAskArgs,
+  prepareInputWithContext,
   respondToToolCall,
+  runToolLoop,
+  serializeUserAskResult,
   stopReasonToString,
   toolChoiceAuto,
   toolChoiceNone,
   toolChoiceRequired,
   toolResultMessage,
-  tryParseToolArgs,
+  truncateInputByTokens,
+  userAskResultChoice,
+  userAskResultFreeform,
   validateWithZod,
   workflow_exports as workflow,
   workflowIntent,