@flue/sdk 0.2.0 → 0.3.1

package/dist/{session-CiAMTsLZ.mjs → session-DukL3zwF.mjs}

@@ -1,4 +1,4 @@
-import { i as loadSkillByPath, n as createTools, r as discoverSessionContext, t as BUILTIN_TOOL_NAMES } from "./agent-BYG0nVbQ.mjs";
+import { i as loadSkillByPath, n as createTools, t as BUILTIN_TOOL_NAMES } from "./agent-BB4lwAd5.mjs";
 import { completeSimple, isContextOverflow } from "@mariozechner/pi-ai";
 import { Agent } from "@mariozechner/pi-agent-core";
 import { toJsonSchema } from "@valibot/to-json-schema";
@@ -384,16 +384,6 @@ async function compact(preparation, model, apiKey, signal) {
 		}
 	};
 }
-function buildCompactedMessages(messages, result) {
-	return [{
-		role: "user",
-		content: [{
-			type: "text",
-			text: `[Context Summary]\n\n${result.summary}`
-		}],
-		timestamp: Date.now()
-	}, ...messages.slice(result.firstKeptIndex)];
-}
 
 //#endregion
 //#region src/result.ts
@@ -478,9 +468,206 @@ var ResultExtractionError = class extends Error {
 	}
 };
 
+//#endregion
+//#region src/env-utils.ts
+async function createScopedEnv(env, commands) {
+	if (env.scope) return env.scope({ commands });
+	if (commands.length > 0) throw new Error("[flue] Cannot use commands: this environment does not support scoped command execution. Commands are only available in BashFactory sandbox mode. Remote sandboxes handle command execution at the platform level.");
+	return env;
+}
+function mergeCommands(defaults, perCall) {
+	if (!perCall || perCall.length === 0) return defaults;
+	if (defaults.length === 0) return perCall;
+	const byName = /* @__PURE__ */ new Map();
+	for (const cmd of defaults) byName.set(cmd.name, cmd);
+	for (const cmd of perCall) byName.set(cmd.name, cmd);
+	return Array.from(byName.values());
+}
+
+//#endregion
+//#region src/roles.ts
+function assertRoleExists(roles, roleName) {
+	if (!roleName) return;
+	if (roles[roleName]) return;
+	const available = Object.keys(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/\`.`);
+}
+function resolveEffectiveRole(options) {
+	const role = options.callRole ?? options.sessionRole ?? options.agentRole;
+	assertRoleExists(options.roles, role);
+	return role;
+}
+function resolveRoleModel(roles, roleName) {
+	assertRoleExists(roles, roleName);
+	return roleName ? roles[roleName]?.model : void 0;
+}
+
+//#endregion
+//#region src/session-history.ts
+var SessionHistory = class SessionHistory {
+	entries;
+	byId;
+	leafId;
+	constructor(entries, leafId) {
+		this.entries = [...entries];
+		this.leafId = leafId;
+		this.byId = new Map(this.entries.map((entry) => [entry.id, entry]));
+	}
+	static empty() {
+		return new SessionHistory([], null);
+	}
+	static fromData(data) {
+		if (!data) return SessionHistory.empty();
+		return new SessionHistory(data.entries, data.leafId);
+	}
+	getLeafId() {
+		return this.leafId;
+	}
+	getActivePath() {
+		const path = [];
+		let current = this.leafId ? this.byId.get(this.leafId) : void 0;
+		while (current) {
+			path.push(current);
+			current = current.parentId ? this.byId.get(current.parentId) : void 0;
+		}
+		return path.reverse();
+	}
+	buildContextEntries() {
+		const path = this.getActivePath();
+		const latestCompactionIndex = findLatestCompactionIndex(path);
+		if (latestCompactionIndex === -1) return pathToContextEntries(path);
+		const compaction = path[latestCompactionIndex];
+		const firstKeptIndex = path.findIndex((entry) => entry.id === compaction.firstKeptEntryId);
+		const keptStart = firstKeptIndex >= 0 ? firstKeptIndex : latestCompactionIndex + 1;
+		const context = [{
+			message: createContextSummaryMessage(compaction.summary, compaction.timestamp),
+			entry: compaction
+		}];
+		context.push(...pathToContextEntries(path.slice(keptStart, latestCompactionIndex)));
+		context.push(...pathToContextEntries(path.slice(latestCompactionIndex + 1)));
+		return context;
+	}
+	buildContext() {
+		return this.buildContextEntries().map((entry) => entry.message);
+	}
+	getLatestCompaction() {
+		const path = this.getActivePath();
+		for (let i = path.length - 1; i >= 0; i--) {
+			const entry = path[i];
+			if (entry.type === "compaction") return entry;
+		}
+	}
+	appendMessage(message, source) {
+		const entry = {
+			type: "message",
+			id: generateEntryId(this.byId),
+			parentId: this.leafId,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			message,
+			source
+		};
+		this.appendEntry(entry);
+		return entry.id;
+	}
+	appendMessages(messages, source) {
+		return messages.map((message) => this.appendMessage(message, source));
+	}
+	appendCompaction(input) {
+		if (!this.byId.has(input.firstKeptEntryId)) throw new Error(`[flue] Cannot compact: entry "${input.firstKeptEntryId}" does not exist.`);
+		const entry = {
+			type: "compaction",
+			id: generateEntryId(this.byId),
+			parentId: this.leafId,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			summary: input.summary,
+			firstKeptEntryId: input.firstKeptEntryId,
+			tokensBefore: input.tokensBefore,
+			details: input.details
+		};
+		this.appendEntry(entry);
+		return entry.id;
+	}
+	appendBranchSummary(summary, fromId, details) {
+		const entry = {
+			type: "branch_summary",
+			id: generateEntryId(this.byId),
+			parentId: this.leafId,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			fromId,
+			summary,
+			details
+		};
+		this.appendEntry(entry);
+		return entry.id;
+	}
+	removeLeafMessage(message) {
+		if (!this.leafId) return false;
+		const leaf = this.byId.get(this.leafId);
+		if (!leaf || leaf.type !== "message" || leaf.message !== message) return false;
+		this.byId.delete(leaf.id);
+		this.entries = this.entries.filter((entry) => entry.id !== leaf.id);
+		this.leafId = leaf.parentId;
+		return true;
+	}
+	toData(metadata, createdAt, updatedAt) {
+		return {
+			version: 2,
+			entries: [...this.entries],
+			leafId: this.leafId,
+			metadata,
+			createdAt,
+			updatedAt
+		};
+	}
+	appendEntry(entry) {
+		this.entries.push(entry);
+		this.byId.set(entry.id, entry);
+		this.leafId = entry.id;
+	}
+};
+function pathToContextEntries(path) {
+	const context = [];
+	for (const entry of path) if (entry.type === "message") context.push({
+		message: entry.message,
+		entry
+	});
+	else if (entry.type === "branch_summary") context.push({
+		message: createUserContextMessage(`[Branch Summary]\n\n${entry.summary}`, entry.timestamp),
+		entry
+	});
+	return context;
+}
+function findLatestCompactionIndex(path) {
+	for (let i = path.length - 1; i >= 0; i--) if (path[i].type === "compaction") return i;
+	return -1;
+}
+function createContextSummaryMessage(summary, timestamp) {
+	return createUserContextMessage(summary.startsWith("[Context Summary]") ? summary : `[Context Summary]\n\n${summary}`, timestamp);
+}
+function createUserContextMessage(text, timestamp) {
+	return {
+		role: "user",
+		content: [{
+			type: "text",
+			text
+		}],
+		timestamp: new Date(timestamp).getTime()
+	};
+}
+function generateEntryId(byId) {
+	for (let i = 0; i < 100; i++) {
+		const id = crypto.randomUUID().slice(0, 8);
+		if (!byId.has(id)) return id;
+	}
+	return crypto.randomUUID();
+}
+
 //#endregion
 //#region src/session.ts
 /** Internal session implementation. Not exported publicly — wrapped by FlueSession. */
+const MAX_SHELL_HISTORY_CHARS = 50 * 1024;
+const MAX_TASK_DEPTH = 4;
 /** In-memory session store. Sessions persist for the lifetime of the process. */
 var InMemorySessionStore = class {
 	store = /* @__PURE__ */ new Map();
@@ -494,66 +681,83 @@ var InMemorySessionStore = class {
 		this.store.delete(id);
 	}
 };
-var Session = class Session {
+var Session = class {
 	id;
 	metadata;
-	agent;
+	get role() {
+		return this.sessionRole;
+	}
+	harness;
+	storageKey;
 	config;
 	env;
 	store;
+	history;
 	createdAt;
 	compactionSettings;
-	lastCompaction;
 	overflowRecoveryAttempted = false;
 	compactionAbortController;
 	eventCallback;
-	builtinTools;
-	sessionCommands;
-	constructor(id, config, env, store, existingData, onAgentEvent, sessionCommands) {
-		this.id = id;
-		this.config = config;
-		this.env = env;
-		this.store = store;
-		this.sessionCommands = sessionCommands ?? [];
-		this.metadata = existingData?.metadata ?? {};
-		this.createdAt = existingData?.createdAt;
-		this.lastCompaction = existingData?.lastCompaction;
-		const cc = config.compaction;
+	agentCommands;
+	agentTools;
+	deleted = false;
+	activeOperation;
+	activeTasks = /* @__PURE__ */ new Set();
+	sessionRole;
+	taskDepth;
+	createTaskSession;
+	onDelete;
+	constructor(options) {
+		this.id = options.id;
+		this.storageKey = options.storageKey;
+		this.config = options.config;
+		this.env = options.env;
+		this.store = options.store;
+		this.agentCommands = options.agentCommands ?? [];
+		this.agentTools = options.agentTools ?? [];
+		this.sessionRole = options.sessionRole;
+		this.taskDepth = options.taskDepth ?? 0;
+		this.createTaskSession = options.createTaskSession;
+		this.onDelete = options.onDelete;
+		this.metadata = options.existingData?.metadata ?? {};
+		this.createdAt = options.existingData?.createdAt;
+		this.history = SessionHistory.fromData(options.existingData);
+		const cc = this.config.compaction;
 		this.compactionSettings = {
 			enabled: cc?.enabled ?? DEFAULT_COMPACTION_SETTINGS.enabled,
 			reserveTokens: cc?.reserveTokens ?? DEFAULT_COMPACTION_SETTINGS.reserveTokens,
 			keepRecentTokens: cc?.keepRecentTokens ?? DEFAULT_COMPACTION_SETTINGS.keepRecentTokens
 		};
-		const systemPrompt = config.systemPrompt;
-		const tools = createTools(env);
-		this.builtinTools = tools;
-		const previousMessages = existingData?.messages ?? [];
-		this.agent = new Agent({
+		const systemPrompt = this.config.systemPrompt;
+		assertRoleExists(this.config.roles, this.config.role);
+		assertRoleExists(this.config.roles, this.sessionRole);
+		const tools = [...this.createBuiltinTools(this.env, this.agentCommands, []), ...this.createCustomTools(this.agentTools)];
+		const previousMessages = this.history.buildContext();
+		this.harness = new Agent({
 			initialState: {
 				systemPrompt,
-				model: config.model,
+				model: this.config.model,
 				tools,
 				messages: previousMessages
 			},
 			toolExecution: "parallel"
 		});
-		this.eventCallback = onAgentEvent;
-		const emit = onAgentEvent;
-		this.agent.subscribe(async (event) => {
+		this.eventCallback = options.onAgentEvent;
+		this.harness.subscribe(async (event) => {
 			switch (event.type) {
 				case "agent_start":
-					emit?.({ type: "agent_start" });
+					this.emit({ type: "agent_start" });
 					break;
 				case "message_update": {
 					const aEvent = event.assistantMessageEvent;
-					if (aEvent.type === "text_delta") emit?.({
+					if (aEvent.type === "text_delta") this.emit({
 						type: "text_delta",
 						text: aEvent.delta
 					});
 					break;
 				}
 				case "tool_execution_start":
-					emit?.({
+					this.emit({
 						type: "tool_start",
 						toolName: event.toolName,
 						toolCallId: event.toolCallId,
@@ -561,7 +765,7 @@ var Session = class Session {
 					});
 					break;
 				case "tool_execution_end":
-					emit?.({
+					this.emit({
 						type: "tool_end",
 						toolName: event.toolName,
 						toolCallId: event.toolCallId,
@@ -570,159 +774,124 @@ var Session = class Session {
 					});
 					break;
 				case "turn_end":
-					emit?.({ type: "turn_end" });
+					this.emit({ type: "turn_end" });
 					break;
-				case "agent_end": {
-					const messages = this.agent.state.messages;
-					const lastMsg = messages[messages.length - 1];
-					if (lastMsg?.role === "assistant") await this.checkCompaction(lastMsg);
-					emit?.({ type: "done" });
-					break;
-				}
+				case "agent_end": break;
 			}
 		});
 	}
 	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;
-		const fullPrompt = buildPromptText(promptWithRole, schema);
-		const effectiveCommands = this.mergeCommands(options?.commands);
-		if (effectiveCommands.length > 0) this.assertCommandSupport(effectiveCommands);
-		const registeredCommandNames = this.registerCommands(effectiveCommands);
-		const registeredToolNames = options?.tools ? this.registerCustomTools(options.tools) : [];
-		try {
-			await this.agent.prompt(fullPrompt);
-			await this.agent.waitForIdle();
-			this.throwIfError("prompt");
-			await this.save();
-			if (schema) return this.extractResultWithRetry(schema);
-			return { text: this.getAssistantText() };
-		} finally {
-			this.unregisterCommands(registeredCommandNames);
-			if (registeredToolNames.length > 0) this.unregisterCustomTools();
-		}
+		return this.runOperation("prompt", async () => {
+			const role = this.resolveEffectiveRole(options?.role);
+			const schema = options?.result;
+			const fullPrompt = buildPromptText(text, schema);
+			const effectiveCommands = mergeCommands(this.agentCommands, options?.commands);
+			return this.withScopedRuntime({
+				commands: effectiveCommands,
+				tools: options?.tools ?? [],
+				role,
+				model: options?.model,
+				callSite: "this prompt() call"
+			}, async () => {
+				const beforeLength = this.harness.state.messages.length;
+				await this.harness.prompt(fullPrompt);
+				await this.harness.waitForIdle();
+				await this.syncHarnessMessagesSince(beforeLength, "prompt");
+				await this.checkLatestAssistantForCompaction();
+				this.throwIfError("prompt");
+				if (schema) return this.extractResultWithRetry(schema);
+				return { text: this.getAssistantText() };
+			});
+		});
 	}
 	async skill(name, options) {
-		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);
-		const promptWithRole = this.injectRoleInstructions(skillPrompt, options?.role);
-		const effectiveCommands = this.mergeCommands(options?.commands);
-		if (effectiveCommands.length > 0) this.assertCommandSupport(effectiveCommands);
-		const registeredCommandNames = this.registerCommands(effectiveCommands);
-		const registeredToolNames = options?.tools ? this.registerCustomTools(options.tools) : [];
-		try {
-			await this.agent.prompt(promptWithRole);
-			await this.agent.waitForIdle();
-			this.throwIfError(`skill("${name}")`);
-			await this.save();
-			if (schema) return this.extractResultWithRetry(schema);
-			return { text: this.getAssistantText() };
-		} finally {
-			this.unregisterCommands(registeredCommandNames);
-			if (registeredToolNames.length > 0) this.unregisterCustomTools();
-		}
+		return this.runOperation("skill", async () => {
+			const role = this.resolveEffectiveRole(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").`);
+			}
+			const schema = options?.result;
+			const skillPrompt = buildSkillPrompt(registeredSkill.instructions, options?.args, schema);
+			const effectiveCommands = mergeCommands(this.agentCommands, options?.commands);
+			return this.withScopedRuntime({
+				commands: effectiveCommands,
+				tools: options?.tools ?? [],
+				role,
+				model: options?.model,
+				callSite: `this skill("${name}") call`
+			}, async () => {
+				const beforeLength = this.harness.state.messages.length;
+				await this.harness.prompt(skillPrompt);
+				await this.harness.waitForIdle();
+				await this.syncHarnessMessagesSince(beforeLength, "skill");
+				await this.checkLatestAssistantForCompaction();
+				this.throwIfError(`skill("${name}")`);
+				if (schema) return this.extractResultWithRetry(schema);
+				return { text: this.getAssistantText() };
+			});
+		});
+	}
+	async task(text, options) {
+		return (await this.runTask(text, options, void 0)).output;
 	}
 	async shell(command, options) {
-		const effectiveCommands = this.mergeCommands(options?.commands);
-		if (effectiveCommands.length > 0) this.assertCommandSupport(effectiveCommands);
-		const registeredNames = this.registerCommands(effectiveCommands);
-		try {
-			const result = await this.env.exec(command, {
+		return this.runOperation("shell", async () => {
+			const effectiveCommands = mergeCommands(this.agentCommands, options?.commands);
+			const result = await (await createScopedEnv(this.env, effectiveCommands)).exec(command, {
 				env: options?.env,
 				cwd: options?.cwd
 			});
-			return {
+			const shellResult = {
 				stdout: result.stdout,
 				stderr: result.stderr,
 				exitCode: result.exitCode
 			};
-		} finally {
-			this.unregisterCommands(registeredNames);
-		}
-	}
-	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) {
-			if (p.startsWith("/")) return normalizePath(p);
-			if (taskCwd === "/") return normalizePath("/" + p);
-			return normalizePath(taskCwd + "/" + p);
-		}
-		const parentEnv = this.env;
-		const taskEnv = {
-			exec: (cmd, opts) => parentEnv.exec(cmd, {
-				cwd: opts?.cwd ?? taskCwd,
-				env: opts?.env
-			}),
-			readFile: (p) => parentEnv.readFile(taskResolvePath(p)),
-			readFileBuffer: (p) => parentEnv.readFileBuffer(taskResolvePath(p)),
-			writeFile: (p, c) => parentEnv.writeFile(taskResolvePath(p), c),
-			stat: (p) => parentEnv.stat(taskResolvePath(p)),
-			readdir: (p) => parentEnv.readdir(taskResolvePath(p)),
-			exists: (p) => parentEnv.exists(taskResolvePath(p)),
-			mkdir: (p, o) => parentEnv.mkdir(taskResolvePath(p), o),
-			rm: (p, o) => parentEnv.rm(taskResolvePath(p), o),
-			cwd: taskCwd,
-			resolvePath: taskResolvePath,
-			commandSupport: parentEnv.commandSupport,
-			cleanup: async () => {}
-		};
-		const localContext = await discoverSessionContext(taskEnv);
-		let taskModel = this.config.model;
-		const taskRole = options?.role ? this.config.roles[options.role] : void 0;
-		if (taskRole?.model && this.config.resolveModel) taskModel = this.config.resolveModel(taskRole.model);
-		if (options?.model && this.config.resolveModel) taskModel = this.config.resolveModel(options.model);
-		const taskConfig = {
-			systemPrompt: localContext.systemPrompt,
-			skills: localContext.skills,
-			roles: this.config.roles,
-			model: this.requireModel(taskModel, "this task() call"),
-			resolveModel: this.config.resolveModel,
-			compaction: this.config.compaction
-		};
-		this.eventCallback?.({
-			type: "task_start",
-			workspace: taskCwd
+			const message = this.createShellMessage(command, shellResult, options);
+			this.history.appendMessage(message, "shell");
+			this.harness.state.messages = this.history.buildContext();
+			await this.save();
+			return shellResult;
 		});
-		const taskStore = new InMemorySessionStore();
-		const taskSession = new Session(`${this.id}:task:${Date.now()}`, taskConfig, taskEnv, taskStore, null, this.eventCallback);
-		try {
-			const promptOpts = { role: options?.role };
-			if (options?.result) promptOpts.result = options.result;
-			return await taskSession.prompt(prompt, promptOpts);
-		} finally {
-			this.eventCallback?.({ type: "task_end" });
-			await taskSession.destroy();
-		}
 	}
 	abort() {
-		this.agent.abort();
+		this.harness.abort();
+		this.compactionAbortController?.abort();
+		for (const task of this.activeTasks) task.abort();
+	}
+	close() {
+		if (this.deleted) return;
+		this.deleted = true;
+		this.abort();
+		this.onDelete?.();
+	}
+	async delete() {
+		if (this.deleted) return;
+		this.deleted = true;
+		this.abort();
+		await deleteSessionTree(this.store, this.storageKey);
+		this.onDelete?.();
 	}
-	async destroy() {
-		this.agent.abort();
-		await this.store.delete(this.id);
-		await this.env.cleanup();
+	resolveEffectiveRole(callRole) {
+		return resolveEffectiveRole({
+			roles: this.config.roles,
+			agentRole: this.config.role,
+			sessionRole: this.sessionRole,
+			callRole
+		});
 	}
-	/** Precedence: prompt-level > role-level > agent-level default. */
-	resolveModelForCall(promptModel, roleName) {
+	/** Precedence: call-level > role-level > agent-level default. */
+	resolveModelForCall(promptModel, roleName, callSite) {
 		let model = this.config.model;
-		if (roleName && this.config.roles[roleName]?.model && this.config.resolveModel) model = this.config.resolveModel(this.config.roles[roleName].model);
+		const roleModel = resolveRoleModel(this.config.roles, roleName);
+		if (roleModel && this.config.resolveModel) model = this.config.resolveModel(roleModel);
 		if (promptModel && this.config.resolveModel) model = this.config.resolveModel(promptModel);
-		this.agent.state.model = this.requireModel(model, "this prompt()/skill()/task() call");
+		return this.requireModel(model, callSite);
 	}
 	/**
 	* Throws a clear, actionable error when no model is configured for a call.
@@ -731,64 +900,19 @@ var Session = class Session {
 	*/
 	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.`);
+		throw new Error(`[flue] No model configured for ${callSite}. Pass \`{ model: "provider/model-id" }\` to \`init()\` for an agent-wide default, or to this prompt()/skill() call for a one-off override.`);
 	}
-	/**
-	* 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;
+	buildSystemPrompt(roleName) {
+		const parts = [this.config.systemPrompt];
+		if (!roleName) return parts.join("\n\n");
 		const role = this.config.roles[roleName];
-		if (!role) return text;
-		return `<role>\n${role.instructions}\n</role>\n\n${text}`;
-	}
-	assertCommandSupport(commands) {
-		if (commands.length === 0) return;
-		if (!this.env.commandSupport) throw new Error("[flue] Cannot use commands: this environment does not support command registration. Commands are only available in isolate sandbox mode. Remote sandboxes handle command execution at the platform level.");
-	}
-	/**
-	* Merge session-wide `commands` (from init()) with per-call commands. When
-	* both define a command with the same name, the per-call entry wins for
-	* that call.
-	*/
-	mergeCommands(perCall) {
-		if (!perCall || perCall.length === 0) return this.sessionCommands;
-		if (this.sessionCommands.length === 0) return perCall;
-		const byName = /* @__PURE__ */ new Map();
-		for (const cmd of this.sessionCommands) byName.set(cmd.name, cmd);
-		for (const cmd of perCall) byName.set(cmd.name, cmd);
-		return Array.from(byName.values());
-	}
-	registerCommands(commands) {
-		if (!this.env.commandSupport || commands.length === 0) return [];
-		const names = [];
-		for (const cmd of commands) {
-			this.env.commandSupport.register(cmd);
-			names.push(cmd.name);
-		}
-		return names;
-	}
-	unregisterCommands(names) {
-		if (!this.env.commandSupport || names.length === 0) return;
-		for (const name of names) this.env.commandSupport.unregister(name);
+		if (!role) return parts.join("\n\n");
+		parts.push(`<role name="${role.name}">\n${role.instructions}\n</role>`);
+		return parts.filter(Boolean).join("\n\n");
 	}
-	registerCustomTools(tools) {
-		const names = [];
-		for (const toolDef of tools) {
-			if (BUILTIN_TOOL_NAMES.has(toolDef.name)) throw new Error(`[flue] Custom tool "${toolDef.name}" conflicts with a built-in tool. Built-in tools: ${[...BUILTIN_TOOL_NAMES].join(", ")}`);
-			if (names.includes(toolDef.name)) throw new Error(`[flue] Duplicate custom tool name "${toolDef.name}". Tool names must be unique.`);
-			names.push(toolDef.name);
-		}
-		const agentTools = tools.map((toolDef) => ({
+	createCustomTools(tools) {
+		this.validateCustomToolNames(tools);
+		return tools.map((toolDef) => ({
 			name: toolDef.name,
 			label: toolDef.name,
 			description: toolDef.description,
@@ -798,50 +922,241 @@ var Session = class Session {
 				return {
 					content: [{
 						type: "text",
-						text: await toolDef.execute(params)
+						text: await toolDef.execute(params, signal)
 					}],
 					details: { customTool: toolDef.name }
 				};
 			}
 		}));
-		this.agent.state.tools = [...this.agent.state.tools, ...agentTools];
-		return names;
 	}
-	unregisterCustomTools() {
-		this.agent.state.tools = [...this.builtinTools];
+	validateCustomToolNames(tools) {
+		const names = /* @__PURE__ */ new Set();
+		for (const toolDef of tools) {
+			if (BUILTIN_TOOL_NAMES.has(toolDef.name)) throw new Error(`[flue] Custom tool "${toolDef.name}" conflicts with a built-in tool. Built-in tools: ${[...BUILTIN_TOOL_NAMES].join(", ")}`);
+			if (names.has(toolDef.name)) throw new Error(`[flue] Duplicate custom tool name "${toolDef.name}". Tool names must be unique.`);
+			names.add(toolDef.name);
+		}
+	}
+	createBuiltinTools(env, commands, tools, role, model) {
+		return createTools(env, {
+			roles: this.config.roles,
+			task: (params, signal) => this.runTaskForTool(params, commands, tools, role, model, signal)
+		});
+	}
+	async withScopedRuntime(options, fn) {
+		const customTools = this.createCustomTools([...this.agentTools, ...options.tools]);
+		const scopedEnv = await createScopedEnv(this.env, options.commands);
+		const previousTools = this.harness.state.tools;
+		const previousModel = this.harness.state.model;
+		const previousSystemPrompt = this.harness.state.systemPrompt;
+		this.harness.state.model = this.resolveModelForCall(options.model, options.role, options.callSite);
+		this.harness.state.systemPrompt = this.buildSystemPrompt(options.role);
+		this.harness.state.tools = [...this.createBuiltinTools(scopedEnv, options.commands, options.tools, options.role, options.model), ...customTools];
+		try {
+			return await fn();
+		} finally {
+			this.harness.state.tools = previousTools;
+			this.harness.state.model = previousModel;
+			this.harness.state.systemPrompt = previousSystemPrompt;
+		}
+	}
+	async runTaskForTool(params, commands, tools, inheritedRole, inheritedModel, signal) {
+		const result = await this.runTask(params.prompt, {
+			role: params.role ?? inheritedRole,
+			inheritedModel,
+			cwd: params.cwd,
+			commands,
+			tools
+		}, signal);
+		return {
+			content: [{
+				type: "text",
+				text: result.text || "(task completed with no text)"
+			}],
+			details: {
+				taskId: result.taskId,
+				sessionId: result.sessionId,
+				messageId: result.messageId,
+				role: result.role,
+				cwd: result.cwd
+			}
+		};
+	}
+	async runTask(text, options, signal) {
+		this.assertActive();
+		if (!this.createTaskSession) throw new Error("[flue] This session cannot create task sessions.");
+		if (this.taskDepth >= MAX_TASK_DEPTH) throw new Error(`[flue] Maximum task depth (${MAX_TASK_DEPTH}) exceeded.`);
+		if (signal?.aborted) throw new Error("Operation aborted");
+		const taskId = crypto.randomUUID();
+		const requestedRole = options?.role ?? this.sessionRole ?? this.config.role;
+		let child;
+		let abortListener;
+		this.emit({
+			type: "task_start",
+			taskId,
+			prompt: text,
+			role: requestedRole,
+			cwd: options?.cwd,
+			parentSessionId: this.id
+		});
+		try {
+			const role = this.resolveEffectiveRole(options?.role);
+			const commands = mergeCommands(this.agentCommands, options?.commands);
+			child = await this.createTaskSession({
+				parentSessionId: this.id,
+				taskId,
+				parentEnv: this.env,
+				cwd: options?.cwd,
+				role,
+				commands,
+				depth: this.taskDepth + 1
+			});
+			await this.recordTaskSession(child.id, child.storageKey, taskId);
+			this.activeTasks.add(child);
+			if (signal) {
+				abortListener = () => child?.abort();
+				signal.addEventListener("abort", abortListener, { once: true });
+				if (signal.aborted) throw new Error("Operation aborted");
+			}
+			const schema = options?.result;
+			const roleModel = resolveRoleModel(this.config.roles, role);
+			const childOptions = {
+				model: options?.model ?? (roleModel ? void 0 : options?.inheritedModel),
+				tools: options?.tools
+			};
+			if (schema) childOptions.result = schema;
+			const output = await child.prompt(text, childOptions);
+			const taskResult = {
+				output,
+				text: typeof output?.text === "string" ? output.text : child.getAssistantText(),
+				taskId,
+				sessionId: child.id,
+				messageId: child.getLatestAssistantMessageId(),
+				role,
+				cwd: options?.cwd
+			};
+			this.emit({
+				type: "task_end",
+				taskId,
+				isError: false,
+				result: taskResult.text,
+				parentSessionId: this.id
+			});
+			return taskResult;
+		} catch (error) {
+			this.emit({
+				type: "task_end",
+				taskId,
+				isError: true,
+				result: getErrorMessage(error),
+				parentSessionId: this.id
+			});
+			this.emit({
+				type: "error",
+				error: getErrorMessage(error)
+			});
+			throw error;
+		} finally {
+			if (signal && abortListener) signal.removeEventListener("abort", abortListener);
+			if (child) {
+				this.activeTasks.delete(child);
+				child.close();
+			}
+		}
+	}
+	async runOperation(operation, fn) {
+		return this.runExclusive(operation, async () => {
+			try {
+				return await fn();
+			} catch (error) {
+				this.emit({
+					type: "error",
+					error: getErrorMessage(error)
+				});
+				throw error;
+			} finally {
+				this.emit({ type: "idle" });
+			}
+		});
+	}
+	async runExclusive(operation, fn) {
+		this.assertActive();
+		if (this.activeOperation) throw new Error(`[flue] Session "${this.id}" is already running ${this.activeOperation}. Start another session for parallel conversation branches.`);
+		this.activeOperation = operation;
+		try {
+			return await fn();
+		} finally {
+			this.activeOperation = void 0;
+		}
+	}
+	emit(event) {
+		this.eventCallback?.({
+			...event,
+			sessionId: this.id
+		});
+	}
+	assertActive() {
+		if (this.deleted) throw new Error(`[flue] Session "${this.id}" has been deleted.`);
+	}
+	createShellMessage(command, result, options) {
+		return {
+			role: "user",
+			content: [{
+				type: "text",
+				text: formatShellHistory(command, result, options?.cwd ? `\ncwd: ${options.cwd}` : "", options?.env ? `\nenv: ${Object.keys(options.env).sort().join(", ")}` : "")
+			}],
+			timestamp: Date.now()
+		};
+	}
+	async syncHarnessMessagesSince(index, source) {
+		const messages = this.harness.state.messages.slice(index);
+		if (messages.length === 0) return;
+		this.history.appendMessages(messages, source);
+		await this.save();
 	}
 	async save() {
 		const now = (/* @__PURE__ */ new Date()).toISOString();
-		const data = {
-			messages: this.agent.state.messages,
-			metadata: this.metadata,
-			createdAt: this.createdAt ?? now,
-			updatedAt: now,
-			lastCompaction: this.lastCompaction
-		};
+		const data = this.history.toData(this.metadata, this.createdAt ?? now, now);
 		if (!this.createdAt) this.createdAt = now;
-		await this.store.save(this.id, data);
+		await this.store.save(this.storageKey, data);
+	}
+	async recordTaskSession(sessionId, storageKey, taskId) {
+		const taskSessions = Array.isArray(this.metadata.taskSessions) ? this.metadata.taskSessions : [];
+		if (!taskSessions.some((task) => task?.sessionId === sessionId)) {
+			taskSessions.push({
+				sessionId,
+				taskId,
+				storageKey
+			});
+			this.metadata.taskSessions = taskSessions;
+			await this.save();
+		}
+	}
+	async checkLatestAssistantForCompaction() {
+		const messages = this.harness.state.messages;
+		const lastMsg = messages[messages.length - 1];
+		if (lastMsg?.role === "assistant") await this.checkCompaction(lastMsg);
 	}
 	async checkCompaction(assistantMessage) {
 		if (!this.compactionSettings.enabled) return;
 		if (assistantMessage.stopReason === "aborted") return;
-		const contextWindow = this.agent.state.model.contextWindow ?? 0;
+		const contextWindow = this.harness.state.model.contextWindow ?? 0;
 		if (isContextOverflow(assistantMessage, contextWindow)) {
 			if (this.overflowRecoveryAttempted) return;
 			this.overflowRecoveryAttempted = true;
 			console.error(`[flue:compaction] Overflow detected, compacting and retrying...`);
-			const messages = this.agent.state.messages;
+			const messages = this.harness.state.messages;
 			const lastMsg = messages[messages.length - 1];
-			if (lastMsg && lastMsg.role === "assistant") this.agent.state.messages = messages.slice(0, -1);
+			if (lastMsg && lastMsg.role === "assistant") {
+				this.harness.state.messages = messages.slice(0, -1);
+				this.history.removeLeafMessage(lastMsg);
+				await this.save();
+			}
 			await this.runCompaction("overflow", true);
 			return;
 		}
-		let contextTokens;
-		if (assistantMessage.stopReason === "error") {
-			const estimate = estimateContextTokens(this.agent.state.messages);
-			if (estimate.lastUsageIndex === null) return;
-			contextTokens = estimate.tokens;
-		} else contextTokens = calculateContextTokens(assistantMessage.usage);
+		if (assistantMessage.stopReason === "error") return;
+		const contextTokens = calculateContextTokens(assistantMessage.usage);
 		if (shouldCompact(contextTokens, contextWindow, this.compactionSettings)) {
 			console.error(`[flue:compaction] Threshold reached — ${contextTokens} tokens used, window ${contextWindow}, reserve ${this.compactionSettings.reserveTokens}, triggering compaction`);
 			await this.runCompaction("threshold", false);
@@ -849,45 +1164,59 @@ var Session = class Session {
 	}
 	async runCompaction(reason, willRetry) {
 		this.compactionAbortController = new AbortController();
-		const messagesBefore = this.agent.state.messages.length;
+		const messagesBefore = this.harness.state.messages.length;
 		try {
-			const model = this.agent.state.model;
-			const messages = this.agent.state.messages;
-			const preparation = prepareCompaction(messages, this.compactionSettings, this.lastCompaction);
+			const model = this.harness.state.model;
+			const contextEntries = this.history.buildContextEntries();
+			const messages = contextEntries.map((entry) => entry.message);
+			const latestCompaction = this.history.getLatestCompaction();
+			const preparation = prepareCompaction(messages, this.compactionSettings, latestCompaction ? {
+				summary: latestCompaction.summary,
+				firstKeptIndex: 1,
+				details: latestCompaction.details
+			} : void 0);
 			if (!preparation) {
 				console.error(`[flue:compaction] Nothing to compact (no valid cut point found)`);
 				return;
 			}
+			const firstKeptEntry = contextEntries[preparation.firstKeptIndex]?.entry;
+			if (!firstKeptEntry || firstKeptEntry.type !== "message") {
+				console.error(`[flue:compaction] Nothing to compact (first kept message has no entry)`);
+				return;
+			}
 			console.error(`[flue:compaction] Summarizing ${preparation.messagesToSummarize.length} messages` + (preparation.isSplitTurn ? ` (split turn: ${preparation.turnPrefixMessages.length} prefix messages)` : "") + `, keeping messages from index ${preparation.firstKeptIndex}`);
 			const estimatedTokens = preparation.tokensBefore;
-			this.eventCallback?.({
+			this.emit({
 				type: "compaction_start",
 				reason,
 				estimatedTokens
 			});
 			const result = await compact(preparation, model, void 0, this.compactionAbortController.signal);
 			if (this.compactionAbortController.signal.aborted) return;
-			const newMessages = buildCompactedMessages(messages, result);
-			this.agent.state.messages = newMessages;
-			const messagesAfter = newMessages.length;
+			this.history.appendCompaction({
+				summary: result.summary,
+				firstKeptEntryId: firstKeptEntry.id,
+				tokensBefore: result.tokensBefore,
+				details: result.details
+			});
+			this.harness.state.messages = this.history.buildContext();
+			const messagesAfter = this.harness.state.messages.length;
 			console.error(`[flue:compaction] Complete — messages: ${messagesBefore} → ${messagesAfter}, tokens before: ${result.tokensBefore}`);
-			this.eventCallback?.({
+			this.emit({
 				type: "compaction_end",
 				messagesBefore,
 				messagesAfter
 			});
-			this.lastCompaction = {
-				summary: result.summary,
-				firstKeptIndex: 1,
-				details: result.details
-			};
 			await this.save();
 			if (willRetry) {
-				const msgs = this.agent.state.messages;
+				const msgs = this.harness.state.messages;
 				const lastMsg = msgs[msgs.length - 1];
-				if (lastMsg?.role === "assistant" && lastMsg.stopReason === "error") this.agent.state.messages = msgs.slice(0, -1);
+				if (lastMsg?.role === "assistant" && lastMsg.stopReason === "error") this.harness.state.messages = msgs.slice(0, -1);
 				console.error(`[flue:compaction] Retrying after overflow recovery...`);
-				await this.agent.continue();
+				const beforeRetry = this.harness.state.messages.length;
+				await this.harness.continue();
+				await this.harness.waitForIdle();
+				await this.syncHarnessMessagesSince(beforeRetry, "retry");
 			}
 		} catch (error) {
 			const errorMessage = error instanceof Error ? error.message : String(error);
@@ -897,11 +1226,11 @@ var Session = class Session {
 		}
 	}
 	throwIfError(context) {
-		const errorMsg = this.agent.state.errorMessage;
+		const errorMsg = this.harness.state.errorMessage;
 		if (errorMsg) throw new Error(`[flue] ${context} failed: ${errorMsg}`);
 	}
 	getAssistantText() {
-		const messages = this.agent.state.messages;
+		const messages = this.harness.state.messages;
 		for (let i = messages.length - 1; i >= 0; i--) {
 			const msg = messages[i];
 			if (msg.role !== "assistant") continue;
@@ -913,6 +1242,13 @@ var Session = class Session {
 		}
 		return "";
 	}
+	getLatestAssistantMessageId() {
+		const path = this.history.getActivePath();
+		for (let i = path.length - 1; i >= 0; i--) {
+			const entry = path[i];
+			if (entry.type === "message" && entry.message.role === "assistant") return entry.id;
+		}
+	}
 	async extractResultWithRetry(schema) {
 		const text = this.getAssistantText();
 		try {
@@ -921,9 +1257,11 @@ var Session = class Session {
 			if (!(err instanceof ResultExtractionError)) throw err;
 			if (!err.message.includes("RESULT_START")) throw err;
 			const followUpPrompt = buildResultExtractionPrompt(schema);
-			await this.agent.prompt(followUpPrompt);
-			await this.agent.waitForIdle();
-			await this.save();
+			const beforeRetry = this.harness.state.messages.length;
+			await this.harness.prompt(followUpPrompt);
+			await this.harness.waitForIdle();
+			await this.syncHarnessMessagesSince(beforeRetry, "retry");
+			await this.checkLatestAssistantForCompaction();
 			return extractResult(this.getAssistantText(), schema);
 		}
 	}
@@ -938,6 +1276,28 @@ function normalizePath(p) {
 	}
 	return "/" + result.join("/");
 }
+async function deleteSessionTree(store, storageKey, seen = /* @__PURE__ */ new Set()) {
+	if (seen.has(storageKey)) return;
+	seen.add(storageKey);
+	const data = await store.load(storageKey);
+	const taskSessions = Array.isArray(data?.metadata?.taskSessions) ? data.metadata.taskSessions : [];
+	for (const task of taskSessions) if (typeof task?.storageKey === "string") await deleteSessionTree(store, task.storageKey, seen);
+	await store.delete(storageKey);
+}
+function formatShellHistory(command, result, cwdLine, envLine) {
+	const sections = [`<shell_command>\n$ ${command}${cwdLine}${envLine}\n</shell_command>`, `<shell_result exitCode="${result.exitCode}">`];
+	if (result.stdout) sections.push(`<stdout>\n${result.stdout}\n</stdout>`);
+	if (result.stderr) sections.push(`<stderr>\n${result.stderr}\n</stderr>`);
+	sections.push("</shell_result>");
+	return truncateShellHistory(sections.join("\n"));
+}
+function truncateShellHistory(text) {
+	if (text.length <= MAX_SHELL_HISTORY_CHARS) return text;
+	return `[Shell output truncated: ${text.length - MAX_SHELL_HISTORY_CHARS} leading characters omitted]\n` + text.slice(text.length - MAX_SHELL_HISTORY_CHARS);
+}
+function getErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 
 //#endregion
-export { Session as n, normalizePath as r, InMemorySessionStore as t };
+export { assertRoleExists as a, normalizePath as i, Session as n, createScopedEnv as o, deleteSessionTree as r, mergeCommands as s, InMemorySessionStore as t };