@sjawhar/pi-envoy 16.0.0 → 16.2.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
@@ -22,8 +22,10 @@ The same route forwards a team or other ad-hoc topic's message to each session r
22
22
  topic that holds its own NATS connection, as this one does, other than its sender, and the sender's
23
23
  error names each session that did not reply. The stream stores each forward on the recipient's
24
24
  agent subject, and when the listener supports consumer delivery that session takes the stored copy
25
- once, also after a restart or a dropped connection (below). A role message is not kept for a later
26
- claimant, and on the core path a session does not recover one it missed.
25
+ once, also after a restart or a dropped connection (below). A role message no live holder can take
26
+ is kept for the session that claims the role next. That session is handed the message once, within
27
+ one hour of the keep, and the publish answers 202 to say the listener kept it. On the core path a
28
+ session does not recover a role message it missed.
27
29
 
28
30
  This extension claims the role for the session the host has open, and every automatic claim is
29
31
  soft: it names the session it continues, which is a fork's or branch's parent, or the session
package/dist/dispatch.js CHANGED
@@ -14963,7 +14963,12 @@ function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false)
14963
14963
  message: alwaysRequireArtifact ? "Exactly one of issue and project is required; artifact or ref must name the document." : "Exactly one of issue and project is required; with project, artifact names the document."
14964
14964
  };
14965
14965
  }
14966
- var ARTIFACT_OWNER_AND_SOURCE_RULE = "Exactly one of path or content is required. Exactly one of issue and project is required; with project, artifact names the document.";
14966
+ var ARTIFACT_SOURCE_RULE = "Exactly one of path or content is required.";
14967
+ var ARTIFACT_OWNER_AND_SOURCE_RULE = `${ARTIFACT_SOURCE_RULE} Exactly one of issue and project is required; with project, artifact names the document.`;
14968
+ function brokenParts(parts) {
14969
+ const broken = parts.filter(([kept]) => !kept).map(([, message]) => message);
14970
+ return broken.length === 0 ? undefined : broken.join(" ");
14971
+ }
14967
14972
  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)";
14968
14973
  var PATH_KEEPS_BYTES = "path (--path <file>), which stores a file whose path does not end in .md or .markdown as its bytes, unchanged";
14969
14974
  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}.`;
@@ -14972,9 +14977,15 @@ var MARKDOWN_EXTENSION = /^(md|markdown)$/i;
14972
14977
  var artifactOwner = documentOwnerValidation(false);
14973
14978
  function artifactProblem(value) {
14974
14979
  const input = value;
14975
- if (!artifactOwner.check(value) || typeof input.path === "string" === (typeof input.content === "string")) {
14976
- return ARTIFACT_OWNER_AND_SOURCE_RULE;
14977
- }
14980
+ const ownerOrSourceProblem = brokenParts([
14981
+ [artifactOwner.check(value), artifactOwner.message],
14982
+ [
14983
+ typeof input.path === "string" !== (typeof input.content === "string"),
14984
+ ARTIFACT_SOURCE_RULE
14985
+ ]
14986
+ ]);
14987
+ if (ownerOrSourceProblem !== undefined)
14988
+ return ownerOrSourceProblem;
14978
14989
  if (typeof input.content !== "string" || typeof input.name !== "string")
14979
14990
  return;
14980
14991
  const extension = NAME_EXTENSION.exec(input.name.trim())?.[1];
@@ -14983,27 +14994,40 @@ function artifactProblem(value) {
14983
14994
  return `${CONTENT_IS_MARKDOWN}, and ${JSON.stringify(input.name)} is not a Markdown name. Upload the file under the same name with ${PATH_KEEPS_BYTES}; content takes a name ending in .md or .markdown or with no extension.`;
14984
14995
  }
14985
14996
  var documentEditOwner = documentOwnerValidation(true);
14997
+ var PRECONDITION_RULE = "A precondition selects exactly one of document or blocks.";
14998
+ function preconditionKept(value) {
14999
+ const input = value;
15000
+ if (input.precondition === undefined)
15001
+ return true;
15002
+ if (typeof input.precondition !== "object" || input.precondition === null)
15003
+ return false;
15004
+ const precondition = input.precondition;
15005
+ return typeof precondition.document === "string" !== Array.isArray(precondition.blocks);
15006
+ }
15007
+ function documentEditProblem(value) {
15008
+ return brokenParts([
15009
+ [documentEditOwner.check(value), documentEditOwner.message],
15010
+ [preconditionKept(value), PRECONDITION_RULE]
15011
+ ]);
15012
+ }
14986
15013
  var documentEditValidation = {
14987
- check: (value) => {
14988
- if (!documentEditOwner.check(value))
14989
- return false;
14990
- const input = value;
14991
- if (input.precondition === undefined)
14992
- return true;
14993
- if (typeof input.precondition !== "object" || input.precondition === null)
14994
- return false;
14995
- const precondition = input.precondition;
14996
- return typeof precondition.document === "string" !== Array.isArray(precondition.blocks);
14997
- },
14998
- message: `${documentEditOwner.message} A precondition selects exactly one of document or blocks.`
15014
+ check: (value) => documentEditProblem(value) === undefined,
15015
+ message: `${documentEditOwner.message} ${PRECONDITION_RULE}`,
15016
+ refusal: (value) => documentEditProblem(value) ?? `${documentEditOwner.message} ${PRECONDITION_RULE}`
14999
15017
  };
15000
15018
  var commentOwner = documentOwnerValidation(true);
15019
+ var COMMENT_TURN_RULE = "turn requires reply_to_ask: turn says who holds an open ask's thread after the reply. Pass reply_to_ask with the open ask's id, or drop turn.";
15020
+ function commentProblem(value) {
15021
+ const input = value;
15022
+ return brokenParts([
15023
+ [commentOwner.check(value), commentOwner.message],
15024
+ [input.turn === undefined || typeof input.reply_to_ask === "string", COMMENT_TURN_RULE]
15025
+ ]);
15026
+ }
15001
15027
  var commentValidation = {
15002
- check: (value) => {
15003
- const input = value;
15004
- return commentOwner.check(value) && (input.turn === undefined || typeof input.reply_to_ask === "string");
15005
- },
15006
- message: `${commentOwner.message} turn requires reply_to_ask.`
15028
+ check: (value) => commentProblem(value) === undefined,
15029
+ message: `${commentOwner.message} ${COMMENT_TURN_RULE}`,
15030
+ refusal: (value) => commentProblem(value) ?? `${commentOwner.message} ${COMMENT_TURN_RULE}`
15007
15031
  };
15008
15032
  var ISSUE_UPDATE_FIELDS_RULE = "Issue update requires at least one field besides issue: status, title, labels, priority, external_links, route, parent, blocked_by, components, repo, before, or after.";
15009
15033
  var ISSUE_UPDATE_DONE_RULE = "status done requires reason, a non-empty note saying why the issue is closing, posted on the issue before it closes because a closed issue refuses messages, comments, and artifacts";
@@ -15030,14 +15054,20 @@ var messageValidation = {
15030
15054
  message: "issue is required unless in_reply_to names a message delivered to this session, which is the one message with no issue."
15031
15055
  };
15032
15056
  var readOwner = documentOwnerValidation(false);
15057
+ var READ_OWNER_RULE = "Exactly one of issue and project is required; project alone lists its documents, and with artifact names one.";
15058
+ var READ_MESSAGE_RULE = "message stands alone: it names the conversation, so name no issue, project, artifact, or ref with it.";
15059
+ function readProblem(value) {
15060
+ const input = value;
15061
+ if (typeof input.message !== "string") {
15062
+ return readOwner.check(value) ? undefined : READ_OWNER_RULE;
15063
+ }
15064
+ const alone = input.issue === undefined && input.project === undefined && input.artifact === undefined && input.ref === undefined;
15065
+ return alone ? undefined : READ_MESSAGE_RULE;
15066
+ }
15033
15067
  var readValidation = {
15034
- check: (value) => {
15035
- const input = value;
15036
- if (typeof input.message !== "string")
15037
- return readOwner.check(value);
15038
- return input.issue === undefined && input.project === undefined && input.artifact === undefined && input.ref === undefined;
15039
- },
15040
- message: "Exactly one of issue and project is required; project alone lists its documents, and with artifact names one. " + "message stands alone: it names the conversation, so name no issue, project, artifact, or ref with it."
15068
+ check: (value) => readProblem(value) === undefined,
15069
+ message: `${READ_OWNER_RULE} ${READ_MESSAGE_RULE}`,
15070
+ refusal: (value) => readProblem(value) ?? `${READ_OWNER_RULE} ${READ_MESSAGE_RULE}`
15041
15071
  };
15042
15072
  var ISSUE_COMPONENTS_MODES = ["inherit", "explicit", "none"];
15043
15073
  function componentsArgument(z) {
@@ -15375,13 +15405,13 @@ var dispatchToolSpecs = [
15375
15405
  {
15376
15406
  name: "dispatch_doc_read",
15377
15407
  example: { issue: "DSP-1" },
15378
- 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. With blocks it lists the live document's blocks instead of its markdown, in document order: each block's id, type, token, anchored comments and asks, and opening words, and under a table each row by the index delete_row takes and each cell by its row and the column delete_column takes; block ids, block tokens and those indexes are what dispatch doc-edit takes. " + "After the markdown it prints every open thread anchored on the document in full: an open ask with its id and question and each reply's author, time and text, and a comment thread with its root's id, author, time, quote and text and each reply's author, time and text, in order; a resolved thread, and an ask that is answered or resolved, is not printed. " + "A picture (an uploaded PNG, JPEG, GIF or WebP of at most 3,750,000 bytes, 5 MB once base64-encoded) comes back as an image you see, with its name, type, size and version, every time you ask, including one a read already showed this session; " + "any other file that is not UTF-8 text is described, with the route that serves its bytes. " + OWNER_REFERENCE,
15408
+ 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. With blocks it lists the live document's blocks instead of its markdown, in document order: each block's id, type, token, anchored comments and asks, and opening words, a typed block's serves and needs under it, and under a table each row by the index delete_row takes and each cell by its row and the column delete_column takes; block ids, block tokens and those indexes are what dispatch doc-edit takes. " + "After the markdown it prints every open thread anchored on the document in full: an open ask with its id and question and each reply's author, time and text, and a comment thread with its root's id, author, time, quote and text and each reply's author, time and text, in order; a resolved thread, and an ask that is answered or resolved, is not printed. " + "A picture (an uploaded PNG, JPEG, GIF or WebP of at most 3,750,000 bytes, 5 MB once base64-encoded) comes back as an image you see, with its name, type, size and version, every time you ask, including one a read already showed this session; " + "any other file that is not UTF-8 text is described, with the route that serves its bytes. " + OWNER_REFERENCE,
15379
15409
  arguments: (z) => ({
15380
15410
  issue: z.string().describe(ISSUE_REFERENCE).optional(),
15381
15411
  project: z.string().describe("Project key owning the document.").optional(),
15382
15412
  artifact: z.string().describe("Optional project document artifact id, slug, or filename; primary document by default for an issue.").optional(),
15383
15413
  version: z.number({ int: true, min: 1 }).describe("Optional version number.").optional(),
15384
- blocks: z.boolean().describe("List the live document's blocks, with each table's rows and cells, instead of its markdown; refused with a version, or for an uploaded file.").optional(),
15414
+ blocks: z.boolean().describe("List the live document's blocks, with a typed block's serves and needs and each table's rows and cells, instead of its markdown; refused with a version, or for an uploaded file.").optional(),
15385
15415
  ref: z.string().describe("Optional dispatch:// document reference; a picture in a conversation on the Agents page is dispatch://agent/<session id>/artifact/<slug>@vN.").optional()
15386
15416
  }),
15387
15417
  validation: documentOwnerValidation(true)
@@ -15389,15 +15419,60 @@ var dispatchToolSpecs = [
15389
15419
  {
15390
15420
  name: "dispatch_request_approval",
15391
15421
  example: { issue: "DSP-1", summary: "A live sync replaces the nightly export." },
15392
- description: "Ask a human to approve a document at its current version. Before calling, have a fresh read-only reader check the spec against the code and the human's words, then resolve every finding; a Legion architect runs `plan-gap-analyst` and `plan-reviewer`. Opens an approval ask (Approve / " + "Request changes) in the human's Inbox whose question names the document and version, " + "followed by the summary; the answer pins a review to that version and arrives as " + "artifact.approved or artifact.changes_requested. An open request follows the document: a " + "later version moves it to that version and leaves it waiting on you, as a human's reply in " + "its thread does. Only the first move since the request was opened or handed back sends an " + "event, and never to the session whose version made it; dispatch doc-read shows whom it " + "waits on. Once the revision is complete and " + HUMAN_AGREED_TO_DOCUMENT + ", call this again to hand that same Inbox row back. The request carries nothing new. A " + "call while it already waits on the human hands nothing back: the same summary changes " + "nothing, and a different one is refused, since it would rewrite the card the human is " + "reading. Approve and Request changes each close the request, so the next call opens a new " + "one. Call it once per revision, when the revision is complete, never after each edit. An " + "approval goes stale when the document changes outside its decision blocks after it, until " + "a later version's text is exactly the approved version's again, as when an accidental " + "edit is undone exactly, and no decision block in it was decided since: that version " + "carries the approval and the document reads approved at it, so nothing is requested for " + "it. When the document does not read approved, request approval again once that revision " + "is complete and " + HUMAN_AGREED_TO_DOCUMENT + ", with a one-sentence summary naming what changed since the earlier approval: the card " + "names that approval (version, date, reviewer) and its Show diff control carries the detail. " + "A human's own answer to a decision block carries the approval to the version it writes when " + "that answer is the whole change since the approved version, so nothing is requested for " + "it. A new version of a Legion root spec closes its armed design gate until a human " + "approves it; a carried approval reopens it too. " + "Refused, with nothing sent, while the document holds an open decision block, even when a " + "human asked for approval: the refusal names each block; ask the human to answer or waive " + "it first. " + OWNER_REFERENCE,
15422
+ description: "Ask a human to approve a document at its current version. Before calling, have a fresh read-only reader check the spec against the code and the human's words, then resolve every finding; a Legion architect runs `plan-gap-analyst` and `plan-reviewer`. Opens an approval ask (Approve / " + "Request changes) in the human's Inbox whose question names the document and version, " + "followed by the summary; the answer pins a review to that version and arrives as " + "artifact.approved or artifact.changes_requested. An open request follows the document: a " + "later version moves it to that version and leaves it waiting on you, as a human's reply in " + "its thread does. Only the first move since the request was opened or handed back sends an " + "event, and never to the session whose version made it; dispatch doc-read shows whom it " + "waits on. Once the revision is complete and " + HUMAN_AGREED_TO_DOCUMENT + ", call this again to hand that same Inbox row back. The request carries nothing new. A " + "call while it already waits on the human hands nothing back: the same summary changes " + "nothing, and a different one is refused, since it would rewrite the card the human is " + "reading. Approve and Request changes each close the request, so the next call opens a new " + "one. Call it once per revision, when the revision is complete, never after each edit. An " + "approval goes stale when the document changes outside its decision blocks after it, until " + "a later version's text is exactly the approved version's again, as when an accidental " + "edit is undone exactly, and no decision block in it was decided since: that version " + "carries the approval and the document reads approved at it, so nothing is requested for " + "it. When the document does not read approved, request approval again once that revision " + "is complete and " + HUMAN_AGREED_TO_DOCUMENT + ", with a one-sentence summary naming what changed since the earlier approval: the card " + "names that approval (version, date, reviewer) and its Show diff control carries the detail. " + "A human's own answer to a decision block carries the approval to the version it writes when " + "that answer is the whole change since the approved version, so nothing is requested for " + "it. A new version of a Legion root spec closes its armed design gate until a human " + "approves it; a carried approval reopens it too. " + "Refused, with nothing sent, while the document holds an open decision block, even when a " + "human asked for approval: the refusal names each block; ask the human to answer or waive " + "it first. " + "Refused 409 PLAN_APPROVED_BY_REVIEW on an issue's plan, which its plan review approves " + "(dispatch plan-approve), never a person. " + "On an issue's spec the answer ends with a `Coverage of <name>:` line naming each requirement " + "the spec marks that no check serves, in any document of the issue or of its descendants, or saying " + "the spec marks no requirements; a spec every requirement of which has a check gets no such line. It never " + "names a missing plan task, and a gap refuses nothing. " + OWNER_REFERENCE,
15393
15423
  arguments: (z) => ({
15394
15424
  issue: z.string().describe(ISSUE_REFERENCE).optional(),
15395
15425
  project: z.string().describe("Project key owning the document.").optional(),
15396
15426
  artifact: z.string().describe("Project document artifact id, slug, or filename; primary document by default for an issue.").optional(),
15397
- summary: z.string({ min: 1 }).describe(`What the human is approving, in one to three sentences, and nothing else: no commentary on itself or the conversation, and no question; after an earlier approval, one sentence naming what changed since it, since the card shows that approval and a diff. A Legion architect adds one last sentence with its two spec reviews' results. Request approval only once ${HUMAN_AGREED_TO_DOCUMENT}.`)
15427
+ summary: z.string({ min: 1 }).describe(`What the human is approving, in one to three sentences, and nothing else: no commentary on itself or the conversation, and no question; after an earlier approval, one sentence naming what changed since it, since the card shows that approval and a diff. A Legion architect adds one last sentence with its two spec reviews' results. Request approval only once ${HUMAN_AGREED_TO_DOCUMENT}.`),
15428
+ include_verification: z.boolean().describe("Ask for the issue's Verification document in the same request, beside this one: one Inbox card names both at their current versions, and the answer records the human's review on each. 409 NO_VERIFICATION_DOCUMENT when the issue has no verification.md. Without it the request names this document alone and records nothing on the Verification document.").optional()
15398
15429
  }),
15399
15430
  validation: documentOwnerValidation(true)
15400
15431
  },
15432
+ {
15433
+ name: "dispatch_plan_approve",
15434
+ example: { issue: "DSP-1", version: 2 },
15435
+ description: "Record the plan review's approval of an issue's plan at the version it reviewed. A plan is " + "approved by that review, never by a person: dispatch request-approval on a plan is refused " + "409 PLAN_APPROVED_BY_REVIEW, so no plan approval ever reaches a human's Inbox. The approval " + "is pinned to the version named, so a later plan version makes it stale and the review runs " + "again. Refused 409 NOT_PLAN_DOCUMENT on any other document, the issue's spec included, and " + "400 INVALID_REVIEW for a version the plan does not have. " + ISSUE_REFERENCE,
15436
+ arguments: (z) => ({
15437
+ issue: z.string().describe(ISSUE_REFERENCE),
15438
+ artifact: z.string().describe("Plan document artifact id, slug, or filename; the issue's plan.md by default.").optional(),
15439
+ version: z.number({ int: true, min: 1 }).describe("The plan version the review read and approved.")
15440
+ })
15441
+ },
15442
+ {
15443
+ name: "dispatch_result",
15444
+ example: {
15445
+ issue: "DSP-1",
15446
+ check: "k1",
15447
+ role: "implementer",
15448
+ verdict: "pass",
15449
+ commit: "1111111111111111111111111111111111111111"
15450
+ },
15451
+ 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. 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,
15452
+ arguments: (z) => ({
15453
+ issue: z.string().describe(ISSUE_REFERENCE),
15454
+ 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."),
15455
+ 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."),
15456
+ verdict: z.enum(["pass", "fail"]).describe("Whether the check passed."),
15457
+ commit: z.string().describe("The 40-character lowercase hex commit the check ran at."),
15458
+ surface: z.string().describe("Where a person reaches the change.").optional(),
15459
+ run: z.string().describe("The command that proved it.").optional(),
15460
+ observed: z.string().describe("What the command printed.").optional(),
15461
+ negative_control: z.string().describe("The deliberately broken input and the refusal seen.").optional(),
15462
+ failed: z.number({ int: true, min: 0 }).describe("Cases the run failed; 0 by default.").optional(),
15463
+ skipped: z.number({ int: true, min: 0 }).describe("Cases the run skipped; 0 by default.").optional(),
15464
+ excluded: z.number({ int: true, min: 0 }).describe("Cases the run excluded; 0 by default.").optional(),
15465
+ screenshots: z.array(z.string()).describe("dispatch:// references to image documents of this issue or of the check's issue.").optional()
15466
+ })
15467
+ },
15468
+ {
15469
+ name: "dispatch_results",
15470
+ example: { issue: "DSP-1" },
15471
+ 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, " + "or, for an after_merge or default_branch check, a commit on the repository's default " + "branch \u2014 and the check's words have not changed since; older otherwise, and unknown when " + "Dispatch cannot read the repository. 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,
15472
+ arguments: (z) => ({
15473
+ issue: z.string().describe(ISSUE_REFERENCE)
15474
+ })
15475
+ },
15401
15476
  {
15402
15477
  name: "dispatch_artifact",
15403
15478
  example: { issue: "DSP-1", name: "design.md", content: `# Design
@@ -15420,7 +15495,7 @@ var dispatchToolSpecs = [
15420
15495
  {
15421
15496
  name: "dispatch_read",
15422
15497
  example: { issue: "DSP-1" },
15423
- description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), project plus artifact, or project alone, which lists the project's documents on no issue and nothing more; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An issue read lists every document, picture and file the issue holds under `Documents:`, each by slug, filename and kind. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + `An issue read, and its dispatch://KEY/log, lists the issue's last ${DEFAULT_ISSUE_READ_EVENTS} events, oldest first; ` + "--events N lists the last N, and --all-events every one. " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + "A block read prints `Block:`, `Document:`, `Changed in version:` and `Text:`, then those two sections; a pinned one adds " + "the block's text at that version and whether it is unchanged, changed or removed since, and an absent block, unpinned, " + "reads `No block <id> in <document>.` " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
15498
+ description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), project plus artifact, or project alone, which lists the project's documents on no issue and nothing more; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An issue read lists every document, picture and file the issue holds under `Documents:`, each by slug, filename and kind. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + "An issue whose spec marks requirements carries one `Coverage:` line per gap, `Coverage: R3 has no check` or " + "`Coverage: R3 has no plan task` (the second only once the issue has a plan document), counting the `check` and " + "`plan_task` blocks of every document of the issue and of its descendants; a spec that marks none reads " + "`Coverage: the spec marks no requirements`. Nothing is refused for a gap. " + `An issue read, and its dispatch://KEY/log, lists the issue's last ${DEFAULT_ISSUE_READ_EVENTS} events, oldest first; ` + "--events N lists the last N, and --all-events every one. " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + "A block read prints `Block:`, `Type:` for a block of a document, `Document:`, every attribute a typed block carries " + "(a `check`'s serves, surface, run, when and negative_control; a `plan_task`'s serves and needs), `Changed in version:` " + "and `Text:`, then those two sections; a pinned one adds " + "the block's text at that version and whether it is unchanged, changed or removed since, and an absent block, unpinned, " + "reads `No block <id> in <document>.` " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
15424
15499
  arguments: (z) => ({
15425
15500
  issue: z.string().describe(ISSUE_REFERENCE).optional(),
15426
15501
  project: z.string().describe("Project key owning the document.").optional(),
@@ -15869,6 +15944,7 @@ var EnvelopeSchema = object({
15869
15944
  dedupe_key: string2().min(1),
15870
15945
  issued_at: number2().int(),
15871
15946
  expires_at: number2().int().optional(),
15947
+ kept_at: number2().int().optional(),
15872
15948
  payload_summary: string2().min(1),
15873
15949
  payload: string2().optional(),
15874
15950
  payload_ref: string2().optional(),
@@ -17141,6 +17217,15 @@ class DispatchClient {
17141
17217
  const answer = await this.#jsonAnswer("POST", ["api", "v1", "artifacts", artifactID, "approval-requests"], input);
17142
17218
  return { ...answer.payload, recorded: answer.status === 201 };
17143
17219
  }
17220
+ async planApprove(artifactID, input) {
17221
+ return this.#json("POST", ["api", "v1", "artifacts", artifactID, "plan-reviews"], input);
17222
+ }
17223
+ async recordResult(issue, input) {
17224
+ return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"], input);
17225
+ }
17226
+ async issueResults(issue) {
17227
+ return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"]);
17228
+ }
17144
17229
  async editAsk(id, input) {
17145
17230
  return this.#json("PATCH", ["api", "v1", "asks", id], input);
17146
17231
  }
@@ -17224,6 +17309,15 @@ class DispatchClient {
17224
17309
  async artifactBlocks(id) {
17225
17310
  return this.#json("GET", ["api", "v1", "artifacts", id, "blocks"]);
17226
17311
  }
17312
+ async issueArtifactBlocks(issue, slug) {
17313
+ return this.#json("GET", ["api", "v1", "issues", issue, "artifacts", slug, "blocks"]);
17314
+ }
17315
+ async projectArtifactBlocks(project, slug) {
17316
+ return this.#json("GET", ["api", "v1", "projects", project, "artifacts", slug, "blocks"]);
17317
+ }
17318
+ async issueCoverage(key) {
17319
+ return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(key), "coverage"]);
17320
+ }
17227
17321
  async commentBlocks(id) {
17228
17322
  return this.#json("GET", ["api", "v1", "comments", id, "blocks"]);
17229
17323
  }
@@ -18599,6 +18693,12 @@ function stringArg(args, name) {
18599
18693
  throw new Error(`${name} is required`);
18600
18694
  return value;
18601
18695
  }
18696
+ function numberArg(args, name) {
18697
+ const value = args[name];
18698
+ if (typeof value !== "number")
18699
+ throw new Error(`${name} is required`);
18700
+ return value;
18701
+ }
18602
18702
  function optionalString(args, name) {
18603
18703
  const value = args[name];
18604
18704
  return typeof value === "string" ? value : undefined;
@@ -18611,6 +18711,13 @@ function optionalNumber(args, name) {
18611
18711
  const value = args[name];
18612
18712
  return typeof value === "number" ? value : undefined;
18613
18713
  }
18714
+ function defined(name, value) {
18715
+ return value === undefined ? {} : { [name]: value };
18716
+ }
18717
+ function optionalStringArray(args, name) {
18718
+ const value = args[name];
18719
+ return Array.isArray(value) ? value : undefined;
18720
+ }
18614
18721
  function optionalPriority(args, name) {
18615
18722
  const value = args[name];
18616
18723
  if (value === null)
@@ -19534,6 +19641,24 @@ function progressText(progress, sep) {
19534
19641
  }
19535
19642
  return parts.join(sep);
19536
19643
  }
19644
+ function formatCheckResults(results) {
19645
+ if (results.verification_artifact_id === "") {
19646
+ 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.`;
19647
+ }
19648
+ if (results.checks.length === 0) {
19649
+ return `${results.issue}'s Verification document holds no check blocks.`;
19650
+ }
19651
+ const lines = results.checks.map((check) => {
19652
+ const head = `- ${check.block_id} (${check.when}): `;
19653
+ const latest = check.results[0];
19654
+ if (latest === undefined) {
19655
+ return `${head}no result yet. ${check.text}`;
19656
+ }
19657
+ return `${head}${latest.verdict} at ${latest.commit_sha.slice(0, 12)} by ${latest.role}, ${latest.currency ?? "unknown"}. ${check.text}`;
19658
+ });
19659
+ return [`Checks of ${results.issue}:`, ...lines].join(`
19660
+ `);
19661
+ }
19537
19662
  function repositoryLine(issue) {
19538
19663
  if (issue.resolved_repo === undefined) {
19539
19664
  return "Repository: unknown (this Dispatch server predates repository fields; upgrade it)";
@@ -19559,7 +19684,7 @@ function refuseUnsavedRepository(verb, issue, repo) {
19559
19684
  const lost = repo === "" ? "the repository was not cleared" : `${repo} was not saved`;
19560
19685
  throw new Error(`Dispatch ${verb} ${issue.key} without its repository: this Dispatch server predates repository fields, so ${lost}; upgrade the server`);
19561
19686
  }
19562
- function issueSummary(issue, events, references, graph, linkBase, titles) {
19687
+ function issueSummary(issue, events, references, graph, linkBase, coverage, titles) {
19563
19688
  const asks = issue.open_asks;
19564
19689
  const spec = issue.artifacts?.find((artifact) => artifact.primary);
19565
19690
  const specApproval = spec === undefined ? undefined : approvalLine(spec);
@@ -19588,6 +19713,7 @@ function issueSummary(issue, events, references, graph, linkBase, titles) {
19588
19713
  repositoryLine(issue),
19589
19714
  `Progress: ${progressText(issue.progress, ", ") || "none"}`,
19590
19715
  ...specApproval === undefined ? [] : [`Spec ${specApproval.replace(/^Approval/, "approval")}`],
19716
+ ...typeof coverage === "string" ? [`Coverage: ${coverage}`] : coverage.gaps.map((gap) => `Coverage: ${gap}`),
19591
19717
  "External links:",
19592
19718
  ...issue.external_links.length === 0 ? ["- none"] : issue.external_links.map((link) => `- ${link.url}${link.kind === undefined ? "" : ` (${link.kind})`}`),
19593
19719
  "Documents:",
@@ -19639,6 +19765,13 @@ async function issueReferencesOrUnavailable(client, key) {
19639
19765
  return unavailableReason(error);
19640
19766
  }
19641
19767
  }
19768
+ async function issueCoverageOrReason(client, key) {
19769
+ try {
19770
+ return await client.issueCoverage(key);
19771
+ } catch (error) {
19772
+ return unavailableReason(error);
19773
+ }
19774
+ }
19642
19775
  async function graphSections(client, ref) {
19643
19776
  const [incoming, outgoing] = await Promise.all([
19644
19777
  graphReferences(client, { to: ref }),
@@ -19667,12 +19800,14 @@ function nodeLine(node) {
19667
19800
  `Node: ${node.kind} ${node.ref ?? node.id} \xB7 made by ${made} \xB7 changed by ${changed}${partOf}`
19668
19801
  ];
19669
19802
  }
19670
- function blockLines(node, ref, noun = "Block") {
19803
+ function blockLines(node, ref, typed, noun = "Block") {
19671
19804
  const unit = ref.item === undefined ? "version" : "revision";
19672
19805
  const blockID = node.block_id ?? ref.block;
19673
19806
  const head = ref.item === undefined ? [
19674
19807
  `Block: ${blockID}`,
19808
+ ...typed === undefined ? [] : [`Type: ${typed.type}`],
19675
19809
  `Document: ${node.document ?? ref.document}`,
19810
+ ...(typed?.attributes ?? []).map((attribute) => `${attribute.name}: ${attribute.value === "" ? "(empty)" : attribute.value}`),
19676
19811
  ...node.changed_version === undefined ? [] : [`Changed in version: ${node.changed_version}`],
19677
19812
  ...node.text === undefined ? [] : ["Text:", node.text]
19678
19813
  ] : [
@@ -19691,6 +19826,16 @@ function blockLines(node, ref, noun = "Block") {
19691
19826
  pin.text
19692
19827
  ];
19693
19828
  }
19829
+ async function typedBlockOf(client, ref) {
19830
+ if (ref.item !== undefined || ref.block === undefined)
19831
+ return;
19832
+ try {
19833
+ const blocks = ref.owner.kind === "project" ? await client.projectArtifactBlocks(ref.owner.project, ref.id) : await client.issueArtifactBlocks(ref.owner.issue, ref.id);
19834
+ return blocks.find((block) => block.id === ref.block);
19835
+ } catch {
19836
+ return;
19837
+ }
19838
+ }
19694
19839
  function askPartNoun(ask, node, blockID) {
19695
19840
  if (ask.answer?.id === blockID)
19696
19841
  return "Answer";
@@ -20060,7 +20205,7 @@ async function listDocumentBlocks(client, artifact) {
20060
20205
  const { bytes, blocks } = live;
20061
20206
  const decoder = new TextDecoder;
20062
20207
  const lines = [
20063
- `Blocks of ${artifact.name}, in document order, each indented under the block holding it: id, type, (token; anchored comments and asks), opening words. A table lists its rows by the index delete_row takes and its cells by the row and the column delete_column takes.`
20208
+ `Blocks of ${artifact.name}, in document order, each indented under the block holding it: id, type, (token; anchored comments and asks), opening words, then a typed block's serves and needs. A table lists its rows by the index delete_row takes and its cells by the row and the column delete_column takes.`
20064
20209
  ];
20065
20210
  const holders = [];
20066
20211
  for (const block of blocks) {
@@ -20072,6 +20217,11 @@ async function listDocumentBlocks(client, artifact) {
20072
20217
  const opening = points.length > BLOCK_OPENING_CHARS ? `${points.slice(0, BLOCK_OPENING_CHARS).join("")}\u2026` : flat;
20073
20218
  const { comments, asks } = block.references;
20074
20219
  lines.push(`${indent}${block.id} ${block.type} (${block.token ?? "no token"}; ${comments} comment${comments === 1 ? "" : "s"}, ${asks} ask${asks === 1 ? "" : "s"}): ${opening}`);
20220
+ for (const attribute of block.attributes ?? []) {
20221
+ if (attribute.kind === "block[]" && attribute.value !== "") {
20222
+ lines.push(`${indent} ${attribute.name}: ${attribute.value}`);
20223
+ }
20224
+ }
20075
20225
  if (block.type === "table") {
20076
20226
  if (block.table === undefined) {
20077
20227
  lines.push(`${indent} This Dispatch does not report table rows yet, so no row or column index is listed.`);
@@ -21069,13 +21219,25 @@ Document token: ${listed.token}`,
21069
21219
  const artifactReference = optionalString(args, "artifact") ?? (ownerArguments.ref?.kind === "spec" || ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : undefined);
21070
21220
  const resolved = await resolveDocument(documentOwner(), artifactReference);
21071
21221
  await refuseOpenDecisionBlocks(client, input.tool, resolved);
21222
+ const includeVerification = optionalBoolean(args, "include_verification") === true;
21072
21223
  const result = await client.requestApproval(resolved.artifact.id, {
21073
21224
  actor,
21074
- summary: stringArg(args, "summary")
21225
+ summary: stringArg(args, "summary"),
21226
+ ...includeVerification ? { include_verification: true } : {}
21075
21227
  });
21228
+ const gaps = result.coverage ?? [];
21229
+ const coverageLines = result.coverage_unread ? [
21230
+ `Coverage of ${resolved.artifact.name}: unread. Dispatch could not read what the spec's requirements lack, so no line here says there is no gap; the request is recorded either way. Read the coverage again with dispatch read --issue, and mark each requirement the spec states with a requirement block and write a check that serves it, in the issue's Verification document, before the work starts.`
21231
+ ] : gaps.length === 0 ? [] : [
21232
+ `Coverage of ${resolved.artifact.name}: ${gaps.map((gap) => `${gap}.`).join(" ")} Mark each requirement the spec states with a requirement block and write a check that serves it, in the issue's Verification document, before the work starts.`
21233
+ ];
21076
21234
  if (result.ask === null) {
21077
21235
  return {
21078
- text: `${resolved.artifact.name} (document id ${resolved.artifact.id}) is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. A change outside the decision blocks after approval makes it stale, so request again only for such a version, once the human has agreed to every point in it, with a --summary naming what changed since version ${result.version}; the human's own answer to a decision block carries the approval when that answer is the whole change.`,
21236
+ text: [
21237
+ `${resolved.artifact.name} (document id ${resolved.artifact.id}) is already approved at version ${result.version} by ${result.approval.by?.id ?? "unknown"}; no new request was opened. A change outside the decision blocks after approval makes it stale, so request again only for such a version, once the human has agreed to every point in it, with a --summary naming what changed since version ${result.version}; the human's own answer to a decision block carries the approval when that answer is the whole change.`,
21238
+ ...coverageLines
21239
+ ].join(`
21240
+ `),
21079
21241
  details: {
21080
21242
  ...resolved.owner.kind === "project" ? documentResultDetails(resolved.artifact) : { issue: resolved.issue?.key },
21081
21243
  artifact: resolved.artifact.id,
@@ -21086,10 +21248,72 @@ Document token: ${listed.token}`,
21086
21248
  const details = await followedAskDetails(client, result.ask, resolved.artifact);
21087
21249
  const outcome = result.recorded ? `Approval requested for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}).` : `The approval request for ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${result.version} (ask ${result.ask.id}) already waits on the human, so this call changed nothing: nothing since it last reached the human (a newer version, a human's reply in its thread, or your progress note) left it waiting on you.`;
21088
21250
  return {
21089
- text: `${outcome} The human's Inbox asks: ${JSON.stringify(result.ask.question)}. The answer arrives as artifact.approved or artifact.changes_requested. An edit before the answer moves this request to the new version and leaves it waiting on you, and a change outside the decision blocks after approval makes the approval stale: either way, request again for the new version once the human has agreed to every point in it, which hands this request back or opens a new one, with a --summary naming what changed since the earlier approval. The human's own answer to a decision block carries the approval when that answer is the whole change since the approved version, and answers an open request Approve in their name: request nothing then.`,
21251
+ text: [
21252
+ `${outcome} The human's Inbox asks: ${JSON.stringify(result.ask.question)}. The answer arrives as artifact.approved or artifact.changes_requested. An edit before the answer moves this request to the new version and leaves it waiting on you, and a change outside the decision blocks after approval makes the approval stale: either way, request again for the new version once the human has agreed to every point in it, which hands this request back or opens a new one, with a --summary naming what changed since the earlier approval. The human's own answer to a decision block carries the approval when that answer is the whole change since the approved version, and answers an open request Approve in their name: request nothing then.`,
21253
+ ...coverageLines
21254
+ ].join(`
21255
+ `),
21090
21256
  details: { ...details, artifact: resolved.artifact.id, version: result.version }
21091
21257
  };
21092
21258
  }
21259
+ case "dispatch_plan_approve": {
21260
+ const planOwner = documentOwner();
21261
+ const named = optionalString(args, "artifact");
21262
+ const byRole = named === undefined && planOwner.kind === "issue" ? (await client.getIssue(planOwner.issue)).plan_artifact_id ?? "" : "";
21263
+ const resolved = await resolveDocument(planOwner, named ?? (byRole || "plan.md"));
21264
+ const version = numberArg(args, "version");
21265
+ const review = await client.planApprove(resolved.artifact.id, { actor, version });
21266
+ return {
21267
+ text: `The plan review approved ${resolved.artifact.name} (document id ${resolved.artifact.id}) at version ${review.version}; no human is asked to approve a plan. A later plan version makes this approval stale: run the review again and record it the same way.`,
21268
+ details: {
21269
+ issue: resolved.issue?.key,
21270
+ artifact: resolved.artifact.id,
21271
+ version: review.version
21272
+ }
21273
+ };
21274
+ }
21275
+ case "dispatch_result": {
21276
+ const issue = stringArg(args, "issue");
21277
+ const optional = {
21278
+ ...defined("surface", optionalString(args, "surface")),
21279
+ ...defined("run", optionalString(args, "run")),
21280
+ ...defined("observed", optionalString(args, "observed")),
21281
+ ...defined("negative_control", optionalString(args, "negative_control")),
21282
+ ...defined("failed", optionalNumber(args, "failed")),
21283
+ ...defined("skipped", optionalNumber(args, "skipped")),
21284
+ ...defined("excluded", optionalNumber(args, "excluded")),
21285
+ ...defined("screenshots", optionalStringArray(args, "screenshots"))
21286
+ };
21287
+ const recorded = await client.recordResult(issue, {
21288
+ actor,
21289
+ check: stringArg(args, "check"),
21290
+ role: stringArg(args, "role"),
21291
+ verdict: stringArg(args, "verdict"),
21292
+ commit: stringArg(args, "commit"),
21293
+ ...optional
21294
+ });
21295
+ return {
21296
+ text: `Recorded ${recorded.result.verdict} for check ${recorded.result.check_block_id} of ${recorded.result.check_issue_key} at ${recorded.result.commit_sha.slice(0, 12)}, as ${recorded.result.role}.
21297
+
21298
+ Pull request body line:
21299
+ ${recorded.line}`,
21300
+ details: {
21301
+ issue,
21302
+ result: recorded.result.id,
21303
+ check: recorded.result.check_block_id,
21304
+ verdict: recorded.result.verdict,
21305
+ line: recorded.line
21306
+ }
21307
+ };
21308
+ }
21309
+ case "dispatch_results": {
21310
+ const issue = stringArg(args, "issue");
21311
+ const results = await client.issueResults(issue);
21312
+ return {
21313
+ text: formatCheckResults(results),
21314
+ details: { issue, checks: results.checks.length }
21315
+ };
21316
+ }
21093
21317
  case "dispatch_artifact": {
21094
21318
  const summary = optionalString(args, "summary");
21095
21319
  const name = stringArg(args, "name");
@@ -21291,7 +21515,7 @@ ${handoff.body}`,
21291
21515
  const askOfPart = ref.item?.kind === "ask" ? client.getAsk(ref.item.id).catch(() => {
21292
21516
  return;
21293
21517
  }) : undefined;
21294
- const [incoming, outgoing, partOf] = await Promise.all([
21518
+ const [incoming, outgoing, partOf, typed] = await Promise.all([
21295
21519
  client.getReferences({ to: blockRef }).catch((error) => {
21296
21520
  if (ref.pin === undefined && dispatchAnswered(error, 404)) {
21297
21521
  throw new Error(`No block ${ref.block} in ${holder}.`);
@@ -21299,13 +21523,14 @@ ${handoff.body}`,
21299
21523
  throw error;
21300
21524
  }),
21301
21525
  graphReferences(client, { from: blockRef }),
21302
- askOfPart
21526
+ askOfPart,
21527
+ typedBlockOf(client, ref)
21303
21528
  ]);
21304
21529
  const blockID = incoming.node.block_id ?? ref.block ?? "";
21305
21530
  const noun = ref.item?.kind !== "ask" ? undefined : partOf === undefined ? "Part" : askPartNoun(partOf.ask, incoming.node, blockID);
21306
21531
  return {
21307
21532
  text: [
21308
- ...blockLines(incoming.node, ref, noun),
21533
+ ...blockLines(incoming.node, ref, typed, noun),
21309
21534
  ...graphSectionLines(incoming, outgoing)
21310
21535
  ].join(`
21311
21536
  `),
@@ -21377,17 +21602,18 @@ ${handoff.body}`,
21377
21602
  const readPromise = client.read(issueKey, readEvents);
21378
21603
  const referencesPromise = issueReferencesOrUnavailable(client, issueKey);
21379
21604
  const read = await readPromise;
21380
- const [references, graph, titles, pictures] = await Promise.all([
21605
+ const [references, graph, titles, pictures, coverage] = await Promise.all([
21381
21606
  referencesPromise,
21382
21607
  graphSections(client, dispatchIssueRef(read.issue.key)),
21383
21608
  liveSessionTitles(client, holdsSession(read.issue.claim) || routeHeldBySession(read.issue)),
21384
21609
  picturesOf([
21385
21610
  ...read.issue.open_asks.map((ask) => ({ text: ask.question, at: ask.created_at })),
21386
21611
  ...read.events.flatMap(eventTexts)
21387
- ])
21612
+ ]),
21613
+ issueCoverageOrReason(client, read.issue.key)
21388
21614
  ]);
21389
21615
  return {
21390
- text: issueSummary(read.issue, read.events, references, [...pictures.lines, ...graph], linkBase, titles),
21616
+ text: issueSummary(read.issue, read.events, references, [...pictures.lines, ...graph], linkBase, coverage, titles),
21391
21617
  details: { issue: read.issue.key },
21392
21618
  ...showImages(pictures),
21393
21619
  ...repositoryFieldsWarnings(read.issue)
@@ -22338,6 +22564,10 @@ var EnvelopeResponseSchema = EnvelopeSchema.extend({
22338
22564
  holder: string2().optional(),
22339
22565
  duplicate: boolean2().optional()
22340
22566
  });
22567
+ var PublishResponseSchema = EnvelopeResponseSchema.extend({
22568
+ kept: boolean2().optional(),
22569
+ kept_reason: _enum2(["unclaimed", "holder_lapsed"]).optional()
22570
+ });
22341
22571
  var ReplayWireSchema = object({
22342
22572
  stream: object({
22343
22573
  id: string2().min(1).optional(),
@@ -22552,18 +22782,21 @@ function createEnvoyClient(config) {
22552
22782
  },
22553
22783
  publish: async (input) => {
22554
22784
  const idempotencyKey = input.idempotencyKey ?? crypto.randomUUID();
22555
- const response = EnvelopeResponseSchema.parse(JSON.parse(await post("/v1/messages/publish", {
22785
+ const response = PublishResponseSchema.parse(JSON.parse(await post("/v1/messages/publish", {
22556
22786
  source: input.source ?? "agent",
22557
22787
  ...sourceSession(input.sourceSessionID),
22558
22788
  topic: input.topic,
22559
22789
  message: input.message,
22560
22790
  ...input.payload === undefined ? {} : { payload: input.payload },
22561
22791
  idempotency_key: idempotencyKey,
22562
- ...messageMetadata(input)
22792
+ ...messageMetadata(input),
22793
+ ...input.keep === undefined ? {} : { keep: input.keep }
22563
22794
  })));
22564
22795
  return {
22565
22796
  envelope: response,
22566
- ...response.holder === undefined ? {} : { holder: response.holder }
22797
+ ...response.holder === undefined ? {} : { holder: response.holder },
22798
+ ...response.kept === undefined ? {} : { kept: response.kept },
22799
+ ...response.kept_reason === undefined ? {} : { keptReason: response.kept_reason }
22567
22800
  };
22568
22801
  },
22569
22802
  unregisterSession: async (input) => {