@flue/sdk 0.3.5 → 0.3.7

package/README.md

@@ -4,11 +4,13 @@
 
 # Flue
 
-Flue is **The Sandbox Agent Framework.** If you know how to use Claude Code (or OpenCode, Codex, Gemini, etc)... then you already know the basics of how to build agents with Flue.
+Flue is **The Agent Harness Framework.** If you know how to use Claude Code (or OpenCode, Codex, Gemini, etc)... then you already know the basics of how to build agents with Flue.
 
-A [Sandbox Agent](https://developers.openai.com/api/docs/guides/agents/sandboxes) pairs an **agent harness** (like Claude Code) with a secure, isolated container workspace. Sandbox Agents can edit files, write and execute code, spin up subagents, run terminal commands, and drive themselves autonomously to solve any given task. This pattern unlocks more powerful, intelligent agents that traditional AI frameworks wouldn't otherwise let you build.
+Flue is a TypeScript framework for building the next generation of agents, designed around a built-in **agent harness**. It's like Claude Code, but 100% headless and programmable. There's no baked-in assumption like requiring a human operator to function. No TUI. No GUI. Just TypeScript.
 
-Our take is that 1) any agent can be represented as a Sandbox Agent, and 2) any agent is _best_ represented as a Sandbox Agent. So we designed Flue to deliver on this vision.
+But using Flue feels like using Claude Code. The agents you build act autonomously to solve problems and complete tasks. They require very little code to run — most of the "logic" lives in Markdown: skills, context, and `AGENTS.md`.
+
+Flue isn't another AI SDK. It's a proper runtime-agnostic framework — think Astro or Next.js, but for agents. Write once, build, and deploy your agents anywhere (Node.js, Cloudflare, GitHub Actions, GitLab CI/CD, etc).
 
 ## Packages
 
@@ -287,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/{agent-BB4lwAd5.mjs → agent-BTB0809P.mjs}

@@ -287,7 +287,7 @@ function createBashTool(env) {
 		}),
 		async execute(_toolCallId, params, signal) {
 			throwIfAborted(signal);
-			return formatBashResult(await env.exec(params.command), params.command);
+			return formatBashResult(await env.exec(params.command, { timeout: params.timeout }), params.command);
 		}
 	};
 }

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-T8pE1xIS.mjs";
-import { i as connectMcpServer, n as McpServerOptions, r as McpTransport, t as McpServerConnection } from "./mcp-BVF-sOBZ.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-BB4lwAd5.mjs";
-import { a as assertRoleExists } from "./session-DukL3zwF.mjs";
+import { r as discoverSessionContext } from "./agent-BTB0809P.mjs";
+import { a as assertRoleExists } from "./session-CNOAfV45.mjs";
 import { bashFactoryToSessionEnv, createCwdSessionEnv } from "./sandbox.mjs";
-import { n as AgentClient, t as connectMcpServer } from "./mcp-DOgMtp8y.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-T8pE1xIS.mjs";
-import { t as CommandExecutor } from "../command-helpers-DdAfbnom.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-BB4lwAd5.mjs";
-import "../session-DukL3zwF.mjs";
+import "../agent-BTB0809P.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";
@@ -195,9 +195,11 @@ async function cfSandboxToSessionEnv(sandbox, cwd = "/workspace") {
 			} else await sandbox.deleteFile(path);
 		},
 		async exec(command, execOpts) {
+			const timeoutMs = typeof execOpts?.timeout === "number" ? execOpts.timeout * 1e3 : void 0;
 			const result = await sandbox.exec(command, {
 				cwd: execOpts?.cwd,
-				env: execOpts?.env
+				env: execOpts?.env,
+				timeout: timeoutMs
 			});
 			return {
 				stdout: result.stdout ?? "",

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

@@ -1,4 +1,4 @@
-import { D as ShellResult } from "./types-T8pE1xIS.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-T8pE1xIS.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 };