@sjawhar/opencode-legion-envoy 8.5.1 → 8.6.0

package/dist/dispatch.js

@@ -16577,14 +16577,14 @@ function toolSchema(tool) {
   toolSchemas.set(tool, schema);
   return schema;
 }
-async function resolveOwnerArguments(tool, input, cwd, env, exec, serverUrl, problems) {
+async function resolveOwnerArguments(tool, input, cwd, env, exec, dashboardUrls, problems) {
   if (issueFreeTools[tool] === true)
     return { args: input, ref: null, owner: null };
   const refArgument = input.ref;
   let ref = null;
   let args = input;
   if (typeof refArgument === "string") {
-    const refText = dispatchRefFromUrl(refArgument, serverUrl) ?? refArgument;
+    const refText = dashboardUrls.map((dashboard) => dispatchRefFromUrl(refArgument, dashboard)).find((ref2) => ref2 !== undefined) ?? refArgument;
     if (refText !== refArgument)
       args = { ...input, ref: refText };
     const agentArtifact = parseAgentArtifactRef(refText);
@@ -16846,7 +16846,7 @@ function progressText(progress, sep) {
   }
   return parts.join(sep);
 }
-function issueSummary(issue2, events, references, graph, titles) {
+function issueSummary(issue2, events, references, graph, linkBase, titles) {
   const asks = issue2.open_asks;
   const spec = issue2.artifacts?.find((artifact) => artifact.primary);
   const specApproval = spec === undefined ? undefined : approvalLine(spec);
@@ -16864,6 +16864,7 @@ function issueSummary(issue2, events, references, graph, titles) {
   return [
     `Title: ${issue2.title}`,
     `Key: ${issue2.key}`,
+    `Link: ${new URL(`/issues/${encodeURIComponent(issue2.key)}`, linkBase).toString()}`,
     `Status: ${issue2.status}`,
     `Assignee: ${issue2.assignee ?? "unassigned"}`,
     `Claimed by: ${issue2.claim === null ? "nobody" : claimText(issue2.claim, titles)}`,
@@ -17328,6 +17329,7 @@ function withAccount(error48, account) {
 }
 async function executeDispatchTool(input) {
   const { url: configUrl, token: configToken } = input.config;
+  const linkBase = input.config.publicUrl ?? configUrl;
   const baseFetch = input.fetchImpl ?? fetch;
   const fetchImpl = Object.assign(async (...args2) => {
     try {
@@ -17342,7 +17344,7 @@ async function executeDispatchTool(input) {
   const env = input.env ?? process.env;
   const exec = input.exec ?? defaultExec;
   const problems = [];
-  const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec, configUrl, problems);
+  const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec, input.config.publicUrl === undefined ? [configUrl] : [configUrl, input.config.publicUrl], problems);
   const ownerMissing = issueFreeTools[input.tool] !== true && ownerArguments.owner === null;
   const schema = toolSchema(input.tool);
   const parsed = schema.safeParse(ownerArguments.args, { reportInput: true });
@@ -17360,13 +17362,13 @@ async function executeDispatchTool(input) {
     const project = optionalString(ownerArguments.args, "project");
     if (project !== undefined) {
       const response2 = await client2.openAsksForProject(project);
-      return { text: formatOpenAsksSummary(response2, configUrl), details: { ...response2 } };
+      return { text: formatOpenAsksSummary(response2, linkBase), details: { ...response2 } };
     }
     const sessionId = input.sessionId?.trim();
     if (!sessionId)
       throw new Error("host session id is required for dispatch open-asks");
     const response = await client2.openAsks(sessionId);
-    return { text: formatOpenAsksSummary(response, configUrl), details: { ...response } };
+    return { text: formatOpenAsksSummary(response, linkBase), details: { ...response } };
   }
   if (input.tool === "dispatch_whoami") {
     const sessionId = input.sessionId?.trim();
@@ -17448,11 +17450,13 @@ async function executeDispatchTool(input) {
             isPrimarySpec: spec !== undefined
           }),
           ...componentGuidance === undefined ? [] : [componentGuidance],
-          ...renderSuggestions(created.advice?.suggestions, configUrl)
+          ...renderSuggestions(created.advice?.suggestions, linkBase)
         ];
+        const href = new URL(`/issues/${encodeURIComponent(created.key)}`, linkBase).toString();
+        const assigned = created.assignee === undefined ? "" : created.assignee === null ? "; unassigned" : `; assigned to ${created.assignee}`;
         return {
           text: [
-            `Created ${created.key}: ${created.title} ${notSubscribed(issueTopic(created.key))}`,
+            `Created ${created.key}: ${created.title} \u2192 ${href}${assigned} ${notSubscribed(issueTopic(created.key))}`,
             ...adviceLines
           ].join(`
 `),
@@ -17470,7 +17474,7 @@ async function executeDispatchTool(input) {
           text: [
             `Not created: "${title}" looks like a duplicate.`,
             ...candidates.map((candidate) => {
-              const href = new URL(candidate.href, configUrl).toString();
+              const href = new URL(candidate.href, linkBase).toString();
               return `${candidate.key} [${candidate.status}] ${candidate.title} \u2192 ${href}`;
             }),
             "Reference the existing issue, or run dispatch issue again with --force after reading it."
@@ -17611,7 +17615,7 @@ async function executeDispatchTool(input) {
         ...limit === undefined ? {} : { limit },
         ...offset === undefined ? {} : { offset }
       });
-      return searchAnswer(search, query, offset, configUrl);
+      return searchAnswer(search, query, offset, linkBase);
     }
     case "dispatch_issues": {
       const project = stringArg(args, "project");
@@ -17675,7 +17679,7 @@ async function executeDispatchTool(input) {
       } catch (error48) {
         throw refusalWithCode(error48);
       }
-      const href = new URL(`/projects/${encodeURIComponent(project.key)}`, configUrl).toString();
+      const href = new URL(`/projects/${encodeURIComponent(project.key)}`, linkBase).toString();
       return {
         text: `Created project ${project.key} (${project.name}) at ${project.created_at}: ${href}`,
         details: { project: project.key, name: project.name, created_at: project.created_at }
@@ -17768,7 +17772,7 @@ async function executeDispatchTool(input) {
       const askOwner = ask.issue_key !== null ? issueTopic(ask.issue_key) : resolved === undefined ? issueTopic(issue2()) : documentTopic(resolved.artifact);
       const adviceLines = [
         ...renderAdvice(input.tool, askOwner.label, ask.advice, {}),
-        ...renderSuggestions(ask.advice?.suggestions, configUrl)
+        ...renderSuggestions(ask.advice?.suggestions, linkBase)
       ];
       return {
         text: [
@@ -18249,7 +18253,7 @@ ${trailer.join(`
         ])
       ]);
       return {
-        text: issueSummary(read.issue, read.events, references, [...pictures2.lines, ...graph], titles),
+        text: issueSummary(read.issue, read.events, references, [...pictures2.lines, ...graph], linkBase, titles),
         details: { issue: read.issue.key },
         ...showImages(pictures2)
       };
@@ -18987,7 +18991,17 @@ function dispatchSettings(env, config2) {
     }
     const url2 = (explicitUrl ?? (source.kind === "file" ? source.server : own.serverUrl ?? DEFAULT_SERVER_URL)).replace(/\/+$/, "");
     const token = source.kind === "variable" ? source.token : fileBearer(source, url2, "DISPATCH", env);
-    return { enabled: true, url: url2, token };
+    const publicUrl = nonEmpty(env.DISPATCH_PUBLIC_URL);
+    const publicParsed = publicUrl === undefined ? undefined : httpUrl2(publicUrl);
+    if (publicUrl !== undefined && (publicParsed === undefined || publicParsed.port === "0")) {
+      return offWithError("DISPATCH_PUBLIC_URL must be an http or https URL");
+    }
+    return {
+      enabled: true,
+      url: url2,
+      token,
+      ...publicUrl === undefined ? {} : { publicUrl: publicUrl.replace(/\/+$/, "") }
+    };
   } catch (error48) {
     return offWithError(messageFor(error48));
   }

package/dist/src/server.js

@@ -14317,6 +14317,8 @@ var DISPATCH_DOCUMENT_TOPIC_PREFIX = `${DISPATCH_TOPIC_PREFIX}document.`;
 function agentSubject(session) {
   return `${AGENT_TOPIC_PREFIX}${session}`;
 }
+// ../contracts/src/slack.ts
+var SLACK_POST_TEXT_MAX = 4000;
 // ../contracts/src/tool-schema.ts
 function overCapMessage(length, max) {
   return `is ${length - max} characters over the ${max}-character limit (${length}/${max})`;
@@ -14925,7 +14927,17 @@ function dispatchSettings(env, config2) {
     }
     const url2 = (explicitUrl ?? (source.kind === "file" ? source.server : own.serverUrl ?? DEFAULT_SERVER_URL)).replace(/\/+$/, "");
     const token = source.kind === "variable" ? source.token : fileBearer(source, url2, "DISPATCH", env);
-    return { enabled: true, url: url2, token };
+    const publicUrl = nonEmpty(env.DISPATCH_PUBLIC_URL);
+    const publicParsed = publicUrl === undefined ? undefined : httpUrl2(publicUrl);
+    if (publicUrl !== undefined && (publicParsed === undefined || publicParsed.port === "0")) {
+      return offWithError("DISPATCH_PUBLIC_URL must be an http or https URL");
+    }
+    return {
+      enabled: true,
+      url: url2,
+      token,
+      ...publicUrl === undefined ? {} : { publicUrl: publicUrl.replace(/\/+$/, "") }
+    };
   } catch (error48) {
     return offWithError(messageFor(error48));
   }
@@ -15129,7 +15141,8 @@ var EnvoyToolOperation = {
   setRole: "setRole",
   getRole: "getRole",
   whoami: "whoami",
-  listSessions: "listSessions"
+  listSessions: "listSessions",
+  slackPost: "slackPost"
 };
 var envoyToolSpecs = [
   {
@@ -15200,6 +15213,16 @@ var envoyToolSpecs = [
       title: schema.string().optional()
     }),
     operation: EnvoyToolOperation.listSessions
+  },
+  {
+    name: "slack_post",
+    description: "Reply in a Slack thread as the Legion Slack app, with the bot token the secrets broker grants this session (LEGION_SLACK_BOT_TOKEN); the session never holds it. channel is the Slack channel id (a mention's channel_id); thread_ts is the thread's root ts: the mention's thread_ts, or its own ts when it has none. Answers the new message's ts. A refusal carries Slack's own error code (not_in_channel: the app is not in that channel) or the broker's state (waiting for approval, denied). Sent once and never retried: after 'Slack did not answer' the reply may already be in the thread, so do not post it again.",
+    arguments: (schema) => ({
+      channel: schema.string({ min: 1 }).describe("Slack channel id, such as C0123ABCD."),
+      thread_ts: schema.string({ min: 1 }).describe("The thread's root ts, which keeps the reply in the mention's thread."),
+      text: schema.string({ min: 1, max: SLACK_POST_TEXT_MAX }).describe(`The reply, in Slack mrkdwn, at most ${SLACK_POST_TEXT_MAX} characters.`)
+    }),
+    operation: EnvoyToolOperation.slackPost
   }
 ];
 var envoyToolSchemas = new Map;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "8.5.1",
+  "version": "8.6.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/src/server.js",

package/skills/dispatch/references/reading.md

@@ -57,8 +57,9 @@ dispatch://PROJECT/artifact/<document-ref>/comment/<id>
 ```
 
 A bare UUID or `KEY#seq` is not a reference; the `dispatch://` form is what Dispatch links and records. `dispatch read` also
-accepts the dashboard URL of an issue, spec, artifact, ask, comment, or project document on the configured server (it maps to the
-`dispatch://` form above), and an ask or comment id may be a unique prefix of at least 8 hex characters; a message id is always the
+accepts the dashboard URL of an issue, spec, artifact, ask, comment, or project document on the configured server, or on its public
+dashboard when `DISPATCH_PUBLIC_URL` names one (it maps to the `dispatch://` form above), and an issue's read names its page
+(`Link:`, on that public dashboard when there is one), the link to hand a person. An ask or comment id may be a unique prefix of at least 8 hex characters; a message id is always the
 full uuid. A non-uuid id on `GET /asks/{id}`, `/comments/{id}`, or `/issues/{key}/messages/{id}` is a 400 `ASK_ID_INPUT` /
 `COMMENT_ID_INPUT` / `MESSAGE_ID_INPUT`, never a 500.
 

package/skills/envoy/SKILL.md

@@ -237,6 +237,12 @@ envoy_subscribe([
 This follows every message and mention in one thread. Channel-level topics end in `.message` or
 `.mention`; thread timestamps replace dots with underscores.
 
+Reply in a thread with `slack_post(channel=<channel_id>, thread_ts=<the message's thread_ts, or
+its ts>, text=…)`, which posts as the Legion Slack app with the bot token the secrets broker grants
+the session (`LEGION_SLACK_BOT_TOKEN`). A refusal carries Slack's own error code, or the broker's
+state when it has not granted the token. The post is sent once; when the answer is that Slack did
+not answer, the reply may already be there, so do not post it again.
+
 ## Ghost Wispr
 
 Ghost Wispr topics are `notifications.ghostwispr.<session>.<kind>`, where `kind` is

package/skills/legion-controller/SKILL.md

@@ -404,7 +404,8 @@ priority first, then board rank ([Keeping the slots full](#keeping-the-slots-ful
 | `todo on <KEY>` from the Go daemon (payload `{kind: "todo"}`) | an issue not handed to Legion that changed while in `todo` and a slot stood free, sent half a minute later | Verify a free slot, then walk the whole `todo` list ([Keeping the slots full](#keeping-the-slots-full-go-daemon)) |
 | `tick on <PROJECT>` from the Go daemon (payload `{kind: "tick", openCapabilities?: [<name>, …]}`) | the project key; the daemon's periodic wake, whatever the slots; `openCapabilities` names the deployment capabilities with no decision, each with its detail and `capabilities.decided.<name>` line under `capabilities` in `read_state`, and the live capabilities a running session's check failed, each with the detail naming the session (pod or pane), role, issue and fact, and no `configLine` | Recheck the trees waiting on a claim, then walk if a slot is free — a gap never stops the walk; post the day's report if this is the day's first turn, naming each open capability in it (the operator closes or decides a deployment row; the operator or the issue's architect fixes a live row's session; you take no other action) |
 | Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; the owning architect writes an issue-design decision as a decision block and opens `dispatch ask` only for a human to-do |
-| Mention | Slack/GitHub PR @mention text | Answer, or route to the owning issue's architect role |
+| Mention | GitHub PR @mention text | Answer, or route to the owning issue's architect role |
+| Slack mention (`from: slack`) | the mention's `channel_id`, `user_id`, `text`, `ts`, `thread_ts` | Nothing when your `Slack channels:` line does not name its `channel_id`; otherwise answer in its thread with `slack_post`: a state question from `read_state`, a work request filed as a Dispatch issue, an architect's question routed to that architect ([Slack mentions](skill://legion-controller/references/slack-mentions.md)) |
 | `held on <KEY>` from the Go daemon (payload `{kind: "held", phase, role?, reason?}`) | the held issue, the phase it left, and the role whose claim failed, or `reason: "escalated"` | Verify the hold in `read_state` (the issue's phase is `held`). Without `reason`, a phase worker's launches or prompts ran out and the tree's architect decides retry or escalate: no action. With `reason: "escalated"` (on the record, `issues.<KEY>.holdReason` is `escalated`), the architect sent it to you: handle it as an architect escalation below. Parking the tree is `set_status` of the root to `backlog`; setting the root back to `todo` later re-admits it as a new generation, which starts again from its architect |
 | `worker-died on <KEY>` from the Go daemon with `role: "architect"` | the tree root whose architect's claim failed, and the phase the root was in | The tree's architect ran out of launches or prompts and the daemon relaunches nothing; every other notice of the tree goes to that architect, so nobody inside the tree can act. Verify in `read_state` (`issues.<KEY>.architect.state` is `failed`); if the root's phase is `done`, the tree is already parked: no action. Otherwise re-admit the tree (`set_status` of the root to `backlog`, then to `todo`: a new generation, whose architect starts again with fresh budgets) or leave it parked and say why on the issue |
 | Direct user message | — | Always first |
@@ -482,12 +483,13 @@ judgments.
 
 ## Mentions
 
-Read the mention and its artifact. Answer it when it asks the controller for triage or
-human-facing information. A human asking how to let a root proceed past its design gate
-approves the root issue's spec document in Dispatch — the `Approve` control in the document's
-header, or the approval question the architect's request opened in the Inbox. The controller
-never opens a gate and there is no operator command for it; a project that does not want the
-gate at all runs `gates.design: off` in its `legion.yaml`. Otherwise resolve the authoritative
-owning architect role and route the verified context with `envoy_publish`. Do not route raw
-event traffic or invent a role token from a partial issue reference.
+Read the mention and its artifact; a Slack mention follows [Slack
+mentions](skill://legion-controller/references/slack-mentions.md). Answer it when it asks the
+controller for triage or human-facing information. A human asking how to let a root proceed past
+its design gate approves the root issue's spec document in Dispatch — the `Approve` control in the
+document's header, or the approval question the architect's request opened in the Inbox. The
+controller never opens a gate and there is no operator command for it; a project that does not
+want the gate at all runs `gates.design: off` in its `legion.yaml`. Otherwise resolve the
+authoritative owning architect role and route the verified context with `envoy_publish`. Do not
+route raw event traffic or invent a role token from a partial issue reference.
 

package/skills/legion-controller/references/slack-mentions.md

@@ -0,0 +1,94 @@
+# Slack mentions
+
+A person who mentions the Legion Slack app in one of the project's Slack channels is talking to
+you, and you answer in that thread. The `Slack channels:` line of your system prompt names each
+channel `legion.yaml` gives the project (`projects.<KEY>.slack_channels`). Only the controller the
+daemon launches has one: the Slack bot token is the Legion daemon service's, which the secrets
+broker grants to that service's own pods alone. With no such line the project has no channel, and
+nothing here applies.
+
+## Your session subscribes for you
+
+Your session hears each listed channel's mentions by itself, on
+`notifications.slack.*.<channel>.mention`, for as long as it holds the controller role: a resumed or
+relaunched session hears the channels its launch names and no others, and drops every Slack topic an
+earlier session subscribed to by hand. Never `envoy_subscribe` a Slack topic yourself.
+
+A delivery from Slack whose `channel_id` the line does not name is not yours: do nothing with it.
+
+A mention published while no controller ran never arrives: Envoy hands a session no copy of an
+event from before it subscribed. Nothing tells you about one, so there is nothing to catch up. When
+the project's `slack_channels` change, the daemon relaunches you into this session with the new
+line.
+
+## What a mention carries
+
+The delivery's `message` holds Slack's fields: `channel_id`, `user_id` (a Slack user id such as
+`U0123ABCD`), `text` (the mention itself appears in it as `<@U…>`, the app's own id), `ts` (the
+mention's own timestamp), `thread_ts` (the thread's root, only when the mention was posted inside a
+thread), and `bot_id` and `bot_name` when a bot posted it.
+
+## Answer in the thread
+
+Every answer is one `slack_post` call:
+
+- `channel` is the mention's `channel_id`.
+- `thread_ts` is the mention's `thread_ts`, or its `ts` when it has none. Either keeps the reply in
+  the thread the mention opened or joined, never at the channel's top level.
+- `text` is what you say, at most 4,000 characters, written as `skill://dispatch`'s "Writing for
+  the human" says. Address the author as `<@user_id>` (by `bot_name` when a bot posted the mention
+  with no `user_id`) and give every issue as its key, its title and its Dispatch link exactly as
+  `dispatch` printed it (the `Link:` line of `dispatch read`, the link on a `Created` line or a
+  search hit): it points at Dispatch's dashboard, and `slack_post` refuses a reply linking an
+  address inside the cluster. Never build a link yourself. Say only what Dispatch shows: an issue's
+  assignee is the one `dispatch` names, never one you assume.
+
+`slack_post` is sent once and never retried. When it answers that Slack did not answer, the reply
+may already be in the thread: do not post it again. When it answers with Slack's refusal, the
+reply is not posted: `not_in_channel` means the app has not been added to that channel, which only
+a person in the workspace can fix, so say so in your next report rather than retrying. When it
+answers that the secrets broker has not granted `LEGION_SLACK_BOT_TOKEN` (its request waits for
+approval, or was denied), nothing was posted and no reply can be until the operator stores the
+token with owner `legion-daemon` and tier `agent`: name the error in your next report.
+
+## Decide what the person wants
+
+Read the mention's `text`. When it names an issue key, read the issue with `dispatch read` before
+answering. Then take the first of these that fits.
+
+- **A question about state.** "What is Legion working on?", "Where is ACME-12?", "Why is it held?"
+  Answer from `read_state` and Dispatch as they stand now, never from memory: each issue's
+  `issues.<KEY>.phase`, its pull request, `admission.active` and `admission.waiting`. Say what you
+  read, not what you infer.
+- **A request for work.** Someone wants a change made, a bug fixed, something investigated. Search
+  first (`skill://dispatch-first`): when an open issue already tracks it, reply with that issue and
+  file nothing. Otherwise file one issue in the project:
+
+  ```text
+  dispatch issue --project <PROJECT> --title '<the request, as a title>' --spec-file - <<'EOF'
+  ## Summary
+
+  <what the person asked for, in your words, and why if they said>
+
+  Asked in Slack by <@user_id> in channel <channel_id>, message <ts>.
+  EOF
+  ```
+
+  Add `--label legion` only when the person asks Legion to do the work ("Legion, fix…", "can
+  Legion take…"); a request for someone to look at something, or one that does not say who, gets
+  no label and waits for a person to hand it over. Never label a request outside the scope the
+  deployment instructions state. Reply with the new issue's key, its title, the link and assignee
+  the `Created` line names (Dispatch assigns the issue to your token's owner when you name nobody),
+  and whether Legion will take it.
+- **Something an issue's architect owns.** A question about a tree's design, a change of direction,
+  a decision only the tree's architect can make about an issue Legion runs. Find the tree: follow
+  `Links:` up through each `child_of` parent with `dispatch read` until you reach the issue
+  `read_state` records with an `architect`. When `issues.<ROOT>.architect.locator.claim` is there,
+  `envoy_publish` the person's words to `notifications.role.` followed by it, with the channel id
+  and `thread_ts` you reply on, and reply in the thread that you passed it to the architect that
+  owns `<ROOT>`, which answers on the issue. When the architect is not running (no locator), say
+  that in the thread instead and what `read_state` shows for the tree. Never invent a role token.
+- **Anything else** (a greeting, a question about Legion itself): answer it briefly in the thread.
+
+A request to approve a design is answered as the skill's "Mentions" section says: a person
+approves the spec in Dispatch, and you never open a gate.