@sjawhar/opencode-legion-envoy 1.10.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(),
@@ -13740,7 +13741,7 @@ var SPEC_SECTIONS = [
 ];
 var SPEC_WRITING_GUIDANCE = `When writing a spec, use these sections in order: ${SPEC_SECTIONS.join(", ")}. ` + "Write for a reader who has not seen the code: plain sentences, every identifier expanded on " + "first use, no coined shorthand; see skills/dispatch Writing for the human and Writing a spec.";
 var ASK_URGENCIES = ["low", "med", "high", "blocking"];
-var DOC_EDIT_OPS = ["replace", "delete", "insert"];
+var DOC_EDIT_OPS = ["replace", "delete", "insert", "retype"];
 var dispatchToolSpecs = [
   {
     name: "dispatch_issue",
@@ -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()
@@ -13850,7 +13852,7 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_doc_edit",
-    description: "Apply deterministic text edits to an issue or project document. Do not use it for review feedback or for reading; use " + "dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. The spec (or any document) holds requirements, " + `design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
+    description: "Apply deterministic document edits, including retyping an identified paragraph into a schema-declared typed block. " + "Do not use it for review feedback or for reading; use dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. " + `The spec (or any document) holds requirements, design, and decisions - never progress, status, or timestamps. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       project: z.string().describe("Project key owning the document.").optional(),
@@ -13863,7 +13865,10 @@ var dispatchToolSpecs = [
         occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based match occurrence.").optional(),
         markdown: z.string().describe("Markdown to insert.").optional(),
         after: z.string().describe("Anchor after which to insert.").optional(),
-        before: z.string().describe("Anchor before which to insert.").optional()
+        before: z.string().describe("Anchor before which to insert.").optional(),
+        block: z.string().describe("Block id to retype.").optional(),
+        type: z.string().describe("Typed block name for retype.").optional(),
+        attributes: z.unknown().describe("Typed block attributes for retype.").optional()
       })).describe("Flat tagged edits; the server validates fields required for each operation."),
       summary: z.string().describe("Optional named-version summary.").optional()
     }),
@@ -14307,6 +14312,7 @@ function zodSchemaApi(zod) {
     },
     boolean: () => api.boolean(),
     enum: (values) => api.enum(values),
+    unknown: () => api.unknown(),
     array: (item, opts = {}) => {
       let schema = api.array(item);
       if (opts.min !== undefined)
@@ -14946,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) {
@@ -15381,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 },
@@ -15487,8 +15501,10 @@ async function executeDispatchTool(input) {
         ...summary === undefined ? {} : { summary },
         actor
       });
+      const retyped = ops.filter((operation) => operation.op === "retype").length;
+      const versionText = edited.version === null ? "no new version" : `version ${edited.version.number}`;
       return {
-        text: edited.version === null ? `Applied ${edited.applied} ops (no new version)` : `Applied ${edited.applied} ops (version ${edited.version.number})`,
+        text: retyped === 0 ? `Applied ${edited.applied} ops (${versionText})` : `Applied ${edited.applied} ops; retyped ${retyped} block${retyped === 1 ? "" : "s"} (${versionText})`,
         details: writeResultDetails(resolved, {
           applied: edited.applied,
           ...edited.version === null ? {} : { version: edited.version.number }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "1.10.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({
@@ -199,13 +217,16 @@ exact `EditOp` shape:
 
 ```ts
 type EditOp = {
-  op: "replace" | "delete" | "insert";
+  op: "replace" | "delete" | "insert" | "retype";
   find?: string;
   with?: string;
   occurrence?: number;
   markdown?: string;
   after?: string;
   before?: string;
+  block?: string;
+  type?: string;
+  attributes?: Record<string, unknown>;
 };
 ```
 
@@ -221,6 +242,9 @@ and deleting a cell's quoted text removes only that text.
 
 Use `replace` for inline continuation. Use zero-based `occurrence` for a repeated target; re-read a missing or ambiguous target before
 retrying. Pass `summary` to name the version when recording a decision.
+`retype` turns the paragraph with `block` into the named typed `type` in place. It keeps the
+block id and uses `attributes` for client-owned typed attributes. Use it when an existing
+paragraph is the question that should become a decision.
 
 ## Typed blocks
 
@@ -236,6 +260,19 @@ quoted: `:::callout{kind="warning" title="Risk"}`. Do not write Pandoc-style `::
 block. Do not set attributes the schema marks `server: true`; the server ignores them and reasserts
 its authoritative value at settlement.
 
+Questions about a document must be `ask` blocks, never an `Open questions` prose section. An ask
+body is one or more question paragraphs followed by an optional bullet list of options, where each
+item is `Label: description`. For example:
+
+```md
+:::ask{urgency="high" multiple="false"}
+Should we ship the migration?
+
+- Ship: Release the verified change.
+- Hold: Wait for another review.
+:::
+```
+
 ## Comments and suggestions
 
 Add feedback with:

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.