@sjawhar/opencode-legion-envoy 0.40.0 → 0.41.0

package/dist/src/server.js

@@ -13673,6 +13673,18 @@ function dispatchToolSchema(spec, z, opts) {
   return spec.validation === undefined ? z.object(shape, opts) : z.refineObject(shape, spec.validation.check, spec.validation.message, opts);
 }
 var ISSUE_REFERENCE = "An issue is a native KEY or external owner/repo#n reference; an external reference creates its native issue in the repository's dashboard-configured project or, failing that, the default project (DISPATCH_DEFAULT_PROJECT).";
+var OWNER_REFERENCE = "Exactly one of issue and project is required. An issue is a native KEY or external owner/repo#n reference; a project is a project key such as CORE and addresses an unlinked project document named by artifact.";
+function documentOwnerValidation(requireArtifact) {
+  return {
+    check: (value) => {
+      const input = value;
+      const hasIssue = typeof input.issue === "string";
+      const hasProject = typeof input.project === "string";
+      return (hasIssue !== hasProject || !hasIssue && !hasProject && typeof input.ref === "string") && (!hasProject || !requireArtifact || typeof input.artifact === "string");
+    },
+    message: "Exactly one of issue and project is required; with project, artifact names the document."
+  };
+}
 var SPEC_SECTIONS = [
   "Decisions needed",
   "Acceptance",
@@ -13700,9 +13712,11 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_ask",
-    description: "Open a durable, answerable decision on an issue. Do not use it for a status update or discussion; " + `use dispatch_message instead. Question is at most 800 characters and has at most 8 options. ${ISSUE_REFERENCE}`,
+    description: "Open a durable, answerable decision on an issue or project document. Do not use it for a status update or discussion; " + `use dispatch_message instead. Question is at most 800 characters and has at most 8 options. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
-      issue: z.string().describe(ISSUE_REFERENCE),
+      issue: z.string().describe(ISSUE_REFERENCE).optional(),
+      project: z.string().describe("Project key owning the document.").optional(),
+      artifact: z.string().describe("Project document slug or id.").optional(),
       question: z.string({ max: 800 }).describe("Decision question, at most 800 characters."),
       options: z.array(z.object({
         label: z.string().describe("Selectable option label."),
@@ -13715,7 +13729,8 @@ var dispatchToolSpecs = [
         quote: z.string().describe("Exact text the decision concerns."),
         occurrence: z.number({ int: true, min: 0 }).describe("Zero-based occurrence of the quote.").optional()
       }).describe("Optional document location for the question.").optional()
-    })
+    }),
+    validation: documentOwnerValidation(true)
   },
   {
     name: "dispatch_edit_ask",
@@ -13749,28 +13764,32 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_comment",
-    description: "Add review feedback to an issue or document quote, or reply to a question asked with dispatch_ask. " + "Do not use it for an exact replacement; use " + `dispatch_suggest instead. Body is at most 2,000 characters. ${ISSUE_REFERENCE}`,
+    description: "Add review feedback to an issue or project document quote, or reply to a question asked with dispatch_ask. " + "Do not use it for an exact replacement; use " + `dispatch_suggest instead. Body is at most 2,000 characters. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
-      issue: z.string().describe(ISSUE_REFERENCE),
+      issue: z.string().describe(ISSUE_REFERENCE).optional(),
+      project: z.string().describe("Project key owning the document.").optional(),
       artifact: z.string().describe("Artifact slug or id required when quote is given.").optional(),
       quote: z.string().describe("Optional exact quoted document text.").optional(),
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional(),
       body: z.string({ max: 2000 }).describe("Review comment, at most 2,000 characters."),
       reply_to: z.string().describe("Optional comment id to reply to.").optional(),
       reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional()
-    })
+    }),
+    validation: documentOwnerValidation(true)
   },
   {
     name: "dispatch_suggest",
-    description: "Propose an exact replacement for quoted document text. Do not use it for general feedback; use " + `dispatch_comment instead. Optional explanation is at most 2,000 characters. ${ISSUE_REFERENCE}`,
+    description: "Propose an exact replacement for quoted document text. Do not use it for general feedback; use " + `dispatch_comment instead. Optional explanation is at most 2,000 characters. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
-      issue: z.string().describe(ISSUE_REFERENCE),
+      issue: z.string().describe(ISSUE_REFERENCE).optional(),
+      project: z.string().describe("Project key owning the document.").optional(),
       artifact: z.string().describe("Artifact slug or id containing the quoted text."),
       quote: z.string().describe("Exact document text to replace."),
       replace_with: z.string().describe("Replacement text."),
       body: z.string({ max: 2000 }).describe("Optional rationale, at most 2,000 characters.").optional(),
       occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional()
-    })
+    }),
+    validation: documentOwnerValidation(true)
   },
   {
     name: "dispatch_message",
@@ -13782,9 +13801,10 @@ var dispatchToolSpecs = [
   },
   {
     name: "dispatch_doc_edit",
-    description: "Apply deterministic text edits to a document. Do not use it for review feedback or for reading; use " + `dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. ${ISSUE_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
+    description: "Apply deterministic text edits to an issue or project document. Do not use it for review feedback or for reading; use " + `dispatch_comment, dispatch_suggest, or dispatch_doc_read instead. ${OWNER_REFERENCE} ${SPEC_WRITING_GUIDANCE}`,
     arguments: (z) => ({
-      issue: z.string().describe(ISSUE_REFERENCE),
+      issue: z.string().describe(ISSUE_REFERENCE).optional(),
+      project: z.string().describe("Project key owning the document.").optional(),
       artifact: z.string().describe("Artifact slug or id for the document."),
       ops: z.array(z.object({
         op: z.enum(DOC_EDIT_OPS).describe("Edit operation."),
@@ -13796,23 +13816,27 @@ var dispatchToolSpecs = [
         before: z.string().describe("Anchor before which to insert.").optional()
       })).describe("Flat tagged edits; the server validates fields required for each operation."),
       summary: z.string().describe("Optional named-version summary.").optional()
-    })
+    }),
+    validation: documentOwnerValidation(true)
   },
   {
     name: "dispatch_doc_read",
-    description: "Read a live document or a named document version. Do not use it for issue status, asks, or events; " + "use dispatch_read instead. Supply ref or issue; issue plus an omitted artifact reads the primary document. " + `${ISSUE_REFERENCE}`,
+    description: "Read a live document or a named document version. Do not use it for issue status, asks, or events; " + "use dispatch_read instead. Supply ref, issue, or project plus artifact; issue plus an omitted artifact reads the primary document. " + OWNER_REFERENCE,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
-      artifact: z.string().describe("Optional artifact slug or id; primary document by default.").optional(),
+      project: z.string().describe("Project key owning the document.").optional(),
+      artifact: z.string().describe("Optional artifact slug or id; primary document by default for an issue.").optional(),
       version: z.number({ int: true, min: 1 }).describe("Optional version number.").optional(),
       ref: z.string().describe("Optional dispatch:// document reference.").optional()
-    })
+    }),
+    validation: documentOwnerValidation(true)
   },
   {
     name: "dispatch_artifact",
-    description: "Attach a local file or inline text as an issue artifact. Do not use it to edit a live document; use " + `dispatch_doc_edit instead. Exactly one of path or content is required; artifacts are limited to 25 MiB. ${ISSUE_REFERENCE}`,
+    description: "Attach a local file or inline text as an issue artifact or project document. Do not use it to edit a live document; use " + `dispatch_doc_edit instead. Exactly one of path or content is required; artifacts are limited to 25 MiB. ${OWNER_REFERENCE}`,
     arguments: (z) => ({
-      issue: z.string().describe(ISSUE_REFERENCE),
+      issue: z.string().describe(ISSUE_REFERENCE).optional(),
+      project: z.string().describe("Project key for an unlinked document.").optional(),
       name: z.string().describe("Artifact filename shown in Dispatch."),
       path: z.string().describe("Local path to the file to upload.").optional(),
       content: z.string().describe("Inline text to store as a Markdown document.").optional(),
@@ -13821,18 +13845,21 @@ var dispatchToolSpecs = [
     validation: {
       check: (value) => {
         const input = value;
-        return typeof input.path === "string" !== (typeof input.content === "string");
+        return documentOwnerValidation(false).check(value) && typeof input.path === "string" !== (typeof input.content === "string");
       },
-      message: "Exactly one of path or content is required."
+      message: "Exactly one of path or content is required. Exactly one of issue and project is required; with project, artifact names the document."
     }
   },
   {
     name: "dispatch_read",
-    description: "Read an issue summary, targeted ask, or targeted comment reply chain. Do not use it for document " + "contents; use dispatch_doc_read instead. Supply issue or ref. " + ISSUE_REFERENCE,
+    description: "Read an issue or project-document summary, targeted ask, or targeted comment reply chain. Do not use it for document " + "contents; use dispatch_doc_read instead. Supply ref, issue, or project plus artifact. " + OWNER_REFERENCE,
     arguments: (z) => ({
       issue: z.string().describe(ISSUE_REFERENCE).optional(),
-      ref: z.string().describe("Optional dispatch:// issue reference.").optional()
-    })
+      project: z.string().describe("Project key owning the document.").optional(),
+      artifact: z.string().describe("Project document slug or id.").optional(),
+      ref: z.string().describe("Optional dispatch:// issue or document reference.").optional()
+    }),
+    validation: documentOwnerValidation(true)
   },
   {
     name: "dispatch_search",
@@ -13960,10 +13987,15 @@ var handoffMessageSchema = object({
 });
 // ../contracts/src/subject.ts
 var AGENT_TOPIC_PREFIX = "notifications.agent.";
-var DISPATCH_ISSUE_TOPIC_PREFIX = "notifications.dispatch.issue.";
+var DISPATCH_TOPIC_PREFIX = "notifications.dispatch.";
+var DISPATCH_ISSUE_TOPIC_PREFIX = `${DISPATCH_TOPIC_PREFIX}issue.`;
+var DISPATCH_DOCUMENT_TOPIC_PREFIX = `${DISPATCH_TOPIC_PREFIX}document.`;
 function dispatchIssueSubject(issueKey, type) {
   return `${DISPATCH_ISSUE_TOPIC_PREFIX}${issueKey}.${type}`;
 }
+function dispatchDocumentSubject(project, slug, type) {
+  return `${DISPATCH_DOCUMENT_TOPIC_PREFIX}${project}.${slug}.${type}`;
+}
 function agentSubject(session) {
   return `${AGENT_TOPIC_PREFIX}${session}`;
 }
@@ -14482,6 +14514,25 @@ class DispatchClient {
   async listIssues(options = {}) {
     return this.#json("GET", ["api", "v1", "issues"], undefined, options);
   }
+  async listProjectArtifacts(project, unlinked = false) {
+    return this.#json("GET", ["api", "v1", "projects", project, "artifacts"], undefined, unlinked ? { unlinked: "true" } : undefined);
+  }
+  async projectArtifact(project, input) {
+    const artifactPath = ["api", "v1", "projects", project, "artifacts"];
+    if ("content" in input)
+      return this.#json("POST", artifactPath, input);
+    const form = new FormData;
+    form.set("name", input.name);
+    if (input.summary !== undefined)
+      form.set("summary", input.summary);
+    if (input.actor !== undefined)
+      form.set("actor", JSON.stringify(input.actor));
+    form.set("file", input.file, input.name);
+    return this.#form("POST", artifactPath, form);
+  }
+  async getProjectArtifact(project, slug) {
+    return this.#json("GET", ["api", "v1", "projects", project, "artifacts", slug]);
+  }
   async search(query, options = {}) {
     return this.#json("GET", ["api", "v1", "search"], undefined, { q: query, ...options });
   }
@@ -14509,6 +14560,12 @@ class DispatchClient {
   async comment(issue, input) {
     return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "comments"], input);
   }
+  async getArtifactAsks(id, state) {
+    return this.#json("GET", ["api", "v1", "artifacts", id, "asks"], undefined, state === undefined ? undefined : { state });
+  }
+  async artifactAsk(id, input) {
+    return this.#json("POST", ["api", "v1", "artifacts", id, "asks"], input);
+  }
   async suggest(issue, input) {
     const { replace_with, ...comment } = input;
     return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "comments"], {
@@ -14516,6 +14573,19 @@ class DispatchClient {
       suggestion: { replace_with }
     });
   }
+  async getArtifactComments(id) {
+    return this.#json("GET", ["api", "v1", "artifacts", id, "comments"]);
+  }
+  async artifactComment(id, input) {
+    return this.#json("POST", ["api", "v1", "artifacts", id, "comments"], input);
+  }
+  async artifactSuggest(id, input) {
+    const { replace_with, ...comment } = input;
+    return this.#json("POST", ["api", "v1", "artifacts", id, "comments"], {
+      ...comment,
+      suggestion: { replace_with }
+    });
+  }
   async message(issue, input) {
     return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "messages"], input);
   }
@@ -14544,6 +14614,12 @@ class DispatchClient {
   async nameArtifactVersion(id, input) {
     return this.#json("POST", ["api", "v1", "artifacts", id, "versions"], input);
   }
+  async getArtifactEvents(id, after = 0, limit = 200) {
+    return this.#json("GET", ["api", "v1", "artifacts", id, "events"], undefined, { after, limit });
+  }
+  async getArtifactReferences(id) {
+    return this.#json("GET", ["api", "v1", "artifacts", id, "references"]);
+  }
   async getAsk(id) {
     return this.#json("GET", ["api", "v1", "asks", id]);
   }
@@ -14553,6 +14629,15 @@ class DispatchClient {
   async getComments(issue, artifact) {
     return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "comments"], undefined, artifact ? { artifact } : undefined);
   }
+  async getIssueReferences(issue) {
+    return this.#json("GET", [
+      "api",
+      "v1",
+      "issues",
+      await this.#resolveIssue(issue),
+      "references"
+    ]);
+  }
   async ensureIssue(issueReference, actor) {
     if (!issueReference.includes("#"))
       return issueReference;
@@ -14659,16 +14744,27 @@ class DispatchClient {
 }
 
 // ../envoy-client/src/dispatch-execute.ts
-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_edit_ask",
-  "dispatch_resolve_ask",
-  "dispatch_search"
-]);
-async function askResultDetails(client, ask) {
+function documentResultDetails(artifact) {
+  return {
+    project: artifact.project,
+    artifact: artifact.id,
+    document: `${artifact.project}/${artifact.slug}`,
+    topic: dispatchDocumentSubject(artifact.project, artifact.slug, ">")
+  };
+}
+function writeResultDetails(resolved, fields) {
+  if (resolved.owner.kind === "project") {
+    return { ...documentResultDetails(resolved.artifact), ...fields };
+  }
+  if (resolved.issue === undefined)
+    throw new Error("issue document is missing its issue");
+  return {
+    issue: resolved.issue.key,
+    topic: dispatchIssueSubject(resolved.issue.key, ">"),
+    ...fields
+  };
+}
+async function askResultDetails(client, ask, resolved) {
   if (ask.issue_key !== null) {
     return {
       issue: ask.issue_key,
@@ -14679,12 +14775,18 @@ async function askResultDetails(client, ask) {
   if (ask.artifact_id === undefined || ask.artifact_id === null) {
     throw new Error("document ask is missing its artifact ID");
   }
-  const artifact = await client.getArtifact(ask.artifact_id);
-  return {
-    topic: `notifications.dispatch.document.${artifact.project}.${artifact.slug}.>`,
-    ask: ask.id
-  };
+  const artifact = resolved?.artifact ?? await client.getArtifact(ask.artifact_id);
+  return { ...documentResultDetails(artifact), ask: ask.id };
 }
+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 = {
+  dispatch_issue: true,
+  dispatch_edit_ask: true,
+  dispatch_resolve_ask: true,
+  dispatch_search: true
+};
 function canonicalExternalIssueRef(value) {
   const match = value.trim().match(externalIssueRefPattern);
   return match ? `${canonicalRepo(match[1] ?? "", match[2] ?? "")}#${match[3]}` : value;
@@ -14729,31 +14831,54 @@ function askUrgency(args) {
   return ASK_URGENCIES.find((urgency) => urgency === value);
 }
 function parseDispatchRef(ref) {
-  const match = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)(?:\/(spec)|\/(log)|\/(children)|\/artifact\/([^/@]+)(?:@v(\d+))?|\/ask\/([^/]+)|\/comment\/([^/]+))?$/);
-  if (!match)
+  const projectDocument = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)(?:@v(\d+))?(?:\/(ask|comment)\/([^/]+))?$/);
+  if (projectDocument) {
+    const [, project, artifact, version, targetKind, targetID] = projectDocument;
+    if (project === undefined || artifact === undefined || version !== undefined && Number(version) < 1) {
+      return null;
+    }
+    if (targetKind === undefined) {
+      return {
+        owner: { kind: "project", project },
+        kind: "artifact",
+        id: artifact,
+        ...version === undefined ? {} : { version: Number(version) }
+      };
+    }
+    if (targetID === undefined || targetKind !== "ask" && targetKind !== "comment")
+      return null;
+    return {
+      owner: { kind: "project", project },
+      kind: targetKind,
+      id: targetID
+    };
+  }
+  const issueReference = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)(?:\/(spec)|\/(log)|\/(children)|\/artifact\/([^/@]+)(?:@v(\d+))?|\/ask\/([^/]+)|\/comment\/([^/]+))?$/);
+  if (!issueReference)
     return null;
-  const [, issue, spec, log, children, artifact, version, ask, comment] = match;
+  const [, issue, spec, log, children, artifact, version, ask, comment] = issueReference;
   if (!issue || version !== undefined && Number(version) < 1)
     return null;
+  const owner = { kind: "issue", issue };
   if (spec)
-    return { issue, kind: "spec", id: spec };
+    return { owner, kind: "spec", id: spec };
   if (log)
-    return { issue, kind: "log", id: log };
+    return { owner, kind: "log", id: log };
   if (children)
-    return { issue, kind: "children", id: children };
+    return { owner, kind: "children", id: children };
   if (artifact) {
     return {
-      issue,
+      owner,
       kind: "artifact",
       id: artifact,
       ...version === undefined ? {} : { version: Number(version) }
     };
   }
   if (ask)
-    return { issue, kind: "ask", id: ask };
+    return { owner, kind: "ask", id: ask };
   if (comment)
-    return { issue, kind: "comment", id: comment };
-  return { issue, kind: "issue", id: issue };
+    return { owner, kind: "comment", id: comment };
+  return { owner, kind: "issue", id: issue };
 }
 function askId(args) {
   const ask = stringArg(args, "ask");
@@ -14771,32 +14896,68 @@ function toolSchema(tool) {
     throw new Error(`Unknown Dispatch tool: ${tool}`);
   return dispatchToolSchema(spec, zodSchemaApi(exports_external), { strict: true });
 }
-async function resolveIssueArguments(tool, args, cwd, env, exec) {
-  if (issueFreeTools.has(tool))
-    return { args, ref: null };
+async function resolveOwnerArguments(tool, args, cwd, env, exec) {
+  if (issueFreeTools[tool] === true)
+    return { args, ref: null, owner: null };
   const refArgument = args.ref;
   const ref = typeof refArgument === "string" ? parseDispatchRef(refArgument) ?? (() => {
     throw new Error("ref must be a valid dispatch:// reference");
   })() : null;
   const issueArgument = args.issue;
+  const projectArgument = args.project;
   const artifactArgument = args.artifact;
   const versionArgument = args.version;
+  if (issueArgument !== undefined && projectArgument !== undefined) {
+    throw new Error("exactly one of issue and project is required");
+  }
+  if (typeof projectArgument === "string") {
+    if (!/^[A-Z][A-Z0-9]{1,9}$/.test(projectArgument)) {
+      throw new Error("project must be a project key such as CORE");
+    }
+    if (ref?.owner.kind === "project" && (ref.owner.project !== projectArgument || artifactArgument !== undefined && artifactArgument !== ref.id)) {
+      throw new Error("project and ref must name the same document");
+    }
+    return {
+      args: {
+        ...args,
+        ...artifactArgument === undefined && ref?.owner.kind === "project" ? { artifact: ref.id } : {},
+        ...versionArgument === undefined && ref?.version !== undefined ? { version: ref.version } : {}
+      },
+      ref,
+      owner: { kind: "project", project: projectArgument }
+    };
+  }
+  if (ref?.owner.kind === "project") {
+    return {
+      args: {
+        ...args,
+        project: ref.owner.project,
+        ...artifactArgument === undefined ? { artifact: ref.id } : {},
+        ...versionArgument === undefined && ref.version !== undefined ? { version: ref.version } : {}
+      },
+      ref,
+      owner: ref.owner
+    };
+  }
   if (issueArgument !== undefined || ref !== null) {
+    const issue = typeof issueArgument === "string" ? canonicalExternalIssueRef(issueArgument) : ref?.owner.kind === "issue" ? ref.owner.issue : undefined;
     return {
       args: {
         ...args,
-        ...typeof issueArgument === "string" ? { issue: canonicalExternalIssueRef(issueArgument) } : issueArgument === undefined && ref?.issue !== undefined ? { issue: ref.issue } : {},
+        ...issue === undefined ? {} : { issue },
         ...artifactArgument === undefined && (ref?.kind === "spec" || ref?.kind === "artifact") ? { artifact: ref.id } : {},
         ...versionArgument === undefined && ref?.version !== undefined ? { version: ref.version } : {}
       },
-      ref
+      ref,
+      owner: issue === undefined ? null : { kind: "issue", issue }
     };
   }
   const legionIssue = env.LEGION_ISSUE;
   if (!legionIssue)
     throw new Error("issue is required; supply issue or set LEGION_ISSUE");
   if (nativeIssueKeyPattern.test(legionIssue) || externalIssueRefPattern.test(legionIssue)) {
-    return { args: { ...args, issue: canonicalExternalIssueRef(legionIssue) }, ref: null };
+    const issue = canonicalExternalIssueRef(legionIssue);
+    return { args: { ...args, issue }, ref: null, owner: { kind: "issue", issue } };
   }
   if (!bareIssueNumberPattern.test(legionIssue)) {
     throw new Error("LEGION_ISSUE must be a native issue key (e.g. LEGION-3), an external owner/repo#n reference, or a bare positive issue number");
@@ -14804,15 +14965,25 @@ async function resolveIssueArguments(tool, args, cwd, env, exec) {
   const repo = await resolveCwdRepo(cwd, exec);
   if (!repo)
     throw new Error("issue is required; LEGION_ISSUE needs a GitHub repository in cwd");
-  return { args: { ...args, issue: `${repo}#${legionIssue}` }, ref: null };
+  const issue = `${repo}#${legionIssue}`;
+  return { args: { ...args, issue }, ref: null, owner: { kind: "issue", issue } };
 }
-async function resolveArtifact(client, issueReference, artifactReference) {
-  const issue = await client.getIssue(issueReference);
+async function resolveArtifact(client, owner, artifactReference) {
+  if (owner.kind === "project") {
+    if (artifactReference === undefined) {
+      throw new Error("artifact is required for a project document");
+    }
+    return {
+      owner,
+      artifact: await client.getProjectArtifact(owner.project, artifactReference)
+    };
+  }
+  const issue = await client.getIssue(owner.issue);
   const artifact = artifactReference === undefined || artifactReference === "spec" ? issue.artifacts.find((candidate) => candidate.primary || candidate.id === issue.primary_artifact_id) : issue.artifacts.find((candidate) => candidate.id === artifactReference || candidate.slug === artifactReference);
   if (!artifact) {
     throw new Error(`artifact ${artifactReference ?? "spec"} was not found on issue ${issue.key}`);
   }
-  return { issue, artifact };
+  return { owner, issue, artifact };
 }
 function anchor(artifact, args) {
   const quote = optionalString(args, "quote");
@@ -14832,7 +15003,7 @@ function toolActor(origin, input) {
     }
   };
 }
-function issueSummary(issue, events) {
+function issueSummary(issue, events, references) {
   const asks = issue.open_asks;
   return [
     `Title: ${issue.title}`,
@@ -14841,6 +15012,9 @@ function issueSummary(issue, events) {
     `Route: ${issue.route ?? "none"}`,
     "Open asks:",
     ...asks.length === 0 ? ["- none"] : asks.map((ask) => `- ${ask.id}: ${ask.question}`),
+    "References:",
+    ...typeof references === "string" ? [`- ${references}`] : references.members.length === 0 ? ["- none"] : references.members.map(({ artifact, depth, via }) => `- ${artifact.project}/${artifact.slug} \xB7 depth ${depth} via ${via.kind} ${via.id}`),
+    ...typeof references === "string" || !references.truncated ? [] : ["- more references beyond 8 hops"],
     "Events:",
     ...events.length === 0 ? ["- none"] : events.map((event) => `- #${event.seq} ${event.type} \xB7 ${event.actor.kind} ${event.actor.id} \xB7 ${event.created_at}`)
   ].join(`
@@ -14905,10 +15079,11 @@ function commentSummary({ comment, replies }) {
 `);
 }
 async function openArtifactMarks(client, resolved) {
-  const marks = resolved.issue.open_asks.filter((ask) => ask.state === "open" && ask.anchor?.artifact_id === resolved.artifact.id).map((ask) => `ask ${ask.id}`);
+  const asks = resolved.owner.kind === "project" ? await client.getArtifactAsks(resolved.artifact.id) : resolved.issue?.open_asks ?? [];
+  const marks = asks.filter((ask) => ask.state === "open" && ask.anchor?.artifact_id === resolved.artifact.id).map((ask) => `ask ${ask.id}`);
   let comments;
   try {
-    comments = await client.getComments(resolved.issue.key, resolved.artifact.id);
+    comments = resolved.owner.kind === "project" ? await client.getArtifactComments(resolved.artifact.id) : await client.getComments(resolved.issue?.key ?? "", resolved.artifact.id);
   } catch (error) {
     if (error instanceof DispatchServiceError && error.status === 404)
       return marks;
@@ -14927,15 +15102,23 @@ async function executeDispatchTool(input) {
   }
   const env = input.env ?? process.env;
   const exec = input.exec ?? defaultExec;
-  const issueArguments = await resolveIssueArguments(input.tool, input.args, input.cwd, env, exec);
-  const args = toolSchema(input.tool).parse(issueArguments.args);
+  const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec);
+  const args = toolSchema(input.tool).parse(ownerArguments.args);
   const actor = toolActor(await resolveOrigin(env, exec, input.cwd), input);
   const client = new DispatchClient(configUrl, configToken, input.fetchImpl);
-  const issueKey = issueFreeTools.has(input.tool) ? null : await ensureIssue(client, stringArg(args, "issue"), actor);
+  const owner = ownerArguments.owner?.kind === "issue" ? {
+    kind: "issue",
+    issue: await ensureIssue(client, ownerArguments.owner.issue, actor)
+  } : ownerArguments.owner;
   const issue = () => {
-    if (issueKey === null)
+    if (owner?.kind !== "issue")
       throw new Error("issue is required");
-    return issueKey;
+    return owner.issue;
+  };
+  const documentOwner = () => {
+    if (owner === null)
+      throw new Error("issue or project is required");
+    return owner;
   };
   switch (input.tool) {
     case "dispatch_issue": {
@@ -15015,22 +15198,25 @@ async function executeDispatchTool(input) {
     }
     case "dispatch_ask": {
       const anchorArgs = asObject(args.anchor);
-      const resolved = anchorArgs ? await resolveArtifact(client, issue(), stringArg(anchorArgs, "artifact")) : undefined;
+      const owner = documentOwner();
+      const artifactReference = optionalString(args, "artifact") ?? (anchorArgs === null ? undefined : optionalString(anchorArgs, "artifact"));
+      const resolved = owner.kind === "project" || artifactReference === undefined ? owner.kind === "project" ? await resolveArtifact(client, owner, artifactReference) : undefined : await resolveArtifact(client, owner, artifactReference);
       const options = args.options;
       const multiple = optionalBoolean(args, "multiple");
       const urgency = askUrgency(args);
       const anchored = anchorArgs && resolved ? anchor(resolved.artifact, anchorArgs) : undefined;
-      const ask = await client.ask(issue(), {
+      const askInput = {
         question: stringArg(args, "question"),
         ...Array.isArray(options) ? { options } : {},
         ...multiple === undefined ? {} : { multiple },
         ...urgency === undefined ? {} : { urgency },
         ...anchored === undefined ? {} : { anchor: anchored },
         actor
-      });
+      };
+      const ask = resolved?.owner.kind === "project" ? await client.artifactAsk(resolved.artifact.id, askInput) : await client.ask(issue(), askInput);
       return {
         text: `Opened ask ${ask.id}: ${ask.question}`,
-        details: await askResultDetails(client, ask)
+        details: await askResultDetails(client, ask, resolved)
       };
     }
     case "dispatch_edit_ask": {
@@ -15055,48 +15241,47 @@ async function executeDispatchTool(input) {
       if (optionalString(args, "quote") !== undefined && artifactReference === undefined) {
         throw new Error("artifact is required when quote is supplied");
       }
-      const resolved = artifactReference ? await resolveArtifact(client, issue(), artifactReference) : undefined;
+      const owner = documentOwner();
+      const resolved = owner.kind === "project" || artifactReference === undefined ? owner.kind === "project" ? await resolveArtifact(client, owner, artifactReference) : undefined : await resolveArtifact(client, owner, artifactReference);
       const anchored = resolved ? anchor(resolved.artifact, args) : undefined;
       const replyTo = optionalString(args, "reply_to");
       const replyToAsk = optionalString(args, "reply_to_ask");
       if (replyTo !== undefined && replyToAsk !== undefined) {
         throw new Error("reply_to and reply_to_ask cannot both be set");
       }
-      const comment = await client.comment(issue(), {
+      const commentInput = {
         body: stringArg(args, "body"),
         ...anchored === undefined ? {} : { anchor: anchored },
         ...replyTo === undefined ? {} : { reply_to: replyTo },
         ...replyToAsk === undefined ? {} : { ask_id: replyToAsk },
         actor
-      });
+      };
+      const comment = resolved?.owner.kind === "project" ? await client.artifactComment(resolved.artifact.id, commentInput) : await client.comment(issue(), commentInput);
       return {
         text: `Posted comment ${comment.id}`,
-        details: {
+        details: resolved === undefined ? {
           issue: comment.issue_key,
-          topic: dispatchIssueSubject(comment.issue_key, ">"),
+          topic: dispatchIssueSubject(issue(), ">"),
           comment: comment.id
-        }
+        } : writeResultDetails(resolved, { comment: comment.id })
       };
     }
     case "dispatch_suggest": {
-      const resolved = await resolveArtifact(client, issue(), stringArg(args, "artifact"));
+      const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
       const anchored = anchor(resolved.artifact, args);
       if (anchored === undefined)
         throw new Error("quote is required");
       const body = optionalString(args, "body");
-      const comment = await client.suggest(issue(), {
+      const suggestionInput = {
         ...body === undefined ? {} : { body },
         anchor: anchored,
         replace_with: stringArg(args, "replace_with"),
         actor
-      });
+      };
+      const comment = resolved.owner.kind === "project" ? await client.artifactSuggest(resolved.artifact.id, suggestionInput) : await client.suggest(issue(), suggestionInput);
       return {
         text: `Posted suggestion ${comment.id}`,
-        details: {
-          issue: comment.issue_key,
-          topic: dispatchIssueSubject(comment.issue_key, ">"),
-          comment: comment.id
-        }
+        details: writeResultDetails(resolved, { comment: comment.id })
       };
     }
     case "dispatch_message": {
@@ -15111,7 +15296,7 @@ async function executeDispatchTool(input) {
       };
     }
     case "dispatch_doc_edit": {
-      const resolved = await resolveArtifact(client, issue(), stringArg(args, "artifact"));
+      const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
       const ops = args.ops;
       const summary = optionalString(args, "summary");
       const edited = await client.docEdit(resolved.artifact.id, {
@@ -15121,32 +15306,33 @@ async function executeDispatchTool(input) {
       });
       return {
         text: edited.version === null ? `Applied ${edited.applied} ops (no new version)` : `Applied ${edited.applied} ops (version ${edited.version.number})`,
-        details: {
-          issue: resolved.issue.key,
-          topic: dispatchIssueSubject(resolved.issue.key, ">"),
+        details: writeResultDetails(resolved, {
           applied: edited.applied,
           ...edited.version === null ? {} : { version: edited.version.number }
-        }
+        })
       };
     }
     case "dispatch_doc_read": {
-      const artifactReference = optionalString(args, "artifact") ?? (issueArguments.ref?.kind === "spec" || issueArguments.ref?.kind === "artifact" ? issueArguments.ref.id : undefined);
-      const resolved = await resolveArtifact(client, issue(), artifactReference);
-      const version = optionalNumber(args, "version") ?? issueArguments.ref?.version;
+      const artifactReference = optionalString(args, "artifact") ?? (ownerArguments.ref?.kind === "spec" || ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : undefined);
+      const resolved = await resolveArtifact(client, documentOwner(), artifactReference);
+      const version = optionalNumber(args, "version") ?? ownerArguments.ref?.version;
       const document = await client.docRead(resolved.artifact.id, version);
       const marks = await openArtifactMarks(client, resolved);
       return {
         text: marks.length === 0 ? document.markdown : `${document.markdown}
 
 Open anchored asks/comments: ${marks.join(", ")}`,
-        details: { issue: resolved.issue.key }
+        details: resolved.owner.kind === "project" ? {
+          project: resolved.artifact.project,
+          document: `${resolved.artifact.project}/${resolved.artifact.slug}`
+        } : { issue: resolved.issue?.key }
       };
     }
     case "dispatch_artifact": {
       const summary = optionalString(args, "summary");
       const name = stringArg(args, "name");
       const content = optionalString(args, "content");
-      const result = await client.artifact(issue(), content === undefined ? {
+      const artifactInput = content === undefined ? {
         name,
         file: Bun.file(resolvePath(input.cwd, stringArg(args, "path"))),
         ...summary === undefined ? {} : { summary },
@@ -15156,47 +15342,73 @@ Open anchored asks/comments: ${marks.join(", ")}`,
         content,
         ...summary === undefined ? {} : { summary },
         actor
-      });
+      };
+      const artifactOwner = documentOwner();
+      const result = artifactOwner.kind === "project" ? await client.projectArtifact(artifactOwner.project, artifactInput) : await client.artifact(issue(), artifactInput);
       return {
         text: `Uploaded ${result.artifact.name} as version ${result.version.number}`,
-        details: {
-          issue: result.artifact.issue_key,
-          topic: dispatchIssueSubject(result.artifact.issue_key, ">"),
+        details: artifactOwner.kind === "project" ? {
+          ...documentResultDetails(result.artifact),
+          version: result.version.number
+        } : {
+          issue: issue(),
+          topic: dispatchIssueSubject(issue(), ">"),
           artifact: result.artifact.id,
           version: result.version.number
         }
       };
     }
     case "dispatch_read": {
-      if (issueArguments.ref?.kind === "ask") {
-        const askRead = await client.getAsk(issueArguments.ref.id);
+      if (ownerArguments.ref?.kind === "ask") {
+        const askRead = await client.getAsk(ownerArguments.ref.id);
         return {
           text: askSummary(askRead),
-          details: { issue: issueArguments.ref.issue }
+          details: ownerArguments.ref.owner.kind === "project" ? { project: ownerArguments.ref.owner.project } : { issue: ownerArguments.ref.owner.issue }
         };
       }
-      if (issueArguments.ref?.kind === "comment") {
-        const comment = await client.getComment(issueArguments.ref.id);
+      if (ownerArguments.ref?.kind === "comment") {
+        const comment = await client.getComment(ownerArguments.ref.id);
         return {
           text: commentSummary(comment),
-          details: { issue: comment.comment.issue_key }
+          details: ownerArguments.ref.owner.kind === "project" ? { project: ownerArguments.ref.owner.project } : { issue: comment.comment.issue_key }
+        };
+      }
+      if (documentOwner().kind === "project") {
+        const resolved = await resolveArtifact(client, documentOwner(), stringArg(args, "artifact"));
+        return {
+          text: [
+            `Document: ${resolved.artifact.project} / ${resolved.artifact.name}`,
+            `Reference: dispatch://${resolved.artifact.project}/artifact/${resolved.artifact.slug}`,
+            `Versions: ${resolved.artifact.versions.length}`
+          ].join(`
+`),
+          details: {
+            project: resolved.artifact.project,
+            document: `${resolved.artifact.project}/${resolved.artifact.slug}`
+          }
         };
       }
       const read = await client.read(issue());
-      if (issueArguments.ref?.kind === "log") {
+      if (ownerArguments.ref?.kind === "log") {
         return {
           text: logSummary(read.issue, read.events),
           details: { issue: read.issue.key }
         };
       }
-      if (issueArguments.ref?.kind === "children") {
+      if (ownerArguments.ref?.kind === "children") {
         return {
           text: childrenSummary(read.issue),
           details: { issue: read.issue.key }
         };
       }
+      let references;
+      try {
+        references = await client.getIssueReferences(read.issue.key);
+      } catch (error) {
+        references = error instanceof DispatchServiceError && error.status === 404 ? "unavailable" : `unavailable: ${error instanceof Error ? error.message : String(error)}`;
+      }
       return {
-        text: issueSummary(read.issue, read.events),
+        text: issueSummary(read.issue, read.events, references),
         details: { issue: read.issue.key }
       };
     }

package/package.json

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

package/skills/dispatch/SKILL.md

@@ -44,13 +44,16 @@ transcript of your thinking. Use exactly these document headings in this order.
 - [ ] The spec covers one implementation plan's worth of work.
 - [ ] Every requirement has exactly one reading.
 
-## Your issue
+## Your owner
 
-Every session works on an issue. Legion pre-fills `issue` from `LEGION_ISSUE`: use a native issue key
-such as `LEGION-3`, an external `owner/repo#n` reference, or a bare positive number (resolved
-against the cwd repository). Otherwise pass the issue to every issue-scoped tool as its native key
-or an external `owner/repo#n` reference. On first use, an external reference creates its native issue in the
-project configured for that repository in Dispatch Settings, then falls back to `DISPATCH_DEFAULT_PROJECT`.
+Every session works on an issue or project document. Legion pre-fills `issue` from
+`LEGION_ISSUE`: use a native issue key such as `LEGION-3`, an external `owner/repo#n`
+reference, or a bare positive number (resolved against the cwd repository). Otherwise pass
+exactly one owner to every owner-scoped tool: `issue` for an issue, or `project` and
+`artifact` for an unlinked project document. A project key such as `CORE` with artifact
+`design-notes` identifies `dispatch://CORE/artifact/design-notes`. 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`.
 
 Architects create newly tracked child work with:
 ```ts
@@ -78,7 +81,9 @@ call with `force: true` when it is genuinely new work.
 Open a decision with:
 ```ts
 dispatch_ask({
-  issue,
+  issue?,
+  project?,
+  artifact?,
   question,
   options?: { label, description? }[],
   multiple?,
@@ -86,7 +91,8 @@ dispatch_ask({
   anchor?: { artifact, quote, occurrence? },
 })
 ```
-It returns `details` `{ issue, topic, ask }`. Options are buttons: never enumerate choices in
+It returns `details` `{ issue, topic, ask }` for an issue or `{ project, artifact, document,
+topic, ask }` for a project document. Options are buttons: never enumerate choices in
 prose. Put the recommendation in `question`, and put each selectable choice in `options`.
 Anchor a document question with `anchor: { artifact, quote, occurrence? }`; `occurrence` is
 zero-based and selects a repeated quote. The server writes the resulting mark. The HTTP API also
@@ -132,16 +138,16 @@ Write and update the issue specification according to [Writing a spec](#writing-
 Read the current document before changing it:
 
 ```ts
-dispatch_doc_read({ issue?, artifact?, version?, ref? })
+dispatch_doc_read({ issue?, project?, artifact?, version?, ref? })
 ```
-It returns live or versioned markdown with open marks and `details` `{ issue }`; omit `artifact`
-with `issue` to read the issue specification. Then write narrative with:
-
+It returns live or versioned markdown with open marks. `issue` with an omitted `artifact`
+reads the issue specification; a project needs `artifact`; and a
+`dispatch://PROJECT/artifact/<slug>` ref supplies both. Then write narrative with:
 ```ts
-dispatch_doc_edit({ issue, artifact, ops, summary? })
+dispatch_doc_edit({ issue?, project?, artifact, ops, summary? })
 ```
-It returns `details` `{ issue, topic, applied, version? }`. `ops` is an array of this exact
-`EditOp` shape:
+It returns issue or project-document owner details plus `applied`, optional `version`, and its
+write `topic`. `ops` is an array of this exact `EditOp` shape:
 
 ```ts
 type EditOp = {
@@ -171,23 +177,24 @@ into a message.
 Add feedback with:
 
 ```ts
-dispatch_comment({ issue, artifact?, quote?, occurrence?, body, reply_to?, reply_to_ask? })
+dispatch_comment({ issue?, project?, artifact?, quote?, occurrence?, body, reply_to?, reply_to_ask? })
 ```
 
-It returns `details` `{ issue, topic, comment }`. `quote` requires `artifact`; omit both for a
-floating issue comment. A reply (`reply_to`/`reply_to_ask`) takes no `quote`; it belongs to its
-parent's anchor. Use `reply_to` to continue a comment thread at its root; a reply to a resolved
-thread reopens it. Use `reply_to_ask` to reply directly under a question asked with
-`dispatch_ask`. The two are mutually exclusive. Comments are edited only by their author from the
-dashboard.
+It returns issue or project-document owner details plus `comment` and, for writes, `topic`.
+`quote` requires `artifact`; omit both for a floating issue comment. A reply
+(`reply_to`/`reply_to_ask`) takes no `quote`; it belongs to its parent's anchor. Use `reply_to`
+to continue a comment thread at its root; a reply to a resolved thread reopens it. Use
+`reply_to_ask` to reply directly under a question asked with `dispatch_ask`. The two are
+mutually exclusive. Comments are edited only by their author from the dashboard.
 
 Propose an exact replacement instead of describing it:
 
 ```ts
-dispatch_suggest({ issue, artifact, quote, replace_with, body?, occurrence? })
+dispatch_suggest({ issue?, project?, artifact, quote, replace_with, body?, occurrence? })
 ```
 
-It returns `details` `{ issue, topic, comment }`. A human accepts or rejects a suggestion. On
+It returns issue or project-document owner details plus `comment` and its write `topic`. A
+human accepts or rejects a suggestion. On
 `TARGET_AMBIGUOUS`, add zero-based `occurrence`. On `TARGET_NOT_FOUND`, re-read the document
 before retrying. `INVALID_ANCHOR` requires exactly one nonempty anchor `quote` or `mark_id`;
 `ANCHOR_MISSING` means a browser mark was not observed in the live tree, and
@@ -201,19 +208,20 @@ reject an invalid actor or route.
 Attach an image, diagram, or local file with:
 
 ```ts
-dispatch_artifact({ issue, name, path, summary? })
+dispatch_artifact({ issue?, project?, name, path, summary? })
 ```
 
 Or, when the text is already in the call, post a Markdown document directly:
 
 ```ts
-dispatch_artifact({ issue, name: "spec.md", content: "# Design\n..." })
+dispatch_artifact({ issue?, project?, name: "spec.md", content: "# Design\n..." })
 ```
 
-Exactly one of `path` and `content` is required. The inline form sends JSON with
-`Content-Type: application/json`. It returns `details` `{ issue, topic, artifact, version }`.
-Uploading the same `name` creates its next version. Use `content` when the text is already in
-the call.
+Exactly one of `issue` and `project` is required. A project upload creates an unlinked project
+document; it must not include `artifact`. Exactly one of `path` and `content` is required. The
+inline form sends JSON with `Content-Type: application/json`. It returns issue or
+project-document owner details plus `artifact`, `version`, and its write `topic`. Uploading the
+same `name` creates its next version. Use `content` when the text is already in the call.
 
 ## Messages
 
@@ -228,23 +236,20 @@ message does not wake anyone. Do not use it for status, a decision, or document
 
 ## What comes back
 
-A write result's `details.topic` subscribes the host to the issue. Events render as:
-
-```text
-dispatch <KEY> · <type> · by <actor>
-```
-
-The issue topic carries every Dispatch event; `notify` only controls agent wake and routed delivery.
-After a restart, catch up with:
+A write result's `details.topic` subscribes the host to its owner. Issue writes use
+`notifications.dispatch.issue.<KEY>.>`; project-document writes use
+`notifications.dispatch.document.<PROJECT>.<SLUG>.>`. The owner topic carries every Dispatch
+event; `notify` only controls agent wake and routed delivery. After a restart, catch up with:
 
 ```ts
-dispatch_read({ issue?, ref? })
+dispatch_read({ issue?, project?, artifact?, ref? })
 ```
 
-With an issue ref, it returns the issue summary, open asks, and recent events with `details`
-`{ issue }`. With an ask ref, it returns that ask's question, options, state, answer, and its
-reply thread. With a comment ref, it returns that comment and its quoted reply chain. Use
-`dispatch_doc_read` for document contents.
+With an issue ref, it returns the issue summary, open asks, references, and recent events with
+`details` `{ issue }`. With a project document owner or ref, it returns a document summary with
+`details` `{ project, document }`. With an ask ref, it returns that ask's question, options,
+state, answer, and its reply thread. With a comment ref, it returns that comment and its quoted
+reply chain. Reads do not subscribe; use `dispatch_doc_read` for document contents.
 
 ## References
 
@@ -256,6 +261,9 @@ dispatch://KEY/spec
 dispatch://KEY/artifact/<slug>[@vN]
 dispatch://KEY/ask/<id>
 dispatch://KEY/comment/<id>
+dispatch://PROJECT/artifact/<slug>[@vN]
+dispatch://PROJECT/artifact/<slug>/ask/<id>
+dispatch://PROJECT/artifact/<slug>/comment/<id>
 ```
 
 ## Before / after