@sjawhar/opencode-legion-envoy 5.5.2 → 5.6.1

package/dist/src/server.js

@@ -13962,6 +13962,7 @@ var ASK_URGENCIES = ["low", "med", "high", "blocking"];
 var ASK_QUESTION_MAX = 800;
 var SEARCH_QUERY_MAX = 1000;
 var SEARCH_QUERY_HINT = "search with a short phrase of a few words, not a passage";
+var SEARCH_KIND_DEPTH = 100;
 var PROJECT_KEY_PATTERN = /^[A-Z][A-Z0-9]{1,9}$/;
 var ISSUE_STATUSES = [
   "triage",
@@ -14297,7 +14298,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_search",
     example: { query: "astrolabe" },
-    description: "Search every issue, document, comment, ask, and message for a keyword or phrase and get deep links. " + "Use it before creating an issue or a design document, and to find where a word was written. " + 'Websearch syntax: "quoted phrase", -excluded, OR.',
+    description: "Search every issue, document, comment, ask, and message for a keyword or phrase and get deep links. " + "Use it before creating an issue or a design document, and to find where a word was written. " + 'Websearch syntax: "quoted phrase", -excluded, OR. ' + "Each kind of content is ranked on its own and the lists are merged, so the top holds the best " + "issue, document, ask, comment and message; an issue key searched alone lists that issue first. " + `The answer names how many results match; offset pages through them, and each kind lists at most its best ${SEARCH_KIND_DEPTH}, ` + "so narrow the query or name a project to reach the rest. Paging is exact only while the " + "corpus holds still: content added, changed, or removed between two offsets can shift rows " + "across a page boundary, so one hit can come back twice and another never.",
     arguments: (z2) => ({
       query: z2.string({
         min: 2,
@@ -14305,7 +14306,8 @@ var dispatchToolSpecs = [
         maxHint: SEARCH_QUERY_HINT
       }).describe(`Keyword, phrase, or websearch expression; 2 to ${SEARCH_QUERY_MAX} characters.`),
       project: z2.string().describe("Optional project key to search within.").optional(),
-      limit: z2.number({ int: true, min: 1, max: 50 }).describe("Maximum results, 1-50; default 20.").optional()
+      limit: z2.number({ int: true, min: 1, max: 50 }).describe("Maximum results, 1-50; default 20.").optional(),
+      offset: z2.number({ int: true, min: 0 }).describe("Results to skip before the page; nonnegative integer; default 0.").optional()
     }),
     validation: {
       check: (value) => {
@@ -15206,6 +15208,71 @@ function dispatchChildRef(ownerRef, kind, id) {
   return `${ownerRef}/${kind}/${id}`;
 }
 
+// ../envoy-client/src/search-answer.ts
+function pageSummaryText(offset, count, total) {
+  return `showing ${offset + 1}-${offset + count} of ${total}`;
+}
+function searchResultLine(result, baseUrl) {
+  const href = new URL(result.href, baseUrl).toString();
+  const { owner } = result;
+  if (owner.kind === "document") {
+    const reference = dispatchDocumentRef(owner.project, owner.slug);
+    return `${reference} [document] ${owner.name} - ${result.kind}: ${snippetText(result.snippet)} -> ${href}`;
+  }
+  const artifactName = result.artifact ? ` ${result.artifact.name}` : "";
+  const label = `${owner.key} [${owner.status}] ${owner.title} - ${result.kind}${artifactName}`;
+  return `${label}: ${snippetText(result.snippet)} -> ${href}`;
+}
+function searchAnswer(search, query, offset, configUrl) {
+  const results = search.results;
+  const count = results.length;
+  const lines = results.map((result) => searchResultLine(result, configUrl));
+  const noun = count === 1 ? "result" : "results";
+  const noResults = `No results for "${query}".`;
+  if (typeof search.total !== "number") {
+    if (offset !== undefined && offset > 0) {
+      throw new Error(`Dispatch answered without a total: it predates search paging and ignored offset ${offset}, so this would be its first page again.`);
+    }
+    return {
+      text: count === 0 ? noResults : [`${count} ${noun} for "${query}" (${search.took_ms} ms)`, ...lines].join(`
+`),
+      details: { query, results }
+    };
+  }
+  const { total, reachable, offset: pageOffset } = search;
+  const end = pageOffset + count;
+  const cut = reachable < total ? `Each kind lists only its best ${SEARCH_KIND_DEPTH} matches, so ${reachable} of the ${total} can be paged to; narrow the query or name a project to reach the rest.` : undefined;
+  const details = {
+    query,
+    results,
+    total,
+    reachable,
+    offset: pageOffset,
+    limit: search.limit
+  };
+  if (count === 0) {
+    return {
+      text: total === 0 ? noResults : [
+        `No results for "${query}" at offset ${pageOffset}: it matches ${total}, and the pages reach the first ${reachable}.`,
+        ...cut === undefined ? [] : [cut]
+      ].join(`
+`),
+      details
+    };
+  }
+  const showing = pageOffset === 0 && count === total ? "" : `${pageSummaryText(pageOffset, count, total)}, `;
+  return {
+    text: [
+      `${count} ${noun} for "${query}" (${showing}${search.took_ms} ms)`,
+      ...cut === undefined ? [] : [cut],
+      ...lines,
+      ...end < reachable ? [`Next page: offset ${end}.`] : []
+    ].join(`
+`),
+    details
+  };
+}
+
 // ../envoy-client/src/tool-input-errors.ts
 class ToolInputError extends Error {
   tool;
@@ -15515,17 +15582,6 @@ function duplicateCandidates(error48) {
     throw error48;
   return error48.candidates;
 }
-function searchResultLine(result, baseUrl) {
-  const href = new URL(result.href, baseUrl).toString();
-  const { owner } = result;
-  if (owner.kind === "document") {
-    const reference = dispatchDocumentRef(owner.project, owner.slug);
-    return `${reference} [document] ${owner.name} - ${result.kind}: ${snippetText(result.snippet)} -> ${href}`;
-  }
-  const artifactName = result.artifact ? ` ${result.artifact.name}` : "";
-  const label = `${owner.key} [${owner.status}] ${owner.title} - ${result.kind}${artifactName}`;
-  return `${label}: ${snippetText(result.snippet)} -> ${href}`;
-}
 function askUrgency(args) {
   const value = args.urgency;
   return ASK_URGENCIES.find((urgency) => urgency === value);
@@ -16721,20 +16777,13 @@ async function executeDispatchTool(input) {
       const query = stringArg(args, "query");
       const project = optionalString(args, "project");
       const limit = optionalNumber(args, "limit");
+      const offset = optionalNumber(args, "offset");
       const search = await client.search(query, {
         ...project === undefined ? {} : { project },
-        ...limit === undefined ? {} : { limit }
+        ...limit === undefined ? {} : { limit },
+        ...offset === undefined ? {} : { offset }
       });
-      const results = search.results;
-      const count = results.length;
-      return {
-        text: count === 0 ? `No results for "${query}".` : [
-          `${count} ${count === 1 ? "result" : "results"} for "${query}" (${search.took_ms} ms)`,
-          ...results.map((result) => searchResultLine(result, configUrl))
-        ].join(`
-`),
-        details: { query, results }
-      };
+      return searchAnswer(search, query, offset, configUrl);
     }
     case "dispatch_issues": {
       const project = stringArg(args, "project");
@@ -16774,7 +16823,7 @@ async function executeDispatchTool(input) {
       }));
       const titles = await liveSessionTitles(client, rows.some((row) => holdsSession(row.claim)));
       const isPartial = offset !== 0 || rows.length !== total;
-      const showing = !isPartial ? "" : rows.length === 0 ? `showing 0-0 of ${total}` : `showing ${offset + 1}-${offset + rows.length} of ${total}`;
+      const showing = !isPartial ? "" : rows.length === 0 ? `showing 0-0 of ${total}` : pageSummaryText(offset, rows.length, total);
       return {
         text: rows.length === 0 ? `No issues in ${project}.${isPartial ? ` (${showing})` : ""}` : [
           `${rows.length} ${rows.length === 1 ? "issue" : "issues"} in ${project}` + (isPartial ? ` (${showing})` : ""),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "5.5.2",
+  "version": "5.6.1",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/src/server.js",

package/skills/dispatch/SKILL.md

@@ -160,15 +160,14 @@ follow [Writing a spec](#writing-a-spec).
 you plan, start a design document, file an issue, ask, post a finding or start work, and what to
 do with each hit. What it leaves out:
 ```ts
-dispatch_search({ query, project?, limit? })
+dispatch_search({ query, project?, limit?, offset? })
 ```
-Websearch syntax applies: `"merge queue"`, `-daemon`, `OR`. It returns the best `limit` hits (20
-by default, 50 at most) across issues, documents, comments, asks, and messages. A query over
-1,000 characters is refused before it is sent: search with the few words `skill://dispatch-first`
-describes, never a pasted passage. Issue-owned hit lines start with the issue key; standalone
-project-document hit lines start with `dispatch://PROJECT/artifact/<slug>`, followed by the
-absolute link. Cite the hit you build on (`dispatch://KEY` or the document reference), or state
-"no prior issue" in the spec.
+Websearch syntax applies: `"merge queue"`, `-daemon`, `OR`. Issues, documents, asks, comments, and messages rank separately; the
+merged page orders each kind's best in turn — issue, document, ask, comment, message — and a bare issue key ranks first. A page
+holds `limit` hits (20 default, 50 max); the first line gives the total (`showing 1-20 of 312`); see
+[Search paging](skill://dispatch/references/issues.md#search-paging) for more. Queries over 1,000 characters are refused: use the
+few words `skill://dispatch-first` names, never a pasted passage. Issue hits start with the issue key; document hits start with
+`dispatch://PROJECT/artifact/<slug>`, then the link. Cite the hit (`dispatch://KEY` or the doc ref) or say "no prior issue".
 
 `dispatch_issue` refuses a title that near-duplicates an issue in the same project and returns the candidates (`POSSIBLE_DUPLICATE`).
 Read them; reference the existing issue, or repeat the call with `force: true` when it is genuinely new work.

package/skills/dispatch/references/issues.md

@@ -193,6 +193,16 @@ The audit finds four shapes:
 Run the audit as a step of a coordinator's loop, at each checkpoint, not as a habit: these shapes
 are found by running the check, not by noticing them.
 
+## Search paging
+
+`skill://dispatch` sends you here when a `dispatch_search` page is not enough: more hits remain,
+or a kind runs out before the page does.
+
+A page holds `limit` hits (20 by default, 50 at most); the first line names how many match
+(`showing 1-20 of 312`), and, while more can be reached, the last line names the next `offset`.
+Each kind lists at most its best 100, so when the result says the rest cannot be paged to, narrow
+the query or name a `project`.
+
 ## Syncing a project's architecture model
 
 Import a project's architecture model from its configured source repository now (a human configures the source in Settings):

package/skills/dispatch/references/messages.md

@@ -25,11 +25,11 @@ reply. A human may reply to your message in turn — the follow-up arrives as a
 `in_reply_to` names your message and whose `reply_body` quotes it; answer it the same way,
 `dispatch_message({ issue, in_reply_to: "<their reply id>", body })`, so the exchange reads as one
 thread. `dispatch_message` itself never carries `target` or `delivery`: agent-to-agent traffic goes
-through Envoy or the hub. A bearer that targets over HTTP names its own session in `actor`
-(`{kind: "session", id}`), and the card shows that session as the author. `GET /api/v1/agents`
-(any authenticated caller) lists live sessions with their capabilities (`aside`, `btw`, `steer`);
-target only a session that advertises the mode you want. Sending to a session with no issue
-(`POST /api/v1/agents/{session_id}/messages`) stays human-only.
+through Envoy or Oh My Pi's `agent://` messages. A bearer that targets over HTTP names its own
+session in `actor` (`{kind: "session", id}`), and the card shows that session as the author.
+`GET /api/v1/agents` (any authenticated caller) lists live sessions with their capabilities
+(`aside`, `btw`, `steer`); target only a session that advertises the mode you want. Sending to a
+session with no issue (`POST /api/v1/agents/{session_id}/messages`) stays human-only.
 
 ## Answering a direct message
 

package/skills/envoy/SKILL.md

@@ -122,8 +122,9 @@ envoy_send(
 
 `envoy_whoami`'s `session_id` is the address a reply to you reaches. Inside a `task` subagent it
 is the session that spawned you: a subagent registers no Envoy session of its own, so a peer
-answering it reaches that session, which relays to you over hub. The `subagent` field in that
-output carries your own host session id — it is not an address, so never hand it to a peer.
+answering it reaches that session, which relays to you with a `write` to your `agent://` address.
+The `subagent` field in that output carries your own host session id — it is not an address, so
+never hand it to a peer.
 
 `session_id` is empty when nothing can be reached: a process that took no Envoy identity, or a
 subagent whose spawning session this process can no longer place (it forked away, and other
@@ -134,8 +135,8 @@ would send your peers to an agent that never spawned you.
 Your own `envoy_publish` never reaches the agent that spawned you. The listener delivers nothing
 to the session a message names as its source, and inside a subagent that source is your parent,
 so a publish to a role it holds — or to any topic it subscribes to — is accepted and delivered to
-nobody. Use hub for that one hop. `envoy_send` to any other session, including a reply, is
-unaffected.
+nobody. Use a `write` to its `agent://` address for that one hop. `envoy_send` to any other
+session, including a reply, is unaffected.
 
 ### Delivery capabilities
 

package/skills/legion-worker/SKILL.md

@@ -62,11 +62,11 @@ workflow table. You may still use ordinary `task` subagents for your own phase w
 is a Legion role.
 Escalate a product, scope, design, 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
-inside your own process, not the architect's separate one. Never write a decision block into a
-spec yourself: the architect decides whether the human must answer it and writes the block, since
-a new version of an approved root spec closes the tree's design gate. A standalone to-do only a
-human can do is a `dispatch_ask`, and its replies return to your own session.
+above), carrying the verified facts and the decision needed. A `write` to `agent://` only reaches
+agents inside your own process, not the architect's separate one. Never write a decision block
+into a spec yourself: the architect decides whether the human must answer it and writes the block,
+since a new version of an approved root spec closes the tree's design gate. A standalone to-do
+only a human can do is a `dispatch_ask`, and its replies return to your own session.
 
 Because the same agent is always resumed for its phase, you may receive more than one
 assignment across your lifetime: once the daemon ends your phase it suspends you, and when a later
@@ -152,9 +152,10 @@ new work.
 clone, so they all share one operation log: `jj undo`, `jj abandon`, and
 `jj op restore|revert|abandon|undo` rewrite it for every tree at once. The extension refuses them in every
 phase-worker pane before they run — a `bash` command in any position of a pipeline or `&&`
-chain, with or without `-R`, judged on the whole argument list; `eval` code; and a `hub`
-process start — from your own tool calls and from any `task` subagent you spawn (it runs in
-your pane, against the same log), and a `bash` command whose quoted text merely mentions `jj`
+chain, with or without `-R`, judged on the whole argument list (a supervised service's start
+included); `eval` code; and stdin written to a service (a `write` to `proc://<id>`) — from your
+own tool calls and from any `task` subagent you spawn (it runs in your pane, against the same
+log), and a `bash` command whose quoted text merely mentions `jj`
 with one of those words (a heredoc, an echo, a commit message) is refused too: write such text
 with the `write` tool or say "operation-log rollback" instead. `jj restore <paths>`,
 `jj op log`, and `jj op show` stay allowed. Recover forward only: a new commit