@sjawhar/pi-envoy 16.37.1 → 16.38.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
@@ -278,7 +278,7 @@ messages; with Envoy on and no NATS server, or with its NATS seed refused (a see
278
278
  other servers, a failing `natsSeed` command, a seed variable that cannot be read), it keeps the
279
279
  tools and `/whoami`, takes no inbound messages, connects to no NATS server, and refuses
280
280
  `envoy_subscribe` and the Legion role claim with `inbound messages are off for this session: <why>`,
281
- the claim before any listener call, so a Legion process fails its boot rather than hold a role
281
+ the claim before any listener call, so a Legion process stops rather than hold a role
282
282
  whose tasks reach nobody. When a
283
283
  section is off for a reason worth saying, the session says so once at its start:
284
284
  `envoy: no envoy.json at <path>: Dispatch and Envoy are off`, the lost `DISPATCH_URL` when
package/dist/dispatch.js CHANGED
@@ -15432,6 +15432,22 @@ var dispatchToolSpecs = [
15432
15432
  }),
15433
15433
  validation: messageValidation
15434
15434
  },
15435
+ {
15436
+ name: "dispatch_send_to_agent",
15437
+ example: {
15438
+ session: "01234567-0000-4000-8000-000000000001",
15439
+ body: "DSP-1: the rota is nowhere written down. Please write it up.",
15440
+ delivery: "aside"
15441
+ },
15442
+ description: "Hand a piece of work to one agent session, in that session's own conversation, which belongs to no " + "issue: the way to reach the agent already on the work - the session holding an issue's claim, or one " + "you are working with. Name the issue in the body, because this message carries none. It is not how " + "you reach a person (dispatch message, or dispatch ask for something only a person can do), and not a " + "note on an issue (dispatch message --issue), which everyone reading that issue sees; this reaches that " + "one session. It spends that session a turn, so send once and read the reply with " + "dispatch read --message <id> rather than sending again. The call is answered once its first delivery " + "attempt has settled. It needs a credential holding the person scope, and one without it is refused " + `403 OAUTH_SCOPE_REQUIRED, naming the scope. ${BODY_BLOCK_RULE}`,
15443
+ arguments: (z) => ({
15444
+ session: z.string({ min: 1 }).describe("The session to send to, by its bare session id. An issue's claim names the session holding it, " + "and dispatch whoami names this session's own."),
15445
+ body: z.string({ min: 1 }).describe(`The words the session reads. Name the issue they are about: this message carries none. ${BODY_BLOCK_RULE}`),
15446
+ delivery: z.enum(["btw", "aside", "steer"]).describe("How the words reach the session: btw waits for its next turn, aside reaches it while a turn " + "runs, and steer goes in as a keystroke at its terminal. A session advertises the modes it " + "takes, and Dispatch sends the mode you name rather than another."),
15447
+ in_reply_to: z.string().describe("Optional id of a message in this same session-to-session conversation, threading this message " + "under it; without it the message starts a conversation of its own.").optional()
15448
+ }),
15449
+ strict: true
15450
+ },
15435
15451
  {
15436
15452
  name: "dispatch_doc_edit",
15437
15453
  example: {
@@ -18124,6 +18140,9 @@ class DispatchClient {
18124
18140
  async message(issue, input) {
18125
18141
  return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "messages"], input);
18126
18142
  }
18143
+ async agentMessage(sessionId, input) {
18144
+ return this.#json("POST", ["api", "v1", "agents", sessionId, "messages"], input);
18145
+ }
18127
18146
  async messageReply(id, input, options = {}) {
18128
18147
  return this.#json("POST", ["api", "v1", "messages", id, "reply"], input, options.followUp === true ? { follow_up: "true" } : undefined);
18129
18148
  }
@@ -19836,6 +19855,9 @@ function itemBlockOf(value) {
19836
19855
  function article(kind) {
19837
19856
  return kind === "ask" ? "an ask" : `a ${kind}`;
19838
19857
  }
19858
+ function conversationReadBack(messageId) {
19859
+ return `${commandLine("dispatch_read", { message: messageId })} reads the conversation back.`;
19860
+ }
19839
19861
  function replyBlockProblem(field, kind, value) {
19840
19862
  if (!/^dispatch:\/\/[^#]*#b-/.test(value))
19841
19863
  return;
@@ -22255,7 +22277,7 @@ async function executeDispatchTool(input) {
22255
22277
  details: { message: reply.id, in_reply_to: inReplyTo, posted: false }
22256
22278
  };
22257
22279
  }
22258
- const readBack = `${commandLine("dispatch_read", { message: inReplyTo })} reads the conversation back.`;
22280
+ const readBack = conversationReadBack(inReplyTo);
22259
22281
  const parent = reply.in_reply_to ?? undefined;
22260
22282
  const follows = parent === inReplyTo ? undefined : parent;
22261
22283
  return {
@@ -22291,6 +22313,27 @@ async function executeDispatchTool(input) {
22291
22313
  }
22292
22314
  };
22293
22315
  }
22316
+ case "dispatch_send_to_agent": {
22317
+ const session = stringArg(args, "session");
22318
+ const inReplyTo = optionalString(args, "in_reply_to");
22319
+ const message = await client.agentMessage(session, {
22320
+ body: stringArg(args, "body"),
22321
+ delivery: stringArg(args, "delivery"),
22322
+ ...inReplyTo === undefined ? {} : { in_reply_to: inReplyTo }
22323
+ });
22324
+ const attempt = message.deliveries?.at(-1);
22325
+ const readBack = conversationReadBack(message.id);
22326
+ const arrival = attempt === undefined ? "Dispatch recorded no delivery attempt for it" : attempt.state === "failed" ? `its delivery failed: ${attempt.error ?? "the listener gave no reason"}` : attempt.state === "pending" ? "its delivery is still on its way" : `it reached that session as ${attempt.delivery}`;
22327
+ return {
22328
+ text: `Sent message ${message.id} to session ${session}; ${arrival}. ${readBack}`,
22329
+ details: {
22330
+ session,
22331
+ message: message.id,
22332
+ ...attempt === undefined ? {} : { delivery: attempt.state },
22333
+ ...inReplyTo === undefined ? {} : { in_reply_to: inReplyTo }
22334
+ }
22335
+ };
22336
+ }
22294
22337
  case "dispatch_doc_edit": {
22295
22338
  const resolved = await resolveDocument(documentOwner(), optionalString(args, "artifact"));
22296
22339
  const ops = args.ops;
package/dist/envoy.js CHANGED
@@ -30471,6 +30471,22 @@ var dispatchToolSpecs = [
30471
30471
  }),
30472
30472
  validation: messageValidation
30473
30473
  },
30474
+ {
30475
+ name: "dispatch_send_to_agent",
30476
+ example: {
30477
+ session: "01234567-0000-4000-8000-000000000001",
30478
+ body: "DSP-1: the rota is nowhere written down. Please write it up.",
30479
+ delivery: "aside"
30480
+ },
30481
+ description: "Hand a piece of work to one agent session, in that session's own conversation, which belongs to no " + "issue: the way to reach the agent already on the work - the session holding an issue's claim, or one " + "you are working with. Name the issue in the body, because this message carries none. It is not how " + "you reach a person (dispatch message, or dispatch ask for something only a person can do), and not a " + "note on an issue (dispatch message --issue), which everyone reading that issue sees; this reaches that " + "one session. It spends that session a turn, so send once and read the reply with " + "dispatch read --message <id> rather than sending again. The call is answered once its first delivery " + "attempt has settled. It needs a credential holding the person scope, and one without it is refused " + `403 OAUTH_SCOPE_REQUIRED, naming the scope. ${BODY_BLOCK_RULE}`,
30482
+ arguments: (z) => ({
30483
+ session: z.string({ min: 1 }).describe("The session to send to, by its bare session id. An issue's claim names the session holding it, " + "and dispatch whoami names this session's own."),
30484
+ body: z.string({ min: 1 }).describe(`The words the session reads. Name the issue they are about: this message carries none. ${BODY_BLOCK_RULE}`),
30485
+ delivery: z.enum(["btw", "aside", "steer"]).describe("How the words reach the session: btw waits for its next turn, aside reaches it while a turn " + "runs, and steer goes in as a keystroke at its terminal. A session advertises the modes it " + "takes, and Dispatch sends the mode you name rather than another."),
30486
+ in_reply_to: z.string().describe("Optional id of a message in this same session-to-session conversation, threading this message " + "under it; without it the message starts a conversation of its own.").optional()
30487
+ }),
30488
+ strict: true
30489
+ },
30474
30490
  {
30475
30491
  name: "dispatch_doc_edit",
30476
30492
  example: {
@@ -35923,6 +35939,9 @@ class DispatchClient {
35923
35939
  async message(issue, input) {
35924
35940
  return this.#json("POST", ["api", "v1", "issues", await this.#resolveIssue(issue), "messages"], input);
35925
35941
  }
35942
+ async agentMessage(sessionId, input) {
35943
+ return this.#json("POST", ["api", "v1", "agents", sessionId, "messages"], input);
35944
+ }
35926
35945
  async messageReply(id, input, options = {}) {
35927
35946
  return this.#json("POST", ["api", "v1", "messages", id, "reply"], input, options.followUp === true ? { follow_up: "true" } : undefined);
35928
35947
  }
@@ -42661,7 +42680,7 @@ var import_nats2 = __toESM(require_mod4(), 1);
42661
42680
 
42662
42681
  // package.json
42663
42682
  var name = "@sjawhar/pi-envoy";
42664
- var version2 = "16.37.1";
42683
+ var version2 = "16.38.1";
42665
42684
  var package_default = {
42666
42685
  name,
42667
42686
  version: version2,
@@ -80,4 +80,4 @@ Every topic starts with `notifications.`.
80
80
  - A message that must reach more than 4 role topics is the project controller's to send, not yours. Each publish wakes a session, and a woken session reads its whole context again, which the provider charges as uncached input: a mean of 576,083 tokens a wake, a median of 493,636 and a ninetieth percentile of 1,327,888. The controller is also the one session that can read whether a wave of wakes is already running, and a fan-out sent into a daemon restart or a pod roll is what puts an Anthropic organization over its per-minute uncached-input cap. Send the controller the topics and the text, and it sends them at its own rate (`skill://legion-controller`).
81
81
  - For a team, the group subscribes to `notifications.team.<name>.>`, and any member publishes to `notifications.team.<name>.all`. Envoy treats any other `notifications.` topic that no source in the table uses the same way. It reaches every session subscribed when it is published, yours too when you subscribe. The listener also asks each other session that holds its own NATS connection and registered the topic (every session that follows it with `envoy_subscribe`) to confirm the message; your own session is never asked. A publish returns an error naming each such session that did not confirm within about 4 seconds, and you see it after about 8 seconds, because the client tries once more. A session named with `receipt_timeout` still gets the message: the listener kept a copy in that session's inbox, which the session reads back once its connection returns. An `unresponsive` session is sent the message the same way, asked for no receipt and named under `unresponsive` in the answer, which is no failure. A session that stopped without unregistering stays in the registry until the reaper finds it `gone`, and is named until then; a named session is not a failed delivery to the others. A team topic is not kept for a session that subscribes later. A topic outside `notifications.` is refused.
82
82
  - How a role claim survives a resume, a fork or a dead process: `skill://envoy/references/roles.md`.
83
- - In a Legion pane, the plugin claims your role at session start; read `skill://envoy/references/legion.md` before you claim, release or publish to a role, or answer a role delivery failure there.
83
+ - In a Legion pane, the plugin claims your role for you, at your session's first turn; read `skill://envoy/references/legion.md` before you claim, release or publish to a role, or answer a role delivery failure there.
@@ -2,7 +2,7 @@
2
2
 
3
3
  Read this in a Legion pane before you touch a role claim, or when a Legion role message fails.
4
4
 
5
- - The Legion plugin claims your assigned role at session start through a daemon-minted role token. Never call `envoy_role_set` and never subscribe to your role topic yourself, because the claim is already made (`packages/pi-shared/src/legion-claim-core.ts`).
5
+ - The Legion plugin claims your assigned role for you, through a daemon-minted role token: it registers your session and reports it ready at session start, and takes the role at your first turn, or at a bound (30 s by default) when no turn comes first. Never call `envoy_role_set` and never subscribe to your role topic yourself, because the claim is already made (`packages/pi-shared/src/legion-claim-core.ts`).
6
6
  - Never build a role token from an issue number or title: only the daemon maps tokens to issues.
7
7
  - A Legion claim is last-claim-wins. It survives parking and worker re-creation, and stays through the issue's linger after close (the deployment's `linger_hours`).
8
8
  - `no_holder`, `holder_lapsed`, `delivery_failed` and `receipt_timeout` on a Legion role are the daemon's liveness signals. Never add a second subscriber or retry by hand: the daemon revives or recreates the worker and re-delivers, or relaunches the root process, which gets a `catch-up` notice of its tree and reads each issue's handoffs on its Dispatch issue (`dispatch handoff-read`).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-envoy",
3
- "version": "16.37.1",
3
+ "version": "16.38.1",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {