@sjawhar/opencode-legion-envoy 1.22.0 → 1.24.0

package/dist/src/server.js

@@ -13552,6 +13552,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 };
 }
@@ -13634,6 +13635,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(),
@@ -13660,7 +13663,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(),
@@ -13751,6 +13754,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",
@@ -13846,9 +13859,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",
@@ -14194,6 +14208,19 @@ var stateRole = strictObject({
   launchFailures: number2().int().nonnegative().optional(),
   locator: stateLocator.optional()
 });
+var stateQueuedWorkerIdentity = {
+  roleToken: nonEmptyString,
+  issue: nonEmptyString,
+  role: nonEmptyString
+};
+var stateQueuedWorker = union([
+  strictObject(stateQueuedWorkerIdentity),
+  strictObject({
+    ...stateQueuedWorkerIdentity,
+    kind: _enum2(["assignment", "catchup"]),
+    queuedAt: nonEmptyString
+  })
+]);
 var LegionDaemonApi = {
   State: {
     response: strictObject({
@@ -14210,7 +14237,8 @@ var LegionDaemonApi = {
       controllerLocator: stateLocator.optional(),
       roles: record(string2(), stateRole),
       controllerPendingNotices: number2().int().nonnegative(),
-      pendingStatusWrites: array(nonEmptyString)
+      pendingStatusWrites: array(nonEmptyString),
+      workerAdmission: strictObject({ queue: array(stateQueuedWorker) })
     })
   },
   ControllerReady: {
@@ -14297,7 +14325,8 @@ var LegionDaemonApi = {
     request: architectCapability.extend({
       issue: nonEmptyString,
       role: legionRole,
-      task: nonEmptyString
+      task: nonEmptyString,
+      requestId: uuid2()
     }),
     response: object({
       status: _enum2(["spawned", "resumed", "queued"]),
@@ -15598,21 +15627,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": {

package/package.json

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

package/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/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/skills/legion-architect/SKILL.md

@@ -301,7 +301,7 @@ active phase worker.
 | `design-approved` | Payload `{type:"design-approved"}`. A human approved the root spec document at its current version; the gate is open. Proceed to section 2. |
 | `design-changes-requested` | Payload `{type:"design-changes-requested", version, reason, author?}`. A human asked for changes to the root spec at `version`, for `reason`. Revise the spec, call `dispatch_request_approval` again, and stay parked; the gate is closed. |
 | `phase-complete` | Payload `{type:"phase-complete", issue, role, summary}`. May arrive live or via `catchup-overseer`'s `phaseCompletions`. Read the committed handoff for that phase, then spawn the next phase's owner, or `spawn_worker` on the same role again to resume it with corrections if the handoff shows unresolved gaps. A `reviewer` completion whose GitHub review is `CHANGES_REQUESTED` (the daemon returns the issue's Dispatch status to `in_progress` for this, on the reviewer's completion and again when you spawn the corrective implementer unless the daemon already knows the issue is `in_progress`) means `spawn_worker` the **implementer** again with the review findings — thread URLs and blocking items — as its task, then route back through tester and reviewer in order; never `spawn_worker` the reviewer directly off this wake and never proceed to retro on this verdict. A reviewer completion with an `APPROVED` review proceeds to retro (step 5). A `reviewer` completion after a conflict-forced rebase whose review body names an unchanged fingerprint is a confirmation, not a round: if retro already completed, `spawn_worker` the merger; otherwise resume the step you were on. An `implementer` completion that follows the merge is its production report: read the record on the pull request and the issue, then run step 7 — the issue is already at `retro`, the daemon writes no status for this completion, and you set `done` yourself. A `tester` completion whose handoff carries `implementerProof.verdict: "rejected"`, or a failure naming the production-like proof, goes back to the **implementer** with that finding — never forward to the reviewer, and never by supplying the proof from another role. A worker that reports no surface reaches the changed path gets a child issue in this tree (infrastructure, tooling, or a skill) and a resume once it lands; that report is never a reason to advance the phase. |
-| `worker-queued` | Payload `{type:"worker-queued", issue, role}`. This role's task is queued for promotion — either the deployment's worker cap is full, or the live worker acknowledged the task without starting a turn and the daemon is retrying it (counted; the worker is replaced after three such failures, still with the same task). Do not respawn or retry — wait for `worker-started`. |
+| `worker-queued` | Payload `{type:"worker-queued", issue, role}`. This role's task is queued for promotion — either the deployment's worker cap is full, or the live worker acknowledged the task without starting a turn and the daemon is retrying it (counted; the worker is replaced after three such failures, still with the same task). Do not respawn or retry — wait for `worker-started`. `legion state` shows the queue (`workerAdmission.queue`: role token, issue, role, kind, and the time the task was first queued — never the task text); read it before re-sending. A `spawn_worker` identical to the queued task changes nothing and is not announced again. Different text replaces the queued task silently in the same FIFO slot and retains its original queue time. A `spawn_worker` that fails with "got no response in 3 attempts" was already retried by the plugin under one request id and may still have reached the daemon: read the queue and the role's claim in `legion state` before sending it again. |
 | `worker-started` | Payload `{type:"worker-started", issue, role}`. A previously queued role has been promoted and is now running. Treat it exactly as a normal spawn: resume tracking that role's live session. |
 | `pr-ready` | Verify the live PR head, green status, and review state. Continue the review/retro/merger order only for that current head. |
 | `pr-review` | Payload `{type:"pr-review", state, author, body}`. Delivered to whichever role is currently active for the issue, falling back to you when no worker phase is active. Follows the same verdict rule as a reviewer's `phase-complete`: `state: "changes_requested"` sends the implementer back in with the review findings, then tester, then reviewer — never the reviewer again and never retro; that `spawn_worker` returns the issue to `in_progress` on its own (the daemon writes it for a corrective implementer whenever the PR's latest recorded review is changes requested, a human's after approval included), so you set nothing by hand; `state: "approved"` proceeds toward retro (step 5) once the step 6 integration/merge-gate conditions are met. `state: "approved"` on a rebased head whose body names an unchanged fingerprint is that confirmation: proceed to retro if it has not run, otherwise to the merger — never to a second retro or test round. |