@sjawhar/pi-legion-envoy 1.38.5 → 1.40.0

package/README.md

@@ -85,10 +85,10 @@ extension files it does not contain.
 
 ## Native Dispatch tools
 
-The extension registers fifteen native Dispatch tools: `dispatch_issue`, `dispatch_ask`, `dispatch_edit_ask`,
-`dispatch_resolve_ask`, `dispatch_follow`, `dispatch_comment`, `dispatch_suggest`, `dispatch_message`,
-`dispatch_doc_edit`, `dispatch_doc_read`, `dispatch_request_approval`, `dispatch_artifact`, `dispatch_read`,
-`dispatch_search`, and `dispatch_open_asks`, when Dispatch configuration resolves both a base URL and bearer token.
+The extension registers sixteen native Dispatch tools: `dispatch_issue`, `dispatch_ask`, `dispatch_edit_ask`,
+`dispatch_resolve_ask`, `dispatch_resolve_comment`, `dispatch_follow`, `dispatch_comment`, `dispatch_suggest`,
+`dispatch_message`, `dispatch_doc_edit`, `dispatch_doc_read`, `dispatch_request_approval`, `dispatch_artifact`,
+`dispatch_read`, `dispatch_search`, and `dispatch_open_asks`, when Dispatch configuration resolves both a base URL and bearer token.
 
 Configure the shared `envoy.json` with:
 
@@ -112,7 +112,7 @@ whose trimmed contents are the token — how the Legion daemon delivers it to a
 pane) wins over every other token source and never falls back when unreadable.
 Omitting `dispatch.serverUrl` while `dispatch.enabled` is true targets
 `http://localhost:8766`, the Go server's listen address. Invalid configuration,
-an invalid URL, or an empty token leaves the fifteen tools unavailable and
+an invalid URL, or an empty token leaves the sixteen tools unavailable and
 reports the source of the error.
 
 Owner-scoped calls use either an issue (a native `KEY` or external `owner/repo#n` reference) or
@@ -121,7 +121,7 @@ an unlinked project document (`project` plus its `artifact` slug). A Legion sess
 repository. `dispatch_doc_read` and `dispatch_read` also accept `dispatch://` references,
 including `dispatch://PROJECT/artifact/<slug>`. `dispatch_search` needs only its query.
 `dispatch_edit_ask`, `dispatch_resolve_ask`, and `dispatch_follow` instead identify an existing
-ask with `ask`. No result carries a subscription topic: opening an ask or replying to one with
+ask with `ask`, and `dispatch_resolve_comment` a comment with `comment`. No result carries a subscription topic: opening an ask or replying to one with
 `dispatch_comment({ reply_to_ask })` makes the session a follower of that ask (its answer and
 replies reach the session directly, server-side), the result carries `details.follows.ask`, and
 the extension's `tool_result` hook tells the model so once per ask. Whole-issue or

package/dist/envoy.js

@@ -29946,6 +29946,14 @@ var dispatchToolSpecs = [
       reason: z.string({ min: 1 }).describe("Why the open ask no longer needs a human answer.")
     })
   },
+  {
+    name: "dispatch_resolve_comment",
+    description: "Resolve a review comment thread once it has been addressed - typically your own comment " + "after the document was fixed. Any session or human may resolve any open comment on an " + "open issue or project document; reopening a resolved comment is human-only (the dashboard). " + "Not for asks: use dispatch_resolve_ask.",
+    arguments: (z) => ({
+      comment: z.string().describe("Comment id (uuid), or a dispatch://KEY/comment/<id> or " + "dispatch://PROJECT/artifact/<slug>/comment/<id> reference; a reference accepts an " + "8+ character id prefix that is unique on its owner.")
+    }),
+    strict: true
+  },
   {
     name: "dispatch_follow",
     description: "Follow or unfollow an ask. Every session that opens or replies to an ask follows it: its answer, " + "edits, resolution, and replies reach that session directly. Unfollow to stop; follow to rejoin or " + "to hear an ask you never wrote to. Whole-issue subscription is separate: envoy_subscribe " + "notifications.dispatch.issue.<KEY>.>",
@@ -30063,7 +30071,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_read",
-    description: "Read an issue or project-document summary, targeted ask, or targeted comment reply chain. Do not use it for document " + "contents; use dispatch_doc_read instead. Supply ref, issue, or project plus artifact. " + OWNER_REFERENCE,
+    description: "Read an issue or project-document summary, targeted ask, or targeted comment reply chain. Do not use it for document " + "contents; use dispatch_doc_read instead. Supply ref, issue, or project plus artifact. " + "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: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -31965,6 +31973,9 @@ class DispatchClient {
   async getComment(id) {
     return this.#json("GET", ["api", "v1", "comments", id]);
   }
+  async resolveComment(id, actor) {
+    return this.#json("POST", ["api", "v1", "comments", id, "resolve"], { actor });
+  }
   async getComments(issue, artifact) {
     return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "comments"], undefined, artifact ? { artifact } : undefined);
   }
@@ -31977,6 +31988,13 @@ class DispatchClient {
       "references"
     ]);
   }
+  async getReferences(query) {
+    return this.#json("GET", ["api", "v1", "references"], undefined, {
+      ..."to" in query ? { to: query.to } : { from: query.from },
+      ...query.kind === undefined || query.kind.length === 0 ? {} : { kind: query.kind.join(",") },
+      ...query.since === undefined ? {} : { since: query.since }
+    });
+  }
   async ensureIssue(issueReference, actor) {
     if (!issueReference.includes("#"))
       return issueReference;
@@ -32242,6 +32260,19 @@ async function askOwnerDetails(client, ask, resolved) {
   const artifact = resolved?.artifact ?? await client.getArtifact(ask.artifact_id);
   return { ...documentResultDetails(artifact), ask: ask.id };
 }
+async function commentOwnerResult(client, comment, artifact) {
+  if (comment.issue_key !== null) {
+    return { label: comment.issue_key, details: { issue: comment.issue_key, comment: comment.id } };
+  }
+  if (comment.artifact_id === undefined || comment.artifact_id === null) {
+    throw new Error("document comment is missing its artifact ID");
+  }
+  const owner = artifact ?? await client.getArtifact(comment.artifact_id);
+  return {
+    label: documentTopic(owner).label,
+    details: { ...documentResultDetails(owner), comment: comment.id }
+  };
+}
 async function followedAskDetails(client, ask, resolved) {
   return { ...await askOwnerDetails(client, ask, resolved), follows: { ask: ask.id } };
 }
@@ -32252,6 +32283,7 @@ var issueFreeTools = {
   dispatch_issue: true,
   dispatch_edit_ask: true,
   dispatch_resolve_ask: true,
+  dispatch_resolve_comment: true,
   dispatch_follow: true,
   dispatch_search: true,
   dispatch_open_asks: true
@@ -32374,6 +32406,7 @@ function parseDispatchRef(ref) {
 }
 var uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var askIdProblem = "ask must be a bare ask id or a dispatch://.../ask/<id> reference";
+var commentIdProblem = "comment must be a bare comment id or a dispatch://.../comment/<id> reference";
 var messageIdProblem = "in_reply_to must be a full message id (uuid) or a dispatch://KEY/message/<id> reference";
 function askId(args) {
   const ask = stringArg(args, "ask");
@@ -32429,6 +32462,13 @@ function argumentProblems(tool, args) {
       }
       break;
     }
+    case "dispatch_resolve_comment": {
+      const comment = optionalString(args, "comment");
+      if (comment?.startsWith("dispatch://") && parseDispatchRef(comment)?.kind !== "comment") {
+        problems.push(commentIdProblem);
+      }
+      break;
+    }
     case "dispatch_comment": {
       if (optionalString(args, "quote") !== undefined && optionalString(args, "artifact") === undefined) {
         problems.push("artifact is required when quote is supplied");
@@ -32656,7 +32696,7 @@ function approvalLine(artifact) {
       return `Approval: changes requested on v${approval.version} by ${approval.by?.id ?? "unknown"}: ${approval.reason ?? ""}`;
   }
 }
-function issueSummary(issue, events, references) {
+function issueSummary(issue, events, references, graph) {
   const asks = issue.open_asks;
   const spec = issue.artifacts?.find((artifact) => artifact.primary);
   const specApproval = spec === undefined ? undefined : approvalLine(spec);
@@ -32676,10 +32716,35 @@ function issueSummary(issue, events, references) {
     ...typeof references === "string" ? [`- ${references}`] : references.members.length === 0 ? ["- none"] : references.members.map(({ artifact, depth, via }) => `- ${artifact.project}/${artifact.slug} \xB7 depth ${depth} via ${via.kind} ${via.id}`),
     ...typeof references === "string" || !references.truncated ? [] : ["- more references beyond 8 hops"],
     "Events:",
-    ...events.length === 0 ? ["- none"] : events.map(eventLine)
+    ...events.length === 0 ? ["- none"] : events.map(eventLine),
+    ...graph
   ].join(`
 `);
 }
+function referenceLines(edges) {
+  if (typeof edges === "string")
+    return [`- ${edges}`];
+  if (edges.length === 0)
+    return ["- none"];
+  return edges.map((edge) => {
+    const excerpt = edge.excerpt === undefined ? "" : `${textHead(edge.excerpt.text)} \xB7 `;
+    return `- ${edge.kind} ${edge.node.kind} ${edge.node.ref ?? edge.node.id} (${excerpt}${edge.created_at})`;
+  });
+}
+async function graphEdges(client, query) {
+  try {
+    return (await client.getReferences(query)).edges;
+  } catch (error) {
+    return error instanceof DispatchServiceError && error.status === 404 ? "unavailable" : `unavailable: ${error instanceof Error ? error.message : String(error)}`;
+  }
+}
+async function graphSections(client, ref) {
+  const [incoming, outgoing] = await Promise.all([
+    graphEdges(client, { to: ref }),
+    graphEdges(client, { from: ref })
+  ]);
+  return ["Referenced by:", ...referenceLines(incoming), "Links:", ...referenceLines(outgoing)];
+}
 function logSummary(issue, events) {
   return [
     `Key: ${issue.key}`,
@@ -32727,7 +32792,7 @@ function childrenSummary(issue) {
   ].join(`
 `);
 }
-function askSummary({ ask, replies }) {
+function askSummary({ ask, replies }, graph) {
   const answer = ask.answer;
   const chain = replies.flatMap((reply) => [
     `${reply.id} \xB7 ${reply.author.kind} ${reply.author.id}`,
@@ -32751,7 +32816,8 @@ function askSummary({ ask, replies }) {
       `- Reason: ${ask.resolution.reason}`
     ],
     "Replies:",
-    ...chain.length === 0 ? ["- none"] : chain
+    ...chain.length === 0 ? ["- none"] : chain,
+    ...graph
   ].join(`
 `);
 }
@@ -32794,7 +32860,7 @@ function formatOpenAsksSummary(response, baseUrl) {
   ].join(`
 `);
 }
-function commentSummary({ comment, replies }) {
+function commentSummary({ comment, replies }, graph) {
   const root = [
     `${comment.id} \xB7 ${comment.author.kind} ${comment.author.id}`,
     ...comment.anchor?.quote === undefined ? [] : [`> ${comment.anchor.quote}`],
@@ -32805,10 +32871,16 @@ function commentSummary({ comment, replies }) {
     ...reply.anchor?.quote === undefined ? [] : [`> ${reply.anchor.quote}`],
     `Body: ${reply.body}`
   ]);
-  return ["Comment:", ...root, "Reply chain:", ...chain.length === 0 ? ["- none"] : chain].join(`
+  return [
+    "Comment:",
+    ...root,
+    "Reply chain:",
+    ...chain.length === 0 ? ["- none"] : chain,
+    ...graph
+  ].join(`
 `);
 }
-function messageSummary({ message, replies }) {
+function messageSummary({ message, replies }, graph) {
   const root = [
     `${message.id} \xB7 ${message.author.kind} ${message.author.id}`,
     `Body: ${message.body}`
@@ -32817,7 +32889,13 @@ function messageSummary({ message, replies }) {
     `${reply.id} \xB7 ${reply.author.kind} ${reply.author.id}`,
     `Body: ${reply.body}`
   ]);
-  return ["Message:", ...root, "Reply chain:", ...chain.length === 0 ? ["- none"] : chain].join(`
+  return [
+    "Message:",
+    ...root,
+    "Reply chain:",
+    ...chain.length === 0 ? ["- none"] : chain,
+    ...graph
+  ].join(`
 `);
 }
 async function openArtifactMarks(client, resolved) {
@@ -32970,6 +33048,23 @@ async function executeDispatchTool(input) {
         details: await askOwnerDetails(client, ask)
       };
     }
+    case "dispatch_resolve_comment": {
+      const reference = stringArg(args, "comment");
+      const ref = reference.startsWith("dispatch://") ? parseDispatchRef(reference) : null;
+      let id = reference;
+      let document;
+      if (ref?.owner.kind === "issue") {
+        const issueKey = ref.owner.issue;
+        id = await resolveIdPrefix(input.tool, "comment", ref, () => client.getComments(issueKey));
+      } else if (ref !== null) {
+        const artifact = (await resolveArtifact(client, ref.owner, ref.artifact)).artifact;
+        document = artifact;
+        id = await resolveIdPrefix(input.tool, "comment", ref, () => client.getArtifactComments(artifact.id));
+      }
+      const comment = await client.resolveComment(id, actor);
+      const { label, details } = await commentOwnerResult(client, comment, document);
+      return { text: `Resolved comment ${comment.id} on ${label}.`, details };
+    }
     case "dispatch_ask": {
       const anchorArgs = asObject(args.anchor);
       const owner = documentOwner();
@@ -33197,8 +33292,9 @@ ${trailer.join(`
         const ref = ownerArguments.ref;
         const id = await resolveIdPrefix(input.tool, "ask", ref, async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks((await resolveArtifact(client, ref.owner, ref.artifact)).artifact.id, "all"));
         const askRead = await client.getAsk(id);
+        const askRef = ref.owner.kind === "issue" ? `dispatch://${ref.owner.issue}/ask/${id}` : `dispatch://${ref.owner.project}/artifact/${ref.artifact}/ask/${id}`;
         return {
-          text: askSummary(askRead),
+          text: askSummary(askRead, await graphSections(client, askRef)),
           details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: ref.owner.issue }
         };
       }
@@ -33206,8 +33302,9 @@ ${trailer.join(`
         const ref = ownerArguments.ref;
         const id = await resolveIdPrefix(input.tool, "comment", ref, async () => ref.owner.kind === "issue" ? client.getComments(ref.owner.issue) : client.getArtifactComments((await resolveArtifact(client, ref.owner, ref.artifact)).artifact.id));
         const comment = await client.getComment(id);
+        const commentRef = ref.owner.kind === "issue" ? `dispatch://${ref.owner.issue}/comment/${id}` : `dispatch://${ref.owner.project}/artifact/${ref.artifact}/comment/${id}`;
         return {
-          text: commentSummary(comment),
+          text: commentSummary(comment, await graphSections(client, commentRef)),
           details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: comment.comment.issue_key }
         };
       }
@@ -33216,19 +33313,22 @@ ${trailer.join(`
           throw new Error("message references are issue-scoped");
         }
         const messageRead = await client.getMessage(ownerArguments.ref.owner.issue, ownerArguments.ref.id);
+        const messageRef = `dispatch://${ownerArguments.ref.owner.issue}/message/${ownerArguments.ref.id}`;
         return {
-          text: messageSummary(messageRead),
+          text: messageSummary(messageRead, await graphSections(client, messageRef)),
           details: { issue: messageRead.message.issue_key }
         };
       }
       if (documentOwner().kind === "project") {
         const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
+        const documentRef = `dispatch://${resolved.artifact.project}/artifact/${resolved.artifact.slug}`;
         return {
           text: [
             `Document: ${resolved.artifact.project} / ${resolved.artifact.name}`,
-            `Reference: dispatch://${resolved.artifact.project}/artifact/${resolved.artifact.slug}`,
+            `Reference: ${documentRef}`,
             `Versions: ${resolved.artifact.versions.length}`,
-            ...approvalLine(resolved.artifact) === undefined ? [] : [approvalLine(resolved.artifact)]
+            ...approvalLine(resolved.artifact) === undefined ? [] : [approvalLine(resolved.artifact)],
+            ...await graphSections(client, documentRef)
           ].join(`
 `),
           details: {
@@ -33257,7 +33357,7 @@ ${trailer.join(`
         references = error instanceof DispatchServiceError && error.status === 404 ? "unavailable" : `unavailable: ${error instanceof Error ? error.message : String(error)}`;
       }
       return {
-        text: issueSummary(read.issue, read.events, references),
+        text: issueSummary(read.issue, read.events, references, await graphSections(client, `dispatch://${read.issue.key}`)),
         details: { issue: read.issue.key }
       };
     }

package/dist/legion.js

@@ -29220,6 +29220,14 @@ var dispatchToolSpecs = [
       reason: z.string({ min: 1 }).describe("Why the open ask no longer needs a human answer.")
     })
   },
+  {
+    name: "dispatch_resolve_comment",
+    description: "Resolve a review comment thread once it has been addressed - typically your own comment " + "after the document was fixed. Any session or human may resolve any open comment on an " + "open issue or project document; reopening a resolved comment is human-only (the dashboard). " + "Not for asks: use dispatch_resolve_ask.",
+    arguments: (z) => ({
+      comment: z.string().describe("Comment id (uuid), or a dispatch://KEY/comment/<id> or " + "dispatch://PROJECT/artifact/<slug>/comment/<id> reference; a reference accepts an " + "8+ character id prefix that is unique on its owner.")
+    }),
+    strict: true
+  },
   {
     name: "dispatch_follow",
     description: "Follow or unfollow an ask. Every session that opens or replies to an ask follows it: its answer, " + "edits, resolution, and replies reach that session directly. Unfollow to stop; follow to rejoin or " + "to hear an ask you never wrote to. Whole-issue subscription is separate: envoy_subscribe " + "notifications.dispatch.issue.<KEY>.>",
@@ -29337,7 +29345,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_read",
-    description: "Read an issue or project-document summary, targeted ask, or targeted comment reply chain. Do not use it for document " + "contents; use dispatch_doc_read instead. Supply ref, issue, or project plus artifact. " + OWNER_REFERENCE,
+    description: "Read an issue or project-document summary, targeted ask, or targeted comment reply chain. Do not use it for document " + "contents; use dispatch_doc_read instead. Supply ref, issue, or project plus artifact. " + "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: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),

package/dist/skills/dispatch/SKILL.md

@@ -199,6 +199,8 @@ Use `retracted` when the question is obsolete and `resolved` when you found the
 in its Conversation card and reply thread. Resolution is not an answer: it never records a human decision, and an answered ask cannot be
 resolved. A human may reply to an open or answered ask; so may you, e.g. after finding the answer — use `reply_to_ask` on
 `dispatch_comment` (mutually exclusive with `reply_to`).
+A review comment you opened has its own closer, `dispatch_resolve_comment` — see
+[Comments and suggestions](#comments-and-suggestions).
 
 A human answers or asks back from the same field; a question-shaped free-text answer is offered as a clarification first. A human
 reply while your ask is still open (the delivered `comment.created` carries `ask_state: open`) is a request for clarification, not
@@ -353,6 +355,18 @@ the human needs to act; see [Asking](#asking). Comments are edited only by their
 dashboard. A delivered `comment.created` event carries the comment `id`; reply to it with
 `dispatch_comment({ reply_to: <id> })`.
 
+Resolve your own review comment once you have addressed it:
+
+```ts
+dispatch_resolve_comment({ comment })
+```
+
+`comment` is the comment id, or a `dispatch://KEY/comment/<id>` or `dispatch://PROJECT/artifact/<slug>/comment/<id>` reference (an
+8+ character id prefix is resolved against the owner's comments). It returns the owner details plus `comment`, and takes no reason —
+say what you did in a `reply_to` first if the thread needs it. The server lets any session or human resolve any open comment, so
+resolve only threads you opened or were asked to close; reopening a resolved thread is human-only (from the dashboard), though your
+reply to it reopens it. Asks are closed with `dispatch_resolve_ask` instead.
+
 Propose an exact replacement instead of describing it:
 
 ```ts
@@ -384,6 +398,11 @@ with your text. Never do that: the spec is edited in place with `dispatch_doc_ed
 artifact by the slug shown in the upload result or by its filename, and a project document by its artifact id, slug, or filename; the
 slug also arrives on `artifact.created` events.
 
+Documents are CommonMark. A bare `<https://example.com|text>` is a CommonMark autolink and is normalised: the angle brackets are
+dropped and the URL keeps `|text`. A backslash-escaped `\<https://example.com|text>` displays as `<https://example.com|text>` in the
+document but comes back re-escaped (`\<`) from `dispatch_doc_read`. A Slack mrkdwn draft, or any other payload that is not Markdown,
+still belongs inside a fenced code block, where it survives verbatim both ways.
+
 ## Structure over stream
 
 Dispatch is a structured workspace, never a message stream (Sami, 2026-09-13, verbatim: "strange
@@ -475,6 +494,14 @@ 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.
 
+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
+document source the excerpt is the block containing the mention. Cross-project, always: a message on another project's issue that
+cites an ask shows up under that ask. So "what led to this decision" is one `dispatch_read` on the ask, and "who relies on this
+document" one read on the document. Cite with `dispatch://` references (below) whenever you name a node in a body — a bare id or
+title is invisible to the graph.
+
 ## References
 
 Use these in document, ask, comment, and message bodies. In the dashboard, a reference renders

package/package.json

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