@sjawhar/pi-legion-envoy 5.23.0 → 5.24.0

package/README.md

@@ -71,14 +71,15 @@ at `dist/skills`. The manifest declares `omp.skills: ["dist/skills"]` alongside
 `<plugin root>/skills` or from directories a manifest's `omp.skills` array names, and this
 package ships skills at `dist/skills` (not the plugin root itself), so the field is required
 for every session — including a headless Legion controller — to see the Legion skills at all.
-The tarball also ships `agents/`, the task agents Legion's skills dispatch (`oracle`, and the
-reviewer's pair `thermonuclear-deep-review` and `thermonuclear-code-quality`), which Oh My Pi
-discovers under any extension package root: an installed plugin in a pane, the explicit
-`--extension` root in a Sandbox pod. The skills those agents and the role prompts load (the pair's
-rubrics, the implementer's `ce-simplify-code`) ship in `dist/skills` with the rest. The Go
-daemon's boot gate and `legion probe-image` resolve every `task(agent="…")` and every
-`skill://<name>` those prompts name through the same launch, and refuse by name an agent or a
-skill Oh My Pi cannot find.
+The tarball also ships `agents/`, the task agents Legion's prompts dispatch (`oracle`, the
+reviewer's pair `thermonuclear-deep-review` and `thermonuclear-code-quality`, and `deep-worker`,
+which writes the implementer's code), which Oh My Pi discovers under any extension package root:
+an installed plugin in a pane, the explicit `--extension` root in a Sandbox pod. Each declares its
+model as a role the operator maps (`docs/kubernetes.md`, "Model roles"). The skills those agents and the
+role prompts load (the pair's rubrics, the implementer's `ce-simplify-code`) ship in
+`dist/skills` with the rest. The Go daemon's boot gate and `legion probe-image` resolve every
+`task(agent="…")` and every `skill://<name>` those prompts name through the same launch, and
+refuse by name an agent or a skill Oh My Pi cannot find.
 `resources_discover` additionally serves the same directory as a secondary, extension-owned
 discovery path. The published manifest exposes `dist/envoy.js` and `dist/legion.js` for
 `omp.extensions` (only `omp.skills` ships as committed, since `dist/skills` is its path in both

package/agents/deep-worker.md

@@ -0,0 +1,64 @@
+---
+name: deep-worker
+description: |
+  Autonomous coding worker. Give it a goal, the workspace and files in scope, the skills to
+  follow, and the checks that must pass; it makes the change, runs the checks, and reports exactly
+  what it changed. It never commits, pushes, or writes to GitHub.
+# @deep is the deployment's `deep` model role; the Go daemon's boot gate refuses to start unless the operator's settings give
+# this agent a model, through modelRoles.deep or a task.agentModelOverrides entry for it (docs/kubernetes.md, Operator configuration).
+model: ["@deep"]
+tools: read, glob, grep, bash, edit, write
+# The implementer waits for each worker's result before it checks or commits it; without this, Oh My
+# Pi runs a task agent in the background whenever async jobs are enabled.
+blocking: true
+---
+
+You are an autonomous coding worker. You are given a goal, not steps: decide how to reach it, then
+reach it.
+
+## Your assignment
+
+Your assignment names four things:
+
+- **The goal:** the behavior the change must produce.
+- **The workspace and the files in scope:** the directory you work in and what you may change.
+- **The skills to follow:** read each one before you change anything. A skill's definition of
+  "done" or "tested" wins over your own, never over the constraints below.
+- **The done-criteria:** the checks that must pass, as exact commands.
+
+If one is missing, or the goal cannot be reached inside the scope you were given, stop and report
+what is missing. Do not guess, and do not widen the scope yourself.
+
+## How you work
+
+- Before you write anything, read the code that already does the nearest thing: the callers of
+  what you will touch, the helper that may already exist, the test that exercises the path. Follow
+  the conventions you find there.
+- Work only in the workspace your assignment names, with absolute paths rooted there; a relative
+  path resolves against your caller's directory, not the workspace. Start every shell command with
+  `cd` into it.
+- Change only the files in scope, and leave every other file as you found it: delete, move, or
+  rewrite nothing outside that scope, generated files included. A change you need outside it is
+  something to report, not an edit to make.
+- Run the named checks yourself and keep working until they pass. Never weaken, skip, or delete a
+  test to make a check pass; a test you believe is wrong is something to report.
+
+## Constraints
+
+- You create no commits and move no bookmark or branch: no `jj commit`, `jj describe`, `jj new`,
+  `jj split`, `jj squash`, `git commit`, or anything that rewrites history. Leave your edits in the
+  working copy. The commits are your caller's.
+- You push nothing, anywhere.
+- You make no GitHub write of any kind: no pull request, review, comment, label, or status, through
+  `gh` or any other route.
+
+## Done
+
+You are done when every named check passes on your final edits, and you ran each one. Report:
+
+- every file you changed, and what you changed in it;
+- every check you ran: its exact command and its result, pasted rather than paraphrased;
+- anything you could not do, any departure from the assignment, and anything you are unsure of.
+
+Report only what you did and observed. Your caller does not take your word for it: it re-runs the
+checks and reads the diff.

package/dist/envoy.js

@@ -29654,6 +29654,8 @@ function serviceSubjectLabel(subject) {
   }
   return subject;
 }
+var MAX_ISSUE_PAGE_LIMIT = 250;
+var DEFAULT_ISSUE_PAGE_LIMIT = 50;
 var ASK_TURNS = ["human", "agent"];
 var DELIVERY_CAPABILITIES = ["aside", "btw", "steer"];
 var DELIVERY_DUPLICATE_WINDOW_MS = 72 * 60 * 60 * 1000;
@@ -30398,7 +30400,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_issues",
     example: { project: "AGENTC", limit: 250, offset: 250 },
-    description: "List a project's issues for a roadmap or backlog pass: every issue in one project, each carrying " + "its status, priority, parent, labels, open-ask count, and route with whether it reaches anyone, " + "so you can see backlog shape without opening every issue. Optionally filter by status, parent, " + "label, priority, route status, or how recently it changed; priority takes one or more of 0-3 " + "(P0-P3) and null for an issue with no priority, so an owner's P0/P1 audit is priority [0, 1]. " + 'route_status "no_holder" lists every open issue whose route names a role nobody holds or a ' + "session that is not running at the moment of the read, whatever its priority. A restarting " + "session is absent for minutes, so an issue is unowned only when a read ten minutes later agrees. " + "Do not use it to search by keyword or phrase; dispatch_search remains the keyword surface. " + "Rows are paged after the server returns the full response: limit sets the page size (default 50, " + "max 250) and offset selects where it starts (default 0), so repeat with the next offset to " + "enumerate every matching issue.",
+    description: "List a project's issues for a roadmap or backlog pass: every issue in one project, each carrying " + "its status, priority, parent, labels, open-ask count, and route with whether it reaches anyone, " + "so you can see backlog shape without opening every issue. Optionally filter by status, parent, " + "label, priority, route status, or how recently it changed; priority takes one or more of 0-3 " + "(P0-P3) and null for an issue with no priority, so an owner's P0/P1 audit is priority [0, 1]. " + 'route_status "no_holder" lists every open issue whose route names a role nobody holds or a ' + "session that is not running at the moment of the read, whatever its priority. A restarting " + "session is absent for minutes, so an issue is unowned only when a read ten minutes later agrees. " + "Do not use it to search by keyword or phrase; dispatch_search remains the keyword surface. " + "Dispatch pages the list: limit sets the page size (default " + `${DEFAULT_ISSUE_PAGE_LIMIT}, max ${MAX_ISSUE_PAGE_LIMIT}) and offset selects where it starts ` + "(default 0), and the answer names how many issues match, so repeat with the next offset to " + "walk every matching issue. A walk is exact only while the list does not change: an issue " + "that enters or leaves what the filters match, or whose status or rank changes, between two " + "pages shifts rows across a page boundary, so one issue can come back twice and another never.",
     arguments: (z2) => ({
       project: z2.string().describe("Project key to list issues from."),
       status: z2.enum(ISSUE_STATUSES).describe("Optional lifecycle status filter.").optional(),
@@ -30407,7 +30409,7 @@ var dispatchToolSpecs = [
       priority: z2.array(z2.number({ int: true, min: 0, max: 3 }).nullable(), { min: 1, max: 5 }).describe("Optional priority filter: one or more of 0 (P0, highest) through 3 (P3, lowest), and null " + "for an issue with no priority; an issue matching any listed value is returned.").optional(),
       updated_since: z2.string().describe("Optional RFC3339 timestamp; only issues updated at or after it.").optional(),
       route_status: z2.enum(ISSUE_ROUTE_STATUSES).describe("Optional: only open issues whose route is in this state. live: a running session holds " + "the role or is the routed session. no_holder: nobody running holds the role, or the " + "session is not running, right now. unknown: the Envoy listener did not answer.").optional(),
-      limit: z2.number({ int: true, min: 1, max: 250 }).describe("Maximum rows, 1-250; default 50.").optional(),
+      limit: z2.number({ int: true, min: 1, max: MAX_ISSUE_PAGE_LIMIT }).describe(`Maximum rows, 1-${MAX_ISSUE_PAGE_LIMIT}; default ${DEFAULT_ISSUE_PAGE_LIMIT}.`).optional(),
       offset: z2.number({ int: true, min: 0 }).describe("Rows to skip before the page; nonnegative integer; default 0.").optional()
     })
   },
@@ -32351,8 +32353,26 @@ class DispatchClient {
   async resolveIssue(issueReference) {
     return this.#resolveIssue(issueReference);
   }
-  async listIssues(options = {}) {
-    return this.#json("GET", ["api", "v1", "issues"], undefined, options);
+  async listIssuePage(options, page) {
+    const answer = await this.#json("GET", ["api", "v1", "issues"], undefined, {
+      ...options,
+      limit: page.limit,
+      offset: page.offset
+    });
+    if (Array.isArray(answer)) {
+      const issues = answer;
+      return {
+        issues: issues.slice(page.offset, page.offset + page.limit),
+        total: issues.length,
+        limit: page.limit,
+        offset: page.offset
+      };
+    }
+    const served = answer;
+    if (typeof served !== "object" || served === null || !Array.isArray(served.issues) || typeof served.total !== "number" || typeof served.limit !== "number" || typeof served.offset !== "number") {
+      throw new Error("GET /api/v1/issues answered neither a page ({issues, total, limit, offset}) nor an array of issues");
+    }
+    return served;
   }
   async listProjectArtifacts(project, unlinked = false) {
     return this.#json("GET", ["api", "v1", "projects", project, "artifacts"], undefined, unlinked ? { unlinked: "true" } : undefined);
@@ -34002,9 +34022,7 @@ async function executeDispatchTool(input) {
       const priority = optionalPriorityFilter(args, "priority");
       const updatedSince = optionalString(args, "updated_since");
       const routeStatus = optionalString(args, "route_status");
-      const limit = Math.min(Math.max(optionalNumber(args, "limit") ?? 50, 1), 250);
-      const offset = Math.max(optionalNumber(args, "offset") ?? 0, 0);
-      const issues = await client.listIssues({
+      const page = await client.listIssuePage({
         project,
         ...status === undefined ? {} : { status },
         ...parent === undefined ? {} : { parent },
@@ -34012,9 +34030,12 @@ async function executeDispatchTool(input) {
         ...priority === undefined ? {} : { priority },
         ...updatedSince === undefined ? {} : { updated_since: updatedSince },
         ...routeStatus === undefined ? {} : { route_status: routeStatus }
+      }, {
+        limit: optionalNumber(args, "limit") ?? DEFAULT_ISSUE_PAGE_LIMIT,
+        offset: optionalNumber(args, "offset") ?? 0
       });
-      const total = issues.length;
-      const rows = issues.slice(offset, offset + limit).map((row) => ({
+      const { total, limit, offset } = page;
+      const rows = page.issues.map((row) => ({
         key: row.key,
         title: row.title,
         status: row.status,

package/dist/legion.js

@@ -29823,6 +29823,8 @@ function serviceSubjectLabel(subject) {
   }
   return subject;
 }
+var MAX_ISSUE_PAGE_LIMIT = 250;
+var DEFAULT_ISSUE_PAGE_LIMIT = 50;
 var ASK_TURNS = ["human", "agent"];
 var DELIVERY_CAPABILITIES = ["aside", "btw", "steer"];
 var DELIVERY_DUPLICATE_WINDOW_MS = 72 * 60 * 60 * 1000;
@@ -30567,7 +30569,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_issues",
     example: { project: "AGENTC", limit: 250, offset: 250 },
-    description: "List a project's issues for a roadmap or backlog pass: every issue in one project, each carrying " + "its status, priority, parent, labels, open-ask count, and route with whether it reaches anyone, " + "so you can see backlog shape without opening every issue. Optionally filter by status, parent, " + "label, priority, route status, or how recently it changed; priority takes one or more of 0-3 " + "(P0-P3) and null for an issue with no priority, so an owner's P0/P1 audit is priority [0, 1]. " + 'route_status "no_holder" lists every open issue whose route names a role nobody holds or a ' + "session that is not running at the moment of the read, whatever its priority. A restarting " + "session is absent for minutes, so an issue is unowned only when a read ten minutes later agrees. " + "Do not use it to search by keyword or phrase; dispatch_search remains the keyword surface. " + "Rows are paged after the server returns the full response: limit sets the page size (default 50, " + "max 250) and offset selects where it starts (default 0), so repeat with the next offset to " + "enumerate every matching issue.",
+    description: "List a project's issues for a roadmap or backlog pass: every issue in one project, each carrying " + "its status, priority, parent, labels, open-ask count, and route with whether it reaches anyone, " + "so you can see backlog shape without opening every issue. Optionally filter by status, parent, " + "label, priority, route status, or how recently it changed; priority takes one or more of 0-3 " + "(P0-P3) and null for an issue with no priority, so an owner's P0/P1 audit is priority [0, 1]. " + 'route_status "no_holder" lists every open issue whose route names a role nobody holds or a ' + "session that is not running at the moment of the read, whatever its priority. A restarting " + "session is absent for minutes, so an issue is unowned only when a read ten minutes later agrees. " + "Do not use it to search by keyword or phrase; dispatch_search remains the keyword surface. " + "Dispatch pages the list: limit sets the page size (default " + `${DEFAULT_ISSUE_PAGE_LIMIT}, max ${MAX_ISSUE_PAGE_LIMIT}) and offset selects where it starts ` + "(default 0), and the answer names how many issues match, so repeat with the next offset to " + "walk every matching issue. A walk is exact only while the list does not change: an issue " + "that enters or leaves what the filters match, or whose status or rank changes, between two " + "pages shifts rows across a page boundary, so one issue can come back twice and another never.",
     arguments: (z2) => ({
       project: z2.string().describe("Project key to list issues from."),
       status: z2.enum(ISSUE_STATUSES).describe("Optional lifecycle status filter.").optional(),
@@ -30576,7 +30578,7 @@ var dispatchToolSpecs = [
       priority: z2.array(z2.number({ int: true, min: 0, max: 3 }).nullable(), { min: 1, max: 5 }).describe("Optional priority filter: one or more of 0 (P0, highest) through 3 (P3, lowest), and null " + "for an issue with no priority; an issue matching any listed value is returned.").optional(),
       updated_since: z2.string().describe("Optional RFC3339 timestamp; only issues updated at or after it.").optional(),
       route_status: z2.enum(ISSUE_ROUTE_STATUSES).describe("Optional: only open issues whose route is in this state. live: a running session holds " + "the role or is the routed session. no_holder: nobody running holds the role, or the " + "session is not running, right now. unknown: the Envoy listener did not answer.").optional(),
-      limit: z2.number({ int: true, min: 1, max: 250 }).describe("Maximum rows, 1-250; default 50.").optional(),
+      limit: z2.number({ int: true, min: 1, max: MAX_ISSUE_PAGE_LIMIT }).describe(`Maximum rows, 1-${MAX_ISSUE_PAGE_LIMIT}; default ${DEFAULT_ISSUE_PAGE_LIMIT}.`).optional(),
       offset: z2.number({ int: true, min: 0 }).describe("Rows to skip before the page; nonnegative integer; default 0.").optional()
     })
   },
@@ -31267,8 +31269,26 @@ class DispatchClient {
   async resolveIssue(issueReference) {
     return this.#resolveIssue(issueReference);
   }
-  async listIssues(options = {}) {
-    return this.#json("GET", ["api", "v1", "issues"], undefined, options);
+  async listIssuePage(options, page) {
+    const answer = await this.#json("GET", ["api", "v1", "issues"], undefined, {
+      ...options,
+      limit: page.limit,
+      offset: page.offset
+    });
+    if (Array.isArray(answer)) {
+      const issues = answer;
+      return {
+        issues: issues.slice(page.offset, page.offset + page.limit),
+        total: issues.length,
+        limit: page.limit,
+        offset: page.offset
+      };
+    }
+    const served = answer;
+    if (typeof served !== "object" || served === null || !Array.isArray(served.issues) || typeof served.total !== "number" || typeof served.limit !== "number" || typeof served.offset !== "number") {
+      throw new Error("GET /api/v1/issues answered neither a page ({issues, total, limit, offset}) nor an array of issues");
+    }
+    return served;
   }
   async listProjectArtifacts(project, unlinked = false) {
     return this.#json("GET", ["api", "v1", "projects", project, "artifacts"], undefined, unlinked ? { unlinked: "true" } : undefined);
@@ -32941,9 +32961,7 @@ async function executeDispatchTool(input) {
       const priority = optionalPriorityFilter(args, "priority");
       const updatedSince = optionalString(args, "updated_since");
       const routeStatus = optionalString(args, "route_status");
-      const limit = Math.min(Math.max(optionalNumber(args, "limit") ?? 50, 1), 250);
-      const offset = Math.max(optionalNumber(args, "offset") ?? 0, 0);
-      const issues = await client.listIssues({
+      const page = await client.listIssuePage({
         project,
         ...status === undefined ? {} : { status },
         ...parent === undefined ? {} : { parent },
@@ -32951,9 +32969,12 @@ async function executeDispatchTool(input) {
         ...priority === undefined ? {} : { priority },
         ...updatedSince === undefined ? {} : { updated_since: updatedSince },
         ...routeStatus === undefined ? {} : { route_status: routeStatus }
+      }, {
+        limit: optionalNumber(args, "limit") ?? DEFAULT_ISSUE_PAGE_LIMIT,
+        offset: optionalNumber(args, "offset") ?? 0
       });
-      const total = issues.length;
-      const rows = issues.slice(offset, offset + limit).map((row) => ({
+      const { total, limit, offset } = page;
+      const rows = page.issues.map((row) => ({
         key: row.key,
         title: row.title,
         status: row.status,
@@ -33502,7 +33523,7 @@ import { logger } from "@oh-my-pi/pi-utils";
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion-envoy",
-  version: "5.23.0",
+  version: "5.24.0",
   type: "module",
   omp: {
     extensions: [

package/dist/skills/dispatch/references/api.md

@@ -26,3 +26,14 @@ A path Dispatch does not serve under `/api` or `/v1` answers
 route"}`; when you see that, you typed the path wrong — read the index rather than guessing. Every
 `/api/v1` error body carries a `code`; branch on the code, never on the text.
 
+`GET /api/v1/issues` answers every matching issue as an array, or one page when you name `limit`
+(1–250) or `offset` (alone it pages 50): `{issues, total, limit, offset}`, where `total` counts
+every issue your filters match. Walking the pages with the next `offset` is exact only while the
+listing does not change: an issue that enters or leaves what the filters match, or whose status or
+rank changes, between two reads shifts rows across a page boundary, and one issue comes back twice
+and another never, even when you stop at `total`. The unpaged array is the only exact set one read
+gives. `cursor` is `400 INVALID_QUERY`. `dispatch_issues` pages for you.
+The event logs page with `after` or `before` and `limit`, and `GET /api/v1/search` takes a `limit`
+of at most 50 and has no next page. Every other route answers without paging and ignores a paging
+parameter.
+

package/dist/skills/dispatch/references/issues.md

@@ -144,8 +144,11 @@ when it last changed — a roadmap or backlog pass without opening every issue.
 (a lifecycle status), `parent` (one issue's children), `label`, `priority` (a list of `0`–`3`, with
 `null` for an issue with no priority: `[0, 1]` is every P0 and P1), `route_status` (below), or
 `updated_since` (an RFC3339 timestamp, for "what moved this week"). `limit` is the page size, 50 by
-default and 250 at most, and `offset` is where the page starts: repeat with the next offset until a
-page comes back short to list every matching issue.
+default and 250 at most, and `offset` is where the page starts; the answer says how many issues
+match. Repeating with the next offset walks every matching issue only while the list does not
+change: an issue that enters or leaves what your filters match, or whose status or rank changes,
+between two pages shifts rows across a page boundary, and the walk then shows one issue twice and
+misses another.
 
 This is not search: it matches no text. Use `dispatch_search` for a keyword or phrase, and
 `dispatch_issues` when you want every issue in a project and its current state.

package/dist/skills/legion-worker/SKILL.md

@@ -59,7 +59,7 @@ only on this phase's artifact.
 
 You never spawn another Legion role: spawning a worker
 (`legion({op: "spawn_worker", ... })`) is architect-only. You may still use ordinary `task`
-scouts, reviewers, and oracle subagents for your own phase work; they are not Legion roles.
+subagents for your own phase work; none of them is a Legion role.
 Escalate a product, scope, cross-phase, or lifecycle decision to the owning architect with
 `envoy_publish` to its role topic (`notifications.role.` followed by its encoded token, see
 above), carrying the verified facts and the decision needed. `hub` only reaches subagents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "5.23.0",
+  "version": "5.24.0",
   "type": "module",
   "omp": {
     "extensions": [