@sjawhar/pi-envoy 17.0.0 → 17.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -317,10 +317,12 @@ The shared specs in `@legion/contracts` supply each command's description and fl
317
317
  `@legion/envoy-client`'s `dispatch-command.ts` derives one command per spec and one flag per field.
318
318
 
319
319
  `dispatch artifact` takes exactly one upload source: a local `--path`, or inline `--content`. For
320
- example, an architect can post a specification directly, its text on stdin:
320
+ example, an architect can post a specification directly, its text on stdin. Every issue is created
321
+ with a `spec.md`, and the command refuses an upload under the name of a document the issue already
322
+ holds, so this one carries `--force`, which writes the next version of it:
321
323
 
322
324
  ```sh
323
- dispatch artifact --issue LEGION-1 --name spec.md --content-file - <<'EOF'
325
+ dispatch artifact --issue LEGION-1 --name spec.md --content-file - --force <<'EOF'
324
326
  # Design
325
327
  EOF
326
328
  ```
package/dist/dispatch.js CHANGED
@@ -972,8 +972,17 @@ import {
972
972
  import { isAbsolute, join, resolve } from "path";
973
973
 
974
974
  // ../envoy-client/src/errors.ts
975
+ function dispatchCode(error) {
976
+ if (!("fromDispatch" in error) || !("code" in error))
977
+ return;
978
+ const code = error.code;
979
+ return typeof code === "string" && code !== "" ? code : undefined;
980
+ }
975
981
  function messageFor(error) {
976
- return error instanceof Error ? error.message : String(error);
982
+ if (!(error instanceof Error))
983
+ return String(error);
984
+ const code = dispatchCode(error);
985
+ return code === undefined || error.message.startsWith(code) ? error.message : `${code}: ${error.message}`;
977
986
  }
978
987
  function hasErrnoCode(error, code) {
979
988
  return error instanceof Error && "code" in error && error.code === code;
@@ -15054,8 +15063,14 @@ function brokenParts(parts) {
15054
15063
  var CONTENT_IS_MARKDOWN = "content is stored as a Markdown document, which rewrites other text (a JSONL file's lines come back joined into one paragraph)";
15055
15064
  var PATH_KEEPS_BYTES = "path (--path <file>), which stores a file whose path does not end in .md or .markdown as its bytes, unchanged";
15056
15065
  var ARTIFACT_CONTENT_NAME_RULE = `${CONTENT_IS_MARKDOWN}, so with content the name ends in .md or .markdown or has no extension; upload any other file (.jsonl, .tsv, .json, .txt) with ${PATH_KEEPS_BYTES}.`;
15066
+ var ARTIFACT_NAME_EXISTS_RULE = "An upload under the name of a document the owner already holds is refused: it writes that document's next version, over the text it holds. Change a document with dispatch doc-edit. Send the upload again with force (--force) to write the next version.";
15067
+ var ARTIFACT_STORED_TEXT_RULE = `content and content-file hold text Dispatch stores as Markdown, and a text the store would write under another spelling is refused. The refusal prints the text Dispatch stores: send that text. A name that does not end in .md or .markdown has a second way out, which keeps the text as it was written: send it as a file with ${PATH_KEEPS_BYTES}.`;
15057
15068
  var NAME_EXTENSION = /\.([^\s.]+)$/u;
15058
15069
  var MARKDOWN_EXTENSION = /^(md|markdown)$/i;
15070
+ function pathKeepsBytesOf(name) {
15071
+ const extension = NAME_EXTENSION.exec(name.trim())?.[1];
15072
+ return extension === undefined || !MARKDOWN_EXTENSION.test(extension);
15073
+ }
15059
15074
  var artifactOwner = documentOwnerValidation(false);
15060
15075
  function artifactProblem(value) {
15061
15076
  const input = value;
@@ -15197,6 +15212,42 @@ var handoffValidation = {
15197
15212
  message: HANDOFF_RULE,
15198
15213
  refusal: (value) => handoffProblem(value) ?? HANDOFF_RULE
15199
15214
  };
15215
+ var RESULT_REQUIRED_FIELDS = ["issue", "check", "role", "verdict", "commit"];
15216
+ var RESULT_RECORD_FIELDS = [
15217
+ ...RESULT_REQUIRED_FIELDS,
15218
+ "surface",
15219
+ "run",
15220
+ "observed",
15221
+ "negative_control",
15222
+ "failed",
15223
+ "skipped",
15224
+ "excluded",
15225
+ "screenshots"
15226
+ ];
15227
+ var RESULT_RETRACT_RULE = "Pass retract with the id of a result recorded before, and reason with why that result is " + "wrong, to retract it.";
15228
+ var RESULT_SHAPE_RULE = `${RESULT_RETRACT_RULE} A call with retract takes reason and no other argument. A call ` + "without retract records a result, and it takes issue, check, role, verdict and commit.";
15229
+ function resultProblem(value) {
15230
+ const input = value;
15231
+ const carried = RESULT_RECORD_FIELDS.filter((field) => input[field] !== undefined);
15232
+ if (typeof input["retract"] === "string") {
15233
+ const reason = input["reason"];
15234
+ if (typeof reason !== "string" || reason.trim() === "") {
15235
+ return "retract needs reason, the words that say why the result is wrong.";
15236
+ }
15237
+ if (carried.length > 0) {
15238
+ return `retract takes reason alone, and this call also carries ${carried.join(", ")}. Retract the result, then record a new one with a call of its own.`;
15239
+ }
15240
+ return;
15241
+ }
15242
+ if (input["reason"] !== undefined) {
15243
+ return "reason goes with retract, and this call carries no retract. Name the result to retract, or drop reason.";
15244
+ }
15245
+ const missing = RESULT_REQUIRED_FIELDS.filter((field) => input[field] === undefined);
15246
+ if (missing.length > 0) {
15247
+ return `recording a result needs ${missing.join(", ")}. ${RESULT_RETRACT_RULE}`;
15248
+ }
15249
+ return;
15250
+ }
15200
15251
  var SEARCH_QUERY_MAX = 1000;
15201
15252
  var SEARCH_QUERY_HINT = "search with a short phrase of a few words, not a passage";
15202
15253
  var SEARCH_KIND_DEPTH = 100;
@@ -15550,13 +15601,13 @@ var dispatchToolSpecs = [
15550
15601
  verdict: "pass",
15551
15602
  commit: "1111111111111111111111111111111111111111"
15552
15603
  },
15553
- description: "Record one result of one check of an issue's Verification document, and print the " + "pull-request body line it implies. The check is named by its block id, or, when two " + "Verification documents in reach share that id, by its canonical reference " + "(dispatch://KEY/artifact/verification-md#b-<id>); 409 CHECK_AMBIGUOUS names them, and an " + "id no Verification document of the issue or of an issue above it holds is 400 " + "UNKNOWN_CHECK. A pass counting any failed, skipped or excluded case contradicts itself " + "and is 400 RESULT_CONTRADICTS. Dispatch asks GitHub whether the repository of the " + "check's issue holds the commit: one it does not hold is 400 RESULT_COMMIT_UNKNOWN, " + "naming the commit and that owner/repo, so record the result after the commit is pushed. " + "A repository Dispatch cannot read records the result as before. " + "The result is recorded against the check's own issue, so " + "a child's run of a parent's check appears under that check. A closed issue takes a " + "result only for a check whose when is after_merge or default_branch \u2014 the production " + "check after the merge \u2014 and refuses every other one with 409 ISSUE_CLOSED, as it refuses " + "every other write. Write the printed line into the pull-request body unchanged: it is " + "the one grammar every writer uses, and it carries no link to Dispatch. " + ISSUE_REFERENCE,
15604
+ description: "Record one result of one check of an issue's Verification document, or retract a result " + "recorded before. A record prints the pull-request body line it implies. Write that line " + "into the pull-request body unchanged: it is the one grammar every writer uses, and it " + "carries no link to Dispatch. " + "Name the check by its block id. Where two Verification documents in reach hold that id, " + "name it by its canonical reference (dispatch://KEY/artifact/verification-md#b-<id>). " + "409 CHECK_AMBIGUOUS names both documents. An id no Verification document of the issue " + "or of an issue above it holds is 400 UNKNOWN_CHECK. " + "A pass that counts a failed, a skipped or an excluded case contradicts itself, and is " + "400 RESULT_CONTRADICTS. " + "Dispatch asks GitHub whether the repository of the check's issue holds the commit. A " + "commit that repository does not hold is 400 RESULT_COMMIT_UNKNOWN, which names the " + "commit and that owner/repo. Record the result after the commit is pushed. A repository " + "Dispatch cannot read records the result as before. " + "The result is recorded against the check's own issue, so a child's run of a parent's " + "check appears under that check. A closed issue takes a result only for a check whose " + "when is after_merge or default_branch, the production check after the merge. It refuses " + "every other record with 409 ISSUE_CLOSED, as it refuses every other write. " + RESULT_RETRACT_RULE + " The retraction keeps both records: the result stays readable, and it proves nothing " + "from then on. Record a new result where the check still needs one. A retraction is " + "taken on a closed issue and for a check of any when. Three callers may retract: the " + "session that recorded the result, a session that holds the Dispatch claim of the issue " + "the result was recorded on, and a caller whose credential carries a person. Every other " + "caller is 403 RETRACTION_FORBIDDEN. A result retracted already is 409 RESULT_RETRACTED. " + ISSUE_REFERENCE,
15554
15605
  arguments: (z) => ({
15555
- issue: z.string().describe(ISSUE_REFERENCE),
15556
- check: z.string().describe("The check block's id, or its canonical reference dispatch://KEY/artifact/verification-md#b-<id> when the id is not unique among the issue's Verification document and those of the issues above it."),
15557
- role: z.string({ max: 32 }).describe("Who ran it: implementer, tester, reviewer. At most 32 characters of a-z and -, printed in the pull-request line."),
15558
- verdict: z.enum(["pass", "fail"]).describe("Whether the check passed."),
15559
- commit: z.string().describe("The 40-character lowercase hex commit the check ran at."),
15606
+ issue: z.string().describe(ISSUE_REFERENCE).optional(),
15607
+ check: z.string().describe("The check block's id, or its canonical reference dispatch://KEY/artifact/verification-md#b-<id> when the id is not unique among the issue's Verification document and those of the issues above it.").optional(),
15608
+ role: z.string({ max: 32 }).describe("Who ran it: implementer, tester, reviewer. At most 32 characters of a-z and -, printed in the pull-request line.").optional(),
15609
+ verdict: z.enum(["pass", "fail"]).describe("Whether the check passed.").optional(),
15610
+ commit: z.string().describe("The 40-character lowercase hex commit the check ran at.").optional(),
15560
15611
  surface: z.string().describe("Where a person reaches the change.").optional(),
15561
15612
  run: z.string().describe("The command that proved it.").optional(),
15562
15613
  observed: z.string().describe("What the command printed.").optional(),
@@ -15564,28 +15615,38 @@ var dispatchToolSpecs = [
15564
15615
  failed: z.number({ int: true, min: 0 }).describe("Cases the run failed; 0 by default.").optional(),
15565
15616
  skipped: z.number({ int: true, min: 0 }).describe("Cases the run skipped; 0 by default.").optional(),
15566
15617
  excluded: z.number({ int: true, min: 0 }).describe("Cases the run excluded; 0 by default.").optional(),
15567
- screenshots: z.array(z.string()).describe("dispatch:// references to image documents of this issue or of the check's issue.").optional()
15568
- })
15618
+ screenshots: z.array(z.string()).describe("dispatch:// references to image documents of this issue or of the check's issue.").optional(),
15619
+ retract: z.string().describe("The id of a result recorded before. It records that the result is wrong, and it takes reason alone beside it.").optional(),
15620
+ reason: z.string().describe("Why the retracted result is wrong. It goes with retract and with nothing else.").optional()
15621
+ }),
15622
+ validation: {
15623
+ check: (value) => resultProblem(value) === undefined,
15624
+ message: RESULT_SHAPE_RULE,
15625
+ refusal: (value) => resultProblem(value) ?? RESULT_SHAPE_RULE
15626
+ }
15569
15627
  },
15570
15628
  {
15571
15629
  name: "dispatch_results",
15572
15630
  example: { issue: "DSP-1" },
15573
- description: "Print each check of an issue's Verification document with its latest result and whether " + "that result is current. A result is current when it ran at the commit the work stands at " + "\u2014 the head of an open pull request of the check's issue, the final head of a merged one, " + "for an after_merge check a commit on the branch that issue's pull request merged into or " + "on the repository's default branch (which answers alone where Dispatch holds no merge of " + "that issue), or for a default_branch check a commit on the repository's default branch, " + "whatever branch the pull request merged into \u2014 and the check's words have not changed " + "since; older otherwise, and unknown when Dispatch cannot read the repository. On an " + "after_merge check's base branch a read GitHub refused \u2014 a 403 or 404, which a branch it " + "no longer holds answers with \u2014 says the commit is not on that branch and leaves the " + "default branch to decide; every other failure of that read, a rate limit or a 5xx " + "among them, leaves the result unknown and never older. A push that moves the " + "pull request's head makes a result older with no write of anyone's: record it again at " + "the new head. " + ISSUE_REFERENCE,
15631
+ description: "Print each check of an issue's Verification document with every result recorded against " + "it, newest first. " + "Each check prints what Dispatch compared its results with. A before_merge check is " + "compared with the head of each pull request Dispatch holds for the check's issue, open " + "or merged. An after_merge check is compared with the branch that issue's pull request " + "merged into and with the repository's default branch, and with the default branch alone " + "where Dispatch holds no merge of the issue. A default_branch check is compared with the " + "repository's default branch alone, whatever branch the pull request merged into. Where " + "a check compared with nothing, it says which of three things happened: the issue has no " + "pull request and no branch to compare with, Dispatch cannot read the repository, or a " + "read Dispatch made did not answer. " + "Each check then prints one line that answers the gate: whether a pass of it stands, and " + "from which roles. A pass stands when its commit is one of the commits the check " + "compared with, the check's words did not move after the result was recorded, and no " + "retraction stands against it. " + "The check's own words print once, under the check. Each result then prints its verdict, " + "its role, its whole 40-character commit, where that commit stands, whether the check's " + "words moved after it was recorded, the time, its id, and the reading the role recorded. " + "A result nobody gave a reading says so. A retracted result prints as retracted, with " + "the reason and the caller that retracted it. A check with no result says so. " + "A push that moves a pull request's head leaves a result at the commit before it, with " + "no write of anyone's: record the check again at the new head. " + ISSUE_REFERENCE,
15574
15632
  arguments: (z) => ({
15575
- issue: z.string().describe(ISSUE_REFERENCE)
15633
+ issue: z.string().describe(ISSUE_REFERENCE),
15634
+ at: z.string().describe("One commit of 40 lowercase hex characters. It becomes the only thing every check is compared with, and Dispatch reads GitHub for none of it.").optional(),
15635
+ brief: z.boolean().describe("Cut each reading whose result stands at none of the compared commits to its first 200 characters. Every other reading prints whole.").optional()
15576
15636
  })
15577
15637
  },
15578
15638
  {
15579
15639
  name: "dispatch_artifact",
15580
15640
  example: { issue: "DSP-1", name: "design.md", content: `# Design
15581
15641
  ` },
15582
- 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. Never upload a document's own name to change it (spec.md replaces the spec whole); edit it with dispatch doc-edit. Uploading the same name again makes its next version, and so does uploading a document's slug (plan-md for plan.md). Exactly one of path or content is required; a markdown document is at most 1 MiB and any other file at most 25 MiB. " + `${ARTIFACT_CONTENT_NAME_RULE} ` + "Markdown is also refused with 413 CAP_EXCEEDED when it makes more than 65,536 elements (a block weighs 3, and an empty list item, quote, footnote definition or typed block 3 more for the empty paragraph it holds; a table cell 4, a hard line break 3, an image 3, a piece of inline HTML 2, an autolink 2, a footnote reference 2; inline syntax, marks, lines of text and backslash escapes or character references 1 each), or when a new version would leave the document's stored markdown (what its text reads back as) longer than 1 MiB or making more than 65,536 elements, and longer or heavier than before; shorten it or split it across documents. " + "In a table row, write every | in a cell as \\|, in code too: a | after two backslashes ends the cell, and a row with more cells than its table is refused. " + "Markdown holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK; a new version of a document is held to it only for the asks it writes or changes. " + `${OWNER_REFERENCE}`,
15642
+ 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. Never upload a document's own name to change it (spec.md replaces the spec whole); edit it with dispatch doc-edit. Exactly one of path or content is required; a markdown document is at most 1 MiB and any other file at most 25 MiB. " + `${ARTIFACT_NAME_EXISTS_RULE} ` + `${ARTIFACT_CONTENT_NAME_RULE} ${ARTIFACT_STORED_TEXT_RULE} ` + "Markdown is also refused with 413 CAP_EXCEEDED when it makes more than 65,536 elements (a block weighs 3, and an empty list item, quote, footnote definition or typed block 3 more for the empty paragraph it holds; a table cell 4, a hard line break 3, an image 3, a piece of inline HTML 2, an autolink 2, a footnote reference 2; inline syntax, marks, lines of text and backslash escapes or character references 1 each), or when a new version would leave the document's stored markdown (what its text reads back as) longer than 1 MiB or making more than 65,536 elements, and longer or heavier than before; shorten it or split it across documents. " + "In a table row, write every | in a cell as \\|, in code too: a | after two backslashes ends the cell, and a row with more cells than its table is refused. " + "Markdown holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK; a new version of a document is held to it only for the asks it writes or changes. " + `${OWNER_REFERENCE}`,
15583
15643
  arguments: (z) => ({
15584
15644
  issue: z.string().describe(ISSUE_REFERENCE).optional(),
15585
15645
  project: z.string().describe("Project key for an unlinked document.").optional(),
15586
15646
  name: z.string().describe("Artifact filename shown in Dispatch."),
15587
15647
  path: z.string().describe("Local path to the file to upload.").optional(),
15588
- content: z.string().describe("Inline text to store as a Markdown document, under a name ending in .md or .markdown or with no extension; a CR LF or a lone carriage return in it is stored as a line feed.").optional(),
15648
+ content: z.string().describe("Inline text to store as a Markdown document, under a name ending in .md or .markdown or with no extension. The command refuses a text the store would write under another spelling, a CR LF or a lone carriage return among them, which Dispatch stores as a line feed. A missing line feed at the end is not such a text: Dispatch adds one, and the upload goes on. The refusal prints the text Dispatch stores, which is the text to send.").optional(),
15649
+ force: z.boolean().describe("Write the next version of a document the owner already holds under this name; without it the upload of a name that exists is refused.").optional(),
15589
15650
  summary: z.string().describe("Optional version summary.").optional()
15590
15651
  }),
15591
15652
  validation: {
@@ -17947,6 +18008,13 @@ class DispatchClient {
17947
18008
  return answer;
17948
18009
  throw new Error(`GET ${this.#url(path, query)} asked for the unpaged listing and got ${whyNotAnArray(answer)}.`);
17949
18010
  }
18011
+ async listIssueArtifacts(issue) {
18012
+ return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "artifacts"]);
18013
+ }
18014
+ async markdownRoundTrip(markdown) {
18015
+ const answer = await this.#json("POST", ["api", "v1", "markdown", "round-trip"], { markdown });
18016
+ return answer.markdown;
18017
+ }
17950
18018
  async listProjectArtifacts(project, unlinked = false) {
17951
18019
  return this.#json("GET", ["api", "v1", "projects", project, "artifacts"], undefined, unlinked ? { unlinked: "true" } : undefined);
17952
18020
  }
@@ -18134,8 +18202,11 @@ class DispatchClient {
18134
18202
  async recordResult(issue, input) {
18135
18203
  return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"], input);
18136
18204
  }
18137
- async issueResults(issue) {
18138
- return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"]);
18205
+ async issueResults(issue, at) {
18206
+ return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"], undefined, at === undefined ? undefined : { at });
18207
+ }
18208
+ async retractResult(resultID, input) {
18209
+ return this.#json("POST", ["api", "v1", "results", resultID, "retract"], input);
18139
18210
  }
18140
18211
  async editAsk(id, input) {
18141
18212
  return this.#json("PATCH", ["api", "v1", "asks", id], input);
@@ -18210,6 +18281,9 @@ class DispatchClient {
18210
18281
  async docRead(id, version) {
18211
18282
  return version === undefined ? this.#json("GET", ["api", "v1", "artifacts", id, "text"]) : this.#json("GET", ["api", "v1", "artifacts", id, "versions", String(version)]);
18212
18283
  }
18284
+ async docReadWithBlocks(id) {
18285
+ return this.#json("GET", ["api", "v1", "artifacts", id, "text"], undefined, { blocks: true });
18286
+ }
18213
18287
  async fileVersion(id, version) {
18214
18288
  const url = this.#url(["api", "v1", "artifacts", id, "versions", String(version)]);
18215
18289
  const response = await this.#send("GET", url, undefined, "*/*");
@@ -19482,11 +19556,11 @@ processGlobal[STATE_KEY] = state;
19482
19556
  class ToolInputError extends Error {
19483
19557
  tool;
19484
19558
  problems;
19485
- constructor(tool, problems) {
19559
+ constructor(tool, problems, options) {
19486
19560
  const count = problems.length;
19487
19561
  const cli = isDispatchTool(tool);
19488
19562
  const help = cli ? [
19489
- `Allowed flags: ${commandFlags(tool).join(", ")}`,
19563
+ ...options?.aboutAFlag === false ? [] : [`Allowed flags: ${commandFlags(tool).join(", ")}`],
19490
19564
  `Example: ${commandLine(tool, exampleFor(tool))}`
19491
19565
  ] : [];
19492
19566
  super([
@@ -19980,7 +20054,7 @@ async function refuseItemOffRef(tool, kind, ref, refText, item, documentId) {
19980
20054
  `${refText} names ${kind} ${item.id} on ${refOwnerName(ref)}, but it is on ${where}`
19981
20055
  ]);
19982
20056
  }
19983
- async function resolveIdPrefix(tool, kind, id, ownerName, list) {
20057
+ async function resolveIdPrefix(tool, kind, id, ownerName, list, candidates) {
19984
20058
  const fullID = normalizeUUID(id);
19985
20059
  if (fullID !== undefined)
19986
20060
  return fullID;
@@ -19990,9 +20064,13 @@ async function resolveIdPrefix(tool, kind, id, ownerName, list) {
19990
20064
  ]);
19991
20065
  }
19992
20066
  const prefix = id.toLowerCase();
19993
- const matches = (await list()).filter((item) => item.id.toLowerCase().startsWith(prefix));
20067
+ const all = await list();
20068
+ const matches = all.filter((item) => item.id.toLowerCase().startsWith(prefix));
19994
20069
  if (matches.length === 1 && matches[0] !== undefined)
19995
20070
  return matches[0].id;
20071
+ if (candidates !== undefined) {
20072
+ throw new ToolInputError(tool, [candidates.refusal(matches, all)], { aboutAFlag: false });
20073
+ }
19996
20074
  throw new ToolInputError(tool, [
19997
20075
  matches.length === 0 ? `${kind} id ${id} matches none of the ${kind}s on ${ownerName}; use the full id` : `${kind} id ${id} matches ${matches.length} ${kind}s on ${ownerName}; use the full id`
19998
20076
  ]);
@@ -20443,6 +20521,9 @@ async function resolveOwnerArguments(tool, input, cwd, env, exec, dashboardUrls,
20443
20521
  if (tool === "dispatch_read" && typeof args.message === "string") {
20444
20522
  return { args, ref, owner: null };
20445
20523
  }
20524
+ if (tool === "dispatch_result" && typeof args["retract"] === "string") {
20525
+ return { args, ref, owner: null };
20526
+ }
20446
20527
  const legionIssue = env.LEGION_ISSUE;
20447
20528
  if (!legionIssue) {
20448
20529
  problems.push(ownerRequiredProblem);
@@ -20601,9 +20682,14 @@ function boundedEditDistance(a, b, limit) {
20601
20682
  return Math.min(previous[b.length], limit + 1);
20602
20683
  }
20603
20684
  var askHintLimit = 8;
20604
- function askIDInputProblem(asks, scope) {
20685
+ function openAskChoices(asks, owner) {
20686
+ if (asks.length === 0)
20687
+ return `${owner} holds no open ask.`;
20605
20688
  const hints = asks.slice(0, askHintLimit).map((ask) => `${ask.id.slice(0, 8)}\u2026 ${textHead(ask.question)}`);
20606
- return `ask IDs are UUIDs; use the full ask ID; ${scope} open asks: ${hints.length === 0 ? "none" : hints.join(", ")}`;
20689
+ return `The open asks of ${owner} are: ${hints.join(", ")}.`;
20690
+ }
20691
+ function askIDInputProblem(asks, owner) {
20692
+ return `ask ids are uuids. Write the whole id, or at least its first 8 characters. ${openAskChoices(asks, owner)}`;
20607
20693
  }
20608
20694
  async function movedApprovalLine(client, askID) {
20609
20695
  const ask = (await client.getAsk(askID).catch(() => {
@@ -20617,14 +20703,29 @@ async function movedApprovalLine(client, askID) {
20617
20703
  const owner = ask.issue_key === null ? `--project ${ask.approval_artifact?.project ?? "<project>"} --artifact ${approval.artifact_id}` : ask.approval_artifact?.primary === true ? `--issue ${ask.issue_key}` : `--issue ${ask.issue_key} --artifact ${approval.artifact_id}`;
20618
20704
  return `The reply did not hand the ask to the human: it is the approval request for ${approval.name} ` + `at version ${approval.requested_version}, and ${approval.name} is now version ${approval.version}. ` + "No reply hands a moved approval request back. Once the human has agreed to every point in " + `version ${approval.version}, run: dispatch request-approval ${owner} --summary ` + `'<what changed since version ${approval.requested_version}>'`;
20619
20705
  }
20620
- async function invalidReplyToAskProblem(client, owner, resolved) {
20706
+ async function replyToAskCandidates(client, owner, resolved) {
20621
20707
  if (owner.kind === "issue") {
20622
20708
  const issue = resolved?.issue ?? await client.getIssue(owner.issue);
20623
- return askIDInputProblem(issue.open_asks ?? [], "this issue's");
20709
+ return { asks: issue.open_asks ?? [], owner: "this issue" };
20624
20710
  }
20625
20711
  if (resolved === undefined)
20626
20712
  throw new Error("project document is missing its resolved artifact");
20627
- return askIDInputProblem(await client.getArtifactAsks(resolved.artifact.id, "open"), "this document's");
20713
+ return {
20714
+ asks: await client.getArtifactAsks(resolved.artifact.id, "open"),
20715
+ owner: "this document"
20716
+ };
20717
+ }
20718
+ async function resolveReplyToAsk(tool, client, target, resolved, id) {
20719
+ const whole = normalizeUUID(id);
20720
+ if (whole !== undefined)
20721
+ return whole;
20722
+ const { asks, owner } = await replyToAskCandidates(client, target, resolved);
20723
+ if (!isIdPrefix(id)) {
20724
+ throw new ToolInputError(tool, [askIDInputProblem(asks, owner)], { aboutAFlag: false });
20725
+ }
20726
+ return resolveIdPrefix(tool, "ask", id, owner, async () => asks, {
20727
+ refusal: (found, all) => found.length === 0 ? `reply_to_ask ${id} names no open ask of ${owner}. ${openAskChoices(all, owner)}` : `reply_to_ask ${id} names ${found.length} open asks of ${owner}. Write more of the id. ${openAskChoices(all, owner)}`
20728
+ });
20628
20729
  }
20629
20730
  function anchor(artifact, args) {
20630
20731
  const quote = optionalString(args, "quote");
@@ -20664,6 +20765,89 @@ function approvalLine(artifact) {
20664
20765
  return `Approval: ${approval.state} on v${approval.version}${content}`;
20665
20766
  }
20666
20767
  }
20768
+ function artifactUnderName(artifacts, name) {
20769
+ const written = name.trim();
20770
+ return artifacts.find((held) => held.slug === written) ?? artifacts.find((held) => held.name === written);
20771
+ }
20772
+ function artifactNameExistsProblem(held, owner) {
20773
+ const versions = held.versions ?? [];
20774
+ const newest = versions[versions.length - 1];
20775
+ if (newest === undefined) {
20776
+ return `${owner} already holds ${held.name} (slug ${held.slug}, kind ${held.kind}), which has no version yet and which ${actorText(held.created_by)} created. ${ARTIFACT_NAME_EXISTS_RULE}`;
20777
+ }
20778
+ const authors = (newest.authors ?? []).map(actorText);
20779
+ const wroteIt = authors.length === 0 ? actorText(held.created_by) : authors.join(" and ");
20780
+ return `${owner} already holds ${held.name} (slug ${held.slug}, kind ${held.kind}) at version ${newest.number}, which ${wroteIt} wrote. ${ARTIFACT_NAME_EXISTS_RULE}`;
20781
+ }
20782
+ var STORED_LINE_QUOTED = 200;
20783
+ function quotedStoredLine(line) {
20784
+ if (line.length <= STORED_LINE_QUOTED)
20785
+ return JSON.stringify(line);
20786
+ const head = JSON.stringify(line.slice(0, STORED_LINE_QUOTED));
20787
+ return `${head} (cut after ${STORED_LINE_QUOTED} of its ${line.length} characters)`;
20788
+ }
20789
+ function firstStoredDifference(given, stored) {
20790
+ const written = given.split(`
20791
+ `);
20792
+ const holds = stored.split(`
20793
+ `);
20794
+ for (let line = 0;line < Math.max(written.length, holds.length); line += 1) {
20795
+ const wrote = written[line];
20796
+ const held = holds[line];
20797
+ if (wrote === held)
20798
+ continue;
20799
+ if (wrote === undefined && held !== undefined) {
20800
+ return `the store writes a line ${line + 1}, ${quotedStoredLine(held)}`;
20801
+ }
20802
+ if (held === undefined && wrote !== undefined) {
20803
+ return `the store drops line ${line + 1}, ${quotedStoredLine(wrote)}`;
20804
+ }
20805
+ if (wrote !== undefined && held !== undefined) {
20806
+ return `line ${line + 1} reads ${quotedStoredLine(wrote)} and is stored as ${quotedStoredLine(held)}`;
20807
+ }
20808
+ }
20809
+ return "the stored text differs from the text given";
20810
+ }
20811
+ var STORED_TEXT_PRINTED = 2000;
20812
+ function storedTextPrinted(stored) {
20813
+ if (stored.length <= STORED_TEXT_PRINTED)
20814
+ return { text: stored, cut: "" };
20815
+ const head = stored.slice(0, STORED_TEXT_PRINTED);
20816
+ const lastLineFeed = head.lastIndexOf(`
20817
+ `);
20818
+ const text = lastLineFeed === -1 ? head : head.slice(0, lastLineFeed + 1);
20819
+ return {
20820
+ text,
20821
+ cut: ` The text below is cut after ${text.length} of its ${stored.length} characters: change the line named above and send the text again.`
20822
+ };
20823
+ }
20824
+ function storedTextProblem(given, stored, name) {
20825
+ const asBytes = pathKeepsBytesOf(name) ? ` To keep the text as you wrote it, send it as a file with ${PATH_KEEPS_BYTES}.` : "";
20826
+ const printed = storedTextPrinted(stored);
20827
+ return [
20828
+ `Dispatch stores this text under another spelling: ${firstStoredDifference(given, stored)}.`,
20829
+ ` Send the text Dispatch stores, which is between the two marker lines below.${asBytes}`,
20830
+ `${printed.cut}
20831
+ --- the text Dispatch stores ---
20832
+ ${printed.text}`,
20833
+ "--- end of the text Dispatch stores ---"
20834
+ ].join("");
20835
+ }
20836
+ function storedTextCheckFailed(error, name) {
20837
+ const failure = `Dispatch could not say how it would store this text, so nothing was uploaded: POST /api/v1/markdown/round-trip failed with ${messageFor(error)}.`;
20838
+ if (!dispatchAnswered(error, 413)) {
20839
+ return `${failure} Send the upload again once that call is answered.`;
20840
+ }
20841
+ const asBytes = pathKeepsBytesOf(name) ? ` Send it as a file with ${PATH_KEEPS_BYTES}, which asks this check nothing.` : "";
20842
+ return `${failure} This text is longer than the check reads, and sending the upload again does not change that: a markdown document is at most 1 MiB, so shorten it or split it across documents of at most that.${asBytes}`;
20843
+ }
20844
+ function roundTripRouteAbsent(error) {
20845
+ return dispatchAnswered(error, 404) || dispatchAnswered(error, 405);
20846
+ }
20847
+ function withoutFinalLineFeed(text) {
20848
+ return text.endsWith(`
20849
+ `) ? text.slice(0, -1) : text;
20850
+ }
20667
20851
  function componentsLine(components) {
20668
20852
  const ids = components.ids ?? [];
20669
20853
  const unknown = components.unknown ?? [];
@@ -20757,7 +20941,96 @@ function progressText(progress, sep) {
20757
20941
  }
20758
20942
  return parts.join(sep);
20759
20943
  }
20760
- function formatCheckResults(results) {
20944
+ var BRIEF_READING_CHARACTERS = 200;
20945
+ var COMPARISON_REASONS = {
20946
+ no_pull_request_or_branch: "the issue has no pull request and no branch to compare with",
20947
+ repository_unreadable: "Dispatch cannot read the repository",
20948
+ read_failed: "a read Dispatch made did not answer"
20949
+ };
20950
+ function learnedText(learned) {
20951
+ if (learned.kind === "read_at")
20952
+ return `Dispatch read it ${learned.at}`;
20953
+ return `GitHub updated it ${learned.at}`;
20954
+ }
20955
+ function basisText(basis) {
20956
+ const learned = basis.learned_at === undefined ? "" : ` (${learnedText(basis.learned_at)})`;
20957
+ if (basis.kind === "pull_request") {
20958
+ const number = basis.pull_request === undefined ? "" : `#${basis.pull_request} `;
20959
+ return `the head of pull request ${number}at ${basis.commit ?? "an unnamed commit"}${learned}`;
20960
+ }
20961
+ if (basis.kind === "branch")
20962
+ return `branch ${basis.branch ?? "unnamed"}${learned}`;
20963
+ return `the commit you named, ${basis.commit ?? ""}${learned}`;
20964
+ }
20965
+ function basisPlace(basis) {
20966
+ if (basis.kind === "pull_request") {
20967
+ return basis.pull_request === undefined ? "the head of a pull request" : `the head of pull request #${basis.pull_request}`;
20968
+ }
20969
+ if (basis.kind === "branch")
20970
+ return `on branch ${basis.branch ?? "unnamed"}`;
20971
+ return "the commit you named";
20972
+ }
20973
+ function commitStandsText(stands) {
20974
+ if (stands === undefined) {
20975
+ return "Where that commit stands is not known: this Dispatch server does not say";
20976
+ }
20977
+ if (stands.answer === "at_basis") {
20978
+ return stands.basis === undefined ? "That commit is one of the compared commits" : `That commit is ${basisPlace(stands.basis)}`;
20979
+ }
20980
+ if (stands.answer === "other_commit")
20981
+ return "That commit is none of the compared commits";
20982
+ return stands.reason === undefined ? "Where that commit stands is not known" : `Where that commit stands is not known: ${COMPARISON_REASONS[stands.reason]}`;
20983
+ }
20984
+ function checkWordsText(check, result) {
20985
+ const versions = `result version ${result.check_version}, check version ${check.version}`;
20986
+ if (result.check_words_moved === undefined) {
20987
+ return `Whether the check's words moved is not known (${versions})`;
20988
+ }
20989
+ return result.check_words_moved ? `The check's words moved after this result (${versions})` : `The check's words did not move after this result (${versions})`;
20990
+ }
20991
+ function passStandsText(pass) {
20992
+ if (pass === undefined)
20993
+ return "Whether a pass stands is not known: this Dispatch server does not say";
20994
+ if (pass.answer === "yes") {
20995
+ const roles = pass.roles ?? [];
20996
+ return roles.length === 0 ? "A pass stands: yes" : `A pass stands: yes, from ${roles.join(", ")}`;
20997
+ }
20998
+ if (pass.answer === "no")
20999
+ return "A pass stands: no";
21000
+ return "A pass stands: not known";
21001
+ }
21002
+ function readingLines(result, brief) {
21003
+ const observed = result.observed;
21004
+ if (observed === "")
21005
+ return [" The role recorded no reading."];
21006
+ const cut = brief && result.commit_stands?.answer !== "at_basis";
21007
+ if (cut && observed.length > BRIEF_READING_CHARACTERS) {
21008
+ return [` Reading: ${observed.slice(0, BRIEF_READING_CHARACTERS)}\u2026 (result ${result.id})`];
21009
+ }
21010
+ return [` Reading: ${observed}`];
21011
+ }
21012
+ function resultLines(check, result, brief) {
21013
+ const lines = [
21014
+ ` - ${result.verdict} by ${result.role} at ${result.commit_sha}. ${commitStandsText(result.commit_stands)}. ${checkWordsText(check, result)}. Recorded ${result.created_at}. Result ${result.id}.`
21015
+ ];
21016
+ const retracted = result.retracted;
21017
+ if (retracted !== undefined) {
21018
+ lines.push(` Retracted by ${actorText(retracted.actor)} at ${retracted.created_at}. The reason: ${retracted.reason}`);
21019
+ }
21020
+ return [...lines, ...readingLines(result, brief)];
21021
+ }
21022
+ function checkLines(check, brief) {
21023
+ const bases = check.compared_with ?? [];
21024
+ const reason = check.compared_nothing;
21025
+ const compared = bases.length > 0 ? `Compared with ${bases.map(basisText).join(", ")}` : reason === undefined ? "Compared with nothing, and this Dispatch server does not say why" : `Compared with nothing: ${COMPARISON_REASONS[reason]}`;
21026
+ const results = check.results ?? [];
21027
+ return [
21028
+ `- ${check.block_id} (${check.when}). ${compared}. ${passStandsText(check.pass_stands)}.`,
21029
+ ` The check's words: ${check.text}`,
21030
+ ...results.length === 0 ? [" No result is recorded for this check."] : results.flatMap((result) => resultLines(check, result, brief))
21031
+ ];
21032
+ }
21033
+ function formatCheckResults(results, brief = false) {
20761
21034
  if (results.verification_artifact_id === "") {
20762
21035
  return `${results.issue} has no Verification document, so it has no checks. Write one (verification.md) with a check block per thing that must be proved.`;
20763
21036
  }
@@ -20765,15 +21038,10 @@ function formatCheckResults(results) {
20765
21038
  if (checks.length === 0) {
20766
21039
  return `${results.issue}'s Verification document holds no check blocks.`;
20767
21040
  }
20768
- const lines = checks.map((check) => {
20769
- const head = `- ${check.block_id} (${check.when}): `;
20770
- const latest = (check.results ?? [])[0];
20771
- if (latest === undefined) {
20772
- return `${head}no result yet. ${check.text}`;
20773
- }
20774
- return `${head}${latest.verdict} at ${latest.commit_sha} by ${latest.role}, ${latest.currency ?? "unknown"}. ${check.text}`;
20775
- });
20776
- return [`Checks of ${results.issue}:`, ...lines].join(`
21041
+ const blocks = checks.map((check) => checkLines(check, brief).join(`
21042
+ `));
21043
+ return [`Checks of ${results.issue}:`, ...blocks].join(`
21044
+
20777
21045
  `);
20778
21046
  }
20779
21047
  function repositoryLine(issue) {
@@ -21440,9 +21708,6 @@ ${text}`,
21440
21708
  var BLOCK_OPENING_CHARS = 60;
21441
21709
  async function listDocumentBlocks(client, artifact) {
21442
21710
  const live = await liveBlocks(client, artifact);
21443
- if (live === undefined) {
21444
- throw new Error(`${artifact.name} changed while dispatch doc-read --blocks read it, so the opening words could name the wrong text; nothing is listed. Run it again.`);
21445
- }
21446
21711
  const { bytes, blocks } = live;
21447
21712
  const decoder = new TextDecoder;
21448
21713
  const lines = [
@@ -21479,15 +21744,19 @@ async function listDocumentBlocks(client, artifact) {
21479
21744
  holders.push(block);
21480
21745
  }
21481
21746
  return { text: lines.join(`
21482
- `), token: live.token };
21747
+ `), token: live.token, version: live.version };
21483
21748
  }
21484
21749
  async function liveBlocks(client, artifact) {
21485
- const before = await client.docRead(artifact.id);
21486
- const blocks = await client.artifactBlocks(artifact.id);
21487
- const after = await client.docRead(artifact.id);
21488
- if (before.token !== after.token || before.markdown !== after.markdown)
21489
- return;
21490
- return { bytes: new TextEncoder().encode(before.markdown), token: before.token, blocks };
21750
+ const read = await client.docReadWithBlocks(artifact.id);
21751
+ if (read.blocks === undefined) {
21752
+ throw new Error(`${artifact.name} was read from a Dispatch older than this command: it serves a document's blocks only on their own route, not beside the text they index, so nothing was listed.`);
21753
+ }
21754
+ return {
21755
+ bytes: new TextEncoder().encode(read.markdown),
21756
+ token: read.token,
21757
+ version: read.version ?? null,
21758
+ blocks: read.blocks
21759
+ };
21491
21760
  }
21492
21761
  async function refuseOpenDecisionBlocks(client, tool, resolved) {
21493
21762
  const artifact = resolved.artifact;
@@ -22270,12 +22539,7 @@ async function executeDispatchTool(input) {
22270
22539
  const anchored = resolved ? anchor(resolved.artifact, args) : undefined;
22271
22540
  const replyTo = itemReplyTo(args, "reply_to");
22272
22541
  const replyToAskTarget = itemReplyTo(args, "reply_to_ask");
22273
- const replyToAsk = replyToAskTarget === undefined ? undefined : normalizeUUID(replyToAskTarget.id);
22274
- if (replyToAskTarget !== undefined && replyToAsk === undefined) {
22275
- throw new ToolInputError(input.tool, [
22276
- await invalidReplyToAskProblem(client, owner, resolved)
22277
- ]);
22278
- }
22542
+ const replyToAsk = replyToAskTarget === undefined ? undefined : await resolveReplyToAsk(input.tool, client, owner, resolved, replyToAskTarget.id);
22279
22543
  const replyToBlock = replyTo?.block ?? replyToAskTarget?.block;
22280
22544
  const requestedTurn = optionalString(args, "turn");
22281
22545
  const body = await writePictures(resolved, stringArg(args, "body"));
@@ -22496,10 +22760,15 @@ async function executeDispatchTool(input) {
22496
22760
  throw new Error(`${resolved.artifact.name} is an uploaded ${resolved.artifact.kind}, not a document, so it has no blocks. Read it with dispatch doc-read without --blocks.`);
22497
22761
  }
22498
22762
  const listed = await listDocumentBlocks(client, resolved.artifact);
22763
+ const trailer = [
22764
+ ...listed.token === undefined ? [] : [`Document token: ${listed.token}`],
22765
+ `Document version: ${listed.version === null ? "none yet" : listed.version}`
22766
+ ];
22499
22767
  return {
22500
- text: listed.token === undefined ? listed.text : `${listed.text}
22768
+ text: `${listed.text}
22501
22769
 
22502
- Document token: ${listed.token}`,
22770
+ ${trailer.join(`
22771
+ `)}`,
22503
22772
  details: resolved.owner.kind === "project" ? {
22504
22773
  project: resolved.artifact.project,
22505
22774
  document: documentLabel(resolved.artifact.project, resolved.artifact.slug)
@@ -22600,6 +22869,23 @@ Document token: ${listed.token}`,
22600
22869
  };
22601
22870
  }
22602
22871
  case "dispatch_result": {
22872
+ const retract = optionalString(args, "retract");
22873
+ if (retract !== undefined) {
22874
+ const retraction = await client.retractResult(retract, {
22875
+ actor,
22876
+ reason: stringArg(args, "reason")
22877
+ });
22878
+ return {
22879
+ text: `Retracted result ${retraction.result_id}. ${actorText(retraction.actor)} retracted it at ${retraction.created_at}. The reason: ${retraction.reason}
22880
+
22881
+ The result stays readable, and it proves nothing from now on. Record a new result where the check still needs one.`,
22882
+ details: {
22883
+ result: retraction.result_id,
22884
+ reason: retraction.reason,
22885
+ created_at: retraction.created_at
22886
+ }
22887
+ };
22888
+ }
22603
22889
  const issue = stringArg(args, "issue");
22604
22890
  const optional = {
22605
22891
  ...defined("surface", optionalString(args, "surface")),
@@ -22635,16 +22921,45 @@ ${recorded.line}`,
22635
22921
  }
22636
22922
  case "dispatch_results": {
22637
22923
  const issue = stringArg(args, "issue");
22638
- const results = await client.issueResults(issue);
22924
+ const at = optionalString(args, "at");
22925
+ const brief = optionalBoolean(args, "brief") === true;
22926
+ const results = await client.issueResults(issue, at);
22927
+ const checks = results.checks ?? [];
22639
22928
  return {
22640
- text: formatCheckResults(results),
22641
- details: { issue, checks: (results.checks ?? []).length }
22929
+ text: formatCheckResults(results, brief),
22930
+ details: {
22931
+ issue,
22932
+ checks: checks.length,
22933
+ results: checks.reduce((total, check) => total + (check.results ?? []).length, 0)
22934
+ }
22642
22935
  };
22643
22936
  }
22644
22937
  case "dispatch_artifact": {
22645
22938
  const summary = optionalString(args, "summary");
22646
22939
  const name = stringArg(args, "name");
22647
22940
  const content = optionalString(args, "content");
22941
+ const artifactOwner = documentOwner();
22942
+ if (optionalBoolean(args, "force") !== true) {
22943
+ const held = artifactUnderName(artifactOwner.kind === "project" ? await client.listProjectArtifacts(artifactOwner.project, true) : await client.listIssueArtifacts(issue()), name);
22944
+ if (held !== undefined) {
22945
+ throw new ToolInputError(input.tool, [
22946
+ artifactNameExistsProblem(held, artifactOwner.kind === "project" ? `project ${artifactOwner.project}` : `issue ${issue()}`)
22947
+ ]);
22948
+ }
22949
+ }
22950
+ if (content !== undefined) {
22951
+ let stored;
22952
+ try {
22953
+ stored = await client.markdownRoundTrip(content);
22954
+ } catch (error) {
22955
+ if (!roundTripRouteAbsent(error)) {
22956
+ throw new Error(storedTextCheckFailed(error, name), { cause: error });
22957
+ }
22958
+ }
22959
+ if (stored !== undefined && withoutFinalLineFeed(stored) !== withoutFinalLineFeed(content)) {
22960
+ throw new ToolInputError(input.tool, [storedTextProblem(content, stored, name)]);
22961
+ }
22962
+ }
22648
22963
  const artifactInput = content === undefined ? {
22649
22964
  name,
22650
22965
  file: input.uploadBytes === undefined ? Bun.file(resolvePath2(input.cwd, stringArg(args, "path"))) : new Blob([new Uint8Array(input.uploadBytes)], {
@@ -22658,7 +22973,6 @@ ${recorded.line}`,
22658
22973
  ...summary === undefined ? {} : { summary },
22659
22974
  actor
22660
22975
  };
22661
- const artifactOwner = documentOwner();
22662
22976
  const result = artifactOwner.kind === "project" ? await client.projectArtifact(artifactOwner.project, artifactInput) : await client.artifact(issue(), artifactInput);
22663
22977
  const artifactRef = dispatchDocumentRef(artifactOwner.kind === "project" ? artifactOwner.project : issue(), result.artifact.slug);
22664
22978
  const uploadOwner = artifactOwner.kind === "project" ? documentTopic(result.artifact) : issueTopic(issue());
package/dist/envoy.js CHANGED
@@ -30096,6 +30096,8 @@ function brokenParts(parts) {
30096
30096
  var CONTENT_IS_MARKDOWN = "content is stored as a Markdown document, which rewrites other text (a JSONL file's lines come back joined into one paragraph)";
30097
30097
  var PATH_KEEPS_BYTES = "path (--path <file>), which stores a file whose path does not end in .md or .markdown as its bytes, unchanged";
30098
30098
  var ARTIFACT_CONTENT_NAME_RULE = `${CONTENT_IS_MARKDOWN}, so with content the name ends in .md or .markdown or has no extension; upload any other file (.jsonl, .tsv, .json, .txt) with ${PATH_KEEPS_BYTES}.`;
30099
+ var ARTIFACT_NAME_EXISTS_RULE = "An upload under the name of a document the owner already holds is refused: it writes that document's next version, over the text it holds. Change a document with dispatch doc-edit. Send the upload again with force (--force) to write the next version.";
30100
+ var ARTIFACT_STORED_TEXT_RULE = `content and content-file hold text Dispatch stores as Markdown, and a text the store would write under another spelling is refused. The refusal prints the text Dispatch stores: send that text. A name that does not end in .md or .markdown has a second way out, which keeps the text as it was written: send it as a file with ${PATH_KEEPS_BYTES}.`;
30099
30101
  var NAME_EXTENSION = /\.([^\s.]+)$/u;
30100
30102
  var MARKDOWN_EXTENSION = /^(md|markdown)$/i;
30101
30103
  var artifactOwner = documentOwnerValidation(false);
@@ -30239,6 +30241,42 @@ var handoffValidation = {
30239
30241
  message: HANDOFF_RULE,
30240
30242
  refusal: (value) => handoffProblem(value) ?? HANDOFF_RULE
30241
30243
  };
30244
+ var RESULT_REQUIRED_FIELDS = ["issue", "check", "role", "verdict", "commit"];
30245
+ var RESULT_RECORD_FIELDS = [
30246
+ ...RESULT_REQUIRED_FIELDS,
30247
+ "surface",
30248
+ "run",
30249
+ "observed",
30250
+ "negative_control",
30251
+ "failed",
30252
+ "skipped",
30253
+ "excluded",
30254
+ "screenshots"
30255
+ ];
30256
+ var RESULT_RETRACT_RULE = "Pass retract with the id of a result recorded before, and reason with why that result is " + "wrong, to retract it.";
30257
+ var RESULT_SHAPE_RULE = `${RESULT_RETRACT_RULE} A call with retract takes reason and no other argument. A call ` + "without retract records a result, and it takes issue, check, role, verdict and commit.";
30258
+ function resultProblem(value) {
30259
+ const input = value;
30260
+ const carried = RESULT_RECORD_FIELDS.filter((field) => input[field] !== undefined);
30261
+ if (typeof input["retract"] === "string") {
30262
+ const reason = input["reason"];
30263
+ if (typeof reason !== "string" || reason.trim() === "") {
30264
+ return "retract needs reason, the words that say why the result is wrong.";
30265
+ }
30266
+ if (carried.length > 0) {
30267
+ return `retract takes reason alone, and this call also carries ${carried.join(", ")}. Retract the result, then record a new one with a call of its own.`;
30268
+ }
30269
+ return;
30270
+ }
30271
+ if (input["reason"] !== undefined) {
30272
+ return "reason goes with retract, and this call carries no retract. Name the result to retract, or drop reason.";
30273
+ }
30274
+ const missing = RESULT_REQUIRED_FIELDS.filter((field) => input[field] === undefined);
30275
+ if (missing.length > 0) {
30276
+ return `recording a result needs ${missing.join(", ")}. ${RESULT_RETRACT_RULE}`;
30277
+ }
30278
+ return;
30279
+ }
30242
30280
  var SEARCH_QUERY_MAX = 1000;
30243
30281
  var SEARCH_QUERY_HINT = "search with a short phrase of a few words, not a passage";
30244
30282
  var SEARCH_KIND_DEPTH = 100;
@@ -30592,13 +30630,13 @@ var dispatchToolSpecs = [
30592
30630
  verdict: "pass",
30593
30631
  commit: "1111111111111111111111111111111111111111"
30594
30632
  },
30595
- description: "Record one result of one check of an issue's Verification document, and print the " + "pull-request body line it implies. The check is named by its block id, or, when two " + "Verification documents in reach share that id, by its canonical reference " + "(dispatch://KEY/artifact/verification-md#b-<id>); 409 CHECK_AMBIGUOUS names them, and an " + "id no Verification document of the issue or of an issue above it holds is 400 " + "UNKNOWN_CHECK. A pass counting any failed, skipped or excluded case contradicts itself " + "and is 400 RESULT_CONTRADICTS. Dispatch asks GitHub whether the repository of the " + "check's issue holds the commit: one it does not hold is 400 RESULT_COMMIT_UNKNOWN, " + "naming the commit and that owner/repo, so record the result after the commit is pushed. " + "A repository Dispatch cannot read records the result as before. " + "The result is recorded against the check's own issue, so " + "a child's run of a parent's check appears under that check. A closed issue takes a " + "result only for a check whose when is after_merge or default_branch \u2014 the production " + "check after the merge \u2014 and refuses every other one with 409 ISSUE_CLOSED, as it refuses " + "every other write. Write the printed line into the pull-request body unchanged: it is " + "the one grammar every writer uses, and it carries no link to Dispatch. " + ISSUE_REFERENCE,
30633
+ description: "Record one result of one check of an issue's Verification document, or retract a result " + "recorded before. A record prints the pull-request body line it implies. Write that line " + "into the pull-request body unchanged: it is the one grammar every writer uses, and it " + "carries no link to Dispatch. " + "Name the check by its block id. Where two Verification documents in reach hold that id, " + "name it by its canonical reference (dispatch://KEY/artifact/verification-md#b-<id>). " + "409 CHECK_AMBIGUOUS names both documents. An id no Verification document of the issue " + "or of an issue above it holds is 400 UNKNOWN_CHECK. " + "A pass that counts a failed, a skipped or an excluded case contradicts itself, and is " + "400 RESULT_CONTRADICTS. " + "Dispatch asks GitHub whether the repository of the check's issue holds the commit. A " + "commit that repository does not hold is 400 RESULT_COMMIT_UNKNOWN, which names the " + "commit and that owner/repo. Record the result after the commit is pushed. A repository " + "Dispatch cannot read records the result as before. " + "The result is recorded against the check's own issue, so a child's run of a parent's " + "check appears under that check. A closed issue takes a result only for a check whose " + "when is after_merge or default_branch, the production check after the merge. It refuses " + "every other record with 409 ISSUE_CLOSED, as it refuses every other write. " + RESULT_RETRACT_RULE + " The retraction keeps both records: the result stays readable, and it proves nothing " + "from then on. Record a new result where the check still needs one. A retraction is " + "taken on a closed issue and for a check of any when. Three callers may retract: the " + "session that recorded the result, a session that holds the Dispatch claim of the issue " + "the result was recorded on, and a caller whose credential carries a person. Every other " + "caller is 403 RETRACTION_FORBIDDEN. A result retracted already is 409 RESULT_RETRACTED. " + ISSUE_REFERENCE,
30596
30634
  arguments: (z) => ({
30597
- issue: z.string().describe(ISSUE_REFERENCE),
30598
- check: z.string().describe("The check block's id, or its canonical reference dispatch://KEY/artifact/verification-md#b-<id> when the id is not unique among the issue's Verification document and those of the issues above it."),
30599
- role: z.string({ max: 32 }).describe("Who ran it: implementer, tester, reviewer. At most 32 characters of a-z and -, printed in the pull-request line."),
30600
- verdict: z.enum(["pass", "fail"]).describe("Whether the check passed."),
30601
- commit: z.string().describe("The 40-character lowercase hex commit the check ran at."),
30635
+ issue: z.string().describe(ISSUE_REFERENCE).optional(),
30636
+ check: z.string().describe("The check block's id, or its canonical reference dispatch://KEY/artifact/verification-md#b-<id> when the id is not unique among the issue's Verification document and those of the issues above it.").optional(),
30637
+ role: z.string({ max: 32 }).describe("Who ran it: implementer, tester, reviewer. At most 32 characters of a-z and -, printed in the pull-request line.").optional(),
30638
+ verdict: z.enum(["pass", "fail"]).describe("Whether the check passed.").optional(),
30639
+ commit: z.string().describe("The 40-character lowercase hex commit the check ran at.").optional(),
30602
30640
  surface: z.string().describe("Where a person reaches the change.").optional(),
30603
30641
  run: z.string().describe("The command that proved it.").optional(),
30604
30642
  observed: z.string().describe("What the command printed.").optional(),
@@ -30606,28 +30644,38 @@ var dispatchToolSpecs = [
30606
30644
  failed: z.number({ int: true, min: 0 }).describe("Cases the run failed; 0 by default.").optional(),
30607
30645
  skipped: z.number({ int: true, min: 0 }).describe("Cases the run skipped; 0 by default.").optional(),
30608
30646
  excluded: z.number({ int: true, min: 0 }).describe("Cases the run excluded; 0 by default.").optional(),
30609
- screenshots: z.array(z.string()).describe("dispatch:// references to image documents of this issue or of the check's issue.").optional()
30610
- })
30647
+ screenshots: z.array(z.string()).describe("dispatch:// references to image documents of this issue or of the check's issue.").optional(),
30648
+ retract: z.string().describe("The id of a result recorded before. It records that the result is wrong, and it takes reason alone beside it.").optional(),
30649
+ reason: z.string().describe("Why the retracted result is wrong. It goes with retract and with nothing else.").optional()
30650
+ }),
30651
+ validation: {
30652
+ check: (value) => resultProblem(value) === undefined,
30653
+ message: RESULT_SHAPE_RULE,
30654
+ refusal: (value) => resultProblem(value) ?? RESULT_SHAPE_RULE
30655
+ }
30611
30656
  },
30612
30657
  {
30613
30658
  name: "dispatch_results",
30614
30659
  example: { issue: "DSP-1" },
30615
- description: "Print each check of an issue's Verification document with its latest result and whether " + "that result is current. A result is current when it ran at the commit the work stands at " + "\u2014 the head of an open pull request of the check's issue, the final head of a merged one, " + "for an after_merge check a commit on the branch that issue's pull request merged into or " + "on the repository's default branch (which answers alone where Dispatch holds no merge of " + "that issue), or for a default_branch check a commit on the repository's default branch, " + "whatever branch the pull request merged into \u2014 and the check's words have not changed " + "since; older otherwise, and unknown when Dispatch cannot read the repository. On an " + "after_merge check's base branch a read GitHub refused \u2014 a 403 or 404, which a branch it " + "no longer holds answers with \u2014 says the commit is not on that branch and leaves the " + "default branch to decide; every other failure of that read, a rate limit or a 5xx " + "among them, leaves the result unknown and never older. A push that moves the " + "pull request's head makes a result older with no write of anyone's: record it again at " + "the new head. " + ISSUE_REFERENCE,
30660
+ description: "Print each check of an issue's Verification document with every result recorded against " + "it, newest first. " + "Each check prints what Dispatch compared its results with. A before_merge check is " + "compared with the head of each pull request Dispatch holds for the check's issue, open " + "or merged. An after_merge check is compared with the branch that issue's pull request " + "merged into and with the repository's default branch, and with the default branch alone " + "where Dispatch holds no merge of the issue. A default_branch check is compared with the " + "repository's default branch alone, whatever branch the pull request merged into. Where " + "a check compared with nothing, it says which of three things happened: the issue has no " + "pull request and no branch to compare with, Dispatch cannot read the repository, or a " + "read Dispatch made did not answer. " + "Each check then prints one line that answers the gate: whether a pass of it stands, and " + "from which roles. A pass stands when its commit is one of the commits the check " + "compared with, the check's words did not move after the result was recorded, and no " + "retraction stands against it. " + "The check's own words print once, under the check. Each result then prints its verdict, " + "its role, its whole 40-character commit, where that commit stands, whether the check's " + "words moved after it was recorded, the time, its id, and the reading the role recorded. " + "A result nobody gave a reading says so. A retracted result prints as retracted, with " + "the reason and the caller that retracted it. A check with no result says so. " + "A push that moves a pull request's head leaves a result at the commit before it, with " + "no write of anyone's: record the check again at the new head. " + ISSUE_REFERENCE,
30616
30661
  arguments: (z) => ({
30617
- issue: z.string().describe(ISSUE_REFERENCE)
30662
+ issue: z.string().describe(ISSUE_REFERENCE),
30663
+ at: z.string().describe("One commit of 40 lowercase hex characters. It becomes the only thing every check is compared with, and Dispatch reads GitHub for none of it.").optional(),
30664
+ brief: z.boolean().describe("Cut each reading whose result stands at none of the compared commits to its first 200 characters. Every other reading prints whole.").optional()
30618
30665
  })
30619
30666
  },
30620
30667
  {
30621
30668
  name: "dispatch_artifact",
30622
30669
  example: { issue: "DSP-1", name: "design.md", content: `# Design
30623
30670
  ` },
30624
- 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. Never upload a document's own name to change it (spec.md replaces the spec whole); edit it with dispatch doc-edit. Uploading the same name again makes its next version, and so does uploading a document's slug (plan-md for plan.md). Exactly one of path or content is required; a markdown document is at most 1 MiB and any other file at most 25 MiB. " + `${ARTIFACT_CONTENT_NAME_RULE} ` + "Markdown is also refused with 413 CAP_EXCEEDED when it makes more than 65,536 elements (a block weighs 3, and an empty list item, quote, footnote definition or typed block 3 more for the empty paragraph it holds; a table cell 4, a hard line break 3, an image 3, a piece of inline HTML 2, an autolink 2, a footnote reference 2; inline syntax, marks, lines of text and backslash escapes or character references 1 each), or when a new version would leave the document's stored markdown (what its text reads back as) longer than 1 MiB or making more than 65,536 elements, and longer or heavier than before; shorten it or split it across documents. " + "In a table row, write every | in a cell as \\|, in code too: a | after two backslashes ends the cell, and a row with more cells than its table is refused. " + "Markdown holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK; a new version of a document is held to it only for the asks it writes or changes. " + `${OWNER_REFERENCE}`,
30671
+ 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. Never upload a document's own name to change it (spec.md replaces the spec whole); edit it with dispatch doc-edit. Exactly one of path or content is required; a markdown document is at most 1 MiB and any other file at most 25 MiB. " + `${ARTIFACT_NAME_EXISTS_RULE} ` + `${ARTIFACT_CONTENT_NAME_RULE} ${ARTIFACT_STORED_TEXT_RULE} ` + "Markdown is also refused with 413 CAP_EXCEEDED when it makes more than 65,536 elements (a block weighs 3, and an empty list item, quote, footnote definition or typed block 3 more for the empty paragraph it holds; a table cell 4, a hard line break 3, an image 3, a piece of inline HTML 2, an autolink 2, a footnote reference 2; inline syntax, marks, lines of text and backslash escapes or character references 1 each), or when a new version would leave the document's stored markdown (what its text reads back as) longer than 1 MiB or making more than 65,536 elements, and longer or heavier than before; shorten it or split it across documents. " + "In a table row, write every | in a cell as \\|, in code too: a | after two backslashes ends the cell, and a row with more cells than its table is refused. " + "Markdown holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK; a new version of a document is held to it only for the asks it writes or changes. " + `${OWNER_REFERENCE}`,
30625
30672
  arguments: (z) => ({
30626
30673
  issue: z.string().describe(ISSUE_REFERENCE).optional(),
30627
30674
  project: z.string().describe("Project key for an unlinked document.").optional(),
30628
30675
  name: z.string().describe("Artifact filename shown in Dispatch."),
30629
30676
  path: z.string().describe("Local path to the file to upload.").optional(),
30630
- content: z.string().describe("Inline text to store as a Markdown document, under a name ending in .md or .markdown or with no extension; a CR LF or a lone carriage return in it is stored as a line feed.").optional(),
30677
+ content: z.string().describe("Inline text to store as a Markdown document, under a name ending in .md or .markdown or with no extension. The command refuses a text the store would write under another spelling, a CR LF or a lone carriage return among them, which Dispatch stores as a line feed. A missing line feed at the end is not such a text: Dispatch adds one, and the upload goes on. The refusal prints the text Dispatch stores, which is the text to send.").optional(),
30678
+ force: z.boolean().describe("Write the next version of a document the owner already holds under this name; without it the upload of a name that exists is refused.").optional(),
30631
30679
  summary: z.string().describe("Optional version summary.").optional()
30632
30680
  }),
30633
30681
  validation: {
@@ -31928,8 +31976,17 @@ import {
31928
31976
  import { isAbsolute, join, resolve } from "path";
31929
31977
 
31930
31978
  // ../envoy-client/src/errors.ts
31979
+ function dispatchCode(error) {
31980
+ if (!("fromDispatch" in error) || !("code" in error))
31981
+ return;
31982
+ const code = error.code;
31983
+ return typeof code === "string" && code !== "" ? code : undefined;
31984
+ }
31931
31985
  function messageFor(error) {
31932
- return error instanceof Error ? error.message : String(error);
31986
+ if (!(error instanceof Error))
31987
+ return String(error);
31988
+ const code = dispatchCode(error);
31989
+ return code === undefined || error.message.startsWith(code) ? error.message : `${code}: ${error.message}`;
31933
31990
  }
31934
31991
  function hasErrnoCode(error, code) {
31935
31992
  return error instanceof Error && "code" in error && error.code === code;
@@ -35743,6 +35800,13 @@ class DispatchClient {
35743
35800
  return answer;
35744
35801
  throw new Error(`GET ${this.#url(path, query)} asked for the unpaged listing and got ${whyNotAnArray(answer)}.`);
35745
35802
  }
35803
+ async listIssueArtifacts(issue) {
35804
+ return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "artifacts"]);
35805
+ }
35806
+ async markdownRoundTrip(markdown) {
35807
+ const answer = await this.#json("POST", ["api", "v1", "markdown", "round-trip"], { markdown });
35808
+ return answer.markdown;
35809
+ }
35746
35810
  async listProjectArtifacts(project, unlinked = false) {
35747
35811
  return this.#json("GET", ["api", "v1", "projects", project, "artifacts"], undefined, unlinked ? { unlinked: "true" } : undefined);
35748
35812
  }
@@ -35930,8 +35994,11 @@ class DispatchClient {
35930
35994
  async recordResult(issue, input) {
35931
35995
  return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"], input);
35932
35996
  }
35933
- async issueResults(issue) {
35934
- return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"]);
35997
+ async issueResults(issue, at) {
35998
+ return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"], undefined, at === undefined ? undefined : { at });
35999
+ }
36000
+ async retractResult(resultID, input) {
36001
+ return this.#json("POST", ["api", "v1", "results", resultID, "retract"], input);
35935
36002
  }
35936
36003
  async editAsk(id, input) {
35937
36004
  return this.#json("PATCH", ["api", "v1", "asks", id], input);
@@ -36006,6 +36073,9 @@ class DispatchClient {
36006
36073
  async docRead(id, version) {
36007
36074
  return version === undefined ? this.#json("GET", ["api", "v1", "artifacts", id, "text"]) : this.#json("GET", ["api", "v1", "artifacts", id, "versions", String(version)]);
36008
36075
  }
36076
+ async docReadWithBlocks(id) {
36077
+ return this.#json("GET", ["api", "v1", "artifacts", id, "text"], undefined, { blocks: true });
36078
+ }
36009
36079
  async fileVersion(id, version) {
36010
36080
  const url = this.#url(["api", "v1", "artifacts", id, "versions", String(version)]);
36011
36081
  const response = await this.#send("GET", url, undefined, "*/*");
@@ -40357,11 +40427,11 @@ async function readSessionAnswers(options) {
40357
40427
  class ToolInputError extends Error {
40358
40428
  tool;
40359
40429
  problems;
40360
- constructor(tool, problems) {
40430
+ constructor(tool, problems, options) {
40361
40431
  const count = problems.length;
40362
40432
  const cli = isDispatchTool(tool);
40363
40433
  const help = cli ? [
40364
- `Allowed flags: ${commandFlags(tool).join(", ")}`,
40434
+ ...options?.aboutAFlag === false ? [] : [`Allowed flags: ${commandFlags(tool).join(", ")}`],
40365
40435
  `Example: ${commandLine(tool, exampleFor(tool))}`
40366
40436
  ] : [];
40367
40437
  super([
@@ -40789,6 +40859,9 @@ async function resolveOwnerArguments(tool, input, cwd, env, exec, dashboardUrls,
40789
40859
  if (tool === "dispatch_read" && typeof args.message === "string") {
40790
40860
  return { args, ref, owner: null };
40791
40861
  }
40862
+ if (tool === "dispatch_result" && typeof args["retract"] === "string") {
40863
+ return { args, ref, owner: null };
40864
+ }
40792
40865
  const legionIssue = env.LEGION_ISSUE;
40793
40866
  if (!legionIssue) {
40794
40867
  problems.push(ownerRequiredProblem);
@@ -40944,12 +41017,16 @@ function boundedEditDistance(a, b, limit) {
40944
41017
  return Math.min(previous[b.length], limit + 1);
40945
41018
  }
40946
41019
  async function liveBlocks(client, artifact) {
40947
- const before = await client.docRead(artifact.id);
40948
- const blocks = await client.artifactBlocks(artifact.id);
40949
- const after = await client.docRead(artifact.id);
40950
- if (before.token !== after.token || before.markdown !== after.markdown)
40951
- return;
40952
- return { bytes: new TextEncoder().encode(before.markdown), token: before.token, blocks };
41020
+ const read = await client.docReadWithBlocks(artifact.id);
41021
+ if (read.blocks === undefined) {
41022
+ throw new Error(`${artifact.name} was read from a Dispatch older than this command: it serves a document's blocks only on their own route, not beside the text they index, so nothing was listed.`);
41023
+ }
41024
+ return {
41025
+ bytes: new TextEncoder().encode(read.markdown),
41026
+ token: read.token,
41027
+ version: read.version ?? null,
41028
+ blocks: read.blocks
41029
+ };
40953
41030
  }
40954
41031
  async function readDocumentBlocks(client, target, context) {
40955
41032
  const tool = "dispatch_doc_edit";
@@ -40969,9 +41046,6 @@ async function readDocumentBlocks(client, target, context) {
40969
41046
  throw error;
40970
41047
  }
40971
41048
  const live = await liveBlocks(client, resolved.artifact);
40972
- if (live === undefined) {
40973
- throw new Error(`${resolved.artifact.name} changed while its blocks were read, so their byte ranges could slice the wrong text; nothing was read. Read it again.`);
40974
- }
40975
41049
  const decoder = new TextDecoder;
40976
41050
  return {
40977
41051
  name: resolved.artifact.name,
@@ -42775,7 +42849,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
42775
42849
 
42776
42850
  // package.json
42777
42851
  var name = "@sjawhar/pi-envoy";
42778
- var version2 = "17.0.0";
42852
+ var version2 = "17.1.0";
42779
42853
  var package_default = {
42780
42854
  name,
42781
42855
  version: version2,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "17.0.0",
3
+ "version": "17.1.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {