@nanobpm/nano-workforce 0.180.0 → 0.181.0

package/app/sequenceIssues.ts

@@ -19,8 +19,9 @@
 // `pr`-typed emits, threaded fact edges, a DAG. It is validated against the S3 vocabulary
 // (`deliveryGraphVocabulary`) so an unknown connector target / probe kind is rejected at the door with
 // `issues[{path,message}]` rather than only surfacing at compile time.
-import type { DeliveryEdge, DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
+import type { DeliveryEdge, DeliveryGraph, DeliveryNode, ReadinessProbe } from "../nano-generated/api-io.d.ts";
 import { CONVERGE_MERGE_TARGET } from "./convergeTargets.ts";
+import { GRAPH_MAX_NODES } from "./deliveryGraph.ts";
 import { deliveryGraphVocabulary } from "./deliveryGraphVocabulary.ts";
 import { type ParsedIssue, parseIssue } from "./plan.ts";
 
@@ -31,10 +32,42 @@ export interface SequenceIssueError {
   readonly message: string;
 }
 
-/** The `sequenceIssues` intent body — an optional leading `behind` gate plus the ordered `issues`. */
+/** An interleaved `wait` GATE that must go green before a given issue's agent starts (issue #740).
+ * Reuses the exact probe schema `wait` nodes already accept — the `npm`/`github-check`/`http`/…
+ * vocabulary — so an author can insert e.g. "wait for `@nanobpm/agentic@0.13.0` to publish" between
+ * two sequence steps without falling off the intent onto raw node/edge JSON. */
+export interface SequenceGate {
+  /** The wait-probe kind (must be a known kind in the S3 vocabulary — `npm`, `github-check`, `http`,
+   * `command`, `capability`, `pr`, `epic`). */
+  kind: string;
+  /** The probe target — kind-specific (`pkg@version` for `npm`, `owner/repo@ref` for `github-check`,
+   * a URL for `http`, …). */
+  target: string;
+  /** Optional kind-specific readiness `match` fields (e.g. `{ version }` for `npm`). */
+  match?: Record<string, unknown>;
+  /** Optional poll budget; defaults to the bounded merge-gate budget ({@link MERGE_POLL}) so a gate
+   * never falls into the 30-minute default trap. */
+  poll?: { everyMs?: number; timeoutMs?: number };
+  /** What to do when the gate never goes green within its budget — `escalate` (default) or `continue`.
+   * `fail` is rejected (not yet supported by the compiler/engine). */
+  onTimeout?: "escalate" | "continue";
+  /** Optional env-key name supplying a credential for the probe (`http`/`capability`). */
+  credentialEnv?: string;
+}
+
+/** One `issues[]` entry with an OPTIONAL leading {@link SequenceGate} — the object form. A bare string
+ * entry (no gate) keeps today's behaviour byte-for-byte. */
+export interface SequenceIssueEntry {
+  gate?: SequenceGate;
+  issue: string;
+}
+
+/** The `sequenceIssues` intent body — an optional leading `behind` gate plus the ordered `issues`,
+ * each of which may be a bare `owner/repo#N` string OR a `{ gate?, issue }` object interleaving a
+ * `wait` gate before that issue's agent (issue #740). */
 export interface SequenceIssuesIntent {
   behind?: string;
-  issues: string[];
+  issues: (string | SequenceIssueEntry)[];
 }
 
 /** The result of {@link buildSequenceGraph}: either the constructed graph, or the path-qualified
@@ -63,6 +96,29 @@ export const MAX_SEQUENCE_ISSUES = 64;
  * downstream connector / `wait[pr]` node late-binds its target PR from the fact (§9.4, issue #548). */
 const PR_EMIT = { name: "pr", type: "pr" as const };
 
+/** A validated, ready-to-emit interleaved gate: `poll` and `onTimeout` are resolved to concrete values
+ * (defaults applied) so {@link assembleGraph} can drop it straight into a `wait` node's config. */
+interface BuiltGate {
+  kind: ReadinessProbe["kind"];
+  target: string;
+  match?: Record<string, unknown>;
+  poll: { everyMs?: number; timeoutMs?: number };
+  onTimeout: "escalate" | "continue";
+  credentialEnv?: string;
+}
+
+/** A parsed `issues[]` entry: the normalised issue plan-key plus its optional interleaved gate. */
+interface ParsedEntry {
+  issueKey: string;
+  gate: BuiltGate | null;
+}
+
+/** Narrow a validated string to the closed `ReadinessProbe["kind"]` union — backed by the runtime
+ * vocabulary set so the type guard and the door validation share one source of truth. */
+function isProbeKind(kind: string, probeKinds: Set<string>): kind is ReadinessProbe["kind"] {
+  return probeKinds.has(kind);
+}
+
 /** Parse a ref into an issue target ONLY if its number is a positive, safe integer. `parseIssue`'s
  * `\d+` accepts `#0` and precision-overflowing numbers (e.g. `#99999999999999999999`, which coerces
  * past `Number.MAX_SAFE_INTEGER`), but such a target can never resolve to a real issue/PR — staging a
@@ -74,12 +130,111 @@ function parseIssueRef(ref: unknown): ParsedIssue | null {
   return Number.isSafeInteger(parsed.number) && parsed.number >= 1 ? parsed : null;
 }
 
+/** Validate one interleaved `gate` spec against the probe vocabulary, applying defaults. Returns the
+ * built gate or path-qualified `issues[{path,message}]` rejections (keyed under `path`, e.g.
+ * `issues[1].gate.kind`). Reuses the same probe schema `wait` nodes accept: `{ kind, target, match?,
+ * poll?, onTimeout?, credentialEnv? }`. */
+function parseGate(raw: unknown, path: string, probeKinds: Set<string>): { gate?: BuiltGate; errors: SequenceIssueError[] } {
+  const errors: SequenceIssueError[] = [];
+  if (!isRecord(raw)) {
+    return { errors: [{ path, message: "`gate` must be an object carrying a `wait` probe (`{ kind, target, … }`)." }] };
+  }
+
+  // Trim before validating AND before persisting: harmless surrounding whitespace must neither
+  // trip a confusing "unknown kind" rejection nor survive into the generated `wait` node, where a
+  // stray trailing space silently probes the wrong target (`pkg@1.0.0 ` → a gate that never goes
+  // green). The persisted value is always the trimmed one.
+  let validKind: ReadinessProbe["kind"] | null = null;
+  const kind = raw.kind;
+  if (typeof kind !== "string" || kind.trim() === "") {
+    errors.push({ path: `${path}.kind`, message: "`gate.kind` is required and must be a non-empty wait-probe kind." });
+  } else {
+    const trimmedKind = kind.trim();
+    if (!isProbeKind(trimmedKind, probeKinds)) {
+      errors.push({ path: `${path}.kind`, message: `wait-probe kind \`${trimmedKind}\` is not in the delivery-graph vocabulary.` });
+    } else {
+      validKind = trimmedKind;
+    }
+  }
+
+  let validTarget: string | null = null;
+  const target = raw.target;
+  if (typeof target !== "string" || target.trim() === "") {
+    errors.push({ path: `${path}.target`, message: "`gate.target` is required and must be a non-empty string." });
+  } else {
+    validTarget = target.trim();
+  }
+
+  let match: Record<string, unknown> | undefined;
+  if (raw.match !== undefined) {
+    if (!isRecord(raw.match)) {
+      errors.push({ path: `${path}.match`, message: "`gate.match`, when present, must be an object of readiness fields." });
+    } else {
+      match = raw.match;
+    }
+  }
+
+  const poll: { everyMs?: number; timeoutMs?: number } = { ...MERGE_POLL };
+  if (raw.poll !== undefined) {
+    if (!isRecord(raw.poll)) {
+      errors.push({ path: `${path}.poll`, message: "`gate.poll`, when present, must be `{ everyMs?, timeoutMs? }`." });
+    } else {
+      for (const key of ["everyMs", "timeoutMs"] as const) {
+        const v = raw.poll[key];
+        if (v === undefined) continue;
+        if (typeof v !== "number" || !Number.isSafeInteger(v) || v < 1) {
+          errors.push({ path: `${path}.poll.${key}`, message: `\`gate.poll.${key}\`, when present, must be a positive integer (milliseconds).` });
+        } else {
+          poll[key] = v;
+        }
+      }
+    }
+  }
+
+  let onTimeout: "escalate" | "continue" = "escalate";
+  if (raw.onTimeout !== undefined) {
+    if (raw.onTimeout !== "escalate" && raw.onTimeout !== "continue") {
+      errors.push({
+        path: `${path}.onTimeout`,
+        message: "`gate.onTimeout` must be `escalate` (default) or `continue` — `fail` is not supported on a `wait` node.",
+      });
+    } else {
+      onTimeout = raw.onTimeout;
+    }
+  }
+
+  let credentialEnv: string | undefined;
+  if (raw.credentialEnv !== undefined) {
+    if (typeof raw.credentialEnv !== "string" || raw.credentialEnv.trim() === "") {
+      errors.push({ path: `${path}.credentialEnv`, message: "`gate.credentialEnv`, when present, must be a non-empty env-key name." });
+    } else {
+      credentialEnv = raw.credentialEnv;
+    }
+  }
+
+  if (errors.length > 0 || validKind === null || validTarget === null) return { errors };
+  return {
+    gate: {
+      kind: validKind,
+      target: validTarget,
+      ...(match ? { match } : {}),
+      poll,
+      onTimeout,
+      ...(credentialEnv ? { credentialEnv } : {}),
+    },
+    errors: [],
+  };
+}
+
 /**
  * Build the canonical delivery graph for a `sequenceIssues` intent, or return path-qualified
  * `issues[{path,message}]` rejections for invalid input. Validates:
  *   - `issues` is a non-empty array within {@link MAX_SEQUENCE_ISSUES};
- *   - every `issues[i]` and the optional `behind` parse as an `owner/repo#N` reference;
- *   - the connector target and wait-probe kinds it emits are known to the S3 vocabulary (drift guard).
+ *   - every `issues[i]` (a bare ref, or a `{ gate?, issue }` object) and the optional `behind` parse
+ *     as an `owner/repo#N` reference;
+ *   - each interleaved `gate` names a wait-probe kind known to the S3 vocabulary (issue #740);
+ *   - the connector target and wait-probe kinds it emits are known to the S3 vocabulary (drift guard);
+ *   - the generated graph stays within the compiler's node ceiling.
  * Pure — no I/O. The constructed graph passes `validateDeliveryGraph` by construction.
  */
 export function buildSequenceGraph(intent: unknown): SequenceIssuesResult {
@@ -89,8 +244,12 @@ export function buildSequenceGraph(intent: unknown): SequenceIssuesResult {
   const rawIssues = body.issues;
   const rawBehind = body.behind;
 
-  // ── `issues`: a non-empty, bounded array of parseable refs ───────────────────────────────────
-  const parsedIssues: string[] = [];
+  // The vocabulary is needed up front to validate interleaved gate `kind`s as each entry is parsed.
+  const vocab = deliveryGraphVocabulary();
+  const probeKinds = new Set(vocab.waitProbeKinds.map((p) => p.kind));
+
+  // ── `issues`: a non-empty, bounded array of parseable refs, each optionally carrying a gate ────
+  const parsedEntries: ParsedEntry[] = [];
   if (!Array.isArray(rawIssues)) {
     issues.push({ path: "issues", message: "`issues` must be a non-empty array of `owner/repo#N` issue references." });
   } else if (rawIssues.length === 0) {
@@ -101,16 +260,26 @@ export function buildSequenceGraph(intent: unknown): SequenceIssuesResult {
       message: `\`issues\` has too many entries (${rawIssues.length}) — the limit is ${MAX_SEQUENCE_ISSUES}.`,
     });
   } else {
-    rawIssues.forEach((ref, i) => {
-      const parsed = parseIssueRef(ref);
+    rawIssues.forEach((entry, i) => {
+      // A bare string entry is a gate-less issue (today's behaviour, byte-for-byte). An object entry
+      // carries a required `issue` ref plus an OPTIONAL leading `gate` (issue #740).
+      const rawRef = isRecord(entry) ? entry.issue : entry;
+      const parsed = parseIssueRef(rawRef);
       if (!parsed) {
+        const shown = isRecord(entry) ? String(rawRef) : String(entry);
         issues.push({
-          path: `issues[${i}]`,
-          message: `\`${String(ref)}\` is not a valid \`owner/repo#N\` issue reference.`,
+          path: isRecord(entry) ? `issues[${i}].issue` : `issues[${i}]`,
+          message: `\`${shown}\` is not a valid \`owner/repo#N\` issue reference.`,
         });
         return;
       }
-      parsedIssues.push(parsed.planKey);
+      let gate: BuiltGate | null = null;
+      if (isRecord(entry) && entry.gate !== undefined && entry.gate !== null) {
+        const parsedGate = parseGate(entry.gate, `issues[${i}].gate`, probeKinds);
+        issues.push(...parsedGate.errors);
+        gate = parsedGate.gate ?? null;
+      }
+      parsedEntries.push({ issueKey: parsed.planKey, gate });
     });
   }
 
@@ -135,7 +304,6 @@ export function buildSequenceGraph(intent: unknown): SequenceIssuesResult {
   // ── Vocabulary drift guard (S3): the target/probe kinds this generator emits MUST be known to the
   // structured vocabulary. This can only trip if the closed vocabulary changes underneath us — it is
   // surfaced as a door `issue` (not a throw) so the failure mode is a clean rejection, not a 500. ──
-  const vocab = deliveryGraphVocabulary();
   const realTargets = new Set(vocab.connectorTargets.filter((t) => t.status === "real").map((t) => t.target));
   if (!realTargets.has(CONVERGE_MERGE_TARGET)) {
     issues.push({
@@ -143,28 +311,43 @@ export function buildSequenceGraph(intent: unknown): SequenceIssuesResult {
       message: `connector target \`${CONVERGE_MERGE_TARGET}\` is not a real target in the delivery-graph vocabulary.`,
     });
   }
-  const probeKinds = new Set(vocab.waitProbeKinds.map((p) => p.kind));
   for (const kind of behindKey ? [PR_PROBE_KIND, EPIC_PROBE_KIND] : [PR_PROBE_KIND]) {
     if (!probeKinds.has(kind)) {
       issues.push({ path: "issues", message: `wait-probe kind \`${kind}\` is not in the delivery-graph vocabulary.` });
     }
   }
 
+  // ── Node-budget guard: interleaved gates add a node per gated issue, so a fully-gated max-length
+  // sequence (plus the optional `behind` gate) can push past the compiler's node ceiling. Reject it
+  // at the door so a SUCCESSFULLY generated graph always validates `by construction`. ──
+  if (issues.length === 0) {
+    const projectedNodes = (behindKey ? 1 : 0) + parsedEntries.reduce((n, e) => n + 3 + (e.gate ? 1 : 0), 0);
+    if (projectedNodes > GRAPH_MAX_NODES) {
+      issues.push({
+        path: "issues",
+        message: `the generated graph would have too many nodes (${projectedNodes}) — the limit is ${GRAPH_MAX_NODES}; use fewer issues or interleaved gates.`,
+      });
+    }
+  }
+
   if (issues.length > 0) return { ok: false, issues };
 
-  return { ok: true, graph: assembleGraph(parsedIssues, behindKey) };
+  return { ok: true, graph: assembleGraph(parsedEntries, behindKey) };
 }
 
-/** Assemble the canonical node/edge chain for the (already-validated) issue keys + optional gate. */
-function assembleGraph(issueKeys: string[], behindKey: string | null): DeliveryGraph {
+/** Assemble the canonical node/edge chain for the (already-validated) parsed entries + optional gate.
+ * Each entry emits `agent → connector[converge-merge] → wait[pr, merged]`; an entry with an
+ * interleaved `gate` gets a leading `wait[<gate.kind>]` node spliced between the prior sequence step
+ * and its agent, so the agent starts only once the prior issue merged AND the gate went green. */
+function assembleGraph(entries: ParsedEntry[], behindKey: string | null): DeliveryGraph {
   const nodes: DeliveryNode[] = [];
   const edges: DeliveryEdge[] = [];
 
   // Optional leading `wait[epic]` gate — the whole sequence waits for `behind` to be fully merged.
-  const GATE_ID = "gate-epic";
+  const EPIC_GATE_ID = "gate-epic";
   if (behindKey) {
     nodes.push({
-      id: GATE_ID,
+      id: EPIC_GATE_ID,
       kind: "wait",
       wait: {
         kind: EPIC_PROBE_KIND,
@@ -177,12 +360,40 @@ function assembleGraph(issueKeys: string[], behindKey: string | null): DeliveryG
     });
   }
 
-  issueKeys.forEach((issueKey, i) => {
+  entries.forEach((entry, i) => {
     const n = i + 1;
     const openId = `open-${n}`;
     const landId = `land-${n}`;
     const mergedId = `merged-${n}`;
     const prRef = `${openId}.pr`;
+    const issueKey = entry.issueKey;
+
+    // The sequence predecessor whose completion releases THIS issue: the prior issue's merge, else the
+    // leading epic gate for the first issue (null when the first issue is ungated by `behind`).
+    const predecessor = i === 0 ? (behindKey ? EPIC_GATE_ID : null) : `merged-${i}`;
+
+    // Interleaved gate (issue #740): a `wait[<kind>]` node the issue's agent waits on. It inherits the
+    // sequence predecessor's edge (so it only starts probing once the prior issue merged) and the
+    // agent then waits on the gate — gating the agent on the prior merge AND the gate condition.
+    let agentPredecessor = predecessor;
+    if (entry.gate) {
+      const gateId = `gate-${n}`;
+      const g = entry.gate;
+      nodes.push({
+        id: gateId,
+        kind: "wait",
+        wait: {
+          kind: g.kind,
+          target: g.target,
+          ...(g.match ? { match: g.match } : {}),
+          poll: { ...g.poll },
+          onTimeout: g.onTimeout,
+          ...(g.credentialEnv ? { credentialEnv: g.credentialEnv } : {}),
+        },
+      });
+      if (predecessor) edges.push({ from: predecessor, to: gateId });
+      agentPredecessor = gateId;
+    }
 
     // agent → opens the PR, emits it as a typed `pr` fact the downstream nodes late-bind.
     nodes.push({
@@ -214,18 +425,16 @@ function assembleGraph(issueKeys: string[], behindKey: string | null): DeliveryG
     edges.push({ from: prRef, to: landId });
     edges.push({ from: prRef, to: mergedId });
 
-    // Sequence: this issue's agent starts once the PRIOR issue merged; the first waits on the gate.
-    if (i === 0) {
-      if (behindKey) edges.push({ from: GATE_ID, to: openId });
-    } else {
-      edges.push({ from: `merged-${i}`, to: openId });
-    }
+    // Sequence: this issue's agent starts once its predecessor (prior merge / epic gate / interleaved
+    // gate) released. A first ungated issue has no predecessor edge (it starts immediately).
+    if (agentPredecessor) edges.push({ from: agentPredecessor, to: openId });
   });
 
+  const gateCount = entries.filter((e) => e.gate).length;
   const name =
-    issueKeys.length === 1
-      ? `sequence ${issueKeys[0]}`
-      : `sequence ${issueKeys.length} issues${behindKey ? ` behind ${behindKey}` : ""}`;
+    entries.length === 1
+      ? `sequence ${entries[0].issueKey}`
+      : `sequence ${entries.length} issues${gateCount > 0 ? ` with ${gateCount} gate${gateCount === 1 ? "" : "s"}` : ""}${behindKey ? ` behind ${behindKey}` : ""}`;
 
   return { name, nodes, edges };
 }

package/e2e/addressable-guide.e2e.ts

@@ -69,6 +69,49 @@ describe("S5 — the addressable operator guide over MCP (#611)", () => {
     assert(res.text.length < 30000, "one section must fit a typical tool-result budget in a single call");
   });
 
+  test("section pagination: start/length pages a section and nextStart walks it to completion (#740)", async () => {
+    const whole = await h.callTool("getAgentGuide", { section: "delivery-graphs" });
+    const wholeSection = (whole.json as { section?: { instructions: string } }).section!;
+    const wholeChars = Array.from(wholeSection.instructions);
+
+    const PAGE = 4000;
+    let start = 0;
+    let assembled = "";
+    let pages = 0;
+    let total = -1;
+    for (;;) {
+      const res = await h.callTool("getAgentGuide", { section: "delivery-graphs", start, length: PAGE });
+      assert(!res.isError, `a paged fetch must not error: ${res.text}`);
+      const body = res.json as {
+        kind?: string;
+        section?: { id: string; instructions: string; start: number; length: number; totalLength: number; nextStart: number | null };
+      };
+      assert.equal(body.kind, "section");
+      const s = body.section!;
+      assert.equal(s.id, "delivery-graphs");
+      assert(Array.from(s.instructions).length <= PAGE, "a page must be bounded by `length`");
+      assert.equal(s.start, start);
+      if (total !== -1) assert.equal(s.totalLength, total, "totalLength is stable across pages");
+      total = s.totalLength;
+      assembled += s.instructions;
+      pages++;
+      if (s.nextStart === null) break;
+      start = s.nextStart;
+      assert(pages < 100, "pagination must terminate");
+    }
+    assert(pages > 1, "a large section must span multiple pages at this window");
+    assert.equal(total, wholeChars.length, "totalLength equals the full section length");
+    assert.equal(assembled, wholeSection.instructions, "the reassembled pages equal the whole section");
+  });
+
+  test("section pagination: a non-integer/negative start is a uniform issues[{path,message}] 400 (#740)", async () => {
+    const res = await h.callTool("getAgentGuide", { section: "delivery-graphs", start: -5 });
+    assert(res.isError, "an invalid pagination arg must surface as a tool-level error");
+    const body = res.json as { issues?: { path: string; message: string }[] };
+    assert(Array.isArray(body.issues) && body.issues.length >= 1, "must answer with issues[]");
+    assert(body.issues!.some((i) => i.path.includes("start")), "the issue must name the `start` argument");
+  });
+
   test("an unknown section id is rejected with issues[{path,message}]", async () => {
     const res = await h.callTool("getAgentGuide", { section: "no-such-section" });
     assert(res.isError, "an unknown section id must surface as a tool-level error");