@flue/sdk 0.3.10 → 0.4.0

package/dist/result-K1IRhWKM.mjs

@@ -0,0 +1,685 @@
+import { Type } 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");
+}
+/** Path to the skills directory under a given base path. */
+function skillsDirIn(basePath) {
+	return basePath.endsWith("/") ? `${basePath}.agents/skills` : `${basePath}/.agents/skills`;
+}
+/**
+* Resolve a skill referenced by relative path under `.agents/skills/`,
+* returning the absolute filesystem path or `null` if the file doesn't
+* exist.
+*
+* The relative path is taken as-is — no extension is auto-appended.
+* Callers reference the full filename, e.g. `'triage/reproduce.md'`.
+*
+* Used by `session.skill()` when the caller passes a path-shaped name
+* (contains `/` or ends in `.md`/`.markdown`). Path-based references
+* bypass the skill registry entirely — the model is given the resolved
+* path and reads the file directly. We don't parse the file here
+* because nothing on the server side needs the frontmatter for these
+* skills; only the model does, and it reads the file itself.
+*/
+async function resolveSkillFilePath(env, basePath, relPath) {
+	const filePath = `${skillsDirIn(basePath)}/${relPath}`;
+	if (!await env.exists(filePath)) return null;
+	return filePath;
+}
+/**
+* Discover skills from `.agents/skills/<name>/SKILL.md` under basePath.
+*
+* Skill bodies are intentionally not retained — at call time the model
+* reads the file from disk itself, which keeps relative references
+* inside the skill resolvable from where they live and lets users edit
+* skill files mid-session without re-initialising the agent. We parse
+* the frontmatter here only to populate the system-prompt's "Available
+* Skills" registry (name + description).
+*/
+async function discoverLocalSkills(env, basePath) {
+	const skillsDir = skillsDirIn(basePath);
+	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
+		};
+	}
+	return skills;
+}
+/**
+* Headless-mode preamble. Included once at the top of every session's
+* system prompt so the model knows it's running without a human operator
+* before the first turn — and doesn't get reminded of it on every
+* `prompt()` / `skill()` call. Previously this lived in
+* `result.ts:buildPromptText` / `buildSkillPrompt` and was inlined into
+* each per-call user message; that was redundant noise once the harness
+* gained tool-call shape (it can't ask questions or wait for input
+* regardless of what the user message says).
+*/
+const HEADLESS_PREAMBLE = "You are running in headless mode with no human operator. Work autonomously — never ask questions, never wait for user input. Make your best judgment and proceed independently.";
+function composeSystemPrompt(agentsMd, skills, env) {
+	const parts = [HEADLESS_PREAMBLE];
+	if (agentsMd) parts.push("", agentsMd);
+	const skillEntries = Object.values(skills);
+	if (skillEntries.length > 0) {
+		parts.push("", "## Available Skills", "", "Each skill below is documented in a markdown file under `.agents/skills/` (relative to your working directory). The default location is `.agents/skills/<name>/SKILL.md`. When asked to run a skill, read its file from disk and follow the instructions there literally — the skill body is not provided inline.", "");
+		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;
+}
+const ReadParams = 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" }))
+});
+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: ReadParams,
+		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
+				}
+			};
+		}
+	};
+}
+const WriteParams = Type.Object({
+	path: Type.String({ description: "Path to the file to write" }),
+	content: Type.String({ description: "Content to write to the file" })
+});
+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: WriteParams,
+		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
+				}
+			};
+		}
+	};
+}
+const EditParams = 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" }))
+});
+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: EditParams,
+		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 }
+			};
+		}
+	};
+}
+const BashParams = Type.Object({
+	command: Type.String({ description: "Bash command to execute" }),
+	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds" }))
+});
+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: BashParams,
+		async execute(_toolCallId, params, signal) {
+			throwIfAborted(signal);
+			const timeoutSignal = typeof params.timeout === "number" ? AbortSignal.timeout(params.timeout * 1e3) : void 0;
+			const execSignal = signal && timeoutSignal ? AbortSignal.any([signal, timeoutSignal]) : signal ?? timeoutSignal;
+			const timedOut = () => formatBashResult({
+				stdout: "",
+				stderr: `[flue] Command timed out after ${params.timeout} seconds.`,
+				exitCode: 124
+			}, params.command);
+			try {
+				const result = await env.exec(params.command, {
+					timeout: params.timeout,
+					signal: execSignal
+				});
+				if (timeoutSignal?.aborted && !signal?.aborted) return timedOut();
+				return formatBashResult(result, params.command);
+			} catch (err) {
+				if (timeoutSignal?.aborted && !signal?.aborted) return timedOut();
+				throw err;
+			}
+		}
+	};
+}
+const TaskParams = 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." }))
+});
+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: TaskParams,
+		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);
+	const exitLine = `Command exited with code ${result.exitCode}`;
+	return {
+		content: [{
+			type: "text",
+			text: result.exitCode === 0 ? output || "(no output)" : `${output || "(no output)"}\n\n${exitLine}`
+		}],
+		details: {
+			command,
+			exitCode: result.exitCode
+		}
+	};
+}
+const GrepParams = 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\"" }))
+});
+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: GrepParams,
+		async execute(_toolCallId, params, signal) {
+			throwIfAborted(signal);
+			const searchPath = params.path || ".";
+			let cmd = `grep -rn ${shellQuote(params.pattern)} ${shellQuote(searchPath)}`;
+			if (params.include) cmd = `grep -rn --include=${shellQuote(params.include)} ${shellQuote(params.pattern)} ${shellQuote(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) }
+			};
+		}
+	};
+}
+const GlobParams = Type.Object({
+	pattern: Type.String({ description: "Filename pattern, e.g. \"*.ts\"" }),
+	path: Type.Optional(Type.String({ description: "Directory to search in (default: .)" }))
+});
+function createGlobTool(env) {
+	return {
+		name: "glob",
+		label: "Find Files",
+		description: "Find files by filename pattern using shell find -name semantics. Returns matching file paths.",
+		parameters: GlobParams,
+		async execute(_toolCallId, params, signal) {
+			throwIfAborted(signal);
+			const cmd = `find ${shellQuote(params.path || ".")} -type f -name ${shellQuote(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 shellQuote(arg) {
+	return `'${arg.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/result.ts
+/**
+* Names of the SDK-injected tools used to capture schema-typed results.
+* Surfaced for diagnostics and logging; not part of the public API.
+*/
+const FINISH_TOOL_NAME = "finish";
+const GIVE_UP_TOOL_NAME = "give_up";
+/** Footer appended to user prompts/skill bodies when a `result` schema is set. */
+function buildResultFooter() {
+	return [
+		"",
+		`When the task is complete, call the \`${FINISH_TOOL_NAME}\` tool with your final answer as its arguments. The arguments are validated against the required schema; if validation fails you will receive an error and may try again.`,
+		`If you determine that you cannot complete the task or cannot produce a result that conforms to the required schema, call the \`${GIVE_UP_TOOL_NAME}\` tool with a clear \`reason\`.`,
+		`Do not respond with the answer in plain text — only a successful \`${FINISH_TOOL_NAME}\` (or \`${GIVE_UP_TOOL_NAME}\`) call counts.`
+	].join("\n");
+}
+/** Follow-up prompt sent when the LLM ends a turn without calling `finish` or `give_up`. */
+function buildResultFollowUpPrompt() {
+	return [`You ended your turn without calling \`${FINISH_TOOL_NAME}\` or \`${GIVE_UP_TOOL_NAME}\`.`, `Either call \`${FINISH_TOOL_NAME}\` with your final answer, or call \`${GIVE_UP_TOOL_NAME}\` with a reason if you cannot determine the answer.`].join(" ");
+}
+/**
+* Build the user-facing prompt text for a `session.skill('<name>')` call,
+* where `<name>` is a name registered in the session's skill registry.
+*
+* The system prompt's "Available Skills" list tells the model where the
+* skill lives (`.agents/skills/<name>/SKILL.md`) and how to run it (read
+* the file, follow its instructions). The per-call message just names
+* the skill plus any arguments — no inlined body, no path hint.
+*/
+function buildSkillByNamePrompt(name, args, schema) {
+	const parts = [`Run the skill named "${name}".`];
+	if (args && Object.keys(args).length > 0) parts.push("", "Arguments:", JSON.stringify(args, null, 2));
+	if (schema) parts.push(buildResultFooter());
+	return parts.join("\n");
+}
+/**
+* Build the user-facing prompt text for a `session.skill('<path>')` call,
+* where `<path>` is a relative path under `.agents/skills/` (e.g.
+* `'triage/reproduce.md'`). Path-based references bypass the registry
+* — the skill isn't named in the system prompt's "Available Skills"
+* list — so we hand the model the resolved absolute path explicitly.
+*/
+function buildSkillByPathPrompt(relPath, resolvedPath, args, schema) {
+	const parts = [
+		`Run the skill file \`${relPath}\`.`,
+		"",
+		`The file can be found at ${resolvedPath}.`
+	];
+	if (args && Object.keys(args).length > 0) parts.push("", "Arguments:", JSON.stringify(args, null, 2));
+	if (schema) parts.push(buildResultFooter());
+	return parts.join("\n");
+}
+function buildPromptText(text, schema) {
+	const parts = [text];
+	if (schema) parts.push(buildResultFooter());
+	return parts.join("\n");
+}
+/**
+* Produce the per-call `finish` and `give_up` tool pair for a given valibot schema.
+*
+* - `finish`'s parameters are derived from the schema via `@valibot/to-json-schema`.
+*   Non-object top-level schemas are wrapped in a `{ result: <schema> }` envelope
+*   because every LLM provider expects tool arguments to be a top-level object.
+* - Pi-agent-core validates args against the JSON Schema before calling `execute`.
+*   Inside `execute` we additionally run `valibot.safeParse` to enforce
+*   valibot-specific refinements and to obtain the parsed output (transforms,
+*   defaults, coercion). On valibot failure we throw — pi-agent-core surfaces
+*   the throw as a tool-error tool-result, so the LLM can self-correct.
+* - First successful `finish` (or `give_up`) call wins. Subsequent calls return
+*   a tool error rather than throwing, to keep the conversation transcript natural.
+* - Successful calls set `terminate: true` so pi-agent-core ends the loop after
+*   the current tool batch.
+*/
+function createResultTools(schema) {
+	let outcome = { type: "pending" };
+	const wrapped = needsEnvelope(schema);
+	const innerJsonSchema = stripJsonSchemaMeta(toJsonSchema(schema, { errorMode: "ignore" }));
+	const finishParameters = wrapped ? {
+		type: "object",
+		properties: { result: innerJsonSchema },
+		required: ["result"],
+		additionalProperties: false
+	} : innerJsonSchema;
+	return {
+		tools: [{
+			name: FINISH_TOOL_NAME,
+			label: FINISH_TOOL_NAME,
+			description: `Call this tool when the task is complete. Provide your final answer as the arguments. The arguments are validated against the required schema; if validation fails you will receive an error message and may try again. The first successful \`${FINISH_TOOL_NAME}\` call wins — once the task is finished, do not call \`${FINISH_TOOL_NAME}\` again.`,
+			parameters: finishParameters,
+			async execute(_toolCallId, params) {
+				if (outcome.type !== "pending") return alreadyDoneToolError(outcome);
+				const candidate = wrapped ? params.result : params;
+				const parsed = v.safeParse(schema, candidate);
+				if (!parsed.success) {
+					const issues = parsed.issues.map((i) => i.message + (i.path ? ` (at ${formatIssuePath(i.path)})` : "")).join("; ");
+					throw new Error(`Result does not match the required schema: ${issues}. Please call \`${FINISH_TOOL_NAME}\` again with a corrected payload.`);
+				}
+				outcome = {
+					type: "finished",
+					value: parsed.output
+				};
+				return {
+					content: [{
+						type: "text",
+						text: "Result accepted. The task is complete."
+					}],
+					details: {
+						tool: FINISH_TOOL_NAME,
+						result: parsed.output
+					},
+					terminate: true
+				};
+			}
+		}, {
+			name: GIVE_UP_TOOL_NAME,
+			label: GIVE_UP_TOOL_NAME,
+			description: "Call this tool only if you have determined that you cannot complete the task or cannot produce a result that conforms to the required schema. Provide a clear `reason`. This ends the task with a failure.",
+			parameters: {
+				type: "object",
+				properties: { reason: {
+					type: "string",
+					minLength: 1,
+					description: "A clear explanation of why the task cannot be completed."
+				} },
+				required: ["reason"],
+				additionalProperties: false
+			},
+			async execute(_toolCallId, params) {
+				if (outcome.type !== "pending") return alreadyDoneToolError(outcome);
+				const reason = params.reason;
+				if (typeof reason !== "string" || reason.trim().length === 0) throw new Error(`\`${GIVE_UP_TOOL_NAME}\` requires a non-empty \`reason\` string.`);
+				outcome = {
+					type: "gave_up",
+					reason
+				};
+				return {
+					content: [{
+						type: "text",
+						text: "Acknowledged."
+					}],
+					details: {
+						tool: GIVE_UP_TOOL_NAME,
+						reason
+					},
+					terminate: true
+				};
+			}
+		}],
+		getOutcome: () => outcome
+	};
+}
+function needsEnvelope(schema) {
+	return schema.type !== "object";
+}
+function stripJsonSchemaMeta(jsonSchema) {
+	const { $schema: _schema, ...rest } = jsonSchema;
+	return rest;
+}
+function formatIssuePath(path) {
+	return path.map((p) => typeof p.key === "number" ? `[${p.key}]` : `.${String(p.key ?? "?")}`).join("").replace(/^\./, "");
+}
+function alreadyDoneToolError(outcome) {
+	return {
+		content: [{
+			type: "text",
+			text: `${outcome.type === "finished" ? "A result was already submitted; the task is complete." : "The task was already given up; it cannot be resumed."} Do not call this tool again.`
+		}],
+		details: { alreadyDone: true }
+	};
+}
+/**
+* Thrown when the LLM calls the `give_up` tool, indicating it cannot produce a
+* result that conforms to the required schema. Carries the LLM-supplied
+* `reason` and the assistant transcript leading up to the give-up.
+*/
+var ResultUnavailableError = class extends Error {
+	constructor(reason, assistantText) {
+		super(`The agent gave up: ${reason}`);
+		this.reason = reason;
+		this.assistantText = assistantText;
+		this.name = "ResultUnavailableError";
+	}
+};
+
+//#endregion
+export { buildSkillByPathPrompt as a, createTools as c, parseFrontmatterFile as d, resolveSkillFilePath as f, buildSkillByNamePrompt as i, formatBashResult as l, buildPromptText as n, createResultTools as o, skillsDirIn as p, buildResultFollowUpPrompt as r, BUILTIN_TOOL_NAMES as s, ResultUnavailableError as t, discoverSessionContext as u };