@sjawhar/opencode-legion-envoy 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/opencode-legion-envoy",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "main": "dist/src/server.js",
   "exports": {
@@ -25,7 +25,7 @@
     "skills"
   ],
   "scripts": {
-    "build": "bun build src/server.ts bin/dispatch-mcp-shim.ts --outdir dist --target bun --format esm --external '@opencode-ai/*'",
+    "build": "bun build src/server.ts --root . --outdir dist --target bun --format esm --external '@opencode-ai/*'",
     "prepack": "bun run build && rm -rf skills && cp -r ../../skills skills",
     "typecheck": "bunx tsc --noEmit",
     "test": "bun test",
@@ -45,6 +45,7 @@
     "@legion/envoy-client": "0.1.0",
     "@types/bun": "latest",
     "solid-js": "^1.9.0",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "zod": "^4.1.8"
   }
 }

package/skills/dispatch/SKILL.md

@@ -6,8 +6,11 @@ description: Use when you need a human decision from Sami or the user — asking
 # Dispatch
 
 `dispatch` turns a question into a durable, dashboard-visible GitHub-issue thread instead
-of a line buried in a transcript. Use it any time you would otherwise leave a question for
-a human to notice on their own.
+of a line buried in a transcript. A thread is **one decision, held as a conversation**: it
+opens with your question, the human replies, and if the reply changes the question you ask
+again on the same thread. It closes when the decision is settled, not when the first reply
+lands. Use it any time you would otherwise leave a question for a human to notice on their
+own.
 
 ## When to dispatch
 
@@ -28,67 +31,215 @@ a human to notice on their own.
 - Anything you can resolve yourself from tools or repo context. Dispatch is for genuine
   human decisions, not a substitute for research.
 
+## Writing for the reader
+
+The reader has not seen your transcript. They are looking at a card on a dashboard between
+other things, and they will answer the question you wrote, not the one you meant.
+
+- **No nouns you coined this session.** No "the list above", "those items", "lane B",
+  "the eval-set thing". No internal identifiers — eval-set ids, lane names, hashes,
+  session ids — unless the question is about them. Expand every identifier on first use.
+  GitHub references may be bare: `#482`, `acme-org/example-repo#17`, or a URL — the
+  dashboard unfurls them into their titles.
+- **Structure over paragraphs.** `context` is at most three short paragraphs or a bullet
+  list, one idea each: what you are doing, what you found, why you are stuck. `question`
+  is a list: current state → desired state → your recommendation and why; the options
+  themselves go in `ask`, each tradeoff as its `description`. Don't just describe the
+  fork — say which branch you'd take and why.
+- **Options are buttons.** If you are offering choices, put them in `ask`; never enumerate
+  them in prose. A human answers a button in one click and the answer arrives structured;
+  a choice buried in a paragraph arrives as a sentence you have to interpret.
+- **Length caps.** `context` is at most 1200 characters, `question` at most 800. The
+  service refuses a longer call before anything reaches GitHub, naming the field and the
+  limit (`context is 1450 characters; the limit is 1200`); nothing is truncated. When you
+  hit a cap: move the choices into `ask`, cut background the reader does not need to
+  decide, and if there really are two decisions, open two threads.
+
+### Before / after
+
+A real thread, as first written — one block, coined nouns, options in prose:
+
+```
+subject:  "e2e submitter"
+context:  "So I've been going through the e2e harness like we discussed and the submitter
+           identity thing from earlier is still broken because the fixture in lane B uses
+           the shared bot account which means the assertions in eval-set 7f3a can't tell
+           who submitted, and the thing I mentioned about the env var not being set in CI
+           is also true so basically the list above doesn't apply until we pick one, and I
+           looked at how the other repo does it and they hardcode it which is fine for them
+           but not us, also the token minting issue is related but separate."
+question: "should I add E2E_SUBMITTER_EMAIL or use the bot or something else? I think
+           probably the env var but not sure, or maybe the hardcode thing, or the third
+           option where the harness reads it from git config. Let me know."
+```
+
+The same decision, written for the reader:
+
+```
+subject:  "E2E harness: which identity submits test PRs?"
+context:  "- The end-to-end test harness (acme-org/example-repo#17158) submits PRs as the
+             shared bot account, so a run cannot tell test submissions apart from real ones.
+           - CI sets no submitter identity today; the harness has no setting for one."
+question: "- Current: every test PR is authored by the shared bot.
+           - Desired: each run's PRs carry an identity that marks them as test submissions.
+           - Recommendation: a dedicated identity from one CI environment variable —
+             smallest change, no per-machine setup."
+ask:      [{ header: "Test submitter identity",
+             question: "Which identity should the harness use?",
+             options: [
+               { label: "Env var E2E_SUBMITTER_EMAIL", description: "one CI variable; the harness reads it" },
+               { label: "Shared bot (status quo)",      description: "no change; runs stay indistinguishable" },
+               { label: "Read from git config",         description: "per-machine setup; drifts" } ] }]
+```
+
 ## How
 
+### Opening a thread
+
 ```
 dispatch({
   subject:  "Postgres migration: run online or take a maintenance window?",
-  context:  "Implementing the users-table index migration for issue #482. The table has
-             40M rows; a plain CREATE INDEX locks writes for ~6 minutes in the staging
-             timing test I just ran.",
-  question: "Current: no online-migration tooling wired into this repo's deploy pipeline.
-             Desired: index added without a customer-visible write outage.
-             Option A — CREATE INDEX CONCURRENTLY, no lock, ~25 min, can't run inside a
-             transaction (rules out the existing migration runner without a change).
-             Option B — take a 6-minute maintenance window during the 03:00 UTC low-traffic
-             slot, keep the existing runner unchanged.
-             Recommendation: B — smaller blast radius, no migration-runner change, and the
-             window is well inside the existing maintenance SLA.",
+  context:  "- Implementing the users-table index migration for #482.
+             - The table has 40M rows; a plain CREATE INDEX locks writes for ~6 minutes
+               in the staging timing test I just ran.",
+  question: "- Current: no online-migration tooling in this repo's deploy pipeline.
+             - Desired: index added without a customer-visible write outage.
+             - Recommendation: the maintenance window — smaller blast radius, no
+               migration-runner change, inside the existing SLA.",
+  ask:      [{ header: "Approach", question: "Which way?",
+               options: [
+                 { label: "CREATE INDEX CONCURRENTLY", description: "no lock, ~25 min, needs a migration-runner change" },
+                 { label: "6-minute window at 03:00 UTC", description: "runner unchanged, brief write outage" } ] }],
   urgency:  "med"
 })
 ```
 
 - `subject`: one line, the decision — this is the issue title and the dashboard row.
-- `context` (required): what you are doing, what you found, why you are stuck. **The
-  reader has not seen your transcript** — never write "the list above," "those items," or
-  anything that assumes shared context. State it fresh.
-- `question` (required): current state → desired state → proposed change, then options
-  with tradeoffs, then your own recommendation. Don't just describe the fork — say which
-  branch you'd take and why.
-- `ask` (optional): a list of `{ question, header?, options: [{ label, description? }] }`
-  when the decision is a discrete set of choices. These render as buttons on the dashboard
-  — use this instead of asking the human to type a free-text answer when the answer really
-  is "pick one of N."
-- `urgency` (optional, default `med`):
-  - `low` — whenever it's convenient, no deadline pressure.
-  - `med` — needed today.
-  - `high` — blocking something that will stall soon if unanswered.
-  - `blocking` — you cannot proceed at all right now.
-- `repo` (optional): only pass this to target a **different** repo than your current
-  working directory's GitHub remote. The shim fills `repo` from cwd automatically —
-  omit it in the common case.
-- `parent` (optional): only set this when a real issue already exists to attach to —
-  `<n>` for an issue in the resolved repo, or `owner/name#<n>` to point at a specific
-  issue in another repo. For Legion roles, `parent` is the root issue you're working
-  under. Omitting it creates a standalone top-level thread; don't invent a parent that
-  doesn't exist.
+- `context` (required, ≤ 1200 chars): what you are doing, what you found, why you are stuck.
+- `question` (required, ≤ 800 chars): current → desired → recommendation (options live in
+  `ask`).
+- `ask` (optional): a list of `{ question, header?, options: [{ label, description? }],
+  multiple?, custom? }`. These render as buttons, always with an "Other (specify)"
+  free-text field beside them (`custom` does not change this); a plain reply on the thread
+  is also possible but arrives unstructured.
+- `urgency` (optional, default `med`): `low` — whenever convenient; `med` — needed today;
+  `high` — something will stall soon; `blocking` — you cannot proceed at all right now.
+- `repo` (optional): only to target a **different** repo than your working directory's
+  GitHub remote; the tool fills it from the cwd otherwise.
+- `parent` (optional): only when a real issue exists to attach to — `<n>` in the resolved
+  repo or `owner/name#<n>` elsewhere; `owner/name#<n>#<commentId>` also appends a
+  breadcrumb to that comment. For Legion roles, `parent` is the root issue you're working
+  under. Omitting it creates a standalone thread; don't invent a parent.
+
+The tool returns `{"thread": N, "url": "..."}`; that URL is the durable record.
+
+### Continuing a thread
+
+When the reply changes the question — the human challenged the premise, ruled out your
+recommendation, or asked for a variant you had not offered — re-ask **on the same thread**:
+
+```
+dispatch({
+  thread:   "482",                      // or "owner/name#482"
+  context:  "- You ruled out the maintenance window: the 03:00 UTC slot is now used by
+               the nightly export.
+             - CONCURRENTLY needs the migration runner to run outside a transaction.",
+  question: "- Current: the runner wraps every migration in a transaction.
+             - Desired: this one index built online.
+             - Recommendation: a one-off flag on the runner for non-transactional
+               migrations, used only by this migration.",
+  ask:      [{ header: "Runner change", question: "Add the non-transactional flag?",
+               options: [{ label: "Yes, one-off flag" }, { label: "No, hand-run the index" }] }]
+})
+```
+
+- `thread` replaces `subject`; `urgency`, `repo`, and `parent` are not accepted with it.
+  The thread must be open and be a dispatch thread; otherwise the tool says so
+  (`#N is not a dispatch thread`, `#N is closed; open a new thread`).
+- Same decision → same thread. A genuinely new decision → a new thread, even if it came
+  up in the reply.
+- **Read a challenge as an answer.** "Why not the bot?" is not a request for more prose;
+  it is the human declining your framing. Say what you now know, then ask the narrowed
+  question with new options — unless the challenge itself decides ("Why not the bot? Just
+  use the bot."), in which case act on it and re-ask nothing. A follow-up carries your
+  session's identity, so the human sees which conversation is asking even after a handoff.
+- The tool returns `{"thread": N, "url": "...", "comment": "..."}`.
 
 ## After dispatching
 
 The reply arrives back in your own session as a steer — you do not fetch it. Keep every
 other non-blocked lane of work moving while you wait; a dispatch is not a reason to go
 idle. Never poll GitHub for the reply and never set up a watcher, cron, or retry loop to
-check on it — the delivery mechanism is already push-based. The issue URL returned by the
-tool (`{"thread": N, "url": "..."}`) is the durable record; you don't need to keep it
-anywhere else.
+check on it — the delivery mechanism is already push-based. Each answer names the question
+it answers, so a thread with two open questions delivers two steers.
 
 If the tool errors because it can't resolve a repo (cwd has no GitHub remote and no
-qualified `parent`), pass `repo=owner/name` explicitly and retry.
+qualified `parent` or `thread`), pass `repo=owner/name` (opening) or
+`thread=owner/name#<n>` (continuing) and retry.
 
 **Named risk:** a thread created in a repo where the Envoy GitHub App is not installed
 gets created successfully, but replies to it never route back to your session — you'll
-wait forever for a steer that can't arrive. Coverage is every repo under `sjawhar`, plus
-`acme-org/example-repo` and `acme-org/example-e2e` — the App is
-deliberately not installed org-wide. That list can change; to check a repo before relying
-on a reply, `gh api /repos/<owner>/<name>/installation` returns 200 when the App is
-installed there and 404 when it is not.
+wait forever for a steer that can't arrive. The App is installed per account and per repo,
+not org-wide, and coverage changes; before relying on a reply from a repo you have not
+dispatched to before, check it: `gh api /repos/<owner>/<name>/installation` returns 200 when
+the App is installed there and 404 when it is not.
+
+## Manual fallback: the marker format
+
+If the tool itself is unavailable, the dashboard still understands a hand-written turn.
+Every dispatch marker is an HTML comment at the very start of the body — invisible on
+GitHub — followed by a blank line and the readable text.
+
+A follow-up question, posted with `gh issue comment <n> --body-file <file>`:
+
+```
+<!-- dispatch:ask
+requestId: <16 lowercase hex chars, unique to this follow-up>
+ask:
+    - askId: <the same 16 chars>
+      question: <the question>
+      header: <short header>
+      options:
+        - label: <label>
+          description: <one line>
+-->
+
+## Context
+
+<context>
+
+## Question
+
+<question>
+```
+
+A new thread, posted with `gh issue create --label dispatch-thread --title "<subject>" --body-file <file>`:
+
+```
+<!-- dispatch:thread
+requestId: <16 lowercase hex chars>
+urgency: med
+ask:
+    - askId: <the same 16 chars>
+      question: <the question>
+      options:
+        - label: <label>
+-->
+
+**<subject>**
+
+## Context
+
+<context>
+
+## Question
+
+<question>
+```
+
+`ask` may be omitted when there are no buttons to offer. A second ask on the same turn has
+`askId: <requestId>.1`, a third `.2`. A hand-posted turn carries no `origin`, so the
+dashboard cannot say which session asked, and nothing subscribes your session to a
+hand-created thread — subscribe it yourself with `envoy_subscribe` to
+`notifications.github.<owner>.<name>.issue.<n>.>` or the reply never arrives. Prefer the
+tool.

package/src/server.ts

@@ -3,13 +3,20 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { agentSubject } from "@legion/contracts";
 import { envoyDefaultsFromEnvironment } from "@legion/envoy-client/defaults";
+import { executeDispatch } from "@legion/envoy-client/dispatch-call";
+import { resolveDispatchConfig } from "@legion/envoy-client/dispatch-config";
+import {
+  DISPATCH_ARGUMENTS,
+  DISPATCH_TOOL_DESCRIPTION,
+  DISPATCH_TOOL_NAME,
+  DISPATCH_URGENCIES,
+  parseDispatchCall,
+} from "@legion/envoy-client/dispatch-contract";
 import { dispatchSubscriptionTopic } from "@legion/envoy-client/dispatch-subscribe";
 import { machineID } from "@legion/envoy-client/machine";
 import { envoyToolSpecs } from "@legion/envoy-client/tool-contract";
 import { createEnvoyClient } from "@legion/envoy-client/transport";
 import { tool } from "@opencode-ai/plugin/tool";
-import { loadEnvoyConfig } from "./config";
-import { buildDispatchMcpEntry, injectEnvoyMcp } from "./dispatch-mcp";
 import { logger } from "./log";
 import { resolvePort } from "./port";
 
@@ -36,9 +43,40 @@ const [
   sessionsSpec,
 ] = envoyToolSpecs;
 
+// The dispatch tool's LLM-facing schema, built with OpenCode's own zod
+// (`tool.schema`): OpenCode converts plugin schemas with that instance, and a
+// schema from another zod build loses its checks and descriptions on the way.
+// It mirrors `dispatchToolShape` from the contract field for field — the test
+// suite compares the two as JSON Schema so they cannot drift apart.
+const dispatchQuestionOption = tool.schema.strictObject({
+  label: tool.schema.string().min(1),
+  description: tool.schema.string().optional(),
+});
+const dispatchQuestion = tool.schema.strictObject({
+  question: tool.schema.string().min(1),
+  header: tool.schema.string().optional(),
+  options: tool.schema.array(dispatchQuestionOption).optional(),
+  multiple: tool.schema.boolean().optional(),
+  custom: tool.schema.boolean().optional(),
+});
+const dispatchArgs = {
+  subject: tool.schema.string().describe(DISPATCH_ARGUMENTS.subject).optional(),
+  thread: tool.schema.string().describe(DISPATCH_ARGUMENTS.thread).optional(),
+  context: tool.schema.string().describe(DISPATCH_ARGUMENTS.context),
+  question: tool.schema.string().describe(DISPATCH_ARGUMENTS.question),
+  ask: tool.schema.array(dispatchQuestion).describe(DISPATCH_ARGUMENTS.ask).optional(),
+  urgency: tool.schema.enum(DISPATCH_URGENCIES).describe(DISPATCH_ARGUMENTS.urgency).optional(),
+  repo: tool.schema.string().describe(DISPATCH_ARGUMENTS.repo).optional(),
+  parent: tool.schema.string().describe(DISPATCH_ARGUMENTS.parent).optional(),
+};
+
 export default async (input: { serverUrl: URL }) => {
   const cwd = process.cwd();
-  const config = await loadEnvoyConfig(cwd);
+  // One loader for the shared envoy.json contract. An invalid file refuses to
+  // load rather than run with dispatch silently off.
+  const dispatchConfig = resolveDispatchConfig(process.env, { cwd });
+  if (dispatchConfig.error !== null) throw new Error(`[envoy-plugin] ${dispatchConfig.error}`);
+  const dispatchServiceUrl = dispatchConfig.url;
   const envoyDefaults = envoyDefaultsFromEnvironment(process.env);
   const envoy = createEnvoyClient({ baseUrl: envoyDefaults.envoyUrl, fetch: globalThis.fetch });
   let activeSessionID: string | null = null;
@@ -153,13 +191,35 @@ export default async (input: { serverUrl: URL }) => {
     clearInterval(heartbeatInterval);
   });
 
+  // The dispatch tool is present iff envoy.json (or DISPATCH_MCP_URL) names a
+  // service. The plugin adds only what it alone knows — that this is OpenCode,
+  // and which session is asking.
+  const dispatchTool =
+    dispatchServiceUrl === null
+      ? {}
+      : {
+          [DISPATCH_TOOL_NAME]: tool({
+            description: DISPATCH_TOOL_DESCRIPTION,
+            args: dispatchArgs,
+            async execute(args, ctx) {
+              ctx.metadata({ title: "Dispatch" });
+              // Validate before the title lookup: an invalid call costs no request.
+              const call = parseDispatchCall(args);
+              const result = await executeDispatch({
+                call,
+                cwd: ctx.directory,
+                host: "opencode",
+                sessionId: ctx.sessionID,
+                sessionTitle: (await fetchTitle(ctx.sessionID)) ?? undefined,
+                serviceUrl: dispatchServiceUrl,
+              });
+              return JSON.stringify(result);
+            },
+          }),
+        };
+
   return {
-    config: (
-      cfg: { mcp?: Record<string, unknown>; skills?: { paths?: string[] } } & Record<
-        string,
-        unknown
-      >
-    ) => {
+    config: (cfg: { skills?: { paths?: string[] } } & Record<string, unknown>) => {
       // Serve the bundled legion skills to every session on this serve.
       if (skillsDirectory) {
         cfg.skills ??= {};
@@ -168,20 +228,6 @@ export default async (input: { serverUrl: URL }) => {
           cfg.skills.paths.push(skillsDirectory);
         }
       }
-      // Inject the envoy MCP entry into the OpenCode config when
-      // dispatch is enabled. Centralizing this in the plugin (instead of
-      // each user's opencode.json) means:
-      //   1. Registration is gated by `dispatch.enabled`
-      //   2. The bearer token is sourced per-CWD via the user's gh shim
-      //      (no env coordination needed)
-      //   3. Token rotation happens transparently inside the shim
-      //      subprocess — OpenCode never sees an expired token
-      const entry = buildDispatchMcpEntry({
-        dispatch: config.dispatch,
-      });
-      if (!entry) return;
-      const { warning } = injectEnvoyMcp(cfg, entry);
-      if (warning) logger.warn(warning);
     },
     event: async ({
       event,
@@ -250,9 +296,9 @@ export default async (input: { serverUrl: URL }) => {
       input: { tool: string; sessionID: string; callID: string; args: unknown },
       output: { title: string; output: string; metadata: unknown }
     ) => {
-      // When this session opens a Dispatch thread via the envoy_dispatch MCP
-      // tool, auto-subscribe it to the thread's GitHub topic so the human's
-      // reply is delivered back through Envoy. Best-effort — a subscribe
+      // When this session opens or continues a Dispatch thread via the native
+      // dispatch tool, auto-subscribe it to the thread's GitHub topic so the
+      // human's reply is delivered back through Envoy. Best-effort — a subscribe
       // failure must never surface to the model or fail the tool call.
       const topic = dispatchSubscriptionTopic(input.tool, output.output);
       if (!topic) return;
@@ -276,6 +322,7 @@ export default async (input: { serverUrl: URL }) => {
       clearInterval(heartbeatInterval);
     },
     tool: {
+      ...dispatchTool,
       envoy_subscribe: tool({
         description: subscribeSpec.description,
         args: { topics: tool.schema.array(tool.schema.string()) },