@sjawhar/pi-envoy 15.1.2 → 15.1.3

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
@@ -14979,7 +14979,7 @@ var messageValidation = {
14979
14979
  },
14980
14980
  message: "issue is required unless in_reply_to names a message delivered to this session, which is the one message with no issue."
14981
14981
  };
14982
- var readOwner = documentOwnerValidation(true);
14982
+ var readOwner = documentOwnerValidation(false);
14983
14983
  var readValidation = {
14984
14984
  check: (value) => {
14985
14985
  const input = value;
@@ -14987,7 +14987,7 @@ var readValidation = {
14987
14987
  return readOwner.check(value);
14988
14988
  return input.issue === undefined && input.project === undefined && input.artifact === undefined && input.ref === undefined;
14989
14989
  },
14990
- message: `${readOwner.message} message stands alone: it names the conversation, so name no issue, project, artifact, or ref with it.`
14990
+ message: "Exactly one of issue and project is required; project alone lists its documents, and with artifact names one. " + "message stands alone: it names the conversation, so name no issue, project, artifact, or ref with it."
14991
14991
  };
14992
14992
  var ISSUE_COMPONENTS_MODES = ["inherit", "explicit", "none"];
14993
14993
  function componentsArgument(z) {
@@ -15246,7 +15246,7 @@ var dispatchToolSpecs = [
15246
15246
  body: z.string({ max: DISPATCH_BODY_MAX }).describe(`Review comment, at most ${DISPATCH_BODY_MAX} characters.`),
15247
15247
  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(),
15248
15248
  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(),
15249
- 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(),
15249
+ 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'. human does not " + "apply to an approval request a newer version moved: it stays with you until dispatch " + "request-approval hands it back at the current version.").optional(),
15250
15250
  images: imagesArgument(z, "the issue (or the project document's project)", `the ${DISPATCH_BODY_MAX}-character body limit`)
15251
15251
  }),
15252
15252
  validation: commentValidation
@@ -15370,7 +15370,7 @@ var dispatchToolSpecs = [
15370
15370
  {
15371
15371
  name: "dispatch_read",
15372
15372
  example: { issue: "DSP-1" },
15373
- 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,
15373
+ 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), project plus artifact, or project alone, which lists the project's documents on no issue and nothing more; 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 issue read lists every document, picture and file the issue holds under `Documents:`, each by slug, filename and kind. " + "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,
15374
15374
  arguments: (z) => ({
15375
15375
  issue: z.string().describe(ISSUE_REFERENCE).optional(),
15376
15376
  project: z.string().describe("Project key owning the document.").optional(),
@@ -19268,7 +19268,7 @@ async function resolveArtifact(client, owner, artifactReference, { canonical = f
19268
19268
  const artifacts = routed === undefined ? unlinked : [routed, ...unlinked.filter((candidate) => candidate.id !== routed.id)];
19269
19269
  return {
19270
19270
  owner,
19271
- artifact: artifactByReference(artifacts, artifactReference, "project", canonical)
19271
+ artifact: artifactByReference(artifacts, artifactReference, owner, canonical)
19272
19272
  };
19273
19273
  }
19274
19274
  const issue = await client.getIssue(owner.issue);
@@ -19276,10 +19276,13 @@ async function resolveArtifact(client, owner, artifactReference, { canonical = f
19276
19276
  if (artifactReference === undefined || artifactReference === "spec") {
19277
19277
  artifact = issue.artifacts.find((candidate) => candidate.primary || candidate.id === issue.primary_artifact_id);
19278
19278
  } else {
19279
- artifact = artifactByReference(issue.artifacts, artifactReference, "issue", canonical);
19279
+ artifact = artifactByReference(issue.artifacts, artifactReference, { kind: "issue", issue: issue.key }, canonical);
19280
19280
  }
19281
19281
  if (!artifact) {
19282
- throw new DocumentNotFoundError(documentReferenceProblem(artifactReference ?? "spec", issue.artifacts, "issue"));
19282
+ throw new DocumentNotFoundError(documentReferenceProblem(artifactReference ?? "spec", issue.artifacts, {
19283
+ kind: "issue",
19284
+ issue: issue.key
19285
+ }));
19283
19286
  }
19284
19287
  return { owner, issue, artifact };
19285
19288
  }
@@ -19300,15 +19303,85 @@ async function documentTargets(client, resolution) {
19300
19303
  }
19301
19304
  var documentHintLimit = 8;
19302
19305
  function documentReferenceProblem(reference, documents, owner, ambiguous = false) {
19303
- const hints = documents.slice(0, documentHintLimit).map((document) => `${document.slug} (${document.name})`);
19306
+ const scope = owner.kind;
19307
+ const busy = !ambiguous && documents.length > documentHintLimit;
19308
+ const hints = (busy ? documentsNearest(reference, documents) : documents).slice(0, documentHintLimit).map((document) => `${document.slug} (${document.name})`);
19304
19309
  const list = hints.length === 0 ? "none" : hints.join(", ");
19305
- return ambiguous ? `"${reference}" names ${documents.length} documents on this ${owner}; use a slug: ${list}` : `document "${reference}" not found by slug; this ${owner}'s documents: ${list}`;
19310
+ if (busy) {
19311
+ const read = owner.kind === "issue" ? `dispatch read --issue ${owner.issue}` : `dispatch read --project ${owner.project}`;
19312
+ const counted = documents.every((document) => (document.kind ?? "doc") === "doc") ? "documents" : "documents and files";
19313
+ return `document "${reference}" not found by slug; this ${scope}'s ${documents.length} ${counted} include: ${list}; ${read} lists them all`;
19314
+ }
19315
+ return ambiguous ? `"${reference}" names ${documents.length} documents on this ${scope}; use a slug: ${list}` : `document "${reference}" not found by slug; this ${scope}'s documents: ${list}`;
19316
+ }
19317
+ function documentsNearest(reference, documents) {
19318
+ return documents.map((document, index) => ({
19319
+ document,
19320
+ index,
19321
+ ...documentCloseness(reference, document.slug, document.name)
19322
+ })).sort((a, b) => {
19323
+ if (a.near !== b.near)
19324
+ return a.near ? -1 : 1;
19325
+ if (a.near && a.distance !== b.distance)
19326
+ return a.distance - b.distance;
19327
+ return b.index - a.index;
19328
+ }).map(({ document }) => document);
19329
+ }
19330
+ function documentListLines(documents) {
19331
+ return documents.length === 0 ? ["- none"] : documents.map((document) => `- ${document.slug} (${document.name}, ${document.kind})`);
19332
+ }
19333
+ function documentCloseness(reference, slug, name) {
19334
+ const wanted = [...reference.replace(/[A-Z]/g, (letter) => letter.toLowerCase())];
19335
+ const limit = Math.max(2, Math.floor(wanted.length / 3));
19336
+ let distance = Number.POSITIVE_INFINITY;
19337
+ for (const candidate of [slug, name]) {
19338
+ const label = [...candidate.replace(/[A-Z]/g, (letter) => letter.toLowerCase())];
19339
+ let edits = boundedEditDistance(wanted, label, limit);
19340
+ if (wanted.length >= 4 && label.join("").includes(wanted.join("")) || label.length >= 4 && wanted.join("").includes(label.join(""))) {
19341
+ edits = Math.abs(label.length - wanted.length);
19342
+ } else if (edits > limit) {
19343
+ continue;
19344
+ }
19345
+ distance = Math.min(distance, edits);
19346
+ }
19347
+ return distance === Number.POSITIVE_INFINITY ? { distance: limit + 1, near: false } : { distance, near: true };
19348
+ }
19349
+ function boundedEditDistance(a, b, limit) {
19350
+ if (Math.abs(a.length - b.length) > limit)
19351
+ return limit + 1;
19352
+ let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
19353
+ let current = new Array(b.length + 1).fill(0);
19354
+ for (let i = 1;i <= a.length; i++) {
19355
+ current[0] = i;
19356
+ let smallest = i;
19357
+ for (let j = 1;j <= b.length; j++) {
19358
+ const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
19359
+ current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, substitution);
19360
+ smallest = Math.min(smallest, current[j]);
19361
+ }
19362
+ if (smallest > limit)
19363
+ return limit + 1;
19364
+ [previous, current] = [current, previous];
19365
+ }
19366
+ return Math.min(previous[b.length], limit + 1);
19306
19367
  }
19307
19368
  var askHintLimit = 8;
19308
19369
  function askIDInputProblem(asks, scope) {
19309
19370
  const hints = asks.slice(0, askHintLimit).map((ask) => `${ask.id.slice(0, 8)}\u2026 ${textHead(ask.question)}`);
19310
19371
  return `ask IDs are UUIDs; use the full ask ID; ${scope} open asks: ${hints.length === 0 ? "none" : hints.join(", ")}`;
19311
19372
  }
19373
+ async function movedApprovalLine(client, askID) {
19374
+ const ask = (await client.getAsk(askID).catch(() => {
19375
+ return;
19376
+ }))?.ask;
19377
+ const approval = ask?.approval;
19378
+ if (ask?.kind !== "approval" || approval === undefined)
19379
+ return;
19380
+ if (approval.requested_version >= approval.version)
19381
+ return;
19382
+ const owner = ask.issue_key === null ? `--project ${ask.approval_artifact?.project ?? "<project>"} --artifact ${approval.artifact_id}` : ask.approval_artifact?.primary === true ? `--issue ${ask.issue_key}` : `--issue ${ask.issue_key} --artifact ${approval.artifact_id}`;
19383
+ return `The reply did not hand the ask to the human: it is the approval request for ${approval.name} ` + `at version ${approval.requested_version}, and ${approval.name} is now version ${approval.version}. ` + "No reply hands a moved approval request back. Once the human has agreed to every point in " + `version ${approval.version}, run: dispatch request-approval ${owner} --summary ` + `'<what changed since version ${approval.requested_version}>'`;
19384
+ }
19312
19385
  async function invalidReplyToAskProblem(client, owner, resolved) {
19313
19386
  if (owner.kind === "issue") {
19314
19387
  const issue = resolved?.issue ?? await client.getIssue(owner.issue);
@@ -19465,6 +19538,8 @@ function issueSummary(issue, events, references, graph, linkBase, titles) {
19465
19538
  ...specApproval === undefined ? [] : [`Spec ${specApproval.replace(/^Approval/, "approval")}`],
19466
19539
  "External links:",
19467
19540
  ...issue.external_links.length === 0 ? ["- none"] : issue.external_links.map((link) => `- ${link.url}${link.kind === undefined ? "" : ` (${link.kind})`}`),
19541
+ "Documents:",
19542
+ ...documentListLines(issue.artifacts ?? []),
19468
19543
  "Open asks:",
19469
19544
  ...asks.length === 0 ? ["- none"] : asks.map((ask) => `- ${ask.id}: ${ask.question}`),
19470
19545
  "References:",
@@ -20713,9 +20788,11 @@ async function executeDispatchTool(input) {
20713
20788
  });
20714
20789
  if (replyToAsk !== undefined) {
20715
20790
  const askState = comment.ask_waiting_on === undefined ? "" : `; ask now waiting on ${comment.ask_waiting_on}`;
20791
+ const moved = requestedTurn !== "agent" && comment.ask_waiting_on === "agent" ? await movedApprovalLine(client, replyToAsk) : undefined;
20716
20792
  return {
20717
20793
  text: [
20718
20794
  `Replied on ask ${replyToAsk} (comment ${comment.id}${askState}). ${await followsAsk(commentOwner, input.subscriptions)}`,
20795
+ ...moved === undefined ? [] : [moved],
20719
20796
  ...adviceLines
20720
20797
  ].join(`
20721
20798
  `),
@@ -21186,6 +21263,19 @@ ${handoff.body}`,
21186
21263
  }
21187
21264
  };
21188
21265
  }
21266
+ const projectOwner = documentOwner();
21267
+ if (projectOwner.kind === "project" && optionalString(args, "artifact") === undefined) {
21268
+ const documents = await client.listProjectArtifacts(projectOwner.project, true);
21269
+ return {
21270
+ text: [
21271
+ `Project: ${projectOwner.project}`,
21272
+ "Documents:",
21273
+ ...documentListLines(documents)
21274
+ ].join(`
21275
+ `),
21276
+ details: { project: projectOwner.project }
21277
+ };
21278
+ }
21189
21279
  const documentReference = optionalString(args, "artifact");
21190
21280
  if (documentOwner().kind === "project" || documentReference !== undefined) {
21191
21281
  const resolved = await resolveDocument(documentOwner(), documentReference);
package/dist/envoy.js CHANGED
@@ -30099,7 +30099,7 @@ var messageValidation = {
30099
30099
  },
30100
30100
  message: "issue is required unless in_reply_to names a message delivered to this session, which is the one message with no issue."
30101
30101
  };
30102
- var readOwner = documentOwnerValidation(true);
30102
+ var readOwner = documentOwnerValidation(false);
30103
30103
  var readValidation = {
30104
30104
  check: (value) => {
30105
30105
  const input = value;
@@ -30107,7 +30107,7 @@ var readValidation = {
30107
30107
  return readOwner.check(value);
30108
30108
  return input.issue === undefined && input.project === undefined && input.artifact === undefined && input.ref === undefined;
30109
30109
  },
30110
- message: `${readOwner.message} message stands alone: it names the conversation, so name no issue, project, artifact, or ref with it.`
30110
+ message: "Exactly one of issue and project is required; project alone lists its documents, and with artifact names one. " + "message stands alone: it names the conversation, so name no issue, project, artifact, or ref with it."
30111
30111
  };
30112
30112
  var ISSUE_COMPONENTS_MODES = ["inherit", "explicit", "none"];
30113
30113
  function componentsArgument(z) {
@@ -30366,7 +30366,7 @@ var dispatchToolSpecs = [
30366
30366
  body: z.string({ max: DISPATCH_BODY_MAX }).describe(`Review comment, at most ${DISPATCH_BODY_MAX} characters.`),
30367
30367
  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(),
30368
30368
  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(),
30369
- 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(),
30369
+ 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'. human does not " + "apply to an approval request a newer version moved: it stays with you until dispatch " + "request-approval hands it back at the current version.").optional(),
30370
30370
  images: imagesArgument(z, "the issue (or the project document's project)", `the ${DISPATCH_BODY_MAX}-character body limit`)
30371
30371
  }),
30372
30372
  validation: commentValidation
@@ -30490,7 +30490,7 @@ var dispatchToolSpecs = [
30490
30490
  {
30491
30491
  name: "dispatch_read",
30492
30492
  example: { issue: "DSP-1" },
30493
- 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,
30493
+ 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), project plus artifact, or project alone, which lists the project's documents on no issue and nothing more; 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 issue read lists every document, picture and file the issue holds under `Documents:`, each by slug, filename and kind. " + "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,
30494
30494
  arguments: (z) => ({
30495
30495
  issue: z.string().describe(ISSUE_REFERENCE).optional(),
30496
30496
  project: z.string().describe("Project key owning the document.").optional(),
@@ -37191,7 +37191,7 @@ async function resolveArtifact(client, owner, artifactReference, { canonical = f
37191
37191
  const artifacts = routed === undefined ? unlinked : [routed, ...unlinked.filter((candidate) => candidate.id !== routed.id)];
37192
37192
  return {
37193
37193
  owner,
37194
- artifact: artifactByReference(artifacts, artifactReference, "project", canonical)
37194
+ artifact: artifactByReference(artifacts, artifactReference, owner, canonical)
37195
37195
  };
37196
37196
  }
37197
37197
  const issue = await client.getIssue(owner.issue);
@@ -37199,10 +37199,13 @@ async function resolveArtifact(client, owner, artifactReference, { canonical = f
37199
37199
  if (artifactReference === undefined || artifactReference === "spec") {
37200
37200
  artifact = issue.artifacts.find((candidate) => candidate.primary || candidate.id === issue.primary_artifact_id);
37201
37201
  } else {
37202
- artifact = artifactByReference(issue.artifacts, artifactReference, "issue", canonical);
37202
+ artifact = artifactByReference(issue.artifacts, artifactReference, { kind: "issue", issue: issue.key }, canonical);
37203
37203
  }
37204
37204
  if (!artifact) {
37205
- throw new DocumentNotFoundError(documentReferenceProblem(artifactReference ?? "spec", issue.artifacts, "issue"));
37205
+ throw new DocumentNotFoundError(documentReferenceProblem(artifactReference ?? "spec", issue.artifacts, {
37206
+ kind: "issue",
37207
+ issue: issue.key
37208
+ }));
37206
37209
  }
37207
37210
  return { owner, issue, artifact };
37208
37211
  }
@@ -37223,9 +37226,64 @@ async function documentTargets(client, resolution) {
37223
37226
  }
37224
37227
  var documentHintLimit = 8;
37225
37228
  function documentReferenceProblem(reference, documents, owner, ambiguous = false) {
37226
- const hints = documents.slice(0, documentHintLimit).map((document) => `${document.slug} (${document.name})`);
37229
+ const scope = owner.kind;
37230
+ const busy = !ambiguous && documents.length > documentHintLimit;
37231
+ const hints = (busy ? documentsNearest(reference, documents) : documents).slice(0, documentHintLimit).map((document) => `${document.slug} (${document.name})`);
37227
37232
  const list = hints.length === 0 ? "none" : hints.join(", ");
37228
- return ambiguous ? `"${reference}" names ${documents.length} documents on this ${owner}; use a slug: ${list}` : `document "${reference}" not found by slug; this ${owner}'s documents: ${list}`;
37233
+ if (busy) {
37234
+ const read = owner.kind === "issue" ? `dispatch read --issue ${owner.issue}` : `dispatch read --project ${owner.project}`;
37235
+ const counted = documents.every((document) => (document.kind ?? "doc") === "doc") ? "documents" : "documents and files";
37236
+ return `document "${reference}" not found by slug; this ${scope}'s ${documents.length} ${counted} include: ${list}; ${read} lists them all`;
37237
+ }
37238
+ return ambiguous ? `"${reference}" names ${documents.length} documents on this ${scope}; use a slug: ${list}` : `document "${reference}" not found by slug; this ${scope}'s documents: ${list}`;
37239
+ }
37240
+ function documentsNearest(reference, documents) {
37241
+ return documents.map((document, index) => ({
37242
+ document,
37243
+ index,
37244
+ ...documentCloseness(reference, document.slug, document.name)
37245
+ })).sort((a, b) => {
37246
+ if (a.near !== b.near)
37247
+ return a.near ? -1 : 1;
37248
+ if (a.near && a.distance !== b.distance)
37249
+ return a.distance - b.distance;
37250
+ return b.index - a.index;
37251
+ }).map(({ document }) => document);
37252
+ }
37253
+ function documentCloseness(reference, slug, name) {
37254
+ const wanted = [...reference.replace(/[A-Z]/g, (letter) => letter.toLowerCase())];
37255
+ const limit = Math.max(2, Math.floor(wanted.length / 3));
37256
+ let distance = Number.POSITIVE_INFINITY;
37257
+ for (const candidate of [slug, name]) {
37258
+ const label = [...candidate.replace(/[A-Z]/g, (letter) => letter.toLowerCase())];
37259
+ let edits = boundedEditDistance(wanted, label, limit);
37260
+ if (wanted.length >= 4 && label.join("").includes(wanted.join("")) || label.length >= 4 && wanted.join("").includes(label.join(""))) {
37261
+ edits = Math.abs(label.length - wanted.length);
37262
+ } else if (edits > limit) {
37263
+ continue;
37264
+ }
37265
+ distance = Math.min(distance, edits);
37266
+ }
37267
+ return distance === Number.POSITIVE_INFINITY ? { distance: limit + 1, near: false } : { distance, near: true };
37268
+ }
37269
+ function boundedEditDistance(a, b, limit) {
37270
+ if (Math.abs(a.length - b.length) > limit)
37271
+ return limit + 1;
37272
+ let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
37273
+ let current = new Array(b.length + 1).fill(0);
37274
+ for (let i = 1;i <= a.length; i++) {
37275
+ current[0] = i;
37276
+ let smallest = i;
37277
+ for (let j = 1;j <= b.length; j++) {
37278
+ const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
37279
+ current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, substitution);
37280
+ smallest = Math.min(smallest, current[j]);
37281
+ }
37282
+ if (smallest > limit)
37283
+ return limit + 1;
37284
+ [previous, current] = [current, previous];
37285
+ }
37286
+ return Math.min(previous[b.length], limit + 1);
37229
37287
  }
37230
37288
  async function liveBlocks(client, artifact) {
37231
37289
  const before = await client.docRead(artifact.id);
@@ -38201,7 +38259,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
38201
38259
 
38202
38260
  // package.json
38203
38261
  var name = "@sjawhar/pi-envoy";
38204
- var version2 = "15.1.2";
38262
+ var version2 = "15.1.3";
38205
38263
  var package_default = {
38206
38264
  name,
38207
38265
  version: version2,
@@ -25,12 +25,12 @@ 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; never repeat it in each message.
28
+ - An open ask is the request; never repeat it per 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
- - 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.
30
+ - Reply on an open ask with `dispatch comment --reply-to-ask`; `--turn agent` for a note needing nothing. An approval request a newer version moved needs `request-approval` again.
31
31
  - When an answer's option and text disagree, the text wins.
32
32
  - 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.
33
- - An ask reaches the issue's assignee. On an unassigned issue, name who must answer.
33
+ - An ask reaches the issue's assignee; if none, name who answers.
34
34
 
35
35
  ## Choosing what to work on
36
36
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "15.1.2",
3
+ "version": "15.1.3",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {