@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 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 = env.CLAUDE_CODE_SESSION_ID ?? env.DISPATCH_SESSION_ID;
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 = "14.2.1";
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 push with GitHub's `skip-checks` trailer runs no checks, and several can sit on top (a Legion handoff push is one): wait for the settlement of the nearest ancestor that is not such a push, the CI head `skill://legion-worker/references/merge-gate.md` reads.
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 the handoffs under `.legion/<issue>/`.
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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "14.2.1",
3
+ "version": "15.0.1",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {