@flue/sdk 0.3.6 → 0.3.7

package/README.md

@@ -289,6 +289,34 @@ await session.prompt('Review the latest changes.'); // uses reviewer
 await session.task('Research related issues.', { role: 'researcher' }); // uses researcher
 ```
 
+### Provider Settings
+
+Use `providers` when model traffic needs provider-specific runtime settings,
+such as an enterprise API gateway, provider-compatible proxy, custom endpoint,
+or gateway-specific credentials. This is common for managed credentials, audit
+logging, traffic routing, or self-hosted OpenAI-compatible providers.
+
+Configure these settings in `init()` instead of mutating global model state. They
+are runtime-scoped to that agent and apply to every model it resolves, including
+agent defaults, role-level models, per-call model selections, tasks, and context
+compaction.
+
+```ts
+const agent = await init({
+  model: 'anthropic/claude-sonnet-4-6',
+  providers: {
+    anthropic: {
+      baseUrl: env.ANTHROPIC_BASE_URL,
+      headers: {
+        'X-Custom-Auth': env.GATEWAY_KEY,
+      },
+      // Use this when the proxy expects a synthetic or gateway-specific key.
+      apiKey: 'dummy',
+    },
+  },
+});
+```
+
 ### Custom Virtual Sandboxes
 
 For most agents, use the built-in virtual sandbox or `sandbox: 'local'`. If you need to customize just-bash directly, pass a Bash factory. The factory must return a fresh Bash-like runtime each time; share the filesystem object in the closure to persist files across sessions and prompts.

package/dist/client.d.mts

@@ -1,5 +1,5 @@
-import { A as TaskOptions, C as SessionEnv, D as ShellResult, E as ShellOptions, M as ToolParameters, S as SessionData, T as SessionStore, _ as FlueSessions, a as BashLike, d as FileStat, f as FlueAgent, g as FlueSession, h as FlueEventCallback, i as BashFactory, j as ToolDef, k as SkillOptions, l as Command, m as FlueEvent, p as FlueContext, r as AgentInit, t as AgentConfig, v as PromptOptions, w as SessionOptions, x as SandboxFactory, y as PromptResponse } from "./types-CItTrBsU.mjs";
-import { i as connectMcpServer, n as McpServerOptions, r as McpTransport, t as McpServerConnection } from "./mcp-EZy-Vb5M.mjs";
+import { A as ShellResult, D as SessionOptions, E as SessionEnv, F as ToolParameters, M as SkillOptions, N as TaskOptions, O as SessionStore, P as ToolDef, S as ProvidersConfig, T as SessionData, _ as FlueSessions, a as BashLike, b as PromptResponse, d as FileStat, f as FlueAgent, g as FlueSession, h as FlueEventCallback, i as BashFactory, k as ShellOptions, l as Command, m as FlueEvent, p as FlueContext, r as AgentInit, t as AgentConfig, v as ModelConfig, w as SandboxFactory, x as ProviderSettings, y as PromptOptions } from "./types-CKcp6T-y.mjs";
+import { i as connectMcpServer, n as McpServerOptions, r as McpTransport, t as McpServerConnection } from "./mcp-CKMPhMDe.mjs";
 import { Type } from "@mariozechner/pi-ai";
 
 //#region src/client.d.ts
@@ -23,4 +23,4 @@ interface FlueContextInternal extends FlueContext {
 }
 declare function createFlueContext(config: FlueContextConfig): FlueContextInternal;
 //#endregion
-export { type AgentInit, type BashFactory, type BashLike, type Command, type FileStat, type FlueAgent, type FlueContext, FlueContextConfig, FlueContextInternal, type FlueEvent, type FlueEventCallback, type FlueSession, type FlueSessions, type McpServerConnection, type McpServerOptions, type McpTransport, type PromptOptions, type PromptResponse, type SandboxFactory, type SessionData, type SessionEnv, type SessionOptions, type SessionStore, type ShellOptions, type ShellResult, type SkillOptions, type TaskOptions, type ToolDef, type ToolParameters, Type, connectMcpServer, createFlueContext };
+export { type AgentInit, type BashFactory, type BashLike, type Command, type FileStat, type FlueAgent, type FlueContext, FlueContextConfig, FlueContextInternal, type FlueEvent, type FlueEventCallback, type FlueSession, type FlueSessions, type McpServerConnection, type McpServerOptions, type McpTransport, type ModelConfig, type PromptOptions, type PromptResponse, type ProviderSettings, type ProvidersConfig, type SandboxFactory, type SessionData, type SessionEnv, type SessionOptions, type SessionStore, type ShellOptions, type ShellResult, type SkillOptions, type TaskOptions, type ToolDef, type ToolParameters, Type, connectMcpServer, createFlueContext };

package/dist/client.mjs

@@ -1,7 +1,7 @@
 import { r as discoverSessionContext } from "./agent-BTB0809P.mjs";
-import { a as assertRoleExists } from "./session-BaaSQTWS.mjs";
+import { a as assertRoleExists } from "./session-CNOAfV45.mjs";
 import { bashFactoryToSessionEnv, createCwdSessionEnv } from "./sandbox.mjs";
-import { n as AgentClient, t as connectMcpServer } from "./mcp-DTFRe9vh.mjs";
+import { n as AgentClient, t as connectMcpServer } from "./mcp-B13ZPduG.mjs";
 import { Type } from "@mariozechner/pi-ai";
 
 //#region src/client.ts
@@ -19,24 +19,28 @@ function createFlueContext(config) {
 			return config.env;
 		},
 		async init(options) {
-			const id = options?.id ?? config.id;
+			if (!options || !("model" in options)) throw new Error("[flue] init() requires a model. Pass { model: \"provider/model-id\" } or { model: false }.");
+			if (options.model !== false && typeof options.model !== "string") throw new Error("[flue] init({ model }) must be a model string or false.");
+			const id = options.id ?? config.id;
 			if (initializedAgentIds.has(id)) throw new Error(`[flue] init() has already been called for agent "${id}" in this request.`);
 			initializedAgentIds.add(id);
 			try {
-				assertRoleExists(config.agentConfig.roles, options?.role);
-				const sandbox = options?.sandbox;
-				const baseEnv = await resolveSessionEnv(id, sandbox, config, options?.cwd);
-				const env = options?.cwd ? createCwdSessionEnv(baseEnv, options.cwd) : baseEnv;
-				const store = options?.persist ?? config.defaultStore;
+				assertRoleExists(config.agentConfig.roles, options.role);
+				const sandbox = options.sandbox;
+				const baseEnv = await resolveSessionEnv(id, sandbox, config, options.cwd);
+				const env = options.cwd ? createCwdSessionEnv(baseEnv, options.cwd) : baseEnv;
+				const store = options.persist ?? config.defaultStore;
 				const localContext = await discoverSessionContext(env);
-				const agentModel = options?.model && config.agentConfig.resolveModel ? config.agentConfig.resolveModel(options.model) : config.agentConfig.model;
+				const providers = mergeProvidersConfig(config.agentConfig.providers, options.providers);
+				const agentModel = config.agentConfig.resolveModel(options.model, providers);
 				return new AgentClient(id, {
 					...config.agentConfig,
 					systemPrompt: localContext.systemPrompt,
 					skills: localContext.skills,
 					model: agentModel,
-					role: options?.role ?? config.agentConfig.role
-				}, env, store, currentEventCallback, options?.commands, options?.tools);
+					role: options.role ?? config.agentConfig.role,
+					providers
+				}, env, store, currentEventCallback, options.commands, options.tools);
 			} catch (error) {
 				initializedAgentIds.delete(id);
 				throw error;
@@ -73,6 +77,23 @@ async function resolveSessionEnv(id, sandbox, config, cwd) {
 	});
 	throw new Error("[flue] Invalid sandbox option passed to init().");
 }
+function mergeProvidersConfig(base, settings) {
+	if (!base) return settings;
+	if (!settings) return base;
+	const merged = { ...base };
+	for (const [provider, config] of Object.entries(settings)) {
+		const previous = merged[provider];
+		merged[provider] = {
+			...previous,
+			...config,
+			headers: previous?.headers || config.headers ? {
+				...previous?.headers ?? {},
+				...config.headers ?? {}
+			} : void 0
+		};
+	}
+	return merged;
+}
 
 //#endregion
 export { Type, connectMcpServer, createFlueContext };

package/dist/cloudflare/index.d.mts

@@ -1,5 +1,5 @@
-import { C as SessionEnv, T as SessionStore, l as Command } from "../types-CItTrBsU.mjs";
-import { t as CommandExecutor } from "../command-helpers-CXzopT_-.mjs";
+import { E as SessionEnv, O as SessionStore, l as Command } from "../types-CKcp6T-y.mjs";
+import { t as CommandExecutor } from "../command-helpers-5DpOaRIB.mjs";
 
 //#region src/cloudflare/virtual-sandbox.d.ts
 interface VirtualSandboxOptions {

package/dist/cloudflare/index.mjs

@@ -1,5 +1,5 @@
 import "../agent-BTB0809P.mjs";
-import "../session-BaaSQTWS.mjs";
+import "../session-CNOAfV45.mjs";
 import { createSandboxSessionEnv } from "../sandbox.mjs";
 import { t as normalizeExecutor } from "../command-helpers-hTZKWK13.mjs";
 import { Workspace, WorkspaceFileSystem } from "@cloudflare/shell";

package/dist/{command-helpers-CXzopT_-.d.mts → command-helpers-5DpOaRIB.d.mts}

@@ -1,4 +1,4 @@
-import { D as ShellResult } from "./types-CItTrBsU.mjs";
+import { A as ShellResult } from "./types-CKcp6T-y.mjs";
 
 //#region src/command-helpers.d.ts
 /**

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as TaskOptions, C as SessionEnv, D as ShellResult, E as ShellOptions, M as ToolParameters, O as Skill, S as SessionData, T as SessionStore, _ as FlueSessions, a as BashLike, b as Role, c as BuildPlugin, d as FileStat, f as FlueAgent, g as FlueSession, h as FlueEventCallback, i as BashFactory, j as ToolDef, k as SkillOptions, l as Command, m as FlueEvent, n as AgentInfo, o as BuildContext, p as FlueContext, r as AgentInit, s as BuildOptions, t as AgentConfig, u as CommandDef, v as PromptOptions, w as SessionOptions, x as SandboxFactory, y as PromptResponse } from "./types-CItTrBsU.mjs";
+import { A as ShellResult, C as Role, D as SessionOptions, E as SessionEnv, F as ToolParameters, M as SkillOptions, N as TaskOptions, O as SessionStore, P as ToolDef, T as SessionData, _ as FlueSessions, a as BashLike, b as PromptResponse, c as BuildPlugin, d as FileStat, f as FlueAgent, g as FlueSession, h as FlueEventCallback, i as BashFactory, j as Skill, k as ShellOptions, l as Command, m as FlueEvent, n as AgentInfo, o as BuildContext, p as FlueContext, r as AgentInit, s as BuildOptions, t as AgentConfig, u as CommandDef, v as ModelConfig, w as SandboxFactory, y as PromptOptions } from "./types-CKcp6T-y.mjs";
 import { AgentTool, AgentToolResult } from "@mariozechner/pi-agent-core";
 
 //#region src/build.d.ts
@@ -113,4 +113,4 @@ interface CreateToolsOptions {
 }
 declare function createTools(env: SessionEnv, options?: CreateToolsOptions): AgentTool<any>[];
 //#endregion
-export { type AgentConfig, type AgentInfo, type AgentInit, BUILTIN_TOOL_NAMES, type BashFactory, type BashLike, type BuildContext, type BuildOptions, type BuildPlugin, type Command, type CommandDef, DEFAULT_DEV_PORT, type DevOptions, type FileStat, type FlueAgent, type FlueContext, type FlueEvent, type FlueEventCallback, type FlueSession, type FlueSessions, type PromptOptions, type PromptResponse, type Role, type SandboxFactory, type SessionData, type SessionEnv, type SessionOptions, type SessionStore, type ShellOptions, type ShellResult, type Skill, type SkillOptions, type TaskOptions, type ToolDef, type ToolParameters, build, createTools, dev, parseEnvFiles, resolveEnvFiles, resolveWorkspaceFromCwd };
+export { type AgentConfig, type AgentInfo, type AgentInit, BUILTIN_TOOL_NAMES, type BashFactory, type BashLike, type BuildContext, type BuildOptions, type BuildPlugin, type Command, type CommandDef, DEFAULT_DEV_PORT, type DevOptions, type FileStat, type FlueAgent, type FlueContext, type FlueEvent, type FlueEventCallback, type FlueSession, type FlueSessions, type ModelConfig, type PromptOptions, type PromptResponse, type Role, type SandboxFactory, type SessionData, type SessionEnv, type SessionOptions, type SessionStore, type ShellOptions, type ShellResult, type Skill, type SkillOptions, type TaskOptions, type ToolDef, type ToolParameters, build, createTools, dev, parseEnvFiles, resolveEnvFiles, resolveWorkspaceFromCwd };

package/dist/index.mjs

@@ -439,13 +439,6 @@ const manifest = ${manifest};
 // dispatcher (which would otherwise return text/plain "Invalid request").
 const webhookAgentNames = new Set(${JSON.stringify(webhookAgents.map((a) => a.name))});
 
-// ─── Infrastructure ─────────────────────────────────────────────────────────
-
-// No build-time model default. The user sets model at runtime via
-// \`init({ model: "provider/model-id" })\` for an agent default, or via
-// \`{ model: "provider/model-id" }\` on any individual prompt/skill/task call.
-const model = undefined;
-
 // ─── Sandbox Environments ───────────────────────────────────────────────────
 
 /**
@@ -549,7 +542,7 @@ function createContextForRequest(id, payload, doInstance) {
     payload,
     env: doInstance?.env ?? {},
     agentConfig: {
-      systemPrompt, skills, roles, model, resolveModel,
+      systemPrompt, skills, roles, model: undefined, resolveModel,
     },
     createDefaultEnv,
     createLocalEnv,
@@ -909,13 +902,6 @@ const manifest = ${JSON.stringify({ agents: agents.map((a) => ({
 			triggers: a.triggers
 		})) }, null, 2)};
 
-// ─── Infrastructure ─────────────────────────────────────────────────────────
-
-// No build-time model default. The user sets model at runtime via
-// \`init({ model: "provider/model-id" })\` for an agent default, or via
-// \`{ model: "provider/model-id" }\` on any individual prompt/skill/task call.
-const model = undefined;
-
 // ─── Sandbox Environments ───────────────────────────────────────────────────
 
 /**
@@ -955,7 +941,7 @@ function createContextForRequest(id, payload) {
     payload,
     env: process.env,
     agentConfig: {
-      systemPrompt, skills, roles, model, resolveModel,
+      systemPrompt, skills, roles, model: undefined, resolveModel,
     },
     createDefaultEnv,
     createLocalEnv,

package/dist/internal.d.mts

@@ -1,5 +1,5 @@
-import { S as SessionData, T as SessionStore } from "./types-CItTrBsU.mjs";
-import "./mcp-EZy-Vb5M.mjs";
+import { O as SessionStore, S as ProvidersConfig, T as SessionData, v as ModelConfig } from "./types-CKcp6T-y.mjs";
+import "./mcp-CKMPhMDe.mjs";
 import { FlueContextConfig, FlueContextInternal, createFlueContext } from "./client.mjs";
 import { bashFactoryToSessionEnv } from "./sandbox.mjs";
 import { getModel } from "@mariozechner/pi-ai";
@@ -285,6 +285,6 @@ declare function validateAgentRequest(opts: ValidateAgentRequestOptions): void;
  * transitive deps. Centralizing the resolver here keeps `_entry.ts`
  * dependency-free apart from `@flue/sdk/*`.
  */
-declare function resolveModel(modelString: string): ReturnType<typeof getModel>;
+declare function resolveModel(model: ModelConfig | undefined, providers?: ProvidersConfig): ReturnType<typeof getModel> | undefined;
 //#endregion
 export { AgentNotFoundError, type FlueContextConfig, type FlueContextInternal, InMemorySessionStore, InvalidRequestError, MethodNotAllowedError, RouteNotFoundError, bashFactoryToSessionEnv, createFlueContext, parseJsonBody, resolveModel, toHttpResponse, toSseData, validateAgentRequest };

package/dist/internal.mjs

@@ -1,7 +1,7 @@
 import "./agent-BTB0809P.mjs";
-import { t as InMemorySessionStore } from "./session-BaaSQTWS.mjs";
+import { t as InMemorySessionStore } from "./session-CNOAfV45.mjs";
 import { bashFactoryToSessionEnv } from "./sandbox.mjs";
-import "./mcp-DTFRe9vh.mjs";
+import "./mcp-B13ZPduG.mjs";
 import { createFlueContext } from "./client.mjs";
 import { getModel } from "@mariozechner/pi-ai";
 
@@ -441,14 +441,30 @@ function validateAgentRequest(opts) {
 * transitive deps. Centralizing the resolver here keeps `_entry.ts`
 * dependency-free apart from `@flue/sdk/*`.
 */
-function resolveModel(modelString) {
+function resolveModel(model, providers) {
+	if (model === false || model === void 0) return void 0;
+	const modelString = model;
 	const slash = modelString.indexOf("/");
 	if (slash === -1) throw new Error(`[flue] Invalid model "${modelString}". Use the "provider/model-id" format (e.g. "anthropic/claude-haiku-4-5").`);
 	const provider = modelString.slice(0, slash);
 	const modelId = modelString.slice(slash + 1);
 	const resolved = getModel(provider, modelId);
 	if (!resolved) throw new Error(`[flue] Unknown model "${modelString}". Provider "${provider}" / model id "${modelId}" is not registered with @mariozechner/pi-ai.`);
-	return resolved;
+	return applyProviderSettings(resolved, providers?.[provider]);
+}
+function applyProviderSettings(model, providerSettings) {
+	if (!providerSettings) return model;
+	const hasBaseUrl = providerSettings.baseUrl !== void 0;
+	const hasHeaders = providerSettings.headers !== void 0;
+	if (!hasBaseUrl && !hasHeaders) return model;
+	return {
+		...model,
+		baseUrl: providerSettings.baseUrl ?? model.baseUrl,
+		headers: hasHeaders ? {
+			...model.headers ?? {},
+			...providerSettings.headers
+		} : model.headers
+	};
 }
 
 //#endregion

package/dist/{mcp-DTFRe9vh.mjs → mcp-B13ZPduG.mjs}

@@ -1,5 +1,5 @@
 import { r as discoverSessionContext } from "./agent-BTB0809P.mjs";
-import { a as assertRoleExists, n as Session, o as createScopedEnv, r as deleteSessionTree, s as mergeCommands } from "./session-BaaSQTWS.mjs";
+import { a as assertRoleExists, n as Session, o as createScopedEnv, r as deleteSessionTree, s as mergeCommands } from "./session-CNOAfV45.mjs";
 import { createCwdSessionEnv } from "./sandbox.mjs";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

package/dist/{mcp-EZy-Vb5M.d.mts → mcp-CKMPhMDe.d.mts}

@@ -1,4 +1,4 @@
-import { j as ToolDef } from "./types-CItTrBsU.mjs";
+import { P as ToolDef } from "./types-CKcp6T-y.mjs";
 
 //#region src/mcp.d.ts
 type McpTransport = 'streamable-http' | 'sse';

package/dist/node/index.d.mts

@@ -1,5 +1,5 @@
-import { l as Command } from "../types-CItTrBsU.mjs";
-import { t as CommandExecutor } from "../command-helpers-CXzopT_-.mjs";
+import { l as Command } from "../types-CKcp6T-y.mjs";
+import { t as CommandExecutor } from "../command-helpers-5DpOaRIB.mjs";
 import { execFile } from "node:child_process";
 
 //#region src/node/define-command.d.ts

package/dist/sandbox.d.mts

@@ -1,4 +1,4 @@
-import { C as SessionEnv, D as ShellResult, d as FileStat, i as BashFactory, u as CommandDef, x as SandboxFactory } from "./types-CItTrBsU.mjs";
+import { A as ShellResult, E as SessionEnv, d as FileStat, i as BashFactory, u as CommandDef, w as SandboxFactory } from "./types-CKcp6T-y.mjs";
 
 //#region src/sandbox.d.ts
 declare function createCwdSessionEnv(parentEnv: SessionEnv, cwd: string): SessionEnv;

package/dist/sandbox.mjs

@@ -1,5 +1,5 @@
 import "./agent-BTB0809P.mjs";
-import { i as normalizePath, o as createScopedEnv } from "./session-BaaSQTWS.mjs";
+import { i as normalizePath, o as createScopedEnv } from "./session-CNOAfV45.mjs";
 
 //#region src/sandbox.ts
 function createCwdSessionEnv(parentEnv, cwd) {

package/dist/{session-BaaSQTWS.mjs → session-CNOAfV45.mjs}

@@ -740,6 +740,7 @@ var Session = class {
 				tools,
 				messages: previousMessages
 			},
+			getApiKey: (provider) => this.getProviderApiKey(provider),
 			toolExecution: "parallel"
 		});
 		this.eventCallback = options.onAgentEvent;
@@ -891,8 +892,8 @@ var Session = class {
 	resolveModelForCall(promptModel, roleName, callSite) {
 		let model = this.config.model;
 		const roleModel = resolveRoleModel(this.config.roles, roleName);
-		if (roleModel && this.config.resolveModel) model = this.config.resolveModel(roleModel);
-		if (promptModel && this.config.resolveModel) model = this.config.resolveModel(promptModel);
+		if (roleModel) model = this.config.resolveModel(roleModel, this.config.providers);
+		if (promptModel) model = this.config.resolveModel(promptModel, this.config.providers);
 		return this.requireModel(model, callSite);
 	}
 	/**
@@ -902,7 +903,10 @@ var Session = class {
 	*/
 	requireModel(model, callSite) {
 		if (model) return model;
-		throw new Error(`[flue] No model configured for ${callSite}. Pass \`{ model: "provider/model-id" }\` to \`init()\` for an agent-wide default, or to this prompt()/skill() call for a one-off override.`);
+		throw new Error(`[flue] No model configured for ${callSite}. Pass \`{ model: "provider/model-id" }\` to this call or configure a role model.`);
+	}
+	getProviderApiKey(provider) {
+		return this.config.providers?.[provider]?.apiKey;
 	}
 	buildSystemPrompt(roleName) {
 		const parts = [this.config.systemPrompt];
@@ -1193,7 +1197,7 @@ var Session = class {
 				reason,
 				estimatedTokens
 			});
-			const result = await compact(preparation, model, void 0, this.compactionAbortController.signal);
+			const result = await compact(preparation, model, this.getProviderApiKey(model.provider), this.compactionAbortController.signal);
 			if (this.compactionAbortController.signal.aborted) return;
 			this.history.appendCompaction({
 				summary: result.summary,

package/dist/{types-CItTrBsU.d.mts → types-CKcp6T-y.d.mts}

@@ -102,6 +102,25 @@ interface CompactionConfig {
   /** Recent tokens to preserve (not summarized). Default: 20000 */
   keepRecentTokens?: number;
 }
+interface ProviderSettings {
+  /**
+   * Provider endpoint used by built-in models. Useful for API gateways,
+   * LiteLLM-style proxies, or enterprise-managed provider endpoints.
+   */
+  baseUrl?: string;
+  /**
+   * Headers merged into the resolved model's provider-level headers. Values
+   * here override headers already defined by the built-in model.
+   */
+  headers?: Record<string, string>;
+  /**
+   * API key returned to the underlying agent runtime for this provider.
+   * Useful when the gateway requires a dummy key or when credentials should
+   * come from the agent's runtime env instead of process-global env vars.
+   */
+  apiKey?: string;
+}
+type ProvidersConfig = Record<string, ProviderSettings>;
 interface AgentConfig {
   /** Discovered at runtime from AGENTS.md + .agents/skills/ in the session's cwd. */
   systemPrompt: string;
@@ -109,17 +128,20 @@ interface AgentConfig {
   skills: Record<string, Skill>;
   roles: Record<string, Role>;
   /**
-   * Agent-wide default model. Undefined by default — the user must set it via
-   * `init({ model: "provider/model-id" })` or pass `{ model }` at each prompt/
-   * skill/task call site. Calls with no model resolved throw clearly at runtime.
+   * Agent-wide default model. Undefined when the user explicitly passes
+   * `init({ model: false })`, so each model-using call must resolve one from a
+   * role or call-site override.
    */
   model: Model<any> | undefined;
   /** Agent-wide default role. Per-session and per-call roles override this. */
   role?: string;
-  /** Resolve a "provider/modelId" string to a Model instance. Throws on invalid input. */
-  resolveModel?: (modelString: string) => Model<any>;
+  /** Provider runtime settings applied when resolving models. */
+  providers?: ProvidersConfig;
+  /** Resolve model config to a Model instance. Throws on invalid model strings. */
+  resolveModel: (model: ModelConfig | undefined, providers?: ProvidersConfig) => Model<any> | undefined;
   compaction?: CompactionConfig;
 }
+type ModelConfig = string | false;
 /**
  * Request context passed to agent handler functions. Pass type parameters
  * to type `payload` and `env` (e.g. the `Env` interface generated by
@@ -131,9 +153,9 @@ interface FlueContext<TPayload = any, TEnv = Record<string, any>> {
   /** Platform env bindings (process.env on Node, Worker env on Cloudflare). */
   readonly env: TEnv;
   /** Initialize an agent runtime with sandbox + persistence. */
-  init(options?: AgentInit): Promise<FlueAgent>;
+  init(options: AgentInit): Promise<FlueAgent>;
 }
-/** All fields are optional — omitting gives platform defaults (empty sandbox, platform store, build-time model). */
+/** Agent runtime options. A default model is required unless explicitly disabled with `model: false`. */
 interface AgentInit {
   /** Agent/sandbox scope id. Defaults to the route/context id. */
   id?: string;
@@ -149,16 +171,37 @@ interface AgentInit {
   /** Defaults to platform store (in-memory on Node, DO SQLite on Cloudflare). */
   persist?: SessionStore;
   /**
-   * Override the default model for this agent. Applies to all prompt() and skill()
-   * calls unless overridden at the call site.
+   * Default model for this agent. Applies to all prompt(), skill(), and task()
+   * calls unless overridden by a role or at the call site. Pass `false` to require every
+   * model-using call to resolve a model from a role or call-site override.
    *
    * Format: `'provider/modelId'` (e.g. `'anthropic/claude-opus-4-20250514'`).
    *
-   * Precedence (highest wins): per-call `model` > role `model` > agent `model` > build-time default.
+   * Precedence (highest wins): per-call `model` > role `model` > agent `model`.
    */
-  model?: string;
+  model: ModelConfig;
   /** Agent-wide default role. Overridden by session-level or per-call roles. */
   role?: string;
+  /**
+   * Provider runtime settings for every model used by this agent, including
+   * role-level and per-call model selections.
+   *
+   * Example:
+   *
+   * ```ts
+   * await init({
+   *   model: 'anthropic/claude-sonnet-4-6',
+   *   providers: {
+   *     anthropic: {
+   *       baseUrl: env.ANTHROPIC_BASE_URL,
+   *       headers: { 'X-Custom-Auth': env.GATEWAY_KEY },
+   *       apiKey: 'dummy',
+   *     },
+   *   },
+   * });
+   * ```
+   */
+  providers?: ProvidersConfig;
   /**
    * Agent-wide tools. Every prompt(), skill(), and task() call can use these.
    * Per-call tools are added on top and must not reuse the same names.
@@ -463,4 +506,4 @@ interface BuildOptions {
   plugin?: BuildPlugin;
 }
 //#endregion
-export { TaskOptions as A, SessionEnv as C, ShellResult as D, ShellOptions as E, ToolParameters as M, Skill as O, SessionData as S, SessionStore as T, FlueSessions as _, BashLike as a, Role as b, BuildPlugin as c, FileStat as d, FlueAgent as f, FlueSession as g, FlueEventCallback as h, BashFactory as i, ToolDef as j, SkillOptions as k, Command as l, FlueEvent as m, AgentInfo as n, BuildContext as o, FlueContext as p, AgentInit as r, BuildOptions as s, AgentConfig as t, CommandDef as u, PromptOptions as v, SessionOptions as w, SandboxFactory as x, PromptResponse as y };
+export { ShellResult as A, Role as C, SessionOptions as D, SessionEnv as E, ToolParameters as F, SkillOptions as M, TaskOptions as N, SessionStore as O, ToolDef as P, ProvidersConfig as S, SessionData as T, FlueSessions as _, BashLike as a, PromptResponse as b, BuildPlugin as c, FileStat as d, FlueAgent as f, FlueSession as g, FlueEventCallback as h, BashFactory as i, Skill as j, ShellOptions as k, Command as l, FlueEvent as m, AgentInfo as n, BuildContext as o, FlueContext as p, AgentInit as r, BuildOptions as s, AgentConfig as t, CommandDef as u, ModelConfig as v, SandboxFactory as w, ProviderSettings as x, PromptOptions as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flue/sdk",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "type": "module",
   "license": "Apache-2.0",
   "exports": {