talon-agent 5.28.0 → 5.30.0

package/src/core/secrets/drop.ts

@@ -0,0 +1,176 @@
+/**
+ * Secret drop: single-use, expiring grants that let the operator paste a
+ * password into a form served by the native bridge instead of into a chat.
+ *
+ * Same trust model as companion pairing (mesh/links/companion-pairing.ts):
+ * the bridge serves the grant pre-auth, and the random 192-bit grant in the
+ * query is the whole authorization. Differences:
+ *
+ *   - GET only shows the form and does NOT spend the grant. Chat apps
+ *     fetch links to build previews, and a preview must not burn the link
+ *     before the human opens it.
+ *   - POST spends it, once, whether or not the write then succeeds — a
+ *     failed write asks for a fresh link rather than leaving a live one
+ *     open to retries.
+ *
+ * The grant records which chat asked, so the receipt ("stored ✓ as <name>")
+ * goes back there. The value itself never leaves `consume` except into the
+ * file.
+ */
+
+import { randomBytes } from "node:crypto";
+
+/** Unused grants die after this long. */
+export const SECRET_GRANT_TTL_MS = 15 * 60 * 1000;
+
+export type SecretDropGrant = {
+  token: string;
+  /** Validated secret name — the file under ~/.talon/secrets. */
+  name: string;
+  /** Shown on the form so the operator knows what is being asked for. */
+  purpose?: string;
+  /** Chat that asked, for the receipt. */
+  chatKey: string;
+  /** Frontend that chat lives on. */
+  frontend: string;
+  createdAt: number;
+};
+
+export class SecretDropStore {
+  private readonly grants = new Map<string, SecretDropGrant>();
+
+  constructor(
+    private readonly ttlMs = SECRET_GRANT_TTL_MS,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  create(grant: Omit<SecretDropGrant, "token" | "createdAt">): SecretDropGrant {
+    this.sweep();
+    const full: SecretDropGrant = {
+      ...grant,
+      ...(grant.purpose ? { purpose: cleanPurpose(grant.purpose) } : {}),
+      token: randomBytes(24).toString("base64url"),
+      createdAt: this.now(),
+    };
+    this.grants.set(full.token, full);
+    return full;
+  }
+
+  /** A live grant, without spending it (the GET form). */
+  peek(token: string): SecretDropGrant | null {
+    this.sweep();
+    return this.grants.get(token) ?? null;
+  }
+
+  /** Spend a live grant (the POST). Null when unknown, expired or used. */
+  consume(token: string): SecretDropGrant | null {
+    this.sweep();
+    const grant = this.grants.get(token);
+    if (!grant) return null;
+    this.grants.delete(token);
+    return grant;
+  }
+
+  private sweep(): void {
+    const cutoff = this.now() - this.ttlMs;
+    for (const [token, grant] of this.grants) {
+      if (grant.createdAt <= cutoff) this.grants.delete(token);
+    }
+  }
+}
+
+/** Purposes come from the model: one line, no markup, bounded. */
+function cleanPurpose(purpose: string): string {
+  return purpose
+    .replace(/[\r\n\t]+/g, " ")
+    .trim()
+    .slice(0, 200);
+}
+
+/** Minimal HTML escape for values interpolated into the pages. */
+function esc(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+const STYLE = `:root { color-scheme: light dark; }
+  body { margin: 0; padding: 24px; font: 15px/1.5 system-ui, sans-serif; }
+  main { max-width: 32rem; margin: 0 auto; }
+  h1 { font-size: 1.25rem; margin: 0 0 .25rem; }
+  p.sub { margin: 0 0 1.25rem; opacity: .7; }
+  textarea { box-sizing: border-box; width: 100%; min-height: 6rem; padding: 10px;
+             font: 14px ui-monospace, monospace; border-radius: 8px; }
+  button { margin-top: 12px; width: 100%; padding: 14px; border: 0; border-radius: 10px;
+           background: #2f6fed; color: #fff; font-weight: 600; font-size: 1rem; }
+  footer { margin-top: 1.5rem; font-size: .8rem; opacity: .6; }`;
+
+/**
+ * One self-contained page, no script and no external assets. `no-referrer`
+ * keeps the grant out of any Referer and makes the browser send
+ * `Origin: null` on the POST; the bridge also accepts its own origin there.
+ */
+function page(title: string, body: string): string {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="referrer" content="no-referrer">
+<meta name="robots" content="noindex">
+<title>${esc(title)}</title>
+<style>
+  ${STYLE}
+</style>
+</head>
+<body>
+<main>
+${body}
+</main>
+</body>
+</html>
+`;
+}
+
+/** The paste form for a live grant. */
+export function secretDropForm(grant: SecretDropGrant): string {
+  const minutes = Math.round(SECRET_GRANT_TTL_MS / 60_000);
+  return page(
+    "Talon secret drop",
+    `  <h1>Store a secret</h1>
+  <p class="sub">Saved as <b>${esc(grant.name)}</b> on the Talon host.${
+    grant.purpose ? `<br>For: ${esc(grant.purpose)}` : ""
+  }</p>
+  <form method="post" action="?grant=${esc(grant.token)}" autocomplete="off">
+    <textarea name="value" required autofocus spellcheck="false"
+      autocapitalize="off" autocorrect="off" aria-label="Secret value"></textarea>
+    <button type="submit">Store</button>
+  </form>
+  <footer>The value goes straight to a file readable only by Talon's user. It is
+  not posted to the chat or shown to the model. This link works once and expires
+  ${minutes} minutes after it was made.</footer>`,
+  );
+}
+
+/** What the browser sees after a POST. */
+export function secretDropResult(
+  ok: boolean,
+  name: string | null,
+  error?: string,
+): string {
+  return ok && name
+    ? page(
+        "Stored",
+        `  <h1>Stored ✓</h1>
+  <p class="sub">Saved as <b>${esc(name)}</b>. You can close this page.</p>`,
+      )
+    : page(
+        "Not stored",
+        `  <h1>Not stored</h1>
+  <p class="sub">${esc(error ?? "This link is unknown, expired, or already used.")}</p>
+  <footer>Ask for a fresh link with /secret &lt;name&gt;.</footer>`,
+      );
+}

package/src/core/secrets/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Secrets — the ~/.talon/secrets folder and the drop links that fill it
+ * without a password ever crossing a chat.
+ */
+
+export {
+  isLiveSecretDrop,
+  openSecretDropForm,
+  secretCommandReply,
+  submitSecretDrop,
+} from "./service.js";

package/src/core/secrets/service.ts

@@ -0,0 +1,248 @@
+/**
+ * The secret-drop service: mint a link (`/secret <name>`, `request_secret`),
+ * serve its form, take the POST, write the file, and tell the chat.
+ *
+ * Frontends and the gateway call {@link requestSecretDrop}; the native
+ * bridge calls {@link openSecretDropForm} and {@link submitSecretDrop}.
+ * Core never imports a frontend, so the receipt goes out through the same
+ * cross-send broker `send_via` uses.
+ *
+ * The value path is: request body → {@link parseSubmittedValue} →
+ * {@link writeSecret}. It is never logged, returned, persisted elsewhere
+ * or put into the receipt.
+ */
+
+import { log, logWarn } from "../../util/log.js";
+import {
+  isDiscordChatId,
+  isNativeChatId,
+  isTeamsChatId,
+  isTelegramChatId,
+  isTerminalChatId,
+  isWhatsAppChatId,
+  numericChatIdFor,
+} from "../frontend-runtime/chat-id.js";
+import { crossSendTarget } from "../engine/gateway-actions/cross-send.js";
+import { getMeshService } from "../mesh/index.js";
+import {
+  SECRET_GRANT_TTL_MS,
+  SecretDropStore,
+  secretDropForm,
+  secretDropResult,
+} from "./drop.js";
+import { secretNameProblem, writeSecret } from "./store.js";
+
+export type SecretDropRequest = {
+  name: unknown;
+  purpose?: unknown;
+  /** Canonical key of the chat that asked (receives the receipt). */
+  chatKey: string;
+  /** Frontend that chat lives on; inferred from the key when absent. */
+  frontend?: string;
+};
+
+export type SecretDropDeps = {
+  store: SecretDropStore;
+  /** The bridge's public base URL, or why there isn't one. */
+  baseUrl: () => { ok: true; url: string } | { ok: false; text: string };
+  write: typeof writeSecret;
+  notify: (frontend: string, chatKey: string, text: string) => Promise<void>;
+};
+
+/** The frontend a chat key belongs to, from its shape. */
+function frontendForChatKey(chatKey: string): string | undefined {
+  if (isNativeChatId(chatKey)) return "native";
+  if (isDiscordChatId(chatKey)) return "discord";
+  if (isWhatsAppChatId(chatKey)) return "whatsapp";
+  if (isTeamsChatId(chatKey)) return "teams";
+  if (isTerminalChatId(chatKey)) return "terminal";
+  if (isTelegramChatId(chatKey)) return "telegram";
+  return undefined;
+}
+
+async function notifyChat(
+  frontend: string,
+  chatKey: string,
+  text: string,
+): Promise<void> {
+  const handler = crossSendTarget(frontend);
+  if (!handler) return;
+  await handler(
+    { action: "send_message", text, target: chatKey },
+    numericChatIdFor(chatKey),
+  );
+}
+
+function meshBaseUrl(): ReturnType<SecretDropDeps["baseUrl"]> {
+  return getMeshService().bridgeBaseUrl();
+}
+
+let deps: SecretDropDeps = {
+  store: new SecretDropStore(),
+  baseUrl: meshBaseUrl,
+  write: writeSecret,
+  notify: notifyChat,
+};
+
+/** Swap collaborators (tests). Returns the previous set. */
+export function setSecretDropDeps(
+  next: Partial<SecretDropDeps>,
+): SecretDropDeps {
+  const prev = deps;
+  deps = { ...deps, ...next };
+  return prev;
+}
+
+/**
+ * Mint a link for one secret. The text is what the chat (or the model)
+ * gets: the link, the name, the expiry — never a value.
+ */
+export function requestSecretDrop(
+  req: SecretDropRequest,
+): { ok: true; text: string; link: string } | { ok: false; text: string } {
+  const problem = secretNameProblem(req.name);
+  if (problem) return { ok: false, text: `Invalid secret name: ${problem}.` };
+  const name = req.name as string;
+  const frontend = req.frontend ?? frontendForChatKey(req.chatKey);
+  if (!frontend) {
+    return { ok: false, text: "Can't tell which chat to confirm the drop in." };
+  }
+  const base = deps.baseUrl();
+  if (!base.ok) return { ok: false, text: base.text };
+  if (!base.url.startsWith("https://")) {
+    return {
+      ok: false,
+      text: "The bridge is plain HTTP, and a password must not cross the network unencrypted. Enable native TLS or set native.publicUrl to an https:// address.",
+    };
+  }
+  const purpose =
+    typeof req.purpose === "string" && req.purpose.trim()
+      ? req.purpose.trim()
+      : undefined;
+  const grant = deps.store.create({
+    name,
+    chatKey: req.chatKey,
+    frontend,
+    ...(purpose ? { purpose } : {}),
+  });
+  const link = `${base.url}/secret?grant=${grant.token}`;
+  const minutes = Math.round(SECRET_GRANT_TTL_MS / 60_000);
+  log("secrets", `Secret drop link minted for "${name}" (chat ${req.chatKey})`);
+  return {
+    ok: true,
+    link,
+    text: [
+      `Open this link to store the secret "${name}":`,
+      "",
+      `  ${link}`,
+      "",
+      `Single-use, expires in ${minutes} minutes. The value is written to ~/.talon/secrets/${name} (mode 600); it never goes through the chat or the model. This chat gets a confirmation when it's stored.`,
+    ].join("\n"),
+  };
+}
+
+/** GET /secret — the form for a live grant (not spent), or null. */
+export function openSecretDropForm(token: string): string | null {
+  const grant = token ? deps.store.peek(token) : null;
+  return grant ? secretDropForm(grant) : null;
+}
+
+/** Whether a POST for `token` is worth reading the body of. */
+export function isLiveSecretDrop(token: string): boolean {
+  return Boolean(token && deps.store.peek(token));
+}
+
+/**
+ * The value out of a form POST (`application/x-www-form-urlencoded`) or a
+ * plain-text body. Null when there is none.
+ */
+function parseSubmittedValue(
+  body: string,
+  contentType: string | undefined,
+): string | null {
+  if ((contentType ?? "").includes("application/x-www-form-urlencoded")) {
+    return new URLSearchParams(body).get("value");
+  }
+  return body || null;
+}
+
+/**
+ * POST /secret — spend the grant, write the value, send the receipt.
+ * Returns the page the browser sees. The grant is spent even when the
+ * write fails, so a failure means "ask again", never "retry this link".
+ */
+export async function submitSecretDrop(
+  token: string,
+  body: string,
+  contentType: string | undefined,
+): Promise<{ status: number; html: string }> {
+  const grant = token ? deps.store.consume(token) : null;
+  if (!grant) return { status: 404, html: secretDropResult(false, null) };
+  const value = parseSubmittedValue(body, contentType);
+  if (!value) {
+    return {
+      status: 400,
+      html: secretDropResult(false, null, "No value was submitted."),
+    };
+  }
+  const written = await deps.write(grant.name, value);
+  if (!written.ok) {
+    logWarn(
+      "secrets",
+      `Secret drop for "${grant.name}" failed: ${written.error}`,
+    );
+    return { status: 500, html: secretDropResult(false, null, written.error) };
+  }
+  log("secrets", `Secret "${grant.name}" stored via drop link`);
+  try {
+    await deps.notify(
+      grant.frontend,
+      grant.chatKey,
+      `stored ✓ as ${grant.name}`,
+    );
+  } catch (err) {
+    logWarn(
+      "secrets",
+      `Secret drop receipt to ${grant.frontend} chat ${grant.chatKey} failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  return { status: 200, html: secretDropResult(true, grant.name) };
+}
+
+export type SecretCommandContext = {
+  /** Everything after `/secret`. */
+  arg: string;
+  chatKey: string;
+  frontend: string;
+  /** Whether the sender may write into the operator's secrets folder. */
+  isOperator: boolean;
+  /** Whether this chat has more than one human in it. */
+  isGroup: boolean;
+};
+
+/**
+ * `/secret <name> [purpose]` — the reply every frontend sends. One
+ * implementation, so the rules (operator only, DMs only, the usage line)
+ * are the same on Telegram, Discord, WhatsApp and the native app.
+ */
+export function secretCommandReply(ctx: SecretCommandContext): string {
+  if (!ctx.isOperator) return "Only the operator can store secrets.";
+  if (ctx.isGroup) {
+    return "Run /secret in a private chat with me: a drop link writes to the secrets folder for whoever opens it, so it doesn't belong in a group.";
+  }
+  const [name = "", ...rest] = ctx.arg.trim().split(/\s+/);
+  if (!name) {
+    return [
+      "Usage: /secret <name> [what it's for]",
+      "",
+      "Sends a single-use link to a paste form. The value is saved to ~/.talon/secrets/<name> and never goes through the chat. Don't paste passwords here.",
+    ].join("\n");
+  }
+  const minted = requestSecretDrop({
+    name,
+    purpose: rest.join(" "),
+    chatKey: ctx.chatKey,
+    frontend: ctx.frontend,
+  });
+  return minted.text;
+}

package/src/core/secrets/store.ts

@@ -0,0 +1,100 @@
+/**
+ * The secrets folder — one file per value under ~/.talon/secrets/, mode 600.
+ *
+ * Writes are atomic (temp file in the same directory, fsync, rename), so a
+ * crash mid-write leaves the old value or the new one, never half of
+ * either. Names are a closed alphabet, checked before any path is built,
+ * and the resolved path must sit directly inside the folder — a name can
+ * never climb out of it or into a subdirectory.
+ *
+ * Nothing here logs a value, and no error message carries one.
+ */
+
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, open, rename, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { dirs } from "../../util/paths.js";
+
+/** Largest value the drop accepts. A password, a key file, not a dump. */
+const MAX_SECRET_BYTES = 64 * 1024;
+
+/**
+ * Letters, digits, `.`, `_`, `-`; starts with a letter or digit; at most
+ * 64 characters. No separators, so no traversal; no leading dot, so no
+ * hidden files and no `..`.
+ */
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/** Why `name` can't be a secret name, or undefined when it can. */
+export function secretNameProblem(name: unknown): string | undefined {
+  if (typeof name !== "string" || !name) return "a name is required";
+  if (!NAME_RE.test(name)) {
+    return "use 1-64 letters, digits, '.', '_' or '-', starting with a letter or digit";
+  }
+  if (name.includes("..")) return "'..' is not allowed in a name";
+  return undefined;
+}
+
+/** The folder secrets live in. Overridable for tests. */
+function secretsDir(): string {
+  return dirs.secrets;
+}
+
+/**
+ * The file a name maps to, or an error. Checks the name and then the
+ * resolved path, so the second check still holds if the first ever widens.
+ */
+export function secretPath(
+  name: string,
+  dir: string = secretsDir(),
+): { ok: true; path: string } | { ok: false; error: string } {
+  const problem = secretNameProblem(name);
+  if (problem) return { ok: false, error: `Invalid secret name: ${problem}` };
+  const root = resolve(dir);
+  const path = resolve(root, name);
+  if (dirname(path) !== root) {
+    return { ok: false, error: "Invalid secret name: it leaves the folder" };
+  }
+  return { ok: true, path };
+}
+
+/**
+ * Write one secret atomically with mode 600, creating the folder (700)
+ * when it's missing. A trailing newline from a paste is dropped; nothing
+ * else about the value is touched.
+ */
+export async function writeSecret(
+  name: string,
+  value: string,
+  dir: string = secretsDir(),
+): Promise<{ ok: true; path: string } | { ok: false; error: string }> {
+  const target = secretPath(name, dir);
+  if (!target.ok) return target;
+  const clean = value.replace(/\r?\n$/, "");
+  if (!clean) return { ok: false, error: "The value is empty" };
+  if (Buffer.byteLength(clean, "utf8") > MAX_SECRET_BYTES) {
+    return { ok: false, error: "The value is too large" };
+  }
+  const root = resolve(dir);
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  // mkdir's mode is masked by umask and ignored for a folder that exists.
+  await chmod(root, 0o700).catch(() => {});
+  const temp = join(root, `.${name}.${randomBytes(6).toString("hex")}.tmp`);
+  try {
+    const fh = await open(temp, "wx", 0o600);
+    try {
+      await fh.writeFile(clean, "utf8");
+      await fh.sync();
+    } finally {
+      await fh.close();
+    }
+    await chmod(temp, 0o600);
+    // rename replaces a symlink at the target, never what it points to.
+    await rename(temp, target.path);
+  } catch (err) {
+    await rm(temp, { force: true }).catch(() => {});
+    const code = (err as NodeJS.ErrnoException).code ?? "error";
+    return { ok: false, error: `Could not write the secret (${code})` };
+  }
+  return { ok: true, path: target.path };
+}

package/src/core/tools/index.ts

@@ -29,6 +29,7 @@ import { whatsappTools } from "./chat/whatsapp.js";
 import { moderationTools } from "./chat/moderation.js";
 import { nativeTools } from "./ops/native.js";
 import { backupTools } from "./ops/backup.js";
+import { secretTools } from "./ops/secrets.js";
 
 /** All built-in tool definitions. */
 export const ALL_TOOLS: readonly ToolDefinition[] = [
@@ -57,6 +58,7 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...agentTools,
   ...backupTools,
   ...preflightTools,
+  ...secretTools,
 ];
 
 /**

package/src/core/tools/ops/agents.ts

@@ -35,9 +35,16 @@ Bad uses: anything needing a back-and-forth with the user, trivial work you
 could do in one tool call, or work whose result you need in the next second
 (spawning costs a model cold-start).
 
-Backend and model default to this chat's; pass them to put the agent
-somewhere else (e.g. a cheap model for a mechanical sweep, or a backend with
-a bigger context window). Returns the agent id immediately.`;
+Backend and model default to the caller's (a sub-agent's own children
+inherit its backend and model); pass them to put the agent somewhere else (e.g. a cheap model for a mechanical sweep, or a backend with
+a bigger context window). Returns the agent id immediately.
+
+There is no hard timeout unless you pass timeout_s (or the deployment sets
+one): an agent runs until it reports, is killed, or goes quiet. A no-progress
+watchdog pings an agent that has made no tool call or output for a while,
+then tells you, then kills it. A killed, timed-out or stalled agent's report
+still carries its last interim messages, progress notes and the files it
+changed, so its work is not lost.`;
 
 export const agentTools: ToolDefinition[] = [
   {
@@ -61,13 +68,13 @@ export const agentTools: ToolDefinition[] = [
         .string()
         .optional()
         .describe(
-          "Backend id to run on. Unset = this chat's backend (agents inherit their parent's). Must have a background capability.",
+          "Backend id to run on. Unset = inherit: an agent's children run on its own backend and model; a chat's spawns start from the chat's backend (and may be routed to one with more headroom). Must have a background capability and, when the deployment sets agents.allowedBackends, be on that list.",
         ),
       model: z
         .string()
         .optional()
         .describe(
-          "Model id on the chosen backend. Unset = that backend's default model. Call list_models for valid ids.",
+          "Model id on the chosen backend. Unset = the parent agent's model when the backend is inherited from one, else that backend's default model. Call list_models for valid ids.",
         ),
       effort: z
         .enum(["minimal", "low", "medium", "high", "xhigh"])
@@ -81,7 +88,7 @@ export const agentTools: ToolDefinition[] = [
         .positive()
         .optional()
         .describe(
-          "Hard wall-clock cap in seconds (default 900, min 30, max 3600). On timeout the agent is aborted and you are told.",
+          "Optional hard wall-clock cap in seconds (min 30). Unset = no cap unless the deployment sets agents.defaultTimeoutMs; agents.maxTimeoutMs, when set, caps every run. Stalled agents are ended by the no-progress watchdog regardless. On timeout the agent is aborted and you are told, with what it had done so far.",
         ),
       preflight: z
         .boolean()
@@ -193,8 +200,15 @@ export const agentTools: ToolDefinition[] = [
   {
     name: "list_peers",
     description:
-      "Sub-agents only. List the other agents your parent spawned alongside you — id, label and what each is working on. These are the only agents you may message directly with message_peer. Call it before assuming you are working alone.",
-    schema: {},
+      'Sub-agents only. List the other live agents you can message with message_peer — id, label, how they relate to you and what each is working on. Default scope "siblings": the agents your parent spawned alongside you. Scope "tree": every live agent working for the same chat — your parent, children, siblings and cousins. Call it before assuming you are working alone.',
+    schema: {
+      scope: z
+        .enum(["siblings", "tree"])
+        .optional()
+        .describe(
+          'Which agents to list: "siblings" (default) or the whole "tree" under your chat.',
+        ),
+    },
     execute: (params, bridge) => bridge("list_peers", params),
     tag: "agents",
   },
@@ -202,10 +216,14 @@ export const agentTools: ToolDefinition[] = [
   {
     name: "message_peer",
     description:
-      "Sub-agents only. Send a note straight to a peer — an agent spawned by the same parent as you — without routing it through your parent. Use it when you find something that changes another agent's work: a shared fact, a dead end worth not repeating, a correction to something you sent earlier. The peer sees it at its next check_inbox, so it is not an interrupt. You can only address peers (see list_peers); any other id is refused. This does not end your run and does not replace report_result.",
+      "Sub-agents only. Send a note straight to any live agent in your tree — a sibling, your parent agent, a child, or a cousin working for the same chat — by id or label, without routing it through anyone. Use it when you find something that changes another agent's work: a shared fact, a dead end worth not repeating, a correction to something you sent earlier. It sees the note at its next check_inbox, so it is not an interrupt. Agents working for another chat are never reachable. This does not end your run and does not replace report_result.",
     schema: {
-      agent_id: z.string().describe("Peer agent id, from list_peers"),
-      text: z.string().min(1).describe("What the peer needs to know"),
+      agent_id: z
+        .string()
+        .describe(
+          "Target agent id (or its exact label, when no other live agent in your tree shares it), from list_peers",
+        ),
+      text: z.string().min(1).describe("What the agent needs to know"),
     },
     execute: (params, bridge) => bridge("message_peer", params),
     tag: "agents",
@@ -229,7 +247,7 @@ export const preflightTools: ToolDefinition[] = [
   {
     name: "run_preflight",
     description:
-      "Run the pre-flight lane (`npm run preflight`: typecheck, lint, format, architecture/knip/ratchet gates, the unit tests touched by your diff, gitleaks) in a talon checkout on the daemon host and get its verdict. Run it before every `git push` on a PR branch and push only when it is GREEN; a RED result lists each failing step with the tail of its log. Takes a few minutes (hard cap 10). Needs `npm ci` done in the checkout.",
+      "Run the pre-flight lane (`npm run preflight`: typecheck, lint, format, architecture/knip/ratchet gates, the unit tests touched by your diff, gitleaks) in a talon checkout on the daemon host and get its verdict. Run it before every `git push` on a PR branch and push only when it is GREEN; a RED result lists each failing step with the tail of its log. Takes a few minutes (hard cap 10). Needs node_modules in the checkout: make worktrees with `node scripts/worktree.mjs add <path> <branch>` (hardlinked shared install, ~0 extra disk) rather than `npm ci`.",
     schema: {
       cwd: z
         .string()

package/src/core/tools/ops/secrets.ts

@@ -0,0 +1,36 @@
+/**
+ * Secret tools — ask the operator for a password without it crossing the
+ * chat. The tool mints a single-use link to a paste form on the native
+ * bridge; the value lands in ~/.talon/secrets/<name> and the chat gets a
+ * receipt. The model sees the link and the name, never the value.
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "../types.js";
+
+export const secretTools: ToolDefinition[] = [
+  {
+    name: "request_secret",
+    description: `Ask the operator for a secret (password, API key, token) without it passing through the chat. Mints a single-use link, valid about 15 minutes, to a paste form served by Talon's native bridge (the agent-tool twin of /secret <name>). The value is written to ~/.talon/secrets/<name> (mode 600) and this chat gets "stored ✓ as <name>" when it lands. You never see the value: read it from the file when a command needs it, e.g. "$(cat ~/.talon/secrets/<name>)", and never echo it.
+
+Use this whenever you need a credential, and point the operator to it if they start pasting one into the chat. Requires the native bridge on an https:// address.`,
+    schema: {
+      name: z
+        .string()
+        .min(1)
+        .max(64)
+        .describe(
+          "File name under ~/.talon/secrets: letters, digits, '.', '_' or '-', starting with a letter or digit (e.g. 'gmail-app-password'). An existing secret of that name is replaced.",
+        ),
+      purpose: z
+        .string()
+        .max(200)
+        .optional()
+        .describe(
+          "One line shown on the form so the operator knows what it's for (e.g. 'Gmail app password for the email plugin').",
+        ),
+    },
+    execute: (params, bridge) => bridge("request_secret", params),
+    tag: "secrets",
+  },
+];