@sjawhar/pi-envoy 10.16.0 → 10.16.1

package/dist/dispatch.js

@@ -14335,11 +14335,11 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_read",
     example: { issue: "DSP-1" },
-    description: "Read an issue or project-document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + "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. " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
+    description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + "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. " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
-      artifact: z2.string().describe("Project document artifact id, slug, or filename.").optional(),
+      artifact: z2.string().describe("Document artifact id, slug, or filename: one of the issue's, or a project document.").optional(),
       ref: z2.string().describe("Optional dispatch:// issue or document reference.").optional(),
       message: z2.string().describe("A message id (uuid): reads the conversation it belongs to, the root message and every " + "reply. Name nothing else with it.").optional()
     }),
@@ -15585,6 +15585,8 @@ function parseDispatchRef(ref) {
         ...version3 === undefined ? {} : { version: Number(version3) }
       };
     }
+    if (version3 !== undefined)
+      return null;
     if (targetID === undefined || targetKind !== "ask" && targetKind !== "comment")
       return null;
     return {
@@ -16455,7 +16457,27 @@ function messageIdOf(value) {
 }
 var idPrefixPattern = /^[0-9a-f][0-9a-f-]{7,}$/i;
 function refOwnerName(ref) {
-  return ref.owner.kind === "issue" ? ref.owner.issue : `${ref.owner.project}/${ref.artifact}`;
+  return ref.owner.kind === "issue" ? ref.owner.issue : `${ref.owner.project}/${ref.artifact ?? ref.id}`;
+}
+async function refuseItemOffRef(tool, kind, ref, refText, item, documentId) {
+  if (ref.owner.kind === "issue") {
+    if (item.issue_key === ref.owner.issue)
+      return;
+  } else if (item.issue_key === null) {
+    const id = await documentId();
+    if ([
+      item.artifact_id,
+      item.anchor?.artifact_id,
+      item.block_artifact?.id,
+      item.approval?.artifact_id
+    ].includes(id)) {
+      return;
+    }
+  }
+  const where = item.issue_key === null ? "another document" : `${item.issue_key}; name it dispatch://${item.issue_key}/${kind}/${item.id}`;
+  throw new ToolInputError(tool, [
+    `${refText} names ${kind} ${item.id} on ${refOwnerName(ref)}, but it is on ${where}`
+  ]);
 }
 async function resolveIdPrefix(tool, kind, id, ownerName, list) {
   const fullID = normalizeUUID(id);
@@ -16528,7 +16550,17 @@ async function resolveAskArgument(tool, args, client, sessionId) {
       asks === undefined ? askIdShapeProblem : `${askIdShapeProblem}; ${openAskHints(asks)}`
     ]);
   }
-  return resolveIdPrefix(tool, "ask", id, "this session", () => sessionOpenAsks(client, sessionId));
+  const resolved = await resolveIdPrefix(tool, "ask", id, "this session", () => sessionOpenAsks(client, sessionId));
+  const reference = stringArg(args, "ask");
+  const ref = reference.startsWith("dispatch://") ? parseDispatchRef(reference) : null;
+  if (ref === null)
+    return { id: resolved };
+  const read = await client.getAsk(resolved);
+  await refuseItemOffRef(tool, "ask", ref, reference, read.ask, async () => {
+    const document = await resolveArtifact(client, ref.owner, ref.artifact, { canonical: true });
+    return document.artifact.id;
+  });
+  return { id: resolved, read };
 }
 function messageInReplyTo(args) {
   const inReplyTo = optionalString(args, "in_reply_to");
@@ -16552,14 +16584,14 @@ function argumentProblems(tool, args) {
     case "dispatch_follow": {
       const ask = optionalString(args, "ask");
       if (ask?.startsWith("dispatch://") && parseDispatchRef(ask)?.kind !== "ask") {
-        problems.push(askIdProblem);
+        problems.push(itemRefProblem(ask) ?? askIdProblem);
       }
       break;
     }
     case "dispatch_resolve_comment": {
       const comment = optionalString(args, "comment");
       if (comment?.startsWith("dispatch://") && parseDispatchRef(comment)?.kind !== "comment") {
-        problems.push(commentIdProblem);
+        problems.push(itemRefProblem(comment) ?? commentIdProblem);
       }
       break;
     }
@@ -16649,26 +16681,96 @@ function dispatchRefFromUrl(value, serverUrl) {
   if (!documentPage)
     return;
   const [, project, slug] = documentPage;
-  const document = `dispatch://${project}/artifact/${decodeURIComponent(slug ?? "")}${versionOf("version")}`;
+  const document = `dispatch://${project}/artifact/${decodeURIComponent(slug ?? "")}`;
   const item = itemFromSearch(url2.search);
   if (item === null)
     return;
-  return item === undefined ? document : `${document}/${item.kind}/${item.id}`;
+  return item === undefined ? `${document}${versionOf("version")}` : `${document}/${item.kind}/${item.id}`;
 }
 var refGrammarProblem = "ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/message/<uuid>, dispatch://KEY-1/artifact/<slug>, " + "dispatch://PROJECT/artifact/<document-ref> (an artifact id, slug, or filename), or " + "dispatch://agent/<session id>/artifact/<slug> (a picture in a conversation on the Agents page, " + "for dispatch doc-read); a dashboard URL on this Dispatch server is accepted too";
 var ownerRequiredProblem = "issue is required; supply issue or set LEGION_ISSUE";
 function innerRefProblem(tool, ref, refText) {
-  if (ref.kind !== "ask" && ref.kind !== "comment" && ref.kind !== "message")
+  if (ref.kind !== "ask" && ref.kind !== "comment" && ref.kind !== "message" && ref.kind !== "log" && ref.kind !== "children") {
     return;
+  }
   if (tool === "dispatch_read" || tool === "dispatch_ask")
     return;
   const owner = refOwnerName(ref);
   const documentTool = tool === "dispatch_suggest" || tool === "dispatch_doc_edit";
   const ownerArguments = ref.owner.kind === "issue" ? `issue ${ref.owner.issue}${documentTool ? " and artifact <the document's slug>" : ""}` : `project ${ref.owner.project} and artifact ${ref.artifact}`;
   const fix = tool === "dispatch_comment" && ref.kind === "ask" ? `reply under it with reply_to_ask ${ref.id} and ${ownerArguments}` : tool === "dispatch_comment" && ref.kind === "comment" ? `reply in its thread with reply_to ${ref.id} and ${ownerArguments}` : `read it with dispatch read, or name ${owner} with ${ownerArguments}`;
-  const item = ref.kind === "ask" ? "an ask" : `a ${ref.kind}`;
+  const item = ref.kind === "ask" ? "an ask" : ref.kind === "log" ? "the event log" : ref.kind === "children" ? "the children" : `a ${ref.kind}`;
   return `ref ${refText} names ${item} on ${owner}; dispatch ${commandName(tool)} would act on ${owner} and drop the ${ref.kind}: ${fix}`;
 }
+var documentItemPattern = /^dispatch:\/\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)\/artifact\/[^/@]+(?:@v\d+)?\/(ask|comment)\/([^/]+)$/;
+var versionedProjectItemPattern = /^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)@v\d+\/(ask|comment)\/([^/]+)$/;
+function itemRefProblem(value) {
+  const throughDocument = value.match(documentItemPattern);
+  if (throughDocument !== null) {
+    const [, issue2, kind, id] = throughDocument;
+    return `${value} names ${kind === "ask" ? "an ask" : "a comment"} through its document, which Dispatch does not address; name it dispatch://${issue2}/${kind}/${id}`;
+  }
+  const versioned = value.match(versionedProjectItemPattern);
+  if (versioned !== null) {
+    const [, project, slug, kind, id] = versioned;
+    const item = kind === "ask" ? "an ask" : "a comment";
+    return `${value} names ${item} at a document version, which ${item} does not have; name it dispatch://${project}/artifact/${slug}/${kind}/${id}`;
+  }
+  return;
+}
+function ownerConflictProblems(tool, args, parsedRef, refText) {
+  const problems = [];
+  const command = `dispatch ${commandName(tool)}`;
+  const issue2 = optionalString(args, "issue");
+  const project = optionalString(args, "project");
+  const artifact = optionalString(args, "artifact");
+  const version2 = optionalNumber(args, "version");
+  const ref = tool === "dispatch_ask" && (issue2 !== undefined || project !== undefined) ? null : parsedRef;
+  const refDocument = ref === null ? undefined : ref.owner.kind === "project" ? ref.artifact ?? ref.id : ref.kind === "spec" || ref.kind === "artifact" ? ref.id : undefined;
+  if (ref !== null && refText !== undefined) {
+    const refOwner = refOwnerName(ref);
+    if (issue2 !== undefined && (ref.owner.kind !== "issue" || nativeIssueKeyPattern.test(issue2) && issue2 !== ref.owner.issue)) {
+      problems.push(`issue ${issue2} and ref ${refText} name two owners; --ref ${refText} alone acts on ${refOwner}, and --issue ${issue2} alone acts on ${issue2}`);
+    }
+    if (project !== undefined && ref.owner.kind === "issue") {
+      problems.push(`project ${project} and ref ${refText} name two owners; --ref ${refText} alone acts on ${refOwner}, and --project ${project}${artifact === undefined ? "" : ` --artifact ${artifact}`} alone acts on that project document`);
+    }
+    if (tool !== "dispatch_ask" && project === undefined && artifact !== undefined && refDocument !== undefined && artifact !== refDocument) {
+      const owner = ref.owner.kind === "issue" ? `--issue ${ref.owner.issue}` : `--project ${ref.owner.project}`;
+      problems.push(`artifact ${artifact} and ref ${refText} name two documents; --ref ${refText} alone names ${refDocument}, and ${owner} --artifact ${artifact} names ${artifact}`);
+    }
+    if (tool === "dispatch_read" && project === undefined && artifact !== undefined && ref.owner.kind === "issue" && ref.kind !== "issue" && refDocument === undefined) {
+      problems.push(`ref ${refText} names no document, so dispatch read would read it and drop artifact ${artifact}: drop --artifact to read the ref, or read the document with --issue ${ref.owner.issue} --artifact ${artifact}`);
+    }
+    if (version2 !== undefined && ref.version !== undefined && version2 !== ref.version) {
+      problems.push(`version ${version2} and ref ${refText} name two versions; name the version once`);
+    }
+    if (ref.version !== undefined && (tool === "dispatch_comment" || tool === "dispatch_suggest" || tool === "dispatch_doc_edit")) {
+      problems.push(`${command} acts on the live document, so the version ref ${refText} names would be dropped: drop its @v${ref.version}`);
+    }
+    if (ref.version !== undefined && tool === "dispatch_read") {
+      problems.push(`dispatch read prints the live document's summary, so the version ref ${refText} names would be dropped: read that version with dispatch doc-read --ref ${refText}`);
+    }
+  }
+  const projectOwned = project !== undefined || ref?.owner.kind === "project";
+  if (tool === "dispatch_comment" && !projectOwned && optionalString(args, "quote") === undefined) {
+    const document = artifact ?? refDocument;
+    if (document !== undefined) {
+      problems.push(`${command} posts on the issue unless quote anchors it in a document, so document ${document} would be dropped: add --quote to comment on a passage of it, or name only the issue`);
+    }
+  }
+  if (tool === "dispatch_ask") {
+    const anchor = asObject(args.anchor);
+    const anchorArtifact = anchor === null ? undefined : optionalString(anchor, "artifact");
+    if (!projectOwned && artifact !== undefined && anchor === null) {
+      problems.push(`${command} opens the ask on the issue unless anchor quotes a document, so artifact ${artifact} would be dropped: add --anchor-json '${JSON.stringify({ artifact, quote: "<exact text>" })}' to ask about a passage of it, or drop --artifact`);
+    }
+    if (artifact !== undefined && anchorArtifact !== undefined && anchorArtifact !== artifact) {
+      problems.push(`artifact ${artifact} and anchor.artifact ${anchorArtifact} name two documents; name the document once`);
+    }
+  }
+  return problems;
+}
 var toolSchemas = new Map;
 function toolSchema(tool) {
   const cached2 = toolSchemas.get(tool);
@@ -16703,7 +16805,7 @@ async function resolveOwnerArguments(tool, input, cwd, env, exec, dashboardUrls,
     }
     ref = parseDispatchRef(refText);
     if (ref === null) {
-      problems.push(tool === "dispatch_ask" && !refText.startsWith("dispatch://") ? "ref must be a dispatch:// reference" : refGrammarProblem);
+      problems.push(itemRefProblem(refText) ?? (tool === "dispatch_ask" && !refText.startsWith("dispatch://") ? "ref must be a dispatch:// reference" : refGrammarProblem));
     } else {
       const inner = innerRefProblem(tool, ref, refText);
       if (inner !== undefined)
@@ -16713,7 +16815,9 @@ async function resolveOwnerArguments(tool, input, cwd, env, exec, dashboardUrls,
   const issueArgument = args.issue;
   const projectArgument = args.project;
   const artifactArgument = args.artifact;
-  const versionArgument = args.version;
+  const versionFromRef = tool === "dispatch_doc_read" && args.version === undefined ? ref?.version : undefined;
+  const refVersion = versionFromRef === undefined ? {} : { version: versionFromRef };
+  const ownerRef = tool === "dispatch_ask" && (issueArgument !== undefined || projectArgument !== undefined) ? null : ref;
   if (issueArgument !== undefined && projectArgument !== undefined) {
     problems.push("exactly one of issue and project is required");
   }
@@ -16721,45 +16825,47 @@ async function resolveOwnerArguments(tool, input, cwd, env, exec, dashboardUrls,
     if (!PROJECT_KEY_PATTERN.test(projectArgument)) {
       problems.push(`project is not a project key: ${PROJECT_KEY_RULE}`);
     }
-    const refDocument = ref?.owner.kind === "project" ? ref.artifact ?? ref.id : undefined;
-    if (ref?.owner.kind === "project" && (ref.owner.project !== projectArgument || artifactArgument !== undefined && artifactArgument !== refDocument)) {
+    const refDocument = ownerRef?.owner.kind === "project" ? ownerRef.artifact ?? ownerRef.id : undefined;
+    if (ownerRef?.owner.kind === "project" && (ownerRef.owner.project !== projectArgument || artifactArgument !== undefined && artifactArgument !== refDocument)) {
       problems.push("project and ref must name the same document");
     }
     return {
       args: {
         ...args,
         ...artifactArgument === undefined && refDocument !== undefined ? { artifact: refDocument } : {},
-        ...versionArgument === undefined && ref?.version !== undefined ? { version: ref.version } : {}
+        ...refVersion
       },
       ref,
       owner: { kind: "project", project: projectArgument }
     };
   }
-  if (ref?.owner.kind === "project") {
+  if (ownerRef?.owner.kind === "project") {
     return {
       args: {
         ...args,
-        project: ref.owner.project,
-        ...artifactArgument === undefined ? { artifact: ref.artifact ?? ref.id } : {},
-        ...versionArgument === undefined && ref.version !== undefined ? { version: ref.version } : {}
+        project: ownerRef.owner.project,
+        ...artifactArgument === undefined ? { artifact: ownerRef.artifact ?? ownerRef.id } : {},
+        ...refVersion
       },
       ref,
-      owner: ref.owner
+      owner: ownerRef.owner
     };
   }
-  if (issueArgument !== undefined || ref !== null) {
+  if (issueArgument !== undefined || ownerRef !== null) {
     const issue3 = typeof issueArgument === "string" ? canonicalExternalIssueRef(issueArgument) : ref?.owner.kind === "issue" ? ref.owner.issue : undefined;
     return {
       args: {
         ...args,
         ...issue3 === undefined ? {} : { issue: issue3 },
-        ...artifactArgument === undefined && (ref?.kind === "spec" || ref?.kind === "artifact") ? { artifact: ref.id } : {},
-        ...versionArgument === undefined && ref?.version !== undefined ? { version: ref.version } : {}
+        ...artifactArgument === undefined && tool !== "dispatch_ask" && (ref?.kind === "spec" || ref?.kind === "artifact") ? { artifact: ref.id } : {},
+        ...refVersion
       },
       ref,
       owner: issue3 === undefined ? null : { kind: "issue", issue: issue3 }
     };
   }
+  if (typeof args.ref === "string")
+    return { args, ref, owner: null };
   const replyTarget = args.in_reply_to;
   if (tool === "dispatch_message" && typeof replyTarget === "string" && !replyTarget.startsWith("dispatch://")) {
     return { args, ref, owner: null };
@@ -17480,7 +17586,9 @@ async function executeDispatchTool(input) {
   const exec = input.exec ?? defaultExec;
   const problems = [];
   const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec, input.config.publicUrl === undefined ? [configUrl] : [configUrl, input.config.publicUrl], problems);
-  const ownerMissing = issueFreeTools[input.tool] !== true && ownerArguments.owner === null;
+  const conflicts = issueFreeTools[input.tool] === true ? [] : ownerConflictProblems(input.tool, input.args, ownerArguments.ref, optionalString(ownerArguments.args, "ref"));
+  problems.push(...conflicts);
+  const ownerMissing = issueFreeTools[input.tool] !== true && (ownerArguments.owner === null || conflicts.length > 0);
   const schema = toolSchema(input.tool);
   const parsed = schema.safeParse(ownerArguments.args, { reportInput: true });
   if (!parsed.success) {
@@ -17530,6 +17638,13 @@ async function executeDispatchTool(input) {
     kind: "issue",
     issue: await resolveExistingIssue(client, ownerArguments.owner.issue)
   } : ownerArguments.owner;
+  const issueArgument = optionalString(input.args, "issue");
+  const refText = optionalString(ownerArguments.args, "ref");
+  if (input.tool !== "dispatch_ask" && owner?.kind === "issue" && issueArgument !== undefined && refText !== undefined && ownerArguments.ref?.owner.kind === "issue" && owner.issue !== ownerArguments.ref.owner.issue) {
+    throw new ToolInputError(input.tool, [
+      `issue ${issueArgument} and ref ${refText} name two owners; --ref ${refText} alone acts on ${ownerArguments.ref.owner.issue}, and --issue ${issueArgument} alone acts on ${owner.issue}`
+    ]);
+  }
   const issue2 = () => {
     if (owner?.kind !== "issue")
       throw new Error("issue is required");
@@ -17857,7 +17972,7 @@ async function executeDispatchTool(input) {
     }
     case "dispatch_resolve_ask": {
       const kind = stringArg(args, "kind");
-      const id = await resolveAskArgument(input.tool, args, client, input.sessionId);
+      const { id } = await resolveAskArgument(input.tool, args, client, input.sessionId);
       const ask = await client.resolveAsk(id, {
         kind,
         reason: stringArg(args, "reason"),
@@ -17883,6 +17998,10 @@ async function executeDispatchTool(input) {
         document = artifact;
         id = await resolveIdPrefix(input.tool, "comment", ref.id, refOwnerName(ref), () => client.getArtifactComments(artifact.id));
       }
+      if (ref !== null) {
+        const read = await client.getComment(id);
+        await refuseItemOffRef(input.tool, "comment", ref, reference, read.comment, async () => document === undefined ? "" : document.id);
+      }
       const comment = await client.resolveComment(id, actor);
       const { label, details } = await commentOwnerResult(client, comment, document);
       return { text: `Resolved comment ${comment.id} on ${label}.`, details };
@@ -17935,7 +18054,7 @@ ${await followsAsk(askOwner, input.subscriptions)}`,
       const options = args.options;
       const multiple = optionalBoolean(args, "multiple");
       const urgency = askUrgency(args);
-      const id = await resolveAskArgument(input.tool, args, client, input.sessionId);
+      const { id } = await resolveAskArgument(input.tool, args, client, input.sessionId);
       const ask = await client.editAsk(id, {
         ...question === undefined ? {} : { question },
         ...Array.isArray(options) ? { options } : {},
@@ -18264,13 +18383,13 @@ ${trailer.join(`
       const sessionId = input.sessionId?.trim();
       if (!sessionId)
         throw new Error("host session id is required for dispatch follow");
-      const ask = await resolveAskArgument(input.tool, args, client, sessionId);
+      const { id: ask, read: refRead } = await resolveAskArgument(input.tool, args, client, sessionId);
       const action = stringArg(args, "action");
       if (action === "unfollow") {
         await client.unfollowAsk(ask, sessionId, actor);
         return { text: `Unfollowed ask ${ask}.`, details: { ask } };
       }
-      const read = await client.getAsk(ask);
+      const read = refRead ?? await client.getAsk(ask);
       await client.followAsk(ask, sessionId, actor);
       return {
         text: `Following ask ${ask}: its answer and replies reach this session directly.`,
@@ -18304,9 +18423,15 @@ ${trailer.join(`
           ...showImages(pictures3)
         };
       }
+      let refDocumentId;
+      const documentIdOf = (ref) => {
+        refDocumentId ??= resolveDocument(ref.owner, ref.artifact).then((resolved) => resolved.artifact.id);
+        return refDocumentId;
+      };
       if (ownerArguments.ref?.kind === "ask") {
         const ref = ownerArguments.ref;
-        const askRead = await readAskRef(input.tool, ref.id, refOwnerName(ref), client, async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks((await resolveDocument(ref.owner, ref.artifact)).artifact.id, "all"));
+        const askRead = await readAskRef(input.tool, ref.id, refOwnerName(ref), client, async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks(await documentIdOf(ref), "all"));
+        await refuseItemOffRef(input.tool, "ask", ref, stringArg(args, "ref"), askRead.ask, () => documentIdOf(ref));
         const askRef = refTarget(ref, "ask", askRead.ask.id);
         const [pictures3, graph2] = await Promise.all([
           picturesOf(askTexts(askRead)),
@@ -18320,8 +18445,9 @@ ${trailer.join(`
       }
       if (ownerArguments.ref?.kind === "comment") {
         const ref = ownerArguments.ref;
-        const id = await resolveIdPrefix(input.tool, "comment", ref.id, refOwnerName(ref), async () => ref.owner.kind === "issue" ? client.getComments(ref.owner.issue) : client.getArtifactComments((await resolveDocument(ref.owner, ref.artifact)).artifact.id));
+        const id = await resolveIdPrefix(input.tool, "comment", ref.id, refOwnerName(ref), async () => ref.owner.kind === "issue" ? client.getComments(ref.owner.issue) : client.getArtifactComments(await documentIdOf(ref)));
         const comment = await client.getComment(id);
+        await refuseItemOffRef(input.tool, "comment", ref, stringArg(args, "ref"), comment.comment, () => documentIdOf(ref));
         const commentRef = refTarget(ref, "comment", id);
         const [pictures3, graph2] = await Promise.all([
           picturesOf(datedBodies([comment.comment, ...comment.replies])),
@@ -18349,21 +18475,28 @@ ${trailer.join(`
           ...showImages(pictures3)
         };
       }
-      if (documentOwner().kind === "project") {
-        const resolved = await resolveDocument(documentOwner(), stringArg(args, "artifact"));
-        const documentRef = dispatchDocumentRef(resolved.artifact.project, resolved.artifact.slug);
+      const documentReference = optionalString(args, "artifact");
+      if (documentOwner().kind === "project" || documentReference !== undefined) {
+        const resolved = await resolveDocument(documentOwner(), documentReference);
+        const { artifact } = resolved;
+        const ownerKey = resolved.issue?.key ?? artifact.project;
+        const documentRef = dispatchDocumentRef(ownerKey, artifact.slug);
+        const approval = approvalLine(artifact);
         return {
           text: [
-            `Document: ${resolved.artifact.project} / ${resolved.artifact.name}`,
+            `Document: ${ownerKey} / ${artifact.name}`,
+            ...resolved.issue === undefined ? [] : [
+              `Issue: ${resolved.issue.key} [${resolved.issue.status}] ${resolved.issue.title}`
+            ],
             `Reference: ${documentRef}`,
-            `Versions: ${resolved.artifact.versions.length}`,
-            ...approvalLine(resolved.artifact) === undefined ? [] : [approvalLine(resolved.artifact)],
+            `Versions: ${artifact.versions.length}`,
+            ...approval === undefined ? [] : [approval],
             ...await graphSections(client, documentRef)
           ].join(`
 `),
           details: {
-            project: resolved.artifact.project,
-            document: documentLabel(resolved.artifact.project, resolved.artifact.slug)
+            ...resolved.issue === undefined ? { project: artifact.project } : { issue: resolved.issue.key },
+            document: documentLabel(ownerKey, artifact.slug)
           }
         };
       }

package/dist/envoy.js

@@ -30322,11 +30322,11 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_read",
     example: { issue: "DSP-1" },
-    description: "Read an issue or project-document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + "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. " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
+    description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + "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. " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
-      artifact: z2.string().describe("Project document artifact id, slug, or filename.").optional(),
+      artifact: z2.string().describe("Document artifact id, slug, or filename: one of the issue's, or a project document.").optional(),
       ref: z2.string().describe("Optional dispatch:// issue or document reference.").optional(),
       message: z2.string().describe("A message id (uuid): reads the conversation it belongs to, the root message and every " + "reply. Name nothing else with it.").optional()
     }),
@@ -31335,6 +31335,8 @@ function parseDispatchRef(ref) {
         ...version3 === undefined ? {} : { version: Number(version3) }
       };
     }
+    if (version3 !== undefined)
+      return null;
     if (targetID === undefined || targetKind !== "ask" && targetKind !== "comment")
       return null;
     return {

package/dist/skills/dispatch/references/reading.md

@@ -4,7 +4,7 @@ Read this to catch up after a restart, read a node, trace what cites it, or writ
 
 ## What comes back
 
-- After a restart, catch up with `dispatch read --issue <KEY>` (or `--project` with `--artifact`, or `--ref`). It prints the issue's summary, open asks, references and recent events, or an ask's, comment's or message's thread. Reads do not subscribe. Use `dispatch doc-read` for document text.
+- After a restart, catch up with `dispatch read --issue <KEY>` (or `--artifact` with `--issue` or `--project`, or `--ref`). It prints the issue's summary, open asks, references and recent events, a document's summary (its issue, reference, versions and approval), or an ask's, comment's or message's thread. Reads do not subscribe. Use `dispatch doc-read` for document text.
 - An anchored comment or ask prints `Position:`, where its quote's block stands. `unavailable (DOC_SERVICE_UNAVAILABLE)` means try again shortly. `unavailable (DOC_SCHEMA)` means the document needs repair.
 - The API gives the same facts as `anchor_block` (or `anchor_block_error`) on `GET /api/v1/comments/{id}` and `GET /api/v1/asks/{id}`. `GET /api/v1/artifacts/{id}/blocks/{block_id}` gives them for any block.
 - Each read ends with `Referenced by:` (what cites the node) and `Links:` (what it cites), across projects. "What led to this decision" is one read on the ask.
@@ -28,3 +28,4 @@ dispatch://PROJECT/artifact/<document-ref>/comment/<id>
 - A reference renders as a link titled by its target. A body that is only a reference gets an unfurl card.
 - A bare UUID or `KEY#seq` is not a reference. `dispatch read` also takes a dashboard URL, also on the public dashboard when `DISPATCH_PUBLIC_URL` names one. An issue read prints its `Link:`: hand that to a person.
 - An ask or comment id can be a unique 8+ hex prefix. A message id is always the full UUID.
+- An ask or comment on an issue's document is `dispatch://KEY/ask/<id>` or `dispatch://KEY/comment/<id>`, never written through its document.

package/dist/skills/dispatch-first/SKILL.md

@@ -18,7 +18,7 @@ dispatch search --query 'reviewer threads OR review comments'
 ```
 
 - No hits: drop a word before you add one. Try two or three wordings (the component's name, the symptom, the fix) before you conclude that nothing exists.
-- Open each hit that could be yours with `dispatch read`, then its parent (the `child_of` row under `Links:`). The parent's children and the `Components:` line show where the rest of the work is.
+- Open each hit that could be yours with `dispatch read`, then its parent (the `child_of` row under `Links:`; a document hit names its issue on `Issue:`). The parent's children and the `Components:` line show where the rest of the work is.
 
 ## What to do with what you find
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-envoy",
-  "version": "10.16.0",
+  "version": "10.16.1",
   "license": "Apache-2.0",
   "type": "module",
   "omp": {