@sjawhar/opencode-legion-envoy 1.11.0 → 1.12.0

package/dist/src/server.js

@@ -13590,6 +13590,7 @@ var ArtifactReviewEventPayloadSchema = object({
 var askEventPayloadFields = {
   id: string2().optional(),
   opened_event_id: number2().int().positive(),
+  kind: _enum2(["question", "approval", "action"]).optional(),
   question: string2().optional(),
   options: array(object({ label: string2().optional() })).nullish(),
   answer: object({ selected: array(string2()).nullish(), text: string2().nullish() }).nullish(),
@@ -13757,13 +13758,14 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_ask",
-    description: "Open a durable, answerable decision on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. Anchor a document question, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". Question is at most 800 ` + `characters and has at most 8 options. ${OWNER_REFERENCE}`,
+    description: "Open a durable, answerable decision or human to-do on an issue or project document. Do not use it for a status update or discussion; " + "use dispatch_message instead. Use kind: action for a to-do a human must complete; it has fixed Done / Can't answers. " + "Anchor a document question, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". Question is at most 800 ` + `characters and has at most 8 options. ${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("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."),
+      kind: z.enum(["action"]).describe("Optional human to-do ask kind.").optional(),
       options: z.array(z.object({
         label: z.string().describe("Selectable option label."),
         description: z.string().describe("Optional option context.").optional()
@@ -14950,6 +14952,12 @@ function askUrgency(args) {
   const value = args.urgency;
   return ASK_URGENCIES.find((urgency) => urgency === value);
 }
+function askKind(args) {
+  const value = optionalString(args, "kind");
+  if (value === undefined || value === "action")
+    return value;
+  throw new Error("kind must be action");
+}
 function parseDispatchRef(ref) {
   const projectDocument = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)(?:@v(\d+))?(?:\/(ask|comment)\/([^/]+))?$/);
   if (projectDocument) {
@@ -15385,9 +15393,11 @@ async function executeDispatchTool(input) {
       const options = args.options;
       const multiple = optionalBoolean(args, "multiple");
       const urgency = askUrgency(args);
+      const kind = askKind(args);
       const anchored = anchorArgs && resolved ? anchor(resolved.artifact, anchorArgs) : undefined;
       const askInput = {
         question: stringArg(args, "question"),
+        ...kind === undefined ? {} : { kind },
         ...Array.isArray(options) ? { options } : {},
         ...multiple === undefined ? {} : { multiple },
         ...urgency === undefined ? {} : { urgency },

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -128,6 +128,24 @@ An ask must be answerable from its own text and its anchor alone. Anchor a quest
 about a comment with `reply_to`; thread a follow-up on your own ask with `reply_to_ask`; cite anything else with a `dispatch://`
 reference (see [References](#references)). Never write "see above", "the message above", or "as attached".
 
+**Anything that needs the human is an ask, or it does not exist.** An approval, a credential,
+a setting only they can change, a review click, a conflict between two of their own rules - if
+your work waits on it, open a `dispatch_ask` with `kind: "action"` the moment you know, the
+action as the question (the server supplies the fixed `Done` / `Can't` options; `Can't` requires
+an explanation). Never write it into a spec, a comment reply, a message, or a
+pull-request body: nothing in those paths reaches the human's Inbox, and a human who is not
+reading your document does not know they are the blocker. Before asking, try to remove the
+step: a value already on the machine, a permission you already hold, an API that replaces the
+click. One ask per item, `urgency: "high"` when work is stopped on it; while it is open, keep
+working on everything that is not.
+
+Use `kind: "action"` for a to-do handed to a human. It has fixed `Done` / `Can't` options;
+`Can't` requires an explanation, while the asker can still correct the action's wording:
+```ts
+dispatch_ask({ issue: "DSP-42", kind: "action",
+  question: "Confirm the deployment is complete." })
+```
+
 Correct or refine an open ask in place instead of opening a second question:
 ```ts
 dispatch_edit_ask({

package/skills/legion-controller/SKILL.md

@@ -25,7 +25,10 @@ environment, then run:
 The command resolves the project from daemon state, claims the Envoy role for the current
 session, and posts readiness before controller commands can act. It retains the environment
 capability for `legion({ op: "set_status", issue, status })`. Never pass a secret as a command argument
-or copy it into a transcript.
+or copy it into a transcript. The claim is kept alive automatically afterwards: the Envoy
+registration heartbeat re-asserts it and re-posts readiness whenever the listener loses sight of
+this session, so `/legion-claim-controller` is the manual override, not a routine step after a
+listener restart.
 
 This handshake lets the daemon redeliver held controller work. It does not turn the controller
 into a state holder: daemon state and the Dispatch project remain authoritative.