@flue/sdk 0.1.0 → 0.1.2

package/dist/{session-BD0MEuO3.mjs → session-BRLCNVG1.mjs}

@@ -1,415 +1,9 @@
+import { i as loadSkillByPath, n as createTools, r as discoverSessionContext, t as BUILTIN_TOOL_NAMES } from "./agent-BYG0nVbQ.mjs";
+import { completeSimple, isContextOverflow } from "@mariozechner/pi-ai";
 import { Agent } from "@mariozechner/pi-agent-core";
-import { Type, completeSimple, isContextOverflow } from "@mariozechner/pi-ai";
 import { toJsonSchema } from "@valibot/to-json-schema";
 import * as v from "valibot";
 
-//#region src/context.ts
-/** Parse optional YAML frontmatter (--- delimited). Basic `key: value` only. */
-function parseFrontmatterFile(content, defaultName) {
-	const frontmatterMatch = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
-	if (!frontmatterMatch) return {
-		name: defaultName,
-		description: "",
-		body: content.trim(),
-		frontmatter: {}
-	};
-	const rawFrontmatter = frontmatterMatch[1] ?? "";
-	const body = frontmatterMatch[2] ?? "";
-	const frontmatter = {};
-	for (const line of rawFrontmatter.split("\n")) {
-		const match = line.match(/^(\w+):\s*(.+)$/);
-		if (match?.[1] && match[2]) frontmatter[match[1]] = match[2].trim();
-	}
-	return {
-		name: frontmatter.name || defaultName,
-		description: frontmatter.description || "",
-		body: body.trim(),
-		frontmatter
-	};
-}
-/** Read AGENTS.md (and CLAUDE.md if present) from a directory. Returns concatenated contents. */
-async function readAgentsMd(env, basePath) {
-	const parts = [];
-	for (const filename of ["AGENTS.md", "CLAUDE.md"]) {
-		const filePath = basePath.endsWith("/") ? basePath + filename : `${basePath}/${filename}`;
-		if (await env.exists(filePath)) {
-			const content = await env.readFile(filePath);
-			parts.push(content.trim());
-		}
-	}
-	return parts.join("\n\n");
-}
-/** Discover skills from .agents/skills/<name>/SKILL.md under basePath. */
-async function discoverLocalSkills(env, basePath) {
-	const skillsDir = basePath.endsWith("/") ? `${basePath}.agents/skills` : `${basePath}/.agents/skills`;
-	if (!await env.exists(skillsDir)) return {};
-	const skills = {};
-	const entries = await env.readdir(skillsDir);
-	for (const entry of entries) {
-		const skillDir = `${skillsDir}/${entry}`;
-		try {
-			if (!(await env.stat(skillDir)).isDirectory) continue;
-		} catch {
-			continue;
-		}
-		const skillMdPath = `${skillDir}/SKILL.md`;
-		if (!await env.exists(skillMdPath)) continue;
-		const parsed = parseFrontmatterFile(await env.readFile(skillMdPath), entry);
-		skills[parsed.name] = {
-			name: parsed.name,
-			description: parsed.description,
-			instructions: parsed.body
-		};
-	}
-	return skills;
-}
-function composeSystemPrompt(agentsMd, skills, env) {
-	const parts = [];
-	if (agentsMd) parts.push(agentsMd);
-	const skillEntries = Object.values(skills);
-	if (skillEntries.length > 0) {
-		parts.push("", "## Available Skills", "");
-		for (const skill of skillEntries) {
-			const desc = skill.description ? ` - ${skill.description}` : "";
-			parts.push(`- **${skill.name}**${desc}`);
-		}
-	}
-	if (env) {
-		const date = (/* @__PURE__ */ new Date()).toLocaleDateString("en-US", {
-			weekday: "short",
-			year: "numeric",
-			month: "short",
-			day: "numeric"
-		});
-		parts.push("", `Date: ${date}`);
-		parts.push(`Working directory: ${env.cwd}`);
-		if (env.directoryListing && env.directoryListing.length > 0) parts.push("", "Directory structure:", env.directoryListing.join("\n"));
-	}
-	return parts.join("\n");
-}
-/** Discover AGENTS.md, local skills, and directory listing from the session's cwd. */
-async function discoverSessionContext(env) {
-	const cwd = env.cwd;
-	const agentsMd = await readAgentsMd(env, cwd);
-	const skills = await discoverLocalSkills(env, cwd);
-	let directoryListing;
-	try {
-		directoryListing = await env.readdir(cwd);
-	} catch {}
-	return {
-		systemPrompt: composeSystemPrompt(agentsMd, skills, {
-			cwd,
-			directoryListing
-		}),
-		skills
-	};
-}
-
-//#endregion
-//#region src/agent.ts
-const MAX_READ_LINES = 2e3;
-const MAX_READ_BYTES = 50 * 1024;
-const MAX_GREP_MATCHES = 100;
-const MAX_GREP_LINE_LENGTH = 500;
-const MAX_GLOB_RESULTS = 1e3;
-const BUILTIN_TOOL_NAMES = new Set([
-	"read",
-	"write",
-	"edit",
-	"bash",
-	"grep",
-	"glob"
-]);
-function createTools(env) {
-	return [
-		createReadTool(env),
-		createWriteTool(env),
-		createEditTool(env),
-		createBashTool(env),
-		createGrepTool(env),
-		createGlobTool(env)
-	];
-}
-function createReadTool(env) {
-	return {
-		name: "read",
-		label: "Read File",
-		description: "Read a file or list a directory. For files, output is truncated to 2000 lines or 50KB — use offset/limit for large files. For directories, returns the list of entries.",
-		parameters: Type.Object({
-			path: Type.String({ description: "Path to the file to read" }),
-			offset: Type.Optional(Type.Number({ description: "Line number to start from (1-indexed)" })),
-			limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" }))
-		}),
-		async execute(_toolCallId, params, signal) {
-			throwIfAborted(signal);
-			try {
-				if ((await env.stat(params.path)).isDirectory) {
-					const entries = await env.readdir(params.path);
-					return {
-						content: [{
-							type: "text",
-							text: entries.join("\n") || "(empty directory)"
-						}],
-						details: {
-							path: params.path,
-							isDirectory: true,
-							entries: entries.length
-						}
-					};
-				}
-			} catch {}
-			const allLines = (await env.readFile(params.path)).split("\n");
-			const startLine = params.offset ? Math.max(0, params.offset - 1) : 0;
-			if (startLine >= allLines.length) throw new Error(`Offset ${params.offset} is beyond end of file (${allLines.length} lines total)`);
-			const endLine = params.limit ? startLine + params.limit : allLines.length;
-			const { text: truncatedText, wasTruncated } = truncateHead(allLines.slice(startLine, endLine), MAX_READ_LINES, MAX_READ_BYTES);
-			let output = truncatedText;
-			if (wasTruncated) {
-				const shownEnd = startLine + truncatedText.split("\n").length;
-				output += `\n\n[Showing lines ${startLine + 1}-${shownEnd} of ${allLines.length}. Use offset=${shownEnd + 1} to continue.]`;
-			}
-			return {
-				content: [{
-					type: "text",
-					text: output
-				}],
-				details: {
-					path: params.path,
-					lines: allLines.length
-				}
-			};
-		}
-	};
-}
-function createWriteTool(env) {
-	return {
-		name: "write",
-		label: "Write File",
-		description: "Write content to a file. Creates the file and parent directories if they do not exist.",
-		parameters: Type.Object({
-			path: Type.String({ description: "Path to the file to write" }),
-			content: Type.String({ description: "Content to write to the file" })
-		}),
-		async execute(_toolCallId, params, signal) {
-			throwIfAborted(signal);
-			const resolved = env.resolvePath(params.path);
-			const dir = resolved.replace(/\/[^/]*$/, "");
-			if (dir && dir !== resolved) await env.mkdir(dir, { recursive: true });
-			await env.writeFile(resolved, params.content);
-			return {
-				content: [{
-					type: "text",
-					text: `Successfully wrote ${params.content.length} bytes to ${params.path}`
-				}],
-				details: {
-					path: params.path,
-					size: params.content.length
-				}
-			};
-		}
-	};
-}
-function createEditTool(env) {
-	return {
-		name: "edit",
-		label: "Edit File",
-		description: "Edit a file using exact text replacement. The oldText must match a unique region of the file. Use replaceAll to replace all occurrences.",
-		parameters: Type.Object({
-			path: Type.String({ description: "Path to the file to edit" }),
-			oldText: Type.String({ description: "Exact text to find (must be unique)" }),
-			newText: Type.String({ description: "Replacement text" }),
-			replaceAll: Type.Optional(Type.Boolean({ description: "Replace all occurrences" }))
-		}),
-		async execute(_toolCallId, params, signal) {
-			throwIfAborted(signal);
-			const content = await env.readFile(params.path);
-			if (params.replaceAll) {
-				const newContent = content.replaceAll(params.oldText, params.newText);
-				if (newContent === content) throw new Error(`Could not find the text in ${params.path}. No changes made.`);
-				await env.writeFile(params.path, newContent);
-				const count = content.split(params.oldText).length - 1;
-				return {
-					content: [{
-						type: "text",
-						text: `Replaced ${count} occurrences in ${params.path}`
-					}],
-					details: {
-						path: params.path,
-						replacements: count
-					}
-				};
-			}
-			const occurrences = countOccurrences(content, params.oldText);
-			if (occurrences === 0) throw new Error(`Could not find the exact text in ${params.path}. Make sure your oldText matches exactly, including whitespace and indentation.`);
-			if (occurrences > 1) throw new Error(`Found ${occurrences} occurrences of the text in ${params.path}. Provide more surrounding context to make the match unique, or use replaceAll.`);
-			const newContent = content.replace(params.oldText, params.newText);
-			await env.writeFile(params.path, newContent);
-			return {
-				content: [{
-					type: "text",
-					text: `Successfully edited ${params.path}`
-				}],
-				details: { path: params.path }
-			};
-		}
-	};
-}
-function createBashTool(env) {
-	return {
-		name: "bash",
-		label: "Run Command",
-		description: "Execute a bash command. Returns stdout and stderr. Output is truncated to the last 2000 lines or 50KB.",
-		parameters: Type.Object({
-			command: Type.String({ description: "Bash command to execute" }),
-			timeout: Type.Optional(Type.Number({ description: "Timeout in seconds" }))
-		}),
-		async execute(_toolCallId, params, signal) {
-			throwIfAborted(signal);
-			return formatBashResult(await env.exec(params.command), params.command);
-		}
-	};
-}
-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}`);
-	return {
-		content: [{
-			type: "text",
-			text: output || "(no output)"
-		}],
-		details: {
-			command,
-			exitCode: result.exitCode
-		}
-	};
-}
-function createGrepTool(env) {
-	return {
-		name: "grep",
-		label: "Search Files",
-		description: "Search file contents for a regex pattern. Returns matching lines with file paths and line numbers.",
-		parameters: Type.Object({
-			pattern: Type.String({ description: "Search pattern (regex)" }),
-			path: Type.Optional(Type.String({ description: "Directory or file to search (default: .)" })),
-			include: Type.Optional(Type.String({ description: "Glob filter, e.g. \"*.ts\"" }))
-		}),
-		async execute(_toolCallId, params, signal) {
-			throwIfAborted(signal);
-			const searchPath = params.path || ".";
-			let cmd = `grep -rn "${escapeShellArg(params.pattern)}" ${escapeShellArg(searchPath)}`;
-			if (params.include) cmd = `grep -rn --include="${escapeShellArg(params.include)}" "${escapeShellArg(params.pattern)}" ${escapeShellArg(searchPath)}`;
-			const result = await env.exec(cmd);
-			if (result.exitCode === 1 && !result.stdout.trim()) return {
-				content: [{
-					type: "text",
-					text: "No matches found."
-				}],
-				details: { matchCount: 0 }
-			};
-			if (result.exitCode > 1) throw new Error(`grep failed: ${result.stderr}`);
-			const lines = result.stdout.trim().split("\n");
-			let finalOutput = lines.slice(0, MAX_GREP_MATCHES).map((line) => line.length > MAX_GREP_LINE_LENGTH ? line.slice(0, MAX_GREP_LINE_LENGTH) + "..." : line).join("\n");
-			if (lines.length > MAX_GREP_MATCHES) finalOutput += `\n\n[Showing ${MAX_GREP_MATCHES} of ${lines.length} matches. Narrow your search.]`;
-			return {
-				content: [{
-					type: "text",
-					text: finalOutput
-				}],
-				details: { matchCount: Math.min(lines.length, MAX_GREP_MATCHES) }
-			};
-		}
-	};
-}
-function createGlobTool(env) {
-	return {
-		name: "glob",
-		label: "Find Files",
-		description: "Find files by glob pattern. Returns matching file paths.",
-		parameters: Type.Object({
-			pattern: Type.String({ description: "Glob pattern, e.g. \"**/*.ts\"" }),
-			path: Type.Optional(Type.String({ description: "Directory to search in (default: .)" }))
-		}),
-		async execute(_toolCallId, params, signal) {
-			throwIfAborted(signal);
-			const cmd = `find ${escapeShellArg(params.path || ".")} -type f -name "${escapeShellArg(params.pattern)}" 2>/dev/null | head -${MAX_GLOB_RESULTS}`;
-			const result = await env.exec(cmd);
-			if (result.exitCode !== 0 && !result.stdout.trim()) return {
-				content: [{
-					type: "text",
-					text: "No files found matching pattern."
-				}],
-				details: { matchCount: 0 }
-			};
-			const paths = result.stdout.trim().split("\n").filter(Boolean);
-			if (paths.length === 0) return {
-				content: [{
-					type: "text",
-					text: "No files found matching pattern."
-				}],
-				details: { matchCount: 0 }
-			};
-			return {
-				content: [{
-					type: "text",
-					text: paths.join("\n")
-				}],
-				details: { matchCount: paths.length }
-			};
-		}
-	};
-}
-function throwIfAborted(signal) {
-	if (signal?.aborted) throw new Error("Operation aborted");
-}
-function countOccurrences(str, substr) {
-	let count = 0;
-	let pos = str.indexOf(substr, 0);
-	while (pos !== -1) {
-		count++;
-		pos = str.indexOf(substr, pos + substr.length);
-	}
-	return count;
-}
-function escapeShellArg(arg) {
-	return arg.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\$/g, "\\$").replace(/`/g, "\\`");
-}
-function truncateHead(lines, maxLines, maxBytes) {
-	let result = "";
-	let lineCount = 0;
-	let wasTruncated = false;
-	for (const line of lines) {
-		if (lineCount >= maxLines) {
-			wasTruncated = true;
-			break;
-		}
-		const next = lineCount === 0 ? line : "\n" + line;
-		if (result.length + next.length > maxBytes) {
-			wasTruncated = true;
-			break;
-		}
-		result += next;
-		lineCount++;
-	}
-	return {
-		text: result,
-		wasTruncated
-	};
-}
-function truncateTail(text, maxLines, maxBytes) {
-	const lines = text.split("\n");
-	if (lines.length <= maxLines && text.length <= maxBytes) return {
-		text,
-		wasTruncated: false
-	};
-	let result = lines.slice(-maxLines).join("\n");
-	if (result.length > maxBytes) result = result.slice(-maxBytes);
-	return {
-		text: result,
-		wasTruncated: true
-	};
-}
-
-//#endregion
 //#region src/compaction.ts
 const DEFAULT_COMPACTION_SETTINGS = {
 	enabled: true,
@@ -987,6 +581,7 @@ var Session = class Session {
 		});
 	}
 	async prompt(text, options) {
+		this.assertRoleExists(options?.role);
 		this.resolveModelForCall(options?.model, options?.role);
 		const promptWithRole = this.injectRoleInstructions(text, options?.role);
 		const schema = options?.result;
@@ -1007,8 +602,16 @@ var Session = class Session {
 		}
 	}
 	async skill(name, options) {
-		const registeredSkill = this.config.skills[name];
-		if (!registeredSkill) throw new Error(`Skill "${name}" not registered. Available: ${Object.keys(this.config.skills).join(", ") || "(none)"}`);
+		this.assertRoleExists(options?.role);
+		let registeredSkill = this.config.skills[name];
+		if (!registeredSkill && (name.includes("/") || /\.(md|markdown)$/i.test(name))) {
+			const loaded = await loadSkillByPath(this.env, this.env.cwd, name);
+			if (loaded) registeredSkill = loaded;
+		}
+		if (!registeredSkill) {
+			const available = Object.keys(this.config.skills).join(", ") || "(none)";
+			throw new Error(`Skill "${name}" not registered. Available: ${available}. Skills can also be referenced by relative path under .agents/skills/ (e.g. "triage/reproduce.md").`);
+		}
 		this.resolveModelForCall(options?.model, options?.role);
 		const schema = options?.result;
 		const skillPrompt = buildSkillPrompt(registeredSkill.instructions, options?.args, schema);
@@ -1046,6 +649,7 @@ var Session = class Session {
 		}
 	}
 	async task(prompt, options) {
+		this.assertRoleExists(options?.role);
 		if (!options?.workspace) throw new Error("[flue] task() requires a workspace option.");
 		const taskCwd = options.workspace.startsWith("/") ? options.workspace : normalizePath(this.env.cwd + "/" + options.workspace);
 		function taskResolvePath(p) {
@@ -1081,7 +685,7 @@ var Session = class Session {
 			systemPrompt: localContext.systemPrompt,
 			skills: localContext.skills,
 			roles: this.config.roles,
-			model: taskModel,
+			model: this.requireModel(taskModel, "this task() call"),
 			resolveModel: this.config.resolveModel,
 			compaction: this.config.compaction
 		};
@@ -1113,7 +717,28 @@ var Session = class Session {
 		let model = this.config.model;
 		if (roleName && this.config.roles[roleName]?.model && this.config.resolveModel) model = this.config.resolveModel(this.config.roles[roleName].model);
 		if (promptModel && this.config.resolveModel) model = this.config.resolveModel(promptModel);
-		this.agent.state.model = model;
+		this.agent.state.model = this.requireModel(model, "this prompt()/skill()/task() call");
+	}
+	/**
+	* Throws a clear, actionable error when no model is configured for a call.
+	* Use with the resolved model (post-precedence) to guarantee we never hand
+	* `undefined` to the underlying agent.
+	*/
+	requireModel(model, callSite) {
+		if (model) return model;
+		throw new Error(`[flue] No model configured for ${callSite}. Pass \`{ model: "provider/model-id" }\` to \`init()\` for a session-wide default, or to this prompt()/skill()/task() call for a one-off override.`);
+	}
+	/**
+	* Throws a clear error when a caller references a role that isn't registered.
+	* Roles are loaded from `.flue/roles/` at build time. Called eagerly at the top
+	* of prompt()/skill()/task() so typos surface before any LLM work begins.
+	*/
+	assertRoleExists(roleName) {
+		if (!roleName) return;
+		if (this.config.roles[roleName]) return;
+		const available = Object.keys(this.config.roles);
+		const list = available.length > 0 ? available.join(", ") : "(none defined)";
+		throw new Error(`[flue] Role "${roleName}" not registered. Available roles: ${list}. Define roles as markdown files under \`.flue/roles/\`.`);
 	}
 	injectRoleInstructions(text, roleName) {
 		if (!roleName) return text;
@@ -1297,4 +922,4 @@ function normalizePath(p) {
 }
 
 //#endregion
-export { createTools as a, BUILTIN_TOOL_NAMES as i, Session as n, discoverSessionContext as o, normalizePath as r, parseFrontmatterFile as s, InMemorySessionStore as t };
+export { Session as n, normalizePath as r, InMemorySessionStore as t };

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flue/sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "license": "Apache-2.0",
   "exports": {
@@ -16,6 +16,10 @@
       "types": "./dist/sandbox.d.mts",
       "import": "./dist/sandbox.mjs"
     },
+    "./internal": {
+      "types": "./dist/internal.d.mts",
+      "import": "./dist/internal.mjs"
+    },
     "./cloudflare": {
       "types": "./dist/cloudflare/index.d.mts",
       "import": "./dist/cloudflare/index.mjs"