@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 +270 -45
- package/dist/envoy.js +240 -113
- package/dist/skills/dispatch/SKILL.md +7 -7
- package/dist/skills/dispatch-writing-specs/SKILL.md +9 -9
- package/package.json +2 -2
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
|
|
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
|
-
|
|
14976
|
-
|
|
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
|
-
|
|
14989
|
-
|
|
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
|
-
|
|
15004
|
-
|
|
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
|
-
|
|
15036
|
-
|
|
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:
|
|
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:
|
|
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
|
|
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
|
-
|
|
30046
|
-
|
|
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
|
-
|
|
30059
|
-
|
|
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
|
-
|
|
30074
|
-
|
|
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
|
-
|
|
30106
|
-
|
|
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.
|
|
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/
|
|
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
|
|
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)
|
|
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
|
-
|
|
44846
|
-
if (confirming.length === 0)
|
|
44972
|
+
if (fresh.length === 0)
|
|
44847
44973
|
return false;
|
|
44848
44974
|
const activeConnection = await connect();
|
|
44849
|
-
|
|
44850
|
-
|
|
44851
|
-
|
|
44852
|
-
|
|
44853
|
-
|
|
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
|
-
|
|
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
|
-
|
|
44878
|
-
|
|
44879
|
-
|
|
44880
|
-
|
|
44881
|
-
|
|
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
|
-
|
|
45200
|
-
|
|
45201
|
-
|
|
45202
|
-
|
|
45203
|
-
|
|
45204
|
-
|
|
45205
|
-
|
|
45206
|
-
|
|
45207
|
-
|
|
45208
|
-
|
|
45209
|
-
|
|
45210
|
-
|
|
45211
|
-
|
|
45212
|
-
|
|
45213
|
-
|
|
45214
|
-
connected
|
|
45215
|
-
|
|
45216
|
-
agentStreamControl
|
|
45217
|
-
|
|
45218
|
-
|
|
45219
|
-
|
|
45220
|
-
|
|
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) => !
|
|
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
|
-
|
|
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'`)
|
|
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
|
|
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
|
|
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`
|
|
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.
|
|
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
|
|
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
|
|
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,
|
|
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
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
72
|
-
- After approval, version only a change to scope,
|
|
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.
|
|
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/
|
|
19
|
+
"url": "https://github.com/cybermonklabs/legion"
|
|
20
20
|
},
|
|
21
21
|
"files": [
|
|
22
22
|
"dist",
|