@nanobpm/nano-workforce 0.159.1 → 0.161.0

package/openapi.yaml

@@ -35,6 +35,37 @@ components:
       properties:
         error:
           type: string
+    ValidationError:
+      description: >-
+        The uniform validation-error contract: a human-readable `error` plus a path-qualified
+        `issues[]` naming each offending input. Returned by endpoints that reject a bad query/body
+        param (e.g. `GET /agent/guide` with an unknown `section` id).
+      type: object
+      additionalProperties: false
+      required:
+        - error
+        - issues
+      properties:
+        error:
+          type: string
+          description: A human-readable summary of the rejection.
+        issues:
+          type: array
+          minItems: 1
+          items:
+            type: object
+            additionalProperties: false
+            required:
+              - path
+              - message
+            properties:
+              path:
+                type: string
+                description: JSON-path pointer at the offending input (e.g. `section`).
+              message:
+                type: string
+                description: Human-actionable description of the failure.
+          description: The path-qualified `{ path, message }` failures (at least one).
     ActivePr:
       type: object
       description: A tracked PR that is not in a terminal (converged/abandoned) state.
@@ -881,6 +912,82 @@ components:
         skill:
           type: string
           description: The full operator skill (SKILL.md) as markdown, including its YAML frontmatter.
+    AgentGuideResponse:
+      type: object
+      description: The addressable operator-guide response served by `getAgentGuide`. Two shapes,
+        discriminated by `kind`. `kind:"toc"` (no `section` argument) carries `sections` — the compact
+        table of contents, one entry per stable section id. `kind:"section"` (a `section` id given)
+        carries `section` — that one section's markdown, with its examples keyed to this instance.
+      additionalProperties: false
+      required:
+        - kind
+        - appVersion
+        - generatedAt
+        - baseUrl
+      properties:
+        kind:
+          type: string
+          description: '"toc" when listing sections (no `section` argument); "section" when returning one.'
+          enum:
+            - toc
+            - section
+        appVersion:
+          type: string
+          nullable: true
+          description: The running app version this guide matches (null when unreadable).
+        generatedAt:
+          type: string
+          description: When this response was rendered (ISO-8601).
+        baseUrl:
+          type: string
+          description: The app control-API base the examples target (e.g. https://host/app/api).
+        engineBase:
+          type: string
+          description: The engine's Camunda-8 v2 REST base this app talks to (present on a section response).
+        sections:
+          type: array
+          description: The table of contents — present when `kind` is "toc". One entry per addressable section.
+          items:
+            type: object
+            additionalProperties: false
+            required:
+              - id
+              - title
+              - summary
+            properties:
+              id:
+                type: string
+                description: The stable section id to pass back as `getAgentGuide(section)`.
+              title:
+                type: string
+                description: The section's heading text (e.g. "9. Author and run a delivery graph (ADR 0005)").
+              summary:
+                type: string
+                description: A one-line summary of what the section covers.
+        section:
+          type: object
+          description: The requested section — present when `kind` is "section".
+          additionalProperties: false
+          required:
+            - id
+            - title
+            - format
+            - instructions
+          properties:
+            id:
+              type: string
+              description: The stable section id that was requested.
+            title:
+              type: string
+              description: The section's heading text.
+            format:
+              type: string
+              description: The `instructions` media format. Always "markdown".
+              enum:
+                - markdown
+            instructions:
+              type: string
+              description: The section's markdown, with example commands keyed to this instance.
     SubmitResult:
       type: object
       required:
@@ -3080,6 +3187,53 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /agent/guide:
+    get:
+      operationId: getAgentGuide
+      summary: The operator guide, ADDRESSABLE — fetch one section instead of the whole ~43KB blob.
+        Read-only, pure, idempotent. Call with NO `section` to get a compact table of contents (every
+        stable section id + a one-line summary); call with `section` set to a TOC id (e.g.
+        `delivery-graphs`) to get ONLY that section's markdown, small enough to fit a typical
+        tool-result limit. This is the MCP-friendly companion to `getAgentInstructions`, which still
+        returns the full guide unchanged for non-MCP callers. Typical flow — first call
+        `getAgentGuide` (no arg) to see the ids, then `getAgentGuide(section=<id>)` for the one you
+        need. An unknown id is rejected with `issues[{path,message}]` that lists the valid ids.
+      security:
+        - hookSecret: []
+        - {}
+      parameters:
+        # Self-contained tool input (epic #605 S0 convention): a single inline `type: string` query
+        # param — no `$ref`, an explicit type and example — so the projected MCP tool schema is
+        # client-usable as-is (no request body; the inline-mcp-bodies generator does not apply here).
+        - name: section
+          in: query
+          required: false
+          schema:
+            type: string
+            example: delivery-graphs
+          description: OPTIONAL stable section id (from the table of contents `getAgentGuide` returns
+            with no argument), e.g. `orient`, `submit-pr`, `submit-epic`, `escalations`, `lifecycle`,
+            `debug`, `debug-models`, `unstick`, `raise-issue`, `delivery-graphs`. Omit it to get the
+            table of contents. An unknown id yields a 400 listing the valid ids.
+      responses:
+        "200":
+          description: Either the table of contents (no `section`) or a single section's markdown.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgentGuideResponse"
+        "400":
+          description: The `section` id is not a known section; `issues` lists the valid ids.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ValidationError"
+        "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
@@ -4064,6 +4218,262 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /delivery-graph/vocabulary:
+    get:
+      operationId: getDeliveryGraphVocabulary
+      summary: The closed delivery-graph vocabulary + wait-probe semantics as structured JSON (ADR 0005).
+      description: >-
+        Read tool (projected onto the MCP surface like `getAgentInstructions`). Returns the CLOSED
+        delivery-graph vocabulary and the non-obvious wait/poll/fact-threading semantics as structured
+        JSON, so you can discover them from the surface instead of reading source. Covers: the four node
+        kinds (`agent`/`wait`/`human`/`connector`) with their per-kind body contracts; every wait probe
+        kind with its `match` fields and — crucially — WHAT it OBSERVES (e.g. `epic` resolves a lineage
+        thread by `rootRequestKey` REGARDLESS of the thread's kind, so it gates plan-fanout epics AND
+        single-PR feature runs alike, ready on `stage:"merged" && active:false`); which connector targets
+        are real (`converge`/`converge-merge`/`merge-main`) vs. forward-declared stubs; the `onTimeout`
+        options; the poll-budget rule (always set a realistic `poll.timeoutMs` on merge/epic gates — the
+        30-minute default is a trap); and the edge/fact-threading rules (a `node.fact` must be threaded by
+        an edge to every consumer, else `unbound-pr`). Derived from the implementing code (a drift test
+        fails the build if a probe kind / connector target is added without a vocabulary entry). Pure,
+        read-only, idempotent — no side effects. Pairs with `compileDeliveryGraph`/`previewDeliveryGraph`:
+        call this first to learn the vocabulary, then author a `DeliveryGraph` and compile it.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The full delivery-graph vocabulary.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                description: The closed delivery-graph vocabulary + wait-probe semantics, derived from the compiler/runner code.
+                required:
+                  - adr
+                  - summary
+                  - nodeKinds
+                  - factTypes
+                  - guardScalarTypes
+                  - waitProbeKinds
+                  - connectorTargets
+                  - onTimeout
+                  - pollBudget
+                  - factThreading
+                properties:
+                  adr:
+                    type: string
+                    description: The governing ADR (agent-authored delivery graphs).
+                  summary:
+                    type: string
+                    description: One-paragraph orientation on the graph shape and the propose→compile→stage surface.
+                  nodeKinds:
+                    type: array
+                    description: The closed node-kind allowlist with each kind's config key and body contract.
+                    items:
+                      type: object
+                      additionalProperties: false
+                      required: [kind, configKey, requiredFields, optionalFields, sideEffecting, mayEmit, summary]
+                      properties:
+                        kind:
+                          type: string
+                          description: The node kind (one of agent | wait | human | connector).
+                        configKey:
+                          type: string
+                          description: The per-kind config object key the node must carry.
+                        requiredFields:
+                          type: array
+                          items: { type: string }
+                          description: Required non-empty fields inside the per-kind config.
+                        optionalFields:
+                          type: array
+                          items: { type: string }
+                          description: Optional fields inside the per-kind config.
+                        sideEffecting:
+                          type: boolean
+                          description: Whether the node performs a side effect (agent/connector) vs. read-only (wait/human).
+                        mayEmit:
+                          type: boolean
+                          description: Whether the node may declare typed emits.
+                        summary:
+                          type: string
+                          description: The body contract / semantics of the kind.
+                  factTypes:
+                    type: array
+                    items: { type: string }
+                    description: The closed emitted-fact type allowlist.
+                  guardScalarTypes:
+                    type: array
+                    items: { type: string }
+                    description: The scalar fact types an edge `when` guard may reference.
+                  waitProbeKinds:
+                    type: array
+                    description: Every wait probe kind, its match fields, and what it observes / when it is ready.
+                    items:
+                      type: object
+                      additionalProperties: false
+                      required: [kind, target, matchFields, observes, ready]
+                      properties:
+                        kind:
+                          type: string
+                          description: The probe kind (http | command | npm | github-check | capability | pr | epic).
+                        target:
+                          type: string
+                          description: What the probe's `target` names.
+                        matchFields:
+                          type: array
+                          items: { type: string }
+                          description: The `match` fields this kind reads.
+                        conditions:
+                          type: array
+                          items: { type: string }
+                          description: The closed condition set for pr/epic kinds (else absent).
+                        observes:
+                          type: string
+                          description: The read that decides readiness (what the probe actually observes).
+                        ready:
+                          type: string
+                          description: The condition under which the probe reports ready.
+                        binds:
+                          type: array
+                          items: { type: string }
+                          description: Output facts the probe binds on a ready match.
+                  connectorTargets:
+                    type: array
+                    description: Which connector targets are real (converge-enrollment) vs. forward-declared stubs.
+                    items:
+                      type: object
+                      additionalProperties: false
+                      required: [target, status, summary]
+                      properties:
+                        target:
+                          type: string
+                          description: The connector target literal (or a sentinel for any other target).
+                        status:
+                          type: string
+                          enum: [real, forward-declared]
+                          description: real ⇒ dispatches a real side effect; forward-declared ⇒ a no-op stub.
+                        convergeOnlyDefault:
+                          type: boolean
+                          description: The default `convergeOnly` for a real converge target.
+                        summary:
+                          type: string
+                          description: What the target does.
+                  onTimeout:
+                    type: array
+                    description: The `onTimeout` options for a bounded wait and what each does.
+                    items:
+                      type: object
+                      additionalProperties: false
+                      required: [value, meaning]
+                      properties:
+                        value: { type: string }
+                        meaning: { type: string }
+                  pollBudget:
+                    type: object
+                    additionalProperties: false
+                    required: [defaultTimeoutMs, defaultTimeoutIso, defaultEveryMs, rule]
+                    description: The poll-budget defaults and the "always set poll.timeoutMs on merge/epic gates" rule.
+                    properties:
+                      defaultTimeoutMs: { type: number }
+                      defaultTimeoutIso: { type: string }
+                      defaultEveryMs: { type: number }
+                      rule: { type: string }
+                  factThreading:
+                    type: object
+                    additionalProperties: false
+                    required: [rule, details]
+                    description: The edge/fact-threading rules — a node.fact reaches a consumer only via an edge.
+                    properties:
+                      rule: { type: string }
+                      details:
+                        type: array
+                        items: { type: string }
+                  guideSection:
+                    type: string
+                    description: The operator-guide section this data mirrors (docs/agent-guide.md §9).
+                example:
+                  adr: "ADR 0005 — agent-authored delivery graphs"
+                  summary: "A delivery graph is a JSON DAG an agent authors as DATA; the surface ends at propose → compile → stage."
+                  nodeKinds:
+                    - kind: agent
+                      configKey: agent
+                      requiredFields: [jobType]
+                      optionalFields: [prompt, converge, merge]
+                      sideEffecting: true
+                      mayEmit: true
+                      summary: "A worker runs an agent job type; an agent that opens a PR emits it as a `pr` fact."
+                    - kind: wait
+                      configKey: wait
+                      requiredFields: [kind, target]
+                      optionalFields: [match, poll, onTimeout, credentialEnv]
+                      sideEffecting: false
+                      mayEmit: true
+                      summary: "A durable, bounded, read-only readiness probe (a ReadinessProbe verbatim)."
+                    - kind: connector
+                      configKey: connector
+                      requiredFields: [target]
+                      optionalFields: [dedupeKey, payload]
+                      sideEffecting: true
+                      mayEmit: true
+                      summary: "An automated outbound action; payload for a converge target is { pr, convergeOnly?, dependsOn? }."
+                  factTypes: [string, number, boolean, artifact, version, url, pr]
+                  guardScalarTypes: [string, number, boolean]
+                  waitProbeKinds:
+                    - kind: pr
+                      target: "an owner/repo#N PR (or a <node>.pr fact reference)"
+                      matchFields: [prState]
+                      conditions: [ready, merged, mergeable, checks-green]
+                      observes: "the live GitHub state of one in-flight PR; only OBSERVES, level-triggered."
+                      ready: "the PR reaches match.prState (default merged)."
+                      binds: [mergedSha]
+                    - kind: epic
+                      target: "the epic's durable planKey (owner/repo#NN, the epic issue)"
+                      matchFields: [epicState]
+                      conditions: [merged, done]
+                      observes: "the app's lineage read-model, resolved by rootRequestKey REGARDLESS of thread kind (feature | epic | pr | delivery) — so it gates a single-PR FEATURE RUN just as well as a plan-fanout epic."
+                      ready: 'the lineage thread reaches stage:"merged" && active:false (every opened slice/PR landed).'
+                      binds: [prCount]
+                  connectorTargets:
+                    - target: converge
+                      status: real
+                      convergeOnlyDefault: true
+                      summary: "Converge-only: drive review convergence and stop at converged."
+                    - target: converge-merge
+                      status: real
+                      convergeOnlyDefault: false
+                      summary: "Unit-level land: converge AND merge onto the PR's own base branch."
+                    - target: merge-main
+                      status: real
+                      convergeOnlyDefault: false
+                      summary: "Graph-level top-level land onto main (two-level merge)."
+                    - target: "<any other target>"
+                      status: forward-declared
+                      summary: "Forward-declared stub — returns a deterministic acknowledgement, fires no real I/O."
+                  onTimeout:
+                    - value: escalate
+                      meaning: "park a human escalation when the bounded wait elapses."
+                    - value: fail
+                      meaning: "terminate the gate as failed (NOT yet supported on a wait node — rejected by the compiler)."
+                    - value: continue
+                      meaning: "proceed as if ready when the wait elapses (a soft gate)."
+                  pollBudget:
+                    defaultTimeoutMs: 1800000
+                    defaultTimeoutIso: PT30M
+                    defaultEveryMs: 15000
+                    rule: "An omitted poll.timeoutMs inherits the 30-minute default — a trap for wait[pr, merged]/wait[epic] which wait hours/days. Always set poll.timeoutMs explicitly on a merge/epic gate."
+                  factThreading:
+                    rule: "A node's emitted fact reaches a consumer ONLY via an edge (<nodeId>.<fact>); an unthreaded reference is rejected (unbound-pr)."
+                    details:
+                      - "The referenced fact must be declared in the producer's emits[] with the right type."
+                      - "A connector payload may omit pr to auto-bind the single incoming pr fact."
+                  guideSection: "docs/agent-guide.md §9 (Author and run a delivery graph)"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /actions/delivery-graph/library/save:
     post:
       operationId: saveToLibrary

package/operations/getAgentGuide.test.ts

@@ -0,0 +1,100 @@
+// Tests for GET /app/api/agent/guide → operation `getAgentGuide` (epic #605 slice S5, issue #611):
+// the addressable operator guide. No `section` → a compact table of contents; `section=<id>` → just
+// that section; an unknown id → 400 with `issues[{path,message}]`. Mirrors the getAgentInstructions
+// test's request shape and shared-secret guard pattern.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import { GUIDE_SECTIONS } from "../app/agentGuide.ts";
+import handler from "./getAgentGuide.ts";
+
+const app = { log: noopLog() } as any as AppApi;
+
+function input(query: Record<string, string> = {}, headers: Record<string, string> = {}) {
+  return {
+    req: {
+      method: "GET",
+      path: "/app/api/agent/guide",
+      query: new URLSearchParams(query),
+      headers: new Headers(headers),
+      text: async () => "",
+    } as any,
+    params: {},
+    query,
+    body: undefined,
+  };
+}
+
+test("no section → the table of contents, one entry per registry section", async () => {
+  const r = (await handler(input(), app)) as any;
+  assertEquals(r.status, 200);
+  assertEquals(r.body.kind, "toc");
+  assert(typeof r.body.baseUrl === "string" && r.body.baseUrl.length > 0);
+  assert(Array.isArray(r.body.sections));
+  assertEquals(r.body.sections.length, GUIDE_SECTIONS.length);
+  const ids = r.body.sections.map((s: any) => s.id);
+  for (const s of GUIDE_SECTIONS) assert(ids.includes(s.id), `TOC must list "${s.id}"`);
+  for (const s of r.body.sections) {
+    assert(typeof s.title === "string" && s.title.length > 0);
+    assert(typeof s.summary === "string" && s.summary.length > 0);
+  }
+});
+
+test("the TOC is far smaller than the full guide (fits a tool-result limit)", async () => {
+  const r = (await handler(input(), app)) as any;
+  assert(JSON.stringify(r.body).length < 4000, "the TOC response must stay compact");
+});
+
+test("section=delivery-graphs → just that section's markdown, base-keyed", async () => {
+  const r = (await handler(input({ section: "delivery-graphs" }), app)) as any;
+  assertEquals(r.status, 200);
+  assertEquals(r.body.kind, "section");
+  assertEquals(r.body.section.id, "delivery-graphs");
+  assertEquals(r.body.section.format, "markdown");
+  assert(r.body.section.instructions.length > 200);
+  assert(!r.body.section.instructions.includes("__BASE__"), "placeholders must be substituted");
+  assert(typeof r.body.engineBase === "string" && r.body.engineBase.length > 0);
+});
+
+test("a section is much smaller than the whole guide", async () => {
+  const toc = (await handler(input(), app)) as any;
+  const section = (await handler(input({ section: "orient" }), app)) as any;
+  assert(
+    JSON.stringify(section.body).length < 30000,
+    "a single section must comfortably fit a typical tool-result limit",
+  );
+  assertEquals(toc.body.kind, "toc");
+});
+
+test("an unknown section id → 400 with issues[{path,message}] listing valid ids", async () => {
+  const r = (await handler(input({ section: "nope" }), app)) as any;
+  assertEquals(r.status, 400);
+  assert(typeof r.body.error === "string");
+  assert(Array.isArray(r.body.issues) && r.body.issues.length === 1);
+  assertEquals(r.body.issues[0].path, "section");
+  assert(r.body.issues[0].message.includes("delivery-graphs"), "the 400 must name the valid ids");
+});
+
+test("blank/whitespace section is treated as no section (TOC)", async () => {
+  const r = (await handler(input({ section: "  " }), app)) as any;
+  assertEquals(r.status, 200);
+  assertEquals(r.body.kind, "toc");
+});
+
+test("shared-secret guard: rejects when the secret is set and header is wrong", async () => {
+  const prev = process.env.NANO_PR_WEBHOOK_SECRET;
+  process.env.NANO_PR_WEBHOOK_SECRET = "s3cr3t";
+  try {
+    // Re-import with the secret set so the module-level SECRET picks it up.
+    const mod = await import(`./getAgentGuide.ts?secret=${Date.now()}`);
+    const guarded = mod.default;
+    const rejected = (await guarded(input({}, {}), app)) as any;
+    assertEquals(rejected.status, 401);
+    const ok = (await guarded(input({}, { "x-hook-secret": "s3cr3t" }), app)) as any;
+    assertEquals(ok.status, 200);
+  } finally {
+    if (prev === undefined) delete process.env.NANO_PR_WEBHOOK_SECRET;
+    else process.env.NANO_PR_WEBHOOK_SECRET = prev;
+  }
+});

package/operations/getAgentGuide.ts

@@ -0,0 +1,92 @@
+// GET /app/api/agent/guide → operationId `getAgentGuide` (epic nano-workforce#605, slice S5,
+// issue #611). The ADDRESSABLE operator guide: fetch one section instead of the whole ~43KB blob
+// that `getAgentInstructions` returns (which can exceed an agent's tool-result limit, forcing it to
+// persist the blob and carve out a section out-of-band).
+//
+//   • No `section` query param → a compact table of contents: every stable section id + a one-line
+//     summary (`kind: "toc"`). Small by construction — safe under any tool-result limit.
+//   • `section=<id>` → ONLY that section's markdown (`kind: "section"`), examples keyed to THIS
+//     instance's control-API base + engine base, exactly as the full guide keys them.
+//   • An unknown id → 400 with `issues: [{ path: "section", message }]` listing the valid ids
+//     (the uniform validation-error contract).
+//
+// This is the MCP-friendly companion to `getAgentInstructions`; the full-guide doors
+// (`GET /agent`, `GET /agent/skill`) are untouched and byte-identical. Read-only, pure, idempotent.
+//
+// The optional shared-secret guard mirrors /agent and /version: enforced HERE only when
+// NANO_PR_WEBHOOK_SECRET is set (the runtime does not enforce OpenAPI `security`).
+import { guideToc, renderGuideSection, resolveEngineBase } from "../app/agentGuide.ts";
+import { resolveApiBase } from "../app/resolveApiBase.ts";
+import { buildVersionInfo, envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("getAgentGuide", ({ query, req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getAgentGuide rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+
+  const baseUrl = resolveApiBase(req, "agent/guide");
+  const rawSection = query.section;
+  const section = typeof rawSection === "string" ? rawSection.trim() : "";
+
+  // No section → the table of contents.
+  if (!section) {
+    return {
+      status: 200,
+      body: {
+        kind: "toc",
+        appVersion: buildVersionInfo().version,
+        generatedAt: new Date().toISOString(),
+        baseUrl,
+        sections: guideToc(),
+      },
+    };
+  }
+
+  // A section id → just that section, or a 400 that names the valid ids.
+  const instructions = renderGuideSection(section, baseUrl);
+  if (instructions === undefined) {
+    // Derive the valid ids from the PARSED table of contents — the sections this deployment can
+    // actually serve — not the static registry. When the guide doc is unreadable (RAW_GUIDE
+    // fallback, no `##` headings) the TOC is empty and NO id is retrievable, so say so explicitly
+    // rather than list registry ids that would themselves 400.
+    const validIds = guideToc().map((s) => s.id);
+    const detail =
+      validIds.length > 0
+        ? `valid ids: ${validIds.join(", ")}`
+        : "no sections are available in this deployment";
+    return {
+      status: 400,
+      body: {
+        error: `unknown guide section "${section}"`,
+        issues: [
+          {
+            path: "section",
+            message: `unknown section id "${section}"; ${detail}`,
+          },
+        ],
+      },
+    };
+  }
+
+  const title = guideToc().find((s) => s.id === section)?.title ?? section;
+  return {
+    status: 200,
+    body: {
+      kind: "section",
+      appVersion: buildVersionInfo().version,
+      generatedAt: new Date().toISOString(),
+      baseUrl,
+      engineBase: resolveEngineBase(),
+      section: {
+        id: section,
+        title,
+        format: "markdown",
+        instructions,
+      },
+    },
+  };
+});

package/operations/getDeliveryGraphVocabulary.ts

@@ -0,0 +1,25 @@
+// GET /app/api/delivery-graph/vocabulary → operationId `getDeliveryGraphVocabulary` (epic
+// nano-workforce#605, S3/#609). A read tool — projected onto the MCP surface like
+// `getAgentInstructions` — that returns the closed delivery-graph vocabulary + wait-probe semantics
+// as STRUCTURED JSON, so an agent can discover the node/probe/connector vocabulary and the non-obvious
+// wait/poll/fact-threading rules from the surface instead of reading source (ADR 0005).
+//
+// The payload is derived from the implementing code (`app/deliveryGraphVocabulary.ts`) — every closed
+// set is imported from its owning module, and a drift test fails the build if a probe kind / connector
+// target lands in the compiler without a vocabulary entry. Cross-linked from docs/agent-guide.md §9.
+//
+// Read-only. The optional shared-secret guard mirrors /agent and /version: enforced HERE only when
+// NANO_PR_WEBHOOK_SECRET is set (the runtime does not enforce OpenAPI `security`).
+import { deliveryGraphVocabulary } from "../app/deliveryGraphVocabulary.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("getDeliveryGraphVocabulary", ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getDeliveryGraphVocabulary rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  return { status: 200, body: deliveryGraphVocabulary() };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.159.1",
+  "version": "0.161.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",