@sjawhar/pi-legion-envoy 1.33.0 → 1.34.0

package/dist/envoy.js

@@ -29649,6 +29649,7 @@ function date4(params) {
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
 config(en_default());
 // ../contracts/src/dispatch-api.ts
+var DELIVERY_CAPABILITIES = ["aside", "btw", "steer"];
 function searchOwnerOf(result) {
   return result.owner ?? { kind: "issue", key: result.issue.key };
 }
@@ -29731,6 +29732,8 @@ var CommentEventPayloadSchema = object({
   ask_id: string2().nullish(),
   ask_question: string2().optional(),
   ask_state: _enum2(["open", "answered", "resolved"]).optional(),
+  ask_waiting_on: _enum2(["human", "agent"]).optional(),
+  turn: _enum2(["human", "agent"]).nullish(),
   anchor: object({ block_id: string2().nullable().optional(), quote: string2().optional() }).nullish(),
   suggestion: object({ replace_with: string2().optional() }).nullish(),
   author: object({ kind: string2(), id: string2() }).optional(),
@@ -29757,7 +29760,7 @@ var DispatchTargetedMessagePayloadSchema = MessageEventPayloadSchema.extend({
 var MessageDeliveryEventPayloadSchema = object({
   message_id: string2().optional(),
   attempt: number2().int().positive().optional(),
-  delivery: _enum2(["btw", "aside", "steer"]).optional(),
+  delivery: _enum2(DELIVERY_CAPABILITIES).optional(),
   session_id: string2().optional(),
   target: string2().optional(),
   title: string2().optional(),
@@ -29848,6 +29851,16 @@ function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false)
     message: alwaysRequireArtifact ? "Exactly one of issue and project is required; artifact or ref must name the document." : "Exactly one of issue and project is required; with project, artifact names the document."
   };
 }
+var commentValidation = (() => {
+  const owner = documentOwnerValidation(true);
+  return {
+    check: (value) => {
+      const input = value;
+      return owner.check(value) && (input.turn === undefined || typeof input.reply_to_ask === "string");
+    },
+    message: `${owner.message} turn requires reply_to_ask.`
+  };
+})();
 var SPEC_SECTIONS = [
   "Summary",
   "Decisions needed",
@@ -29943,9 +29956,10 @@ var dispatchToolSpecs = [
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional(),
       body: z.string({ max: 2000 }).describe("Review comment, at most 2,000 characters."),
       reply_to: z.string().describe("Full id of a comment to reply to; replying to any comment in a thread continues that " + "thread (an ask's clarification thread included).").optional(),
-      reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional()
+      reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional(),
+      turn: z.enum(["agent", "human"]).describe("Only with reply_to_ask: who holds the turn after this reply. agent: a progress note - " + "you keep the turn and the ask stays 'Waiting on agents' for the human; human (default): " + "you need the human to act - the ask returns to 'Waiting on you'.").optional()
     }),
-    validation: documentOwnerValidation(true)
+    validation: commentValidation
   },
   {
     name: "dispatch_suggest",
@@ -31103,7 +31117,7 @@ var TolerantInboundEnvelopeSchema = object({
 }).passthrough();
 var DispatchDeliveryRequestSchema = object({
   attempt: number2().int().positive(),
-  mode: _enum2(["btw", "aside", "steer"])
+  mode: _enum2(DELIVERY_CAPABILITIES)
 });
 var DispatchTargetedFrameSchema = object({
   event: DispatchEventSchema,
@@ -32595,21 +32609,34 @@ async function executeDispatchTool(input) {
       if (replyTo !== undefined && replyToAsk !== undefined) {
         throw new Error("reply_to and reply_to_ask cannot both be set");
       }
+      const requestedTurn = optionalString(args, "turn");
+      if (requestedTurn !== undefined && replyToAsk === undefined) {
+        throw new Error("turn requires reply_to_ask");
+      }
+      if (requestedTurn !== undefined && requestedTurn !== "agent" && requestedTurn !== "human") {
+        throw new Error("turn must be agent or human");
+      }
       const commentInput = {
         body: stringArg(args, "body"),
         ...anchored === undefined ? {} : { anchor: anchored },
         ...replyTo === undefined ? {} : { reply_to: replyTo },
         ...replyToAsk === undefined ? {} : { ask_id: replyToAsk },
+        ...requestedTurn === undefined ? {} : { turn: requestedTurn },
         actor
       };
       const comment = resolved?.owner.kind === "project" ? await client.artifactComment(resolved.artifact.id, commentInput) : await client.comment(issue(), commentInput);
+      const askState = comment.turn === null ? "" : ` (ask now waiting on ${comment.turn})`;
       return {
-        text: `Posted comment ${comment.id}`,
+        text: `Posted comment ${comment.id}${askState}`,
         details: resolved === undefined ? {
           issue: comment.issue_key,
           topic: dispatchIssueSubject(issue(), ">"),
-          comment: comment.id
-        } : writeResultDetails(resolved, { comment: comment.id })
+          comment: comment.id,
+          ...comment.turn === null ? {} : { ask_waiting_on: comment.turn }
+        } : writeResultDetails(resolved, {
+          comment: comment.id,
+          ...comment.turn === null ? {} : { ask_waiting_on: comment.turn }
+        })
       };
     }
     case "dispatch_suggest": {
@@ -33290,6 +33317,8 @@ async function copySessionID(copyToClipboard, sessionID) {
 // extensions/envoy.ts
 var codec2 = import_nats.StringCodec();
 var NATS_RETRY_INTERVAL_MS = 15000;
+var ALL_CAPABILITIES = DELIVERY_CAPABILITIES;
+var CAPABILITIES_WITHOUT_BTW = DELIVERY_CAPABILITIES.filter((capability) => capability !== "btw");
 var ROLE_CLAIM_ENTRY = "envoy-role-claim";
 var OPEN_ASKS_TIMEOUT_MS = 3000;
 function isRoleClaimEntry(entry) {
@@ -33548,7 +33577,7 @@ function envoyExtension(pi) {
     topics: [...new Set([agentSubject(sessionID), ...subscriptions.keys()])],
     port: 0,
     title: activeSessionContext?.sessionManager.getSessionName?.() ?? "",
-    capabilities: typeof pi.askEphemeral === "function" ? ["aside", "btw"] : ["aside"],
+    capabilities: typeof pi.askEphemeral === "function" ? ALL_CAPABILITIES : CAPABILITIES_WITHOUT_BTW,
     driving: false,
     selfSubscribed: true
   });

package/dist/legion.js

@@ -29649,6 +29649,7 @@ function date4(params) {
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
 config(en_default());
 // ../contracts/src/dispatch-api.ts
+var DELIVERY_CAPABILITIES = ["aside", "btw", "steer"];
 function searchOwnerOf(result) {
   return result.owner ?? { kind: "issue", key: result.issue.key };
 }
@@ -29731,6 +29732,8 @@ var CommentEventPayloadSchema = object({
   ask_id: string2().nullish(),
   ask_question: string2().optional(),
   ask_state: _enum2(["open", "answered", "resolved"]).optional(),
+  ask_waiting_on: _enum2(["human", "agent"]).optional(),
+  turn: _enum2(["human", "agent"]).nullish(),
   anchor: object({ block_id: string2().nullable().optional(), quote: string2().optional() }).nullish(),
   suggestion: object({ replace_with: string2().optional() }).nullish(),
   author: object({ kind: string2(), id: string2() }).optional(),
@@ -29757,7 +29760,7 @@ var DispatchTargetedMessagePayloadSchema = MessageEventPayloadSchema.extend({
 var MessageDeliveryEventPayloadSchema = object({
   message_id: string2().optional(),
   attempt: number2().int().positive().optional(),
-  delivery: _enum2(["btw", "aside", "steer"]).optional(),
+  delivery: _enum2(DELIVERY_CAPABILITIES).optional(),
   session_id: string2().optional(),
   target: string2().optional(),
   title: string2().optional(),
@@ -29848,6 +29851,16 @@ function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false)
     message: alwaysRequireArtifact ? "Exactly one of issue and project is required; artifact or ref must name the document." : "Exactly one of issue and project is required; with project, artifact names the document."
   };
 }
+var commentValidation = (() => {
+  const owner = documentOwnerValidation(true);
+  return {
+    check: (value) => {
+      const input = value;
+      return owner.check(value) && (input.turn === undefined || typeof input.reply_to_ask === "string");
+    },
+    message: `${owner.message} turn requires reply_to_ask.`
+  };
+})();
 var SPEC_SECTIONS = [
   "Summary",
   "Decisions needed",
@@ -29943,9 +29956,10 @@ var dispatchToolSpecs = [
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional(),
       body: z.string({ max: 2000 }).describe("Review comment, at most 2,000 characters."),
       reply_to: z.string().describe("Full id of a comment to reply to; replying to any comment in a thread continues that " + "thread (an ask's clarification thread included).").optional(),
-      reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional()
+      reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional(),
+      turn: z.enum(["agent", "human"]).describe("Only with reply_to_ask: who holds the turn after this reply. agent: a progress note - " + "you keep the turn and the ask stays 'Waiting on agents' for the human; human (default): " + "you need the human to act - the ask returns to 'Waiting on you'.").optional()
     }),
-    validation: documentOwnerValidation(true)
+    validation: commentValidation
   },
   {
     name: "dispatch_suggest",
@@ -31616,7 +31630,7 @@ var TolerantInboundEnvelopeSchema = object({
 }).passthrough();
 var DispatchDeliveryRequestSchema = object({
   attempt: number2().int().positive(),
-  mode: _enum2(["btw", "aside", "steer"])
+  mode: _enum2(DELIVERY_CAPABILITIES)
 });
 var DispatchTargetedFrameSchema = object({
   event: DispatchEventSchema,
@@ -33086,21 +33100,34 @@ async function executeDispatchTool(input) {
       if (replyTo !== undefined && replyToAsk !== undefined) {
         throw new Error("reply_to and reply_to_ask cannot both be set");
       }
+      const requestedTurn = optionalString(args, "turn");
+      if (requestedTurn !== undefined && replyToAsk === undefined) {
+        throw new Error("turn requires reply_to_ask");
+      }
+      if (requestedTurn !== undefined && requestedTurn !== "agent" && requestedTurn !== "human") {
+        throw new Error("turn must be agent or human");
+      }
       const commentInput = {
         body: stringArg(args, "body"),
         ...anchored === undefined ? {} : { anchor: anchored },
         ...replyTo === undefined ? {} : { reply_to: replyTo },
         ...replyToAsk === undefined ? {} : { ask_id: replyToAsk },
+        ...requestedTurn === undefined ? {} : { turn: requestedTurn },
         actor
       };
       const comment = resolved?.owner.kind === "project" ? await client.artifactComment(resolved.artifact.id, commentInput) : await client.comment(issue(), commentInput);
+      const askState = comment.turn === null ? "" : ` (ask now waiting on ${comment.turn})`;
       return {
-        text: `Posted comment ${comment.id}`,
+        text: `Posted comment ${comment.id}${askState}`,
         details: resolved === undefined ? {
           issue: comment.issue_key,
           topic: dispatchIssueSubject(issue(), ">"),
-          comment: comment.id
-        } : writeResultDetails(resolved, { comment: comment.id })
+          comment: comment.id,
+          ...comment.turn === null ? {} : { ask_waiting_on: comment.turn }
+        } : writeResultDetails(resolved, {
+          comment: comment.id,
+          ...comment.turn === null ? {} : { ask_waiting_on: comment.turn }
+        })
       };
     }
     case "dispatch_suggest": {
@@ -33773,6 +33800,8 @@ async function copySessionID(copyToClipboard, sessionID) {
 // extensions/envoy.ts
 var codec2 = import_nats.StringCodec();
 var NATS_RETRY_INTERVAL_MS = 15000;
+var ALL_CAPABILITIES = DELIVERY_CAPABILITIES;
+var CAPABILITIES_WITHOUT_BTW = DELIVERY_CAPABILITIES.filter((capability) => capability !== "btw");
 var ROLE_CLAIM_ENTRY = "envoy-role-claim";
 var OPEN_ASKS_TIMEOUT_MS = 3000;
 function isRoleClaimEntry(entry) {
@@ -34031,7 +34060,7 @@ function envoyExtension(pi) {
     topics: [...new Set([agentSubject(sessionID), ...subscriptions.keys()])],
     port: 0,
     title: activeSessionContext?.sessionManager.getSessionName?.() ?? "",
-    capabilities: typeof pi.askEphemeral === "function" ? ["aside", "btw"] : ["aside"],
+    capabilities: typeof pi.askEphemeral === "function" ? ALL_CAPABILITIES : CAPABILITIES_WITHOUT_BTW,
     driving: false,
     selfSubscribed: true
   });

package/dist/skills/dispatch/SKILL.md

@@ -42,6 +42,16 @@ agent's `envoy.json` to set the GitHub OAuth callback origin: the value must
 be the exact URL humans type in their browser, and the GitHub App callback is
 `<DISPATCH_SERVER_URL>/auth/callback`.
 
+### Finding a route
+
+The tools cover the everyday surface. For anything else, ask the server: `GET /api/v1` (no
+credential) returns every route as `{method, path, auth, description}` sorted by path — `auth`
+is `public`, `any` (a human or a bearer), `human` (a bearer gets `403 HUMAN_ONLY`), or `bearer`.
+A path Dispatch does not serve under `/api` or `/v1` answers
+`404 {"code":"NOT_FOUND","error":"no route for GET /v1/issues","hint":"GET /api/v1 lists every
+route"}`; when you see that, you typed the path wrong — read the index rather than guessing. Every
+`/api/v1` error body carries a `code`; branch on the code, never on the text.
+
 ## Writing a spec
 
 A spec has two readers: the human who decides reads the top; the implementer who builds reads the
@@ -194,6 +204,14 @@ an answer: the human did not understand the question or needs more before choosi
 in the same thread with `dispatch_comment({ reply_to_ask })`, or reword the question itself with `dispatch_edit_ask` when the wording
 was the problem; either puts the ask back in front of them. Do not open a second ask.
 
+Every reply to an open ask says whose turn it is next, and the Inbox files the ask by that, not by who spoke last. Your plain reply
+(`turn` omitted, or `turn: "human"`) hands the turn to the human: the ask returns to their `Waiting on you`. When you are not done
+yet — "dispatched two auditors, back with results", "checking the release branch, back shortly", any working-on-it note — reply with
+`turn: "agent"`: the note lands in the thread, the ask stays under `Waiting on agents`, and the human is not told to act. Use
+`turn: "agent"` for every progress note and `turn: "human"` (the default) only when you need them. A human's reply always hands the
+turn to you. The result names the state (`ask now waiting on agent` / `human`), the delivered `comment.created` carries it as
+`ask_waiting_on`, and every ask read carries it as `waiting_on`.
+
 ## Approval of a spec
 
 Approval is a property of a document, not a question you phrase: a human approves a specific version, the way a pull-request
@@ -300,7 +318,7 @@ an ask block without a question or with a blank option is rejected with `INVALID
 Add feedback with:
 
 ```ts
-dispatch_comment({ issue?, project?, artifact?, ref?, quote?, occurrence?, body, reply_to?, reply_to_ask? })
+dispatch_comment({ issue?, project?, artifact?, ref?, quote?, occurrence?, body, reply_to?, reply_to_ask?, turn? })
 ```
 
 It returns issue or project-document owner details plus `comment` and, for writes, `topic`.
@@ -309,8 +327,10 @@ It returns issue or project-document owner details plus `comment` and, for write
 for display. Omit both for a floating issue comment. A reply (`reply_to`/`reply_to_ask`) takes no
 `quote`; it belongs to its parent's anchor. Reply to any comment in a thread; the server keeps
 threads flat. A reply to a resolved thread reopens it. Use `reply_to_ask` to reply directly under a
-question asked with `dispatch_ask`. Comments are edited only by their author from the dashboard. A
-delivered `comment.created` event carries the comment `id`; reply to it with
+question asked with `dispatch_ask`; `turn` (only with `reply_to_ask`) says who holds the turn after
+the reply — `agent` for a progress note that keeps the ask waiting on you, `human` (the default) when
+the human needs to act; see [Asking](#asking). Comments are edited only by their author from the
+dashboard. A delivered `comment.created` event carries the comment `id`; reply to it with
 `dispatch_comment({ reply_to: <id> })`.
 
 Propose an exact replacement instead of describing it:
@@ -395,7 +415,10 @@ dispatch_message({
 delivery can post its answer automatically; use this call when the frame asks the primary agent to
 reply. `dispatch_message` itself never carries `target` or `delivery`: agent-to-agent traffic goes
 through Envoy or the hub. A bearer that targets over HTTP names its own session in `actor`
-(`{kind: "session", id}`), and the card shows that session as the author.
+(`{kind: "session", id}`), and the card shows that session as the author. `GET /api/v1/agents`
+(any authenticated caller) lists live sessions with their capabilities (`aside`, `btw`, `steer`);
+target only a session that advertises the mode you want. Sending to a session with no issue
+(`POST /api/v1/agents/{session_id}/messages`) stays human-only.
 
 ## What comes back
 

package/dist/skills/envoy/SKILL.md

@@ -90,6 +90,16 @@ envoy_send(
 )
 ```
 
+### Delivery capabilities
+
+Each session row from `envoy_sessions` carries `capabilities`, the targeted-delivery modes that
+session's host honours: `aside` (a message queued beside the model's work), `btw` (an ephemeral
+question the host answers without disturbing the current turn), and `steer` (an interjection at
+the next tool boundary). An OMP session advertises `aside`, `btw`, and `steer` (`aside` and
+`steer` on a host without `askEphemeral`); a Claude Code session advertises `aside` only, because
+its channel notifications queue for the next turn. Target a session only with a mode it
+advertises.
+
 ## Waiting for CI or a merge
 
 Subscribe to `notifications.github.example-org.example-repo.pr.42.>` and end the turn. The single

package/package.json

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