@sjawhar/pi-envoy 10.3.0 → 10.5.0

package/dist/dispatch.js

@@ -16577,14 +16577,14 @@ function toolSchema(tool) {
   toolSchemas.set(tool, schema);
   return schema;
 }
-async function resolveOwnerArguments(tool, input, cwd, env, exec, serverUrl, problems) {
+async function resolveOwnerArguments(tool, input, cwd, env, exec, dashboardUrls, problems) {
   if (issueFreeTools[tool] === true)
     return { args: input, ref: null, owner: null };
   const refArgument = input.ref;
   let ref = null;
   let args = input;
   if (typeof refArgument === "string") {
-    const refText = dispatchRefFromUrl(refArgument, serverUrl) ?? refArgument;
+    const refText = dashboardUrls.map((dashboard) => dispatchRefFromUrl(refArgument, dashboard)).find((ref2) => ref2 !== undefined) ?? refArgument;
     if (refText !== refArgument)
       args = { ...input, ref: refText };
     const agentArtifact = parseAgentArtifactRef(refText);
@@ -16846,7 +16846,7 @@ function progressText(progress, sep) {
   }
   return parts.join(sep);
 }
-function issueSummary(issue2, events, references, graph, titles) {
+function issueSummary(issue2, events, references, graph, linkBase, titles) {
   const asks = issue2.open_asks;
   const spec = issue2.artifacts?.find((artifact) => artifact.primary);
   const specApproval = spec === undefined ? undefined : approvalLine(spec);
@@ -16864,6 +16864,7 @@ function issueSummary(issue2, events, references, graph, titles) {
   return [
     `Title: ${issue2.title}`,
     `Key: ${issue2.key}`,
+    `Link: ${new URL(`/issues/${encodeURIComponent(issue2.key)}`, linkBase).toString()}`,
     `Status: ${issue2.status}`,
     `Assignee: ${issue2.assignee ?? "unassigned"}`,
     `Claimed by: ${issue2.claim === null ? "nobody" : claimText(issue2.claim, titles)}`,
@@ -17328,6 +17329,7 @@ function withAccount(error48, account) {
 }
 async function executeDispatchTool(input) {
   const { url: configUrl, token: configToken } = input.config;
+  const linkBase = input.config.publicUrl ?? configUrl;
   const baseFetch = input.fetchImpl ?? fetch;
   const fetchImpl = Object.assign(async (...args2) => {
     try {
@@ -17342,7 +17344,7 @@ async function executeDispatchTool(input) {
   const env = input.env ?? process.env;
   const exec = input.exec ?? defaultExec;
   const problems = [];
-  const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec, configUrl, problems);
+  const ownerArguments = await resolveOwnerArguments(input.tool, input.args, input.cwd, env, exec, input.config.publicUrl === undefined ? [configUrl] : [configUrl, input.config.publicUrl], problems);
   const ownerMissing = issueFreeTools[input.tool] !== true && ownerArguments.owner === null;
   const schema = toolSchema(input.tool);
   const parsed = schema.safeParse(ownerArguments.args, { reportInput: true });
@@ -17360,13 +17362,13 @@ async function executeDispatchTool(input) {
     const project = optionalString(ownerArguments.args, "project");
     if (project !== undefined) {
       const response2 = await client2.openAsksForProject(project);
-      return { text: formatOpenAsksSummary(response2, configUrl), details: { ...response2 } };
+      return { text: formatOpenAsksSummary(response2, linkBase), details: { ...response2 } };
     }
     const sessionId = input.sessionId?.trim();
     if (!sessionId)
       throw new Error("host session id is required for dispatch open-asks");
     const response = await client2.openAsks(sessionId);
-    return { text: formatOpenAsksSummary(response, configUrl), details: { ...response } };
+    return { text: formatOpenAsksSummary(response, linkBase), details: { ...response } };
   }
   if (input.tool === "dispatch_whoami") {
     const sessionId = input.sessionId?.trim();
@@ -17448,11 +17450,13 @@ async function executeDispatchTool(input) {
             isPrimarySpec: spec !== undefined
           }),
           ...componentGuidance === undefined ? [] : [componentGuidance],
-          ...renderSuggestions(created.advice?.suggestions, configUrl)
+          ...renderSuggestions(created.advice?.suggestions, linkBase)
         ];
+        const href = new URL(`/issues/${encodeURIComponent(created.key)}`, linkBase).toString();
+        const assigned = created.assignee === undefined ? "" : created.assignee === null ? "; unassigned" : `; assigned to ${created.assignee}`;
         return {
           text: [
-            `Created ${created.key}: ${created.title} ${notSubscribed(issueTopic(created.key))}`,
+            `Created ${created.key}: ${created.title} \u2192 ${href}${assigned} ${notSubscribed(issueTopic(created.key))}`,
             ...adviceLines
           ].join(`
 `),
@@ -17470,7 +17474,7 @@ async function executeDispatchTool(input) {
           text: [
             `Not created: "${title}" looks like a duplicate.`,
             ...candidates.map((candidate) => {
-              const href = new URL(candidate.href, configUrl).toString();
+              const href = new URL(candidate.href, linkBase).toString();
               return `${candidate.key} [${candidate.status}] ${candidate.title} \u2192 ${href}`;
             }),
             "Reference the existing issue, or run dispatch issue again with --force after reading it."
@@ -17611,7 +17615,7 @@ async function executeDispatchTool(input) {
         ...limit === undefined ? {} : { limit },
         ...offset === undefined ? {} : { offset }
       });
-      return searchAnswer(search, query, offset, configUrl);
+      return searchAnswer(search, query, offset, linkBase);
     }
     case "dispatch_issues": {
       const project = stringArg(args, "project");
@@ -17675,7 +17679,7 @@ async function executeDispatchTool(input) {
       } catch (error48) {
         throw refusalWithCode(error48);
       }
-      const href = new URL(`/projects/${encodeURIComponent(project.key)}`, configUrl).toString();
+      const href = new URL(`/projects/${encodeURIComponent(project.key)}`, linkBase).toString();
       return {
         text: `Created project ${project.key} (${project.name}) at ${project.created_at}: ${href}`,
         details: { project: project.key, name: project.name, created_at: project.created_at }
@@ -17768,7 +17772,7 @@ async function executeDispatchTool(input) {
       const askOwner = ask.issue_key !== null ? issueTopic(ask.issue_key) : resolved === undefined ? issueTopic(issue2()) : documentTopic(resolved.artifact);
       const adviceLines = [
         ...renderAdvice(input.tool, askOwner.label, ask.advice, {}),
-        ...renderSuggestions(ask.advice?.suggestions, configUrl)
+        ...renderSuggestions(ask.advice?.suggestions, linkBase)
       ];
       return {
         text: [
@@ -18249,7 +18253,7 @@ ${trailer.join(`
         ])
       ]);
       return {
-        text: issueSummary(read.issue, read.events, references, [...pictures2.lines, ...graph], titles),
+        text: issueSummary(read.issue, read.events, references, [...pictures2.lines, ...graph], linkBase, titles),
         details: { issue: read.issue.key },
         ...showImages(pictures2)
       };
@@ -18987,7 +18991,17 @@ function dispatchSettings(env, config2) {
     }
     const url2 = (explicitUrl ?? (source.kind === "file" ? source.server : own.serverUrl ?? DEFAULT_SERVER_URL)).replace(/\/+$/, "");
     const token = source.kind === "variable" ? source.token : fileBearer(source, url2, "DISPATCH", env);
-    return { enabled: true, url: url2, token };
+    const publicUrl = nonEmpty(env.DISPATCH_PUBLIC_URL);
+    const publicParsed = publicUrl === undefined ? undefined : httpUrl2(publicUrl);
+    if (publicUrl !== undefined && (publicParsed === undefined || publicParsed.port === "0")) {
+      return offWithError("DISPATCH_PUBLIC_URL must be an http or https URL");
+    }
+    return {
+      enabled: true,
+      url: url2,
+      token,
+      ...publicUrl === undefined ? {} : { publicUrl: publicUrl.replace(/\/+$/, "") }
+    };
   } catch (error48) {
     return offWithError(messageFor(error48));
   }

package/dist/envoy.js

@@ -30463,6 +30463,12 @@ var DISPATCH_DOCUMENT_TOPIC_PREFIX = `${DISPATCH_TOPIC_PREFIX}document.`;
 function agentSubject(session) {
   return `${AGENT_TOPIC_PREFIX}${session}`;
 }
+// ../contracts/src/slack.ts
+var SLACK_POST_TEXT_MAX = 4000;
+function slackTopicChannel(topic) {
+  const [scope, source, , channel] = topic.split(".");
+  return scope === "notifications" && source === "slack" ? channel ?? "" : undefined;
+}
 // ../contracts/src/tool-schema.ts
 function overCapMessage(length, max) {
   return `is ${length - max} characters over the ${max}-character limit (${length}/${max})`;
@@ -32577,7 +32583,17 @@ function dispatchSettings(env, config2) {
     }
     const url2 = (explicitUrl ?? (source.kind === "file" ? source.server : own.serverUrl ?? DEFAULT_SERVER_URL)).replace(/\/+$/, "");
     const token = source.kind === "variable" ? source.token : fileBearer(source, url2, "DISPATCH", env);
-    return { enabled: true, url: url2, token };
+    const publicUrl = nonEmpty(env.DISPATCH_PUBLIC_URL);
+    const publicParsed = publicUrl === undefined ? undefined : httpUrl2(publicUrl);
+    if (publicUrl !== undefined && (publicParsed === undefined || publicParsed.port === "0")) {
+      return offWithError("DISPATCH_PUBLIC_URL must be an http or https URL");
+    }
+    return {
+      enabled: true,
+      url: url2,
+      token,
+      ...publicUrl === undefined ? {} : { publicUrl: publicUrl.replace(/\/+$/, "") }
+    };
   } catch (error48) {
     return offWithError(messageFor(error48));
   }
@@ -33698,6 +33714,293 @@ function sessionDispatchSettings(file2, env, options) {
   };
 }
 
+// ../envoy-client/src/slack-post.ts
+import { BlockList, isIP } from "net";
+var SLACK_BOT_TOKEN_SECRET = "LEGION_SLACK_BOT_TOKEN";
+var SLACK_POST_API_URL_VARIABLE = "SLACK_POST_API_URL";
+var POST_TIMEOUT_MS = 30000;
+var SLACK_ERROR_CODES = [
+  "access_denied",
+  "accesslimited",
+  "account_inactive",
+  "agent_prompt_display_not_allowed",
+  "app_access_restricted",
+  "as_user_not_supported",
+  "attachment_payload_limit_exceeded",
+  "cannot_reply_to_message",
+  "channel_not_found",
+  "deprecated_endpoint",
+  "draft_already_deleted",
+  "draft_already_sent",
+  "draft_has_conflict",
+  "draft_not_found",
+  "duplicate_channel_not_found",
+  "duplicate_message_not_found",
+  "ekm_access_denied",
+  "enterprise_is_restricted",
+  "fatal_error",
+  "internal_error",
+  "invalid_arg_name",
+  "invalid_arguments",
+  "invalid_array_arg",
+  "invalid_auth",
+  "invalid_blocks",
+  "invalid_blocks_format",
+  "invalid_charset",
+  "invalid_form_data",
+  "invalid_metadata_format",
+  "invalid_metadata_schema",
+  "invalid_post_type",
+  "is_archived",
+  "markdown_text_conflict",
+  "message_limit_exceeded",
+  "messages_tab_disabled",
+  "metadata_must_be_sent_from_app",
+  "metadata_too_large",
+  "method_deprecated",
+  "missing_file_data",
+  "missing_post_type",
+  "missing_scope",
+  "msg_blocks_too_long",
+  "no_permission",
+  "no_text",
+  "not_allowed_token_type",
+  "not_authed",
+  "not_in_channel",
+  "org_login_required",
+  "rate_limited",
+  "ratelimited",
+  "request_timeout",
+  "restricted_action",
+  "restricted_action_non_threadable_channel",
+  "restricted_action_read_only_channel",
+  "restricted_action_thread_locked",
+  "restricted_action_thread_only_channel",
+  "send_on_behalf_not_allowed",
+  "service_unavailable",
+  "slack_connect_canvas_sharing_blocked",
+  "slack_connect_file_link_sharing_blocked",
+  "slack_connect_lists_sharing_blocked",
+  "team_access_not_granted",
+  "team_added_to_org",
+  "team_not_found",
+  "token_expired",
+  "token_revoked",
+  "too_many_attachments",
+  "too_many_contact_cards",
+  "two_factor_setup_required"
+];
+var POSTER = `
+const codes = ${JSON.stringify(Object.fromEntries(SLACK_ERROR_CODES.map((code) => [code, true])))};
+const token = process.env.LEGION_SLACK_BOT_TOKEN || "";
+const out = (value) => {
+  let line = JSON.stringify(value);
+  if (token !== "") line = line.split(token).join("[redacted]");
+  process.stdout.write(line + "\\n");
+};
+let sent = false;
+try {
+  const input = JSON.parse(await Bun.stdin.text());
+  if (token === "") {
+    out({ invalid: "the poster's environment carries no LEGION_SLACK_BOT_TOKEN" });
+    process.exit(0);
+  }
+  const base = (process.env.SLACK_POST_API_URL || "https://slack.com/api").replace(/\\/+$/, "");
+  let status = 0;
+  let raw = "";
+  try {
+    sent = true;
+    const response = await fetch(base + "/chat.postMessage", {
+      method: "POST",
+      headers: { Authorization: "Bearer " + token, "Content-Type": "application/json; charset=utf-8" },
+      body: JSON.stringify({ channel: input.channel, thread_ts: input.thread_ts, text: input.text }),
+      signal: AbortSignal.timeout(10000),
+    });
+    status = response.status;
+    raw = await response.text();
+  } catch {
+    out({ unanswered: true });
+    process.exit(0);
+  }
+  let answer;
+  try {
+    answer = JSON.parse(raw);
+  } catch {}
+  if (!answer || typeof answer !== "object" || typeof answer.ok !== "boolean") {
+    out({ invalid: "HTTP " + Number(status) + " with a body that is not Slack's JSON" });
+  } else if (!answer.ok) {
+    out({ refused: typeof answer.error === "string" && Object.hasOwn(codes, answer.error) ? answer.error : null });
+  } else if (
+    typeof answer.ts !== "string" || !/^[0-9]{1,12}\\.[0-9]{1,8}$/.test(answer.ts) ||
+    (answer.channel !== undefined && (typeof answer.channel !== "string" || !/^[CDG][A-Z0-9]{1,30}$/.test(answer.channel)))
+  ) {
+    out({ invalid: "ok with a ts or channel that is not Slack's" });
+  } else {
+    out({ ts: answer.ts, channel: answer.channel === undefined ? input.channel : answer.channel });
+  }
+} catch {
+  out(sent ? { unanswered: true } : { invalid: "a reply the poster could not read" });
+}
+`;
+var MAY_HAVE_POSTED = "the reply may have been posted, and posting it again may put it in the thread twice";
+var URL_CANDIDATE = /(?<![a-z0-9+.-])[a-z][a-z0-9+.-]{0,31}:\/\/[^\s<>|"'`]+/gi;
+var WEB_SCHEME = /^https?:\/\//i;
+var BARE_HOST = /(?<![\w@./:%-])((?:[a-z0-9-]{1,63}\.)*[a-z0-9-]{1,63})\.?(:\d{1,5})?(?![\w-])/gi;
+var BARE_IPV6 = /(?<![\w@./:%-])\[([0-9a-f:.]{2,45})(?:%[\w.-]{1,32})?\](?::\d{1,5})?/gi;
+var TRAILING_PUNCTUATION = /[.,;:!?)\]}]+$/;
+var CLUSTER_ADDRESSES = new BlockList;
+for (const [network, prefix] of [
+  ["0.0.0.0", 8],
+  ["10.0.0.0", 8],
+  ["100.64.0.0", 10],
+  ["127.0.0.0", 8],
+  ["169.254.0.0", 16],
+  ["172.16.0.0", 12],
+  ["192.168.0.0", 16]
+]) {
+  CLUSTER_ADDRESSES.addSubnet(network, prefix, "ipv4");
+}
+for (const [network, prefix] of [
+  ["::", 96],
+  ["fc00::", 7],
+  ["fe80::", 10]
+]) {
+  CLUSTER_ADDRESSES.addSubnet(network, prefix, "ipv6");
+}
+function linkInsideCluster(text, env) {
+  const { DISPATCH_URL: apiUrl, DISPATCH_PUBLIC_URL: publicUrl } = env;
+  const apiHost = hostOf(apiUrl);
+  const publicHost = hostOf(publicUrl);
+  const dispatchHost = apiHost !== undefined && publicHost !== undefined && apiHost !== publicHost ? apiHost : undefined;
+  const decoded = text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+  for (const match of decoded.matchAll(URL_CANDIDATE)) {
+    if (!WEB_SCHEME.test(match[0]))
+      continue;
+    for (const written of new Set([match[0], match[0].replace(TRAILING_PUNCTUATION, "")])) {
+      const host = hostOf(written);
+      if (host !== undefined && insideCluster(host, dispatchHost, true))
+        return written;
+    }
+  }
+  const prose = decoded.replace(URL_CANDIDATE, (url2) => " ".repeat(url2.length));
+  for (const match of prose.matchAll(BARE_IPV6)) {
+    if (insideCluster(`[${match[1]}]`, dispatchHost, false))
+      return match[0];
+  }
+  for (const match of prose.matchAll(BARE_HOST)) {
+    const host = (match[1] ?? "").toLowerCase();
+    if (!host.includes(".") && match[2] === undefined)
+      continue;
+    if (insideCluster(host, dispatchHost, false))
+      return match[0];
+  }
+  return;
+}
+function hostOf(value) {
+  if (value === undefined || value === "")
+    return;
+  try {
+    return new URL(value).hostname.toLowerCase().replace(/\.$/, "") || undefined;
+  } catch {
+    return;
+  }
+}
+function insideCluster(host, dispatchHost, fromUrl) {
+  if (host === dispatchHost)
+    return true;
+  if (host.endsWith(".svc") || host.includes(".svc.") || host.endsWith(".cluster.local"))
+    return true;
+  const address = host.startsWith("[") ? host.slice(1, -1) : host;
+  const family = isIP(address);
+  if (family !== 0)
+    return CLUSTER_ADDRESSES.check(address, family === 4 ? "ipv4" : "ipv6");
+  return fromUrl && !host.includes(".");
+}
+async function postSlackReply(reply, options = {}) {
+  const env = options.env ?? process.env;
+  const internal = linkInsideCluster(reply.text, env);
+  if (internal !== undefined) {
+    throw new Error(`the reply links ${internal}, an address inside the cluster nobody in Slack can open; link Dispatch's dashboard instead (dispatch prints it when DISPATCH_PUBLIC_URL is set); nothing was posted`);
+  }
+  const override = env[SLACK_POST_API_URL_VARIABLE];
+  if (override !== undefined && override !== "" && !allowedAPIURL(override)) {
+    throw new Error(`${SLACK_POST_API_URL_VARIABLE} must be an https URL, or http on a loopback host (got ${override}); nothing was posted`);
+  }
+  const { PATH: searchPath = "" } = env;
+  const client = Bun.which("agent-secrets", { PATH: searchPath });
+  if (client === null) {
+    throw new Error("agent-secrets is not on PATH: slack_post takes the bot token from the secrets broker, which this session is not enrolled with; nothing was posted");
+  }
+  const reason = `slack_post: reply in Slack channel ${reply.channel}, thread ${reply.threadTs}`;
+  const child = Bun.spawn([client, SLACK_BOT_TOKEN_SECRET, "--reason", reason, "--wait", "0s", "--", "bun", "-e", POSTER], {
+    env,
+    stdin: new Blob([
+      JSON.stringify({ channel: reply.channel, thread_ts: reply.threadTs, text: reply.text })
+    ]),
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  const timer = setTimeout(() => child.kill("SIGKILL"), POST_TIMEOUT_MS);
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited
+  ]).finally(() => clearTimeout(timer));
+  const said = stderr.trim().split(`
+`).filter(Boolean).join(" ");
+  const line = posterLine(stdout);
+  if (line === undefined) {
+    if (child.signalCode === "SIGKILL") {
+      throw new Error(`slack_post got no answer within ${POST_TIMEOUT_MS / 1000} s: ${MAY_HAVE_POSTED}`);
+    }
+    if (said.startsWith("agent-secrets:")) {
+      if (code === 75) {
+        throw new Error(`the secrets broker has not granted ${SLACK_BOT_TOKEN_SECRET}: its request is waiting for approval (${said}); nothing was posted`);
+      }
+      if (code === 77) {
+        throw new Error(`the secrets broker denied ${SLACK_BOT_TOKEN_SECRET} (${said}); nothing was posted`);
+      }
+      throw new Error(`the secrets broker did not release ${SLACK_BOT_TOKEN_SECRET} (${said}); nothing was posted`);
+    }
+    throw new Error(`slack_post's poster exited ${code} without an answer: ${MAY_HAVE_POSTED}`);
+  }
+  if (line.refused === null) {
+    throw new Error("Slack refused chat.postMessage with an error code slack_post does not pass on");
+  }
+  if (line.refused !== undefined)
+    throw new Error(`Slack refused chat.postMessage: ${line.refused}`);
+  if (line.unanswered !== undefined) {
+    throw new Error(`Slack did not answer chat.postMessage: ${MAY_HAVE_POSTED}`);
+  }
+  if (line.ts === undefined) {
+    throw new Error(`chat.postMessage answered ${line.invalid ?? "nothing"}: ${MAY_HAVE_POSTED}`);
+  }
+  return { channel: line.channel ?? reply.channel, threadTs: reply.threadTs, ts: line.ts };
+}
+function posterLine(stdout) {
+  const last = stdout.trim().split(`
+`).at(-1);
+  if (last === undefined || last === "")
+    return;
+  try {
+    const parsed = JSON.parse(last);
+    return typeof parsed === "object" && parsed !== null ? parsed : undefined;
+  } catch {
+    return;
+  }
+}
+function allowedAPIURL(value) {
+  let url2;
+  try {
+    url2 = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url2.protocol === "https:")
+    return true;
+  return url2.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]"].includes(url2.hostname);
+}
+
 // ../envoy-client/src/tool-contract.ts
 var DELIVERY_CONTRACT = "Delivery is at-least-once, possibly out of order across topics; use id for dedupe and at for freshness.";
 var TOPIC_GUIDE = "Topic guide (all are under notifications.): agent.<session_id> (subscribe: own inbox); role.<role> " + "(publish-to; holders claim via envoy_role_set). > matches one or more trailing tokens and does not " + "match the base subject. Envoy registers the concrete base when you subscribe to <subject>.>, so " + "the recommended default remains github.<owner>.<repo>.pr.<n>.>. <owner> and <repo> are one token " + "each, with every dot in the name written _ (sjawhar/.github is github.sjawhar._github; " + "acme/site.io is github.acme.site_io), and a topic spelled with the dot receives nothing. " + "Default PR subscription: " + "github.<owner>.<repo>.pr.<n>.> (it receives the quiet PR family): pr.<n> (lifecycle: " + "opened/synchronize/closed; closed carries merged, merge_commit_sha, merged_by, head_sha), " + "pr.<n>.comment, pr.<n>.review, pr.<n>.mention, pr.<n>.checks (one settlement event per commit whose checks settle, the head or not, naming its sha: " + 'passed/failed/cancelled/skipped with failing names and URLs; re-fires with superseded_settlement: "true" ' + "when new runs appear for the same commit). Other GitHub: issue.<n>, issue.<n>.comment, " + "issue.<n>.mention, mention, push.branch.<name>, push.tag.<name>, workflow.<file>.<action> (only " + "runs without an associated PR); slack.<team>.<channel>.message|mention and " + "slack.<team>.<channel>.thread.<ts>.message|mention; ghostwispr.<session>.<kind>; " + "whatsapp.<phone>.<jid>.<kind>; envoy.exceptions.<original-topic>.";
@@ -33735,7 +34038,8 @@ var EnvoyToolOperation = {
   setRole: "setRole",
   getRole: "getRole",
   whoami: "whoami",
-  listSessions: "listSessions"
+  listSessions: "listSessions",
+  slackPost: "slackPost"
 };
 var envoyToolSpecs = [
   {
@@ -33806,6 +34110,16 @@ var envoyToolSpecs = [
       title: schema.string().optional()
     }),
     operation: EnvoyToolOperation.listSessions
+  },
+  {
+    name: "slack_post",
+    description: "Reply in a Slack thread as the Legion Slack app, with the bot token the secrets broker grants this session (LEGION_SLACK_BOT_TOKEN); the session never holds it. channel is the Slack channel id (a mention's channel_id); thread_ts is the thread's root ts: the mention's thread_ts, or its own ts when it has none. Answers the new message's ts. A refusal carries Slack's own error code (not_in_channel: the app is not in that channel) or the broker's state (waiting for approval, denied). Sent once and never retried: after 'Slack did not answer' the reply may already be in the thread, so do not post it again.",
+    arguments: (schema) => ({
+      channel: schema.string({ min: 1 }).describe("Slack channel id, such as C0123ABCD."),
+      thread_ts: schema.string({ min: 1 }).describe("The thread's root ts, which keeps the reply in the mention's thread."),
+      text: schema.string({ min: 1, max: SLACK_POST_TEXT_MAX }).describe(`The reply, in Slack mrkdwn, at most ${SLACK_POST_TEXT_MAX} characters.`)
+    }),
+    operation: EnvoyToolOperation.slackPost
   }
 ];
 function sendConfirmationText(result) {
@@ -34070,7 +34384,7 @@ function sourceSession(sessionID) {
 
 // ../pi-shared/src/interface.ts
 import { logger } from "@oh-my-pi/pi-utils";
-var ENVOY_PLUGIN_INTERFACE_VERSION = 2;
+var ENVOY_PLUGIN_INTERFACE_VERSION = 3;
 var ENVOY_PLUGIN_INTERFACE_KEY = Symbol.for("legion.pi-shared.envoy-plugin-interface");
 var LEGION_PLUGIN_LOADED_KEY = Symbol.for("legion.pi-legion.loaded");
 var LEGACY_LEGION_LOADED_KEY = Symbol.for("legion.pi-envoy.legion-loaded");
@@ -34084,7 +34398,12 @@ function envoyPluginInterface() {
   const created = {
     version: ENVOY_PLUGIN_INTERFACE_VERSION,
     publishers: [],
-    roleClaim: { instances: [], managedSessions: new Set, regained: undefined },
+    roleClaim: {
+      instances: [],
+      managedSessions: new Set,
+      regained: undefined,
+      slackRoleOwned: false
+    },
     injectedUserTurns: new Map,
     bootstrappedSession: { file: undefined }
   };
@@ -35717,9 +36036,21 @@ function envoyExtension(pi) {
     });
     if (registry2 === undefined)
       return;
+    const retired = publishedInterface?.roleClaim.slackRoleOwned === true ? registry2.topics.filter((topic) => slackTopicChannel(topic) !== undefined) : [];
+    if (retired.length > 0) {
+      await client.unsubscribe({ sessionID, topics: retired }).catch((error48) => {
+        logger3.warn("envoy: could not unregister a resumed controller's retired Slack topics", {
+          sessionID,
+          topics: retired,
+          error: messageFor(error48)
+        });
+      });
+    }
     for (const topic of registry2.topics) {
       if (topic === agentSubject(sessionID) || topic.startsWith(ROLE_TOPIC_PREFIX))
         continue;
+      if (retired.includes(topic))
+        continue;
       await subscribe(topic);
     }
   };
@@ -36287,6 +36618,14 @@ Not delivered: that holder is the session this subagent sends as, and the listen
             title
           });
         }
+        case EnvoyToolOperation.slackPost: {
+          const posted = await postSlackReply({
+            channel: stringFor(parameters, "channel"),
+            threadTs: stringFor(parameters, "thread_ts"),
+            text: stringFor(parameters, "text")
+          });
+          return toolSuccess(`posted ${posted.ts} in ${posted.channel}, thread ${posted.threadTs}`, { channel: posted.channel, thread_ts: posted.threadTs, ts: posted.ts });
+        }
       }
     } catch (error48) {
       return toolFailure(error48);

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

@@ -57,8 +57,9 @@ dispatch://PROJECT/artifact/<document-ref>/comment/<id>
 ```
 
 A bare UUID or `KEY#seq` is not a reference; the `dispatch://` form is what Dispatch links and records. `dispatch read` also
-accepts the dashboard URL of an issue, spec, artifact, ask, comment, or project document on the configured server (it maps to the
-`dispatch://` form above), and an ask or comment id may be a unique prefix of at least 8 hex characters; a message id is always the
+accepts the dashboard URL of an issue, spec, artifact, ask, comment, or project document on the configured server, or on its public
+dashboard when `DISPATCH_PUBLIC_URL` names one (it maps to the `dispatch://` form above), and an issue's read names its page
+(`Link:`, on that public dashboard when there is one), the link to hand a person. An ask or comment id may be a unique prefix of at least 8 hex characters; a message id is always the
 full uuid. A non-uuid id on `GET /asks/{id}`, `/comments/{id}`, or `/issues/{key}/messages/{id}` is a 400 `ASK_ID_INPUT` /
 `COMMENT_ID_INPUT` / `MESSAGE_ID_INPUT`, never a 500.
 

package/dist/skills/envoy/SKILL.md

@@ -237,6 +237,12 @@ envoy_subscribe([
 This follows every message and mention in one thread. Channel-level topics end in `.message` or
 `.mention`; thread timestamps replace dots with underscores.
 
+Reply in a thread with `slack_post(channel=<channel_id>, thread_ts=<the message's thread_ts, or
+its ts>, text=…)`, which posts as the Legion Slack app with the bot token the secrets broker grants
+the session (`LEGION_SLACK_BOT_TOKEN`). A refusal carries Slack's own error code, or the broker's
+state when it has not granted the token. The post is sent once; when the answer is that Slack did
+not answer, the reply may already be there, so do not post it again.
+
 ## Ghost Wispr
 
 Ghost Wispr topics are `notifications.ghostwispr.<session>.<kind>`, where `kind` is

package/package.json

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