@sjawhar/pi-legion-envoy 1.6.0 → 1.8.0

package/dist/envoy.js

@@ -29662,6 +29662,7 @@ var DispatchEventSchema = object({
 });
 var IssueEventPayloadSchema = object({
   title: string2().optional(),
+  labels: array(string2()).optional(),
   status: string2().optional(),
   rank: string2().optional(),
   route: string2().nullish()
@@ -29837,7 +29838,8 @@ var dispatchToolSpecs = [
       parent: z.string().describe("Optional parent issue.").optional(),
       external: z.string().describe("Optional external issue reference.").optional(),
       force: z.boolean().describe("Create even though POSSIBLE_DUPLICATE listed similar issues; pass it only after reading them.").optional(),
-      spec: z.string().describe(`Optional initial primary-document markdown. ${SPEC_WRITING_GUIDANCE}`).optional()
+      spec: z.string().describe(`Optional initial primary-document markdown. ${SPEC_WRITING_GUIDANCE}`).optional(),
+      labels: z.array(z.string({ min: 1, max: 40 }), { max: 20 }).describe("Optional initial labels, at most 20 labels of up to 40 characters.").optional()
     })
   },
   {
@@ -29846,7 +29848,7 @@ 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("Project document slug or id.").optional(),
+      artifact: z.string().describe("Project document artifact id, slug, or filename.").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({
@@ -29899,7 +29901,7 @@ 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 required when quote is given.").optional(),
+      artifact: z.string().describe("Project document artifact id, slug, or filename 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(),
@@ -29915,7 +29917,7 @@ 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; optional when ref names it.").optional(),
+      artifact: z.string().describe("Project document artifact id, slug, or filename 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."),
@@ -29939,7 +29941,7 @@ 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; optional when ref names it.").optional(),
+      artifact: z.string().describe("Project document artifact id, slug, or filename; 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."),
@@ -29960,7 +29962,7 @@ 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("Optional artifact slug or id; primary document by default for an issue.").optional(),
+      artifact: z.string().describe("Optional project document artifact id, slug, or filename; primary document by default for an issue.").optional(),
       version: z.number({ int: true, min: 1 }).describe("Optional version number.").optional(),
       ref: z.string().describe("Optional dispatch:// document reference.").optional()
     }),
@@ -29972,7 +29974,7 @@ 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; primary document by default for an issue.").optional()
+      artifact: z.string().describe("Project document artifact id, slug, or filename; primary document by default for an issue.").optional()
     }),
     validation: documentOwnerValidation(true)
   },
@@ -30001,7 +30003,7 @@ 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("Project document slug or id.").optional(),
+      artifact: z.string().describe("Project document artifact id, slug, or filename.").optional(),
       ref: z.string().describe("Optional dispatch:// issue or document reference.").optional()
     }),
     validation: documentOwnerValidation(true)
@@ -31582,6 +31584,9 @@ class DispatchClient {
   async docRead(id, version) {
     return version === undefined ? this.#json("GET", ["api", "v1", "artifacts", id, "text"]) : this.#json("GET", ["api", "v1", "artifacts", id, "versions", String(version)]);
   }
+  async artifactBlocks(id) {
+    return this.#json("GET", ["api", "v1", "artifacts", id, "blocks"]);
+  }
   async docEdit(id, input) {
     return this.#json("POST", ["api", "v1", "artifacts", id, "edits"], input);
   }
@@ -31892,7 +31897,7 @@ async function resolveOwnerArguments(tool, args, cwd, env, exec) {
     return { args, ref: null, owner: null };
   const refArgument = args.ref;
   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/<slug>");
+    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;
   const issueArgument = args.issue;
   const projectArgument = args.project;
@@ -31973,14 +31978,16 @@ async function resolveArtifact(client, owner, artifactReference) {
       if (!(error instanceof DispatchServiceError) || error.status !== 404)
         throw error;
       const artifacts = await client.listProjectArtifacts(owner.project, true);
-      const matches = artifacts.filter((candidate) => candidate.name === artifactReference);
-      if (matches.length > 1) {
-        throw new Error(`artifact name ${artifactReference} is ambiguous in project ${owner.project}; ` + `${matches.length} documents share it \u2014 use its slug instead`);
-      }
-      const artifact = matches[0];
-      if (!artifact)
+      const artifact = artifacts.find((candidate) => candidate.id === artifactReference) ?? artifacts.find((candidate) => candidate.slug === artifactReference);
+      if (artifact)
+        return { owner, artifact };
+      const names = artifacts.filter((candidate) => candidate.name === artifactReference);
+      if (names.length > 1) {
+        throw new Error(`artifact name ${artifactReference} is ambiguous in project ${owner.project}; ` + `${names.length} documents share it \u2014 use its slug instead`);
+      }
+      if (names[0] === undefined)
         throw error;
-      return { owner, artifact };
+      return { owner, artifact: names[0] };
     }
   }
   const issue = await client.getIssue(owner.issue);
@@ -32031,6 +32038,7 @@ function issueSummary(issue, events, references) {
     `Title: ${issue.title}`,
     `Key: ${issue.key}`,
     `Status: ${issue.status}`,
+    `Labels: ${issue.labels.length === 0 ? "none" : issue.labels.join(", ")}`,
     `Route: ${issue.route ?? "none"}`,
     ...specApproval === undefined ? [] : [`Spec ${specApproval.replace(/^Approval/, "approval")}`],
     "Open asks:",
@@ -32163,6 +32171,7 @@ async function executeDispatchTool(input) {
       const external = optionalString(args, "external");
       const force = optionalBoolean(args, "force");
       const spec = optionalString(args, "spec");
+      const labels = args.labels;
       try {
         const created = await client.issue({
           project,
@@ -32171,6 +32180,7 @@ async function executeDispatchTool(input) {
           ...external === undefined ? {} : { external },
           ...force === undefined ? {} : { force },
           ...spec === undefined ? {} : { spec },
+          ...Array.isArray(labels) ? { labels } : {},
           actor
         });
         return {

package/dist/legion.js

@@ -29661,6 +29661,7 @@ var DispatchEventSchema = object({
 });
 var IssueEventPayloadSchema = object({
   title: string2().optional(),
+  labels: array(string2()).optional(),
   status: string2().optional(),
   rank: string2().optional(),
   route: string2().nullish()
@@ -29836,7 +29837,8 @@ var dispatchToolSpecs = [
       parent: z.string().describe("Optional parent issue.").optional(),
       external: z.string().describe("Optional external issue reference.").optional(),
       force: z.boolean().describe("Create even though POSSIBLE_DUPLICATE listed similar issues; pass it only after reading them.").optional(),
-      spec: z.string().describe(`Optional initial primary-document markdown. ${SPEC_WRITING_GUIDANCE}`).optional()
+      spec: z.string().describe(`Optional initial primary-document markdown. ${SPEC_WRITING_GUIDANCE}`).optional(),
+      labels: z.array(z.string({ min: 1, max: 40 }), { max: 20 }).describe("Optional initial labels, at most 20 labels of up to 40 characters.").optional()
     })
   },
   {
@@ -29845,7 +29847,7 @@ 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("Project document slug or id.").optional(),
+      artifact: z.string().describe("Project document artifact id, slug, or filename.").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({
@@ -29898,7 +29900,7 @@ 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 required when quote is given.").optional(),
+      artifact: z.string().describe("Project document artifact id, slug, or filename 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(),
@@ -29914,7 +29916,7 @@ 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; optional when ref names it.").optional(),
+      artifact: z.string().describe("Project document artifact id, slug, or filename 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."),
@@ -29938,7 +29940,7 @@ 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; optional when ref names it.").optional(),
+      artifact: z.string().describe("Project document artifact id, slug, or filename; 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."),
@@ -29959,7 +29961,7 @@ 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("Optional artifact slug or id; primary document by default for an issue.").optional(),
+      artifact: z.string().describe("Optional project document artifact id, slug, or filename; primary document by default for an issue.").optional(),
       version: z.number({ int: true, min: 1 }).describe("Optional version number.").optional(),
       ref: z.string().describe("Optional dispatch:// document reference.").optional()
     }),
@@ -29971,7 +29973,7 @@ 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; primary document by default for an issue.").optional()
+      artifact: z.string().describe("Project document artifact id, slug, or filename; primary document by default for an issue.").optional()
     }),
     validation: documentOwnerValidation(true)
   },
@@ -30000,7 +30002,7 @@ 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("Project document slug or id.").optional(),
+      artifact: z.string().describe("Project document artifact id, slug, or filename.").optional(),
       ref: z.string().describe("Optional dispatch:// issue or document reference.").optional()
     }),
     validation: documentOwnerValidation(true)
@@ -32008,6 +32010,9 @@ class DispatchClient {
   async docRead(id, version) {
     return version === undefined ? this.#json("GET", ["api", "v1", "artifacts", id, "text"]) : this.#json("GET", ["api", "v1", "artifacts", id, "versions", String(version)]);
   }
+  async artifactBlocks(id) {
+    return this.#json("GET", ["api", "v1", "artifacts", id, "blocks"]);
+  }
   async docEdit(id, input) {
     return this.#json("POST", ["api", "v1", "artifacts", id, "edits"], input);
   }
@@ -32318,7 +32323,7 @@ async function resolveOwnerArguments(tool, args, cwd, env, exec) {
     return { args, ref: null, owner: null };
   const refArgument = args.ref;
   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/<slug>");
+    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;
   const issueArgument = args.issue;
   const projectArgument = args.project;
@@ -32399,14 +32404,16 @@ async function resolveArtifact(client, owner, artifactReference) {
       if (!(error instanceof DispatchServiceError) || error.status !== 404)
         throw error;
       const artifacts = await client.listProjectArtifacts(owner.project, true);
-      const matches = artifacts.filter((candidate) => candidate.name === artifactReference);
-      if (matches.length > 1) {
-        throw new Error(`artifact name ${artifactReference} is ambiguous in project ${owner.project}; ` + `${matches.length} documents share it \u2014 use its slug instead`);
-      }
-      const artifact = matches[0];
-      if (!artifact)
+      const artifact = artifacts.find((candidate) => candidate.id === artifactReference) ?? artifacts.find((candidate) => candidate.slug === artifactReference);
+      if (artifact)
+        return { owner, artifact };
+      const names = artifacts.filter((candidate) => candidate.name === artifactReference);
+      if (names.length > 1) {
+        throw new Error(`artifact name ${artifactReference} is ambiguous in project ${owner.project}; ` + `${names.length} documents share it \u2014 use its slug instead`);
+      }
+      if (names[0] === undefined)
         throw error;
-      return { owner, artifact };
+      return { owner, artifact: names[0] };
     }
   }
   const issue = await client.getIssue(owner.issue);
@@ -32457,6 +32464,7 @@ function issueSummary(issue, events, references) {
     `Title: ${issue.title}`,
     `Key: ${issue.key}`,
     `Status: ${issue.status}`,
+    `Labels: ${issue.labels.length === 0 ? "none" : issue.labels.join(", ")}`,
     `Route: ${issue.route ?? "none"}`,
     ...specApproval === undefined ? [] : [`Spec ${specApproval.replace(/^Approval/, "approval")}`],
     "Open asks:",
@@ -32589,6 +32597,7 @@ async function executeDispatchTool(input) {
       const external = optionalString(args, "external");
       const force = optionalBoolean(args, "force");
       const spec = optionalString(args, "spec");
+      const labels = args.labels;
       try {
         const created = await client.issue({
           project,
@@ -32597,6 +32606,7 @@ async function executeDispatchTool(input) {
           ...external === undefined ? {} : { external },
           ...force === undefined ? {} : { force },
           ...spec === undefined ? {} : { spec },
+          ...Array.isArray(labels) ? { labels } : {},
           actor
         });
         return {

package/dist/skills/dispatch/SKILL.md

@@ -76,10 +76,11 @@ Issue reads include `rank`, the server-owned ordering key used by project boards
 
 Architects create newly tracked child work with:
 ```ts
-dispatch_issue({ project, title, parent?, external?, spec?, force? })
+dispatch_issue({ project, title, parent?, external?, spec?, force?, labels?: string[] })
 ```
-It returns `details` `{ issue, topic }`. Use `dispatch_issue` only to create an issue; never use it to park a question. When `spec` is
-supplied, follow [Writing a spec](#writing-a-spec).
+`labels` are optional initial labels: Dispatch trims them, preserves their case, and removes case-insensitive duplicates. It returns
+`details` `{ issue, topic }`. Use `dispatch_issue` only to create an issue; never use it to park a question. When `spec` is supplied,
+follow [Writing a spec](#writing-a-spec).
 
 ## Search first
 
@@ -188,7 +189,7 @@ Read the current document before changing it:
 dispatch_doc_read({ issue?, project?, artifact?, version?, ref? })
 ```
 It returns live or versioned markdown with open marks. `issue` with an omitted `artifact` reads the issue specification; a project needs
-`artifact`; and a `dispatch://PROJECT/artifact/<slug>` ref supplies both. Then write with:
+`artifact`; and a `dispatch://PROJECT/artifact/<document-ref>` ref supplies both, where `document-ref` is the id, slug, or filename.
 
 ```ts
 dispatch_doc_edit({ issue?, project?, artifact, ops, summary? })
@@ -266,7 +267,8 @@ Exactly one of `issue` and `project` is required. A project upload creates an un
 Exactly one of `path` and `content` is required. It returns issue or project-document owner details plus `artifact`, `version`, and its
 write `topic`. Uploading the same `name` creates its next version — so uploading `spec.md` **replaces the issue's own specification**
 with your text. Never do that: the spec is edited in place with `dispatch_doc_edit` (see [The Spec](#the-spec)). Address an existing
-artifact by the slug shown in the upload result or by its filename; the slug also arrives on `artifact.created` events.
+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.
 
 ## Messages
 
@@ -315,9 +317,9 @@ dispatch://KEY/artifact/<slug>[@vN]
 dispatch://KEY/ask/<id>
 dispatch://KEY/comment/<id>
 dispatch://KEY/message/<id>
-dispatch://PROJECT/artifact/<slug>[@vN]
-dispatch://PROJECT/artifact/<slug>/ask/<id>
-dispatch://PROJECT/artifact/<slug>/comment/<id>
+dispatch://PROJECT/artifact/<document-ref>[@vN]
+dispatch://PROJECT/artifact/<document-ref>/ask/<id>
+dispatch://PROJECT/artifact/<document-ref>/comment/<id>
 ```
 
 A bare UUID or `KEY#seq` is not a reference; the `dispatch://` form is what Dispatch links and records.

package/package.json

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