skilld-harness 3.1.0 → 3.3.0

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { DEFAULT_OUTPUT_POLICY, isSkillName, loadSkilldMaintainedSkill, normalizeOutputPath, resolveWithin } from "./_chunks/skills.mjs";
 import { lstat, mkdir, open, opendir, realpath, rename, rm, rmdir, unlink, writeFile } from "node:fs/promises";
-import { dirname, join, posix, relative, resolve, sep } from "node:path";
+import { basename, dirname, join, posix, relative, resolve, sep } from "node:path";
 import { HarnessAgent } from "@ai-sdk/harness/agent";
 import { createHash, randomUUID } from "node:crypto";
 import { parseDocument } from "yaml";
@@ -275,14 +275,16 @@ const promoteSkill = async (rootDir, name, files, attempts) => {
 			if (backupCleanup instanceof Error) warnings.push(`Previous Skill cleanup failed at ${backup}: ${backupCleanup.message}`);
 		}
 		return ok({
-			_tag: "GeneratedSkill",
-			name,
-			outputDir: target,
-			files: files.map((file) => ({
-				path: file.path,
-				bytes: file.content.byteLength
-			})),
-			sourceAttempts: attempts,
+			skill: {
+				_tag: "GeneratedSkill",
+				name,
+				outputDir: target,
+				files: files.map((file) => ({
+					path: file.path,
+					bytes: file.content.byteLength
+				})),
+				sourceAttempts: attempts
+			},
 			warnings
 		});
 	}
@@ -301,14 +303,65 @@ const promoteSkill = async (rootDir, name, files, attempts) => {
 		cause
 	});
 };
-const allowedFrontmatter = /* @__PURE__ */ new Set([
-	"name",
-	"description",
-	"license",
-	"compatibility",
-	"metadata",
-	"allowed-tools"
-]);
+const searchCommand = /\b(?:git grep|grep|rg)\b/;
+const inlineCode = /`([^`\n]+)`/g;
+const fencedBlock = /```[^\n]*\n[\s\S]*?```/g;
+const denial = /\b(no|not|none|never|absent|missing|lacks|without|instead|rather|empty|undeclared|unavailable|nothing)\b|\bdoes ?n[o']t\b/i;
+const creation = /\b(?:copy|create|write|generate)\b/i;
+function fencedBlocks(markdown) {
+	return markdown.match(fencedBlock) ?? [];
+}
+function proseParagraphs(markdown) {
+	return markdown.replace(fencedBlock, "").split(/\n[ \t]*\n/).map((paragraph) => paragraph.replace(/\n/g, " ").trim()).filter((paragraph) => paragraph.length > 0);
+}
+const pathExtension = /\.(?:md|mdx|json|jsonc|ts|tsx|mts|cts|js|mjs|cjs|jsx|vue|svelte|txt|yml|yaml|toml|html|css|scss|rs|py|go|sh|lock|env|csv|xml)$/i;
+const versionShape = /^v?\d+(?:\.\d+)*$/i;
+const productName = /^[A-Za-z][A-Za-z0-9_]*\.[A-Za-z0-9]+$/;
+function pathCandidate(token) {
+	if (token.length === 0 || /\s/.test(token)) return null;
+	if (/^[-$#<{[]/.test(token)) return null;
+	if (token.includes("://") || /[()|;&"'@:]/.test(token)) return null;
+	const trimmed = token.replace(/^\.\//, "").replace(/\/+$/, "");
+	if (trimmed.length === 0 || trimmed.startsWith("..")) return null;
+	if (versionShape.test(trimmed) || productName.test(trimmed) || /\/\d+$/.test(trimmed)) return null;
+	if (!trimmed.includes("/") && !pathExtension.test(trimmed)) return null;
+	return trimmed;
+}
+function literalPrefix(candidate) {
+	const wildcard = candidate.search(/[*?]/);
+	if (wildcard === -1) return candidate;
+	return candidate.slice(0, wildcard).replace(/[^/]*$/, "").replace(/\/+$/, "");
+}
+function resolves(candidate, known) {
+	if (known.has(candidate)) return true;
+	const prefix = literalPrefix(candidate);
+	if (prefix.length === 0) return true;
+	for (const path of known) {
+		if (path.startsWith(`${candidate}.`)) return true;
+		if (path === prefix || path.startsWith(`${prefix}/`)) return true;
+	}
+	return false;
+}
+function checkProjectSkill(input) {
+	const issues = [];
+	const known = /* @__PURE__ */ new Set([...input.projectPaths, ...input.outputPaths]);
+	const unknown = /* @__PURE__ */ new Set();
+	for (const paragraph of proseParagraphs(input.markdown)) {
+		if (denial.test(paragraph) || creation.test(paragraph)) continue;
+		for (const match of paragraph.matchAll(inlineCode)) {
+			const candidate = pathCandidate(match[1].trim());
+			if (candidate !== null && !resolves(candidate, known)) unknown.add(candidate);
+		}
+	}
+	for (const path of [...unknown].sort()) issues.push(`SKILL.md points at a path the project does not contain: ${path}.`);
+	const inline = [...input.markdown.matchAll(inlineCode)].map((match) => match[1]);
+	const commands = [...fencedBlocks(input.markdown), ...inline].join("\n");
+	if (!searchCommand.test(commands)) issues.push("SKILL.md must give the Agent at least one search command it can repeat.");
+	return issues;
+}
+const allowedFrontmatter = /* @__PURE__ */ new Set(["name", "description"]);
+const packageSkillLineLimit = 500;
+const packageSkillReferenceLimit = 8;
 const invalid = (issues) => err({
 	_tag: "InvalidSkill",
 	message: "Skill output failed deterministic checks.",
@@ -321,13 +374,44 @@ function decodeText(content) {
 		return null;
 	}
 }
-const isStringMap = (value) => value !== null && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((item) => typeof item === "string");
-const validateGeneratedSkill = (name, files) => {
+function linkTargets(markdown) {
+	const targets = /* @__PURE__ */ new Set();
+	const add = (raw) => {
+		const target = raw.trim().replace(/^<|>$/g, "").split(/\s/)[0].replace(/[#?].*$/, "").replace(/^\.\//, "");
+		if (target.length > 0) targets.add(target);
+	};
+	for (const match of markdown.matchAll(/\]\(([^)\n]+)\)/g)) add(match[1]);
+	for (const match of markdown.matchAll(/^\s*\[[^\]\n]+\]:\s*(\S+)/gm)) add(match[1]);
+	for (const match of markdown.matchAll(/`([^`\n]+)`/g)) add(match[1]);
+	return targets;
+}
+function lineCount(text) {
+	const lines = text.split("\n");
+	return lines.at(-1) === "" ? lines.length - 1 : lines.length;
+}
+function structureIssues(markdown, files, contract) {
+	const issues = [];
+	const referencePaths = files.map((file) => file.path).filter((path) => path.startsWith("references/")).sort();
+	if (contract._tag === "PackageSkill") {
+		const lines = lineCount(markdown);
+		if (lines >= packageSkillLineLimit) issues.push(`SKILL.md must stay under ${packageSkillLineLimit} lines; it has ${lines}.`);
+		if (referencePaths.length > packageSkillReferenceLimit) issues.push(`A package Skill may write at most ${packageSkillReferenceLimit} reference files; it wrote ${referencePaths.length}.`);
+	}
+	const linked = linkTargets(markdown);
+	for (const path of referencePaths) if (!linked.has(path)) issues.push(`SKILL.md must link ${path}.`);
+	return issues;
+}
+const validateGeneratedSkill = (name, files, contract) => {
 	const issues = [];
 	const skillFiles = files.filter((file) => file.path === "SKILL.md");
 	if (skillFiles.length !== 1) return invalid(["Output must contain exactly one SKILL.md file."]);
 	const source = decodeText(skillFiles[0].content);
 	if (source === null) return invalid(["SKILL.md must contain valid UTF-8 text."]);
+	if (contract._tag === "ProjectSkill") issues.push(...checkProjectSkill({
+		markdown: source,
+		projectPaths: contract.projectPaths,
+		outputPaths: files.map((file) => file.path)
+	}));
 	const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
 	if (!match) return invalid(["SKILL.md must start with YAML frontmatter."]);
 	if (match[2]?.trim().length === 0) issues.push("SKILL.md instructions must not be empty.");
@@ -344,10 +428,7 @@ const validateGeneratedSkill = (name, files) => {
 	if (frontmatter.name !== name) issues.push("Frontmatter name must match the Skill directory name.");
 	if (typeof frontmatter.name !== "string" || !isSkillName(frontmatter.name)) issues.push("Frontmatter name is invalid.");
 	if (typeof frontmatter.description !== "string" || frontmatter.description.trim().length === 0 || frontmatter.description.length > 1024) issues.push("Frontmatter description must contain 1 to 1024 characters.");
-	if (frontmatter.license !== void 0 && typeof frontmatter.license !== "string") issues.push("Frontmatter license must be a string.");
-	if (frontmatter.compatibility !== void 0 && (typeof frontmatter.compatibility !== "string" || frontmatter.compatibility.length > 500)) issues.push("Frontmatter compatibility must be a string of at most 500 characters.");
-	if (frontmatter.metadata !== void 0 && !isStringMap(frontmatter.metadata)) issues.push("Frontmatter metadata must map strings to strings.");
-	if (frontmatter["allowed-tools"] !== void 0 && typeof frontmatter["allowed-tools"] !== "string") issues.push("Frontmatter allowed-tools must be a string.");
+	issues.push(...structureIssues(source, files, contract));
 	return issues.length === 0 ? ok(void 0) : invalid(issues);
 };
 const findingLevels = /* @__PURE__ */ new Set([
@@ -391,6 +472,9 @@ const validateSkillReview = (files) => {
 		findings
 	});
 };
+function skippedFileWarnings(skipped, policy) {
+	return skipped.map((file) => `Source file ${file.path} was left out: ${file.bytes} bytes exceeds the ${policy.maxSourceFileBytes} byte file limit.`);
+}
 const ignoredNames = /* @__PURE__ */ new Set([
 	".git",
 	".hg",
@@ -428,7 +512,10 @@ async function collectHostDirectory(directory, policy, sourceLabel = directory,
 	if (canonicalRoot instanceof Error) return unavailable("Source directory cannot be resolved.", canonicalRoot);
 	if (canonicalRoot !== root) return unavailable("Source path must not pass through a symbolic link.");
 	const files = [];
+	const skippedFiles = [];
 	let totalBytes = 0;
+	const relativePath = (absolute) => relative(root, absolute).split(sep).join("/");
+	const entryUnavailable = (absolute, message, cause, fix) => unavailable(`${message}: ${relativePath(absolute)}.${fix === void 0 ? "" : ` ${fix}`}`, cause);
 	const walk = async (current) => {
 		if (signal?.aborted) return cancelled();
 		const canonicalCurrent = await realpath(current).catch((error) => error);
@@ -440,28 +527,32 @@ async function collectHostDirectory(directory, policy, sourceLabel = directory,
 			if (ignoredNames.has(entry.name)) continue;
 			const absolute = join(current, entry.name);
 			const stat = await lstat(absolute).catch((error) => error);
-			if (stat instanceof Error) return unavailable("Source entry cannot be read.", stat);
-			if (stat.isSymbolicLink()) return unavailable("Source contains a symbolic link.");
+			if (stat instanceof Error) return entryUnavailable(absolute, "Source entry cannot be read", stat);
+			if (stat.isSymbolicLink()) return entryUnavailable(absolute, "Source contains a symbolic link", void 0, "Remove the link, or pass a clean export such as a `git archive` of the directory.");
 			if (stat.isDirectory()) {
 				const nested = await walk(absolute);
 				if (nested._tag === "Err") return nested;
 				continue;
 			}
-			if (!stat.isFile()) return unavailable("Source contains a special file.");
-			const path = relative(root, absolute).split(sep).join("/");
+			if (!stat.isFile()) return entryUnavailable(absolute, "Source contains a special file");
+			const path = relativePath(absolute);
 			const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW).catch((error) => error);
-			if (handle instanceof Error) return unavailable("Source file cannot be opened without following links.", handle);
+			if (handle instanceof Error) return entryUnavailable(absolute, "Source file cannot be opened without following links", handle);
 			const openedStat = await handle.stat().catch((error) => error);
 			if (openedStat instanceof Error) {
 				await handle.close();
-				return unavailable("Source file cannot be inspected.", openedStat);
+				return entryUnavailable(absolute, "Source file cannot be inspected", openedStat);
 			}
 			if (!openedStat.isFile() || openedStat.dev !== stat.dev || openedStat.ino !== stat.ino) {
 				await handle.close();
-				return unavailable("Source file changed during collection.");
+				return entryUnavailable(absolute, "Source file changed during collection");
 			}
 			if (openedStat.size > policy.maxSourceFileBytes) {
 				await handle.close();
+				skippedFiles.push({
+					path,
+					bytes: openedStat.size
+				});
 				continue;
 			}
 			if (files.length >= policy.maxSourceFiles) {
@@ -474,8 +565,8 @@ async function collectHostDirectory(directory, policy, sourceLabel = directory,
 			}
 			const content = await handle.readFile().catch((error) => error);
 			await handle.close();
-			if (content instanceof Error) return unavailable("Source file cannot be read.", content);
-			if (content.byteLength !== openedStat.size) return unavailable("Source file changed during collection.");
+			if (content instanceof Error) return entryUnavailable(absolute, "Source file cannot be read", content);
+			if (content.byteLength !== openedStat.size) return entryUnavailable(absolute, "Source file changed during collection");
 			if (signal?.aborted) return cancelled();
 			files.push({
 				path,
@@ -489,8 +580,10 @@ async function collectHostDirectory(directory, policy, sourceLabel = directory,
 	if (walked._tag === "Err") return walked;
 	if (files.length === 0) return unavailable("Source directory has no usable files.");
 	files.sort((left, right) => left.path.localeCompare(right.path));
+	skippedFiles.sort((left, right) => left.path.localeCompare(right.path));
 	return ok({
 		files,
+		skippedFiles,
 		attempts: [{
 			source: sourceLabel,
 			status: "used"
@@ -558,6 +651,7 @@ async function extractArchive(compressed, policy, layout) {
 	source.on("error", (error) => gunzip.destroy(error));
 	source.pipe(gunzip);
 	const files = [];
+	const skippedFiles = [];
 	const seen = /* @__PURE__ */ new Set();
 	const maxArchiveBytes = policy.maxSourceBytes + (policy.maxSourceFiles + 2) * blockBytes * 2;
 	let archiveBytes = 0;
@@ -645,7 +739,7 @@ async function extractArchive(compressed, policy, layout) {
 					};
 					continue;
 				}
-				if (type !== "0" && type !== "\0") return unavailable$1("Source archive contains a linked or special entry.");
+				if (type !== "0" && type !== "\0") return unavailable$1(`Source archive contains a linked or special entry: ${nextPath ?? headerPath}.`);
 				const path = archivePath(nextPath ?? headerPath, layout);
 				nextPath = null;
 				if (path === null) return unavailable$1("Source archive contains an invalid path.");
@@ -654,6 +748,10 @@ async function extractArchive(compressed, policy, layout) {
 				fileEntries += 1;
 				if (fileEntries > policy.maxSourceFiles) return unavailable$1("Source archive contains too many files.");
 				if (size <= policy.maxSourceFileBytes && totalBytes + size > policy.maxSourceBytes) return unavailable$1("Source archive exceeds the total byte limit.");
+				if (size > policy.maxSourceFileBytes) skippedFiles.push({
+					path,
+					bytes: size
+				});
 				entry = {
 					kind: size > policy.maxSourceFileBytes ? "skip" : "file",
 					path,
@@ -671,7 +769,11 @@ async function extractArchive(compressed, policy, layout) {
 	if (entry !== null || pending.some((byte) => byte !== 0) || !ended) return unavailable$1("Source archive ended before its final entry.");
 	if (files.length === 0) return unavailable$1("Source archive has no usable files.");
 	files.sort((left, right) => left.path.localeCompare(right.path));
-	return ok(files);
+	skippedFiles.sort((left, right) => left.path.localeCompare(right.path));
+	return ok({
+		files,
+		skippedFiles
+	});
 }
 const packageSpecPattern = /^(@[^/@]+\/[^/@]+|[^/@]+)(?:@(\S+))?$/;
 const exactVersionPattern = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[\da-z-]+(?:\.[\da-z-]+)*)?(?:\+[\da-z-]+(?:\.[\da-z-]+)*)?$/i;
@@ -949,7 +1051,8 @@ async function prepareNpmPackage(spec, policy, fetchClient, signal) {
 		return unavailable(message, [...attempts, skipped(version.dist.tarball, message)]);
 	}
 	attempts.push(used(version.dist.tarball));
-	let files = [...extracted.value];
+	let files = [...extracted.value.files];
+	let skippedFiles = [...extracted.value.skippedFiles];
 	const repositoryArchive = githubArchiveUrl(version.repository ?? repository, version.gitHead);
 	const available = remainingPolicy(policy, files);
 	if (repositoryArchive !== null && available === null) attempts.push(skipped(repositoryArchive, "Prepared package files reached the source limit."));
@@ -964,7 +1067,11 @@ async function prepareNpmPackage(spec, policy, fetchClient, signal) {
 			const repositoryFiles = await extractResponse(fetchedRepository.value, available, "github");
 			if (repositoryFiles._tag === "Err") attempts.push(skipped(repositoryArchive, repositoryFiles.error.message));
 			else {
-				files = [...files, ...repositoryFiles.value.map((file) => ({
+				files = [...files, ...repositoryFiles.value.files.map((file) => ({
+					...file,
+					path: posix.join("repository", file.path)
+				}))];
+				skippedFiles = [...skippedFiles, ...repositoryFiles.value.skippedFiles.map((file) => ({
 					...file,
 					path: posix.join("repository", file.path)
 				}))];
@@ -973,8 +1080,10 @@ async function prepareNpmPackage(spec, policy, fetchClient, signal) {
 		}
 	}
 	files.sort((left, right) => left.path.localeCompare(right.path));
+	skippedFiles.sort((left, right) => left.path.localeCompare(right.path));
 	return ok({
 		files,
+		skippedFiles,
 		attempts,
 		npmResolution: {
 			package: parsed.name,
@@ -982,6 +1091,61 @@ async function prepareNpmPackage(spec, policy, fetchClient, signal) {
 		}
 	});
 }
+function addCount(total, count) {
+	return total === void 0 ? count : count === void 0 ? total : total + count;
+}
+function isPromiseLike(value) {
+	return (typeof value === "object" || typeof value === "function") && value !== null && typeof value.then === "function";
+}
+function createRunLog(onEvent) {
+	const warnings = [];
+	const eventFailures = /* @__PURE__ */ new Set();
+	let usage = {
+		inputTokens: void 0,
+		cachedInputTokens: void 0,
+		outputTokens: void 0
+	};
+	let steps = 0;
+	const fail = (cause) => {
+		eventFailures.add(`onEvent failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+	};
+	return {
+		emit: (event) => {
+			if (event._tag === "StepFinish") {
+				steps += 1;
+				usage = {
+					inputTokens: addCount(usage.inputTokens, event.usage.inputTokens),
+					cachedInputTokens: addCount(usage.cachedInputTokens, event.usage.cachedInputTokens),
+					outputTokens: addCount(usage.outputTokens, event.usage.outputTokens)
+				};
+			}
+			if (!onEvent) return;
+			try {
+				const returned = onEvent(event);
+				if (isPromiseLike(returned)) Promise.resolve(returned).catch(fail);
+			} catch (cause) {
+				fail(cause);
+			}
+		},
+		warn: (warning) => warnings.push(warning),
+		settle: (total, count) => {
+			usage = total;
+			steps = count;
+		},
+		report: () => ({
+			usage,
+			steps,
+			warnings: [...warnings, ...eventFailures]
+		})
+	};
+}
+function toUsage(usage) {
+	return {
+		inputTokens: usage.inputTokens,
+		cachedInputTokens: usage.inputTokenDetails.cacheReadTokens,
+		outputTokens: usage.outputTokens
+	};
+}
 function cancelled() {
 	return err({
 		_tag: "Cancelled",
@@ -1040,6 +1204,7 @@ async function prepareRun(input, policy, fetchClient, signal) {
 			skillName: "generate-project-skill",
 			outputName: input.destination.name,
 			source: source.value,
+			sourceDir: "",
 			current: current.value,
 			destination: input.destination
 		});
@@ -1049,7 +1214,8 @@ async function prepareRun(input, policy, fetchClient, signal) {
 		return source._tag === "Err" ? source : ok({
 			skillName: "review-skill",
 			outputName: "review",
-			source: source.value
+			source: source.value,
+			sourceDir: basename(input.skillDir)
 		});
 	}
 	if (input.source._tag === "NpmPackage") {
@@ -1062,6 +1228,7 @@ async function prepareRun(input, policy, fetchClient, signal) {
 			skillName: "generate-package-skill",
 			outputName: input.destination.name,
 			source: source.value,
+			sourceDir: "",
 			current: current.value,
 			destination: input.destination
 		});
@@ -1086,6 +1253,7 @@ async function prepareRun(input, policy, fetchClient, signal) {
 		skillName: "generate-package-skill",
 		outputName: input.destination.name,
 		source: source.value,
+		sourceDir: "",
 		current: current.value,
 		destination: input.destination
 	});
@@ -1098,8 +1266,11 @@ function requestContent(skill) {
 function renderRequest(template, sourcePath, currentSkillPath, outputPath, skillName) {
 	return template.replaceAll("{{SOURCE_PATH}}", sourcePath).replaceAll("{{CURRENT_SKILL_PATH}}", currentSkillPath).replaceAll("{{OUTPUT_PATH}}", outputPath).replaceAll("{{SKILL_NAME}}", skillName);
 }
+function sourcePathOf(active, prepared) {
+	return posix.join(active.workDir, "input/source", prepared.sourceDir);
+}
 async function writePreparedSource(active, prepared, signal) {
-	const sourcePath = posix.join(active.workDir, "input/source");
+	const sourcePath = sourcePathOf(active, prepared);
 	const reset = await active.sandbox.run({
 		command: "rm -rf -- \"$SKILLD_INPUT\" \"$SKILLD_OUTPUT\" && mkdir -p -- \"$SKILLD_INPUT\"",
 		env: {
@@ -1123,6 +1294,7 @@ async function writePreparedSource(active, prepared, signal) {
 		path: posix.join(active.workDir, "input/source-manifest.json"),
 		content: `${JSON.stringify({
 			sourceAttempts: prepared.source.attempts,
+			skippedFiles: prepared.source.skippedFiles,
 			npmResolution: prepared.source.npmResolution,
 			hasCurrentSkill: prepared.current !== void 0
 		}, null, 2)}\n`,
@@ -1145,17 +1317,40 @@ function createSkillHarness(options) {
 	const sandboxConfig = { ...options.sandboxConfig };
 	const harness = options.harness;
 	const sandbox = options.sandbox;
-	return { run: async (input, runOptions = {}) => {
+	return { run: (input, runOptions = {}) => runSkill(input, runOptions) };
+	async function runSkill(input, runOptions) {
+		const log = createRunLog(runOptions.onEvent);
+		const outcome = await runLogged(input, runOptions, log);
+		const report = log.report();
+		return outcome._tag === "Ok" ? {
+			_tag: "Ok",
+			value: outcome.value,
+			report
+		} : {
+			_tag: "Err",
+			error: outcome.error,
+			report
+		};
+	}
+	async function runLogged(input, runOptions, log) {
 		const parsed = parseSkillRun(input);
 		if (parsed._tag === "Err") return parsed;
 		const prepared = await prepareRun(parsed.value, policy, fetchClient, runOptions.signal);
 		if (prepared._tag === "Err") return prepared;
+		for (const warning of skippedFileWarnings(prepared.value.source.skippedFiles, policy)) log.warn(warning);
 		const skill = await loadSkilldMaintainedSkill(prepared.value.skillName);
+		const sandboxSession = await sandbox.createSession({ abortSignal: runOptions.signal }).then(ok, (cause) => err(cause));
+		if (sandboxSession._tag === "Err") return toAgentError(sandboxSession.error, runOptions.signal);
+		const result = await runAgent(prepared.value, skill, sandboxSession.value, log, runOptions.signal);
+		const destroyed = await Promise.resolve(sandboxSession.value.destroy()).then(() => void 0, (cause) => cause);
+		if (destroyed !== void 0) log.warn(`Sandbox session cleanup failed: ${destroyed instanceof Error ? destroyed.message : String(destroyed)}`);
+		return result;
+	}
+	async function runAgent(prepared, skill, sandboxSession, log, signal) {
 		let active;
 		const userOnSession = sandboxConfig.onSession;
 		const agent = new HarnessAgent({
 			harness,
-			sandbox,
 			skills: [skill],
 			permissionMode: "allow-all",
 			sandboxConfig: {
@@ -1165,44 +1360,79 @@ function createSkillHarness(options) {
 						sandbox: sessionOptions.session,
 						workDir: sessionOptions.sessionWorkDir
 					};
-					await writePreparedSource(active, prepared.value, runOptions.signal);
+					await writePreparedSource(active, prepared, signal);
 					await userOnSession?.(sessionOptions);
 				}
 			}
 		});
-		const sessionResult = await agent.createSession({ abortSignal: runOptions.signal }).then(ok, (cause) => err(cause));
-		if (sessionResult._tag === "Err") return toAgentError(sessionResult.error, runOptions.signal);
+		const sessionResult = await agent.createSession({
+			sandboxSession,
+			abortSignal: signal
+		}).then(ok, (cause) => err(cause));
+		if (sessionResult._tag === "Err") return toAgentError(sessionResult.error, signal);
 		const session = sessionResult.value;
 		try {
 			if (!active) return err({
 				_tag: "AgentFailed",
 				message: "Harness did not provide its sandbox session."
 			});
-			const sourcePath = posix.join(active.workDir, "input/source");
+			const sourcePath = sourcePathOf(active, prepared);
 			const currentSkillPath = posix.join(active.workDir, "input/current-skill");
-			const outputPath = posix.join(active.workDir, "skilld-output", prepared.value.outputName);
-			const prompt = renderRequest(requestContent(skill), sourcePath, currentSkillPath, outputPath, prepared.value.outputName);
+			const outputPath = posix.join(active.workDir, "skilld-output", prepared.outputName);
+			const prompt = renderRequest(requestContent(skill), sourcePath, currentSkillPath, outputPath, prepared.outputName);
+			let step = 0;
 			const generated = await agent.generate({
 				session,
 				prompt,
-				abortSignal: runOptions.signal
+				abortSignal: signal,
+				onStepStart: (event) => {
+					step = event.stepNumber;
+					log.emit({
+						_tag: "StepStart",
+						step
+					});
+				},
+				onToolExecutionStart: ({ toolCall }) => {
+					log.emit({
+						_tag: "ToolCall",
+						step,
+						toolName: toolCall.toolName,
+						toolCallId: toolCall.toolCallId,
+						input: toolCall.input
+					});
+				},
+				onStepEnd: (result) => {
+					log.emit({
+						_tag: "StepFinish",
+						step: result.stepNumber,
+						finishReason: result.finishReason,
+						usage: toUsage(result.usage)
+					});
+				}
 			}).then(ok, (cause) => err(cause));
-			if (generated._tag === "Err") return toAgentError(generated.error, runOptions.signal);
-			if (runOptions.signal?.aborted) return cancelled();
-			const collected = await collectSandboxOutput(active.sandbox, outputPath, policy, runOptions.signal);
+			if (generated._tag === "Err") return toAgentError(generated.error, signal);
+			log.settle(toUsage(generated.value.totalUsage), generated.value.steps.length);
+			if (signal?.aborted) return cancelled();
+			const collected = await collectSandboxOutput(active.sandbox, outputPath, policy, signal);
 			if (collected._tag === "Err") return collected;
-			if (prepared.value.skillName === "review-skill") return validateSkillReview(collected.value);
-			const validated = validateGeneratedSkill(prepared.value.outputName, collected.value);
+			if (prepared.skillName === "review-skill") return validateSkillReview(collected.value);
+			const validated = validateGeneratedSkill(prepared.outputName, collected.value, prepared.skillName === "generate-project-skill" ? {
+				_tag: "ProjectSkill",
+				projectPaths: prepared.source.files.map((file) => file.path)
+			} : { _tag: "PackageSkill" });
 			if (validated._tag === "Err") return validated;
-			if (!prepared.value.destination) return err({
+			if (!prepared.destination) return err({
 				_tag: "InvalidInput",
 				message: "Skill destination is required."
 			});
-			return promoteSkill(prepared.value.destination.rootDir, prepared.value.destination.name, collected.value, prepared.value.source.attempts);
+			const promoted = await promoteSkill(prepared.destination.rootDir, prepared.destination.name, collected.value, prepared.source.attempts);
+			if (promoted._tag === "Err") return promoted;
+			for (const warning of promoted.value.warnings) log.warn(warning);
+			return ok(promoted.value.skill);
 		} finally {
 			await session.destroy();
 		}
-	} };
+	}
 }
 export { createSkillHarness };