@shivaedev/work-board 0.7.2 → 0.9.0

package/src/browser/responses/setup.ts

@@ -0,0 +1,132 @@
+import { draftSession } from "./draftSession.ts";
+import { responsePreview } from "./preview.ts";
+import { questionnaireControls } from "./questionnaireControls.ts";
+import { submitResponse } from "./submit.ts";
+
+function attach() {
+	const doc = document.getElementById("doc");
+	if (doc?.dataset.view !== "response") {
+		return;
+	}
+	const form = doc.querySelector<HTMLFormElement>("#response-form");
+	if (!form || form.dataset.bound === "true") {
+		return;
+	}
+	form.dataset.bound = "true";
+	const status = form.querySelector<HTMLParagraphElement>("#response-status");
+	const author = form.elements.namedItem("author");
+	const body = form.elements.namedItem("body");
+	const type = form.elements.namedItem("type");
+	const supersedes = form.elements.namedItem("supersedes");
+	const submit = form.querySelector<HTMLButtonElement>("#response-submit");
+	const preview = form.querySelector<HTMLPreElement>("#response-preview-content");
+	const clear = form.querySelector<HTMLButtonElement>("#response-clear");
+	const previewButton = form.querySelector<HTMLButtonElement>("#response-preview");
+	if (
+		!(
+			status
+			&& author instanceof HTMLInputElement
+			&& body instanceof HTMLTextAreaElement
+			&& type instanceof HTMLSelectElement
+			&& submit
+			&& preview
+			&& clear
+			&& previewButton
+		)
+	) {
+		return;
+	}
+	if (status.textContent?.includes("JavaScript is required")) {
+		status.textContent = "Draft ready. Preview the Markdown before recording it.";
+	}
+	const item = form.dataset.item ?? "";
+	const request = form.dataset.request ?? "";
+	const revision = form.dataset.revision ?? "";
+	const questionId = form.dataset.question ?? "";
+	const key = `${item}/${request}`;
+	const storage = `work-board:drafts:${document.documentElement.dataset.workspace}`;
+	let storageApi: Storage | undefined;
+	try {
+		storageApi = window.localStorage;
+	} catch {
+		storageApi = undefined;
+	}
+	const drafts = draftSession(key, revision, storageApi, storage, (message) => {
+		status.textContent = message;
+	});
+	let draft = drafts.current();
+	const controls = questionnaireControls(form);
+	let recovery = controls.restore(draft, revision);
+	if (draft.question && draft.question !== questionId && draft.revision === revision) {
+		status.textContent = "Source moved since this draft. Text is retained and selections cleared; review the source and preview before responding.";
+	}
+	if (supersedes instanceof HTMLSelectElement) {
+		supersedes.value = draft.supersedes ?? "";
+	}
+	author.value = draft.author;
+	body.value = draft.body;
+	type.value = draft.type;
+	const fields = { author, body, type };
+	function save() {
+		draft = drafts.update({
+			answers: controls.read(),
+			author: fields.author.value,
+			body: fields.body.value,
+			question: draft.question ?? questionId,
+			recovery,
+			revision: draft.revision,
+			supersedes: supersedes instanceof HTMLSelectElement ? supersedes.value || undefined : undefined,
+			type: fields.type.value,
+		});
+	}
+	form.addEventListener("input", () => {
+		save();
+		preview.hidden = true;
+		submit.disabled = true;
+	});
+	previewButton.disabled = false;
+	clear.disabled = false;
+	previewButton.addEventListener("click", () => {
+		controls.validate(type.value);
+		draft = drafts.update({
+			answers: controls.read(),
+			author: author.value,
+			body: body.value,
+			id: draft.revision === revision && (!draft.question || draft.question === questionId) ? drafts.current().id : `response.${crypto.randomUUID()}`,
+			question: questionId,
+			recovery,
+			revision,
+			supersedes: supersedes instanceof HTMLSelectElement ? supersedes.value || undefined : undefined,
+			type: type.value,
+		});
+		preview.textContent = responsePreview(draft, questionId ?? "", controls.models);
+		preview.hidden = false;
+		submit.disabled = form.dataset.writable !== "true" || !form.checkValidity();
+	});
+	clear.addEventListener("click", drafts.clear);
+	form.addEventListener("submit", async (event) => {
+		event.preventDefault();
+		if (submit.disabled || draft.revision !== revision || draft.question !== questionId || !form.reportValidity()) {
+			return;
+		}
+		submit.disabled = true;
+		previewButton.disabled = true;
+		if (await submitResponse(form, status, drafts, draft)) {
+			draft = drafts.current();
+			recovery = draft.recovery;
+			if (form.isConnected) {
+				body.value = "";
+				controls.restore(draft, revision);
+				if (supersedes instanceof HTMLSelectElement) {
+					supersedes.value = "";
+				}
+			}
+		}
+		previewButton.disabled = false;
+	});
+}
+export function setupResponses() {
+	document.addEventListener("board-page", attach);
+	window.addEventListener("pageshow", attach);
+	attach();
+}

package/src/browser/responses/submissionFields.ts

@@ -0,0 +1,15 @@
+import { Schema } from "effect";
+import type { Draft } from "./drafts.ts";
+import { ResponseKind } from "./schema.ts";
+
+export function submissionFields(pending: Draft, question: string) {
+	return {
+		...(pending.answers === undefined ? {} : { answers: pending.answers }),
+		...(pending.supersedes === undefined ? {} : { supersedes: pending.supersedes }),
+		author: pending.author,
+		body: pending.body,
+		id: pending.id,
+		question,
+		type: Schema.decodeUnknownSync(ResponseKind)(pending.type),
+	};
+}

package/src/browser/responses/submit.ts

@@ -0,0 +1,33 @@
+import { session } from "#browser/session.ts";
+import type { draftSession } from "./draftSession.ts";
+import type { Draft } from "./drafts.ts";
+import { ResponseFailed } from "./schema.ts";
+import { submissionFields } from "./submissionFields.ts";
+
+export async function submitResponse(form: HTMLFormElement, status: HTMLParagraphElement, drafts: ReturnType<typeof draftSession>, pending: Draft) {
+	status.dataset.outcome = "pending";
+	status.textContent = "Pending: registering reviewed context, then recording response…";
+	const native = session(window);
+	try {
+		const question = await native.mutate(
+			native.responses.registerQuestion.run({ item: form.dataset.item ?? "", request: form.dataset.request ?? "", revision: pending.revision }),
+		);
+		await native.mutate(native.responses.recordResponse.run(submissionFields(pending, question.id)));
+		if (form.isConnected) {
+			status.dataset.outcome = "saved";
+			status.textContent = `Saved: responses/${pending.id}.md. This records feedback, not acceptance.`;
+		}
+		const cleared = drafts.saved(pending);
+		if (!cleared && form.isConnected) {
+			status.textContent += " Your current draft remains unsaved.";
+		}
+		return cleared;
+	} catch (error) {
+		if (form.isConnected) {
+			const outcome = error instanceof ResponseFailed && error.code !== "Uncertain" ? "rejected" : "uncertain";
+			status.dataset.outcome = outcome;
+			status.textContent = `${outcome === "rejected" ? "Rejected" : "Uncertain"}: ${String(error)}. Draft retained. Preview and retry with the same identity; saved content will be reconciled.`;
+		}
+		return false;
+	}
+}

package/src/cli.ts

@@ -1,24 +1,16 @@
 #!/usr/bin/env node
-import { NodeRuntime, NodeServices } from "@effect/platform-node";
-import { Effect, Layer, Option, Path } from "effect";
-import { Argument, Command, Flag } from "effect/unstable/cli";
-import { HOST, serveBoard } from "./serve.ts";
+const action = process.argv[2];
+if (action === "wait" || action === "response" || action === "question") {
+	try {
+		const entry: typeof import("#responses/agent-cli.ts") = await import(new URL("../assets/agent.js", import.meta.url).href);
+		await entry.runAgent(process.argv.slice(2));
+	} catch (error) {
+		process.stderr.write(`${String(error)}\n`);
+		process.exitCode ??= 1;
+	}
+} else {
+	const entry = await import("./serve-cli.ts");
+	entry.runServe();
+}
 
-const VERSION = "0.7.2";
-
-const serve = Effect.fn("WorkBoard.serve")(function* (input: { readonly dir: string; readonly port: number; readonly home: Option.Option<string> }) {
-	const path = yield* Path.Path;
-	return yield* Layer.launch(serveBoard({ home: Option.getOrUndefined(input.home), port: input.port, root: path.resolve(input.dir) }));
-});
-
-const workBoard = Command.make(
-	"work-board",
-	{
-		dir: Argument.directory("dir", { mustExist: true }).pipe(Argument.withDescription("The folder of markdown files to serve")),
-		home: Flag.string("home").pipe(Flag.optional, Flag.withDescription("The file shown as a board at /, relative to the folder")),
-		port: Flag.integer("port").pipe(Flag.withDefault(4747), Flag.withDescription(`The port to listen on at ${HOST}`)),
-	},
-	serve,
-).pipe(Command.withDescription("Serve a folder of markdown files as a live page that updates in place when a file changes."));
-
-Command.run(workBoard, { version: VERSION }).pipe(Effect.provide(NodeServices.layer), NodeRuntime.runMain);
+export {};

package/src/files/changes.ts

@@ -10,6 +10,7 @@ export interface Changes {
 	readonly events: PubSub.PubSub<Change>;
 	readonly files: Effect.Effect<readonly MarkdownFile[], PlatformError.PlatformError>;
 	readonly realRoot: string;
+	readonly refresh?: Effect.Effect<void>;
 	readonly revision: Effect.Effect<number>;
 	readonly sequence?: Effect.Effect<number>;
 	readonly watching: Ref.Ref<boolean>;
@@ -65,6 +66,6 @@ export const watchChanges = Effect.fn("WorkBoard.watchChanges")(function* (root:
 		yield* Ref.set(cached, Option.some({ files: listed, generation: now }));
 		return listed;
 	});
-	const changes: Changes = { events, files, realRoot, revision: Ref.get(generation), sequence: Ref.get(sequence), watching };
+	const changes: Changes = { events, files, realRoot, refresh: stale, revision: Ref.get(generation), sequence: Ref.get(sequence), watching };
 	return changes;
 });

package/src/http/respond.ts

@@ -6,6 +6,8 @@ const POLICY = [
 	"style-src 'self' 'unsafe-inline'",
 	"img-src 'self' data: https:",
 	"object-src 'none'",
+	"form-action 'none'",
+	"frame-src 'none'",
 	"base-uri 'none'",
 	"frame-ancestors 'none'",
 ].join("; ");

package/src/metadata/backlinks.ts

@@ -10,6 +10,11 @@ export interface Backlink {
 function references(document: MetadataDocument, model: MetadataModel) {
 	const { fields, lines } = document.parsed;
 	return [
+		...(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
+			? [{ kind: "superseding response", line: lines.response, target: referenceFile(fields.response.supersedes, model) }]
+			: []),
 		...(fields.attention?.flatMap((request, index) =>
 			request.unblocks.map((target, targetIndex) => ({
 				kind: "attention target",

package/src/metadata/problems.ts

@@ -27,6 +27,9 @@ 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.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 }] : []),
 		...(fields.attention?.flatMap((request, index) =>
 			request.unblocks.map((target, targetIndex) => ({ field: "attention", key: `attention.${index}.unblocks.${targetIndex}`, target })),
 		) ?? []),

package/src/metadata/schema.ts

@@ -1,6 +1,8 @@
 import { Schema } from "effect";
+import { QuestionRecord, ResponseRecord } from "#browser/responses/schema.ts";
+import { Identity as SourceIdentity } from "#path/Identity.ts";
 
-export const Identity = Schema.String.check(Schema.isPattern(/^[a-zA-Z\d][a-zA-Z\d._-]*$/u));
+export const Identity = SourceIdentity;
 export const Reference = Schema.String.check(Schema.isPattern(/^[a-zA-Z\d][a-zA-Z\d._-]*(?:#[a-zA-Z\d][a-zA-Z\d._-]*)?$/u));
 const Text = Schema.String.check(Schema.isPattern(/\S/u));
 const Attention = Schema.Struct({
@@ -36,10 +38,12 @@ export const Metadata = Schema.Struct({
 	evidence: Schema.optional(Schema.Array(Evidence)),
 	id: Schema.optional(Identity),
 	items: Schema.optional(Schema.Array(Identity)),
-	kind: Schema.optional(Schema.Literals(["task", "investigation", "decision", "result", "project", "board"])),
+	kind: Schema.optional(Schema.Literals(["task", "investigation", "decision", "result", "project", "board", "question", "response"])),
 	nextAction: Schema.optional(Text),
 	owner: Schema.optional(Text),
+	question: Schema.optional(QuestionRecord),
 	relationships: Schema.optional(Schema.Array(Relationship)),
+	response: Schema.optional(ResponseRecord),
 	status: Schema.optional(Text),
 }).pipe(Schema.encodeKeys({ nextAction: "next_action" }));
 export type Metadata = typeof Metadata.Type;

package/src/page/attentionDetails.ts

@@ -1,4 +1,5 @@
 import { attentionSource } from "#attention/requests.ts";
+import { identityUrl } from "#metadata/links.ts";
 import type { MetadataModel } from "#metadata/model.ts";
 import type { ParsedMetadata } from "#metadata/parse.ts";
 import { escapeHtml } from "./escape.ts";
@@ -12,7 +13,7 @@ export function attentionDetails(parsed: ParsedMetadata, file: string, model: Me
 	return `<h3>Recorded attention requests</h3><p>Open/closed is source state. Closing a request does not establish acceptance or record an answer.</p><ul>${requests
 		.map(
 			(request, index) =>
-				`<li id="${attentionSource({ file, parsed }, index)}" tabindex="-1"><b>${escapeHtml(request.kind)} · ${escapeHtml(request.id)} · ${escapeHtml(request.state)}</b><p>${escapeHtml(request.reason)}</p><p>Response needed from: ${request.responseFrom.map(escapeHtml).join(", ")}</p><p>Recorded to unblock: ${request.unblocks.map((target) => referenceHtml(target, target, model)).join(", ")}</p><p>Source: ${escapeHtml(file)}:${parsed.lines[`attention.${index}`] ?? parsed.lines.attention ?? 2}</p></li>`,
+				`<li id="${attentionSource({ file, parsed }, index)}" tabindex="-1"><b>${escapeHtml(request.kind)} · ${escapeHtml(request.id)} · ${escapeHtml(request.state)}</b><p>${escapeHtml(request.reason)}</p><p>Response needed from: ${request.responseFrom.map(escapeHtml).join(", ")}</p><p>Recorded to unblock: ${request.unblocks.map((target) => referenceHtml(target, target, model)).join(", ")}</p><p><a href="/_board/respond?item=${encodeURIComponent(parsed.fields.id ?? "")}&amp;request=${encodeURIComponent(request.id)}">Respond to this request</a> · <a href="${identityUrl(parsed.fields.id ?? "")}">Reviewed item</a></p><p>Source: ${escapeHtml(file)}:${parsed.lines[`attention.${index}`] ?? parsed.lines.attention ?? 2}</p></li>`,
 		)
 		.join("")}</ul>`;
 }

package/src/page/metadataDetails.ts

@@ -18,6 +18,12 @@ export function metadataDetails(parsed: ParsedMetadata, file: string, model: Met
 			? `<h3>Declared board membership</h3><ul>${fields.items.map((id) => `<li>${referenceHtml(id, id, model)}</li>`).join("")}</ul>`
 			: "",
 
+		fields.question
+			? `<h3>Reviewed question</h3><p>${referenceHtml(fields.question.item, fields.question.item, model)} / ${escapeHtml(fields.question.request)} · ${escapeHtml(fields.question.reason)}</p><p>Reviewed SHA-256: <code>${fields.question.reviewedRevision}</code>. Registered: ${new Date(fields.question.registeredAt).toISOString()}. Unanswered deadline: ${new Date(fields.question.deadline).toISOString()}.</p>`
+			: "",
+		fields.response
+			? `<h3>Recorded response</h3><p>${referenceHtml(fields.response.question, fields.response.question, model)} · ${escapeHtml(fields.response.author)} · ${escapeHtml(fields.response.type)}</p><p>Reviewed SHA-256: <code>${fields.response.reviewedRevision}</code>. This is authored feedback, not verified acceptance.</p>${fields.response.supersedes ? `<p>Explicitly supersedes ${referenceHtml(fields.response.supersedes, fields.response.supersedes, model)}.</p>` : ""}`
+			: "",
 		criteriaEvidence(parsed, model),
 		attentionDetails(parsed, file, model),
 		recordedEvidence(parsed, file, model),

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/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/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" = false,
+	view: boolean | "overview" | "changes" | "start" | "response" = false,
 ): string =>
 	[
 		`<!doctype html><html lang="en" data-workspace="${escapeHtml(workspace)}"><head><meta charset="utf-8">`,

package/src/page/style.ts

@@ -96,4 +96,6 @@ export const style =
 	+ workStyle()
 	+ attentionStyle()
 	+ visualStyles
-	+ documents;
+	+ documents
+	+ ".response-panel fieldset, .questionnaire-reading { min-width: 0; border: 1px solid var(--border); border-radius: 12px; padding: 1rem; margin: 1rem 0; } .response-panel legend { font-weight: 650; } .response-panel .question-option { display: grid; grid-template-columns: 1.5rem minmax(0, 1fr); gap: .75rem; padding: 1rem; margin: .5rem 0; border: 1px solid var(--border); border-radius: 8px; } .response-panel .question-option:has(input:checked) { border-color: var(--link); background: var(--surface); } .response-panel .question-option input { width: 1.2rem; height: 1.2rem; margin-top: .2rem; accent-color: var(--link); } .response-panel .question-option label { font-weight: 650; cursor: pointer; } .response-panel .question-option p { margin-top: .5rem; } .response-panel #response-history article { border-top: 1px solid var(--border); margin-top: 1.5rem; padding-top: 1rem; } .response-context, .question-option, .response-panel fieldset { overflow-wrap: anywhere; }"
+	+ ".response-panel { max-width: 850px; margin: auto; padding: 1.5rem; } .response-panel form { display: grid; gap: 1rem; } .response-panel label { display: grid; gap: .5rem; } .response-panel input, .response-panel textarea, .response-panel select { width: 100%; box-sizing: border-box; font: inherit; background: var(--surface); color: inherit; padding: .75rem; border: 1px solid var(--border); } .response-panel pre, .response-panel code { white-space: pre-wrap; overflow-wrap: anywhere; }";

package/src/page/swap.ts

@@ -18,6 +18,9 @@ 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 tool of copy.querySelectorAll("[data-visual-tools], [data-image-error], [data-diagram-error]")) tool.remove();
   for (const node of [copy, ...copy.querySelectorAll("*")]) {
     node.removeAttribute("data-live-change");

package/src/path/Identity.ts

@@ -0,0 +1,3 @@
+import { Schema } from "effect";
+
+export const Identity = Schema.String.check(Schema.isPattern(/^[a-zA-Z\d][a-zA-Z\d._-]*$/u));

package/src/render/markdown.ts

@@ -14,16 +14,18 @@ import { documentLinks } from "./documentLinks.ts";
 import { RenderFailed } from "./failed.ts";
 import { footnoteIds } from "./footnotes.ts";
 import { Highlighter } from "./highlighter.ts";
+import { questionnaireDocuments } from "./questionnaireDocuments.ts";
 
 export interface RenderOptions {
 	readonly file?: string;
 	readonly headings?: ReturnType<typeof documentHeadings>;
 	readonly idPrefix?: string;
+	readonly safe?: boolean;
 }
 
 export const renderMarkdown = Effect.fn("WorkBoard.renderMarkdown")(function* (source: string, options: RenderOptions = {}) {
 	const highlighter = yield* Highlighter;
-	const plugins: PluggableList = [rehypeRaw, codeBlocks(highlighter)];
+	const plugins: PluggableList = [...(options.safe ? [] : [rehypeRaw]), codeBlocks(highlighter)];
 	if (options.idPrefix !== undefined) {
 		plugins.push(footnoteIds(options.idPrefix));
 	}
@@ -41,7 +43,8 @@ export const renderMarkdown = Effect.fn("WorkBoard.renderMarkdown")(function* (s
 					children: source,
 					components: { img: ({ node: _node, ...props }) => createElement("img", { ...props, loading: "lazy" }) },
 					rehypePlugins: plugins,
-					remarkPlugins: [remarkGfm, remarkDirective, visualDocuments, callouts],
+					remarkPlugins: [remarkGfm, remarkDirective, questionnaireDocuments, visualDocuments, callouts],
+					skipHtml: options.safe,
 				}),
 			),
 	});

package/src/render/questionnaireDocuments.ts

@@ -0,0 +1,12 @@
+import type { Root } from "mdast";
+import { visit } from "unist-util-visit";
+
+export function questionnaireDocuments() {
+	return (tree: Root) => {
+		visit(tree, "containerDirective", (node) => {
+			if (node.name === "question" || node.name === "option") {
+				node.data = { hName: "section", hProperties: { className: ["questionnaire-reading", `questionnaire-${node.name}`] } };
+			}
+		});
+	};
+}

package/src/render/visualDocuments.ts

@@ -43,6 +43,9 @@ export function visualDocuments() {
 			if (!isDirective(directive) || index === undefined || parent === undefined) {
 				return;
 			}
+			if (directive.type === "containerDirective" && ["question", "option"].includes(directive.name)) {
+				return;
+			}
 			const failure = failureOf(directive, source);
 			if (failure === undefined) {
 				return;

package/src/responses/agent-cli.ts

@@ -0,0 +1,35 @@
+import * as Effect from "effect/Effect";
+import { agentRequest } from "./agent.ts";
+import { flags } from "./flags.ts";
+
+export async function runAgent(args: readonly string[]) {
+	const [action, request, ...options] = args;
+	if ((action !== "wait" && action !== "response" && action !== "question") || !request) {
+		throw new Error(
+			"Usage: work-board question <item>/<request> | wait <question-id> [--after <response-id>] | response <question-id> [--port 4747]",
+		);
+	}
+	const parsed = flags(options);
+	const controller = new AbortController();
+	function cancel() {
+		controller.abort();
+	}
+	process.once("SIGINT", cancel);
+	process.once("SIGTERM", cancel);
+	try {
+		const result = await Effect.runPromise(
+			agentRequest(action, { ...parsed, request }, (text) => process.stderr.write(`${text}\n`)).pipe(Effect.result),
+			{ signal: controller.signal },
+		);
+		if (result._tag === "Failure") {
+			if (result.failure instanceof Error && "code" in result.failure && result.failure.code === "Unanswered") {
+				process.exitCode = 2;
+			}
+			throw result.failure;
+		}
+		process.stdout.write(`${JSON.stringify(result.success)}\n`);
+	} finally {
+		process.removeListener("SIGINT", cancel);
+		process.removeListener("SIGTERM", cancel);
+	}
+}

package/src/responses/agent.ts

@@ -0,0 +1,59 @@
+import * as NodeHttpClient from "@effect/platform-node/NodeHttpClient";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as RpcClient from "effect/unstable/rpc/RpcClient";
+import * as RpcSerialization from "effect/unstable/rpc/RpcSerialization";
+import { responseContract } from "#rpc/responseContract.ts";
+import { waitForResponse } from "./waitFor.ts";
+
+export interface AgentOptions {
+	readonly after?: string | undefined;
+	readonly request: string;
+	readonly revision?: string | undefined;
+	readonly url: string;
+}
+function protocol(url: string) {
+	return RpcClient.layerProtocolHttp({ url: `${url}/_board/rpc` }).pipe(Layer.provide([NodeHttpClient.layerNodeHttp, RpcSerialization.layerNdjson]));
+}
+function validate(url: string) {
+	const parsed = new URL(url);
+	if (
+		parsed.protocol !== "http:"
+		|| !["127.0.0.1", "localhost", "[::1]"].includes(parsed.hostname)
+		|| parsed.username
+		|| parsed.password
+		|| parsed.pathname !== "/"
+		|| parsed.search
+		|| parsed.hash
+	) {
+		throw new Error("Use a loopback Work Board URL, such as http://127.0.0.1:4747.");
+	}
+	return parsed.origin;
+}
+export function agentRequest(action: "question" | "response" | "wait", options: AgentOptions, diagnostic: (text: string) => void = () => undefined) {
+	return Effect.scoped(
+		Effect.gen(function* () {
+			const client = yield* RpcClient.make(responseContract, { flatten: true });
+			const [item, request, extra] = options.request.split("/");
+			if (action === "question") {
+				if (!(item && request) || extra) {
+					return yield* Effect.fail(new Error("Use question <item>/<request>."));
+				}
+				return yield* client("work-board.question", { item, request });
+			}
+			let id = options.request;
+			if (request !== undefined) {
+				if (action !== "wait" || !item || !request || extra || !options.revision) {
+					return yield* Effect.fail(new Error("Use wait <item>/<request> --revision <reviewed SHA-256>, or wait <registered-question-id>."));
+				}
+				const question = yield* client("work-board.registerQuestion", { item, request, revision: options.revision });
+				id = question.id;
+				diagnostic(`Registered ${id}; reattach with work-board wait ${id}. Deadline: ${new Date(question.question.deadline).toISOString()}`);
+			}
+			if (action === "response") {
+				return yield* client("work-board.responses", { question: id });
+			}
+			return yield* waitForResponse(() => client("work-board.awaitResponse", { after: options.after, question: id }), diagnostic);
+		}),
+	).pipe(Effect.provide(protocol(validate(options.url))));
+}

package/src/responses/await.ts

@@ -0,0 +1,21 @@
+import { Clock, Effect } from "effect";
+import { type Reading, ResponseFailed } from "#browser/responses/schema.ts";
+import { outcome } from "./outcome.ts";
+
+export function awaitResponse(read: (id: string) => Effect.Effect<Reading, ResponseFailed>) {
+	return Effect.fn("WorkBoard.awaitResponse")(function* (input: { readonly question: string; readonly after?: string | undefined }) {
+		const lease = (yield* Clock.currentTimeMillis) + 30_000;
+		while (true) {
+			const result = yield* read(input.question);
+			const now = yield* Clock.currentTimeMillis;
+			const state = outcome(result, input.after, now);
+			if (state.kind === "missing_cursor") {
+				return yield* Effect.fail(new ResponseFailed({ code: "Missing", message: "The next-response cursor is not recorded for this question." }));
+			}
+			if (state.kind !== "pending" || now >= lease) {
+				return { expired: state.kind === "unanswered", question: result.question, response: state.kind === "response" ? state.response : undefined };
+			}
+			yield* Effect.sleep("1 second");
+		}
+	});
+}

package/src/responses/composerHtml.ts

@@ -0,0 +1,28 @@
+import { Effect } from "effect";
+import type { QuestionPreview, RecordedResponse } from "#browser/responses/schema.ts";
+import { fileUrl } from "#files/url.ts";
+import { escapeHtml } from "#page/escape.ts";
+import { renderMarkdown } from "#render/markdown.ts";
+import { templateHtml } from "./templateHtml.ts";
+
+export const composerHtml = Effect.fn("WorkBoard.composerHtml")(function* (
+	q: QuestionPreview,
+	records: readonly RecordedResponse[],
+	enabled: boolean,
+) {
+	const template = yield* templateHtml(q.context, q.request, q.source);
+	const history = yield* Effect.forEach(records, (record) =>
+		Effect.map(
+			renderMarkdown(record.body, { file: `responses/${record.id}.md`, safe: true }),
+			(html) =>
+				`<article id="${escapeHtml(record.id)}"><h3><a href="/responses/${record.id}.md">${escapeHtml(record.response.author)} · ${record.response.type}</a></h3><p>${record.response.question === q.id ? "This reviewed revision" : "Earlier reviewed context — does not approve the current source"} · <code>${record.response.reviewedRevision}</code></p>${record.response.supersedes ? `<p>Explicitly supersedes <a href="/responses/${escapeHtml(record.response.supersedes)}.md">${escapeHtml(record.response.supersedes)}</a>.</p>` : ""}${html}</article>`,
+		),
+	);
+	const prior = records
+		.map(
+			(record) =>
+				`<option value="${escapeHtml(record.id)}">${escapeHtml(record.id)} · ${escapeHtml(record.response.author)} · ${record.response.reviewedRevision.slice(0, 12)}</option>`,
+		)
+		.join("");
+	return `<section class="response-panel"><h1>Respond to ${escapeHtml(q.item)} / ${escapeHtml(q.request)}</h1><p>${escapeHtml(q.reason)}</p><p><a href="${fileUrl(q.source)}">Source: ${escapeHtml(q.source)}</a> · Reviewed SHA-256: <code>${q.reviewedRevision}</code></p><p>Saved replies are authored feedback. They do not close the request or establish acceptance.</p><section class="response-context">${template.background}</section><details><summary>Exact source being reviewed</summary><pre>${escapeHtml(q.context)}</pre></details><form id="response-form" data-question="${q.id}" data-writable="${enabled}" data-item="${escapeHtml(q.item)}" data-request="${escapeHtml(q.request)}" data-revision="${q.reviewedRevision}"><label>Local author label <input name="author" maxlength="200" required></label><label>Response kind <select name="type"><option value="answer">Answer (including no)</option><option value="clarify">Ask back / clarify</option><option value="not_now">Not now</option></select></label>${template.controls}<label>${template.hasPrompts ? "Overall response / next action (optional)" : "Your response"}<textarea name="body" rows="8" maxlength="32768" ${template.hasPrompts ? "" : "required"}></textarea></label><label>Supersedes an earlier response (optional)<select name="supersedes"><option value="">Adds feedback; does not supersede</option>${prior}</select></label><pre id="response-draft-recovery" hidden></pre><p>Submit the whole packet together. Drafts stay in this browser for 30 days after the last edit, with a 2 MiB workspace limit. Saved responses are Markdown files in responses/.</p><button id="response-preview" type="button" disabled>Preview Markdown</button><pre id="response-preview-content" hidden></pre><button id="response-submit" type="submit" disabled>Record response</button><button id="response-clear" type="button" disabled>Clear workspace drafts</button><p id="response-status" role="status">${enabled ? "JavaScript is required to record a response." : "Read-only mode. Restart with --responses to explicitly enable local writes."}</p></form><section id="response-history"><h2>Recorded responses</h2>${history.join("") || "<p>No response is recorded for this source revision.</p>"}</section></section>`;
+});

package/src/responses/flags.ts

@@ -0,0 +1,22 @@
+export function flags(args: readonly string[]) {
+	const values = new Map<string, string>();
+	for (let index = 0; index < args.length; index += 2) {
+		const name = args[index];
+		const value = args[index + 1];
+		if (!(name && value && ["--port", "--url", "--revision", "--after"].includes(name))) {
+			throw new Error("Use --port, --url, --revision or --after, each with a value.");
+		}
+		if (values.has(name)) {
+			throw new Error(`Repeated option ${name}`);
+		}
+		values.set(name, value);
+	}
+	const port = values.get("--port") ?? "4747";
+	if (/^\d{1,5}$/u.exec(port) === null || Number(port) > 65_535 || Number(port) < 1) {
+		throw new Error("Invalid port.");
+	}
+	if (values.has("--url") && values.has("--port")) {
+		throw new Error("Choose --url or --port.");
+	}
+	return { after: values.get("--after"), revision: values.get("--revision"), url: values.get("--url") ?? `http://127.0.0.1:${port}` };
+}

package/src/responses/history.ts

@@ -0,0 +1,18 @@
+import type { QuestionPreview } from "#browser/responses/schema.ts";
+import type { Snapshot } from "#search/snapshot.ts";
+import { malformedResponse, questionFrom, responsesFor } from "./records.ts";
+
+export function responseHistory(data: Snapshot, preview: QuestionPreview) {
+	if (data.unavailable.length > 0 || data.documents.some(malformedResponse)) {
+		throw new Error("Response history is incomplete or malformed.");
+	}
+	const questions = data.documents.flatMap((document) => {
+		const question = questionFrom(document);
+		return question && question.question.item === preview.item && question.question.request === preview.request ? [question] : [];
+	});
+	const responses = questions.flatMap((question) => responsesFor(data.documents, question).responses);
+	if ([...questions, ...responses].some((record) => data.model.ids.get(record.id)?.length !== 1)) {
+		throw new Error("Response history includes ambiguous identities.");
+	}
+	return responses.sort((a, b) => b.response.recordedAt - a.response.recordedAt);
+}