talon-agent 5.13.0 → 5.18.1

package/src/cli/commands/mesh.ts

@@ -0,0 +1,133 @@
+/**
+ * `talon mesh` — per-device credentials from the outside.
+ *
+ *   talon mesh [list]                    every credential + devices still on
+ *                                        the shared token
+ *   talon mesh revoke <device|credId>    revoke now; live sessions drop
+ *   talon mesh rotate <device>           the device swaps credentials on its
+ *                                        next heartbeat (old one: 7-day grace)
+ *   talon mesh scopes <device> <list>    e.g. device,client,operator
+ *
+ * Everything goes through the running daemon's loopback gateway
+ * (core/engine/gateway-routes.ts → core/mesh/credentials/admin.ts): the
+ * daemon owns the store and the live sessions a revocation must drop, so
+ * editing the file behind its back could never take effect in time.
+ */
+
+import pc from "picocolors";
+import { fetchGateway, requireGatewayPort } from "../daemon-api.js";
+import type { DeviceCredential } from "../../core/mesh/credentials/index.js";
+
+const USAGE = `
+  ${pc.bold("talon mesh")} — per-device mesh credentials
+
+    ${pc.cyan("list")}                              credentials, scopes, last use (default)
+    ${pc.cyan("revoke")} <device|credential-id>     revoke now; drops its live sessions
+    ${pc.cyan("rotate")} <device>                   re-issue on the device's next heartbeat
+    ${pc.cyan("scopes")} <device> <scope,scope>     set scopes: device, client, operator
+`;
+
+type Overview = {
+  ok: boolean;
+  error?: string;
+  credentials?: DeviceCredential[];
+  legacyDevices?: { deviceId: string; lastSeen: number }[];
+  legacySharedToken?: boolean;
+};
+
+type AdminReply = { ok: boolean; text?: string; error?: string };
+
+function ago(ts: number | undefined, now: number): string {
+  if (ts === undefined) return "never";
+  const s = Math.max(0, Math.round((now - ts) / 1000));
+  if (s < 90) return `${s}s ago`;
+  if (s < 5400) return `${Math.round(s / 60)}m ago`;
+  if (s < 172_800) return `${Math.round(s / 3600)}h ago`;
+  return `${Math.round(s / 86_400)}d ago`;
+}
+
+function stateOf(c: DeviceCredential, now: number): string {
+  if (c.revokedAt !== undefined) return pc.dim(`revoked (${c.revokeReason})`);
+  if (c.expiresAt !== undefined && now >= c.expiresAt) return pc.dim("expired");
+  if (c.supersededBy) return pc.yellow(`superseded by ${c.supersededBy}`);
+  if (c.rotateRequestedAt !== undefined) return pc.yellow("rotation pending");
+  if (c.deviceId === null) return pc.yellow("unbound (awaiting first use)");
+  return pc.green("active");
+}
+
+function renderOverview(o: Overview): void {
+  const now = Date.now();
+  const creds = o.credentials ?? [];
+  console.log(`\n  ${pc.bold("Mesh credentials")}\n`);
+  if (creds.length === 0) console.log(`  ${pc.dim("(none issued yet)")}`);
+  for (const c of creds) {
+    console.log(
+      `  ${pc.cyan(c.id)}  ${c.deviceId ?? pc.dim("—")}  [${c.scopes.join(", ")}]  ${stateOf(c, now)}`,
+    );
+    console.log(
+      pc.dim(
+        `      via ${c.origin}, issued ${ago(c.createdAt, now)}, last used ${ago(c.lastUsedAt, now)}`,
+      ),
+    );
+  }
+  const legacy = o.legacyDevices ?? [];
+  if (legacy.length > 0) {
+    console.log(`\n  ${pc.yellow("Still on the shared native.token:")}`);
+    for (const d of legacy) {
+      console.log(`  ${d.deviceId}  ${pc.dim(`seen ${ago(d.lastSeen, now)}`)}`);
+    }
+  }
+  console.log(
+    `\n  Legacy shared token from remote clients: ${
+      o.legacySharedToken ? pc.yellow("accepted") : pc.green("refused")
+    }\n`,
+  );
+}
+
+async function adminOp(
+  port: number,
+  body: Record<string, unknown>,
+): Promise<void> {
+  const reply = (await fetchGateway(port, "/mesh/credentials", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  })) as AdminReply;
+  if (reply.ok) {
+    console.log(`\n  ${pc.green("✔")} ${reply.text}\n`);
+  } else {
+    console.error(`\n  ${pc.red("✖")} ${reply.error}\n`);
+    process.exitCode = 1;
+  }
+}
+
+export async function runMeshCommand(args: string[]): Promise<void> {
+  const [sub = "list", target, scopes] = args;
+  if (sub === "help" || sub === "--help" || sub === "-h") {
+    console.log(USAGE);
+    return;
+  }
+  const known = ["list", "revoke", "rotate", "scopes"];
+  if (!known.includes(sub)) {
+    console.error(`  Unknown mesh command: ${sub}\n${USAGE}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (sub !== "list" && !target) {
+    console.error(
+      `  ${pc.red("✖")} talon mesh ${sub} needs a device.\n${USAGE}`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const port = await requireGatewayPort();
+  if (port === null) {
+    process.exitCode = 1;
+    return;
+  }
+  if (sub === "list") {
+    renderOverview((await fetchGateway(port, "/mesh/credentials")) as Overview);
+    return;
+  }
+  await adminOp(port, { op: sub, device: target, scopes });
+}

package/src/cli/config.ts

@@ -46,6 +46,8 @@ export type Config = {
   pulse: boolean;
   pulseIntervalMs: number;
   adminUserId?: number;
+  /** Telegram DM allowlist; defaults to `[adminUserId]` when set up. */
+  allowedUsers?: number[];
   apiId?: number;
   apiHash?: string;
   maxMessageLength: number;
@@ -222,7 +224,7 @@ export function isConfigured(config: Config): boolean {
     ? config.frontend
     : [config.frontend];
   return fes.every((fe) => {
-    if (fe === "telegram") return !!config.botToken;
+    if (fe === "telegram") return !!config.botToken && !!config.adminUserId;
     if (fe === "teams") return !!config.teamsWebhookUrl;
     if (fe === "discord") return !!config.discord?.botToken;
     // WhatsApp's credentials live in ~/.talon/whatsapp-auth/, not the

package/src/cli/daemon-api.ts

@@ -6,19 +6,41 @@
 
 import pc from "picocolors";
 import { findRunningInstance } from "../core/daemon/discovery.js";
+import {
+  gatewayAuthHeaders,
+  gatewayTokenPath,
+  readGatewayToken,
+} from "../core/engine/gateway-auth.js";
 
 const REQUEST_TIMEOUT_MS = 3_000;
 
+/**
+ * Call a gateway endpoint as the operator: every request carries the gateway
+ * token (read from ~/.talon/keys/gateway-token), and a POST always declares a
+ * JSON body — the gateway refuses anything else.
+ */
 export async function fetchGateway(
   port: number,
   path: string,
   init?: RequestInit,
   timeoutMs: number = REQUEST_TIMEOUT_MS,
 ): Promise<unknown> {
+  const isPost = init?.method === "POST";
   const response = await fetch(`http://127.0.0.1:${port}${path}`, {
     ...init,
+    ...(isPost && init?.body === undefined ? { body: "{}" } : {}),
+    headers: {
+      ...(isPost ? { "Content-Type": "application/json" } : {}),
+      ...(init?.headers as Record<string, string> | undefined),
+      ...gatewayAuthHeaders(readGatewayToken()),
+    },
     signal: AbortSignal.timeout(timeoutMs),
   });
+  if (response.status === 401) {
+    throw new Error(
+      `gateway refused the request (401) — is ${gatewayTokenPath()} readable by this user?`,
+    );
+  }
   if (!response.ok) throw new Error(`gateway answered ${response.status}`);
   return response.json();
 }

package/src/cli/index.ts

@@ -39,6 +39,7 @@ import { runSkillCommand } from "./skill.js";
 import { runMemoryCommand } from "./memory.js";
 import { mainMenu } from "./menu.js";
 import { runBackupCommand } from "./commands/backup.js";
+import { runMeshCommand } from "./commands/mesh.js";
 
 export * from "./context.js";
 export * from "./config.js";
@@ -62,6 +63,7 @@ const CLI_COMMANDS = [
   "skill",
   "memory",
   "backup",
+  "mesh",
 ];
 
 /** `talon events [-f] [--history [N]]` → the tail options. */
@@ -110,6 +112,9 @@ function printHelp(): void {
   console.log(
     `    ${pc.cyan("backup")}     Snapshots and checkpoints (now/list/show/pin/restore)`,
   );
+  console.log(
+    `    ${pc.cyan("mesh")}       Device credentials (list/revoke/rotate/scopes)`,
+  );
   console.log(`    ${pc.cyan("config")}     View/edit configuration`);
   console.log(`    ${pc.cyan("logs")}       Tail log file`);
   console.log(`    ${pc.cyan("doctor")}     Validate environment`);
@@ -173,6 +178,7 @@ const COMMANDS: Record<string, CommandHandler> = {
   kill: (args) => killTask(args[0]),
   events: (args) => showEvents(eventsOptions(args)),
   backup: (args) => runBackupCommand(args),
+  mesh: (args) => runMeshCommand(args),
   plugin: (args) => runPluginCommand(args),
   skill: (args) => runSkillCommand(args),
   memory: (args) => runMemoryCommand(args),

package/src/cli/install-sources.ts

@@ -10,13 +10,15 @@
  *   4. anything else                         → { kind: "other" } — the caller
  *      decides (plugins treat it as an npm spec, skills reject it)
  *
- * Cloning always uses `--depth=1` (installs never need history) and spawns
+ * Cloning always uses `--depth=1` (installs never need history), ends the
+ * options with `--` so a URL can never be read as a git flag, and reports
+ * the commit it got so the install can be pinned/audited later. It spawns
  * `git`/`npm` via cross-spawn, which resolves the `.cmd`/`.exe` shims on
  * Windows — never assume a POSIX shell here.
  */
 
 import crossSpawn from "cross-spawn";
-import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 
@@ -91,16 +93,49 @@ export function runTool(
 }
 
 export type CloneOutcome =
-  { ok: true; dir: string; cleanup: () => void } | { ok: false; error: string };
+  | { ok: true; dir: string; commit?: string; cleanup: () => void }
+  | { ok: false; error: string };
+
+/** The checked-out commit of a clone, when git can tell us. */
+function headCommit(dir: string): string | undefined {
+  const result = crossSpawn.sync("git", ["-C", dir, "rev-parse", "HEAD"], {
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  const sha = result.status === 0 ? result.stdout?.toString().trim() : "";
+  return sha && /^[0-9a-f]{40,64}$/.test(sha) ? sha : undefined;
+}
 
 /** Shallow-clone into a fresh temp directory. Caller must run `cleanup`. */
 export function cloneShallow(url: string): CloneOutcome {
+  // `--` below already stops option parsing; refusing a leading dash too
+  // means a hostile "URL" never even reaches git.
+  if (url.startsWith("-")) {
+    return { ok: false, error: `Refusing a git URL that starts with "-"` };
+  }
   const dir = mkdtempSync(join(tmpdir(), "talon-install-"));
   const cleanup = () => rmSync(dir, { recursive: true, force: true });
-  const outcome = runTool("git", ["clone", "--depth=1", url, dir]);
+  const outcome = runTool("git", ["clone", "--depth=1", "--", url, dir]);
   if (!outcome.ok) {
     cleanup();
     return { ok: false, error: `Clone failed: ${outcome.error}` };
   }
-  return { ok: true, dir, cleanup };
+  return { ok: true, dir, commit: headCommit(dir), cleanup };
+}
+
+/** The file a git-installed plugin keeps its provenance in. */
+const INSTALL_RECORD = ".talon-install.json";
+
+/** Write where an install came from and exactly which commit it is. */
+export function writeInstallRecord(
+  dir: string,
+  record: { source: string; subpath?: string; commit?: string },
+): void {
+  writeFileSync(
+    join(dir, INSTALL_RECORD),
+    JSON.stringify(
+      { ...record, installedAt: new Date().toISOString() },
+      null,
+      2,
+    ) + "\n",
+  );
 }

package/src/cli/plugin.ts

@@ -25,6 +25,7 @@ import { fetchGateway } from "./daemon-api.js";
 import { loadConfig, saveConfig, type Config } from "./config.js";
 import {
   cloneShallow,
+  writeInstallRecord,
   resolveSource,
   runTool,
   type ResolvedSource,
@@ -258,7 +259,16 @@ function installFromGit(
     }
     // An install is a snapshot, not a checkout — updates go through
     // `install --force`, so the clone's history has no business here.
+    // What it WAS a snapshot of is kept, so the exact commit is auditable.
     rmSync(join(stage, ".git"), { recursive: true, force: true });
+    writeInstallRecord(stage, {
+      source: source.url,
+      ...(source.subpath ? { subpath: source.subpath } : {}),
+      ...(clone.commit ? { commit: clone.commit } : {}),
+    });
+    if (clone.commit) {
+      console.log(`  ${pc.dim(`Commit ${clone.commit}`)}`);
+    }
 
     if (existsSync(join(stage, "package.json"))) {
       console.log(`  ${pc.dim("Installing dependencies…")}`);

package/src/cli/setup.ts

@@ -94,6 +94,20 @@ type TelegramAnswers = Pick<
   "botToken" | "adminId" | "apiId" | "apiHash"
 >;
 
+/**
+ * The Telegram admin id is required: it is the bot's owner (admin commands)
+ * and the default DM allowlist. The daemon refuses to start without it.
+ */
+export function validateTelegramAdminId(
+  value: string | undefined,
+): string | undefined {
+  const v = value?.trim() ?? "";
+  if (!v) return "Required — the bot answers only its admin (and allowedUsers)";
+  if (!/^\d+$/.test(v) || Number(v) <= 0 || !Number.isSafeInteger(Number(v)))
+    return "Must be your numeric Telegram user ID";
+  return undefined;
+}
+
 async function askTelegram(config: Config): Promise<TelegramAnswers> {
   const botToken = await askOrExit(
     p.text({
@@ -110,8 +124,9 @@ async function askTelegram(config: Config): Promise<TelegramAnswers> {
   const adminId = await askOrExit(
     p.text({
       message: "Your Telegram user ID",
-      placeholder: "optional — message @userinfobot to find yours",
+      placeholder: "message @userinfobot to find yours",
       initialValue: config.adminUserId ? String(config.adminUserId) : "",
+      validate: validateTelegramAdminId,
     }),
   );
 
@@ -619,6 +634,34 @@ export type SetupAnswers = {
   whatsapp?: Config["whatsapp"];
 };
 
+/**
+ * Admin + DM allowlist for the saved config. With Telegram on, the admin id
+ * is the one just entered, and an empty allowlist defaults to that admin —
+ * a fresh bot answers its owner and no one else. With Telegram off, both are
+ * left as they were (other surfaces read `adminUserId` too).
+ */
+function telegramAccess(
+  existing: Config,
+  answers: SetupAnswers,
+  telegramOn: boolean,
+): Pick<Config, "adminUserId" | "allowedUsers"> {
+  const adminUserId = answers.adminId
+    ? parseInt(answers.adminId, 10) || undefined
+    : undefined;
+  if (!telegramOn || adminUserId === undefined) {
+    return {
+      adminUserId: adminUserId ?? existing.adminUserId,
+      allowedUsers: existing.allowedUsers,
+    };
+  }
+  return {
+    adminUserId,
+    allowedUsers: existing.allowedUsers?.length
+      ? existing.allowedUsers
+      : [adminUserId],
+  };
+}
+
 /**
  * Fold the wizard's answers onto the existing config.
  *
@@ -674,9 +717,7 @@ export function buildSetupConfig(
     concurrency: existing.concurrency,
     pulse: answers.pulse,
     pulseIntervalMs: existing.pulseIntervalMs,
-    adminUserId: answers.adminId
-      ? parseInt(answers.adminId, 10) || undefined
-      : undefined,
+    ...telegramAccess(existing, answers, on("telegram")),
     apiId: answers.apiId,
     apiHash: answers.apiHash,
     maxMessageLength: existing.maxMessageLength,

package/src/cli/skill.ts

@@ -171,6 +171,9 @@ async function cmdInstall(args: string[]): Promise<void> {
         return;
       }
       installed = installAll(dirs, force);
+      if (clone.commit) {
+        console.log(`  ${pc.dim(`From ${resolved.url} @ ${clone.commit}`)}`);
+      }
     } finally {
       clone.cleanup();
     }

package/src/core/agent-runtime/backend-registry.ts

@@ -76,6 +76,14 @@ export interface BackendFactory {
   id: string;
   /** Display label used in `/status` and agent logs (e.g. "Kilo"). */
   label: string;
+  /**
+   * Can this backend run a guest-scoped turn (a non-operator sender) with
+   * nothing but the hub's conversation-only tools? `"enforced"` means its
+   * own built-ins (shell, file tools) are dropped for guest turns;
+   * `"refused"` means they can't be, so the weaver refuses guest turns on
+   * it. Absent is treated as `"refused"` — fail closed.
+   */
+  guestToolScope?: "enforced" | "refused";
   /** Initialise the backend; called exactly once per Talon process. */
   init(config: TalonConfig, ctx: BackendInitContext): Promise<BackendInstance>;
   /**
@@ -136,6 +144,14 @@ export function clearBackends(): void {
   backends.clear();
 }
 
+/**
+ * Whether guest-scoped turns may run on this backend. Unknown ids and
+ * factories that don't declare `guestToolScope` fail closed.
+ */
+export function backendEnforcesGuestScope(id: string): boolean {
+  return backends.get(id)?.guestToolScope === "enforced";
+}
+
 /** Whether a backend with this id is currently registered. */
 export function hasBackend(id: string): boolean {
   return backends.has(id);