@sjawhar/pi-envoy 10.15.0 → 10.16.0

package/README.md

@@ -183,9 +183,10 @@ comment with `--comment`. No result carries a subscription topic: opening an ask
 one with `dispatch comment --reply-to-ask`, makes the session a follower of that ask (its answer
 and replies reach the session directly, server-side), and the command prints
 `Following ask <id> on <owner>: …` after its result the first time the session follows that ask.
-Whole-issue or whole-document subscription is the model's own `envoy_subscribe` of the topic every
+Whole-issue or whole-document subscription is the model's own `envoy_subscribe` of the topic a
 write result names (`notifications.dispatch.issue.<KEY>.>` or
-`notifications.dispatch.document.<PROJECT>.<SLUG>.>`).
+`notifications.dispatch.document.<PROJECT>.<SLUG>.>`), which it names only when none of the
+session's subscriptions, as the Envoy listener records them, covers that owner.
 
 The shared specs in `@legion/contracts` supply each command's description and flags:
 `@legion/envoy-client`'s `dispatch-command.ts` derives one command per spec and one flag per field.

package/dist/dispatch.js

@@ -16066,6 +16066,45 @@ async function readPictures(client, addresses, shown) {
   return { lines, images, shown: showing };
 }
 
+// ../envoy-client/src/dispatch-subscribe.ts
+function followedAsk(details) {
+  if (typeof details !== "object" || details === null)
+    return null;
+  const { follows, issue: issue2, document } = details;
+  if (typeof follows !== "object" || follows === null)
+    return null;
+  const { ask } = follows;
+  if (typeof ask !== "string" || ask === "")
+    return null;
+  if (typeof issue2 === "string" && issue2 !== "")
+    return { ask, owner: issueTopic(issue2) };
+  if (typeof document !== "string")
+    return null;
+  const [project, slug] = document.split("/", 2);
+  if (!project || !slug)
+    return null;
+  return { ask, owner: { label: document, topic: documentTopicOf(project, slug).topic } };
+}
+function followNoticeText({ ask, owner }, topics) {
+  const subscribe = ownerSubscribeLine(owner, topics);
+  return `Following ask ${ask} on ${owner.label}: its answer and replies reach you directly (${commandLine("dispatch_follow", { ask, action: "unfollow" })} to stop).${subscribe === null ? "" : ` ${subscribe}.`}`;
+}
+function ownerSubscribeLine(owner, topics) {
+  if (topics == null || topics.some((topic) => subscriptionCovers(topic, owner)))
+    return null;
+  return `For every event on ${owner.label}: envoy_subscribe ${owner.topic}`;
+}
+function subscriptionCovers(topic, owner) {
+  const base = owner.topic.slice(0, -".>".length).split(".");
+  for (const [index, part] of topic.split(".").entries()) {
+    if (part === ">")
+      return true;
+    if (index >= base.length || part !== "*" && part !== base[index])
+      return false;
+  }
+  return false;
+}
+
 // ../envoy-client/src/search-answer.ts
 function pageSummaryText(offset, count, total) {
   return `showing ${offset + 1}-${offset + count} of ${total}`;
@@ -16152,11 +16191,14 @@ function resolvedTopic(resolved) {
     throw new Error("issue document is missing its issue");
   return issueTopic(resolved.issue.key);
 }
-function notSubscribed(owner) {
-  return `(not subscribed to ${owner.label}; envoy_subscribe ${owner.topic} for every event on it)`;
+async function notSubscribed(owner, subscriptions) {
+  if (ownerSubscribeLine(owner, await subscriptions?.()) === null)
+    return "";
+  return ` (not subscribed to ${owner.label}; envoy_subscribe ${owner.topic} for every event on it)`;
 }
-function followsAsk(owner) {
-  return `You follow this ask: its answer and replies reach you directly. For every event on ${owner.label}: envoy_subscribe ${owner.topic}`;
+async function followsAsk(owner, subscriptions) {
+  const subscribe = ownerSubscribeLine(owner, await subscriptions?.());
+  return `You follow this ask: its answer and replies reach you directly.${subscribe === null ? "" : ` ${subscribe}`}`;
 }
 var triageAdviceShown = new Set;
 function adviceMemory() {
@@ -16433,6 +16475,37 @@ async function resolveIdPrefix(tool, kind, id, ownerName, list) {
   ]);
 }
 var askIdShapeProblem = "ask ids are uuids (a prefix of at least 8 hex characters works)";
+async function readAskRef(tool, id, ownerName, client, list) {
+  const fullID = normalizeUUID(id);
+  if (fullID !== undefined) {
+    try {
+      return await client.getAsk(fullID);
+    } catch (error48) {
+      if (!(error48 instanceof DispatchServiceError) || error48.status !== 404)
+        throw error48;
+      const blocks = (await list()).filter((ask) => ask.block_id?.toLowerCase() === fullID);
+      if (blocks.length !== 1 || blocks[0] === undefined)
+        throw error48;
+      return client.getAsk(blocks[0].id);
+    }
+  }
+  const asks = await list();
+  let matches = asks.filter((ask) => ask.block_id === id);
+  if (matches.length === 0) {
+    if (!idPrefixPattern.test(id)) {
+      throw new ToolInputError(tool, [
+        `ask id ${id} must be a full uuid, a prefix of at least 8 hex characters, or the id of an :::ask block on ${ownerName}`
+      ]);
+    }
+    const prefix = id.toLowerCase();
+    matches = asks.filter((ask) => ask.id.toLowerCase().startsWith(prefix) || (ask.block_id?.toLowerCase().startsWith(prefix) ?? false));
+  }
+  if (matches.length === 1 && matches[0] !== undefined)
+    return client.getAsk(matches[0].id);
+  throw new ToolInputError(tool, [
+    matches.length === 0 ? `ask id ${id} matches none of the asks on ${ownerName}; use the full id` : `ask id ${id} matches ${matches.length} asks on ${ownerName}; use the full id`
+  ]);
+}
 async function sessionOpenAsks(client, sessionId) {
   const session = sessionId?.trim();
   if (!session)
@@ -17055,6 +17128,7 @@ function askSummary({ ask, replies, answers }, graph) {
     "Options:",
     ...ask.options.length === 0 ? ["- none"] : ask.options.map((option) => `- ${option.label}${option.description ? ` \u2014 ${option.description}` : ""}`),
     `State: ${ask.state}`,
+    `Ask id: ${ask.id}`,
     "Answer:",
     ...answer === null ? ["- none"] : [
       `- By: ${answer.user}`,
@@ -17520,7 +17594,7 @@ async function executeDispatchTool(input) {
         const assigned = created.assignee === undefined ? "" : created.assignee === null ? "; unassigned" : `; assigned to ${created.assignee}`;
         return {
           text: [
-            `Created ${created.key}: ${created.title} \u2192 ${href}${assigned} ${notSubscribed(issueTopic(created.key))}`,
+            `Created ${created.key}: ${created.title} \u2192 ${href}${assigned}${await notSubscribed(issueTopic(created.key), input.subscriptions)}`,
             ...adviceLines
           ].join(`
 `),
@@ -17637,7 +17711,7 @@ async function executeDispatchTool(input) {
       });
       return {
         text: [
-          `${after.key}: ${changes.join("; ")} ${notSubscribed(issueTopic(after.key))}`,
+          `${after.key}: ${changes.join("; ")}${await notSubscribed(issueTopic(after.key), input.subscriptions)}`,
           ...adviceLines
         ].join(`
 `),
@@ -17670,8 +17744,7 @@ async function executeDispatchTool(input) {
         text = `${issueKey}: claimed by you since ${held.at}. Its status is ${after.status}; a claim moves nothing, so move it to in_progress with dispatch issue-update when you start, and release the claim when you stop.`;
       }
       return {
-        text: [text, notSubscribed(issueTopic(issueKey))].join(`
-`),
+        text: `${text}${await notSubscribed(issueTopic(issueKey), input.subscriptions)}`,
         details: { issue: issueKey, status: after.status, claim: held }
       };
     }
@@ -17847,7 +17920,7 @@ async function executeDispatchTool(input) {
       return {
         text: [
           `Asked ${ask.id} on ${askOwner.label} (urgency ${ask.urgency}): ${ask.question}
-${followsAsk(askOwner)}`,
+${await followsAsk(askOwner, input.subscriptions)}`,
           ...adviceLines
         ].join(`
 `),
@@ -17913,7 +17986,7 @@ ${followsAsk(askOwner)}`,
         const askState = comment.ask_waiting_on === undefined ? "" : `; ask now waiting on ${comment.ask_waiting_on}`;
         return {
           text: [
-            `Replied on ask ${replyToAsk} (comment ${comment.id}${askState}). ${followsAsk(commentOwner2)}`,
+            `Replied on ask ${replyToAsk} (comment ${comment.id}${askState}). ${await followsAsk(commentOwner2, input.subscriptions)}`,
             ...adviceLines
           ].join(`
 `),
@@ -17927,7 +18000,10 @@ ${followsAsk(askOwner)}`,
         };
       }
       return {
-        text: [`Posted comment ${comment.id} ${notSubscribed(commentOwner2)}`, ...adviceLines].join(`
+        text: [
+          `Posted comment ${comment.id}${await notSubscribed(commentOwner2, input.subscriptions)}`,
+          ...adviceLines
+        ].join(`
 `),
         details: {
           ...commentDetails,
@@ -17949,7 +18025,7 @@ ${followsAsk(askOwner)}`,
       };
       const comment = resolved.owner.kind === "project" ? await client.artifactSuggest(resolved.artifact.id, suggestionInput) : await client.suggest(issue2(), suggestionInput);
       return {
-        text: `Posted suggestion ${comment.id} ${notSubscribed(resolvedTopic(resolved))}`,
+        text: `Posted suggestion ${comment.id}${await notSubscribed(resolvedTopic(resolved), input.subscriptions)}`,
         details: writeResultDetails(resolved, { comment: comment.id })
       };
     }
@@ -18007,7 +18083,7 @@ ${followsAsk(askOwner)}`,
       const adviceLines = renderAdvice(input.tool, issueKey, message.advice, {});
       return {
         text: [
-          `Posted message ${message.id} (${messageRef}) ${notSubscribed(issueTopic(issueKey))}`,
+          `Posted message ${message.id} (${messageRef})${await notSubscribed(issueTopic(issueKey), input.subscriptions)}`,
           ...adviceLines
         ].join(`
 `),
@@ -18045,7 +18121,7 @@ ${followsAsk(askOwner)}`,
       const tokenTrailer = edited.token === undefined ? [] : [`Document token: ${edited.token}`];
       return {
         text: [
-          `${applied} ${notSubscribed(resolvedTopic(resolved))}`,
+          `${applied}${await notSubscribed(resolvedTopic(resolved), input.subscriptions)}`,
           ...tokenTrailer,
           ...adviceLines
         ].join(`
@@ -18168,7 +18244,7 @@ ${trailer.join(`
       });
       return {
         text: [
-          `Uploaded ${result.artifact.name} as version ${result.version.number} (artifact slug ${result.artifact.slug}; ${artifactRef}) ${notSubscribed(uploadOwner)}`,
+          `Uploaded ${result.artifact.name} as version ${result.version.number} (artifact slug ${result.artifact.slug}; ${artifactRef})${await notSubscribed(uploadOwner, input.subscriptions)}`,
           ...adviceLines
         ].join(`
 `),
@@ -18230,9 +18306,8 @@ ${trailer.join(`
       }
       if (ownerArguments.ref?.kind === "ask") {
         const ref = ownerArguments.ref;
-        const id = await resolveIdPrefix(input.tool, "ask", ref.id, refOwnerName(ref), async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks((await resolveDocument(ref.owner, ref.artifact)).artifact.id, "all"));
-        const askRead = await client.getAsk(id);
-        const askRef = refTarget(ref, "ask", id);
+        const askRead = await readAskRef(input.tool, ref.id, refOwnerName(ref), client, async () => ref.owner.kind === "issue" ? client.listIssueAsks(ref.owner.issue) : client.getArtifactAsks((await resolveDocument(ref.owner, ref.artifact)).artifact.id, "all"));
+        const askRef = refTarget(ref, "ask", askRead.ask.id);
         const [pictures3, graph2] = await Promise.all([
           picturesOf(askTexts(askRead)),
           graphSections(client, askRef)
@@ -18505,33 +18580,6 @@ function pruneSessions(root, now) {
   writeFileSync(stamp, "", { mode: PRIVATE_FILE });
 }
 
-// ../envoy-client/src/dispatch-subscribe.ts
-function dispatchFollowNotice(details) {
-  if (typeof details !== "object" || details === null)
-    return null;
-  const { follows, issue: issue2, document } = details;
-  if (typeof follows !== "object" || follows === null)
-    return null;
-  const { ask } = follows;
-  if (typeof ask !== "string" || ask === "")
-    return null;
-  let owner;
-  if (typeof issue2 === "string" && issue2 !== "") {
-    owner = issueTopic(issue2);
-  } else if (typeof document === "string") {
-    const [project, slug] = document.split("/", 2);
-    if (!project || !slug)
-      return null;
-    owner = { label: document, topic: documentTopicOf(project, slug).topic };
-  } else {
-    return null;
-  }
-  return {
-    ask,
-    text: `Following ask ${ask} on ${owner.label}: its answer and replies reach you directly (${commandLine("dispatch_follow", { ask, action: "unfollow" })} to stop). For every event on ${owner.label}: envoy_subscribe ${owner.topic}.`
-  };
-}
-
 // ../envoy-client/src/envoy-config.ts
 import {
   chmodSync,
@@ -19079,6 +19127,109 @@ function dispatchSettings(env, config2) {
   }
 }
 
+// ../envoy-client/src/envoy-settings.ts
+var DEFAULT_ENVOY_URL = "http://127.0.0.1:9020";
+var DEFAULT_HEARTBEAT_MS = 120000;
+var MIN_HEARTBEAT_MS = 25;
+function natsSeedFromEnvironment(env) {
+  const { NATS_NKEY_SEED_FILE: file2, NATS_NKEY_SEED: plain } = env;
+  if (file2 !== undefined) {
+    if (file2 === "")
+      throw new Error("NATS_NKEY_SEED_FILE is set but empty");
+    return {
+      value: readSecretFile("NATS_NKEY_SEED_FILE", file2),
+      source: `NATS_NKEY_SEED_FILE (${file2})`
+    };
+  }
+  if (plain === undefined)
+    return;
+  const value = plain.trim();
+  if (value.length === 0)
+    throw new Error("NATS_NKEY_SEED is set but empty");
+  return { value, source: "NATS_NKEY_SEED" };
+}
+var NO_NATS_SERVER = "Envoy has no NATS server (envoy.natsUrls, ENVOY_NATS_URL)";
+var NO_NATS_CONNECTION = "this session opens no NATS connection";
+function natsServerKey(url2) {
+  const match = /^([a-z][a-z0-9+.-]*):\/\/([^@/]*@)?(\[[^\]]*\]|[^:/]*)(?::(\d+))?(\/.*)?$/i.exec(url2);
+  if (match === null)
+    return url2;
+  const [, scheme = "", userinfo = "", host = "", port = "4222", rest = ""] = match;
+  return `${scheme.toLowerCase()}://${userinfo}${host.toLowerCase()}:${port}${rest.replace(/\/+$/, "")}`;
+}
+function natsCredential(env, section, namedNatsUrls, filePath) {
+  const fromEnvironment = natsSeedFromEnvironment(env);
+  if (fromEnvironment !== undefined || section.natsSeed === undefined)
+    return fromEnvironment;
+  if (namedNatsUrls.length > 0) {
+    const servers = new Set((section.natsUrls ?? []).map(natsServerKey));
+    const named = new Set(namedNatsUrls.map(natsServerKey));
+    if (named.size !== servers.size || ![...named].every((server) => servers.has(server))) {
+      throw new Error(`ENVOY_NATS_URL names other servers than ${filePath}'s envoy.natsUrls; set NATS_NKEY_SEED_FILE for them`);
+    }
+  }
+  return {
+    value: fileValue(section.natsSeed, "envoy.natsSeed", filePath, env),
+    source: `envoy.natsSeed in ${filePath}`
+  };
+}
+function envoySettings(env, config2, options = {}) {
+  if (config2.kind === "failed")
+    return offWithError(config2.error);
+  const section = config2.envoy;
+  if (section.enabled === false) {
+    return offWithNotice(`${config2.path} sets envoy.enabled to false: Envoy is off`);
+  }
+  const namedUrl = nonEmpty(env.ENVOY_URL);
+  const namedNatsUrls = (env.ENVOY_NATS_URL ?? "").split(",").map((url3) => url3.trim()).filter((url3) => url3.length > 0);
+  const addressed = namedUrl !== undefined || namedNatsUrls.length > 0 || section.url !== undefined || (section.natsUrls ?? []).length > 0 || section.enabled === true;
+  if (!addressed) {
+    return offWithNotice(config2.missing === null ? `${config2.path} names no Envoy listener or NATS server, and neither ENVOY_URL nor ENVOY_NATS_URL is set: Envoy is off` : missingConfigNotice(config2.path, config2.missing, "Envoy is off"));
+  }
+  if (namedUrl !== undefined && httpUrl2(namedUrl) === undefined) {
+    return offWithError("ENVOY_URL must be an http or https URL");
+  }
+  const listener = section.url ?? DEFAULT_ENVOY_URL;
+  const url2 = namedUrl ?? listener;
+  let token;
+  try {
+    const source = bearerSource(env, "ENVOY", () => section.token === undefined ? undefined : {
+      token: section.token,
+      field: "envoy.token",
+      path: config2.path,
+      server: listener,
+      checkout: false
+    });
+    token = source.kind === "none" ? undefined : source.kind === "variable" ? source.token : fileBearer(source, url2, "ENVOY", env);
+  } catch (error48) {
+    return offWithError(messageFor(error48));
+  }
+  const natsUrls = namedNatsUrls.length > 0 ? namedNatsUrls : section.natsUrls ?? [];
+  let inbound;
+  if (options.nats === false)
+    inbound = { off: NO_NATS_CONNECTION };
+  else if (natsUrls.length === 0)
+    inbound = { off: NO_NATS_SERVER };
+  else {
+    try {
+      inbound = { natsUrls, natsSeed: natsCredential(env, section, namedNatsUrls, config2.path) };
+    } catch (error48) {
+      inbound = { off: messageFor(error48) };
+    }
+  }
+  const rawHeartbeatMs = Number(env.ENVOY_HEARTBEAT_MS);
+  return {
+    enabled: true,
+    url: normalizeEnvoyUrl(url2),
+    token,
+    inbound,
+    heartbeatMs: Number.isFinite(rawHeartbeatMs) && rawHeartbeatMs > 0 ? Math.max(rawHeartbeatMs, MIN_HEARTBEAT_MS) : DEFAULT_HEARTBEAT_MS
+  };
+}
+function normalizeEnvoyUrl(value) {
+  return value.replace(/\/+$/, "");
+}
+
 // ../envoy-client/src/session-settings.ts
 function sessionConfigFile(harness, env) {
   try {
@@ -19105,6 +19256,241 @@ function sessionDispatchSettings(file2, env, options) {
     missing: config2.kind === "read" ? config2.missing : null
   };
 }
+function sessionEnvoySettings(file2, env, options) {
+  if (file2.path === null)
+    return offWithError(file2.error);
+  return envoySettings(env, readEnvoyConfig(file2.path, env, options), { nats: options.nats });
+}
+
+// ../envoy-client/src/transport.ts
+var DEFAULT_TIMEOUT_MS = 5000;
+var RETRY_DELAY_MS = 250;
+var InterestWireSchema = exports_external.object({
+  session_id: exports_external.string(),
+  machine_id: exports_external.string(),
+  dir: exports_external.string(),
+  topics: exports_external.array(exports_external.string()),
+  updated_at: exports_external.number().int().optional(),
+  warnings: exports_external.array(exports_external.string()).optional()
+});
+var SessionWireSchema = exports_external.object({
+  session_id: exports_external.string(),
+  machine_id: exports_external.string(),
+  host: exports_external.string().optional(),
+  dir: exports_external.string(),
+  port: exports_external.number().int(),
+  title: exports_external.string(),
+  topics: exports_external.array(exports_external.string()),
+  roles: exports_external.array(exports_external.string()).optional(),
+  capabilities: exports_external.array(exports_external.string()).optional(),
+  self_subscribed: exports_external.boolean(),
+  last_seen: exports_external.number().int().optional()
+});
+var RoleWireSchema = exports_external.object({
+  role: exports_external.string(),
+  holder: exports_external.string(),
+  host: exports_external.string().optional(),
+  last_seen: exports_external.number().int()
+});
+var RoleHeldWireSchema = exports_external.object({
+  error: exports_external.string(),
+  role: exports_external.string(),
+  holder: exports_external.string()
+});
+var ErrorWireSchema = exports_external.object({
+  error: exports_external.string(),
+  expected: exports_external.array(exports_external.string()).optional()
+});
+var EnvelopeResponseSchema = EnvelopeSchema.extend({
+  recipient: exports_external.string().optional(),
+  holder: exports_external.string().optional()
+});
+function expandSubscriptionTopics(topics) {
+  const expanded = new Set;
+  for (const topic of topics) {
+    const base = topic.endsWith(".>") ? topic.slice(0, -2) : undefined;
+    if (base === undefined || base.includes("*") || base.includes(">")) {
+      expanded.add(topic);
+      continue;
+    }
+    const segments = base.split(".");
+    if (segments.length < 2 || segments.some((segment) => segment.length === 0)) {
+      throw new TypeError(`cannot expand Envoy wildcard topic "${topic}": its concrete base must have at least two non-empty segments`);
+    }
+    expanded.add(base);
+    expanded.add(topic);
+  }
+  return [...expanded];
+}
+
+class EnvoyApiError extends Error {
+  details;
+  name = "EnvoyApiError";
+  expected;
+  constructor(details) {
+    let parsed;
+    try {
+      const result = ErrorWireSchema.safeParse(JSON.parse(details.responseBody));
+      if (result.success)
+        parsed = result.data;
+    } catch {}
+    super(parsed === undefined ? `${details.method} ${details.url} failed with ${details.status}: ${details.responseBody}` : `${parsed.error}${parsed.expected === undefined ? "" : ` (expected: ${parsed.expected.join(", ")})`}`);
+    this.details = details;
+    this.expected = parsed?.expected;
+  }
+}
+function createEnvoyClient(config2) {
+  const baseUrl = normalizeEnvoyUrl(config2.baseUrl);
+  const timeoutMs = config2.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const apiToken = config2.token;
+  const request = async (path2, init) => {
+    const url2 = `${baseUrl}${path2}`;
+    const attempts = config2.retry === false ? 1 : 2;
+    for (let attempt = 0;attempt < attempts; attempt += 1) {
+      let response;
+      try {
+        const headers = new Headers(init.headers);
+        if (apiToken)
+          headers.set("Authorization", `Bearer ${apiToken}`);
+        response = await config2.fetch(url2, {
+          ...init,
+          headers,
+          signal: AbortSignal.timeout(timeoutMs)
+        });
+      } catch (error49) {
+        if (attempt + 1 < attempts) {
+          await waitForRetry();
+          continue;
+        }
+        throw error49;
+      }
+      const responseBody = await response.text();
+      if (response.ok)
+        return responseBody;
+      const error48 = new EnvoyApiError({
+        method: init.method ?? "GET",
+        url: url2,
+        status: response.status,
+        responseBody
+      });
+      if (response.status >= 500 && attempt + 1 < attempts) {
+        await waitForRetry();
+        continue;
+      }
+      throw error48;
+    }
+    throw new Error("Envoy request exhausted retries");
+  };
+  const post = (path2, body) => request(path2, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  return {
+    subscribe: async (input) => InterestWireSchema.parse(JSON.parse(await post("/v1/interests/subscribe", {
+      session_id: input.sessionID,
+      dir: input.directory,
+      topics: expandSubscriptionTopics(input.topics),
+      port: input.port,
+      title: input.title,
+      ...input.capabilities === undefined ? {} : { capabilities: input.capabilities },
+      driving: input.driving,
+      ...input.selfSubscribed === undefined ? {} : { self_subscribed: input.selfSubscribed },
+      host: machineID()
+    }))),
+    unsubscribe: async (input) => {
+      await post("/v1/interests/unsubscribe", {
+        session_id: input.sessionID,
+        topics: expandSubscriptionTopics(input.topics)
+      });
+    },
+    getInterest: async (sessionID) => InterestWireSchema.parse(JSON.parse(await request(`/v1/interests/${sessionID}`, {}))),
+    send: async (input) => {
+      const idempotencyKey = input.idempotencyKey ?? crypto.randomUUID();
+      const response = EnvelopeResponseSchema.parse(JSON.parse(await post("/v1/messages/send", {
+        source: input.source ?? "agent",
+        ...sourceSession(input.sourceSessionID),
+        target_session: input.targetSessionID,
+        message: input.message,
+        idempotency_key: idempotencyKey,
+        ...messageMetadata(input)
+      })));
+      return {
+        envelope: response,
+        recipient: response.recipient ?? input.targetSessionID,
+        confirmed: response.recipient !== undefined
+      };
+    },
+    publish: async (input) => {
+      const idempotencyKey = input.idempotencyKey ?? crypto.randomUUID();
+      const response = EnvelopeResponseSchema.parse(JSON.parse(await post("/v1/messages/publish", {
+        source: input.source ?? "agent",
+        ...sourceSession(input.sourceSessionID),
+        topic: input.topic,
+        message: input.message,
+        ...input.payload === undefined ? {} : { payload: input.payload },
+        idempotency_key: idempotencyKey,
+        ...messageMetadata(input)
+      })));
+      return {
+        envelope: response,
+        ...response.holder === undefined ? {} : { holder: response.holder }
+      };
+    },
+    unregisterSession: async (sessionID) => {
+      await request(`/v1/sessions/${encodeURIComponent(sessionID)}`, { method: "DELETE" });
+    },
+    setRole: async (input) => {
+      const soft = input.soft === true;
+      const previous = soft ? input.previousSessionID ?? "" : "";
+      const body = {
+        session_id: input.sessionID,
+        role: input.role,
+        ...soft ? { soft: true } : {},
+        ...previous === "" ? {} : { previous_session_id: previous }
+      };
+      let raw;
+      try {
+        raw = await post("/v1/roles/set", body);
+      } catch (error48) {
+        if (error48 instanceof EnvoyApiError && error48.details.status === 409) {
+          const held = RoleHeldWireSchema.safeParse(JSON.parse(error48.details.responseBody));
+          if (held.success)
+            return { claimed: false, holder: held.data.holder };
+        }
+        throw error48;
+      }
+      return { claimed: true, interest: InterestWireSchema.parse(JSON.parse(raw)) };
+    },
+    getRole: async (role) => RoleWireSchema.parse(JSON.parse(await request(`/v1/roles/${encodeURIComponent(role)}`, { method: "GET" }))),
+    listSessions: async (input = {}) => {
+      const search = new URLSearchParams;
+      if (input.directory !== undefined)
+        search.set("dir", input.directory);
+      if (input.title !== undefined)
+        search.set("title", input.title);
+      const query = search.size === 0 ? "" : `?${search.toString()}`;
+      return SessionWireSchema.array().parse(JSON.parse(await request(`/v1/sessions${query}`, {})));
+    }
+  };
+}
+function waitForRetry() {
+  const { promise: promise2, resolve: resolve2 } = Promise.withResolvers();
+  setTimeout(resolve2, RETRY_DELAY_MS);
+  return promise2;
+}
+function messageMetadata(input) {
+  return {
+    ...input.inReplyTo === undefined ? {} : { in_reply_to: input.inReplyTo },
+    ...input.supersedes === undefined ? {} : { supersedes: input.supersedes },
+    ...input.urgency === undefined ? {} : { urgency: input.urgency },
+    ...input.expectsReply === undefined ? {} : { expects_reply: input.expectsReply },
+    ...input.expiresAt === undefined ? {} : { expires_at: input.expiresAt }
+  };
+}
+function sourceSession(sessionID) {
+  return sessionID === undefined || sessionID === "" ? {} : { source_session: sessionID };
+}
 
 // ../envoy-client/src/dispatch-cli.ts
 var OK = 0;
@@ -19116,6 +19502,7 @@ var STATE_WRITE_FAILED = "dispatch: Dispatch took the call, but this session's s
 function stateWriteFailed(problem) {
   return `${STATE_WRITE_FAILED} could not be written: ${problem}`;
 }
+var SUBSCRIPTIONS_TIMEOUT_MS = 1500;
 function fitOutput(text, pictures, kept, limit, writeFull) {
   const whole = [text, ...pictures, ...kept].join(`
 `);
@@ -19214,6 +19601,28 @@ async function runDispatchCli(argv, rawEnv, io) {
     return USAGE;
   }
   const config2 = resolution;
+  let topics;
+  const readTopics = async () => {
+    try {
+      const envoy = sessionEnvoySettings(file2, env, { cwd: io.cwd, nats: false });
+      if (!envoy.enabled)
+        return null;
+      const listener = createEnvoyClient({
+        baseUrl: envoy.url,
+        fetch: io.fetchImpl ?? fetch,
+        token: envoy.token,
+        timeoutMs: SUBSCRIPTIONS_TIMEOUT_MS,
+        retry: false
+      });
+      return (await listener.getInterest(sessionId)).topics;
+    } catch (error48) {
+      return error48 instanceof EnvoyApiError && error48.details.status === 404 ? [] : null;
+    }
+  };
+  const subscriptions = () => {
+    topics ??= readTopics();
+    return topics;
+  };
   let follows;
   try {
     pruneSessions(sessionStateRoot(env), Date.now());
@@ -19239,7 +19648,8 @@ async function runDispatchCli(argv, rawEnv, io) {
       sessionTitle: env.DISPATCH_SESSION_TITLE ?? readSessionTitle(dir),
       config: config2,
       env,
-      ...io.fetchImpl === undefined ? {} : { fetchImpl: io.fetchImpl }
+      ...io.fetchImpl === undefined ? {} : { fetchImpl: io.fetchImpl },
+      subscriptions
     });
     text = result.text;
     for (const warning of result.warnings ?? []) {
@@ -19254,10 +19664,10 @@ async function runDispatchCli(argv, rawEnv, io) {
     } catch (error48) {
       problems.push(messageFor(error48));
     }
-    const notice = dispatchFollowNotice(result.details);
-    if (notice !== null && !follows.has(notice.ask)) {
-      follows.add(notice.ask);
-      notes.push(notice.text);
+    const followed = followedAsk(result.details);
+    if (followed !== null && !follows.has(followed.ask)) {
+      follows.add(followed.ask);
+      notes.push(followNoticeText(followed, await subscriptions()));
     }
     entry = { tool, details: result.details };
     code = OK;

package/dist/envoy.js

@@ -33423,6 +33423,34 @@ function machineID() {
 // ../envoy-client/src/dispatch-cwd.ts
 var execFileAsync = promisify(execFile);
 
+// ../envoy-client/src/dispatch-subscribe.ts
+function subscriptionRemovedTopics(raw, sessionID) {
+  let envelope2;
+  try {
+    envelope2 = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (typeof envelope2 !== "object" || envelope2 === null)
+    return;
+  const { source, payload } = envelope2;
+  if (source !== "dispatch" || typeof payload !== "string")
+    return;
+  let event;
+  try {
+    event = JSON.parse(payload);
+  } catch {
+    return;
+  }
+  const parsedEvent = DispatchEventSchema.safeParse(event);
+  if (!parsedEvent.success || parsedEvent.data.type !== "subscription.removed")
+    return;
+  const parsedPayload = SubscriptionRemovedEventPayloadSchema.safeParse(parsedEvent.data.payload);
+  if (!parsedPayload.success || parsedPayload.data.session_id !== sessionID)
+    return;
+  return parsedPayload.data.topics ?? [];
+}
+
 // ../envoy-client/src/dispatch-execute.ts
 var triageAdviceShown = new Set;
 var refGrammarProblem = "ref must be a valid dispatch:// reference such as dispatch://KEY-1, " + "dispatch://KEY-1/ask/<uuid>, dispatch://KEY-1/comment/<uuid>, " + "dispatch://KEY-1/message/<uuid>, dispatch://KEY-1/artifact/<slug>, " + "dispatch://PROJECT/artifact/<document-ref> (an artifact id, slug, or filename), or " + "dispatch://agent/<session id>/artifact/<slug> (a picture in a conversation on the Agents page, " + "for dispatch doc-read); a dashboard URL on this Dispatch server is accepted too";
@@ -33516,34 +33544,6 @@ function writeSessionTitle(dir, title) {
   writeAtomically(join3(dir, "title"), title);
 }
 
-// ../envoy-client/src/dispatch-subscribe.ts
-function subscriptionRemovedTopics(raw, sessionID) {
-  let envelope2;
-  try {
-    envelope2 = JSON.parse(raw);
-  } catch {
-    return;
-  }
-  if (typeof envelope2 !== "object" || envelope2 === null)
-    return;
-  const { source, payload } = envelope2;
-  if (source !== "dispatch" || typeof payload !== "string")
-    return;
-  let event;
-  try {
-    event = JSON.parse(payload);
-  } catch {
-    return;
-  }
-  const parsedEvent = DispatchEventSchema.safeParse(event);
-  if (!parsedEvent.success || parsedEvent.data.type !== "subscription.removed")
-    return;
-  const parsedPayload = SubscriptionRemovedEventPayloadSchema.safeParse(parsedEvent.data.payload);
-  if (!parsedPayload.success || parsedPayload.data.session_id !== sessionID)
-    return;
-  return parsedPayload.data.topics ?? [];
-}
-
 // ../envoy-client/src/nats-auth.ts
 var import_nats = __toESM(require_mod4(), 1);
 var seedKeys = import_nats.nkeys;
@@ -34249,7 +34249,8 @@ function createEnvoyClient(config2) {
   const apiToken = config2.token;
   const request = async (path2, init) => {
     const url2 = `${baseUrl}${path2}`;
-    for (let attempt = 0;attempt < 2; attempt += 1) {
+    const attempts = config2.retry === false ? 1 : 2;
+    for (let attempt = 0;attempt < attempts; attempt += 1) {
       let response;
       try {
         const headers = new Headers(init.headers);
@@ -34261,7 +34262,7 @@ function createEnvoyClient(config2) {
           signal: AbortSignal.timeout(timeoutMs)
         });
       } catch (error49) {
-        if (attempt === 0) {
+        if (attempt + 1 < attempts) {
           await waitForRetry();
           continue;
         }
@@ -34276,7 +34277,7 @@ function createEnvoyClient(config2) {
         status: response.status,
         responseBody
       });
-      if (response.status >= 500 && attempt === 0) {
+      if (response.status >= 500 && attempt + 1 < attempts) {
         await waitForRetry();
         continue;
       }

package/dist/skills/dispatch/SKILL.md

@@ -57,6 +57,7 @@ A spec is the design conversation with the human, written down. It starts as the
 - **Rewrite a changed point. Do not append.** The decision block stays as the record. Versions keep the history.
 - **No placeholders**: no TBD, TODO or hedging. An open item is a decision block or a two-lane contract you settle over Envoy. Or it is a technical decision your lane makes where the work happens, outside the spec.
 - **No progress**: no status, timestamps, "Update HH:MMZ" sections, PR lists or handoff notes.
+- **Repeated measurements** (hourly counts, a fleet table) go in one artifact that you edit in place, linked once from the spec. Never post them as ask replies or as new spec rows.
 - **No commentary**: never call it a draft, version or turn, preview a later version, describe a correction, or narrate the exchange.
 
 Before a version goes out, read it as the human will. No two passages conflict, each point has one reading, and each decision block passes the phone test.

package/dist/skills/dispatch/references/asks.md

@@ -20,9 +20,10 @@ dispatch ask --issue DSP-42 \
   --option 'Leave it expired: Changes nothing now but leaves the fix unable to run.'
 ```
 
-- Correct an open ask in place with `dispatch edit-ask`, not a second ask, while the same decision stays open. The human then reconfirms. You cannot edit an answered or resolved ask. If the decision changed, retract it and open a new one.
+- Correct an open ask in place with `dispatch edit-ask`, not a second ask, while the same decision stays open. The human then reconfirms. You cannot edit an answered or resolved ask. If the decision of an open ask changed, retract it and open a new one. If the decision of an answered ask changed, open a new one.
 - `edit-ask` on a block ask writes the block too, so it mints a version and closes a spec's design gate until approved. Change anything else about the block with `dispatch doc-edit`. A retry with unchanged fields is safe.
 - A human can change an answer. A new `ask.answered` carries `previous_answer`. Act on the newest.
+- When the selected option and the typed text disagree, the text is the answer. Act on it. To clarify, open a new ask.
 - Retract a moot or superseded ask, or resolve one whose answer you found:
 
 ```bash

package/dist/skills/dispatch/references/document-edits.md

@@ -34,7 +34,7 @@ EOF
 - `delete` of a block's whole text deletes the block. A partial match keeps it. A bullet with a nested list hoists the list. A bullet with other content needs `delete {block:"<item id>"}`.
 - Dispatch refuses a `delete` or `retype` that takes out an open ask's block, delete-then-insert included. Reword with `replace`, relocate with `move`, or use `dispatch edit-ask`. Moving an open block out of a container and deleting the container takes two calls.
 - `retype` turns a paragraph or typed block into a typed block in place, keeping its id. Use it when a paragraph is the question that should become a decision.
-- An ask block has two ids. The block id (`:::ask{#<id> …}`) goes bare in `block` for `move` / `delete` (`block:<id>` only in `before` / `after`). The ask id goes to `dispatch open-asks`, `dispatch read` and `--reply-to-ask`. `dispatch://KEY/ask/<block-id>` answers `not found`.
+- An ask block has two ids. The block id (`:::ask{#<id> …}`) goes bare in `block` for `move` / `delete` (`block:<id>` only in `before` / `after`). `dispatch read --ref dispatch://KEY/ask/<id>` takes either id, whole or as a unique prefix of 8 or more hex characters, and prints the ask id as `Ask id:`. `dispatch open-asks` lists ask ids. `edit-ask`, `resolve-ask`, `follow` and `--reply-to-ask` take only the ask id.
 
 ## Tables
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sjawhar/pi-envoy",
-  "version": "10.15.0",
+  "version": "10.16.0",
   "license": "Apache-2.0",
   "type": "module",
   "omp": {