@sjawhar/opencode-legion-envoy 0.35.0 → 0.36.0

package/README.md

@@ -22,14 +22,16 @@ This package exposes:
 - `dispatch_doc_read`
 - `dispatch_artifact`
 - `dispatch_read`
-
-The native `dispatch_*` tools create and read Dispatch issues, asks, comments, documents, and
-artifacts. 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`. Each call fills the target issue from
-the session working directory, stamps it with the OpenCode session id and title, and stores
-`details.topic` as tool metadata so a successful mutation subscribes to that exact Dispatch topic.
+- `dispatch_search`
+
+The eleven 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
+variables; `dispatch.enabled: true` without `dispatch.serverUrl` targets `http://localhost:8766`.
+Each issue-scoped call fills the target issue from the session working directory, stamps it with
+the OpenCode session id and title, and stores a successful mutation's `details.topic` as tool
+metadata so the host subscribes to that exact Dispatch topic.
 
 `dispatch_artifact` accepts exactly one upload source: a local `path`, or inline `content`.
 An architect can post a specification directly with

package/dist/src/server.js

@@ -13597,6 +13597,56 @@ var ChildStatusEventPayloadSchema = object({
   from: string2().optional(),
   to: string2().optional()
 });
+// ../contracts/src/dispatch-snippet.ts
+var HTML_ENTITIES = [
+  ["&lt;", "<"],
+  ["&gt;", ">"],
+  ["&#39;", "'"],
+  ["&#34;", '"'],
+  ["&amp;", "&"]
+];
+function decodeEntities(text) {
+  let decoded = text;
+  for (const [entity, character] of HTML_ENTITIES) {
+    decoded = decoded.replaceAll(entity, character);
+  }
+  return decoded;
+}
+function hasOnlyBalancedMarkers(snippet) {
+  let marked = false;
+  for (const marker of snippet.matchAll(/<mark>|<\/mark>/gu)) {
+    if (marker[0] === "<mark>") {
+      if (marked)
+        return false;
+      marked = true;
+    } else {
+      if (!marked)
+        return false;
+      marked = false;
+    }
+  }
+  return !marked;
+}
+function snippetSegments(snippet) {
+  if (!hasOnlyBalancedMarkers(snippet)) {
+    return snippet === "" ? [] : [{ text: decodeEntities(snippet), mark: false }];
+  }
+  let mark = false;
+  const segments = [];
+  for (const part of snippet.split(/(<mark>|<\/mark>)/u)) {
+    if (part === "<mark>") {
+      mark = true;
+    } else if (part === "</mark>") {
+      mark = false;
+    } else if (part !== "") {
+      segments.push({ text: decodeEntities(part), mark });
+    }
+  }
+  return segments;
+}
+function snippetText(snippet) {
+  return snippetSegments(snippet).map(({ text, mark }) => mark ? `**${text}**` : text).join("");
+}
 // ../contracts/src/dispatch-tools.ts
 function dispatchToolSchema(spec, z, opts) {
   const shape = spec.arguments(z);
@@ -13618,12 +13668,13 @@ var DOC_EDIT_OPS = ["replace", "delete", "insert"];
 var dispatchToolSpecs = [
   {
     name: "dispatch_issue",
-    description: "Create a native Dispatch issue for newly tracked work. Do not use it when an existing issue " + `already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
+    description: "Create a native Dispatch issue for newly tracked work. Search first with dispatch_search; if potentially duplicate issues exist, this returns 409 POSSIBLE_DUPLICATE unless force is true after reading them. " + `Do not use it when an existing issue already covers the work; read or update that issue instead. ${ISSUE_REFERENCE}`,
     arguments: (z) => ({
       project: z.string().describe("Project key for the new issue."),
       title: z.string().describe("Concise issue title."),
       parent: z.string().describe("Optional parent issue.").optional(),
       external: z.string().describe("Optional external issue reference.").optional(),
+      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()
     })
   },
@@ -13741,6 +13792,15 @@ var dispatchToolSpecs = [
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
       ref: z.string().describe("Optional dispatch:// issue reference.").optional()
     })
+  },
+  {
+    name: "dispatch_search",
+    description: "Search every issue, document, comment, ask, and message for a keyword or phrase and get deep links. " + "Use it before creating an issue or a design document, and to find where a word was written. " + 'Websearch syntax: "quoted phrase", -excluded, OR.',
+    arguments: (z) => ({
+      query: z.string({ min: 2 }).describe("Keyword, phrase, or websearch expression; at least 2 characters."),
+      project: z.string().describe("Optional project key to search within.").optional(),
+      limit: z.number({ int: true, min: 1, max: 50 }).describe("Maximum results, 1-50; default 20.").optional()
+    })
   }
 ];
 // ../contracts/src/envelope.ts
@@ -14331,6 +14391,9 @@ class DispatchClient {
   async listIssues(options = {}) {
     return this.#json("GET", ["api", "v1", "issues"], undefined, options);
   }
+  async search(query, options = {}) {
+    return this.#json("GET", ["api", "v1", "search"], undefined, { q: query, ...options });
+  }
   async getIssue(issue) {
     return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue)]);
   }
@@ -14505,6 +14568,7 @@ class DispatchClient {
 var nativeIssueKeyPattern = /^[A-Z][A-Z0-9]{1,9}-[0-9]+$/;
 var externalIssueRefPattern = /^([^/\s]+)\/([^/\s#]+)#([1-9][0-9]*)$/;
 var bareIssueNumberPattern = /^[1-9][0-9]*$/;
+var issueFreeTools = new Set(["dispatch_issue", "dispatch_resolve_ask", "dispatch_search"]);
 function canonicalExternalIssueRef(value) {
   const match = value.trim().match(externalIssueRefPattern);
   return match ? `${canonicalRepo(match[1] ?? "", match[2] ?? "")}#${match[3]}` : value;
@@ -14527,6 +14591,23 @@ function optionalNumber(args, name) {
   const value = args[name];
   return typeof value === "number" ? value : undefined;
 }
+function isDuplicateCandidate(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const candidate = value;
+  return typeof candidate.key === "string" && typeof candidate.title === "string" && typeof candidate.status === "string" && typeof candidate.snippet === "string" && typeof candidate.shared_terms === "number" && typeof candidate.href === "string";
+}
+function duplicateCandidates(error) {
+  if (error.candidates === undefined || !error.candidates.every(isDuplicateCandidate))
+    throw error;
+  return error.candidates;
+}
+function searchResultLine(result, baseUrl) {
+  const artifactName = result.artifact ? ` ${result.artifact.name}` : "";
+  const label = `${result.issue.key} [${result.issue.status}] ${result.issue.title} - ${result.kind}${artifactName}`;
+  const href = new URL(result.href, baseUrl).toString();
+  return `${label}: ${snippetText(result.snippet)} -> ${href}`;
+}
 function askUrgency(args) {
   const value = args.urgency;
   return ASK_URGENCIES.find((urgency) => urgency === value);
@@ -14565,7 +14646,7 @@ function toolSchema(tool) {
   return dispatchToolSchema(spec, zodSchemaApi(exports_external), { strict: true });
 }
 async function resolveIssueArguments(tool, args, cwd, env, exec) {
-  if (tool === "dispatch_issue" || tool === "dispatch_resolve_ask")
+  if (issueFreeTools.has(tool))
     return { args, ref: null };
   const refArgument = args.ref;
   const ref = typeof refArgument === "string" ? parseDispatchRef(refArgument) ?? (() => {
@@ -14713,7 +14794,9 @@ async function openArtifactMarks(client, resolved) {
   ];
 }
 async function executeDispatchTool(input) {
-  if (!input.config.enabled || !input.config.url || !input.config.token) {
+  const configUrl = input.config.url;
+  const configToken = input.config.token;
+  if (!input.config.enabled || !configUrl || !configToken) {
     throw new Error("Dispatch is disabled; resolve both DISPATCH_URL and DISPATCH_TOKEN");
   }
   const env = input.env ?? process.env;
@@ -14721,8 +14804,8 @@ async function executeDispatchTool(input) {
   const issueArguments = await resolveIssueArguments(input.tool, input.args, input.cwd, env, exec);
   const args = toolSchema(input.tool).parse(issueArguments.args);
   const actor = toolActor(await resolveOrigin(env, exec, input.cwd), input);
-  const client = new DispatchClient(input.config.url, input.config.token, input.fetchImpl);
-  const issueKey = input.tool === "dispatch_issue" || input.tool === "dispatch_resolve_ask" ? null : await ensureIssue(client, stringArg(args, "issue"), actor);
+  const client = new DispatchClient(configUrl, configToken, input.fetchImpl);
+  const issueKey = issueFreeTools.has(input.tool) ? null : await ensureIssue(client, stringArg(args, "issue"), actor);
   const issue = () => {
     if (issueKey === null)
       throw new Error("issue is required");
@@ -14730,20 +14813,62 @@ async function executeDispatchTool(input) {
   };
   switch (input.tool) {
     case "dispatch_issue": {
+      const project = stringArg(args, "project");
+      const title = stringArg(args, "title");
       const parent = optionalString(args, "parent");
       const external = optionalString(args, "external");
+      const force = optionalBoolean(args, "force");
       const spec = optionalString(args, "spec");
-      const created = await client.issue({
-        project: stringArg(args, "project"),
-        title: stringArg(args, "title"),
-        ...parent === undefined ? {} : { parent },
-        ...external === undefined ? {} : { external },
-        ...spec === undefined ? {} : { spec },
-        actor
+      try {
+        const created = await client.issue({
+          project,
+          title,
+          ...parent === undefined ? {} : { parent },
+          ...external === undefined ? {} : { external },
+          ...force === undefined ? {} : { force },
+          ...spec === undefined ? {} : { spec },
+          actor
+        });
+        return {
+          text: `Created ${created.key}: ${created.title}`,
+          details: { issue: created.key, topic: dispatchIssueSubject(created.key, ">") }
+        };
+      } catch (error) {
+        if (!(error instanceof DispatchServiceError) || error.code !== "POSSIBLE_DUPLICATE") {
+          throw error;
+        }
+        const candidates = duplicateCandidates(error);
+        return {
+          text: [
+            `Not created: "${title}" looks like a duplicate.`,
+            ...candidates.map((candidate) => {
+              const href = new URL(candidate.href, configUrl).toString();
+              return `${candidate.key} [${candidate.status}] ${candidate.title} \u2192 ${href}`;
+            }),
+            "Reference the existing issue, or call dispatch_issue again with force: true after reading it."
+          ].join(`
+`),
+          details: { duplicates: candidates }
+        };
+      }
+    }
+    case "dispatch_search": {
+      const query = stringArg(args, "query");
+      const project = optionalString(args, "project");
+      const limit = optionalNumber(args, "limit");
+      const search = await client.search(query, {
+        ...project === undefined ? {} : { project },
+        ...limit === undefined ? {} : { limit }
       });
+      const results = search.results;
+      const count = results.length;
       return {
-        text: `Created ${created.key}: ${created.title}`,
-        details: { issue: created.key, topic: dispatchIssueSubject(created.key, ">") }
+        text: count === 0 ? `No results for "${query}".` : [
+          `${count} ${count === 1 ? "result" : "results"} for "${query}" (${search.took_ms} ms)`,
+          ...results.map((result) => searchResultLine(result, configUrl))
+        ].join(`
+`),
+        details: { query, results }
       };
     }
     case "dispatch_resolve_ask": {

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -54,11 +54,24 @@ project configured for that repository in Dispatch Settings, then falls back to
 
 Architects create newly tracked child work with:
 ```ts
-dispatch_issue({ project, title, parent?, external?, spec? })
+dispatch_issue({ project, title, parent?, external?, spec?, force? })
 ```
 It returns `details` `{ issue, topic }`. 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).
+it to park a question. When `spec` is supplied, follow [Writing a spec](#writing-a-spec).
+
+## Search first
+
+Before you create an issue or start a design document, search:
+```ts
+dispatch_search({ query, project?, limit? })
+```
+It returns every issue, document, comment, ask, and message that contains the words, with the
+issue key and a link. Cite the hit you build on (`dispatch://KEY` or the document reference), or
+state "no prior issue" in the spec. Websearch syntax applies: `"merge queue"`, `-daemon`, `OR`.
+
+`dispatch_issue` refuses a title that near-duplicates an issue in the same project and returns
+the candidates (`POSSIBLE_DUPLICATE`). Read them; reference the existing issue, or repeat the
+call with `force: true` when it is genuinely new work.
 
 ## Asking