@shivaedev/work-board 0.9.0 → 0.10.0

package/src/browser/client.ts

@@ -12,6 +12,7 @@ import type { Contract } from "@shivaedev/effect-contract/contract.ts";
 import { live } from "@shivaedev/effect-contract/live.ts";
 import { type ResumeOptions, resumeSignal } from "@shivaedev/effect-contract/resume.ts";
 import { type ReadFailed, workContract, workRpcs } from "#rpc/contract.ts";
+import { handoffContract } from "#rpc/handoffContract.ts";
 import { workspace } from "#rpc/keys.ts";
 import { responseContract } from "#rpc/responseContract.ts";
 
@@ -23,6 +24,7 @@ type BoundContract<TContract> =
 	TContract extends Contract<infer TName, infer TQueries, infer TCommands, infer TRpcs> ? Bound<TName, TQueries, TCommands, TRpcs, Reader> : never;
 export interface BrowserClient {
 	readonly api: BoundContract<typeof workContract>;
+	readonly handoffs: BoundContract<typeof handoffContract>;
 	readonly mutate: <A, E>(effect: Effect.Effect<A, E, Reader | Reactivity.Reactivity>, signal?: AbortSignal) => Promise<A>;
 	readonly read: <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>, signal?: AbortSignal) => Promise<A>;
 	readonly registry: AtomRegistry.AtomRegistry;
@@ -81,5 +83,5 @@ export function browserClient(url: string, options: ResumeOptions = {}): Browser
 		return result.success;
 	}
 	const responses = bind(responseContract, Client);
-	return { api, mutate, read, registry, responses, run, updates };
+	return { api, handoffs: bind(handoffContract, Client), mutate, read, registry, responses, run, updates };
 }

package/src/browser/entry.ts

@@ -1,7 +1,9 @@
+import { setupHandoffs } from "#browser/handoffs/setup.ts";
 import { setupResponses } from "#browser/responses/setup.ts";
 
 if (typeof window !== "undefined" && typeof document !== "undefined") {
 	setupResponses();
+	setupHandoffs();
 }
 
 import { session as ownedSession } from "./session.ts";

package/src/browser/handoffs/copy.ts

@@ -0,0 +1,45 @@
+const bound = new WeakSet<HTMLButtonElement>();
+export function copyPrompts(root: ParentNode) {
+	for (const button of root.querySelectorAll<HTMLButtonElement>("[data-handoff-copy]")) {
+		if (bound.has(button)) {
+			continue;
+		}
+		bound.add(button);
+		button.addEventListener("click", async () => {
+			const field = document.getElementById(button.dataset.handoffCopy ?? "");
+			const status = button.parentElement?.querySelector("[data-copy-status]");
+			if (!(field instanceof HTMLTextAreaElement && status)) {
+				return;
+			}
+			try {
+				await navigator.clipboard.writeText(field.value);
+				status.textContent = "Prompt copied. Paste it into your existing agent session.";
+			} catch {
+				field.focus();
+				field.select();
+				status.textContent = "Clipboard unavailable. The prompt is selected; copy it manually.";
+			}
+		});
+	}
+}
+export function preparedPrompt(container: HTMLElement, id: string, prompt: string) {
+	const label = document.createElement("label");
+	label.textContent = "Prompt for your existing agent session";
+	const field = document.createElement("textarea");
+	field.id = `handoff-prompt-${id}`;
+	field.readOnly = true;
+	field.rows = 3;
+	field.value = prompt;
+	label.append(field);
+	const button = document.createElement("button");
+	button.type = "button";
+	button.dataset.handoffCopy = field.id;
+	button.textContent = "Copy tiny prompt";
+	const status = document.createElement("p");
+	status.dataset.copyStatus = "";
+	status.setAttribute("role", "status");
+	status.textContent = "Prepared; receipt not confirmed. Copy the prompt to your agent.";
+	container.replaceChildren(label, button, status);
+	container.hidden = false;
+	copyPrompts(container);
+}

package/src/browser/handoffs/fields.ts

@@ -0,0 +1,50 @@
+import { Option, Schema } from "effect";
+import type { HandoffInput } from "#browser/handoffs/schema.ts";
+import type { Draft } from "#browser/responses/drafts.ts";
+
+const TextFields = Schema.Struct({ constraints: Schema.String, goal: Schema.String, nextAction: Schema.String });
+export function handoffFields(form: HTMLFormElement) {
+	const recipient = form.elements.namedItem("recipient");
+	const goal = form.elements.namedItem("goal");
+	const constraints = form.elements.namedItem("constraints");
+	const nextAction = form.elements.namedItem("nextAction");
+	if (
+		!(
+			recipient instanceof HTMLInputElement
+			&& goal instanceof HTMLTextAreaElement
+			&& constraints instanceof HTMLTextAreaElement
+			&& nextAction instanceof HTMLTextAreaElement
+		)
+	) {
+		return undefined;
+	}
+	return { constraints, goal, nextAction, recipient };
+}
+export function restoreFields(fields: NonNullable<ReturnType<typeof handoffFields>>, draft: Draft) {
+	if (!draft.body) {
+		return;
+	}
+	try {
+		const saved = Schema.decodeUnknownOption(TextFields)(JSON.parse(draft.body));
+		if (Option.isSome(saved)) {
+			fields.constraints.value = saved.value.constraints;
+			fields.goal.value = saved.value.goal;
+			fields.nextAction.value = saved.value.nextAction;
+			fields.recipient.value = draft.author;
+		}
+	} catch {
+		fields.goal.value = draft.body;
+		fields.recipient.value = draft.author;
+	}
+}
+export function inputFrom(form: HTMLFormElement, draft: Draft): HandoffInput {
+	const fields = Schema.decodeUnknownSync(TextFields)(JSON.parse(draft.body));
+	return {
+		...fields,
+		id: draft.id,
+		item: form.dataset.item ?? "",
+		recipient: draft.author,
+		revision: draft.revision,
+		source: form.dataset.source ?? "",
+	};
+}

package/src/browser/handoffs/schema.ts

@@ -0,0 +1,44 @@
+import { Schema } from "effect";
+import { Revision } from "#browser/responses/schema.ts";
+import { Identity } from "#path/Identity.ts";
+
+const Text = Schema.String.check(Schema.isPattern(/\S/u), Schema.isMaxLength(8192));
+const HandoffFields = Schema.Struct({
+	by: Schema.optional(Text),
+	constraints: Schema.String.check(Schema.isMaxLength(8192)),
+	goal: Text,
+	item: Identity,
+	nextAction: Text,
+	note: Schema.optional(Text),
+	preparedAt: Schema.Number.check(Schema.isFinite(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(8_640_000_000_000_000)),
+	recipient: Text.check(Schema.isMaxLength(200)),
+	reviewedRevision: Revision,
+	source: Schema.String,
+	state: Schema.Literals(["requested", "acknowledged", "rejected", "unavailable"]),
+});
+export const HandoffRecord = HandoffFields.pipe(
+	Schema.encodeKeys({ nextAction: "next_action", preparedAt: "prepared_at", reviewedRevision: "reviewed_revision" }),
+);
+export type HandoffRecord = typeof HandoffRecord.Type;
+export const HandoffInput = Schema.Struct({
+	constraints: HandoffFields.fields.constraints,
+	goal: HandoffFields.fields.goal,
+	id: Identity,
+	item: Identity,
+	nextAction: HandoffFields.fields.nextAction,
+	recipient: HandoffFields.fields.recipient,
+	revision: Revision,
+	source: Schema.String,
+});
+export type HandoffInput = typeof HandoffInput.Type;
+export const Handoff = Schema.Struct({ context: Schema.String, file: Schema.String, handoff: HandoffRecord, id: Identity, prompt: Schema.String });
+export type Handoff = typeof Handoff.Type;
+export const HandoffReading = Schema.Struct({ records: Schema.Array(Handoff), unknown: Schema.Array(Schema.String) });
+export const HandoffPreview = Schema.Struct({
+	context: Schema.String,
+	id: Identity,
+	item: Identity,
+	reviewedRevision: Revision,
+	source: Schema.String,
+});
+export type HandoffPreview = typeof HandoffPreview.Type;

package/src/browser/handoffs/setup.ts

@@ -0,0 +1,113 @@
+import { copyPrompts, preparedPrompt } from "#browser/handoffs/copy.ts";
+import { handoffFields, inputFrom, restoreFields } from "#browser/handoffs/fields.ts";
+import { draftSession } from "#browser/responses/draftSession.ts";
+import { ResponseFailed } from "#browser/responses/schema.ts";
+import { session } from "#browser/session.ts";
+
+const bound = new WeakSet<HTMLFormElement>();
+function attach() {
+	const doc = document.getElementById("doc");
+	if (doc?.dataset.view !== "handoff") {
+		return;
+	}
+	copyPrompts(doc);
+	const form = doc.querySelector<HTMLFormElement>("#handoff-form");
+	if (!form || bound.has(form)) {
+		return;
+	}
+	const found = handoffFields(form);
+	const status = form.querySelector<HTMLParagraphElement>("#handoff-status");
+	const preview = form.querySelector<HTMLPreElement>("#handoff-preview-content");
+	const previewButton = form.querySelector<HTMLButtonElement>("#handoff-preview");
+	const submit = form.querySelector<HTMLButtonElement>("#handoff-submit");
+	const clear = form.querySelector<HTMLButtonElement>("#handoff-clear");
+	const prepared = form.querySelector<HTMLElement>("#handoff-prepared");
+	if (!(found && status && preview && previewButton && submit && clear && prepared)) {
+		return;
+	}
+	const fields = found;
+	bound.add(form);
+	form.dataset.bound = "true";
+	const revision = form.dataset.revision ?? "";
+	const question = form.dataset.question ?? "";
+	let storage: Storage | undefined;
+	try {
+		storage = window.localStorage;
+	} catch {
+		storage = undefined;
+	}
+	if (status.textContent?.includes("JavaScript is required")) {
+		status.textContent = "Draft ready. Review and preview before preparing the file.";
+	}
+	const drafts = draftSession(
+		`handoff:${form.dataset.item}`,
+		revision,
+		storage,
+		`work-board:drafts:${document.documentElement.dataset.workspace}`,
+		(message) => {
+			status.textContent = message;
+		},
+		"handoff",
+	);
+	let draft = drafts.current();
+	restoreFields(fields, draft);
+	function save() {
+		draft = drafts.update({
+			author: fields.recipient.value,
+			body: JSON.stringify({ constraints: fields.constraints.value, goal: fields.goal.value, nextAction: fields.nextAction.value }),
+		});
+	}
+	form.addEventListener("input", () => {
+		save();
+		preview.hidden = true;
+		submit.disabled = true;
+	});
+	previewButton.disabled = false;
+	clear.disabled = false;
+	clear.addEventListener("click", drafts.clear);
+	previewButton.addEventListener("click", () => {
+		save();
+		draft = drafts.update({
+			id: draft.revision === revision && (!draft.question || draft.question === question) ? draft.id : `handoff.${crypto.randomUUID()}`,
+			question,
+			revision,
+		});
+		const input = inputFrom(form, draft);
+		preview.textContent = `New file: handoffs/${input.id}.md\nPrepared time and reviewed snapshot are assigned by the server.\n\n---\n${JSON.stringify({ handoff: { constraints: input.constraints, goal: input.goal, item: input.item, "next_action": input.nextAction, recipient: input.recipient, "reviewed_revision": input.revision, source: input.source, state: "requested" }, id: input.id, kind: "handoff" }, null, 2)}\n---\nThe complete reviewed source is preserved below the frontmatter.`;
+		preview.hidden = false;
+		submit.disabled = form.dataset.writable !== "true" || !form.checkValidity();
+	});
+	form.addEventListener("submit", async (event) => {
+		event.preventDefault();
+		if (submit.disabled || !form.reportValidity()) {
+			return;
+		}
+		const pending = draft;
+		submit.disabled = true;
+		previewButton.disabled = true;
+		status.textContent = "Pending: preparing the local handoff file…";
+		try {
+			const native = session(window);
+			const saved = await native.mutate(native.handoffs.prepareHandoff.run(inputFrom(form, pending)));
+			const cleared = drafts.saved(pending);
+			draft = drafts.current();
+			if (form.isConnected) {
+				status.textContent = `Prepared: ${saved.file}. Receipt: ${saved.handoff.state}; execution and acceptance remain separate.${cleared ? "" : " Your newer draft remains unsaved."}`;
+				preparedPrompt(prepared, saved.id, saved.prompt);
+			}
+		} catch (error) {
+			if (form.isConnected) {
+				status.textContent = failureStatus(error);
+			}
+		}
+		previewButton.disabled = false;
+	});
+}
+function failureStatus(error: unknown) {
+	return `${error instanceof ResponseFailed && error.code !== "Uncertain" ? "Rejected" : "Uncertain"}: ${String(error)}. Draft retained; preview and retry.`;
+}
+export function setupHandoffs() {
+	document.addEventListener("board-page", attach);
+	window.addEventListener("pageshow", attach);
+	attach();
+}

package/src/browser/responses/draftSession.ts

@@ -2,7 +2,14 @@ import { Clock, Effect } from "effect";
 import { DRAFT_AGE, type Draft, encodeDrafts, readDrafts } from "./drafts.ts";
 
 const states = new Map<string, Draft>();
-export function draftSession(key: string, revision: string, storage: Storage | undefined, storageKey: string, report: (message: string) => void) {
+export function draftSession(
+	key: string,
+	revision: string,
+	storage: Storage | undefined,
+	storageKey: string,
+	report: (message: string) => void,
+	prefix = "response",
+) {
 	const stateKey = `${JSON.stringify(storageKey)}:${key}`;
 	function local() {
 		if (!storage) {
@@ -32,7 +39,7 @@ export function draftSession(key: string, revision: string, storage: Storage | u
 		?? drafts[key] ?? {
 			author: "",
 			body: "",
-			id: `response.${crypto.randomUUID()}`,
+			id: `${prefix}.${crypto.randomUUID()}`,
 			revision,
 			type: "answer",
 			updatedAt: Effect.runSync(Clock.currentTimeMillis),
@@ -72,7 +79,7 @@ export function draftSession(key: string, revision: string, storage: Storage | u
 		if (states.get(stateKey) !== pending) {
 			const live = states.get(stateKey);
 			if (live?.id === pending.id) {
-				update({ id: `response.${crypto.randomUUID()}` });
+				update({ id: `${prefix}.${crypto.randomUUID()}` });
 			}
 			return false;
 		}
@@ -90,7 +97,7 @@ export function draftSession(key: string, revision: string, storage: Storage | u
 			...current,
 			answers: undefined,
 			body: "",
-			id: `response.${crypto.randomUUID()}`,
+			id: `${prefix}.${crypto.randomUUID()}`,
 			recovery: undefined,
 			supersedes: undefined,
 			updatedAt: Effect.runSync(Clock.currentTimeMillis),

package/src/handoffs/html.ts

@@ -0,0 +1,42 @@
+import { Effect } from "effect";
+import type { Handoff, HandoffPreview } from "#browser/handoffs/schema.ts";
+import { fileUrl } from "#files/url.ts";
+import { metadataParse } from "#metadata/parse.ts";
+import { escapeHtml } from "#page/escape.ts";
+import type { RenderFailed } from "#render/failed.ts";
+import type { Highlighter } from "#render/highlighter.ts";
+import { renderMarkdown } from "#render/markdown.ts";
+
+export function promptHtml(id: string, prompt: string) {
+	return `<div class="handoff-copy"><label>Prompt for your existing agent session<textarea id="handoff-prompt-${escapeHtml(id)}" readonly rows="3">${escapeHtml(prompt)}</textarea></label><button type="button" data-handoff-copy="handoff-prompt-${escapeHtml(id)}">Copy tiny prompt</button><p role="status" data-copy-status>Copy and paste this into your agent session. Preparing a file does not notify an agent.</p></div>`;
+}
+function receiptNote(h: Handoff["handoff"]) {
+	if (!(h.by || h.note)) {
+		return "";
+	}
+	return `<p>${escapeHtml(h.by ?? "Attribution not recorded")}${h.note ? ` · ${escapeHtml(h.note)}` : ""}</p>`;
+}
+export const handoffHistoryHtml = Effect.fn("WorkBoard.handoffHistoryHtml")(function* (
+	records: readonly Handoff[],
+	current?: HandoffPreview,
+): Effect.fn.Return<string[], RenderFailed, Highlighter> {
+	return yield* Effect.forEach(records, (record) =>
+		Effect.gen(function* () {
+			const h = record.handoff;
+			const goal = yield* renderMarkdown(h.goal, { file: h.source, safe: true });
+			const constraints = yield* renderMarkdown(h.constraints, { file: h.source, safe: true });
+			const next = yield* renderMarkdown(h.nextAction, { file: h.source, safe: true });
+			const same = current?.reviewedRevision === h.reviewedRevision && current.source === h.source;
+			return `<article id="${escapeHtml(record.id)}"><h3><a href="${fileUrl(record.file)}">${escapeHtml(record.id)}</a> · ${escapeHtml(h.recipient)}</h3><p><b>Receipt: ${escapeHtml(h.state)}</b>${h.state === "requested" ? " — prepared; receipt not confirmed" : ""}. Execution and acceptance are not recorded by this state.</p><p>${same ? "Current reviewed source" : "Earlier or unavailable reviewed source; recheck before acting"} · <a href="${fileUrl(h.source)}">${escapeHtml(h.source)}</a> · <code>${h.reviewedRevision}</code></p>${receiptNote(h)}<h4>Goal</h4>${goal}<h4>Constraints</h4>${constraints || "<p>None recorded.</p>"}<h4>Next action</h4>${next}${promptHtml(record.id, record.prompt)}<details><summary>Exact reviewed source snapshot</summary><pre>${escapeHtml(record.context)}</pre></details></article>`;
+		}),
+	);
+});
+export const handoffFormHtml = Effect.fn("WorkBoard.handoffFormHtml")(function* (
+	source: HandoffPreview,
+	enabled: boolean,
+): Effect.fn.Return<string, RenderFailed, Highlighter> {
+	const parsed = metadataParse(source.context);
+	const background = yield* renderMarkdown(parsed.body, { file: source.source, safe: true });
+	const goal = /^#\s+(?<title>.+)$/mu.exec(parsed.body)?.groups?.title ?? source.item;
+	return `<section class="response-context">${background}</section><details><summary>Exact source being reviewed</summary><pre>${escapeHtml(source.context)}</pre></details><form id="handoff-form" data-item="${escapeHtml(source.item)}" data-source="${escapeHtml(source.source)}" data-revision="${source.reviewedRevision}" data-question="${source.id}" data-writable="${enabled}"><label>Recipient — local agent label<input name="recipient" required maxlength="200"></label><label>Goal<textarea name="goal" required maxlength="8192" rows="3">${escapeHtml(goal)}</textarea></label><label>Constraints (optional)<textarea name="constraints" maxlength="8192" rows="4"></textarea></label><label>Next action<textarea name="nextAction" required maxlength="8192" rows="3">${escapeHtml(parsed.fields.nextAction ?? "")}</textarea></label><p>The file includes the full reviewed source and its declared acceptance criteria. Preparing it does not change the item or start an agent. Drafts use the existing 30-day/2-MiB workspace store.</p><button id="handoff-preview" type="button" disabled>Preview Markdown</button><pre id="handoff-preview-content" hidden></pre><button id="handoff-submit" type="submit" disabled>Prepare handoff</button><button id="handoff-clear" type="button" disabled>Clear workspace drafts</button><p id="handoff-status" role="status">${enabled ? "JavaScript is required to prepare a handoff." : "Read-only mode. Restart with --responses to enable local writes."}</p><section id="handoff-prepared" hidden></section></form>`;
+});

package/src/handoffs/page.ts

@@ -0,0 +1,45 @@
+import { Effect, type FileSystem, type Path, type PlatformError } from "effect";
+import type { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import type { Changes } from "#files/changes.ts";
+import { handoffFormHtml, handoffHistoryHtml } from "#handoffs/html.ts";
+import type { handoffService } from "#handoffs/service.ts";
+import { respond } from "#http/respond.ts";
+import { escapeHtml } from "#page/escape.ts";
+import { navHtml } from "#page/nav.ts";
+import { shell } from "#page/shell.ts";
+import type { Highlighter } from "#render/highlighter.ts";
+
+function unknownHistory(files: readonly string[]) {
+	return files.length > 0
+		? `<p role="status">Some handoff history is unavailable: ${files.map(escapeHtml).join(", ")}. Missing records do not establish that no receipt exists.</p>`
+		: "";
+}
+export function handoffPage(
+	service: Effect.Success<ReturnType<typeof handoffService>>,
+	changes: Changes,
+	home: string | undefined,
+	enabled: boolean,
+) {
+	return Effect.fn("WorkBoard.handoffPage")(function* (
+		request: HttpServerRequest.HttpServerRequest,
+	): Effect.fn.Return<HttpServerResponse.HttpServerResponse, PlatformError.PlatformError, FileSystem.FileSystem | Path.Path | Highlighter> {
+		const item = new URL(request.url, "http://127.0.0.1").searchParams.get("item") ?? "";
+		const files = yield* changes.files;
+		function layout(body: string, status = 200) {
+			return respond(shell("Handoff", navHtml(files, "", home), body, changes.realRoot, false, undefined, "handoff"), "text/html", status);
+		}
+		return yield* Effect.gen(function* () {
+			const source = yield* Effect.result(service.locate(item));
+			const current = source._tag === "Success" ? source.success : undefined;
+			const reading = yield* service.read(item);
+			const history = yield* handoffHistoryHtml(reading.records, current);
+			const form = current
+				? yield* handoffFormHtml(current, enabled)
+				: `<p role="status">Source unavailable: ${escapeHtml(String(source._tag === "Failure" ? source.failure : ""))}. Existing handoffs remain readable.</p>`;
+			return layout(
+				`<section class="response-panel"><h1>Agent handoff · ${escapeHtml(item)}</h1><p>Prepare a Markdown file, then copy a tiny prompt into your existing agent session. Sessions may poll or wait for human answers. Agents record receipt with ordinary file edits.</p>${form}<section id="handoff-history"><h2>Prepared handoffs</h2>${unknownHistory(reading.unknown)}${history.join("") || "<p>No readable handoff is recorded for this item.</p>"}</section></section>`,
+				current || reading.records.length > 0 ? 200 : 409,
+			);
+		}).pipe(Effect.catch((error) => Effect.succeed(layout(`<h1>Handoff unavailable</h1><p>${escapeHtml(String(error))}</p>`, 409))));
+	});
+}

package/src/handoffs/records.ts

@@ -0,0 +1,34 @@
+import { join } from "node:path";
+import { Schema } from "effect";
+import { stringify } from "yaml";
+import type { Handoff, HandoffInput, HandoffRecord } from "#browser/handoffs/schema.ts";
+import { HandoffRecord as RecordSchema } from "#browser/handoffs/schema.ts";
+import type { MetadataDocument } from "#metadata/model.ts";
+
+export function handoffFrom(document: MetadataDocument | undefined, root: string): Handoff | undefined {
+	if (!document) {
+		return undefined;
+	}
+	const { id, kind, handoff } = document.parsed.fields;
+	return id && kind === "handoff" && handoff
+		? { context: document.parsed.body, file: document.file, handoff, id, prompt: handoffPrompt(join(root, document.file)) }
+		: undefined;
+}
+export function handoffPrompt(path: string): string {
+	return `Read the handoff at ${JSON.stringify(path)}. Record receipt by editing its handoff.state and add handoff.by/note; then follow its instructions.`;
+}
+export function handoffMarkdown(id: string, handoff: HandoffRecord, context: string): string {
+	return `---\n${stringify({ handoff: Schema.encodeSync(RecordSchema)(handoff), id, kind: "handoff" })}---\n${context}`;
+}
+export function matchesHandoff(record: Handoff, input: HandoffInput) {
+	const saved = record.handoff;
+	return (
+		saved.item === input.item
+		&& saved.source === input.source
+		&& saved.reviewedRevision === input.revision
+		&& saved.recipient === input.recipient
+		&& saved.goal === input.goal
+		&& saved.constraints === input.constraints
+		&& saved.nextAction === input.nextAction
+	);
+}

package/src/handoffs/service.ts

@@ -0,0 +1,103 @@
+import { join } from "node:path";
+import { Clock, Effect, FileSystem, Semaphore } from "effect";
+import type { Handoff, HandoffInput } from "#browser/handoffs/schema.ts";
+import { ResponseFailed } from "#browser/responses/schema.ts";
+import { markdownPath } from "#files/markdownPath.ts";
+import { handoffFrom, handoffMarkdown, handoffPrompt, matchesHandoff } from "#handoffs/records.ts";
+import { handoffSource } from "#handoffs/source.ts";
+import { publish } from "#responses/publish.ts";
+import { revisionOf } from "#responses/records.ts";
+import type { ResponseOptions } from "#responses/service.ts";
+
+export const handoffService = Effect.fn("WorkBoard.handoffService")(function* (options: ResponseOptions) {
+	const fs = yield* FileSystem.FileSystem;
+	const lock = yield* Semaphore.make(1);
+	const snapshot = options.index.pipe(
+		Effect.catch(() => Effect.fail(new ResponseFailed({ code: "Unavailable", message: "The workspace could not be indexed." }))),
+	);
+	const locate = handoffSource(options.root, options.changes.realRoot, snapshot, fs);
+	const read = Effect.fn("WorkBoard.read")(function* (item: string) {
+		const data = yield* snapshot;
+		const unknown = [...data.unavailable];
+		const records = data.documents.flatMap((document) => {
+			const record = handoffFrom(document, options.changes.realRoot);
+			if (
+				(record && data.model.ids.get(record.id)?.length !== 1)
+				|| (document.parsed.fields.kind === "handoff" && !record)
+				|| (document.file.startsWith("handoffs/") && document.parsed.diagnostics.some((problem) => problem.field === undefined))
+			) {
+				unknown.push(document.file);
+				return [];
+			}
+			return record?.handoff.item === item ? [record] : [];
+		});
+		return { records: records.sort((a, b) => b.handoff.preparedAt - a.handoff.preparedAt || a.id.localeCompare(b.id)), unknown };
+	});
+	const reconcile = Effect.fn("WorkBoard.reconcile")(function* (record: Handoff | undefined, input: HandoffInput) {
+		if (!record || record.file !== `handoffs/${input.id}.md` || !matchesHandoff(record, input) || revisionOf(record.context) !== input.revision) {
+			return yield* Effect.fail(
+				new ResponseFailed({ code: "Conflict", message: "This handoff identity moved, is duplicated or records different direction." }),
+			);
+		}
+		const path = yield* markdownPath(options.root, options.changes.realRoot, record.file);
+		if (!path) {
+			return yield* Effect.fail(new ResponseFailed({ code: "Missing", message: "The prepared handoff moved or disappeared." }));
+		}
+		const raw = yield* fs
+			.readFileString(path)
+			.pipe(Effect.catch(() => Effect.fail(new ResponseFailed({ code: "Unavailable", message: "The handoff could not be reconciled." }))));
+		yield* publish(options.root, options.changes.realRoot, record.id, raw, "handoffs");
+		return record;
+	});
+
+	function prepare(input: HandoffInput) {
+		return lock.withPermit(
+			Effect.gen(function* () {
+				if (!options.enabled) {
+					return yield* Effect.fail(
+						new ResponseFailed({ code: "Disabled", message: "Restart with --responses to enable local response/handoff writes." }),
+					);
+				}
+				const data = yield* snapshot;
+				const existing = data.model.ids.get(input.id);
+				if (existing?.length) {
+					const record = existing.length === 1 ? handoffFrom(existing[0], options.changes.realRoot) : undefined;
+					return yield* reconcile(record, input);
+				}
+				const current = yield* locate(input.item);
+				if (current.reviewedRevision !== input.revision || current.source !== input.source) {
+					return yield* Effect.fail(
+						new ResponseFailed({ code: "Stale", message: "The source changed or moved. Keep your draft and review it again." }),
+					);
+				}
+				const file = `handoffs/${input.id}.md`;
+				const record: Handoff = {
+					context: current.context,
+					file,
+					handoff: {
+						constraints: input.constraints,
+						goal: input.goal,
+						item: input.item,
+						nextAction: input.nextAction,
+						preparedAt: yield* Clock.currentTimeMillis,
+						recipient: input.recipient,
+						reviewedRevision: input.revision,
+						source: input.source,
+						state: "requested",
+					},
+					id: input.id,
+					prompt: handoffPrompt(join(options.changes.realRoot, file)),
+				};
+				yield* publish(
+					options.root,
+					options.changes.realRoot,
+					record.id,
+					handoffMarkdown(record.id, record.handoff, record.context),
+					"handoffs",
+				).pipe(Effect.ensuring(options.changes.refresh ?? Effect.void));
+				return record;
+			}),
+		);
+	}
+	return { locate, prepare, read };
+});

package/src/handoffs/source.ts

@@ -0,0 +1,35 @@
+import { Effect, type FileSystem } from "effect";
+import type { HandoffPreview } from "#browser/handoffs/schema.ts";
+import { ResponseFailed } from "#browser/responses/schema.ts";
+import { markdownPath } from "#files/markdownPath.ts";
+import { metadataParse } from "#metadata/parse.ts";
+import { questionId, revisionOf } from "#responses/records.ts";
+import type { Snapshot } from "#search/snapshot.ts";
+
+export function handoffSource(root: string, realRoot: string, snapshot: Effect.Effect<Snapshot, ResponseFailed>, fs: FileSystem.FileSystem) {
+	return Effect.fn("WorkBoard.handoffSource")(function* (item: string) {
+		const data = yield* snapshot;
+		const matches = data.model.ids.get(item);
+		if (data.unavailable.length > 0 || matches?.length !== 1 || !matches[0]) {
+			return yield* Effect.fail(new ResponseFailed({ code: "Missing", message: "The item is missing, ambiguous or unavailable." }));
+		}
+		const file = matches[0].file;
+		const real = yield* markdownPath(root, realRoot, file);
+		const context = real ? yield* fs.readFileString(real).pipe(Effect.catch(() => Effect.succeed(undefined))) : undefined;
+		if (context === undefined) {
+			return yield* Effect.fail(new ResponseFailed({ code: "Unavailable", message: "The handoff source could not be read." }));
+		}
+		const fields = metadataParse(context).fields;
+		if (fields.id !== item || fields.kind === "question" || fields.kind === "response" || fields.kind === "handoff") {
+			return yield* Effect.fail(new ResponseFailed({ code: "Stale", message: "Choose a current project item for this handoff." }));
+		}
+		if (new TextEncoder().encode(context).length > 256 * 1024) {
+			return yield* Effect.fail(
+				new ResponseFailed({ code: "Unsupported", message: "Handoff context is limited to 256 KiB. Choose a focused item." }),
+			);
+		}
+		const reviewedRevision = revisionOf(context);
+		const preview: HandoffPreview = { context, id: questionId(item, "handoff", reviewedRevision, file), item, reviewedRevision, source: file };
+		return preview;
+	});
+}

package/src/metadata/backlinks.ts

@@ -10,6 +10,7 @@ export interface Backlink {
 function references(document: MetadataDocument, model: MetadataModel) {
 	const { fields, lines } = document.parsed;
 	return [
+		...(fields.handoff ? [{ kind: "agent handoff", line: lines.handoff, target: referenceFile(fields.handoff.item, model) }] : []),
 		...(fields.question ? [{ kind: "reviewed question", line: lines.question, target: referenceFile(fields.question.item, model) }] : []),
 		...(fields.response ? [{ kind: "recorded response", line: lines.response, target: referenceFile(fields.response.question, model) }] : []),
 		...(fields.response?.supersedes

package/src/metadata/problems.ts

@@ -27,6 +27,7 @@ function criterionProblems(document: MetadataDocument): readonly Diagnostic[] {
 function referenceProblems(document: MetadataDocument, ids: ReadonlyMap<string, readonly MetadataDocument[]>): readonly Diagnostic[] {
 	const { fields, lines } = document.parsed;
 	const references = [
+		...(fields.handoff ? [{ field: "handoff", key: "handoff.item", target: fields.handoff.item }] : []),
 		...(fields.question ? [{ field: "question", key: "question.item", target: fields.question.item }] : []),
 		...(fields.response ? [{ field: "response", key: "response.question", target: fields.response.question }] : []),
 		...(fields.response?.supersedes ? [{ field: "response", key: "response.supersedes", target: fields.response.supersedes }] : []),

package/src/metadata/schema.ts

@@ -1,4 +1,5 @@
 import { Schema } from "effect";
+import { HandoffRecord } from "#browser/handoffs/schema.ts";
 import { QuestionRecord, ResponseRecord } from "#browser/responses/schema.ts";
 import { Identity as SourceIdentity } from "#path/Identity.ts";
 
@@ -36,9 +37,10 @@ export const Metadata = Schema.Struct({
 	attention: Schema.optional(Schema.Array(Attention)),
 	criteria: Schema.optional(Schema.Array(Criterion)),
 	evidence: Schema.optional(Schema.Array(Evidence)),
+	handoff: Schema.optional(HandoffRecord),
 	id: Schema.optional(Identity),
 	items: Schema.optional(Schema.Array(Identity)),
-	kind: Schema.optional(Schema.Literals(["task", "investigation", "decision", "result", "project", "board", "question", "response"])),
+	kind: Schema.optional(Schema.Literals(["task", "investigation", "decision", "result", "project", "board", "question", "response", "handoff"])),
 	nextAction: Schema.optional(Text),
 	owner: Schema.optional(Text),
 	question: Schema.optional(QuestionRecord),