@sjawhar/pi-legion-envoy 1.11.0 → 1.12.0

package/dist/envoy.js

@@ -29687,6 +29687,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(),
@@ -29854,13 +29855,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()
@@ -31915,6 +31917,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) {
@@ -32350,9 +32358,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 },
@@ -33105,7 +33115,8 @@ function legionRoleClaimBridge() {
     return bridge;
   const createdBridge = {
     claim: undefined,
-    ready: Promise.withResolvers()
+    ready: Promise.withResolvers(),
+    regained: undefined
   };
   store[LEGION_ROLE_CLAIM_BRIDGE] = createdBridge;
   return createdBridge;
@@ -33114,6 +33125,9 @@ async function claimEnvoyRole(sessionID, role, context) {
   const bridge = legionRoleClaimBridge();
   await (bridge.claim ?? await bridge.ready.promise)(sessionID, role, context);
 }
+function onEnvoyRoleRegained(listener) {
+  legionRoleClaimBridge().regained = listener;
+}
 function resolveSkillsDirectory() {
   const moduleDirectory = dirname(fileURLToPath(import.meta.url));
   const candidates = [
@@ -33304,10 +33318,58 @@ function envoyExtension(pi) {
     driving: false,
     selfSubscribed: true
   });
+  const reassertRole = async (afterOutage, context) => {
+    const topic = claimedRoleTopic;
+    if (topic === undefined)
+      return;
+    const id = sessionID;
+    const role = topic.slice(ROLE_TOPIC_PREFIX.length);
+    const holder = await client.getRole(role).then((info) => info.holder, (error) => {
+      if (error instanceof EnvoyApiError && error.details.status === 404)
+        return;
+      throw error;
+    });
+    let reason;
+    if (holder === id) {
+      if (!afterOutage)
+        return;
+      reason = "reregistered";
+    } else {
+      const result = await client.setRole({ sessionID: id, role, soft: true });
+      if (claimedRoleTopic !== topic || sessionID !== id) {
+        if (result.claimed)
+          await client.unsubscribe({ sessionID: id, topics: [topic] });
+        return;
+      }
+      if (!result.claimed) {
+        claimedRoleTopic = undefined;
+        logger.warn("envoy: role re-assertion refused; held by another live session", {
+          role,
+          sessionID: id,
+          holder: result.holder
+        });
+        context.ui.notify(`envoy: role ${role} is now held by session ${result.holder}; this session no longer holds it`, "warning");
+        return;
+      }
+      logger.warn("envoy: role re-asserted after the listener lost the claim", {
+        role,
+        sessionID: id,
+        previousHolder: holder ?? null
+      });
+      reason = "reclaimed";
+    }
+    const regained = legionRoleClaimBridge().regained;
+    if (regained === undefined)
+      return;
+    Promise.resolve().then(() => regained(role, reason)).catch((error) => {
+      logger.warn("envoy: role regain hook failed", { role, reason, error: messageFor(error) });
+    });
+  };
   const ensureHeartbeat = (context) => {
     if (heartbeatRegistered)
       return;
     let heartbeatOutageNotified = false;
+    let registrationFailed = false;
     let healing = false;
     context.setInterval(() => {
       const liveSessionID = context.sessionManager.getSessionId();
@@ -33317,7 +33379,12 @@ function envoyExtension(pi) {
       if (healing)
         return;
       healing = true;
-      (drifted ? establishSession(context) : registerSession()).then(() => {
+      const afterOutage = registrationFailed;
+      (drifted ? establishSession(context) : registerSession()).then(() => drifted ? undefined : reassertRole(afterOutage, context), (error) => {
+        registrationFailed = true;
+        throw error;
+      }).then(() => {
+        registrationFailed = false;
         heartbeatOutageNotified = false;
       }).catch((error) => {
         if (heartbeatOutageNotified)
@@ -33767,5 +33834,6 @@ function topicsFor(parameters, fallback = []) {
 }
 export {
   claimEnvoyRole,
-  envoyExtension as default
+  envoyExtension as default,
+  onEnvoyRoleRegained
 };

package/dist/legion.js

@@ -29686,6 +29686,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(),
@@ -29853,13 +29854,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()
@@ -32341,6 +32343,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) {
@@ -32776,9 +32784,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 },
@@ -33523,7 +33533,8 @@ function legionRoleClaimBridge() {
     return bridge;
   const createdBridge = {
     claim: undefined,
-    ready: Promise.withResolvers()
+    ready: Promise.withResolvers(),
+    regained: undefined
   };
   store[LEGION_ROLE_CLAIM_BRIDGE] = createdBridge;
   return createdBridge;
@@ -33532,6 +33543,9 @@ async function claimEnvoyRole(sessionID, role, context) {
   const bridge = legionRoleClaimBridge();
   await (bridge.claim ?? await bridge.ready.promise)(sessionID, role, context);
 }
+function onEnvoyRoleRegained(listener) {
+  legionRoleClaimBridge().regained = listener;
+}
 function resolveSkillsDirectory() {
   const moduleDirectory = dirname(fileURLToPath(import.meta.url));
   const candidates = [
@@ -33722,10 +33736,58 @@ function envoyExtension(pi) {
     driving: false,
     selfSubscribed: true
   });
+  const reassertRole = async (afterOutage, context) => {
+    const topic = claimedRoleTopic;
+    if (topic === undefined)
+      return;
+    const id = sessionID;
+    const role = topic.slice(ROLE_TOPIC_PREFIX.length);
+    const holder = await client.getRole(role).then((info) => info.holder, (error) => {
+      if (error instanceof EnvoyApiError && error.details.status === 404)
+        return;
+      throw error;
+    });
+    let reason;
+    if (holder === id) {
+      if (!afterOutage)
+        return;
+      reason = "reregistered";
+    } else {
+      const result = await client.setRole({ sessionID: id, role, soft: true });
+      if (claimedRoleTopic !== topic || sessionID !== id) {
+        if (result.claimed)
+          await client.unsubscribe({ sessionID: id, topics: [topic] });
+        return;
+      }
+      if (!result.claimed) {
+        claimedRoleTopic = undefined;
+        logger.warn("envoy: role re-assertion refused; held by another live session", {
+          role,
+          sessionID: id,
+          holder: result.holder
+        });
+        context.ui.notify(`envoy: role ${role} is now held by session ${result.holder}; this session no longer holds it`, "warning");
+        return;
+      }
+      logger.warn("envoy: role re-asserted after the listener lost the claim", {
+        role,
+        sessionID: id,
+        previousHolder: holder ?? null
+      });
+      reason = "reclaimed";
+    }
+    const regained = legionRoleClaimBridge().regained;
+    if (regained === undefined)
+      return;
+    Promise.resolve().then(() => regained(role, reason)).catch((error) => {
+      logger.warn("envoy: role regain hook failed", { role, reason, error: messageFor(error) });
+    });
+  };
   const ensureHeartbeat = (context) => {
     if (heartbeatRegistered)
       return;
     let heartbeatOutageNotified = false;
+    let registrationFailed = false;
     let healing = false;
     context.setInterval(() => {
       const liveSessionID = context.sessionManager.getSessionId();
@@ -33735,7 +33797,12 @@ function envoyExtension(pi) {
       if (healing)
         return;
       healing = true;
-      (drifted ? establishSession(context) : registerSession()).then(() => {
+      const afterOutage = registrationFailed;
+      (drifted ? establishSession(context) : registerSession()).then(() => drifted ? undefined : reassertRole(afterOutage, context), (error) => {
+        registrationFailed = true;
+        throw error;
+      }).then(() => {
+        registrationFailed = false;
         heartbeatOutageNotified = false;
       }).catch((error) => {
         if (heartbeatOutageNotified)
@@ -34301,15 +34368,29 @@ function legionExtension(pi) {
       }
     });
   };
+  const rerunReadyAfterRegain = async (endpoint, role, reason, call) => {
+    try {
+      await callReadyWithRetry(`${endpoint} after role regain`, call);
+      console.error(`[legion] re-ran ${endpoint} after role ${role} was ${reason}`);
+    } catch (error) {
+      console.error(`[legion] ${endpoint} after role ${role} was ${reason} failed; the daemon's held work stays undelivered until the next regain or boot: ${messageFor(error)}`);
+    }
+  };
   const claimController = async (context) => {
     const sessionID = context.sessionManager.getSessionId();
     const daemon = createLegionDaemonClient(requiredEnvironment(process.env, "LEGION_DAEMON_URL"));
     const secret = controllerCapability ?? requiredControllerCapability(process.env);
     controllerCapability = secret;
     const { project } = await daemon.state();
-    await claimEnvoyRole(sessionID, controllerToken(project), "setInterval" in context ? context : undefined);
+    const token = controllerToken(project);
+    await claimEnvoyRole(sessionID, token, "setInterval" in context ? context : undefined);
     await daemon.controllerReady({ secret, sessionId: sessionID });
     controllerSessionID = sessionID;
+    onEnvoyRoleRegained(async (role, reason) => {
+      if (role !== token)
+        return;
+      await rerunReadyAfterRegain("controller/ready", role, reason, () => daemon.controllerReady({ secret, sessionId: sessionID }));
+    });
   };
   const reclaimArchitect = async () => {
     if (capability === undefined || capability.kind !== "root-architect") {
@@ -34412,6 +34493,17 @@ function legionExtension(pi) {
           secret: started.secret,
           generation: generation(process.env)
         }));
+        onEnvoyRoleRegained(async (role, reason) => {
+          if (role !== roleToken || capability === undefined)
+            return;
+          const { secret } = capability;
+          await rerunReadyAfterRegain("process/ready", role, reason, () => roleDaemon().processReady({
+            tree,
+            sessionId: sessionID,
+            secret,
+            generation: generation(process.env)
+          }));
+        });
         registerArchitectTools();
         await activateLegionTool();
       } catch (error) {

package/dist/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/dist/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.

package/package.json

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