@sjawhar/pi-envoy 16.0.0 → 16.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/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(),
@@ -17141,6 +17216,15 @@ class DispatchClient {
17141
17216
  const answer = await this.#jsonAnswer("POST", ["api", "v1", "artifacts", artifactID, "approval-requests"], input);
17142
17217
  return { ...answer.payload, recorded: answer.status === 201 };
17143
17218
  }
17219
+ async planApprove(artifactID, input) {
17220
+ return this.#json("POST", ["api", "v1", "artifacts", artifactID, "plan-reviews"], input);
17221
+ }
17222
+ async recordResult(issue, input) {
17223
+ return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"], input);
17224
+ }
17225
+ async issueResults(issue) {
17226
+ return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"]);
17227
+ }
17144
17228
  async editAsk(id, input) {
17145
17229
  return this.#json("PATCH", ["api", "v1", "asks", id], input);
17146
17230
  }
@@ -17224,6 +17308,15 @@ class DispatchClient {
17224
17308
  async artifactBlocks(id) {
17225
17309
  return this.#json("GET", ["api", "v1", "artifacts", id, "blocks"]);
17226
17310
  }
17311
+ async issueArtifactBlocks(issue, slug) {
17312
+ return this.#json("GET", ["api", "v1", "issues", issue, "artifacts", slug, "blocks"]);
17313
+ }
17314
+ async projectArtifactBlocks(project, slug) {
17315
+ return this.#json("GET", ["api", "v1", "projects", project, "artifacts", slug, "blocks"]);
17316
+ }
17317
+ async issueCoverage(key) {
17318
+ return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(key), "coverage"]);
17319
+ }
17227
17320
  async commentBlocks(id) {
17228
17321
  return this.#json("GET", ["api", "v1", "comments", id, "blocks"]);
17229
17322
  }
@@ -18599,6 +18692,12 @@ function stringArg(args, name) {
18599
18692
  throw new Error(`${name} is required`);
18600
18693
  return value;
18601
18694
  }
18695
+ function numberArg(args, name) {
18696
+ const value = args[name];
18697
+ if (typeof value !== "number")
18698
+ throw new Error(`${name} is required`);
18699
+ return value;
18700
+ }
18602
18701
  function optionalString(args, name) {
18603
18702
  const value = args[name];
18604
18703
  return typeof value === "string" ? value : undefined;
@@ -18611,6 +18710,13 @@ function optionalNumber(args, name) {
18611
18710
  const value = args[name];
18612
18711
  return typeof value === "number" ? value : undefined;
18613
18712
  }
18713
+ function defined(name, value) {
18714
+ return value === undefined ? {} : { [name]: value };
18715
+ }
18716
+ function optionalStringArray(args, name) {
18717
+ const value = args[name];
18718
+ return Array.isArray(value) ? value : undefined;
18719
+ }
18614
18720
  function optionalPriority(args, name) {
18615
18721
  const value = args[name];
18616
18722
  if (value === null)
@@ -19534,6 +19640,24 @@ function progressText(progress, sep) {
19534
19640
  }
19535
19641
  return parts.join(sep);
19536
19642
  }
19643
+ function formatCheckResults(results) {
19644
+ if (results.verification_artifact_id === "") {
19645
+ 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.`;
19646
+ }
19647
+ if (results.checks.length === 0) {
19648
+ return `${results.issue}'s Verification document holds no check blocks.`;
19649
+ }
19650
+ const lines = results.checks.map((check) => {
19651
+ const head = `- ${check.block_id} (${check.when}): `;
19652
+ const latest = check.results[0];
19653
+ if (latest === undefined) {
19654
+ return `${head}no result yet. ${check.text}`;
19655
+ }
19656
+ return `${head}${latest.verdict} at ${latest.commit_sha.slice(0, 12)} by ${latest.role}, ${latest.currency ?? "unknown"}. ${check.text}`;
19657
+ });
19658
+ return [`Checks of ${results.issue}:`, ...lines].join(`
19659
+ `);
19660
+ }
19537
19661
  function repositoryLine(issue) {
19538
19662
  if (issue.resolved_repo === undefined) {
19539
19663
  return "Repository: unknown (this Dispatch server predates repository fields; upgrade it)";
@@ -19559,7 +19683,7 @@ function refuseUnsavedRepository(verb, issue, repo) {
19559
19683
  const lost = repo === "" ? "the repository was not cleared" : `${repo} was not saved`;
19560
19684
  throw new Error(`Dispatch ${verb} ${issue.key} without its repository: this Dispatch server predates repository fields, so ${lost}; upgrade the server`);
19561
19685
  }
19562
- function issueSummary(issue, events, references, graph, linkBase, titles) {
19686
+ function issueSummary(issue, events, references, graph, linkBase, coverage, titles) {
19563
19687
  const asks = issue.open_asks;
19564
19688
  const spec = issue.artifacts?.find((artifact) => artifact.primary);
19565
19689
  const specApproval = spec === undefined ? undefined : approvalLine(spec);
@@ -19588,6 +19712,7 @@ function issueSummary(issue, events, references, graph, linkBase, titles) {
19588
19712
  repositoryLine(issue),
19589
19713
  `Progress: ${progressText(issue.progress, ", ") || "none"}`,
19590
19714
  ...specApproval === undefined ? [] : [`Spec ${specApproval.replace(/^Approval/, "approval")}`],
19715
+ ...typeof coverage === "string" ? [`Coverage: ${coverage}`] : coverage.gaps.map((gap) => `Coverage: ${gap}`),
19591
19716
  "External links:",
19592
19717
  ...issue.external_links.length === 0 ? ["- none"] : issue.external_links.map((link) => `- ${link.url}${link.kind === undefined ? "" : ` (${link.kind})`}`),
19593
19718
  "Documents:",
@@ -19639,6 +19764,13 @@ async function issueReferencesOrUnavailable(client, key) {
19639
19764
  return unavailableReason(error);
19640
19765
  }
19641
19766
  }
19767
+ async function issueCoverageOrReason(client, key) {
19768
+ try {
19769
+ return await client.issueCoverage(key);
19770
+ } catch (error) {
19771
+ return unavailableReason(error);
19772
+ }
19773
+ }
19642
19774
  async function graphSections(client, ref) {
19643
19775
  const [incoming, outgoing] = await Promise.all([
19644
19776
  graphReferences(client, { to: ref }),
@@ -19667,12 +19799,14 @@ function nodeLine(node) {
19667
19799
  `Node: ${node.kind} ${node.ref ?? node.id} \xB7 made by ${made} \xB7 changed by ${changed}${partOf}`
19668
19800
  ];
19669
19801
  }
19670
- function blockLines(node, ref, noun = "Block") {
19802
+ function blockLines(node, ref, typed, noun = "Block") {
19671
19803
  const unit = ref.item === undefined ? "version" : "revision";
19672
19804
  const blockID = node.block_id ?? ref.block;
19673
19805
  const head = ref.item === undefined ? [
19674
19806
  `Block: ${blockID}`,
19807
+ ...typed === undefined ? [] : [`Type: ${typed.type}`],
19675
19808
  `Document: ${node.document ?? ref.document}`,
19809
+ ...(typed?.attributes ?? []).map((attribute) => `${attribute.name}: ${attribute.value === "" ? "(empty)" : attribute.value}`),
19676
19810
  ...node.changed_version === undefined ? [] : [`Changed in version: ${node.changed_version}`],
19677
19811
  ...node.text === undefined ? [] : ["Text:", node.text]
19678
19812
  ] : [
@@ -19691,6 +19825,16 @@ function blockLines(node, ref, noun = "Block") {
19691
19825
  pin.text
19692
19826
  ];
19693
19827
  }
19828
+ async function typedBlockOf(client, ref) {
19829
+ if (ref.item !== undefined || ref.block === undefined)
19830
+ return;
19831
+ try {
19832
+ const blocks = ref.owner.kind === "project" ? await client.projectArtifactBlocks(ref.owner.project, ref.id) : await client.issueArtifactBlocks(ref.owner.issue, ref.id);
19833
+ return blocks.find((block) => block.id === ref.block);
19834
+ } catch {
19835
+ return;
19836
+ }
19837
+ }
19694
19838
  function askPartNoun(ask, node, blockID) {
19695
19839
  if (ask.answer?.id === blockID)
19696
19840
  return "Answer";
@@ -20060,7 +20204,7 @@ async function listDocumentBlocks(client, artifact) {
20060
20204
  const { bytes, blocks } = live;
20061
20205
  const decoder = new TextDecoder;
20062
20206
  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.`
20207
+ `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
20208
  ];
20065
20209
  const holders = [];
20066
20210
  for (const block of blocks) {
@@ -20072,6 +20216,11 @@ async function listDocumentBlocks(client, artifact) {
20072
20216
  const opening = points.length > BLOCK_OPENING_CHARS ? `${points.slice(0, BLOCK_OPENING_CHARS).join("")}\u2026` : flat;
20073
20217
  const { comments, asks } = block.references;
20074
20218
  lines.push(`${indent}${block.id} ${block.type} (${block.token ?? "no token"}; ${comments} comment${comments === 1 ? "" : "s"}, ${asks} ask${asks === 1 ? "" : "s"}): ${opening}`);
20219
+ for (const attribute of block.attributes ?? []) {
20220
+ if (attribute.kind === "block[]" && attribute.value !== "") {
20221
+ lines.push(`${indent} ${attribute.name}: ${attribute.value}`);
20222
+ }
20223
+ }
20075
20224
  if (block.type === "table") {
20076
20225
  if (block.table === undefined) {
20077
20226
  lines.push(`${indent} This Dispatch does not report table rows yet, so no row or column index is listed.`);
@@ -21069,13 +21218,25 @@ Document token: ${listed.token}`,
21069
21218
  const artifactReference = optionalString(args, "artifact") ?? (ownerArguments.ref?.kind === "spec" || ownerArguments.ref?.kind === "artifact" ? ownerArguments.ref.id : undefined);
21070
21219
  const resolved = await resolveDocument(documentOwner(), artifactReference);
21071
21220
  await refuseOpenDecisionBlocks(client, input.tool, resolved);
21221
+ const includeVerification = optionalBoolean(args, "include_verification") === true;
21072
21222
  const result = await client.requestApproval(resolved.artifact.id, {
21073
21223
  actor,
21074
- summary: stringArg(args, "summary")
21224
+ summary: stringArg(args, "summary"),
21225
+ ...includeVerification ? { include_verification: true } : {}
21075
21226
  });
21227
+ const gaps = result.coverage ?? [];
21228
+ const coverageLines = result.coverage_unread ? [
21229
+ `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.`
21230
+ ] : gaps.length === 0 ? [] : [
21231
+ `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.`
21232
+ ];
21076
21233
  if (result.ask === null) {
21077
21234
  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.`,
21235
+ text: [
21236
+ `${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.`,
21237
+ ...coverageLines
21238
+ ].join(`
21239
+ `),
21079
21240
  details: {
21080
21241
  ...resolved.owner.kind === "project" ? documentResultDetails(resolved.artifact) : { issue: resolved.issue?.key },
21081
21242
  artifact: resolved.artifact.id,
@@ -21086,10 +21247,72 @@ Document token: ${listed.token}`,
21086
21247
  const details = await followedAskDetails(client, result.ask, resolved.artifact);
21087
21248
  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
21249
  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.`,
21250
+ text: [
21251
+ `${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.`,
21252
+ ...coverageLines
21253
+ ].join(`
21254
+ `),
21090
21255
  details: { ...details, artifact: resolved.artifact.id, version: result.version }
21091
21256
  };
21092
21257
  }
21258
+ case "dispatch_plan_approve": {
21259
+ const planOwner = documentOwner();
21260
+ const named = optionalString(args, "artifact");
21261
+ const byRole = named === undefined && planOwner.kind === "issue" ? (await client.getIssue(planOwner.issue)).plan_artifact_id ?? "" : "";
21262
+ const resolved = await resolveDocument(planOwner, named ?? (byRole || "plan.md"));
21263
+ const version = numberArg(args, "version");
21264
+ const review = await client.planApprove(resolved.artifact.id, { actor, version });
21265
+ return {
21266
+ 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.`,
21267
+ details: {
21268
+ issue: resolved.issue?.key,
21269
+ artifact: resolved.artifact.id,
21270
+ version: review.version
21271
+ }
21272
+ };
21273
+ }
21274
+ case "dispatch_result": {
21275
+ const issue = stringArg(args, "issue");
21276
+ const optional = {
21277
+ ...defined("surface", optionalString(args, "surface")),
21278
+ ...defined("run", optionalString(args, "run")),
21279
+ ...defined("observed", optionalString(args, "observed")),
21280
+ ...defined("negative_control", optionalString(args, "negative_control")),
21281
+ ...defined("failed", optionalNumber(args, "failed")),
21282
+ ...defined("skipped", optionalNumber(args, "skipped")),
21283
+ ...defined("excluded", optionalNumber(args, "excluded")),
21284
+ ...defined("screenshots", optionalStringArray(args, "screenshots"))
21285
+ };
21286
+ const recorded = await client.recordResult(issue, {
21287
+ actor,
21288
+ check: stringArg(args, "check"),
21289
+ role: stringArg(args, "role"),
21290
+ verdict: stringArg(args, "verdict"),
21291
+ commit: stringArg(args, "commit"),
21292
+ ...optional
21293
+ });
21294
+ return {
21295
+ 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}.
21296
+
21297
+ Pull request body line:
21298
+ ${recorded.line}`,
21299
+ details: {
21300
+ issue,
21301
+ result: recorded.result.id,
21302
+ check: recorded.result.check_block_id,
21303
+ verdict: recorded.result.verdict,
21304
+ line: recorded.line
21305
+ }
21306
+ };
21307
+ }
21308
+ case "dispatch_results": {
21309
+ const issue = stringArg(args, "issue");
21310
+ const results = await client.issueResults(issue);
21311
+ return {
21312
+ text: formatCheckResults(results),
21313
+ details: { issue, checks: results.checks.length }
21314
+ };
21315
+ }
21093
21316
  case "dispatch_artifact": {
21094
21317
  const summary = optionalString(args, "summary");
21095
21318
  const name = stringArg(args, "name");
@@ -21291,7 +21514,7 @@ ${handoff.body}`,
21291
21514
  const askOfPart = ref.item?.kind === "ask" ? client.getAsk(ref.item.id).catch(() => {
21292
21515
  return;
21293
21516
  }) : undefined;
21294
- const [incoming, outgoing, partOf] = await Promise.all([
21517
+ const [incoming, outgoing, partOf, typed] = await Promise.all([
21295
21518
  client.getReferences({ to: blockRef }).catch((error) => {
21296
21519
  if (ref.pin === undefined && dispatchAnswered(error, 404)) {
21297
21520
  throw new Error(`No block ${ref.block} in ${holder}.`);
@@ -21299,13 +21522,14 @@ ${handoff.body}`,
21299
21522
  throw error;
21300
21523
  }),
21301
21524
  graphReferences(client, { from: blockRef }),
21302
- askOfPart
21525
+ askOfPart,
21526
+ typedBlockOf(client, ref)
21303
21527
  ]);
21304
21528
  const blockID = incoming.node.block_id ?? ref.block ?? "";
21305
21529
  const noun = ref.item?.kind !== "ask" ? undefined : partOf === undefined ? "Part" : askPartNoun(partOf.ask, incoming.node, blockID);
21306
21530
  return {
21307
21531
  text: [
21308
- ...blockLines(incoming.node, ref, noun),
21532
+ ...blockLines(incoming.node, ref, typed, noun),
21309
21533
  ...graphSectionLines(incoming, outgoing)
21310
21534
  ].join(`
21311
21535
  `),
@@ -21377,17 +21601,18 @@ ${handoff.body}`,
21377
21601
  const readPromise = client.read(issueKey, readEvents);
21378
21602
  const referencesPromise = issueReferencesOrUnavailable(client, issueKey);
21379
21603
  const read = await readPromise;
21380
- const [references, graph, titles, pictures] = await Promise.all([
21604
+ const [references, graph, titles, pictures, coverage] = await Promise.all([
21381
21605
  referencesPromise,
21382
21606
  graphSections(client, dispatchIssueRef(read.issue.key)),
21383
21607
  liveSessionTitles(client, holdsSession(read.issue.claim) || routeHeldBySession(read.issue)),
21384
21608
  picturesOf([
21385
21609
  ...read.issue.open_asks.map((ask) => ({ text: ask.question, at: ask.created_at })),
21386
21610
  ...read.events.flatMap(eventTexts)
21387
- ])
21611
+ ]),
21612
+ issueCoverageOrReason(client, read.issue.key)
21388
21613
  ]);
21389
21614
  return {
21390
- text: issueSummary(read.issue, read.events, references, [...pictures.lines, ...graph], linkBase, titles),
21615
+ text: issueSummary(read.issue, read.events, references, [...pictures.lines, ...graph], linkBase, coverage, titles),
21391
21616
  details: { issue: read.issue.key },
21392
21617
  ...showImages(pictures),
21393
21618
  ...repositoryFieldsWarnings(read.issue)
package/dist/envoy.js CHANGED
@@ -30033,7 +30033,12 @@ function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false)
30033
30033
  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."
30034
30034
  };
30035
30035
  }
30036
- 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.";
30036
+ var ARTIFACT_SOURCE_RULE = "Exactly one of path or content is required.";
30037
+ var ARTIFACT_OWNER_AND_SOURCE_RULE = `${ARTIFACT_SOURCE_RULE} Exactly one of issue and project is required; with project, artifact names the document.`;
30038
+ function brokenParts(parts) {
30039
+ const broken = parts.filter(([kept]) => !kept).map(([, message]) => message);
30040
+ return broken.length === 0 ? undefined : broken.join(" ");
30041
+ }
30037
30042
  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)";
30038
30043
  var PATH_KEEPS_BYTES = "path (--path <file>), which stores a file whose path does not end in .md or .markdown as its bytes, unchanged";
30039
30044
  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}.`;
@@ -30042,9 +30047,15 @@ var MARKDOWN_EXTENSION = /^(md|markdown)$/i;
30042
30047
  var artifactOwner = documentOwnerValidation(false);
30043
30048
  function artifactProblem(value) {
30044
30049
  const input = value;
30045
- if (!artifactOwner.check(value) || typeof input.path === "string" === (typeof input.content === "string")) {
30046
- return ARTIFACT_OWNER_AND_SOURCE_RULE;
30047
- }
30050
+ const ownerOrSourceProblem = brokenParts([
30051
+ [artifactOwner.check(value), artifactOwner.message],
30052
+ [
30053
+ typeof input.path === "string" !== (typeof input.content === "string"),
30054
+ ARTIFACT_SOURCE_RULE
30055
+ ]
30056
+ ]);
30057
+ if (ownerOrSourceProblem !== undefined)
30058
+ return ownerOrSourceProblem;
30048
30059
  if (typeof input.content !== "string" || typeof input.name !== "string")
30049
30060
  return;
30050
30061
  const extension = NAME_EXTENSION.exec(input.name.trim())?.[1];
@@ -30053,27 +30064,40 @@ function artifactProblem(value) {
30053
30064
  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.`;
30054
30065
  }
30055
30066
  var documentEditOwner = documentOwnerValidation(true);
30067
+ var PRECONDITION_RULE = "A precondition selects exactly one of document or blocks.";
30068
+ function preconditionKept(value) {
30069
+ const input = value;
30070
+ if (input.precondition === undefined)
30071
+ return true;
30072
+ if (typeof input.precondition !== "object" || input.precondition === null)
30073
+ return false;
30074
+ const precondition = input.precondition;
30075
+ return typeof precondition.document === "string" !== Array.isArray(precondition.blocks);
30076
+ }
30077
+ function documentEditProblem(value) {
30078
+ return brokenParts([
30079
+ [documentEditOwner.check(value), documentEditOwner.message],
30080
+ [preconditionKept(value), PRECONDITION_RULE]
30081
+ ]);
30082
+ }
30056
30083
  var documentEditValidation = {
30057
- check: (value) => {
30058
- if (!documentEditOwner.check(value))
30059
- return false;
30060
- const input = value;
30061
- if (input.precondition === undefined)
30062
- return true;
30063
- if (typeof input.precondition !== "object" || input.precondition === null)
30064
- return false;
30065
- const precondition = input.precondition;
30066
- return typeof precondition.document === "string" !== Array.isArray(precondition.blocks);
30067
- },
30068
- message: `${documentEditOwner.message} A precondition selects exactly one of document or blocks.`
30084
+ check: (value) => documentEditProblem(value) === undefined,
30085
+ message: `${documentEditOwner.message} ${PRECONDITION_RULE}`,
30086
+ refusal: (value) => documentEditProblem(value) ?? `${documentEditOwner.message} ${PRECONDITION_RULE}`
30069
30087
  };
30070
30088
  var commentOwner = documentOwnerValidation(true);
30089
+ 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.";
30090
+ function commentProblem(value) {
30091
+ const input = value;
30092
+ return brokenParts([
30093
+ [commentOwner.check(value), commentOwner.message],
30094
+ [input.turn === undefined || typeof input.reply_to_ask === "string", COMMENT_TURN_RULE]
30095
+ ]);
30096
+ }
30071
30097
  var commentValidation = {
30072
- check: (value) => {
30073
- const input = value;
30074
- return commentOwner.check(value) && (input.turn === undefined || typeof input.reply_to_ask === "string");
30075
- },
30076
- message: `${commentOwner.message} turn requires reply_to_ask.`
30098
+ check: (value) => commentProblem(value) === undefined,
30099
+ message: `${commentOwner.message} ${COMMENT_TURN_RULE}`,
30100
+ refusal: (value) => commentProblem(value) ?? `${commentOwner.message} ${COMMENT_TURN_RULE}`
30077
30101
  };
30078
30102
  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.";
30079
30103
  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";
@@ -30100,14 +30124,20 @@ var messageValidation = {
30100
30124
  message: "issue is required unless in_reply_to names a message delivered to this session, which is the one message with no issue."
30101
30125
  };
30102
30126
  var readOwner = documentOwnerValidation(false);
30127
+ var READ_OWNER_RULE = "Exactly one of issue and project is required; project alone lists its documents, and with artifact names one.";
30128
+ var READ_MESSAGE_RULE = "message stands alone: it names the conversation, so name no issue, project, artifact, or ref with it.";
30129
+ function readProblem(value) {
30130
+ const input = value;
30131
+ if (typeof input.message !== "string") {
30132
+ return readOwner.check(value) ? undefined : READ_OWNER_RULE;
30133
+ }
30134
+ const alone = input.issue === undefined && input.project === undefined && input.artifact === undefined && input.ref === undefined;
30135
+ return alone ? undefined : READ_MESSAGE_RULE;
30136
+ }
30103
30137
  var readValidation = {
30104
- check: (value) => {
30105
- const input = value;
30106
- if (typeof input.message !== "string")
30107
- return readOwner.check(value);
30108
- return input.issue === undefined && input.project === undefined && input.artifact === undefined && input.ref === undefined;
30109
- },
30110
- 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."
30138
+ check: (value) => readProblem(value) === undefined,
30139
+ message: `${READ_OWNER_RULE} ${READ_MESSAGE_RULE}`,
30140
+ refusal: (value) => readProblem(value) ?? `${READ_OWNER_RULE} ${READ_MESSAGE_RULE}`
30111
30141
  };
30112
30142
  var ISSUE_COMPONENTS_MODES = ["inherit", "explicit", "none"];
30113
30143
  function componentsArgument(z) {
@@ -30445,13 +30475,13 @@ var dispatchToolSpecs = [
30445
30475
  {
30446
30476
  name: "dispatch_doc_read",
30447
30477
  example: { issue: "DSP-1" },
30448
- 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,
30478
+ 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,
30449
30479
  arguments: (z) => ({
30450
30480
  issue: z.string().describe(ISSUE_REFERENCE).optional(),
30451
30481
  project: z.string().describe("Project key owning the document.").optional(),
30452
30482
  artifact: z.string().describe("Optional project document artifact id, slug, or filename; primary document by default for an issue.").optional(),
30453
30483
  version: z.number({ int: true, min: 1 }).describe("Optional version number.").optional(),
30454
- 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(),
30484
+ 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(),
30455
30485
  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()
30456
30486
  }),
30457
30487
  validation: documentOwnerValidation(true)
@@ -30459,15 +30489,60 @@ var dispatchToolSpecs = [
30459
30489
  {
30460
30490
  name: "dispatch_request_approval",
30461
30491
  example: { issue: "DSP-1", summary: "A live sync replaces the nightly export." },
30462
- 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,
30492
+ 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,
30463
30493
  arguments: (z) => ({
30464
30494
  issue: z.string().describe(ISSUE_REFERENCE).optional(),
30465
30495
  project: z.string().describe("Project key owning the document.").optional(),
30466
30496
  artifact: z.string().describe("Project document artifact id, slug, or filename; primary document by default for an issue.").optional(),
30467
- 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}.`)
30497
+ 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}.`),
30498
+ 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()
30468
30499
  }),
30469
30500
  validation: documentOwnerValidation(true)
30470
30501
  },
30502
+ {
30503
+ name: "dispatch_plan_approve",
30504
+ example: { issue: "DSP-1", version: 2 },
30505
+ 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,
30506
+ arguments: (z) => ({
30507
+ issue: z.string().describe(ISSUE_REFERENCE),
30508
+ artifact: z.string().describe("Plan document artifact id, slug, or filename; the issue's plan.md by default.").optional(),
30509
+ version: z.number({ int: true, min: 1 }).describe("The plan version the review read and approved.")
30510
+ })
30511
+ },
30512
+ {
30513
+ name: "dispatch_result",
30514
+ example: {
30515
+ issue: "DSP-1",
30516
+ check: "k1",
30517
+ role: "implementer",
30518
+ verdict: "pass",
30519
+ commit: "1111111111111111111111111111111111111111"
30520
+ },
30521
+ 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,
30522
+ arguments: (z) => ({
30523
+ issue: z.string().describe(ISSUE_REFERENCE),
30524
+ 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."),
30525
+ 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."),
30526
+ verdict: z.enum(["pass", "fail"]).describe("Whether the check passed."),
30527
+ commit: z.string().describe("The 40-character lowercase hex commit the check ran at."),
30528
+ surface: z.string().describe("Where a person reaches the change.").optional(),
30529
+ run: z.string().describe("The command that proved it.").optional(),
30530
+ observed: z.string().describe("What the command printed.").optional(),
30531
+ negative_control: z.string().describe("The deliberately broken input and the refusal seen.").optional(),
30532
+ failed: z.number({ int: true, min: 0 }).describe("Cases the run failed; 0 by default.").optional(),
30533
+ skipped: z.number({ int: true, min: 0 }).describe("Cases the run skipped; 0 by default.").optional(),
30534
+ excluded: z.number({ int: true, min: 0 }).describe("Cases the run excluded; 0 by default.").optional(),
30535
+ screenshots: z.array(z.string()).describe("dispatch:// references to image documents of this issue or of the check's issue.").optional()
30536
+ })
30537
+ },
30538
+ {
30539
+ name: "dispatch_results",
30540
+ example: { issue: "DSP-1" },
30541
+ 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,
30542
+ arguments: (z) => ({
30543
+ issue: z.string().describe(ISSUE_REFERENCE)
30544
+ })
30545
+ },
30471
30546
  {
30472
30547
  name: "dispatch_artifact",
30473
30548
  example: { issue: "DSP-1", name: "design.md", content: `# Design
@@ -30490,7 +30565,7 @@ var dispatchToolSpecs = [
30490
30565
  {
30491
30566
  name: "dispatch_read",
30492
30567
  example: { issue: "DSP-1" },
30493
- 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,
30568
+ 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,
30494
30569
  arguments: (z) => ({
30495
30570
  issue: z.string().describe(ISSUE_REFERENCE).optional(),
30496
30571
  project: z.string().describe("Project key owning the document.").optional(),
@@ -32552,6 +32627,15 @@ class DispatchClient {
32552
32627
  const answer = await this.#jsonAnswer("POST", ["api", "v1", "artifacts", artifactID, "approval-requests"], input);
32553
32628
  return { ...answer.payload, recorded: answer.status === 201 };
32554
32629
  }
32630
+ async planApprove(artifactID, input) {
32631
+ return this.#json("POST", ["api", "v1", "artifacts", artifactID, "plan-reviews"], input);
32632
+ }
32633
+ async recordResult(issue, input) {
32634
+ return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"], input);
32635
+ }
32636
+ async issueResults(issue) {
32637
+ return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "results"]);
32638
+ }
32555
32639
  async editAsk(id, input) {
32556
32640
  return this.#json("PATCH", ["api", "v1", "asks", id], input);
32557
32641
  }
@@ -32635,6 +32719,15 @@ class DispatchClient {
32635
32719
  async artifactBlocks(id) {
32636
32720
  return this.#json("GET", ["api", "v1", "artifacts", id, "blocks"]);
32637
32721
  }
32722
+ async issueArtifactBlocks(issue, slug) {
32723
+ return this.#json("GET", ["api", "v1", "issues", issue, "artifacts", slug, "blocks"]);
32724
+ }
32725
+ async projectArtifactBlocks(project, slug) {
32726
+ return this.#json("GET", ["api", "v1", "projects", project, "artifacts", slug, "blocks"]);
32727
+ }
32728
+ async issueCoverage(key) {
32729
+ return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(key), "coverage"]);
32730
+ }
32638
32731
  async commentBlocks(id) {
32639
32732
  return this.#json("GET", ["api", "v1", "comments", id, "blocks"]);
32640
32733
  }
@@ -38327,7 +38420,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
38327
38420
 
38328
38421
  // package.json
38329
38422
  var name = "@sjawhar/pi-envoy";
38330
- var version2 = "16.0.0";
38423
+ var version2 = "16.1.0";
38331
38424
  var package_default = {
38332
38425
  name,
38333
38426
  version: version2,
@@ -38346,7 +38439,7 @@ var package_default = {
38346
38439
  },
38347
38440
  repository: {
38348
38441
  type: "git",
38349
- url: "https://github.com/sjawhar/legion"
38442
+ url: "https://github.com/cybermonklabs/legion"
38350
38443
  },
38351
38444
  files: [
38352
38445
  "dist",
@@ -44203,6 +44296,7 @@ function envoyExtension(pi) {
44203
44296
  };
44204
44297
  const passDeadlineMs = () => active?.settings.passDeadlineMs ?? MIN_PASS_DEADLINE_MS;
44205
44298
  const subscriptions = new Map;
44299
+ const confirming = new Map;
44206
44300
  const delivered = createDeliveryDedupe();
44207
44301
  let connection;
44208
44302
  let sessionDirectory2 = "";
@@ -44414,6 +44508,7 @@ function envoyExtension(pi) {
44414
44508
  return;
44415
44509
  if (status.type !== import_nats2.Events.Reconnect)
44416
44510
  continue;
44511
+ unanswered.delete(watched);
44417
44512
  renewRelayEpoch();
44418
44513
  triggerReplay();
44419
44514
  }
@@ -44768,8 +44863,8 @@ ${REPLAYED_BTW_NOTE}`, "inert", identity, claim);
44768
44863
  let shuttingDown = false;
44769
44864
  const intentionallyClosed = new Set;
44770
44865
  const awaitingRetry = new Set;
44771
- const SUBSCRIBE_FLUSH_TIMEOUT_MS = 1e4;
44772
- const unconfirmed = new Map;
44866
+ const SUBSCRIBE_FLUSH_TIMEOUT_MS = Number(process.env.ENVOY_SUBSCRIBE_FLUSH_TIMEOUT_MS ?? "") || 1e4;
44867
+ const unanswered = new Set;
44773
44868
  const closeIntentionally = (topic) => {
44774
44869
  const subscription = subscriptions.get(topic);
44775
44870
  if (subscription === undefined) {
@@ -44818,7 +44913,7 @@ ${REPLAYED_BTW_NOTE}`, "inert", identity, claim);
44818
44913
  awaitingRetry.add(topic);
44819
44914
  setTimeout(() => {
44820
44915
  awaitingRetry.delete(topic);
44821
- if (shuttingDown || subscriptions.has(topic) && !unconfirmed.has(topic))
44916
+ if (shuttingDown || subscriptions.has(topic))
44822
44917
  return;
44823
44918
  if (intentionallyClosed.delete(topic))
44824
44919
  return;
@@ -44839,52 +44934,81 @@ ${REPLAYED_BTW_NOTE}`, "inert", identity, claim);
44839
44934
  clearTimeout(timer);
44840
44935
  }
44841
44936
  };
44937
+ const BACKGROUND_CONFIRM_CAP_MS = 600000;
44938
+ const confirmSubscribed = async (connection, what) => {
44939
+ if (unanswered.has(connection))
44940
+ return;
44941
+ try {
44942
+ await within(connection.flush(), SUBSCRIBE_FLUSH_TIMEOUT_MS, `confirming ${what}`);
44943
+ } catch (error) {
44944
+ if (shuttingDown || connection.isClosed())
44945
+ throw error;
44946
+ unanswered.add(connection);
44947
+ confirmInBackground(connection, what);
44948
+ }
44949
+ };
44950
+ const confirmInBackground = async (connection, what) => {
44951
+ const until = Date.now() + BACKGROUND_CONFIRM_CAP_MS;
44952
+ try {
44953
+ while (!shuttingDown && !connection.isClosed() && Date.now() < until) {
44954
+ await new Promise((resolve) => setTimeout(resolve, RESUBSCRIBE_DELAY_MS));
44955
+ if (shuttingDown || connection.isClosed())
44956
+ return;
44957
+ try {
44958
+ await within(connection.flush(), SUBSCRIBE_FLUSH_TIMEOUT_MS, `confirming ${what}`);
44959
+ return;
44960
+ } catch {}
44961
+ }
44962
+ } finally {
44963
+ unanswered.delete(connection);
44964
+ }
44965
+ };
44842
44966
  const subscribe = async (topic, connect = ensureConnection) => {
44843
44967
  const subjects = expandSubscriptionTopics([topic]);
44968
+ const inFlight = subjects.flatMap((subject) => confirming.get(subject) ?? []);
44969
+ if (inFlight.length > 0)
44970
+ await Promise.allSettled(inFlight);
44844
44971
  const fresh = subjects.filter((candidate) => !subscriptions.has(candidate));
44845
- const confirming = subjects.filter((candidate) => !subscriptions.has(candidate) || unconfirmed.has(candidate));
44846
- if (confirming.length === 0)
44972
+ if (fresh.length === 0)
44847
44973
  return false;
44848
44974
  const activeConnection = await connect();
44849
- for (const subject of fresh) {
44850
- const subscription = activeConnection.subscribe(subject);
44851
- intentionallyClosed.delete(subject);
44852
- subscriptions.set(subject, subscription);
44853
- pump(subject, subscription);
44854
- }
44855
- const pending = confirming.flatMap((subject) => {
44856
- const subscription = subscriptions.get(subject);
44857
- return subscription === undefined ? [] : [[subject, subscription]];
44858
- });
44859
- for (const [subject, subscription] of pending)
44860
- unconfirmed.set(subject, subscription);
44861
- await within(activeConnection.flush(), SUBSCRIBE_FLUSH_TIMEOUT_MS, `confirming the subscription to ${topic}`);
44862
- for (const [subject, subscription] of pending) {
44863
- if (unconfirmed.get(subject) === subscription && subscriptions.get(subject) === subscription) {
44864
- unconfirmed.delete(subject);
44975
+ const opened = [];
44976
+ const closeOpened = () => {
44977
+ for (const [subject, subscription] of opened) {
44978
+ if (subscriptions.get(subject) === subscription)
44979
+ closeIntentionally(subject);
44865
44980
  }
44981
+ };
44982
+ try {
44983
+ for (const subject of fresh) {
44984
+ const subscription = activeConnection.subscribe(subject);
44985
+ intentionallyClosed.delete(subject);
44986
+ subscriptions.set(subject, subscription);
44987
+ opened.push([subject, subscription]);
44988
+ pump(subject, subscription);
44989
+ }
44990
+ } catch (error) {
44991
+ closeOpened();
44992
+ throw error;
44866
44993
  }
44867
- return true;
44868
- };
44869
- const confirmPending = async (connect = ensureConnection) => {
44870
- for (const [subject, subscription] of unconfirmed) {
44871
- if (subscriptions.get(subject) !== subscription)
44872
- unconfirmed.delete(subject);
44873
- }
44874
- const pending = [...unconfirmed];
44875
- if (pending.length === 0)
44994
+ const settled = confirmSubscribed(activeConnection, `the subscription to ${topic}`);
44995
+ const confirmation = settled.catch(() => {
44876
44996
  return;
44877
- const activeConnection = await connect();
44878
- await within(activeConnection.flush(), SUBSCRIBE_FLUSH_TIMEOUT_MS, `confirming the subscriptions to ${pending.map(([subject]) => subject).join(", ")}`);
44879
- for (const [subject, subscription] of pending) {
44880
- if (unconfirmed.get(subject) === subscription && subscriptions.get(subject) === subscription) {
44881
- unconfirmed.delete(subject);
44997
+ });
44998
+ for (const [subject] of opened)
44999
+ confirming.set(subject, confirmation);
45000
+ try {
45001
+ await settled;
45002
+ } catch (error) {
45003
+ closeOpened();
45004
+ throw error;
45005
+ } finally {
45006
+ for (const [subject] of opened) {
45007
+ if (confirming.get(subject) === confirmation)
45008
+ confirming.delete(subject);
44882
45009
  }
44883
45010
  }
44884
- };
44885
- const agentSubjectUnconfirmed = (session) => {
44886
- const own = agentSubject(session);
44887
- return subscriptions.has(own) && unconfirmed.has(own);
45011
+ return true;
44888
45012
  };
44889
45013
  const noteInbox = (envelope) => {
44890
45014
  inbox.unshift({
@@ -45027,6 +45151,14 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
45027
45151
  owner.subscription = subscription;
45028
45152
  owner.delivery.beginEpoch();
45029
45153
  pumpRelay(owner, subscription);
45154
+ try {
45155
+ await confirmSubscribed(connected, `the relay subscription for ${owner.sessionID}`);
45156
+ } catch (error) {
45157
+ if (owner.subscription === subscription)
45158
+ owner.subscription = undefined;
45159
+ subscription.unsubscribe();
45160
+ throw error;
45161
+ }
45030
45162
  };
45031
45163
  const openRelay = async (context, id, connect) => {
45032
45164
  if (replay === undefined)
@@ -45094,7 +45226,6 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
45094
45226
  });
45095
45227
  let agentStreamControl;
45096
45228
  let agentStreamControlSession = "";
45097
- let agentStreamControlConfirmed = false;
45098
45229
  let agentStreamCommandsRefreshedOnWatchAt = -Infinity;
45099
45230
  let agentStreamViewerAttached = false;
45100
45231
  const refreshAgentStreamCommands = (session) => {
@@ -45196,30 +45327,28 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
45196
45327
  }, RESUBSCRIBE_DELAY_MS);
45197
45328
  };
45198
45329
  const watchAgentStream = async (session, connect = ensureConnection) => {
45199
- let subscription = agentStreamControlSession === session ? agentStreamControl : undefined;
45200
- let connected;
45201
- if (subscription !== undefined) {
45202
- if (agentStreamControlConfirmed)
45203
- return;
45204
- connected = await connect();
45205
- } else {
45206
- agentStreamControl?.unsubscribe();
45207
- agentStreamControl = undefined;
45208
- if (agentStreamControlSession !== session) {
45209
- agentStream.reset();
45210
- agentStreamViewerAttached = false;
45211
- agentStreamCommandsRefreshedOnWatchAt = -Infinity;
45212
- }
45213
- agentStreamControlSession = session;
45214
- connected = await connect();
45215
- subscription = connected.subscribe(agentStreamControlSubject(session));
45216
- agentStreamControl = subscription;
45217
- agentStreamControlConfirmed = false;
45218
- pumpAgentStreamControl(subscription, session);
45219
- }
45220
- await within(connected.flush(), SUBSCRIBE_FLUSH_TIMEOUT_MS, `confirming the agent stream control subscription for ${session}`);
45221
- if (agentStreamControl === subscription)
45222
- agentStreamControlConfirmed = true;
45330
+ if (agentStreamControlSession === session && agentStreamControl !== undefined)
45331
+ return;
45332
+ agentStreamControl?.unsubscribe();
45333
+ agentStreamControl = undefined;
45334
+ if (agentStreamControlSession !== session) {
45335
+ agentStream.reset();
45336
+ agentStreamViewerAttached = false;
45337
+ agentStreamCommandsRefreshedOnWatchAt = -Infinity;
45338
+ }
45339
+ agentStreamControlSession = session;
45340
+ const connected = await connect();
45341
+ const subscription = connected.subscribe(agentStreamControlSubject(session));
45342
+ agentStreamControl = subscription;
45343
+ pumpAgentStreamControl(subscription, session);
45344
+ try {
45345
+ await confirmSubscribed(connected, `the agent stream control subscription for ${session}`);
45346
+ } catch (error) {
45347
+ if (agentStreamControl === subscription)
45348
+ agentStreamControl = undefined;
45349
+ subscription.unsubscribe();
45350
+ throw error;
45351
+ }
45223
45352
  };
45224
45353
  const recordAgentStreamMessage = (message, streaming) => {
45225
45354
  if (sessionID === "")
@@ -45289,7 +45418,7 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
45289
45418
  const topics = [
45290
45419
  ...new Set([
45291
45420
  own,
45292
- ...[...subscriptions.keys()].filter((subject) => !unconfirmed.has(subject) && !registrationState.isRoleBound(subject) && !reachesPrivateStreamSubject(own, subject))
45421
+ ...[...subscriptions.keys()].filter((subject) => !registrationState.isRoleBound(subject) && !reachesPrivateStreamSubject(own, subject))
45293
45422
  ])
45294
45423
  ];
45295
45424
  if (asking !== undefined)
@@ -45309,9 +45438,6 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
45309
45438
  };
45310
45439
  const sendRegistration = (send) => {
45311
45440
  const registeringFor = sessionID;
45312
- if (agentSubjectUnconfirmed(registeringFor)) {
45313
- return Promise.reject(new Error(`the server has not confirmed this session's subscription to ${agentSubject(registeringFor)}, so the session is not registered until it does`));
45314
- }
45315
45441
  const asking = relay?.sessionID === registeringFor && relay.subscription !== undefined ? relay : undefined;
45316
45442
  const input = registrationInput(asking);
45317
45443
  return send(input).then((result) => {
@@ -45518,18 +45644,10 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
45518
45644
  inboundFailure = error;
45519
45645
  }
45520
45646
  }
45521
- let confirmFailure;
45522
- if (inbound && inboundFailure === undefined) {
45523
- await confirmPending(handle.connect).catch((error) => {
45524
- confirmFailure = error;
45525
- });
45526
- }
45527
45647
  handle.check();
45528
45648
  const registration = await sendRegistration(handle.register).then(() => {
45529
45649
  return;
45530
- }, (error) => ({
45531
- error: agentSubjectUnconfirmed(host) ? inboundFailure ?? confirmFailure ?? error : error
45532
- }));
45650
+ }, (error) => ({ error }));
45533
45651
  handle.check();
45534
45652
  if (registration === undefined) {
45535
45653
  handle.markEstablished(host);
@@ -45811,6 +45929,7 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
45811
45929
  subscriptions.clear();
45812
45930
  intentionallyClosed.clear();
45813
45931
  awaitingRetry.clear();
45932
+ unanswered.clear();
45814
45933
  agentStreamControl = undefined;
45815
45934
  agentStreamControlSession = "";
45816
45935
  const liveSessionID = context.sessionManager.getSessionId();
@@ -46120,8 +46239,14 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
46120
46239
  case EnvoyToolOperation.subscribe: {
46121
46240
  const added = [];
46122
46241
  const already = [];
46242
+ let openFailure;
46123
46243
  for (const topic of topicsFor(parameters)) {
46124
- (await subscribe(topic) ? added : already).push(topic);
46244
+ try {
46245
+ (await subscribe(topic) ? added : already).push(topic);
46246
+ } catch (error) {
46247
+ openFailure = error;
46248
+ break;
46249
+ }
46125
46250
  }
46126
46251
  let warnings;
46127
46252
  let registrationError;
@@ -46134,6 +46259,8 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
46134
46259
  await replayFollowedChanged();
46135
46260
  triggerReplay();
46136
46261
  }
46262
+ if (openFailure !== undefined)
46263
+ throw openFailure;
46137
46264
  const subscribed = `Subscribed: ${added.join(", ") || "(none new)"}`;
46138
46265
  return toolSuccess(warnings === undefined || warnings.length === 0 ? subscribed : `${subscribed}
46139
46266
  Warnings: ${warnings.join("; ")}`, {
@@ -8,16 +8,16 @@ description: "Use before your first dispatch command in a session: a message, co
8
8
  Dispatch is a record for the people who decide, never a log of your work.
9
9
 
10
10
  - Use the `dispatch` command; the HTTP API only for what no command does. `dispatch <command> --help` gives its rules and an example.
11
- - Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'`). Give object and list fields as JSON.
11
+ - Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'`); give object and list fields as JSON.
12
12
  - Exit 1 is a refusal, 2 a usage error. A refusal lists each problem: fix them all, then call once.
13
13
 
14
14
  ## Asks and ask blocks
15
15
 
16
- - A design question a document records is an ask block (a decision block) at the end of its section, at each phase:
16
+ - A design question a document records is an ask block (a decision block) at the end of its section:
17
17
 
18
18
  ```md
19
19
  :::ask{urgency="med"}
20
- Which machines, files or people, the numbers, then "A happens to X, or B to Y?" Recommendation: the option and its reason.
20
+ Which machines, files or people, the numbers, then "A happens to X, or B to Y?" Recommendation and its reason.
21
21
 
22
22
  - Option one: what it costs.
23
23
  - Option two: what it costs.
@@ -27,7 +27,7 @@ Which machines, files or people, the numbers, then "A happens to X, or B to Y?"
27
27
  - In Legion, fix a clear defect in code your tree uses, hand others to the controller, and ask about decisions (`skill://legion-worker/references/findings.md`).
28
28
  - An open ask is the request; never repeat it per message.
29
29
  - Change an open ask's block with `dispatch edit-ask`, or `doc-edit`'s `replace` or `move`. An answered ask is fixed: ask anew.
30
- - Reply on an open ask with `dispatch comment --reply-to-ask`; `--turn agent` for a note needing nothing. An approval request a newer version moved needs `request-approval` again.
30
+ - Reply on an open ask with `dispatch comment --reply-to-ask`; `--turn agent` (a progress note) needs it. An approval request a newer version moved needs `request-approval` again.
31
31
  - When an answer's option and text disagree, the text wins.
32
32
  - An ask block has a block id, for `doc-edit`, and an ask id, for the ask commands. `dispatch read --ref dispatch://KEY/ask/<id>` takes either.
33
33
  - An ask reaches the issue's assignee; if none, name who answers.
@@ -41,9 +41,9 @@ Which machines, files or people, the numbers, then "A happens to X, or B to Y?"
41
41
 
42
42
  ## Issue status is yours to move
43
43
 
44
- Outside Legion, claim your issue (`dispatch claim`) and move it and your children: `in_progress` at implementation, `testing` on a production-like surface, `needs_review` while its PR waits, `done` with `--reason` once driven in production. An issue with the `legion` label, or under one: never write its status with `dispatch` or route it, and claim it only as a role of its tree, even when its claim reads `· not running`. An outside claim can take the tree out of the workflow. A status write is set back or stands.
44
+ Outside Legion, claim your issue (`dispatch claim`) and move it and your children: `in_progress` at implementation, `testing` on a production-like surface, `needs_review` while its PR waits, `done` with `--reason` once driven in production. Never write or route the status of an issue with the `legion` label or under one, and claim one only as a role of its tree, even when its claim reads `· not running`: an outside claim can take the tree out of the workflow. A status write is set back or stands.
45
45
 
46
- A claim, or `dispatch issue-update --route session:<your id>` (`--route ''` on release), brings a person's answers, comments and messages; for agents' activity, `envoy_subscribe notifications.dispatch.issue.<KEY>.>`, which shows no event Dispatch marks quiet.
46
+ A claim, or `dispatch issue-update --route session:<your id>` (`--route ''` on release), brings a person's answers, comments and messages; for agents' activity, `envoy_subscribe notifications.dispatch.issue.<KEY>.>`, which shows no quiet event.
47
47
 
48
48
  ## Close what you opened
49
49
 
@@ -79,7 +79,7 @@ dispatch://PROJECT/artifact/<slug>/ask/<id>
79
79
  dispatch://PROJECT/artifact/<slug>/comment/<id>#b-<block>[@vN]
80
80
  ```
81
81
 
82
- A bare id, filename or path is not a reference, and outside Dispatch neither is `dispatch://`: give the `https://` link `dispatch` printed. Write each id whole, from `dispatch read`'s `Ask id:` or the page URL: the command takes a prefix, a person's link does not.
82
+ A bare id, filename or path is not a reference, and outside Dispatch neither is `dispatch://`: give the `https://` link `dispatch` printed. Write each id whole.
83
83
 
84
84
  ## Setup and the HTTP API
85
85
 
@@ -1,13 +1,13 @@
1
1
  ---
2
2
  name: dispatch-writing-specs
3
- description: "Use in a session with Dispatch before you write or change a spec, and before an ask, comment or message a person reads. It replaces superpowers' brainstorming there."
3
+ description: "Use in a session with Dispatch before you write or change a spec, ask, comment or message a person reads. It replaces superpowers' brainstorming there."
4
4
  ---
5
5
 
6
6
  # Writing specs
7
7
 
8
8
  ## The aim
9
9
 
10
- Reach shared understanding with the person at the least cost of their time. A Legion phase worker writes no spec (`skill://legion-worker`).
10
+ Reach shared understanding with the person at the least cost of their time. A Legion phase worker writes none (`skill://legion-worker`).
11
11
 
12
12
  ## The outline
13
13
 
@@ -18,12 +18,12 @@ Part | Content
18
18
  `Summary` | The change in the reader's own terms, at most 100 words
19
19
  `Problem` | What goes wrong, for whom, with counts
20
20
  `Goals and non-goals` | What is in and out of scope
21
- `Requirements` | `**R1.**` on, each naming its source (`From:`)
21
+ `Requirements` | a `:::requirement` block each, `**R1.**` on, its source (`From:`)
22
+ `Verification` | the issue's `verification.md`, a `:::check` block each: `serves`, `surface`, `run`, `when`, `negative_control`
22
23
  `Design` | How it meets them; a value and its reason for each limit, size and time
23
24
  `Decisions` | One line: `The decisions are in dispatch://KEY/artifact/decisions-md.`
24
- `Acceptance` | `**A1.**` on, each naming the requirements it tests
25
25
 
26
- Another agent can build and check the work from the spec alone. A small change gets a few sentences per part, no matrix; split a large design into child issues.
26
+ `serves` and `needs` name a block of this issue or an ancestor. Another agent can build and check the work from these alone. A small change gets a few sentences per part, no matrix; split a large design into child issues.
27
27
 
28
28
  ## Rules for the text
29
29
 
@@ -33,7 +33,7 @@ For each spec, ask, comment and message:
33
33
  - Write about the current design, never the person or how people reached it, and never quote people or upload their words.
34
34
  - Link each source where the person wrote it, each id whole. With no link, state the design.
35
35
  - In a spec, cite code by file and symbol, never a line number: it goes stale at the next edit.
36
- - A sentence that cites a gate passing (test, review, check, proof) also says what the pass does not show: "Tests pass: a wrong verdict, not a missing one."
36
+ - A sentence that cites a gate passing (test, review, check) also says what the pass does not show: "Tests pass: a wrong verdict, not a missing one."
37
37
  - Name your session only if a reader must reach it.
38
38
  - Keep only text that helps a reader understand, decide, build, check.
39
39
  - Explain each name or term a new reader may not know, and what each issue you name does for them.
@@ -68,9 +68,9 @@ At your next edit, rewrite a spec outside the outline whole in one version, movi
68
68
 
69
69
  ## Approval
70
70
 
71
- - Request approval once: each ask block answered or waived, each claim checked, this version unapproved. Unbuilt acceptance checks never delay it.
72
- - After approval, version only a change to scope, acceptance, cost, risk or a person's decision, all at once; put other fixes in the plan or a comment. An exact undo can restore approval.
71
+ - Request approval of the spec and `verification.md` (`--include-verification`): each ask block answered or waived, each claim checked, this version unapproved. An unrun check never delays it.
72
+ - After approval, version only a change to scope, a check, cost, risk or a person's decision, all at once; put other fixes in the plan or a comment. An exact undo can restore approval.
73
73
 
74
74
  ## The plan
75
75
 
76
- Write the plan with `writing-plans` as the issue's `plan.md`, not a repository file.
76
+ Write the plan with `writing-plans` as the issue's `plan.md`, not a repository file. Each task is a `:::plan_task` block with `serves` and `needs`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "16.0.0",
3
+ "version": "16.1.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {
@@ -16,7 +16,7 @@
16
16
  },
17
17
  "repository": {
18
18
  "type": "git",
19
- "url": "https://github.com/sjawhar/legion"
19
+ "url": "https://github.com/cybermonklabs/legion"
20
20
  },
21
21
  "files": [
22
22
  "dist",