@flue/sdk 0.4.1 → 0.5.0

package/README.md

@@ -37,9 +37,9 @@ export const triggers = { webhook: true };
 
 // The agent handler. Where the orchestration of the agent lives.
 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();
+  // `harness` -- Your initialized harness including sandbox, tools, skills, etc.
+  const harness = await init({ model: 'anthropic/claude-sonnet-4-6' });
+  const session = await harness.session();
 
   // prompt() sends a message in the session, triggering action.
   const { data } = await session.prompt(`Translate this to ${payload.language}: "${payload.text}"`, {
@@ -56,7 +56,7 @@ export default async function ({ init, payload }: FlueContext) {
 
 ### Support Agent
 
-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.
+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 harness 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.
 
 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.
 
@@ -69,12 +69,12 @@ import * as v from 'valibot';
 export const triggers = { webhook: true };
 
 export default async function ({ init, payload, env }: FlueContext) {
-  // Mount the R2 knowledge base bucket as the agent's filesystem.
+  // Mount the R2 knowledge base bucket as the harness filesystem.
   // 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 agent = await init({ sandbox, model: 'openrouter/moonshotai/kimi-k2.6' });
-  const session = await agent.session();
+  const harness = await init({ sandbox, model: 'openrouter/moonshotai/kimi-k2.6' });
+  const session = await harness.session();
 
   return await session.prompt(
     `You are a support agent. Search the knowledge base for articles
@@ -109,11 +109,11 @@ export default async function ({ init, payload }: FlueContext) {
   //
   // `model` sets the default model for every prompt/skill call in this
   // agent. Override per-call with `{ model: '...' }` on prompt()/skill().
-  const agent = await init({
+  const harness = await init({
     sandbox: 'local',
     model: 'anthropic/claude-opus-4-7',
   });
-  const session = await agent.session();
+  const session = await harness.session();
 
   // Skills can be referenced either by their frontmatter `name:` (shown below)
   // or by a relative path under `.agents/skills/` — e.g.
@@ -157,15 +157,15 @@ export default async function ({ init, payload, env }: FlueContext) {
   // 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 agent id, and reuse that
+  // first check for an existing sandbox for the agent instance 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 setupAgent = await init({
+  const setupHarness = await init({
     sandbox: daytona(sandbox),
     model: 'openai/gpt-5.5',
   });
-  const setup = await setupAgent.session();
+  const setup = await setupHarness.session();
 
   // For simplicity, we clone the target repo into the sandbox here.
   // You could also bake these into the container image snapshot for a
@@ -173,15 +173,15 @@ export default async function ({ init, payload, env }: FlueContext) {
   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
+  // Start a second harness in the cloned repo. It shares the same sandbox, but
   // discovers AGENTS.md and skills from /workspace/project.
-  const projectAgent = await init({
-    id: 'project',
+  const projectHarness = await init({
+    name: 'project',
     sandbox: daytona(sandbox),
     cwd: '/workspace/project',
     model: 'openai/gpt-5.5',
   });
-  const session = await projectAgent.session();
+  const session = await projectHarness.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
@@ -209,11 +209,11 @@ export default async function ({ init, payload, env }: FlueContext) {
   });
 
   try {
-    const agent = await init({
+    const harness = await init({
       model: 'anthropic/claude-sonnet-4-6',
       tools: github.tools,
     });
-    const session = await agent.session();
+    const session = await harness.session();
     return await session.prompt(payload.prompt);
   } finally {
     await github.close();
@@ -223,15 +223,17 @@ export default async function ({ init, payload, env }: FlueContext) {
 
 `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
+## Agents, Harnesses, And Sessions
 
-Every agent invocation runs inside an initialized agent runtime. For HTTP agents, the agent ID is the last path segment:
+An agent is the source file in `agents/<name>.ts`. For HTTP agents, the URL `<id>` segment identifies the agent instance: the durable runtime scope for one customer, repo, conversation space, or other caller-defined boundary.
 
 ```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.
+Inside a run, `init()` creates a harness: a configured handle for model defaults, tools, sandbox, filesystem, and sessions. The default harness is named `"default"`; pass `init({ name })` when one run needs multiple isolated harness scopes.
+
+By default, `harness.session()` opens the default session inside the default harness for that agent instance. Reuse the same URL `<id>` to continue the same agent instance. Use a new URL `<id>` to start fresh.
 
 ```bash
 # Start a conversation (port 3583 is `flue dev`'s default)
@@ -250,16 +252,16 @@ curl http://localhost:3583/agents/hello/session-xyz \
   -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.
+Agent instances own sandbox state such as files written during a run. Harnesses group related session state within an instance. Sessions persist message history and conversation metadata inside a harness. 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.
+In production, generate a stable URL `<id>` for the agent instance you want to preserve. Use `harness.session(threadName)` when you need multiple conversations inside the same harness.
 
 ### 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 session = await harness.session();
 
 const research = await session.task('Research the auth flow and summarize the key files.', {
   cwd: '/workspace/project',
@@ -271,11 +273,11 @@ const answer = await session.prompt(
 );
 ```
 
-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.
+Roles can be set at the harness, session, or call level. Precedence is `call role > session role > harness 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' });
+const harness = await init({ model: 'anthropic/claude-sonnet-4-6', role: 'coder' });
+const session = await harness.session('review-thread', { role: 'reviewer' });
 
 await session.prompt('Review the latest changes.'); // uses reviewer
 await session.task('Research related issues.', { role: 'researcher' }); // uses researcher
@@ -288,25 +290,25 @@ 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.
+Configure these settings in `app.ts` instead of mutating global model state. They
+apply to every harness and session that resolves models through that provider.
 
 ```ts
-const agent = await init({
-  model: 'anthropic/claude-sonnet-4-6',
-  providers: {
-    anthropic: {
+// .flue/app.ts
+import { configureProvider, flue } from '@flue/sdk/app';
+
+export default {
+  fetch(req, env, ctx) {
+    configureProvider('anthropic', {
       baseUrl: env.ANTHROPIC_BASE_URL,
-      headers: {
-        'X-Custom-Auth': env.GATEWAY_KEY,
-      },
+      headers: { 'X-Custom-Auth': env.GATEWAY_KEY },
       // Use this when the proxy expects a synthetic or gateway-specific key.
       apiKey: 'dummy',
-    },
+    });
+
+    return flue().fetch(req, env, ctx);
   },
-});
+};
 ```
 
 ### Custom Virtual Sandboxes
@@ -318,11 +320,11 @@ import { Bash, InMemoryFs } from 'just-bash';
 
 const fs = new InMemoryFs();
 
-const agent = await init({
+const harness = await init({
   sandbox: () => new Bash({ fs, cwd: '/workspace', python: true }),
   model: 'anthropic/claude-sonnet-4-6',
 });
-const session = await agent.session();
+const session = await harness.session();
 ```
 
 ## Connectors

package/dist/app.d.mts

@@ -1,5 +1,5 @@
-import { w as ProviderSettings } from "./types-BAmV4f3Q.mjs";
-import { i as flue } from "./flue-app-CG8i4wNG.mjs";
+import { w as ProviderSettings } from "./types-Cdcq_ET2.mjs";
+import { i as flue } from "./flue-app-O4_iqLkn.mjs";
 import { t as CLOUDFLARE_AI_BINDING_API } from "./cloudflare-model-BeiZ1pLz.mjs";
 import { Api, Model, registerApiProvider as registerApiProvider$1 } from "@mariozechner/pi-ai";
 

package/dist/app.mjs

@@ -1,4 +1,4 @@
-import { r as flue } from "./flue-app-DeTOZjPs.mjs";
-import { a as registerApiProvider, o as registerProvider, t as configureProvider } from "./providers-DeFRIwp0.mjs";
+import { r as flue } from "./flue-app-SjL4I83Y.mjs";
+import { a as registerApiProvider, o as registerProvider, t as configureProvider } from "./providers-BjEEoKLy.mjs";
 
 export { configureProvider, flue, registerApiProvider, registerProvider };

package/dist/client.d.mts

@@ -1,10 +1,11 @@
-import { A as SessionStore, C as PromptUsage, D as SessionData, E as SandboxFactory, F as TaskOptions, I as ThinkingLevel, L as ToolDef, M as ShellResult, O as SessionEnv, P as SkillOptions, R as ToolParameters, S as PromptResultResponse, _ as FlueSessions, a as BashLike, b as PromptOptions, d as FlueAgent, f as FlueContext, g as FlueSession, h as FlueFs, i as BashFactory, j as ShellOptions, k as SessionOptions, m as FlueEventCallback, p as FlueEvent, r as AgentInit, t as AgentConfig, u as FileStat, v as ModelConfig, w as ProviderSettings, x as PromptResponse, y as PromptModel } from "./types-BAmV4f3Q.mjs";
-import { i as connectMcpServer, n as McpServerOptions, r as McpTransport, t as McpServerConnection } from "./mcp-C3UBXVkR.mjs";
+import { A as SessionStore, C as PromptUsage, D as SessionData, E as SandboxFactory, F as TaskOptions, I as ThinkingLevel, L as ToolDef, M as ShellResult, O as SessionEnv, P as SkillOptions, R as ToolParameters, S as PromptResultResponse, _ as FlueSessions, a as BashLike, b as PromptOptions, d as FlueContext, f as FlueEvent, g as FlueSession, h as FlueHarness, i as BashFactory, j as ShellOptions, k as SessionOptions, m as FlueFs, p as FlueEventCallback, r as AgentInit, t as AgentConfig, u as FileStat, v as ModelConfig, w as ProviderSettings, x as PromptResponse, y as PromptModel } from "./types-Cdcq_ET2.mjs";
+import { i as connectMcpServer, n as McpServerOptions, r as McpTransport, t as McpServerConnection } from "./mcp-BfcWmA-A.mjs";
 import { Type } from "@mariozechner/pi-ai";
 
 //#region src/client.d.ts
 interface FlueContextConfig {
   id: string;
+  runId: string;
   payload: any;
   env: Record<string, any>;
   agentConfig: AgentConfig;
@@ -25,8 +26,11 @@ interface FlueContextConfig {
 }
 /** Extends FlueContext with server-only methods. Agent handlers only see FlueContext. */
 interface FlueContextInternal extends FlueContext {
+  /** Decorate and dispatch an event, returning the decorated event. */
+  emitEvent(event: FlueEvent): FlueEvent;
+  subscribeEvent(callback: FlueEventCallback): () => void;
   setEventCallback(callback: FlueEventCallback | undefined): void;
 }
 declare function createFlueContext(config: FlueContextConfig): FlueContextInternal;
 //#endregion
-export { type AgentInit, type BashFactory, type BashLike, type FileStat, type FlueAgent, type FlueContext, FlueContextConfig, FlueContextInternal, type FlueEvent, type FlueEventCallback, type FlueFs, type FlueSession, type FlueSessions, type McpServerConnection, type McpServerOptions, type McpTransport, type ModelConfig, type PromptModel, type PromptOptions, type PromptResponse, type PromptResultResponse, type PromptUsage, type ProviderSettings, type SandboxFactory, type SessionData, type SessionEnv, type SessionOptions, type SessionStore, type ShellOptions, type ShellResult, type SkillOptions, type TaskOptions, type ThinkingLevel, type ToolDef, type ToolParameters, Type, connectMcpServer, createFlueContext };
+export { type AgentInit, type BashFactory, type BashLike, type FileStat, type FlueContext, FlueContextConfig, FlueContextInternal, type FlueEvent, type FlueEventCallback, type FlueFs, type FlueHarness, type FlueSession, type FlueSessions, type McpServerConnection, type McpServerOptions, type McpTransport, type ModelConfig, type PromptModel, type PromptOptions, type PromptResponse, type PromptResultResponse, type PromptUsage, type ProviderSettings, type SandboxFactory, type SessionData, type SessionEnv, type SessionOptions, type SessionStore, type ShellOptions, type ShellResult, type SkillOptions, type TaskOptions, type ThinkingLevel, type ToolDef, type ToolParameters, Type, connectMcpServer, createFlueContext };

package/dist/client.mjs

@@ -1,18 +1,39 @@
 import { u as discoverSessionContext } from "./result-K1IRhWKM.mjs";
-import "./providers-DeFRIwp0.mjs";
-import { a as assertRoleExists } from "./session-CFOByKnM.mjs";
+import "./providers-BjEEoKLy.mjs";
+import { a as assertRoleExists } from "./session-CRFfAJDq.mjs";
 import { bashFactoryToSessionEnv, createCwdSessionEnv } from "./sandbox.mjs";
-import { n as AgentClient, t as connectMcpServer } from "./mcp-DM6yv_Qc.mjs";
+import { n as Harness, t as connectMcpServer } from "./mcp-DwLSoSxp.mjs";
 import { Type } from "@mariozechner/pi-ai";
 
 //#region src/client.ts
 function createFlueContext(config) {
-	let currentEventCallback;
-	const initializedAgentIds = /* @__PURE__ */ new Set();
-	return {
+	const subscribers = /* @__PURE__ */ new Set();
+	let handlerUnsubscribe;
+	let eventIndex = 0;
+	const initializedHarnessNames = /* @__PURE__ */ new Set();
+	const emitEvent = (event) => {
+		const decorated = {
+			...event,
+			runId: config.runId,
+			eventIndex: eventIndex++,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		for (const subscriber of subscribers) try {
+			Promise.resolve(subscriber(decorated)).catch((error) => {
+				console.error("[flue:subscriber] Event subscriber failed:", error);
+			});
+		} catch (error) {
+			console.error("[flue:subscriber] Event subscriber failed:", error);
+		}
+		return decorated;
+	};
+	const ctx = {
 		get id() {
 			return config.id;
 		},
+		get runId() {
+			return config.runId;
+		},
 		get payload() {
 			return config.payload;
 		},
@@ -22,37 +43,88 @@ function createFlueContext(config) {
 		get req() {
 			return config.req;
 		},
+		log: {
+			info(message, attributes) {
+				emitEvent({
+					type: "log",
+					level: "info",
+					message,
+					attributes: normalizeLogAttributes(attributes)
+				});
+			},
+			warn(message, attributes) {
+				emitEvent({
+					type: "log",
+					level: "warn",
+					message,
+					attributes: normalizeLogAttributes(attributes)
+				});
+			},
+			error(message, attributes) {
+				emitEvent({
+					type: "log",
+					level: "error",
+					message,
+					attributes: normalizeLogAttributes(attributes)
+				});
+			}
+		},
 		async init(options) {
 			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);
+			const name = options.name ?? "default";
+			if (initializedHarnessNames.has(name)) throw new Error(`[flue] init() has already been called with name "${name}" in this request.`);
+			initializedHarnessNames.add(name);
 			try {
 				assertRoleExists(config.agentConfig.roles, options.role);
 				const sandbox = options.sandbox;
-				const baseEnv = await resolveSessionEnv(id, sandbox, config, options.cwd);
+				const baseEnv = await resolveSessionEnv(config.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 = config.agentConfig.resolveModel(options.model);
-				return new AgentClient(id, {
+				const agentConfig = {
 					...config.agentConfig,
 					systemPrompt: localContext.systemPrompt,
 					skills: localContext.skills,
 					model: agentModel,
 					role: options.role ?? config.agentConfig.role,
 					thinkingLevel: options.thinkingLevel ?? config.agentConfig.thinkingLevel
-				}, env, store, currentEventCallback, options.tools);
+				};
+				return new Harness(config.id, name, agentConfig, env, store, (event) => {
+					emitEvent(event);
+				}, options.tools);
 			} catch (error) {
-				initializedAgentIds.delete(id);
+				initializedHarnessNames.delete(name);
 				throw error;
 			}
 		},
+		emitEvent,
+		subscribeEvent(callback) {
+			subscribers.add(callback);
+			return () => subscribers.delete(callback);
+		},
 		setEventCallback(callback) {
-			currentEventCallback = callback;
+			handlerUnsubscribe?.();
+			handlerUnsubscribe = callback ? ctx.subscribeEvent(callback) : void 0;
 		}
 	};
+	return ctx;
+}
+function normalizeLogAttributes(attributes) {
+	if (!attributes) return void 0;
+	if (!(attributes.error instanceof Error)) return attributes;
+	return {
+		...attributes,
+		error: serializeLogError(attributes.error)
+	};
+}
+function serializeLogError(error) {
+	return {
+		name: error.name,
+		message: error.message,
+		stack: error.stack
+	};
 }
 /** Duck-type detection for just-bash Bash instances. */
 function isBashLike(value) {

package/dist/cloudflare/index.d.mts

@@ -1,4 +1,4 @@
-import { A as SessionStore, O as SessionEnv } from "../types-BAmV4f3Q.mjs";
+import { A as SessionStore, O as SessionEnv } from "../types-Cdcq_ET2.mjs";
 import { n as CloudflareAIBindingApi } from "../cloudflare-model-BeiZ1pLz.mjs";
 import { ApiProvider, StreamOptions } from "@mariozechner/pi-ai";
 

package/dist/cloudflare/index.mjs

@@ -1,7 +1,7 @@
 import "../result-K1IRhWKM.mjs";
-import { c as CLOUDFLARE_AI_BINDING_API, n as getModelBinding } from "../providers-DeFRIwp0.mjs";
+import { c as CLOUDFLARE_AI_BINDING_API, n as getModelBinding } from "../providers-BjEEoKLy.mjs";
 import { t as abortErrorFor } from "../abort-Bg3qsAkU.mjs";
-import "../session-CFOByKnM.mjs";
+import "../session-CRFfAJDq.mjs";
 import { createSandboxSessionEnv } from "../sandbox.mjs";
 import { createAssistantMessageEventStream, parseStreamingJson } from "@mariozechner/pi-ai";
 import { Workspace, WorkspaceFileSystem } from "@cloudflare/shell";

package/dist/{flue-app-CG8i4wNG.d.mts → flue-app-O4_iqLkn.d.mts}

@@ -1,6 +1,58 @@
+import { f as FlueEvent } from "./types-Cdcq_ET2.mjs";
 import { FlueContextInternal } from "./client.mjs";
 import { Hono } from "hono";
 
+//#region src/runtime/run-store.d.ts
+type RunStatus = 'active' | 'completed' | 'errored';
+interface RunRecord {
+  runId: string;
+  instanceId: string;
+  agentName: string;
+  status: RunStatus;
+  startedAt: string;
+  endedAt?: string;
+  isError?: boolean;
+  durationMs?: number;
+  result?: unknown;
+  error?: unknown;
+}
+interface CreateRunInput {
+  runId: string;
+  instanceId: string;
+  agentName: string;
+  startedAt: string;
+  payload: unknown;
+}
+interface EndRunInput {
+  runId: string;
+  endedAt: string;
+  isError: boolean;
+  durationMs: number;
+  result?: unknown;
+  error?: unknown;
+}
+interface RunStore {
+  createRun(input: CreateRunInput): Promise<void>;
+  endRun(input: EndRunInput): Promise<void>;
+  appendEvent(runId: string, event: FlueEvent): Promise<void>;
+  getEvents(runId: string, fromIndex?: number): Promise<FlueEvent[]>;
+  getRun(runId: string): Promise<RunRecord | null>;
+}
+interface RunStoreOptions {
+  maxCompletedRuns?: number;
+  maxEventBytes?: number;
+}
+//#endregion
+//#region src/runtime/run-subscribers.d.ts
+type RunSubscriberListener = (event: FlueEvent) => void;
+interface RunSubscriberRegistry {
+  subscribe(runId: string, listener: RunSubscriberListener): () => void;
+  publish(runId: string, event: FlueEvent): void;
+  /** Release registry state for a terminal run. */
+  complete(runId: string): void;
+}
+declare function createRunSubscriberRegistry(): RunSubscriberRegistry;
+//#endregion
 //#region src/runtime/handle-agent.d.ts
 /**
  * Agent handler signature — the default export of a `.flue/agents/<name>.ts`
@@ -13,18 +65,18 @@ type AgentHandler = (ctx: FlueContextInternal) => unknown | Promise<unknown>;
  *   - Node: env=process.env, defaultStore=in-memory, no resolveSandbox.
  *   - Cloudflare: env=DO env, defaultStore=DO SQLite, resolveSandbox=cfSandboxToSessionEnv.
  */
-type CreateContextFn = (id: string, payload: unknown, request: Request) => FlueContextInternal;
+type CreateContextFn = (id: string, runId: string, payload: unknown, request: Request) => FlueContextInternal;
 /**
  * Webhook execution wrapper. Receives the prepared run callback and returns
  * a promise that resolves with the handler's return value. Implementations:
  *
  *   - Node: just `run()` — no fiber, no DO.
- *   - Cloudflare: `doInstance.runFiber('flue:webhook:<requestId>', run)`.
+ *   - Cloudflare: `doInstance.runFiber('flue:webhook:<runId>', run)`.
  *
  * The caller is responsible for any logging on completion/error; this routine
  * just kicks it off and returns the 202.
  */
-type StartWebhookFn = (requestId: string, run: () => Promise<unknown>) => Promise<unknown>;
+type StartWebhookFn = (runId: string, run: () => Promise<unknown>) => Promise<unknown>;
 /**
  * Foreground handler execution wrapper. Wraps the call to `handler(ctx)` so
  * targets can layer in keepalive / context propagation. Defaults to direct
@@ -61,6 +113,15 @@ interface HandleAgentOptions {
    * mid-stream.
    */
   runHandler?: RunHandlerFn;
+  /** Per-target run history store. If omitted, run persistence is disabled. */
+  runStore?: RunStore;
+  /**
+   * Per-target in-process subscriber registry used by the run-stream
+   * route to live-tail an active run. Optional — if omitted, the run
+   * still produces events and is persisted, but live-tail subscribers
+   * see only what's already in the store at the moment they connect.
+   */
+  runSubscribers?: RunSubscriberRegistry;
 }
 /**
  * Dispatch a single `/agents/:name/:id` request. The mode is chosen by
@@ -125,6 +186,10 @@ interface FlueRuntime {
   startWebhook?: StartWebhookFn;
   /** Optional Node foreground handler wrapper. Defaults to direct invocation. */
   runHandler?: RunHandlerFn;
+  /** Node run history store. */
+  runStore?: RunStore;
+  /** Node in-process registry used for live run-stream tailing. */
+  runSubscribers?: RunSubscriberRegistry;
   /**
    * Forward an incoming request to the per-agent Durable Object via
    * Cloudflare's Agents SDK. Required when {@link target} is `'cloudflare'`.
@@ -181,4 +246,4 @@ declare function flue(): Hono;
  */
 declare function createDefaultFlueApp(): Hono;
 //#endregion
-export { AgentHandler as a, RunHandlerFn as c, flue as i, StartWebhookFn as l, configureFlueRuntime as n, CreateContextFn as o, createDefaultFlueApp as r, HandleAgentOptions as s, FlueRuntime as t, handleAgentRequest as u };
+export { RunStatus as _, AgentHandler as a, RunHandlerFn as c, RunSubscriberListener as d, RunSubscriberRegistry as f, RunRecord as g, EndRunInput as h, flue as i, StartWebhookFn as l, CreateRunInput as m, configureFlueRuntime as n, CreateContextFn as o, createRunSubscriberRegistry as p, createDefaultFlueApp as r, HandleAgentOptions as s, FlueRuntime as t, handleAgentRequest as u, RunStore as v, RunStoreOptions as y };