partforge 0.4.0 → 0.5.1

package/README.md

@@ -50,6 +50,11 @@ hide internal params, and keep the interface simple while staying deeply adjusta
 `src/parts/demo.js` is a minimal worked example; run `npm run dev` and open
 `/demo.html` to see it live.
 
+- **Agent clarification (`request-a-pick`):** an external tool can ask the user to click
+  geometry and get the `Selection` back — serve with `?pickserver`, drive with
+  `partforge pick-serve` + `partforge pick "<prompt>" …`. See
+  `skills/partforge/SKILL.md` and the authoring guide.
+
 ## License
 
 MIT

package/bin/cli.js

@@ -8,54 +8,76 @@ import { detectBackend } from "../src/framework/geometry/probe.js";
 import { bootOcctKernel } from "../src/testing/occt.js";
 import { measure } from "../src/testing/measure.js";
 import { renderViews } from "../src/testing/render.js";
+import { createPickServer, requestPicks, formatPickResult } from "../src/framework/pick-request/server.js";
 
 const die = (msg) => { console.error(msg); process.exit(1); };
 const slug = (s) => String(s).toLowerCase().replace(/\s+/g, "-");
 
-const [, , cmd, partPath, ...rest] = process.argv;
+const [, , cmd, ...args] = process.argv;
 const flags = {};
 const positional = [];
-for (let i = 0; i < rest.length; i++) {
-  if (rest[i].startsWith("--")) {
-    const key = rest[i].slice(2);
-    flags[key] = rest[i + 1] && !rest[i + 1].startsWith("--") ? rest[++i] : true;
-  } else positional.push(rest[i]);
+for (let i = 0; i < args.length; i++) {
+  if (args[i].startsWith("--")) {
+    const key = args[i].slice(2);
+    flags[key] = args[i + 1] && !args[i + 1].startsWith("--") ? args[++i] : true;
+  } else positional.push(args[i]);
 }
-const view = positional[0];
 
-if (!["measure", "render"].includes(cmd)) die("usage: partforge <measure|render> <part-module> [view] [flags]");
-if (!partPath) die(`usage: partforge ${cmd} <part-module> [view]`);
+const USAGE = "usage: partforge <measure|render|pick-serve|pick> …";
 
-const mod = await import(pathToFileURL(resolve(process.cwd(), partPath)))
-  .catch((e) => die(`cannot load part "${partPath}": ${e.message}`));
-const part = mod.default;
-if (!part?.parts || !part?.views) die(`"${partPath}" has no default-exported PartDefinition`);
-
-let kernel;
-if (detectBackend(part) === "occt") {
-  kernel = await bootOcctKernel();
-} else {
-  const wasm = await Module(); wasm.setup();
-  kernel = createManifoldKernel(wasm, { quality: "preview" });
+// --- pick-serve / pick: no part module, no kernel boot --------------------------
+if (cmd === "pick-serve") {
+  const port = Number(flags.port) || 4518;
+  const timeoutMs = (Number(flags.timeout) || 120) * 1000;
+  const { port: bound } = await createPickServer({ port, timeoutMs }).start();
+  console.log(`partforge pick-server listening on http://127.0.0.1:${bound}`);
+  // keep the process alive serving requests
+} else if (cmd === "pick") {
+  if (positional.length === 0) die('usage: partforge pick "<prompt>" ["<prompt>" …] [--port N]');
+  const port = Number(flags.port) || 4518;
+  const out = await requestPicks({ port, prompts: positional }).catch((e) => die(e.message));
+  console.log(formatPickResult(out));
+  process.exit(out.status === "done" ? 0 : 1);
+} else if (!["measure", "render"].includes(cmd)) {
+  die(USAGE);
 }
 
-try {
-  if (cmd === "measure") {
-    const report = measure(kernel, part, view);
-    printMeasure(report);
-    const file = `measure-${slug(report.part)}-${report.view}.json`;
-    writeFileSync(file, JSON.stringify(report, null, 2));
-    console.log(`\nwrote ${file}`);
-    if (flags.json) console.log(JSON.stringify(report, null, 2));
-    process.exit(report.ok ? 0 : 1);
+const partPath = positional[0];
+const view = positional[1];
+if (["measure", "render"].includes(cmd) && !partPath) die(`usage: partforge ${cmd} <part-module> [view]`);
+
+if (["measure", "render"].includes(cmd)) {
+  const mod = await import(pathToFileURL(resolve(process.cwd(), partPath)))
+    .catch((e) => die(`cannot load part "${partPath}": ${e.message}`));
+  const part = mod.default;
+  if (!part?.parts || !part?.views) die(`"${partPath}" has no default-exported PartDefinition`);
+
+  let kernel;
+  if (detectBackend(part) === "occt") {
+    kernel = await bootOcctKernel();
   } else {
-    const views = typeof flags.views === "string" ? flags.views.split(",") : undefined;
-    const files = await renderViews(kernel, part, view, { views, out: flags.out || "render" });
-    for (const f of files) console.log(`wrote ${f}`);
-    process.exit(0);
+    const wasm = await Module(); wasm.setup();
+    kernel = createManifoldKernel(wasm, { quality: "preview" });
+  }
+
+  try {
+    if (cmd === "measure") {
+      const report = measure(kernel, part, view);
+      printMeasure(report);
+      const file = `measure-${slug(report.part)}-${report.view}.json`;
+      writeFileSync(file, JSON.stringify(report, null, 2));
+      console.log(`\nwrote ${file}`);
+      if (flags.json) console.log(JSON.stringify(report, null, 2));
+      process.exit(report.ok ? 0 : 1);
+    } else {
+      const views = typeof flags.views === "string" ? flags.views.split(",") : undefined;
+      const files = await renderViews(kernel, part, view, { views, out: flags.out || "render" });
+      for (const f of files) console.log(`wrote ${f}`);
+      process.exit(0);
+    }
+  } catch (e) {
+    die(`${cmd} failed: ${e.message || e}`);
   }
-} catch (e) {
-  die(`${cmd} failed: ${e.message || e}`);
 }
 
 function printMeasure(r) {

package/docs/AUTHORING-PARTS.md

@@ -467,3 +467,21 @@ entirely on OCCT, its fillets are exact in the STEP **and** present in the print
   `place(..., { purpose: "export" })` may depend on `view`.
 - Keep geometry backend-agnostic (kernel calls only) so it works in both backends; only
   STEP requires OCCT.
+
+---
+
+## Interactive clarification: request-a-pick
+
+An external tool (e.g. an AI agent editing your part) can ask the *user* to click
+geometry and receive the `Selection` back, closing the loop in the other direction
+from `?pick`.
+
+- Serve your app with **`?pickserver`** (or `?pickserver=http://host:port`) to enable
+  it. While idle nothing changes; when the local pick-server requests a click, a banner
+  appears ("🤖 Claude needs you to click …") and the picker arms for one click.
+- The agent side runs `partforge pick-serve` once, then `partforge pick "<prompt>" …`
+  for one or more clicks (collected in order, returned together). The CLI blocks until
+  the user clicks, then prints the `Selection`(s) as JSON.
+
+See the bundled skill `skills/partforge/SKILL.md` for the agent workflow. This is plain
+click-routing — no LLM logic lives in partforge.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,7 @@
   "files": [
     "src",
     "bin",
+    "skills/partforge/SKILL.md",
     "docs/AUTHORING-PARTS.md",
     "README.md"
   ],

package/skills/partforge/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: partforge-request-pick
+description: Use when editing a partforge part for a user who has the live app open and you need them to point at geometry — ask for one or more clicks and get the Selection(s) back.
+---
+
+# partforge: request-a-pick
+
+When you're editing a partforge part and you're unsure *which* face, edge, hole, or
+sub-part the user means, don't guess — ask them to click it in the live app. Their
+click comes back to you as a structured `Selection` (sub-part, local CAD point,
+surface normal, the parameters they were viewing).
+
+## When to use
+
+- The user's request is geometrically ambiguous ("make this thicker", "fillet that
+  edge", "move the hole") and more than one feature could match.
+- You need a concrete location/normal to drive an edit.
+
+## One-time setup (per session)
+
+Start the pick-server (it bridges the app and this CLI). The user must have the app
+open with `?pickserver` (e.g. `http://localhost:5173/?pickserver`).
+
+```bash
+partforge pick-serve &     # default http://127.0.0.1:4518
+```
+
+## Requesting clicks
+
+Ask for one or many — they're collected in order and returned together:
+
+```bash
+partforge pick "click the face you want filleted"
+partforge pick "click the mounting hole" "click the top edge" "click the boss"
+```
+
+Tell the user out loud to check their browser ("I've put a prompt in your browser —
+click the face you want filleted"). The command **blocks** until they click (or
+timeout), then prints a summary plus JSON:
+
+```json
+{ "status": "done", "picks": [ { "prompt": "...", "selection": { "subPart": "...", "point": [...], "normal": [...], "params": {...} } } ] }
+```
+
+Picks come back **in request order**, each echoing its prompt, so you can map them.
+
+## Handling outcomes
+
+- `done` — proceed with the returned `selection`(s).
+- `timeout` — the user didn't click in time; `picks` holds any collected so far. Ask
+  again or fall back to asking in words.
+- `cancelled` — the user clicked "Can't find it"; reconsider what you're asking for.
+- `busy` (exit non-zero) — a request is already in flight; wait and retry.
+
+## Notes
+
+- This only *reads* a click — it never edits files. You make the edits yourself after.
+- The server is localhost-only and holds one request at a time.

package/src/framework/app.css

@@ -163,4 +163,39 @@ button.action:disabled { opacity: .5; cursor: default; }
 /* relevance: controls/sections that don't affect the on-screen parts */
 .irrelevant { opacity: 0.45; }
 .irrelevant:hover { opacity: 0.7; }
-.section-hidden { display: none; }
+.section-hidden { display: none; }
+
+/* request-a-pick: agent prompt banner, floated top-centre well below the part tabs,
+   laid out like a chat message (avatar + text). Slides/fades in when shown; themed. */
+#pf-pick-banner {
+  position: fixed; top: 78px; left: 50%; transform: translateX(-50%);
+  z-index: 30; max-width: min(56ch, calc(100vw - 24px));
+  padding: 10px 36px 10px 12px;
+  background: var(--surface); color: var(--text);
+  border: 1px solid var(--border); border-radius: 10px;
+  box-shadow: 0 6px 24px rgba(0,0,0,.35);
+  font-size: 12px; line-height: 1.45;
+  animation: pf-pick-in .18s ease;
+}
+#pf-pick-banner .pf-pick-row { display: flex; align-items: center; gap: 10px; }
+#pf-pick-banner .pf-pick-avatar {
+  flex: none; width: 30px; height: 30px; border-radius: 50%; font-size: 17px;
+  display: flex; align-items: center; justify-content: center;
+  background: var(--surface-2); border: 1px solid var(--border);
+}
+#pf-pick-banner .pf-pick-msg { display: flex; flex-direction: column; gap: 1px; min-width: 0; }
+#pf-pick-banner .pf-pick-label { color: var(--muted); font-size: 11px; }
+#pf-pick-banner .pf-pick-prompt { color: var(--text-strong); font-weight: 600; }
+#pf-pick-close {
+  position: absolute; top: 6px; right: 6px; appearance: none;
+  width: 20px; height: 20px; padding: 0;
+  border: 1px solid var(--border); border-radius: 6px;
+  background: var(--surface-2); color: var(--muted);
+  cursor: pointer; font-size: 13px; line-height: 1;
+  display: flex; align-items: center; justify-content: center;
+}
+#pf-pick-close:hover { color: var(--text-strong); border-color: var(--accent); }
+@keyframes pf-pick-in {
+  from { opacity: 0; transform: translateX(-50%) translateY(-10px); }
+  to   { opacity: 1; transform: translateX(-50%) translateY(0); }
+}

package/src/framework/mount.js

@@ -9,6 +9,7 @@ import { viewSubParts } from "./jobs.js";
 import { detectBackend } from "./geometry/probe.js";
 import { createDebugOverlay } from "./debug-overlay.js";
 import { attachPicker, formatSelection } from "./selection/index.js";
+import { createPickRequestClient } from "./pick-request/index.js";
 
 // Mount a full parametric-part app from a PartDefinition: 3-D viewer + control
 // panel + the two geometry workers + the auto-regenerating view/cache loop +
@@ -108,6 +109,18 @@ export function mount(part, { createWorker, container = document.getElementById(
       picker.setActive(isActive);
       btn.style.outline = isActive ? "2px solid #ffcc33" : "";
     });
+  } else if (qs.has("pickserver")) {
+    // Agent-driven mode: arm the picker only when the local pick-server asks for a
+    // click. Mutually exclusive with the clipboard ?pick toggle (else-if), so only one
+    // click listener is ever live. `?pickserver` or `?pickserver=http://host:port`.
+    const serverUrl = typeof qs.get("pickserver") === "string" && qs.get("pickserver")
+      ? qs.get("pickserver") : "http://127.0.0.1:4518";
+    createPickRequestClient({
+      serverUrl,
+      viewer,
+      part,
+      getContext: () => ({ view, params, derived: part.derive ? part.derive({ ...part.defaults, ...params }) : {} }),
+    });
   }
 
   let framedView = null; // the view the camera was last framed to (null until first show)

package/src/framework/pick-request/batch.js

@@ -0,0 +1,42 @@
+// Pure state machine for one batch of click requests: ordered prompts in,
+// ordered picks out. No http, no DOM, no timers (the server owns the clock).
+import { randomUUID } from "node:crypto";
+
+export function createBatch(prompts) {
+  return { id: randomUUID(), prompts: [...prompts], picks: [], index: 0, status: "collecting" };
+}
+
+export function view(batch) {
+  const collecting = batch.status === "collecting";
+  return {
+    id: batch.id,
+    index: batch.index,
+    total: batch.prompts.length,
+    prompt: collecting ? batch.prompts[batch.index] : null,
+    status: batch.status,
+  };
+}
+
+// Record a click for the current step. Ignores a non-collecting batch or an index
+// that isn't the one we're waiting on (stale/duplicate click guard).
+export function resolve(batch, index, selection) {
+  if (batch.status !== "collecting" || index !== batch.index) return batch;
+  batch.picks.push({ prompt: batch.prompts[batch.index], selection });
+  batch.index += 1;
+  if (batch.index >= batch.prompts.length) batch.status = "done";
+  return batch;
+}
+
+export function cancel(batch) {
+  if (batch.status === "collecting") batch.status = "cancelled";
+  return batch;
+}
+
+export function timeout(batch) {
+  if (batch.status === "collecting") batch.status = "timeout";
+  return batch;
+}
+
+export function result(batch) {
+  return { status: batch.status, picks: batch.picks };
+}

package/src/framework/pick-request/client.js

@@ -0,0 +1,65 @@
+// Browser side of request-a-pick: drives the shared prompt banner from two sources —
+// an agent asking for clicks over SSE, and a click-to-copy button in the viewbar.
+// Created only under ?pickserver (see mount.js), so both are present exactly when the
+// user is working with an agent.
+import { createPromptBanner } from "./prompt-banner.js";
+import { formatSelection } from "../selection/format.js";
+
+export function createPickRequestClient({ serverUrl = "http://127.0.0.1:4518", viewer, part, getContext }) {
+  let active = null; // { id, index } of the agent prompt we're waiting on
+  const banner = createPromptBanner({ viewer, part, getContext });
+
+  const postJson = (path, body) =>
+    fetch(`${serverUrl}${path}`, {
+      method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body),
+    }).catch(() => banner.message("⚠ couldn't reach pick-server — click not sent"));
+
+  // --- agent prompts over SSE -------------------------------------------------
+  const es = new globalThis.EventSource(`${serverUrl}/events`);
+  es.addEventListener("prompt", (e) => {
+    const v = JSON.parse(e.data);
+    active = { id: v.id, index: v.index };
+    banner.request({
+      avatar: "🤖",
+      label: v.total > 1 ? `Your agent asks: (${v.index + 1} of ${v.total})` : "Your agent asks:",
+      text: v.prompt,
+      onResolve: (selection) => postJson("/resolve", { id: active.id, index: active.index, selection }),
+      onDismiss: () => { if (active) postJson("/cancel", { id: active.id }); },
+    });
+  });
+  es.addEventListener("cleared", () => { active = null; banner.dismiss(); });
+  es.onerror = () => { banner.message("⚠ agent pick-server not reachable"); };
+  es.onopen = () => { if (!active) banner.dismiss(); };
+
+  // --- click-to-copy button, prepended into the viewbar (left of the play btn) -
+  // Copies the SAME description an agent receives for a click, so the two paths match.
+  const viewbar = document.getElementById("viewbar");
+  let copyBtn = null;
+  if (viewbar) {
+    copyBtn = document.createElement("button");
+    copyBtn.id = "copy";
+    copyBtn.type = "button";
+    // Flat single-colour copy glyph (inherits the viewbar button's currentColor).
+    copyBtn.innerHTML = '<svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linejoin="round" aria-hidden="true"><rect x="5.5" y="5.5" width="8" height="8" rx="1.5"/><path d="M10.5 5.5V4A1.5 1.5 0 0 0 9 2.5H4A1.5 1.5 0 0 0 2.5 4V9A1.5 1.5 0 0 0 4 10.5H5.5"/></svg>';
+    copyBtn.title = "Click a detail to copy its agent description";
+    copyBtn.setAttribute("aria-label", "Copy a detail's agent description");
+    copyBtn.addEventListener("click", () => {
+      if (banner.isOpen()) { banner.dismiss(); return; } // toggle off
+      banner.request({
+        avatar: "📋",
+        label: "Copy to clipboard",
+        text: "Click on a detail to copy its agent description to the clipboard.",
+        onResolve: (selection) => {
+          navigator.clipboard?.writeText(formatSelection(selection, { style: "prompt" }));
+          banner.message("✓ Copied to clipboard");
+          setTimeout(() => banner.dismiss(), 1000);
+        },
+      });
+    });
+    viewbar.prepend(copyBtn);
+  }
+
+  return {
+    detach: () => { es.close(); banner.detach(); copyBtn?.remove(); },
+  };
+}

package/src/framework/pick-request/index.js

@@ -0,0 +1 @@
+export { createPickRequestClient } from "./client.js";

package/src/framework/pick-request/prompt-banner.js

@@ -0,0 +1,88 @@
+// A small chat-style prompt banner that arms the selection picker for one click.
+// Shared by request-a-pick's two drivers (an agent asking via SSE, and the
+// click-to-copy button) so they look and behave identically. The look (position,
+// theme colours, slide-in animation) lives in app.css (#pf-pick-banner).
+import { attachPicker } from "../selection/pick.js";
+
+export function createPromptBanner({ viewer, part, getContext }) {
+  let onResolve = null; // called with the Selection on the next pick
+  let onDismiss = null; // called when the user closes the banner via ×
+
+  const banner = document.createElement("div");
+  banner.id = "pf-pick-banner";
+  banner.style.display = "none";
+
+  const row = document.createElement("div");
+  row.className = "pf-pick-row";
+  const avatar = document.createElement("div");
+  avatar.className = "pf-pick-avatar";
+  const msg = document.createElement("div");
+  msg.className = "pf-pick-msg";
+  const label = document.createElement("div");
+  label.className = "pf-pick-label";
+  const prompt = document.createElement("div");
+  prompt.className = "pf-pick-prompt";
+  msg.append(label, prompt);
+  row.append(avatar, msg);
+
+  const close = document.createElement("button");
+  close.id = "pf-pick-close";
+  close.type = "button";
+  close.textContent = "×";
+  close.setAttribute("aria-label", "Dismiss");
+
+  banner.append(row, close);
+  document.body.appendChild(banner);
+
+  const isOpen = () => banner.style.display !== "none";
+
+  function dismiss() {
+    onResolve = null;
+    onDismiss = null;
+    picker.setActive(false);
+    banner.style.display = "none";
+  }
+
+  const picker = attachPicker(viewer, {
+    part, getContext,
+    onPick: (selection) => {
+      const resolve = onResolve;
+      onResolve = null;            // a pick resolves once; a stray click after is a no-op
+      picker.setActive(false);     // consumer re-arms via request() if more clicks are wanted
+      resolve?.(selection);
+    },
+  });
+
+  close.addEventListener("click", () => {
+    const dismissed = onDismiss;
+    dismiss();
+    dismissed?.();
+  });
+
+  // Show a prompt and arm the picker for one click. Prompt/label text is rendered via
+  // textContent (never innerHTML) — it can carry agent-supplied strings.
+  function request({ avatar: glyph, label: text, text: body, onResolve: resolve = null, onDismiss: dismissed = null }) {
+    onResolve = resolve;
+    onDismiss = dismissed;
+    avatar.textContent = glyph;
+    label.textContent = text || "";
+    prompt.textContent = body;
+    banner.style.display = "block";
+    picker.setActive(true);
+  }
+
+  // Show a transient note (error or confirmation) with no pending pick. Keeps the
+  // current avatar so a "✓ Copied" / "⚠ …" note stays in context.
+  function message(body) {
+    onResolve = null;
+    picker.setActive(false);
+    label.textContent = "";
+    prompt.textContent = body;
+    banner.style.display = "block";
+  }
+
+  return {
+    request, message, dismiss, isOpen,
+    detach: () => { picker.detach(); banner.remove(); },
+  };
+}

package/src/framework/pick-request/server.js

@@ -0,0 +1,158 @@
+// src/framework/pick-request/server.js
+// The Node side of request-a-pick: an http+SSE server holding one active batch,
+// a blocking CLI client (requestPicks), and CLI output formatting. 127.0.0.1 only.
+import { createServer, request as httpRequest } from "node:http";
+import { createBatch, view, resolve, cancel, timeout, result } from "./batch.js";
+import { formatSelection } from "../selection/format.js";
+
+const json = (res, code, obj, origin) => {
+  res.writeHead(code, { "content-type": "application/json", "access-control-allow-origin": origin || "*" });
+  res.end(JSON.stringify(obj));
+};
+const readBody = (req) => new Promise((resolve_) => {
+  let b = "";
+  req.on("data", (c) => (b += c));
+  req.on("end", () => {
+    if (!b) { resolve_({}); return; }
+    try { resolve_(JSON.parse(b)); } catch { resolve_({ _parseError: true }); }
+  });
+});
+
+export function createPickServer({ port = 4518, timeoutMs = 120000 } = {}) {
+  let batch = null;        // the one active batch (or null)
+  let pending = null;      // { res, timer } — the held POST /request response
+  const sseClients = new Set();
+  const allSockets = new Set(); // track every socket for forceful teardown
+
+  const sse = (event, data) => {
+    for (const res of sseClients) res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+  };
+  const finish = () => {                 // resolve the held /request with the result
+    if (pending) {
+      clearTimeout(pending.timer);
+      json(pending.res, 200, result(batch));
+      pending = null;
+    }
+    sse("cleared", {});
+    batch = null;
+  };
+
+  const server = createServer(async (req, res) => {
+    const origin = req.headers.origin;
+    if (req.method === "OPTIONS") {
+      res.writeHead(204, {
+        "access-control-allow-origin": origin || "*",
+        "access-control-allow-methods": "GET,POST,OPTIONS",
+        "access-control-allow-headers": "content-type",
+      });
+      return res.end();
+    }
+    const url = req.url.split("?")[0];
+
+    if (req.method === "POST" && url === "/request") {
+      if (batch) return json(res, 409, { status: "busy" }, origin);
+      const body = await readBody(req);
+      if (body._parseError) return json(res, 400, { error: "invalid JSON" }, origin);
+      if (!Array.isArray(body.prompts) || body.prompts.length === 0) {
+        return json(res, 400, { error: "prompts must be a non-empty array" }, origin);
+      }
+      batch = createBatch(body.prompts);
+      pending = { res, timer: setTimeout(() => { timeout(batch); finish(); }, timeoutMs) };
+      sse("prompt", view(batch));
+      return; // held open until finish()
+    }
+    if (req.method === "GET" && url === "/events") {
+      res.writeHead(200, {
+        "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive",
+        "access-control-allow-origin": origin || "*",
+      });
+      res.write(": connected\n\n"); // SSE comment — flushes headers, makes fetch() resolve
+      sseClients.add(res);
+      if (batch) res.write(`event: prompt\ndata: ${JSON.stringify(view(batch))}\n\n`); // replay current
+      req.on("close", () => sseClients.delete(res));
+      return;
+    }
+    if (req.method === "POST" && url === "/resolve") {
+      const body = await readBody(req);
+      if (body._parseError) return json(res, 400, { error: "invalid JSON" }, origin);
+      const { id, index, selection } = body;
+      if (batch && id === batch.id) {
+        resolve(batch, index, selection);
+        if (view(batch).status === "collecting") sse("prompt", view(batch));
+        else finish();
+      }
+      return json(res, 200, { ok: true }, origin);
+    }
+    if (req.method === "POST" && url === "/cancel") {
+      const body = await readBody(req);
+      if (body._parseError) return json(res, 400, { error: "invalid JSON" }, origin);
+      const { id } = body;
+      if (batch && id === batch.id) { cancel(batch); finish(); }
+      return json(res, 200, { ok: true }, origin);
+    }
+    return json(res, 404, { error: "not found" }, origin);
+  });
+
+  server.on("connection", (socket) => {
+    allSockets.add(socket);
+    socket.on("close", () => allSockets.delete(socket));
+  });
+
+  return {
+    start: () => new Promise((res_) => server.listen(port, "127.0.0.1", () => res_({ port: server.address().port }))),
+    stop: () => new Promise((res_) => {
+      // If a batch is active, cancel it and resolve the held /request cleanly
+      // so any awaiting requestPicks() gets a result instead of a socket hang-up.
+      if (batch) { cancel(batch); finish(); }
+      for (const c of sseClients) c.end();
+      server.close(() => res_());
+      // destroy any lingering sockets (SSE keep-alive) so server.close resolves
+      for (const s of allSockets) s.destroy();
+    }),
+  };
+}
+
+// CLI client: POST the prompts and await the held response (blocks until the batch
+// reaches a terminal status server-side). Fails fast with a hint if nothing answers.
+export function requestPicks({ port = 4518, host = "127.0.0.1", prompts }) {
+  return new Promise((resolve_, reject) => {
+    const payload = JSON.stringify({ prompts });
+    const req = httpRequest(
+      { host, port, path: "/request", method: "POST", headers: { "content-type": "application/json", "content-length": Buffer.byteLength(payload) } },
+      (res) => {
+        let b = "";
+        res.on("data", (c) => (b += c));
+        res.on("end", () => {
+          try {
+            resolve_(JSON.parse(b));
+          } catch {
+            reject(new Error(`unexpected response from pick-server on ${host}:${port} (is the app open and \`partforge pick-serve\` running?)`));
+          }
+        });
+      },
+    );
+    req.on("error", (e) => reject(new Error(`could not reach pick-server on ${host}:${port} (is the app open and \`partforge pick-serve\` running?) — ${e.message}`)));
+    req.end(payload);
+  });
+}
+
+// Human-readable CLI output: one summary line per pick, then the raw JSON to parse.
+export function formatPickResult({ status, picks }) {
+  const safePicks = Array.isArray(picks) ? picks : [];
+  const lines = [`status: ${status} (${safePicks.length} pick${safePicks.length === 1 ? "" : "s"})`];
+  for (const { prompt, selection } of safePicks) {
+    let summary;
+    try {
+      if (selection && selection.point && selection.normal && selection.params) {
+        summary = formatSelection(selection, { style: "prompt" });
+      } else {
+        summary = selection?.subPart ?? JSON.stringify(selection);
+      }
+    } catch {
+      summary = JSON.stringify(selection);
+    }
+    lines.push(`• "${prompt}" → ${summary}`);
+  }
+  lines.push("", JSON.stringify({ status, picks }, null, 2));
+  return lines.join("\n");
+}