talon-agent 5.5.1 → 5.7.0

package/README.md

@@ -249,6 +249,7 @@ The `native` frontend turns the daemon into a **client bridge** — a versioned
 - **Local (desktop):** the app connects to a Talon on the same machine and launches one if needed (`TALON_FRONTEND_OVERRIDE=desktop`).
 - **Remote (mobile/LAN):** point the app at `host:port` + token; the bridge requires `Authorization: Bearer …` (or `?token=` on the SSE stream) whenever a token is set.
 - **Encryption:** off-loopback binds serve **HTTPS by default** with a persistent self-signed certificate (`~/.talon/keys/`); the companion pins its SHA-256 fingerprint on first connect and refuses any change afterwards. The daemon logs the fingerprint at startup and `/health` advertises it. Opt out (or in, on loopback) with `"tls": false` / `true` in the `native` section.
+- **From anywhere, certificate-only (Immich-style):** put your reverse proxy (Caddy, nginx, Traefik, Cloudflare Tunnel) in front with client-certificate auth; import the `.p12` in the companion, which also switches to your home-network address whenever it answers. Talon still authenticates with its token — see [docs/mtls.md](docs/mtls.md).
 
 The app **keeps itself up to date** — it watches this repo's releases and installs the next one itself (silently on a rooted/Shizuku phone, swap-and-relaunch on desktop; see [docs/companion-updates.md](docs/companion-updates.md)). It provides multi-chat history, live streaming with reasoning + tool-call visibility, per-chat model/effort/reset, and **settings sync** — read and change the daemon's own config (default model, display name, timezone, pulse/heartbeat/dream) and restart it. See [apps/companion/README.md](apps/companion/README.md).
 
@@ -529,7 +530,7 @@ Commands: `/model`, `/effort`, `/context`, `/status`, `/reset`, `/rename`, `/res
 
 ## Production
 
-**Docker:** the image runs the daemon on Bun (`bun src/index.ts`); `~/.talon` and `~/.claude` are bind-mounted from the host into the container's `HOME=/home/bun`.
+**Docker:** the image runs the daemon on Bun (`bun src/index.ts`); `~/.talon` and `~/.claude` are bind-mounted from the host into the container's `HOME=/home/bun`. Prebuilt images are on GHCR (`ghcr.io/dylanneve1/talon:latest`), and a first boot can be configured entirely from `TALON_*` environment variables — see **[docs/docker.md](docs/docker.md)** for the quick install, and **[docs/truenas.md](docs/truenas.md)** for a step-by-step TrueNAS SCALE install.
 
 ```bash
 docker compose up -d
@@ -537,6 +538,8 @@ docker compose up -d
 
 A Node 24 + tsx image is kept as a fallback for one release cycle: `docker build --build-arg RUNTIME=node -t talon .` (or set `build.args.RUNTIME` in `docker-compose.yml`). Mount paths are the same for both. See [`packaging/README.md`](packaging/README.md#docker-image) for the build's details.
 
+The image is also ready for the **Antigravity (`agy`) backend**: add `-f docker-compose.agy.yml` to mount `~/.gemini` and the `agy` binary (or bake the binary in with `AGY_DOWNLOAD_URL` + `AGY_SHA256`). See [docs/docker.md](docs/docker.md#antigravity-agy-backend).
+
 **Systemd:** unit file at `packaging/systemd/talon.service` — copy to `/etc/systemd/system/`, set `User=` and `WorkingDirectory=`, then `systemctl enable --now talon`.
 
 **Health endpoint:** `GET http://localhost:19876/health` returns JSON with uptime, memory, queue depth, active sessions, and last activity timestamp.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.5.1",
+  "version": "5.7.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/src/backend/claude-sdk/options.ts

@@ -34,6 +34,16 @@ import { reportToolFingerprint } from "../runtime/cache/cache-metrics.js";
 import { log, logError } from "../../util/log.js";
 import { getConfig, getBridgePort } from "./state.js";
 import { ALLOWED_TOOLS_CHAT, EFFORT_MAP } from "./constants.js";
+import {
+  isGuestChat,
+  isGuestPluginAllowed,
+} from "../../core/mcp-hub/guest-scope.js";
+import { VALID_TOOL_FRONTENDS } from "../../core/mcp-hub/talon-server.js";
+
+/** `telegram-tools`, `whatsapp-tools`, ... — the hub's own frontend servers. */
+function isFrontendToolServerName(name: string): boolean {
+  return name.endsWith("-tools") && VALID_TOOL_FRONTENDS.has(name.slice(0, -6));
+}
 
 /**
  * Built-in SDK tools that Talon's native tool set replaces when
@@ -383,14 +393,28 @@ export function buildSdkOptions(
   const { postToolUseFailureHook, postToolBatchHook } =
     buildTurnTerminatorHooks();
 
-  const builtinTools = config.nativeTools
-    ? ALLOWED_TOOLS_CHAT.filter((t) => !NATIVE_REPLACED_BUILTINS.has(t))
-    : [...ALLOWED_TOOLS_CHAT];
-
-  const mcpServers = {
+  // Guest DMs (non-operator) get no SDK built-ins at all — Bash/Read/
+  // Write/Skill live outside the hub, so the hub's guest scope can't hide
+  // them — and only the plugin servers the guest scope allows.
+  const guest = isGuestChat(chatId);
+  const builtinTools = guest
+    ? []
+    : config.nativeTools
+      ? ALLOWED_TOOLS_CHAT.filter((t) => !NATIVE_REPLACED_BUILTINS.has(t))
+      : [...ALLOWED_TOOLS_CHAT];
+
+  const allServers = {
     ...buildMcpServers(chatId),
     ...buildPluginMcpServers(chatId),
   };
+  const mcpServers = guest
+    ? Object.fromEntries(
+        Object.entries(allServers).filter(
+          ([name]) =>
+            isFrontendToolServerName(name) || isGuestPluginAllowed(name),
+        ),
+      )
+    : allServers;
 
   // Tool definitions render BEFORE the system prompt, so a set that shifts
   // mid-session invalidates the system prompt and every cached message after

package/src/bootstrap.ts

@@ -144,6 +144,8 @@ export async function bootstrap(
     disabledToolTags: config.disabledToolTags,
     braveApiKey: config.braveApiKey,
     nativeTools: config.nativeTools,
+    guestDmScope: config.guestDmScope,
+    adminUserId: config.adminUserId,
   });
 
   initWorkspace(config.workspace);

package/src/core/config/index.ts

@@ -192,6 +192,16 @@ const nativeConfigSchema = z
      * working zero-config).
      */
     tls: z.boolean().optional(),
+    /**
+     * The URL other devices should dial, when it isn't the bind address —
+     * a container (Docker, TrueNAS) or anything behind NAT or a proxy,
+     * where the bridge only sees its internal IP. Used for pairing links,
+     * node installers and `/mesh`. e.g. "https://truenas.lan:19880".
+     */
+    publicUrl: z
+      .string()
+      .regex(/^https?:\/\/\S+$/, "native.publicUrl must be an http(s) URL")
+      .optional(),
   })
   .strict();
 
@@ -608,6 +618,22 @@ const configSchema = z.object({
   disabledTools: z.array(z.string()).optional(),
   disabledToolTags: z.array(z.string()).optional(),
 
+  /**
+   * Conversation-only tool surface for DMs from anyone who isn't an
+   * operator. The admin's Telegram DM and any `operatorChats` keep
+   * everything; other DMs (Telegram user ids, `wa_dm_*`) get reply/react/
+   * history/stickers plus the `guestPlugins` servers — no shell, files,
+   * mail, devices, cron, memory, agents or cross-chat sends. Groups are
+   * unaffected. Off by default. See core/mcp-hub/guest-scope.ts.
+   */
+  guestDmScope: z
+    .object({
+      enabled: z.boolean().default(false),
+      operatorChats: z.array(z.string()).default([]),
+      guestPlugins: z.array(z.string()).optional(),
+    })
+    .optional(),
+
   /**
    * Developer build flag. Gates dev-only affordances such as the
    * `/update` self-update command. Off by default so packaged /

package/src/core/mcp-hub/guest-scope.ts

@@ -0,0 +1,142 @@
+/**
+ * Guest DM tool scope.
+ *
+ * Anyone the operator lets DM the bot gets the same agent the operator
+ * gets: shell, files, mail, mesh devices, cron, memory, cross-chat sends.
+ * With `guestDmScope.enabled`, a DM from anyone who is not an operator gets a
+ * conversation-only surface instead, enforced here in the hub, so it holds
+ * for every backend that reaches tools through the hub:
+ *
+ *   - Talon tools: an explicit allowlist (reply, react, edit/delete own
+ *     messages, read this chat's history and media, look at stickers).
+ *     Nothing that runs code, touches files, schedules, remembers, spawns
+ *     agents, reaches devices or acts on another chat.
+ *   - Parameters: a guest session may only target its own chat and may
+ *     never attach a local file by path (`send(file_path=…)` would
+ *     otherwise read any file the daemon can read and hand it over).
+ *   - Plugin servers: only those named in `guestPlugins` (default: web
+ *     search and the time/weather/currency extras).
+ *
+ * Groups are untouched: they already require the operator's membership,
+ * and their tool surface is a separate decision.
+ *
+ * Backend built-ins that live outside the hub (the Claude SDK's own
+ * Bash/Read/Write, Codex's shell) are the backend's job. The Claude SDK
+ * backend drops its built-ins for guest chats (see claude-sdk/options.ts).
+ */
+
+export type GuestDmScopeConfig = {
+  enabled?: boolean;
+  /** Chat ids that keep the full surface in addition to the admin's DM. */
+  operatorChats?: readonly string[];
+  /** Plugin/hub server names a guest DM may use. */
+  guestPlugins?: readonly string[];
+};
+
+const DEFAULT_GUEST_PLUGINS: readonly string[] = [
+  "brave-search",
+  "extras-tools",
+];
+
+/** Talon tools a guest DM may see and call. Everything else is hidden. */
+export const GUEST_TOOL_ALLOWLIST: ReadonlySet<string> = new Set([
+  "end_turn",
+  "send",
+  "react",
+  "edit_message",
+  "delete_message",
+  "stop_poll",
+  "get_chat_info",
+  "read_chat_history",
+  "search_chat_history",
+  "get_message_by_id",
+  "download_media",
+  "list_media",
+  "get_sticker_pack",
+  "download_sticker",
+]);
+
+/** Parameters that name another chat. A guest may only name its own. */
+const CHAT_TARGET_PARAMS = ["chat_id", "to_chat_id", "from_chat_id"] as const;
+
+type ScopeState = {
+  enabled: boolean;
+  operators: Set<string>;
+  plugins: Set<string>;
+};
+
+let state: ScopeState = {
+  enabled: false,
+  operators: new Set(),
+  plugins: new Set(DEFAULT_GUEST_PLUGINS),
+};
+
+/** Set at bootstrap (and on config reload). */
+export function initGuestDmScope(
+  cfg: GuestDmScopeConfig | undefined,
+  adminUserId?: number,
+): void {
+  const operators = new Set<string>(cfg?.operatorChats ?? []);
+  if (adminUserId) operators.add(String(adminUserId));
+  state = {
+    enabled: cfg?.enabled === true,
+    operators,
+    plugins: new Set(cfg?.guestPlugins ?? DEFAULT_GUEST_PLUGINS),
+  };
+}
+
+/**
+ * Is this chat id a one-to-one DM? Telegram DMs are the peer's positive
+ * user id; WhatsApp DMs are `wa_dm_<number>`. Anything else (groups,
+ * Discord, native, heartbeat) is not treated as a DM here.
+ */
+export function isDmChatId(chatId: string): boolean {
+  return /^\d+$/.test(chatId) || chatId.startsWith("wa_dm_");
+}
+
+/** Should this chat get the guest surface? */
+export function isGuestChat(chatId: string): boolean {
+  if (!state.enabled) return false;
+  if (!isDmChatId(chatId)) return false;
+  return !state.operators.has(chatId);
+}
+
+export function isGuestToolAllowed(name: string): boolean {
+  return GUEST_TOOL_ALLOWLIST.has(name);
+}
+
+export function isGuestPluginAllowed(serverName: string): boolean {
+  return state.plugins.has(serverName);
+}
+
+/**
+ * Why a guest call with these params must be refused, or null if it is
+ * fine. Checked on every guest tool call, after the allowlist.
+ */
+export function guestParamViolation(
+  chatId: string,
+  params: Record<string, unknown>,
+): string | null {
+  for (const key of CHAT_TARGET_PARAMS) {
+    const v = params[key];
+    if (v !== undefined && v !== null && String(v) !== chatId) {
+      return `${key} must be this chat`;
+    }
+  }
+  if (params.file_path !== undefined) {
+    return "file_path is not available here; use a url or file_id";
+  }
+  const media = params.media;
+  if (Array.isArray(media)) {
+    for (const item of media) {
+      if (
+        item &&
+        typeof item === "object" &&
+        (item as Record<string, unknown>).file_path !== undefined
+      ) {
+        return "file_path is not available here; use a url or file_id";
+      }
+    }
+  }
+  return null;
+}

package/src/core/mcp-hub/index.ts

@@ -53,6 +53,12 @@ import {
   type ChildSpec,
 } from "./children.js";
 import type { ToolFrontend } from "../tools/types.js";
+import {
+  initGuestDmScope,
+  isGuestChat,
+  isGuestPluginAllowed,
+  type GuestDmScopeConfig,
+} from "./guest-scope.js";
 
 export const HUB_PATH_PREFIX = "/mcp/";
 
@@ -64,6 +70,10 @@ export type HubConfig = {
   braveApiKey?: string;
   /** Surface the native tool set (bash/read/write/… + teleport). */
   nativeTools?: boolean;
+  /** Conversation-only tool surface for non-operator DMs. */
+  guestDmScope?: GuestDmScopeConfig;
+  /** Operator's Telegram id — their DM always keeps the full surface. */
+  adminUserId?: number;
 };
 
 let hubConfig: HubConfig = {};
@@ -71,6 +81,7 @@ let hubConfig: HubConfig = {};
 /** Set at bootstrap; safe to call again on config reload. */
 export function initHub(config: HubConfig): void {
   hubConfig = config;
+  initGuestDmScope(config.guestDmScope, config.adminUserId);
   startChildReaper();
 }
 
@@ -215,6 +226,7 @@ function buildServerFor(target: HubTarget, bridgeUrl: string) {
       disabledTools: hubConfig.disabledTools,
       disabledToolTags: hubConfig.disabledToolTags,
       includeNativeTools: hubConfig.nativeTools,
+      guest: isGuestChat(target.chatId),
     });
   }
   return buildProxyServer(target.serverName, () =>
@@ -327,6 +339,15 @@ export async function handleHubRequest(
       return;
     }
 
+    if (
+      target.kind === "plugin" &&
+      isGuestChat(target.chatId) &&
+      !isGuestPluginAllowed(target.serverName)
+    ) {
+      jsonRpcError(res, 403, "Not available in this chat");
+      return;
+    }
+
     const server = buildServerFor(target, bridgeUrl);
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: () => randomUUID(),

package/src/core/mcp-hub/talon-server.ts

@@ -18,6 +18,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { composeTools } from "../tools/index.js";
 import { createBridge, textResult } from "../tools/bridge.js";
 import type { ToolFrontend, ToolTag } from "../tools/types.js";
+import { guestParamViolation, isGuestToolAllowed } from "./guest-scope.js";
 
 export const VALID_TOOL_FRONTENDS: ReadonlySet<string> = new Set([
   "telegram",
@@ -37,6 +38,11 @@ export type TalonServerOptions = {
   disabledToolTags?: readonly string[];
   /** Expose the native tool set (replaces the SDK built-ins). */
   includeNativeTools?: boolean;
+  /**
+   * Guest DM: expose only the conversation allowlist and refuse calls that
+   * name another chat or a local file. See guest-scope.ts.
+   */
+  guest?: boolean;
 };
 
 /** Build a Talon tool MCP server bound to one (frontend, chatId) pair. */
@@ -65,10 +71,21 @@ export function buildTalonToolServer(options: TalonServerOptions): McpServer {
     if (endTurn) tools.push(endTurn);
   }
 
-  for (const tool of tools) {
-    server.tool(tool.name, tool.description, tool.schema, async (params) =>
-      textResult(await tool.execute(params, bridge)),
-    );
+  const surface = options.guest
+    ? tools.filter((t) => isGuestToolAllowed(t.name))
+    : tools;
+
+  for (const tool of surface) {
+    server.tool(tool.name, tool.description, tool.schema, async (params) => {
+      if (options.guest) {
+        const why = guestParamViolation(
+          options.chatId,
+          params as Record<string, unknown>,
+        );
+        if (why) return textResult(`Not available in this chat: ${why}.`);
+      }
+      return textResult(await tool.execute(params, bridge));
+    });
   }
 
   return server;

package/src/core/mesh/links/bridge-links.ts

@@ -40,6 +40,11 @@ export type MeshBridgeInfo = {
   token?: string;
   /** TLS certificate SHA-256 (absent over plain HTTP). */
   fingerprint?: string;
+  /**
+   * The operator's `native.publicUrl`: what devices dial when the bind
+   * address isn't reachable as-is (containers, NAT, proxies).
+   */
+  publicUrl?: string;
 };
 
 export class BridgeLinks {
@@ -261,9 +266,10 @@ export class BridgeLinks {
   }
 
   /**
-   * The bridge base URL a NEW host should dial: an explicit override wins;
-   * otherwise derive from the bridge's bind. A wildcard bind maps to this
-   * host's first external IPv4; a loopback bind is unreachable from other
+   * The bridge base URL a NEW host should dial: an explicit override wins,
+   * then the configured `native.publicUrl`; otherwise derive from the
+   * bridge's bind. A wildcard bind maps to this host's first external IPv4;
+   * a loopback bind is unreachable from other
    * machines, so it's an error rather than a link that can't work.
    */
   private bridgeBaseUrl(
@@ -277,6 +283,10 @@ export class BridgeLinks {
       }
       return url;
     }
+    // Inside a container the "first external IPv4" is the container's own
+    // bridge-network address, which no phone can reach — the operator's
+    // public URL is the only right answer there.
+    if (info.publicUrl) return info.publicUrl.trim().replace(/\/+$/, "");
     let host = info.host;
     if (host === "0.0.0.0" || host === "::") {
       const external = firstExternalIPv4();

package/src/frontend/native/index.ts

@@ -185,6 +185,9 @@ export function createNativeFrontend(
         port: server.getPort(),
         ...(listen.token ? { token: listen.token } : {}),
         ...(fingerprint ? { fingerprint } : {}),
+        ...(config.native?.publicUrl
+          ? { publicUrl: config.native.publicUrl }
+          : {}),
       });
       await writeBridgeDiscovery({
         port: server.getPort(),

package/src/frontend/telegram/commands/memory.ts

@@ -7,9 +7,10 @@
  * (rollout PR 6), so the operator can always ask what Talon remembers
  * without the answer being able to change it.
  *
- * Gated exactly like `/status` — not at all. The store holds the
- * operator's own memory, and a read of it is the least privileged thing
- * a chat can do.
+ * Admin only, and only in a private chat. The store holds the operator's
+ * private notes — people, places, health, relationships — so a read of it
+ * is not a low-privilege action: in a group every member would see the
+ * reply, and anyone else who can reach the bot must not see it at all.
  *
  * Every line is model- or user-authored text reaching an HTML-parsed
  * send, so it goes through `escapeHtml` before it is joined; the reply
@@ -20,6 +21,7 @@
 import type { Bot, Context } from "grammy";
 import { escapeHtml } from "../formatting.js";
 import { replyHtmlChunked } from "../admin/chunked-reply.js";
+import { isAuthorizedAdmin } from "./state.js";
 import {
   formatMemory,
   getMemory,
@@ -36,11 +38,31 @@ const LIST_LIMIT = 15;
 
 export function registerMemoryCommand(bot: Bot): void {
   bot.command("memory", async (ctx: Context) => {
+    const verdict = memoryAccess(ctx);
+    if (verdict !== "ok") {
+      await ctx.reply(
+        verdict === "not-private"
+          ? "Memory is private — ask me in a DM."
+          : "Not authorized.",
+      );
+      return;
+    }
     const arg = (ctx.match ?? "").toString().trim();
     await replyHtmlChunked(ctx, renderMemory(arg));
   });
 }
 
+/**
+ * Who may read memory here: the admin, in a private chat.
+ * Order matters — a non-admin in a group gets "not authorized", not
+ * a hint that a DM would work.
+ */
+function memoryAccess(ctx: Context): "ok" | "not-admin" | "not-private" {
+  if (!isAuthorizedAdmin(ctx)) return "not-admin";
+  if (ctx.chat?.type !== "private") return "not-private";
+  return "ok";
+}
+
 /** Route the argument to one of the four reads. Returns ready HTML. */
 function renderMemory(arg: string): string {
   const why = /^why\b\s*(.*)$/is.exec(arg);