@sjawhar/pi-legion-envoy 1.51.1 → 1.51.2

package/dist/envoy.js

@@ -29908,6 +29908,7 @@ var DOC_EDIT_OPS = ["replace", "delete", "insert", "retype", "move"];
 var dispatchToolSpecs = [
   {
     name: "dispatch_issue",
+    example: { project: "DSP", title: "Native workspace" },
     description: "Create a native Dispatch issue for newly tracked work. Search first with dispatch_search; if potentially duplicate issues exist, this returns 409 POSSIBLE_DUPLICATE unless force is true after reading them. " + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       project: z.string().describe("Project key for the new issue."),
@@ -29924,6 +29925,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_issue_update",
+    example: { issue: "DSP-1", status: "in_progress" },
     description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, link a URL " + "(the pull request that delivers it, a run, a document), set its route, set or clear its parent, " + "or attach it to architecture components. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. external_links are " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link. components replaces the issue's own attachment and is allowed on a " + "closed issue. Priority is the human's and is not settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
@@ -29946,6 +29948,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_ask",
+    example: { issue: "DSP-1", question: "Ship this?" },
     description: "Open a durable, answerable decision on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. A to-do a human must complete is a question phrased as that to-do, with the options you want (for example Done / Can't). " + "Anchor a document question, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". A quote anchor is pinned to its block. Question is at most ${ASK_QUESTION_MAX} ` + `characters and has at most 8 options. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
@@ -29969,6 +29972,10 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_edit_ask",
+    example: {
+      ask: "01234567-0000-4000-8000-000000000001",
+      question: "Ship the revised plan?"
+    },
     description: "Edit an open question in place. Use it to correct or refine the same decision; retract the " + "old ask and open a new one when the decision itself changes. Previous text remains in the " + "event log. Only the asking session can edit it; answered or resolved asks cannot be edited.",
     arguments: (z) => ({
       ask: z.string().describe("Ask id to edit."),
@@ -29990,6 +29997,11 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_resolve_ask",
+    example: {
+      ask: "01234567-0000-4000-8000-000000000001",
+      kind: "retracted",
+      reason: "A newer question supersedes this one."
+    },
     description: "Retract an open question that is moot or resolve one after finding the answer. This closes the question without answering it.",
     arguments: (z) => ({
       ask: z.string().describe("Ask id to close."),
@@ -29999,6 +30011,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_resolve_comment",
+    example: { comment: "01234567-0000-4000-8000-000000000001" },
     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.")
@@ -30007,6 +30020,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_follow",
+    example: { ask: "01234567-0000-4000-8000-000000000001", action: "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>.>",
     arguments: (z) => ({
       ask: z.string().describe("Full ask id (uuid)."),
@@ -30016,6 +30030,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_comment",
+    example: { issue: "DSP-1", body: "Looks good." },
     description: "Add review feedback to an issue or project document quote, or reply to a question asked with dispatch_ask. " + "Do not use it for an exact replacement; use " + `dispatch_suggest instead. A quote anchor is pinned to its block. Body is at most 2,000 characters. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
@@ -30033,6 +30048,12 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_suggest",
+    example: {
+      issue: "DSP-1",
+      artifact: "spec",
+      quote: "old wording",
+      replace_with: "new wording"
+    },
     description: "Propose an exact replacement for quoted document text. Do not use it for general feedback; use " + `dispatch_comment instead. Optional explanation is at most 2,000 characters. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
@@ -30048,6 +30069,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_message",
+    example: { issue: "DSP-1", body: "Implementation started." },
     description: "Post a note humans must read now: a reply to a human's message, a deliverable that landed, or a blocker only " + "they can clear. Never progress or status updates - Dispatch is a high-signal record, not a log. Not a decision " + `(dispatch_ask) or document feedback (dispatch_comment). Body is at most 2,000 characters. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
@@ -30057,6 +30079,11 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_doc_edit",
+    example: {
+      issue: "DSP-1",
+      artifact: "spec",
+      ops: [{ op: "replace", find: "old", with: "new" }]
+    },
     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(),
@@ -30081,6 +30108,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_doc_read",
+    example: { issue: "DSP-1" },
     description: "Read a live document or a named document version. Do not use it for issue status, asks, or events; " + "use dispatch_read instead. Supply ref, issue, or project plus artifact; issue plus an omitted artifact reads the primary document. " + OWNER_REFERENCE,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
@@ -30093,6 +30121,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_request_approval",
+    example: { issue: "DSP-1" },
     description: "Ask a human to approve a document at its current version - the exception path for a spec " + "that departs from what was settled or proposes children, not a step for every issue. Opens an " + "approval ask (Approve / Request changes) in the human's Inbox; the answer pins a review to the " + "document version and arrives as artifact.approved or artifact.changes_requested. A later edit " + "makes an approval stale; request again for the new version. Idempotent while a request is open. " + OWNER_REFERENCE,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
@@ -30103,6 +30132,8 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_artifact",
+    example: { issue: "DSP-1", name: "design.md", content: `# Design
+` },
     description: "Attach a local file or inline text as an issue artifact or project document. Do not use it to edit a live document; use " + `dispatch_doc_edit instead. Exactly one of path or content is required; artifacts are limited to 25 MiB. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
@@ -30122,6 +30153,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. 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(),
@@ -30133,6 +30165,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.',
     arguments: (z) => ({
       query: z.string({ min: 2 }).describe("Keyword, phrase, or websearch expression; at least 2 characters."),
@@ -30142,6 +30175,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_issues",
+    example: { project: "AGENTC" },
     description: "List a project's issues for a roadmap or backlog pass: every issue in one project, each carrying " + "its status, priority, parent, labels, and open-ask count, so you can see backlog shape without " + "opening every issue. Optionally filter by status, parent, label, or how recently it changed. Do " + "not use it to search by keyword or phrase; dispatch_search remains the keyword surface. Rows are " + "capped at limit (default 50, max 250), applied to the response here, not by the server.",
     arguments: (z) => ({
       project: z.string().describe("Project key to list issues from."),
@@ -30154,6 +30188,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_architecture_sync",
+    example: { project: "CORE" },
     description: "Import a project's architecture model from its configured source repository now, instead of " + "waiting for the server's five-minute schedule. Returns the imported commit and component " + "count, or the recorded error when the model was rejected (the previous model stays up). " + "The source itself is configured by a human in Settings; 404 SOURCE_NOT_FOUND without one.",
     arguments: (z) => ({
       project: z.string().describe("Project key whose architecture source to sync, such as CORE.")
@@ -30162,6 +30197,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_open_asks",
+    example: {},
     description: "List active unanswered asks, oldest first, with age and whose reply is needed. Omit project to " + "see only this session's own authored asks (call before saying you are waiting for human input); " + "supply project to see every open ask across that project's issues and documents, whoever authored " + "them.",
     arguments: (z) => ({
       project: z.string().describe("Project key; when supplied, lists every open ask in the project instead of only this session's own.").optional()
@@ -30170,6 +30206,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_whoami",
+    example: {},
     description: "Who Dispatch takes this session for: {session, owner}. owner is the lowercase GitHub login of the human whose personal token you run under (the default assignee of issues you create), or null under the shared token.",
     arguments: () => ({}),
     strict: true
@@ -32260,9 +32297,11 @@ class ToolInputError extends Error {
   problems;
   constructor(tool, problems) {
     const count = problems.length;
+    const help = dispatchInputHelp(tool);
     super([
       `${tool} was not called: ${count} problem${count === 1 ? "" : "s"}`,
-      ...problems.map((problem) => `- ${problem}`)
+      ...problems.map((problem) => `- ${problem}`),
+      ...help === undefined ? [] : help.map((line) => `- ${line}`)
     ].join(`
 `));
     this.name = "ToolInputError";
@@ -32270,6 +32309,14 @@ class ToolInputError extends Error {
     this.problems = problems;
   }
 }
+function dispatchInputHelp(tool) {
+  const spec = dispatchToolSpecs.find((candidate) => candidate.name === tool);
+  if (spec === undefined)
+    return;
+  const schema = dispatchToolSchema(spec, zodSchemaApi(exports_external), { strict: true });
+  const allowed = Object.keys(shapeOf(schema) ?? {}).join(", ") || "none";
+  return [`Allowed keys: ${allowed}`, `Example: ${tool}(${JSON.stringify(spec.example)})`];
+}
 function unwrap(schema) {
   let current = schema;
   while (current !== undefined) {
@@ -32574,7 +32621,21 @@ function refTarget(ref, kind, id) {
   const ownerRef = ref.owner.kind === "issue" ? dispatchIssueRef(ref.owner.issue) : dispatchDocumentRef(ref.owner.project, `${ref.artifact}`);
   return dispatchChildRef(ownerRef, kind, id);
 }
-var uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var canonicalUUIDPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var compactUUIDPattern = /^[0-9a-f]{32}$/i;
+function normalizeUUID(value) {
+  let compact = value;
+  if (value.slice(0, 9).toLowerCase() === "urn:uuid:") {
+    compact = value.slice(9);
+  } else if (value.length === 38 && value.startsWith("{") && value.endsWith("}")) {
+    compact = value.slice(1, -1);
+  }
+  if (canonicalUUIDPattern.test(compact))
+    compact = compact.replaceAll("-", "");
+  if (!compactUUIDPattern.test(compact))
+    return;
+  return `${compact.slice(0, 8)}-${compact.slice(8, 12)}-${compact.slice(12, 16)}-${compact.slice(16, 20)}-${compact.slice(20)}`.toLowerCase();
+}
 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";
@@ -32587,12 +32648,13 @@ function messageIdOf(value) {
     const reference = parseDispatchRef(value);
     return reference?.kind === "message" ? reference.id : undefined;
   })() : value;
-  return id !== undefined && uuidPattern.test(id) ? id : undefined;
+  return id === undefined ? undefined : normalizeUUID(id);
 }
 var idPrefixPattern = /^[0-9a-f][0-9a-f-]{7,}$/i;
 async function resolveIdPrefix(tool, kind, ref, list) {
-  if (uuidPattern.test(ref.id))
-    return ref.id;
+  const fullID = normalizeUUID(ref.id);
+  if (fullID !== undefined)
+    return fullID;
   const ownerName = ref.owner.kind === "issue" ? ref.owner.issue : `${ref.owner.project}/${ref.artifact}`;
   if (!idPrefixPattern.test(ref.id)) {
     throw new ToolInputError(tool, [
@@ -32824,21 +32886,53 @@ async function resolveArtifact(client, owner, artifactReference) {
         return { owner, artifact };
       const names = artifacts.filter((candidate) => candidate.name === artifactReference);
       if (names.length > 1) {
-        throw new Error(`artifact name ${artifactReference} is ambiguous in project ${owner.project}; ` + `${names.length} documents share it \u2014 use its slug instead`);
+        throw new Error(documentReferenceProblem(artifactReference, names, "project", true));
+      }
+      if (names[0] === undefined) {
+        throw new Error(documentReferenceProblem(artifactReference, artifacts, "project"));
       }
-      if (names[0] === undefined)
-        throw error;
       return { owner, artifact: names[0] };
     }
   }
   const issue = await client.getIssue(owner.issue);
-  const artifact = artifactReference === undefined || artifactReference === "spec" ? issue.artifacts.find((candidate) => candidate.primary || candidate.id === issue.primary_artifact_id) : issue.artifacts.find((candidate) => candidate.id === artifactReference || candidate.slug === artifactReference || candidate.name === artifactReference);
+  let artifact;
+  if (artifactReference === undefined || artifactReference === "spec") {
+    artifact = issue.artifacts.find((candidate) => candidate.primary || candidate.id === issue.primary_artifact_id);
+  } else {
+    artifact = issue.artifacts.find((candidate) => candidate.id === artifactReference || candidate.slug === artifactReference);
+    if (artifact === undefined) {
+      const names = issue.artifacts.filter((candidate) => candidate.name === artifactReference);
+      if (names.length > 1) {
+        throw new Error(documentReferenceProblem(artifactReference, names, "issue", true));
+      }
+      artifact = names[0];
+    }
+  }
   if (!artifact) {
-    const slugs = issue.artifacts.map((candidate) => `${candidate.slug}${candidate.primary || candidate.id === issue.primary_artifact_id ? " (primary)" : ""}`);
-    throw new Error(`artifact "${artifactReference ?? "spec"}" was not found on issue ${issue.key}; artifacts: ${slugs.length === 0 ? "none" : slugs.join(", ")}`);
+    throw new Error(documentReferenceProblem(artifactReference ?? "spec", issue.artifacts, "issue"));
   }
   return { owner, issue, artifact };
 }
+var documentHintLimit = 8;
+function documentReferenceProblem(reference, documents, owner, ambiguous = false) {
+  const hints = documents.slice(0, documentHintLimit).map((document) => `${document.slug} (${document.name})`);
+  const list = hints.length === 0 ? "none" : hints.join(", ");
+  return ambiguous ? `"${reference}" names ${documents.length} documents on this ${owner}; use a slug: ${list}` : `document "${reference}" not found by slug; this ${owner}'s documents: ${list}`;
+}
+var askHintLimit = 8;
+function askIDInputProblem(asks, scope) {
+  const hints = asks.slice(0, askHintLimit).map((ask) => `${ask.id.slice(0, 8)}\u2026 ${textHead(ask.question)}`);
+  return `ask IDs are UUIDs; use the full ask ID; ${scope} open asks: ${hints.length === 0 ? "none" : hints.join(", ")}`;
+}
+async function invalidReplyToAskProblem(client, owner, resolved) {
+  if (owner.kind === "issue") {
+    const issue = resolved?.issue ?? await client.getIssue(owner.issue);
+    return askIDInputProblem(issue.open_asks, "this issue's");
+  }
+  if (resolved === undefined)
+    throw new Error("project document is missing its resolved artifact");
+  return askIDInputProblem(await client.getArtifactAsks(resolved.artifact.id, "open"), "this document's");
+}
 function anchor(artifact, args) {
   const quote = optionalString(args, "quote");
   if (quote === undefined)
@@ -33442,7 +33536,13 @@ ${followsAsk(askOwner)}`,
       const resolved = owner.kind === "project" || artifactReference === undefined ? owner.kind === "project" ? await resolveArtifact(client, owner, artifactReference) : undefined : await resolveArtifact(client, owner, artifactReference);
       const anchored = resolved ? anchor(resolved.artifact, args) : undefined;
       const replyTo = optionalString(args, "reply_to");
-      const replyToAsk = optionalString(args, "reply_to_ask");
+      const replyToAskReference = optionalString(args, "reply_to_ask");
+      const replyToAsk = replyToAskReference === undefined ? undefined : normalizeUUID(replyToAskReference);
+      if (replyToAskReference !== undefined && replyToAsk === undefined) {
+        throw new ToolInputError(input.tool, [
+          await invalidReplyToAskProblem(client, owner, resolved)
+        ]);
+      }
       const requestedTurn = optionalString(args, "turn");
       const commentInput = {
         body: stringArg(args, "body"),

package/dist/legion.js

@@ -16145,7 +16145,7 @@ import { logger } from "@oh-my-pi/pi-utils";
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion-envoy",
-  version: "1.51.1",
+  version: "1.51.2",
   type: "module",
   omp: {
     extensions: [
@@ -29227,6 +29227,7 @@ var DOC_EDIT_OPS = ["replace", "delete", "insert", "retype", "move"];
 var dispatchToolSpecs = [
   {
     name: "dispatch_issue",
+    example: { project: "DSP", title: "Native workspace" },
     description: "Create a native Dispatch issue for newly tracked work. Search first with dispatch_search; if potentially duplicate issues exist, this returns 409 POSSIBLE_DUPLICATE unless force is true after reading them. " + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       project: z.string().describe("Project key for the new issue."),
@@ -29243,6 +29244,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_issue_update",
+    example: { issue: "DSP-1", status: "in_progress" },
     description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, link a URL " + "(the pull request that delivers it, a run, a document), set its route, set or clear its parent, " + "or attach it to architecture components. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. external_links are " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link. components replaces the issue's own attachment and is allowed on a " + "closed issue. Priority is the human's and is not settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
@@ -29265,6 +29267,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_ask",
+    example: { issue: "DSP-1", question: "Ship this?" },
     description: "Open a durable, answerable decision on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. A to-do a human must complete is a question phrased as that to-do, with the options you want (for example Done / Can't). " + "Anchor a document question, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". A quote anchor is pinned to its block. Question is at most ${ASK_QUESTION_MAX} ` + `characters and has at most 8 options. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
@@ -29288,6 +29291,10 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_edit_ask",
+    example: {
+      ask: "01234567-0000-4000-8000-000000000001",
+      question: "Ship the revised plan?"
+    },
     description: "Edit an open question in place. Use it to correct or refine the same decision; retract the " + "old ask and open a new one when the decision itself changes. Previous text remains in the " + "event log. Only the asking session can edit it; answered or resolved asks cannot be edited.",
     arguments: (z) => ({
       ask: z.string().describe("Ask id to edit."),
@@ -29309,6 +29316,11 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_resolve_ask",
+    example: {
+      ask: "01234567-0000-4000-8000-000000000001",
+      kind: "retracted",
+      reason: "A newer question supersedes this one."
+    },
     description: "Retract an open question that is moot or resolve one after finding the answer. This closes the question without answering it.",
     arguments: (z) => ({
       ask: z.string().describe("Ask id to close."),
@@ -29318,6 +29330,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_resolve_comment",
+    example: { comment: "01234567-0000-4000-8000-000000000001" },
     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.")
@@ -29326,6 +29339,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_follow",
+    example: { ask: "01234567-0000-4000-8000-000000000001", action: "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>.>",
     arguments: (z) => ({
       ask: z.string().describe("Full ask id (uuid)."),
@@ -29335,6 +29349,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_comment",
+    example: { issue: "DSP-1", body: "Looks good." },
     description: "Add review feedback to an issue or project document quote, or reply to a question asked with dispatch_ask. " + "Do not use it for an exact replacement; use " + `dispatch_suggest instead. A quote anchor is pinned to its block. Body is at most 2,000 characters. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
@@ -29352,6 +29367,12 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_suggest",
+    example: {
+      issue: "DSP-1",
+      artifact: "spec",
+      quote: "old wording",
+      replace_with: "new wording"
+    },
     description: "Propose an exact replacement for quoted document text. Do not use it for general feedback; use " + `dispatch_comment instead. Optional explanation is at most 2,000 characters. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
@@ -29367,6 +29388,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_message",
+    example: { issue: "DSP-1", body: "Implementation started." },
     description: "Post a note humans must read now: a reply to a human's message, a deliverable that landed, or a blocker only " + "they can clear. Never progress or status updates - Dispatch is a high-signal record, not a log. Not a decision " + `(dispatch_ask) or document feedback (dispatch_comment). Body is at most 2,000 characters. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
@@ -29376,6 +29398,11 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_doc_edit",
+    example: {
+      issue: "DSP-1",
+      artifact: "spec",
+      ops: [{ op: "replace", find: "old", with: "new" }]
+    },
     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(),
@@ -29400,6 +29427,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_doc_read",
+    example: { issue: "DSP-1" },
     description: "Read a live document or a named document version. Do not use it for issue status, asks, or events; " + "use dispatch_read instead. Supply ref, issue, or project plus artifact; issue plus an omitted artifact reads the primary document. " + OWNER_REFERENCE,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
@@ -29412,6 +29440,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_request_approval",
+    example: { issue: "DSP-1" },
     description: "Ask a human to approve a document at its current version - the exception path for a spec " + "that departs from what was settled or proposes children, not a step for every issue. Opens an " + "approval ask (Approve / Request changes) in the human's Inbox; the answer pins a review to the " + "document version and arrives as artifact.approved or artifact.changes_requested. A later edit " + "makes an approval stale; request again for the new version. Idempotent while a request is open. " + OWNER_REFERENCE,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
@@ -29422,6 +29451,8 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_artifact",
+    example: { issue: "DSP-1", name: "design.md", content: `# Design
+` },
     description: "Attach a local file or inline text as an issue artifact or project document. Do not use it to edit a live document; use " + `dispatch_doc_edit instead. Exactly one of path or content is required; artifacts are limited to 25 MiB. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
@@ -29441,6 +29472,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. 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(),
@@ -29452,6 +29484,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.',
     arguments: (z) => ({
       query: z.string({ min: 2 }).describe("Keyword, phrase, or websearch expression; at least 2 characters."),
@@ -29461,6 +29494,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_issues",
+    example: { project: "AGENTC" },
     description: "List a project's issues for a roadmap or backlog pass: every issue in one project, each carrying " + "its status, priority, parent, labels, and open-ask count, so you can see backlog shape without " + "opening every issue. Optionally filter by status, parent, label, or how recently it changed. Do " + "not use it to search by keyword or phrase; dispatch_search remains the keyword surface. Rows are " + "capped at limit (default 50, max 250), applied to the response here, not by the server.",
     arguments: (z) => ({
       project: z.string().describe("Project key to list issues from."),
@@ -29473,6 +29507,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_architecture_sync",
+    example: { project: "CORE" },
     description: "Import a project's architecture model from its configured source repository now, instead of " + "waiting for the server's five-minute schedule. Returns the imported commit and component " + "count, or the recorded error when the model was rejected (the previous model stays up). " + "The source itself is configured by a human in Settings; 404 SOURCE_NOT_FOUND without one.",
     arguments: (z) => ({
       project: z.string().describe("Project key whose architecture source to sync, such as CORE.")
@@ -29481,6 +29516,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_open_asks",
+    example: {},
     description: "List active unanswered asks, oldest first, with age and whose reply is needed. Omit project to " + "see only this session's own authored asks (call before saying you are waiting for human input); " + "supply project to see every open ask across that project's issues and documents, whoever authored " + "them.",
     arguments: (z) => ({
       project: z.string().describe("Project key; when supplied, lists every open ask in the project instead of only this session's own.").optional()
@@ -29489,6 +29525,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_whoami",
+    example: {},
     description: "Who Dispatch takes this session for: {session, owner}. owner is the lowercase GitHub login of the human whose personal token you run under (the default assignee of issues you create), or null under the shared token.",
     arguments: () => ({}),
     strict: true

package/package.json

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