talon-agent 1.48.0 → 1.49.0

package/README.md

@@ -23,6 +23,7 @@ Multi-platform agentic AI harness. Runs on **Telegram**, **Discord**, **Microsof
 | **Skills**            | Agent-authored reusable scripts (bash/python/node) — procedures worked out once get saved and replayed locally at zero token cost            |
 | **Triggers**          | Self-authored watcher scripts (bash/python/node) that wake the bot when conditions are met                                                   |
 | **Task table**        | Every unit of agent work — chat turns, heartbeat, dream, isolated cron/trigger jobs — registered live; `talon ps` / `talon kill`             |
+| **Event bus**         | Typed internal pub-sub spine (task + turn lifecycle events); subsystems subscribe instead of importing each other; `talon events -f`         |
 | **Per-chat settings** | Model, effort level, and pulse toggle per conversation via inline keyboard                                                                   |
 | **Model registry**    | Models discovered from the active backend at startup — new models appear in all pickers automatically                                        |
 

package/package.json

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

package/src/bootstrap.ts

@@ -22,6 +22,7 @@ import {
   initDispatcher,
   execute as dispatcherExecute,
 } from "./core/engine/dispatcher.js";
+import { bus } from "./core/bus/index.js";
 import { initPulse, resetPulseTimer } from "./core/background/pulse.js";
 import { initCron } from "./core/background/cron.js";
 import {
@@ -410,13 +411,14 @@ export async function initBackendAndDispatcher(
       resolveFrontendByNumericId(chatId, stringId, frontends).sendTyping(
         chatId,
       ),
-    onActivity: () => resetPulseTimer(),
-    // Turn-start hook: fire-and-forget dream (background memory
-    // consolidation) check. Wired here so the Weaver stays ignorant of
-    // the dream subsystem.
-    onTurnStart: maybeStartDream,
   });
 
+  // Cross-subsystem reactions ride the bus, so the Weaver stays ignorant of
+  // dream and pulse: a bound turn kicks the fire-and-forget dream check, a
+  // completed turn resets the pulse idle timer.
+  bus.subscribe("turn.started", () => maybeStartDream());
+  bus.subscribe("turn.completed", () => resetPulseTimer());
+
   initPulse();
   initCron({
     sendMessage: async (chatId: number, text: string, stringId?: string) =>

package/src/cli/daemon-api.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared CLI access to the running daemon's gateway (127.0.0.1 JSON
+ * endpoints: /tasks, /events/recent, …). Discovery finds the instance the
+ * same way `talon status` does; commands render, this module only fetches.
+ */
+
+import pc from "picocolors";
+import { findRunningInstance } from "../core/daemon/discovery.js";
+
+const REQUEST_TIMEOUT_MS = 3_000;
+
+export async function fetchGateway(
+  port: number,
+  path: string,
+  init?: RequestInit,
+): Promise<unknown> {
+  const response = await fetch(`http://127.0.0.1:${port}${path}`, {
+    ...init,
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (!response.ok) throw new Error(`gateway answered ${response.status}`);
+  return response.json();
+}
+
+/** Find the daemon and return its gateway port, or render why not. */
+export async function requireGatewayPort(): Promise<number | null> {
+  const instance = await findRunningInstance();
+  if (!instance) {
+    console.log(`  ${pc.red("●")} Talon is not running\n`);
+    return null;
+  }
+  if (!instance.port) {
+    console.log(
+      `  ${pc.yellow("●")} Talon is running (PID ${instance.pid}) but its gateway port is unknown — possibly still starting.\n`,
+    );
+    return null;
+  }
+  return instance.port;
+}

package/src/cli/events.ts

@@ -0,0 +1,98 @@
+/**
+ * `talon events` — tail the daemon's event bus.
+ *
+ * Renders the gateway's `/events/recent` ring; `--follow` (`-f`) keeps
+ * polling with a since-cursor for a live tail. Rendering only — the bus
+ * itself lives in core/bus/.
+ */
+
+import pc from "picocolors";
+import { fetchGateway, requireGatewayPort } from "./daemon-api.js";
+import type { PublishedEvent } from "../core/bus/index.js";
+
+const FOLLOW_POLL_MS = 1_000;
+
+function timestamp(at: number): string {
+  return new Date(at).toTimeString().slice(0, 8);
+}
+
+/** One tail line of type-specific detail, content-free like the events. */
+function describe(event: PublishedEvent): string {
+  switch (event.type) {
+    case "task.started":
+      return (
+        `#${event.task.id} ${event.task.kind} "${event.task.label}"` +
+        (event.task.chatId ? ` chat=${event.task.chatId}` : "")
+      );
+    case "task.settled":
+      return (
+        `#${event.task.id} ${event.task.kind} "${event.task.label}" → ${event.task.state}` +
+        (event.task.error ? ` (${event.task.error})` : "")
+      );
+    case "turn.started":
+      return `chat=${event.chatId} ${event.backendId}/${event.model} (${event.source})`;
+    case "turn.completed":
+      return `chat=${event.chatId} ${event.durationMs}ms in=${event.inputTokens} out=${event.outputTokens}`;
+  }
+}
+
+function render(event: PublishedEvent): void {
+  console.log(
+    `  ${pc.dim(timestamp(event.at))}  ${pc.cyan(event.type.padEnd(14))}  ${describe(event)}`,
+  );
+}
+
+async function fetchEvents(
+  port: number,
+  sinceId: number,
+): Promise<PublishedEvent[]> {
+  const body = (await fetchGateway(
+    port,
+    `/events/recent?since=${sinceId}`,
+  )) as { events?: PublishedEvent[] };
+  return body.events ?? [];
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function showEvents(follow: boolean): Promise<void> {
+  console.log();
+  const port = await requireGatewayPort();
+  if (port === null) return;
+
+  let cursor = 0;
+  try {
+    const events = await fetchEvents(port, cursor);
+    if (events.length === 0 && !follow) {
+      console.log(
+        `  ${pc.dim("No events yet — the bus ring starts empty on each daemon start.")}\n`,
+      );
+      return;
+    }
+    for (const event of events) render(event);
+    cursor = events.at(-1)?.id ?? 0;
+  } catch (err) {
+    console.log(
+      `  ${pc.red("✖")} Could not read the event bus: ${err instanceof Error ? err.message : err}\n`,
+    );
+    return;
+  }
+
+  if (!follow) {
+    console.log();
+    return;
+  }
+  console.log(`  ${pc.dim("Following — Ctrl+C to stop.")}`);
+  for (;;) {
+    await sleep(FOLLOW_POLL_MS);
+    try {
+      const events = await fetchEvents(port, cursor);
+      for (const event of events) render(event);
+      if (events.length > 0) cursor = events.at(-1)!.id;
+    } catch {
+      // Transient gateway hiccup (restart mid-follow) — keep polling.
+    }
+  }
+}

package/src/cli/index.ts

@@ -31,6 +31,7 @@ import { runDoctor } from "./doctor.js";
 import { startChat } from "./chat.js";
 import { daemonStart, daemonStop, daemonRestart } from "./daemon.js";
 import { showTasks, killTask } from "./tasks.js";
+import { showEvents } from "./events.js";
 import { mainMenu } from "./menu.js";
 
 export * from "./context.js";
@@ -58,6 +59,7 @@ const CLI_COMMANDS = [
   "doctor",
   "ps",
   "kill",
+  "events",
 ];
 
 /** Route a `talon <command>` invocation. Called by the entry point. */
@@ -105,6 +107,11 @@ export async function runCli(): Promise<void> {
     case "kill":
       await killTask(process.argv[3]);
       break;
+    case "events":
+      await showEvents(
+        process.argv[3] === "-f" || process.argv[3] === "--follow",
+      );
+      break;
     case "--version":
     case "-v": {
       console.log(pkg.version);
@@ -124,6 +131,9 @@ export async function runCli(): Promise<void> {
       console.log(`    ${pc.cyan("status")}     Show bot health`);
       console.log(`    ${pc.cyan("ps")}         List agent tasks (task table)`);
       console.log(`    ${pc.cyan("kill")}       Abort a killable task by id`);
+      console.log(
+        `    ${pc.cyan("events")}     Tail the event bus (-f follows)`,
+      );
       console.log(`    ${pc.cyan("config")}     View/edit configuration`);
       console.log(`    ${pc.cyan("logs")}       Tail log file`);
       console.log(`    ${pc.cyan("doctor")}     Validate environment`);

package/src/cli/tasks.ts

@@ -8,15 +8,13 @@
  */
 
 import pc from "picocolors";
-import { findRunningInstance } from "../core/daemon/discovery.js";
+import { fetchGateway, requireGatewayPort } from "./daemon-api.js";
 import type {
   KillOutcome,
   TaskRecord,
   TaskState,
 } from "../core/tasks/index.js";
 
-const REQUEST_TIMEOUT_MS = 3_000;
-
 function formatDuration(ms: number): string {
   const seconds = Math.floor(ms / 1000);
   if (seconds < 60) return `${seconds}s`;
@@ -107,35 +105,6 @@ function renderTable(tasks: TaskRecord[], now: number): void {
   console.log();
 }
 
-async function fetchGateway(
-  port: number,
-  path: string,
-  init?: RequestInit,
-): Promise<unknown> {
-  const response = await fetch(`http://127.0.0.1:${port}${path}`, {
-    ...init,
-    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
-  });
-  if (!response.ok) throw new Error(`gateway answered ${response.status}`);
-  return response.json();
-}
-
-/** Find the daemon and return its gateway port, or render why not. */
-async function requireGatewayPort(): Promise<number | null> {
-  const instance = await findRunningInstance();
-  if (!instance) {
-    console.log(`  ${pc.red("●")} Talon is not running\n`);
-    return null;
-  }
-  if (!instance.port) {
-    console.log(
-      `  ${pc.yellow("●")} Talon is running (PID ${instance.pid}) but its gateway port is unknown — possibly still starting.\n`,
-    );
-    return null;
-  }
-  return instance.port;
-}
-
 export async function showTasks(): Promise<void> {
   console.log();
   const port = await requireGatewayPort();

package/src/core/bus/bus.ts

@@ -0,0 +1,114 @@
+/**
+ * TalonBus — the daemon's internal event spine.
+ *
+ * One instance (`bus`) serves the whole process. Producers publish typed
+ * events (see events.ts); consumers subscribe by type. The bus is the seam
+ * that lets subsystems react to each other without importing each other —
+ * bootstrap wires dream and pulse as subscribers instead of threading
+ * callbacks through the Weaver, and future work (triggers as subscribers,
+ * companion task feeds, mesh presence) lands as more publishers/consumers.
+ *
+ * Delivery contract:
+ *   - Synchronous, in publish order, to every matching subscriber.
+ *   - Fire-and-forget: a subscriber that throws (or returns a rejecting
+ *     promise) is logged and never affects the publisher or its peers.
+ *   - Subscribers must not block: anything slow belongs behind its own
+ *     queue or timer, not inside a handler.
+ *
+ * The bus also keeps a bounded ring of recent events with monotonic ids —
+ * the observability surface behind the gateway's `/events/recent` and
+ * `talon events`. In-memory only, like the task table: events describe
+ * moments in a live process, so there is nothing truthful to persist.
+ */
+
+import { logError } from "../../util/log.js";
+import type { PublishedEvent, TalonEvent, TalonEventType } from "./events.js";
+
+/** Recent events kept for the tail surfaces. */
+const DEFAULT_RECENT_LIMIT = 200;
+
+type Handler<T extends TalonEventType> = (
+  event: Extract<PublishedEvent, { type: T }>,
+) => void | Promise<void>;
+
+type AnyHandler = (event: PublishedEvent) => void | Promise<void>;
+
+export class TalonBus {
+  private readonly byType = new Map<TalonEventType, Set<AnyHandler>>();
+  private readonly all = new Set<AnyHandler>();
+  private readonly ring: PublishedEvent[] = [];
+  private readonly recentLimit: number;
+  private nextId = 1;
+
+  constructor(recentLimit = DEFAULT_RECENT_LIMIT) {
+    this.recentLimit = recentLimit;
+  }
+
+  /** Subscribe to one event type. Returns the unsubscribe function. */
+  subscribe<T extends TalonEventType>(
+    type: T,
+    handler: Handler<T>,
+  ): () => void {
+    const set = this.byType.get(type) ?? new Set<AnyHandler>();
+    this.byType.set(type, set);
+    const anyHandler = handler as AnyHandler;
+    set.add(anyHandler);
+    return () => {
+      set.delete(anyHandler);
+    };
+  }
+
+  /** Subscribe to every event (tails, forwarders). Returns unsubscribe. */
+  subscribeAll(handler: AnyHandler): () => void {
+    this.all.add(handler);
+    return () => {
+      this.all.delete(handler);
+    };
+  }
+
+  /** Stamp and deliver an event. Never throws. */
+  publish(event: TalonEvent): PublishedEvent {
+    const published: PublishedEvent = {
+      ...event,
+      id: this.nextId++,
+      at: Date.now(),
+    };
+    this.ring.push(published);
+    if (this.ring.length > this.recentLimit) {
+      this.ring.splice(0, this.ring.length - this.recentLimit);
+    }
+    for (const handler of this.byType.get(event.type) ?? []) {
+      this.deliver(handler, published);
+    }
+    for (const handler of this.all) {
+      this.deliver(handler, published);
+    }
+    return published;
+  }
+
+  /**
+   * Recent events, id-ascending — all of the ring, or only those after
+   * `sinceId` (the tail-follow cursor).
+   */
+  recent(sinceId = 0): PublishedEvent[] {
+    return sinceId > 0
+      ? this.ring.filter((event) => event.id > sinceId)
+      : [...this.ring];
+  }
+
+  private deliver(handler: AnyHandler, event: PublishedEvent): void {
+    try {
+      const result = handler(event);
+      if (result instanceof Promise) {
+        result.catch((err: unknown) => {
+          logError("bus", `Subscriber for ${event.type} rejected`, err);
+        });
+      }
+    } catch (err) {
+      logError("bus", `Subscriber for ${event.type} threw`, err);
+    }
+  }
+}
+
+/** The daemon-wide bus. Tests needing isolation construct their own. */
+export const bus = new TalonBus();

package/src/core/bus/events.ts

@@ -0,0 +1,64 @@
+/**
+ * Event vocabulary — every event the Talon bus carries.
+ *
+ * The union is deliberately small and honest: a type exists here only when
+ * something in the runtime actually publishes it. Growing the vocabulary is
+ * a one-line union change; each addition should land together with its
+ * publisher (and ideally its first subscriber).
+ *
+ * Two families exist today:
+ *
+ *   - `task.*` — lifecycle of agent work, published by the task table
+ *     (core/tasks). Uniform across kinds: a heartbeat pass, a dream run, an
+ *     isolated cron/trigger job, and a chat turn all surface here.
+ *   - `turn.*` — the chat-domain moments inside a turn that other
+ *     subsystems key off: `turn.started` fires once the warp is bound and
+ *     the backend is about to run (never for a no-model refusal);
+ *     `turn.completed` fires only for a successfully finished turn.
+ */
+
+import type { TaskRecord } from "../tasks/types.js";
+
+/** A task left the queue and began running. */
+export interface TaskStartedEvent {
+  readonly type: "task.started";
+  readonly task: TaskRecord;
+}
+
+/** A task reached a terminal state (done / failed / killed). */
+export interface TaskSettledEvent {
+  readonly type: "task.settled";
+  readonly task: TaskRecord;
+}
+
+/** A chat turn bound its warp and is about to run on the backend. */
+export interface TurnStartedEvent {
+  readonly type: "turn.started";
+  readonly chatId: string;
+  readonly source: string;
+  readonly model: string;
+  readonly backendId: string;
+}
+
+/** A chat turn finished successfully (refusals and failures never emit this). */
+export interface TurnCompletedEvent {
+  readonly type: "turn.completed";
+  readonly chatId: string;
+  readonly source: string;
+  readonly durationMs: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+}
+
+export type TalonEvent =
+  TaskStartedEvent | TaskSettledEvent | TurnStartedEvent | TurnCompletedEvent;
+
+export type TalonEventType = TalonEvent["type"];
+
+/** What subscribers receive: the event plus its bus stamp. */
+export type PublishedEvent = TalonEvent & {
+  /** Monotonic per-process sequence number — the tail cursor. */
+  readonly id: number;
+  /** Publish time, epoch ms. */
+  readonly at: number;
+};

package/src/core/bus/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Event bus — public surface.
+ *
+ * See bus.ts for the spine and events.ts for the vocabulary. Publishers
+ * today: the task table (task.*) and the Weaver (turn.*). Subscribers are
+ * wired at the composition root (bootstrap: dream on turn.started, pulse on
+ * turn.completed); read surfaces: gateway `GET /events/recent`, CLI
+ * `talon events`.
+ */
+
+export { TalonBus, bus } from "./bus.js";
+export type {
+  PublishedEvent,
+  TalonEvent,
+  TalonEventType,
+  TaskSettledEvent,
+  TaskStartedEvent,
+  TurnCompletedEvent,
+  TurnStartedEvent,
+} from "./events.js";

package/src/core/engine/gateway.ts

@@ -27,6 +27,7 @@ import {
   HUB_PATH_PREFIX,
 } from "../mcp-hub/index.js";
 import { handlePluginAction } from "../plugin/index.js";
+import { bus } from "../bus/index.js";
 import { taskTable } from "../tasks/index.js";
 import type { FrontendActionHandler } from "../types.js";
 import { BOT_MESSAGE_ACTIONS, noteBotMessage } from "../soul/taps.js";
@@ -396,6 +397,23 @@ export class Gateway {
           return;
         }
 
+        if (req.method === "GET" && req.url?.startsWith("/events/recent")) {
+          // Bus tail — recent events, optionally after a cursor. Read by
+          // `talon events`. Same 127.0.0.1 trust boundary as /action.
+          const url = new URL(req.url, "http://gateway");
+          const since = Number(url.searchParams.get("since") ?? "0");
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(
+            JSON.stringify({
+              ok: true,
+              events: bus.recent(
+                Number.isInteger(since) && since > 0 ? since : 0,
+              ),
+            }),
+          );
+          return;
+        }
+
         if (req.method === "GET" && req.url === "/tasks") {
           // The task table — every live/recent unit of agent work. Read by
           // `talon ps`. Same 127.0.0.1 trust boundary as /action.

package/src/core/tasks/table.ts

@@ -12,6 +12,8 @@
  * work that no longer exists.
  */
 
+import { bus } from "../bus/index.js";
+import type { TaskSettledEvent, TaskStartedEvent } from "../bus/events.js";
 import type {
   KillOutcome,
   TaskBinding,
@@ -25,6 +27,17 @@ import type {
 /** Settled tasks kept for `list()` after they leave the live map. */
 const DEFAULT_HISTORY_LIMIT = 50;
 
+export interface TaskTableOptions {
+  /** Settled tasks kept for `list()` (default 50). */
+  readonly historyLimit?: number;
+  /**
+   * Sink for `task.*` lifecycle events — the singleton wires the bus here.
+   * Injected (rather than imported at the emit sites) so unit-constructed
+   * tables stay silent.
+   */
+  readonly publish?: (event: TaskStartedEvent | TaskSettledEvent) => void;
+}
+
 type MutableTaskRecord = {
   -readonly [K in keyof TaskRecord]: TaskRecord[K];
 };
@@ -39,10 +52,14 @@ export class TaskTable {
   private readonly live = new Map<number, LiveTask>();
   private readonly history: TaskRecord[] = [];
   private readonly historyLimit: number;
+  private readonly publish?: (
+    event: TaskStartedEvent | TaskSettledEvent,
+  ) => void;
   private nextId = 1;
 
-  constructor(historyLimit = DEFAULT_HISTORY_LIMIT) {
-    this.historyLimit = historyLimit;
+  constructor(options: TaskTableOptions = {}) {
+    this.historyLimit = options.historyLimit ?? DEFAULT_HISTORY_LIMIT;
+    if (options.publish) this.publish = options.publish;
   }
 
   /** Register a run that starts immediately. */
@@ -122,6 +139,7 @@ export class TaskTable {
     if (!task || task.record.state !== "queued") return;
     task.record.state = "running";
     task.record.startedAt = Date.now();
+    this.publish?.({ type: "task.started", task: { ...task.record } });
   }
 
   private bind(id: number, binding: TaskBinding): void {
@@ -154,8 +172,11 @@ export class TaskTable {
     if (this.history.length > this.historyLimit) {
       this.history.splice(0, this.history.length - this.historyLimit);
     }
+    this.publish?.({ type: "task.settled", task: { ...record } });
   }
 }
 
 /** The daemon-wide table. Tests needing isolation construct their own. */
-export const taskTable = new TaskTable();
+export const taskTable = new TaskTable({
+  publish: (event) => bus.publish(event),
+});

package/src/core/weaver/weaver.ts

@@ -24,6 +24,7 @@ import type { AgentResult } from "../agent-runtime/events.js";
 import type { ModelRef } from "../agent-runtime/model-ref.js";
 import type { MemoryRetriever } from "../memory/retrieval.js";
 import type { ContextManager, ExecuteParams, ExecuteResult } from "../types.js";
+import { bus } from "../bus/index.js";
 import { taskTable, type TaskHandle } from "../tasks/index.js";
 import { log, logDebug, logWarn } from "../../util/log.js";
 import { Loom } from "./loom.js";
@@ -51,15 +52,6 @@ export type WeaverDeps = {
   ) => Promise<ModelRef | null>;
   context: ContextManager;
   sendTyping: (chatId: number, stringId?: string) => Promise<void>;
-  onActivity: () => void;
-  /**
-   * Optional fire-and-forget hook invoked at the start of every turn,
-   * after the warp is bound and before the backend is called. The
-   * composition root wires background work here (e.g. dream memory
-   * consolidation) so the Weaver stays ignorant of those subsystems.
-   * Must not throw and must not block — it is called synchronously.
-   */
-  onTurnStart?: () => void;
   /**
    * Optional memory pre-retrieval (Phase B). Called for `source: "message"`
    * turns after model/backend resolution and context acquisition, before
@@ -134,7 +126,7 @@ export class Weaver {
     params: ExecuteParams,
     task: TaskHandle,
   ): Promise<ExecuteResult> {
-    const { context, onActivity, retrieveMemory } = this.deps;
+    const { context, retrieveMemory } = this.deps;
     const backend = this.deps.getBackend(params.chatId);
     const reqId = randomBytes(4).toString("hex");
 
@@ -180,7 +172,16 @@ export class Weaver {
       );
     }
 
-    this.deps.onTurnStart?.();
+    // Turn-start signal — dream (and anything else the composition root
+    // subscribes) keys off this. Fires only for turns that actually reach
+    // the backend: the no-model refusal above returns before this point.
+    bus.publish({
+      type: "turn.started",
+      chatId: params.chatId,
+      source: params.source,
+      model: warp.ref.id,
+      backendId: warp.backendId,
+    });
 
     logDebug(
       "dispatcher",
@@ -221,7 +222,16 @@ export class Weaver {
       });
       const agentResult = await carryTurnEvents(stream, params.onEvent);
 
-      onActivity();
+      // Completion signal — pulse (and any other liveness subscriber) keys
+      // off this. Failures throw past it; refusals never get this far.
+      bus.publish({
+        type: "turn.completed",
+        chatId: params.chatId,
+        source: params.source,
+        durationMs: agentResult?.durationMs ?? 0,
+        inputTokens: agentResult?.usage.inputTokens ?? 0,
+        outputTokens: agentResult?.usage.outputTokens ?? 0,
+      });
       logDebug(
         "dispatcher",
         `[${reqId}] completed in ${agentResult?.durationMs ?? 0}ms ` +

package/src/util/log.ts

@@ -23,6 +23,7 @@ import { dirs, files } from "./paths.js";
 export type LogComponent =
   | "bot"
   | "bridge"
+  | "bus"
   | "db"
   | "kv"
   | "media"