@sjawhar/opencode-legion-envoy 0.42.0 → 0.44.0

package/dist/src/server.js

@@ -13628,6 +13628,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;", "<"],
@@ -13685,15 +13690,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 = [
@@ -13728,6 +13735,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."),
@@ -13780,6 +13788,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."),
@@ -13794,13 +13803,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",
@@ -13817,7 +13827,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(),
@@ -13829,7 +13840,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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {

package/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