@sjawhar/pi-legion-envoy 1.9.0 → 1.11.0

package/dist/envoy.js

@@ -29730,10 +29730,20 @@ var CommentEventPayloadSchema = object({
 var MessageEventPayloadSchema = object({
   id: string2().optional(),
   body: string2().optional(),
-  reply_to: string2().nullish(),
+  target: string2().nullish(),
+  in_reply_to: string2().nullish(),
   reply_body: string2().optional(),
   author: object({ kind: string2(), id: string2() }).optional()
 });
+var MessageDeliveryEventPayloadSchema = object({
+  message_id: string2().optional(),
+  attempt: number2().int().positive().optional(),
+  delivery: _enum2(["btw", "aside", "steer"]).optional(),
+  session_id: string2().optional(),
+  title: string2().optional(),
+  state: _enum2(["sent", "failed"]).optional(),
+  error: string2().optional()
+});
 var ChildStatusEventPayloadSchema = object({
   child_key: string2().optional(),
   from: string2().optional(),
@@ -29827,7 +29837,7 @@ var SPEC_SECTIONS = [
 ];
 var SPEC_WRITING_GUIDANCE = `When writing a spec, use these sections in order: ${SPEC_SECTIONS.join(", ")}. ` + "Write for a reader who has not seen the code: plain sentences, every identifier expanded on " + "first use, no coined shorthand; see skills/dispatch Writing for the human and Writing a spec.";
 var ASK_URGENCIES = ["low", "med", "high", "blocking"];
-var DOC_EDIT_OPS = ["replace", "delete", "insert"];
+var DOC_EDIT_OPS = ["replace", "delete", "insert", "retype"];
 var dispatchToolSpecs = [
   {
     name: "dispatch_issue",
@@ -29932,12 +29942,12 @@ var dispatchToolSpecs = [
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
       body: z.string({ max: 2000 }).describe("Update text, at most 2,000 characters."),
-      reply_to: z.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.").optional()
+      in_reply_to: z.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.").optional()
     })
   },
   {
     name: "dispatch_doc_edit",
-    description: "Apply deterministic text edits to an issue or project document. Do not use it for review feedback or for reading; use " + "dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. The spec (or any document) holds requirements, " + `design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
+    description: "Apply deterministic document edits, including retyping an identified paragraph into a schema-declared typed block. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -29950,7 +29960,10 @@ var dispatchToolSpecs = [
         occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based match occurrence.").optional(),
         markdown: z.string().describe("Markdown to insert.").optional(),
         after: z.string().describe("Anchor after which to insert.").optional(),
-        before: z.string().describe("Anchor before which to insert.").optional()
+        before: z.string().describe("Anchor before which to insert.").optional(),
+        block: z.string().describe("Block id to retype.").optional(),
+        type: z.string().describe("Typed block name for retype.").optional(),
+        attributes: z.unknown().describe("Typed block attributes for retype.").optional()
       })).describe("Flat tagged edits; the server validates fields required for each operation."),
       summary: z.string().describe("Optional named-version summary.").optional()
     }),
@@ -30411,6 +30424,7 @@ function zodSchemaApi(zod) {
     },
     boolean: () => api.boolean(),
     enum: (values) => api.enum(values),
+    unknown: () => api.unknown(),
     array: (item, opts = {}) => {
       let schema = api.array(item);
       if (opts.min !== undefined)
@@ -31008,6 +31022,31 @@ var TolerantInboundEnvelopeSchema = object({
   source: InboundEnvelopeSchema.shape.source.optional().catch(undefined),
   sender: object(tolerantShape(InboundSenderSchema.shape)).optional().catch(undefined)
 }).passthrough();
+var DispatchDeliveryRequestSchema = object({
+  attempt: number2().int().positive(),
+  mode: _enum2(["btw", "aside", "steer"])
+});
+var DispatchTargetedMessagePayloadSchema = object({
+  id: string2(),
+  issue_key: string2(),
+  author: object({ kind: string2(), id: string2() }),
+  body: string2(),
+  target: string2(),
+  in_reply_to: string2().nullable(),
+  deliveries: array(unknown()),
+  created_at: string2()
+});
+var DispatchTargetedFrameSchema = object({
+  event: DispatchEventSchema,
+  delivery: DispatchDeliveryRequestSchema
+}).refine(({ event }) => event.type === "message.created" && DispatchTargetedMessagePayloadSchema.safeParse(event.payload).success, { message: "targeted delivery requires a message.created event" });
+var RecoverableDispatchDeliveryFailureSchema = object({
+  event: object({
+    issue_key: string2(),
+    payload: object({ id: string2(), body: string2().optional() }).passthrough()
+  }).passthrough(),
+  delivery: DispatchDeliveryRequestSchema
+});
 function senderLabel(envelope) {
   const sender = envelope.source_session ?? envelope.source ?? "unknown";
   return envelope.sender?.title === undefined ? sender : `${sender} (${envelope.sender.title})`;
@@ -31034,6 +31073,8 @@ var DISPATCH_PAYLOAD_SCHEMAS = {
   "suggestion.accepted": CommentEventPayloadSchema,
   "suggestion.rejected": CommentEventPayloadSchema,
   "message.created": MessageEventPayloadSchema,
+  "message.delivery": MessageDeliveryEventPayloadSchema,
+  "message.answered": MessageEventPayloadSchema,
   "child.status": ChildStatusEventPayloadSchema
 };
 function dispatchOwner(event, topic) {
@@ -31066,6 +31107,9 @@ function dispatchMessageReplyPreview(event) {
   const parsed = MessageEventPayloadSchema.safeParse(event.payload);
   return parsed.success && parsed.data.reply_body !== undefined && parsed.data.reply_body !== "" ? parsed.data.reply_body : undefined;
 }
+function isObject2(value) {
+  return typeof value === "object" && value !== null;
+}
 function parseDispatchFrame(rawPayload) {
   let value;
   try {
@@ -31073,11 +31117,41 @@ function parseDispatchFrame(rawPayload) {
   } catch {
     return { raw: rawPayload };
   }
+  const targeted = DispatchTargetedFrameSchema.safeParse(value);
+  if (targeted.success) {
+    const wireFrame = value;
+    return {
+      event: targeted.data.event,
+      notify: wireFrame.event.notify,
+      delivery: targeted.data.delivery
+    };
+  }
+  if (isObject2(value) && "delivery" in value) {
+    const recoverable = RecoverableDispatchDeliveryFailureSchema.safeParse(value);
+    if (recoverable.success) {
+      return {
+        raw: value,
+        rejectedDelivery: {
+          attempt: recoverable.data.delivery.attempt,
+          mode: recoverable.data.delivery.mode,
+          messageID: recoverable.data.event.payload.id,
+          issueKey: recoverable.data.event.issue_key,
+          body: recoverable.data.event.payload.body ?? ""
+        },
+        malformedDelivery: true
+      };
+    }
+    return { raw: value, malformedDelivery: true };
+  }
   const parsed = DispatchEventSchema.safeParse(value);
   if (!parsed.success)
     return { raw: value };
   const wireEvent = value;
-  return { event: parsed.data, notify: wireEvent.notify };
+  return {
+    event: parsed.data,
+    notify: wireEvent.notify,
+    delivery: undefined
+  };
 }
 function inboundTimestamp(milliseconds) {
   if (milliseconds === undefined)
@@ -31115,6 +31189,10 @@ function renderInbound(raw, sessionID, subject) {
   }
   let dispatchEvent;
   let dispatchIssue;
+  let dispatchReply;
+  let delivery;
+  let rejectedDelivery;
+  let malformedDelivery = false;
   let askQuestion;
   let messageReplyPreview;
   const dispatchRendered = envelope.source === "dispatch" && envelope.payload !== undefined;
@@ -31144,6 +31222,20 @@ function renderInbound(raw, sessionID, subject) {
         }
         askQuestion = dispatchAskQuestion(frame.event);
         messageReplyPreview = dispatchMessageReplyPreview(frame.event);
+        if (frame.event.type === "message.created" && frame.event.issue_key !== null) {
+          const message = MessageEventPayloadSchema.safeParse(frame.event.payload);
+          const requested = DispatchDeliveryRequestSchema.safeParse(frame.delivery);
+          if (message.success && requested.success && message.data.id !== undefined) {
+            delivery = {
+              attempt: requested.data.attempt,
+              mode: requested.data.mode,
+              messageID: message.data.id,
+              issueKey: frame.event.issue_key,
+              body: message.data.body ?? envelope.payload_summary ?? ""
+            };
+            dispatchReply = `dispatch_message(issue="${frame.event.issue_key}", in_reply_to="${message.data.id}", body="...")`;
+          }
+        }
         dispatchEvent = {
           owner: dispatchOwner(frame.event, subject ?? envelope.topic),
           ...frame.event.issue_key === null ? {
@@ -31158,6 +31250,8 @@ function renderInbound(raw, sessionID, subject) {
         };
       } else {
         dispatchEvent = frame.raw;
+        rejectedDelivery = frame.rejectedDelivery;
+        malformedDelivery = frame.malformedDelivery === true;
       }
     }
   }
@@ -31182,7 +31276,7 @@ ${envelope.payload ?? ""}`;
     }
   }
   const role = envelope.sender?.roles?.[0];
-  const reply = replyWith(envelope);
+  const reply = dispatchReply ?? replyWith(envelope);
   const sourceIssue = parseIssues.includes("source") || KNOWN_SOURCES[envelope.source] !== undefined ? undefined : `source=${envelope.source}`;
   const unrecognised = [
     ...parseIssues,
@@ -31212,7 +31306,14 @@ ${envelope.payload ?? ""}`;
     },
     ...unrecognised === undefined ? {} : { unrecognised }
   };
-  return { skip: false, content: encode3({ envoy: rendered }), envelope };
+  return {
+    skip: false,
+    content: encode3({ envoy: rendered }),
+    envelope,
+    ...delivery === undefined ? {} : { delivery },
+    ...rejectedDelivery === undefined ? {} : { rejectedDelivery },
+    ...malformedDelivery ? { malformedDelivery: true } : {}
+  };
 }
 
 // ../envoy-client/src/dispatch-config.ts
@@ -31876,13 +31977,13 @@ function askId(args) {
   }
   return reference.id;
 }
-function messageReplyTo(args) {
-  const replyTo = optionalString(args, "reply_to");
-  if (replyTo === undefined || !replyTo.startsWith("dispatch://"))
-    return replyTo;
-  const reference = parseDispatchRef(replyTo);
+function messageInReplyTo(args) {
+  const inReplyTo = optionalString(args, "in_reply_to");
+  if (inReplyTo === undefined || !inReplyTo.startsWith("dispatch://"))
+    return inReplyTo;
+  const reference = parseDispatchRef(inReplyTo);
   if (reference?.kind !== "message") {
-    throw new Error("reply_to must be a bare message id or a dispatch://.../message/<id> reference");
+    throw new Error("in_reply_to must be a bare message id or a dispatch://.../message/<id> reference");
   }
   return reference.id;
 }
@@ -32330,10 +32431,10 @@ async function executeDispatchTool(input) {
       };
     }
     case "dispatch_message": {
-      const replyTo = messageReplyTo(args);
+      const inReplyTo = messageInReplyTo(args);
       const message = await client.message(issue(), {
         body: stringArg(args, "body"),
-        ...replyTo === undefined ? {} : { reply_to: replyTo },
+        ...inReplyTo === undefined ? {} : { in_reply_to: inReplyTo },
         actor
       });
       const messageRef = `dispatch://${message.issue_key}/message/${message.id}`;
@@ -32355,8 +32456,10 @@ async function executeDispatchTool(input) {
         ...summary === undefined ? {} : { summary },
         actor
       });
+      const retyped = ops.filter((operation) => operation.op === "retype").length;
+      const versionText = edited.version === null ? "no new version" : `version ${edited.version.number}`;
       return {
-        text: edited.version === null ? `Applied ${edited.applied} ops (no new version)` : `Applied ${edited.applied} ops (version ${edited.version.number})`,
+        text: retyped === 0 ? `Applied ${edited.applied} ops (${versionText})` : `Applied ${edited.applied} ops; retyped ${retyped} block${retyped === 1 ? "" : "s"} (${versionText})`,
         details: writeResultDetails(resolved, {
           applied: edited.applied,
           ...edited.version === null ? {} : { version: edited.version.number }
@@ -32708,6 +32811,7 @@ var SessionWireSchema = object({
   title: string2(),
   topics: array(string2()),
   roles: array(string2()).optional(),
+  capabilities: array(string2()).optional(),
   self_subscribed: boolean2(),
   last_seen: number2().int().optional()
 });
@@ -32816,6 +32920,7 @@ function createEnvoyClient(config) {
       topics: expandSubscriptionTopics(input.topics),
       port: input.port,
       title: input.title,
+      ...input.capabilities === undefined ? {} : { capabilities: input.capabilities },
       driving: input.driving,
       ...input.selfSubscribed === undefined ? {} : { self_subscribed: input.selfSubscribed }
     }))),
@@ -33050,6 +33155,26 @@ function envoyExtension(pi) {
     });
     return connection;
   };
+  const postDispatchReply = async (delivery, result) => {
+    if (!dispatchConfig.enabled || dispatchConfig.url === null || dispatchConfig.token === null) {
+      throw new Error("Dispatch reply endpoint is not configured");
+    }
+    const response = await fetch(`${dispatchConfig.url}/api/v1/messages/${delivery.messageID}/reply`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${dispatchConfig.token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        actor: { kind: "session", id: sessionID },
+        attempt: delivery.attempt,
+        ...result
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Dispatch reply failed: ${response.status} ${await response.text()}`);
+    }
+  };
   const deliver = async (subject, raw, reply) => {
     const rendered = renderInbound(raw, sessionID, subject);
     for (const topic of subscriptionRemovedTopics(raw, sessionID) ?? [])
@@ -33069,9 +33194,34 @@ function envoyExtension(pi) {
           inbox.pop();
       }
       try {
-        pi.sendMessage({ customType: "envoy-message", content: rendered.content, display: true }, { deliverAs: "steer", triggerTurn: true });
+        if (rendered.rejectedDelivery !== undefined) {
+          console.warn(`[envoy] rejecting malformed Dispatch targeted delivery ${rendered.rejectedDelivery.messageID}`);
+          await postDispatchReply(rendered.rejectedDelivery, {
+            error: "Invalid Dispatch targeted delivery frame"
+          });
+        } else if (rendered.malformedDelivery === true) {
+          console.warn("[envoy] dropping malformed Dispatch targeted delivery without a reply address");
+        } else if (rendered.delivery?.mode === "btw") {
+          if (pi.askEphemeral === undefined) {
+            await postDispatchReply(rendered.delivery, {
+              error: "This OMP host does not support BTW delivery"
+            });
+          } else {
+            try {
+              const reply = await pi.askEphemeral({ prompt: rendered.delivery.body });
+              await postDispatchReply(rendered.delivery, { body: reply.replyText });
+            } catch (error) {
+              await postDispatchReply(rendered.delivery, { error: messageFor(error) });
+            }
+          }
+        } else {
+          pi.sendMessage({ customType: "envoy-message", content: rendered.content, display: true }, {
+            deliverAs: rendered.delivery?.mode === "aside" ? "aside" : "steer",
+            triggerTurn: true
+          });
+        }
       } catch (error) {
-        console.warn(`[envoy] failed to inject envelope ${envelope?.event_id ?? "unknown"}`, error);
+        console.warn(`[envoy] failed to deliver envelope ${envelope?.event_id ?? "unknown"}`, error);
         throw error;
       }
       if (dedupeKey !== undefined) {
@@ -33150,6 +33300,7 @@ function envoyExtension(pi) {
     topics: [...new Set([agentSubject(sessionID), ...subscriptions.keys()])],
     port: 0,
     title: activeSessionContext?.sessionManager.getSessionName?.() ?? "",
+    capabilities: typeof pi.askEphemeral === "function" ? ["aside", "btw"] : ["aside"],
     driving: false,
     selfSubscribed: true
   });

package/dist/legion.js

@@ -29729,10 +29729,20 @@ var CommentEventPayloadSchema = object({
 var MessageEventPayloadSchema = object({
   id: string2().optional(),
   body: string2().optional(),
-  reply_to: string2().nullish(),
+  target: string2().nullish(),
+  in_reply_to: string2().nullish(),
   reply_body: string2().optional(),
   author: object({ kind: string2(), id: string2() }).optional()
 });
+var MessageDeliveryEventPayloadSchema = object({
+  message_id: string2().optional(),
+  attempt: number2().int().positive().optional(),
+  delivery: _enum2(["btw", "aside", "steer"]).optional(),
+  session_id: string2().optional(),
+  title: string2().optional(),
+  state: _enum2(["sent", "failed"]).optional(),
+  error: string2().optional()
+});
 var ChildStatusEventPayloadSchema = object({
   child_key: string2().optional(),
   from: string2().optional(),
@@ -29826,7 +29836,7 @@ var SPEC_SECTIONS = [
 ];
 var SPEC_WRITING_GUIDANCE = `When writing a spec, use these sections in order: ${SPEC_SECTIONS.join(", ")}. ` + "Write for a reader who has not seen the code: plain sentences, every identifier expanded on " + "first use, no coined shorthand; see skills/dispatch Writing for the human and Writing a spec.";
 var ASK_URGENCIES = ["low", "med", "high", "blocking"];
-var DOC_EDIT_OPS = ["replace", "delete", "insert"];
+var DOC_EDIT_OPS = ["replace", "delete", "insert", "retype"];
 var dispatchToolSpecs = [
   {
     name: "dispatch_issue",
@@ -29931,12 +29941,12 @@ var dispatchToolSpecs = [
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
       body: z.string({ max: 2000 }).describe("Update text, at most 2,000 characters."),
-      reply_to: z.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.").optional()
+      in_reply_to: z.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.").optional()
     })
   },
   {
     name: "dispatch_doc_edit",
-    description: "Apply deterministic text edits to an issue or project document. Do not use it for review feedback or for reading; use " + "dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. The spec (or any document) holds requirements, " + `design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
+    description: "Apply deterministic document edits, including retyping an identified paragraph into a schema-declared typed block. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -29949,7 +29959,10 @@ var dispatchToolSpecs = [
         occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based match occurrence.").optional(),
         markdown: z.string().describe("Markdown to insert.").optional(),
         after: z.string().describe("Anchor after which to insert.").optional(),
-        before: z.string().describe("Anchor before which to insert.").optional()
+        before: z.string().describe("Anchor before which to insert.").optional(),
+        block: z.string().describe("Block id to retype.").optional(),
+        type: z.string().describe("Typed block name for retype.").optional(),
+        attributes: z.unknown().describe("Typed block attributes for retype.").optional()
       })).describe("Flat tagged edits; the server validates fields required for each operation."),
       summary: z.string().describe("Optional named-version summary.").optional()
     }),
@@ -30410,6 +30423,7 @@ function zodSchemaApi(zod) {
     },
     boolean: () => api.boolean(),
     enum: (values) => api.enum(values),
+    unknown: () => api.unknown(),
     array: (item, opts = {}) => {
       let schema = api.array(item);
       if (opts.min !== undefined)
@@ -31456,6 +31470,31 @@ var TolerantInboundEnvelopeSchema = object({
   source: InboundEnvelopeSchema.shape.source.optional().catch(undefined),
   sender: object(tolerantShape(InboundSenderSchema.shape)).optional().catch(undefined)
 }).passthrough();
+var DispatchDeliveryRequestSchema = object({
+  attempt: number2().int().positive(),
+  mode: _enum2(["btw", "aside", "steer"])
+});
+var DispatchTargetedMessagePayloadSchema = object({
+  id: string2(),
+  issue_key: string2(),
+  author: object({ kind: string2(), id: string2() }),
+  body: string2(),
+  target: string2(),
+  in_reply_to: string2().nullable(),
+  deliveries: array(unknown()),
+  created_at: string2()
+});
+var DispatchTargetedFrameSchema = object({
+  event: DispatchEventSchema,
+  delivery: DispatchDeliveryRequestSchema
+}).refine(({ event }) => event.type === "message.created" && DispatchTargetedMessagePayloadSchema.safeParse(event.payload).success, { message: "targeted delivery requires a message.created event" });
+var RecoverableDispatchDeliveryFailureSchema = object({
+  event: object({
+    issue_key: string2(),
+    payload: object({ id: string2(), body: string2().optional() }).passthrough()
+  }).passthrough(),
+  delivery: DispatchDeliveryRequestSchema
+});
 function senderLabel(envelope) {
   const sender = envelope.source_session ?? envelope.source ?? "unknown";
   return envelope.sender?.title === undefined ? sender : `${sender} (${envelope.sender.title})`;
@@ -31482,6 +31521,8 @@ var DISPATCH_PAYLOAD_SCHEMAS = {
   "suggestion.accepted": CommentEventPayloadSchema,
   "suggestion.rejected": CommentEventPayloadSchema,
   "message.created": MessageEventPayloadSchema,
+  "message.delivery": MessageDeliveryEventPayloadSchema,
+  "message.answered": MessageEventPayloadSchema,
   "child.status": ChildStatusEventPayloadSchema
 };
 function dispatchOwner(event, topic) {
@@ -31514,6 +31555,9 @@ function dispatchMessageReplyPreview(event) {
   const parsed = MessageEventPayloadSchema.safeParse(event.payload);
   return parsed.success && parsed.data.reply_body !== undefined && parsed.data.reply_body !== "" ? parsed.data.reply_body : undefined;
 }
+function isObject2(value) {
+  return typeof value === "object" && value !== null;
+}
 function parseDispatchFrame(rawPayload) {
   let value;
   try {
@@ -31521,11 +31565,41 @@ function parseDispatchFrame(rawPayload) {
   } catch {
     return { raw: rawPayload };
   }
+  const targeted = DispatchTargetedFrameSchema.safeParse(value);
+  if (targeted.success) {
+    const wireFrame = value;
+    return {
+      event: targeted.data.event,
+      notify: wireFrame.event.notify,
+      delivery: targeted.data.delivery
+    };
+  }
+  if (isObject2(value) && "delivery" in value) {
+    const recoverable = RecoverableDispatchDeliveryFailureSchema.safeParse(value);
+    if (recoverable.success) {
+      return {
+        raw: value,
+        rejectedDelivery: {
+          attempt: recoverable.data.delivery.attempt,
+          mode: recoverable.data.delivery.mode,
+          messageID: recoverable.data.event.payload.id,
+          issueKey: recoverable.data.event.issue_key,
+          body: recoverable.data.event.payload.body ?? ""
+        },
+        malformedDelivery: true
+      };
+    }
+    return { raw: value, malformedDelivery: true };
+  }
   const parsed = DispatchEventSchema.safeParse(value);
   if (!parsed.success)
     return { raw: value };
   const wireEvent = value;
-  return { event: parsed.data, notify: wireEvent.notify };
+  return {
+    event: parsed.data,
+    notify: wireEvent.notify,
+    delivery: undefined
+  };
 }
 function inboundTimestamp(milliseconds) {
   if (milliseconds === undefined)
@@ -31563,6 +31637,10 @@ function renderInbound(raw, sessionID, subject) {
   }
   let dispatchEvent;
   let dispatchIssue;
+  let dispatchReply;
+  let delivery;
+  let rejectedDelivery;
+  let malformedDelivery = false;
   let askQuestion;
   let messageReplyPreview;
   const dispatchRendered = envelope.source === "dispatch" && envelope.payload !== undefined;
@@ -31592,6 +31670,20 @@ function renderInbound(raw, sessionID, subject) {
         }
         askQuestion = dispatchAskQuestion(frame.event);
         messageReplyPreview = dispatchMessageReplyPreview(frame.event);
+        if (frame.event.type === "message.created" && frame.event.issue_key !== null) {
+          const message = MessageEventPayloadSchema.safeParse(frame.event.payload);
+          const requested = DispatchDeliveryRequestSchema.safeParse(frame.delivery);
+          if (message.success && requested.success && message.data.id !== undefined) {
+            delivery = {
+              attempt: requested.data.attempt,
+              mode: requested.data.mode,
+              messageID: message.data.id,
+              issueKey: frame.event.issue_key,
+              body: message.data.body ?? envelope.payload_summary ?? ""
+            };
+            dispatchReply = `dispatch_message(issue="${frame.event.issue_key}", in_reply_to="${message.data.id}", body="...")`;
+          }
+        }
         dispatchEvent = {
           owner: dispatchOwner(frame.event, subject ?? envelope.topic),
           ...frame.event.issue_key === null ? {
@@ -31606,6 +31698,8 @@ function renderInbound(raw, sessionID, subject) {
         };
       } else {
         dispatchEvent = frame.raw;
+        rejectedDelivery = frame.rejectedDelivery;
+        malformedDelivery = frame.malformedDelivery === true;
       }
     }
   }
@@ -31630,7 +31724,7 @@ ${envelope.payload ?? ""}`;
     }
   }
   const role = envelope.sender?.roles?.[0];
-  const reply = replyWith(envelope);
+  const reply = dispatchReply ?? replyWith(envelope);
   const sourceIssue = parseIssues.includes("source") || KNOWN_SOURCES[envelope.source] !== undefined ? undefined : `source=${envelope.source}`;
   const unrecognised = [
     ...parseIssues,
@@ -31660,7 +31754,14 @@ ${envelope.payload ?? ""}`;
     },
     ...unrecognised === undefined ? {} : { unrecognised }
   };
-  return { skip: false, content: encode3({ envoy: rendered }), envelope };
+  return {
+    skip: false,
+    content: encode3({ envoy: rendered }),
+    envelope,
+    ...delivery === undefined ? {} : { delivery },
+    ...rejectedDelivery === undefined ? {} : { rejectedDelivery },
+    ...malformedDelivery ? { malformedDelivery: true } : {}
+  };
 }
 
 // ../envoy-client/src/dispatch-config.ts
@@ -32302,13 +32403,13 @@ function askId(args) {
   }
   return reference.id;
 }
-function messageReplyTo(args) {
-  const replyTo = optionalString(args, "reply_to");
-  if (replyTo === undefined || !replyTo.startsWith("dispatch://"))
-    return replyTo;
-  const reference = parseDispatchRef(replyTo);
+function messageInReplyTo(args) {
+  const inReplyTo = optionalString(args, "in_reply_to");
+  if (inReplyTo === undefined || !inReplyTo.startsWith("dispatch://"))
+    return inReplyTo;
+  const reference = parseDispatchRef(inReplyTo);
   if (reference?.kind !== "message") {
-    throw new Error("reply_to must be a bare message id or a dispatch://.../message/<id> reference");
+    throw new Error("in_reply_to must be a bare message id or a dispatch://.../message/<id> reference");
   }
   return reference.id;
 }
@@ -32756,10 +32857,10 @@ async function executeDispatchTool(input) {
       };
     }
     case "dispatch_message": {
-      const replyTo = messageReplyTo(args);
+      const inReplyTo = messageInReplyTo(args);
       const message = await client.message(issue(), {
         body: stringArg(args, "body"),
-        ...replyTo === undefined ? {} : { reply_to: replyTo },
+        ...inReplyTo === undefined ? {} : { in_reply_to: inReplyTo },
         actor
       });
       const messageRef = `dispatch://${message.issue_key}/message/${message.id}`;
@@ -32781,8 +32882,10 @@ async function executeDispatchTool(input) {
         ...summary === undefined ? {} : { summary },
         actor
       });
+      const retyped = ops.filter((operation) => operation.op === "retype").length;
+      const versionText = edited.version === null ? "no new version" : `version ${edited.version.number}`;
       return {
-        text: edited.version === null ? `Applied ${edited.applied} ops (no new version)` : `Applied ${edited.applied} ops (version ${edited.version.number})`,
+        text: retyped === 0 ? `Applied ${edited.applied} ops (${versionText})` : `Applied ${edited.applied} ops; retyped ${retyped} block${retyped === 1 ? "" : "s"} (${versionText})`,
         details: writeResultDetails(resolved, {
           applied: edited.applied,
           ...edited.version === null ? {} : { version: edited.version.number }
@@ -33134,6 +33237,7 @@ var SessionWireSchema = object({
   title: string2(),
   topics: array(string2()),
   roles: array(string2()).optional(),
+  capabilities: array(string2()).optional(),
   self_subscribed: boolean2(),
   last_seen: number2().int().optional()
 });
@@ -33242,6 +33346,7 @@ function createEnvoyClient(config) {
       topics: expandSubscriptionTopics(input.topics),
       port: input.port,
       title: input.title,
+      ...input.capabilities === undefined ? {} : { capabilities: input.capabilities },
       driving: input.driving,
       ...input.selfSubscribed === undefined ? {} : { self_subscribed: input.selfSubscribed }
     }))),
@@ -33468,6 +33573,26 @@ function envoyExtension(pi) {
     });
     return connection;
   };
+  const postDispatchReply = async (delivery, result) => {
+    if (!dispatchConfig.enabled || dispatchConfig.url === null || dispatchConfig.token === null) {
+      throw new Error("Dispatch reply endpoint is not configured");
+    }
+    const response = await fetch(`${dispatchConfig.url}/api/v1/messages/${delivery.messageID}/reply`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${dispatchConfig.token}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        actor: { kind: "session", id: sessionID },
+        attempt: delivery.attempt,
+        ...result
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Dispatch reply failed: ${response.status} ${await response.text()}`);
+    }
+  };
   const deliver = async (subject, raw, reply) => {
     const rendered = renderInbound(raw, sessionID, subject);
     for (const topic of subscriptionRemovedTopics(raw, sessionID) ?? [])
@@ -33487,9 +33612,34 @@ function envoyExtension(pi) {
           inbox.pop();
       }
       try {
-        pi.sendMessage({ customType: "envoy-message", content: rendered.content, display: true }, { deliverAs: "steer", triggerTurn: true });
+        if (rendered.rejectedDelivery !== undefined) {
+          console.warn(`[envoy] rejecting malformed Dispatch targeted delivery ${rendered.rejectedDelivery.messageID}`);
+          await postDispatchReply(rendered.rejectedDelivery, {
+            error: "Invalid Dispatch targeted delivery frame"
+          });
+        } else if (rendered.malformedDelivery === true) {
+          console.warn("[envoy] dropping malformed Dispatch targeted delivery without a reply address");
+        } else if (rendered.delivery?.mode === "btw") {
+          if (pi.askEphemeral === undefined) {
+            await postDispatchReply(rendered.delivery, {
+              error: "This OMP host does not support BTW delivery"
+            });
+          } else {
+            try {
+              const reply = await pi.askEphemeral({ prompt: rendered.delivery.body });
+              await postDispatchReply(rendered.delivery, { body: reply.replyText });
+            } catch (error) {
+              await postDispatchReply(rendered.delivery, { error: messageFor(error) });
+            }
+          }
+        } else {
+          pi.sendMessage({ customType: "envoy-message", content: rendered.content, display: true }, {
+            deliverAs: rendered.delivery?.mode === "aside" ? "aside" : "steer",
+            triggerTurn: true
+          });
+        }
       } catch (error) {
-        console.warn(`[envoy] failed to inject envelope ${envelope?.event_id ?? "unknown"}`, error);
+        console.warn(`[envoy] failed to deliver envelope ${envelope?.event_id ?? "unknown"}`, error);
         throw error;
       }
       if (dedupeKey !== undefined) {
@@ -33568,6 +33718,7 @@ function envoyExtension(pi) {
     topics: [...new Set([agentSubject(sessionID), ...subscriptions.keys()])],
     port: 0,
     title: activeSessionContext?.sessionManager.getSessionName?.() ?? "",
+    capabilities: typeof pi.askEphemeral === "function" ? ["aside", "btw"] : ["aside"],
     driving: false,
     selfSubscribed: true
   });

package/dist/skills/dispatch/SKILL.md

@@ -199,13 +199,16 @@ exact `EditOp` shape:
 
 ```ts
 type EditOp = {
-  op: "replace" | "delete" | "insert";
+  op: "replace" | "delete" | "insert" | "retype";
   find?: string;
   with?: string;
   occurrence?: number;
   markdown?: string;
   after?: string;
   before?: string;
+  block?: string;
+  type?: string;
+  attributes?: Record<string, unknown>;
 };
 ```
 
@@ -221,6 +224,9 @@ and deleting a cell's quoted text removes only that text.
 
 Use `replace` for inline continuation. Use zero-based `occurrence` for a repeated target; re-read a missing or ambiguous target before
 retrying. Pass `summary` to name the version when recording a decision.
+`retype` turns the paragraph with `block` into the named typed `type` in place. It keeps the
+block id and uses `attributes` for client-owned typed attributes. Use it when an existing
+paragraph is the question that should become a decision.
 
 ## Typed blocks
 
@@ -236,6 +242,19 @@ quoted: `:::callout{kind="warning" title="Risk"}`. Do not write Pandoc-style `::
 block. Do not set attributes the schema marks `server: true`; the server ignores them and reasserts
 its authoritative value at settlement.
 
+Questions about a document must be `ask` blocks, never an `Open questions` prose section. An ask
+body is one or more question paragraphs followed by an optional bullet list of options, where each
+item is `Label: description`. For example:
+
+```md
+:::ask{urgency="high" multiple="false"}
+Should we ship the migration?
+
+- Ship: Release the verified change.
+- Hold: Wait for another review.
+:::
+```
+
 ## Comments and suggestions
 
 Add feedback with:
@@ -298,6 +317,24 @@ dispatch_message({ issue, body })
 It returns `details` `{ issue, topic, message }`. `body` is capped at 2,000 characters. A message is not a decision
 (`dispatch_ask`) or document feedback (`dispatch_comment`), and it does not wake anyone unless the issue is routed.
 
+### Targeted agent messages
+
+A human can target the issue message at a live Envoy session or role as **BTW**, **Aside**, or
+**Steer**. The incoming Dispatch frame names the issue and includes a `reply_with` instruction;
+reply on the same open issue with the existing tool, never a new targeted send:
+
+```ts
+dispatch_message({
+  issue: "CORE-1",
+  in_reply_to: "<targeted-message-id>",
+  body: "The requested answer.",
+})
+```
+
+`in_reply_to` correlates the answer under the human's message in its Conversation card. A BTW
+delivery can post its answer automatically; use this call when the frame asks the primary agent to
+reply. Agent bearers cannot set `target` or `delivery`.
+
 ## What comes back
 
 A write result's `details.topic` subscribes the host to its owner, and the first such subscription on an issue or document also tells

package/package.json

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