@sjawhar/pi-legion-envoy 1.51.1 → 1.52.0

package/dist/envoy.js

@@ -29726,6 +29726,24 @@ var AskEditedEventPayloadSchema = object({
   }),
   edited_by: object({ kind: string2(), id: string2() }).passthrough()
 });
+var CommentMentionSchema = object({
+  target: string2(),
+  delivery: _enum2(DELIVERY_CAPABILITIES),
+  session_id: string2().nullable()
+});
+var CommentDeliverySchema = object({
+  comment_id: string2(),
+  target: string2(),
+  attempt: number2().int().positive(),
+  delivery: _enum2(DELIVERY_CAPABILITIES),
+  session_id: string2().nullable(),
+  envelope_id: string2().nullable(),
+  state: _enum2(["pending", "sent", "failed"]),
+  error: string2().nullable(),
+  resolve_error: string2().nullable(),
+  reply_id: string2().nullable(),
+  created_at: string2()
+});
 var CommentEventPayloadSchema = object({
   id: string2().optional(),
   artifact_name: string2().optional(),
@@ -29741,7 +29759,9 @@ var CommentEventPayloadSchema = object({
   anchor: object({ block_id: string2().nullable().optional(), quote: string2().optional() }).nullish(),
   suggestion: object({ replace_with: string2().optional() }).nullish(),
   author: object({ kind: string2(), id: string2() }).optional(),
-  created_at: string2().optional()
+  created_at: string2().optional(),
+  mentions: array(CommentMentionSchema).optional(),
+  deliveries: array(CommentDeliverySchema).optional()
 });
 var MessageEventPayloadSchema = object({
   id: string2().optional(),
@@ -29751,8 +29771,9 @@ var MessageEventPayloadSchema = object({
   reply_body: string2().optional(),
   author: object({ kind: string2(), id: string2() }).optional()
 });
+var DispatchTargetedResourceIDSchema = uuid2();
 var DispatchTargetedMessagePayloadSchema = MessageEventPayloadSchema.extend({
-  id: string2(),
+  id: DispatchTargetedResourceIDSchema,
   issue_key: string2().nullable(),
   author: object({ kind: string2(), id: string2() }),
   body: string2(),
@@ -29761,6 +29782,31 @@ var DispatchTargetedMessagePayloadSchema = MessageEventPayloadSchema.extend({
   deliveries: array(unknown()),
   created_at: string2()
 });
+var DispatchTargetedCommentPayloadSchema = CommentEventPayloadSchema.extend({
+  id: DispatchTargetedResourceIDSchema,
+  issue_key: string2().nullable(),
+  artifact_id: string2().nullable(),
+  author: object({ kind: string2(), id: string2() }),
+  body: string2(),
+  reply_to: string2().nullable(),
+  ask_id: string2().nullable(),
+  mentions: array(CommentMentionSchema),
+  deliveries: array(CommentDeliverySchema),
+  created_at: string2(),
+  artifact_name: string2()
+});
+var DispatchTargetedMessageDeliverySchema = object({
+  attempt: number2().int().positive(),
+  mode: _enum2(DELIVERY_CAPABILITIES)
+});
+var DispatchTargetedCommentDeliverySchema = DispatchTargetedMessageDeliverySchema.extend({
+  comment_id: DispatchTargetedResourceIDSchema,
+  target: string2()
+});
+var DispatchTargetedDeliverySchema = union([
+  DispatchTargetedCommentDeliverySchema,
+  DispatchTargetedMessageDeliverySchema
+]);
 var MessageDeliveryEventPayloadSchema = object({
   message_id: string2().optional(),
   attempt: number2().int().positive().optional(),
@@ -29908,6 +29954,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 +29971,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 +29994,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 +30018,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 +30043,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 +30057,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 +30066,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 +30076,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 +30094,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 +30115,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 +30125,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 +30154,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 +30167,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 +30178,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 +30199,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 +30211,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 +30221,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 +30234,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 +30243,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 +30252,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
@@ -31290,13 +31373,18 @@ var TolerantInboundEnvelopeSchema = object({
   source: InboundEnvelopeSchema.shape.source.optional().catch(undefined),
   sender: object(tolerantShape(InboundSenderSchema.shape)).optional().catch(undefined)
 }).passthrough();
+function dispatchReplyPath(resource, id) {
+  const collection = resource === "message" ? "messages" : "comments";
+  return `/api/v1/${collection}/${encodeURIComponent(id)}/reply`;
+}
 async function postDeliveryReply(config, sessionId, delivery, result) {
-  const response = await fetch(`${config.url}/api/v1/messages/${delivery.messageID}/reply`, {
+  const response = await fetch(`${config.url}${dispatchReplyPath(delivery.resource, delivery.id)}`, {
     method: "POST",
     headers: { Authorization: `Bearer ${config.token}`, "Content-Type": "application/json" },
     body: JSON.stringify({
       actor: { kind: "session", id: sessionId },
       attempt: delivery.attempt,
+      ...delivery.replyFields,
       ...result
     })
   });
@@ -31315,21 +31403,32 @@ function rememberBounded(seen, key, limit) {
       seen.delete(oldest.value);
   }
 }
-var DispatchDeliveryRequestSchema = object({
-  attempt: number2().int().positive(),
-  mode: _enum2(DELIVERY_CAPABILITIES)
-});
+function isCommentTargetedDelivery(delivery) {
+  return "comment_id" in delivery;
+}
 var DispatchTargetedFrameSchema = object({
   event: DispatchEventSchema,
-  delivery: DispatchDeliveryRequestSchema
-}).refine(({ event }) => event.type === "message.created" && DispatchTargetedMessagePayloadSchema.safeParse(event.payload).success, { message: "targeted delivery requires a message.created event" });
+  delivery: DispatchTargetedDeliverySchema
+}).superRefine(({ event, delivery }, context) => {
+  if (event.type === "message.created" && !isCommentTargetedDelivery(delivery) && DispatchTargetedMessagePayloadSchema.safeParse(event.payload).success) {
+    return;
+  }
+  if (event.type === "comment.created" && isCommentTargetedDelivery(delivery) && DispatchTargetedCommentPayloadSchema.safeParse(event.payload).success) {
+    return;
+  }
+  context.addIssue({
+    code: "custom",
+    message: event.type === "comment.created" ? "targeted delivery requires a complete comment.created event" : "targeted delivery requires a complete message.created event"
+  });
+});
 var RecoverableDispatchDeliveryFailureSchema = object({
   event: object({
+    type: _enum2(["message.created", "comment.created"]),
     issue_key: string2().nullable(),
     payload: object({ id: string2(), body: string2().optional() }).passthrough()
   }).passthrough(),
-  delivery: DispatchDeliveryRequestSchema
-});
+  delivery: DispatchTargetedDeliverySchema
+}).refine(({ event, delivery }) => event.type === "comment.created" ? isCommentTargetedDelivery(delivery) : !isCommentTargetedDelivery(delivery) && DispatchTargetedResourceIDSchema.safeParse(event.payload.id).success, { message: "delivery resource must match its event type" });
 function senderLabel(envelope) {
   const sender = envelope.source_session ?? envelope.source ?? "unknown";
   return envelope.sender?.title === undefined ? sender : `${sender} (${envelope.sender.title})`;
@@ -31474,12 +31573,19 @@ function parseDispatchFrame(rawPayload) {
     }
     const recoverable = RecoverableDispatchDeliveryFailureSchema.safeParse(value);
     if (recoverable.success) {
+      const delivery = recoverable.data.delivery;
+      const commentDelivery = isCommentTargetedDelivery(delivery);
+      const resource = commentDelivery ? "comment" : "message";
+      const id = commentDelivery ? delivery.comment_id : recoverable.data.event.payload.id;
       return {
         raw: value,
         rejectedDelivery: {
-          attempt: recoverable.data.delivery.attempt,
-          mode: recoverable.data.delivery.mode,
-          messageID: recoverable.data.event.payload.id,
+          resource,
+          id,
+          attempt: delivery.attempt,
+          mode: delivery.mode,
+          replyPath: dispatchReplyPath(resource, id),
+          replyFields: commentDelivery ? { target: delivery.target } : {},
           issueKey: recoverable.data.event.issue_key,
           body: recoverable.data.event.payload.body ?? ""
         },
@@ -31596,15 +31702,18 @@ function renderInbound(raw, sessionID, subject) {
         }
         dispatchReply = dispatchCommentReplyWith(frame.event, topic, commentPayload);
         if (frame.event.type === "message.created") {
-          const message = MessageEventPayloadSchema.safeParse(frame.event.payload);
-          const requested = DispatchDeliveryRequestSchema.safeParse(frame.delivery);
-          if (message.success && requested.success && message.data.id !== undefined) {
+          const message = DispatchTargetedMessagePayloadSchema.safeParse(frame.event.payload);
+          const requested = DispatchTargetedDeliverySchema.safeParse(frame.delivery);
+          if (message.success && requested.success && !isCommentTargetedDelivery(requested.data)) {
             delivery = {
+              resource: "message",
+              id: message.data.id,
               attempt: requested.data.attempt,
               mode: requested.data.mode,
-              messageID: message.data.id,
+              replyPath: dispatchReplyPath("message", message.data.id),
+              replyFields: {},
               issueKey: frame.event.issue_key,
-              body: message.data.body ?? envelope.payload_summary ?? ""
+              body: message.data.body
             };
             if (frame.event.issue_key !== null) {
               dispatchReply = {
@@ -31613,6 +31722,21 @@ function renderInbound(raw, sessionID, subject) {
               };
             }
           }
+        } else if (frame.event.type === "comment.created") {
+          const comment = DispatchTargetedCommentPayloadSchema.safeParse(frame.event.payload);
+          const requested = DispatchTargetedDeliverySchema.safeParse(frame.delivery);
+          if (comment.success && requested.success && isCommentTargetedDelivery(requested.data)) {
+            delivery = {
+              resource: "comment",
+              id: requested.data.comment_id,
+              attempt: requested.data.attempt,
+              mode: requested.data.mode,
+              replyPath: dispatchReplyPath("comment", requested.data.comment_id),
+              replyFields: { target: requested.data.target },
+              issueKey: frame.event.issue_key,
+              body: comment.data.body
+            };
+          }
         }
         dispatchEvent = {
           owner: dispatchOwner(frame.event, topic),
@@ -32260,9 +32384,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 +32396,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 +32708,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 +32735,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 +32973,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 +33623,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"),
@@ -34370,7 +34557,7 @@ function envoyExtension(pi) {
       }
       try {
         if (rendered.rejectedDelivery !== undefined) {
-          console.warn(`[envoy] rejecting malformed Dispatch targeted delivery ${rendered.rejectedDelivery.messageID}`);
+          console.warn(`[envoy] rejecting malformed Dispatch targeted delivery ${rendered.rejectedDelivery.id}`);
           await postDispatchReply(rendered.rejectedDelivery, {
             error: "Invalid Dispatch targeted delivery frame"
           });

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.52.0",
   type: "module",
   omp: {
     extensions: [
@@ -29045,6 +29045,24 @@ var AskEditedEventPayloadSchema = object({
   }),
   edited_by: object({ kind: string2(), id: string2() }).passthrough()
 });
+var CommentMentionSchema = object({
+  target: string2(),
+  delivery: _enum2(DELIVERY_CAPABILITIES),
+  session_id: string2().nullable()
+});
+var CommentDeliverySchema = object({
+  comment_id: string2(),
+  target: string2(),
+  attempt: number2().int().positive(),
+  delivery: _enum2(DELIVERY_CAPABILITIES),
+  session_id: string2().nullable(),
+  envelope_id: string2().nullable(),
+  state: _enum2(["pending", "sent", "failed"]),
+  error: string2().nullable(),
+  resolve_error: string2().nullable(),
+  reply_id: string2().nullable(),
+  created_at: string2()
+});
 var CommentEventPayloadSchema = object({
   id: string2().optional(),
   artifact_name: string2().optional(),
@@ -29060,7 +29078,9 @@ var CommentEventPayloadSchema = object({
   anchor: object({ block_id: string2().nullable().optional(), quote: string2().optional() }).nullish(),
   suggestion: object({ replace_with: string2().optional() }).nullish(),
   author: object({ kind: string2(), id: string2() }).optional(),
-  created_at: string2().optional()
+  created_at: string2().optional(),
+  mentions: array(CommentMentionSchema).optional(),
+  deliveries: array(CommentDeliverySchema).optional()
 });
 var MessageEventPayloadSchema = object({
   id: string2().optional(),
@@ -29070,8 +29090,9 @@ var MessageEventPayloadSchema = object({
   reply_body: string2().optional(),
   author: object({ kind: string2(), id: string2() }).optional()
 });
+var DispatchTargetedResourceIDSchema = uuid2();
 var DispatchTargetedMessagePayloadSchema = MessageEventPayloadSchema.extend({
-  id: string2(),
+  id: DispatchTargetedResourceIDSchema,
   issue_key: string2().nullable(),
   author: object({ kind: string2(), id: string2() }),
   body: string2(),
@@ -29080,6 +29101,31 @@ var DispatchTargetedMessagePayloadSchema = MessageEventPayloadSchema.extend({
   deliveries: array(unknown()),
   created_at: string2()
 });
+var DispatchTargetedCommentPayloadSchema = CommentEventPayloadSchema.extend({
+  id: DispatchTargetedResourceIDSchema,
+  issue_key: string2().nullable(),
+  artifact_id: string2().nullable(),
+  author: object({ kind: string2(), id: string2() }),
+  body: string2(),
+  reply_to: string2().nullable(),
+  ask_id: string2().nullable(),
+  mentions: array(CommentMentionSchema),
+  deliveries: array(CommentDeliverySchema),
+  created_at: string2(),
+  artifact_name: string2()
+});
+var DispatchTargetedMessageDeliverySchema = object({
+  attempt: number2().int().positive(),
+  mode: _enum2(DELIVERY_CAPABILITIES)
+});
+var DispatchTargetedCommentDeliverySchema = DispatchTargetedMessageDeliverySchema.extend({
+  comment_id: DispatchTargetedResourceIDSchema,
+  target: string2()
+});
+var DispatchTargetedDeliverySchema = union([
+  DispatchTargetedCommentDeliverySchema,
+  DispatchTargetedMessageDeliverySchema
+]);
 var MessageDeliveryEventPayloadSchema = object({
   message_id: string2().optional(),
   attempt: number2().int().positive().optional(),
@@ -29227,6 +29273,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 +29290,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 +29313,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 +29337,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 +29362,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 +29376,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 +29385,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 +29395,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 +29413,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 +29434,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 +29444,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 +29473,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 +29486,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 +29497,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 +29518,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 +29530,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 +29540,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 +29553,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 +29562,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 +29571,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.52.0",
   "type": "module",
   "omp": {
     "extensions": [