@sjawhar/pi-legion-envoy 0.42.0 → 0.44.0

package/dist/envoy.js

@@ -29725,6 +29725,11 @@ var ChildStatusEventPayloadSchema = object({
   from: string2().optional(),
   to: string2().optional()
 });
+var SubscriptionRemovedEventPayloadSchema = object({
+  session_id: string2().optional(),
+  by: object({ kind: string2(), id: string2().optional() }).passthrough().optional(),
+  topics: array(string2()).optional()
+});
 // ../contracts/src/dispatch-snippet.ts
 var HTML_ENTITIES = [
   ["&lt;", "<"],
@@ -29782,15 +29787,17 @@ function dispatchToolSchema(spec, z, opts) {
 }
 var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference; an external reference creates its native issue in the repository's dashboard-configured project or, failing that, the default project (DISPATCH_DEFAULT_PROJECT).";
 var OWNER_REFERENCE = "Exactly one of issue and project is required. An issue is a native KEY or external owner/repo#n reference; a project is a project key such as CORE and addresses an unlinked project document named by artifact.";
-function documentOwnerValidation(requireArtifact) {
+function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false) {
   return {
     check: (value) => {
       const input = value;
       const hasIssue = typeof input.issue === "string";
       const hasProject = typeof input.project === "string";
-      return (hasIssue !== hasProject || !hasIssue && !hasProject && typeof input.ref === "string") && (!hasProject || !requireArtifact || typeof input.artifact === "string");
+      const hasArtifact = typeof input.artifact === "string";
+      const hasRef = typeof input.ref === "string";
+      return (hasIssue !== hasProject || !hasIssue && !hasProject && hasRef) && (!hasProject || !requireArtifact || hasArtifact) && (!alwaysRequireArtifact || hasArtifact || hasRef);
     },
-    message: "Exactly one of issue and project is required; with project, artifact names the document."
+    message: alwaysRequireArtifact ? "Exactly one of issue and project is required; artifact or ref must name the document." : "Exactly one of issue and project is required; with project, artifact names the document."
   };
 }
 var SPEC_SECTIONS = [
@@ -29825,6 +29832,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 slug or id.").optional(),
+      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       question: z.string({ max: 800 }).describe("Decision question, at most 800 characters."),
       options: z.array(z.object({
         label: z.string().describe("Selectable option label."),
@@ -29877,6 +29885,7 @@ var dispatchToolSpecs = [
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
       artifact: z.string().describe("Artifact slug or id required when quote is given.").optional(),
+      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       quote: z.string().describe("Optional exact quoted document text.").optional(),
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional(),
       body: z.string({ max: 2000 }).describe("Review comment, at most 2,000 characters."),
@@ -29891,13 +29900,14 @@ var dispatchToolSpecs = [
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
-      artifact: z.string().describe("Artifact slug or id containing the quoted text."),
+      artifact: z.string().describe("Artifact slug or id containing the quoted text; optional when ref names it.").optional(),
+      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       quote: z.string().describe("Exact document text to replace."),
       replace_with: z.string().describe("Replacement text."),
       body: z.string({ max: 2000 }).describe("Optional rationale, at most 2,000 characters.").optional(),
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional()
     }),
-    validation: documentOwnerValidation(true)
+    validation: documentOwnerValidation(true, true)
   },
   {
     name: "dispatch_message",
@@ -29914,7 +29924,8 @@ var dispatchToolSpecs = [
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
-      artifact: z.string().describe("Artifact slug or id for the document."),
+      artifact: z.string().describe("Artifact slug or id for the document; optional when ref names it.").optional(),
+      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       ops: z.array(z.object({
         op: z.enum(DOC_EDIT_OPS).describe("Edit operation."),
         find: z.string().describe("Text to find for replace or delete.").optional(),
@@ -29926,7 +29937,7 @@ var dispatchToolSpecs = [
       })).describe("Flat tagged edits; the server validates fields required for each operation."),
       summary: z.string().describe("Optional named-version summary.").optional()
     }),
-    validation: documentOwnerValidation(true)
+    validation: documentOwnerValidation(true, true)
   },
   {
     name: "dispatch_doc_read",
@@ -31101,6 +31112,18 @@ function renderInbound(raw, sessionID, subject) {
         if (frame.event.actor.kind === "session" && frame.event.actor.id === sessionID) {
           return { skip: true, content: "", envelope };
         }
+        if (frame.event.type === "subscription.removed") {
+          const removed = SubscriptionRemovedEventPayloadSchema.safeParse(frame.event.payload);
+          if (!removed.success || removed.data.session_id !== sessionID) {
+            return { skip: true, content: "", envelope };
+          }
+          const who = removed.data.by?.id ?? "someone";
+          return {
+            skip: false,
+            content: `Unsubscribed from ${dispatchOwner(frame.event, subject ?? envelope.topic)} by ${who}`,
+            envelope
+          };
+        }
         askQuestion = dispatchAskQuestion(frame.event);
         messageReplyPreview = dispatchMessageReplyPreview(frame.event);
         dispatchEvent = {
@@ -32381,6 +32404,46 @@ function dispatchSubscriptionTopic(details) {
   const { topic } = details;
   return typeof topic === "string" && topic.startsWith("notifications.dispatch.") ? topic : null;
 }
+function dispatchTopicLabel(topic) {
+  if (topic.startsWith(DISPATCH_ISSUE_TOPIC_PREFIX)) {
+    const [key] = topic.slice(DISPATCH_ISSUE_TOPIC_PREFIX.length).split(".", 2);
+    if (key !== undefined && key !== "")
+      return key;
+  }
+  if (topic.startsWith(DISPATCH_DOCUMENT_TOPIC_PREFIX)) {
+    const [project, slug] = topic.slice(DISPATCH_DOCUMENT_TOPIC_PREFIX.length).split(".", 3);
+    if (project !== undefined && project !== "" && slug !== undefined && slug !== "") {
+      return `${project}/${slug}`;
+    }
+  }
+  return topic;
+}
+function subscriptionRemovedTopics(raw, sessionID) {
+  let envelope;
+  try {
+    envelope = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (typeof envelope !== "object" || envelope === null)
+    return;
+  const { source, payload } = envelope;
+  if (source !== "dispatch" || typeof payload !== "string")
+    return;
+  let event;
+  try {
+    event = JSON.parse(payload);
+  } catch {
+    return;
+  }
+  const parsedEvent = DispatchEventSchema.safeParse(event);
+  if (!parsedEvent.success || parsedEvent.data.type !== "subscription.removed")
+    return;
+  const parsedPayload = SubscriptionRemovedEventPayloadSchema.safeParse(parsedEvent.data.payload);
+  if (!parsedPayload.success || parsedPayload.data.session_id !== sessionID)
+    return;
+  return parsedPayload.data.topics ?? [];
+}
 
 // ../envoy-client/src/tool-contract.ts
 var DELIVERY_CONTRACT = "Delivery is at-least-once, possibly out of order across topics; use id for dedupe and at for freshness.";
@@ -32858,6 +32921,8 @@ function envoyExtension(pi) {
   };
   const deliver = async (subject, raw, reply) => {
     const rendered = renderInbound(raw, sessionID, subject);
+    for (const topic of subscriptionRemovedTopics(raw, sessionID) ?? [])
+      closeIntentionally(topic);
     const dedupeKey = rendered.envelope?.dedupe_key;
     const duplicate = dedupeKey !== undefined && dedupeKeys.has(dedupeKey);
     if (!duplicate && !rendered.skip) {
@@ -33249,8 +33314,16 @@ function envoyExtension(pi) {
     if (topic === null)
       return;
     try {
-      if (await subscribe(topic))
+      const isNew = await subscribe(topic);
+      if (isNew)
         await registerSession();
+      if (isNew) {
+        pi.sendMessage({
+          customType: "envoy-message",
+          content: `Subscribed to ${dispatchTopicLabel(topic)} (every event on this issue reaches you; envoy_unsubscribe ${topic} to stop).`,
+          display: true
+        }, { deliverAs: "steer", triggerTurn: false });
+      }
     } catch (error) {
       activeSessionContext?.ui.notify(`envoy: dispatch reply auto-subscribe failed (${messageFor(error)}); run envoy_subscribe ${topic}`, "warning");
     }

package/dist/legion.js

@@ -29724,6 +29724,11 @@ var ChildStatusEventPayloadSchema = object({
   from: string2().optional(),
   to: string2().optional()
 });
+var SubscriptionRemovedEventPayloadSchema = object({
+  session_id: string2().optional(),
+  by: object({ kind: string2(), id: string2().optional() }).passthrough().optional(),
+  topics: array(string2()).optional()
+});
 // ../contracts/src/dispatch-snippet.ts
 var HTML_ENTITIES = [
   ["&lt;", "<"],
@@ -29781,15 +29786,17 @@ function dispatchToolSchema(spec, z, opts) {
 }
 var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference; an external reference creates its native issue in the repository's dashboard-configured project or, failing that, the default project (DISPATCH_DEFAULT_PROJECT).";
 var OWNER_REFERENCE = "Exactly one of issue and project is required. An issue is a native KEY or external owner/repo#n reference; a project is a project key such as CORE and addresses an unlinked project document named by artifact.";
-function documentOwnerValidation(requireArtifact) {
+function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false) {
   return {
     check: (value) => {
       const input = value;
       const hasIssue = typeof input.issue === "string";
       const hasProject = typeof input.project === "string";
-      return (hasIssue !== hasProject || !hasIssue && !hasProject && typeof input.ref === "string") && (!hasProject || !requireArtifact || typeof input.artifact === "string");
+      const hasArtifact = typeof input.artifact === "string";
+      const hasRef = typeof input.ref === "string";
+      return (hasIssue !== hasProject || !hasIssue && !hasProject && hasRef) && (!hasProject || !requireArtifact || hasArtifact) && (!alwaysRequireArtifact || hasArtifact || hasRef);
     },
-    message: "Exactly one of issue and project is required; with project, artifact names the document."
+    message: alwaysRequireArtifact ? "Exactly one of issue and project is required; artifact or ref must name the document." : "Exactly one of issue and project is required; with project, artifact names the document."
   };
 }
 var SPEC_SECTIONS = [
@@ -29824,6 +29831,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 slug or id.").optional(),
+      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       question: z.string({ max: 800 }).describe("Decision question, at most 800 characters."),
       options: z.array(z.object({
         label: z.string().describe("Selectable option label."),
@@ -29876,6 +29884,7 @@ var dispatchToolSpecs = [
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
       artifact: z.string().describe("Artifact slug or id required when quote is given.").optional(),
+      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       quote: z.string().describe("Optional exact quoted document text.").optional(),
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional(),
       body: z.string({ max: 2000 }).describe("Review comment, at most 2,000 characters."),
@@ -29890,13 +29899,14 @@ var dispatchToolSpecs = [
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
-      artifact: z.string().describe("Artifact slug or id containing the quoted text."),
+      artifact: z.string().describe("Artifact slug or id containing the quoted text; optional when ref names it.").optional(),
+      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       quote: z.string().describe("Exact document text to replace."),
       replace_with: z.string().describe("Replacement text."),
       body: z.string({ max: 2000 }).describe("Optional rationale, at most 2,000 characters.").optional(),
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional()
     }),
-    validation: documentOwnerValidation(true)
+    validation: documentOwnerValidation(true, true)
   },
   {
     name: "dispatch_message",
@@ -29913,7 +29923,8 @@ var dispatchToolSpecs = [
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
-      artifact: z.string().describe("Artifact slug or id for the document."),
+      artifact: z.string().describe("Artifact slug or id for the document; optional when ref names it.").optional(),
+      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional(),
       ops: z.array(z.object({
         op: z.enum(DOC_EDIT_OPS).describe("Edit operation."),
         find: z.string().describe("Text to find for replace or delete.").optional(),
@@ -29925,7 +29936,7 @@ var dispatchToolSpecs = [
       })).describe("Flat tagged edits; the server validates fields required for each operation."),
       summary: z.string().describe("Optional named-version summary.").optional()
     }),
-    validation: documentOwnerValidation(true)
+    validation: documentOwnerValidation(true, true)
   },
   {
     name: "dispatch_doc_read",
@@ -31548,6 +31559,18 @@ function renderInbound(raw, sessionID, subject) {
         if (frame.event.actor.kind === "session" && frame.event.actor.id === sessionID) {
           return { skip: true, content: "", envelope };
         }
+        if (frame.event.type === "subscription.removed") {
+          const removed = SubscriptionRemovedEventPayloadSchema.safeParse(frame.event.payload);
+          if (!removed.success || removed.data.session_id !== sessionID) {
+            return { skip: true, content: "", envelope };
+          }
+          const who = removed.data.by?.id ?? "someone";
+          return {
+            skip: false,
+            content: `Unsubscribed from ${dispatchOwner(frame.event, subject ?? envelope.topic)} by ${who}`,
+            envelope
+          };
+        }
         askQuestion = dispatchAskQuestion(frame.event);
         messageReplyPreview = dispatchMessageReplyPreview(frame.event);
         dispatchEvent = {
@@ -32821,6 +32844,46 @@ function dispatchSubscriptionTopic(details) {
   const { topic } = details;
   return typeof topic === "string" && topic.startsWith("notifications.dispatch.") ? topic : null;
 }
+function dispatchTopicLabel(topic) {
+  if (topic.startsWith(DISPATCH_ISSUE_TOPIC_PREFIX)) {
+    const [key] = topic.slice(DISPATCH_ISSUE_TOPIC_PREFIX.length).split(".", 2);
+    if (key !== undefined && key !== "")
+      return key;
+  }
+  if (topic.startsWith(DISPATCH_DOCUMENT_TOPIC_PREFIX)) {
+    const [project, slug] = topic.slice(DISPATCH_DOCUMENT_TOPIC_PREFIX.length).split(".", 3);
+    if (project !== undefined && project !== "" && slug !== undefined && slug !== "") {
+      return `${project}/${slug}`;
+    }
+  }
+  return topic;
+}
+function subscriptionRemovedTopics(raw, sessionID) {
+  let envelope;
+  try {
+    envelope = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (typeof envelope !== "object" || envelope === null)
+    return;
+  const { source, payload } = envelope;
+  if (source !== "dispatch" || typeof payload !== "string")
+    return;
+  let event;
+  try {
+    event = JSON.parse(payload);
+  } catch {
+    return;
+  }
+  const parsedEvent = DispatchEventSchema.safeParse(event);
+  if (!parsedEvent.success || parsedEvent.data.type !== "subscription.removed")
+    return;
+  const parsedPayload = SubscriptionRemovedEventPayloadSchema.safeParse(parsedEvent.data.payload);
+  if (!parsedPayload.success || parsedPayload.data.session_id !== sessionID)
+    return;
+  return parsedPayload.data.topics ?? [];
+}
 
 // ../envoy-client/src/tool-contract.ts
 var DELIVERY_CONTRACT = "Delivery is at-least-once, possibly out of order across topics; use id for dedupe and at for freshness.";
@@ -33290,6 +33353,8 @@ function envoyExtension(pi) {
   };
   const deliver = async (subject, raw, reply) => {
     const rendered = renderInbound(raw, sessionID, subject);
+    for (const topic of subscriptionRemovedTopics(raw, sessionID) ?? [])
+      closeIntentionally(topic);
     const dedupeKey = rendered.envelope?.dedupe_key;
     const duplicate = dedupeKey !== undefined && dedupeKeys.has(dedupeKey);
     if (!duplicate && !rendered.skip) {
@@ -33681,8 +33746,16 @@ function envoyExtension(pi) {
     if (topic === null)
       return;
     try {
-      if (await subscribe(topic))
+      const isNew = await subscribe(topic);
+      if (isNew)
         await registerSession();
+      if (isNew) {
+        pi.sendMessage({
+          customType: "envoy-message",
+          content: `Subscribed to ${dispatchTopicLabel(topic)} (every event on this issue reaches you; envoy_unsubscribe ${topic} to stop).`,
+          display: true
+        }, { deliverAs: "steer", triggerTurn: false });
+      }
     } catch (error) {
       activeSessionContext?.ui.notify(`envoy: dispatch reply auto-subscribe failed (${messageFor(error)}); run envoy_subscribe ${topic}`, "warning");
     }

package/dist/skills/dispatch/SKILL.md

@@ -169,19 +169,22 @@ retrying. Pass `summary` to name the version when recording a decision.
 Add feedback with:
 
 ```ts
-dispatch_comment({ issue?, project?, artifact?, quote?, occurrence?, body, reply_to?, reply_to_ask? })
+dispatch_comment({ issue?, project?, artifact?, ref?, quote?, occurrence?, body, reply_to?, reply_to_ask? })
 ```
 
-It returns issue or project-document owner details plus `comment` and, for writes, `topic`. `quote` requires `artifact`; omit both for a
-floating issue comment. A reply (`reply_to`/`reply_to_ask`) takes no `quote`; it belongs to its parent's anchor. Use `reply_to` to
-continue a comment thread at its root; a reply to a resolved thread reopens it. Use `reply_to_ask` to reply directly under a question
-asked with `dispatch_ask`. Comments are edited only by their author from the dashboard. A delivered `comment.created` event carries the
-comment `id`; reply to it with `dispatch_comment({ reply_to: <id> })`.
+It returns issue or project-document owner details plus `comment` and, for writes, `topic`.
+`ref` names the owner (an issue or project-document reference) in place of `issue`/`project`.
+`quote` requires `artifact`; omit both for a floating issue comment. A reply (`reply_to`/`reply_to_ask`)
+takes no `quote`; it belongs to its parent's anchor. Use `reply_to` to continue a comment thread at
+its root; a reply to a resolved thread reopens it. Use `reply_to_ask` to reply directly under a
+question asked with `dispatch_ask`. Comments are edited only by their author from the dashboard. A
+delivered `comment.created` event carries the comment `id`; reply to it with
+`dispatch_comment({ reply_to: <id> })`.
 
 Propose an exact replacement instead of describing it:
 
 ```ts
-dispatch_suggest({ issue?, project?, artifact, quote, replace_with, body?, occurrence? })
+dispatch_suggest({ issue?, project?, artifact, ref?, quote, replace_with, body?, occurrence? })
 ```
 
 It returns issue or project-document owner details plus `comment` and its write `topic`. A human accepts or rejects a suggestion.
@@ -223,9 +226,11 @@ It returns `details` `{ issue, topic, message }`. `body` is capped at 2,000 char
 
 ## What comes back
 
-A write result's `details.topic` subscribes the host to its owner. Issue writes use `notifications.dispatch.issue.<KEY>.>`;
+A write result's `details.topic` subscribes the host to its owner, and the first such subscription on an issue or document also tells
+you so (an already-subscribed write stays quiet — no repeat notice). Issue writes use `notifications.dispatch.issue.<KEY>.>`;
 project-document writes use `notifications.dispatch.document.<PROJECT>.<SLUG>.>`. The owner topic carries every Dispatch event; `notify`
-only controls agent wake and routed delivery. After a restart, catch up with:
+only controls agent wake and routed delivery. A human may unsubscribe you from the issue or document header; you are told with a
+`subscription.removed` notice when that happens. After a restart, catch up with:
 
 ```ts
 dispatch_read({ issue?, project?, artifact?, ref? })
@@ -238,7 +243,12 @@ message ref, it returns that message and its reply chain. Reads do not subscribe
 
 ## References
 
-Use these in document, ask, comment, and message bodies; Dispatch unfurls them:
+Use these in document, ask, comment, and message bodies. In the dashboard, a reference renders
+as an inline link whose text is the target's title (an issue's title, an ask's question, a
+comment's first line, a document's name) once it resolves; a body that is only a bare reference
+still gets an unfurl card instead. Every `ref` argument below (and `issue`/`project`) accepts
+either form — an issue key or a project key is never ambiguous, since a project key never
+contains a dash:
 
 ```text
 dispatch://KEY

package/package.json

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