@flue/sdk 0.1.0 → 0.1.1

package/README.md

@@ -1,8 +1,14 @@
-# flue
-
 > **Experimental** — Flue is under active development. APIs may change.
+>
+> Looking for `v0.0.x`? [See here.](https://github.com/withastro/flue/tree/v0.0.x)
+
+# 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.
 
-Agent framework where agents are directories compiled into deployable server artifacts.
+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.
+
+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.
 
 ## Packages
 
@@ -18,6 +24,8 @@ Agent framework where agents are directories compiled into deployable server art
 
 The simplest agent — no container, no tools, just a prompt and a typed result.
 
+Unless you opt-in to initializing a full container sandbox, Flue will default to a virtual sandbox for every agent, powered by [just-bash](https://github.com/vercel-labs/just-bash). A virtual sandbox is going to be dramatically faster, cheaper, and more scalable than running a full container for every agent, which makes it perfect for building high-traffic/high-scale agents.
+
 ```ts
 // .flue/agents/hello-world.ts
 import type { FlueContext } from '@flue/sdk/client';
@@ -34,8 +42,8 @@ export default async function ({ init, payload, sessionId }: FlueContext) {
   const session = await init();
 
   // prompt() sends a message in the session, triggering action.
-  // You can pass a schema to `result` to get typed, validated JSON back.
   const result = await session.prompt(`Translate this to ${payload.language}: "${payload.text}"`, {
+    // Pass a result schema to get typed, schema-validated data back from your agent.
     result: v.object({
       translation: v.string(),
       confidence: v.picklist(['low', 'medium', 'high']),
@@ -48,9 +56,9 @@ export default async function ({ init, payload, sessionId }: FlueContext) {
 
 ### Support Agent
 
-A support agent, also running in a virtual sandbox but now with an R2 bucket mounted as its file-system. The knowledge base is stored in R2 and mounted directly into the agent's filesystem — the agent searches it with its built-in tools (grep, glob, read).
+A support agent can also run in a virtual sandbox, but we now add a file-system using an R2 bucket. The knowledge base is stored in R2 and mounted directly into the agent's filesystem — the agent searches it with its built-in tools (grep, glob, read). Skills are also defined in the bucket that help the agent perform its task.
 
-Session message history and file-system state are automatically persisted using Durable Objects (Cloudflare only). So you can revisit this session days, weeks, or years later and pick up where you left off automatically.
+Because this agent is deployed to Cloudflare, message history and session state are automatically persisted for you. So you (or your customer) can revisit this support session days, weeks, or years later and pick up exactly where you left off.
 
 ```ts
 // .flue/agents/support.ts
@@ -72,18 +80,17 @@ export default async function ({ init, payload, env }: FlueContext) {
     relevant to this request, then write a helpful response.
 
     Customer: ${payload.message}`,
+    {
+      // Provide roles (aka subagents) to guide your agent. Defined in .flue/roles/
+      role: 'triager',
+    },
   );
 }
 ```
 
 ### Issue Triage (CI)
 
-A triage agent that runs whenever a new issue is opened (or commented on) on GitHub, running on GitHub Actions.
-
-Flue was designed to power CI workflows since day one. The `"local"` filesystem sandbox enables two things:
-
-1. Mount the current directory to your virtual file system.
-2. Connect privileged CLIs to your agent (`gh`, `glab`, `git`) without leaking sensitive keys and secrets.
+A triage agent that runs in CI whenever an issue is opened on GitHub. The `"local"` sandbox mounts the host filesystem and lets you connect privileged CLIs (`gh`, `npm`, `git`) to the agent without leaking secrets.
 
 ```ts
 // .flue/agents/triage.ts
@@ -92,6 +99,8 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import * as v from 'valibot';
 
+// Because we are running this in CI, we don't need to expose this as an HTTP endpoint.
+// The CLI can run any agent from the command line, `flue run triage ...`
 export const triggers = {};
 
 // Connect privileged CLIs to your agent without leaking sensitive keys and secrets.
@@ -108,15 +117,23 @@ export default async function ({ init, payload }: FlueContext) {
   // 'local' mounts the host filesystem at /workspace — ideal for CI
   // where the repo is already checked out. Skills and AGENTS.md are
   // discovered automatically from the workspace directory.
-  const session = await init({ sandbox: 'local' });
+  //
+  // `model` sets the default model for every prompt/skill call in this
+  // session. Override per-call with `{ model: '...' }` on prompt()/skill().
+  const session = await init({
+    sandbox: 'local',
+    model: 'anthropic/claude-opus-4-20250514',
+  });
 
+  // Skills can be referenced either by their frontmatter `name:` (shown below)
+  // or by a relative path under `.agents/skills/` — e.g.
+  // `session.skill('triage/reproduce.md', ...)`. Path references are handy for
+  // skill packs that group multiple stages under one directory.
   const result = await session.skill('triage', {
     // Pass arguments to any prompt or skill.
     args: { issueNumber: payload.issueNumber },
     // Grant access to `gh` and `npm` for the life of this skill.
     commands: [gh, npm],
-    // Provide roles (aka subagents) to guide your agent. Defined in .flue/roles/
-    role: 'triager',
     // Result schemas are great for being able to act/orchestrate
     // based on the result of your prompt or skill call.
     result: v.object({

package/dist/client.d.mts

@@ -1,4 +1,4 @@
-import { C as ShellOptions, D as TaskOptions, E as SkillOptions, O as ToolDef, S as SessionStore, b as SessionEnv, d as FlueContext, f as FlueEvent, g as PromptResponse, h as PromptOptions, l as CommandSupport, m as FlueSession, p as FlueEventCallback, r as BashLike, s as Command, t as AgentConfig, u as FileStat, v as SandboxFactory, w as ShellResult, x as SessionInit, y as SessionData } from "./types-xNvqlohs.mjs";
+import { C as ShellOptions, D as TaskOptions, E as SkillOptions, O as ToolDef, S as SessionStore, b as SessionEnv, d as FlueContext, f as FlueEvent, g as PromptResponse, h as PromptOptions, l as CommandSupport, m as FlueSession, p as FlueEventCallback, r as BashLike, s as Command, t as AgentConfig, u as FileStat, v as SandboxFactory, w as ShellResult, x as SessionInit, y as SessionData } from "./types-C97_qJ21.mjs";
 import { Type } from "@mariozechner/pi-ai";
 
 //#region src/client.d.ts

package/dist/client.mjs

@@ -1,4 +1,4 @@
-import { n as Session, o as discoverSessionContext } from "./session-BD0MEuO3.mjs";
+import { n as Session, o as discoverSessionContext } from "./session-0gnaB_aY.mjs";
 import { bashToSessionEnv } from "./sandbox.mjs";
 import { Type } from "@mariozechner/pi-ai";
 
@@ -24,10 +24,12 @@ function createFlueContext(config) {
 			const store = options?.persist ?? config.defaultStore;
 			const savedData = await store.load(config.sessionId);
 			const localContext = await discoverSessionContext(env);
+			const sessionModel = options?.model && config.agentConfig.resolveModel ? config.agentConfig.resolveModel(options.model) : config.agentConfig.model;
 			const sessionConfig = {
 				...config.agentConfig,
 				systemPrompt: localContext.systemPrompt,
-				skills: localContext.skills
+				skills: localContext.skills,
+				model: sessionModel
 			};
 			return new Session(config.sessionId, sessionConfig, env, store, savedData, currentEventCallback);
 		},

package/dist/cloudflare/index.d.mts

@@ -1,4 +1,4 @@
-import { S as SessionStore, b as SessionEnv } from "../types-xNvqlohs.mjs";
+import { S as SessionStore, b as SessionEnv } from "../types-C97_qJ21.mjs";
 
 //#region src/cloudflare/virtual-sandbox.d.ts
 interface VirtualSandboxOptions {

package/dist/cloudflare/index.mjs

@@ -1,4 +1,4 @@
-import "../session-BD0MEuO3.mjs";
+import "../session-0gnaB_aY.mjs";
 import { createSandboxSessionEnv } from "../sandbox.mjs";
 import { Workspace, WorkspaceFileSystem } from "@cloudflare/shell";
 

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { C as ShellOptions, D as TaskOptions, E as SkillOptions, O as ToolDef, S as SessionStore, T as Skill, _ as Role, a as BuildOptions, b as SessionEnv, c as CommandDef, d as FlueContext, f as FlueEvent, g as PromptResponse, h as PromptOptions, i as BuildContext, l as CommandSupport, m as FlueSession, n as AgentInfo, o as BuildPlugin, p as FlueEventCallback, r as BashLike, s as Command, t as AgentConfig, u as FileStat, v as SandboxFactory, w as ShellResult, x as SessionInit, y as SessionData } from "./types-xNvqlohs.mjs";
+import { C as ShellOptions, D as TaskOptions, E as SkillOptions, O as ToolDef, S as SessionStore, T as Skill, _ as Role, a as BuildOptions, b as SessionEnv, c as CommandDef, d as FlueContext, f as FlueEvent, g as PromptResponse, h as PromptOptions, i as BuildContext, l as CommandSupport, m as FlueSession, n as AgentInfo, o as BuildPlugin, p as FlueEventCallback, r as BashLike, s as Command, t as AgentConfig, u as FileStat, v as SandboxFactory, w as ShellResult, x as SessionInit, y as SessionData } from "./types-C97_qJ21.mjs";
 import { FlueContextConfig, FlueContextInternal, createFlueContext } from "./client.mjs";
 import { AgentTool } from "@mariozechner/pi-agent-core";
 import "valibot";

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as createTools, i as BUILTIN_TOOL_NAMES, s as parseFrontmatterFile, t as InMemorySessionStore } from "./session-BD0MEuO3.mjs";
+import { a as createTools, i as BUILTIN_TOOL_NAMES, s as parseFrontmatterFile, t as InMemorySessionStore } from "./session-0gnaB_aY.mjs";
 import { createFlueContext } from "./client.mjs";
 import * as esbuild from "esbuild";
 import * as fs from "node:fs";
@@ -9,9 +9,7 @@ import { packageUpSync } from "package-up";
 var CloudflarePlugin = class {
 	name = "cloudflare";
 	generateEntryPoint(ctx) {
-		const { agents, roles, options, resolveSDKImport } = ctx;
-		const modelProvider = options.model?.provider ?? "anthropic";
-		const modelId = options.model?.modelId ?? "claude-haiku-4-5";
+		const { agents, roles, resolveSDKImport } = ctx;
 		const rolesJson = JSON.stringify(roles);
 		const webhookAgents = agents.filter((a) => a.triggers.webhook);
 		const agentImports = agents.map((a) => {
@@ -51,14 +49,30 @@ const manifest = ${manifest};
 
 // ─── Infrastructure ─────────────────────────────────────────────────────────
 
-const model = getModel(${JSON.stringify(modelProvider)}, ${JSON.stringify(modelId)});
+// No build-time model default. The user sets model at runtime via
+// \`init({ model: "provider/model-id" })\` for a session default, or via
+// \`{ model: "provider/model-id" }\` on any individual prompt/skill/task call.
+const model = undefined;
 
 function resolveModel(modelString) {
   const slash = modelString.indexOf('/');
-  if (slash !== -1) {
-    return getModel(modelString.slice(0, slash), modelString.slice(slash + 1));
+  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 getModel(${JSON.stringify(modelProvider)}, modelString);
+  return resolved;
 }
 
 // ─── Sandbox Environments ───────────────────────────────────────────────────
@@ -370,9 +384,7 @@ function agentClassName(name) {
 var NodePlugin = class {
 	name = "node";
 	generateEntryPoint(ctx) {
-		const { agents, roles, options, resolveSDKImport } = ctx;
-		const modelProvider = options.model?.provider ?? "anthropic";
-		const modelId = options.model?.modelId ?? "claude-haiku-4-5";
+		const { agents, roles, resolveSDKImport } = ctx;
 		const rolesJson = JSON.stringify(roles);
 		const webhookAgents = agents.filter((a) => a.triggers.webhook);
 		const agentImports = agents.map((a) => {
@@ -414,14 +426,30 @@ const manifest = ${manifest};
 
 // ─── Infrastructure ─────────────────────────────────────────────────────────
 
-const model = getModel(${JSON.stringify(modelProvider)}, ${JSON.stringify(modelId)});
+// No build-time model default. The user sets model at runtime via
+// \`init({ model: "provider/model-id" })\` for a session default, or via
+// \`{ model: "provider/model-id" }\` on any individual prompt/skill/task call.
+const model = undefined;
 
 function resolveModel(modelString) {
   const slash = modelString.indexOf('/');
-  if (slash !== -1) {
-    return getModel(modelString.slice(0, slash), modelString.slice(slash + 1));
+  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 getModel(${JSON.stringify(modelProvider)}, modelString);
+  return resolved;
 }
 
 // ─── Sandbox Environments ───────────────────────────────────────────────────

package/dist/sandbox.d.mts

@@ -1,4 +1,4 @@
-import { b as SessionEnv, c as CommandDef, r as BashLike, u as FileStat, v as SandboxFactory, w as ShellResult } from "./types-xNvqlohs.mjs";
+import { b as SessionEnv, c as CommandDef, r as BashLike, u as FileStat, v as SandboxFactory, w as ShellResult } from "./types-C97_qJ21.mjs";
 
 //#region src/sandbox.d.ts
 declare function bashToSessionEnv(bash: BashLike): SessionEnv;

package/dist/sandbox.mjs

@@ -1,4 +1,4 @@
-import { r as normalizePath } from "./session-BD0MEuO3.mjs";
+import { r as normalizePath } from "./session-0gnaB_aY.mjs";
 
 //#region src/sandbox.ts
 function bashToSessionEnv(bash) {

package/dist/{session-BD0MEuO3.mjs → session-0gnaB_aY.mjs}

@@ -39,6 +39,28 @@ async function readAgentsMd(env, basePath) {
 	}
 	return parts.join("\n\n");
 }
+/**
+* Load a skill directly by relative path under `.agents/skills/`.
+*
+* The path is taken as-is — no extension is auto-appended. Callers reference
+* the full filename, e.g. `'triage/reproduce.md'`. Returns `null` if the file
+* doesn't exist.
+*
+* Used as a fallback by `session.skill()` when the requested name doesn't match
+* a discovered skill's frontmatter `name:` field. Lets users organise skills as
+* a pack of sibling markdown files under one directory (orchestration SKILL.md
+* + stage files) without forcing each stage into its own `SKILL.md` subdirectory.
+*/
+async function loadSkillByPath(env, basePath, relPath) {
+	const filePath = `${basePath.endsWith("/") ? `${basePath}.agents/skills` : `${basePath}/.agents/skills`}/${relPath}`;
+	if (!await env.exists(filePath)) return null;
+	const parsed = parseFrontmatterFile(await env.readFile(filePath), relPath.replace(/\.(md|markdown)$/i, ""));
+	return {
+		name: parsed.name,
+		description: parsed.description,
+		instructions: parsed.body
+	};
+}
 /** Discover skills from .agents/skills/<name>/SKILL.md under basePath. */
 async function discoverLocalSkills(env, basePath) {
 	const skillsDir = basePath.endsWith("/") ? `${basePath}.agents/skills` : `${basePath}/.agents/skills`;
@@ -987,6 +1009,7 @@ var Session = class Session {
 		});
 	}
 	async prompt(text, options) {
+		this.assertRoleExists(options?.role);
 		this.resolveModelForCall(options?.model, options?.role);
 		const promptWithRole = this.injectRoleInstructions(text, options?.role);
 		const schema = options?.result;
@@ -1007,8 +1030,16 @@ var Session = class Session {
 		}
 	}
 	async skill(name, options) {
-		const registeredSkill = this.config.skills[name];
-		if (!registeredSkill) throw new Error(`Skill "${name}" not registered. Available: ${Object.keys(this.config.skills).join(", ") || "(none)"}`);
+		this.assertRoleExists(options?.role);
+		let registeredSkill = this.config.skills[name];
+		if (!registeredSkill && (name.includes("/") || /\.(md|markdown)$/i.test(name))) {
+			const loaded = await loadSkillByPath(this.env, this.env.cwd, name);
+			if (loaded) registeredSkill = loaded;
+		}
+		if (!registeredSkill) {
+			const available = Object.keys(this.config.skills).join(", ") || "(none)";
+			throw new Error(`Skill "${name}" not registered. Available: ${available}. Skills can also be referenced by relative path under .agents/skills/ (e.g. "triage/reproduce.md").`);
+		}
 		this.resolveModelForCall(options?.model, options?.role);
 		const schema = options?.result;
 		const skillPrompt = buildSkillPrompt(registeredSkill.instructions, options?.args, schema);
@@ -1046,6 +1077,7 @@ var Session = class Session {
 		}
 	}
 	async task(prompt, options) {
+		this.assertRoleExists(options?.role);
 		if (!options?.workspace) throw new Error("[flue] task() requires a workspace option.");
 		const taskCwd = options.workspace.startsWith("/") ? options.workspace : normalizePath(this.env.cwd + "/" + options.workspace);
 		function taskResolvePath(p) {
@@ -1081,7 +1113,7 @@ var Session = class Session {
 			systemPrompt: localContext.systemPrompt,
 			skills: localContext.skills,
 			roles: this.config.roles,
-			model: taskModel,
+			model: this.requireModel(taskModel, "this task() call"),
 			resolveModel: this.config.resolveModel,
 			compaction: this.config.compaction
 		};
@@ -1113,7 +1145,28 @@ var Session = class Session {
 		let model = this.config.model;
 		if (roleName && this.config.roles[roleName]?.model && this.config.resolveModel) model = this.config.resolveModel(this.config.roles[roleName].model);
 		if (promptModel && this.config.resolveModel) model = this.config.resolveModel(promptModel);
-		this.agent.state.model = model;
+		this.agent.state.model = this.requireModel(model, "this prompt()/skill()/task() call");
+	}
+	/**
+	* Throws a clear, actionable error when no model is configured for a call.
+	* Use with the resolved model (post-precedence) to guarantee we never hand
+	* `undefined` to the underlying agent.
+	*/
+	requireModel(model, callSite) {
+		if (model) return model;
+		throw new Error(`[flue] No model configured for ${callSite}. Pass \`{ model: "provider/model-id" }\` to \`init()\` for a session-wide default, or to this prompt()/skill()/task() call for a one-off override.`);
+	}
+	/**
+	* Throws a clear error when a caller references a role that isn't registered.
+	* Roles are loaded from `.flue/roles/` at build time. Called eagerly at the top
+	* of prompt()/skill()/task() so typos surface before any LLM work begins.
+	*/
+	assertRoleExists(roleName) {
+		if (!roleName) return;
+		if (this.config.roles[roleName]) return;
+		const available = Object.keys(this.config.roles);
+		const list = available.length > 0 ? available.join(", ") : "(none defined)";
+		throw new Error(`[flue] Role "${roleName}" not registered. Available roles: ${list}. Define roles as markdown files under \`.flue/roles/\`.`);
 	}
 	injectRoleInstructions(text, roleName) {
 		if (!roleName) return text;

package/dist/{types-xNvqlohs.d.mts → types-C97_qJ21.d.mts}

@@ -107,8 +107,13 @@ interface AgentConfig {
   /** Discovered at runtime from .agents/skills/ in the session's cwd. */
   skills: Record<string, Skill>;
   roles: Record<string, Role>;
-  model: Model<any>;
-  /** Resolve a "provider/modelId" string to a Model instance. */
+  /**
+   * Session-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.
+   */
+  model: Model<any> | undefined;
+  /** Resolve a "provider/modelId" string to a Model instance. Throws on invalid input. */
   resolveModel?: (modelString: string) => Model<any>;
   compaction?: CompactionConfig;
 }
@@ -121,7 +126,7 @@ interface FlueContext {
   /** Create a session with sandbox + persistence. Can only be called once per request. */
   init(options?: SessionInit): Promise<FlueSession>;
 }
-/** Both fields are optional — omitting gives platform defaults (empty sandbox, platform store). */
+/** All fields are optional — omitting gives platform defaults (empty sandbox, platform store, build-time model). */
 interface SessionInit {
   /**
    * - `'empty'` (default): In-memory sandbox, no files, no host access.
@@ -132,6 +137,15 @@ interface SessionInit {
   sandbox?: 'empty' | 'local' | SandboxFactory | BashLike;
   /** Defaults to platform store (in-memory on Node, DO SQLite on Cloudflare). */
   persist?: SessionStore;
+  /**
+   * Override the default model for this session. Applies to all prompt(), skill(),
+   * and task() calls unless overridden at the call site.
+   *
+   * Format: `'provider/modelId'` (e.g. `'anthropic/claude-opus-4-20250514'`).
+   *
+   * Precedence (highest wins): per-call `model` > role `model` > session `model` > build-time default.
+   */
+  model?: string;
 }
 interface FlueSession {
   prompt<S extends v.GenericSchema>(text: string, options: PromptOptions<S> & {
@@ -318,10 +332,6 @@ interface BuildOptions {
   target?: 'node' | 'cloudflare';
   /** Overrides `target` when provided. */
   plugin?: BuildPlugin;
-  model?: {
-    provider: string;
-    modelId: string;
-  };
 }
 //#endregion
 export { ShellOptions as C, TaskOptions as D, SkillOptions as E, ToolDef as O, SessionStore as S, Skill as T, Role as _, BuildOptions as a, SessionEnv as b, CommandDef as c, FlueContext as d, FlueEvent as f, PromptResponse as g, PromptOptions as h, BuildContext as i, CommandSupport as l, FlueSession as m, AgentInfo as n, BuildPlugin as o, FlueEventCallback as p, BashLike as r, Command as s, AgentConfig as t, FileStat as u, SandboxFactory as v, ShellResult as w, SessionInit as x, SessionData as y };

package/package.json

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