@flue/sdk 0.3.10 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flue/sdk",
-  "version": "0.3.10",
+  "version": "0.4.0",
   "type": "module",
   "license": "Apache-2.0",
   "exports": {
@@ -8,6 +8,10 @@
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs"
     },
+    "./app": {
+      "types": "./dist/app.d.mts",
+      "import": "./dist/app.mjs"
+    },
     "./client": {
       "types": "./dist/client.d.mts",
       "import": "./dist/client.mjs"
@@ -27,6 +31,10 @@
     "./node": {
       "types": "./dist/node/index.d.mts",
       "import": "./dist/node/index.mjs"
+    },
+    "./config": {
+      "types": "./dist/config.d.mts",
+      "import": "./dist/config.mjs"
     }
   },
   "main": "./dist/index.mjs",
@@ -34,6 +42,9 @@
   "files": [
     "dist"
   ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
   "dependencies": {
     "@cloudflare/shell": "^0.3.2",
     "@hono/node-server": "^1.14.0",
@@ -45,6 +56,7 @@
     "hono": "^4.7.0",
     "just-bash": "^2.14.2",
     "package-up": "^5.0.0",
+    "typescript": "^5.9.2",
     "valibot": "^1.0.0"
   },
   "devDependencies": {

package/dist/agent-BTB0809P.mjs

@@ -1,453 +0,0 @@
-import { Type } from "@mariozechner/pi-ai";
-
-//#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");
-}
-/**
-* Load a skill directly by relative path under `.agents/skills/`.
-*
-* The path is taken as-is — no extension is auto-appended. Callers reference
-* the full filename, e.g. `'triage/reproduce.md'`. Returns `null` if the file
-* doesn't exist.
-*
-* Used as a fallback by `session.skill()` when the requested name doesn't match
-* a discovered skill's frontmatter `name:` field. Lets users organise skills as
-* a pack of sibling markdown files under one directory (orchestration SKILL.md
-* + stage files) without forcing each stage into its own `SKILL.md` subdirectory.
-*/
-async function loadSkillByPath(env, basePath, relPath) {
-	const filePath = `${basePath.endsWith("/") ? `${basePath}.agents/skills` : `${basePath}/.agents/skills`}/${relPath}`;
-	if (!await env.exists(filePath)) return null;
-	const parsed = parseFrontmatterFile(await env.readFile(filePath), relPath.replace(/\.(md|markdown)$/i, ""));
-	return {
-		name: parsed.name,
-		description: parsed.description,
-		instructions: parsed.body
-	};
-}
-/** Discover skills from .agents/skills/<name>/SKILL.md under basePath. */
-async function discoverLocalSkills(env, basePath) {
-	const skillsDir = basePath.endsWith("/") ? `${basePath}.agents/skills` : `${basePath}/.agents/skills`;
-	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",
-	"task"
-]);
-function createTools(env, options) {
-	const tools = [
-		createReadTool(env),
-		createWriteTool(env),
-		createEditTool(env),
-		createBashTool(env),
-		createGrepTool(env),
-		createGlobTool(env)
-	];
-	if (options?.task) tools.push(createTaskTool(options.task, options.roles ?? {}));
-	return tools;
-}
-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, { timeout: params.timeout }), params.command);
-		}
-	};
-}
-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}`);
-	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
-export { parseFrontmatterFile as a, loadSkillByPath as i, createTools as n, discoverSessionContext as r, BUILTIN_TOOL_NAMES as t };

package/dist/command-helpers-5DpOaRIB.d.mts

@@ -1,21 +0,0 @@
-import { A as ShellResult } from "./types-CKcp6T-y.mjs";
-
-//#region src/command-helpers.d.ts
-/**
- * Loose return shape accepted from user-supplied command executors. All forms
- * are normalized to a full `ShellResult` by `normalizeExecutor()`.
- */
-type CommandExecutorResult = ShellResult | {
-  stdout?: string;
-  stderr?: string;
-  exitCode?: number;
-} | string | void;
-/**
- * User-supplied command executor. Can return a full `ShellResult`, a partial
- * `{ stdout?, stderr?, exitCode? }` object, a bare string (treated as stdout),
- * or void (empty success). Thrown errors are caught and converted to an
- * `exitCode`-bearing `ShellResult` — no `try`/`catch` needed at the call site.
- */
-type CommandExecutor = (args: string[]) => Promise<CommandExecutorResult>;
-//#endregion
-export { CommandExecutor as t };

package/dist/command-helpers-hTZKWK13.mjs

@@ -1,37 +0,0 @@
-//#region src/command-helpers.ts
-/**
-* Wrap a user-supplied `CommandExecutor` to always resolve with a full
-* `ShellResult`. Applies loose-return normalization and catches throws.
-*/
-function normalizeExecutor(executor) {
-	return async (args) => {
-		try {
-			const raw = await executor(args);
-			if (raw === void 0 || raw === null) return {
-				stdout: "",
-				stderr: "",
-				exitCode: 0
-			};
-			if (typeof raw === "string") return {
-				stdout: raw,
-				stderr: "",
-				exitCode: 0
-			};
-			return {
-				stdout: raw.stdout ?? "",
-				stderr: raw.stderr ?? "",
-				exitCode: raw.exitCode ?? 0
-			};
-		} catch (err) {
-			const e = err ?? {};
-			return {
-				stdout: typeof e.stdout === "string" ? e.stdout : "",
-				stderr: typeof e.stderr === "string" ? e.stderr : String(err),
-				exitCode: typeof e.code === "number" ? e.code : 1
-			};
-		}
-	};
-}
-
-//#endregion
-export { normalizeExecutor as t };