talon-agent 5.29.0 → 5.30.0

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

@@ -37,7 +37,14 @@ could do in one tool call, or work whose result you need in the next second
 
 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.`;
+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[] = [
   {
@@ -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",
+  },
+];

package/src/core/tools/types.ts

@@ -32,7 +32,8 @@ export type ToolTag =
   | "mesh"
   | "moderation"
   | "native"
-  | "backup";
+  | "backup"
+  | "secrets";
 
 /** The bridge caller signature — injected into execute(). */
 export type BridgeFunction = (

package/src/frontend/discord/commands/definitions.ts

@@ -17,6 +17,26 @@ import type { TalonConfig } from "../../../core/config/index.js";
 import { log, logError, logWarn } from "../../../util/log.js";
 import { getRepoRoot } from "../../../core/update/self-update.js";
 
+/** /secret — one-time paste link for a password (admin, DMs). */
+function secretCommand(): unknown {
+  return new SlashCommandBuilder()
+    .setName("secret")
+    .setDescription("Store a password via a one-time link (admin, DMs)")
+    .addStringOption((o) =>
+      o
+        .setName("name")
+        .setDescription("File name under ~/.talon/secrets")
+        .setRequired(true),
+    )
+    .addStringOption((o) =>
+      o
+        .setName("purpose")
+        .setDescription("What it's for (shown on the form)")
+        .setRequired(false),
+    )
+    .toJSON();
+}
+
 /**
  * /backup — its own builder: the definitions list is one long literal and
  * this is the only entry with two options and seven choices.
@@ -167,6 +187,7 @@ function buildCommandDefinitions(devBuild = false): unknown[] {
         ]
       : []),
     backupCommand(),
+    secretCommand(),
     new SlashCommandBuilder()
       .setName("admin")
       .setDescription("Admin operations (admin only)")

package/src/frontend/discord/commands/router.ts

@@ -38,6 +38,7 @@ import {
   handleSettings,
 } from "./settings.js";
 import { handleBackup } from "./backup.js";
+import { handleSecret } from "./secret.js";
 import {
   handleRestart,
   handleMetrics,
@@ -163,6 +164,8 @@ async function routeSlashCommand(
       return handleUpdate(interaction, config);
     case "backup":
       return handleBackup(interaction);
+    case "secret":
+      return handleSecret(interaction, chatId);
     case "admin":
       return handleAdmin(interaction, config, gateway);
     default:

package/src/frontend/discord/commands/secret.ts

@@ -0,0 +1,26 @@
+/**
+ * /secret name:<name> [purpose:<text>] — a single-use link to paste a
+ * password into instead of the channel. Rules and reply live in
+ * core/secrets; the reply is ephemeral either way.
+ */
+
+import type { ChatInputCommandInteraction } from "discord.js";
+import { secretCommandReply } from "../../../core/secrets/index.js";
+import { isAdmin } from "../handlers/index.js";
+import { reply } from "./interaction.js";
+
+export async function handleSecret(
+  i: ChatInputCommandInteraction,
+  chatId: string,
+): Promise<void> {
+  const name = (i.options.getString("name") ?? "").trim();
+  const purpose = (i.options.getString("purpose") ?? "").trim();
+  const text = secretCommandReply({
+    arg: `${name} ${purpose}`,
+    chatKey: chatId,
+    frontend: "discord",
+    isOperator: isAdmin(i.user.id),
+    isGroup: i.inGuild(),
+  });
+  await reply(i, text, true);
+}

package/src/frontend/native/bridge/routes/host.ts

@@ -178,6 +178,16 @@ export type BridgeServerHandlers = {
     | Promise<{ script: string; filename: string } | null>;
   /** Resolve a node-provisioning token to the binary to stream, or null. */
   openNodeBinary(token: string): { path: string; size: number } | null;
+  /** The secret-drop form for a live grant (not spent), or null. */
+  openSecretDrop(token: string): string | null;
+  /** Whether a secret-drop grant is live (checked before reading a body). */
+  isLiveSecretDrop(token: string): boolean;
+  /** Spend a secret-drop grant and store the value; the page to show. */
+  submitSecretDrop(
+    token: string,
+    body: string,
+    contentType: string | undefined,
+  ): Promise<{ status: number; html: string }>;
 };
 
 /**