@sjawhar/opencode-legion-envoy 5.8.2 → 5.9.1

package/dist/src/server.js

@@ -13886,6 +13886,21 @@ function snippetSegments(snippet) {
 function snippetText(snippet) {
   return snippetSegments(snippet).map(({ text, mark }) => mark ? `**${text}**` : text).join("");
 }
+// ../contracts/src/dispatch-text-rules.ts
+var SESSION_ID_PATTERN = "[^/?#\\s\\p{Z}\\p{Cc}<>\"'`\\[\\]|]+";
+var sessionIdOnly = new RegExp(`^${SESSION_ID_PATTERN}$`, "u");
+function pictureCaption(name) {
+  return name.replace(/[\\[\]`]/g, "\\$&").replace(/\s+/g, " ");
+}
+var PICTURE_TYPES = {
+  "image/png": true,
+  "image/jpeg": true,
+  "image/gif": true,
+  "image/webp": true
+};
+function isPictureType(mime) {
+  return PICTURE_TYPES[mime] === true;
+}
 // ../contracts/src/dispatch-tools.ts
 function dispatchToolSchema(spec, z2, opts) {
   const shape = spec.arguments(z2);
@@ -13959,8 +13974,12 @@ function componentsArgument(z2) {
   }).describe("Attach the issue to architecture components. Attach the root before decomposing it; children inherit unless they choose.");
 }
 var SPEC_WRITING_POINTER = 'Write a spec as the "Writing a spec" section of skill://dispatch says.';
+function imagesArgument(z2, owner, cap) {
+  return z2.array(z2.string({ min: 1 }), { min: 1 }).describe(`Optional local picture files to show inline: PNG, JPEG, GIF or WebP (by their bytes, not their name), each at most 25 MiB. Each is uploaded to ${owner} and appended after a blank line as one ![<file name>](dispatch://\u2026@vN) line, in this order; those lines count toward ${cap}.`).optional();
+}
 var ASK_URGENCIES = ["low", "med", "high", "blocking"];
 var ASK_QUESTION_MAX = 800;
+var DISPATCH_BODY_MAX = 2000;
 var SEARCH_QUERY_MAX = 1000;
 var SEARCH_QUERY_HINT = "search with a short phrase of a few words, not a passage";
 var SEARCH_KIND_DEPTH = 100;
@@ -14060,7 +14079,7 @@ var dispatchToolSpecs = [
         }
       ]
     },
-    description: "Open a to-do or permission only a human can give, or a decision that has no document to " + "live in. A question about the design an issue's document records is not this tool: write " + "it into that document as a decision block (dispatch_doc_edit inserting an ask block at the " + "end of the section it concerns), at every phase, approved spec or not; the block reaches " + "the Inbox and its answer lands next to its context. Never give an ask an Approve option: a " + "document is approved through dispatch_request_approval. Do not use this tool for a status " + "update or discussion; use dispatch_message instead. " + ASK_QUESTION_CONTRACT + " " + ASK_OPTIONS_CONTRACT + " For an action only a human can perform, state what it changes and risks as constraints. " + "Anything that requires a human to do, including a credential or grant renewal, is an ask, " + "never a message. " + "Anchor a to-do about a document passage, 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}`,
+    description: "Open a to-do or permission only a human can give, or a decision that has no document to " + "live in. A question about the design an issue's document records is not this tool: write " + "it into that document as a decision block (dispatch_doc_edit inserting an ask block at the " + "end of the section it concerns), at every phase, approved spec or not; the block reaches " + "the Inbox and its answer lands next to its context. Never give an ask an Approve option: a " + "document is approved through dispatch_request_approval. Do not use this tool for a status " + "update or discussion; use dispatch_message instead. " + ASK_QUESTION_CONTRACT + " " + ASK_OPTIONS_CONTRACT + " For an action only a human can perform, state what it changes and risks as constraints. " + "Anything that requires a human to do, including a credential or grant renewal, is an ask, " + "never a message. " + "Anchor a to-do about a document passage, 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, ` + `the lines images appends included, and has at most 8 options. ${OWNER_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
@@ -14077,7 +14096,8 @@ var dispatchToolSpecs = [
         artifact: z2.string().describe("Artifact slug or id containing the quoted text."),
         quote: z2.string().describe("Exact text the decision concerns."),
         occurrence: z2.number({ int: true, min: 0 }).describe("Zero-based occurrence of the quote.").optional()
-      }).describe("Optional document location for the question.").optional()
+      }).describe("Optional document location for the question.").optional(),
+      images: imagesArgument(z2, "the issue (or the project document's project)", `the ${ASK_QUESTION_MAX}-character question limit`)
     }),
     validation: documentOwnerValidation(true)
   },
@@ -14152,7 +14172,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}`,
+    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, the lines images appends included. ${OWNER_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
@@ -14160,10 +14180,11 @@ var dispatchToolSpecs = [
       ref: z2.string().describe("Optional dispatch:// issue or document reference.").optional(),
       quote: z2.string().describe("Optional exact quoted document text.").optional(),
       occurrence: z2.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional(),
-      body: z2.string({ max: 2000 }).describe("Review comment, at most 2,000 characters."),
+      body: z2.string({ max: DISPATCH_BODY_MAX }).describe("Review comment, at most 2,000 characters."),
       reply_to: z2.string().describe("A comment id (uuid); replying to any comment in a thread continues that thread (an " + "ask's clarification thread included). To reply to an ask, use reply_to_ask with the " + "ask id instead.").optional(),
       reply_to_ask: z2.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional(),
-      turn: z2.enum(["agent", "human"]).describe("Only with reply_to_ask: who holds the turn after this reply. agent: a progress note - " + "you keep the turn and the ask stays 'Waiting on agents' for the human; human (default): " + "you need the human to act - the ask returns to 'Waiting on you'.").optional()
+      turn: z2.enum(["agent", "human"]).describe("Only with reply_to_ask: who holds the turn after this reply. agent: a progress note - " + "you keep the turn and the ask stays 'Waiting on agents' for the human; human (default): " + "you need the human to act - the ask returns to 'Waiting on you'.").optional(),
+      images: imagesArgument(z2, "the issue (or the project document's project)", "the 2,000-character body limit")
     }),
     validation: commentValidation
   },
@@ -14191,11 +14212,12 @@ 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 or a deliverable that landed. A to-do only a human can " + "complete is an ask (dispatch_ask), so it reaches their inbox. Never progress or status updates - Dispatch is a high-signal " + "record, not a log. Not a design decision (write it as a decision block in the document) or document feedback (dispatch_comment). " + "To answer a human's direct message to this session - one sent from the Agents page, which names no issue - pass that message's bare id as " + "in_reply_to and no issue; the reply lands in that conversation. Another call with the same in_reply_to and new text posts a follow-up, " + "threaded under this session's first reply; the same text again posts nothing. dispatch_read({message}) reads " + "that conversation back. Every other message names its issue. " + `Body is at most 2,000 characters. ${ISSUE_REFERENCE}`,
+    description: "Post a note humans must read now: a reply to a human's message or a deliverable that landed. A to-do only a human can " + "complete is an ask (dispatch_ask), so it reaches their inbox. Never progress or status updates - Dispatch is a high-signal " + "record, not a log. Not a design decision (write it as a decision block in the document) or document feedback (dispatch_comment). " + "To answer a human's direct message to this session - one sent from the Agents page, which names no issue - pass that message's bare id as " + "in_reply_to and no issue; the reply lands in that conversation. Another call with the same in_reply_to and new text posts a follow-up, " + "threaded under this session's first reply; the same text again posts nothing. dispatch_read({message}) reads " + "that conversation back. Every other message names its issue. " + `Body is at most 2,000 characters, the lines images appends included. ${ISSUE_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(`${ISSUE_REFERENCE} Omit it only when in_reply_to answers a human's direct message to this session.`).optional(),
-      body: z2.string({ max: 2000 }).describe("Update text, at most 2,000 characters."),
-      in_reply_to: z2.string().describe("Optional message id or dispatch://KEY/message/<id> reference to reply to, threading " + "this message under it so the reply stays with the original in the Conversation. " + "A bare id with no issue answers a human's direct message to this session; a " + "dispatch://KEY/message/<id> names the issue its message lives on, so that form is a " + "reply on that issue.").optional()
+      body: z2.string({ max: DISPATCH_BODY_MAX }).describe("Update text, at most 2,000 characters."),
+      in_reply_to: z2.string().describe("Optional message id or dispatch://KEY/message/<id> reference to reply to, threading " + "this message under it so the reply stays with the original in the Conversation. " + "A bare id with no issue answers a human's direct message to this session; a " + "dispatch://KEY/message/<id> names the issue its message lives on, so that form is a " + "reply on that issue.").optional(),
+      images: imagesArgument(z2, "the issue (a reply to a direct message: your own conversation, dispatch://agent/<your session id>)", "the 2,000-character body limit")
     }),
     validation: messageValidation
   },
@@ -14240,13 +14262,13 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_doc_read",
     example: { issue: "DSP-1" },
-    description: "Read a live document or a named document version, or the text of an uploaded file at its latest or named 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. " + "A live read returns its document token for an optional dispatch_doc_edit precondition; use /blocks for per-block tokens. " + "A file that is not UTF-8 text is described, with the route that serves its bytes. " + OWNER_REFERENCE,
+    description: "Read a live document or a named document version, or the text of an uploaded file at its latest or named 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. " + "A live read returns its document token for an optional dispatch_doc_edit precondition; use /blocks for per-block tokens. " + "A picture (an uploaded PNG, JPEG, GIF or WebP of at most 3,750,000 bytes, 5 MB once base64-encoded) comes back as an image you see, with its name, type, size and version, every time you ask, including one a read already showed this session; " + "any other file that is not UTF-8 text is described, with the route that serves its bytes. " + 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("Optional project document artifact id, slug, or filename; primary document by default for an issue.").optional(),
       version: z2.number({ int: true, min: 1 }).describe("Optional version number.").optional(),
-      ref: z2.string().describe("Optional dispatch:// document reference.").optional()
+      ref: z2.string().describe("Optional dispatch:// document reference; a picture in a conversation on the Agents page is dispatch://agent/<session id>/artifact/<slug>@vN.").optional()
     }),
     validation: documentOwnerValidation(true)
   },
@@ -14286,7 +14308,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, 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. " + OWNER_REFERENCE,
+    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,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
@@ -14630,7 +14652,7 @@ function resolveDispatchConfig(env, options = {}) {
 }
 
 // ../envoy-client/src/dispatch-execute.ts
-import { resolve as resolvePath } from "path";
+import { resolve as resolvePath2 } from "path";
 
 // ../envoy-client/src/ask-answer.ts
 var HEAD_LENGTH = 120;
@@ -14876,21 +14898,27 @@ class DispatchClient {
     return this.#json("GET", ["api", "v1", "projects", project, "artifacts"], undefined, unlinked ? { unlinked: "true" } : undefined);
   }
   async projectArtifact(project, input) {
-    const artifactPath = ["api", "v1", "projects", project, "artifacts"];
-    if ("content" in input)
-      return this.#json("POST", artifactPath, input);
-    const form = new FormData;
-    form.set("name", input.name);
-    if (input.summary !== undefined)
-      form.set("summary", input.summary);
-    if (input.actor !== undefined)
-      form.set("actor", JSON.stringify(input.actor));
-    form.set("file", input.file, input.name);
-    return this.#form("POST", artifactPath, form);
+    return this.#upload(["api", "v1", "projects", project, "artifacts"], input);
   }
   async getProjectArtifact(project, slug) {
     return this.#json("GET", ["api", "v1", "projects", project, "artifacts", slug]);
   }
+  async agentArtifact(sessionId, input) {
+    return this.#upload(["api", "v1", "agents", sessionId, "artifacts"], input);
+  }
+  async getAgentArtifact(sessionId, slug) {
+    return this.#json("GET", ["api", "v1", "agents", sessionId, "artifacts", slug]);
+  }
+  async getIssueArtifact(issue2, slug) {
+    return this.#json("GET", [
+      "api",
+      "v1",
+      "issues",
+      await this.#resolveIssue(issue2),
+      "artifacts",
+      slug
+    ]);
+  }
   async search(query, options = {}) {
     return this.#json("GET", ["api", "v1", "search"], undefined, { q: query, ...options });
   }
@@ -15011,17 +15039,7 @@ class DispatchClient {
     return this.#json("POST", ["api", "v1", "messages", id, "deliveries", String(attempt), "accept"], input);
   }
   async artifact(issue2, input) {
-    const artifactPath = ["api", "v1", "issues", await this.#resolveIssue(issue2), "artifacts"];
-    if ("content" in input)
-      return this.#json("POST", artifactPath, input);
-    const form = new FormData;
-    form.set("name", input.name);
-    if (input.summary !== undefined)
-      form.set("summary", input.summary);
-    if (input.actor !== undefined)
-      form.set("actor", JSON.stringify(input.actor));
-    form.set("file", input.file, input.name);
-    return this.#form("POST", artifactPath, form);
+    return this.#upload(["api", "v1", "issues", await this.#resolveIssue(issue2), "artifacts"], input);
   }
   async getArtifact(id) {
     return this.#json("GET", ["api", "v1", "artifacts", id]);
@@ -15128,6 +15146,18 @@ class DispatchClient {
     });
     return { status: response.status, payload: await this.#response(method, url2, response) };
   }
+  async#upload(path2, input) {
+    if ("content" in input)
+      return this.#json("POST", path2, input);
+    const form = new FormData;
+    form.set("name", input.name);
+    if (input.summary !== undefined)
+      form.set("summary", input.summary);
+    if (input.actor !== undefined)
+      form.set("actor", JSON.stringify(input.actor));
+    form.set("file", input.file, input.name);
+    return this.#form("POST", path2, form);
+  }
   async#form(method, path2, body) {
     const url2 = this.#url(path2);
     const response = await this.fetchImpl(url2, {
@@ -15208,70 +15238,115 @@ function dispatchDocumentRef(owner, slug) {
 function dispatchChildRef(ownerRef, kind, id) {
   return `${ownerRef}/${kind}/${id}`;
 }
-
-// ../envoy-client/src/search-answer.ts
-function pageSummaryText(offset, count, total) {
-  return `showing ${offset + 1}-${offset + count} of ${total}`;
-}
-function searchResultLine(result, baseUrl) {
-  const href = new URL(result.href, baseUrl).toString();
-  const { owner } = result;
-  if (owner.kind === "document") {
-    const reference = dispatchDocumentRef(owner.project, owner.slug);
-    return `${reference} [document] ${owner.name} - ${result.kind}: ${snippetText(result.snippet)} -> ${href}`;
-  }
-  const artifactName = result.artifact ? ` ${result.artifact.name}` : "";
-  const label = `${owner.key} [${owner.status}] ${owner.title} - ${result.kind}${artifactName}`;
-  return `${label}: ${snippetText(result.snippet)} -> ${href}`;
-}
-function searchAnswer(search, query, offset, configUrl) {
-  const results = search.results;
-  const count = results.length;
-  const lines = results.map((result) => searchResultLine(result, configUrl));
-  const noun = count === 1 ? "result" : "results";
-  const noResults = `No results for "${query}".`;
-  if (typeof search.total !== "number") {
-    if (offset !== undefined && offset > 0) {
-      throw new Error(`Dispatch answered without a total: it predates search paging and ignored offset ${offset}, so this would be its first page again.`);
+function parseDispatchRef(ref) {
+  const projectDocument = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)(?:@v(\d+))?(?:\/(ask|comment)\/([^/]+))?$/);
+  if (projectDocument) {
+    const [, project, artifact2, version3, targetKind, targetID] = projectDocument;
+    if (project === undefined || artifact2 === undefined || version3 !== undefined && Number(version3) < 1) {
+      return null;
+    }
+    if (targetKind === undefined) {
+      return {
+        owner: { kind: "project", project },
+        kind: "artifact",
+        id: artifact2,
+        ...version3 === undefined ? {} : { version: Number(version3) }
+      };
     }
+    if (targetID === undefined || targetKind !== "ask" && targetKind !== "comment")
+      return null;
     return {
-      text: count === 0 ? noResults : [`${count} ${noun} for "${query}" (${search.took_ms} ms)`, ...lines].join(`
-`),
-      details: { query, results }
+      owner: { kind: "project", project },
+      kind: targetKind,
+      id: targetID,
+      artifact: artifact2
     };
   }
-  const { total, reachable, offset: pageOffset } = search;
-  const end = pageOffset + count;
-  const cut = reachable < total ? `Each kind lists only its best ${SEARCH_KIND_DEPTH} matches, so ${reachable} of the ${total} can be paged to; narrow the query or name a project to reach the rest.` : undefined;
-  const details = {
-    query,
-    results,
-    total,
-    reachable,
-    offset: pageOffset,
-    limit: search.limit
-  };
-  if (count === 0) {
+  const issueReference = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)(?:\/(spec)|\/(log)|\/(children)|\/artifact\/([^/@]+)(?:@v(\d+))?|\/ask\/([^/]+)|\/comment\/([^/]+)|\/message\/([^/]+))?$/);
+  if (!issueReference)
+    return null;
+  const [, issue2, spec, log, children, artifact, version2, ask, comment, message] = issueReference;
+  if (!issue2 || version2 !== undefined && Number(version2) < 1)
+    return null;
+  const owner = { kind: "issue", issue: issue2 };
+  if (spec)
+    return { owner, kind: "spec", id: spec };
+  if (log)
+    return { owner, kind: "log", id: log };
+  if (children)
+    return { owner, kind: "children", id: children };
+  if (artifact) {
     return {
-      text: total === 0 ? noResults : [
-        `No results for "${query}" at offset ${pageOffset}: it matches ${total}, and the pages reach the first ${reachable}.`,
-        ...cut === undefined ? [] : [cut]
-      ].join(`
-`),
-      details
+      owner,
+      kind: "artifact",
+      id: artifact,
+      ...version2 === undefined ? {} : { version: Number(version2) }
     };
   }
-  const showing = pageOffset === 0 && count === total ? "" : `${pageSummaryText(pageOffset, count, total)}, `;
-  return {
-    text: [
-      `${count} ${noun} for "${query}" (${showing}${search.took_ms} ms)`,
-      ...cut === undefined ? [] : [cut],
-      ...lines,
-      ...end < reachable ? [`Next page: offset ${end}.`] : []
-    ].join(`
-`),
-    details
-  };
+  if (ask)
+    return { owner, kind: "ask", id: ask };
+  if (comment)
+    return { owner, kind: "comment", id: comment };
+  if (message)
+    return { owner, kind: "message", id: message };
+  return { owner, kind: "issue", id: issue2 };
+}
+
+// ../envoy-client/src/dispatch-picture-tools.ts
+import { basename, resolve as resolvePath } from "path";
+
+// ../envoy-client/src/dispatch-pictures.ts
+var PICTURE_UPLOAD_MAX_BYTES = 25 * 1024 * 1024;
+var PICTURE_SHOWN_MAX_BYTES = 3750000;
+var pictureShownMaxText = `${PICTURE_SHOWN_MAX_BYTES.toLocaleString("en-US")} bytes (5 MB of base64)`;
+function oversizePictureText(name, bytes) {
+  return `${name} is ${bytes.toLocaleString("en-US")} bytes, over the ${pictureShownMaxText} a model is shown`;
+}
+var PICTURES_SHOWN_MAX = 8;
+var PICTURES_SHOWN_MAX_BYTES = 10 * 1024 * 1024;
+var PICTURE_SNIFF_BYTES = 12;
+function bytesAt(bytes, offset, expected) {
+  return expected.every((byte, index) => bytes[offset + index] === byte);
+}
+function sniffPictureType(bytes) {
+  if (bytesAt(bytes, 0, [137, 80, 78, 71, 13, 10, 26, 10]))
+    return "image/png";
+  if (bytesAt(bytes, 0, [255, 216, 255]))
+    return "image/jpeg";
+  if (bytesAt(bytes, 0, [71, 73, 70, 56]) && (bytes[4] === 55 || bytes[4] === 57) && bytes[5] === 97) {
+    return "image/gif";
+  }
+  if (bytesAt(bytes, 0, [82, 73, 70, 70]) && bytesAt(bytes, 8, [87, 69, 66, 80])) {
+    return "image/webp";
+  }
+  return;
+}
+function toolImage(bytes) {
+  const mimeType = sniffPictureType(bytes);
+  if (mimeType === undefined || bytes.length > PICTURE_SHOWN_MAX_BYTES)
+    return;
+  return { data: Buffer.from(bytes).toString("base64"), mimeType };
+}
+function pictureLine(name, address) {
+  return `![${pictureCaption(name)}](${address})`;
+}
+function withPictureLines(text, lines) {
+  if (lines.length === 0)
+    return text;
+  const head = text.trimEnd();
+  return head === "" ? lines.join(`
+`) : `${head}
+
+${lines.join(`
+`)}`;
+}
+var PICTURE_SYNTAX = /!\[(?:\\.|[^\\\]])*\]\((dispatch:\/\/[^\s()]+@v[1-9][0-9]*)(?:\s+"(?:\\.|[^\\"])*")?\)/g;
+function pictureAddresses(text) {
+  return [...text.matchAll(PICTURE_SYNTAX)].map((match) => match[1]);
+}
+function picturesNewestFirst(texts) {
+  const ordered = texts.map((item, index) => ({ item, index, at: Date.parse(item.at) })).sort((left, right) => (Number.isNaN(right.at) ? 0 : right.at) - (Number.isNaN(left.at) ? 0 : left.at) || left.index - right.index);
+  return [...new Set(ordered.flatMap(({ item }) => pictureAddresses(item.text)))];
 }
 
 // ../envoy-client/src/tool-input-errors.ts
@@ -15397,6 +15472,314 @@ function formatZodIssues(issues, schema) {
   });
 }
 
+// ../envoy-client/src/dispatch-picture-tools.ts
+var PICTURE_TYPE_NAMES = "a PNG, JPEG, GIF or WebP";
+async function localPictures(images, cwd, problems) {
+  if (!Array.isArray(images))
+    return [];
+  const checked = await Promise.all(images.map((path2) => localPicture(path2, cwd)));
+  const pictures = [];
+  for (const outcome of checked) {
+    if (typeof outcome === "string")
+      problems.push(outcome);
+    else if (outcome !== undefined)
+      pictures.push(outcome);
+  }
+  return pictures;
+}
+async function localPicture(path2, cwd) {
+  if (typeof path2 !== "string" || path2 === "")
+    return;
+  const absolute = resolvePath(cwd, path2);
+  const file2 = Bun.file(absolute);
+  let size;
+  let head;
+  try {
+    const stats = await file2.stat();
+    if (!stats.isFile())
+      return `images: ${path2} is not a file`;
+    size = stats.size;
+    head = new Uint8Array(await file2.slice(0, PICTURE_SNIFF_BYTES).arrayBuffer());
+  } catch (error48) {
+    return `images: ${path2} cannot be read: ${messageFor(error48)}`;
+  }
+  if (size > PICTURE_UPLOAD_MAX_BYTES) {
+    return `images: ${path2} is ${size.toLocaleString("en-US")} bytes, over the ${PICTURE_UPLOAD_MAX_BYTES / 1024 / 1024} MiB one Dispatch upload takes`;
+  }
+  const type = sniffPictureType(head);
+  if (type === undefined) {
+    return `images: ${path2} is not ${PICTURE_TYPE_NAMES} picture (judged by its bytes, not its name)`;
+  }
+  return { path: path2, name: basename(absolute), file: Bun.file(absolute, { type }) };
+}
+function uploadSlug(name) {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  return slug === "" ? "artifact" : slug;
+}
+async function textWithPictures(tool, text, pictures, limit, owner, upload, actor) {
+  if (pictures.length === 0)
+    return text;
+  const counted = `${limit.text} plus ${pictures.length} ${pictures.length === 1 ? "picture" : "pictures"}`;
+  const fix = `${limit.shorten} or send fewer pictures`;
+  const predicted = withPictureLines(text, pictures.map((picture) => pictureLine(picture.name, `dispatch://${owner}/artifact/${uploadSlug(picture.name)}@v1`)));
+  if (predicted.length > limit.cap) {
+    throw new ToolInputError(tool, [
+      `${counted} ${overCapMessage(predicted.length, limit.cap)}; ${fix}`
+    ]);
+  }
+  const lines = [];
+  const addresses = [];
+  for (const picture of pictures) {
+    let uploaded;
+    try {
+      uploaded = await upload({ name: picture.name, file: picture.file, actor });
+    } catch (error48) {
+      const earlier = addresses.length === 0 ? "" : `; the pictures before it are uploaded (${addresses.join(", ")})`;
+      throw new Error(`images: ${picture.path} was not uploaded: ${messageFor(error48)}. Nothing was posted${earlier}.`);
+    }
+    const address = `dispatch://${owner}/artifact/${uploaded.artifact.slug}@v${uploaded.version.number}`;
+    addresses.push(address);
+    lines.push(pictureLine(picture.name, address));
+  }
+  const posted = withPictureLines(text, lines);
+  if (posted.length > limit.cap) {
+    throw new Error(`${counted} ${overCapMessage(posted.length, limit.cap)} with the addresses Dispatch gave ` + `the uploads (${addresses.join(", ")}), so nothing was posted; ${fix}.`);
+  }
+  return posted;
+}
+var AGENT_ARTIFACT_REF = new RegExp(`^dispatch://agent/(${SESSION_ID_PATTERN})/artifact/([^/@]+)(?:@v(\\d+))?$`, "u");
+function parseAgentArtifactRef(ref) {
+  const match = ref.match(AGENT_ARTIFACT_REF);
+  if (match === null)
+    return null;
+  const [, session, slug, version2] = match;
+  if (session === undefined || slug === undefined || version2 !== undefined && Number(version2) < 1) {
+    return null;
+  }
+  return { session, slug, ...version2 === undefined ? {} : { version: Number(version2) } };
+}
+function datedBodies(records) {
+  return records.map((record2) => ({ text: record2.body, at: record2.created_at }));
+}
+function askTexts({ ask, replies }) {
+  return [
+    { text: ask.question, at: ask.created_at },
+    ...ask.answer?.text ? [{ text: ask.answer.text, at: ask.answer.at }] : [],
+    ...ask.resolution === undefined ? [] : [{ text: ask.resolution.reason, at: ask.resolution.at }],
+    ...datedBodies(replies)
+  ];
+}
+function eventTexts(event) {
+  let texts;
+  switch (event.type) {
+    case "ask.opened":
+    case "ask.anchor_refreshed":
+    case "ask.edited":
+    case "ask.handed_back":
+    case "ask.answered":
+    case "ask.resolved":
+      texts = [
+        event.payload.question,
+        event.payload.answer?.text,
+        event.payload.resolution?.reason
+      ];
+      break;
+    case "comment.created":
+    case "comment.answered":
+    case "comment.anchor_refreshed":
+    case "comment.edited":
+    case "comment.resolved":
+    case "comment.reopened":
+    case "suggestion.accepted":
+    case "suggestion.rejected":
+    case "message.created":
+    case "message.answered":
+      texts = [event.payload.body];
+      break;
+    default:
+      texts = [];
+  }
+  return texts.filter((text) => typeof text === "string" && text !== "").map((text) => ({ text, at: event.created_at }));
+}
+function shownPictureLine(index, address, name, mimeType, bytes) {
+  return `- image ${index}: ${address} (${name}, ${mimeType}, ${bytes.toLocaleString("en-US")} bytes)`;
+}
+function pictureTarget(address) {
+  const agent = parseAgentArtifactRef(address);
+  if (agent !== null) {
+    if (agent.version === undefined)
+      return;
+    return {
+      key: `agent/${agent.session}/${agent.slug}`,
+      read: (client) => client.getAgentArtifact(agent.session, agent.slug),
+      version: agent.version
+    };
+  }
+  const ref = parseDispatchRef(address);
+  if (ref?.kind !== "artifact" || ref.version === undefined)
+    return;
+  const { owner, id: slug } = ref;
+  return owner.kind === "issue" ? {
+    key: `${owner.issue}/${slug}`,
+    read: (client) => client.getIssueArtifact(owner.issue, slug),
+    version: ref.version
+  } : {
+    key: `${owner.project}/${slug}`,
+    read: (client) => client.getProjectArtifact(owner.project, slug),
+    version: ref.version
+  };
+}
+var SESSIONS_SHOWN_MAX = 64;
+var picturesShown = new Map;
+function shownPictures(sessionId) {
+  const shown = picturesShown.get(sessionId) ?? new Set;
+  picturesShown.delete(sessionId);
+  picturesShown.set(sessionId, shown);
+  const oldest = picturesShown.keys().next();
+  if (picturesShown.size > SESSIONS_SHOWN_MAX && oldest.done !== true) {
+    picturesShown.delete(oldest.value);
+  }
+  return shown;
+}
+async function readPictures(client, addresses, shown) {
+  if (addresses.length === 0)
+    return { lines: [], images: [], shown: [] };
+  const artifacts = new Map;
+  const images = [];
+  const showing = [];
+  const lines = ["Pictures:"];
+  let shownBytes = 0;
+  const overBudget = `past this read's ${PICTURES_SHOWN_MAX_BYTES / 1024 / 1024} MiB of pictures; dispatch_doc_read shows it`;
+  for (const address of addresses) {
+    const skip = (reason) => lines.push(`- not shown: ${address} (${reason})`);
+    if (shown?.has(address)) {
+      skip("shown earlier this session; dispatch_doc_read shows it again");
+      continue;
+    }
+    if (images.length === PICTURES_SHOWN_MAX) {
+      skip(`past this read's ${PICTURES_SHOWN_MAX} pictures; dispatch_doc_read shows it`);
+      continue;
+    }
+    const target = pictureTarget(address);
+    if (target === undefined) {
+      skip("names no versioned Dispatch artifact");
+      continue;
+    }
+    try {
+      let read = artifacts.get(target.key);
+      if (read === undefined) {
+        read = target.read(client);
+        artifacts.set(target.key, read);
+      }
+      const artifact = await read;
+      const version2 = artifact.versions.find((candidate) => candidate.number === target.version);
+      if (version2 === undefined) {
+        skip(`${artifact.name} has no version ${target.version}`);
+        continue;
+      }
+      if (artifact.kind !== "image") {
+        skip(`${artifact.name} is a ${artifact.kind}, not a picture`);
+        continue;
+      }
+      const mime = version2.mime?.split(";")[0]?.trim();
+      if (mime !== undefined && !isPictureType(mime)) {
+        skip(`${artifact.name} is ${mime}, not ${PICTURE_TYPE_NAMES} a model is shown`);
+        continue;
+      }
+      if (version2.size !== undefined && version2.size > PICTURE_SHOWN_MAX_BYTES) {
+        skip(oversizePictureText(artifact.name, version2.size));
+        continue;
+      }
+      if (version2.size !== undefined && shownBytes + version2.size > PICTURES_SHOWN_MAX_BYTES) {
+        skip(overBudget);
+        continue;
+      }
+      const file2 = await client.fileVersion(artifact.id, target.version);
+      const image = toolImage(file2.bytes);
+      if (image === undefined) {
+        skip(sniffPictureType(file2.bytes) === undefined ? `${artifact.name} is not ${PICTURE_TYPE_NAMES} a model is shown` : oversizePictureText(artifact.name, file2.bytes.length));
+        continue;
+      }
+      if (shownBytes + file2.bytes.length > PICTURES_SHOWN_MAX_BYTES) {
+        skip(overBudget);
+        continue;
+      }
+      shownBytes += file2.bytes.length;
+      images.push(image);
+      showing.push(address);
+      lines.push(shownPictureLine(images.length, address, artifact.name, image.mimeType, file2.bytes.length));
+    } catch (error48) {
+      skip(`unavailable: ${messageFor(error48)}`);
+    }
+  }
+  return { lines, images, shown: showing };
+}
+
+// ../envoy-client/src/search-answer.ts
+function pageSummaryText(offset, count, total) {
+  return `showing ${offset + 1}-${offset + count} of ${total}`;
+}
+function searchResultLine(result, baseUrl) {
+  const href = new URL(result.href, baseUrl).toString();
+  const { owner } = result;
+  if (owner.kind === "document") {
+    const reference = dispatchDocumentRef(owner.project, owner.slug);
+    return `${reference} [document] ${owner.name} - ${result.kind}: ${snippetText(result.snippet)} -> ${href}`;
+  }
+  const artifactName = result.artifact ? ` ${result.artifact.name}` : "";
+  const label = `${owner.key} [${owner.status}] ${owner.title} - ${result.kind}${artifactName}`;
+  return `${label}: ${snippetText(result.snippet)} -> ${href}`;
+}
+function searchAnswer(search, query, offset, configUrl) {
+  const results = search.results;
+  const count = results.length;
+  const lines = results.map((result) => searchResultLine(result, configUrl));
+  const noun = count === 1 ? "result" : "results";
+  const noResults = `No results for "${query}".`;
+  if (typeof search.total !== "number") {
+    if (offset !== undefined && offset > 0) {
+      throw new Error(`Dispatch answered without a total: it predates search paging and ignored offset ${offset}, so this would be its first page again.`);
+    }
+    return {
+      text: count === 0 ? noResults : [`${count} ${noun} for "${query}" (${search.took_ms} ms)`, ...lines].join(`
+`),
+      details: { query, results }
+    };
+  }
+  const { total, reachable, offset: pageOffset } = search;
+  const end = pageOffset + count;
+  const cut = reachable < total ? `Each kind lists only its best ${SEARCH_KIND_DEPTH} matches, so ${reachable} of the ${total} can be paged to; narrow the query or name a project to reach the rest.` : undefined;
+  const details = {
+    query,
+    results,
+    total,
+    reachable,
+    offset: pageOffset,
+    limit: search.limit
+  };
+  if (count === 0) {
+    return {
+      text: total === 0 ? noResults : [
+        `No results for "${query}" at offset ${pageOffset}: it matches ${total}, and the pages reach the first ${reachable}.`,
+        ...cut === undefined ? [] : [cut]
+      ].join(`
+`),
+      details
+    };
+  }
+  const showing = pageOffset === 0 && count === total ? "" : `${pageSummaryText(pageOffset, count, total)}, `;
+  return {
+    text: [
+      `${count} ${noun} for "${query}" (${showing}${search.took_ms} ms)`,
+      ...cut === undefined ? [] : [cut],
+      ...lines,
+      ...end < reachable ? [`Next page: offset ${end}.`] : []
+    ].join(`
+`),
+    details
+  };
+}
+
 // ../envoy-client/src/dispatch-execute.ts
 function documentTopic(artifact) {
   return documentTopicOf(artifact.project, artifact.slug);
@@ -15415,6 +15798,7 @@ function followsAsk(owner) {
   return `You follow this ask: its answer and replies reach you directly. For every event on ${owner.label}: envoy_subscribe ${owner.topic}`;
 }
 var triageAdviceShown = new Set;
+var SPEC_CHECK_REMINDER = 'Has a fresh reader checked this spec? Each claim about how a system works today should trace to code read or a command run, and each requirement to the human\'s words or a cited fact. If not, have a fresh read-only subagent (`plan-gap-analyst` on Oh My Pi) check it now and fix what it finds. See the `dispatch-first` skill, "Design in the spec".';
 function renderAdvice(tool, key, advice, opts) {
   if (advice === undefined)
     return [];
@@ -15624,59 +16008,11 @@ function askQuestionWithRef(args) {
 function askQuestionProblem(withRef) {
   return withRef.length > ASK_QUESTION_MAX ? `question plus ref ${overCapMessage(withRef.length, ASK_QUESTION_MAX)}; shorten the question or drop the ref` : undefined;
 }
-function parseDispatchRef(ref) {
-  const projectDocument = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)(?:@v(\d+))?(?:\/(ask|comment)\/([^/]+))?$/);
-  if (projectDocument) {
-    const [, project, artifact2, version3, targetKind, targetID] = projectDocument;
-    if (project === undefined || artifact2 === undefined || version3 !== undefined && Number(version3) < 1) {
-      return null;
-    }
-    if (targetKind === undefined) {
-      return {
-        owner: { kind: "project", project },
-        kind: "artifact",
-        id: artifact2,
-        ...version3 === undefined ? {} : { version: Number(version3) }
-      };
-    }
-    if (targetID === undefined || targetKind !== "ask" && targetKind !== "comment")
-      return null;
-    return {
-      owner: { kind: "project", project },
-      kind: targetKind,
-      id: targetID,
-      artifact: artifact2
-    };
-  }
-  const issueReference = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)(?:\/(spec)|\/(log)|\/(children)|\/artifact\/([^/@]+)(?:@v(\d+))?|\/ask\/([^/]+)|\/comment\/([^/]+)|\/message\/([^/]+))?$/);
-  if (!issueReference)
-    return null;
-  const [, issue2, spec, log, children, artifact, version2, ask, comment, message] = issueReference;
-  if (!issue2 || version2 !== undefined && Number(version2) < 1)
-    return null;
-  const owner = { kind: "issue", issue: issue2 };
-  if (spec)
-    return { owner, kind: "spec", id: spec };
-  if (log)
-    return { owner, kind: "log", id: log };
-  if (children)
-    return { owner, kind: "children", id: children };
-  if (artifact) {
-    return {
-      owner,
-      kind: "artifact",
-      id: artifact,
-      ...version2 === undefined ? {} : { version: Number(version2) }
-    };
-  }
-  if (ask)
-    return { owner, kind: "ask", id: ask };
-  if (comment)
-    return { owner, kind: "comment", id: comment };
-  if (message)
-    return { owner, kind: "message", id: message };
-  return { owner, kind: "issue", id: issue2 };
-}
+var pictureSendingTools = {
+  dispatch_ask: true,
+  dispatch_comment: true,
+  dispatch_message: true
+};
 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);
@@ -15856,6 +16192,15 @@ function dispatchRefFromUrl(value, serverUrl) {
       return `dispatch://${key}/message/${message}`;
     return `dispatch://${key}`;
   }
+  const agentArtifactPage = url2.pathname.match(/^\/agents\/([^/]+)\/artifacts\/([^/]+)\/?$/);
+  if (agentArtifactPage) {
+    const [, session, slug2] = agentArtifactPage;
+    try {
+      return `dispatch://agent/${decodeURIComponent(session ?? "")}/artifact/${decodeURIComponent(slug2 ?? "")}${versionOf("v")}`;
+    } catch {
+      return;
+    }
+  }
   const documentPage = url2.pathname.match(/^\/projects\/([A-Z][A-Z0-9]{1,9})\/documents\/([^/]+)\/?$/);
   if (!documentPage)
     return;
@@ -15866,7 +16211,7 @@ function dispatchRefFromUrl(value, serverUrl) {
     return;
   return item === undefined ? document : `${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>, or " + "dispatch://PROJECT/artifact/<document-ref> (an artifact id, slug, or filename); " + "a dashboard URL on this Dispatch server is accepted too";
+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";
 var toolSchemas = new Map;
 function toolSchema(tool) {
@@ -15890,6 +16235,16 @@ async function resolveOwnerArguments(tool, input, cwd, env, exec, serverUrl, pro
     const refText = dispatchRefFromUrl(refArgument, serverUrl) ?? refArgument;
     if (refText !== refArgument)
       args = { ...input, ref: refText };
+    const agentArtifact = parseAgentArtifactRef(refText);
+    if (agentArtifact !== null) {
+      if (tool !== "dispatch_doc_read") {
+        problems.push(`ref ${refText} names a picture in a conversation on the Agents page; only dispatch_doc_read reads one`);
+      }
+      if (args.issue !== undefined || args.project !== undefined || args.artifact !== undefined) {
+        problems.push("a dispatch://agent/... ref names its upload alone: name no issue, project, or artifact with it");
+      }
+      return { args, ref: null, owner: null, agentArtifact };
+    }
     ref = parseDispatchRef(refText);
     if (ref === null) {
       problems.push(tool === "dispatch_ask" && !refText.startsWith("dispatch://") ? "ref must be a dispatch:// reference" : refGrammarProblem);
@@ -16232,6 +16587,7 @@ function eventHead(event) {
     case "ask.answered":
       return `${textHead(event.payload.question)} -> ${textHead(askAnswerText(event.payload.answer))}`;
     case "comment.created":
+    case "comment.answered":
     case "comment.anchor_refreshed":
     case "comment.edited":
     case "comment.resolved":
@@ -16417,20 +16773,42 @@ async function blockAsks(client, resolved, state) {
   const asks = await (resolved.issue === undefined ? client.getArtifactAsks(resolved.artifact.id, state) : client.listIssueAsks(resolved.issue.key, state));
   return asks.filter((ask) => typeof ask.block_id === "string" && ask.block_artifact?.id === resolved.artifact.id);
 }
-async function readUploadedFile(client, resolved, requested) {
-  const { artifact } = resolved;
+async function readUploadedFile(client, artifact, details, requested, owner, shown) {
   const latest = Math.max(0, ...artifact.versions.map((version2) => version2.number));
   const number4 = requested ?? latest;
-  const file2 = await client.fileVersion(artifact.id, number4);
   const of = number4 === latest ? "" : ` of ${latest}`;
+  const bytesRoute = `GET /api/v1/artifacts/${artifact.id}/versions/${number4} serves its bytes.`;
+  const tooLarge = (mime, bytes) => ({
+    text: `${oversizePictureText(artifact.name, bytes)}, so dispatch_doc_read cannot show this ` + `uploaded ${mime} picture (version ${number4}${of}). ${bytesRoute}`,
+    details
+  });
+  const stated = artifact.versions.find((version2) => version2.number === number4);
+  if (artifact.kind === "image" && stated?.size !== undefined && stated.size > PICTURE_SHOWN_MAX_BYTES) {
+    return tooLarge(stated.mime ?? "image", stated.size);
+  }
+  const file2 = await client.fileVersion(artifact.id, number4);
   const size = `${file2.bytes.length.toLocaleString("en-US")} bytes`;
-  const details = resolved.owner.kind === "project" ? { project: artifact.project, document: documentLabel(artifact.project, artifact.slug) } : { issue: resolved.issue?.key };
+  if (artifact.kind === "image") {
+    const image = toolImage(file2.bytes);
+    if (image !== undefined) {
+      const address = `dispatch://${owner}/artifact/${artifact.slug}@v${number4}`;
+      shown?.add(address);
+      return {
+        text: `Picture ${artifact.name}: ${image.mimeType}, version ${number4}${of}, ${size}.
+` + shownPictureLine(1, address, artifact.name, image.mimeType, file2.bytes.length),
+        details,
+        images: [image]
+      };
+    }
+    if (sniffPictureType(file2.bytes) !== undefined)
+      return tooLarge(file2.mime, file2.bytes.length);
+  }
   let text;
   try {
     text = new TextDecoder("utf-8", { fatal: true }).decode(file2.bytes);
   } catch {
     return {
-      text: `${artifact.name} is an uploaded ${file2.mime} file (version ${number4}${of}, ${size}) that is not ` + `UTF-8 text, so dispatch_doc_read cannot show it. GET /api/v1/artifacts/${artifact.id}/versions/${number4} serves its bytes.`,
+      text: `${artifact.name} is an uploaded ${file2.mime} file (version ${number4}${of}, ${size}) that is not ` + `UTF-8 text, so dispatch_doc_read cannot show it. ${bytesRoute}`,
       details
     };
   }
@@ -16571,6 +16949,7 @@ async function executeDispatchTool(input) {
     problems.push(...formatZodIssues(issues, schema));
   }
   problems.push(...argumentProblems(input.tool, ownerArguments.args));
+  const pictures = pictureSendingTools[input.tool] === true ? await localPictures(ownerArguments.args.images, input.cwd, problems) : [];
   if (problems.length > 0)
     throw new ToolInputError(input.tool, problems);
   const dispatchClient = () => new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
@@ -16622,6 +17001,17 @@ async function executeDispatchTool(input) {
       throw new Error("issue or project is required");
     return owner;
   };
+  const postWithPictures = (text, limit, owner2, upload) => textWithPictures(input.tool, text, pictures, limit, owner2, upload, actor);
+  const writePictures = (resolved, text, limit) => {
+    if (resolved?.owner.kind === "project") {
+      const { project } = resolved.owner;
+      return postWithPictures(text, limit, project, (upload) => client.projectArtifact(project, upload));
+    }
+    const issueKey = issue2();
+    return postWithPictures(text, limit, issueKey, (upload) => client.artifact(issueKey, upload));
+  };
+  const hostSession = input.sessionId?.trim();
+  const shown = hostSession ? shownPictures(hostSession) : undefined;
   switch (input.tool) {
     case "dispatch_issue": {
       const project = stringArg(args, "project");
@@ -16659,6 +17049,7 @@ async function executeDispatchTool(input) {
         return {
           text: [
             `Created ${created.key}: ${created.title} ${notSubscribed(issueTopic(created.key))}`,
+            ...spec === undefined ? [] : [SPEC_CHECK_REMINDER],
             ...adviceLines
           ].join(`
 `),
@@ -16924,8 +17315,15 @@ async function executeDispatchTool(input) {
       const multiple = optionalBoolean(args, "multiple");
       const urgency = askUrgency(args);
       const anchored = anchorArgs && resolved ? anchor(resolved.artifact, anchorArgs) : undefined;
+      const withRef = askQuestionWithRef(args);
+      const refAppended = withRef !== stringArg(args, "question");
+      const question = await writePictures(resolved, withRef, {
+        cap: ASK_QUESTION_MAX,
+        text: refAppended ? "question plus ref" : "question",
+        shorten: refAppended ? "shorten the question, drop the ref" : "shorten the question"
+      });
       const askInput = {
-        question: askQuestionWithRef(args),
+        question,
         ...Array.isArray(options) ? { options } : {},
         ...multiple === undefined ? {} : { multiple },
         ...urgency === undefined ? {} : { urgency },
@@ -16983,8 +17381,13 @@ ${followsAsk(askOwner)}`,
         ]);
       }
       const requestedTurn = optionalString(args, "turn");
+      const body = await writePictures(resolved, stringArg(args, "body"), {
+        cap: DISPATCH_BODY_MAX,
+        text: "body",
+        shorten: "shorten the body"
+      });
       const commentInput = {
-        body: stringArg(args, "body"),
+        body,
         ...anchored === undefined ? {} : { anchor: anchored },
         ...replyTo === undefined ? {} : { reply_to: replyTo },
         ...replyToAsk === undefined ? {} : { ask_id: replyToAsk },
@@ -17044,16 +17447,29 @@ ${followsAsk(askOwner)}`,
     }
     case "dispatch_message": {
       const inReplyTo = messageInReplyTo(args);
-      const body = stringArg(args, "body");
+      const written = stringArg(args, "body");
+      const bodyLimit = {
+        cap: DISPATCH_BODY_MAX,
+        text: "body",
+        shorten: "shorten the body"
+      };
       if (owner === null && inReplyTo !== undefined) {
-        const reply = await client.messageReply(inReplyTo, { body, attempt: 1, actor }, { followUp: true });
-        if (reply.duplicate === true && reply.body === body) {
+        let body2 = written;
+        if (pictures.length > 0) {
+          const sessionId = input.sessionId?.trim();
+          if (!sessionId) {
+            throw new Error("host session id is required to send pictures in a direct-message reply");
+          }
+          body2 = await postWithPictures(written, bodyLimit, `agent/${sessionId}`, (upload) => client.agentArtifact(sessionId, upload));
+        }
+        const reply = await client.messageReply(inReplyTo, { body: body2, attempt: 1, actor }, { followUp: true });
+        if (reply.duplicate === true && reply.body === body2) {
           return {
             text: `Dispatch already has this exact text in the conversation (message ${reply.id}); ` + "nothing new was posted. Send different text if you have more to say.",
             details: { message: reply.id, in_reply_to: inReplyTo, posted: false, duplicate: true }
           };
         }
-        if (reply.body !== body) {
+        if (reply.body !== body2) {
           return {
             text: `Message ${inReplyTo} was already answered by message ${reply.id}; Dispatch kept ` + "that reply and posted nothing. Wait for their next message rather than answering " + "this one again.",
             details: { message: reply.id, in_reply_to: inReplyTo, posted: false }
@@ -17073,6 +17489,7 @@ ${followsAsk(askOwner)}`,
         };
       }
       const issueKey = issue2();
+      const body = await postWithPictures(written, bodyLimit, issueKey, (upload) => client.artifact(issueKey, upload));
       const message = await client.message(issueKey, {
         body,
         ...inReplyTo === undefined ? {} : { in_reply_to: inReplyTo },
@@ -17136,11 +17553,20 @@ ${followsAsk(askOwner)}`,
       };
     }
     case "dispatch_doc_read": {
+      const { agentArtifact } = ownerArguments;
+      if (agentArtifact !== undefined) {
+        const artifact = await client.getAgentArtifact(agentArtifact.session, agentArtifact.slug);
+        return readUploadedFile(client, artifact, { session: agentArtifact.session, artifact: artifact.slug }, optionalNumber(args, "version") ?? agentArtifact.version, `agent/${agentArtifact.session}`, shown);
+      }
       const artifactReference = optionalString(args, "artifact") ?? (ownerArguments.ref?.kind === "spec" || ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : undefined);
       const resolved = await resolveDocument(documentOwner(), artifactReference);
       const version2 = optionalNumber(args, "version") ?? ownerArguments.ref?.version;
       if (resolved.artifact.kind === "file" || resolved.artifact.kind === "image") {
-        return readUploadedFile(client, resolved, version2);
+        const { artifact } = resolved;
+        return readUploadedFile(client, artifact, resolved.owner.kind === "project" ? {
+          project: artifact.project,
+          document: documentLabel(artifact.project, artifact.slug)
+        } : { issue: resolved.issue?.key }, version2, resolved.owner.kind === "project" ? resolved.owner.project : resolved.owner.issue, shown);
       }
       const documentPromise = client.docRead(resolved.artifact.id, version2);
       const marksPromise = openArtifactMarks(client, resolved);
@@ -17188,7 +17614,8 @@ ${trailer.join(`
       const details = await followedAskDetails(client, result.ask, resolved.artifact);
       const outcome = result.recorded ? `Approval requested for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}).` : `The approval request for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}) already waits on the human, so this call changed nothing: nothing since it last reached the human (a newer version, a human's reply in its thread, or your progress note) left it waiting on you.`;
       return {
-        text: `${outcome} The human's Inbox asks: ${JSON.stringify(result.ask.question)}. The answer arrives as artifact.approved or artifact.changes_requested. An edit before the answer moves this request to the new version and leaves it waiting on you, and an edit after approval makes the approval stale: either way, request again for the new version once the human has agreed to every point in it, which hands this request back or opens a new one.`,
+        text: `${outcome} The human's Inbox asks: ${JSON.stringify(result.ask.question)}. The answer arrives as artifact.approved or artifact.changes_requested. An edit before the answer moves this request to the new version and leaves it waiting on you, and an edit after approval makes the approval stale: either way, request again for the new version once the human has agreed to every point in it, which hands this request back or opens a new one.${result.recorded ? `
+${SPEC_CHECK_REMINDER}` : ""}`,
         details: { ...details, artifact: resolved.artifact.id, version: result.version }
       };
     }
@@ -17198,7 +17625,7 @@ ${trailer.join(`
       const content = optionalString(args, "content");
       const artifactInput = content === undefined ? {
         name,
-        file: Bun.file(resolvePath(input.cwd, stringArg(args, "path"))),
+        file: Bun.file(resolvePath2(input.cwd, stringArg(args, "path"))),
         ...summary === undefined ? {} : { summary },
         actor
       } : {
@@ -17251,18 +17678,29 @@ ${trailer.join(`
     }
     case "dispatch_read": {
       const message = optionalString(args, "message");
+      const picturesOf = (texts) => readPictures(client, picturesNewestFirst(texts), shown);
+      const showImages = (pictures3) => {
+        for (const address of pictures3.shown)
+          shown?.add(address);
+        return pictures3.images.length === 0 ? {} : { images: pictures3.images };
+      };
       if (message !== undefined) {
         const sessionId = input.sessionId?.trim();
         if (!sessionId)
           throw new Error("host session id is required for dispatch_read({message})");
         const thread = await client.getMessageThread(messageIdOf(message), sessionId);
         const issueKey2 = thread.message.issue_key;
+        const [pictures3, graph2] = await Promise.all([
+          picturesOf(datedBodies([thread.message, ...thread.replies])),
+          issueKey2 === null ? [] : graphSections(client, dispatchChildRef(dispatchIssueRef(issueKey2), "message", thread.message.id))
+        ]);
         return {
-          text: messageSummary(thread, issueKey2 === null ? [] : await graphSections(client, dispatchChildRef(dispatchIssueRef(issueKey2), "message", thread.message.id))),
+          text: messageSummary(thread, [...pictures3.lines, ...graph2]),
           details: {
             message: thread.message.id,
             ...issueKey2 === null ? {} : { issue: issueKey2 }
-          }
+          },
+          ...showImages(pictures3)
         };
       }
       if (ownerArguments.ref?.kind === "ask") {
@@ -17270,9 +17708,14 @@ ${trailer.join(`
         const id = await resolveIdPrefix(input.tool, "ask", ref.id, refOwnerName(ref), async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks((await resolveDocument(ref.owner, ref.artifact)).artifact.id, "all"));
         const askRead = await client.getAsk(id);
         const askRef = refTarget(ref, "ask", id);
+        const [pictures3, graph2] = await Promise.all([
+          picturesOf(askTexts(askRead)),
+          graphSections(client, askRef)
+        ]);
         return {
-          text: askSummary(askRead, await graphSections(client, askRef)),
-          details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: ref.owner.issue }
+          text: askSummary(askRead, [...pictures3.lines, ...graph2]),
+          details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: ref.owner.issue },
+          ...showImages(pictures3)
         };
       }
       if (ownerArguments.ref?.kind === "comment") {
@@ -17280,9 +17723,14 @@ ${trailer.join(`
         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 comment = await client.getComment(id);
         const commentRef = refTarget(ref, "comment", id);
+        const [pictures3, graph2] = await Promise.all([
+          picturesOf(datedBodies([comment.comment, ...comment.replies])),
+          graphSections(client, commentRef)
+        ]);
         return {
-          text: commentSummary(comment, await graphSections(client, commentRef)),
-          details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: comment.comment.issue_key }
+          text: commentSummary(comment, [...pictures3.lines, ...graph2]),
+          details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: comment.comment.issue_key },
+          ...showImages(pictures3)
         };
       }
       if (ownerArguments.ref?.kind === "message") {
@@ -17291,9 +17739,14 @@ ${trailer.join(`
         }
         const messageRead = await client.getMessage(ownerArguments.ref.owner.issue, ownerArguments.ref.id);
         const messageRef = dispatchChildRef(dispatchIssueRef(ownerArguments.ref.owner.issue), "message", ownerArguments.ref.id);
+        const [pictures3, graph2] = await Promise.all([
+          picturesOf(datedBodies([messageRead.message, ...messageRead.replies])),
+          graphSections(client, messageRef)
+        ]);
         return {
-          text: messageSummary(messageRead, await graphSections(client, messageRef)),
-          details: { issue: messageRead.message.issue_key }
+          text: messageSummary(messageRead, [...pictures3.lines, ...graph2]),
+          details: { issue: messageRead.message.issue_key },
+          ...showImages(pictures3)
         };
       }
       if (documentOwner().kind === "project") {
@@ -17317,9 +17770,12 @@ ${trailer.join(`
       const issueKey = issue2();
       if (ownerArguments.ref?.kind === "log") {
         const read2 = await client.read(issueKey);
+        const pictures3 = await picturesOf(read2.events.flatMap(eventTexts));
         return {
-          text: logSummary(read2.issue, read2.events),
-          details: { issue: read2.issue.key }
+          text: [logSummary(read2.issue, read2.events), ...pictures3.lines].join(`
+`),
+          details: { issue: read2.issue.key },
+          ...showImages(pictures3)
         };
       }
       if (ownerArguments.ref?.kind === "children") {
@@ -17332,14 +17788,19 @@ ${trailer.join(`
       const readPromise = client.read(issueKey);
       const referencesPromise = issueReferencesOrUnavailable(client, issueKey);
       const read = await readPromise;
-      const [references, graph, titles] = await Promise.all([
+      const [references, graph, titles, pictures2] = await Promise.all([
         referencesPromise,
         graphSections(client, dispatchIssueRef(read.issue.key)),
-        liveSessionTitles(client, holdsSession(read.issue.claim) || routeHeldBySession(read.issue))
+        liveSessionTitles(client, holdsSession(read.issue.claim) || routeHeldBySession(read.issue)),
+        picturesOf([
+          ...read.issue.open_asks.map((ask) => ({ text: ask.question, at: ask.created_at })),
+          ...read.events.flatMap(eventTexts)
+        ])
       ]);
       return {
-        text: issueSummary(read.issue, read.events, references, graph, titles),
-        details: { issue: read.issue.key }
+        text: issueSummary(read.issue, read.events, references, [...pictures2.lines, ...graph], titles),
+        details: { issue: read.issue.key },
+        ...showImages(pictures2)
       };
     }
     default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "5.8.2",
+  "version": "5.9.1",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/src/server.js",

package/skills/AGENTS.md

@@ -9,7 +9,7 @@ event intake, process lifecycle, credentials, and role delivery.
 | `ce-simplify-code/` | the implementer, once per pull request | the behaviour-preserving simplify pass, in the implementer's first implementing round (Legion's copy of the MIT-licensed Compound Engineering skill; `LICENSE` beside it) |
 | `dispatch/` | every role, and any session writing to Dispatch | specs, asks, comments, artifacts, and messages on native Dispatch |
 | `dispatch-brainstorming/` | any session with Dispatch that starts a design conversation or writes a plan, as `dispatch-first` directs | the design conversation in the issue's spec, turn by turn to one approval, and the plan as the issue's `plan.md`; in a session with Dispatch it replaces superpowers' `brainstorming` and `writing-plans` |
-| `dispatch-first/` | every session with Dispatch configured, injected by each host plugin on every request (Oh My Pi), on every `SessionStart` (startup, resume, clear, compact, fork) and `SubagentStart` (Claude Code), or as an instruction file (OpenCode) | searching Dispatch before acting, extending the existing issue, citing decisions, closing duplicates; kept under 60 lines and 6,000 characters |
+| `dispatch-first/` | every session with Dispatch configured, injected by each host plugin on every request (Oh My Pi), on every `SessionStart` (startup, resume, clear, compact, fork) and `SubagentStart` (Claude Code), or as an instruction file (OpenCode) | searching Dispatch before acting, extending the existing issue, citing decisions, closing duplicates, the fresh-reader check before a spec reaches a human; kept under 60 lines and 6,000 characters |
 | `envoy/` | every role | subscriptions, agent-to-agent messages, and topic formats |
 | `legion-architect/` | root and sub-architects | tree ownership, decomposition, waves, gates, integration, sign-off |
 | `legion-controller/` | the controller root process | wake routing, keeping the admission slots full from `todo`, the daily report, escalation |

package/skills/dispatch/SKILL.md

@@ -416,6 +416,9 @@ It returns live or versioned markdown with open marks. A live read ends with a d
 `artifact` reads the issue specification; a project needs `artifact`; and a `dispatch://PROJECT/artifact/<document-ref>`
 ref supplies both, where `document-ref` is the slug (an id or a filename resolves when no document has that slug). A file
 `dispatch_artifact` uploaded reads its text at the latest or named version, or a description when it is not UTF-8 text.
+A picture (PNG, JPEG, GIF or WebP under 3,750,000 bytes, 5 MB of base64) comes back as an image you see, with its name, type, size and version;
+that includes `dispatch://agent/<session id>/artifact/<slug>@vN`, one a person sent you on the Agents page. A session is shown each picture once,
+since the provider refuses a request over 32 MB: later reads and deliveries name it, and `dispatch_doc_read` shows it again (after compaction too).
 
 Editing one is [Editing a document](skill://dispatch/references/document-edits.md): the shape of `dispatch_doc_edit`,
 how to quote the text you mean, one `replace` per paragraph, preconditions against a stale edit, and
@@ -474,6 +477,9 @@ dispatch_message({ issue, body })
 It returns `details` `{ issue, message }`. `body` is capped at 2,000 characters. A message is not a decision
 (a decision block, or `dispatch_ask` for a human to-do) or document feedback (`dispatch_comment`), and it does not wake anyone unless the issue is routed.
 
+**Pictures.** To show a screenshot inline, pass its path in `images` (`dispatch_message`, `dispatch_comment`, `dispatch_ask`);
+`dispatch_read` hands you the pictures what it shows embeds. Both are in [Documents](skill://dispatch/references/documents.md), "Artifacts".
+
 A BTW, Aside or Steer frame, or a message from the Agents page, is answered as
 [Targeted and direct messages](skill://dispatch/references/messages.md) says.
 

package/skills/dispatch/references/documents.md

@@ -146,6 +146,29 @@ slug also arrives on `artifact.created` events. Dispatch suffixes a slug two doc
 filename can be another's slug (`plan v2` takes `plan-v2`, then a document named `plan-v2` takes `plan-v2-2`): a bare
 `artifact` that names both is refused with each one's id, while a `dispatch://` reference's document part is always the slug.
 
+A picture meant to be seen inline in a message, comment or ask is not uploaded with `dispatch_artifact`: pass its local
+path in that tool's `images` (PNG, JPEG, GIF or WebP by its bytes, at most 25 MiB each). Each is uploaded to the issue (a
+project document's project; for a reply to a direct message, your own conversation) and appended after a blank line as
+one `![<file name>](dispatch://<owner>/artifact/<slug>@vN)` line, about 60 characters that count toward the body or
+question cap; a call the lines would carry over the cap is refused with the count before anything uploads, and again,
+with nothing posted, in the rare case where Dispatch gives an upload a longer address than that (a later version of a
+name the owner already holds, or a slug another file took first). The `@vN` pins the version the upload made (the same
+file name again makes the next version). A plain `dispatch://KEY/artifact/<slug>` reference to an image stays a link
+with a thumbnail.
+
+`dispatch_read` hands you the pictures the messages, asks and comments it shows embed, newest first, at most 8 and
+10 MiB per read, and its `Pictures:` section names each one shown, in order, and the rest by reference for
+`dispatch_doc_read`, which shows one picture (at most 3,750,000 bytes, the 5 MB of base64 a model provider takes; a
+larger one or an SVG is described). A picture in a
+conversation on the Agents page belongs to that conversation, `dispatch://agent/<session id>/artifact/<slug>@vN`, and
+`dispatch_doc_read` reads it by that reference alone. On Oh My Pi an Inbox delivery carries its pictures the same way; in
+Claude Code it stays text with the reference.
+
+A session is shown each picture once. A later read or delivery that embeds a picture you were already shown names it in
+`Pictures:` as `shown earlier this session` and sends no bytes, since every request carries the session's whole history
+and a model provider refuses one over 32 MB; `dispatch_doc_read` always shows the picture, so ask it for one you need
+again, after compaction too.
+
 Documents are CommonMark. A bare `<https://example.com|text>` is a CommonMark autolink and is normalised: the angle brackets are
 dropped and the URL keeps `|text`. A backslash-escaped `\<https://example.com|text>` displays as `<https://example.com|text>` in the
 document but comes back re-escaped (`\<`) from `dispatch_doc_read`. A Slack mrkdwn draft, or any other payload that is not Markdown,

package/skills/dispatch-first/SKILL.md

@@ -50,7 +50,7 @@ found yourself.
 A design conversation with a person, or the implementation plan that follows one, uses
 `skill://dispatch-brainstorming`: read it before your first design question on a change, the spec,
 or that plan. It replaces superpowers' `brainstorming` and `writing-plans` here, even when the user
-invokes one by name. A Legion architect's own issue spec follows `skill://legion-architect`.
+invokes one by name. A Legion architect's own issue spec follows `skill://legion-architect`. Before a spec's first version and each approval request, have a fresh read-only subagent (on Oh My Pi, `task(agent="plan-gap-analyst")`) check it against the code, the human's words and any command output a claim rests on, and resolve what it flags.
 
 ## Load the full skill before you write