@juicesharp/rpiv-workflow 1.14.0

package/outcomes/collectors/directory-path.ts

@@ -0,0 +1,40 @@
+/**
+ * Directory-path collector — `transcriptPathCollector` wrapped with the
+ * common `<dir>/<filename>.<ext>` regex idiom so authors don't write
+ * the regex themselves.
+ *
+ * Use when the convention is "all outputs land under one folder"
+ * (`docs/adr/`, `outputs/`, `.scratch/runs/`). Universal — every
+ * project has directories.
+ *
+ * For more exotic shapes (per-run nesting, multiple acceptable
+ * directories, custom filename rules) drop down to
+ * `transcriptPathCollector({ pattern })` and supply the regex directly.
+ */
+
+import type { ArtifactCollector } from "../../output-spec.js";
+import { transcriptPathCollector } from "./transcript-path.js";
+
+export interface DirectoryPathCollectorOpts {
+	/** cwd-relative directory the agent's announced path must sit under (e.g. `"docs/adr"`). */
+	dir: string;
+	/**
+	 * Optional file extension filter (no leading dot — `"md"`, `"json"`,
+	 * etc.). Defaults to any common alphanumeric extension.
+	 */
+	ext?: string;
+}
+
+export function directoryPathCollector(opts: DirectoryPathCollectorOpts): ArtifactCollector {
+	if (typeof opts.dir !== "string" || opts.dir.length === 0) {
+		throw new Error("directoryPathCollector: `dir` is required and must be a non-empty string");
+	}
+	const escapedDir = escapeRegex(opts.dir);
+	const extPart = opts.ext ? escapeRegex(opts.ext) : "[a-zA-Z0-9]+";
+	const pattern = new RegExp(`${escapedDir}/[\\w.-]+\\.${extPart}`, "g");
+	return transcriptPathCollector({ pattern });
+}
+
+function escapeRegex(s: string): string {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/outcomes/collectors/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Bundled collectors — universal primitives + ergonomic wrappers +
+ * composition helpers. Re-exported through `outcomes/index.ts` and
+ * surfaced to authors via the package's top-level barrel.
+ *
+ * The framework ships ONLY host-agnostic collectors — no Pi tool-name
+ * defaults, no `.rpiv/artifacts/` defaults, no domain helpers
+ * (Linear/S3/Notion). Convention layers live in sibling packages
+ * (`rpiv-pi` ships `rpivArtifactCollector` / `rpivBucketCollector`).
+ */
+
+export { type DirectoryPathCollectorOpts, directoryPathCollector } from "./directory-path.js";
+export { type ToolCall, type ToolCallCollectorOpts, toolCallCollector } from "./tool-call.js";
+export { type TranscriptPathCollectorOpts, transcriptPathCollector } from "./transcript-path.js";
+export { unionCollectors } from "./union.js";
+export { type UrlCollectorOpts, urlCollector } from "./url.js";
+export {
+	type WorkspaceDiffCollectorOpts,
+	type WorkspaceDiffSnapshot,
+	workspaceDiffCollector,
+} from "./workspace-diff.js";

package/outcomes/collectors/tool-call.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from "vitest";
+import { fs } from "../../handle.js";
+import type { BranchEntry } from "../../transcript.js";
+import { toolCallCollector } from "./tool-call.js";
+
+const asstWithTools = (parts: Array<{ name: string; input: Record<string, unknown> }>): BranchEntry => ({
+	type: "message",
+	message: {
+		role: "assistant",
+		content: parts.map((p) => ({ type: "tool_use", name: p.name, input: p.input })),
+	},
+});
+
+const ctxOf = (branch: BranchEntry[]) => ({
+	cwd: "/tmp",
+	runId: "test",
+	stageIndex: 0,
+	state: {} as never,
+	branch,
+	branchOffset: undefined,
+	snapshot: undefined,
+	skill: "test",
+});
+
+describe("toolCallCollector", () => {
+	it("throws when match or toArtifact are missing", () => {
+		// @ts-expect-error — intentional misuse
+		expect(() => toolCallCollector({})).toThrow(/required functions/);
+	});
+
+	it("emits one artifact per matching tool call in branch order", async () => {
+		const collector = toolCallCollector({
+			match: (tc) => tc.name === "write_file",
+			toArtifact: (tc) => ({ handle: fs(String(tc.input.path)), role: "written" }),
+		});
+		const ctx = ctxOf([
+			asstWithTools([
+				{ name: "write_file", input: { path: "a.ts" } },
+				{ name: "read_file", input: { path: "ignored.ts" } },
+				{ name: "write_file", input: { path: "b.ts" } },
+			]),
+		]);
+		const result = await collector.collect(ctx);
+		expect(result.kind).toBe("ok");
+		if (result.kind !== "ok") return;
+		expect(result.artifacts).toEqual([
+			{ handle: { kind: "fs", path: "a.ts" }, role: "written" },
+			{ handle: { kind: "fs", path: "b.ts" }, role: "written" },
+		]);
+	});
+
+	it("returns ok+empty when nothing matches (runner decides whether to fatal)", async () => {
+		const collector = toolCallCollector({
+			match: (tc) => tc.name === "write_file",
+			toArtifact: (tc) => ({ handle: fs(String(tc.input.path)) }),
+		});
+		const ctx = ctxOf([asstWithTools([{ name: "read_file", input: { path: "x.ts" } }])]);
+		const result = await collector.collect(ctx);
+		expect(result.kind).toBe("ok");
+		if (result.kind !== "ok") return;
+		expect(result.artifacts).toEqual([]);
+	});
+
+	it("toArtifact returning undefined skips the call", async () => {
+		const collector = toolCallCollector({
+			match: () => true,
+			toArtifact: (tc) => (tc.input.path ? { handle: fs(String(tc.input.path)) } : undefined),
+		});
+		const ctx = ctxOf([
+			asstWithTools([
+				{ name: "bash", input: { cmd: "ls" } }, // no path → skipped
+				{ name: "write_file", input: { path: "a.ts" } },
+			]),
+		]);
+		const result = await collector.collect(ctx);
+		expect(result.kind === "ok" && result.artifacts).toEqual([{ handle: { kind: "fs", path: "a.ts" } }]);
+	});
+
+	it("respects branchOffset", async () => {
+		const collector = toolCallCollector({
+			match: (tc) => tc.name === "write_file",
+			toArtifact: (tc) => ({ handle: fs(String(tc.input.path)) }),
+		});
+		const branch = [
+			asstWithTools([{ name: "write_file", input: { path: "prior.ts" } }]),
+			asstWithTools([{ name: "write_file", input: { path: "current.ts" } }]),
+		];
+		const ctx = { ...ctxOf(branch), branchOffset: 1 };
+		const result = await collector.collect(ctx);
+		expect(result.kind === "ok" && result.artifacts).toEqual([{ handle: { kind: "fs", path: "current.ts" } }]);
+	});
+
+	it("multi-tool match — one collector covers write_file + edit", async () => {
+		const collector = toolCallCollector({
+			match: (tc) => tc.name === "write_file" || tc.name === "edit",
+			toArtifact: (tc) => ({ handle: fs(String(tc.input.path ?? tc.input.target_file)) }),
+		});
+		const ctx = ctxOf([
+			asstWithTools([
+				{ name: "write_file", input: { path: "new.ts" } },
+				{ name: "edit", input: { target_file: "old.ts" } },
+			]),
+		]);
+		const result = await collector.collect(ctx);
+		expect(result.kind === "ok" && result.artifacts.map((a) => a.handle)).toEqual([
+			{ kind: "fs", path: "new.ts" },
+			{ kind: "fs", path: "old.ts" },
+		]);
+	});
+});

package/outcomes/collectors/tool-call.ts

@@ -0,0 +1,63 @@
+/**
+ * Tool-call collector — observes assistant tool_use parts in the branch
+ * and turns each into an Artifact via the author-supplied mappers.
+ *
+ * Universal: knows nothing about specific tool names. Authors wire
+ * `match(tc)` to pick which calls are interesting (often
+ * `tc.name === "write_file"`) and `toArtifact(tc)` to extract the
+ * Artifact (most commonly an `fs` handle pulled from the tool input).
+ * Multiple matching calls produce multiple artifacts in branch order.
+ *
+ * Far more reliable than transcript-text scanning: tool-use blocks
+ * are the agent's actual recorded actions, not its narration of them.
+ *
+ * Returns `ok` with an empty list when no matching calls fire — the
+ * runner's `enforceCompletionContract` then halts for produces
+ * (the stage promised an output and didn't deliver) or passes through
+ * for side-effect (chain inherits prior). The collector itself doesn't
+ * second-guess that policy.
+ */
+
+import type { Artifact } from "../../handle.js";
+import type { ArtifactCollector } from "../../output-spec.js";
+import { defineCollector } from "../../output-spec.js";
+import { iterToolUses } from "../../transcript.js";
+
+export interface ToolCall {
+	name: string;
+	input: Record<string, unknown>;
+}
+
+export interface ToolCallCollectorOpts {
+	/**
+	 * Predicate over the tool call. Return true to consider this call,
+	 * false to skip. No default — match semantics are entirely
+	 * caller-defined (e.g. `(tc) => tc.name === "write_file"`).
+	 */
+	match(tc: ToolCall): boolean;
+	/**
+	 * Map a matched tool call to an Artifact. Return undefined to skip
+	 * (useful when the tool's input doesn't carry a path, or the path
+	 * fails a sanity check). The returned Artifact's handle is what
+	 * downstream stages see on `output.artifacts`.
+	 */
+	toArtifact(tc: ToolCall): Artifact | undefined;
+}
+
+export function toolCallCollector(opts: ToolCallCollectorOpts): ArtifactCollector {
+	if (typeof opts.match !== "function" || typeof opts.toArtifact !== "function") {
+		throw new Error("toolCallCollector: `match` and `toArtifact` are required functions");
+	}
+	const { match, toArtifact } = opts;
+	return defineCollector({
+		collect: (ctx) => {
+			const artifacts: Artifact[] = [];
+			for (const tc of iterToolUses(ctx.branch, ctx.branchOffset)) {
+				if (!match(tc)) continue;
+				const artifact = toArtifact(tc);
+				if (artifact) artifacts.push(artifact);
+			}
+			return { kind: "ok", artifacts };
+		},
+	});
+}

package/outcomes/collectors/transcript-path.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import type { BranchEntry } from "../../transcript.js";
+import { transcriptPathCollector } from "./transcript-path.js";
+
+const asst = (text: string): BranchEntry => ({
+	type: "message",
+	message: { role: "assistant", content: [{ type: "text", text }] },
+});
+
+const ctxOf = (branch: BranchEntry[]) => ({
+	cwd: "/tmp",
+	runId: "test",
+	stageIndex: 0,
+	state: {} as never,
+	branch,
+	branchOffset: undefined,
+	snapshot: undefined,
+	skill: "test",
+});
+
+describe("transcriptPathCollector", () => {
+	it("throws at construction when pattern is missing", () => {
+		// @ts-expect-error — intentional misuse
+		expect(() => transcriptPathCollector({})).toThrow(/pattern.*required/);
+	});
+
+	it("emits one fs artifact for the last regex match in assistant text", async () => {
+		const collector = transcriptPathCollector({ pattern: /docs\/adr\/[\w-]+\.md/g });
+		const ctx = ctxOf([asst("Wrote docs/adr/0001-init.md, see docs/adr/0002-types.md")]);
+		const result = await collector.collect(ctx);
+		expect(result.kind).toBe("ok");
+		if (result.kind !== "ok") return;
+		expect(result.artifacts).toEqual([{ handle: { kind: "fs", path: "docs/adr/0002-types.md" }, role: "primary" }]);
+	});
+
+	it("fatals when no match is found (produces contract)", async () => {
+		const collector = transcriptPathCollector({ pattern: /docs\/adr\/[\w-]+\.md/g });
+		const ctx = ctxOf([asst("nothing here")]);
+		const result = await collector.collect(ctx);
+		expect(result.kind).toBe("fatal");
+		if (result.kind !== "fatal") return;
+		expect(result.message).toMatch(/finished without producing a path matching/);
+	});
+
+	it("scans reverse — returns the match from the latest assistant message", async () => {
+		const collector = transcriptPathCollector({ pattern: /docs\/[\w-]+\.md/g });
+		const ctx = ctxOf([asst("first: docs/old.md"), asst("final: docs/new.md")]);
+		const result = await collector.collect(ctx);
+		expect(result.kind === "ok" && result.artifacts[0]?.handle).toEqual({ kind: "fs", path: "docs/new.md" });
+	});
+
+	it("respects branchOffset (continue-policy: skips prior-stage prefix)", async () => {
+		const collector = transcriptPathCollector({ pattern: /docs\/[\w-]+\.md/g });
+		const branch = [asst("prior: docs/old.md"), asst("current: docs/new.md")];
+		const ctx = { ...ctxOf(branch), branchOffset: 1 };
+		const result = await collector.collect(ctx);
+		expect(result.kind === "ok" && result.artifacts[0]?.handle).toEqual({ kind: "fs", path: "docs/new.md" });
+	});
+
+	it("ignores user messages and non-message entries", async () => {
+		const collector = transcriptPathCollector({ pattern: /docs\/[\w-]+\.md/g });
+		const ctx = ctxOf([
+			{ type: "message", message: { role: "user", content: [{ type: "text", text: "see docs/from-user.md" }] } },
+			{ type: "thinking_level_change" },
+			asst("agent: docs/from-agent.md"),
+		]);
+		const result = await collector.collect(ctx);
+		expect(result.kind === "ok" && result.artifacts[0]?.handle).toEqual({ kind: "fs", path: "docs/from-agent.md" });
+	});
+});

package/outcomes/collectors/transcript-path.ts

@@ -0,0 +1,53 @@
+/**
+ * Transcript-path collector — the lowest-level text-scan primitive.
+ *
+ * Scans the assistant's spoken text (in reverse) for `pattern`, emits
+ * the LAST match as a single `fs` artifact. Caller supplies the regex
+ * verbatim — the framework knows zero about any project's layout
+ * conventions. Build domain-specific collectors (rpiv-pi's
+ * `rpivArtifactCollector`, an `adrCollector` for `docs/adr/...`, etc.) by
+ * wrapping this and supplying the appropriate pattern.
+ *
+ * The pattern's `g` flag is honoured: with `g`, every occurrence in
+ * each text block is considered (helper takes the last one); without
+ * `g`, only the first per block. Authors who want N matches → N
+ * artifacts compose with `unionCollectors` or write a bespoke collector.
+ *
+ * Fatal when no match is found — produces stages that wire this
+ * promise an output, and silently returning zero artifacts hides the
+ * agent's failure mode behind a stale primary-artifact.
+ */
+
+import { fs } from "../../handle.js";
+import type { ArtifactCollector } from "../../output-spec.js";
+import { defineCollector } from "../../output-spec.js";
+import { lastMatchInBranch } from "../../transcript.js";
+
+export interface TranscriptPathCollectorOpts {
+	/**
+	 * Pattern to match against assistant text. REQUIRED — the framework
+	 * has no default (path layouts are project-specific). Use `g` to scan
+	 * for all matches per block (helper takes the last); without `g`,
+	 * only the first match per block is considered.
+	 */
+	pattern: RegExp;
+}
+
+export function transcriptPathCollector(opts: TranscriptPathCollectorOpts): ArtifactCollector {
+	if (!(opts.pattern instanceof RegExp)) {
+		throw new Error("transcriptPathCollector: `pattern` is required and must be a RegExp");
+	}
+	const pattern = opts.pattern;
+	return defineCollector({
+		collect: (ctx) => {
+			const path = lastMatchInBranch(ctx.branch, pattern, ctx.branchOffset);
+			if (!path) {
+				return {
+					kind: "fatal",
+					message: `${ctx.skill} finished without producing a path matching ${pattern.source}`,
+				};
+			}
+			return { kind: "ok", artifacts: [{ handle: fs(path), role: "primary" }] };
+		},
+	});
+}

package/outcomes/collectors/union.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { fs } from "../../handle.js";
+import type { ArtifactCollector } from "../../output-spec.js";
+import { unionCollectors } from "./union.js";
+
+const ctxOf = () => ({
+	cwd: "/tmp",
+	runId: "test",
+	stageIndex: 0,
+	state: {} as never,
+	branch: [],
+	branchOffset: undefined,
+	snapshot: undefined,
+	skill: "test",
+});
+
+const okCollector = (paths: string[]): ArtifactCollector => ({
+	collect: () => ({ kind: "ok", artifacts: paths.map((p) => ({ handle: fs(p) })) }),
+});
+
+const fatalCollector = (msg: string): ArtifactCollector => ({
+	collect: () => ({ kind: "fatal", message: msg }),
+});
+
+describe("unionCollectors", () => {
+	it("throws when constructed with zero collectors", () => {
+		expect(() => unionCollectors()).toThrow(/at least one collector/);
+	});
+
+	it("concatenates artifacts in collector order", async () => {
+		const union = unionCollectors(okCollector(["a.ts", "b.ts"]), okCollector(["c.ts"]));
+		const result = await union.collect(ctxOf());
+		expect(
+			result.kind === "ok" && result.artifacts.map((a) => (a.handle.kind === "fs" ? a.handle.path : "")),
+		).toEqual(["a.ts", "b.ts", "c.ts"]);
+	});
+
+	it("returns ok+empty when every sub-collector yielded ok+empty", async () => {
+		const union = unionCollectors(okCollector([]), okCollector([]));
+		const result = await union.collect(ctxOf());
+		expect(result.kind === "ok" && result.artifacts).toEqual([]);
+	});
+
+	it("returns ok when at least one sub-collector succeeds (even if others fatal)", async () => {
+		const union = unionCollectors(fatalCollector("transcript: no match"), okCollector(["b.ts"]));
+		const result = await union.collect(ctxOf());
+		expect(
+			result.kind === "ok" && result.artifacts.map((a) => (a.handle.kind === "fs" ? a.handle.path : "")),
+		).toEqual(["b.ts"]);
+	});
+
+	it("returns fatal carrying the LAST fatal message when every sub-collector fataled", async () => {
+		const union = unionCollectors(fatalCollector("first failure"), fatalCollector("second failure"));
+		const result = await union.collect(ctxOf());
+		expect(result.kind).toBe("fatal");
+		if (result.kind !== "fatal") return;
+		expect(result.message).toBe("second failure");
+	});
+});

package/outcomes/collectors/union.ts

@@ -0,0 +1,55 @@
+/**
+ * Union collector — runs N collectors and concatenates their artifacts.
+ *
+ * Useful for the "look in transcript OR tool calls" pattern, or for
+ * combining a workspace-diff scan with a transcript URL scan. The
+ * sub-collectors run sequentially; their `snapshot` hooks are NOT
+ * threaded (each collector gets its own snapshot only if it declares
+ * one and is invoked through `OutputSpec.collector` directly — wrapping
+ * collectors inside a union loses individual snapshots today).
+ *
+ * Fatal policy: `unionCollectors` returns `fatal` only when EVERY
+ * sub-collector returned fatal (carries the last fatal message for
+ * diagnostics). One success is enough for the union to succeed —
+ * matches the "any of these channels produced the artifact" mental
+ * model the union represents.
+ *
+ * Empty artifact list from one sub-collector is treated as `ok` (it
+ * just contributes nothing to the concatenation). The union itself
+ * returns `ok` with the merged list; the runner's
+ * `enforceCompletionContract` decides whether an empty merged list is
+ * a halt (produces) or a pass-through (side-effect).
+ */
+
+import type { Artifact } from "../../handle.js";
+import type { ArtifactCollector, CollectResult } from "../../output-spec.js";
+import { defineCollector } from "../../output-spec.js";
+
+export function unionCollectors(...collectors: ArtifactCollector[]): ArtifactCollector {
+	if (collectors.length === 0) {
+		throw new Error("unionCollectors: at least one collector is required");
+	}
+	return defineCollector({
+		collect: async (ctx) => {
+			const all: Artifact[] = [];
+			let lastFatalMessage: string | undefined;
+			let everySubCollectorFatal = true;
+			for (const c of collectors) {
+				const result: CollectResult = await c.collect(ctx);
+				if (result.kind === "fatal") {
+					lastFatalMessage = result.message;
+					continue;
+				}
+				everySubCollectorFatal = false;
+				all.push(...result.artifacts);
+			}
+			if (everySubCollectorFatal) {
+				return {
+					kind: "fatal",
+					message: lastFatalMessage ?? `${ctx.skill}: unionCollectors had no successful sub-collector`,
+				};
+			}
+			return { kind: "ok", artifacts: all };
+		},
+	});
+}

package/outcomes/collectors/url.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import type { BranchEntry } from "../../transcript.js";
+import { urlCollector } from "./url.js";
+
+const asst = (text: string): BranchEntry => ({
+	type: "message",
+	message: { role: "assistant", content: [{ type: "text", text }] },
+});
+
+const ctxOf = (branch: BranchEntry[]) => ({
+	cwd: "/tmp",
+	runId: "test",
+	stageIndex: 0,
+	state: {} as never,
+	branch,
+	branchOffset: undefined,
+	snapshot: undefined,
+	skill: "test",
+});
+
+describe("urlCollector", () => {
+	it("emits a url() handle for an https URL in assistant text", async () => {
+		const collector = urlCollector();
+		const ctx = ctxOf([asst("Opened https://github.com/owner/repo/pull/42 for review.")]);
+		const result = await collector.collect(ctx);
+		expect(result.kind === "ok" && result.artifacts[0]?.handle).toEqual({
+			kind: "url",
+			href: "https://github.com/owner/repo/pull/42",
+		});
+	});
+
+	it("trims trailing prose punctuation (.,;:!?))", async () => {
+		const collector = urlCollector();
+		const ctx = ctxOf([asst("See https://example.com/page.")]);
+		const result = await collector.collect(ctx);
+		expect(result.kind === "ok" && result.artifacts[0]?.handle).toEqual({
+			kind: "url",
+			href: "https://example.com/page",
+		});
+	});
+
+	it("returns the last URL when multiple appear", async () => {
+		const collector = urlCollector();
+		const ctx = ctxOf([asst("first: https://a.com second: https://b.com")]);
+		const result = await collector.collect(ctx);
+		expect(result.kind === "ok" && result.artifacts[0]?.handle).toEqual({ kind: "url", href: "https://b.com" });
+	});
+
+	it("fatals when no URL is found", async () => {
+		const collector = urlCollector();
+		const ctx = ctxOf([asst("no link here")]);
+		const result = await collector.collect(ctx);
+		expect(result.kind).toBe("fatal");
+	});
+
+	it("accepts a narrower pattern (e.g. only linear.app URLs)", async () => {
+		const collector = urlCollector({ pattern: /https:\/\/linear\.app\/[^\s)]+/g });
+		const ctx = ctxOf([
+			asst("Filed https://github.com/owner/r/issues/1 and https://linear.app/team/issue/ENG-42 — see linear."),
+		]);
+		const result = await collector.collect(ctx);
+		expect(result.kind === "ok" && result.artifacts[0]?.handle).toEqual({
+			kind: "url",
+			href: "https://linear.app/team/issue/ENG-42",
+		});
+	});
+});

package/outcomes/collectors/url.ts

@@ -0,0 +1,45 @@
+/**
+ * URL collector — scans assistant text for a URL and emits it as a
+ * `url` handle (not `fs`). Use when the stage produces a remote
+ * reference: a Linear ticket URL, a deployed-preview link, a posted
+ * PR/comment, etc.
+ *
+ * Default `pattern` is RFC-3986-flavoured `https?://` — genuinely
+ * universal (every protocol-bearing URL the agent prints in markdown
+ * matches). Authors needing a narrower shape (only github.com, only
+ * linear.app) pass their own RegExp.
+ */
+
+import { url } from "../../handle.js";
+import type { ArtifactCollector } from "../../output-spec.js";
+import { defineCollector } from "../../output-spec.js";
+import { lastMatchInBranch } from "../../transcript.js";
+
+/**
+ * Conservative URL matcher — `https?://` plus non-whitespace, stopping
+ * at common terminator characters (`<>"'` and trailing punctuation
+ * the model often appends in prose). Not RFC-3986 strict; tuned for
+ * the assistant-prose case rather than for validating arbitrary input.
+ */
+const DEFAULT_URL_PATTERN = /\bhttps?:\/\/[^\s<>"'`]+[^\s<>"'`.,;:!?)\]}]/g;
+
+export interface UrlCollectorOpts {
+	/** Override the default URL pattern (e.g. narrow to one host). */
+	pattern?: RegExp;
+}
+
+export function urlCollector(opts: UrlCollectorOpts = {}): ArtifactCollector {
+	const pattern = opts.pattern ?? DEFAULT_URL_PATTERN;
+	return defineCollector({
+		collect: (ctx) => {
+			const href = lastMatchInBranch(ctx.branch, pattern, ctx.branchOffset);
+			if (!href) {
+				return {
+					kind: "fatal",
+					message: `${ctx.skill} finished without producing a URL matching ${pattern.source}`,
+				};
+			}
+			return { kind: "ok", artifacts: [{ handle: url(href), role: "primary" }] };
+		},
+	});
+}