@nanobpm/nano-workforce 0.37.0 → 0.39.0

package/actions/blackboard.ts

@@ -1,77 +0,0 @@
-// GET/POST /hooks/blackboard?token=<capabilityToken> — the epic coordination blackboard endpoint
-// (Tier 1, issues #51 / #49 D4).
-//
-// This is a DIRECT side-channel for agents, distinct from the c8ctl-nano activation/completion
-// channel. The per-plan capability token (query string) IS the credential: it scopes every read
-// and write to exactly one plan, so no shared secret is needed — the agent curls the exact URL it
-// was handed in its prompt. An unknown token is a 404 (never leaks which plans exist).
-//
-//   GET  → { planKey, entries: [ { id, author_task, kind, files, body, wave, created_at } ], cursor }
-//          optional ?since=<id> returns only entries with id > since (incremental poll). `cursor` is
-//          the plan's current head id; pass it back as `since` on the next poll (Tier 2).
-//   POST → append one entry: { author_task?, kind?, files?, body, wave?, dedupe_key? }. Idempotent
-//          on (plan, dedupe_key). Returns { id, inserted, conflicts } — `conflicts` lists prior
-//          sibling `file-claim`s on the same file(s) (advisory first-writer-wins; never a lock).
-import type { ActionHandler } from "@nanobpm/urban";
-import {
-  appendEntry,
-  detectFileClaimConflicts,
-  normalizeKind,
-  planKeyForToken,
-  readBlackboardPage,
-} from "../app/blackboard.ts";
-
-const handler: ActionHandler = async ({ req, body }, app) => {
-  const token = (req.query.get("token") ?? req.headers.get("x-blackboard-token") ?? "").trim();
-  if (!token) return { status: 400, body: { error: "missing blackboard token" } };
-  const planKey = await planKeyForToken(app.data, token);
-  if (!planKey) return { status: 404, body: { error: "unknown blackboard token" } };
-
-  if (req.method === "GET") {
-    const rawSince = req.query.get("since");
-    const since = rawSince != null && /^\d+$/.test(rawSince) ? Number(rawSince) : undefined;
-    const { entries, cursor } = await readBlackboardPage(app.data, planKey, { since });
-    return { status: 200, body: { planKey, entries, cursor } };
-  }
-
-  if (req.method === "POST") {
-    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-    const b = (body ?? {}) as Record<string, unknown>;
-    const text = typeof b.body === "string" ? b.body.trim() : "";
-    if (!text) return { status: 400, body: { error: "'body' (the note text) is required" } };
-    const kind = normalizeKind(b.kind);
-    const files = Array.isArray(b.files) ? b.files.map(String) : [];
-    // Normalize once (trim + default to "system") so the value we send to appendEntry matches the
-    // value we send to detectFileClaimConflicts. Otherwise an omitted/blank author_task is stored as
-    // "system" but conflict detection sees "", and the caller's own prior "system" claims are wrongly
-    // reported as sibling conflicts.
-    const author_task = (typeof b.author_task === "string" ? b.author_task.trim() : "") || "system";
-    const res = await appendEntry(app.data, planKey, {
-      author_task,
-      kind,
-      files,
-      body: text,
-      wave: typeof b.wave === "number" ? b.wave : null,
-      dedupe_key: typeof b.dedupe_key === "string" ? b.dedupe_key : undefined,
-    });
-    // Advisory conflict-of-intent: surface prior sibling claims on the same file(s). Computed AFTER
-    // the append and filtered to claims strictly before ours (id < res.id), so first-writer-wins is
-    // decided by insertion order — a sibling that raced a claim in between is still caught, and our
-    // own just-written row is never reported. Never blocks the append — the agent decides how to react.
-    const conflicts = kind === "file-claim"
-      ? await detectFileClaimConflicts(app.data, planKey, {
-        author_task,
-        files,
-        beforeId: Number(res.id),
-      })
-      : [];
-    return {
-      status: res.inserted ? 201 : 200,
-      body: { id: Number(res.id), inserted: res.inserted, conflicts },
-    };
-  }
-
-  return { status: 405, body: { error: "method not allowed (use GET or POST)" } };
-};
-
-export default handler;

package/actions/feature-answer-hook.ts

@@ -1,45 +0,0 @@
-// POST /hooks/feature-answer — answer an implementation-phase task escalation out
-// of band (optional shared-secret guard via X-Hook-Secret, enforced only when
-// NANO_PR_WEBHOOK_SECRET is set — mirrors /hooks/submit and /hooks/plan), issue #25.
-// Lets an external
-// system (a chat relay, a CI job, a human via curl) resume a parked implementation
-// agent without the page. Same idempotent `answerTaskEscalation` path the page's
-// answer form uses.
-//
-// Body accepts either the raw correlation key or a plan+task pair:
-//   { "corrKey": "owner/repo#12:task-3", "answer": "…" }
-//   { "plan": "owner/repo#12", "task": "task-3", "answer": "…" }
-import type { ActionHandler } from "@nanobpm/urban";
-import { answerTaskEscalation, featureCorrKey } from "../app/plan.ts";
-
-const WEBHOOK_SECRET = process.env.NANO_PR_WEBHOOK_SECRET ?? "";
-
-const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
-
-const handler: ActionHandler = async ({ req, body }, app) => {
-  if (WEBHOOK_SECRET && req.headers.get("x-hook-secret") !== WEBHOOK_SECRET) {
-    return { status: 401, body: { error: "unauthorized" } };
-  }
-  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-  const b = (body ?? {}) as {
-    corrKey?: unknown;
-    plan?: unknown;
-    task?: unknown;
-    answer?: unknown;
-  };
-  const answer = str(b.answer);
-  if (!answer) return { status: 400, body: { error: "answer is required" } };
-
-  const corrKey = str(b.corrKey) || (str(b.plan) && str(b.task) ? featureCorrKey(str(b.plan), str(b.task)) : "");
-  if (!corrKey) {
-    return {
-      status: 400,
-      body: { error: "provide corrKey, or both plan (owner/repo#N) and task" },
-    };
-  }
-
-  const r = await answerTaskEscalation(app.data, app.engine, corrKey, answer);
-  return { status: r.ok ? 200 : 404, body: r };
-};
-
-export default handler;

package/actions/plan-hook.ts

@@ -1,20 +0,0 @@
-// POST /hooks/plan — kick off a planning fan-out out of band (shared-secret auth via
-// X-Hook-Secret). Lets an external system (a GitHub webhook relay on issue open/label, a CI job)
-// hand an issue to the fleet. Same idempotent startPlan path as the page's "Plan issue" action.
-import type { ActionHandler } from "@nanobpm/urban";
-import { parseIssue, startPlan } from "../app/plan.ts";
-
-const WEBHOOK_SECRET = process.env.NANO_PR_WEBHOOK_SECRET ?? "";
-
-const handler: ActionHandler = async ({ req, body }, app) => {
-  if (WEBHOOK_SECRET && req.headers.get("x-hook-secret") !== WEBHOOK_SECRET) {
-    return { status: 401, body: { error: "unauthorized" } };
-  }
-  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-  const b = (body ?? {}) as { url?: unknown; issue?: unknown };
-  const parsed = parseIssue(String(b.issue ?? b.url ?? ""));
-  if (!parsed) return { status: 400, body: { error: "could not parse issue (use owner/repo#123 or an issue URL)" } };
-  return { status: 202, body: await startPlan(app.data, app.engine, parsed) };
-};
-
-export default handler;

package/actions/webhook-submit.ts

@@ -1,22 +0,0 @@
-// POST /hooks/submit — submit a PR out-of-band (shared-secret auth via X-Hook-Secret). Not
-// part of the page UI; lets an external system (a GitHub webhook relay, a CI job) kick off a
-// convergence run. Same idempotent submit path as the page's "Start review" action.
-import type { ActionHandler } from "@nanobpm/urban";
-import { clampRounds, MAX_ROUNDS, parsePr, submitPr } from "../app/service.ts";
-
-const WEBHOOK_SECRET = process.env.NANO_PR_WEBHOOK_SECRET ?? "";
-
-const handler: ActionHandler = async ({ req, body }, app) => {
-  if (WEBHOOK_SECRET && req.headers.get("x-hook-secret") !== WEBHOOK_SECRET) {
-    return { status: 401, body: { error: "unauthorized" } };
-  }
-  // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-  const b = (body ?? {}) as { url?: unknown; pr?: unknown; dependsOn?: unknown; maxRounds?: unknown };
-  const parsed = parsePr(String(b.url ?? b.pr ?? ""));
-  if (!parsed) return { status: 400, body: { error: "could not parse PR url" } };
-  const dependsOn = Array.isArray(b.dependsOn) ? b.dependsOn.map((d) => String(d)) : [];
-  const maxRounds = clampRounds(b.maxRounds, MAX_ROUNDS);
-  return { status: 202, body: await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds) };
-};
-
-export default handler;

package/openapi.json

@@ -1,248 +0,0 @@
-{
-  "openapi": "3.0.3",
-  "info": {
-    "title": "Nano Workforce control API",
-    "version": "1.0.0",
-    "description": "The externally-facing control surface an operator, an automation harness, or an LLM uses to observe and steer PR-convergence and planning runs. Contract-first (ADR 0058): the toolkit derives typed request/response contracts + runtime validators from this document and each `operationId` is implemented by a delegate module in `operations/`. Mounted under base `/app/api`, kept off the framework-reserved `/app` page-runtime namespace (which owns `/app/runtime.js`, `/app/pages/*`, `/app/data/*`). The `/hooks/*` webhook endpoints stay on `actions[]` because they live outside the `/app` namespace."
-  },
-  "components": {
-    "securitySchemes": {
-      "hookSecret": {
-        "type": "apiKey",
-        "in": "header",
-        "name": "x-hook-secret",
-        "description": "Optional shared secret. Enforced by the delegate (NOT the runtime) only when NANO_PR_WEBHOOK_SECRET is set; unset means the endpoint is open. Declared here for documentation."
-      }
-    },
-    "schemas": {
-      "ErrorBody": {
-        "type": "object",
-        "required": ["error"],
-        "properties": { "error": { "type": "string" } }
-      },
-      "ActivePr": {
-        "type": "object",
-        "description": "A tracked PR that is not in a terminal (converged/abandoned) state.",
-        "required": [
-          "prKey", "repo", "number", "url", "title", "status", "round",
-          "processKey", "waitingSince", "openEscalation", "updatedAt",
-          "activeWorker", "leaseUntil"
-        ],
-        "properties": {
-          "prKey": { "type": "string" },
-          "repo": { "type": "string" },
-          "number": { "type": "integer" },
-          "url": { "type": "string" },
-          "title": { "type": ["string", "null"] },
-          "status": { "type": "string" },
-          "round": { "type": "integer" },
-          "processKey": { "type": ["string", "null"], "description": "The engine process instance key; also the keyField the pages processExplorer link uses." },
-          "waitingSince": { "type": ["string", "null"] },
-          "openEscalation": { "type": ["string", "null"] },
-          "updatedAt": { "type": "string" },
-          "activeWorker": { "type": ["string", "null"] },
-          "leaseUntil": { "type": ["string", "null"] }
-        }
-      },
-      "ActivePrList": {
-        "type": "object",
-        "required": ["count", "prs"],
-        "properties": {
-          "count": { "type": "integer" },
-          "prs": { "type": "array", "items": { "$ref": "#/components/schemas/ActivePr" } }
-        }
-      },
-      "VersionInfo": {
-        "type": "object",
-        "description": "The running app's identity (which code is actually live).",
-        "required": [
-          "name", "version", "urbanVersion", "gitSha", "gitBranch",
-          "runtime", "pid", "startedAt", "uptimeSeconds"
-        ],
-        "properties": {
-          "name": { "type": "string" },
-          "version": { "type": ["string", "null"] },
-          "urbanVersion": { "type": ["string", "null"] },
-          "gitSha": { "type": ["string", "null"] },
-          "gitBranch": { "type": ["string", "null"] },
-          "runtime": { "type": "string" },
-          "pid": { "type": ["integer", "null"] },
-          "startedAt": { "type": "string" },
-          "uptimeSeconds": { "type": "integer" }
-        }
-      },
-      "SubmitResult": {
-        "type": "object",
-        "required": ["prKey"],
-        "properties": {
-          "prKey": { "type": "string" },
-          "processKey": { "type": ["string", "null"], "description": "The started convergence-loop instance key (null if the engine did not return one)." },
-          "alreadyRunning": { "type": "boolean", "description": "True when a non-terminal convergence loop for this PR already exists; the aggregate was refreshed and no new instance was started." }
-        }
-      },
-      "StartPlanResult": {
-        "type": "object",
-        "required": ["planKey"],
-        "properties": {
-          "planKey": { "type": "string" },
-          "processKey": { "type": ["string", "null"] },
-          "alreadyRunning": { "type": "boolean", "description": "True when a non-terminal plan for this issue already exists; no new instance was started." }
-        }
-      },
-      "StartVariables": {
-        "type": "object",
-        "description": "Process-start variables. `pr`/`url` (convergence) or `issue`/`url` (planning) name the target; extra keys are forwarded to the engine.",
-        "additionalProperties": true,
-        "properties": {
-          "pr": { "type": "string", "description": "PR reference: owner/repo#123 or a PR URL." },
-          "issue": { "type": "string", "description": "Issue reference: owner/repo#123 or an issue URL." },
-          "url": { "type": "string", "description": "Alias for pr/issue when a bare URL is supplied." },
-          "dependsOn": { "type": "array", "items": { "type": "string" } },
-          "maxRounds": { "type": "integer", "minimum": 1 }
-        }
-      },
-      "MessageResult": {
-        "type": "object",
-        "description": "The result of publishing a message / answering an escalation. Shape varies by message name; `ok` is always present.",
-        "additionalProperties": true,
-        "required": ["ok"],
-        "properties": { "ok": { "type": "boolean" } }
-      }
-    }
-  },
-  "paths": {
-    "/status": {
-      "get": {
-        "operationId": "listActivePrs",
-        "summary": "List every tracked PR currently in flight (not converged/abandoned), newest-updated first.",
-        "security": [{ "hookSecret": [] }, {}],
-        "responses": {
-          "200": {
-            "description": "The active PRs.",
-            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivePrList" } } }
-          },
-          "401": {
-            "description": "Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).",
-            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }
-          }
-        }
-      }
-    },
-    "/version": {
-      "get": {
-        "operationId": "getVersion",
-        "summary": "The running app's identity (app/urban versions, git sha/branch, runtime, pid, uptime).",
-        "security": [{ "hookSecret": [] }, {}],
-        "responses": {
-          "200": {
-            "description": "The version/identity payload.",
-            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionInfo" } } }
-          },
-          "401": {
-            "description": "Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).",
-            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }
-          }
-        }
-      }
-    },
-    "/actions/start/convergence-loop": {
-      "post": {
-        "operationId": "startConvergenceLoop",
-        "summary": "Register/refresh a PR aggregate (idempotent on prKey) and start its convergence loop.",
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "additionalProperties": true,
-                "required": ["variables"],
-                "properties": { "variables": { "$ref": "#/components/schemas/StartVariables" } }
-              }
-            }
-          }
-        },
-        "responses": {
-          "202": {
-            "description": "The loop was started (or refreshed).",
-            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } }
-          },
-          "400": {
-            "description": "The PR reference could not be parsed.",
-            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }
-          }
-        }
-      }
-    },
-    "/actions/start/plan-fanout": {
-      "post": {
-        "operationId": "startPlanFanout",
-        "summary": "Register/refresh a plan aggregate (idempotent on planKey) and start the planning fan-out.",
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "additionalProperties": true,
-                "required": ["variables"],
-                "properties": { "variables": { "$ref": "#/components/schemas/StartVariables" } }
-              }
-            }
-          }
-        },
-        "responses": {
-          "202": {
-            "description": "The plan fan-out was started (or was already running).",
-            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartPlanResult" } } }
-          },
-          "400": {
-            "description": "The issue reference could not be parsed.",
-            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }
-          }
-        }
-      }
-    },
-    "/actions/message": {
-      "post": {
-        "operationId": "postMessage",
-        "summary": "Publish a message / answer an escalation. For escalation-answered and feature-escalation-answered names, runs the corresponding answer flow; otherwise a plain publishMessage.",
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "additionalProperties": true,
-                "required": ["name"],
-                "properties": {
-                  "name": { "type": "string", "description": "The message name (correlates a waiting event)." },
-                  "correlationKey": { "type": "string" },
-                  "variables": {
-                    "type": "object",
-                    "additionalProperties": true,
-                    "properties": { "answer": { "type": "string" } }
-                  }
-                }
-              }
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "The message was published (or the escalation answered).",
-            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResult" } } }
-          },
-          "400": {
-            "description": "A required field was missing/blank.",
-            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }
-          },
-          "404": {
-            "description": "No matching open escalation / parked token to answer.",
-            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResult" } } }
-          }
-        }
-      }
-    }
-  }
-}