@shivaedev/work-board 0.9.0 → 0.10.0

package/src/page/metadata.ts

@@ -6,6 +6,12 @@ import { backlinksHtml } from "./backlinksHtml.ts";
 import { escapeHtml } from "./escape.ts";
 import { metadataDetails } from "./metadataDetails.ts";
 
+function handoffLink(id: string | undefined, kind: string | undefined, unique: boolean) {
+	return unique && id && !["question", "response", "handoff"].includes(kind ?? "")
+		? `<p><a href="/_board/handoff?item=${encodeURIComponent(id)}">Prepare an agent handoff</a></p>`
+		: "";
+}
+
 export function metadataHtml(parsed: ParsedMetadata, file: string, model: MetadataModel): string {
 	const backlinks = backlinksHtml(file, model);
 	const diagnostics = model.diagnostics.get(file) ?? parsed.diagnostics;
@@ -27,7 +33,7 @@ export function metadataHtml(parsed: ParsedMetadata, file: string, model: Metada
 		unique && fields.kind === "board" && fields.id
 			? `<p><a href="${escapeHtml(viewUrl(stateOf("/"), { board: fields.id }))}">View this board</a></p>`
 			: "";
-	return `<section class="work-meta" aria-label="Recorded work"><p class="metadata-summary">Recorded work · ${identity}${fields.status ? ` · ${escapeHtml(fields.status)}` : ""}${fields.owner ? ` · ${escapeHtml(fields.owner)}` : ""}</p>${fields.nextAction ? `<p>Next action: ${escapeHtml(fields.nextAction)}</p>` : ""}${boardLink}${problems}<details data-key="work-metadata"><summary>Work details and source</summary>${details}<p>Source: ${escapeHtml(file)}:${parsed.lines.id ?? 1}; prose starts at line ${parsed.bodyLine}.</p>${parsed.raw ? `<details data-key="frontmatter-source"><summary>Original frontmatter</summary><pre>${escapeHtml(parsed.raw)}</pre></details>` : ""}</details></section>${backlinks}`;
+	return `<section class="work-meta" aria-label="Recorded work"><p class="metadata-summary">Recorded work · ${identity}${fields.status ? ` · ${escapeHtml(fields.status)}` : ""}${fields.owner ? ` · ${escapeHtml(fields.owner)}` : ""}</p>${fields.nextAction ? `<p>Next action: ${escapeHtml(fields.nextAction)}</p>` : ""}${boardLink}${handoffLink(fields.id, fields.kind, unique)}${problems}<details data-key="work-metadata"><summary>Work details and source</summary>${details}<p>Source: ${escapeHtml(file)}:${parsed.lines.id ?? 1}; prose starts at line ${parsed.bodyLine}.</p>${parsed.raw ? `<details data-key="frontmatter-source"><summary>Original frontmatter</summary><pre>${escapeHtml(parsed.raw)}</pre></details>` : ""}</details></section>${backlinks}`;
 }
 
 export const metadataStyles = `

package/src/page/metadataDetails.ts

@@ -10,6 +10,9 @@ import { recordedEvidence } from "./recordedEvidence.ts";
 export function metadataDetails(parsed: ParsedMetadata, file: string, model: MetadataModel): string {
 	const fields = parsed.fields;
 	const details = [
+		fields.handoff
+			? `<h3>Agent handoff</h3><p>${referenceHtml(fields.handoff.item, fields.handoff.item, model)} · ${escapeHtml(fields.handoff.recipient)} · ${escapeHtml(fields.handoff.state)}</p><p>Receipt is separate from execution and acceptance.</p><p>${escapeHtml(fields.handoff.by ?? "Attribution not recorded")}${fields.handoff.note ? ` · ${escapeHtml(fields.handoff.note)}` : ""}</p><p>Reviewed SHA-256: <code>${fields.handoff.reviewedRevision}</code></p><p><a href="/_board/handoff?item=${encodeURIComponent(fields.handoff.item)}">Read handoff history and copy its prompt</a></p>`
+			: "",
 		`<dl><dt>Kind</dt><dd>${valueHtml(fields.kind)}</dd><dt>Status</dt><dd>${valueHtml(fields.status)}</dd><dt>Owner</dt><dd>${valueHtml(fields.owner)}</dd><dt>Next action</dt><dd>${valueHtml(fields.nextAction)}</dd></dl>`,
 		fields.relationships?.length
 			? `<h3>Relationships</h3><ul>${fields.relationships.map((link) => `<li>${escapeHtml(relationshipLabel(link.kind))}: ${referenceHtml(link.target, link.target, model)}</li>`).join("")}</ul>`

package/src/page/navigationScript.ts

@@ -88,7 +88,7 @@ document.addEventListener("click", (event) => {
   const link = event.target.closest?.("a[href]");
   if (!link || event.defaultPrevented || event.button !== 0 || event.ctrlKey || event.metaKey || event.shiftKey || event.altKey || link.hasAttribute("download") || (link.target && link.target !== "_self")) return;
   const target = new URL(link.href, location.href);
-  if (target.origin !== location.origin || !(target.pathname === "/" || (target.pathname === "/_board/respond" || target.pathname === "/_board/start" || target.pathname === "/_board/changes" || target.pathname === "/_board/overview" || target.pathname === "/_board/work" || target.pathname.startsWith("/_board/item/")) || /\\.md$/i.test(target.pathname))) return;
+  if (target.origin !== location.origin || !(target.pathname === "/" || (target.pathname === "/_board/handoff" || target.pathname === "/_board/respond" || target.pathname === "/_board/start" || target.pathname === "/_board/changes" || target.pathname === "/_board/overview" || target.pathname === "/_board/work" || target.pathname.startsWith("/_board/item/")) || /\\.md$/i.test(target.pathname))) return;
   event.preventDefault();
   navigate(target);
 });

package/src/page/shell.ts

@@ -17,7 +17,7 @@ export const shell = (
 	workspace: string,
 	board: boolean,
 	identity?: string,
-	view: boolean | "overview" | "changes" | "start" | "response" = false,
+	view: boolean | "overview" | "changes" | "start" | "response" | "handoff" = false,
 ): string =>
 	[
 		`<!doctype html><html lang="en" data-workspace="${escapeHtml(workspace)}"><head><meta charset="utf-8">`,

package/src/page/swap.ts

@@ -18,8 +18,8 @@ export const remember = (element) => {
 
 const normalized = (element) => {
   const copy = element.cloneNode(true);
-  for (const form of [copy, ...copy.querySelectorAll("#response-form")]) {
-    if (form.id === "response-form") { form.replaceChildren(); delete form.dataset.bound; }
+  for (const form of [copy, ...copy.querySelectorAll("#response-form, #handoff-form")]) {
+    if (form.id === "response-form" || form.id === "handoff-form") { form.replaceChildren(); delete form.dataset.bound; }
   }
   for (const tool of copy.querySelectorAll("[data-visual-tools], [data-image-error], [data-diagram-error]")) tool.remove();
   for (const node of [copy, ...copy.querySelectorAll("*")]) {

package/src/responses/publish.ts

@@ -9,20 +9,20 @@ function failure(cause: unknown): ResponseFailed {
 		? cause
 		: new ResponseFailed({
 				code: "Unavailable",
-				message: "The response could not be recorded. Keep the draft and retry after checking local filesystem access.",
+				message: "The local record could not be recorded. Keep the draft and retry after checking local filesystem access.",
 			});
 }
-export function publish(root: string, realRoot: string, id: string, content: string) {
+export function publish(root: string, realRoot: string, id: string, content: string, namespace: "responses" | "handoffs" = "responses") {
 	return Effect.tryPromise({
 		catch: failure,
 		try: async () => {
 			if (/^[a-zA-Z\d][a-zA-Z\d._-]*$/u.exec(id) === null) {
-				throw new ResponseFailed({ code: "Conflict", message: "Invalid response identity." });
+				throw new ResponseFailed({ code: "Conflict", message: "Invalid record identity." });
 			}
 			if (process.platform !== "linux") {
 				throw new ResponseFailed({
 					code: "Unsupported",
-					message: "Safe response publication currently requires Linux directory descriptors. Reading remains available.",
+					message: "Local record publication currently requires Linux directory descriptors. Reading remains available.",
 				});
 			}
 			const directory = await open(root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
@@ -32,16 +32,16 @@ export function publish(root: string, realRoot: string, id: string, content: str
 					throw new ResponseFailed({ code: "Conflict", message: "The workspace root changed. Restart against the intended root." });
 				}
 				try {
-					await mkdir(`${base}/responses`);
+					await mkdir(`${base}/${namespace}`);
 				} catch (cause) {
 					if (!(cause instanceof Error && "code" in cause && cause.code === "EEXIST")) {
 						throw cause;
 					}
 				}
 				await directory.sync();
-				const target = await open(`${base}/responses`, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+				const target = await open(`${base}/${namespace}`, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
 				try {
-					await publishIn(target, root, realRoot, id, content);
+					await publishIn(target, root, realRoot, id, content, namespace);
 				} finally {
 					await target.close();
 				}

package/src/responses/publishIn.ts

@@ -4,7 +4,7 @@ import { type FileHandle, link, open, readFile, realpath, unlink } from "node:fs
 import { ResponseFailed } from "#browser/responses/schema.ts";
 
 function uncertain(cause: unknown) {
-	return new ResponseFailed({ cause, code: "Uncertain", message: "Publication may have completed. Re-read the response identity before retrying." });
+	return new ResponseFailed({ cause, code: "Uncertain", message: "Publication may have completed. Re-read the record identity before retrying." });
 }
 function exists(cause: unknown) {
 	return cause instanceof Error && "code" in cause && cause.code === "EEXIST";
@@ -28,9 +28,16 @@ async function linkOrReconcile(temporary: string, name: string, content: string)
 	}
 	return false;
 }
-export async function publishIn(target: FileHandle, root: string, realRoot: string, id: string, content: string) {
+export async function publishIn(
+	target: FileHandle,
+	root: string,
+	realRoot: string,
+	id: string,
+	content: string,
+	namespace: "responses" | "handoffs" = "responses",
+) {
 	const folder = `/proc/self/fd/${target.fd}`;
-	const expected = `${realRoot}/responses`;
+	const expected = `${realRoot}/${namespace}`;
 	async function validate() {
 		if ((await realpath(folder)) !== expected || (await realpath(root)) !== realRoot) {
 			throw new ResponseFailed({ code: "Conflict", message: "The write boundary changed." });

package/src/responses/records.ts

@@ -51,5 +51,8 @@ export function matchesResponse(record: RecordedResponse, input: DraftInput) {
 
 export function malformedResponse(document: MetadataDocument) {
 	const fields = document.parsed.fields;
-	return fields.kind === "response" && !(fields.id && fields.response);
+	return (
+		(fields.kind === "response" && !(fields.id && fields.response))
+		|| (document.file.startsWith("responses/") && document.parsed.diagnostics.some((problem) => problem.field === undefined))
+	);
 }

package/src/rpc/contract.ts

@@ -4,6 +4,7 @@ import { contract } from "@shivaedev/effect-contract/contract.ts";
 import { LiveHint } from "@shivaedev/effect-contract/live.ts";
 import { query } from "@shivaedev/effect-contract/operation.ts";
 import { HistoryInput, HistoryOutput } from "#history/schema.ts";
+import { handoffContract } from "#rpc/handoffContract.ts";
 import { responseContract } from "#rpc/responseContract.ts";
 import { index, navigation, watcher, workspace } from "./keys.ts";
 import { pageKeys } from "./pageKeys.ts";
@@ -19,7 +20,7 @@ const PageUrl = Schema.String.check(
 			const path = new URL(value, "http://127.0.0.1").pathname;
 			return (
 				path === "/"
-				|| ["/_board/work", "/_board/overview", "/_board/changes", "/_board/start", "/_board/respond"].includes(path)
+				|| ["/_board/work", "/_board/overview", "/_board/changes", "/_board/start", "/_board/respond", "/_board/handoff"].includes(path)
 				|| /^\/_board\/item\/[^/]+\/$/u.exec(path) !== null
 				|| /\.md$/iu.exec(path) !== null
 				|| "Expected a local reading URL"
@@ -60,4 +61,4 @@ const ReadWatcher = query("watcher", {
 });
 export const workContract = contract("work-board", { queries: [ReadPage, ReadNavigation, ReadSearch, ReadHistory, ReadWatcher] });
 export const Subscribe = Rpc.make("work-board.subscribe", { error: ReadFailed, stream: true, success: LiveHint });
-export const workRpcs = workContract.add(Subscribe).merge(responseContract);
+export const workRpcs = workContract.add(Subscribe).merge(responseContract).merge(handoffContract);

package/src/rpc/handoffContract.ts

@@ -0,0 +1,26 @@
+import { Schema } from "effect";
+import { contract } from "@shivaedev/effect-contract/contract.ts";
+import { command, query } from "@shivaedev/effect-contract/operation.ts";
+import { Handoff, HandoffInput, HandoffPreview, HandoffReading } from "#browser/handoffs/schema.ts";
+import { ResponseFailed } from "#browser/responses/schema.ts";
+import { index, workspace } from "#rpc/keys.ts";
+
+const locate = query("handoffSource", {
+	payload: { item: Schema.String },
+	reads: () => [workspace.list, index.list],
+	rejections: { ResponseFailed },
+	success: HandoffPreview,
+});
+const read = query("handoffs", {
+	payload: { item: Schema.String },
+	reads: () => [workspace.list, index.list],
+	rejections: { ResponseFailed },
+	success: HandoffReading,
+});
+const prepare = command("prepareHandoff", {
+	invalidates: () => [workspace.list, index.list],
+	payload: HandoffInput,
+	rejections: { ResponseFailed },
+	success: Handoff,
+});
+export const handoffContract = contract("work-board", { commands: [prepare], queries: [locate, read] });

package/src/rpc/server.ts

@@ -2,6 +2,7 @@ import { Clock, Effect, Layer, Ref } from "effect";
 import { HttpIncomingMessage, HttpServerResponse } from "effect/unstable/http";
 import { RpcSerialization, RpcServer } from "effect/unstable/rpc";
 import type { Changes } from "#files/changes.ts";
+import type { handoffService } from "#handoffs/service.ts";
 import { MAX_BYTES } from "#history/limits.ts";
 import { historyResponse } from "#history/response.ts";
 import { HEADERS } from "#http/respond.ts";
@@ -14,15 +15,18 @@ import { hints } from "./hints.ts";
 
 export interface ServerOptions {
 	readonly changes: Changes;
+	readonly handoffs: Effect.Success<ReturnType<typeof handoffService>>;
 	readonly home: string | undefined;
 	readonly index: Effect.Effect<Snapshot, unknown>;
 	readonly page: (url: string) => Effect.Effect<HttpServerResponse.HttpServerResponse, unknown>;
 	readonly responses: Effect.Success<ReturnType<typeof responseService>>;
 }
 
-export const server = Effect.fn("WorkBoard.server")(function* ({ changes, home, index, page, responses }: ServerOptions) {
+export const server = Effect.fn("WorkBoard.server")(function* ({ changes, handoffs, home, index, page, responses }: ServerOptions) {
 	const handlers = workRpcs.toLayer({
 		"work-board.awaitResponse": responses.awaitResponse,
+		"work-board.handoffSource": ({ item }) => handoffs.locate(item),
+		"work-board.handoffs": ({ item }) => handoffs.read(item),
 		"work-board.history": ({ action, baseline }) =>
 			Effect.gen(function* () {
 				const now = yield* Clock.currentTimeMillis;
@@ -43,6 +47,7 @@ export const server = Effect.fn("WorkBoard.server")(function* ({ changes, home,
 				}),
 				Effect.catch((error) => Effect.fail(error instanceof ReadFailed ? error : new ReadFailed({ operation: "page", status: 500 }))),
 			),
+		"work-board.prepareHandoff": handoffs.prepare,
 		"work-board.question": ({ item, request }) => responses.locate(item, request),
 		"work-board.recordResponse": responses.record,
 		"work-board.registerQuestion": responses.register,

package/src/serve-cli.ts

@@ -4,7 +4,7 @@ import { Effect, Layer, Option, Path } from "effect";
 import { Argument, Command, Flag } from "effect/unstable/cli";
 import { HOST, serveBoard } from "./serve.ts";
 
-const VERSION = "0.9.0";
+const VERSION = "0.10.0";
 
 const serve = Effect.fn("WorkBoard.serve")(function* (input: {
 	readonly dir: string;
@@ -26,7 +26,7 @@ const workBoard = Command.make(
 		port: Flag.integer("port").pipe(Flag.withDefault(4747), Flag.withDescription(`The port to listen on at ${HOST}`)),
 		responses: Flag.boolean("responses").pipe(
 			Flag.withDefault(false),
-			Flag.withDescription("Explicitly enable local durable question and response writes (Linux)"),
+			Flag.withDescription("Explicitly enable local durable question, response and handoff writes (Linux)"),
 		),
 	},
 	serve,