@sjawhar/pi-legion-envoy 5.1.1 → 5.2.1

package/dist/envoy.js

@@ -30052,7 +30052,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_issue",
     example: { project: "DSP", title: "Native workspace" },
-    description: "Create a native Dispatch issue for newly tracked work. Search first with dispatch_search; if potentially duplicate issues exist, this returns 409 POSSIBLE_DUPLICATE unless force is true after reading them. " + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
+    description: "Create a native Dispatch issue for newly tracked work. Search first with dispatch_search; if potentially duplicate issues exist, this returns 409 POSSIBLE_DUPLICATE unless force is true after reading them. " + "A spec holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK. " + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
     arguments: (z2) => ({
       project: z2.string().describe("Project key for the new issue."),
       title: z2.string().describe("Concise issue title."),
@@ -30298,7 +30298,7 @@ var dispatchToolSpecs = [
     name: "dispatch_artifact",
     example: { issue: "DSP-1", name: "design.md", content: `# Design
 ` },
-    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}`,
+    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. " + "Markdown holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK; a new version of a document is held to it only for the asks it writes or changes. " + `${OWNER_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key for an unlinked document.").optional(),
@@ -34979,8 +34979,15 @@ var ROLE_CLAIM_ENTRY = "envoy-role-claim";
 var OPEN_ASKS_TIMEOUT_MS = 3000;
 var LEGION_MANAGED_ENTRY = "legion-managed-session";
 var ASK_REMINDER_MESSAGE = "dispatch-ask-reminder";
-var OPEN_ASKS_REMINDER = "You have no unanswered asks in Dispatch. If you are waiting for human input, open an ask. Otherwise ignore this reminder and continue with any remaining work. Do not reply just to acknowledge this reminder.";
+var ASK_SELF_CHECK_PROMPT = "Your run has just ended. Answer with exactly one word and nothing else: WAITING or PROCEEDING. " + "WAITING \u2014 you stopped because you need a decision, an approval, or information from a human. " + "PROCEEDING \u2014 you finished, you will carry on by yourself, or you are waiting only on tools, " + "subagents, or events.";
+var WAITING_VERDICT = /^\W*WAITING\b/;
+var ECHOED_CHOICE = /\bPROCEEDING\b/;
+var isWaitingVerdict = (reply) => WAITING_VERDICT.test(reply) && !ECHOED_CHOICE.test(reply);
+var ASK_SELF_CHECK_TIMEOUT_MS = 60000;
+var ASK_CHECKS_PER_PERIOD = 5;
+var UNASKED_WAIT_REMINDER = "You just said you are waiting on a human, but you have no open ask in Dispatch, so nobody knows you are waiting. Open it now with dispatch_ask \u2014 or dispatch_request_approval when what you need is approval of a document \u2014 naming exactly what you need and from whom. Do not reply just to acknowledge this reminder.";
 var ASK_OPENING_TOOLS = ["dispatch_ask", "dispatch_request_approval"];
+var DISPATCH_TOOL_PREFIX = "dispatch_";
 function isLegionManagedEntry(entry) {
   if (typeof entry !== "object" || entry === null)
     return false;
@@ -35051,11 +35058,23 @@ function envoyExtension(pi) {
     session_id: "",
     period: 0,
     baseline_as_of: null,
-    fired: false,
-    saw_ask: false
+    check_due: false,
+    checks: 0
   };
   let awarenessGeneration = 0;
   let askCheckInFlight = false;
+  let settledDuringCheck;
+  const takeSettledDuringCheck = () => {
+    const settle = settledDuringCheck;
+    settledDuringCheck = undefined;
+    return settle;
+  };
+  let askCheckAbort;
+  const abortSelfCheck = (reason) => {
+    askCheckAbort?.abort(new Error(reason));
+    askCheckAbort = undefined;
+  };
+  let runSeq = 0;
   let legionManagedTranscript = false;
   const legionManaged = (id) => legionManagedTranscript || legionRoleClaimBridge().managedSessions.has(id);
   const availabilityWarningSessionIDs = new Set;
@@ -35066,6 +35085,19 @@ function envoyExtension(pi) {
     availabilityWarningSessionIDs.add(sessionID2);
     context.ui.notify(`envoy: Dispatch open-ask check unavailable (${messageFor(error48)}); the stop-time ask reminder is off until it recovers`, "warning");
   };
+  const askEphemeral = pi.askEphemeral;
+  const overriddenTimeout = Number(process.env.ENVOY_SELF_CHECK_TIMEOUT_MS);
+  const selfCheckTimeoutMs = Number.isFinite(overriddenTimeout) && overriddenTimeout > 0 ? overriddenTimeout : ASK_SELF_CHECK_TIMEOUT_MS;
+  const selfCheckWarningSessionIDs = new Set;
+  const logSelfCheckFailure = (failedSessionID, error48) => {
+    if (selfCheckWarningSessionIDs.has(failedSessionID))
+      return;
+    selfCheckWarningSessionIDs.add(failedSessionID);
+    logger.warn("envoy: run-end waiting self-check failed; no reminder was sent", {
+      sessionID: failedSessionID,
+      error: messageFor(error48)
+    });
+  };
   const queryOpenAsks = async (requestedSessionID, since) => {
     const config2 = activeDispatchConfig();
     if (config2 === null)
@@ -35086,15 +35118,18 @@ function envoyExtension(pi) {
     sessionID = context.sessionManager.getSessionId();
     activeSessionContext = context;
     const branch = context.sessionManager.getBranch?.() ?? [];
-    askAwareness = {
-      session_id: sessionID,
-      period: 0,
-      baseline_as_of: null,
-      fired: false,
-      saw_ask: false
-    };
+    if (askAwareness.session_id !== sessionID) {
+      abortSelfCheck(`session changed from ${askAwareness.session_id || "none"} to ${sessionID}`);
+      askAwareness = {
+        session_id: sessionID,
+        period: 0,
+        baseline_as_of: null,
+        check_due: false,
+        checks: 0
+      };
+      awarenessGeneration++;
+    }
     legionManagedTranscript = branch.some(isLegionManagedEntry);
-    awarenessGeneration++;
   };
   pi.on("resources_discover", async () => ({ skillPaths: [SKILLS_DIRECTORY] }));
   registerEnvoyMessageRenderer(pi);
@@ -35610,69 +35645,148 @@ function envoyExtension(pi) {
   registerEnvoyWhoamiCommand(pi, () => sessionID);
   pi.on("before_agent_start", async (event, context) => {
     const id = context.sessionManager.getSessionId();
-    if (id === "" || event.prompt.trim() === "" || !context.hasUI || legionManaged(id)) {
+    if (id === "" || event.prompt.trim() === "" || !context.hasUI || askEphemeral === undefined || legionManaged(id)) {
       return;
     }
     if (await isSubagent(context))
       return;
+    awarenessGeneration++;
+    abortSelfCheck("a new user turn superseded the self-check");
     try {
       const open = await queryOpenAsks(id);
       if (open !== null)
-        armAskAwareness(id, event.prompt, open.snapshot.as_of);
+        armAskAwareness(id, open.snapshot.as_of);
     } catch (error48) {
       warnAskAvailability(context, error48);
     }
     return;
   });
-  function armAskAwareness(id, prompt, asOf) {
-    if (prompt.trim() === "")
-      return;
-    awarenessGeneration++;
+  pi.on("agent_start", async () => {
+    runSeq += 1;
+  });
+  function armAskAwareness(id, asOf) {
     askAwareness = {
       session_id: id,
       period: (askAwareness.session_id === id ? askAwareness.period : 0) + 1,
       baseline_as_of: asOf,
-      fired: false,
-      saw_ask: false
+      check_due: true,
+      checks: 0
     };
   }
   pi.on("agent_end", async (event, context) => {
     const id = context.sessionManager.getSessionId();
     const lastReply = event.messages?.findLast((message) => message.role === "assistant");
-    if (event.willContinue === true || lastReply?.stopReason !== "stop" || shuttingDown || !context.hasUI || id === "" || id !== sessionID || legionManaged(id) || askAwareness.session_id !== id || askAwareness.period === 0 || askAwareness.fired || askAwareness.saw_ask || askAwareness.baseline_as_of === null || askCheckInFlight) {
+    if (event.willContinue === true || lastReply?.stopReason !== "stop" || !context.hasUI || id === "" || !checkOwed(id)) {
+      return;
+    }
+    if (askCheckInFlight) {
+      settledDuringCheck = { context, seenRun: runSeq };
       return;
     }
-    const period = askAwareness.period;
-    const generation = awarenessGeneration;
     askCheckInFlight = true;
     try {
-      let open;
-      try {
-        open = await queryOpenAsks(id, askAwareness.baseline_as_of);
-      } catch (error48) {
-        if (generation === awarenessGeneration)
-          warnAskAvailability(context, error48);
-        return;
-      }
-      if (open === null || shuttingDown || generation !== awarenessGeneration || sessionID !== id || context.sessionManager.getSessionId() !== id || legionManaged(id) || askAwareness.session_id !== id || askAwareness.period !== period || askAwareness.fired || askAwareness.saw_ask) {
-        return;
+      let settle = { context, seenRun: runSeq };
+      while (settle !== undefined) {
+        await checkAtSettle(id, settle);
+        settle = takeSettledDuringCheck();
+        if (settle?.context.sessionManager.getSessionId() !== id || settle.seenRun !== runSeq || !checkOwed(id)) {
+          settle = undefined;
+        }
       }
-      if (open.snapshot.count > 0 || open.snapshot.opened_since)
-        return;
-      askAwareness = { ...askAwareness, fired: true };
-      pi.sendMessage({ customType: ASK_REMINDER_MESSAGE, content: OPEN_ASKS_REMINDER, display: false }, { deliverAs: "steer", triggerTurn: true });
     } finally {
       askCheckInFlight = false;
+      settledDuringCheck = undefined;
     }
   });
+  function checkOwed(id) {
+    return !(shuttingDown || legionManaged(id) || askAwareness.session_id !== id || askAwareness.period === 0 || !askAwareness.check_due || askAwareness.checks >= ASK_CHECKS_PER_PERIOD || askAwareness.baseline_as_of === null || askEphemeral === undefined);
+  }
+  async function checkAtSettle(id, settle) {
+    const { context, seenRun } = settle;
+    const period = askAwareness.period;
+    const generation = awarenessGeneration;
+    const baseline = askAwareness.baseline_as_of;
+    if (baseline === null || askEphemeral === undefined)
+      return;
+    const stale = () => shuttingDown || generation !== awarenessGeneration || context.sessionManager.getSessionId() !== id || legionManaged(id) || askAwareness.session_id !== id || askAwareness.period !== period || !askAwareness.check_due;
+    let open;
+    try {
+      open = await queryOpenAsks(id, baseline);
+    } catch (error48) {
+      if (generation === awarenessGeneration)
+        warnAskAvailability(context, error48);
+      return;
+    }
+    if (open === null || stale())
+      return;
+    if (runSeq !== seenRun)
+      return;
+    if (open.snapshot.count > 0 || open.snapshot.opened_since) {
+      askAwareness = {
+        ...askAwareness,
+        check_due: false,
+        baseline_as_of: open.snapshot.as_of
+      };
+      return;
+    }
+    const abort = new AbortController;
+    askCheckAbort = abort;
+    let answered;
+    try {
+      answered = askEphemeral({ prompt: ASK_SELF_CHECK_PROMPT, signal: abort.signal }).then((reply) => reply.replyText, (error48) => {
+        if (!abort.signal.aborted)
+          logSelfCheckFailure(id, error48);
+        return;
+      });
+    } catch (error48) {
+      logSelfCheckFailure(id, error48);
+      answered = Promise.resolve(undefined);
+    }
+    const expiry = Promise.withResolvers();
+    const expire = setTimeout(() => {
+      const timedOut = new Error(`self-check timed out after ${selfCheckTimeoutMs} ms`);
+      abort.abort(timedOut);
+      logSelfCheckFailure(id, timedOut);
+      expiry.resolve(undefined);
+    }, selfCheckTimeoutMs);
+    let verdict;
+    try {
+      verdict = await Promise.race([answered, expiry.promise]);
+    } finally {
+      clearTimeout(expire);
+      if (askCheckAbort === abort)
+        askCheckAbort = undefined;
+    }
+    if (stale()) {
+      abort.abort(new Error("the self-check was superseded before its verdict arrived"));
+      return;
+    }
+    const superseded = runSeq !== seenRun;
+    askAwareness = {
+      ...askAwareness,
+      check_due: superseded,
+      checks: askAwareness.checks + 1,
+      baseline_as_of: open.snapshot.as_of
+    };
+    if (superseded)
+      return;
+    if (verdict === undefined || !isWaitingVerdict(verdict.trim()))
+      return;
+    pi.sendMessage({ customType: ASK_REMINDER_MESSAGE, content: UNASKED_WAIT_REMINDER, display: false }, { deliverAs: "steer", triggerTurn: true });
+  }
   const announceFollow = createFollowAnnouncer((text) => {
     pi.sendMessage({ customType: "envoy-message", content: text, display: true, details: LOCAL_ENVOY_NOTICE }, { deliverAs: "steer", triggerTurn: false });
   });
-  pi.on("tool_result", async (event) => {
+  pi.on("tool_result", async (event, context) => {
     if (event.isError)
       return;
-    if (ASK_OPENING_TOOLS.includes(event.toolName) && askAwareness.session_id === sessionID && askAwareness.period > 0 && !askAwareness.saw_ask) {
-      askAwareness = { ...askAwareness, saw_ask: true };
+    if (askAwareness.session_id === context.sessionManager.getSessionId() && askAwareness.period > 0) {
+      if (ASK_OPENING_TOOLS.includes(event.toolName)) {
+        askAwareness = { ...askAwareness, check_due: false };
+        abortSelfCheck("the agent opened the ask itself");
+      } else if (!event.toolName.startsWith(DISPATCH_TOOL_PREFIX)) {
+        askAwareness = { ...askAwareness, check_due: true };
+      }
     }
     announceFollow(event.details);
   });

package/dist/legion.js

@@ -16142,7 +16142,7 @@ import { logger } from "@oh-my-pi/pi-utils";
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion-envoy",
-  version: "5.1.1",
+  version: "5.2.1",
   type: "module",
   omp: {
     extensions: [
@@ -30125,7 +30125,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_issue",
     example: { project: "DSP", title: "Native workspace" },
-    description: "Create a native Dispatch issue for newly tracked work. Search first with dispatch_search; if potentially duplicate issues exist, this returns 409 POSSIBLE_DUPLICATE unless force is true after reading them. " + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
+    description: "Create a native Dispatch issue for newly tracked work. Search first with dispatch_search; if potentially duplicate issues exist, this returns 409 POSSIBLE_DUPLICATE unless force is true after reading them. " + "A spec holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK. " + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
     arguments: (z2) => ({
       project: z2.string().describe("Project key for the new issue."),
       title: z2.string().describe("Concise issue title."),
@@ -30371,7 +30371,7 @@ var dispatchToolSpecs = [
     name: "dispatch_artifact",
     example: { issue: "DSP-1", name: "design.md", content: `# Design
 ` },
-    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}`,
+    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. " + "Markdown holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK; a new version of a document is held to it only for the asks it writes or changes. " + `${OWNER_REFERENCE}`,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key for an unlinked document.").optional(),

package/dist/skills/dispatch/SKILL.md

@@ -688,7 +688,10 @@ 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:
+item is `Label: description`. A spec, an uploaded document or an uploaded version holding an ask that
+breaks that shape - a code block, heading or quote in it, a paragraph after its options, a second
+list - is refused with `INVALID_ASK_BLOCK`; so is an edit that writes one. An ask someone left
+unreadable in the browser refuses nothing it is carried through unchanged by. For example:
 
 ```md
 :::ask{urgency="high" multiple="false"}

package/package.json

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