@sjawhar/pi-envoy 16.40.0 → 16.41.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
@@ -14710,6 +14710,9 @@ var askEventPayloadFields = {
14710
14710
  actor: object({ kind: string2().optional(), id: string2().optional() }).passthrough().optional(),
14711
14711
  at: string2().optional()
14712
14712
  }).nullish(),
14713
+ asked_of: string2().nullish(),
14714
+ asked_of_by: string2().nullish(),
14715
+ asked_of_at: string2().nullish(),
14713
14716
  thread_logins: array(string2()).optional()
14714
14717
  };
14715
14718
  var AskEventPayloadSchema = intersection(object(askEventPayloadFields), object({
@@ -15025,6 +15028,8 @@ var BOARD_NEIGHBOUR_REFUSAL = "The server refuses a key that does not exist, one
15025
15028
  var OWNER_REFERENCE = "Exactly one of issue and project is required. An issue is a native KEY or external owner/repo#n reference; a project is a project key such as CORE and addresses an unlinked project document named by artifact.";
15026
15029
  var ASK_QUESTION_CONTRACT = "The question names the concrete case first: which machines, files, sessions or people, and the " + "numbers. It asks the choice in those terms, saying what happens to whom under each option " + '("Ship Friday and risk signing out 1,240 users, or hold to Monday?"), never "How should we ' + 'proceed?" or "Which option?", because a reader cannot work back from a general question to ' + "the case. It carries every fact the reader needs to decide and nothing " + "that does not change the decision. Generalize only after the specifics, if at all. Then give " + "your recommendation and its reason.";
15027
15030
  var ASK_OPTIONS_CONTRACT = "Options carry the genuinely different approaches. Each option has a label, and its description " + "says what that approach costs.";
15031
+ var ASK_IS_FOR_A_PERSON = "An ask is a question for a person, never a request to another agent. Ask an agent by envoy_send or a comment on the issue.";
15032
+ var ASK_WAITS_ON_THE_ASSIGNEE = "An ask waits on the issue's assignee until a person hands it on. No agent can hand one on.";
15028
15033
  var HUMAN_AGREED_TO_DOCUMENT = "the human has agreed to every point in the document";
15029
15034
  function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false) {
15030
15035
  return {
@@ -15105,7 +15110,7 @@ var commentValidation = {
15105
15110
  message: `${commentOwner.message} ${COMMENT_TURN_RULE}`,
15106
15111
  refusal: (value) => commentProblem(value) ?? `${commentOwner.message} ${COMMENT_TURN_RULE}`
15107
15112
  };
15108
- var ISSUE_UPDATE_FIELDS_RULE = "Issue update requires at least one field besides issue: status, title, labels, priority, external_links, route, parent, blocked_by, components, repo, before, or after.";
15113
+ var ISSUE_UPDATE_FIELDS_RULE = "Issue update requires at least one field besides issue: status, title, labels, priority, assignee, external_links, route, parent, blocked_by, components, repo, before, or after.";
15109
15114
  var ISSUE_UPDATE_DONE_RULE = "status done requires reason, a non-empty note saying why the issue is closing, posted on the issue before it closes so the close carries its note";
15110
15115
  var ISSUE_UPDATE_REASON_RULE = "reason goes only with status done";
15111
15116
  var ISSUE_UPDATE_RULE = `${ISSUE_UPDATE_FIELDS_RULE} ${ISSUE_UPDATE_DONE_RULE}; ${ISSUE_UPDATE_REASON_RULE}.`;
@@ -15119,7 +15124,7 @@ function issueUpdateProblem(value) {
15119
15124
  const status = typeof input.status === "string" ? `status ${input.status}` : "an update without status done";
15120
15125
  return `${ISSUE_UPDATE_REASON_RULE}: it is the note posted on the issue as it closes, and ${status} closes nothing. Drop reason, or set status done to close the issue.`;
15121
15126
  }
15122
- const changesAField = typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || typeof input.priority === "number" || input.priority === null || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string" || Array.isArray(input.blocked_by) || typeof input.components === "object" && input.components !== null || typeof input.repo === "string" || typeof input.before === "string" || typeof input.after === "string";
15127
+ const changesAField = typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || typeof input.priority === "number" || input.priority === null || typeof input.assignee === "string" || input.assignee === null || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string" || Array.isArray(input.blocked_by) || typeof input.components === "object" && input.components !== null || typeof input.repo === "string" || typeof input.before === "string" || typeof input.after === "string";
15123
15128
  return changesAField ? undefined : ISSUE_UPDATE_FIELDS_RULE;
15124
15129
  }
15125
15130
  var messageValidation = {
@@ -15251,7 +15256,7 @@ var dispatchToolSpecs = [
15251
15256
  priority: 1,
15252
15257
  before: "DSP-2"
15253
15258
  },
15254
- description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, set " + "its priority, link a URL (the pull request that delivers it, a run, a document), set its " + "route, set or clear its parent, replace the issues it is blocked by, attach it to " + "architecture components, set the repository it targets, or move it on its project's " + "board. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. A non-empty external_links is " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link; an empty external_links removes every link instead. components " + "replaces the issue's own attachment. Closing an issue " + "(status done) requires reason, the note that says why: it is posted on the issue as a " + "message, then the issue closes, so the close carries its note; closing an issue that is " + "already closed is refused (ISSUE_CLOSED) before anything is posted. Reason goes only " + "with status done. Closing an issue withdraws every open ask " + "it holds (resolution kind withdrawn, naming the closer), and reopening it brings exactly " + "those asks back. " + "A closed issue still takes messages and comments, though not asks or artifacts; of this " + "tool's fields it takes only a board move " + "(before, after), components, " + "a reopening status (any status but done), and an external_links write that adds no new " + "link (so a link can move to the issue that replaced it); everything else, priority " + "included, waits for the reopen. " + "priority is yours to set and a human overrides it. before and after move the issue on " + "its project's board: before puts it above that issue, after below, and both together " + "land it between them. A project's board order is one agent's to keep; in a Legion " + "deployment that is the controller. Never reassign an issue a person holds to get a " + "faster answer: who holds it is their call. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
15259
+ description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, set " + "its priority, set or clear its assignee, link a URL (the pull request that delivers it, a " + "run, a document), set its " + "route, set or clear its parent, replace the issues it is blocked by, attach it to " + "architecture components, set the repository it targets, or move it on its project's " + "board. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. A non-empty external_links is " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link; an empty external_links removes every link instead. components " + "replaces the issue's own attachment. Closing an issue " + "(status done) requires reason, the note that says why: it is posted on the issue as a " + "message, then the issue closes, so the close carries its note; closing an issue that is " + "already closed is refused (ISSUE_CLOSED) before anything is posted. Reason goes only " + "with status done. Closing an issue withdraws every open ask " + "it holds (resolution kind withdrawn, naming the closer), and reopening it brings exactly " + "those asks back. " + "A closed issue still takes messages and comments, though not asks or artifacts; of this " + "tool's fields it takes only a board move " + "(before, after), components, " + "a reopening status (any status but done), and an external_links write that adds no new " + "link (so a link can move to the issue that replaced it); everything else, priority " + "included, waits for the reopen. " + "priority is yours to set and a human overrides it. assignee is the person who answers " + "this issue's asks, and every ask on it waits on them until a person hands that ask on. " + "Passing null unassigns the issue. Set the assignee when a person said who owns the work, as you " + "file the issue or hand it over. before and after move the issue on " + "its project's board: before puts it above that issue, after below, and both together " + "land it between them. A project's board order is one agent's to keep; in a Legion " + "deployment that is the controller. Never reassign an issue a person holds to get a " + "faster answer: who holds it is their call. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
15255
15260
  arguments: (z) => ({
15256
15261
  issue: z.string().describe(ISSUE_REFERENCE),
15257
15262
  status: z.enum(ISSUE_STATUSES).describe("New lifecycle status.").optional(),
@@ -15259,6 +15264,7 @@ var dispatchToolSpecs = [
15259
15264
  title: z.string({ min: 1, max: ISSUE_TITLE_MAX }).describe("Replacement title, at most 1,000 characters.").optional(),
15260
15265
  labels: z.array(z.string({ min: 1, max: 40 }), { max: 20 }).describe("Replacement label set, at most 20 labels of up to 40 characters; replaces every existing label.").optional(),
15261
15266
  priority: z.number({ int: true, min: 0, max: 3 }).nullable().optional().describe("Coarse priority: 0 is P0 (highest) through 3 is P3 (lowest); null clears it."),
15267
+ assignee: z.string().nullable().optional().describe("Email of the person who answers this issue's asks (someone who has signed in to Dispatch); null unassigns the issue. Set it only when a person said who owns the issue, never to move a question off the person holding it."),
15262
15268
  external_links: z.array(z.string({ min: 1 })).describe("URLs to link; a non-empty list merges into the issue's existing external links by URL, an empty list removes every link instead.").optional(),
15263
15269
  route: z.string().describe("Route the issue to role:<name> or session:<id>; an empty string clears it.").optional(),
15264
15270
  parent: z.string().describe("Parent issue key in the same project; an empty string clears the parent.").optional(),
@@ -15301,7 +15307,7 @@ var dispatchToolSpecs = [
15301
15307
  }
15302
15308
  ]
15303
15309
  },
15304
- description: "Open a to-do or permission only a human can give, or a decision that has no document to " + "live in. A question about the design an issue's document records is not this tool: write " + "it into that document as a decision block (dispatch doc-edit inserting an ask block at the " + "end of the section it concerns), at every phase, approved spec or not; the block reaches " + "the Inbox and its answer lands next to its context. Never give an ask an Approve option: a " + "document is approved through dispatch request-approval. Do not use this tool for a status " + "update or discussion; use dispatch message instead. Never create an issue to park a " + "question: the question is an ask on the issue it concerns. " + ASK_QUESTION_CONTRACT + " " + ASK_OPTIONS_CONTRACT + " For an action only a human can perform, state what it changes and risks as constraints. " + "Anything that requires a human to do, including a credential or grant renewal, is an ask, " + "never a message. Measure what you can first, and put the measurement and the size of the " + "population it covers in the question; drop an option that cannot fix most of that " + "population, never offer it cut down, and keep an option not to act (Hold). Set urgency high " + "when your work halts on the answer, and keep working on everything else. " + "Anchor a to-do about a document passage, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". ` + `A quote anchor is pinned to its block. ${ASK_BOUND_RULE} The lines images appends count ` + `toward that bound, and an ask has at most 8 options. ${RELATED_CHECK_RESULT} ` + `An ask among the related items says whether it is answered, by whom and with which options. ${OWNER_REFERENCE}`,
15310
+ description: `${ASK_IS_FOR_A_PERSON} ${ASK_WAITS_ON_THE_ASSIGNEE} ` + "Open a to-do or permission only a human can give, or a decision that has no document to " + "live in. A question about the design an issue's document records is not this tool: write " + "it into that document as a decision block (dispatch doc-edit inserting an ask block at the " + "end of the section it concerns), at every phase, approved spec or not; the block reaches " + "the Inbox and its answer lands next to its context. Never give an ask an Approve option: a " + "document is approved through dispatch request-approval. Do not use this tool for a status " + "update or discussion; use dispatch message instead. Never create an issue to park a " + "question: the question is an ask on the issue it concerns. " + ASK_QUESTION_CONTRACT + " " + ASK_OPTIONS_CONTRACT + " For an action only a human can perform, state what it changes and risks as constraints. " + "Anything that requires a human to do, including a credential or grant renewal, is an ask, " + "never a message. Measure what you can first, and put the measurement and the size of the " + "population it covers in the question; drop an option that cannot fix most of that " + "population, never offer it cut down, and keep an option not to act (Hold). Set urgency high " + "when your work halts on the answer, and keep working on everything else. " + "Anchor a to-do about a document passage, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". ` + `A quote anchor is pinned to its block. ${ASK_BOUND_RULE} The lines images appends count ` + `toward that bound, and an ask has at most 8 options. ${RELATED_CHECK_RESULT} ` + `An ask among the related items says whether it is answered, by whom and with which options. ${OWNER_REFERENCE}`,
15305
15311
  arguments: (z) => ({
15306
15312
  issue: z.string().describe(ISSUE_REFERENCE).optional(),
15307
15313
  project: z.string().describe("Project key owning the document.").optional(),
@@ -15339,7 +15345,7 @@ var dispatchToolSpecs = [
15339
15345
  }
15340
15346
  ]
15341
15347
  },
15342
- description: "Edit an open question in place. Use it to correct or refine the same decision; retract the " + "old ask and open a new one when the decision itself changes. " + ASK_QUESTION_CONTRACT + " " + ASK_OPTIONS_CONTRACT + " Previous text remains in the event log. Only the asking session can edit it; answered or " + "resolved asks cannot be edited. An ask that lives as an `ask` block in a document is written " + "in the document too, changing only the fields you name - pass urgency alone and the " + "question's wording, formatting, links and comment anchors are untouched - so the edit " + "writes a document version and closes a spec's design gate until that version is approved; " + "text the block cannot carry back unchanged is refused, naming the field - an option label " + 'containing ": ", the separator between a label and its description, is one example.',
15348
+ description: `${ASK_IS_FOR_A_PERSON} ${ASK_WAITS_ON_THE_ASSIGNEE} ` + "Edit an open question in place. Use it to correct or refine the same decision; retract the " + "old ask and open a new one when the decision itself changes. " + ASK_QUESTION_CONTRACT + " " + ASK_OPTIONS_CONTRACT + " Previous text remains in the event log. Only the asking session can edit it; answered or " + "resolved asks cannot be edited. An ask that lives as an `ask` block in a document is written " + "in the document too, changing only the fields you name - pass urgency alone and the " + "question's wording, formatting, links and comment anchors are untouched - so the edit " + "writes a document version and closes a spec's design gate until that version is approved; " + "text the block cannot carry back unchanged is refused, naming the field - an option label " + 'containing ": ", the separator between a label and its description, is one example.',
15343
15349
  arguments: (z) => ({
15344
15350
  ask: z.string().describe("Ask id (uuid); an 8+ hex prefix unique among this session's own open asks works too."),
15345
15351
  question: z.string().optional().describe(`${ASK_QUESTION_CONTRACT} Replaces the ask's question. ${ASK_BOUND_RULE}`),
@@ -19722,6 +19728,12 @@ function optionalString(args, name) {
19722
19728
  const value = args[name];
19723
19729
  return typeof value === "string" ? value : undefined;
19724
19730
  }
19731
+ function optionalNullableString(args, name) {
19732
+ const value = args[name];
19733
+ if (value === null)
19734
+ return null;
19735
+ return typeof value === "string" ? value : undefined;
19736
+ }
19725
19737
  function optionalBoolean(args, name) {
19726
19738
  const value = args[name];
19727
19739
  return typeof value === "boolean" ? value : undefined;
@@ -20919,6 +20931,8 @@ function eventHead(event) {
20919
20931
  const previousAnswer = event.payload.previous_answer;
20920
20932
  return `${textHead(event.payload.question)} -> ${textHead(askAnswerText(event.payload.answer))}${previousAnswer === undefined ? "" : ` (was: ${textHead(askAnswerText(previousAnswer))})`}`;
20921
20933
  }
20934
+ case "ask.asked_of":
20935
+ return `${textHead(event.payload.question)} -> asked of ${event.payload.asked_of ?? "the assignee of its issue"}`;
20922
20936
  case "comment.created":
20923
20937
  case "comment.answered":
20924
20938
  case "comment.anchor_refreshed":
@@ -21057,9 +21071,13 @@ function openAskAge(ageSeconds) {
21057
21071
  const days = Math.floor(hours / 24);
21058
21072
  return `${days}d${hours % 24 === 0 ? "" : ` ${hours % 24}h`}`;
21059
21073
  }
21074
+ function openAskAskedOf(ask) {
21075
+ const person = ask.waiting_on_person;
21076
+ return person === undefined || person === "" ? "nobody" : person;
21077
+ }
21060
21078
  function openAskLine(ask, baseUrl) {
21061
21079
  const priority = ask.priority === null ? "" : `P${ask.priority} \xB7 `;
21062
- return `- ${openAskAge(ask.age_seconds)} \xB7 ${priority}${ownerTitle(ask.owner)} \xB7 ${ask.question} \xB7 ${new URL(ask.ref, baseUrl).toString()}`;
21080
+ return `- ${openAskAge(ask.age_seconds)} \xB7 ${priority}${ownerTitle(ask.owner)} \xB7 asked of ${openAskAskedOf(ask)} \xB7 ${ask.question} \xB7 ${new URL(ask.ref, baseUrl).toString()}`;
21063
21081
  }
21064
21082
  function formatOpenAsksSummary(response, baseUrl) {
21065
21083
  const scope = "active open asks you authored on open issues and project documents";
@@ -21810,6 +21828,7 @@ async function executeDispatchTool(input) {
21810
21828
  const rankBefore = optionalString(args, "before");
21811
21829
  const rankAfter = optionalString(args, "after");
21812
21830
  const priority = optionalPriority(args, "priority");
21831
+ const assignee = optionalNullableString(args, "assignee");
21813
21832
  const labels = Array.isArray(args.labels) ? args.labels : undefined;
21814
21833
  const blockedBy = Array.isArray(args.blocked_by) ? args.blocked_by : undefined;
21815
21834
  const requestedLinks = Array.isArray(args.external_links) ? [...new Set(args.external_links)] : undefined;
@@ -21855,6 +21874,7 @@ async function executeDispatchTool(input) {
21855
21874
  ...title === undefined ? {} : { title },
21856
21875
  ...labels === undefined ? {} : { labels },
21857
21876
  ...priority === undefined ? {} : { priority },
21877
+ ...assignee === undefined ? {} : { assignee },
21858
21878
  ...route === undefined ? {} : { route },
21859
21879
  ...parent === undefined ? {} : { parent: parent === "" ? null : parent },
21860
21880
  ...blockedBy === undefined ? {} : { blocked_by: blockedBy },
@@ -21888,6 +21908,7 @@ async function executeDispatchTool(input) {
21888
21908
  (after.labels ?? []).length === 0 ? "labels cleared" : `labels ${(after.labels ?? []).join(", ")}`
21889
21909
  ],
21890
21910
  ...priority === undefined ? [] : [after.priority === null ? "priority cleared" : `priority -> P${after.priority}`],
21911
+ ...assignee === undefined ? [] : [after.assignee === null ? "assignee cleared" : `assignee -> ${after.assignee}`],
21891
21912
  ...rank === undefined ? [] : [
21892
21913
  `rank -> ${[
21893
21914
  ...rankAfter === undefined ? [] : [`after ${rankAfter}`],
package/dist/envoy.js CHANGED
@@ -29799,6 +29799,9 @@ var askEventPayloadFields = {
29799
29799
  actor: object({ kind: string2().optional(), id: string2().optional() }).passthrough().optional(),
29800
29800
  at: string2().optional()
29801
29801
  }).nullish(),
29802
+ asked_of: string2().nullish(),
29803
+ asked_of_by: string2().nullish(),
29804
+ asked_of_at: string2().nullish(),
29802
29805
  thread_logins: array(string2()).optional()
29803
29806
  };
29804
29807
  var AskEventPayloadSchema = intersection(object(askEventPayloadFields), object({
@@ -30064,6 +30067,8 @@ var BOARD_NEIGHBOUR_REFUSAL = "The server refuses a key that does not exist, one
30064
30067
  var OWNER_REFERENCE = "Exactly one of issue and project is required. An issue is a native KEY or external owner/repo#n reference; a project is a project key such as CORE and addresses an unlinked project document named by artifact.";
30065
30068
  var ASK_QUESTION_CONTRACT = "The question names the concrete case first: which machines, files, sessions or people, and the " + "numbers. It asks the choice in those terms, saying what happens to whom under each option " + '("Ship Friday and risk signing out 1,240 users, or hold to Monday?"), never "How should we ' + 'proceed?" or "Which option?", because a reader cannot work back from a general question to ' + "the case. It carries every fact the reader needs to decide and nothing " + "that does not change the decision. Generalize only after the specifics, if at all. Then give " + "your recommendation and its reason.";
30066
30069
  var ASK_OPTIONS_CONTRACT = "Options carry the genuinely different approaches. Each option has a label, and its description " + "says what that approach costs.";
30070
+ var ASK_IS_FOR_A_PERSON = "An ask is a question for a person, never a request to another agent. Ask an agent by envoy_send or a comment on the issue.";
30071
+ var ASK_WAITS_ON_THE_ASSIGNEE = "An ask waits on the issue's assignee until a person hands it on. No agent can hand one on.";
30067
30072
  var HUMAN_AGREED_TO_DOCUMENT = "the human has agreed to every point in the document";
30068
30073
  function documentOwnerValidation(requireArtifact, alwaysRequireArtifact = false) {
30069
30074
  return {
@@ -30144,7 +30149,7 @@ var commentValidation = {
30144
30149
  message: `${commentOwner.message} ${COMMENT_TURN_RULE}`,
30145
30150
  refusal: (value) => commentProblem(value) ?? `${commentOwner.message} ${COMMENT_TURN_RULE}`
30146
30151
  };
30147
- var ISSUE_UPDATE_FIELDS_RULE = "Issue update requires at least one field besides issue: status, title, labels, priority, external_links, route, parent, blocked_by, components, repo, before, or after.";
30152
+ var ISSUE_UPDATE_FIELDS_RULE = "Issue update requires at least one field besides issue: status, title, labels, priority, assignee, external_links, route, parent, blocked_by, components, repo, before, or after.";
30148
30153
  var ISSUE_UPDATE_DONE_RULE = "status done requires reason, a non-empty note saying why the issue is closing, posted on the issue before it closes so the close carries its note";
30149
30154
  var ISSUE_UPDATE_REASON_RULE = "reason goes only with status done";
30150
30155
  var ISSUE_UPDATE_RULE = `${ISSUE_UPDATE_FIELDS_RULE} ${ISSUE_UPDATE_DONE_RULE}; ${ISSUE_UPDATE_REASON_RULE}.`;
@@ -30158,7 +30163,7 @@ function issueUpdateProblem(value) {
30158
30163
  const status = typeof input.status === "string" ? `status ${input.status}` : "an update without status done";
30159
30164
  return `${ISSUE_UPDATE_REASON_RULE}: it is the note posted on the issue as it closes, and ${status} closes nothing. Drop reason, or set status done to close the issue.`;
30160
30165
  }
30161
- const changesAField = typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || typeof input.priority === "number" || input.priority === null || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string" || Array.isArray(input.blocked_by) || typeof input.components === "object" && input.components !== null || typeof input.repo === "string" || typeof input.before === "string" || typeof input.after === "string";
30166
+ const changesAField = typeof input.status === "string" || typeof input.title === "string" || Array.isArray(input.labels) || typeof input.priority === "number" || input.priority === null || typeof input.assignee === "string" || input.assignee === null || Array.isArray(input.external_links) || typeof input.route === "string" || typeof input.parent === "string" || Array.isArray(input.blocked_by) || typeof input.components === "object" && input.components !== null || typeof input.repo === "string" || typeof input.before === "string" || typeof input.after === "string";
30162
30167
  return changesAField ? undefined : ISSUE_UPDATE_FIELDS_RULE;
30163
30168
  }
30164
30169
  var messageValidation = {
@@ -30290,7 +30295,7 @@ var dispatchToolSpecs = [
30290
30295
  priority: 1,
30291
30296
  before: "DSP-2"
30292
30297
  },
30293
- description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, set " + "its priority, link a URL (the pull request that delivers it, a run, a document), set its " + "route, set or clear its parent, replace the issues it is blocked by, attach it to " + "architecture components, set the repository it targets, or move it on its project's " + "board. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. A non-empty external_links is " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link; an empty external_links removes every link instead. components " + "replaces the issue's own attachment. Closing an issue " + "(status done) requires reason, the note that says why: it is posted on the issue as a " + "message, then the issue closes, so the close carries its note; closing an issue that is " + "already closed is refused (ISSUE_CLOSED) before anything is posted. Reason goes only " + "with status done. Closing an issue withdraws every open ask " + "it holds (resolution kind withdrawn, naming the closer), and reopening it brings exactly " + "those asks back. " + "A closed issue still takes messages and comments, though not asks or artifacts; of this " + "tool's fields it takes only a board move " + "(before, after), components, " + "a reopening status (any status but done), and an external_links write that adds no new " + "link (so a link can move to the issue that replaced it); everything else, priority " + "included, waits for the reopen. " + "priority is yours to set and a human overrides it. before and after move the issue on " + "its project's board: before puts it above that issue, after below, and both together " + "land it between them. A project's board order is one agent's to keep; in a Legion " + "deployment that is the controller. Never reassign an issue a person holds to get a " + "faster answer: who holds it is their call. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
30298
+ description: "Update an existing issue: move its lifecycle status, retitle it, replace its labels, set " + "its priority, set or clear its assignee, link a URL (the pull request that delivers it, a " + "run, a document), set its " + "route, set or clear its parent, replace the issues it is blocked by, attach it to " + "architecture components, set the repository it targets, or move it on its project's " + "board. Status is one of " + `${ISSUE_STATUSES.join(", ")}; outside Legion, move it yourself as the work advances; inside ` + "Legion the daemon moves it. A non-empty external_links is " + "merged into the issue's existing links by URL, so linking the pull request you just opened " + "keeps every earlier link; an empty external_links removes every link instead. components " + "replaces the issue's own attachment. Closing an issue " + "(status done) requires reason, the note that says why: it is posted on the issue as a " + "message, then the issue closes, so the close carries its note; closing an issue that is " + "already closed is refused (ISSUE_CLOSED) before anything is posted. Reason goes only " + "with status done. Closing an issue withdraws every open ask " + "it holds (resolution kind withdrawn, naming the closer), and reopening it brings exactly " + "those asks back. " + "A closed issue still takes messages and comments, though not asks or artifacts; of this " + "tool's fields it takes only a board move " + "(before, after), components, " + "a reopening status (any status but done), and an external_links write that adds no new " + "link (so a link can move to the issue that replaced it); everything else, priority " + "included, waits for the reopen. " + "priority is yours to set and a human overrides it. assignee is the person who answers " + "this issue's asks, and every ask on it waits on them until a person hands that ask on. " + "Passing null unassigns the issue. Set the assignee when a person said who owns the work, as you " + "file the issue or hand it over. before and after move the issue on " + "its project's board: before puts it above that issue, after below, and both together " + "land it between them. A project's board order is one agent's to keep; in a Legion " + "deployment that is the controller. Never reassign an issue a person holds to get a " + "faster answer: who holds it is their call. At least one " + `field besides issue is required. ${ISSUE_REFERENCE}`,
30294
30299
  arguments: (z) => ({
30295
30300
  issue: z.string().describe(ISSUE_REFERENCE),
30296
30301
  status: z.enum(ISSUE_STATUSES).describe("New lifecycle status.").optional(),
@@ -30298,6 +30303,7 @@ var dispatchToolSpecs = [
30298
30303
  title: z.string({ min: 1, max: ISSUE_TITLE_MAX }).describe("Replacement title, at most 1,000 characters.").optional(),
30299
30304
  labels: z.array(z.string({ min: 1, max: 40 }), { max: 20 }).describe("Replacement label set, at most 20 labels of up to 40 characters; replaces every existing label.").optional(),
30300
30305
  priority: z.number({ int: true, min: 0, max: 3 }).nullable().optional().describe("Coarse priority: 0 is P0 (highest) through 3 is P3 (lowest); null clears it."),
30306
+ assignee: z.string().nullable().optional().describe("Email of the person who answers this issue's asks (someone who has signed in to Dispatch); null unassigns the issue. Set it only when a person said who owns the issue, never to move a question off the person holding it."),
30301
30307
  external_links: z.array(z.string({ min: 1 })).describe("URLs to link; a non-empty list merges into the issue's existing external links by URL, an empty list removes every link instead.").optional(),
30302
30308
  route: z.string().describe("Route the issue to role:<name> or session:<id>; an empty string clears it.").optional(),
30303
30309
  parent: z.string().describe("Parent issue key in the same project; an empty string clears the parent.").optional(),
@@ -30340,7 +30346,7 @@ var dispatchToolSpecs = [
30340
30346
  }
30341
30347
  ]
30342
30348
  },
30343
- description: "Open a to-do or permission only a human can give, or a decision that has no document to " + "live in. A question about the design an issue's document records is not this tool: write " + "it into that document as a decision block (dispatch doc-edit inserting an ask block at the " + "end of the section it concerns), at every phase, approved spec or not; the block reaches " + "the Inbox and its answer lands next to its context. Never give an ask an Approve option: a " + "document is approved through dispatch request-approval. Do not use this tool for a status " + "update or discussion; use dispatch message instead. Never create an issue to park a " + "question: the question is an ask on the issue it concerns. " + ASK_QUESTION_CONTRACT + " " + ASK_OPTIONS_CONTRACT + " For an action only a human can perform, state what it changes and risks as constraints. " + "Anything that requires a human to do, including a credential or grant renewal, is an ask, " + "never a message. Measure what you can first, and put the measurement and the size of the " + "population it covers in the question; drop an option that cannot fix most of that " + "population, never offer it cut down, and keep an option not to act (Hold). Set urgency high " + "when your work halts on the answer, and keep working on everything else. " + "Anchor a to-do about a document passage, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". ` + `A quote anchor is pinned to its block. ${ASK_BOUND_RULE} The lines images appends count ` + `toward that bound, and an ask has at most 8 options. ${RELATED_CHECK_RESULT} ` + `An ask among the related items says whether it is answered, by whom and with which options. ${OWNER_REFERENCE}`,
30349
+ description: `${ASK_IS_FOR_A_PERSON} ${ASK_WAITS_ON_THE_ASSIGNEE} ` + "Open a to-do or permission only a human can give, or a decision that has no document to " + "live in. A question about the design an issue's document records is not this tool: write " + "it into that document as a decision block (dispatch doc-edit inserting an ask block at the " + "end of the section it concerns), at every phase, approved spec or not; the block reaches " + "the Inbox and its answer lands next to its context. Never give an ask an Approve option: a " + "document is approved through dispatch request-approval. Do not use this tool for a status " + "update or discussion; use dispatch message instead. Never create an issue to park a " + "question: the question is an ask on the issue it concerns. " + ASK_QUESTION_CONTRACT + " " + ASK_OPTIONS_CONTRACT + " For an action only a human can perform, state what it changes and risks as constraints. " + "Anything that requires a human to do, including a credential or grant renewal, is an ask, " + "never a message. Measure what you can first, and put the measurement and the size of the " + "population it covers in the question; drop an option that cannot fix most of that " + "population, never offer it cut down, and keep an option not to act (Hold). Set urgency high " + "when your work halts on the answer, and keep working on everything else. " + "Anchor a to-do about a document passage, thread reply_to/reply_to_ask, or cite a dispatch:// " + `reference \u2014 it must be answerable from its own text and anchor alone, never "see above". ` + `A quote anchor is pinned to its block. ${ASK_BOUND_RULE} The lines images appends count ` + `toward that bound, and an ask has at most 8 options. ${RELATED_CHECK_RESULT} ` + `An ask among the related items says whether it is answered, by whom and with which options. ${OWNER_REFERENCE}`,
30344
30350
  arguments: (z) => ({
30345
30351
  issue: z.string().describe(ISSUE_REFERENCE).optional(),
30346
30352
  project: z.string().describe("Project key owning the document.").optional(),
@@ -30378,7 +30384,7 @@ var dispatchToolSpecs = [
30378
30384
  }
30379
30385
  ]
30380
30386
  },
30381
- description: "Edit an open question in place. Use it to correct or refine the same decision; retract the " + "old ask and open a new one when the decision itself changes. " + ASK_QUESTION_CONTRACT + " " + ASK_OPTIONS_CONTRACT + " Previous text remains in the event log. Only the asking session can edit it; answered or " + "resolved asks cannot be edited. An ask that lives as an `ask` block in a document is written " + "in the document too, changing only the fields you name - pass urgency alone and the " + "question's wording, formatting, links and comment anchors are untouched - so the edit " + "writes a document version and closes a spec's design gate until that version is approved; " + "text the block cannot carry back unchanged is refused, naming the field - an option label " + 'containing ": ", the separator between a label and its description, is one example.',
30387
+ description: `${ASK_IS_FOR_A_PERSON} ${ASK_WAITS_ON_THE_ASSIGNEE} ` + "Edit an open question in place. Use it to correct or refine the same decision; retract the " + "old ask and open a new one when the decision itself changes. " + ASK_QUESTION_CONTRACT + " " + ASK_OPTIONS_CONTRACT + " Previous text remains in the event log. Only the asking session can edit it; answered or " + "resolved asks cannot be edited. An ask that lives as an `ask` block in a document is written " + "in the document too, changing only the fields you name - pass urgency alone and the " + "question's wording, formatting, links and comment anchors are untouched - so the edit " + "writes a document version and closes a spec's design gate until that version is approved; " + "text the block cannot carry back unchanged is refused, naming the field - an option label " + 'containing ": ", the separator between a label and its description, is one example.',
30382
30388
  arguments: (z) => ({
30383
30389
  ask: z.string().describe("Ask id (uuid); an 8+ hex prefix unique among this session's own open asks works too."),
30384
30390
  question: z.string().optional().describe(`${ASK_QUESTION_CONTRACT} Replaces the ask's question. ${ASK_BOUND_RULE}`),
@@ -36829,6 +36835,7 @@ var DISPATCH_PAYLOAD_SCHEMAS = {
36829
36835
  "ask.anchor_refreshed": AskEventPayloadSchema,
36830
36836
  "ask.edited": AskEditedEventPayloadSchema,
36831
36837
  "ask.handed_back": AskEventPayloadSchema,
36838
+ "ask.asked_of": AskEventPayloadSchema,
36832
36839
  "ask.answered": AskEventPayloadSchema,
36833
36840
  "ask.resolved": AskEventPayloadSchema,
36834
36841
  "comment.created": CommentEventPayloadSchema,
@@ -36948,6 +36955,15 @@ function dispatchCompact(event, comment) {
36948
36955
  };
36949
36956
  break;
36950
36957
  }
36958
+ case "ask.asked_of": {
36959
+ const handedOnBy = ask.data.asked_of_by;
36960
+ record = {
36961
+ ...record,
36962
+ asked_of: ask.data.asked_of ?? "the assignee of its issue",
36963
+ ...handedOnBy === null || handedOnBy === undefined || handedOnBy === "" ? {} : { handed_on_by: handedOnBy }
36964
+ };
36965
+ break;
36966
+ }
36951
36967
  case "ask.resolved": {
36952
36968
  const resolved = askResolutionText(ask.data.resolution);
36953
36969
  record = resolved === undefined ? record : { ...record, resolved };
@@ -42697,7 +42713,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
42697
42713
 
42698
42714
  // package.json
42699
42715
  var name = "@sjawhar/pi-envoy";
42700
- var version2 = "16.40.0";
42716
+ var version2 = "16.41.0";
42701
42717
  var package_default = {
42702
42718
  name,
42703
42719
  version: version2,
@@ -14,24 +14,23 @@ Dispatch is a record for the people who decide, never a log of your work.
14
14
 
15
15
  ## Asks and ask blocks
16
16
 
17
- - A design question a document records is an ask block (a decision block) at the end of its section:
17
+ - An ask is a question for a person, never a request to another agent. Ask an agent by envoy_send or a comment on the issue.
18
+ - An ask waits on the issue's assignee until a person hands it on. No agent can hand one on.
19
+ - A design question a document records is an ask block at the end of its section:
18
20
 
19
21
  ```md
20
22
  :::ask{urgency="med"}
21
- The question and the recommendation, as `skill://dispatch-writing-specs` writes them.
23
+ The question and the recommendation (`skill://dispatch-writing-specs`).
22
24
 
23
25
  - Option one: what it costs.
24
26
  - Option two: what it costs.
25
27
  :::
26
28
  ```
27
29
 
28
- - An ask is short and asks one thing; its reasoning goes in the document.
29
- - An open ask is the request; never repeat it per message.
30
- - 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
+ - Never repeat an open ask in a message.
31
+ - Change an open ask's block with `dispatch edit-ask` (its ask id), or `doc-edit`'s `replace` or `move` (its block id). An answered ask is fixed: ask anew. `dispatch read --ref` takes either id.
31
32
  - Reply on an open ask with `dispatch comment --reply-to-ask`; `--turn agent` (a progress note) needs it. An approval request a newer version moved needs `request-approval` again.
32
33
  - When an answer's option and text disagree, the text wins.
33
- - 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.
34
- - An ask reaches the issue's assignee; if none, name who answers.
35
34
 
36
35
  ## Choosing what to work on
37
36
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "16.40.0",
3
+ "version": "16.41.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {