talon-agent 5.25.1 → 5.26.0

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

@@ -0,0 +1,113 @@
+/**
+ * The native bridge's slash commands — the single list `/help` prints,
+ * `GET /commands` serves for client autocomplete, and the parser matches
+ * against. A name not in this list is never intercepted: `/etc/hosts`,
+ * `/shrug` or a typo reaches the model as ordinary text.
+ *
+ * `admin` marks what needs the `operator` scope — the same scope the
+ * bridge demands for `POST /control` and `POST /config` — so a
+ * client-only credential cannot restart the daemon or restore a snapshot
+ * by typing what it could not POST.
+ */
+
+import type { ClientCommand } from "../protocol.js";
+
+export const NATIVE_COMMANDS = [
+  {
+    name: "help",
+    description: "All commands",
+  },
+  {
+    name: "status",
+    description: "Session info, context usage and stats",
+  },
+  {
+    name: "settings",
+    description: "This chat's model, backend, effort and pulse",
+  },
+  {
+    name: "model",
+    description: "List models; pick one or switch backend",
+    args: "[<n>|<id>|<backend>|default|backend default]",
+  },
+  {
+    name: "effort",
+    description: "Show or set thinking effort",
+    args: "[off|low|medium|high|max|adaptive]",
+  },
+  {
+    name: "pulse",
+    description: "Periodic check-ins: on, off, or an interval",
+    args: "[on|off|<interval>]",
+  },
+  {
+    name: "stop",
+    description: "Stop the current response",
+  },
+  {
+    name: "reset",
+    description: "Clear the session and start fresh",
+  },
+  {
+    name: "ping",
+    description: "Health check",
+  },
+  {
+    name: "usage",
+    description: "Plan limits across every backend",
+  },
+  {
+    name: "mesh",
+    description: "Ping and list mesh devices",
+  },
+  {
+    name: "plugins",
+    description: "List loaded plugins",
+  },
+  {
+    name: "memory",
+    description: "What Talon remembers — list, search, why <id>",
+    args: "[<query>|why <id>|kind <kind>]",
+  },
+  {
+    name: "metrics",
+    description: "Aggregate performance metrics",
+    args: "[all]",
+    admin: true,
+  },
+  {
+    name: "doctor",
+    description: "Environment and native-module health",
+    admin: true,
+  },
+  {
+    name: "dream",
+    description: "Force memory consolidation",
+    admin: true,
+  },
+  {
+    name: "restart",
+    description: "Restart the daemon",
+    admin: true,
+  },
+  {
+    name: "backup",
+    description: "Snapshots and checkpoints; restore <id>",
+    args: "[status|now|checkpoint <label>|list|show <id>|pin <id>|unpin <id>|restore <id>]",
+    admin: true,
+  },
+] as const satisfies readonly ClientCommand[];
+
+export type NativeCommandName = (typeof NATIVE_COMMANDS)[number]["name"];
+
+/** The command list as the wire carries it (a fresh copy per call). */
+export function listNativeCommands(): ClientCommand[] {
+  return NATIVE_COMMANDS.map((c) => ({ ...c }));
+}
+
+/** The definition for a name, when it is one of ours. */
+export function findNativeCommand(name: string): ClientCommand | undefined {
+  return (NATIVE_COMMANDS as readonly ClientCommand[]).find(
+    (c) => c.name === name,
+  );
+}

package/src/frontend/native/commands/format.ts

@@ -0,0 +1,24 @@
+/**
+ * The native bridge's report dialect: Markdown, which every client
+ * renders, with no escaping (nothing is parsed server-side) and no
+ * per-message cap — a bridge message is a JSON string, not a platform
+ * bubble, so a report is one reply however long it grows.
+ */
+
+import type { ReportFormatter } from "../../presentation/reports.js";
+
+export const NATIVE_REPORTS: ReportFormatter = {
+  bold: (s) => `**${s}**`,
+  italic: (s) => `_${s}_`,
+  emphasis: (s) => `*${s}*`,
+  code: (s) => `\`${s}\``,
+  escape: (s) => s,
+  lineLimit: 100_000,
+  metricLabelMax: 80,
+  pulseLabel: "🔔 Pulse:",
+};
+
+/** Wrap preformatted text (status tables, listings) in a code fence. */
+export function fence(text: string): string {
+  return `\`\`\`\n${text.replace(/```/g, "ˋˋˋ")}\n\`\`\``;
+}

package/src/frontend/native/commands/index.ts

@@ -0,0 +1,106 @@
+/**
+ * Slash commands on the native bridge.
+ *
+ * `/send` hands every message here first. Text that names one of the
+ * commands in definitions.ts is answered by the daemon — the command and
+ * its reply land in the chat as ordinary messages, persisted like
+ * WhatsApp's so a reload keeps them — and never reaches the model. Any
+ * other text, including `/something` that is not ours, returns false and
+ * runs a turn exactly as before.
+ *
+ * Commands run even while a turn is in flight (that is what `/stop` is
+ * for) and are never queued behind one.
+ */
+
+import { logError } from "../../../util/log.js";
+import type { ChatEntry } from "../chats/chats.js";
+import type { NativeRuntime } from "../runtime.js";
+import { emitNotice, emitUser } from "../turn/emit.js";
+import { adminCommands } from "./admin.js";
+import { backupCommand } from "./backup.js";
+import { findNativeCommand, type NativeCommandName } from "./definitions.js";
+import { infoCommands } from "./info.js";
+import { sessionCommands } from "./session.js";
+import type { NativeCommandContext, NativeCommandHandler } from "./types.js";
+
+export { listNativeCommands } from "./definitions.js";
+
+const HANDLERS: Record<NativeCommandName, NativeCommandHandler> = {
+  ...infoCommands,
+  ...sessionCommands,
+  ...adminCommands,
+  backup: backupCommand,
+};
+
+export type ParsedNativeCommand = { name: NativeCommandName; arg: string };
+
+/**
+ * Parse a slash command out of message text. Null for anything that is
+ * not one of ours — a path (`/etc/hosts`), a fraction, an unknown `/foo`.
+ */
+export function parseNativeCommand(text: string): ParsedNativeCommand | null {
+  const match = /^\/([a-zA-Z]+)(?:\s+([\s\S]*))?$/.exec(text.trim());
+  if (!match) return null;
+  const def = findNativeCommand(match[1]!.toLowerCase());
+  if (!def) return null;
+  return {
+    name: def.name as NativeCommandName,
+    arg: (match[2] ?? "").trim(),
+  };
+}
+
+/** Who sent the command, as far as authorisation is concerned. */
+export type NativeCommandCaller = {
+  /** The bridge credential holds the `operator` scope. */
+  operator: boolean;
+};
+
+async function runCommand(
+  runtime: NativeRuntime,
+  entry: ChatEntry,
+  cmd: ParsedNativeCommand,
+  caller: NativeCommandCaller,
+): Promise<void> {
+  const ctx: NativeCommandContext = {
+    runtime,
+    entry,
+    arg: cmd.arg,
+    operator: caller.operator,
+    deps: { config: runtime.config, gateway: runtime.gateway },
+    reply: (text) => {
+      emitNotice(runtime, entry, text);
+    },
+  };
+  if (findNativeCommand(cmd.name)?.admin && !caller.operator) {
+    ctx.reply(
+      `Not authorized — \`/${cmd.name}\` needs an operator credential, and this device's credential does not have that scope.`,
+    );
+    return;
+  }
+  try {
+    await HANDLERS[cmd.name](ctx);
+  } catch (err) {
+    logError("native", `/${cmd.name} failed`, err);
+    ctx.reply(
+      `⚠️ /${cmd.name} failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+/**
+ * Handle `text` as a slash command if it is one. True when it was — the
+ * caller then skips the agent turn. The command runs in the background:
+ * `/send` is fire-and-forget, and replies stream back as `message` events.
+ */
+export function handleNativeCommand(
+  runtime: NativeRuntime,
+  entry: ChatEntry,
+  text: string,
+  caller: NativeCommandCaller,
+): boolean {
+  const cmd = parseNativeCommand(text);
+  if (!cmd) return false;
+  emitUser(runtime, entry, text.trim(), [], { autoTitle: false });
+  void runCommand(runtime, entry, cmd, caller);
+  return true;
+}

package/src/frontend/native/commands/info.ts

@@ -0,0 +1,97 @@
+/**
+ * Read-only commands — `/help`, `/ping`, `/usage`, `/mesh`, `/plugins`,
+ * `/memory`. Each report is the one Telegram and Discord print, in the
+ * native Markdown dialect (presentation/reports.ts, memory-report.ts).
+ *
+ * `/memory` is not operator-gated here, unlike Telegram's admin-only
+ * `/memory`: the bridge already serves the same rows on `GET /memory` to
+ * any `client` credential, and a native chat is always a private one.
+ */
+
+import { getLoadedPlugins } from "../../../core/plugin/index.js";
+import { collectPlanUsage } from "../../presentation/plan-usage-report.js";
+import { renderMemoryReport } from "../../presentation/memory-report.js";
+import {
+  renderMeshReport,
+  renderUsageMessage,
+} from "../../presentation/reports.js";
+import { formatDuration } from "../../presentation/format.js";
+import { NATIVE_COMMANDS } from "./definitions.js";
+import { NATIVE_REPORTS } from "./format.js";
+import type { NativeCommandContext, NativeCommandHandler } from "./types.js";
+
+/** `/help` — generated from the definitions, so it can never drift. */
+function renderNativeHelp(operator: boolean): string {
+  const lines = ["**Commands**"];
+  for (const cmd of NATIVE_COMMANDS) {
+    const args = "args" in cmd ? ` ${cmd.args}` : "";
+    const admin =
+      "admin" in cmd
+        ? operator
+          ? " (admin)"
+          : " (admin — not available to this device)"
+        : "";
+    lines.push(`\`/${cmd.name}${args}\` — ${cmd.description}${admin}`);
+  }
+  lines.push(
+    "",
+    "Anything else starting with a slash goes to the model as a normal message.",
+  );
+  return lines.join("\n");
+}
+
+async function help(ctx: NativeCommandContext): Promise<void> {
+  ctx.reply(renderNativeHelp(ctx.operator));
+}
+
+async function ping(ctx: NativeCommandContext): Promise<void> {
+  const uptime = formatDuration(process.uptime() * 1000);
+  ctx.reply(
+    `Pong! Bridge ✓ · ${ctx.runtime.chats.count()} chat(s) · uptime ${uptime}`,
+  );
+}
+
+async function usage(ctx: NativeCommandContext): Promise<void> {
+  const entries = await collectPlanUsage(ctx.runtime.config);
+  ctx.reply(renderUsageMessage(entries, NATIVE_REPORTS));
+}
+
+async function mesh(ctx: NativeCommandContext): Promise<void> {
+  try {
+    const results = await ctx.runtime.mesh.pingAll();
+    ctx.reply(renderMeshReport(results, NATIVE_REPORTS));
+  } catch {
+    ctx.reply("Could not reach the mesh service.");
+  }
+}
+
+async function plugins(ctx: NativeCommandContext): Promise<void> {
+  const loaded = getLoadedPlugins();
+  if (loaded.length === 0) {
+    ctx.reply("No plugins loaded.");
+    return;
+  }
+  const lines = loaded.map((p) => {
+    const ver = p.plugin.version ? ` v${p.plugin.version}` : "";
+    const desc = p.plugin.description ? ` — ${p.plugin.description}` : "";
+    const mcp = p.plugin.mcpServerPath ? " [MCP]" : "";
+    const fe = p.plugin.frontends?.length
+      ? ` (${p.plugin.frontends.join(", ")})`
+      : "";
+    return `• **${p.plugin.name}**${ver}${mcp}${fe}${desc}`;
+  });
+  ctx.reply(`**Plugins (${loaded.length})**\n\n${lines.join("\n")}`);
+}
+
+async function memory(ctx: NativeCommandContext): Promise<void> {
+  ctx.reply(renderMemoryReport(ctx.arg, NATIVE_REPORTS));
+}
+
+export const infoCommands = {
+  help,
+  ping,
+  usage,
+  mesh,
+  plugins,
+  memory,
+} satisfies Record<string, NativeCommandHandler>;

package/src/frontend/native/commands/session.ts

@@ -0,0 +1,130 @@
+/**
+ * Per-chat commands — `/model`, `/effort`, `/settings`, `/status`,
+ * `/pulse`, `/stop`, `/reset`.
+ *
+ * The listings and pickers are the ones WhatsApp prints
+ * (presentation/text-commands.ts). What is native here is the state the
+ * bridge keeps beside the shared stores: a backend switch goes through
+ * the bridge's own `setBackend` (it also drops turn meta, the cached
+ * context readout and the queued follow-up), `/reset` through the same
+ * `resetChat` as `POST /chats/reset`, and every change ends with a
+ * `chat_updated` so every connected client's header follows.
+ */
+
+import {
+  disablePulse,
+  enablePulse,
+} from "../../../core/background/pulse/pulse.js";
+import {
+  getChatSettings,
+  setChatPulseInterval,
+} from "../../../storage/chat-settings.js";
+import { resetChatBackend } from "../../presentation/model-commands.js";
+import { formatDuration, parseInterval } from "../../presentation/format.js";
+import {
+  effortCommandReply,
+  modelCommandReply,
+  settingsCommandReply,
+  statusCommandReply,
+} from "../../presentation/text-commands.js";
+import { broadcastChatUpdated } from "../chats/chat-wire.js";
+import { resetChat, wipeChatConversation } from "../chats/reset.js";
+import { setBackend } from "../surface/models.js";
+import { broadcastStatus } from "../surface/status.js";
+import { interruptTurn } from "../turn/turn.js";
+import type { NativeCommandContext, NativeCommandHandler } from "./types.js";
+
+/** Pulse intervals below this would have the chat check in constantly. */
+const MIN_PULSE_INTERVAL_MS = 5 * 60 * 1000;
+
+async function model(ctx: NativeCommandContext): Promise<void> {
+  const { runtime, entry, deps } = ctx;
+  const text = await modelCommandReply(entry.id, ctx.arg, deps, {
+    switchBackend: async (target) => {
+      const result = await setBackend(runtime, entry.id, target.id);
+      return result.ok
+        ? `Backend: ${target.label} (\`${target.id}\`).`
+        : `Could not switch to ${target.label}: ${result.error ?? "rebind failed"}`;
+    },
+    resetBackend: async () => {
+      const outcome = await resetChatBackend(entry.id, deps);
+      wipeChatConversation(runtime, entry.id);
+      broadcastStatus(runtime);
+      return outcome.text;
+    },
+  });
+  if (ctx.arg) broadcastChatUpdated(runtime, entry);
+  ctx.reply(text);
+}
+
+async function effort(ctx: NativeCommandContext): Promise<void> {
+  const text = await effortCommandReply(ctx.entry.id, ctx.arg, ctx.deps);
+  if (ctx.arg) broadcastChatUpdated(ctx.runtime, ctx.entry);
+  ctx.reply(text);
+}
+
+async function settings(ctx: NativeCommandContext): Promise<void> {
+  ctx.reply(await settingsCommandReply(ctx.entry.id, ctx.deps));
+}
+
+async function status(ctx: NativeCommandContext): Promise<void> {
+  ctx.reply(await statusCommandReply(ctx.entry.id, ctx.deps));
+}
+
+/** The reply for a pulse argument, applying the change it names. */
+function applyPulse(chatId: string, arg: string): string {
+  const lower = arg.toLowerCase();
+  if (!lower || lower === "status") {
+    const sets = getChatSettings(chatId);
+    return (
+      `**🔔 Pulse:** ${sets.pulse === true ? "on" : "off"}` +
+      (sets.pulseIntervalMs
+        ? ` (every ${formatDuration(sets.pulseIntervalMs)})`
+        : "") +
+      "\n\nReads along every few minutes and jumps in when there's something to add. " +
+      "`/pulse on`, `/pulse off`, `/pulse 30m`."
+    );
+  }
+  if (lower === "on" || lower === "enable") {
+    enablePulse(chatId);
+    return "🔔 Pulse enabled.";
+  }
+  if (lower === "off" || lower === "disable") {
+    disablePulse(chatId);
+    return "🔔 Pulse disabled.";
+  }
+  const intervalMs = parseInterval(lower);
+  if (!intervalMs)
+    return "Use: `/pulse on`, `/pulse off`, `/pulse 30m`, `/pulse 2h`";
+  if (intervalMs < MIN_PULSE_INTERVAL_MS)
+    return "Minimum interval is 5 minutes.";
+  setChatPulseInterval(chatId, intervalMs);
+  enablePulse(chatId);
+  return `🔔 Pulse cooldown set to **${formatDuration(intervalMs)}**`;
+}
+
+async function pulse(ctx: NativeCommandContext): Promise<void> {
+  const text = applyPulse(ctx.entry.id, ctx.arg);
+  if (ctx.arg) broadcastChatUpdated(ctx.runtime, ctx.entry);
+  ctx.reply(text);
+}
+
+async function stop(ctx: NativeCommandContext): Promise<void> {
+  const stopped = await interruptTurn(ctx.runtime, ctx.entry.id);
+  ctx.reply(stopped ? "⏹ Stopped." : "Nothing is running.");
+}
+
+/** `resetChat` posts its own notice — a second "cleared" would be noise. */
+async function reset(ctx: NativeCommandContext): Promise<void> {
+  resetChat(ctx.runtime, ctx.entry.id);
+}
+
+export const sessionCommands = {
+  model,
+  effort,
+  settings,
+  status,
+  pulse,
+  stop,
+  reset,
+} satisfies Record<string, NativeCommandHandler>;

package/src/frontend/native/commands/types.ts

@@ -0,0 +1,26 @@
+/**
+ * What a native slash-command handler receives. Handlers answer through
+ * `reply` rather than a return value, so a command that has more to say
+ * later (a snapshot finishing, a restart about to happen) says it in
+ * order, and one with nothing to add (`/reset` — the reset emits its own
+ * notice) simply says nothing.
+ */
+
+import type { ModelCommandDeps } from "../../presentation/model-commands.js";
+import type { ChatEntry } from "../chats/chats.js";
+import type { NativeRuntime } from "../runtime.js";
+
+export type NativeCommandContext = {
+  runtime: NativeRuntime;
+  entry: ChatEntry;
+  /** Everything after the command name, trimmed. */
+  arg: string;
+  /** The caller holds the bridge's `operator` scope. */
+  operator: boolean;
+  /** The shared model-command dependencies for this runtime. */
+  deps: ModelCommandDeps;
+  /** Post a Markdown reply into the chat. */
+  reply(text: string): void;
+};
+
+export type NativeCommandHandler = (ctx: NativeCommandContext) => Promise<void>;

package/src/frontend/native/protocol.ts

@@ -216,6 +216,24 @@ export type LogEntry = {
   stack?: string;
 };
 
+/**
+ * One slash command the daemon answers itself in a native chat, as
+ * `GET /commands` lists it — so a client can offer autocomplete. Additive
+ * in v1 behind the `commands` capability. A `/send` whose text starts with
+ * a listed name is handled by the daemon (the command and its reply land
+ * in the chat as ordinary messages); any other text reaches the model.
+ */
+export type ClientCommand = {
+  /** Without the leading slash, e.g. `"backup"`. */
+  name: string;
+  /** One line, for the suggestion list. */
+  description: string;
+  /** Argument synopsis, e.g. `"[list|now|restore <id>]"`; absent = none. */
+  args?: string;
+  /** Needs the `operator` scope; other callers get a refusal. */
+  admin?: boolean;
+};
+
 /** A selectable model for the picker. */
 export type ModelOption = {
   id: string;

package/src/frontend/native/surface/handlers.ts

@@ -10,6 +10,7 @@ import { getPooledBackend } from "../../../core/engine/backend-controller/index.
 import { createChat, deleteChat, renameChat } from "../chats/chat-lifecycle.js";
 import { broadcastChatUpdated, toClientChat } from "../chats/chat-wire.js";
 import { control } from "./control.js";
+import { handleNativeCommand, listNativeCommands } from "../commands/index.js";
 import {
   pluginItems,
   skillItems,
@@ -108,11 +109,22 @@ export function buildBridgeHandlers(
     // straight delegations to the read-only half of the store.
     listMemory,
     memoryWhy,
-    send: (id, text, opts) => {
+    send: (id, text, opts, caller) => {
       const entry = chats.get(id) ?? chats.ensure(id);
       // Resolve the client's references into the records this daemon minted
       // at upload time — dropping anything it can't account for.
       const attachments = resolveAttachments(runtime, opts);
+      // A slash command the daemon answers itself never reaches the model,
+      // and never waits behind a running turn (`/stop` is for exactly
+      // that). A message with files attached is always the model's.
+      if (
+        !attachments.length &&
+        handleNativeCommand(runtime, entry, text, {
+          operator: caller?.operator === true,
+        })
+      ) {
+        return;
+      }
       // A turn is already running for this chat — don't interrupt it. Park the
       // message as the single queued follow-up (synced to every client); it
       // auto-sends when the running turn ends. `isBusy` reads `liveTurns`,
@@ -188,6 +200,7 @@ export function buildBridgeHandlers(
     setSkillEnabled: (name, enabled) =>
       toggleSkill(config, getPooledBackend(config.backend), name, enabled),
     control,
+    listCommands: () => listNativeCommands(),
     logs: ({ lines, minLevel, component }) =>
       readLogEntries(files.log, { limit: lines, minLevel, component }),
     liveTurnEvents: () => liveTurnEvents(runtime),

package/src/frontend/native/surface/status.ts

@@ -14,7 +14,15 @@ export function bridgeStatus(runtime: NativeRuntime): BridgeStatus {
     protocol: BRIDGE_PROTOCOL_VERSION,
     // "attachments": /upload streams any file type and /send takes an
     // `attachments` list, so a client can stage several files per message.
-    capabilities: ["mesh", "mesh-commands", "plugins-skills", "attachments"],
+    // "commands": `/send` answers slash commands itself and `GET /commands`
+    // lists them for autocomplete.
+    capabilities: [
+      "mesh",
+      "mesh-commands",
+      "plugins-skills",
+      "attachments",
+      "commands",
+    ],
     botName: runtime.botName,
     backend: config.backend,
     model: resolveModel(config.model)?.displayName ?? config.model,

package/src/frontend/native/turn/emit.ts

@@ -67,6 +67,36 @@ export function emitAssistant(
   return id;
 }
 
+/**
+ * Persist + broadcast an assistant message that is not a turn's reply —
+ * a slash command's answer. Unlike `emitAssistant` it leaves
+ * `lastAssistantId` alone: a turn still running beside the command must
+ * attach its tool timeline to its own reply, not to this one.
+ */
+export function emitNotice(
+  runtime: NativeRuntime,
+  entry: ChatEntry,
+  text: string,
+): number {
+  const id = runtime.nextId();
+  const ts = Date.now();
+  pushMessage(entry.id, {
+    msgId: id,
+    senderId: BOT_SENDER_ID,
+    senderName: runtime.botName,
+    text,
+    timestamp: ts,
+  });
+  runtime.chats.touch(entry.id, text);
+  runtime.broadcast({
+    kind: "message",
+    chatId: entry.id,
+    message: { id: String(id), chatId: entry.id, role: "assistant", text, ts },
+  });
+  broadcastChatUpdated(runtime, entry);
+  return id;
+}
+
 /** Persist + broadcast an assistant photo message (image + optional caption). */
 export function emitPhoto(
   runtime: NativeRuntime,
@@ -122,6 +152,7 @@ export function emitUser(
   entry: ChatEntry,
   text: string,
   attachments: ClientAttachment[] = [],
+  opts: { autoTitle?: boolean } = {},
 ): number {
   const id = runtime.nextId();
   const ts = Date.now();
@@ -160,7 +191,7 @@ export function emitUser(
     entry.id,
     attachments.length ? text || attachmentPreview(attachments) : text,
   );
-  maybeAutoTitle(runtime, entry, text);
+  if (opts.autoTitle !== false) maybeAutoTitle(runtime, entry, text);
   runtime.broadcast({ kind: "message", chatId: entry.id, message });
   broadcastChatUpdated(runtime, entry);
   return id;