@sjawhar/opencode-legion-envoy 1.36.0 → 1.38.0

package/README.md

@@ -29,11 +29,12 @@ This package exposes:
 - `dispatch_read`
 - `dispatch_search`
 - `dispatch_issues`
+- `dispatch_architecture_sync`
 - `dispatch_open_asks`
 - `dispatch_whoami`
 
-The nineteen native `dispatch_*` tools create and read Dispatch issues, asks, comments,
-documents, and artifacts, list a project's issues, or search all of them. They are present when `dispatch.enabled`
+The twenty native `dispatch_*` tools create and read Dispatch issues, asks, comments,
+documents, and artifacts, list a project's issues, sync a project's architecture model, 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
 variables; `dispatch.enabled: true` without `dispatch.serverUrl` targets `http://localhost:8766`.

package/dist/src/server.js

@@ -13766,6 +13766,14 @@ var commentValidation = (() => {
     message: `${owner.message} turn requires reply_to_ask.`
   };
 })();
+var ISSUE_COMPONENTS_MODES = ["inherit", "explicit", "none"];
+function componentsArgument(z) {
+  return z.object({
+    mode: z.enum(ISSUE_COMPONENTS_MODES).describe("inherit: take the parent chain's attachment (the default; deletes this issue's own). explicit: attach to ids. none: not architectural work, with reason."),
+    ids: z.array(z.string({ min: 1 }), { min: 1, max: 50 }).describe("For mode explicit: bare component ids from the project's architecture model (web, dispatch-server), not external ones.").optional(),
+    reason: z.string({ min: 1 }).describe("For mode none: why this issue is not architectural (process, hiring, ops).").optional()
+  }).describe("Attach the issue to architecture components. Attach the root before decomposing it; children inherit unless they choose.");
+}
 var SPEC_SECTIONS = [
   "Summary",
   "Decisions needed",
@@ -13804,12 +13812,13 @@ var dispatchToolSpecs = [
       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(),
-      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()
+      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(),
+      components: componentsArgument(z).optional()
     })
   },
   {
     name: "dispatch_issue_update",
-    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, link a URL " + "(the pull request that delivers it, a run, a document), set its route, or set or clear its parent. " + "Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. external_links are " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link. Priority is the human's and is not settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
+    description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, link a URL " + "(the pull request that delivers it, a run, a document), set its route, set or clear its parent, " + "or attach it to architecture components. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. external_links are " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link. components replaces the issue's own attachment and is allowed on a " + "closed issue. Priority is the human's and is not settable here. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE),
       status: z.enum(ISSUE_STATUSES).describe("New lifecycle status.").optional(),
@@ -13817,14 +13826,15 @@ var dispatchToolSpecs = [
       labels: z.array(z.string({ min: 1, max: 40 }), { max: 20 }).describe("Replacement label set, at most 20 labels of up to 40 characters; replaces every existing label.").optional(),
       external_links: z.array(z.string({ min: 1 })).describe("URLs to link; merged into the issue's existing external links by URL.").optional(),
       route: z.string().describe("Route the issue to role:<name> or session:<id>; an empty string clears it.").optional(),
-      parent: z.string().describe("Parent issue key in the same project; an empty string clears the parent.").optional()
+      parent: z.string().describe("Parent issue key in the same project; an empty string clears the parent.").optional(),
+      components: componentsArgument(z).optional()
     }),
     validation: {
       check: (value) => {
         const input = value;
-        return typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string";
+        return typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string" || typeof input.components === "object" && input.components !== null;
       },
-      message: "Issue update requires at least one field besides issue: status, title, labels, external_links, route, or parent."
+      message: "Issue update requires at least one field besides issue: status, title, labels, external_links, route, parent, or components."
     },
     strict: true
   },
@@ -14036,6 +14046,14 @@ var dispatchToolSpecs = [
       limit: z.number({ int: true, min: 1, max: 250 }).describe("Maximum rows, 1-250; default 50.").optional()
     })
   },
+  {
+    name: "dispatch_architecture_sync",
+    description: "Import a project's architecture model from its configured source repository now, instead of " + "waiting for the server's five-minute schedule. Returns the imported commit and component " + "count, or the recorded error when the model was rejected (the previous model stays up). " + "The source itself is configured by a human in Settings; 404 SOURCE_NOT_FOUND without one.",
+    arguments: (z) => ({
+      project: z.string().describe("Project key whose architecture source to sync, such as CORE.")
+    }),
+    strict: true
+  },
   {
     name: "dispatch_open_asks",
     description: "List active unanswered asks, oldest first, with age and whose reply is needed. Omit project to " + "see only this session's own authored asks (call before saying you are waiting for human input); " + "supply project to see every open ask across that project's issues and documents, whoever authored " + "them.",
@@ -14876,6 +14894,9 @@ class DispatchClient {
   async whoami() {
     return this.#json("GET", ["api", "v1", "whoami"]);
   }
+  async syncArchitectureSource(project) {
+    return this.#json("POST", ["api", "v1", "projects", project, "architecture-source", "sync"]);
+  }
   async resolveAsk(id, input) {
     return this.#json("POST", ["api", "v1", "asks", id, "resolve"], input);
   }
@@ -15291,7 +15312,8 @@ var issueFreeTools = {
   dispatch_search: true,
   dispatch_issues: true,
   dispatch_open_asks: true,
-  dispatch_whoami: true
+  dispatch_whoami: true,
+  dispatch_architecture_sync: true
 };
 function canonicalExternalIssueRef(value) {
   const match = value.trim().match(externalIssueRefPattern);
@@ -15315,6 +15337,27 @@ function optionalNumber(args, name) {
   const value = args[name];
   return typeof value === "number" ? value : undefined;
 }
+function optionalComponents(args, name) {
+  const value = args[name];
+  if (typeof value !== "object" || value === null)
+    return;
+  const input = value;
+  return {
+    mode: input.mode,
+    ...input.ids === undefined ? {} : { ids: input.ids },
+    ...input.reason === undefined ? {} : { reason: input.reason }
+  };
+}
+function componentsChange(input, after) {
+  switch (input.mode) {
+    case "explicit":
+      return `components -> explicit [${after.ids.join(", ")}]`;
+    case "none":
+      return `components -> none (${after.reason ?? input.reason ?? ""})`;
+    case "inherit":
+      return "components -> inherit";
+  }
+}
 function isDuplicateCandidate(value) {
   if (typeof value !== "object" || value === null)
     return false;
@@ -15698,6 +15741,18 @@ function approvalLine(artifact) {
       return `Approval: changes requested on v${approval.version} by ${approval.by?.id ?? "unknown"}: ${approval.reason ?? ""}`;
   }
 }
+function componentsLine(components) {
+  const inherited = components.inherited_from === null ? "" : ` (inherited from ${components.inherited_from})`;
+  const retired = components.unknown.length === 0 ? "" : ` (retired: ${components.unknown.join(", ")})`;
+  switch (components.mode) {
+    case "explicit":
+      return `Components: ${components.ids.length === 0 ? "none live" : components.ids.join(", ")}${inherited}${retired}`;
+    case "none":
+      return `Components: none \u2014 ${components.reason ?? ""}${inherited}`;
+    case "inherit":
+      return "Components: unassigned";
+  }
+}
 function issueSummary(issue, events, references, graph) {
   const asks = issue.open_asks;
   const spec = issue.artifacts?.find((artifact) => artifact.primary);
@@ -15706,6 +15761,8 @@ function issueSummary(issue, events, references, graph) {
     throw new Error("Dispatch issue is missing priority");
   if (issue.assignee === undefined)
     throw new Error("Dispatch issue is missing assignee");
+  if (issue.components === undefined)
+    throw new Error("Dispatch issue is missing components");
   return [
     `Title: ${issue.title}`,
     `Key: ${issue.key}`,
@@ -15713,6 +15770,7 @@ function issueSummary(issue, events, references, graph) {
     `Assignee: ${issue.assignee ?? "unassigned"}`,
     ...issue.priority === null ? [] : [`Priority: P${issue.priority}`],
     `Labels: ${issue.labels.length === 0 ? "none" : issue.labels.join(", ")}`,
+    componentsLine(issue.components),
     `Route: ${issue.route ?? "none"}`,
     ...specApproval === undefined ? [] : [`Spec ${specApproval.replace(/^Approval/, "approval")}`],
     "Open asks:",
@@ -16002,6 +16060,7 @@ async function executeDispatchTool(input) {
       const spec = optionalString(args, "spec");
       const priority = optionalNumber(args, "priority");
       const assignee = optionalString(args, "assignee");
+      const components = optionalComponents(args, "components");
       const labels = args.labels;
       try {
         const created = await client.issue({
@@ -16013,6 +16072,7 @@ async function executeDispatchTool(input) {
           ...spec === undefined ? {} : { spec },
           ...priority === undefined ? {} : { priority },
           ...assignee === undefined ? {} : { assignee },
+          ...components === undefined ? {} : { components },
           ...Array.isArray(labels) ? { labels } : {},
           actor
         });
@@ -16045,6 +16105,7 @@ async function executeDispatchTool(input) {
       const title = optionalString(args, "title");
       const route = optionalString(args, "route");
       const parent = optionalString(args, "parent");
+      const components = optionalComponents(args, "components");
       const labels = Array.isArray(args.labels) ? args.labels : undefined;
       const requestedLinks = Array.isArray(args.external_links) ? [...new Set(args.external_links)] : undefined;
       let newLinks = [];
@@ -16058,6 +16119,7 @@ async function executeDispatchTool(input) {
           ...labels === undefined ? {} : { labels },
           ...route === undefined ? {} : { route },
           ...parent === undefined ? {} : { parent: parent === "" ? null : parent },
+          ...components === undefined ? {} : { components },
           ...requestedLinks === undefined ? {} : { external_links: [...before.external_links, ...newLinks.map((url) => ({ url }))] },
           actor
         });
@@ -16070,7 +16132,8 @@ async function executeDispatchTool(input) {
             newLinks.length === 0 ? `already linked ${requestedLinks.join(", ")} ${linkCount}` : `linked ${newLinks.join(", ")} ${linkCount}`
           ],
           ...route === undefined ? [] : [after.route === null ? "route cleared" : `route ${after.route}`],
-          ...parent === undefined ? [] : [after.parent === null ? "parent cleared" : `parent -> ${after.parent}`]
+          ...parent === undefined ? [] : [after.parent === null ? "parent cleared" : `parent -> ${after.parent}`],
+          ...components === undefined ? [] : [componentsChange(components, after.components)]
         ];
         return {
           text: `${after.key}: ${changes.join("; ")} ${notSubscribed(issueTopic(after.key))}`,
@@ -16139,6 +16202,25 @@ async function executeDispatchTool(input) {
         details: { issues: rows }
       };
     }
+    case "dispatch_architecture_sync": {
+      const project = stringArg(args, "project");
+      const source = await client.syncArchitectureSource(project);
+      const at = source.last_sync_at ?? "unknown time";
+      return {
+        text: source.last_error === null ? `Synced ${project} architecture from ${source.repo}@${source.branch}: commit ${source.last_commit ?? "unknown"} (${at}).` : [
+          `Sync failed for ${project} (${source.repo}@${source.branch}): ${source.last_error}`,
+          source.last_commit === null ? "No model has ever imported for this project." : `The previous model stays up (commit ${source.last_commit}).`
+        ].join(`
+`),
+        details: {
+          project,
+          repo: source.repo,
+          branch: source.branch,
+          commit: source.last_commit,
+          error: source.last_error
+        }
+      };
+    }
     case "dispatch_resolve_ask": {
       const kind = stringArg(args, "kind");
       const ask = await client.resolveAsk(stringArg(args, "ask"), {

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -248,6 +248,23 @@ that follow from it:
 the question carries `dispatch://KEY/artifact/<slug>` (or `ref`), never just its filename. Text
 they must read to decide belongs in the spec in the first place — see [Artifacts](#artifacts).
 
+Attach an issue to the architecture components it changes, before decomposing it — children inherit the parent's attachment unless they choose their own, so attaching the root once classifies the whole tree:
+
+```
+dispatch_issue({ project: "CORE", title: "...", components: { mode: "explicit", ids: ["dispatch-server", "web"] } })
+dispatch_issue_update({ issue: "CORE-12", components: { mode: "explicit", ids: ["web"] } })   // this issue's own set, replacing what it inherited
+dispatch_issue_update({ issue: "CORE-13", components: { mode: "none", reason: "hiring, not code" } })
+dispatch_issue_update({ issue: "CORE-14", components: { mode: "inherit" } })                  // back to the parent chain's attachment
+```
+
+Component ids are the file names under the repository's `.dispatch/architecture/` (`web.md` → `web`); an id the model lacks, or an `external` component, is refused with `COMPONENTS_INPUT`. A closed issue can be classified without reopening. Two rules: declare and attach before decomposing work, and change code and its architecture description (`.dispatch/architecture/<id>.md`) in the same review — the tree at `GET /api/v1/projects/{key}/architecture` counts every issue whose effective set names a component or anything it contains.
+
+Import a project's architecture model from its configured source repository now (a human configures the source in Settings):
+```ts
+dispatch_architecture_sync({ project: "CORE" })
+```
+It returns the imported commit, or the recorded error when the model was rejected — the previous model stays up. Without a configured source it answers 404 `SOURCE_NOT_FOUND`.
+
 Before saying you are waiting for human input, call `dispatch_open_asks`. With no arguments it lists this session's active asks across open issues and project documents, including whether the human or agent owes the next reply. With `dispatch_open_asks({ project })` it lists every open ask in that project — on its issues and on its documents, whoever authored them — which is how you audit what a whole project is waiting on rather than just your own asks.
 
 **Anything that needs the human is an ask, or it does not exist.** An approval, a credential,

package/skills/legion-architect/SKILL.md

@@ -331,3 +331,7 @@ capacity, and cross-tree conflict. Use the Legion escalation operation for those
 everything else in the tree, or use `dispatch_ask` for a human question; workers may reach
 Sami directly with `dispatch_ask` the same way. Do not create a wait loop for any wake
 source.
+
+## Architecture components
+
+Bootstrap on a root whose project has an architecture source: in the root's first PR (the implement worker pushes it), write `.dispatch/architecture/<id>.md` files for the planned components — front matter `title`, `parent`, `depends_on`, `external`; no `paths` yet. The importer reads the source branch's head, so the sync and the attach below work only once that PR has merged to the source branch: until then leave the root on `inherit` (the attach would answer `400 COMPONENTS_INPUT`, the component does not exist yet). After the merge, `dispatch_architecture_sync({ project })` and attach the root with `dispatch_issue_update({ issue, components: { mode: "explicit", ids: [...] } })`. Children inherit the root's attachment; give a child its own `components` only when it changes a narrower set, and `{ mode: "none", reason }` when it is not architectural work. Attach before decomposing, and require every implementer to change the component file beside the code it describes in the same review.