@flue/sdk 0.2.0 → 0.3.1

package/README.md

@@ -35,11 +35,10 @@ import * as v from 'valibot';
 export const triggers = { webhook: true };
 
 // The agent handler. Where the orchestration of the agent lives.
-export default async function ({ init, payload, sessionId }: FlueContext) {
-  // `session` -- Your session with the agent, including sandbox, message history, etc.
-  // By default, calling `init()` with no arguments gets you a completely empty agent,
-  // with no skills, AGENTS.md, or files.
-  const session = await init();
+export default async function ({ init, payload }: FlueContext) {
+  // `agent` -- Your initialized agent runtime including sandbox, tools, skills, etc.
+  const agent = await init({ model: 'anthropic/claude-sonnet-4-6' });
+  const session = await agent.session();
 
   // prompt() sends a message in the session, triggering action.
   const result = await session.prompt(`Translate this to ${payload.language}: "${payload.text}"`, {
@@ -73,7 +72,8 @@ export default async function ({ init, payload, env }: FlueContext) {
   // The agent can grep, glob, and read articles with bash, but
   // without needing to spin up an entire container sandbox.
   const sandbox = await getVirtualSandbox(env.KNOWLEDGE_BASE);
-  const session = await init({ sandbox });
+  const agent = await init({ sandbox, model: 'openrouter/moonshotai/kimi-k2.6' });
+  const session = await agent.session();
 
   return await session.prompt(
     `You are a support agent. Search the knowledge base for articles
@@ -114,11 +114,12 @@ export default async function ({ init, payload }: FlueContext) {
   // discovered automatically from the workspace directory.
   //
   // `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({
+  // agent. Override per-call with `{ model: '...' }` on prompt()/skill().
+  const agent = await init({
     sandbox: 'local',
-    model: 'anthropic/claude-opus-4-20250514',
+    model: 'anthropic/claude-opus-4-7',
   });
+  const session = await agent.session();
 
   // Skills can be referenced either by their frontmatter `name:` (shown below)
   // or by a relative path under `.agents/skills/` — e.g.
@@ -158,23 +159,35 @@ import { daytona } from '@flue/connectors/daytona';
 export const triggers = { webhook: true };
 
 export default async function ({ init, payload, env }: FlueContext) {
-  // Each session gets a real container via Daytona. The container has
+  // Each agent gets a real container via Daytona. The container has
   // a full Linux environment with persistent filesystem and shell.
   //
   // For simplicity, we always create a new sandbox here. You could also
-  // first check for an existing sandbox for the sessionId, and reuse that
+  // first check for an existing sandbox for the agent id, and reuse that
   // instead to best pick up where you last left off in the conversation.
   const client = new Daytona({ apiKey: env.DAYTONA_API_KEY });
   const sandbox = await client.create();
-  const session = await init({
+  const setupAgent = await init({
     sandbox: daytona(sandbox, { cleanup: true }),
+    model: 'openai/gpt-5.5',
   });
+  const setup = await setupAgent.session();
 
   // For simplicity, we clone the target repo into the sandbox here.
   // You could also bake these into the container image snapshot for a
   // faster / near-instant startup.
-  await session.shell(`git clone ${payload.repo} /workspace/project`);
-  await session.shell('npm install', { cwd: '/workspace/project' });
+  await setup.shell(`git clone ${payload.repo} /workspace/project`);
+  await setup.shell('npm install', { cwd: '/workspace/project' });
+
+  // Start a second agent in the cloned repo. It shares the same sandbox, but
+  // discovers AGENTS.md and skills from /workspace/project.
+  const projectAgent = await init({
+    id: 'project',
+    sandbox: daytona(sandbox),
+    cwd: '/workspace/project',
+    model: 'openai/gpt-5.5',
+  });
+  const session = await projectAgent.session();
 
   // Coding agents don't hide the agent DX from the user, so no need to
   // wrap the user's prompt in anything. Just send it to the agent directly
@@ -183,24 +196,146 @@ export default async function ({ init, payload, env }: FlueContext) {
 }
 ```
 
+### Remote MCP Tools
+
+MCP is available as a runtime tool adapter. Connect to a remote MCP server in trusted code, pass its tools to `init()`, and keep secrets in `env` instead of filesystem context or prompts.
+
+```ts
+// .flue/agents/assistant.ts
+import { connectMcpServer, type FlueContext } from '@flue/sdk/client';
+
+export const triggers = { webhook: true };
+
+export default async function ({ init, payload, env }: FlueContext) {
+  const github = await connectMcpServer('github', {
+    url: 'https://mcp.github.com/mcp',
+    headers: {
+      Authorization: `Bearer ${env.GITHUB_TOKEN}`,
+    },
+  });
+
+  try {
+    const agent = await init({
+      model: 'anthropic/claude-sonnet-4-6',
+      tools: github.tools,
+    });
+    const session = await agent.session();
+    return await session.prompt(payload.prompt);
+  } finally {
+    await github.close();
+  }
+}
+```
+
+`connectMcpServer()` defaults to modern streamable HTTP. For legacy SSE servers, pass `transport: 'sse'`. Flue does not auto-detect transports, spawn local stdio MCP servers, or handle OAuth callbacks in this first version.
+
+## Agents And Sessions
+
+Every agent invocation runs inside an initialized agent runtime. For HTTP agents, the agent ID is the last path segment:
+
+```txt
+POST /agents/<agent-name>/<id>
+```
+
+By default, `agent.session()` opens the default session for that agent ID. Reuse the same agent ID to continue the same default conversation. Use a new agent ID to start fresh.
+
+```bash
+# Start a conversation (port 3583 is `flue dev`'s default)
+curl http://localhost:3583/agents/hello/session-abc \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Alice"}'
+
+# Continue that conversation
+curl http://localhost:3583/agents/hello/session-abc \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Alice"}'
+
+# Start a separate conversation
+curl http://localhost:3583/agents/hello/session-xyz \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Alice"}'
+```
+
+Agents own sandbox state such as files written during a run. Sessions persist message history and conversation metadata inside an agent. On Cloudflare, session data is backed by Durable Objects and survives across requests. On Node.js, sessions are stored in memory by default unless you provide a custom store.
+
+In production, generate a stable agent ID for the sandbox/runtime scope you want to preserve. Use `agent.session(threadId)` when you need multiple conversations inside the same agent.
+
+### Tasks
+
+Use `session.task()` to run a focused, one-shot child agent in a detached session. Tasks share the same sandbox/filesystem, but get their own message history and discover `AGENTS.md` plus `.agents/skills/` from their working directory. The same `task` tool is also available to the LLM during `prompt()` and `skill()` calls, so the agent can delegate parallel research or exploration work itself.
+
+```ts
+const session = await agent.session();
+
+const research = await session.task('Research the auth flow and summarize the key files.', {
+  cwd: '/workspace/project',
+  role: 'researcher',
+});
+
+const answer = await session.prompt(
+  `Use this research to draft the implementation plan:\n\n${research.text}`,
+);
+```
+
+Roles can be set at the agent, session, or call level. Precedence is `call role > session role > agent role`. Role instructions are applied as call-scoped system prompt overlays, not injected into the persisted user message history.
+
+```ts
+const agent = await init({ model: 'anthropic/claude-sonnet-4-6', role: 'coder' });
+const session = await agent.session('review-thread', { role: 'reviewer' });
+
+await session.prompt('Review the latest changes.'); // uses reviewer
+await session.task('Research related issues.', { role: 'researcher' }); // uses researcher
+```
+
+### 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.
+
+```ts
+import { Bash, InMemoryFs } from 'just-bash';
+
+const fs = new InMemoryFs();
+
+const agent = await init({
+  sandbox: () => new Bash({ fs, cwd: '/workspace', python: true }),
+  model: 'anthropic/claude-sonnet-4-6',
+});
+const session = await agent.session();
+```
+
 ## Running Agents
 
-### Trigger From the CLI
+### Local Development (`flue dev`)
 
-Build and run any agent locally, perfect for fast local testing or running in CI.
+Long-running watch-mode dev server. Rebuilds and reloads on file changes — edit an agent, re-run `curl`, see your change.
 
 ```bash
-flue run hello --target node --session-id test-1 \
+flue dev --target node          # Node.js dev server
+flue dev --target cloudflare    # Cloudflare Workers (via wrangler) dev server
+```
+
+Defaults to port `3583` ("FLUE" on a phone keypad). Override with `--port`.
+
+`flue dev --target cloudflare` requires `wrangler` as a peer dependency in your project (`npm install --save-dev wrangler`).
+
+### Trigger From the CLI (`flue run`)
+
+Build and run any agent locally, perfect for running in CI or for one-shot scripted invocations. Production-shaped — builds the deployable artifact and starts it once.
+
+```bash
+flue run hello --target node --id test-1 \
   --payload '{"text": "Hello world", "language": "French"}'
 ```
 
-### Trigger From HTTP Endpoint
+### Trigger From HTTP Endpoint (`flue build`)
 
 Build and deploy your agents as a web server, perfect for hosted agents.
 
-`flue build` builds to a `./dist` directory, which you can then deploy anywhere. Cloudflare and any Node.js host are supported today, with more coming in the future.
+`flue build` builds to a `./dist` directory, which you can then deploy. Cloudflare and any Node.js host are supported today, with more coming in the future.
 
 ```
-flue build --target node          # Node.js server
+flue build --target node          # Node.js server (single bundled .mjs)
 flue build --target cloudflare    # Cloudflare Workers + Durable Objects
 ```
+
+For Cloudflare, `flue build` produces an unbundled TypeScript entry that `wrangler deploy` bundles itself — the same path `flue dev --target cloudflare` uses. Dev and deploy go through the same bundler, so what works in dev will work in production.

package/dist/{agent-BYG0nVbQ.mjs → agent-BB4lwAd5.mjs}

@@ -137,10 +137,11 @@ const BUILTIN_TOOL_NAMES = new Set([
 	"edit",
 	"bash",
 	"grep",
-	"glob"
+	"glob",
+	"task"
 ]);
-function createTools(env) {
-	return [
+function createTools(env, options) {
+	const tools = [
 		createReadTool(env),
 		createWriteTool(env),
 		createEditTool(env),
@@ -148,6 +149,8 @@ function createTools(env) {
 		createGrepTool(env),
 		createGlobTool(env)
 	];
+	if (options?.task) tools.push(createTaskTool(options.task, options.roles ?? {}));
+	return tools;
 }
 function createReadTool(env) {
 	return {
@@ -288,6 +291,24 @@ function createBashTool(env) {
 		}
 	};
 }
+function createTaskTool(runTask, roles) {
+	const roleNames = Object.keys(roles);
+	return {
+		name: "task",
+		label: "Run Task",
+		description: "Delegate a focused task to a detached child agent with its own context. Use this for independent research, file exploration, or parallel work. The task returns only its final answer to this conversation." + (roleNames.length > 0 ? ` Available roles: ${roleNames.join(", ")}.` : " No roles are currently defined."),
+		parameters: Type.Object({
+			description: Type.Optional(Type.String({ description: "Short human-readable label for the delegated work" })),
+			prompt: Type.String({ description: "Focused instructions for the child agent" }),
+			role: Type.Optional(Type.String({ description: "Role to use for the child agent" })),
+			cwd: Type.Optional(Type.String({ description: "Working directory for the child agent. AGENTS.md and skills are discovered from here." }))
+		}),
+		async execute(_toolCallId, params, signal) {
+			throwIfAborted(signal);
+			return runTask(params, signal);
+		}
+	};
+}
 function formatBashResult(result, command) {
 	const { text: output } = truncateTail((result.stdout + (result.stderr ? "\n" + result.stderr : "")).trim(), MAX_READ_LINES, MAX_READ_BYTES);
 	if (result.exitCode !== 0) throw new Error(`${output}\n\nCommand exited with code ${result.exitCode}`);

package/dist/client.d.mts

@@ -1,9 +1,10 @@
-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-C0nqbu6Z.mjs";
+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 { Type } from "@mariozechner/pi-ai";
 
 //#region src/client.d.ts
 interface FlueContextConfig {
-  sessionId: string;
+  id: string;
   payload: any;
   env: Record<string, any>;
   agentConfig: AgentConfig;
@@ -22,4 +23,4 @@ interface FlueContextInternal extends FlueContext {
 }
 declare function createFlueContext(config: FlueContextConfig): FlueContextInternal;
 //#endregion
-export { type BashLike, type Command, type CommandSupport, type FileStat, type FlueContext, FlueContextConfig, FlueContextInternal, type FlueEvent, type FlueEventCallback, type FlueSession, type PromptOptions, type PromptResponse, type SandboxFactory, type SessionData, type SessionEnv, type SessionInit, type SessionStore, type ShellOptions, type ShellResult, type SkillOptions, type TaskOptions, type ToolDef, Type, 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 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 };

package/dist/client.mjs

@@ -1,15 +1,16 @@
-import { r as discoverSessionContext } from "./agent-BYG0nVbQ.mjs";
-import { n as Session } from "./session-CiAMTsLZ.mjs";
-import { bashToSessionEnv } from "./sandbox.mjs";
+import { r as discoverSessionContext } from "./agent-BB4lwAd5.mjs";
+import { a as assertRoleExists } from "./session-DukL3zwF.mjs";
+import { bashFactoryToSessionEnv, createCwdSessionEnv } from "./sandbox.mjs";
+import { n as AgentClient, t as connectMcpServer } from "./mcp-DOgMtp8y.mjs";
 import { Type } from "@mariozechner/pi-ai";
 
 //#region src/client.ts
 function createFlueContext(config) {
-	let initialized = false;
 	let currentEventCallback;
+	const initializedAgentIds = /* @__PURE__ */ new Set();
 	return {
-		get sessionId() {
-			return config.sessionId;
+		get id() {
+			return config.id;
 		},
 		get payload() {
 			return config.payload;
@@ -18,21 +19,28 @@ function createFlueContext(config) {
 			return config.env;
 		},
 		async init(options) {
-			if (initialized) throw new Error("[flue] init() can only be called once per request.");
-			initialized = true;
-			const sandbox = options?.sandbox;
-			const env = await resolveSessionEnv(config.sessionId, sandbox, 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,
-				model: sessionModel
-			};
-			return new Session(config.sessionId, sessionConfig, env, store, savedData, currentEventCallback, options?.commands);
+			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;
+				const localContext = await discoverSessionContext(env);
+				const agentModel = options?.model && config.agentConfig.resolveModel ? config.agentConfig.resolveModel(options.model) : config.agentConfig.model;
+				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);
+			} catch (error) {
+				initializedAgentIds.delete(id);
+				throw error;
+			}
 		},
 		setEventCallback(callback) {
 			currentEventCallback = callback;
@@ -43,17 +51,28 @@ function createFlueContext(config) {
 function isBashLike(value) {
 	return typeof value === "object" && value !== null && "exec" in value && "getCwd" in value && "fs" in value && typeof value.exec === "function" && typeof value.getCwd === "function" && typeof value.fs === "object";
 }
-/** Resolve sandbox option to SessionEnv: empty → local → BashLike → platform hook → SandboxFactory. */
-async function resolveSessionEnv(sessionId, sandbox, config) {
+function isBashFactory(value) {
+	return typeof value === "function";
+}
+function isSandboxFactory(value) {
+	return typeof value === "object" && value !== null && "createSessionEnv" in value && typeof value.createSessionEnv === "function";
+}
+/** Resolve sandbox option to SessionEnv: empty → local → BashFactory → platform hook → SandboxFactory. */
+async function resolveSessionEnv(id, sandbox, config, cwd) {
 	if (sandbox === void 0 || sandbox === "empty") return config.createDefaultEnv();
 	if (sandbox === "local") return config.createLocalEnv();
-	if (isBashLike(sandbox)) return bashToSessionEnv(sandbox);
+	if (isBashFactory(sandbox)) return bashFactoryToSessionEnv(sandbox);
+	if (isBashLike(sandbox)) throw new Error("[flue] init({ sandbox }) no longer accepts a Bash-like object directly. Pass a BashFactory instead, e.g. `sandbox: () => new Bash({ fs })`.");
 	if (config.resolveSandbox) {
 		const resolved = await config.resolveSandbox(sandbox);
 		if (resolved) return resolved;
 	}
-	return sandbox.createSessionEnv({ sessionId });
+	if (isSandboxFactory(sandbox)) return sandbox.createSessionEnv({
+		id,
+		cwd
+	});
+	throw new Error("[flue] Invalid sandbox option passed to init().");
 }
 
 //#endregion
-export { Type, createFlueContext };
+export { Type, connectMcpServer, createFlueContext };

package/dist/cloudflare/index.d.mts

@@ -1,5 +1,5 @@
-import { S as SessionStore, b as SessionEnv, s as Command } from "../types-C0nqbu6Z.mjs";
-import { t as CommandExecutor } from "../command-helpers-C8SHLdaA.mjs";
+import { C as SessionEnv, T as SessionStore, l as Command } from "../types-T8pE1xIS.mjs";
+import { t as CommandExecutor } from "../command-helpers-DdAfbnom.mjs";
 
 //#region src/cloudflare/virtual-sandbox.d.ts
 interface VirtualSandboxOptions {
@@ -19,10 +19,6 @@ declare function cfSandboxToSessionEnv(sandbox: any, cwd?: string): Promise<Sess
 declare function store(): SessionStore;
 //#endregion
 //#region src/cloudflare/context.d.ts
-/**
- * Cloudflare environment context injection. Safe because each DO is single-threaded.
- * Set before handler invocation, accessed by runtime primitives, cleared after.
- */
 interface CloudflareContext {
   env: Record<string, any>;
   agentInstance: {
@@ -33,8 +29,7 @@ interface CloudflareContext {
     sql: any;
   };
 }
-declare function setCloudflareContext(ctx: CloudflareContext): void;
+declare function runWithCloudflareContext<T>(ctx: CloudflareContext, fn: () => T): T;
 declare function getCloudflareContext(): CloudflareContext;
-declare function clearCloudflareContext(): void;
 //#endregion
-export { type CloudflareContext, type VirtualSandboxOptions, cfSandboxToSessionEnv, clearCloudflareContext, defineCommand, getCloudflareContext, getVirtualSandbox, setCloudflareContext, store };
+export { type CloudflareContext, type VirtualSandboxOptions, cfSandboxToSessionEnv, defineCommand, getCloudflareContext, getVirtualSandbox, runWithCloudflareContext, store };

package/dist/cloudflare/index.mjs

@@ -1,20 +1,26 @@
-import "../agent-BYG0nVbQ.mjs";
-import "../session-CiAMTsLZ.mjs";
+import "../agent-BB4lwAd5.mjs";
+import "../session-DukL3zwF.mjs";
 import { createSandboxSessionEnv } from "../sandbox.mjs";
-import { t as normalizeExecutor } from "../command-helpers-CxRhK1my.mjs";
+import { t as normalizeExecutor } from "../command-helpers-hTZKWK13.mjs";
 import { Workspace, WorkspaceFileSystem } from "@cloudflare/shell";
+import { AsyncLocalStorage } from "node:async_hooks";
 
 //#region src/cloudflare/context.ts
-let currentContext = null;
-function setCloudflareContext(ctx) {
-	currentContext = ctx;
+/**
+* Cloudflare environment context injection.
+*
+* Durable Objects are single-threaded, but async executions can still interleave
+* at await points. AsyncLocalStorage keeps Cloudflare runtime primitives scoped
+* to the request/fiber that invoked them instead of sharing a module global.
+*/
+const contextStorage = new AsyncLocalStorage();
+function runWithCloudflareContext(ctx, fn) {
+	return contextStorage.run(ctx, fn);
 }
 function getCloudflareContext() {
-	if (!currentContext) throw new Error("[flue:cloudflare] Not running in a Cloudflare context. This function can only be called inside a Cloudflare Worker or Durable Object.");
-	return currentContext;
-}
-function clearCloudflareContext() {
-	currentContext = null;
+	const ctx = contextStorage.getStore();
+	if (!ctx) throw new Error("[flue:cloudflare] Not running in a Cloudflare context. This function can only be called inside a Cloudflare Worker or Durable Object.");
+	return ctx;
 }
 
 //#endregion
@@ -81,8 +87,9 @@ async function getVirtualSandbox(bucket, options) {
 			/* @vite-ignore */
 			"just-bash"
 );
-		return new Bash({
-			fs: new InMemoryFs(),
+		const fs = new InMemoryFs();
+		return () => new Bash({
+			fs,
 			network: { dangerouslyAllowFullInternetAccess: true }
 		});
 	}
@@ -99,7 +106,7 @@ async function getVirtualSandbox(bucket, options) {
 );
 	const fs = new MountableFs({ base: new InMemoryFs() });
 	fs.mount("/workspace", r2Adapter);
-	return new Bash({
+	return () => new Bash({
 		fs,
 		cwd: "/workspace",
 		network: { dangerouslyAllowFullInternetAccess: true }
@@ -205,26 +212,30 @@ async function cfSandboxToSessionEnv(sandbox, cwd = "/workspace") {
 //#region src/cloudflare/session-store.ts
 function store() {
 	return {
-		async save(_id, data) {
+		async save(id, data) {
 			const { agentInstance } = getCloudflareContext();
+			const sessions = { ...agentInstance.state?.sessions ?? {} };
+			sessions[id] = data;
 			agentInstance.setState({
 				...agentInstance.state,
-				sessionData: data
+				sessions
 			});
 		},
-		async load(_id) {
+		async load(id) {
 			const { agentInstance } = getCloudflareContext();
-			return agentInstance.state?.sessionData ?? null;
+			return agentInstance.state?.sessions?.[id] ?? null;
 		},
-		async delete(_id) {
+		async delete(id) {
 			const { agentInstance } = getCloudflareContext();
+			const sessions = { ...agentInstance.state?.sessions ?? {} };
+			delete sessions[id];
 			agentInstance.setState({
 				...agentInstance.state,
-				sessionData: null
+				sessions
 			});
 		}
 	};
 }
 
 //#endregion
-export { cfSandboxToSessionEnv, clearCloudflareContext, defineCommand, getCloudflareContext, getVirtualSandbox, setCloudflareContext, store };
+export { cfSandboxToSessionEnv, defineCommand, getCloudflareContext, getVirtualSandbox, runWithCloudflareContext, store };

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

@@ -1,4 +1,4 @@
-import { w as ShellResult } from "./types-C0nqbu6Z.mjs";
+import { D as ShellResult } from "./types-T8pE1xIS.mjs";
 
 //#region src/command-helpers.d.ts
 /**

package/dist/index.d.mts

@@ -1,7 +1,15 @@
-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-C0nqbu6Z.mjs";
-import { AgentTool } from "@mariozechner/pi-agent-core";
+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 { AgentTool, AgentToolResult } from "@mariozechner/pi-agent-core";
 
 //#region src/build.d.ts
+/**
+ * Result returned by {@link build}. `changed` indicates whether any file in
+ * `dist/` was actually modified. Callers (notably the dev server) use this to
+ * skip restarting downstream processes for no-op rebuilds on agent body edits.
+ */
+interface BuildResult {
+  changed: boolean;
+}
 /**
  * Build a workspace into a deployable artifact.
  *
@@ -12,7 +20,7 @@ import { AgentTool } from "@mariozechner/pi-agent-core";
  *
  * AGENTS.md and .agents/skills/ are NOT bundled — discovered at runtime from session cwd.
  */
-declare function build(options: BuildOptions): Promise<void>;
+declare function build(options: BuildOptions): Promise<BuildResult>;
 /**
  * Resolve a Flue workspace directory from the current working directory,
  * using the two-layout convention. Intended for the CLI when `--workspace` is
@@ -28,8 +36,43 @@ declare function build(options: BuildOptions): Promise<void>;
  */
 declare function resolveWorkspaceFromCwd(cwd: string): string | null;
 //#endregion
+//#region src/dev.d.ts
+interface DevOptions {
+  workspaceDir: string;
+  outputDir: string;
+  target: 'node' | 'cloudflare';
+  /** Defaults to 3583 ("FLUE" on a phone keypad). */
+  port?: number;
+}
+/** Default port for `flue dev`. F=3, L=5, U=8, E=3 on a phone keypad. */
+declare const DEFAULT_DEV_PORT = 3583;
+/**
+ * Start a Flue dev server. Resolves only when the server is shut down (e.g.
+ * via SIGINT). Errors during the initial build/start are thrown synchronously;
+ * errors during subsequent rebuilds are logged but do NOT exit the dev server
+ * — the user is editing code, after all, and we want to recover when they fix it.
+ */
+declare function dev(options: DevOptions): Promise<void>;
+//#endregion
 //#region src/agent.d.ts
 declare const BUILTIN_TOOL_NAMES: Set<string>;
-declare function createTools(env: SessionEnv): AgentTool<any>[];
+interface TaskToolParams {
+  prompt: string;
+  description?: string;
+  role?: string;
+  cwd?: string;
+}
+interface TaskToolResultDetails {
+  taskId: string;
+  sessionId: string;
+  messageId?: string;
+  role?: string;
+  cwd?: string;
+}
+interface CreateToolsOptions {
+  task?: (params: TaskToolParams, signal?: AbortSignal) => Promise<AgentToolResult<TaskToolResultDetails>>;
+  roles?: Record<string, Role>;
+}
+declare function createTools(env: SessionEnv, options?: CreateToolsOptions): AgentTool<any>[];
 //#endregion
-export { type AgentConfig, type AgentInfo, BUILTIN_TOOL_NAMES, type BashLike, type BuildContext, type BuildOptions, type BuildPlugin, type Command, type CommandDef, type CommandSupport, type FileStat, type FlueContext, type FlueEvent, type FlueEventCallback, type FlueSession, type PromptOptions, type PromptResponse, type Role, type SandboxFactory, type SessionData, type SessionEnv, type SessionInit, type SessionStore, type ShellOptions, type ShellResult, type Skill, type SkillOptions, type TaskOptions, type ToolDef, build, createTools, 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 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, resolveWorkspaceFromCwd };