@sjawhar/pi-envoy 11.1.0 → 11.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/dispatch.js CHANGED
@@ -13857,6 +13857,44 @@ function itemFromSearch(search) {
13857
13857
  }
13858
13858
  return ask === null ? { id, kind: "comment" } : { id, kind: "ask" };
13859
13859
  }
13860
+
13861
+ // ../contracts/src/dispatch-block-ref.ts
13862
+ var encoder = new TextEncoder;
13863
+ function encodeBlockId(id) {
13864
+ let encoded = "";
13865
+ for (const character of id) {
13866
+ for (const byte of encoder.encode(character)) {
13867
+ const bare = byte >= 48 && byte <= 57 || byte >= 65 && byte <= 90 || byte >= 97 && byte <= 122 || byte === 45;
13868
+ encoded += bare ? String.fromCharCode(byte) : `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
13869
+ }
13870
+ }
13871
+ return encoded;
13872
+ }
13873
+ function decodeBlockId(encoded) {
13874
+ if (encoded === "" || encoded.includes("@")) {
13875
+ return;
13876
+ }
13877
+ let id;
13878
+ try {
13879
+ id = decodeURIComponent(encoded);
13880
+ } catch {
13881
+ return;
13882
+ }
13883
+ return id === "" || hasControlCharacter(id) ? undefined : id;
13884
+ }
13885
+ var MAX_BLOCK_PIN = 9223372036854775807n;
13886
+ function parseBlockFragment(encoded) {
13887
+ const at = encoded.indexOf("@");
13888
+ const pin = at === -1 ? undefined : encoded.slice(at + 1).match(/^v([1-9][0-9]*)$/)?.[1];
13889
+ if (at !== -1 && (pin === undefined || BigInt(pin) > MAX_BLOCK_PIN)) {
13890
+ return;
13891
+ }
13892
+ const block = decodeBlockId(at === -1 ? encoded : encoded.slice(0, at));
13893
+ if (block === undefined) {
13894
+ return;
13895
+ }
13896
+ return pin === undefined ? { block } : { block, pin };
13897
+ }
13860
13898
  // ../contracts/src/dispatch-snippet.ts
13861
13899
  var HTML_ENTITIES = [
13862
13900
  ["&lt;", "<"],
@@ -14129,7 +14167,7 @@ var dispatchToolSpecs = [
14129
14167
  issue: z2.string().describe(ISSUE_REFERENCE).optional(),
14130
14168
  project: z2.string().describe("Project key owning the document.").optional(),
14131
14169
  artifact: z2.string().describe("Project document artifact id, slug, or filename.").optional(),
14132
- ref: z2.string().describe("Optional dispatch:// reference (issue, document, message, or ask); appended to the question and rendered as a link.").optional(),
14170
+ ref: z2.string().describe("Optional dispatch:// reference (issue, document, block, message, or ask); appended to the question and rendered as a link.").optional(),
14133
14171
  question: z2.string({ max: ASK_QUESTION_MAX }).describe(`${ASK_QUESTION_CONTRACT} At most ${ASK_QUESTION_MAX} characters.`),
14134
14172
  options: z2.array(z2.object({
14135
14173
  label: z2.string().describe("Selectable option label."),
@@ -14274,7 +14312,7 @@ var dispatchToolSpecs = [
14274
14312
  ops: [{ op: "delete_column", block: "table-123", index: 1 }],
14275
14313
  precondition: { blocks: [{ id: "table-123", token: "sha256:current-table-token" }] }
14276
14314
  },
14277
- 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. " + "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. " + `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}`,
14315
+ 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. " + "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. " + "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}`,
14278
14316
  arguments: (z2) => ({
14279
14317
  issue: z2.string().describe(ISSUE_REFERENCE).optional(),
14280
14318
  project: z2.string().describe("Project key owning the document.").optional(),
@@ -14354,12 +14392,12 @@ var dispatchToolSpecs = [
14354
14392
  {
14355
14393
  name: "dispatch_read",
14356
14394
  example: { issue: "DSP-1" },
14357
- description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + `An issue read, and its dispatch://KEY/log, lists the issue's last ${DEFAULT_ISSUE_READ_EVENTS} events, oldest first; ` + "--events N lists the last N, and --all-events every one. " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
14395
+ description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + `An issue read, and its dispatch://KEY/log, lists the issue's last ${DEFAULT_ISSUE_READ_EVENTS} events, oldest first; ` + "--events N lists the last N, and --all-events every one. " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + "A block read prints `Block:`, `Document:`, `Changed in version:` and `Text:`, then those two sections; a pinned one adds " + "the block's text at that version and whether it is unchanged, changed or removed since, and an absent block, unpinned, " + "reads `No block <id> in <document>.` " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
14358
14396
  arguments: (z2) => ({
14359
14397
  issue: z2.string().describe(ISSUE_REFERENCE).optional(),
14360
14398
  project: z2.string().describe("Project key owning the document.").optional(),
14361
14399
  artifact: z2.string().describe("Document artifact id, slug, or filename: one of the issue's, or a project document.").optional(),
14362
- ref: z2.string().describe("Optional dispatch:// reference: dispatch://KEY, dispatch://KEY/spec, " + "dispatch://KEY/artifact/<slug>[@vN], dispatch://KEY/ask/<id>, dispatch://KEY/comment/<id>, " + "dispatch://KEY/message/<id>, dispatch://PROJECT/artifact/<slug>[@vN], and its " + "/ask/<id> and /comment/<id>; or the dashboard URL of one.").optional(),
14400
+ ref: z2.string().describe("Optional dispatch:// reference: dispatch://KEY, dispatch://KEY/spec, " + "dispatch://KEY/artifact/<slug>[@vN], dispatch://KEY/ask/<id>, dispatch://KEY/comment/<id>, " + "dispatch://KEY/message/<id>, dispatch://PROJECT/artifact/<slug>[@vN], and its " + "/ask/<id> and /comment/<id>; or the dashboard URL of one. A block: " + "dispatch://KEY/spec#b-<block id>[@vN], dispatch://KEY/artifact/<slug>#b-<block id>[@vN] or " + "dispatch://PROJECT/artifact/<slug>#b-<block id>[@vN], the id percent-encoded except ASCII " + "letters, digits and -.").optional(),
14363
14401
  message: z2.string().describe("A message id (uuid): reads the conversation it belongs to, the root message and every " + "reply. Name nothing else with it.").optional(),
14364
14402
  events: z2.number({ int: true, min: 1 }).describe(`How many of the issue's newest events an issue read or its dispatch://KEY/log lists, oldest first; default ${DEFAULT_ISSUE_READ_EVENTS}. Name no --all-events with it.`).optional(),
14365
14403
  all_events: z2.boolean().describe(`List every one of the issue's events, oldest first, on an issue read or its dispatch://KEY/log, in place of the last ${DEFAULT_ISSUE_READ_EVENTS}. Name no --events with it.`).optional()
@@ -15723,7 +15761,27 @@ function dispatchDocumentRef(owner, slug) {
15723
15761
  function dispatchChildRef(ownerRef, kind, id) {
15724
15762
  return `${ownerRef}/${kind}/${id}`;
15725
15763
  }
15764
+ function parseBlockRef(document, fragment) {
15765
+ const target = parseBlockFragment(fragment);
15766
+ const parsed = parseDispatchRef(document);
15767
+ if (target === undefined || parsed === null || parsed.version !== undefined || parsed.kind !== "spec" && parsed.kind !== "artifact") {
15768
+ return null;
15769
+ }
15770
+ return {
15771
+ owner: parsed.owner,
15772
+ kind: "block",
15773
+ id: parsed.id,
15774
+ block: target.block,
15775
+ document,
15776
+ ...parsed.owner.kind === "project" ? { artifact: parsed.id } : {},
15777
+ ...target.pin === undefined ? {} : { pin: target.pin }
15778
+ };
15779
+ }
15726
15780
  function parseDispatchRef(ref) {
15781
+ const hash2 = ref.indexOf("#");
15782
+ if (hash2 !== -1 && ref.startsWith("b-", hash2 + 1)) {
15783
+ return parseBlockRef(ref.slice(0, hash2), ref.slice(hash2 + 3));
15784
+ }
15727
15785
  const projectDocument = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)(?:@v(\d+))?(?:\/(ask|comment)\/([^/]+))?$/);
15728
15786
  if (projectDocument) {
15729
15787
  const [, project, artifact2, version3, targetKind, targetID] = projectDocument;
@@ -16856,9 +16914,13 @@ function dispatchRefFromUrl(value, serverUrl) {
16856
16914
  const value2 = url2.searchParams.get(name);
16857
16915
  return value2 !== null && /^[1-9][0-9]*$/.test(value2) ? `@v${value2}` : "";
16858
16916
  };
16917
+ const blockOf = (versionName) => {
16918
+ const id = url2.hash.startsWith("#b-") ? decodeBlockId(url2.hash.slice(3)) : undefined;
16919
+ return id === undefined || url2.searchParams.get(versionName) ? "" : `#b-${encodeBlockId(id)}`;
16920
+ };
16859
16921
  const issuePage = url2.pathname.match(/^\/issues\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)(?:\/(spec|log|conversation|activity|children)|\/artifacts\/([^/]+)|\/asks\/([^/]+)|\/comments\/([^/]+)|\/messages\/([^/]+))?\/?$/);
16860
16922
  if (issuePage) {
16861
- const [, key, page, artifact, ask, comment, message] = issuePage;
16923
+ const [, key = "", page, artifact, ask, comment, message] = issuePage;
16862
16924
  const version2 = versionOf("v");
16863
16925
  if (page === "spec" || artifact !== undefined) {
16864
16926
  const item2 = itemFromSearch(url2.search);
@@ -16869,10 +16931,13 @@ function dispatchRefFromUrl(value, serverUrl) {
16869
16931
  }
16870
16932
  if (page === "spec" && version2 !== "")
16871
16933
  return `dispatch://${key}/artifact/spec${version2}`;
16934
+ if (page === "spec")
16935
+ return `dispatch://${key}/spec${blockOf("v")}`;
16872
16936
  if (page !== undefined)
16873
16937
  return `dispatch://${key}/${page === "conversation" ? "log" : page}`;
16874
16938
  if (artifact !== undefined) {
16875
- return `dispatch://${key}/artifact/${decodeURIComponent(artifact)}${version2}`;
16939
+ const slug2 = decodeURIComponent(artifact);
16940
+ return `dispatch://${key}/artifact/${slug2}${version2}${blockOf("v")}`;
16876
16941
  }
16877
16942
  if (ask !== undefined)
16878
16943
  return `dispatch://${key}/ask/${ask}`;
@@ -16895,25 +16960,26 @@ function dispatchRefFromUrl(value, serverUrl) {
16895
16960
  if (!documentPage)
16896
16961
  return;
16897
16962
  const [, project, slug] = documentPage;
16898
- const document = `dispatch://${project}/artifact/${decodeURIComponent(slug ?? "")}`;
16963
+ const decodedSlug = decodeURIComponent(slug ?? "");
16964
+ const document = `dispatch://${project}/artifact/${decodedSlug}`;
16899
16965
  const item = itemFromSearch(url2.search);
16900
16966
  if (item === null)
16901
16967
  return;
16902
- return item === undefined ? `${document}${versionOf("version")}` : `${document}/${item.kind}/${item.id}`;
16968
+ return item === undefined ? `${document}${versionOf("version")}${blockOf("version")}` : `${document}/${item.kind}/${item.id}`;
16903
16969
  }
16904
- var refGrammarProblem = "ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/message/<uuid>, dispatch://KEY-1/artifact/<slug>, " + "dispatch://PROJECT/artifact/<document-ref> (an artifact id, slug, or filename), or " + "dispatch://agent/<session id>/artifact/<slug> (a picture in a conversation on the Agents page, " + "for dispatch doc-read); a dashboard URL on this Dispatch server is accepted too";
16970
+ var refGrammarProblem = "ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/message/<uuid>, dispatch://KEY-1/artifact/<slug>, " + "dispatch://PROJECT/artifact/<document-ref> (an artifact id, slug, or filename), " + "dispatch://KEY-1/spec#b-<block id>, dispatch://KEY-1/artifact/<slug>#b-<block id> or " + "dispatch://PROJECT/artifact/<slug>#b-<block id> (one block of a document, its id " + "percent-encoded, optionally pinned to a version of the document with @v<N> after it; for " + "dispatch read), or " + "dispatch://agent/<session id>/artifact/<slug> (a picture in a conversation on the Agents page, " + "for dispatch doc-read); a dashboard URL on this Dispatch server is accepted too";
16905
16971
  var ownerRequiredProblem = "issue is required; supply issue or set LEGION_ISSUE";
16906
16972
  function innerRefProblem(tool, ref, refText) {
16907
- if (ref.kind !== "ask" && ref.kind !== "comment" && ref.kind !== "message" && ref.kind !== "log" && ref.kind !== "children") {
16973
+ if (ref.kind !== "ask" && ref.kind !== "comment" && ref.kind !== "message" && ref.kind !== "log" && ref.kind !== "children" && ref.kind !== "block") {
16908
16974
  return;
16909
16975
  }
16910
16976
  if (tool === "dispatch_read" || tool === "dispatch_ask")
16911
16977
  return;
16912
16978
  const owner = refOwnerName(ref);
16913
- const suggestTool = tool === "dispatch_suggest";
16914
- const ownerArguments = ref.owner.kind === "issue" ? `issue ${ref.owner.issue}${suggestTool ? " and artifact <the document's slug>" : ""}` : `project ${ref.owner.project} and artifact ${ref.artifact}`;
16979
+ const documentArgument = ref.kind === "block" && tool !== "dispatch_comment" ? ` and artifact ${ref.id}` : tool === "dispatch_suggest" ? " and artifact <the document's slug>" : "";
16980
+ const ownerArguments = ref.owner.kind === "issue" ? `issue ${ref.owner.issue}${documentArgument}` : `project ${ref.owner.project} and artifact ${ref.artifact}`;
16915
16981
  const fix = tool === "dispatch_comment" && ref.kind === "ask" ? `reply under it with reply_to_ask ${ref.id} and ${ownerArguments}` : tool === "dispatch_comment" && ref.kind === "comment" ? `reply in its thread with reply_to ${ref.id} and ${ownerArguments}` : `read it with dispatch read, or name ${owner} with ${ownerArguments}`;
16916
- const item = ref.kind === "ask" ? "an ask" : ref.kind === "log" ? "the event log" : ref.kind === "children" ? "the children" : `a ${ref.kind}`;
16982
+ const item = ref.kind === "ask" ? "an ask" : ref.kind === "log" ? "the event log" : ref.kind === "children" ? "the children" : ref.kind === "block" ? `block ${ref.block}` : `a ${ref.kind}`;
16917
16983
  return `ref ${refText} names ${item} on ${owner}; dispatch ${commandName(tool)} would act on ${owner} and drop the ${ref.kind}: ${fix}`;
16918
16984
  }
16919
16985
  var documentItemPattern = /^dispatch:\/\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)\/artifact\/[^/@]+(?:@v\d+)?\/(ask|comment)\/([^/]+)$/;
@@ -16940,7 +17006,7 @@ function ownerConflictProblems(tool, args, parsedRef, refText) {
16940
17006
  const artifact = optionalString(args, "artifact");
16941
17007
  const version2 = optionalNumber(args, "version");
16942
17008
  const ref = tool === "dispatch_ask" && (issue2 !== undefined || project !== undefined) ? null : parsedRef;
16943
- const refDocument = ref === null ? undefined : ref.owner.kind === "project" ? ref.artifact ?? ref.id : ref.kind === "spec" || ref.kind === "artifact" ? ref.id : undefined;
17009
+ const refDocument = ref === null ? undefined : ref.owner.kind === "project" ? ref.artifact ?? ref.id : ref.kind === "spec" || ref.kind === "artifact" || ref.kind === "block" ? ref.id : undefined;
16944
17010
  if (ref !== null && refText !== undefined) {
16945
17011
  const refOwner = refOwnerName(ref);
16946
17012
  if (issue2 !== undefined && (ref.owner.kind !== "issue" || nativeIssueKeyPattern.test(issue2) && issue2 !== ref.owner.issue)) {
@@ -16968,7 +17034,7 @@ function ownerConflictProblems(tool, args, parsedRef, refText) {
16968
17034
  }
16969
17035
  const projectOwned = project !== undefined || ref?.owner.kind === "project";
16970
17036
  if (tool === "dispatch_comment" && !projectOwned && optionalString(args, "quote") === undefined) {
16971
- const document = artifact ?? refDocument;
17037
+ const document = artifact ?? (ref?.kind === "block" ? undefined : refDocument);
16972
17038
  if (document !== undefined) {
16973
17039
  problems.push(`${command} posts on the issue unless quote anchors it in a document, so document ${document} would be dropped: add --quote to comment on a passage of it, or name only the issue`);
16974
17040
  }
@@ -17348,7 +17414,8 @@ function referenceLines(edges) {
17348
17414
  return ["- none"];
17349
17415
  return edges.map((edge) => {
17350
17416
  const excerpt2 = edge.excerpt === undefined ? "" : `${textHead(edge.excerpt.text)} \xB7 `;
17351
- return `- ${edge.kind} ${edge.node.kind} ${edge.node.ref ?? edge.node.id} (${excerpt2}${edge.created_at})`;
17417
+ const block = edge.block === undefined ? "" : ` (block ${edge.block.ref ?? edge.block.id})`;
17418
+ return `- ${edge.kind} ${edge.node.kind} ${edge.node.ref ?? edge.node.id} (${excerpt2}${edge.created_at})${block}`;
17352
17419
  });
17353
17420
  }
17354
17421
  function unavailableReason(error48) {
@@ -17373,8 +17440,30 @@ async function graphSections(client, ref) {
17373
17440
  graphEdges(client, { to: ref }),
17374
17441
  graphEdges(client, { from: ref })
17375
17442
  ]);
17443
+ return graphSectionLines(incoming, outgoing);
17444
+ }
17445
+ function graphSectionLines(incoming, outgoing) {
17376
17446
  return ["Referenced by:", ...referenceLines(incoming), "Links:", ...referenceLines(outgoing)];
17377
17447
  }
17448
+ function blockLines(node, ref) {
17449
+ const head = [
17450
+ `Block: ${node.block_id ?? ref.block}`,
17451
+ `Document: ${node.document ?? ref.document}`,
17452
+ ...node.changed_version === undefined ? [] : [`Changed in version: ${node.changed_version}`],
17453
+ ...node.text === undefined ? [] : ["Text:", node.text]
17454
+ ];
17455
+ const { pin } = node;
17456
+ if (pin === undefined)
17457
+ return head;
17458
+ const state = pin.state === "unchanged" ? `Unchanged since version ${pin.version}.` : pin.state === "changed" ? `Changed since version ${pin.version}; last changed in version ${node.changed_version}.` : `Removed in version ${pin.removed_version}.`;
17459
+ return [
17460
+ ...head,
17461
+ `Pinned to version: ${pin.version}`,
17462
+ state,
17463
+ `Text at version ${pin.version}:`,
17464
+ pin.text
17465
+ ];
17466
+ }
17378
17467
  function logSummary(issue2, events) {
17379
17468
  return [
17380
17469
  `Key: ${issue2.key}`,
@@ -18740,6 +18829,30 @@ ${trailer.join(`
18740
18829
  ...showImages(pictures3)
18741
18830
  };
18742
18831
  }
18832
+ if (ownerArguments.ref?.kind === "block") {
18833
+ const ref = ownerArguments.ref;
18834
+ const blockRef = stringArg(args, "ref");
18835
+ const [incoming, outgoing] = await Promise.all([
18836
+ client.getReferences({ to: blockRef }).catch((error48) => {
18837
+ if (ref.pin === undefined && dispatchAnswered(error48, 404)) {
18838
+ throw new Error(`No block ${ref.block} in ${ref.document}.`);
18839
+ }
18840
+ throw error48;
18841
+ }),
18842
+ graphEdges(client, { from: blockRef })
18843
+ ]);
18844
+ return {
18845
+ text: [
18846
+ ...blockLines(incoming.node, ref),
18847
+ ...graphSectionLines(incoming.edges, outgoing)
18848
+ ].join(`
18849
+ `),
18850
+ details: {
18851
+ ...ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: ref.owner.issue },
18852
+ block: incoming.node.block_id ?? ref.block
18853
+ }
18854
+ };
18855
+ }
18743
18856
  const documentReference = optionalString(args, "artifact");
18744
18857
  if (documentOwner().kind === "project" || documentReference !== undefined) {
18745
18858
  const resolved = await resolveDocument(documentOwner(), documentReference);
package/dist/envoy.js CHANGED
@@ -29899,6 +29899,38 @@ function capAgentStreamText(text, limit) {
29899
29899
  return text;
29900
29900
  return text.slice(0, limit) + AGENT_STREAM_TRUNCATION_SUFFIX;
29901
29901
  }
29902
+ // ../contracts/src/dispatch-href.ts
29903
+ function hasControlCharacter(value) {
29904
+ return /\p{Cc}/u.test(value);
29905
+ }
29906
+
29907
+ // ../contracts/src/dispatch-block-ref.ts
29908
+ var encoder = new TextEncoder;
29909
+ function decodeBlockId(encoded) {
29910
+ if (encoded === "" || encoded.includes("@")) {
29911
+ return;
29912
+ }
29913
+ let id;
29914
+ try {
29915
+ id = decodeURIComponent(encoded);
29916
+ } catch {
29917
+ return;
29918
+ }
29919
+ return id === "" || hasControlCharacter(id) ? undefined : id;
29920
+ }
29921
+ var MAX_BLOCK_PIN = 9223372036854775807n;
29922
+ function parseBlockFragment(encoded) {
29923
+ const at = encoded.indexOf("@");
29924
+ const pin = at === -1 ? undefined : encoded.slice(at + 1).match(/^v([1-9][0-9]*)$/)?.[1];
29925
+ if (at !== -1 && (pin === undefined || BigInt(pin) > MAX_BLOCK_PIN)) {
29926
+ return;
29927
+ }
29928
+ const block = decodeBlockId(at === -1 ? encoded : encoded.slice(0, at));
29929
+ if (block === undefined) {
29930
+ return;
29931
+ }
29932
+ return pin === undefined ? { block } : { block, pin };
29933
+ }
29902
29934
  // ../contracts/src/dispatch-text-rules.ts
29903
29935
  var SESSION_ID_PATTERN = "[^/?#\\s\\p{Z}\\p{Cc}<>\"'`\\[\\]|]+";
29904
29936
  var sessionIdOnly = new RegExp(`^${SESSION_ID_PATTERN}$`, "u");
@@ -30118,7 +30150,7 @@ var dispatchToolSpecs = [
30118
30150
  issue: z2.string().describe(ISSUE_REFERENCE).optional(),
30119
30151
  project: z2.string().describe("Project key owning the document.").optional(),
30120
30152
  artifact: z2.string().describe("Project document artifact id, slug, or filename.").optional(),
30121
- ref: z2.string().describe("Optional dispatch:// reference (issue, document, message, or ask); appended to the question and rendered as a link.").optional(),
30153
+ ref: z2.string().describe("Optional dispatch:// reference (issue, document, block, message, or ask); appended to the question and rendered as a link.").optional(),
30122
30154
  question: z2.string({ max: ASK_QUESTION_MAX }).describe(`${ASK_QUESTION_CONTRACT} At most ${ASK_QUESTION_MAX} characters.`),
30123
30155
  options: z2.array(z2.object({
30124
30156
  label: z2.string().describe("Selectable option label."),
@@ -30263,7 +30295,7 @@ var dispatchToolSpecs = [
30263
30295
  ops: [{ op: "delete_column", block: "table-123", index: 1 }],
30264
30296
  precondition: { blocks: [{ id: "table-123", token: "sha256:current-table-token" }] }
30265
30297
  },
30266
- 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. " + "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. " + `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}`,
30298
+ 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. " + "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. " + "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}`,
30267
30299
  arguments: (z2) => ({
30268
30300
  issue: z2.string().describe(ISSUE_REFERENCE).optional(),
30269
30301
  project: z2.string().describe("Project key owning the document.").optional(),
@@ -30343,12 +30375,12 @@ var dispatchToolSpecs = [
30343
30375
  {
30344
30376
  name: "dispatch_read",
30345
30377
  example: { issue: "DSP-1" },
30346
- description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + `An issue read, and its dispatch://KEY/log, lists the issue's last ${DEFAULT_ISSUE_READ_EVENTS} events, oldest first; ` + "--events N lists the last N, and --all-events every one. " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
30378
+ description: "Read an issue or document summary, targeted ask, or targeted comment reply chain, or the conversation " + "a message belongs to. Do not use it for document contents; use dispatch doc-read instead. Supply ref, issue, " + "issue plus artifact (one of its documents), or project plus artifact; or message alone, which reads a human's direct message to this session and every " + "reply to it (they belong to no issue). A document summary names its issue, reference, versions and approval. " + "An anchored comment or ask also says where its quote sits, as `Position:`: the block's path from the top, " + "and in a table the row (0 is the header), the cells before the anchored one, and the column's header; " + "`Position: unavailable (<code>)` when Dispatch could not read the document: `DOC_SERVICE_UNAVAILABLE` " + "(try again shortly), `DOC_SCHEMA` (the document needs repair), `DOCUMENT_UNLOADABLE` (the document " + "needs a rebuild) or `INTERNAL`. " + "An issue read carries a `Progress:` line, `tasks 3/7, children 2/5`: its spec's task-list items " + "(`- [ ]` / `- [x]`, nested lists included) and its direct children, each done of total and each only " + "when it has any (`Progress: none` otherwise). " + `An issue read, and its dispatch://KEY/log, lists the issue's last ${DEFAULT_ISSUE_READ_EVENTS} events, oldest first; ` + "--events N lists the last N, and --all-events every one. " + "Every read ends with `Referenced by:` (what cites or hangs off this node, each with its dispatch:// address, " + "an excerpt, and when) and `Links:` (what it cites), so tracing provenance is one call. " + "A block read prints `Block:`, `Document:`, `Changed in version:` and `Text:`, then those two sections; a pinned one adds " + "the block's text at that version and whether it is unchanged, changed or removed since, and an absent block, unpinned, " + "reads `No block <id> in <document>.` " + "The pictures the shown messages, asks and comments embed come back as images you see, newest first, at most 8 " + "and 10 MiB of them per read, each a PNG, JPEG, GIF or WebP of at most 3,750,000 bytes (5 MB of base64); a `Pictures:` section names each " + "one shown, in order, and the rest by reference, for dispatch doc-read. A picture this session was already shown is named, not sent again " + "(every request carries the session's history, and the provider refuses one over 32 MB); dispatch doc-read shows it again. " + OWNER_REFERENCE,
30347
30379
  arguments: (z2) => ({
30348
30380
  issue: z2.string().describe(ISSUE_REFERENCE).optional(),
30349
30381
  project: z2.string().describe("Project key owning the document.").optional(),
30350
30382
  artifact: z2.string().describe("Document artifact id, slug, or filename: one of the issue's, or a project document.").optional(),
30351
- ref: z2.string().describe("Optional dispatch:// reference: dispatch://KEY, dispatch://KEY/spec, " + "dispatch://KEY/artifact/<slug>[@vN], dispatch://KEY/ask/<id>, dispatch://KEY/comment/<id>, " + "dispatch://KEY/message/<id>, dispatch://PROJECT/artifact/<slug>[@vN], and its " + "/ask/<id> and /comment/<id>; or the dashboard URL of one.").optional(),
30383
+ ref: z2.string().describe("Optional dispatch:// reference: dispatch://KEY, dispatch://KEY/spec, " + "dispatch://KEY/artifact/<slug>[@vN], dispatch://KEY/ask/<id>, dispatch://KEY/comment/<id>, " + "dispatch://KEY/message/<id>, dispatch://PROJECT/artifact/<slug>[@vN], and its " + "/ask/<id> and /comment/<id>; or the dashboard URL of one. A block: " + "dispatch://KEY/spec#b-<block id>[@vN], dispatch://KEY/artifact/<slug>#b-<block id>[@vN] or " + "dispatch://PROJECT/artifact/<slug>#b-<block id>[@vN], the id percent-encoded except ASCII " + "letters, digits and -.").optional(),
30352
30384
  message: z2.string().describe("A message id (uuid): reads the conversation it belongs to, the root message and every " + "reply. Name nothing else with it.").optional(),
30353
30385
  events: z2.number({ int: true, min: 1 }).describe(`How many of the issue's newest events an issue read or its dispatch://KEY/log lists, oldest first; default ${DEFAULT_ISSUE_READ_EVENTS}. Name no --all-events with it.`).optional(),
30354
30386
  all_events: z2.boolean().describe(`List every one of the issue's events, oldest first, on an issue read or its dispatch://KEY/log, in place of the last ${DEFAULT_ISSUE_READ_EVENTS}. Name no --events with it.`).optional()
@@ -31355,7 +31387,27 @@ function dispatchDocumentRef(owner, slug) {
31355
31387
  function dispatchChildRef(ownerRef, kind, id) {
31356
31388
  return `${ownerRef}/${kind}/${id}`;
31357
31389
  }
31390
+ function parseBlockRef(document, fragment) {
31391
+ const target = parseBlockFragment(fragment);
31392
+ const parsed = parseDispatchRef(document);
31393
+ if (target === undefined || parsed === null || parsed.version !== undefined || parsed.kind !== "spec" && parsed.kind !== "artifact") {
31394
+ return null;
31395
+ }
31396
+ return {
31397
+ owner: parsed.owner,
31398
+ kind: "block",
31399
+ id: parsed.id,
31400
+ block: target.block,
31401
+ document,
31402
+ ...parsed.owner.kind === "project" ? { artifact: parsed.id } : {},
31403
+ ...target.pin === undefined ? {} : { pin: target.pin }
31404
+ };
31405
+ }
31358
31406
  function parseDispatchRef(ref) {
31407
+ const hash2 = ref.indexOf("#");
31408
+ if (hash2 !== -1 && ref.startsWith("b-", hash2 + 1)) {
31409
+ return parseBlockRef(ref.slice(0, hash2), ref.slice(hash2 + 3));
31410
+ }
31359
31411
  const projectDocument = ref.match(/^dispatch:\/\/([A-Z][A-Z0-9]{1,9})\/artifact\/([^/@]+)(?:@v(\d+))?(?:\/(ask|comment)\/([^/]+))?$/);
31360
31412
  if (projectDocument) {
31361
31413
  const [, project, artifact2, version3, targetKind, targetID] = projectDocument;
@@ -33579,7 +33631,7 @@ function subscriptionRemovedTopics(raw, sessionID) {
33579
33631
 
33580
33632
  // ../envoy-client/src/dispatch-execute.ts
33581
33633
  var triageAdviceShown = new Set;
33582
- var refGrammarProblem = "ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/message/<uuid>, dispatch://KEY-1/artifact/<slug>, " + "dispatch://PROJECT/artifact/<document-ref> (an artifact id, slug, or filename), or " + "dispatch://agent/<session id>/artifact/<slug> (a picture in a conversation on the Agents page, " + "for dispatch doc-read); a dashboard URL on this Dispatch server is accepted too";
33634
+ var refGrammarProblem = "ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/message/<uuid>, dispatch://KEY-1/artifact/<slug>, " + "dispatch://PROJECT/artifact/<document-ref> (an artifact id, slug, or filename), " + "dispatch://KEY-1/spec#b-<block id>, dispatch://KEY-1/artifact/<slug>#b-<block id> or " + "dispatch://PROJECT/artifact/<slug>#b-<block id> (one block of a document, its id " + "percent-encoded, optionally pinned to a version of the document with @v<N> after it; for " + "dispatch read), or " + "dispatch://agent/<session id>/artifact/<slug> (a picture in a conversation on the Agents page, " + "for dispatch doc-read); a dashboard URL on this Dispatch server is accepted too";
33583
33635
  var toolSchemas = new Map;
33584
33636
  function asObject(value) {
33585
33637
  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
@@ -34683,7 +34735,7 @@ var BLANK_LINE = /^[ \t]*$/;
34683
34735
  var REFUSED_UNQUOTED = "\n;&|$`<>()#\\";
34684
34736
  var REFUSED_DOUBLE_QUOTED = "$`\\";
34685
34737
  function dispatchCommandHead(command) {
34686
- if (typeof command !== "string" || hasControlCharacter(command))
34738
+ if (typeof command !== "string" || hasControlCharacter2(command))
34687
34739
  return;
34688
34740
  const all = command.split(`
34689
34741
  `);
@@ -34710,7 +34762,7 @@ function dispatchCommandHead(command) {
34710
34762
  function firstWord(head) {
34711
34763
  return head.split(/[ \t]/, 1)[0] ?? "";
34712
34764
  }
34713
- function hasControlCharacter(text) {
34765
+ function hasControlCharacter2(text) {
34714
34766
  for (let index = 0;index < text.length; index += 1) {
34715
34767
  const code = text.charCodeAt(index);
34716
34768
  if (code < 32 && code !== 10 && code !== 9 || code === 127)
@@ -34807,10 +34859,10 @@ import { logger as logger3, procmgr, VERSION } from "@oh-my-pi/pi-utils";
34807
34859
  var import_nats2 = __toESM(require_mod4(), 1);
34808
34860
 
34809
34861
  // src/agent-stream.ts
34810
- var encoder = new TextEncoder;
34862
+ var encoder2 = new TextEncoder;
34811
34863
  var REPLAY_ARRAY_BYTES = 2;
34812
34864
  function jsonBytes(value) {
34813
- return encoder.encode(JSON.stringify(value)).length;
34865
+ return encoder2.encode(JSON.stringify(value)).length;
34814
34866
  }
34815
34867
  var SEQ_PER_MS = 1000;
34816
34868
  function modelReference(provider, id) {
@@ -7,14 +7,14 @@ description: "Use before your first dispatch command in a session: a message, co
7
7
 
8
8
  Dispatch is a record for the people who decide, never a log of your work.
9
9
 
10
- - Use the `dispatch` command; the HTTP API only for what no command does. `dispatch <command> --help` gives each command's rules and an example.
10
+ - Use the `dispatch` command; the HTTP API only for what no command does. `dispatch <command> --help` gives its rules and an example.
11
11
  - Put long text on stdin: `--<field>-file -` with a quoted here-document (`<<'EOF'`). Give object and list fields as JSON.
12
12
  - Exit 1 is a refusal, 2 a usage error. A refusal lists each problem: fix them all, then call once.
13
- - `DOC_SERVICE_UNAVAILABLE` means the document is reloading and nothing was written. Wait a few seconds and repeat the call.
13
+ - `DOC_SERVICE_UNAVAILABLE`: the document is reloading, nothing was written; retry in a few seconds.
14
14
 
15
15
  ## Asks and ask blocks
16
16
 
17
- - A question about a design a document records is an ask block (a decision block) at the end of its section, at each phase:
17
+ - A design question a document records is an ask block (a decision block) at the end of its section, at each phase:
18
18
 
19
19
  ```md
20
20
  :::ask{urgency="med"}
@@ -30,37 +30,37 @@ The problem and why it matters. Recommendation: the option and its reason.
30
30
  - An open ask is the request. Do not raise it again in each message.
31
31
  - Change an open ask's block with `dispatch edit-ask`, or `doc-edit`'s `replace` or `move`. An answered ask is fixed: ask anew.
32
32
  - Answer a person's reply to an open ask with `dispatch comment --reply-to-ask`; `--turn agent` for a note that needs nothing from them.
33
- - When an answer's option and text disagree, the text is the answer.
33
+ - When an answer's option and text disagree, the text wins.
34
34
  - An ask block has a block id, for `doc-edit`, and an ask id, for the ask commands. `dispatch read --ref dispatch://KEY/ask/<id>` takes either.
35
35
  - An ask reaches the issue's assignee. On an unassigned issue, name who must answer.
36
36
 
37
37
  ## Choosing what to work on
38
38
 
39
- - When you finish an issue, take the top ready issue: status `todo`, by priority and then board rank, in each project.
40
- - `todo` means specced and waiting on nothing. An issue that waits goes in `backlog`, saying on what.
39
+ - When you finish an issue, take the top ready one: `todo`, by priority then board rank, per project.
40
+ - `todo` means specced and waiting on nothing; one that waits goes in `backlog`, saying on what.
41
41
  - Hold at most three issues in flight; move the rest to `backlog`, saying where each is.
42
42
  - Never reorder the board: one agent keeps each project's order (`issue-update --before`/`--after`). If the top looks wrong, tell `notifications.role.legion-<project>-controller`.
43
43
 
44
44
  ## Issue status is yours to move
45
45
 
46
- Outside Legion, claim your issue (`dispatch claim`) and move it and your children: `in_progress` at implementation, `testing` on a production-like surface, `needs_review` while its PR waits, and `done` with `--reason` once you drove it in production. Never write the status of an issue with the `legion` label, or under one.
46
+ Outside Legion, claim your issue (`dispatch claim`) and move it and your children: `in_progress` at implementation, `testing` on a production-like surface, `needs_review` while its PR waits, `done` with `--reason` once driven in production. An issue with the `legion` label, or under one: never write its status, and claim it only as a Legion role of its tree, even when its claim reads `· not running`, as a suspended architect's does: taking it takes the tree out of the workflow.
47
47
 
48
- A claim delivers no comments: in the same turn, `dispatch issue-update --route session:<your id>` (clear with `--route ''` on release) or `envoy_subscribe notifications.dispatch.issue.<KEY>.>`. Never route such an issue.
48
+ A claim delivers no comments: that turn, `dispatch issue-update --route session:<your id>` (`--route ''` on release) or `envoy_subscribe notifications.dispatch.issue.<KEY>.>`. Never route such an issue.
49
49
 
50
50
  ## Close what you opened
51
51
 
52
- - An ask you opened is yours until it is answered or resolved. When the answer comes another way, or the design makes it moot, `dispatch resolve-ask` it in the same turn.
52
+ - An ask you opened is yours until answered or resolved. If it is answered another way or made moot, `dispatch resolve-ask` it that turn.
53
53
  - Resolve each open ask a later write names that is no longer needed; retract one a new ask replaces.
54
54
 
55
55
  ## Structure over stream
56
56
 
57
57
  - One issue per deliverable, its content the issue's document. Decisions are asks. A message only announces.
58
- - A message replies to a person, or tells them a change they must know now.
59
- - Text a person must read to decide is a section of the spec. An artifact is a real file.
58
+ - A message replies to a person or tells them what they must know now.
59
+ - Text a person must read to decide belongs in the spec. An artifact is a real file.
60
60
 
61
61
  ## Architecture components
62
62
 
63
- Attach each architectural issue to its components (`--components-json`), the root before you decompose it. Change code and `.dispatch/architecture/<id>.md` in the same review.
63
+ Attach each architectural issue to its components (`--components-json`), the root before decomposing it. Change code and `.dispatch/architecture/<id>.md` in the same review.
64
64
 
65
65
  ## References
66
66
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "11.1.0",
3
+ "version": "11.2.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {