@sjawhar/opencode-legion-envoy 3.19.4 → 3.19.6

package/dist/src/server.js

@@ -14252,7 +14252,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_read",
     example: { issue: "DSP-1" },
-    description: "Read an issue or project-document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch_doc_read instead. Supply ref, issue, " + "or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + OWNER_REFERENCE,
+    description: "Read an issue or project-document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch_doc_read instead. Supply ref, issue, " + "or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair) or `INTERNAL`. " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + OWNER_REFERENCE,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
@@ -16569,6 +16569,7 @@ function askSummary({ ask, replies }, graph) {
   ]);
   return [
     `Question: ${ask.question}`,
+    ...anchorLines(ask),
     "Options:",
     ...ask.options.length === 0 ? ["- none"] : ask.options.map((option) => `- ${option.label}${option.description ? ` \u2014 ${option.description}` : ""}`),
     `State: ${ask.state}`,
@@ -16632,12 +16633,12 @@ function formatOpenAsksSummary(response, baseUrl) {
 function commentSummary({ comment, replies }, graph) {
   const root = [
     `${comment.id} \xB7 ${actorText(comment.author)}`,
-    ...comment.anchor?.quote === undefined ? [] : [`> ${comment.anchor.quote}`],
+    ...anchorLines(comment),
     `Body: ${comment.body}`
   ];
   const chain = replies.flatMap((reply) => [
     `${reply.id} \xB7 ${actorText(reply.author)}`,
-    ...reply.anchor?.quote === undefined ? [] : [`> ${reply.anchor.quote}`],
+    ...anchorLines(reply),
     `Body: ${reply.body}`
   ]);
   return [
@@ -16649,6 +16650,28 @@ function commentSummary({ comment, replies }, graph) {
   ].join(`
 `);
 }
+function anchorLines(record2) {
+  return [
+    ...record2.anchor?.quote === undefined ? [] : [`> ${record2.anchor.quote}`],
+    ...record2.anchor_block === undefined ? [] : [`Position: ${positionText(record2.anchor_block)}`],
+    ...record2.anchor_block_error === undefined ? [] : [`Position: unavailable (${record2.anchor_block_error})`]
+  ];
+}
+function positionText(block) {
+  const { table, path: path2 } = block;
+  const segments = path2.map((entry) => `${entry.type}[${entry.index}]`);
+  if (table === undefined || table.row === null)
+    return segments.join(" \u203A ");
+  const tableAt = path2.findIndex((entry) => entry.type === "table");
+  const cells = table.cells ?? [];
+  const label = (table.column === null ? cells : cells.slice(0, table.column)).map((cell) => cell.trim()).filter((cell) => cell !== "" && !/^\d+$/.test(cell)).join(" \xB7 ");
+  const row = label === "" ? `row ${table.row}` : `row ${table.row} (${label})`;
+  const header = table.header === null || table.header === "" ? String(table.column) : table.header;
+  return [
+    ...segments.slice(0, tableAt + 1),
+    table.column === null ? row : `${row}, column ${header}`
+  ].join(" \u203A ");
+}
 function messageSummary({ message, replies }, graph) {
   const root = [`${message.id} \xB7 ${actorText(message.author)}`, `Body: ${message.body}`];
   const chain = replies.flatMap((reply) => [
@@ -16759,17 +16782,19 @@ async function refuseRemovingOpenDecisionBlocks(client, tool, resolved, ops) {
   ].join(`
 `));
 }
-function refusalWithCode(error48, suffix = "") {
+function refusalWithCode(error48, ...clauses) {
+  const suffix = clauses.filter((clause) => clause !== "").join("; ");
+  const joined = suffix === "" ? "" : `; ${suffix}`;
   if (error48 instanceof DispatchGatewayError) {
     let told = error48.message;
-    if (suffix !== "") {
-      told = error48.mayHaveReachedDispatch ? `${error48.answer}${suffix}` : `${error48.answer}, so ${error48.advice}${suffix}`;
+    if (joined !== "") {
+      told = error48.mayHaveReachedDispatch ? `${error48.answer}${joined}` : `${error48.answer}, so ${error48.advice}${joined}`;
     }
     return new DispatchGatewayError(error48.status, error48.answer, error48.advice, `${error48.code}: ${told}`);
   }
   if (!(error48 instanceof DispatchServiceError))
     return error48;
-  return new DispatchServiceError(error48.code, error48.status, `${error48.code}: ${error48.message}${suffix}`, error48.candidates, error48.current, error48.mismatches);
+  return new DispatchServiceError(error48.code, error48.status, `${error48.code}: ${error48.message}${joined}`, error48.candidates, error48.current, error48.mismatches);
 }
 function dispatchAnswered(error48, status) {
   return error48 instanceof DispatchServiceError && error48.fromDispatch && error48.status === status;
@@ -16955,7 +16980,7 @@ async function executeDispatchTool(input) {
         } catch (error48) {
           const told = writeMayHaveLanded(error48) ? "the reason may or may not have been posted, and the close was not sent: read the issue's messages before retrying, since retrying this call posts its reason again" : "the reason was not posted, so the close was not sent";
           if (error48 instanceof DispatchServiceError)
-            throw refusalWithCode(error48, `; ${told}`);
+            throw refusalWithCode(error48, told);
           throw withAccount(error48, told);
         }
       }
@@ -16975,14 +17000,14 @@ async function executeDispatchTool(input) {
           actor
         });
       } catch (error48) {
-        const taken = dispatchAnswered(error48, 500) && newLinks.length > 0 ? `; one of ${newLinks.join(", ")} may already be linked from another issue (a URL links exactly one issue)` : "";
+        const taken = dispatchAnswered(error48, 500) && newLinks.length > 0 ? `one of ${newLinks.join(", ")} may already be linked from another issue (a URL links exactly one issue)` : "";
         if (closingNote === undefined)
           throw refusalWithCode(error48, taken);
         const posted = `the reason already landed as message ${closingNote.id} (${closingNote.ref})`;
         const fix = error48 instanceof DispatchGatewayError && error48.transient ? "" : "fix what refused the close, then ";
         const landed = writeMayHaveLanded(error48) ? `${posted}, and the close may or may not have taken effect. Read the issue's status before retrying: done means it closed; otherwise retry with a reason that points at message ${closingNote.id}, since retrying this call posts its reason again` : `${posted} but the issue did not close. Retrying this call posts its reason again, so ${fix}retry with a reason that points at message ${closingNote.id}`;
         if (error48 instanceof DispatchServiceError)
-          throw refusalWithCode(error48, `${taken}; ${landed}`);
+          throw refusalWithCode(error48, taken, landed);
         throw withAccount(error48, landed);
       }
       const linkCount = `(${after.external_links.length} ${after.external_links.length === 1 ? "link" : "links"})`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "3.19.4",
+  "version": "3.19.6",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/skills/dispatch/SKILL.md

@@ -84,7 +84,7 @@ a new version that keeps the human's own text, never a second "spec" artifact be
   versions keep the history.
 - **No placeholders.** No TBD, TODO, or hedging ("might", "could consider"): an open item is a
   decision block, a technical decision your lane makes and records in the text, or, for a
-  contract between two lanes or a halt condition, a question for the platform PO (see
+  contract between two lanes, a question for the platform PO (see
   [Before you ask](#before-you-ask) under Asking).
 - **No progress.** The spec records the design and its decisions, never status, timestamps, an
   "Update HH:MMZ" section, a pull-request list, or handoff notes. Progress is not a Dispatch
@@ -208,10 +208,11 @@ Every `dispatch_ask` passes four gates first:
 1. **Does it need his authority, taste, or risk appetite?** This is the bar for a decision
    written as an `:::ask` block in context ([Decision blocks](#decision-blocks)). Technical
    decisions inside your outcome do not: schema shapes, table layouts, field names, and migration
-   internals are your lane's to decide and record in the spec. Two things still go to the
-   platform PO over Envoy: a contract between two lanes, and a halt condition (a change to IAM,
-   deletion or exposure of production data, anything that reaches a customer). The PO takes those
-   to Sami as a Dispatch ask; you do not open one yourself, even as a permission ask under gate 2.
+   internals are your lane's to decide and record in the spec. A contract between two lanes still
+   goes to the platform PO over Envoy, and you open no ask for it. A halt condition (a change to
+   IAM, deletion or exposure of production data, anything that reaches a customer) passes this
+   gate: it is your own `dispatch_ask` to Sami on your own issue, never routed through the
+   platform PO.
 2. **Is there genuine uncertainty, and have you measured what you can?** If there is none, it is
    a plan you execute. The one legitimate ask without uncertainty is permission for an action
    only a human can authorise — a production write, an external send, a console action — and then
@@ -242,9 +243,9 @@ Every `dispatch_ask` passes four gates first:
    is not what this forbids; changing something else is. An ask that turns his complaint about
    one control into a choice about another does not address what he asked, and changing that
    other control is a change he never asked for. What is still an ask the moment you know it,
-   even before delivery, is anything "Anything that needs the human is an ask" (further down)
-   lists that the delivery waits on — including a conflict between what he asked for and another
-   of his rules, which this gate would otherwise bury as settled.
+   even before delivery, is anything "Anything you are blocked on a human for is an open ask"
+   (further down) lists that the delivery waits on — including a conflict between what he asked
+   for and another of his rules, which this gate would otherwise bury as settled.
 
 The platform PO audits open asks. One that fails a gate — or that points at another message in
 prose instead of carrying its content (below) — is retracted, with the PO's answer as the record.
@@ -314,8 +315,7 @@ Before saying you are waiting for human input, call `dispatch_open_asks`. With n
 **Anything you are blocked on a human for is an open ask.** An agent waits on a human only through
 an open ask. An approval, a credential or grant to renew, a setting only they can change, a review
 click, a decision, or a conflict between two of their own rules: open a `dispatch_ask` the moment
-you know, the action as the question. The exception is a halt condition from [Before you
-ask](#before-you-ask) gate 1, which goes to the platform PO over Envoy instead. Never write it
+you know, the action as the question. Never write it
 into a spec, a comment reply, a message, or a pull-request body: nothing in those paths reaches
 the human's Inbox, and a human who is not reading your document does not know they are the
 blocker. Before asking, try to remove the step: a value already on the machine, a permission you

package/skills/dispatch/references/document-edits.md

@@ -57,7 +57,10 @@ table's block id. A row index includes the header: row `0` is the header and its
 row and any row's last column cannot be deleted. An index is required. A missing, non-integer, negative, or out-of-range index is
 `INVALID_OP` on `index`, naming the supplied value and the table's actual dimensions before making any change. Markdown parsing
 canonicalizes short ragged rows by padding missing cells, so column deletion preserves every non-selected cell in the canonical table.
-`GET /api/v1/artifacts/<artifact UUID>/blocks` reports a table's own references plus its descendant cell anchors. A row or column
+`GET /api/v1/artifacts/<artifact UUID>/blocks` reports a table's own references plus its descendant cell anchors.
+`GET /api/v1/artifacts/<artifact UUID>/blocks/<block id>` places one block: its path from the top-level block down, and for a cell
+the row index (0 is the header, what `delete_row` takes), the column index (what `delete_column` takes), the text of the header cell
+drawn above it (with colspans or rowspans, the column the cell is drawn in) and the row's cells. A row or column
 deletion that would remove an open ask or unresolved comment anchor is `INVALID_OP` on `index`, naming the axis and anchor ids;
 answered asks and resolved comments are history and do not block it. A `find` or quote anchor tolerates inline Markdown
 (`**bold**`, `` `code` ``) and a leading `# ` selects a heading by its text; a miss names the quote and the three nearest blocks so

package/skills/dispatch/references/reading.md

@@ -16,6 +16,15 @@ document owner or ref, it returns a document summary with `details` `{ project,
 question, options, state, answer, and its reply thread. With a comment ref, it returns that comment and its quoted reply chain. With a
 message ref, it returns that message and its reply chain. Reads do not subscribe; use `dispatch_doc_read` for document contents.
 
+An anchored comment or ask also prints `Position:`, where its quote's block stands — `table[3] › row 5 (Red-teamer loop), column Due`
+is the fourth top-level block, a table, its row 5 (row 0 is the header; the index `delete_row` takes), labelled by the row's cells
+before the anchored one, in the column headed Due; outside a table it is the path of types and child indexes down to the block. The
+same facts are `anchor_block` on `GET /api/v1/comments/{id}` and `GET /api/v1/asks/{id}`, and
+`GET /api/v1/artifacts/{id}/blocks/{block_id}` answers them for any block id a document holds. When Dispatch could not read the
+document, the read still answers and prints `Position: unavailable (DOC_SERVICE_UNAVAILABLE)` (try again shortly),
+`Position: unavailable (DOC_SCHEMA)` (the document needs repair) or `Position: unavailable (INTERNAL)`; the API carries that
+code as `anchor_block_error`.
+
 Every read ends with two sections from the reference graph. `Referenced by:` lists what points at the node — every document, ask,
 comment, or message that cites it, plus its structure: child issues, attached documents, anchored and owned asks and comments, replies,
 followers — and `Links:` lists what it cites. Each row is `- <edge kind> <node kind> dispatch://… (<excerpt> · <when>)`; for a