@sjawhar/pi-legion-envoy 1.2.0 → 1.4.0

package/dist/envoy.js

@@ -29671,6 +29671,14 @@ var ArtifactVersionEventPayloadSchema = object({
   version: object({ number: number2().optional(), summary: string2().nullish() }).optional(),
   diff: string2().optional()
 });
+var ArtifactReviewEventPayloadSchema = object({
+  artifact_id: string2().optional(),
+  name: string2().optional(),
+  version: number2().int().optional(),
+  actor: object({ kind: string2(), id: string2() }).passthrough().optional(),
+  reason: string2().nullish(),
+  ask_id: string2().nullish()
+});
 var askEventPayloadFields = {
   id: string2().optional(),
   opened_event_id: number2().int().positive(),
@@ -29952,6 +29960,16 @@ var dispatchToolSpecs = [
     }),
     validation: documentOwnerValidation(true)
   },
+  {
+    name: "dispatch_request_approval",
+    description: "Ask a human to approve a document at its current version - the exception path for a spec " + "that departs from what was settled or proposes children, not a step for every issue. Opens an " + "approval ask (Approve / Request changes) in the human's Inbox; the answer pins a review to the " + "document version and arrives as artifact.approved or artifact.changes_requested. A later edit " + "makes an approval stale; request again for the new version. Idempotent while a request is open. " + OWNER_REFERENCE,
+    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()
+    }),
+    validation: documentOwnerValidation(true)
+  },
   {
     name: "dispatch_artifact",
     description: "Attach a local file or inline text as an issue artifact or project document. Do not use it to edit a live document; use " + `dispatch_doc_edit instead. Exactly one of path or content is required; artifacts are limited to 25 MiB. ${OWNER_REFERENCE}`,
@@ -31476,6 +31494,9 @@ class DispatchClient {
   async resolveAsk(id, input) {
     return this.#json("POST", ["api", "v1", "asks", id, "resolve"], input);
   }
+  async requestApproval(artifactID, input) {
+    return this.#json("POST", ["api", "v1", "artifacts", artifactID, "approval-requests"], input);
+  }
   async editAsk(id, input) {
     return this.#json("PATCH", ["api", "v1", "asks", id], input);
   }
@@ -31961,13 +31982,31 @@ function toolActor(origin, input) {
     }
   };
 }
+function approvalLine(artifact) {
+  const approval = artifact.approval;
+  if (approval === undefined || approval.state === "draft")
+    return;
+  switch (approval.state) {
+    case "awaiting":
+      return `Approval: awaiting (requested by ${approval.requested_by?.id ?? "unknown"}, ask ${approval.ask_id ?? "?"})`;
+    case "approved":
+      return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}`;
+    case "stale":
+      return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}, edited since (now v${approval.latest_version}) - request approval again`;
+    case "changes_requested":
+      return `Approval: changes requested on v${approval.version} by ${approval.by?.id ?? "unknown"}: ${approval.reason ?? ""}`;
+  }
+}
 function issueSummary(issue, events, references) {
   const asks = issue.open_asks;
+  const spec = issue.artifacts?.find((artifact) => artifact.primary);
+  const specApproval = spec === undefined ? undefined : approvalLine(spec);
   return [
     `Title: ${issue.title}`,
     `Key: ${issue.key}`,
     `Status: ${issue.status}`,
     `Route: ${issue.route ?? "none"}`,
+    ...specApproval === undefined ? [] : [`Spec ${specApproval.replace(/^Approval/, "approval")}`],
     "Open asks:",
     ...asks.length === 0 ? ["- none"] : asks.map((ask) => `- ${ask.id}: ${ask.question}`),
     "References:",
@@ -32294,16 +32333,42 @@ async function executeDispatchTool(input) {
       const version = optionalNumber(args, "version") ?? ownerArguments.ref?.version;
       const document = await client.docRead(resolved.artifact.id, version);
       const marks = await openArtifactMarks(client, resolved);
+      const approval = approvalLine(resolved.artifact);
+      const trailer = [
+        ...marks.length === 0 ? [] : [`Open anchored asks/comments: ${marks.join(", ")}`],
+        ...approval === undefined ? [] : [approval]
+      ];
       return {
-        text: marks.length === 0 ? document.markdown : `${document.markdown}
+        text: trailer.length === 0 ? document.markdown : `${document.markdown}
 
-Open anchored asks/comments: ${marks.join(", ")}`,
+${trailer.join(`
+`)}`,
         details: resolved.owner.kind === "project" ? {
           project: resolved.artifact.project,
           document: `${resolved.artifact.project}/${resolved.artifact.slug}`
         } : { issue: resolved.issue?.key }
       };
     }
+    case "dispatch_request_approval": {
+      const artifactReference = optionalString(args, "artifact") ?? (ownerArguments.ref?.kind === "spec" || ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : undefined);
+      const resolved = await resolveArtifact(client, documentOwner(), artifactReference);
+      const result = await client.requestApproval(resolved.artifact.id, { actor });
+      if (result.ask === null) {
+        return {
+          text: `${resolved.artifact.name} is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. An edit after approval makes it stale, so request again only for a new version.`,
+          details: {
+            ...resolved.owner.kind === "project" ? documentResultDetails(resolved.artifact) : { issue: resolved.issue?.key },
+            artifact: resolved.artifact.id,
+            version: result.version
+          }
+        };
+      }
+      const details = await askResultDetails(client, result.ask, resolved);
+      return {
+        text: `Approval requested for ${resolved.artifact.name} at version ${result.version} (ask ${result.ask.id}). The answer arrives as artifact.approved or artifact.changes_requested; an edit after approval makes it stale, so request again for the new version.`,
+        details: { ...details, artifact: resolved.artifact.id, version: result.version }
+      };
+    }
     case "dispatch_artifact": {
       const summary = optionalString(args, "summary");
       const name = stringArg(args, "name");
@@ -32366,7 +32431,8 @@ Open anchored asks/comments: ${marks.join(", ")}`,
           text: [
             `Document: ${resolved.artifact.project} / ${resolved.artifact.name}`,
             `Reference: dispatch://${resolved.artifact.project}/artifact/${resolved.artifact.slug}`,
-            `Versions: ${resolved.artifact.versions.length}`
+            `Versions: ${resolved.artifact.versions.length}`,
+            ...approvalLine(resolved.artifact) === undefined ? [] : [approvalLine(resolved.artifact)]
           ].join(`
 `),
           details: {

package/dist/legion.js

@@ -29670,6 +29670,14 @@ var ArtifactVersionEventPayloadSchema = object({
   version: object({ number: number2().optional(), summary: string2().nullish() }).optional(),
   diff: string2().optional()
 });
+var ArtifactReviewEventPayloadSchema = object({
+  artifact_id: string2().optional(),
+  name: string2().optional(),
+  version: number2().int().optional(),
+  actor: object({ kind: string2(), id: string2() }).passthrough().optional(),
+  reason: string2().nullish(),
+  ask_id: string2().nullish()
+});
 var askEventPayloadFields = {
   id: string2().optional(),
   opened_event_id: number2().int().positive(),
@@ -29951,6 +29959,16 @@ var dispatchToolSpecs = [
     }),
     validation: documentOwnerValidation(true)
   },
+  {
+    name: "dispatch_request_approval",
+    description: "Ask a human to approve a document at its current version - the exception path for a spec " + "that departs from what was settled or proposes children, not a step for every issue. Opens an " + "approval ask (Approve / Request changes) in the human's Inbox; the answer pins a review to the " + "document version and arrives as artifact.approved or artifact.changes_requested. A later edit " + "makes an approval stale; request again for the new version. Idempotent while a request is open. " + OWNER_REFERENCE,
+    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()
+    }),
+    validation: documentOwnerValidation(true)
+  },
   {
     name: "dispatch_artifact",
     description: "Attach a local file or inline text as an issue artifact or project document. Do not use it to edit a live document; use " + `dispatch_doc_edit instead. Exactly one of path or content is required; artifacts are limited to 25 MiB. ${OWNER_REFERENCE}`,
@@ -31902,6 +31920,9 @@ class DispatchClient {
   async resolveAsk(id, input) {
     return this.#json("POST", ["api", "v1", "asks", id, "resolve"], input);
   }
+  async requestApproval(artifactID, input) {
+    return this.#json("POST", ["api", "v1", "artifacts", artifactID, "approval-requests"], input);
+  }
   async editAsk(id, input) {
     return this.#json("PATCH", ["api", "v1", "asks", id], input);
   }
@@ -32387,13 +32408,31 @@ function toolActor(origin, input) {
     }
   };
 }
+function approvalLine(artifact) {
+  const approval = artifact.approval;
+  if (approval === undefined || approval.state === "draft")
+    return;
+  switch (approval.state) {
+    case "awaiting":
+      return `Approval: awaiting (requested by ${approval.requested_by?.id ?? "unknown"}, ask ${approval.ask_id ?? "?"})`;
+    case "approved":
+      return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}`;
+    case "stale":
+      return `Approval: approved v${approval.version} by ${approval.by?.id ?? "unknown"}, edited since (now v${approval.latest_version}) - request approval again`;
+    case "changes_requested":
+      return `Approval: changes requested on v${approval.version} by ${approval.by?.id ?? "unknown"}: ${approval.reason ?? ""}`;
+  }
+}
 function issueSummary(issue, events, references) {
   const asks = issue.open_asks;
+  const spec = issue.artifacts?.find((artifact) => artifact.primary);
+  const specApproval = spec === undefined ? undefined : approvalLine(spec);
   return [
     `Title: ${issue.title}`,
     `Key: ${issue.key}`,
     `Status: ${issue.status}`,
     `Route: ${issue.route ?? "none"}`,
+    ...specApproval === undefined ? [] : [`Spec ${specApproval.replace(/^Approval/, "approval")}`],
     "Open asks:",
     ...asks.length === 0 ? ["- none"] : asks.map((ask) => `- ${ask.id}: ${ask.question}`),
     "References:",
@@ -32720,16 +32759,42 @@ async function executeDispatchTool(input) {
       const version = optionalNumber(args, "version") ?? ownerArguments.ref?.version;
       const document = await client.docRead(resolved.artifact.id, version);
       const marks = await openArtifactMarks(client, resolved);
+      const approval = approvalLine(resolved.artifact);
+      const trailer = [
+        ...marks.length === 0 ? [] : [`Open anchored asks/comments: ${marks.join(", ")}`],
+        ...approval === undefined ? [] : [approval]
+      ];
       return {
-        text: marks.length === 0 ? document.markdown : `${document.markdown}
+        text: trailer.length === 0 ? document.markdown : `${document.markdown}
 
-Open anchored asks/comments: ${marks.join(", ")}`,
+${trailer.join(`
+`)}`,
         details: resolved.owner.kind === "project" ? {
           project: resolved.artifact.project,
           document: `${resolved.artifact.project}/${resolved.artifact.slug}`
         } : { issue: resolved.issue?.key }
       };
     }
+    case "dispatch_request_approval": {
+      const artifactReference = optionalString(args, "artifact") ?? (ownerArguments.ref?.kind === "spec" || ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : undefined);
+      const resolved = await resolveArtifact(client, documentOwner(), artifactReference);
+      const result = await client.requestApproval(resolved.artifact.id, { actor });
+      if (result.ask === null) {
+        return {
+          text: `${resolved.artifact.name} is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. An edit after approval makes it stale, so request again only for a new version.`,
+          details: {
+            ...resolved.owner.kind === "project" ? documentResultDetails(resolved.artifact) : { issue: resolved.issue?.key },
+            artifact: resolved.artifact.id,
+            version: result.version
+          }
+        };
+      }
+      const details = await askResultDetails(client, result.ask, resolved);
+      return {
+        text: `Approval requested for ${resolved.artifact.name} at version ${result.version} (ask ${result.ask.id}). The answer arrives as artifact.approved or artifact.changes_requested; an edit after approval makes it stale, so request again for the new version.`,
+        details: { ...details, artifact: resolved.artifact.id, version: result.version }
+      };
+    }
     case "dispatch_artifact": {
       const summary = optionalString(args, "summary");
       const name = stringArg(args, "name");
@@ -32792,7 +32857,8 @@ Open anchored asks/comments: ${marks.join(", ")}`,
           text: [
             `Document: ${resolved.artifact.project} / ${resolved.artifact.name}`,
             `Reference: dispatch://${resolved.artifact.project}/artifact/${resolved.artifact.slug}`,
-            `Versions: ${resolved.artifact.versions.length}`
+            `Versions: ${resolved.artifact.versions.length}`,
+            ...approvalLine(resolved.artifact) === undefined ? [] : [approvalLine(resolved.artifact)]
           ].join(`
 `),
           details: {

package/dist/skills/dispatch/SKILL.md

@@ -123,6 +123,22 @@ clarification, not an answer: the human did not understand the question or needs
 in their Inbox. Answer in the same thread with `dispatch_comment({ reply_to_ask })`, or reword the question itself with
 `dispatch_edit_ask` when the wording was the problem; either puts the ask back in front of them. Do not open a second ask.
 
+## Approval of a spec
+
+Approval is a property of a document, not a question you phrase: a human approves a specific version, the way a pull-request
+review approves a commit, and any later edit makes that approval stale. It is the exception, not a step for every issue - reach
+for it when a spec departs from what the human already settled, proposes children, or when the project has armed a design gate.
+
+```
+dispatch_request_approval({ issue?, project?, artifact? })
+```
+
+Opens (or returns the open) approval ask for the document at its latest version - options `Approve` and `Request changes`, in
+the human's Inbox like any ask. The answer reaches you as `artifact.approved` or `artifact.changes_requested` with the pinned
+`version`; `changes_requested` carries the reason, which is your next piece of work. `dispatch_read` and `dispatch_doc_read` show
+the document's approval state; `stale` means it was approved and then edited - request again for the new version. Never write
+"Approve" options into an ordinary `dispatch_ask`, and never approve anything yourself: only humans review.
+
 ## The Spec
 
 The spec holds requirements, design, acceptance, decisions, and rejected alternatives, structured per [Writing a spec](#writing-a-spec).

package/package.json

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