@sjawhar/opencode-legion-envoy 1.27.4 → 1.28.0

package/dist/src/server.js

@@ -13779,7 +13779,7 @@ var SPEC_SECTIONS = [
 ];
 var SPEC_WRITING_GUIDANCE = `When writing a spec, use these sections in order: ${SPEC_SECTIONS.join(", ")}. ` + "Write for a reader who has not seen the code: plain sentences, every identifier expanded on " + "first use, no coined shorthand; see skills/dispatch Writing for the human and Writing a spec.";
 var ASK_URGENCIES = ["low", "med", "high", "blocking"];
-var DOC_EDIT_OPS = ["replace", "delete", "insert", "retype"];
+var DOC_EDIT_OPS = ["replace", "delete", "insert", "retype", "move"];
 var dispatchToolSpecs = [
   {
     name: "dispatch_issue",
@@ -13901,7 +13901,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_doc_edit",
-    description: "Apply deterministic document edits, including retyping an identified paragraph into a schema-declared typed block. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + 'For replace, delete, and quote insert anchors, find text as rendered: inline Markdown (**bold**, `code`) is tolerated; a leading \'# \' matches a heading. Insert anchors also accept "start", "end", and "heading:<exact heading text>". ' + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
+    description: "Apply deterministic document edits: replace or delete quoted text, insert markdown at an anchor, retype an identified paragraph or typed block into a schema-declared typed block, and delete or move a whole block by its id. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + "For replace, delete, and quote anchors, find text as rendered: inline Markdown (**bold**, `code`) is tolerated; a leading '# ' matches a heading. replace is inline: with is the new text of the matched span, so a leading list or heading marker stays literal text. " + "A delete whose find is a block's entire text removes the block (a list emptied of its items goes too); delete with block removes any block by id, and move with block relocates one. " + 'Insert and move anchors also accept "start", "end", "heading:<exact heading text>", and "block:<id>"; block ids are the #id of a typed block or a row of GET /api/v1/artifacts/{id}/blocks. ' + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -13909,13 +13909,13 @@ var dispatchToolSpecs = [
       ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       ops: z.array(z.object({
         op: z.enum(DOC_EDIT_OPS).describe("Edit operation."),
-        find: z.string().describe("Text of the target block as rendered, for replace or delete; inline markdown (**bold**, `code`) is tolerated; a leading '# ' matches a heading.").optional(),
-        with: z.string().describe("Replacement text for replace.").optional(),
+        find: z.string().describe("Text of the target as rendered, for replace or delete; inline markdown (**bold**, `code`) is tolerated; a leading '# ' matches a heading. A delete of a block's entire text removes the block.").optional(),
+        with: z.string().describe("Replacement text for replace, parsed as inline markdown within the matched block; a leading list or heading marker is literal text.").optional(),
         occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based match occurrence.").optional(),
         markdown: z.string().describe("Markdown to insert.").optional(),
-        after: z.string().describe(`Insert after this anchor: a quote of the neighbouring block's text, or one of "start", "end", "heading:<exact heading text>".`).optional(),
-        before: z.string().describe(`Insert before this anchor: a quote of the neighbouring block's text, or one of "start", "end", "heading:<exact heading text>".`).optional(),
-        block: z.string().describe("Block id to retype.").optional(),
+        after: z.string().describe(`Insert or move after this anchor: a quote of the neighbouring block's text, or one of "start", "end", "heading:<exact heading text>", "block:<id>".`).optional(),
+        before: z.string().describe(`Insert or move before this anchor: a quote of the neighbouring block's text, or one of "start", "end", "heading:<exact heading text>", "block:<id>".`).optional(),
+        block: z.string().describe("Block id for retype, delete, or move: the #id of a typed block, or an id from GET /api/v1/artifacts/{id}/blocks.").optional(),
         type: z.string().describe("Typed block name for retype.").optional(),
         attributes: z.unknown().describe("Typed block attributes for retype.").optional()
       })).describe("Flat tagged edits; the server validates fields required for each operation."),
@@ -13966,7 +13966,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(),
@@ -14914,6 +14914,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;
@@ -15593,7 +15600,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);
@@ -15613,10 +15620,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}`,
@@ -15664,7 +15696,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}`,
@@ -15688,7 +15720,8 @@ function askSummary({ ask, replies }) {
       `- Reason: ${ask.resolution.reason}`
     ],
     "Replies:",
-    ...chain.length === 0 ? ["- none"] : chain
+    ...chain.length === 0 ? ["- none"] : chain,
+    ...graph
   ].join(`
 `);
 }
@@ -15731,7 +15764,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}`],
@@ -15742,10 +15775,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}`
@@ -15754,7 +15793,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) {
@@ -16134,8 +16179,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 }
         };
       }
@@ -16143,8 +16189,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 }
         };
       }
@@ -16153,19 +16200,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: {
@@ -16194,7 +16244,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/package.json

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

package/skills/dispatch/SKILL.md

@@ -253,7 +253,7 @@ exact `EditOp` shape:
 
 ```ts
 type EditOp = {
-  op: "replace" | "delete" | "insert" | "retype";
+  op: "replace" | "delete" | "insert" | "retype" | "move";
   find?: string;
   with?: string;
   occurrence?: number;
@@ -271,18 +271,34 @@ code without backticks, bold without asterisks, and link text without link synta
 anchor is its cell text. Quote code-block contents without their Markdown fences. A quote must stay
 within one textblock; split changes that span separate blocks into separate operations.
 
-`replace` requires `find` and `with`; `delete` requires `find`; `insert` requires `markdown` and exactly one of `after` or `before`. An
-insert anchor is a quote, `"start"`, `"end"`, or `"heading:Title"`. Ordinary inserts create a sibling block before or after the quote or
-heading's enclosing document block; `"start"` and `"end"` select the document edges. At a table-cell quote, a body-row fragment (no
-header or delimiter rows) extends that table before or after the matched row instead; short rows are padded, wider rows are rejected,
-and deleting a cell's quoted text removes only that text. A `find` or quote anchor tolerates inline Markdown (`**bold**`, `` `code` ``)
-and a leading `# ` selects a heading by its text; a miss names the three nearest blocks so the next quote lands.
-
-Use `replace` for inline continuation. Use zero-based `occurrence` for a repeated target; re-read a missing or ambiguous target before
-retrying. Pass `summary` to name the version when recording a decision.
-`retype` turns the paragraph with `block` into the named typed `type` in place. It keeps the
-block id and uses `attributes` for client-owned typed attributes. Use it when an existing
-paragraph is the question that should become a decision.
+`replace` requires `find` and `with`; `delete` requires `find` or `block`; `insert` requires `markdown` and exactly one of `after` or
+`before`; `move` requires `block` and exactly one of `after` or `before`. An insert or move anchor is a quote, `"start"`, `"end"`,
+`"heading:Title"`, or `"block:<id>"`. Ordinary inserts create a sibling block before or after the quote, heading, or block's enclosing
+document block, and a move lands the block at that same boundary; `"start"` and `"end"` select the document edges. At a table-cell
+quote, a body-row fragment (no header or delimiter rows) extends that table before or after the matched row instead; short rows are
+padded, wider rows are rejected, and deleting a cell's quoted text removes only that text. A `find` or quote anchor tolerates inline
+Markdown (`**bold**`, `` `code` ``) and a leading `# ` selects a heading by its text; a miss names the three nearest blocks so the next
+quote lands.
+
+`replace` is inline: `with` is the new text of the matched span inside its block, so a leading list or heading marker (`4. Design`,
+`# Title`) stays literal text and never turns the block into a list or heading; `with` that forms more than one paragraph is rejected
+(`INVALID_OP` on `with`) — delete the block and insert new blocks instead. Use zero-based `occurrence` for a repeated target; re-read a
+missing or ambiguous target before retrying. Pass `summary` to name the version when recording a decision.
+
+A `delete` whose `find` is a block's entire text removes the block itself — the bullet, paragraph, or heading, not just its words — and
+a list emptied of every item disappears with it; a partial match keeps the block with its remaining text. Deleting the text of a bullet
+that holds a nested list hoists that list's items into the bullet's place (as an outliner does); a bullet with any other content
+(paragraphs, code, tables) is refused with `INVALID_OP` naming `delete {block:"<item id>"}`, which removes the item with its content.
+`delete` with `block` removes any block by id (paragraph, heading, list, list item, table, or typed block; deleting an open `ask` block
+retracts its ask, while an answered one keeps its answer as the record), and `move` with `block` relocates one, keeping its id and
+attributes — a moved `ask` keeps its ask and answer. Block ids are the `#id` a typed block renders (`:::ask{#5467e5ce-…}`) and, for
+every block including untyped ones, the `id` rows of `GET /api/v1/artifacts/{id}/blocks` (or `/api/v1/issues/{key}/artifacts/{slug}/blocks`),
+each with its `type` and byte range in the canonical markdown. A move whose anchor lies inside the moved block, or a delete that would
+leave a typed block without the body its content rule requires, is `INVALID_OP` naming the field and the rule.
+
+`retype` turns the paragraph or typed block with `block` into the named typed `type` in place. It keeps the
+block id, keeps a typed block's body, and uses `attributes` for client-owned typed attributes. Use it when
+an existing paragraph is the question that should become a decision.
 
 ## Typed blocks
 
@@ -459,6 +475,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