@sjawhar/pi-legion-envoy 7.2.0 → 7.2.2

package/dist/envoy.js

@@ -30349,7 +30349,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_doc_read",
     example: { issue: "DSP-1" },
-    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. " + "A live read returns its document token for an optional dispatch_doc_edit precondition; use /blocks for per-block tokens. " + OWNER_REFERENCE,
+    description: "Read a live document or a named document version, or the text of an uploaded file at its latest or named 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. " + "A live read returns its document token for an optional dispatch_doc_edit precondition; use /blocks for per-block tokens. " + "A file that is not UTF-8 text is described, with the route that serves its bytes. " + OWNER_REFERENCE,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
@@ -32356,6 +32356,20 @@ class DispatchClient {
   async docRead(id, version2) {
     return version2 === undefined ? this.#json("GET", ["api", "v1", "artifacts", id, "text"]) : this.#json("GET", ["api", "v1", "artifacts", id, "versions", String(version2)]);
   }
+  async fileVersion(id, version2) {
+    const url2 = this.#url(["api", "v1", "artifacts", id, "versions", String(version2)]);
+    const response = await this.fetchImpl(url2, {
+      method: "GET",
+      headers: { Accept: "*/*", Authorization: `Bearer ${this.token}` },
+      signal: this.#signal
+    });
+    if (!response.ok)
+      return this.#response("GET", url2, response);
+    return {
+      mime: response.headers.get("Content-Type") ?? "application/octet-stream",
+      bytes: new Uint8Array(await response.arrayBuffer())
+    };
+  }
   async artifactBlocks(id) {
     return this.#json("GET", ["api", "v1", "artifacts", id, "blocks"]);
   }
@@ -33618,6 +33632,30 @@ async function blockAsks(client, resolved, state) {
   const asks = await (resolved.issue === undefined ? client.getArtifactAsks(resolved.artifact.id, state) : client.listIssueAsks(resolved.issue.key, state));
   return asks.filter((ask) => typeof ask.block_id === "string" && ask.block_artifact?.id === resolved.artifact.id);
 }
+async function readUploadedFile(client, resolved, requested) {
+  const { artifact } = resolved;
+  const latest = Math.max(0, ...artifact.versions.map((version2) => version2.number));
+  const number4 = requested ?? latest;
+  const file2 = await client.fileVersion(artifact.id, number4);
+  const of = number4 === latest ? "" : ` of ${latest}`;
+  const size = `${file2.bytes.length.toLocaleString("en-US")} bytes`;
+  const details = resolved.owner.kind === "project" ? { project: artifact.project, document: documentLabel(artifact.project, artifact.slug) } : { issue: resolved.issue?.key };
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(file2.bytes);
+  } catch {
+    return {
+      text: `${artifact.name} is an uploaded ${file2.mime} file (version ${number4}${of}, ${size}) that is not ` + `UTF-8 text, so dispatch_doc_read cannot show it. GET /api/v1/artifacts/${artifact.id}/versions/${number4} serves its bytes.`,
+      details
+    };
+  }
+  return {
+    text: `File ${artifact.name}: ${file2.mime}, version ${number4}${of}, ${size}.
+
+${text}`,
+    details
+  };
+}
 async function refuseOpenDecisionBlocks(client, tool, resolved) {
   const artifact = resolved.artifact;
   const latest = artifact.approval?.latest_version;
@@ -34315,6 +34353,9 @@ ${followsAsk(askOwner)}`,
       const artifactReference = optionalString(args, "artifact") ?? (ownerArguments.ref?.kind === "spec" || ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : undefined);
       const resolved = await resolveDocument(documentOwner(), artifactReference);
       const version2 = optionalNumber(args, "version") ?? ownerArguments.ref?.version;
+      if (resolved.artifact.kind === "file" || resolved.artifact.kind === "image") {
+        return readUploadedFile(client, resolved, version2);
+      }
       const documentPromise = client.docRead(resolved.artifact.id, version2);
       const marksPromise = openArtifactMarks(client, resolved);
       const marksResultPromise = marksPromise.then((value) => ({ status: "fulfilled", value }), (reason) => ({ status: "rejected", reason }));

package/dist/legion.js

@@ -14436,7 +14436,7 @@ var dispatchToolSpecs = [
   {
     name: "dispatch_doc_read",
     example: { issue: "DSP-1" },
-    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. " + "A live read returns its document token for an optional dispatch_doc_edit precondition; use /blocks for per-block tokens. " + OWNER_REFERENCE,
+    description: "Read a live document or a named document version, or the text of an uploaded file at its latest or named 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. " + "A live read returns its document token for an optional dispatch_doc_edit precondition; use /blocks for per-block tokens. " + "A file that is not UTF-8 text is described, with the route that serves its bytes. " + OWNER_REFERENCE,
     arguments: (z2) => ({
       issue: z2.string().describe(ISSUE_REFERENCE).optional(),
       project: z2.string().describe("Project key owning the document.").optional(),
@@ -15118,6 +15118,20 @@ class DispatchClient {
   async docRead(id, version2) {
     return version2 === undefined ? this.#json("GET", ["api", "v1", "artifacts", id, "text"]) : this.#json("GET", ["api", "v1", "artifacts", id, "versions", String(version2)]);
   }
+  async fileVersion(id, version2) {
+    const url2 = this.#url(["api", "v1", "artifacts", id, "versions", String(version2)]);
+    const response = await this.fetchImpl(url2, {
+      method: "GET",
+      headers: { Accept: "*/*", Authorization: `Bearer ${this.token}` },
+      signal: this.#signal
+    });
+    if (!response.ok)
+      return this.#response("GET", url2, response);
+    return {
+      mime: response.headers.get("Content-Type") ?? "application/octet-stream",
+      bytes: new Uint8Array(await response.arrayBuffer())
+    };
+  }
   async artifactBlocks(id) {
     return this.#json("GET", ["api", "v1", "artifacts", id, "blocks"]);
   }
@@ -16403,6 +16417,30 @@ async function blockAsks(client, resolved, state) {
   const asks = await (resolved.issue === undefined ? client.getArtifactAsks(resolved.artifact.id, state) : client.listIssueAsks(resolved.issue.key, state));
   return asks.filter((ask) => typeof ask.block_id === "string" && ask.block_artifact?.id === resolved.artifact.id);
 }
+async function readUploadedFile(client, resolved, requested) {
+  const { artifact } = resolved;
+  const latest = Math.max(0, ...artifact.versions.map((version2) => version2.number));
+  const number4 = requested ?? latest;
+  const file2 = await client.fileVersion(artifact.id, number4);
+  const of = number4 === latest ? "" : ` of ${latest}`;
+  const size = `${file2.bytes.length.toLocaleString("en-US")} bytes`;
+  const details = resolved.owner.kind === "project" ? { project: artifact.project, document: documentLabel(artifact.project, artifact.slug) } : { issue: resolved.issue?.key };
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(file2.bytes);
+  } catch {
+    return {
+      text: `${artifact.name} is an uploaded ${file2.mime} file (version ${number4}${of}, ${size}) that is not ` + `UTF-8 text, so dispatch_doc_read cannot show it. GET /api/v1/artifacts/${artifact.id}/versions/${number4} serves its bytes.`,
+      details
+    };
+  }
+  return {
+    text: `File ${artifact.name}: ${file2.mime}, version ${number4}${of}, ${size}.
+
+${text}`,
+    details
+  };
+}
 async function refuseOpenDecisionBlocks(client, tool, resolved) {
   const artifact = resolved.artifact;
   const latest = artifact.approval?.latest_version;
@@ -17100,6 +17138,9 @@ ${followsAsk(askOwner)}`,
       const artifactReference = optionalString(args, "artifact") ?? (ownerArguments.ref?.kind === "spec" || ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : undefined);
       const resolved = await resolveDocument(documentOwner(), artifactReference);
       const version2 = optionalNumber(args, "version") ?? ownerArguments.ref?.version;
+      if (resolved.artifact.kind === "file" || resolved.artifact.kind === "image") {
+        return readUploadedFile(client, resolved, version2);
+      }
       const documentPromise = client.docRead(resolved.artifact.id, version2);
       const marksPromise = openArtifactMarks(client, resolved);
       const marksResultPromise = marksPromise.then((value) => ({ status: "fulfilled", value }), (reason) => ({ status: "rejected", reason }));
@@ -17418,7 +17459,7 @@ function endInjectedUserTurns(sessionID) {
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion-envoy",
-  version: "7.2.0",
+  version: "7.2.2",
   license: "Apache-2.0",
   type: "module",
   omp: {

package/dist/skills/dispatch/SKILL.md

@@ -418,10 +418,10 @@ Read the current document before changing it:
 ```ts
 dispatch_doc_read({ issue?, project?, artifact?, version?, ref? })
 ```
-It returns live or versioned markdown with open marks. A live read ends with a document token; `issue` with an
-omitted `artifact` reads the issue specification; a project needs `artifact`; and a
-`dispatch://PROJECT/artifact/<document-ref>` ref supplies both, where `document-ref` is the slug (an id or a
-filename resolves when no document has that slug).
+It returns live or versioned markdown with open marks. A live read ends with a document token; `issue` with an omitted
+`artifact` reads the issue specification; a project needs `artifact`; and a `dispatch://PROJECT/artifact/<document-ref>`
+ref supplies both, where `document-ref` is the slug (an id or a filename resolves when no document has that slug). A file
+`dispatch_artifact` uploaded reads its text at the latest or named version, or a description when it is not UTF-8 text.
 
 Editing one is [Editing a document](skill://dispatch/references/document-edits.md): the shape of `dispatch_doc_edit`,
 how to quote the text you mean, one `replace` per paragraph, preconditions against a stale edit, and

package/dist/skills/legion-worker/SKILL.md

@@ -304,8 +304,8 @@ line), the full definition of a proof, what the tester verifies, and the simplif
 
 - **Review threads** are disposed of one by one, never in bulk, and only an `Accepted:` from the
   thread's opener (or, on a bot's thread, from the Legion reviewer) closes one. The implementer
-  runs `legion threads resolve` before every push that answers a review, and the merger before
-  READY: `skill://legion-worker/references/review-threads.md`.
+  runs `legion threads resolve` after every push that answers a review, before its completion,
+  and the merger before READY: `skill://legion-worker/references/review-threads.md`.
 - **No deferrals.** A finding that changes
   behaviour, hides an error, or breaks a gate is fixed in this pull request; naming, duplication,
   or wording cleanup is batched into the one `Fast-follow:` line instead of iterating per push.

package/dist/skills/legion-worker/references/merge-gate.md

@@ -39,7 +39,7 @@ confirmation or a new round, as the fingerprint decides (*The reviewer*, below,
   nothing restarts. Different: a new round — thermo again, one review.
 - Answer every thread you opened, and every thread a bot opened that is none of Legion's role
   Apps, as `skill://legion-worker/references/review-threads.md` says; the same reference says
-  when every thread is settled enough to approve.
+  when every thread is settled enough to approve, and resolving one never gates your approval.
 
 A reviewer's phase ends with its completion, not with its review. A round that writes a handoff
 takes this order: write, commit and push the handoff; submit the review of the head that push

package/dist/skills/legion-worker/references/pr-body.md

@@ -29,7 +29,7 @@ later phase keeps it current rather than replacing it:
 **Threads:** <n> resolved, 0 unresolved. Each disposed individually, never in bulk:
 - Thread <id>: fixed in <commit-sha> — <one line>.
 - Thread <id>: not a defect — <reason>.
-`legion threads resolve --pr <n> --repo <owner>/<repo>` at <head-sha>:
+`legion threads resolve --pr <n> --repo <owner>/<repo>`, run after the push that made <head-sha>:
 resolved <thread URL> — its opener's acceptance
 resolved <thread URL> — the Legion reviewer's acceptance of a bot's thread
 left open <thread URL> — newest reply by <login> is not an acceptance

package/dist/skills/legion-worker/references/review-threads.md

@@ -1,8 +1,9 @@
 # Review threads
 
 Part of `skill://legion-worker`. Read it when you reply to, accept, or resolve a review thread,
-or run `legion threads resolve`: the implementer before every push that answers a review, the
-reviewer on every re-review, the merger before READY. Every path it cites is in sjawhar/legion.
+or run `legion threads resolve`: the implementer after every push that answers a review, the
+merger before READY, and the reviewer, who answers threads on every re-review and runs nothing.
+Every path it cites is in sjawhar/legion.
 
 - **Threads are dispositioned individually, never resolved in bulk.** Every open review
   thread gets its own line naming the fixing commit or the reason it isn't a defect. The
@@ -19,16 +20,19 @@ reviewer on every re-review, the merger before READY. Every path it cites is in
   When neither is set, add `--gh` to that command, which applies the fallback's rule below through
   your own `gh`; where no `legion` command is installed, use `gh api graphql` with the session's
   GitHub credential and the fallback below.
-  In a Legion pane, the **implementer** runs the command before every push that answers a review
-  (the corrective push and the final `.legion/` deletion push) and pastes its output into the
-  `Threads` section. The command resolves each unresolved thread whose newest submitted comment is
-  the opener's own `Accepted:` reply. On a thread a bot account opened that is none of Legion's
-  role Apps (the daemon names them, keyed by App role), the Legion reviewer's `Accepted:` also
-  closes it. GitHub cannot tell a CI bot, which never accepts, from a person whose `gh` is routed
-  to an App, so the reviewer adjudicates such a finding, and it may accept one an App-routed person
-  raised. The subject of a finding never closes it: the implementer's `Fixed in <commit>: …` or
-  `Declined: …` answers a thread and closes none. A thread either Legion App opened, a reviewer's
-  finding included, still needs its opener's `Accepted:`. It makes one `resolveReviewThread` per
+  In a Legion pane, the **implementer** runs the command after every push that answers a review
+  (the corrective push, and the final `.legion/` deletion push where the daemon has one) and
+  before its `handoff_complete`, and pastes its output, stamped with the head it just pushed, into
+  the `Threads` section. The output is then recorded against the head the reviewer will read, and
+  nothing reads thread state before the implementer's completion. The command resolves each
+  unresolved thread whose newest submitted comment is the opener's own `Accepted:` reply. On a
+  thread a bot account opened that is none of Legion's role Apps (the daemon names them, keyed by
+  App role), the Legion reviewer's `Accepted:` also closes it. GitHub cannot tell a CI bot, which
+  never accepts, from a person whose `gh` is routed to an App, so the reviewer adjudicates such a
+  finding, and it may accept one an App-routed person raised. The subject of a finding never
+  closes it: the implementer's `Fixed in <commit>: …` or `Declined: …` answers a thread and closes
+  none. A thread either Legion App opened, a reviewer's finding included, still needs its opener's
+  `Accepted:`. It makes one `resolveReviewThread` per
   thread, prints `resolved <url> — <whose acceptance>` (its opener's, or the Legion reviewer's on a
   bot's thread, so the ledger shows which) or `left open <url> — newest reply by <login> is …`
   naming why, and exits 1 naming the thread's URL and GitHub's message when GitHub refuses one.
@@ -63,10 +67,18 @@ reviewer on every re-review, the merger before READY. Every path it cites is in
   Re-read `reviewThreads` and confirm that thread's `isResolved` is true. In either route, report
   a refused resolution to the architect, which opens an ask for a human to resolve the thread by
   hand — never skip it silently. The merger runs the command once more before publishing READY
-  and does not publish while any `left open` line remains.
+  and does not publish while any `left open` line remains. That run is where every accepted
+  thread's resolution is guaranteed, since the merge queue's gate counts the unresolved threads at
+  the head. Acceptances posted after the implementer's last run are resolved here.
 
 - **The reviewer, on a re-review.** When you re-review after a corrective push, answer every
-  thread you opened in one of the three forms above — `Accepted:` is the only reply the
-  implementer's `legion threads resolve` acts on — and approve only once every thread you opened
-  carries your `Accepted:` reply and the implementer's run has resolved it (verify
-  `isResolved: true` with `gh api graphql`, never from the PR body).
+  thread you opened, and every thread a bot opened that is none of Legion's role Apps, in one of
+  the three forms above — `Accepted:` is the only reply `legion threads resolve` acts on. A bot's
+  finding you cannot accept becomes your own: leave it `Still open:` and request changes.
+  Approve once each of those threads has your own `Accepted:` as its newest submitted comment,
+  whether or not GitHub shows the thread resolved yet, and every other unresolved thread its
+  opener's (read the newest comments with `gh api graphql`, never from the PR body). Another
+  opener's thread that a person resolved with GitHub's button, with no `Accepted:`, gates nothing:
+  neither `legion threads resolve` nor the merge queue's gate counts a resolved thread. Resolution
+  is the pull request author's App's, so your approval never waits on it. The merger resolves
+  accepted threads that remain open before publishing READY.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-legion-envoy",
-  "version": "7.2.0",
+  "version": "7.2.2",
   "license": "Apache-2.0",
   "type": "module",
   "omp": {