@nanobpm/nano-workforce 0.150.0 → 0.150.2

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.150.2](https://github.com/nanobpm/nano-workforce/compare/v0.150.1...v0.150.2) (2026-08-28)
+
+### Bug Fixes
+
+* honour X-Forwarded-Prefix in resolveApiBase so the operator guide baseUrl resolves behind the app-view proxy ([#580](https://github.com/nanobpm/nano-workforce/issues/580)) ([21fdeca](https://github.com/nanobpm/nano-workforce/commit/21fdecac2d7c383cca066fa47950d9b6d28f41fc)), closes [#578](https://github.com/nanobpm/nano-workforce/issues/578)
+
+## [0.150.1](https://github.com/nanobpm/nano-workforce/compare/v0.150.0...v0.150.1) (2026-08-28)
+
+### Bug Fixes
+
+* **startFeature:** thread probePollEvery through the readiness gate ([#579](https://github.com/nanobpm/nano-workforce/issues/579)) ([#582](https://github.com/nanobpm/nano-workforce/issues/582)) ([d8f7739](https://github.com/nanobpm/nano-workforce/commit/d8f773907e1c66292fa6799f70e8d957f6f5f626)), closes [#295](https://github.com/nanobpm/nano-workforce/issues/295)
+
 ## [0.150.0](https://github.com/nanobpm/nano-workforce/compare/v0.149.0...v0.150.0) (2026-08-28)
 
 ### Features

package/app/resolveApiBase.test.ts

@@ -41,3 +41,59 @@ test("tolerates a leading slash on the mount suffix", () => {
 test("strips multiple trailing slashes after the mount suffix", () => {
   assertEquals(resolveApiBase(req({ host: "h" }, "/app/api/agent/skill///"), "agent/skill"), "http://h/app/api");
 });
+
+test("prepends a validated x-forwarded-prefix to the reconstructed base", () => {
+  const r = req(
+    { host: "nano.ngrok-free.dev", "x-forwarded-prefix": "/console/app-view/Workforce" },
+    "/app/api/agent",
+  );
+  assertEquals(resolveApiBase(r, "agent"), "http://nano.ngrok-free.dev/console/app-view/Workforce/app/api");
+});
+
+test("normalises a trailing slash on x-forwarded-prefix", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "/console/app-view/Workforce/" }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "http://h/console/app-view/Workforce/app/api");
+});
+
+test("ignores a x-forwarded-prefix carrying a scheme", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "https://evil.test" }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "http://h/app/api");
+});
+
+test("ignores a x-forwarded-prefix carrying an authority", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "//evil.test" }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "http://h/app/api");
+});
+
+test("ignores a x-forwarded-prefix with .. traversal", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "/a/../.." }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "http://h/app/api");
+});
+
+test("ignores a x-forwarded-prefix with percent-encoded .. traversal", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "/a/%2e%2e/%2e%2e" }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "http://h/app/api");
+});
+
+test("ignores a x-forwarded-prefix with a percent-encoded authority", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "/%2F%2Fevil.test" }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "http://h/app/api");
+});
+
+test("ignores a relative (non-absolute) x-forwarded-prefix", () => {
+  const r = req({ host: "h", "x-forwarded-prefix": "console/app-view/Workforce" }, "/app/api/agent");
+  assertEquals(resolveApiBase(r, "agent"), "http://h/app/api");
+});
+
+test("prefix composes with x-forwarded-proto and x-forwarded-host", () => {
+  const r = req(
+    {
+      host: "internal",
+      "x-forwarded-host": "nano.ngrok-free.dev",
+      "x-forwarded-proto": "https",
+      "x-forwarded-prefix": "/console/app-view/Workforce",
+    },
+    "/app/api/agent/skill",
+  );
+  assertEquals(resolveApiBase(r, "agent/skill"), "https://nano.ngrok-free.dev/console/app-view/Workforce/app/api");
+});

package/app/resolveApiBase.ts

@@ -4,8 +4,9 @@
 // to the request base (getAgentInstructions, getAgentSkill, …) — per AGENTS.md "Derivation over
 // duplication: no drift surfaces", proxy-header handling and base-path stripping must not fork.
 //
-// Honour reverse-proxy forwarding headers; fall back to a localhost default when the Host header is
-// absent (e.g. a raw unit-test request).
+// Honour reverse-proxy forwarding headers — proto, host, and the external path prefix
+// (X-Forwarded-Prefix, e.g. the console app-view proxy's "/console/app-view/{project}") — and fall
+// back to a localhost default when the Host header is absent (e.g. a raw unit-test request).
 
 /**
  * Recover the control-API base from a request, stripping the operation's own mount suffix.
@@ -20,9 +21,29 @@ export function resolveApiBase(req: { path: string; headers: Headers }, mountSuf
   // x-forwarded-proto is user-controlled behind some proxies; only trust http/https.
   const proto = rawProto === "http" || rawProto === "https" ? rawProto : "http";
   const host = (req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? "").split(",")[0].trim();
+  // The external path prefix stripped by a reverse proxy (e.g. the console app-view proxy mounts us
+  // under "/console/app-view/{project}"). X-Forwarded-Prefix is the de-facto standard header for it.
+  // It is untrusted, proxy-supplied input that ends up in a URL handed to an agent, so validate it as
+  // strictly as x-forwarded-proto above: accept only an absolute path of URL-safe path characters —
+  // rejecting anything with a scheme, an authority ("//host"), or a "."/".." traversal segment — then
+  // drop trailing slashes so it composes cleanly with the base path. Anything else falls back to an
+  // empty prefix, i.e. today's behaviour.
+  //
+  // Percent-encoding can smuggle those forms past a literal check: "%2e%2e" decodes to "..", and
+  // "%2f%2f" decodes to an authority-introducing "//". So normalise the common encoded spellings of
+  // "." and "/" (case-insensitively) before rejecting dot-segments and "//"; the still-encoded raw
+  // value is what we reflect once it validates.
+  const rawPrefix = (req.headers.get("x-forwarded-prefix") ?? "").split(",")[0].trim();
+  const decodedPrefix = rawPrefix.replace(/%2e/gi, ".").replace(/%2f/gi, "/");
+  const prefix =
+    /^\/(?!\/)[A-Za-z0-9._~\-/%]*$/.test(rawPrefix) &&
+    !decodedPrefix.includes("//") &&
+    !/(^|\/)\.\.?(\/|$)/.test(decodedPrefix)
+      ? rawPrefix.replace(/\/+$/, "")
+      : "";
   // The op is mounted at "<base>/<mountSuffix>"; strip the trailing segments to recover the base path.
   const suffix = mountSuffix.replace(/^\/+/, "").replace(/\/+$/, "");
   const stripRe = new RegExp(`/${suffix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/*$`);
   const basePath = req.path.replace(stripRe, "") || "/app/api";
-  return host ? `${proto}://${host}${basePath}` : `http://localhost:3000${basePath}`;
+  return host ? `${proto}://${host}${prefix}${basePath}` : `http://localhost:3000${prefix}${basePath}`;
 }

package/operations/getAgentInstructions.test.ts

@@ -86,6 +86,30 @@ test("examples are keyed to the request's control-API base and leave no placehol
   assert(!md.includes("__ENGINE__"), "no unsubstituted __ENGINE__ placeholder");
 });
 
+test("x-forwarded-prefix is prepended to the baseUrl and rendered examples", async () => {
+  const proxied = input(
+    {
+      host: "internal",
+      "x-forwarded-host": "nano.ngrok-free.dev",
+      "x-forwarded-proto": "https",
+      "x-forwarded-prefix": "/console/app-view/Workforce",
+    },
+  );
+  const body = (await handler(proxied, app)) as any;
+  assertEquals(body.body.baseUrl, "https://nano.ngrok-free.dev/console/app-view/Workforce/app/api");
+  const md = body.body.instructions as string;
+  assert(
+    md.includes("https://nano.ngrok-free.dev/console/app-view/Workforce/app/api/version"),
+    "prefixed base URL substituted into examples",
+  );
+});
+
+test("a hostile x-forwarded-prefix is ignored rather than reflected into the baseUrl", async () => {
+  const hostile = input({ host: "wf.example.com", "x-forwarded-prefix": "https://evil.test" });
+  const body = (await handler(hostile, app)) as any;
+  assertEquals(body.body.baseUrl, "http://wf.example.com/app/api", "hostile prefix falls back to today's behaviour");
+});
+
 test("x-forwarded-proto is restricted to http/https", async () => {
   const spoofed = input({ host: "wf.example.com", "x-forwarded-proto": "javascript" });
   const body = (await handler(spoofed, app)) as any;

package/operations/startFeature.readiness.integration.test.ts

@@ -0,0 +1,195 @@
+// Integration coverage for the intake READINESS gate (issue #295) driven through the operation EDGE —
+// `startFeature` → `parseFeatureReadiness` → the started run's variables. The unit tests in
+// app/featureReadiness.test.ts already prove the parser derives `probes`/`probeTimeout`/`probePollEvery`
+// correctly in isolation, and app/feature.test.ts proves `startFeature` seeds them onto the run. What
+// nothing asserted — and what regressed in issue #579 — is that the OPERATION threads the parser's
+// output through to `startFeature` intact: a too-narrow local dropped `probePollEvery` on the floor, so
+// every gated start (`blockedOn`/`readiness`) 500'd on startFeature's invariant. This file locks the
+// composed door behaviour: a gated start returns 202 and the run it fans out carries non-blank bounds.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { resetDefaultBranchCache } from "../app/github.ts";
+import { noopLog } from "../test/log.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
+import startFeature from "./startFeature.ts";
+
+// ── in-memory github model (default branch = main, so `confirmDefaultBase` is required) ───────────
+function githubFetch(repo: string) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = new URL(String(url));
+    const method = (init?.method ?? "GET").toUpperCase();
+    const path = u.pathname;
+    const json = (obj: unknown, status = 200) =>
+      new Response(JSON.stringify(obj), { status, headers: { "content-type": "application/json" } });
+    if (method === "GET" && path === `/repos/${repo}`) return Promise.resolve(json({ default_branch: "main" }));
+    const refPrefix = `/repos/${repo}/git/ref/heads/`;
+    if (method === "GET" && path.startsWith(refPrefix)) {
+      const branch = decodeURIComponent(path.slice(refPrefix.length));
+      if (branch !== "main") return Promise.resolve(new Response("Not Found", { status: 404 }));
+      return Promise.resolve(json({ ref: `refs/heads/${branch}`, object: { sha: `${branch}-sha` } }));
+    }
+    return Promise.resolve(new Response(`unexpected ${method} ${path}`, { status: 500 }));
+  };
+}
+
+async function withGithub<T>(repo: string, fn: () => Promise<T>): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  process.env["GITHUB_TOKEN"] = "tok";
+  resetDefaultBranchCache();
+  globalThis.fetch = githubFetch(repo) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    resetDefaultBranchCache();
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    if (prevTok === undefined) delete process.env["GITHUB_TOKEN"];
+    else process.env["GITHUB_TOKEN"] = prevTok;
+  }
+}
+
+// ── in-memory app (data + engine) ────────────────────────────────────────────
+// `started` records each engine.createInstance call so a test can assert the run's seeded variables.
+function makeApp() {
+  const tables = new Map<string, Record<string, unknown>[]>();
+  const started: { processDefinitionId?: string; variables?: Record<string, unknown> }[] = [];
+  const table = (name: string, key: string) => {
+    const rows = tables.get(name) ?? (() => {
+      const fresh: Record<string, unknown>[] = [];
+      tables.set(name, fresh);
+      return fresh;
+    })();
+    return {
+      get: (k: unknown) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+      find: (q: Record<string, unknown>) =>
+        Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+      findOne: (q: Record<string, unknown>) =>
+        Promise.resolve(rows.find((r) => Object.entries(q).every(([f, v]) => r[f] === v)) ?? null),
+      insert: (r: Record<string, unknown>) => {
+        rows.push(r);
+        return Promise.resolve(r);
+      },
+      update: (k: unknown, patch: Record<string, unknown>) => {
+        const row = rows.find((r) => r[key] === k);
+        if (row) Object.assign(row, patch);
+        return Promise.resolve(row);
+      },
+      delete: (k: unknown) => {
+        const i = rows.findIndex((r) => r[key] === k);
+        if (i >= 0) rows.splice(i, 1);
+        return Promise.resolve();
+      },
+    };
+  };
+  const app = {
+    data: { table: withTrackingViews(table) },
+    engine: {
+      createInstance: (req: { processDefinitionId?: string; variables?: Record<string, unknown> }) => {
+        started.push(req);
+        return Promise.resolve({ processInstanceKey: "PI-F1" });
+      },
+    },
+    log: noopLog(),
+  } as any as AppApi;
+  return { app, started };
+}
+
+function input(body: unknown) {
+  return {
+    req: { method: "POST", path: "/", query: new URLSearchParams(), headers: new Headers(), text: async () => "" } as any,
+    params: {},
+    query: {},
+    body,
+  };
+}
+
+const REPO = "owner/repo";
+const GATED_BASE = { baseBranch: "main", confirmDefaultBase: true } as const;
+
+// ── the #579 regression: a gated start must reach 202 AND thread the bounds through ───────────────
+
+test("blockedOn gate → 202 and the started run carries non-blank probeTimeout + probePollEvery", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(
+      input({ issue: `${REPO}#577`, ...GATED_BASE, blockedOn: [`${REPO}#578`] }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    assertEquals(started.length, 1);
+    const v = started[0].variables as Record<string, unknown>;
+    // The regressed field: it was dropped by a too-narrow local, so the run seeded a blank cadence and
+    // startFeature's invariant threw → 500. Both bounds must arrive non-blank.
+    assertEquals((v.probeTimeout as string).trim().length > 0, true);
+    assertEquals((v.probePollEvery as string).trim().length > 0, true);
+    assertEquals(Array.isArray(v.readinessProbes) && (v.readinessProbes as unknown[]).length === 1, true);
+  });
+});
+
+test("explicit readiness descriptor list → 202 with both bounds threaded to the run", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(
+      input({
+        issue: `${REPO}#577`,
+        ...GATED_BASE,
+        readiness: [{ kind: "command", target: "gh api repos/owner/repo/issues/578 --jq .state", match: { stdoutIncludes: "closed" } }],
+      }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    const v = started[0].variables as Record<string, unknown>;
+    assertEquals((v.probeTimeout as string).trim().length > 0, true);
+    assertEquals((v.probePollEvery as string).trim().length > 0, true);
+  });
+});
+
+test("blockedOn + consumerPackage (capability edge) → 202 with both bounds threaded", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(
+      input({ issue: `${REPO}#577`, ...GATED_BASE, blockedOn: [`${REPO}#578`], consumerPackage: "@nanobpm/engine-wasm" }),
+      app,
+    )) as any;
+    assertEquals(res.status, 202);
+    const v = started[0].variables as Record<string, unknown>;
+    assertEquals((v.probeTimeout as string).trim().length > 0, true);
+    assertEquals((v.probePollEvery as string).trim().length > 0, true);
+    const probes = v.readinessProbes as { kind?: string }[];
+    assertEquals(probes[0]?.kind, "capability");
+  });
+});
+
+// ── regression: an UNGATED start still passes null/absent for both bounds (gate skipped) ──────────
+
+test("no readiness ⇒ 202 and the run seeds null probeTimeout + probePollEvery (gate skipped)", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(input({ issue: `${REPO}#577`, ...GATED_BASE }), app)) as any;
+    assertEquals(res.status, 202);
+    const v = started[0].variables as Record<string, unknown>;
+    assertEquals(v.probeTimeout, null);
+    assertEquals(v.probePollEvery, null);
+    assertEquals(v.readinessProbes, null);
+  });
+});
+
+// ── a malformed gate is a caller-meaningful 400, never a 500 ──────────────────────────────────────
+
+test("malformed readiness descriptor → 400 at the edge (never a 500)", async () => {
+  await withGithub(REPO, async () => {
+    const { app, started } = makeApp();
+    const res = (await startFeature(
+      input({ issue: `${REPO}#577`, ...GATED_BASE, blockedOn: [""] }),
+      app,
+    )) as any;
+    assertEquals(res.status, 400);
+    assertEquals(typeof res.body.error, "string");
+    assertEquals(started.length, 0);
+  });
+});

package/operations/startFeature.ts

@@ -13,7 +13,7 @@
 // confirm-default / shared-base rules, with the same typed-error → HTTP mapping.
 
 import { startFeature } from "../app/feature.ts";
-import { parseFeatureReadiness } from "../app/featureReadiness.ts";
+import { type FeatureReadiness, parseFeatureReadiness } from "../app/featureReadiness.ts";
 import { BaseBranchMustExistError } from "../app/github.ts";
 import {
   admitPlan,
@@ -23,7 +23,6 @@ import {
   parseIssue,
   SharedBaseError,
 } from "../app/plan.ts";
-import type { ReadinessProbe } from "../app/readiness.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("startFeature", async ({ body }, app) => {
@@ -126,7 +125,12 @@ export default defineOperation("startFeature", async ({ body }, app) => {
   // `blockedOn` shorthand (resolved against `consumerPackage`) into the probes + bound the run parks
   // on before implementing. A malformed gate (bad descriptor, unparseable handle, blank package) is a
   // 400 at the edge — it must never wait forever at runtime.
-  let readiness: { probes: ReadinessProbe[]; probeTimeout: string | null };
+  // Type the local as the parser's OWN return type (not a hand-written subset): `parseFeatureReadiness`
+  // derives `probes`, `probeTimeout` AND `probePollEvery` together, and all three must be threaded to
+  // the run. A narrower local silently drops a field the parser produced (issue #579: `probePollEvery`
+  // was dropped, so every gated start 500'd on startFeature's invariant) without TypeScript flagging it,
+  // because the narrower shape is structurally assignable from the wider return.
+  let readiness: FeatureReadiness;
   try {
     readiness = parseFeatureReadiness({
       readiness: "readiness" in body ? body.readiness : undefined,
@@ -138,6 +142,31 @@ export default defineOperation("startFeature", async ({ body }, app) => {
     app.log.warn("start-feature rejected: invalid readiness gate", { message });
     return { status: 400, body: { error: message } };
   }
+  // Validate the gate's timing bounds at the EDGE, before dispatch: a non-empty probe set is
+  // load-bearing together with a non-blank `probeTimeout` (preflight escalation timers + pr.readiness-probe)
+  // and `probePollEvery` (preflight retry cadence). `parseFeatureReadiness` always derives all three
+  // together, so this only fires for a mis-derived/hand-seeded gate — but validating here turns that
+  // into a caller-meaningful 400 rather than a bare-Error 500 from startFeature's internal invariant.
+  if (readiness.probes.length > 0) {
+    const missingBounds: string[] = [];
+    if ((readiness.probeTimeout ?? "").trim() === "") missingBounds.push("a timeout");
+    if ((readiness.probePollEvery ?? "").trim() === "") missingBounds.push("a poll cadence");
+    if (missingBounds.length > 0) {
+      app.log.warn("start-feature rejected: readiness gate missing timing bound", {
+        missing: missingBounds,
+        probes: readiness.probes.length,
+      });
+      return {
+        status: 400,
+        body: {
+          error:
+            `readiness gate is malformed: ${readiness.probes.length} probe(s) but the request did not ` +
+            `resolve to ${missingBounds.join(" and ")}. A gated start (readiness/blockedOn) must resolve ` +
+            `to a non-blank timeout and poll cadence`,
+        },
+      };
+    }
+  }
   const result = await startFeature(
     app.data,
     app.engine,
@@ -146,7 +175,7 @@ export default defineOperation("startFeature", async ({ body }, app) => {
     converge,
     autoMerge,
     customInstructions,
-    { probes: readiness.probes, probeTimeout: readiness.probeTimeout },
+    { probes: readiness.probes, probeTimeout: readiness.probeTimeout, probePollEvery: readiness.probePollEvery },
   );
   app.log.info("feature run started", {
     featureKey: parsed.planKey,

package/package.json

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