@sjawhar/pi-legion-envoy 1.26.0 → 1.27.1

package/dist/envoy.js

@@ -29883,7 +29883,7 @@ var dispatchToolSpecs = [
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
       artifact: z.string().describe("Project document artifact id, slug, or filename.").optional(),
-      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
+      ref: z.string().describe("Optional dispatch:// reference (issue, document, message, or ask); appended to the question and rendered as a link.").optional(),
       question: z.string({ max: 800 }).describe("Decision question, at most 800 characters."),
       kind: z.enum(["action"]).describe("Optional human to-do ask kind.").optional(),
       options: z.array(z.object({
@@ -32015,6 +32015,19 @@ function askKind(args) {
     return value;
   throw new Error("kind must be action");
 }
+function askQuestionWithRef(args) {
+  const question = stringArg(args, "question");
+  const ref = optionalString(args, "ref");
+  if (ref === undefined || question.includes(ref))
+    return question;
+  const withRef = `${question}
+
+Ref: ${ref}`;
+  if (withRef.length > 800) {
+    throw new Error("question plus ref must be at most 800 characters");
+  }
+  return withRef;
+}
 function parseDispatchRef(ref) {
   const projectDocument = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)(?:@v(\d+))?(?:\/(ask|comment)\/([^/]+))?$/);
   if (projectDocument) {
@@ -32097,6 +32110,9 @@ async function resolveOwnerArguments(tool, args, cwd, env, exec) {
   if (issueFreeTools[tool] === true)
     return { args, ref: null, owner: null };
   const refArgument = args.ref;
+  if (tool === "dispatch_ask" && typeof refArgument === "string" && !refArgument.startsWith("dispatch://")) {
+    throw new Error("ref must be a dispatch:// reference");
+  }
   const ref = typeof refArgument === "string" ? parseDispatchRef(refArgument) ?? (() => {
     throw new Error("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)");
   })() : null;
@@ -32506,7 +32522,7 @@ async function executeDispatchTool(input) {
       const kind = askKind(args);
       const anchored = anchorArgs && resolved ? anchor(resolved.artifact, anchorArgs) : undefined;
       const askInput = {
-        question: stringArg(args, "question"),
+        question: askQuestionWithRef(args),
         ...kind === undefined ? {} : { kind },
         ...Array.isArray(options) ? { options } : {},
         ...multiple === undefined ? {} : { multiple },

package/dist/legion.js

@@ -29883,7 +29883,7 @@ var dispatchToolSpecs = [
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
       artifact: z.string().describe("Project document artifact id, slug, or filename.").optional(),
-      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
+      ref: z.string().describe("Optional dispatch:// reference (issue, document, message, or ask); appended to the question and rendered as a link.").optional(),
       question: z.string({ max: 800 }).describe("Decision question, at most 800 characters."),
       kind: z.enum(["action"]).describe("Optional human to-do ask kind.").optional(),
       options: z.array(z.object({
@@ -32446,6 +32446,19 @@ function askKind(args) {
     return value;
   throw new Error("kind must be action");
 }
+function askQuestionWithRef(args) {
+  const question = stringArg(args, "question");
+  const ref = optionalString(args, "ref");
+  if (ref === undefined || question.includes(ref))
+    return question;
+  const withRef = `${question}
+
+Ref: ${ref}`;
+  if (withRef.length > 800) {
+    throw new Error("question plus ref must be at most 800 characters");
+  }
+  return withRef;
+}
 function parseDispatchRef(ref) {
   const projectDocument = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)(?:@v(\d+))?(?:\/(ask|comment)\/([^/]+))?$/);
   if (projectDocument) {
@@ -32528,6 +32541,9 @@ async function resolveOwnerArguments(tool, args, cwd, env, exec) {
   if (issueFreeTools[tool] === true)
     return { args, ref: null, owner: null };
   const refArgument = args.ref;
+  if (tool === "dispatch_ask" && typeof refArgument === "string" && !refArgument.startsWith("dispatch://")) {
+    throw new Error("ref must be a dispatch:// reference");
+  }
   const ref = typeof refArgument === "string" ? parseDispatchRef(refArgument) ?? (() => {
     throw new Error("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)");
   })() : null;
@@ -32937,7 +32953,7 @@ async function executeDispatchTool(input) {
       const kind = askKind(args);
       const anchored = anchorArgs && resolved ? anchor(resolved.artifact, anchorArgs) : undefined;
       const askInput = {
-        question: stringArg(args, "question"),
+        question: askQuestionWithRef(args),
         ...kind === undefined ? {} : { kind },
         ...Array.isArray(options) ? { options } : {},
         ...multiple === undefined ? {} : { multiple },

package/dist/skills/dispatch/SKILL.md

@@ -111,6 +111,7 @@ dispatch_ask({
   issue?,
   project?,
   artifact?,
+  ref?,
   question,
   options?: { label, description? }[],
   multiple?,
@@ -120,6 +121,8 @@ dispatch_ask({
 ```
 It returns `details` `{ issue, topic, ask }` for an issue or `{ project, artifact, document, topic, ask }` for a project document.
 
+References belong in the question text; `ref` is sugar that appends its `dispatch://` value to the question as a rendered link.
+
 An ask is read on a phone by someone who has not read the code. Open with one or two plain
 sentences: what needs deciding and why it matters now. Each option is a button with a label and
 one sentence saying what happens if it is chosen; never enumerate choices in prose. Put the
@@ -341,6 +344,24 @@ with your text. Never do that: the spec is edited in place with `dispatch_doc_ed
 artifact by the slug shown in the upload result or by its filename, and a project document by its artifact id, slug, or filename; the
 slug also arrives on `artifact.created` events.
 
+## Structure over stream
+
+Dispatch is a structured workspace, never a message stream (Sami, 2026-09-13, verbatim: "strange
+to me that agents keep trying to use dispatch as a giant stream of messages instead of
+high-signal, structured conversation"). The structure IS the product:
+
+- **One issue per piece of work.** A new deliverable — an email to send, a document to review, a
+  decision with its own lifecycle — gets its own issue with the content as the issue's document
+  (spec artifact), not a message pile on an existing issue. If you are about to post a message
+  carrying a draft, a spec, or anything over a couple of paragraphs, stop: that is an issue with a
+  document, or an artifact on the issue it belongs to.
+- **Content lives in documents; decisions live in asks; messages only announce.** A draft the
+  human must read goes in a document artifact the dashboard renders with versions and margins; the
+  ask that needs their word references it (`ref`, or the `dispatch://` link inline) instead of
+  restating it. A message never carries a body a human has to scroll.
+- **Never split one deliverable across a message + an ask that points at it.** Ask the question
+  with the document reference in the question text; the reader lands on the content in one click.
+
 ## Messages
 
 Dispatch is a high-signal record for humans, not a log of what you are doing. A message is a reply to a human's message, or a

package/package.json

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