@sjawhar/opencode-legion-envoy 1.29.0 → 1.30.0

package/README.md

@@ -28,8 +28,9 @@ This package exposes:
 - `dispatch_read`
 - `dispatch_search`
 - `dispatch_open_asks`
+- `dispatch_whoami`
 
-The sixteen native `dispatch_*` tools create and read Dispatch issues, asks, comments,
+The seventeen native `dispatch_*` tools create and read Dispatch issues, asks, comments,
 documents, and artifacts, or search all of them. They are present when `dispatch.enabled`
 resolves a server URL and bearer token from envoy.json (`~/.config/opencode/envoy.json`, merged
 with `<repo>/.opencode/envoy.json`) or the `DISPATCH_URL` and `DISPATCH_TOKEN` environment

package/dist/src/server.js

@@ -13792,7 +13792,8 @@ var dispatchToolSpecs = [
       force: z.boolean().describe("Create even though POSSIBLE_DUPLICATE listed similar issues; pass it only after reading them.").optional(),
       spec: z.string().describe(`Optional initial primary-document markdown. ${SPEC_WRITING_GUIDANCE}`).optional(),
       labels: z.array(z.string({ min: 1, max: 40 }), { max: 20 }).describe("Optional initial labels, at most 20 labels of up to 40 characters.").optional(),
-      priority: z.number({ int: true, min: 0, max: 3 }).describe("Optional coarse priority: P0 is highest and P3 is lowest.").optional()
+      priority: z.number({ int: true, min: 0, max: 3 }).describe("Optional coarse priority: P0 is highest and P3 is lowest.").optional(),
+      assignee: z.string().describe("GitHub login of the human who answers this issue's asks; defaults to your owner when you act for a person, else the parent's assignee, else unassigned.").optional()
     })
   },
   {
@@ -13997,6 +13998,12 @@ var dispatchToolSpecs = [
     description: "List this session's active unanswered asks across issues and project documents, including age and whose reply is needed. Call before saying you are waiting for human input.",
     arguments: () => ({}),
     strict: true
+  },
+  {
+    name: "dispatch_whoami",
+    description: "Who Dispatch takes this session for: {session, owner}. owner is the lowercase GitHub login of the human whose personal token you run under (the default assignee of issues you create), or null under the shared token.",
+    arguments: () => ({}),
+    strict: true
   }
 ];
 // ../contracts/src/envelope.ts
@@ -14810,6 +14817,9 @@ class DispatchClient {
       ...since === undefined ? {} : { since }
     });
   }
+  async whoami() {
+    return this.#json("GET", ["api", "v1", "whoami"]);
+  }
   async resolveAsk(id, input) {
     return this.#json("POST", ["api", "v1", "asks", id, "resolve"], input);
   }
@@ -15223,7 +15233,8 @@ var issueFreeTools = {
   dispatch_resolve_comment: true,
   dispatch_follow: true,
   dispatch_search: true,
-  dispatch_open_asks: true
+  dispatch_open_asks: true,
+  dispatch_whoami: true
 };
 function canonicalExternalIssueRef(value) {
   const match = value.trim().match(externalIssueRefPattern);
@@ -15639,10 +15650,13 @@ function issueSummary(issue, events, references, graph) {
   const specApproval = spec === undefined ? undefined : approvalLine(spec);
   if (issue.priority === undefined)
     throw new Error("Dispatch issue is missing priority");
+  if (issue.assignee === undefined)
+    throw new Error("Dispatch issue is missing assignee");
   return [
     `Title: ${issue.title}`,
     `Key: ${issue.key}`,
     `Status: ${issue.status}`,
+    `Assignee: ${issue.assignee ?? "unassigned"}`,
     ...issue.priority === null ? [] : [`Priority: P${issue.priority}`],
     `Labels: ${issue.labels.length === 0 ? "none" : issue.labels.join(", ")}`,
     `Route: ${issue.route ?? "none"}`,
@@ -15890,6 +15904,18 @@ async function executeDispatchTool(input) {
     const response = await client.openAsks(sessionId);
     return { text: formatOpenAsksSummary(response, configUrl), details: { ...response } };
   }
+  if (input.tool === "dispatch_whoami") {
+    const sessionId = input.sessionId?.trim();
+    if (!sessionId)
+      throw new Error("host session id is required for dispatch_whoami");
+    const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
+    const identity = await client.whoami();
+    const owner = identity.kind === "agent" ? identity.owner : identity.login.toLowerCase();
+    return {
+      text: owner === null ? `Session ${sessionId} runs under the shared token: no owner, so issues you create without an assignee are unassigned (or inherit their parent's).` : `Session ${sessionId} acts for ${owner}: issues you create without an assignee are assigned to ${owner}.`,
+      details: { session: sessionId, owner }
+    };
+  }
   const args = parsed.success ? parsed.data : ownerArguments.args;
   const actor = toolActor(await resolveOrigin(env, exec, input.cwd), input);
   const client = new DispatchClient(configUrl, configToken, fetchImpl, input.signal);
@@ -15916,6 +15942,7 @@ async function executeDispatchTool(input) {
       const force = optionalBoolean(args, "force");
       const spec = optionalString(args, "spec");
       const priority = optionalNumber(args, "priority");
+      const assignee = optionalString(args, "assignee");
       const labels = args.labels;
       try {
         const created = await client.issue({
@@ -15926,6 +15953,7 @@ async function executeDispatchTool(input) {
           ...force === undefined ? {} : { force },
           ...spec === undefined ? {} : { spec },
           ...priority === undefined ? {} : { priority },
+          ...assignee === undefined ? {} : { assignee },
           ...Array.isArray(labels) ? { labels } : {},
           actor
         });

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -90,13 +90,21 @@ exactly one owner to every owner-scoped tool: `issue` for an issue, or `project`
 [References](#references) for the resulting ref shape). On first use, an external issue reference creates its native issue in the
 project configured for that repository in Dispatch Settings, then falls back to `DISPATCH_DEFAULT_PROJECT`.
 
-Issue reads include `rank`, the server-owned ordering key used by project boards; reorder through `PATCH /api/v1/issues/{key}` with neighboring issue keys. They also include nullable coarse priority (`P0` highest through `P3` lowest).
+Issue reads include `rank`, the server-owned ordering key used by project boards; reorder through `PATCH /api/v1/issues/{key}` with neighboring issue keys. They also include nullable coarse priority (`P0` highest through `P3` lowest) and `assignee`: the lowercase GitHub login of the human who answers the issue's asks, or `null` when nobody holds it. `dispatch_read` of an issue prints it as `Assignee: <login>` or `Assignee: unassigned`.
+
+### Who answers an ask
+
+An ask goes to the issue's assignee: their Inbox opens on **Mine**, which lists asks on the issues they hold plus an Unassigned band; an ask on an unassigned issue waits in that band for someone to take it. Find out who Dispatch takes you for with:
+```ts
+dispatch_whoami({})
+```
+It returns `details` `{ session, owner }`: `owner` is the lowercase login of the human whose personal token you run under, or `null` under the shared token. An issue you create without `assignee` goes to your owner; under the shared token it inherits its parent's assignee, or stays unassigned without a parent. If an issue you are asking on is unassigned and the answer matters, assign it to your owner (`PATCH /api/v1/issues/{key}` with `{"assignee": "<login>"}`; any authenticated caller may reassign, and an unlisted login is refused with `ASSIGNEE_NOT_ALLOWED`) or name in the question who should answer it. Never reassign an issue a human holds to get an answer faster: that is the human's call.
 
 Architects create newly tracked child work with:
 ```ts
-dispatch_issue({ project, title, parent?, external?, spec?, force?, labels?: string[], priority?: 0 | 1 | 2 | 3 })
+dispatch_issue({ project, title, parent?, external?, spec?, force?, labels?: string[], priority?: 0 | 1 | 2 | 3, assignee?: string })
 ```
-`labels` are optional initial labels: Dispatch trims them, preserves their case, and removes case-insensitive duplicates. Set `priority` on creation only when the human's intent makes the bucket clear; otherwise priority remains the human's decision. It returns
+`labels` are optional initial labels: Dispatch trims them, preserves their case, and removes case-insensitive duplicates. Set `priority` on creation only when the human's intent makes the bucket clear; otherwise priority remains the human's decision. Set `assignee` (a GitHub login on the sign-in allowlist) only when the human said who owns the work; otherwise the default above applies, so a child inherits its parent's assignee. It returns
 `details` `{ issue }`; creating an issue does not subscribe you to it (see [Following](#following)). Use `dispatch_issue` only to create an issue; never use it to park a question. When `spec` is supplied,
 follow [Writing a spec](#writing-a-spec).
 
@@ -367,7 +375,9 @@ say what you did in a `reply_to` first if the thread needs it. The server lets a
 resolve only threads you opened or were asked to close; reopening a resolved thread is human-only (from the dashboard), though your
 reply to it reopens it. Asks are closed with `dispatch_resolve_ask` instead.
 
-Propose an exact replacement instead of describing it:
+An exact replacement for document text is a suggestion (`dispatch_suggest`), never a comment; a
+comment is for a question or a note the human answers in words. A human accepts a suggestion with
+one click and cannot accept a comment, so propose the replacement instead of describing it:
 
 ```ts
 dispatch_suggest({ issue?, project?, artifact, ref?, quote, replace_with, body?, occurrence? })

package/skills/legion-architect/SKILL.md

@@ -75,7 +75,10 @@ exercise a criterion end to end, building that path is a child issue of this tre
   the role-token `<project>` (the daemon's own project, e.g. `acme`), a different string. A
   root session has `LEGION_TREE == LEGION_ISSUE`. The daemon establishes the sub-issue
   relationship from `parent`. Keep the returned issue keys in ordered waves; a child is
-  inert until released.
+  inert until released. Do not pass `assignee`: the default keeps the tree's questions in one
+  Inbox — under the shared token a child inherits its parent's assignee (the human who
+  answers the tree's asks); under a personal token it goes to that token's owner, whom
+  `dispatch_whoami` names. Set it only when a human told you a specific person owns that child.
 
 Specifications written into Dispatch follow [`skills/dispatch`'s Writing a spec](../dispatch/SKILL.md#writing-a-spec).
 Wave releases, child closures, and your own status are visible from the issue tree and the

package/skills/legion-controller/SKILL.md

@@ -107,6 +107,9 @@ override a Sami ruling quoted here.
 1. Read `legion state --json`, then inspect the reported Dispatch issue with `dispatch_read`.
    Verify the issue is in this project, is eligible for a root process, and whether it
    has pre-existing children. Dispatch and daemon state, not the wake text, decide triage.
+   Note the `Assignee:` line: that human answers the tree's asks, and their Inbox opens on
+   the issues they hold. Never reassign during triage — who holds an issue is the humans'
+   decision, made from the issue header.
 2. If it should run now, admit the root issue:
 
    ```text
@@ -123,6 +126,11 @@ override a Sami ruling quoted here.
    (or `icebox` for longer-term deferral). Dispatch status is the durable record;
    there is no separate marker to maintain. Do not triage a system-created child as a root
    issue.
+4. When you post a triage note (a `dispatch_comment` on the issue saying what you decided and
+   why), name who will be asked: `Assigned to <login>, who will get this tree's questions`,
+   or, when the `Assignee:` line says `unassigned`, `Unassigned — nobody's Inbox shows this
+   tree's questions until someone takes it from the issue header (Assignee, beside Priority)`.
+   An unassigned root still runs; the architect's asks wait in every Inbox's Unassigned band.
 
 ## Backlog eligibility