@sjawhar/pi-envoy 15.1.3 → 15.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -105,8 +105,8 @@ set -g set-clipboard on
105
105
 
106
106
  A session with Dispatch configured — a top-level session, a Legion pane or a `task` subagent —
107
107
  sends two extra user messages with every model request of its conversation. At the head, after
108
- any compaction summary, it sends the `dispatch-first` skill, whose text never changes. At the
109
- tail, after the request's last message, it sends what people wrote to the session in the last 72
108
+ any compaction summary, it sends the `dispatch-first` skill, whose text never changes. It also
109
+ sends what people wrote to the session in the last 72
110
110
  hours that Dispatch delivered to it: answers to its asks, replies on them and in its comment
111
111
  threads, comments on its documents and routed issues, mentions, and messages, newest first and
112
112
  word for word. A subagent reads its parent's list. The list stays under 8,000 characters (at most 7,999): the oldest
@@ -119,9 +119,15 @@ own `404 NOT_FOUND` "no route for …". Against that Dispatch a request carries
119
119
  `dispatch answers` cannot read it either; a list read before from it is still carried, its
120
120
  left-out line naming no command; the log says once per session that the Dispatch has no answers
121
121
  route; and that Dispatch is not asked again for 5 minutes. Any other answer, a proxy's 404 page or
122
- a 200 that is no answers list included, is a failed read. The list sits at the tail so that a
123
- change in it costs only its own tokens: the cached conversation before it is sent byte for byte as
124
- before.
122
+ a 200 that is no answers list included, is a failed read.
123
+
124
+ The list goes after the request's last message only on the request where it first shows an item,
125
+ or new words in one. On every request after that it stays right after the message it followed
126
+ there, so the request ends with its own last message and the model does not take a list with
127
+ nothing new in it for a new turn; it keeps that place when it only loses items or its header
128
+ changes. After a compaction summarizes that message, or in a new process, the list goes after the
129
+ last message once more. It is never at the head, so a change in it costs only the bytes after it,
130
+ and a list that keeps its place is inside the cached prefix of the next request.
125
131
 
126
132
  Oh My Pi also builds requests that are not turns of the conversation from it; those carry the
127
133
  skill but no list, and wait on no read: a side turn (a Dispatch BTW, the stop-time self-check,
@@ -191,10 +197,13 @@ The extension registers no Dispatch tool. Agents reach Dispatch through the `dis
191
197
  their shell: `dispatch --help` lists its commands, `dispatch <command> --help` each one's flags and
192
198
  an example, and the `dispatch` skill teaches when to use each. The package ships `bin/dispatch`, a
193
199
  shim that runs the bundled `dist/dispatch.js` (built from `@legion/envoy-client`'s
194
- `bin/dispatch.ts`) with `bun`. At load the extension puts that `bin/` first on `PATH`, sets
195
- `DISPATCH_HOST=omp` and hands the session's envoy.json on as `ENVOY_CONFIG_FILE`; each session
196
- start, switch and branch sets `DISPATCH_SESSION_ID` to the session's id, so a command acts as the
197
- session whose shell ran it and reads the file that session reads.
200
+ `bin/dispatch.ts`) with `bun`. The manifest's `omp.bin` names that `bin/`, so an Oh My Pi that
201
+ supports the field puts it on `PATH` under the plugin's installed path, which keeps working when a
202
+ symlinked plugins root is re-pointed and its old target removed; under an older Oh My Pi the
203
+ extension puts `bin/` first on `PATH` itself at load. The extension also sets `DISPATCH_HOST=omp`
204
+ and hands the session's envoy.json on as `ENVOY_CONFIG_FILE`; each session start, switch and
205
+ branch sets `DISPATCH_SESSION_ID` to the session's id, so a command acts as the session whose shell
206
+ ran it and reads the file that session reads.
198
207
 
199
208
  A session reads one envoy.json, with a section for Dispatch and one for Envoy:
200
209
 
package/dist/dispatch.js CHANGED
@@ -15292,7 +15292,7 @@ var dispatchToolSpecs = [
15292
15292
  ops: [{ op: "delete_column", block: "table-123", index: 1 }],
15293
15293
  precondition: { blocks: [{ id: "table-123", token: "sha256:current-table-token" }] }
15294
15294
  },
15295
- description: "Apply deterministic document edits: replace or delete quoted text, insert markdown at an anchor, retype an identified paragraph or typed block into a schema-declared typed block, delete or move a whole block by its id, or delete a table row or column in place. " + "Do not use it for review feedback or for reading; use dispatch comment, dispatch suggest, or dispatch doc-read instead. " + `For replace, delete, and quote anchors, find text as rendered: inline Markdown (**bold**, \`code\`) is tolerated and must be balanced; a leading '# ' matches a heading at any level. replace is inline: with is the new text of the matched span, so a marker of a different kind from the block's own stays literal text ('4. Design' written into a heading). A with that opens with a marker of the same kind as the matched block's own would write it twice and is INVALID_OP - including prose that merely looks like one ('1999. was a year' into an ordered item), which you write as text by escaping it ('1999\\. was a year'). The exception is a heading rename whose find carried a heading marker: replace(find="## Old", with="## New") gives '## New', and a different level applies only when find named the heading's actual level (find "## Old" with "### New" makes it an h3), since '# ' selects a heading without naming its level. A task item (\`- [ ]\` / \`- [x]\`) is ticked the same way: when find matches from the start of the item's text and with opens with '[x] ' or '[ ] ', the opening sets the item's box and the rest is its new text (replace(find="Write it", with="[x] Write it") ticks it); the same opening over a plain list item or a paragraph stays literal text. Any non-empty with that renders to no text - a line indented four spaces or a tab, which markdown reads as a code block, or whitespace alone - is INVALID_OP rather than a silent deletion; pass an empty with to delete the matched text on purpose - a list item, quote, typed block or footnote definition left holding only the emptied paragraph keeps it. ` + "with cannot open a new block: after a hard line break inside with (two trailing spaces, or a backslash, before the newline) a heading, bullet, '1.'/'1)' ordered, or '>' blockquote marker is INVALID_OP too, since that line would stay escaped text inside the matched block - use insert, plus delete for what it replaces, to add the block. A hard break in with is itself INVALID_OP when the matched text is in a heading or a table cell, which are written on one line. In a table cell, with is the cell's text: write a | in it bare, in code too, since code whose text has an odd run of backslashes right before a | cannot be stored in a cell and is INVALID_OP, naming the cell. " + "A delete whose find is a block's entire text removes the block (a list emptied of its items goes too); delete with block removes any block by id, and move with block relocates one. A delete or retype that would take an ask block out of the document while its ask is open is refused, with nothing sent. delete_row and delete_column take a table block and a zero-based index, preserving the table block id and refusing to remove cells with open asks or unresolved comments. " + `Insert and move anchors also accept "start", "end", "heading:<exact heading text>", and "block:<id>"; dispatch doc-read --blocks lists every block's id, type, opening words and token, and each table's rows and cells with the indexes delete_row and delete_column take (GET /api/v1/artifacts/{artifact UUID}/blocks serves the same list). ` + "Optionally require the state just read: precondition selects exactly one of a document token from dispatch doc-read, or block {id, token} values from dispatch doc-read --blocks. A block guard must include every block the batch changes; Dispatch resolves quote targets and rejects an uncovered batch rather than applying it. Use a document token for insert or move, which depend on document order. Prefer block tokens when the covered content blocks are independent sections. Tokens include inline marks, so a fresh human comment also makes a stale edit fail. PRECONDITION_FAILED means re-read; EDIT_QUEUE_FULL means back off before retrying. " + "The result carries the document token this edit produced, so a chain of guarded edits passes each result's token as the next edit's precondition with no dispatch doc-read between them. " + "A batch that leaves the document exactly as it was mints no version, named or not, and the result says nothing changed and names each operation that did nothing. " + "A change a browser removes while the edit is in flight is never reported as applied: EDIT_LOST_TO_CONCURRENT_CHANGE means the write was refused and nothing was written, so re-read the document and decide again, as with PRECONDITION_FAILED; lost_ops on a successful result names operations whose text the live document no longer has, because the deletion landed after the version was written. " + "One replace per paragraph: more new paragraphs go in one insert after the last one you rewrote, since two inserts at one anchor come out reversed; read the passage back with dispatch doc-read afterwards. " + "Each decision block the edit adds gets the related-item check dispatch ask gets, waiting at most five seconds for all of them together: the result prints, after its first line, `Decision block <id>:` and what that check found, that it found nothing, or that it was not made and why. " + "A block id written as {#id} longer than 256 bytes is stored, but its block is no graph node, so no reference reaches it. " + `The spec holds requirements, design, and decisions - never progress, status, or timestamps; a record of open items or progress is a document of its own. ${OWNER_REFERENCE} ${SPEC_WRITING_POINTER}`,
15295
+ description: "Apply deterministic document edits: replace or delete quoted text, insert markdown at an anchor, retype an identified paragraph or typed block into a schema-declared typed block, delete or move a whole block by its id, or delete a table row or column in place. " + "Do not use it for review feedback or for reading; use dispatch comment, dispatch suggest, or dispatch doc-read instead. " + "For replace, delete, and quote anchors, find text as rendered: inline Markdown (**bold**, `code`) is tolerated and must be balanced; a leading '# ' matches a heading at any level. A find that opens with a list marker ('- ', '5. ', with an optional '[ ] ' or '[x] ' after it) and matches no text as written selects an item of that kind of list whose text starts with the rest, its number not matched and a box matching only a task item in that state. A find or quote anchor stays inside one block, and in a table inside one cell: ' | ' is the boundary markdown writes between two cells, not text a cell holds, so a quote that runs across cells is refused, naming the cells; change several cells with one operation per cell in the same batch, and anchor on one cell's text. replace is inline: with is the new text of the matched span, so a marker of a different kind from the block's own stays literal text ('4. Design' written into a heading). A with that opens with a marker of the same kind as the matched block's own would write it twice and is INVALID_OP - including prose that merely looks like one ('1999. was a year' into an ordered item), which you write as text by escaping it ('1999\\. was a year'). The exceptions are an item a find's list marker selected (it matched no text as written): replace(find=\"5. Old\", with=\"5. New\") gives the item the text 'New' under its own number, and a with that is the marker alone is INVALID_OP; and a heading rename whose find carried a heading marker: replace(find=\"## Old\", with=\"## New\") gives '## New', where a different level applies only when find named the heading's actual level (find \"## Old\" with \"### New\" makes it an h3), since '# ' selects a heading without naming its level. A task item (`- [ ]` / `- [x]`) is ticked the same way: when find matches from the start of the item's text and with opens with '[x] ' or '[ ] ', the opening sets the item's box and the rest is its new text (replace(find=\"Write it\", with=\"[x] Write it\") ticks it); the same opening over a plain list item or a paragraph stays literal text. Any non-empty with that renders to no text - a line indented four spaces or a tab, which markdown reads as a code block, or whitespace alone - is INVALID_OP rather than a silent deletion; pass an empty with to delete the matched text on purpose - a list item, quote, typed block or footnote definition left holding only the emptied paragraph keeps it. " + "with cannot open a new block: after a hard line break inside with (two trailing spaces, or a backslash, before the newline) a heading, bullet, '1.'/'1)' ordered, or '>' blockquote marker is INVALID_OP too, since that line would stay escaped text inside the matched block - use insert, plus delete for what it replaces, to add the block. A hard break in with is itself INVALID_OP when the matched text is in a heading or a table cell, which are written on one line. In a table cell, with is the cell's text: write a | in it bare, in code too, since code whose text has an odd run of backslashes right before a | cannot be stored in a cell and is INVALID_OP, naming the cell. " + "A delete whose find is a block's entire text removes the block (a list emptied of its items goes too); delete with block removes any block by id, and move with block relocates one. A delete or retype that would take an ask block out of the document while its ask is open is refused, with nothing sent. delete_row and delete_column take a table block and a zero-based index, preserving the table block id and refusing to remove cells with open asks or unresolved comments. " + `Insert and move anchors also accept "start", "end", "heading:<exact heading text>", and "block:<id>"; dispatch doc-read --blocks lists every block's id, type, opening words and token, and each table's rows and cells with the indexes delete_row and delete_column take (GET /api/v1/artifacts/{artifact UUID}/blocks serves the same list). ` + "Optionally require the state just read: precondition selects exactly one of a document token from dispatch doc-read, or block {id, token} values from dispatch doc-read --blocks. A block guard must include every block the batch changes; Dispatch resolves quote targets and rejects an uncovered batch rather than applying it. Use a document token for insert or move, which depend on document order. Prefer block tokens when the covered content blocks are independent sections. Tokens include inline marks, so a fresh human comment also makes a stale edit fail. PRECONDITION_FAILED means re-read; EDIT_QUEUE_FULL means back off before retrying. " + "The result carries the document token this edit produced, so a chain of guarded edits passes each result's token as the next edit's precondition with no dispatch doc-read between them. " + "A batch that leaves the document exactly as it was mints no version, named or not, and the result says nothing changed and names each operation that did nothing. " + "A change a browser removes while the edit is in flight is never reported as applied: EDIT_LOST_TO_CONCURRENT_CHANGE means the write was refused and nothing was written, so re-read the document and decide again, as with PRECONDITION_FAILED; lost_ops on a successful result names operations whose text the live document no longer has, because the deletion landed after the version was written. " + "One replace per paragraph: more new paragraphs go in one insert after the last one you rewrote, since two inserts at one anchor come out reversed; read the passage back with dispatch doc-read afterwards. " + "Each decision block the edit adds gets the related-item check dispatch ask gets, waiting at most five seconds for all of them together: the result prints, after its first line, `Decision block <id>:` and what that check found, that it found nothing, or that it was not made and why. " + "A block id written as {#id} longer than 256 bytes is stored, but its block is no graph node, so no reference reaches it. " + `The spec holds requirements, design, and decisions - never progress, status, or timestamps; a record of open items or progress is a document of its own. ${OWNER_REFERENCE} ${SPEC_WRITING_POINTER}`,
15296
15296
  arguments: (z) => ({
15297
15297
  issue: z.string().describe(ISSUE_REFERENCE).optional(),
15298
15298
  project: z.string().describe("Project key owning the document.").optional(),
package/dist/envoy.js CHANGED
@@ -17048,7 +17048,7 @@ __export(exports_coerce, {
17048
17048
  });
17049
17049
 
17050
17050
  // extensions/envoy.ts
17051
- import { existsSync as existsSync2 } from "fs";
17051
+ import { existsSync as existsSync2, realpathSync as realpathSync2 } from "fs";
17052
17052
  import { delimiter, dirname as dirname2, resolve as resolve4 } from "path";
17053
17053
  import { fileURLToPath } from "url";
17054
17054
 
@@ -30412,7 +30412,7 @@ var dispatchToolSpecs = [
30412
30412
  ops: [{ op: "delete_column", block: "table-123", index: 1 }],
30413
30413
  precondition: { blocks: [{ id: "table-123", token: "sha256:current-table-token" }] }
30414
30414
  },
30415
- description: "Apply deterministic document edits: replace or delete quoted text, insert markdown at an anchor, retype an identified paragraph or typed block into a schema-declared typed block, delete or move a whole block by its id, or delete a table row or column in place. " + "Do not use it for review feedback or for reading; use dispatch comment, dispatch suggest, or dispatch doc-read instead. " + `For replace, delete, and quote anchors, find text as rendered: inline Markdown (**bold**, \`code\`) is tolerated and must be balanced; a leading '# ' matches a heading at any level. replace is inline: with is the new text of the matched span, so a marker of a different kind from the block's own stays literal text ('4. Design' written into a heading). A with that opens with a marker of the same kind as the matched block's own would write it twice and is INVALID_OP - including prose that merely looks like one ('1999. was a year' into an ordered item), which you write as text by escaping it ('1999\\. was a year'). The exception is a heading rename whose find carried a heading marker: replace(find="## Old", with="## New") gives '## New', and a different level applies only when find named the heading's actual level (find "## Old" with "### New" makes it an h3), since '# ' selects a heading without naming its level. A task item (\`- [ ]\` / \`- [x]\`) is ticked the same way: when find matches from the start of the item's text and with opens with '[x] ' or '[ ] ', the opening sets the item's box and the rest is its new text (replace(find="Write it", with="[x] Write it") ticks it); the same opening over a plain list item or a paragraph stays literal text. Any non-empty with that renders to no text - a line indented four spaces or a tab, which markdown reads as a code block, or whitespace alone - is INVALID_OP rather than a silent deletion; pass an empty with to delete the matched text on purpose - a list item, quote, typed block or footnote definition left holding only the emptied paragraph keeps it. ` + "with cannot open a new block: after a hard line break inside with (two trailing spaces, or a backslash, before the newline) a heading, bullet, '1.'/'1)' ordered, or '>' blockquote marker is INVALID_OP too, since that line would stay escaped text inside the matched block - use insert, plus delete for what it replaces, to add the block. A hard break in with is itself INVALID_OP when the matched text is in a heading or a table cell, which are written on one line. In a table cell, with is the cell's text: write a | in it bare, in code too, since code whose text has an odd run of backslashes right before a | cannot be stored in a cell and is INVALID_OP, naming the cell. " + "A delete whose find is a block's entire text removes the block (a list emptied of its items goes too); delete with block removes any block by id, and move with block relocates one. A delete or retype that would take an ask block out of the document while its ask is open is refused, with nothing sent. delete_row and delete_column take a table block and a zero-based index, preserving the table block id and refusing to remove cells with open asks or unresolved comments. " + `Insert and move anchors also accept "start", "end", "heading:<exact heading text>", and "block:<id>"; dispatch doc-read --blocks lists every block's id, type, opening words and token, and each table's rows and cells with the indexes delete_row and delete_column take (GET /api/v1/artifacts/{artifact UUID}/blocks serves the same list). ` + "Optionally require the state just read: precondition selects exactly one of a document token from dispatch doc-read, or block {id, token} values from dispatch doc-read --blocks. A block guard must include every block the batch changes; Dispatch resolves quote targets and rejects an uncovered batch rather than applying it. Use a document token for insert or move, which depend on document order. Prefer block tokens when the covered content blocks are independent sections. Tokens include inline marks, so a fresh human comment also makes a stale edit fail. PRECONDITION_FAILED means re-read; EDIT_QUEUE_FULL means back off before retrying. " + "The result carries the document token this edit produced, so a chain of guarded edits passes each result's token as the next edit's precondition with no dispatch doc-read between them. " + "A batch that leaves the document exactly as it was mints no version, named or not, and the result says nothing changed and names each operation that did nothing. " + "A change a browser removes while the edit is in flight is never reported as applied: EDIT_LOST_TO_CONCURRENT_CHANGE means the write was refused and nothing was written, so re-read the document and decide again, as with PRECONDITION_FAILED; lost_ops on a successful result names operations whose text the live document no longer has, because the deletion landed after the version was written. " + "One replace per paragraph: more new paragraphs go in one insert after the last one you rewrote, since two inserts at one anchor come out reversed; read the passage back with dispatch doc-read afterwards. " + "Each decision block the edit adds gets the related-item check dispatch ask gets, waiting at most five seconds for all of them together: the result prints, after its first line, `Decision block <id>:` and what that check found, that it found nothing, or that it was not made and why. " + "A block id written as {#id} longer than 256 bytes is stored, but its block is no graph node, so no reference reaches it. " + `The spec holds requirements, design, and decisions - never progress, status, or timestamps; a record of open items or progress is a document of its own. ${OWNER_REFERENCE} ${SPEC_WRITING_POINTER}`,
30415
+ description: "Apply deterministic document edits: replace or delete quoted text, insert markdown at an anchor, retype an identified paragraph or typed block into a schema-declared typed block, delete or move a whole block by its id, or delete a table row or column in place. " + "Do not use it for review feedback or for reading; use dispatch comment, dispatch suggest, or dispatch doc-read instead. " + "For replace, delete, and quote anchors, find text as rendered: inline Markdown (**bold**, `code`) is tolerated and must be balanced; a leading '# ' matches a heading at any level. A find that opens with a list marker ('- ', '5. ', with an optional '[ ] ' or '[x] ' after it) and matches no text as written selects an item of that kind of list whose text starts with the rest, its number not matched and a box matching only a task item in that state. A find or quote anchor stays inside one block, and in a table inside one cell: ' | ' is the boundary markdown writes between two cells, not text a cell holds, so a quote that runs across cells is refused, naming the cells; change several cells with one operation per cell in the same batch, and anchor on one cell's text. replace is inline: with is the new text of the matched span, so a marker of a different kind from the block's own stays literal text ('4. Design' written into a heading). A with that opens with a marker of the same kind as the matched block's own would write it twice and is INVALID_OP - including prose that merely looks like one ('1999. was a year' into an ordered item), which you write as text by escaping it ('1999\\. was a year'). The exceptions are an item a find's list marker selected (it matched no text as written): replace(find=\"5. Old\", with=\"5. New\") gives the item the text 'New' under its own number, and a with that is the marker alone is INVALID_OP; and a heading rename whose find carried a heading marker: replace(find=\"## Old\", with=\"## New\") gives '## New', where a different level applies only when find named the heading's actual level (find \"## Old\" with \"### New\" makes it an h3), since '# ' selects a heading without naming its level. A task item (`- [ ]` / `- [x]`) is ticked the same way: when find matches from the start of the item's text and with opens with '[x] ' or '[ ] ', the opening sets the item's box and the rest is its new text (replace(find=\"Write it\", with=\"[x] Write it\") ticks it); the same opening over a plain list item or a paragraph stays literal text. Any non-empty with that renders to no text - a line indented four spaces or a tab, which markdown reads as a code block, or whitespace alone - is INVALID_OP rather than a silent deletion; pass an empty with to delete the matched text on purpose - a list item, quote, typed block or footnote definition left holding only the emptied paragraph keeps it. " + "with cannot open a new block: after a hard line break inside with (two trailing spaces, or a backslash, before the newline) a heading, bullet, '1.'/'1)' ordered, or '>' blockquote marker is INVALID_OP too, since that line would stay escaped text inside the matched block - use insert, plus delete for what it replaces, to add the block. A hard break in with is itself INVALID_OP when the matched text is in a heading or a table cell, which are written on one line. In a table cell, with is the cell's text: write a | in it bare, in code too, since code whose text has an odd run of backslashes right before a | cannot be stored in a cell and is INVALID_OP, naming the cell. " + "A delete whose find is a block's entire text removes the block (a list emptied of its items goes too); delete with block removes any block by id, and move with block relocates one. A delete or retype that would take an ask block out of the document while its ask is open is refused, with nothing sent. delete_row and delete_column take a table block and a zero-based index, preserving the table block id and refusing to remove cells with open asks or unresolved comments. " + `Insert and move anchors also accept "start", "end", "heading:<exact heading text>", and "block:<id>"; dispatch doc-read --blocks lists every block's id, type, opening words and token, and each table's rows and cells with the indexes delete_row and delete_column take (GET /api/v1/artifacts/{artifact UUID}/blocks serves the same list). ` + "Optionally require the state just read: precondition selects exactly one of a document token from dispatch doc-read, or block {id, token} values from dispatch doc-read --blocks. A block guard must include every block the batch changes; Dispatch resolves quote targets and rejects an uncovered batch rather than applying it. Use a document token for insert or move, which depend on document order. Prefer block tokens when the covered content blocks are independent sections. Tokens include inline marks, so a fresh human comment also makes a stale edit fail. PRECONDITION_FAILED means re-read; EDIT_QUEUE_FULL means back off before retrying. " + "The result carries the document token this edit produced, so a chain of guarded edits passes each result's token as the next edit's precondition with no dispatch doc-read between them. " + "A batch that leaves the document exactly as it was mints no version, named or not, and the result says nothing changed and names each operation that did nothing. " + "A change a browser removes while the edit is in flight is never reported as applied: EDIT_LOST_TO_CONCURRENT_CHANGE means the write was refused and nothing was written, so re-read the document and decide again, as with PRECONDITION_FAILED; lost_ops on a successful result names operations whose text the live document no longer has, because the deletion landed after the version was written. " + "One replace per paragraph: more new paragraphs go in one insert after the last one you rewrote, since two inserts at one anchor come out reversed; read the passage back with dispatch doc-read afterwards. " + "Each decision block the edit adds gets the related-item check dispatch ask gets, waiting at most five seconds for all of them together: the result prints, after its first line, `Decision block <id>:` and what that check found, that it found nothing, or that it was not made and why. " + "A block id written as {#id} longer than 256 bytes is stored, but its block is no graph node, so no reference reaches it. " + `The spec holds requirements, design, and decisions - never progress, status, or timestamps; a record of open items or progress is a document of its own. ${OWNER_REFERENCE} ${SPEC_WRITING_POINTER}`,
30416
30416
  arguments: (z) => ({
30417
30417
  issue: z.string().describe(ISSUE_REFERENCE).optional(),
30418
30418
  project: z.string().describe("Project key owning the document.").optional(),
@@ -36641,15 +36641,26 @@ function withinWindow(items, now) {
36641
36641
  const start = now - SESSION_ANSWERS_WINDOW_MS;
36642
36642
  return items.filter((item) => Date.parse(item.at) >= start);
36643
36643
  }
36644
+ function sessionAnswersWords(items) {
36645
+ return items.map((item) => JSON.stringify([
36646
+ item.kind,
36647
+ item.id,
36648
+ item.author.id,
36649
+ item.at,
36650
+ item.edited_at ?? null,
36651
+ item.selected ?? null,
36652
+ item.text
36653
+ ]));
36654
+ }
36644
36655
  var MAX_CHARS_TEXT = SESSION_ANSWERS_MAX_CHARS.toLocaleString("en-US");
36645
36656
  function leftOutLine(count, namesCommand) {
36646
36657
  const counted = `${count} older ${count === 1 ? "item" : "items"} left out to stay under ${MAX_CHARS_TEXT} characters`;
36647
36658
  return namesCommand ? `${counted}: run \`dispatch answers\` to read every one in full.` : `${counted}.`;
36648
36659
  }
36649
- function renderSessionAnswers(items, options) {
36650
- const shown = withinWindow(items, Number(options.now));
36651
- const unsent = shown.length === items.length ? Math.max(0, (options.total ?? items.length) - items.length) : 0;
36652
- const count = shown.length + unsent;
36660
+ function renderShown(items, options) {
36661
+ const inWindow = withinWindow(items, Number(options.now));
36662
+ const unsent = inWindow.length === items.length ? Math.max(0, (options.total ?? items.length) - items.length) : 0;
36663
+ const count = inWindow.length + unsent;
36653
36664
  if (count === 0)
36654
36665
  return;
36655
36666
  const header = options.cached === undefined ? SESSION_ANSWERS_MARKER : `${SESSION_ANSWERS_MARKER}
@@ -36657,7 +36668,7 @@ As read at ${options.cached.readAt}; this read failed: ${failureSentence(options
36657
36668
  const namesCommand = options.withoutCommand !== true;
36658
36669
  const blocks = [];
36659
36670
  let length = header.length;
36660
- for (const item of shown) {
36671
+ for (const item of inWindow) {
36661
36672
  const block = renderSessionAnswerItem(item);
36662
36673
  const after = count - blocks.length - 1;
36663
36674
  const needed = length + 2 + block.length + (after === 0 ? 0 : 2 + leftOutLine(after, namesCommand).length);
@@ -36667,9 +36678,14 @@ As read at ${options.cached.readAt}; this read failed: ${failureSentence(options
36667
36678
  length += 2 + block.length;
36668
36679
  }
36669
36680
  const leftOut = count - blocks.length;
36670
- return [header, ...blocks, ...leftOut === 0 ? [] : [leftOutLine(leftOut, namesCommand)]].join(`
36681
+ const text = [
36682
+ header,
36683
+ ...blocks,
36684
+ ...leftOut === 0 ? [] : [leftOutLine(leftOut, namesCommand)]
36685
+ ].join(`
36671
36686
 
36672
36687
  `);
36688
+ return { text, shown: inWindow.slice(0, blocks.length) };
36673
36689
  }
36674
36690
  function failureSentence(reason) {
36675
36691
  const text = reason.replace(/\s+/g, " ").trim();
@@ -36731,18 +36747,24 @@ async function readSessionAnswers(options) {
36731
36747
  const entries = state.sessions.get(session) ?? new Map;
36732
36748
  state.sessions.set(session, entries);
36733
36749
  const carry = (cache, reason, noRoute = false) => {
36734
- const text = cache === undefined ? undefined : renderSessionAnswers(cache.items, {
36750
+ const rendered = cache === undefined ? undefined : renderShown(cache.items, {
36735
36751
  now: now(),
36736
36752
  total: cache.total,
36737
36753
  cached: { readAt: cache.read_at, reason },
36738
36754
  withoutCommand: noRoute
36739
36755
  });
36740
- if (cache === undefined || text === undefined) {
36756
+ if (cache === undefined || rendered === undefined) {
36741
36757
  if (noRoute)
36742
36758
  return { text: undefined, source: "unavailable", reason };
36743
36759
  return { text: sessionAnswersFailureLine(reason), source: "failure", reason };
36744
36760
  }
36745
- return { text, source: "cache", readAt: cache.read_at, reason };
36761
+ return {
36762
+ text: rendered.text,
36763
+ source: "cache",
36764
+ readAt: cache.read_at,
36765
+ words: sessionAnswersWords(rendered.shown),
36766
+ reason
36767
+ };
36746
36768
  };
36747
36769
  if (!dispatch.enabled) {
36748
36770
  const url = options.dispatchUrl;
@@ -36832,13 +36854,12 @@ async function readSessionAnswers(options) {
36832
36854
  return noRoute();
36833
36855
  if ("failure" in outcome)
36834
36856
  return carry(current.cache, outcome.failure);
36857
+ const rendered = renderShown(outcome.cache.items, { now: now(), total: outcome.cache.total });
36835
36858
  return {
36836
- text: renderSessionAnswers(outcome.cache.items, {
36837
- now: now(),
36838
- total: outcome.cache.total
36839
- }),
36859
+ text: rendered?.text,
36840
36860
  source: "fresh",
36841
- readAt: outcome.cache.read_at
36861
+ readAt: outcome.cache.read_at,
36862
+ words: sessionAnswersWords(rendered?.shown ?? [])
36842
36863
  };
36843
36864
  }
36844
36865
 
@@ -38259,7 +38280,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
38259
38280
 
38260
38281
  // package.json
38261
38282
  var name = "@sjawhar/pi-envoy";
38262
- var version2 = "15.1.3";
38283
+ var version2 = "15.3.0";
38263
38284
  var package_default = {
38264
38285
  name,
38265
38286
  version: version2,
@@ -38271,6 +38292,9 @@ var package_default = {
38271
38292
  ],
38272
38293
  skills: [
38273
38294
  "dist/skills"
38295
+ ],
38296
+ bin: [
38297
+ "bin"
38274
38298
  ]
38275
38299
  },
38276
38300
  repository: {
@@ -39941,6 +39965,14 @@ function endsWithSessionAnswers(messages) {
39941
39965
  const text = leadingText(messages.at(-1), "user");
39942
39966
  return text !== undefined && isSessionAnswersText(text);
39943
39967
  }
39968
+ function messageKey(message) {
39969
+ if (typeof message !== "object" || message === null)
39970
+ return "";
39971
+ const role = "role" in message ? String(message.role) : "";
39972
+ const timestamp = "timestamp" in message ? String(message.timestamp) : "";
39973
+ const call = "toolCallId" in message ? `#${String(message.toolCallId)}` : "";
39974
+ return `${role}@${timestamp}${call}`;
39975
+ }
39944
39976
  function isSideTurn(messages) {
39945
39977
  if (hostText(messages.at(-1), "user") === undefined)
39946
39978
  return false;
@@ -39965,11 +39997,21 @@ function entryMessage2(entry) {
39965
39997
  const timestamp = "timestamp" in entry && typeof entry.timestamp === "string" ? new Date(entry.timestamp).getTime() : undefined;
39966
39998
  return { role, timestamp };
39967
39999
  }
40000
+ function failedCalls(message) {
40001
+ if (message.role !== "assistant" || message.stopReason !== "error" && message.stopReason !== "aborted") {
40002
+ return [];
40003
+ }
40004
+ return (Array.isArray(message.content) ? message.content : []).flatMap((block) => typeof block === "object" && block !== null && ("type" in block) && block.type === "toolCall" && ("id" in block) ? [String(block.id)] : []);
40005
+ }
39968
40006
  function branchPosition(messages, entries) {
39969
40007
  const last = messages.at(-1);
39970
40008
  if (typeof last !== "object" || last === null || !("timestamp" in last) || !("role" in last)) {
39971
40009
  return { at: "absent" };
39972
40010
  }
40011
+ const dropped = new Set(entries.flatMap((entry) => {
40012
+ const message = entryMessage2(entry);
40013
+ return message === undefined ? [] : failedCalls(message);
40014
+ }));
39973
40015
  let later = false;
39974
40016
  let tip;
39975
40017
  for (let index = entries.length - 1;index >= 0; index -= 1) {
@@ -39981,7 +40023,7 @@ function branchPosition(messages, entries) {
39981
40023
  if (message.role === last.role && message.timestamp === last.timestamp) {
39982
40024
  return later ? { at: "before" } : { at: "last", tip };
39983
40025
  }
39984
- const failed = message.role === "assistant" && (message.stopReason === "error" || message.stopReason === "aborted");
40026
+ const failed = message.role === "assistant" && (message.stopReason === "error" || message.stopReason === "aborted") || message.role === "toolResult" && dropped.has(String(message.toolCallId));
39985
40027
  if (!failed)
39986
40028
  later = true;
39987
40029
  }
@@ -39991,10 +40033,39 @@ var CONVERSIONS_KEY = Symbol.for("legion.pi-envoy.session-answers-conversions.v1
39991
40033
  var conversionsGlobal = globalThis;
39992
40034
  var conversions = conversionsGlobal[CONVERSIONS_KEY] ?? new WeakMap;
39993
40035
  conversionsGlobal[CONVERSIONS_KEY] = conversions;
40036
+ var PLACEMENTS_KEY = Symbol.for("legion.pi-envoy.session-answers-placements.v1");
40037
+ var placementsGlobal = globalThis;
40038
+ var placements = placementsGlobal[PLACEMENTS_KEY] ?? new WeakMap;
40039
+ placementsGlobal[PLACEMENTS_KEY] = placements;
40040
+ function showsNew(shown, next) {
40041
+ if (shown.words === undefined || next.words === undefined)
40042
+ return shown.text !== next.text;
40043
+ const before = new Set(shown.words);
40044
+ return next.words.some((word) => !before.has(word));
40045
+ }
40046
+ function placeList(messages, carried, request, compacting) {
40047
+ const list = userTextMessage(carried.text);
40048
+ if (compacting)
40049
+ return [...messages, list];
40050
+ const sessions = placements.get(request.session) ?? new Map;
40051
+ placements.set(request.session, sessions);
40052
+ const placed = sessions.get(request.id);
40053
+ if (placed !== undefined && !showsNew(placed.carried, carried)) {
40054
+ const index = messages.findLastIndex((message) => messageKey(message) === placed.after);
40055
+ if (index >= 0) {
40056
+ sessions.set(request.id, { after: placed.after, carried });
40057
+ return [...messages.slice(0, index + 1), list, ...messages.slice(index + 1)];
40058
+ }
40059
+ }
40060
+ sessions.set(request.id, { after: messageKey(messages.at(-1)), carried });
40061
+ return [...messages, list];
40062
+ }
39994
40063
  async function withSessionAnswers(messages, request) {
39995
- if (decided.has(messages) || endsWithSessionAnswers(messages))
40064
+ if (decided.has(messages))
39996
40065
  return;
39997
40066
  decided.add(messages);
40067
+ if (endsWithSessionAnswers(messages))
40068
+ return placedLegacy(messages, request);
39998
40069
  if (isSideTurn(messages) || hostText(messages.at(-1), "user")?.startsWith(HANDOFF_PROMPT) === true) {
39999
40070
  return;
40000
40071
  }
@@ -40004,19 +40075,30 @@ async function withSessionAnswers(messages, request) {
40004
40075
  conversions.set(request.session, "cut");
40005
40076
  return;
40006
40077
  }
40007
- const key = position.at === "last" ? [
40008
- position.tip,
40009
- ...messages.map((message) => typeof message === "object" && message !== null ? `${"role" in message ? String(message.role) : ""}@${"timestamp" in message ? String(message.timestamp) : ""}` : "")
40010
- ].join(`
40078
+ const key = position.at === "last" ? [position.tip, ...messages.map(messageKey)].join(`
40011
40079
  `) : undefined;
40012
40080
  conversions.set(request.session, { key, afterCut: previous === "cut" });
40013
40081
  if (key !== undefined && typeof previous === "object" && previous.key === key && !previous.afterCut && request.compacting()) {
40014
40082
  return;
40015
40083
  }
40016
- const text = await request.read();
40017
- if (text === undefined)
40084
+ const carried = await request.read();
40085
+ if (carried === undefined)
40018
40086
  return;
40019
- return [...messages, userTextMessage(text)];
40087
+ const placed = placeList(messages, carried, request, previous === "cut" || request.compacting());
40088
+ decided.add(placed);
40089
+ return placed;
40090
+ }
40091
+ function placedLegacy(messages, request) {
40092
+ const last = messages.at(-1);
40093
+ const text = leadingText(last, "user");
40094
+ const added = typeof last === "object" && last !== null && "timestamp" in last && last.timestamp === 0;
40095
+ if (text === undefined || !added)
40096
+ return;
40097
+ const recorded = conversions.get(request.session);
40098
+ const compacting = typeof recorded === "object" && recorded.afterCut || request.compacting();
40099
+ const placed = placeList(messages.slice(0, -1), { text }, request, compacting);
40100
+ decided.add(placed);
40101
+ return placed;
40020
40102
  }
40021
40103
 
40022
40104
  // src/side-turn.ts
@@ -44006,7 +44088,14 @@ function resolveSkillsDirectory() {
44006
44088
  var SKILLS_DIRECTORY = resolveSkillsDirectory();
44007
44089
  var DISPATCH_FIRST_CONTEXT = readDispatchFirstContext(dispatchFirstSkillFile(SKILLS_DIRECTORY));
44008
44090
  var PLUGIN_BIN = resolve4(dirname2(fileURLToPath(import.meta.url)), "..", "bin");
44009
- if (!(process.env.PATH ?? "").split(delimiter).includes(PLUGIN_BIN)) {
44091
+ var pluginBinOnPath = (process.env.PATH ?? "").split(delimiter).some((entry) => {
44092
+ try {
44093
+ return entry !== "" && realpathSync2(entry) === PLUGIN_BIN;
44094
+ } catch {
44095
+ return false;
44096
+ }
44097
+ });
44098
+ if (!pluginBinOnPath) {
44010
44099
  process.env.PATH = `${PLUGIN_BIN}${delimiter}${process.env.PATH ?? ""}`;
44011
44100
  }
44012
44101
  process.env.DISPATCH_HOST = "omp";
@@ -45631,10 +45720,10 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
45631
45720
  });
45632
45721
  if (read.notice !== undefined)
45633
45722
  logger3.warn(`envoy: ${read.notice}`);
45634
- return read.text;
45723
+ return read.text === undefined ? undefined : { text: read.text, words: read.words ?? [] };
45635
45724
  } catch (error) {
45636
45725
  logger3.warn(`envoy: people's answers could not be read: ${messageFor(error)}`);
45637
- return sessionAnswersFailureLine(messageFor(error));
45726
+ return { text: sessionAnswersFailureLine(messageFor(error)), words: [] };
45638
45727
  }
45639
45728
  };
45640
45729
  if (atStart.dispatch.enabled || inbound) {
@@ -45646,6 +45735,7 @@ ${REPLAYED_BTW_NOTE}`, frame.envelope, "inert");
45646
45735
  const messages = await withSessionAnswers(withSkill ?? aged ?? event.messages, {
45647
45736
  branch: () => context.sessionManager.getBranch?.() ?? [],
45648
45737
  session: context.sessionManager,
45738
+ id: context.sessionManager.getSessionId(),
45649
45739
  compacting: () => {
45650
45740
  const live = liveAgentSession(context.sessionManager.getSessionId());
45651
45741
  return live !== undefined && (("isCompacting" in live) && live.isCompacting === true || ("compactionSpeculation" in live) && live.compactionSpeculation === "running");
@@ -47,8 +47,7 @@ A claim, or `dispatch issue-update --route session:<your id>` (`--route ''` on r
47
47
 
48
48
  ## Close what you opened
49
49
 
50
- - An ask you opened is yours until answered or resolved. `dispatch resolve-ask` it that turn once anything makes it needless: another answer, a later write, work dropped.
51
- - Retract an ask a new one replaces.
50
+ - Resolve your open ask (`dispatch resolve-ask`) the turn it turns needless: another answer, a later write, dropped work, a replacement. If a person said keep it open, say why in its thread; they close it.
52
51
 
53
52
  ## Structure over stream
54
53
 
@@ -67,6 +66,7 @@ Link each item you name:
67
66
  ```text
68
67
  dispatch://KEY
69
68
  dispatch://KEY/spec
69
+ dispatch://KEY/spec#b-<block>[@vN]
70
70
  dispatch://KEY/artifact/<slug>[@vN]
71
71
  dispatch://KEY/ask/<id>
72
72
  dispatch://KEY/ask/<id>#b-<part>[@vN]
@@ -20,55 +20,56 @@ Part | Content
20
20
  `Goals and non-goals` | What is in and out of scope
21
21
  `Requirements` | `**R1.**` on, each naming its source (`From:`)
22
22
  `Design` | How it meets them; a value and its reason for each limit, size and time
23
- `Decisions` | Your own choices
23
+ `Decisions` | One line: `The decisions are in dispatch://KEY/artifact/decisions-md.`
24
24
  `Acceptance` | `**A1.**` on, each naming the requirements it tests
25
25
 
26
- Another agent can build and check the work from the spec alone. A small change gets a few sentences per part, no matrix. Split a large design into child issues.
26
+ Another agent can build and check the work from the spec alone. A small change gets a few sentences per part, no matrix; split a large design into child issues.
27
27
 
28
28
  ## Rules for the text
29
29
 
30
30
  For each spec, ask, comment and message:
31
31
 
32
32
  - Write in `skill://asd-ste100`'s strict mode.
33
- - Write about the current design, never the person or how people reached it. Never quote people or upload their words.
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 (a test, review, check or proof) also says what the pass does not show: "The tests pass; they catch a wrong verdict, not a proof of a contradiction."
36
+ - A sentence that cites a gate passing (test, review, check, proof) also says what the pass does not show: "Tests pass: a wrong verdict, not a missing one."
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
- - Explain each name or term a new reader may not know. Say in a clause what each issue you name does for this reader.
39
+ - Explain each name or term a new reader may not know, and what each issue you name does for them.
40
40
  - In an ask, ask block, comment or message, name a requirement or check by what it is, never its number.
41
41
 
42
42
  ## Questions
43
43
 
44
- - Name the concrete case first: which machines, files, sessions or people, and the numbers. Then ask the choice in those terms, never "Which option?": a reader cannot work back from a general question to the case.
45
- - Propose an answer to each point, numbers included, with a reason.
46
- - A choice inside what the person asked for, or one their messages favour, is settled: decide it.
44
+ - Name the concrete case first: which machines, files, sessions or people, and the numbers. Then ask the choice in those terms, never "Which option?".
45
+ - A choice inside what the person asked for, or one their messages favour, is yours: decide it.
47
46
  - Ask only for the person's authority, taste or risk appetite, when options differ on what they care about.
48
- - Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options with costs, your recommendation, answerable on a phone.
47
+ - Ask with an [ask block](skill://dispatch/SKILL.md#asks-and-ask-blocks): 2 to 4 options with costs, your recommendation and its reason, answerable on a phone.
49
48
 
50
49
  ## Each version
51
50
 
52
- 1. After a person's answer, comment or edit, rewrite what it touches; delete what it contradicts. Never narrate an edit or what used to be here; versions and comments hold the history. Reply in a comment's thread.
53
- 2. Before each spec write, paste the whole spec, never a path, into a fresh subagent's assignment. It lists gaps, conflicts, uncheckable requirements, unclear text, and missing or needless questions. Fix or record each.
51
+ 1. After a person's answer, comment or edit, rewrite what it touches and delete what it contradicts. Never narrate an edit or what used to be here: versions and comments hold the history. Reply in a comment's thread.
52
+ 2. Before each spec write, paste the whole spec, never a path, into a fresh subagent: it lists gaps, conflicts, uncheckable requirements, unclear text and missing or needless questions. Fix or record each.
54
53
  3. Before each approval request, `wait` for a read-only fact check: `task(agent="scout")`.
55
54
  4. Name each version with `dispatch doc-edit --summary`.
56
55
 
57
56
  ## Decisions
58
57
 
59
- - Each design choice no source states is a `###` entry: choice, reason, options weighed, parts shaped.
60
- - An unsure entry adds an `Unsure:` paragraph: what would change your mind.
61
- - A replaced entry moves under a final `### Replaced`.
62
- - Link a person's answered ask block from each part it shapes.
58
+ Each choice you made alone, and each a person made in an answered ask, is a `##` section of the issue's `decisions.md`.
59
+
60
+ - The heading names the choice; the text gives the reason and the options weighed.
61
+ - Link each spec block it shaped, `dispatch://KEY/spec#b-<id>` (`doc-read --blocks` lists the ids), and a person's decision its ask, `dispatch://KEY/ask/<id>`.
62
+ - An unsure section adds a paragraph that starts `Unsure:`: what would change your mind.
63
+ - A replaced section moves under a final `## Replaced` as a `###`.
63
64
 
64
65
  ## Old specs
65
66
 
66
- At your next edit, rewrite a spec outside the outline whole, in one version. Move its ask blocks with `doc-edit`'s `move`. Kept text follows the text rules: restate each retelling, quotation or unlinked attribution as design, or cut it.
67
+ At your next edit, rewrite a spec outside the outline whole in one version, moving its ask blocks with `doc-edit`'s `move`; restate each retelling, quotation or unlinked attribution as design, or cut it.
67
68
 
68
69
  ## Approval
69
70
 
70
- - Request approval once, when each ask block is answered or waived, each claim is checked, and this version is unapproved. Unbuilt acceptance checks never delay it.
71
- - After approval, version only a change to scope, acceptance, cost, risk or a person's decision, all at once. Put other fixes in the plan or a comment.
71
+ - Request approval once: each ask block answered or waived, each claim checked, this version unapproved. Unbuilt acceptance checks never delay it.
72
+ - After approval, version only a change to scope, acceptance, cost, risk or a person's decision, all at once; put other fixes in the plan or a comment.
72
73
 
73
74
  ## The plan
74
75
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "15.1.3",
3
+ "version": "15.3.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {
@@ -9,6 +9,9 @@
9
9
  ],
10
10
  "skills": [
11
11
  "dist/skills"
12
+ ],
13
+ "bin": [
14
+ "bin"
12
15
  ]
13
16
  },
14
17
  "repository": {