@sjawhar/pi-envoy 15.0.3 → 15.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -313,7 +313,12 @@ reviews these calls:
313
313
  Every other Dispatch command is outside the gate, and its text posts unreviewed: among them
314
314
  `dispatch issue-update --reason`, `dispatch resolve-ask --reason` and `dispatch suggest`.
315
315
 
316
- The gate reads the arguments from the command's own `--dry-run`. An upload that reads its name
316
+ The gate reads the arguments from the command's own `--dry-run`. The dry run sends nothing and
317
+ contacts no Dispatch server, so a slow one most likely means a busy machine. The reads, the dry
318
+ run and the `cd`'s `pwd -P` probe, take at most half the call's deadline: the first run of each
319
+ is cut at 20 s, or sooner when that half ends sooner, and a run cut there is run once more with
320
+ what is left of that half (25 s at the 90 s default), when at least 2 s of it is left. The
321
+ review keeps the other half. An upload that reads its name
317
322
  from a file (`--name-file`) is decided from the name the dry run prints. `--path-file` is refused:
318
323
  its content names a file the gate does not read before Dispatch opens it. An upload whose name or
319
324
  path holds an expansion (`"$NAME"`) is outside the form the gate reads. The gate reads each file
@@ -558,7 +563,7 @@ why. The note reaches a headless session too:
558
563
  | Outcome | What happened |
559
564
  | --- | --- |
560
565
  | `timeout` | the review did not answer within its deadline |
561
- | `error` | the review failed: a model error, a handler exception, or a dry run that failed |
566
+ | `error` | the review failed: a model error, a handler exception, or a dry run that failed; a dry run that timed out twice, or once with no time left to run it again, gets a note that the machine was busy and that the agent should read back what the write posted |
562
567
  | `no-verdict` | the model answered with no verdict the gate could read |
563
568
  | `halted` | three calls in a row reached no verdict, and the gate is paused for the session |
564
569
  | `skipped` | the session's main model is on another provider than the gate's |
package/dist/dispatch.js CHANGED
@@ -14611,8 +14611,13 @@ var askEventPayloadFields = {
14611
14611
  opened_event_id: number2().int().positive(),
14612
14612
  kind: string2().optional(),
14613
14613
  question: string2().optional(),
14614
- options: array(object({ label: string2().optional() })).optional(),
14615
- answer: object({ selected: array(string2()).nullish(), text: string2().nullish() }).nullish(),
14614
+ options: array(object({ id: string2().optional(), label: string2().optional() })).optional(),
14615
+ revision: number2().int().positive().optional(),
14616
+ answer: object({
14617
+ id: string2().optional(),
14618
+ selected: array(string2()).nullish(),
14619
+ text: string2().nullish()
14620
+ }).nullish(),
14616
14621
  previous_answer: object({
14617
14622
  user: string2().optional(),
14618
14623
  selected: array(string2()).nullish(),
@@ -15220,8 +15225,8 @@ var dispatchToolSpecs = [
15220
15225
  quote: z.string().describe("Optional exact quoted document text.").optional(),
15221
15226
  occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional(),
15222
15227
  body: z.string({ max: DISPATCH_BODY_MAX }).describe(`Review comment, at most ${DISPATCH_BODY_MAX} characters.`),
15223
- reply_to: z.string().describe("A comment id (uuid); replying to any comment in a thread continues that thread (an " + "ask's clarification thread included). A block reference to one block of the comment " + "(dispatch://KEY/comment/<id>#b-<block id>) replies to that comment and names the " + "passage the reply answers. To reply to an ask, use reply_to_ask with the " + "ask id instead.").optional(),
15224
- reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional(),
15228
+ reply_to: z.string().describe("A comment id (uuid); replying to any comment in a thread continues that thread (an " + "ask's clarification thread included). A block reference to one block of the comment " + "(dispatch://KEY/comment/<id>#b-<block id>) replies to that comment and names the " + "passage the reply answers. To reply to an ask, use reply_to_ask with the ask id, or " + "with a reference to one of its parts, instead.").optional(),
15229
+ reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. A block " + "reference to one part of the ask (dispatch://KEY/ask/<id>#b-<part id>, the id an " + "option or the answer carries) threads under that ask and names the part the reply " + "answers. Mutually exclusive with reply_to.").optional(),
15225
15230
  turn: z.enum(["agent", "human"]).describe("Only with reply_to_ask: who holds the turn after this reply. agent: a progress note - " + "you keep the turn and the ask stays 'Waiting on agents' for the human; human (default): " + "you need the human to act - the ask returns to 'Waiting on you'.").optional(),
15226
15231
  images: imagesArgument(z, "the issue (or the project document's project)", `the ${DISPATCH_BODY_MAX}-character body limit`)
15227
15232
  }),
@@ -15548,7 +15553,7 @@ var ISSUE_KEY = `${PROJECT_KEY}-[1-9][0-9]*`;
15548
15553
  var DOCUMENT_SLUG = "[a-z0-9]+(?:-[a-z0-9]+)*";
15549
15554
  var ISSUE_KEY_ONLY = new RegExp(`^${ISSUE_KEY}$`);
15550
15555
  var BLOCK_REFERENCE = new RegExp(`^dispatch://(?:(${ISSUE_KEY})/spec|(${ISSUE_KEY}|${PROJECT_KEY})/artifact/(${DOCUMENT_SLUG}))#b-(.*)$`, "s");
15551
- var ITEM_BLOCK_REFERENCE = new RegExp(`^dispatch://(?:${ISSUE_KEY}/(comment|message)|${PROJECT_KEY}/artifact/${DOCUMENT_SLUG}/(comment))/([^/?#]+)#b-(.*)$`, "s");
15556
+ var ITEM_BLOCK_REFERENCE = new RegExp(`^dispatch://(?:${ISSUE_KEY}/(ask|comment|message)|${PROJECT_KEY}/artifact/${DOCUMENT_SLUG}/(ask|comment))/([^/?#]+)#b-(.*)$`, "s");
15552
15557
  var atIdBound = `dispatch://CORE-1/spec#b-${"x".repeat(MAX_BLOCK_ID_BYTES)}`;
15553
15558
  var DISPATCH_BLOCK_POINTER_VALUES = [
15554
15559
  {
@@ -15648,25 +15653,55 @@ var DISPATCH_BLOCK_POINTER_VALUES = [
15648
15653
  value: "dispatch://CORE-1/comment/11111111-1111-4111-8111-111111111111#b-b2",
15649
15654
  ok: false,
15650
15655
  why: "a block of an issue's comment",
15651
- problem: "a block[] attribute points only at a block of a document"
15656
+ problem: "is a block of a comment: a block[] attribute points only at a block of a document"
15652
15657
  },
15653
15658
  {
15654
15659
  value: "dispatch://CORE-1/comment/11111111-1111-4111-8111-111111111111#b-b2@v1",
15655
15660
  ok: false,
15656
15661
  why: "a block of a revision of an issue's comment",
15657
- problem: "a block[] attribute points only at a block of a document"
15662
+ problem: "is a block of a comment: a block[] attribute points only at a block of a document"
15658
15663
  },
15659
15664
  {
15660
15665
  value: "dispatch://CORE/artifact/handbook-md/comment/88888888-8888-4888-8888-888888888888#b-b2",
15661
15666
  ok: false,
15662
15667
  why: "a block of a project document's comment",
15663
- problem: "a block[] attribute points only at a block of a document"
15668
+ problem: "is a block of a comment: a block[] attribute points only at a block of a document"
15664
15669
  },
15665
15670
  {
15666
15671
  value: "dispatch://CORE-1/message/33333333-3333-4333-8333-333333333333#b-b2",
15667
15672
  ok: false,
15668
15673
  why: "a block of an issue message",
15669
- problem: "a block[] attribute points only at a block of a document"
15674
+ problem: "is a block of a message: a block[] attribute points only at a block of a document"
15675
+ },
15676
+ {
15677
+ value: "dispatch://CORE-1/ask/22222222-2222-4222-8222-222222222222#b-b2",
15678
+ ok: false,
15679
+ why: "a part of an issue's ask",
15680
+ problem: "is a block of an ask: a block[] attribute points only at a block of a document"
15681
+ },
15682
+ {
15683
+ value: "dispatch://CORE-1/ask/22222222-2222-4222-8222-222222222222#b-b2@v1",
15684
+ ok: false,
15685
+ why: "a part of a revision of an issue's ask",
15686
+ problem: "is a block of an ask: a block[] attribute points only at a block of a document"
15687
+ },
15688
+ {
15689
+ value: "dispatch://CORE/artifact/handbook-md/ask/99999999-9999-4999-8999-999999999999#b-b2",
15690
+ ok: false,
15691
+ why: "a part of a project document's ask",
15692
+ problem: "is a block of an ask: a block[] attribute points only at a block of a document"
15693
+ },
15694
+ {
15695
+ value: "dispatch://CORE/artifact/handbook-md/ask/99999999-9999-4999-8999-999999999999#b-b2@v1",
15696
+ ok: false,
15697
+ why: "a part of a revision of a project document's ask",
15698
+ problem: "is a block of an ask: a block[] attribute points only at a block of a document"
15699
+ },
15700
+ {
15701
+ value: "dispatch://CORE-1/artifact/notes-md/ask/a1#b-b2",
15702
+ ok: false,
15703
+ why: "an issue document's ask, a shape no reference has",
15704
+ problem: "is not a block reference as Dispatch writes one"
15670
15705
  },
15671
15706
  {
15672
15707
  value: "dispatch://CORE-1/artifact/notes-md/comment/c1#b-x",
@@ -15684,7 +15719,7 @@ var DISPATCH_BLOCK_POINTER_VALUES = [
15684
15719
  value: "dispatch://CORE-1/spec#b-x dispatch://CORE-1/message/33333333-3333-4333-8333-333333333333#b-b2",
15685
15720
  ok: false,
15686
15721
  why: "a document's block, then an issue message's",
15687
- problem: "a block[] attribute points only at a block of a document"
15722
+ problem: "is a block of a message: a block[] attribute points only at a block of a document"
15688
15723
  }
15689
15724
  ];
15690
15725
  var TYPED_BLOCK_ID_SHORTCUT_EXCLUDED = `
@@ -17439,6 +17474,7 @@ function dispatchIssueRef(key) {
17439
17474
  function dispatchDocumentRef(owner, slug) {
17440
17475
  return `dispatch://${owner}/artifact/${slug}`;
17441
17476
  }
17477
+ var ITEM_KINDS = ["ask", "comment", "message"];
17442
17478
  function dispatchChildRef(ownerRef, kind, id) {
17443
17479
  return `${ownerRef}/${kind}/${id}`;
17444
17480
  }
@@ -17450,7 +17486,7 @@ function parseBlockRef(holder, fragment) {
17450
17486
  }
17451
17487
  const pin = target.pin === undefined ? {} : { pin: target.pin };
17452
17488
  const artifact = parsed.artifact === undefined ? {} : { artifact: parsed.artifact };
17453
- if (parsed.kind === "comment" || parsed.kind === "message" && target.pin === undefined) {
17489
+ if (parsed.kind === "ask" || parsed.kind === "comment" || parsed.kind === "message" && target.pin === undefined) {
17454
17490
  return {
17455
17491
  owner: parsed.owner,
17456
17492
  kind: "block",
@@ -18612,18 +18648,23 @@ function itemBlockOf(value) {
18612
18648
  const ref = parseDispatchRef(value);
18613
18649
  return ref?.item === undefined || ref.block === undefined ? undefined : { ...ref, item: ref.item, block: ref.block };
18614
18650
  }
18651
+ function article(kind) {
18652
+ return kind === "ask" ? "an ask" : `a ${kind}`;
18653
+ }
18615
18654
  function replyBlockProblem(field, kind, value) {
18616
18655
  if (!/^dispatch:\/\/[^#]*#b-/.test(value))
18617
18656
  return;
18618
18657
  const form = `dispatch://KEY/${kind}/<id>#b-<block id>`;
18619
18658
  const ref = parseDispatchRef(value);
18620
18659
  if (ref?.kind !== "block") {
18621
- return `${field} ${value} names no block; a block of a ${kind} reads ${form}`;
18660
+ return `${field} ${value} names no block; a block of ${article(kind)} reads ${form}`;
18622
18661
  }
18623
18662
  const other = ref.item?.kind;
18624
18663
  if (other !== kind) {
18625
- const answer = other === "comment" ? `; answer it with ${commandLine("dispatch_comment", { reply_to: value })}` : other === "message" ? `; answer it with ${commandLine("dispatch_message", { in_reply_to: value })}` : "";
18626
- return `${field} ${value} names a block of ${other === undefined ? "a document" : `a ${other}`}, but a ${kind} reply answers a block of a ${kind} (${form})${answer}`;
18664
+ const answer = other === "comment" ? `; answer it with ${commandLine("dispatch_comment", { reply_to: value })}` : other === "message" ? `; answer it with ${commandLine("dispatch_message", { in_reply_to: value })}` : other === "ask" ? `; answer it with ${commandLine("dispatch_comment", { reply_to_ask: value })}` : "";
18665
+ const named = other === undefined ? "a document" : article(other);
18666
+ const answers = kind === "ask" ? "reply_to_ask answers a part of the ask it names" : `${article(kind)} reply answers a block of ${article(kind)}`;
18667
+ return `${field} ${value} names a block of ${named}, but ${answers} (${form})${answer}`;
18627
18668
  }
18628
18669
  if (ref.pin !== undefined) {
18629
18670
  return `${field} ${value} names revision ${ref.pin} of the block, but a reply answers the block whatever its text becomes: drop @v${ref.pin}`;
@@ -18747,8 +18788,8 @@ function messageInReplyTo(args) {
18747
18788
  const id = messageIdOf(block?.item.id ?? inReplyTo);
18748
18789
  return id === undefined ? undefined : { id, ...block === undefined ? {} : { block: block.block } };
18749
18790
  }
18750
- function commentReplyTo(args) {
18751
- const replyTo = optionalString(args, "reply_to");
18791
+ function itemReplyTo(args, field) {
18792
+ const replyTo = optionalString(args, field);
18752
18793
  if (replyTo === undefined)
18753
18794
  return;
18754
18795
  const block = itemBlockOf(replyTo);
@@ -18788,12 +18829,17 @@ function argumentProblems(tool, args) {
18788
18829
  problems.push("artifact is required when quote is supplied");
18789
18830
  }
18790
18831
  const replyTo = optionalString(args, "reply_to");
18791
- if (replyTo !== undefined && optionalString(args, "reply_to_ask") !== undefined) {
18832
+ const replyToAsk = optionalString(args, "reply_to_ask");
18833
+ if (replyTo !== undefined && replyToAsk !== undefined) {
18792
18834
  problems.push("reply_to and reply_to_ask cannot both be set");
18793
18835
  }
18794
- const replyBlock = replyTo === undefined ? undefined : replyBlockProblem("reply_to", "comment", replyTo);
18795
- if (replyBlock !== undefined)
18796
- problems.push(replyBlock);
18836
+ for (const problem of [
18837
+ replyTo === undefined ? undefined : replyBlockProblem("reply_to", "comment", replyTo),
18838
+ replyToAsk === undefined ? undefined : replyBlockProblem("reply_to_ask", "ask", replyToAsk)
18839
+ ]) {
18840
+ if (problem !== undefined)
18841
+ problems.push(problem);
18842
+ }
18797
18843
  break;
18798
18844
  }
18799
18845
  case "dispatch_message": {
@@ -18905,7 +18951,7 @@ function dispatchRefFromUrl(value, serverUrl) {
18905
18951
  return `dispatch://${key}/artifact/${slug}${version}${blockOf("v")}`;
18906
18952
  }
18907
18953
  if (ask !== undefined)
18908
- return `dispatch://${key}/ask/${ask}`;
18954
+ return `dispatch://${key}/ask/${ask}${blockOf()}`;
18909
18955
  if (comment !== undefined)
18910
18956
  return `dispatch://${key}/comment/${comment}${blockOf()}`;
18911
18957
  if (message !== undefined)
@@ -18932,7 +18978,7 @@ function dispatchRefFromUrl(value, serverUrl) {
18932
18978
  return;
18933
18979
  return item === undefined ? `${document}${versionOf("version")}${blockOf("version")}` : `${document}/${item.kind}/${item.id}`;
18934
18980
  }
18935
- 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), dispatch://KEY-1/comment/<uuid>#b-<block id>, " + "dispatch://PROJECT/artifact/<slug>/comment/<uuid>#b-<block id> or " + "dispatch://KEY-1/message/<uuid>#b-<block id> (one block of a comment or message, a " + "comment's optionally pinned to a revision of the comment 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";
18981
+ 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), dispatch://KEY-1/ask/<uuid>#b-<part id> or " + "dispatch://PROJECT/artifact/<slug>/ask/<uuid>#b-<part id> (one part of an ask: its question, " + "one of its options or its answer, optionally pinned to a revision of the ask's parts with " + "@v<N> after it; for dispatch read), dispatch://KEY-1/comment/<uuid>#b-<block id>, " + "dispatch://PROJECT/artifact/<slug>/comment/<uuid>#b-<block id> or " + "dispatch://KEY-1/message/<uuid>#b-<block id> (one block of a comment or message, a " + "comment's optionally pinned to a revision of the comment 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";
18936
18982
  var ownerRequiredProblem = "issue is required; supply issue or set LEGION_ISSUE";
18937
18983
  function innerRefProblem(tool, ref, refText) {
18938
18984
  if (ref.kind !== "ask" && ref.kind !== "comment" && ref.kind !== "message" && ref.kind !== "log" && ref.kind !== "children" && ref.kind !== "block") {
@@ -18944,8 +18990,9 @@ function innerRefProblem(tool, ref, refText) {
18944
18990
  const itemKind = ref.item?.kind ?? ref.kind;
18945
18991
  const documentArgument = ref.kind === "block" && ref.item === undefined && tool !== "dispatch_comment" ? ` and artifact ${ref.id}` : tool === "dispatch_suggest" ? " and artifact <the document's slug>" : "";
18946
18992
  const ownerArguments = ref.owner.kind === "issue" ? `issue ${ref.owner.issue}${documentArgument}` : `project ${ref.owner.project} and artifact ${ref.artifact}`;
18947
- const fix = tool === "dispatch_comment" && itemKind === "ask" ? `reply under it with reply_to_ask ${ref.id} and ${ownerArguments}` : tool === "dispatch_comment" && itemKind === "comment" ? `reply in its thread with reply_to ${ref.id} and ${ownerArguments}` : `read it with dispatch read, or name ${owner} with ${ownerArguments}`;
18948
- const item = ref.kind === "ask" ? "an ask" : ref.kind === "log" ? "the event log" : ref.kind === "children" ? "the children" : ref.kind === "block" ? `block ${ref.block}${ref.item === undefined ? "" : ` of a ${ref.item.kind}`}` : `a ${ref.kind}`;
18993
+ const partRef = ref.pin === undefined ? refText : refText.slice(0, -`@v${ref.pin}`.length);
18994
+ const fix = tool === "dispatch_comment" && itemKind === "ask" ? `reply under it with reply_to_ask ${ref.item === undefined ? ref.id : partRef} and ${ownerArguments}` : tool === "dispatch_comment" && itemKind === "comment" ? `reply in its thread with reply_to ${ref.id} and ${ownerArguments}` : `read it with dispatch read, or name ${owner} with ${ownerArguments}`;
18995
+ const item = ref.kind === "ask" ? "an ask" : ref.kind === "log" ? "the event log" : ref.kind === "children" ? "the children" : ref.kind === "block" ? `block ${ref.block}${ref.item === undefined ? "" : ` of ${article(ref.item.kind)}`}` : `a ${ref.kind}`;
18949
18996
  return `ref ${refText} names ${item} on ${owner}; dispatch ${commandName(tool)} would act on ${owner} and drop the ${ref.kind}: ${fix}`;
18950
18997
  }
18951
18998
  var documentItemPattern = /^dispatch:\/\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)\/artifact\/[^/@]+(?:@v\d+)?\/(ask|comment)\/([^/]+)$/;
@@ -19391,14 +19438,19 @@ function referenceLines(read) {
19391
19438
  return [`- ${read}`];
19392
19439
  if (read.edges.length === 0)
19393
19440
  return ["- none"];
19394
- return read.edges.map((edge) => {
19395
- const { node } = edge;
19396
- const excerpt = edge.excerpt === undefined ? "" : `${textHead(edge.excerpt.text)} \xB7 `;
19397
- const block = edge.block === undefined ? "" : ` (block ${edge.block.ref ?? edge.block.id})`;
19398
- const item = node.kind === "block" && node.document === undefined && (node.parent?.kind === "comment" || node.parent?.kind === "message") ? node.parent : undefined;
19399
- const source = item === undefined ? `${node.kind} ${node.ref ?? node.id}` : `${item.kind} ${item.ref ?? item.id} block ${node.block_id ?? node.id}`;
19400
- return `- ${edge.kind} ${source} (${excerpt}${edge.created_at})${block}`;
19401
- });
19441
+ return read.edges.map(edgeLine);
19442
+ }
19443
+ function isItemKind(kind) {
19444
+ return ITEM_KINDS.some((item) => item === kind);
19445
+ }
19446
+ function edgeLine(edge) {
19447
+ const { node } = edge;
19448
+ const excerpt = edge.excerpt === undefined ? "" : `${textHead(edge.excerpt.text)} \xB7 `;
19449
+ const block = edge.block === undefined ? "" : ` (block ${edge.block.ref ?? edge.block.id})`;
19450
+ const parent = node.parent ?? undefined;
19451
+ const item = node.kind === "block" && node.document === undefined && isItemKind(parent?.kind) ? parent : undefined;
19452
+ const source = item === undefined ? `${node.kind} ${node.ref ?? node.id}` : `${item.kind} ${item.ref ?? item.id} block ${node.block_id ?? node.id}`;
19453
+ return `- ${edge.kind} ${source} (${excerpt}${edge.created_at})${block}`;
19402
19454
  }
19403
19455
  function unavailableReason(error) {
19404
19456
  return dispatchAnswered(error, 404) ? "unavailable" : `unavailable: ${messageFor(error)}`;
@@ -19440,12 +19492,12 @@ function nodeLine(node) {
19440
19492
  const made = fact(node.made_by, node.made_at);
19441
19493
  const changed = fact(node.changed_by, node.changed_at);
19442
19494
  const { parent } = node;
19443
- const partOf = parent == null ? "" : ` \xB7 part of ${parent.ref ?? `${parent.kind} ${parent.id}`}${node.parent_version == null ? "" : ` (${parent.kind === "comment" ? "revision" : "version"} ${node.parent_version})`}`;
19495
+ const partOf = parent == null ? "" : ` \xB7 part of ${parent.ref ?? `${parent.kind} ${parent.id}`}${node.parent_version == null ? "" : ` (${isItemKind(parent.kind) ? "revision" : "version"} ${node.parent_version})`}`;
19444
19496
  return [
19445
19497
  `Node: ${node.kind} ${node.ref ?? node.id} \xB7 made by ${made} \xB7 changed by ${changed}${partOf}`
19446
19498
  ];
19447
19499
  }
19448
- function blockLines(node, ref) {
19500
+ function blockLines(node, ref, noun = "Block") {
19449
19501
  const unit = ref.item === undefined ? "version" : "revision";
19450
19502
  const blockID = node.block_id ?? ref.block;
19451
19503
  const head = ref.item === undefined ? [
@@ -19454,7 +19506,7 @@ function blockLines(node, ref) {
19454
19506
  ...node.changed_version === undefined ? [] : [`Changed in version: ${node.changed_version}`],
19455
19507
  ...node.text === undefined ? [] : ["Text:", node.text]
19456
19508
  ] : [
19457
- `Block ${blockID} of ${ref.item.kind} ${ref.item.id}${node.changed_version === undefined ? "" : ` (changed in revision ${node.changed_version})`}:`,
19509
+ `${noun} ${blockID} of ${ref.item.kind} ${ref.item.id}${node.changed_version === undefined ? "" : ` (changed in revision ${node.changed_version})`}:`,
19458
19510
  ...node.text === undefined ? [] : [node.text]
19459
19511
  ];
19460
19512
  const { pin } = node;
@@ -19469,6 +19521,14 @@ function blockLines(node, ref) {
19469
19521
  pin.text
19470
19522
  ];
19471
19523
  }
19524
+ function askPartNoun(ask, node, blockID) {
19525
+ if (ask.answer?.id === blockID)
19526
+ return "Answer";
19527
+ if (ask.options.some((option) => option.id === blockID))
19528
+ return "Option";
19529
+ const placed = (ask.revision ?? 0) > 0 && ask.options.every((option) => option.id !== undefined) && (ask.answer === null || ask.answer.id !== undefined);
19530
+ return placed && node.pin?.state !== "removed" ? "Question" : "Part";
19531
+ }
19472
19532
  function logSummary(issue, events) {
19473
19533
  return [
19474
19534
  `Key: ${issue.key}`,
@@ -19533,9 +19593,11 @@ function childrenSummary(issue) {
19533
19593
  ].join(`
19534
19594
  `);
19535
19595
  }
19536
- function askSummary({ ask, replies, answers }, graph) {
19596
+ function askSummary({ ask, replies, answers }, askRef, pictures, incoming, outgoing) {
19537
19597
  const answer = ask.answer;
19538
19598
  const earlierAnswers = answers.slice(0, -1);
19599
+ const parts = askPartEdges(ask, incoming);
19600
+ const partRef = (id) => `${askRef}#b-${encodeBlockId(id)}`;
19539
19601
  const chain = replies.flatMap((reply) => [
19540
19602
  `${reply.id} \xB7 ${actorText(reply.author)}`,
19541
19603
  `Body: ${reply.body}`
@@ -19544,14 +19606,19 @@ function askSummary({ ask, replies, answers }, graph) {
19544
19606
  `Question: ${ask.question}`,
19545
19607
  ...anchorLines(ask),
19546
19608
  "Options:",
19547
- ...ask.options.length === 0 ? ["- none"] : ask.options.map((option) => `- ${option.label}${option.description ? ` \u2014 ${option.description}` : ""}`),
19609
+ ...ask.options.length === 0 ? ["- none"] : ask.options.flatMap((option) => [
19610
+ `- ${option.label}${option.description ? ` \u2014 ${option.description}` : ""}${option.id === undefined ? "" : ` (${partRef(option.id)})`}`,
19611
+ ...partReferenceLines(parts.at, option.id)
19612
+ ]),
19548
19613
  `State: ${ask.state}`,
19549
19614
  `Ask id: ${ask.id}`,
19550
19615
  "Answer:",
19551
19616
  ...answer === null ? ["- none"] : [
19552
19617
  `- By: ${answer.user}`,
19553
19618
  `- Selected: ${answer.selected.length === 0 ? "none" : answer.selected.join(", ")}`,
19554
- ...answer.text === null ? [] : [`- Text: ${answer.text}`]
19619
+ ...answer.text === null ? [] : [`- Text: ${answer.text}`],
19620
+ ...answer.id === undefined ? [] : [`- Reference: ${partRef(answer.id)}`],
19621
+ ...partReferenceLines(parts.at, answer.id)
19555
19622
  ],
19556
19623
  ...earlierAnswers.length === 0 ? [] : [
19557
19624
  "Earlier answers:",
@@ -19565,10 +19632,38 @@ function askSummary({ ask, replies, answers }, graph) {
19565
19632
  ],
19566
19633
  "Replies:",
19567
19634
  ...chain.length === 0 ? ["- none"] : chain,
19568
- ...graph
19635
+ ...pictures,
19636
+ ...graphSectionLines(parts.rest, outgoing)
19569
19637
  ].join(`
19570
19638
  `);
19571
19639
  }
19640
+ function askPartEdges(ask, incoming) {
19641
+ const ids = new Set([...ask.options.map((option) => option.id), ask.answer?.id].filter((id) => id !== undefined));
19642
+ const at = new Map;
19643
+ if (typeof incoming === "string" || ids.size === 0)
19644
+ return { at, rest: incoming };
19645
+ const rest = [];
19646
+ for (const edge of incoming.edges) {
19647
+ const part = edge.block?.block_id;
19648
+ if (part === undefined || !ids.has(part)) {
19649
+ rest.push(edge);
19650
+ continue;
19651
+ }
19652
+ const { block: _block, ...atPart } = edge;
19653
+ const held = at.get(part);
19654
+ if (held === undefined)
19655
+ at.set(part, [atPart]);
19656
+ else
19657
+ held.push(atPart);
19658
+ }
19659
+ return { at, rest: { node: incoming.node, edges: rest } };
19660
+ }
19661
+ function partReferenceLines(at, id) {
19662
+ const edges = id === undefined ? undefined : at.get(id);
19663
+ if (edges === undefined || edges.length === 0)
19664
+ return [];
19665
+ return [" Referenced by:", ...edges.map((edge) => ` ${edgeLine(edge)}`)];
19666
+ }
19572
19667
  function openAskAge(ageSeconds) {
19573
19668
  const seconds = Math.max(0, Math.floor(ageSeconds));
19574
19669
  if (seconds < 60)
@@ -20542,14 +20637,15 @@ async function executeDispatchTool(input) {
20542
20637
  const owner = documentOwner();
20543
20638
  const resolved = owner.kind === "project" || artifactReference === undefined ? owner.kind === "project" ? await resolveDocument(owner, artifactReference) : undefined : await resolveDocument(owner, artifactReference);
20544
20639
  const anchored = resolved ? anchor(resolved.artifact, args) : undefined;
20545
- const replyTo = commentReplyTo(args);
20546
- const replyToAskReference = optionalString(args, "reply_to_ask");
20547
- const replyToAsk = replyToAskReference === undefined ? undefined : normalizeUUID(replyToAskReference);
20548
- if (replyToAskReference !== undefined && replyToAsk === undefined) {
20640
+ const replyTo = itemReplyTo(args, "reply_to");
20641
+ const replyToAskTarget = itemReplyTo(args, "reply_to_ask");
20642
+ const replyToAsk = replyToAskTarget === undefined ? undefined : normalizeUUID(replyToAskTarget.id);
20643
+ if (replyToAskTarget !== undefined && replyToAsk === undefined) {
20549
20644
  throw new ToolInputError(input.tool, [
20550
20645
  await invalidReplyToAskProblem(client, owner, resolved)
20551
20646
  ]);
20552
20647
  }
20648
+ const replyToBlock = replyTo?.block ?? replyToAskTarget?.block;
20553
20649
  const requestedTurn = optionalString(args, "turn");
20554
20650
  const body = await writePictures(resolved, stringArg(args, "body"), {
20555
20651
  cap: DISPATCH_BODY_MAX,
@@ -20560,7 +20656,7 @@ async function executeDispatchTool(input) {
20560
20656
  body,
20561
20657
  ...anchored === undefined ? {} : { anchor: anchored },
20562
20658
  ...replyTo === undefined ? {} : { reply_to: replyTo.id },
20563
- ...replyTo?.block === undefined ? {} : { reply_to_block: replyTo.block },
20659
+ ...replyToBlock === undefined ? {} : { reply_to_block: replyToBlock },
20564
20660
  ...replyToAsk === undefined ? {} : { ask_id: replyToAsk },
20565
20661
  ...requestedTurn === undefined ? {} : { turn: requestedTurn },
20566
20662
  actor
@@ -20973,12 +21069,13 @@ ${handoff.body}`,
20973
21069
  const askRead = await readAskRef(input.tool, ref.id, refOwnerName(ref), client, async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks(await documentIdOf(ref), "all"));
20974
21070
  await refuseItemOffRef(input.tool, "ask", ref, stringArg(args, "ref"), askRead.ask, () => documentIdOf(ref));
20975
21071
  const askRef = refTarget(ref, "ask", askRead.ask.id);
20976
- const [pictures, graph] = await Promise.all([
21072
+ const [pictures, incoming, outgoing] = await Promise.all([
20977
21073
  picturesOf(askTexts(askRead)),
20978
- graphSections(client, askRef)
21074
+ graphReferences(client, { to: askRef }),
21075
+ graphReferences(client, { from: askRef })
20979
21076
  ]);
20980
21077
  return {
20981
- text: askSummary(askRead, [...pictures.lines, ...graph]),
21078
+ text: askSummary(askRead, askRef, pictures.lines, incoming, outgoing),
20982
21079
  details: ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: ref.owner.issue },
20983
21080
  ...showImages(pictures)
20984
21081
  };
@@ -21019,17 +21116,26 @@ ${handoff.body}`,
21019
21116
  const ref = ownerArguments.ref;
21020
21117
  const blockRef = stringArg(args, "ref");
21021
21118
  const holder = blockRef.slice(0, blockRef.indexOf("#"));
21022
- const [incoming, outgoing] = await Promise.all([
21119
+ const askOfPart = ref.item?.kind === "ask" ? client.getAsk(ref.item.id).catch(() => {
21120
+ return;
21121
+ }) : undefined;
21122
+ const [incoming, outgoing, partOf] = await Promise.all([
21023
21123
  client.getReferences({ to: blockRef }).catch((error) => {
21024
21124
  if (ref.pin === undefined && dispatchAnswered(error, 404)) {
21025
21125
  throw new Error(`No block ${ref.block} in ${holder}.`);
21026
21126
  }
21027
21127
  throw error;
21028
21128
  }),
21029
- graphReferences(client, { from: blockRef })
21129
+ graphReferences(client, { from: blockRef }),
21130
+ askOfPart
21030
21131
  ]);
21132
+ const blockID = incoming.node.block_id ?? ref.block ?? "";
21133
+ const noun = ref.item?.kind !== "ask" ? undefined : partOf === undefined ? "Part" : askPartNoun(partOf.ask, incoming.node, blockID);
21031
21134
  return {
21032
- text: [...blockLines(incoming.node, ref), ...graphSectionLines(incoming, outgoing)].join(`
21135
+ text: [
21136
+ ...blockLines(incoming.node, ref, noun),
21137
+ ...graphSectionLines(incoming, outgoing)
21138
+ ].join(`
21033
21139
  `),
21034
21140
  details: {
21035
21141
  ...ref.owner.kind === "project" ? { project: ref.owner.project } : { issue: ref.owner.issue },
package/dist/envoy.js CHANGED
@@ -29752,8 +29752,13 @@ var askEventPayloadFields = {
29752
29752
  opened_event_id: number2().int().positive(),
29753
29753
  kind: string2().optional(),
29754
29754
  question: string2().optional(),
29755
- options: array(object({ label: string2().optional() })).optional(),
29756
- answer: object({ selected: array(string2()).nullish(), text: string2().nullish() }).nullish(),
29755
+ options: array(object({ id: string2().optional(), label: string2().optional() })).optional(),
29756
+ revision: number2().int().positive().optional(),
29757
+ answer: object({
29758
+ id: string2().optional(),
29759
+ selected: array(string2()).nullish(),
29760
+ text: string2().nullish()
29761
+ }).nullish(),
29757
29762
  previous_answer: object({
29758
29763
  user: string2().optional(),
29759
29764
  selected: array(string2()).nullish(),
@@ -30340,8 +30345,8 @@ var dispatchToolSpecs = [
30340
30345
  quote: z.string().describe("Optional exact quoted document text.").optional(),
30341
30346
  occurrence: z.number({ int: true, min: 0 }).describe("Optional zero-based occurrence of quote.").optional(),
30342
30347
  body: z.string({ max: DISPATCH_BODY_MAX }).describe(`Review comment, at most ${DISPATCH_BODY_MAX} characters.`),
30343
- reply_to: z.string().describe("A comment id (uuid); replying to any comment in a thread continues that thread (an " + "ask's clarification thread included). A block reference to one block of the comment " + "(dispatch://KEY/comment/<id>#b-<block id>) replies to that comment and names the " + "passage the reply answers. To reply to an ask, use reply_to_ask with the " + "ask id instead.").optional(),
30344
- reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. Mutually " + "exclusive with reply_to.").optional(),
30348
+ reply_to: z.string().describe("A comment id (uuid); replying to any comment in a thread continues that thread (an " + "ask's clarification thread included). A block reference to one block of the comment " + "(dispatch://KEY/comment/<id>#b-<block id>) replies to that comment and names the " + "passage the reply answers. To reply to an ask, use reply_to_ask with the ask id, or " + "with a reference to one of its parts, instead.").optional(),
30349
+ reply_to_ask: z.string().describe("Optional ask id to reply to, threading this comment under that question. A block " + "reference to one part of the ask (dispatch://KEY/ask/<id>#b-<part id>, the id an " + "option or the answer carries) threads under that ask and names the part the reply " + "answers. Mutually exclusive with reply_to.").optional(),
30345
30350
  turn: z.enum(["agent", "human"]).describe("Only with reply_to_ask: who holds the turn after this reply. agent: a progress note - " + "you keep the turn and the ask stays 'Waiting on agents' for the human; human (default): " + "you need the human to act - the ask returns to 'Waiting on you'.").optional(),
30346
30351
  images: imagesArgument(z, "the issue (or the project document's project)", `the ${DISPATCH_BODY_MAX}-character body limit`)
30347
30352
  }),
@@ -30668,7 +30673,7 @@ var ISSUE_KEY = `${PROJECT_KEY}-[1-9][0-9]*`;
30668
30673
  var DOCUMENT_SLUG = "[a-z0-9]+(?:-[a-z0-9]+)*";
30669
30674
  var ISSUE_KEY_ONLY = new RegExp(`^${ISSUE_KEY}$`);
30670
30675
  var BLOCK_REFERENCE = new RegExp(`^dispatch://(?:(${ISSUE_KEY})/spec|(${ISSUE_KEY}|${PROJECT_KEY})/artifact/(${DOCUMENT_SLUG}))#b-(.*)$`, "s");
30671
- var ITEM_BLOCK_REFERENCE = new RegExp(`^dispatch://(?:${ISSUE_KEY}/(comment|message)|${PROJECT_KEY}/artifact/${DOCUMENT_SLUG}/(comment))/([^/?#]+)#b-(.*)$`, "s");
30676
+ var ITEM_BLOCK_REFERENCE = new RegExp(`^dispatch://(?:${ISSUE_KEY}/(ask|comment|message)|${PROJECT_KEY}/artifact/${DOCUMENT_SLUG}/(ask|comment))/([^/?#]+)#b-(.*)$`, "s");
30672
30677
  var atIdBound = `dispatch://CORE-1/spec#b-${"x".repeat(MAX_BLOCK_ID_BYTES)}`;
30673
30678
  var DISPATCH_BLOCK_POINTER_VALUES = [
30674
30679
  {
@@ -30768,25 +30773,55 @@ var DISPATCH_BLOCK_POINTER_VALUES = [
30768
30773
  value: "dispatch://CORE-1/comment/11111111-1111-4111-8111-111111111111#b-b2",
30769
30774
  ok: false,
30770
30775
  why: "a block of an issue's comment",
30771
- problem: "a block[] attribute points only at a block of a document"
30776
+ problem: "is a block of a comment: a block[] attribute points only at a block of a document"
30772
30777
  },
30773
30778
  {
30774
30779
  value: "dispatch://CORE-1/comment/11111111-1111-4111-8111-111111111111#b-b2@v1",
30775
30780
  ok: false,
30776
30781
  why: "a block of a revision of an issue's comment",
30777
- problem: "a block[] attribute points only at a block of a document"
30782
+ problem: "is a block of a comment: a block[] attribute points only at a block of a document"
30778
30783
  },
30779
30784
  {
30780
30785
  value: "dispatch://CORE/artifact/handbook-md/comment/88888888-8888-4888-8888-888888888888#b-b2",
30781
30786
  ok: false,
30782
30787
  why: "a block of a project document's comment",
30783
- problem: "a block[] attribute points only at a block of a document"
30788
+ problem: "is a block of a comment: a block[] attribute points only at a block of a document"
30784
30789
  },
30785
30790
  {
30786
30791
  value: "dispatch://CORE-1/message/33333333-3333-4333-8333-333333333333#b-b2",
30787
30792
  ok: false,
30788
30793
  why: "a block of an issue message",
30789
- problem: "a block[] attribute points only at a block of a document"
30794
+ problem: "is a block of a message: a block[] attribute points only at a block of a document"
30795
+ },
30796
+ {
30797
+ value: "dispatch://CORE-1/ask/22222222-2222-4222-8222-222222222222#b-b2",
30798
+ ok: false,
30799
+ why: "a part of an issue's ask",
30800
+ problem: "is a block of an ask: a block[] attribute points only at a block of a document"
30801
+ },
30802
+ {
30803
+ value: "dispatch://CORE-1/ask/22222222-2222-4222-8222-222222222222#b-b2@v1",
30804
+ ok: false,
30805
+ why: "a part of a revision of an issue's ask",
30806
+ problem: "is a block of an ask: a block[] attribute points only at a block of a document"
30807
+ },
30808
+ {
30809
+ value: "dispatch://CORE/artifact/handbook-md/ask/99999999-9999-4999-8999-999999999999#b-b2",
30810
+ ok: false,
30811
+ why: "a part of a project document's ask",
30812
+ problem: "is a block of an ask: a block[] attribute points only at a block of a document"
30813
+ },
30814
+ {
30815
+ value: "dispatch://CORE/artifact/handbook-md/ask/99999999-9999-4999-8999-999999999999#b-b2@v1",
30816
+ ok: false,
30817
+ why: "a part of a revision of a project document's ask",
30818
+ problem: "is a block of an ask: a block[] attribute points only at a block of a document"
30819
+ },
30820
+ {
30821
+ value: "dispatch://CORE-1/artifact/notes-md/ask/a1#b-b2",
30822
+ ok: false,
30823
+ why: "an issue document's ask, a shape no reference has",
30824
+ problem: "is not a block reference as Dispatch writes one"
30790
30825
  },
30791
30826
  {
30792
30827
  value: "dispatch://CORE-1/artifact/notes-md/comment/c1#b-x",
@@ -30804,7 +30839,7 @@ var DISPATCH_BLOCK_POINTER_VALUES = [
30804
30839
  value: "dispatch://CORE-1/spec#b-x dispatch://CORE-1/message/33333333-3333-4333-8333-333333333333#b-b2",
30805
30840
  ok: false,
30806
30841
  why: "a document's block, then an issue message's",
30807
- problem: "a block[] attribute points only at a block of a document"
30842
+ problem: "is a block of a message: a block[] attribute points only at a block of a document"
30808
30843
  }
30809
30844
  ];
30810
30845
  // ../contracts/src/envelope.ts
@@ -32854,7 +32889,7 @@ function parseBlockRef(holder, fragment) {
32854
32889
  }
32855
32890
  const pin = target.pin === undefined ? {} : { pin: target.pin };
32856
32891
  const artifact = parsed.artifact === undefined ? {} : { artifact: parsed.artifact };
32857
- if (parsed.kind === "comment" || parsed.kind === "message" && target.pin === undefined) {
32892
+ if (parsed.kind === "ask" || parsed.kind === "comment" || parsed.kind === "message" && target.pin === undefined) {
32858
32893
  return {
32859
32894
  owner: parsed.owner,
32860
32895
  kind: "block",
@@ -36805,6 +36840,9 @@ function optionalNumber(args, name) {
36805
36840
  const value = args[name];
36806
36841
  return typeof value === "number" ? value : undefined;
36807
36842
  }
36843
+ function article(kind) {
36844
+ return kind === "ask" ? "an ask" : `a ${kind}`;
36845
+ }
36808
36846
  function refOwnerName(ref) {
36809
36847
  return ref.owner.kind === "issue" ? ref.owner.issue : `${ref.owner.project}/${ref.artifact ?? ref.id}`;
36810
36848
  }
@@ -36849,7 +36887,7 @@ function dispatchRefFromUrl(value, serverUrl) {
36849
36887
  return `dispatch://${key}/artifact/${slug}${version}${blockOf("v")}`;
36850
36888
  }
36851
36889
  if (ask !== undefined)
36852
- return `dispatch://${key}/ask/${ask}`;
36890
+ return `dispatch://${key}/ask/${ask}${blockOf()}`;
36853
36891
  if (comment !== undefined)
36854
36892
  return `dispatch://${key}/comment/${comment}${blockOf()}`;
36855
36893
  if (message !== undefined)
@@ -36876,7 +36914,7 @@ function dispatchRefFromUrl(value, serverUrl) {
36876
36914
  return;
36877
36915
  return item === undefined ? `${document}${versionOf("version")}${blockOf("version")}` : `${document}/${item.kind}/${item.id}`;
36878
36916
  }
36879
- 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), dispatch://KEY-1/comment/<uuid>#b-<block id>, " + "dispatch://PROJECT/artifact/<slug>/comment/<uuid>#b-<block id> or " + "dispatch://KEY-1/message/<uuid>#b-<block id> (one block of a comment or message, a " + "comment's optionally pinned to a revision of the comment 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";
36917
+ 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), dispatch://KEY-1/ask/<uuid>#b-<part id> or " + "dispatch://PROJECT/artifact/<slug>/ask/<uuid>#b-<part id> (one part of an ask: its question, " + "one of its options or its answer, optionally pinned to a revision of the ask's parts with " + "@v<N> after it; for dispatch read), dispatch://KEY-1/comment/<uuid>#b-<block id>, " + "dispatch://PROJECT/artifact/<slug>/comment/<uuid>#b-<block id> or " + "dispatch://KEY-1/message/<uuid>#b-<block id> (one block of a comment or message, a " + "comment's optionally pinned to a revision of the comment 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";
36880
36918
  var ownerRequiredProblem = "issue is required; supply issue or set LEGION_ISSUE";
36881
36919
  function innerRefProblem(tool, ref, refText) {
36882
36920
  if (ref.kind !== "ask" && ref.kind !== "comment" && ref.kind !== "message" && ref.kind !== "log" && ref.kind !== "children" && ref.kind !== "block") {
@@ -36888,8 +36926,9 @@ function innerRefProblem(tool, ref, refText) {
36888
36926
  const itemKind = ref.item?.kind ?? ref.kind;
36889
36927
  const documentArgument = ref.kind === "block" && ref.item === undefined && tool !== "dispatch_comment" ? ` and artifact ${ref.id}` : tool === "dispatch_suggest" ? " and artifact <the document's slug>" : "";
36890
36928
  const ownerArguments = ref.owner.kind === "issue" ? `issue ${ref.owner.issue}${documentArgument}` : `project ${ref.owner.project} and artifact ${ref.artifact}`;
36891
- const fix = tool === "dispatch_comment" && itemKind === "ask" ? `reply under it with reply_to_ask ${ref.id} and ${ownerArguments}` : tool === "dispatch_comment" && itemKind === "comment" ? `reply in its thread with reply_to ${ref.id} and ${ownerArguments}` : `read it with dispatch read, or name ${owner} with ${ownerArguments}`;
36892
- const item = ref.kind === "ask" ? "an ask" : ref.kind === "log" ? "the event log" : ref.kind === "children" ? "the children" : ref.kind === "block" ? `block ${ref.block}${ref.item === undefined ? "" : ` of a ${ref.item.kind}`}` : `a ${ref.kind}`;
36929
+ const partRef = ref.pin === undefined ? refText : refText.slice(0, -`@v${ref.pin}`.length);
36930
+ const fix = tool === "dispatch_comment" && itemKind === "ask" ? `reply under it with reply_to_ask ${ref.item === undefined ? ref.id : partRef} and ${ownerArguments}` : tool === "dispatch_comment" && itemKind === "comment" ? `reply in its thread with reply_to ${ref.id} and ${ownerArguments}` : `read it with dispatch read, or name ${owner} with ${ownerArguments}`;
36931
+ const item = ref.kind === "ask" ? "an ask" : ref.kind === "log" ? "the event log" : ref.kind === "children" ? "the children" : ref.kind === "block" ? `block ${ref.block}${ref.item === undefined ? "" : ` of ${article(ref.item.kind)}`}` : `a ${ref.kind}`;
36893
36932
  return `ref ${refText} names ${item} on ${owner}; dispatch ${commandName(tool)} would act on ${owner} and drop the ${ref.kind}: ${fix}`;
36894
36933
  }
36895
36934
  var documentItemPattern = /^dispatch:\/\/([A-Z][A-Z0-9]{1,9}-[1-9][0-9]*)\/artifact\/[^/@]+(?:@v\d+)?\/(ask|comment)\/([^/]+)$/;
@@ -38121,7 +38160,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
38121
38160
 
38122
38161
  // package.json
38123
38162
  var name = "@sjawhar/pi-envoy";
38124
- var version2 = "15.0.3";
38163
+ var version2 = "15.1.1";
38125
38164
  var package_default = {
38126
38165
  name,
38127
38166
  version: version2,
@@ -41288,7 +41327,9 @@ var INDIRECT_FLAGS = ["--name-file", "--path-file"];
41288
41327
  var NO_SEND_FLAGS = ["--dry-run", "--help"];
41289
41328
  var REBUTTAL_KEY = "advisor_rebuttal";
41290
41329
  var REBUTTAL_FLAG = "--advisor-rebuttal";
41291
- var DRY_RUN_TIMEOUT_MS = 1e4;
41330
+ var DRY_RUN_TIMEOUT_MS = 20000;
41331
+ var READ_SHARE = 0.5;
41332
+ var MIN_RETRY_MS = 2000;
41292
41333
  var GATE_TIMEOUT_MS = 90000;
41293
41334
  var CEILING_MARGIN_MS = 5000;
41294
41335
  var ABORT_GRACE_MS = 2000;
@@ -42376,6 +42417,9 @@ var renderUnreviewed = (outcome, reason) => {
42376
42417
  ${opening}${why}. The call ran unreviewed.
42377
42418
  </advisor-gate>`;
42378
42419
  };
42420
+ var renderSlowDryRun = (reason) => `<advisor-gate advisor="AskGate" outcome="error">
42421
+ AskGate did not review this Dispatch write: ${agentFacing(reason)}. A dry run only checks the arguments on this machine and contacts no Dispatch server, so the likely cause is a busy machine, not Dispatch. The call ran unreviewed: read back what it posted, and correct it if it is wrong.
42422
+ </advisor-gate>`;
42379
42423
  function resendFlags(flag) {
42380
42424
  if (flag === "--path" || flag === "--path-file")
42381
42425
  return { stdin: "--content-file", regular: "`--path` or `--content-file`" };
@@ -42658,14 +42702,12 @@ ${notice}
42658
42702
  rebuttals.delete(rebuttals.keys().next().value);
42659
42703
  return { input: { ...input, content } };
42660
42704
  };
42661
- const pass = (outcome, fields = {}, effect = "none") => {
42662
- const note = renderUnreviewed(outcome, fields.reason);
42663
- return {
42664
- fields: { decision: "allow", outcome, ...fields },
42665
- ...note === undefined ? {} : { result: { additionalContext: note } },
42666
- effect
42667
- };
42668
- };
42705
+ const pass = (outcome, fields = {}, effect = "none", note = renderUnreviewed(outcome, fields.reason)) => ({
42706
+ fields: { decision: "allow", outcome, ...fields },
42707
+ ...note === undefined ? {} : { result: { additionalContext: note } },
42708
+ effect
42709
+ });
42710
+ const callDeadlineMs = () => Math.min(timeoutMs, deps.handlerCeilingMs() - CEILING_MARGIN_MS);
42669
42711
  const givenUp = (mode, cause, fields = {}) => mode === "block" ? {
42670
42712
  fields: { decision: "revise", outcome: cause, ...fields },
42671
42713
  result: { block: true, reason: NO_VERDICT_REFUSAL[cause] },
@@ -42823,7 +42865,7 @@ ${user}
42823
42865
  const { role, model } = resolved;
42824
42866
  if (ctx.model?.provider !== model.provider)
42825
42867
  return pass("skipped", { reason: `primary on ${ctx.model?.provider ?? "no model"}` });
42826
- const deadlineMs = Math.min(timeoutMs, deps.handlerCeilingMs() - CEILING_MARGIN_MS);
42868
+ const deadlineMs = callDeadlineMs();
42827
42869
  stop.arm(Math.max(0, deadlineMs - (deps.now() - started)));
42828
42870
  const chain = [
42829
42871
  model,
@@ -42926,7 +42968,7 @@ ${user}
42926
42968
  return { kind: "error", reason: messageOf(error) };
42927
42969
  }
42928
42970
  };
42929
- const readArgs = async (scoped, input, ctx, stop) => {
42971
+ const readArgs = async (scoped, input, ctx, stop, readsEnd) => {
42930
42972
  const raw = typeof input.cwd === "string" && input.cwd !== "" ? input.cwd.replace(/^~(?=$|\/)/, deps.home) : undefined;
42931
42973
  const cwd = raw === undefined || /^\/+$/.test(raw) ? ctx.cwd : path4.resolve(ctx.cwd, raw);
42932
42974
  const { CDPATH: _cdpath, ...env } = deps.env;
@@ -42935,23 +42977,37 @@ ${user}
42935
42977
  throw new Error("the gate's deadline fired while its dry run was still reading");
42936
42978
  return stop.cause;
42937
42979
  };
42938
- const runScript = async (script) => {
42980
+ const runScript = async (script, limitMs) => {
42939
42981
  const run = await deps.dryRun(script, {
42940
42982
  cwd,
42941
42983
  env,
42942
- timeoutMs: DRY_RUN_TIMEOUT_MS,
42984
+ timeoutMs: limitMs,
42943
42985
  signal: stop.signal
42944
42986
  });
42945
42987
  const cause = abandoned();
42946
42988
  return cause === undefined ? { run } : { cause };
42947
42989
  };
42948
42990
  const stdoutOf = async (script, what) => {
42949
- const ran = await runScript(script);
42991
+ const firstMs = Math.max(0, Math.min(DRY_RUN_TIMEOUT_MS, readsEnd - deps.now()));
42992
+ let ran = await runScript(script, firstMs);
42950
42993
  if ("cause" in ran)
42951
42994
  return ran;
42995
+ let retryMs;
42996
+ if (ran.run.timedOut) {
42997
+ const leftMs = readsEnd - deps.now();
42998
+ if (leftMs >= MIN_RETRY_MS) {
42999
+ retryMs = leftMs;
43000
+ ran = await runScript(script, retryMs);
43001
+ if ("cause" in ran)
43002
+ return ran;
43003
+ }
43004
+ }
42952
43005
  const { run } = ran;
42953
43006
  if (run.timedOut)
42954
- return { failure: `${what} did not finish within ${DRY_RUN_TIMEOUT_MS} ms` };
43007
+ return {
43008
+ failure: `${what} did not finish within ${firstMs} ms, ${retryMs === undefined ? "and the call's deadline left no time to run it again" : `nor within ${retryMs} ms when run again`}`,
43009
+ slow: true
43010
+ };
42955
43011
  if (run.exitCode !== 0) {
42956
43012
  const printed = clipBytes((run.stdout || run.stderr).trim(), GATE_PRINTED_MAX_BYTES);
42957
43013
  return { failure: `${what} exited ${run.exitCode ?? "on a signal"}: ${printed}` };
@@ -43168,7 +43224,9 @@ ${user}
43168
43224
  else {
43169
43225
  const stop = openStop(event.toolCallId);
43170
43226
  try {
43171
- const run = await readArgs(scoped, event.input, ctx, stop);
43227
+ const deadlineMs = callDeadlineMs();
43228
+ const readsEnd = started + Math.floor(deadlineMs * READ_SHARE);
43229
+ const run = await readArgs(scoped, event.input, ctx, stop, readsEnd);
43172
43230
  if ("unscoped" in run)
43173
43231
  return revised === undefined ? undefined : { input: revised };
43174
43232
  if ("cause" in run)
@@ -43183,7 +43241,7 @@ ${user}
43183
43241
  else
43184
43242
  decision = unreadableCall(run.unreadable, checks);
43185
43243
  } else if ("failure" in run)
43186
- decision = pass("error", { reason: run.failure });
43244
+ decision = pass("error", { reason: run.failure, deadlineMs }, "none", run.slow ? renderSlowDryRun(run.failure) : undefined);
43187
43245
  else {
43188
43246
  dryRun = { args: run.args, files: run.files };
43189
43247
  const { key, label } = breakerKey(scoped.tool, run.review);
@@ -25,7 +25,7 @@ Which machines, files or people, the numbers, then "A happens to X, or B to Y?"
25
25
  ```
26
26
 
27
27
  - In Legion, fix a clear defect in code your tree uses, hand others to the controller, and ask about decisions (`skill://legion-worker/references/findings.md`).
28
- - An open ask is the request. Do not repeat it in each message.
28
+ - An open ask is the request; never repeat it in each message.
29
29
  - Change an open ask's block with `dispatch edit-ask`, or `doc-edit`'s `replace` or `move`. An answered ask is fixed: ask anew.
30
30
  - 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.
31
31
  - When an answer's option and text disagree, the text wins.
@@ -69,6 +69,7 @@ dispatch://KEY
69
69
  dispatch://KEY/spec
70
70
  dispatch://KEY/artifact/<slug>[@vN]
71
71
  dispatch://KEY/ask/<id>
72
+ dispatch://KEY/ask/<id>#b-<part>[@vN]
72
73
  dispatch://KEY/comment/<id>
73
74
  dispatch://KEY/comment/<id>#b-<block>[@vN]
74
75
  dispatch://KEY/message/<id>
@@ -78,9 +79,9 @@ dispatch://PROJECT/artifact/<slug>/ask/<id>
78
79
  dispatch://PROJECT/artifact/<slug>/comment/<id>#b-<block>[@vN]
79
80
  ```
80
81
 
81
- A bare id, filename or local path is not a reference, and outside Dispatch neither is `dispatch://`: give the `https://` link `dispatch` printed. Write each id whole, from `dispatch read`'s `Ask id:` or the page URL: the command takes a prefix, a person's link does not.
82
+ A bare id, filename or path is not a reference, and outside Dispatch neither is `dispatch://`: give the `https://` link `dispatch` printed. Write each id whole, from `dispatch read`'s `Ask id:` or the page URL: the command takes a prefix, a person's link does not.
82
83
 
83
84
  ## Setup and the HTTP API
84
85
 
85
- - Use a personal token from Dispatch **Settings → Agent tokens**, as `DISPATCH_TOKEN` or `dispatch.token` in the session's `envoy.json`.
86
+ - Use a personal token from **Settings → Agent tokens**, as `DISPATCH_TOKEN` or `dispatch.token` in the session's `envoy.json`.
86
87
  - `GET /api/v1` lists every route; never guess one. Branch on an error's `code`, not its text.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "15.0.3",
3
+ "version": "15.1.1",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {