@nanobpm/nano-workforce 0.179.2 → 0.181.0

package/openapi.yaml

@@ -1248,7 +1248,20 @@ components:
                 - markdown
             instructions:
               type: string
-              description: The section's markdown, with example commands keyed to this instance.
+              description: The section's markdown (or a bounded page of it when paginating), with example commands keyed to this instance.
+            start:
+              type: integer
+              description: The CHARACTER offset this page starts at (present only when paginating, issue #740).
+            length:
+              type: integer
+              description: The number of characters returned in this page (present only when paginating).
+            totalLength:
+              type: integer
+              description: The total number of characters in the fully-rendered section (present only when paginating).
+            nextStart:
+              type: integer
+              nullable: true
+              description: The `start` to pass for the next page, or null when this is the last page (present only when paginating).
     SubmitResult:
       type: object
       required:
@@ -2832,6 +2845,95 @@ components:
           description: >-
             A NAVIGATIONAL cockpit deep-link to the staged proposal (helps the agent hand the human a
             link). It is a pointer only — NOT a dispatch handle; nothing in this response can start a run.
+        superseded:
+          type: array
+          items:
+            type: string
+          description: >-
+            Digests of prior staged proposals sharing this graph's LOGICAL key (derived from its `name`)
+            that this stage replaced — flipped to `superseded` (issue #740). Empty on a first stage. Lets
+            the agent tell the operator precisely which proposals it retired.
+        siblingsStaged:
+          type: integer
+          description: >-
+            How many OTHER live staged proposals remain after this stage (a DIFFERENT logical key from
+            this one) — i.e. proposals this stage did NOT supersede (issue #740). A non-zero count flags
+            potential ORPHANED SIBLINGS (e.g. an earlier stage of the "same" runbook under a different
+            `name`, which supersede does not catch) cluttering the operator's Delivery Graphs list, so
+            the agent can name them for cleanup.
+    SequenceGate:
+      description: >-
+        An interleaved `wait` GATE (issue #740) that must go green before a given issue's agent starts
+        — reusing the exact probe schema `wait` nodes accept (`npm`/`github-check`/`http`/`command`/
+        `capability`/`pr`/`epic`). It lets an author splice e.g. "wait for `@nanobpm/agentic@0.13.0` to
+        publish" between two sequence steps without hand-authoring raw node/edge JSON.
+      type: object
+      additionalProperties: false
+      required:
+        - kind
+        - target
+      properties:
+        kind:
+          type: string
+          minLength: 1
+          description: >-
+            The wait-probe kind — one of the S3 vocabulary kinds (`npm`, `github-check`, `http`,
+            `command`, `capability`, `pr`, `epic`). An unknown kind is a 400.
+        target:
+          type: string
+          minLength: 1
+          description: >-
+            The probe target — kind-specific: `pkg@version` for `npm`, `owner/repo@ref` for
+            `github-check`, a URL for `http`, an `owner/repo#N` PR for `pr`, etc.
+        match:
+          type: object
+          description: >-
+            OPTIONAL kind-specific readiness match fields (e.g. `{ version }` for `npm`,
+            `{ conclusion, checkName }` for `github-check`).
+        poll:
+          type: object
+          additionalProperties: false
+          description: >-
+            OPTIONAL poll budget. Defaults to the bounded merge-gate budget (re-probe every 5 minutes,
+            budget 3 days) so a gate never falls into the 30-minute default trap.
+          properties:
+            everyMs:
+              type: integer
+              minimum: 1
+              description: How often to re-probe (milliseconds).
+            timeoutMs:
+              type: integer
+              minimum: 1
+              description: The total budget before the gate escalates/continues (milliseconds).
+        onTimeout:
+          type: string
+          enum:
+            - escalate
+            - continue
+          description: >-
+            What to do when the gate never goes green within its budget — `escalate` (default) parks on
+            a human; `continue` proceeds anyway. `fail` is not supported on a `wait` node.
+        credentialEnv:
+          type: string
+          minLength: 1
+          description: OPTIONAL env-key name supplying a credential for the probe (`http`/`capability`).
+    SequenceIssueEntry:
+      description: >-
+        One `issues[]` entry with an OPTIONAL leading gate (issue #740) — an object form of a sequence
+        step. The `issue` is implemented + converged + merged like a bare-string entry; the optional
+        `gate` must go green (in addition to the prior issue merging) before this issue's agent starts.
+      type: object
+      additionalProperties: false
+      required:
+        - issue
+      properties:
+        gate:
+          $ref: "#/components/schemas/SequenceGate"
+        issue:
+          type: string
+          minLength: 1
+          maxLength: 255
+          description: An `owner/repo#N` issue reference to implement + converge + merge, in sequence.
     SequenceIssuesIntent:
       description: >-
         The `sequenceIssues` INTENT (epic nano-workforce#605, S4) — a high-level shape that GENERATES
@@ -2843,15 +2945,21 @@ components:
         `compileDeliveryGraph` — it never dispatches (dispatch is an operator-only cockpit action, ADR
         0005 Decision 7). For each issue it emits `agent` (`senior:feature`, emits a `pr` fact) →
         `connector` (`converge-merge`, late-binding that `pr`) → `wait[pr, merged]` (a realistic
-        `poll.timeoutMs`), threading the `pr` fact per §9.4. Invalid input (empty `issues`, an
-        unparseable ref) is a 400 carrying `issues: [{ path, message }]`; nothing is staged.
+        `poll.timeoutMs`), threading the `pr` fact per §9.4. An `issues[]` entry may be a bare
+        `owner/repo#N` string OR a `{ gate?, issue }` object that interleaves a `wait` gate (the
+        `npm`/`github-check`/… vocabulary) before that issue's agent (issue #740). Invalid input (empty
+        `issues`, an unparseable ref, an unknown gate kind) is a 400 carrying `issues: [{ path, message
+        }]`; nothing is staged.
       type: object
       additionalProperties: false
       example:
-        behind: nanobpm/nano-ide#488
         issues:
-          - nanobpm/nano-workforce#567
-          - nanobpm/nano-workforce#568
+          - nanobpm/nano-ide#557
+          - gate:
+              kind: npm
+              target: "@nanobpm/agentic@0.13.0"
+            issue: jwulf/c8ctl-plugin-nano#186
+          - nanobpm/nano-workforce#738
       required:
         - issues
       properties:
@@ -2868,15 +2976,22 @@ components:
           minItems: 1
           maxItems: 64
           items:
-            type: string
-            minLength: 1
-            maxLength: 255
-            description: An `owner/repo#N` issue reference to implement + converge + merge, in sequence.
+            oneOf:
+              - type: string
+                minLength: 1
+                maxLength: 255
+                description: A bare `owner/repo#N` issue reference (no gate) — today's behaviour, byte-for-byte.
+              - $ref: "#/components/schemas/SequenceIssueEntry"
+            description: >-
+              A sequence step — a bare `owner/repo#N` string, or a `{ gate?, issue }` object that
+              interleaves a `wait` gate before that issue's agent (issue #740).
           description: >-
             The ordered issues to sequence — each is implemented by a `senior:feature` agent that opens
             a PR, driven to convergence + merge, and the NEXT issue's implementation starts only once
-            the prior issue has merged. At least one; at most 64 (keeps the generated graph within the
-            compiler's node ceiling).
+            the prior issue has merged (and any interleaved gate has gone green). At least one; at most
+            64. The compiler's node ceiling is enforced SEPARATELY by a node-budget guard (interleaved
+            gates each add nodes, so a fully-gated 64-issue sequence can exceed the ceiling and is
+            rejected there) — `maxItems: 64` bounds the entry count, not the generated node count.
     SequenceIssuesRejected:
       description: >-
         A rejected `sequenceIssues` intent — the input failed validation (empty/oversized `issues`, an
@@ -3847,6 +3962,31 @@ paths:
             with no argument), e.g. `orient`, `submit-pr`, `submit-epic`, `escalations`, `lifecycle`,
             `debug`, `debug-models`, `unstick`, `raise-issue`, `delivery-graphs`, `tool-crosswalk`. Omit it to get the
             table of contents. An unknown id yields a 400 listing the valid ids.
+        - name: start
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+            example: 0
+          description: >-
+            OPTIONAL pagination cursor (issue #740) — the CHARACTER offset into a `section`'s markdown to
+            start at. Passing `start` and/or `length` engages bounded-chunk retrieval so a large section
+            (e.g. `delivery-graphs`) can be paged through without overflowing a tool-result limit; the
+            response echoes `start`, `length`, `totalLength`, and a `nextStart` cursor (null on the last
+            page). Ignored when no `section` is given. Omit both `start` and `length` to get the whole
+            section unchanged.
+        - name: length
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            example: 12000
+          description: >-
+            OPTIONAL pagination window (issue #740) — the maximum number of CHARACTERS to return for a
+            `section`. Defaults to a bounded page size when `start` is given without `length`. Pair with
+            `start`/`nextStart` to page through an oversized section.
       responses:
         "200":
           description: Either the table of contents (no `section`) or a single section's markdown.
@@ -4161,14 +4301,17 @@ paths:
           application/json:
             schema:
               # BEGIN generated:mcp-body source=#/components/schemas/SequenceIssuesIntent (scripts/inline-mcp-bodies.ts — do not hand-edit)
-              description: 'The `sequenceIssues` INTENT (epic nano-workforce#605, S4) — a high-level shape that GENERATES the canonical "implement issue → converge → merge" delivery graph (operator-guide §9.4) instead of making an agent hand-author its node/edge JSON. It names an ordered list of `issues` to sequence (each issue''s implementation starts once the PRIOR issue has merged) and an OPTIONAL leading `behind` gate (wait for that issue/epic/feature to be fully merged first, §9.5). The door GENERATES, then STAGES the graph through the same compile+stage flow as `compileDeliveryGraph` — it never dispatches (dispatch is an operator-only cockpit action, ADR 0005 Decision 7). For each issue it emits `agent` (`senior:feature`, emits a `pr` fact) → `connector` (`converge-merge`, late-binding that `pr`) → `wait[pr, merged]` (a realistic `poll.timeoutMs`), threading the `pr` fact per §9.4. Invalid input (empty `issues`, an unparseable ref) is a 400 carrying `issues: [{ path, message }]`; nothing is staged.'
+              description: 'The `sequenceIssues` INTENT (epic nano-workforce#605, S4) — a high-level shape that GENERATES the canonical "implement issue → converge → merge" delivery graph (operator-guide §9.4) instead of making an agent hand-author its node/edge JSON. It names an ordered list of `issues` to sequence (each issue''s implementation starts once the PRIOR issue has merged) and an OPTIONAL leading `behind` gate (wait for that issue/epic/feature to be fully merged first, §9.5). The door GENERATES, then STAGES the graph through the same compile+stage flow as `compileDeliveryGraph` — it never dispatches (dispatch is an operator-only cockpit action, ADR 0005 Decision 7). For each issue it emits `agent` (`senior:feature`, emits a `pr` fact) → `connector` (`converge-merge`, late-binding that `pr`) → `wait[pr, merged]` (a realistic `poll.timeoutMs`), threading the `pr` fact per §9.4. An `issues[]` entry may be a bare `owner/repo#N` string OR a `{ gate?, issue }` object that interleaves a `wait` gate (the `npm`/`github-check`/… vocabulary) before that issue''s agent (issue #740). Invalid input (empty `issues`, an unparseable ref, an unknown gate kind) is a 400 carrying `issues: [{ path, message }]`; nothing is staged.'
               type: object
               additionalProperties: false
               example:
-                behind: nanobpm/nano-ide#488
                 issues:
-                  - nanobpm/nano-workforce#567
-                  - nanobpm/nano-workforce#568
+                  - nanobpm/nano-ide#557
+                  - gate:
+                      kind: npm
+                      target: '@nanobpm/agentic@0.13.0'
+                    issue: jwulf/c8ctl-plugin-nano#186
+                  - nanobpm/nano-workforce#738
               required:
                 - issues
               properties:
@@ -4182,11 +4325,66 @@ paths:
                   minItems: 1
                   maxItems: 64
                   items:
-                    type: string
-                    minLength: 1
-                    maxLength: 255
-                    description: An `owner/repo#N` issue reference to implement + converge + merge, in sequence.
-                  description: The ordered issues to sequence — each is implemented by a `senior:feature` agent that opens a PR, driven to convergence + merge, and the NEXT issue's implementation starts only once the prior issue has merged. At least one; at most 64 (keeps the generated graph within the compiler's node ceiling).
+                    oneOf:
+                      - type: string
+                        minLength: 1
+                        maxLength: 255
+                        description: A bare `owner/repo#N` issue reference (no gate) — today's behaviour, byte-for-byte.
+                      - description: "One `issues[]` entry with an OPTIONAL leading gate (issue #740) — an object form of a sequence step. The `issue` is implemented + converged + merged like a bare-string entry; the optional `gate` must go green (in addition to the prior issue merging) before this issue's agent starts."
+                        type: object
+                        additionalProperties: false
+                        required:
+                          - issue
+                        properties:
+                          gate:
+                            description: 'An interleaved `wait` GATE (issue #740) that must go green before a given issue''s agent starts — reusing the exact probe schema `wait` nodes accept (`npm`/`github-check`/`http`/`command`/ `capability`/`pr`/`epic`). It lets an author splice e.g. "wait for `@nanobpm/agentic@0.13.0` to publish" between two sequence steps without hand-authoring raw node/edge JSON.'
+                            type: object
+                            additionalProperties: false
+                            required:
+                              - kind
+                              - target
+                            properties:
+                              kind:
+                                type: string
+                                minLength: 1
+                                description: The wait-probe kind — one of the S3 vocabulary kinds (`npm`, `github-check`, `http`, `command`, `capability`, `pr`, `epic`). An unknown kind is a 400.
+                              target:
+                                type: string
+                                minLength: 1
+                                description: 'The probe target — kind-specific: `pkg@version` for `npm`, `owner/repo@ref` for `github-check`, a URL for `http`, an `owner/repo#N` PR for `pr`, etc.'
+                              match:
+                                type: object
+                                description: OPTIONAL kind-specific readiness match fields (e.g. `{ version }` for `npm`, `{ conclusion, checkName }` for `github-check`).
+                              poll:
+                                type: object
+                                additionalProperties: false
+                                description: OPTIONAL poll budget. Defaults to the bounded merge-gate budget (re-probe every 5 minutes, budget 3 days) so a gate never falls into the 30-minute default trap.
+                                properties:
+                                  everyMs:
+                                    type: integer
+                                    minimum: 1
+                                    description: How often to re-probe (milliseconds).
+                                  timeoutMs:
+                                    type: integer
+                                    minimum: 1
+                                    description: The total budget before the gate escalates/continues (milliseconds).
+                              onTimeout:
+                                type: string
+                                enum:
+                                  - escalate
+                                  - continue
+                                description: What to do when the gate never goes green within its budget — `escalate` (default) parks on a human; `continue` proceeds anyway. `fail` is not supported on a `wait` node.
+                              credentialEnv:
+                                type: string
+                                minLength: 1
+                                description: OPTIONAL env-key name supplying a credential for the probe (`http`/`capability`).
+                          issue:
+                            type: string
+                            minLength: 1
+                            maxLength: 255
+                            description: An `owner/repo#N` issue reference to implement + converge + merge, in sequence.
+                    description: "A sequence step — a bare `owner/repo#N` string, or a `{ gate?, issue }` object that interleaves a `wait` gate before that issue's agent (issue #740)."
+                  description: "The ordered issues to sequence — each is implemented by a `senior:feature` agent that opens a PR, driven to convergence + merge, and the NEXT issue's implementation starts only once the prior issue has merged (and any interleaved gate has gone green). At least one; at most 64. The compiler's node ceiling is enforced SEPARATELY by a node-budget guard (interleaved gates each add nodes, so a fully-gated 64-issue sequence can exceed the ceiling and is rejected there) — `maxItems: 64` bounds the entry count, not the generated node count."
               # END generated:mcp-body
       responses:
         "200":

package/operations/compileDeliveryGraph.test.ts

@@ -127,6 +127,10 @@ test("compile-delivery-graph: a changed graph with the same name SUPERSEDES the
     assert(a.body.digest !== b.body.digest, "the changed graph has a new digest");
     assertEquals((await deliveryGraphProposals(data).get(a.body.digest))?.status, "superseded");
     assertEquals((await deliveryGraphProposals(data).get(b.body.digest))?.status, "staged");
+    // The supersede is surfaced in the compile result body so the operator sees the retirement (#740).
+    assertEquals(b.body.superseded, [a.body.digest]);
+    assertEquals(b.body.siblingsStaged, 0);
+    assertEquals(a.body.superseded, []); // the first stage retired nothing
   });
 });
 

package/operations/getAgentGuide.test.ts

@@ -82,6 +82,19 @@ test("blank/whitespace section is treated as no section (TOC)", async () => {
   assertEquals(r.body.kind, "toc");
 });
 
+test("a pagination cursor beyond MAX_SAFE_INTEGER → 400 (unsafe integers lose precision)", async () => {
+  // 9007199254740993 === 9007199254740992 in IEEE-754 double, so `Number.isInteger` accepts it
+  // while it no longer represents the caller's requested character offset. It must be rejected.
+  const unsafe = "9007199254740993";
+  const rStart = (await handler(input({ section: "delivery-graphs", start: unsafe }), app)) as any;
+  assertEquals(rStart.status, 400);
+  assert(Array.isArray(rStart.body.issues) && rStart.body.issues.some((i: any) => i.path === "start"));
+
+  const rLength = (await handler(input({ section: "delivery-graphs", length: unsafe }), app)) as any;
+  assertEquals(rLength.status, 400);
+  assert(Array.isArray(rLength.body.issues) && rLength.body.issues.some((i: any) => i.path === "length"));
+});
+
 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";

package/operations/getAgentGuide.ts

@@ -15,13 +15,29 @@
 //
 // 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 { GUIDE_SECTION_PAGE_DEFAULT, guideToc, renderGuideSection, renderGuideSectionChunk, 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") ?? "";
 
+/** Parse a `start`/`length` pagination query param: a present value must be a non-negative SAFE
+ *  integer (`length` additionally >= 1). `Number.isSafeInteger` (not `Number.isInteger`) is required
+ *  because these values are used as character cursors: an integer beyond `Number.MAX_SAFE_INTEGER`
+ *  (e.g. `9007199254740993`) loses precision, so accepting it would silently misinterpret the
+ *  caller's requested window. Returns the parsed number, `undefined` when absent, or a
+ *  path-qualified validation issue. */
+function parsePageArg(raw: unknown, path: string, min: number): { value?: number; issue?: { path: string; message: string } } {
+  if (raw === undefined || raw === null || (typeof raw === "string" && raw.trim() === "")) return {};
+  const s = typeof raw === "string" ? raw.trim() : String(raw);
+  const n = Number(s);
+  if (!Number.isSafeInteger(n) || n < min) {
+    return { issue: { path, message: `\`${path}\` must be an integer >= ${min} (character offset); got "${s}"` } };
+  }
+  return { value: n };
+}
+
 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");
@@ -46,9 +62,23 @@ export default defineOperation("getAgentGuide", ({ query, req }, app) => {
     };
   }
 
-  // A section id → just that section, or a 400 that names the valid ids.
-  const instructions = renderGuideSection(section, baseUrl);
-  if (instructions === undefined) {
+  // Pagination window (issue #740): a caller engages it by passing `start` and/or `length` (character
+  // offsets). Absent both, the whole section is returned unchanged (byte-for-byte identical to before).
+  const startArg = parsePageArg(query.start, "start", 0);
+  const lengthArg = parsePageArg(query.length, "length", 1);
+  const pageIssues = [startArg.issue, lengthArg.issue].filter((i): i is { path: string; message: string } => i !== undefined);
+  if (pageIssues.length > 0) {
+    app.log.warn("getAgentGuide rejected: invalid pagination args", { issues: pageIssues.length });
+    return { status: 400, body: { error: "invalid pagination arguments", issues: pageIssues } };
+  }
+  const paginate = startArg.value !== undefined || lengthArg.value !== undefined;
+
+  // A section id → just that section (or a bounded page of it), or a 400 that names the valid ids.
+  const chunk = paginate ? renderGuideSectionChunk(section, baseUrl, startArg.value ?? 0, lengthArg.value ?? GUIDE_SECTION_PAGE_DEFAULT) : undefined;
+  // The resolved body text: a page's slice when paginating, else the whole section. `undefined` from
+  // either path means the section id is unknown → the uniform 400 below.
+  const resolved = chunk ? chunk.instructions : paginate ? undefined : renderGuideSection(section, baseUrl);
+  if (resolved === 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
@@ -85,7 +115,12 @@ export default defineOperation("getAgentGuide", ({ query, req }, app) => {
         id: section,
         title,
         format: "markdown",
-        instructions,
+        instructions: resolved,
+        // Pagination cursor state — present ONLY when the caller engaged a window, so an un-paginated
+        // `section=<id>` call's body stays byte-for-byte identical (issue #740).
+        ...(chunk
+          ? { start: chunk.start, length: chunk.length, totalLength: chunk.totalLength, nextStart: chunk.nextStart }
+          : {}),
       },
     },
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.179.2",
+  "version": "0.181.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",