skilld-harness 3.2.0 → 3.3.0

package/README.md

@@ -11,6 +11,12 @@ It then promotes generated Skills with an atomic directory rename.
 pnpm add skilld-harness @ai-sdk/harness ws zod
 ```
 
+Add one Harness adapter. The examples below use OpenCode:
+
+```sh
+pnpm add @ai-sdk/harness-opencode
+```
+
 Use Node 22 or newer.
 The sandbox must provide POSIX `sh`, `rm`, `mkdir`, and GNU `find`.
 
@@ -35,7 +41,46 @@ const result = await skillHarness.run({
 ```
 
 Every run returns a tagged `Ok` or `Err` value.
-An installed Skill can include cleanup warnings after promotion.
+The input tag sets the `Ok` value: `PackageSkill` and `ProjectSkill` return a `GeneratedSkill`, and `ReviewSkill` returns a `SkillReview`.
+Both `Ok` and `Err` carry a `report`, so a failed run still reports its cost.
+`report.usage` holds input, cached input, and output tokens.
+`report.steps` is the number of model calls.
+A token count is `undefined` when the adapter does not report it.
+If the run fails before the Agent starts, `steps` is 0.
+`report.warnings` names each source file the Harness left out for size, each `onEvent` failure, and each cleanup problem.
+An `InvalidSkill` error lists each failed output check in `issues`.
+
+The Harness checks the rules that the generation Skills state:
+
+- The frontmatter contains only `name` and `description`.
+- `SKILL.md` links every file under `references/`, by a Markdown link or an inline code path.
+- A package Skill keeps `SKILL.md` under 500 lines and writes at most eight reference files.
+- A project Skill points only at project files and gives at least one search command.
+
+A run can take several minutes. Pass `onEvent` to follow the Agent:
+
+```ts
+import type { SkillRun } from 'skilld-harness'
+import { createSkillHarness } from 'skilld-harness'
+
+declare const skillHarness: ReturnType<typeof createSkillHarness>
+declare const input: SkillRun
+
+await skillHarness.run(input, {
+  onEvent: (event) => {
+    if (event._tag === 'ToolCall')
+      console.log(`step ${event.step}: ${event.toolName}`)
+    if (event._tag === 'StepFinish')
+      console.log(`step ${event.step} used ${event.usage.outputTokens} output tokens`)
+  },
+})
+```
+
+The events are `StepStart`, `ToolCall`, and `StepFinish`. Steps count from 0.
+A `ToolCall` event arrives after the tool returns.
+If the adapter runs the tool itself, the event arrives when its step ends.
+The run does not wait for a promise that `onEvent` returns.
+If `onEvent` throws, or its promise or thenable rejects, the run continues, and `report.warnings` carries the error.
 
 Pass `fetch` to `createSkillHarness` when the host owns HTTP access.
 The default adapter uses the Node global fetch implementation.
@@ -63,11 +108,33 @@ The session runs in a new temporary directory and exposes one port on
 `127.0.0.1` for bridge-backed Harness adapters. `destroy` kills every process
 the session started and removes the directory.
 
+Each session gets its own `HOME`, XDG directories, and `TMPDIR` under the
+session root. Harness state, the adapter bootstrap, and installed Skills stay
+inside the session, and `destroy` removes them. The Agent does not load your own
+agent configuration, Skills, or MCP servers. Configure the adapter explicitly,
+for example through `openCodeConfig`.
+
+Processes receive a minimal environment: `PATH`, locale, terminal, and proxy
+variables. Pass any other variable through the `env` option. The adapter reads
+its credentials from your environment and hands them to the processes it starts.
+For OpenCode Go, set `OPENCODE_API_KEY`. The adapter does not read the key that
+`opencode auth login` stores.
+
+Each session installs the adapter bootstrap again, because nothing persists
+between sessions. With OpenCode, that is about 200 MB of downloads per run.
+
 | Option | Default | Effect |
 | --- | --- | --- |
 | `root` | a new temporary directory | Session root directory. |
 | `port` | a free port from the operating system | Bridge port. |
 | `keepRoot` | `false` | Keep the session root after `destroy`. |
+| `env` | none | More environment variables for every process. |
+
+The adapter prints this warning on every local run:
+"credential brokering does not work. Falling back to less secure credential forwarding."
+It is expected. The local sandbox cannot rewrite requests, so the adapter
+gives the raw API key to the processes it starts. If the Agent must not see the key,
+use a hosted sandbox provider that supports request transformations.
 
 The local sandbox needs POSIX `sh` at `/bin/sh` and GNU `find`, because the
 Harness inventories output with `find -printf`. It runs on Linux. It does not
@@ -80,10 +147,14 @@ policy, which stops at 64 files. Raise it on `createSkillHarness`:
 createSkillHarness({ harness, sandbox, outputPolicy: { maxOutputFiles: 512 } })
 ```
 
-**It applies no isolation.** Every process reaches the whole computer and the
-caller's environment. Use it for your own Skills on your own computer or on a
-self-hosted runner. Use a hosted sandbox provider when the Harness must contain
-what it runs.
+**It applies no process isolation.** A separate `HOME` keeps state apart. It does
+not stop a process from reading or writing any file your user account can reach.
+Use it for your own Skills on your own computer or on a self-hosted runner. Use a
+hosted sandbox provider when the Harness must contain what it runs.
+
+A `LocalPackage` source copies the working tree, including uncommitted and
+untracked files. A symbolic link anywhere in it stops the run, and the error
+names the link. To use only committed files, pass a `git archive` export.
 
 ## Visible Skills
 
@@ -101,3 +172,8 @@ const skill = await loadSkilldMaintainedSkill('generate-project-skill')
 
 The same Skill files remain usable directly through an Agent.
 Direct runs remain user reviewed.
+
+## Develop against the local package
+
+`package.json` exports `dist` files. Run `pnpm build` in `packages/harness`
+before you link the package into another project. A stale `dist` fails on import.

package/dist/_chunks/skills.mjs

@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { readFile, readdir } from "node:fs/promises";
 import { dirname, isAbsolute, posix, relative, resolve, sep } from "node:path";
 import { parseDocument } from "yaml";
 import { fileURLToPath } from "node:url";
@@ -29,16 +29,27 @@ function parseManifest(source) {
 	if (new Set(value).size !== value.length) throw new Error("skilld-maintained Skill manifest contains duplicate names.");
 	return Object.freeze([...value]);
 }
-async function locateFile(path) {
-	for (const root of skillRoots) {
-		const value = await readFile(resolve(root, path), "utf8").catch((error) => {
+async function locateFile(path, roots) {
+	for (const root of roots) {
+		const content = await readFile(resolve(root, path), "utf8").catch((error) => {
 			if (error.code === "ENOENT") return null;
 			throw error;
 		});
-		if (value !== null) return value;
+		if (content !== null) return {
+			root,
+			content
+		};
 	}
 	throw new Error(`skilld-maintained Skill file is missing: ${path}`);
 }
+async function listFiles(dir, prefix = "") {
+	const entries = await readdir(resolve(dir, prefix), { withFileTypes: true });
+	return (await Promise.all(entries.map(async (entry) => {
+		const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+		if (entry.isDirectory()) return listFiles(dir, path);
+		return entry.isFile() ? [path] : [];
+	}))).flat().sort();
+}
 function splitSkill(source) {
 	const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
 	if (!match) throw new Error("skilld-maintained Skill frontmatter is invalid.");
@@ -54,24 +65,30 @@ function splitSkill(source) {
 		content: match[2]
 	};
 }
-async function harnessSkillNames() {
-	return parseManifest(await locateFile("harness-skills.json"));
+async function harnessSkillNames(roots = skillRoots) {
+	const { content } = await locateFile("harness-skills.json", roots);
+	return parseManifest(content);
 }
-async function skilldMaintainedSkillNames() {
-	return parseManifest(await locateFile("skilld-maintained-skills.json"));
+async function skilldMaintainedSkillNames(roots = skillRoots) {
+	const { content } = await locateFile("skilld-maintained-skills.json", roots);
+	return parseManifest(content);
 }
-async function loadSkilldMaintainedSkill(name) {
-	if (!(await skilldMaintainedSkillNames()).includes(name)) throw new Error(`Unknown skilld-maintained Skill: ${name}`);
-	const skill = splitSkill(await locateFile(`${name}/SKILL.md`));
+async function loadSkilldMaintainedSkill(name, roots = skillRoots) {
+	if (!(await skilldMaintainedSkillNames(roots)).includes(name)) throw new Error(`Unknown skilld-maintained Skill: ${name}`);
+	const { root, content: source } = await locateFile(`${name}/SKILL.md`, roots);
+	const skill = splitSkill(source);
 	if (skill.name !== name) throw new Error(`skilld-maintained Skill name does not match its directory: ${name}`);
-	if (!(await harnessSkillNames()).includes(name)) return skill;
-	const request = await locateFile(`${name}/assets/harness-request.md`);
+	if (!(await harnessSkillNames(roots)).includes(name)) return skill;
+	const skillDir = resolve(root, name);
+	const paths = (await listFiles(skillDir)).filter((path) => path !== "SKILL.md");
+	if (!paths.includes("assets/harness-request.md")) throw new Error(`skilld-maintained Skill file is missing: ${name}/assets/harness-request.md`);
+	const files = await Promise.all(paths.map(async (path) => ({
+		path,
+		content: await readFile(resolve(skillDir, path), "utf8")
+	})));
 	return {
 		...skill,
-		files: [{
-			path: "assets/harness-request.md",
-			content: request
-		}]
+		files
 	};
 }
 const DEFAULT_OUTPUT_POLICY = Object.freeze({

package/dist/_chunks/skills.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"skills.mjs","names":[],"sources":["../../src/internal/paths.ts","../../src/skills.ts"],"sourcesContent":["import { isAbsolute, posix, relative, resolve, sep } from 'node:path'\n\nexport function isSkillName(value: string): boolean {\n  return value.length >= 1\n    && value.length <= 64\n    && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value)\n}\n\nexport function resolveWithin(root: string, candidate: string): string | null {\n  const absoluteRoot = resolve(root)\n  const absoluteCandidate = resolve(root, candidate)\n  const fromRoot = relative(absoluteRoot, absoluteCandidate)\n  if (fromRoot === '' || (!fromRoot.startsWith(`..${sep}`) && fromRoot !== '..' && !isAbsolute(fromRoot)))\n    return absoluteCandidate\n  return null\n}\n\nexport function normalizeOutputPath(value: string): string | null {\n  if (value.length === 0 || value.includes('\\\\') || value.includes('\\0') || posix.isAbsolute(value))\n    return null\n  const normalized = posix.normalize(value)\n  if (normalized === '.' || normalized === '..' || normalized.startsWith('../') || normalized !== value)\n    return null\n  return normalized\n}\n","import type { HarnessV1Skill } from '@ai-sdk/harness'\nimport { readFile } from 'node:fs/promises'\nimport { dirname, resolve } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { parseDocument } from 'yaml'\nimport { isSkillName } from './internal/paths.ts'\n\nconst skillRoots = [\n  resolve(dirname(fileURLToPath(import.meta.url)), '../skills'),\n  resolve(dirname(fileURLToPath(import.meta.url)), 'skills'),\n  resolve(dirname(fileURLToPath(import.meta.url)), '../../../skills'),\n] as const\n\nfunction parseManifest(source: string): ReadonlyArray<string> {\n  const value = JSON.parse(source) as unknown\n  if (!Array.isArray(value) || value.some(name => typeof name !== 'string' || !isSkillName(name)))\n    throw new Error('skilld-maintained Skill manifest is invalid.')\n  if (new Set(value).size !== value.length)\n    throw new Error('skilld-maintained Skill manifest contains duplicate names.')\n  return Object.freeze([...value])\n}\n\nasync function locateFile(path: string): Promise<string> {\n  for (const root of skillRoots) {\n    const value = await readFile(resolve(root, path), 'utf8').catch((error) => {\n      if ((error as NodeJS.ErrnoException).code === 'ENOENT')\n        return null\n      throw error\n    })\n    if (value !== null)\n      return value\n  }\n  throw new Error(`skilld-maintained Skill file is missing: ${path}`)\n}\n\nfunction splitSkill(source: string): { name: string, description: string, content: string } {\n  const match = source.match(/^---\\r?\\n([\\s\\S]*?)\\r?\\n---\\r?\\n([\\s\\S]*)$/)\n  if (!match)\n    throw new Error('skilld-maintained Skill frontmatter is invalid.')\n\n  const document = parseDocument(match[1]!, { uniqueKeys: true })\n  if (document.errors.length > 0)\n    throw new Error('skilld-maintained Skill frontmatter is invalid.')\n  const frontmatter = document.toJS() as unknown\n  if (!frontmatter || typeof frontmatter !== 'object')\n    throw new Error('skilld-maintained Skill frontmatter is invalid.')\n\n  const values = frontmatter as Record<string, unknown>\n  if (typeof values.name !== 'string' || typeof values.description !== 'string')\n    throw new Error('skilld-maintained Skill frontmatter is incomplete.')\n\n  return { name: values.name, description: values.description, content: match[2]! }\n}\n\nexport async function harnessSkillNames(): Promise<ReadonlyArray<string>> {\n  const source = await locateFile('harness-skills.json')\n  return parseManifest(source)\n}\n\nexport async function skilldMaintainedSkillNames(): Promise<ReadonlyArray<string>> {\n  const source = await locateFile('skilld-maintained-skills.json')\n  return parseManifest(source)\n}\n\nexport async function loadSkilldMaintainedSkill(name: string): Promise<HarnessV1Skill> {\n  const names = await skilldMaintainedSkillNames()\n  if (!names.includes(name))\n    throw new Error(`Unknown skilld-maintained Skill: ${name}`)\n\n  const source = await locateFile(`${name}/SKILL.md`)\n  const skill = splitSkill(source)\n  if (skill.name !== name)\n    throw new Error(`skilld-maintained Skill name does not match its directory: ${name}`)\n\n  const harnessSkills = await harnessSkillNames()\n  if (!harnessSkills.includes(name))\n    return skill\n\n  const request = await locateFile(`${name}/assets/harness-request.md`)\n  return {\n    ...skill,\n    files: [{ path: 'assets/harness-request.md', content: request }],\n  }\n}\n\nexport const DEFAULT_OUTPUT_POLICY = Object.freeze({\n  maxSourceFiles: 2_000,\n  maxSourceFileBytes: 512 * 1024,\n  maxSourceBytes: 50 * 1024 * 1024,\n  maxOutputFiles: 64,\n  maxOutputFileBytes: 512 * 1024,\n  maxOutputBytes: 4 * 1024 * 1024,\n})\n"],"mappings":"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"}
+{"version":3,"file":"skills.mjs","names":[],"sources":["../../src/internal/paths.ts","../../src/skills.ts"],"sourcesContent":["import { isAbsolute, posix, relative, resolve, sep } from 'node:path'\n\nexport function isSkillName(value: string): boolean {\n  return value.length >= 1\n    && value.length <= 64\n    && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value)\n}\n\nexport function resolveWithin(root: string, candidate: string): string | null {\n  const absoluteRoot = resolve(root)\n  const absoluteCandidate = resolve(root, candidate)\n  const fromRoot = relative(absoluteRoot, absoluteCandidate)\n  if (fromRoot === '' || (!fromRoot.startsWith(`..${sep}`) && fromRoot !== '..' && !isAbsolute(fromRoot)))\n    return absoluteCandidate\n  return null\n}\n\nexport function normalizeOutputPath(value: string): string | null {\n  if (value.length === 0 || value.includes('\\\\') || value.includes('\\0') || posix.isAbsolute(value))\n    return null\n  const normalized = posix.normalize(value)\n  if (normalized === '.' || normalized === '..' || normalized.startsWith('../') || normalized !== value)\n    return null\n  return normalized\n}\n","import type { HarnessV1Skill } from '@ai-sdk/harness'\nimport { readdir, readFile } from 'node:fs/promises'\nimport { dirname, resolve } from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { parseDocument } from 'yaml'\nimport { isSkillName } from './internal/paths.ts'\n\nconst skillRoots = [\n  resolve(dirname(fileURLToPath(import.meta.url)), '../skills'),\n  resolve(dirname(fileURLToPath(import.meta.url)), 'skills'),\n  resolve(dirname(fileURLToPath(import.meta.url)), '../../../skills'),\n] as const\n\nfunction parseManifest(source: string): ReadonlyArray<string> {\n  const value = JSON.parse(source) as unknown\n  if (!Array.isArray(value) || value.some(name => typeof name !== 'string' || !isSkillName(name)))\n    throw new Error('skilld-maintained Skill manifest is invalid.')\n  if (new Set(value).size !== value.length)\n    throw new Error('skilld-maintained Skill manifest contains duplicate names.')\n  return Object.freeze([...value])\n}\n\n/** Reads the first root that has `path`, and returns that root with the file. */\nasync function locateFile(path: string, roots: ReadonlyArray<string>): Promise<{ root: string, content: string }> {\n  for (const root of roots) {\n    const content = await readFile(resolve(root, path), 'utf8').catch((error) => {\n      if ((error as NodeJS.ErrnoException).code === 'ENOENT')\n        return null\n      throw error\n    })\n    if (content !== null)\n      return { root, content }\n  }\n  throw new Error(`skilld-maintained Skill file is missing: ${path}`)\n}\n\n/** Lists every regular file under `dir`, nested folders included, as sorted POSIX paths. */\nasync function listFiles(dir: string, prefix = ''): Promise<ReadonlyArray<string>> {\n  const entries = await readdir(resolve(dir, prefix), { withFileTypes: true })\n  const nested = await Promise.all(entries.map(async (entry) => {\n    const path = prefix ? `${prefix}/${entry.name}` : entry.name\n    if (entry.isDirectory())\n      return listFiles(dir, path)\n    return entry.isFile() ? [path] : []\n  }))\n  return nested.flat().sort()\n}\n\nfunction splitSkill(source: string): { name: string, description: string, content: string } {\n  const match = source.match(/^---\\r?\\n([\\s\\S]*?)\\r?\\n---\\r?\\n([\\s\\S]*)$/)\n  if (!match)\n    throw new Error('skilld-maintained Skill frontmatter is invalid.')\n\n  const document = parseDocument(match[1]!, { uniqueKeys: true })\n  if (document.errors.length > 0)\n    throw new Error('skilld-maintained Skill frontmatter is invalid.')\n  const frontmatter = document.toJS() as unknown\n  if (!frontmatter || typeof frontmatter !== 'object')\n    throw new Error('skilld-maintained Skill frontmatter is invalid.')\n\n  const values = frontmatter as Record<string, unknown>\n  if (typeof values.name !== 'string' || typeof values.description !== 'string')\n    throw new Error('skilld-maintained Skill frontmatter is incomplete.')\n\n  return { name: values.name, description: values.description, content: match[2]! }\n}\n\nexport async function harnessSkillNames(roots: ReadonlyArray<string> = skillRoots): Promise<ReadonlyArray<string>> {\n  const { content } = await locateFile('harness-skills.json', roots)\n  return parseManifest(content)\n}\n\nexport async function skilldMaintainedSkillNames(roots: ReadonlyArray<string> = skillRoots): Promise<ReadonlyArray<string>> {\n  const { content } = await locateFile('skilld-maintained-skills.json', roots)\n  return parseManifest(content)\n}\n\n/**\n * Loads one skilld-maintained Skill. A Harness Skill also carries every supporting file\n * in its folder, nested `scripts/` and `references/` folders included, so the Agent can read them.\n * `roots` lists the folders to search, first match wins.\n */\nexport async function loadSkilldMaintainedSkill(name: string, roots: ReadonlyArray<string> = skillRoots): Promise<HarnessV1Skill> {\n  const names = await skilldMaintainedSkillNames(roots)\n  if (!names.includes(name))\n    throw new Error(`Unknown skilld-maintained Skill: ${name}`)\n\n  const { root, content: source } = await locateFile(`${name}/SKILL.md`, roots)\n  const skill = splitSkill(source)\n  if (skill.name !== name)\n    throw new Error(`skilld-maintained Skill name does not match its directory: ${name}`)\n\n  const harnessSkills = await harnessSkillNames(roots)\n  if (!harnessSkills.includes(name))\n    return skill\n\n  const skillDir = resolve(root, name)\n  const paths = (await listFiles(skillDir)).filter(path => path !== 'SKILL.md')\n  if (!paths.includes('assets/harness-request.md'))\n    throw new Error(`skilld-maintained Skill file is missing: ${name}/assets/harness-request.md`)\n  const files = await Promise.all(paths.map(async path => ({\n    path,\n    content: await readFile(resolve(skillDir, path), 'utf8'),\n  })))\n  return { ...skill, files }\n}\n\nexport const DEFAULT_OUTPUT_POLICY = Object.freeze({\n  maxSourceFiles: 2_000,\n  maxSourceFileBytes: 512 * 1024,\n  maxSourceBytes: 50 * 1024 * 1024,\n  maxOutputFiles: 64,\n  maxOutputFileBytes: 512 * 1024,\n  maxOutputBytes: 4 * 1024 * 1024,\n})\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -32,8 +32,37 @@ interface SkillOutputPolicy {
   readonly maxOutputFileBytes: number;
   readonly maxOutputBytes: number;
 }
+/** Token counts the Agent reported. A count is undefined when the Harness adapter does not report it. */
+interface SkillRunUsage {
+  /** Every input token, cached ones included. */
+  readonly inputTokens: number | undefined;
+  /** Input tokens read from the provider cache. */
+  readonly cachedInputTokens: number | undefined;
+  readonly outputTokens: number | undefined;
+}
+/** Progress of the Agent during a Skill run. A step is one model call. Steps count from 0. */
+type SkillRunEvent = {
+  readonly _tag: 'StepStart';
+  readonly step: number;
+} | {
+  readonly _tag: 'ToolCall';
+  readonly step: number;
+  readonly toolName: string;
+  readonly toolCallId: string;
+  readonly input: unknown;
+} | {
+  readonly _tag: 'StepFinish';
+  readonly step: number;
+  readonly finishReason: string;
+  readonly usage: SkillRunUsage;
+};
 interface SkillRunOptions {
   readonly signal?: AbortSignal;
+  /**
+   * Receives progress events while the Agent works. The run does not wait for a returned promise or thenable.
+   * If it throws or its promise rejects, the run continues and the result report carries a warning.
+   */
+  readonly onEvent?: (event: SkillRunEvent) => void;
 }
 interface SkillFile {
   readonly path: string;
@@ -50,8 +79,6 @@ interface GeneratedSkill {
   readonly outputDir: string;
   readonly files: ReadonlyArray<SkillFile>;
   readonly sourceAttempts: ReadonlyArray<SourceAttempt>;
-  /** Cleanup problems after the new Skill reached its destination. */
-  readonly warnings: ReadonlyArray<string>;
 }
 interface SkillReviewFinding {
   readonly level: 'error' | 'warning' | 'note';
@@ -97,15 +124,38 @@ type SkillRunError = {
   readonly _tag: 'Cancelled';
   readonly message: string;
 };
-type SkillRunResult = {
+/** The value each Skill run input returns. */
+interface SkillRunValues {
+  readonly PackageSkill: GeneratedSkill;
+  readonly ProjectSkill: GeneratedSkill;
+  readonly ReviewSkill: SkillReview;
+}
+/**
+ * What a Skill run cost, and what went wrong beside its outcome.
+ * Every result carries one, so a failed run still reports its cost.
+ */
+interface SkillRunReport {
+  /** Tokens the Agent used. A run that failed before the Agent started reports no counts. */
+  readonly usage: SkillRunUsage;
+  /** Model calls the Agent made. */
+  readonly steps: number;
+  /**
+   * Source files the Harness left out for size, onEvent failures, and cleanup
+   * problems after the run.
+   */
+  readonly warnings: ReadonlyArray<string>;
+}
+type SkillRunResult<Tag extends SkillRun['_tag'] = SkillRun['_tag']> = {
   readonly _tag: 'Ok';
-  readonly value: GeneratedSkill | SkillReview;
+  readonly value: SkillRunValues[Tag];
+  readonly report: SkillRunReport;
 } | {
   readonly _tag: 'Err';
   readonly error: SkillRunError;
+  readonly report: SkillRunReport;
 };
 interface SkillHarness {
-  readonly run: (input: SkillRun, options?: SkillRunOptions) => Promise<SkillRunResult>;
+  readonly run: <Run extends SkillRun>(input: Run, options?: SkillRunOptions) => Promise<SkillRunResult<Run['_tag']>>;
 }
 interface CreateSkillHarnessOptions {
   readonly harness: HarnessV1;
@@ -118,5 +168,5 @@ interface CreateSkillHarnessOptions {
   readonly fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 }
 export declare function createSkillHarness(options: CreateSkillHarnessOptions): SkillHarness;
-export type { CreateSkillHarnessOptions, GeneratedSkill, PackageSource, SkillDestination, SkillFile, SkillHarness, SkillOutputPolicy, SkillReview, SkillReviewFinding, SkillRun, SkillRunError, SkillRunOptions, SkillRunResult, SourceAttempt };
+export type { CreateSkillHarnessOptions, GeneratedSkill, PackageSource, SkillDestination, SkillFile, SkillHarness, SkillOutputPolicy, SkillReview, SkillReviewFinding, SkillRun, SkillRunError, SkillRunEvent, SkillRunOptions, SkillRunReport, SkillRunResult, SkillRunUsage, SkillRunValues, SourceAttempt };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/harness.ts"],"mappings":";;UAGiB;WACN;WACA;;KAGC;WAEC;WACA;;WAGA;WACA;WACA;;KAGD;WAEC;WACA,QAAQ;WACR,aAAa;;WAGb;WACA;WACA,aAAa;;WAGb;WACA;;UAGI;WACN;WACA;WACA;WACA;WACA;WACA;;UAGM;WACN,SAAS;;UAGH;WACN;WACA;;UAGM;WACN;WACA;WACA;;UAGM;WACN;WACA;WACA;WACA,OAAO,cAAc;WACrB,gBAAgB,cAAc;;WAE9B,UAAU;;UAGJ;WACN;WACA;WACA;WACA;;UAGM;WACN;WACA;WACA,UAAU,cAAc;;KAGvB;WACK;WAA+B;;WAEjC;WACA;WACA,UAAU,cAAc;WACxB;;WAEE;WAA8B;WAA0B;;WACxD;WAA+B;WAA0B,QAAQ;;WACjE;WAAmC;WAA0B;;WAC7D;WAA6B;WAA0B;;WACvD;WAAkC;WAA0B;WAAuB;;WACnF;WAA4B;;KAEjC;WACK;WAAqB,OAAO,iBAAiB;;WAC7C;WAAsB,OAAO;;UAE7B;WACN,MAAM,OAAO,UAAU,UAAU,oBAAoB,QAAQ;;UAGvD;WACN,SAAS;;WAET,SAAS;;WAET,gBAAgB;WAChB,eAAe,QAAQ;;WAEvB,SAAS,gBAAgB,MAAM,SAAS,OAAO,gBAAgB,QAAQ;;wBCkElE,mBAAmB,SAAS,4BAA4B"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/harness.ts"],"mappings":";;UAGiB;WACN;WACA;;KAGC;WAEC;WACA;;WAGA;WACA;WACA;;KAGD;WAEC;WACA,QAAQ;WACR,aAAa;;WAGb;WACA;WACA,aAAa;;WAGb;WACA;;UAGI;WACN;WACA;WACA;WACA;WACA;WACA;;;UAIM;;WAEN;;WAEA;WACA;;;KAIC;WACK;WAA4B;;WAE9B;WACA;WACA;WACA;WACA;;WAGA;WACA;WACA;WACA,OAAO;;UAGL;WACN,SAAS;;;;;WAKT,WAAW,OAAO;;UAGZ;WACN;WACA;;UAGM;WACN;WACA;WACA;;UAGM;WACN;WACA;WACA;WACA,OAAO,cAAc;WACrB,gBAAgB,cAAc;;UAGxB;WACN;WACA;WACA;WACA;;UAGM;WACN;WACA;WACA,UAAU,cAAc;;KAGvB;WACK;WAA+B;;WAEjC;WACA;WACA,UAAU,cAAc;WACxB;;WAEE;WAA8B;WAA0B;;WACxD;WAA+B;WAA0B,QAAQ;;WACjE;WAAmC;WAA0B;;WAC7D;WAA6B;WAA0B;;WACvD;WAAkC;WAA0B;WAAuB;;WACnF;WAA4B;;;UAG5B;WACN,cAAc;WACd,cAAc;WACd,aAAa;;;;;;UAOP;;WAEN,OAAO;;WAEP;;;;;WAKA,UAAU;;KAGT,eAAe,YAAY,mBAAmB;WACzC;WAAqB,OAAO,eAAe;WAAe,QAAQ;;WAClE;WAAsB,OAAO;WAAwB,QAAQ;;UAE7D;WACN,MAAM,YAAY,UAAU,OAAO,KAAK,UAAU,oBAAoB,QAAQ,eAAe;;UAGvF;WACN,SAAS;;WAET,SAAS;;WAET,gBAAgB;WAChB,eAAe,QAAQ;;WAEvB,SAAS,gBAAgB,MAAM,SAAS,OAAO,gBAAgB,QAAQ;;wBC0GlE,mBAAmB,SAAS,4BAA4B"}