@sjawhar/pi-envoy 14.2.1 → 15.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -0
- package/dist/dispatch.js +177 -5
- package/dist/envoy.js +130 -3
- package/dist/skills/envoy/SKILL.md +1 -1
- package/dist/skills/envoy/references/legion.md +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -284,6 +284,13 @@ dispatch artifact --issue LEGION-1 --name spec.md --content-file - <<'EOF'
|
|
|
284
284
|
EOF
|
|
285
285
|
```
|
|
286
286
|
|
|
287
|
+
`dispatch handoff-write --issue <KEY> --phase <phase> --body-file <path>` records a Legion phase
|
|
288
|
+
handoff on its issue as this session: the file's text, one JSON object, is stored exactly as
|
|
289
|
+
written, and each write is the phase's next version. Keep the file outside the workspace (such as
|
|
290
|
+
`$TMPDIR/<KEY>-<phase>.json`), since jj snapshots every file in it.
|
|
291
|
+
`dispatch handoff-read --issue <KEY> --phase <phase>` prints one line naming the record's version,
|
|
292
|
+
id, session and time, then the body exactly as stored; `--version <n>` reads an earlier version.
|
|
293
|
+
|
|
287
294
|
Lifecycle and scope decisions between Legion roles go through `envoy_publish` to the owning
|
|
288
295
|
architect's role topic; Dispatch is for durable questions to the human and the shared
|
|
289
296
|
document, not for coordination between roles.
|
package/dist/dispatch.js
CHANGED
|
@@ -14551,6 +14551,11 @@ var IssueDeployedEventPayloadSchema = strictObject({
|
|
|
14551
14551
|
run_id: number2().int().positive(),
|
|
14552
14552
|
completed_at: exports_iso.datetime()
|
|
14553
14553
|
});
|
|
14554
|
+
var HandoffRecordedPayloadSchema = strictObject({
|
|
14555
|
+
handoff_id: string2(),
|
|
14556
|
+
phase: string2(),
|
|
14557
|
+
version: number2().int().positive()
|
|
14558
|
+
});
|
|
14554
14559
|
var DispatchServerStartedPayloadSchema = strictObject({
|
|
14555
14560
|
commit: string2().min(1),
|
|
14556
14561
|
started_at: exports_iso.datetime()
|
|
@@ -14975,6 +14980,39 @@ function imagesArgument(z, owner, cap) {
|
|
|
14975
14980
|
var ASK_URGENCIES = ["low", "med", "high", "blocking"];
|
|
14976
14981
|
var ASK_QUESTION_MAX = 2000;
|
|
14977
14982
|
var DISPATCH_BODY_MAX = 32000;
|
|
14983
|
+
var DISPATCH_HANDOFF_BODY_MAX = 262144;
|
|
14984
|
+
var HANDOFF_PHASE_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
|
|
14985
|
+
var HANDOFF_PHASE_RULE_WORDS = "a lowercase letter, then up to 31 lowercase letters, digits or hyphens, such as implement";
|
|
14986
|
+
var HANDOFF_PHASE_RULE = `phase is not a handoff phase: ${HANDOFF_PHASE_RULE_WORDS}`;
|
|
14987
|
+
function isJsonObjectText(text) {
|
|
14988
|
+
try {
|
|
14989
|
+
const parsed = JSON.parse(text);
|
|
14990
|
+
return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed);
|
|
14991
|
+
} catch {
|
|
14992
|
+
return false;
|
|
14993
|
+
}
|
|
14994
|
+
}
|
|
14995
|
+
function handoffProblem(value) {
|
|
14996
|
+
const { phase, body } = value;
|
|
14997
|
+
if (typeof phase === "string" && !HANDOFF_PHASE_PATTERN.test(phase))
|
|
14998
|
+
return HANDOFF_PHASE_RULE;
|
|
14999
|
+
if (typeof body !== "string")
|
|
15000
|
+
return;
|
|
15001
|
+
const bytes = new TextEncoder().encode(body).length;
|
|
15002
|
+
if (bytes > DISPATCH_HANDOFF_BODY_MAX) {
|
|
15003
|
+
return `body is ${bytes - DISPATCH_HANDOFF_BODY_MAX} bytes over the ${DISPATCH_HANDOFF_BODY_MAX}-byte limit (${bytes}/${DISPATCH_HANDOFF_BODY_MAX})`;
|
|
15004
|
+
}
|
|
15005
|
+
if (!isJsonObjectText(body)) {
|
|
15006
|
+
return 'body is not one JSON object: a handoff body is a JSON object such as {"schemaVersion":1}';
|
|
15007
|
+
}
|
|
15008
|
+
return;
|
|
15009
|
+
}
|
|
15010
|
+
var HANDOFF_RULE = `${HANDOFF_PHASE_RULE}; the body is one JSON object of at most ${DISPATCH_HANDOFF_BODY_MAX} bytes.`;
|
|
15011
|
+
var handoffValidation = {
|
|
15012
|
+
check: (value) => handoffProblem(value) === undefined,
|
|
15013
|
+
message: HANDOFF_RULE,
|
|
15014
|
+
refusal: (value) => handoffProblem(value) ?? HANDOFF_RULE
|
|
15015
|
+
};
|
|
14978
15016
|
var SEARCH_QUERY_MAX = 1000;
|
|
14979
15017
|
var SEARCH_QUERY_HINT = "search with a short phrase of a few words, not a passage";
|
|
14980
15018
|
var SEARCH_KIND_DEPTH = 100;
|
|
@@ -15290,7 +15328,7 @@ var dispatchToolSpecs = [
|
|
|
15290
15328
|
name: "dispatch_artifact",
|
|
15291
15329
|
example: { issue: "DSP-1", name: "design.md", content: `# Design
|
|
15292
15330
|
` },
|
|
15293
|
-
description: "Attach a local file or inline text as an issue artifact or project document. Do not use it to edit a live document; use " + "dispatch doc-edit instead. Never upload a document's own name to change it (spec.md replaces the spec whole); edit it with dispatch doc-edit. Uploading the same name again makes its next version. Exactly one of path or content is required; a markdown document is at most 1 MiB and any other file at most 25 MiB. " + "Markdown is also refused with 413 CAP_EXCEEDED when it makes more than 65,536 elements (a block weighs 3, and an empty list item, quote, footnote definition or typed block 3 more for the empty paragraph it holds; a table cell 4, a hard line break 3, an image 3, a piece of inline HTML 2, an autolink 2, a footnote reference 2; inline syntax, marks, lines of text and backslash escapes or character references 1 each), or when a new version would leave the document's stored markdown (what its text reads back as) longer than 1 MiB or making more than 65,536 elements, and longer or heavier than before; shorten it or split it across documents. " + "In a table row, write every | in a cell as \\|, in code too: a | after two backslashes ends the cell, and a row with more cells than its table is refused. " + "Markdown holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK; a new version of a document is held to it only for the asks it writes or changes. " + `${OWNER_REFERENCE}`,
|
|
15331
|
+
description: "Attach a local file or inline text as an issue artifact or project document. Do not use it to edit a live document; use " + "dispatch doc-edit instead. Never upload a document's own name to change it (spec.md replaces the spec whole); edit it with dispatch doc-edit. Uploading the same name again makes its next version, and so does uploading a document's slug (plan-md for plan.md). Exactly one of path or content is required; a markdown document is at most 1 MiB and any other file at most 25 MiB. " + "Markdown is also refused with 413 CAP_EXCEEDED when it makes more than 65,536 elements (a block weighs 3, and an empty list item, quote, footnote definition or typed block 3 more for the empty paragraph it holds; a table cell 4, a hard line break 3, an image 3, a piece of inline HTML 2, an autolink 2, a footnote reference 2; inline syntax, marks, lines of text and backslash escapes or character references 1 each), or when a new version would leave the document's stored markdown (what its text reads back as) longer than 1 MiB or making more than 65,536 elements, and longer or heavier than before; shorten it or split it across documents. " + "In a table row, write every | in a cell as \\|, in code too: a | after two backslashes ends the cell, and a row with more cells than its table is refused. " + "Markdown holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK; a new version of a document is held to it only for the asks it writes or changes. " + `${OWNER_REFERENCE}`,
|
|
15294
15332
|
arguments: (z) => ({
|
|
15295
15333
|
issue: z.string().describe(ISSUE_REFERENCE).optional(),
|
|
15296
15334
|
project: z.string().describe("Project key for an unlinked document.").optional(),
|
|
@@ -15436,6 +15474,34 @@ var dispatchToolSpecs = [
|
|
|
15436
15474
|
description: "Who Dispatch takes this session for: {session, owner, service, project}. session is the session Dispatch records your writes as. It is the session your credential proved, and the tool says so when that is not the session you run in. owner is the lowercase email of the person you act for, and is the first choice of assignee for issues you create. owner is null under the shared token. With a null owner, a create with no assignee falls back to the parent's assignee and then to the project's default assignee. service is the subject of the verified service-account token that authenticated you, or null. project is the one project key your credential may write, or null when it names none.",
|
|
15437
15475
|
arguments: () => ({}),
|
|
15438
15476
|
strict: true
|
|
15477
|
+
},
|
|
15478
|
+
{
|
|
15479
|
+
name: "dispatch_handoff_write",
|
|
15480
|
+
example: {
|
|
15481
|
+
issue: "DSP-1",
|
|
15482
|
+
phase: "implement",
|
|
15483
|
+
body: '{"schemaVersion":1,"phase":"implement","issue":"DSP-1"}'
|
|
15484
|
+
},
|
|
15485
|
+
description: "Record this session's handoff for one phase of an issue: the body, one JSON object, is " + "stored on the issue exactly as sent, under this session, and read back byte for byte. Each " + "write is the next version (1, 2, ...) of that phase's handoff; earlier versions stay. Write " + "the body to a file outside your workspace and pass it with --body-file (- reads stdin). A " + "closed issue refuses it with 409 ISSUE_CLOSED, and a body over " + `${DISPATCH_HANDOFF_BODY_MAX} bytes with 413 CAP_EXCEEDED. Read it back with dispatch ` + `handoff-read. ${ISSUE_REFERENCE}`,
|
|
15486
|
+
arguments: (z) => ({
|
|
15487
|
+
issue: z.string().describe(ISSUE_REFERENCE),
|
|
15488
|
+
phase: z.string().describe("The phase the handoff ends: a lowercase slug such as plan, implement, test or review."),
|
|
15489
|
+
body: z.string({ min: 1 }).describe(`The handoff: one JSON object, at most ${DISPATCH_HANDOFF_BODY_MAX} bytes, stored and read back exactly as sent.`)
|
|
15490
|
+
}),
|
|
15491
|
+
validation: handoffValidation,
|
|
15492
|
+
strict: true
|
|
15493
|
+
},
|
|
15494
|
+
{
|
|
15495
|
+
name: "dispatch_handoff_read",
|
|
15496
|
+
example: { issue: "DSP-1", phase: "implement" },
|
|
15497
|
+
description: "Read the newest handoff recorded for one phase of an issue, or the version you name: one " + "line naming the phase, version, id, the session that wrote it and when, then the body " + "exactly as stored. A closed issue's handoffs read too. A phase with no handoff, or no " + `such version, is 404 HANDOFF_NOT_FOUND. ${ISSUE_REFERENCE}`,
|
|
15498
|
+
arguments: (z) => ({
|
|
15499
|
+
issue: z.string().describe(ISSUE_REFERENCE),
|
|
15500
|
+
phase: z.string().describe("The handoff's phase: a lowercase slug such as plan, implement, test or review."),
|
|
15501
|
+
version: z.number({ int: true, min: 1 }).describe("The version to read, from 1; omit it to read the newest.").optional()
|
|
15502
|
+
}),
|
|
15503
|
+
validation: handoffValidation,
|
|
15504
|
+
strict: true
|
|
15439
15505
|
}
|
|
15440
15506
|
];
|
|
15441
15507
|
|
|
@@ -16527,6 +16593,35 @@ var KEYED_LAYER_MEMORY_MS = 5 * 60000;
|
|
|
16527
16593
|
var KEYED_LAYER_SEEN = new Map;
|
|
16528
16594
|
var KEYED_LAYER_PROBES = new Map;
|
|
16529
16595
|
var KEY_LAYER_PROBE_MS = 5000;
|
|
16596
|
+
function keyedLayerMemory() {
|
|
16597
|
+
const wall = Date.now();
|
|
16598
|
+
const now = performance.now();
|
|
16599
|
+
const kept = {};
|
|
16600
|
+
for (const [origin, seen] of KEYED_LAYER_SEEN) {
|
|
16601
|
+
const age = now - seen;
|
|
16602
|
+
if (age >= 0 && age < KEYED_LAYER_MEMORY_MS) {
|
|
16603
|
+
kept[origin] = new Date(wall - age).toISOString();
|
|
16604
|
+
}
|
|
16605
|
+
}
|
|
16606
|
+
return kept;
|
|
16607
|
+
}
|
|
16608
|
+
function rememberKeyedLayer(saved) {
|
|
16609
|
+
if (typeof saved !== "object" || saved === null)
|
|
16610
|
+
return;
|
|
16611
|
+
const wall = Date.now();
|
|
16612
|
+
const now = performance.now();
|
|
16613
|
+
for (const [origin, at] of Object.entries(saved)) {
|
|
16614
|
+
if (typeof at !== "string")
|
|
16615
|
+
continue;
|
|
16616
|
+
const age = wall - Date.parse(at);
|
|
16617
|
+
if (!(age >= 0 && age < KEYED_LAYER_MEMORY_MS))
|
|
16618
|
+
continue;
|
|
16619
|
+
const seen = now - age;
|
|
16620
|
+
const known = KEYED_LAYER_SEEN.get(origin);
|
|
16621
|
+
if (known === undefined || known < seen)
|
|
16622
|
+
KEYED_LAYER_SEEN.set(origin, seen);
|
|
16623
|
+
}
|
|
16624
|
+
}
|
|
16530
16625
|
function keyEchoed(response, key) {
|
|
16531
16626
|
const echoed = response.headers.get(IDEMPOTENCY_KEY_HEADER)?.trim() ?? "";
|
|
16532
16627
|
return echoed.replace(/^"(.*)"$/, "$1") === key;
|
|
@@ -16993,6 +17088,26 @@ class DispatchClient {
|
|
|
16993
17088
|
async getComments(issue) {
|
|
16994
17089
|
return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "comments"]);
|
|
16995
17090
|
}
|
|
17091
|
+
async writeHandoff(issue, phase, input) {
|
|
17092
|
+
return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "handoffs", phase], input);
|
|
17093
|
+
}
|
|
17094
|
+
async listHandoffs(issue) {
|
|
17095
|
+
return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "handoffs"]);
|
|
17096
|
+
}
|
|
17097
|
+
async latestHandoff(issue, phase) {
|
|
17098
|
+
return this.#json("GET", [
|
|
17099
|
+
"api",
|
|
17100
|
+
"v1",
|
|
17101
|
+
"issues",
|
|
17102
|
+
await this.#resolveIssue(issue),
|
|
17103
|
+
"handoffs",
|
|
17104
|
+
phase,
|
|
17105
|
+
"latest"
|
|
17106
|
+
]);
|
|
17107
|
+
}
|
|
17108
|
+
async handoff(id) {
|
|
17109
|
+
return this.#json("GET", ["api", "v1", "handoffs", id]);
|
|
17110
|
+
}
|
|
16996
17111
|
async getIssueReferences(issue) {
|
|
16997
17112
|
return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "references"], undefined, { versions: "latest" });
|
|
16998
17113
|
}
|
|
@@ -20710,6 +20825,61 @@ Document token: ${listed.token}`,
|
|
|
20710
20825
|
details: await followedAskDetails(client, read.ask)
|
|
20711
20826
|
};
|
|
20712
20827
|
}
|
|
20828
|
+
case "dispatch_handoff_write": {
|
|
20829
|
+
if (!input.sessionId?.trim()) {
|
|
20830
|
+
throw new Error("host session id is required for dispatch handoff-write");
|
|
20831
|
+
}
|
|
20832
|
+
let recorded;
|
|
20833
|
+
try {
|
|
20834
|
+
recorded = await client.writeHandoff(issue(), stringArg(args, "phase"), {
|
|
20835
|
+
actor,
|
|
20836
|
+
body: stringArg(args, "body")
|
|
20837
|
+
});
|
|
20838
|
+
} catch (error) {
|
|
20839
|
+
throw refusalWithCode(error);
|
|
20840
|
+
}
|
|
20841
|
+
return {
|
|
20842
|
+
text: `Recorded the ${recorded.phase} handoff of ${recorded.issue_key}, version ${recorded.version} (id ${recorded.id})`,
|
|
20843
|
+
details: {
|
|
20844
|
+
issue: recorded.issue_key,
|
|
20845
|
+
phase: recorded.phase,
|
|
20846
|
+
version: recorded.version,
|
|
20847
|
+
handoff: recorded.id
|
|
20848
|
+
}
|
|
20849
|
+
};
|
|
20850
|
+
}
|
|
20851
|
+
case "dispatch_handoff_read": {
|
|
20852
|
+
const issueKey = issue();
|
|
20853
|
+
const phase = stringArg(args, "phase");
|
|
20854
|
+
const version = optionalNumber(args, "version");
|
|
20855
|
+
let handoff;
|
|
20856
|
+
try {
|
|
20857
|
+
if (version === undefined) {
|
|
20858
|
+
handoff = await client.latestHandoff(issueKey, phase);
|
|
20859
|
+
} else {
|
|
20860
|
+
const listed = await client.listHandoffs(issueKey);
|
|
20861
|
+
const ofPhase = listed.filter((summary) => summary.phase === phase);
|
|
20862
|
+
const match = ofPhase.find((summary) => summary.version === version);
|
|
20863
|
+
if (match === undefined) {
|
|
20864
|
+
const newest = Math.max(0, ...ofPhase.map((summary) => summary.version));
|
|
20865
|
+
throw new Error(`HANDOFF_NOT_FOUND: issue ${issueKey} has no ${phase} handoff version ${version}; ${newest === 0 ? `it has no ${phase} handoff at all` : `its newest ${phase} handoff is version ${newest}`}`);
|
|
20866
|
+
}
|
|
20867
|
+
handoff = await client.handoff(match.id);
|
|
20868
|
+
}
|
|
20869
|
+
} catch (error) {
|
|
20870
|
+
throw refusalWithCode(error);
|
|
20871
|
+
}
|
|
20872
|
+
return {
|
|
20873
|
+
text: `${handoff.issue_key} ${handoff.phase} handoff, version ${handoff.version} (id ${handoff.id}), written by ${actorText(handoff.author)} at ${handoff.created_at}
|
|
20874
|
+
${handoff.body}`,
|
|
20875
|
+
details: {
|
|
20876
|
+
issue: handoff.issue_key,
|
|
20877
|
+
phase: handoff.phase,
|
|
20878
|
+
version: handoff.version,
|
|
20879
|
+
handoff: handoff.id
|
|
20880
|
+
}
|
|
20881
|
+
};
|
|
20882
|
+
}
|
|
20713
20883
|
case "dispatch_read": {
|
|
20714
20884
|
const message = optionalString(args, "message");
|
|
20715
20885
|
const picturesOf = (texts) => readPictures(client, picturesNewestFirst(texts), shown);
|
|
@@ -20953,13 +21123,15 @@ function loadSessionMemory(dir, sessionId) {
|
|
|
20953
21123
|
const pictures = shownPictures(sessionId);
|
|
20954
21124
|
for (const address of stringList(state.pictures))
|
|
20955
21125
|
pictures.add(address);
|
|
21126
|
+
rememberKeyedLayer(state.keyedLayer);
|
|
20956
21127
|
return new Set(stringList(state.follows));
|
|
20957
21128
|
}
|
|
20958
21129
|
function writeMemory(dir, sessionId, follows) {
|
|
20959
21130
|
const state = {
|
|
20960
21131
|
advice: [...adviceMemory()],
|
|
20961
21132
|
pictures: [...shownPictures(sessionId)],
|
|
20962
|
-
follows: [...follows]
|
|
21133
|
+
follows: [...follows],
|
|
21134
|
+
keyedLayer: keyedLayerMemory()
|
|
20963
21135
|
};
|
|
20964
21136
|
writeAtomically(join3(dir, "state.json"), `${JSON.stringify(state)}
|
|
20965
21137
|
`);
|
|
@@ -22107,9 +22279,10 @@ async function runDispatchCli(argv, rawEnv, io) {
|
|
|
22107
22279
|
if (value !== undefined && value !== "")
|
|
22108
22280
|
env[name] = value;
|
|
22109
22281
|
}
|
|
22282
|
+
const claudeSession = env.ENVOY_SESSION_ID ?? env.CLAUDE_CODE_SESSION_ID;
|
|
22110
22283
|
const refuse = (text, code, tool, askgate) => {
|
|
22111
22284
|
print(text);
|
|
22112
|
-
const sessionId =
|
|
22285
|
+
const sessionId = claudeSession ?? env.DISPATCH_SESSION_ID;
|
|
22113
22286
|
if (sessionId !== undefined) {
|
|
22114
22287
|
try {
|
|
22115
22288
|
appendResult(sessionDirectory(env, sessionId), {
|
|
@@ -22141,8 +22314,7 @@ async function runDispatchCli(argv, rawEnv, io) {
|
|
|
22141
22314
|
if (host === undefined) {
|
|
22142
22315
|
return refuse(hostName === undefined ? "dispatch: DISPATCH_HOST is not set. The host plugin sets it in an agent's shell. From an agent's session, send the command as a bash call. To run dispatch by hand, set DISPATCH_HOST, and set DISPATCH_SESSION_ID to the id of your own session." : `dispatch: DISPATCH_HOST is ${JSON.stringify(hostName)}, not omp or claude.`, USAGE, parsed.tool);
|
|
22143
22316
|
}
|
|
22144
|
-
const sessionVariable = host === "claude" ? "CLAUDE_CODE_SESSION_ID" : "DISPATCH_SESSION_ID";
|
|
22145
|
-
const sessionId = env[sessionVariable];
|
|
22317
|
+
const [sessionId, sessionVariable] = host === "claude" ? [claudeSession, "ENVOY_SESSION_ID or CLAUDE_CODE_SESSION_ID"] : [env.DISPATCH_SESSION_ID, "DISPATCH_SESSION_ID"];
|
|
22146
22318
|
if (sessionId === undefined) {
|
|
22147
22319
|
return refuse(`dispatch: ${sessionVariable} is not set, so this call has no session to act as. The host plugin sets it in an agent's shell.`, USAGE, parsed.tool);
|
|
22148
22320
|
}
|
package/dist/envoy.js
CHANGED
|
@@ -29692,6 +29692,11 @@ var IssueDeployedEventPayloadSchema = strictObject({
|
|
|
29692
29692
|
run_id: number2().int().positive(),
|
|
29693
29693
|
completed_at: exports_iso.datetime()
|
|
29694
29694
|
});
|
|
29695
|
+
var HandoffRecordedPayloadSchema = strictObject({
|
|
29696
|
+
handoff_id: string2(),
|
|
29697
|
+
phase: string2(),
|
|
29698
|
+
version: number2().int().positive()
|
|
29699
|
+
});
|
|
29695
29700
|
var DispatchServerStartedPayloadSchema = strictObject({
|
|
29696
29701
|
commit: string2().min(1),
|
|
29697
29702
|
started_at: exports_iso.datetime()
|
|
@@ -30095,6 +30100,39 @@ function imagesArgument(z, owner, cap) {
|
|
|
30095
30100
|
var ASK_URGENCIES = ["low", "med", "high", "blocking"];
|
|
30096
30101
|
var ASK_QUESTION_MAX = 2000;
|
|
30097
30102
|
var DISPATCH_BODY_MAX = 32000;
|
|
30103
|
+
var DISPATCH_HANDOFF_BODY_MAX = 262144;
|
|
30104
|
+
var HANDOFF_PHASE_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
|
|
30105
|
+
var HANDOFF_PHASE_RULE_WORDS = "a lowercase letter, then up to 31 lowercase letters, digits or hyphens, such as implement";
|
|
30106
|
+
var HANDOFF_PHASE_RULE = `phase is not a handoff phase: ${HANDOFF_PHASE_RULE_WORDS}`;
|
|
30107
|
+
function isJsonObjectText(text) {
|
|
30108
|
+
try {
|
|
30109
|
+
const parsed = JSON.parse(text);
|
|
30110
|
+
return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed);
|
|
30111
|
+
} catch {
|
|
30112
|
+
return false;
|
|
30113
|
+
}
|
|
30114
|
+
}
|
|
30115
|
+
function handoffProblem(value) {
|
|
30116
|
+
const { phase, body } = value;
|
|
30117
|
+
if (typeof phase === "string" && !HANDOFF_PHASE_PATTERN.test(phase))
|
|
30118
|
+
return HANDOFF_PHASE_RULE;
|
|
30119
|
+
if (typeof body !== "string")
|
|
30120
|
+
return;
|
|
30121
|
+
const bytes = new TextEncoder().encode(body).length;
|
|
30122
|
+
if (bytes > DISPATCH_HANDOFF_BODY_MAX) {
|
|
30123
|
+
return `body is ${bytes - DISPATCH_HANDOFF_BODY_MAX} bytes over the ${DISPATCH_HANDOFF_BODY_MAX}-byte limit (${bytes}/${DISPATCH_HANDOFF_BODY_MAX})`;
|
|
30124
|
+
}
|
|
30125
|
+
if (!isJsonObjectText(body)) {
|
|
30126
|
+
return 'body is not one JSON object: a handoff body is a JSON object such as {"schemaVersion":1}';
|
|
30127
|
+
}
|
|
30128
|
+
return;
|
|
30129
|
+
}
|
|
30130
|
+
var HANDOFF_RULE = `${HANDOFF_PHASE_RULE}; the body is one JSON object of at most ${DISPATCH_HANDOFF_BODY_MAX} bytes.`;
|
|
30131
|
+
var handoffValidation = {
|
|
30132
|
+
check: (value) => handoffProblem(value) === undefined,
|
|
30133
|
+
message: HANDOFF_RULE,
|
|
30134
|
+
refusal: (value) => handoffProblem(value) ?? HANDOFF_RULE
|
|
30135
|
+
};
|
|
30098
30136
|
var SEARCH_QUERY_MAX = 1000;
|
|
30099
30137
|
var SEARCH_QUERY_HINT = "search with a short phrase of a few words, not a passage";
|
|
30100
30138
|
var SEARCH_KIND_DEPTH = 100;
|
|
@@ -30410,7 +30448,7 @@ var dispatchToolSpecs = [
|
|
|
30410
30448
|
name: "dispatch_artifact",
|
|
30411
30449
|
example: { issue: "DSP-1", name: "design.md", content: `# Design
|
|
30412
30450
|
` },
|
|
30413
|
-
description: "Attach a local file or inline text as an issue artifact or project document. Do not use it to edit a live document; use " + "dispatch doc-edit instead. Never upload a document's own name to change it (spec.md replaces the spec whole); edit it with dispatch doc-edit. Uploading the same name again makes its next version. Exactly one of path or content is required; a markdown document is at most 1 MiB and any other file at most 25 MiB. " + "Markdown is also refused with 413 CAP_EXCEEDED when it makes more than 65,536 elements (a block weighs 3, and an empty list item, quote, footnote definition or typed block 3 more for the empty paragraph it holds; a table cell 4, a hard line break 3, an image 3, a piece of inline HTML 2, an autolink 2, a footnote reference 2; inline syntax, marks, lines of text and backslash escapes or character references 1 each), or when a new version would leave the document's stored markdown (what its text reads back as) longer than 1 MiB or making more than 65,536 elements, and longer or heavier than before; shorten it or split it across documents. " + "In a table row, write every | in a cell as \\|, in code too: a | after two backslashes ends the cell, and a row with more cells than its table is refused. " + "Markdown holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK; a new version of a document is held to it only for the asks it writes or changes. " + `${OWNER_REFERENCE}`,
|
|
30451
|
+
description: "Attach a local file or inline text as an issue artifact or project document. Do not use it to edit a live document; use " + "dispatch doc-edit instead. Never upload a document's own name to change it (spec.md replaces the spec whole); edit it with dispatch doc-edit. Uploading the same name again makes its next version, and so does uploading a document's slug (plan-md for plan.md). Exactly one of path or content is required; a markdown document is at most 1 MiB and any other file at most 25 MiB. " + "Markdown is also refused with 413 CAP_EXCEEDED when it makes more than 65,536 elements (a block weighs 3, and an empty list item, quote, footnote definition or typed block 3 more for the empty paragraph it holds; a table cell 4, a hard line break 3, an image 3, a piece of inline HTML 2, an autolink 2, a footnote reference 2; inline syntax, marks, lines of text and backslash escapes or character references 1 each), or when a new version would leave the document's stored markdown (what its text reads back as) longer than 1 MiB or making more than 65,536 elements, and longer or heavier than before; shorten it or split it across documents. " + "In a table row, write every | in a cell as \\|, in code too: a | after two backslashes ends the cell, and a row with more cells than its table is refused. " + "Markdown holding an ask block whose body breaks its content rule (one or more question paragraphs, then at most one bullet list of options, last) is refused with 400 INVALID_ASK_BLOCK; a new version of a document is held to it only for the asks it writes or changes. " + `${OWNER_REFERENCE}`,
|
|
30414
30452
|
arguments: (z) => ({
|
|
30415
30453
|
issue: z.string().describe(ISSUE_REFERENCE).optional(),
|
|
30416
30454
|
project: z.string().describe("Project key for an unlinked document.").optional(),
|
|
@@ -30556,6 +30594,34 @@ var dispatchToolSpecs = [
|
|
|
30556
30594
|
description: "Who Dispatch takes this session for: {session, owner, service, project}. session is the session Dispatch records your writes as. It is the session your credential proved, and the tool says so when that is not the session you run in. owner is the lowercase email of the person you act for, and is the first choice of assignee for issues you create. owner is null under the shared token. With a null owner, a create with no assignee falls back to the parent's assignee and then to the project's default assignee. service is the subject of the verified service-account token that authenticated you, or null. project is the one project key your credential may write, or null when it names none.",
|
|
30557
30595
|
arguments: () => ({}),
|
|
30558
30596
|
strict: true
|
|
30597
|
+
},
|
|
30598
|
+
{
|
|
30599
|
+
name: "dispatch_handoff_write",
|
|
30600
|
+
example: {
|
|
30601
|
+
issue: "DSP-1",
|
|
30602
|
+
phase: "implement",
|
|
30603
|
+
body: '{"schemaVersion":1,"phase":"implement","issue":"DSP-1"}'
|
|
30604
|
+
},
|
|
30605
|
+
description: "Record this session's handoff for one phase of an issue: the body, one JSON object, is " + "stored on the issue exactly as sent, under this session, and read back byte for byte. Each " + "write is the next version (1, 2, ...) of that phase's handoff; earlier versions stay. Write " + "the body to a file outside your workspace and pass it with --body-file (- reads stdin). A " + "closed issue refuses it with 409 ISSUE_CLOSED, and a body over " + `${DISPATCH_HANDOFF_BODY_MAX} bytes with 413 CAP_EXCEEDED. Read it back with dispatch ` + `handoff-read. ${ISSUE_REFERENCE}`,
|
|
30606
|
+
arguments: (z) => ({
|
|
30607
|
+
issue: z.string().describe(ISSUE_REFERENCE),
|
|
30608
|
+
phase: z.string().describe("The phase the handoff ends: a lowercase slug such as plan, implement, test or review."),
|
|
30609
|
+
body: z.string({ min: 1 }).describe(`The handoff: one JSON object, at most ${DISPATCH_HANDOFF_BODY_MAX} bytes, stored and read back exactly as sent.`)
|
|
30610
|
+
}),
|
|
30611
|
+
validation: handoffValidation,
|
|
30612
|
+
strict: true
|
|
30613
|
+
},
|
|
30614
|
+
{
|
|
30615
|
+
name: "dispatch_handoff_read",
|
|
30616
|
+
example: { issue: "DSP-1", phase: "implement" },
|
|
30617
|
+
description: "Read the newest handoff recorded for one phase of an issue, or the version you name: one " + "line naming the phase, version, id, the session that wrote it and when, then the body " + "exactly as stored. A closed issue's handoffs read too. A phase with no handoff, or no " + `such version, is 404 HANDOFF_NOT_FOUND. ${ISSUE_REFERENCE}`,
|
|
30618
|
+
arguments: (z) => ({
|
|
30619
|
+
issue: z.string().describe(ISSUE_REFERENCE),
|
|
30620
|
+
phase: z.string().describe("The handoff's phase: a lowercase slug such as plan, implement, test or review."),
|
|
30621
|
+
version: z.number({ int: true, min: 1 }).describe("The version to read, from 1; omit it to read the newest.").optional()
|
|
30622
|
+
}),
|
|
30623
|
+
validation: handoffValidation,
|
|
30624
|
+
strict: true
|
|
30559
30625
|
}
|
|
30560
30626
|
];
|
|
30561
30627
|
|
|
@@ -32439,6 +32505,26 @@ class DispatchClient {
|
|
|
32439
32505
|
async getComments(issue) {
|
|
32440
32506
|
return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "comments"]);
|
|
32441
32507
|
}
|
|
32508
|
+
async writeHandoff(issue, phase, input) {
|
|
32509
|
+
return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "handoffs", phase], input);
|
|
32510
|
+
}
|
|
32511
|
+
async listHandoffs(issue) {
|
|
32512
|
+
return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "handoffs"]);
|
|
32513
|
+
}
|
|
32514
|
+
async latestHandoff(issue, phase) {
|
|
32515
|
+
return this.#json("GET", [
|
|
32516
|
+
"api",
|
|
32517
|
+
"v1",
|
|
32518
|
+
"issues",
|
|
32519
|
+
await this.#resolveIssue(issue),
|
|
32520
|
+
"handoffs",
|
|
32521
|
+
phase,
|
|
32522
|
+
"latest"
|
|
32523
|
+
]);
|
|
32524
|
+
}
|
|
32525
|
+
async handoff(id) {
|
|
32526
|
+
return this.#json("GET", ["api", "v1", "handoffs", id]);
|
|
32527
|
+
}
|
|
32442
32528
|
async getIssueReferences(issue) {
|
|
32443
32529
|
return this.#json("GET", ["api", "v1", "issues", await this.#resolveIssue(issue), "references"], undefined, { versions: "latest" });
|
|
32444
32530
|
}
|
|
@@ -36976,6 +37062,7 @@ async function readDocumentBlocks(client, target, context) {
|
|
|
36976
37062
|
const decoder = new TextDecoder;
|
|
36977
37063
|
return {
|
|
36978
37064
|
name: resolved.artifact.name,
|
|
37065
|
+
slug: resolved.artifact.slug,
|
|
36979
37066
|
blocks: live.blocks.map((block) => ({
|
|
36980
37067
|
id: block.id,
|
|
36981
37068
|
text: decoder.decode(live.bytes.subarray(block.from, block.to))
|
|
@@ -37906,7 +37993,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
|
|
|
37906
37993
|
|
|
37907
37994
|
// package.json
|
|
37908
37995
|
var name = "@sjawhar/pi-envoy";
|
|
37909
|
-
var version2 = "
|
|
37996
|
+
var version2 = "15.0.1";
|
|
37910
37997
|
var package_default = {
|
|
37911
37998
|
name,
|
|
37912
37999
|
version: version2,
|
|
@@ -40959,7 +41046,7 @@ async function readAsks(deps, call, first) {
|
|
|
40959
41046
|
return { asks, textMissing, asksPartial: false };
|
|
40960
41047
|
}
|
|
40961
41048
|
const name = uploadName(call.input);
|
|
40962
|
-
const currentIds = read !== "not-found" && read.name === name ? new Set(read.blocks.map((block) => block.id)) : undefined;
|
|
41049
|
+
const currentIds = read !== "not-found" && (read.name === name || read.slug === name) ? new Set(read.blocks.map((block) => block.id)) : undefined;
|
|
40963
41050
|
return {
|
|
40964
41051
|
asks: first.filter((ask) => ask.id === undefined || currentIds?.has(ask.id) !== true),
|
|
40965
41052
|
textMissing: false,
|
|
@@ -41159,6 +41246,40 @@ var OPERATORS = ["&&", "||", ";;", "|&", ";", "&", "|", "(", ")"];
|
|
|
41159
41246
|
var REDIRECT = /^(\d*)(&>>|&>|<<<|<<-|<<|<>|<&|>&|>>|>\||<|>)/;
|
|
41160
41247
|
var QUOTED_DELIMITER = /^(?:'[A-Za-z_][A-Za-z0-9_]*'|"[A-Za-z_][A-Za-z0-9_]*")$/;
|
|
41161
41248
|
var EXPANDING = "$`~*?[";
|
|
41249
|
+
function heredocSubstitution(text, from) {
|
|
41250
|
+
if (!text.startsWith("$(", from))
|
|
41251
|
+
return;
|
|
41252
|
+
const opener = /^[^\S\n]*cat[^\S\n]+(?:-[^\S\n]+)?<<(-?)[^\S\n]*(?:'([^']*)'|"([^"\\`]*)")[^\S\n]*\n/.exec(text.slice(from + 2));
|
|
41253
|
+
if (opener === null)
|
|
41254
|
+
return;
|
|
41255
|
+
const delimiter = opener[2] ?? opener[3] ?? "";
|
|
41256
|
+
if (delimiter === "")
|
|
41257
|
+
return;
|
|
41258
|
+
const strip = opener[1] === "-";
|
|
41259
|
+
const body = [];
|
|
41260
|
+
let index = from + 2 + opener[0].length;
|
|
41261
|
+
while (index <= text.length) {
|
|
41262
|
+
const stop = text.indexOf(`
|
|
41263
|
+
`, index);
|
|
41264
|
+
const line = text.slice(index, stop === -1 ? text.length : stop);
|
|
41265
|
+
if ((strip ? line.replace(/^\t+/, "") : line) === delimiter) {
|
|
41266
|
+
const rest = text.slice(stop === -1 ? text.length : stop + 1);
|
|
41267
|
+
const close = /^\s*\)/.exec(rest);
|
|
41268
|
+
if (close === null)
|
|
41269
|
+
return;
|
|
41270
|
+
return {
|
|
41271
|
+
end: (stop === -1 ? text.length : stop + 1) + close[0].length,
|
|
41272
|
+
value: body.join(`
|
|
41273
|
+
`).replace(/\n+$/, "")
|
|
41274
|
+
};
|
|
41275
|
+
}
|
|
41276
|
+
if (stop === -1)
|
|
41277
|
+
break;
|
|
41278
|
+
body.push(strip ? line.replace(/^\t+/, "") : line);
|
|
41279
|
+
index = stop + 1;
|
|
41280
|
+
}
|
|
41281
|
+
return;
|
|
41282
|
+
}
|
|
41162
41283
|
function expansionEnd(text, from) {
|
|
41163
41284
|
if (text[from] === "`") {
|
|
41164
41285
|
let index = from + 1;
|
|
@@ -41236,6 +41357,12 @@ function readWord(text, from) {
|
|
|
41236
41357
|
while (index < text.length && text[index] !== '"') {
|
|
41237
41358
|
const inner = text[index];
|
|
41238
41359
|
if (REFUSED_DOUBLE_QUOTED2.includes(inner)) {
|
|
41360
|
+
const here = inner === "$" ? heredocSubstitution(text, index) : undefined;
|
|
41361
|
+
if (here !== undefined) {
|
|
41362
|
+
value += here.value;
|
|
41363
|
+
index = here.end;
|
|
41364
|
+
continue;
|
|
41365
|
+
}
|
|
41239
41366
|
unread.push(inner);
|
|
41240
41367
|
refused = true;
|
|
41241
41368
|
if (inner === "\\") {
|
|
@@ -56,7 +56,7 @@ Every topic starts with `notifications.`.
|
|
|
56
56
|
## Wait for CI or a merge
|
|
57
57
|
|
|
58
58
|
- Subscribe to `github.<owner>.<repo>.pr.<n>.>` and end the turn. Never start a `gh` poller: the event wakes you, and a poller burns turns.
|
|
59
|
-
- One `pr.<n>.checks` event arrives per commit whose checks settle, the head or not. Compare its `sha` with the head you wait on, because an earlier commit's settlement can arrive first. A
|
|
59
|
+
- One `pr.<n>.checks` event arrives per commit whose checks settle, the head or not. Compare its `sha` with the head you wait on, because an earlier commit's settlement can arrive first. A commit whose message carries one of GitHub's skip keywords (`[skip ci]` and its kin) starts no workflow, so no settlement of it may ever arrive.
|
|
60
60
|
- Settlement waits until the commit has had no check event for 5 seconds (`ENVOY_CI_DEBOUNCE`) and every reported check run and check suite of it has finished. No event arrives before that. Envoy does not read GitHub's required-checks list, so a green settlement does not mean GitHub will merge the PR.
|
|
61
61
|
- A `pr.<n>` event with `closed` and `merged: true` means the PR merged; it carries `merge_commit_sha`, `merged_by` and `head_sha`.
|
|
62
62
|
- A later settlement of the same commit can carry `superseded_settlement: "true"`. Code that orders settlements follows `skill://envoy/references/check-settlement.md`.
|
|
@@ -5,7 +5,7 @@ Read this in a Legion pane before you touch a role claim, or when a Legion role
|
|
|
5
5
|
- The Legion plugin claims your assigned role at session start through a daemon-minted role token. Never call `envoy_role_set` and never subscribe to your role topic yourself, because the claim is already made (`packages/pi-shared/src/legion-claim-core.ts`).
|
|
6
6
|
- Never build a role token from an issue number or title: only the daemon maps tokens to issues.
|
|
7
7
|
- A Legion claim is last-claim-wins. It survives parking and worker re-creation, and stays through the issue's linger after close (the deployment's `linger_hours`).
|
|
8
|
-
- `no_holder`, `delivery_failed` and `receipt_timeout` on a Legion role are the daemon's liveness signals. Never add a second subscriber or retry by hand: the daemon revives or recreates the worker and re-delivers, or relaunches the root process, which gets a `catch-up` notice of its tree and reads
|
|
8
|
+
- `no_holder`, `delivery_failed` and `receipt_timeout` on a Legion role are the daemon's liveness signals. Never add a second subscriber or retry by hand: the daemon revives or recreates the worker and re-delivers, or relaunches the root process, which gets a `catch-up` notice of its tree and reads each issue's handoffs on its Dispatch issue (`dispatch handoff-read`).
|
|
9
9
|
- `no_holder`: no live session holds the role.
|
|
10
10
|
- `delivery_failed`: the message is not known to have reached the holder: the holder lookup failed, the holder was stale, the publish errored, or the stream did not store the forward. In the last case the holder can have seen the message live, and its dedupe drops a re-sent copy.
|
|
11
11
|
- `receipt_timeout`: the listener forwarded the message to a live holder and no receipt arrived in time. Its payload keeps `original_topic`, `event_id`, `payload` and the original `dedupe_key`, so the daemon can re-send it and the receiver's dedupe drops a copy that did arrive.
|