@sjawhar/pi-legion-envoy 0.26.0 → 0.28.0

package/README.md

@@ -79,8 +79,8 @@ extension files it does not contain.
 
 ## Native Dispatch tools
 
-The extension registers `dispatch_issue`, `dispatch_ask`, `dispatch_comment`,
-`dispatch_suggest`, `dispatch_message`, `dispatch_doc_edit`,
+The extension registers `dispatch_issue`, `dispatch_ask`, `dispatch_resolve_ask`,
+`dispatch_comment`, `dispatch_suggest`, `dispatch_message`, `dispatch_doc_edit`,
 `dispatch_doc_read`, `dispatch_artifact`, and `dispatch_read` when Dispatch
 configuration resolves both a base URL and bearer token.
 

package/dist/envoy.js

@@ -29671,7 +29671,13 @@ var ArtifactVersionEventPayloadSchema = object({
 var AskEventPayloadSchema = object({
   question: string2().optional(),
   options: array(object({ label: string2().optional() })).nullish(),
-  answer: object({ selected: array(string2()).nullish(), text: string2().nullish() }).nullish()
+  answer: object({ selected: array(string2()).nullish(), text: string2().nullish() }).nullish(),
+  resolution: object({
+    kind: _enum2(["retracted", "resolved"]).optional(),
+    reason: string2().optional(),
+    actor: object({ kind: string2().optional(), id: string2().optional() }).passthrough().optional(),
+    at: string2().optional()
+  }).nullish()
 });
 var CommentEventPayloadSchema = object({
   artifact_name: string2().optional(),
@@ -29727,6 +29733,15 @@ var dispatchToolSpecs = [
       }).describe("Optional document location for the question.").optional()
     })
   },
+  {
+    name: "dispatch_resolve_ask",
+    description: "Retract an open question that is moot or resolve one after finding the answer. This closes the question without answering it.",
+    arguments: (z) => ({
+      ask: z.string().describe("Ask id to close."),
+      kind: z.enum(["retracted", "resolved"]).describe("Whether the ask is retracted or self-resolved."),
+      reason: z.string({ min: 1 }).describe("Why the open ask no longer needs a human answer.")
+    })
+  },
   {
     name: "dispatch_comment",
     description: "Add review feedback to an issue or document quote, or reply to a question asked with dispatch_ask. " + "Do not use it for an exact replacement; use " + `dispatch_suggest instead. Body is at most 2,000 characters. ${ISSUE_REFERENCE}`,
@@ -30798,6 +30813,7 @@ var DISPATCH_PAYLOAD_SCHEMAS = {
   "artifact.version": ArtifactVersionEventPayloadSchema,
   "ask.opened": AskEventPayloadSchema,
   "ask.answered": AskEventPayloadSchema,
+  "ask.resolved": AskEventPayloadSchema,
   "comment.created": CommentEventPayloadSchema,
   "comment.resolved": CommentEventPayloadSchema,
   "suggestion.accepted": CommentEventPayloadSchema,
@@ -31180,6 +31196,9 @@ class DispatchClient {
   async ask(issue, input) {
     return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "asks"], input);
   }
+  async resolveAsk(id, input) {
+    return this.#json("POST", ["api", "v1", "asks", id, "resolve"], input);
+  }
   async comment(issue, input) {
     return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "comments"], input);
   }
@@ -31398,7 +31417,7 @@ function toolSchema(tool) {
   return dispatchToolSchema(spec, zodSchemaApi(exports_external), { strict: true });
 }
 async function resolveIssueArguments(tool, args, cwd, env, exec) {
-  if (tool === "dispatch_issue")
+  if (tool === "dispatch_issue" || tool === "dispatch_resolve_ask")
     return { args, ref: null };
   const refArgument = args.ref;
   const ref = typeof refArgument === "string" ? parseDispatchRef(refArgument) ?? (() => {
@@ -31505,6 +31524,12 @@ function askSummary({ ask, replies }) {
       `- Selected: ${answer.selected.length === 0 ? "none" : answer.selected.join(", ")}`,
       ...answer.text === null ? [] : [`- Text: ${answer.text}`]
     ],
+    ...ask.resolution === undefined ? [] : [
+      "Resolution:",
+      `- By: ${ask.resolution.actor.id}`,
+      `- Kind: ${ask.resolution.kind}`,
+      `- Reason: ${ask.resolution.reason}`
+    ],
     "Replies:",
     ...chain.length === 0 ? ["- none"] : chain
   ].join(`
@@ -31549,7 +31574,7 @@ async function executeDispatchTool(input) {
   const args = toolSchema(input.tool).parse(issueArguments.args);
   const actor = toolActor(await resolveOrigin(env, exec, input.cwd), input);
   const client = new DispatchClient(input.config.url, input.config.token, input.fetchImpl);
-  const issueKey = input.tool === "dispatch_issue" ? null : await ensureIssue(client, stringArg(args, "issue"), actor);
+  const issueKey = input.tool === "dispatch_issue" || input.tool === "dispatch_resolve_ask" ? null : await ensureIssue(client, stringArg(args, "issue"), actor);
   const issue = () => {
     if (issueKey === null)
       throw new Error("issue is required");
@@ -31573,6 +31598,26 @@ async function executeDispatchTool(input) {
         details: { issue: created.key, topic: dispatchIssueSubject(created.key, ">") }
       };
     }
+    case "dispatch_resolve_ask": {
+      const kind = stringArg(args, "kind");
+      if (kind !== "retracted" && kind !== "resolved")
+        throw new Error("kind must be retracted or resolved");
+      const ask = await client.resolveAsk(stringArg(args, "ask"), {
+        kind,
+        reason: stringArg(args, "reason"),
+        actor
+      });
+      if (ask.resolution === undefined)
+        throw new Error("resolved ask is missing its resolution");
+      return {
+        text: `${kind === "retracted" ? "Retracted" : "Resolved"} ask ${ask.id}: ${ask.resolution.reason}`,
+        details: {
+          issue: ask.issue_key,
+          topic: dispatchIssueSubject(ask.issue_key, ">"),
+          ask: ask.id
+        }
+      };
+    }
     case "dispatch_ask": {
       const anchorArgs = asObject(args.anchor);
       const resolved = anchorArgs ? await resolveArtifact(client, issue(), stringArg(anchorArgs, "artifact")) : undefined;

package/dist/legion.js

@@ -29669,7 +29669,13 @@ var ArtifactVersionEventPayloadSchema = object({
 var AskEventPayloadSchema = object({
   question: string2().optional(),
   options: array(object({ label: string2().optional() })).nullish(),
-  answer: object({ selected: array(string2()).nullish(), text: string2().nullish() }).nullish()
+  answer: object({ selected: array(string2()).nullish(), text: string2().nullish() }).nullish(),
+  resolution: object({
+    kind: _enum2(["retracted", "resolved"]).optional(),
+    reason: string2().optional(),
+    actor: object({ kind: string2().optional(), id: string2().optional() }).passthrough().optional(),
+    at: string2().optional()
+  }).nullish()
 });
 var CommentEventPayloadSchema = object({
   artifact_name: string2().optional(),
@@ -29725,6 +29731,15 @@ var dispatchToolSpecs = [
       }).describe("Optional document location for the question.").optional()
     })
   },
+  {
+    name: "dispatch_resolve_ask",
+    description: "Retract an open question that is moot or resolve one after finding the answer. This closes the question without answering it.",
+    arguments: (z) => ({
+      ask: z.string().describe("Ask id to close."),
+      kind: z.enum(["retracted", "resolved"]).describe("Whether the ask is retracted or self-resolved."),
+      reason: z.string({ min: 1 }).describe("Why the open ask no longer needs a human answer.")
+    })
+  },
   {
     name: "dispatch_comment",
     description: "Add review feedback to an issue or document quote, or reply to a question asked with dispatch_ask. " + "Do not use it for an exact replacement; use " + `dispatch_suggest instead. Body is at most 2,000 characters. ${ISSUE_REFERENCE}`,
@@ -31290,6 +31305,7 @@ var DISPATCH_PAYLOAD_SCHEMAS = {
   "artifact.version": ArtifactVersionEventPayloadSchema,
   "ask.opened": AskEventPayloadSchema,
   "ask.answered": AskEventPayloadSchema,
+  "ask.resolved": AskEventPayloadSchema,
   "comment.created": CommentEventPayloadSchema,
   "comment.resolved": CommentEventPayloadSchema,
   "suggestion.accepted": CommentEventPayloadSchema,
@@ -31665,6 +31681,9 @@ class DispatchClient {
   async ask(issue, input) {
     return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "asks"], input);
   }
+  async resolveAsk(id, input) {
+    return this.#json("POST", ["api", "v1", "asks", id, "resolve"], input);
+  }
   async comment(issue, input) {
     return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "comments"], input);
   }
@@ -31883,7 +31902,7 @@ function toolSchema(tool) {
   return dispatchToolSchema(spec, zodSchemaApi(exports_external), { strict: true });
 }
 async function resolveIssueArguments(tool, args, cwd, env, exec) {
-  if (tool === "dispatch_issue")
+  if (tool === "dispatch_issue" || tool === "dispatch_resolve_ask")
     return { args, ref: null };
   const refArgument = args.ref;
   const ref = typeof refArgument === "string" ? parseDispatchRef(refArgument) ?? (() => {
@@ -31990,6 +32009,12 @@ function askSummary({ ask, replies }) {
       `- Selected: ${answer.selected.length === 0 ? "none" : answer.selected.join(", ")}`,
       ...answer.text === null ? [] : [`- Text: ${answer.text}`]
     ],
+    ...ask.resolution === undefined ? [] : [
+      "Resolution:",
+      `- By: ${ask.resolution.actor.id}`,
+      `- Kind: ${ask.resolution.kind}`,
+      `- Reason: ${ask.resolution.reason}`
+    ],
     "Replies:",
     ...chain.length === 0 ? ["- none"] : chain
   ].join(`
@@ -32034,7 +32059,7 @@ async function executeDispatchTool(input) {
   const args = toolSchema(input.tool).parse(issueArguments.args);
   const actor = toolActor(await resolveOrigin(env, exec, input.cwd), input);
   const client = new DispatchClient(input.config.url, input.config.token, input.fetchImpl);
-  const issueKey = input.tool === "dispatch_issue" ? null : await ensureIssue(client, stringArg(args, "issue"), actor);
+  const issueKey = input.tool === "dispatch_issue" || input.tool === "dispatch_resolve_ask" ? null : await ensureIssue(client, stringArg(args, "issue"), actor);
   const issue = () => {
     if (issueKey === null)
       throw new Error("issue is required");
@@ -32058,6 +32083,26 @@ async function executeDispatchTool(input) {
         details: { issue: created.key, topic: dispatchIssueSubject(created.key, ">") }
       };
     }
+    case "dispatch_resolve_ask": {
+      const kind = stringArg(args, "kind");
+      if (kind !== "retracted" && kind !== "resolved")
+        throw new Error("kind must be retracted or resolved");
+      const ask = await client.resolveAsk(stringArg(args, "ask"), {
+        kind,
+        reason: stringArg(args, "reason"),
+        actor
+      });
+      if (ask.resolution === undefined)
+        throw new Error("resolved ask is missing its resolution");
+      return {
+        text: `${kind === "retracted" ? "Retracted" : "Resolved"} ask ${ask.id}: ${ask.resolution.reason}`,
+        details: {
+          issue: ask.issue_key,
+          topic: dispatchIssueSubject(ask.issue_key, ">"),
+          ask: ask.id
+        }
+      };
+    }
     case "dispatch_ask": {
       const anchorArgs = asObject(args.anchor);
       const resolved = anchorArgs ? await resolveArtifact(client, issue(), stringArg(anchorArgs, "artifact")) : undefined;

package/dist/skills/dispatch/SKILL.md

@@ -44,8 +44,20 @@ It returns `details` `{ issue, topic, ask }`. Options are buttons: never enumera
 prose. Put the recommendation in `question`, and put each selectable choice in `options`.
 Anchor a document question with `anchor: { artifact, quote, occurrence? }`; `occurrence` is
 zero-based and selects a repeated quote. An anchor whose quote disappears becomes orphaned but
-remains readable against its original document version. An ask stays open until a human answers;
-you cannot withdraw it. Ask once and well. The host steers you when a human answers.
+remains readable against its original document version.
+
+An ask stays open until a human answers, unless its question no longer needs that answer. Retract a
+moot or superseded question, or self-resolve one after finding the answer:
+```ts
+dispatch_resolve_ask({
+  ask,
+  kind: "retracted",
+  reason: "A newer ask supersedes this question.",
+})
+```
+Use `retracted` when the question is obsolete and `resolved` when you found the answer. Include the
+reason because the question remains in its issue log and reply thread. Resolution is not an answer:
+it never records a human decision, and an answered ask cannot be resolved.
 
 An ask is a thread, not a dead end: a human can reply to it before or after answering, and you
 (the asker) can reply too — e.g. acknowledging a clarifying question, or following up after the

package/package.json

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