talon-agent 1.47.1 → 1.48.0

package/README.md

@@ -22,6 +22,7 @@ Multi-platform agentic AI harness. Runs on **Telegram**, **Discord**, **Microsof
 | **Goals**             | Persistent multi-day objectives the agent commits to in chat; every heartbeat run re-reads them, makes progress, and records what it did     |
 | **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`             |
 | **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.47.1",
+  "version": "1.48.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/src/cli/index.ts

@@ -30,6 +30,7 @@ import { tailLogs } from "./logs.js";
 import { runDoctor } from "./doctor.js";
 import { startChat } from "./chat.js";
 import { daemonStart, daemonStop, daemonRestart } from "./daemon.js";
+import { showTasks, killTask } from "./tasks.js";
 import { mainMenu } from "./menu.js";
 
 export * from "./context.js";
@@ -55,6 +56,8 @@ const CLI_COMMANDS = [
   "run",
   "chat",
   "doctor",
+  "ps",
+  "kill",
 ];
 
 /** Route a `talon <command>` invocation. Called by the entry point. */
@@ -96,6 +99,12 @@ export async function runCli(): Promise<void> {
     case "doctor":
       runDoctor();
       break;
+    case "ps":
+      await showTasks();
+      break;
+    case "kill":
+      await killTask(process.argv[3]);
+      break;
     case "--version":
     case "-v": {
       console.log(pkg.version);
@@ -113,6 +122,8 @@ export async function runCli(): Promise<void> {
       console.log(`    ${pc.cyan("run")}        Run in foreground (attached)`);
       console.log(`    ${pc.cyan("chat")}       Terminal chat mode`);
       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("config")}     View/edit configuration`);
       console.log(`    ${pc.cyan("logs")}       Tail log file`);
       console.log(`    ${pc.cyan("doctor")}     Validate environment`);

package/src/cli/tasks.ts

@@ -0,0 +1,212 @@
+/**
+ * `talon ps` / `talon kill` — the task table from the outside.
+ *
+ * Data comes from the running daemon's gateway (`GET /tasks`,
+ * `POST /tasks/kill`); discovery finds the instance the same way
+ * `talon status` does. This module only renders — the table itself
+ * lives in core/tasks/.
+ */
+
+import pc from "picocolors";
+import { findRunningInstance } from "../core/daemon/discovery.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`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+  return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`;
+}
+
+function formatTokenCount(n: number): string {
+  if (n < 1000) return String(n);
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
+  return `${(n / 1_000_000).toFixed(1)}M`;
+}
+
+function formatTokens(task: TaskRecord): string {
+  if (!task.usage) return "—";
+  return `${formatTokenCount(task.usage.inputTokens)}→${formatTokenCount(task.usage.outputTokens)}`;
+}
+
+/** Queued: wait so far. Running: runtime so far. Settled: total runtime. */
+function formatTime(task: TaskRecord, now: number): string {
+  if (task.state === "queued") return formatDuration(now - task.queuedAt);
+  const start = task.startedAt ?? task.queuedAt;
+  return formatDuration((task.endedAt ?? now) - start);
+}
+
+function colorState(state: TaskState): string {
+  switch (state) {
+    case "running":
+      return pc.green(state);
+    case "queued":
+      return pc.yellow(state);
+    case "done":
+      return pc.dim(state);
+    case "failed":
+      return pc.red(state);
+    case "killed":
+      return pc.magenta(state);
+  }
+}
+
+/** Live tasks first (oldest running at the top), then history newest-first. */
+function displayOrder(tasks: TaskRecord[]): TaskRecord[] {
+  const live = tasks.filter(
+    (t) => t.state === "running" || t.state === "queued",
+  );
+  const settled = tasks.filter(
+    (t) => t.state !== "running" && t.state !== "queued",
+  );
+  live.sort((a, b) => a.id - b.id);
+  settled.sort((a, b) => b.id - a.id);
+  return [...live, ...settled];
+}
+
+type Row = readonly string[];
+
+const HEADER: Row = ["ID", "STATE", "KIND", "TIME", "TOKENS", "LABEL", "CHAT"];
+
+function toRow(task: TaskRecord, now: number): Row {
+  return [
+    String(task.id),
+    task.state,
+    task.kind,
+    formatTime(task, now),
+    formatTokens(task),
+    task.label,
+    task.chatId ?? "—",
+  ];
+}
+
+/**
+ * Pad every column to its widest cell. Colors are applied after padding
+ * (the state cell) so ANSI escapes never skew the width math.
+ */
+function renderTable(tasks: TaskRecord[], now: number): void {
+  const rows = tasks.map((t) => toRow(t, now));
+  const widths = HEADER.map((h, col) =>
+    Math.max(h.length, ...rows.map((r) => r[col]!.length)),
+  );
+  const pad = (row: Row) => row.map((cell, col) => cell.padEnd(widths[col]!));
+
+  console.log(`  ${pc.dim(pad(HEADER).join("  "))}`);
+  tasks.forEach((task, i) => {
+    const cells = pad(rows[i]!);
+    cells[1] =
+      colorState(task.state) + " ".repeat(widths[1]! - task.state.length);
+    console.log(`  ${cells.join("  ")}`);
+  });
+  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();
+  if (port === null) return;
+
+  let tasks: TaskRecord[];
+  try {
+    const body = (await fetchGateway(port, "/tasks")) as {
+      tasks?: TaskRecord[];
+    };
+    tasks = body.tasks ?? [];
+  } catch (err) {
+    console.log(
+      `  ${pc.red("✖")} Could not read the task table: ${err instanceof Error ? err.message : err}\n`,
+    );
+    return;
+  }
+
+  if (tasks.length === 0) {
+    console.log(
+      `  ${pc.dim("No tasks — the table starts empty on each daemon start.")}\n`,
+    );
+    return;
+  }
+  renderTable(displayOrder(tasks), Date.now());
+}
+
+export async function killTask(rawId: string | undefined): Promise<void> {
+  console.log();
+  const id = Number(rawId);
+  if (rawId === undefined || !Number.isInteger(id)) {
+    console.log(
+      `  ${pc.red("✖")} Usage: ${pc.cyan("talon kill <id>")} — ids come from ${pc.cyan("talon ps")}\n`,
+    );
+    return;
+  }
+
+  const port = await requireGatewayPort();
+  if (port === null) return;
+
+  let outcome: KillOutcome;
+  try {
+    outcome = (await fetchGateway(port, "/tasks/kill", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ id }),
+    })) as KillOutcome;
+  } catch (err) {
+    console.log(
+      `  ${pc.red("✖")} Kill request failed: ${err instanceof Error ? err.message : err}\n`,
+    );
+    return;
+  }
+
+  if (outcome.ok) {
+    console.log(
+      `  ${pc.green("●")} Task ${id} aborted — it settles as ${pc.magenta("killed")} once the backend honours the abort.\n`,
+    );
+    return;
+  }
+  switch (outcome.reason) {
+    case "not-found":
+      console.log(`  ${pc.red("✖")} No task ${id} in the table.\n`);
+      return;
+    case "finished":
+      console.log(`  ${pc.dim("●")} Task ${id} already finished.\n`);
+      return;
+    case "not-killable":
+      console.log(
+        `  ${pc.yellow("!")} Task ${id} has no abort hook (chat turns run to completion) — it cannot be killed.\n`,
+      );
+      return;
+  }
+}

package/src/core/background/dream.ts

@@ -22,6 +22,7 @@ import { getDefaultModel } from "../models/catalog.js";
 import type { OneShotAgentParams } from "../types.js";
 import type { Backend } from "../agent-runtime/capabilities.js";
 import { getSoul } from "../soul/service.js";
+import { taskTable } from "../tasks/index.js";
 import { FailureBackoff } from "./failure-backoff.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
@@ -259,6 +260,13 @@ If commands fail, log the error and continue — this stage is optional.`
 
   const abortController = new AbortController();
 
+  const task = taskTable.begin({
+    kind: "dream",
+    label: "consolidation",
+    abort: () => abortController.abort(),
+  });
+  task.bind({ model });
+
   const oneShotParams: OneShotAgentParams = {
     prompt,
     systemPrompt,
@@ -298,6 +306,7 @@ If commands fail, log the error and continue — this stage is optional.`
   try {
     await Promise.race([agentPromise, timeoutPromise]);
   } catch (err) {
+    task.fail(err);
     appendDreamLog(
       dreamLogFile,
       `\n---\n**Dream FAILED at ${new Date().toISOString()}:** ${err}\n`,
@@ -323,6 +332,7 @@ If commands fail, log the error and continue — this stage is optional.`
     if (timeoutHandle) clearTimeout(timeoutHandle);
   }
 
+  task.succeed();
   return dreamLogFile;
 }
 

package/src/core/background/heartbeat/agent.ts

@@ -12,6 +12,7 @@ import { toYMD } from "../../../util/time.js";
 import { getDefaultModel } from "../../models/catalog.js";
 import { loadSystemTemplate } from "../../prompt/templates.js";
 import { formatGoal, getOpenGoals } from "../../../storage/goal-store.js";
+import { taskTable } from "../../tasks/index.js";
 import type { OneShotAgentParams } from "../../types.js";
 import { hb } from "./state.js";
 
@@ -184,6 +185,13 @@ export async function runHeartbeatAgent(
   // heartbeatAbortGraceMs below.
   const abortController = new AbortController();
 
+  const task = taskTable.begin({
+    kind: "heartbeat",
+    label: `#${runCount}`,
+    abort: () => abortController.abort(),
+  });
+  task.bind({ model });
+
   const oneShotParams: OneShotAgentParams = {
     prompt,
     systemPrompt: buildHeartbeatSystemPrompt(),
@@ -231,6 +239,7 @@ export async function runHeartbeatAgent(
       clearTimeout(timeoutHandle);
       timeoutHandle = null;
     }
+    task.fail(err);
     await appendHeartbeatLog(
       heartbeatLogFile,
       `\n---\n**Heartbeat #${runCount} FAILED at ${new Date().toISOString()}:** ${err}\n`,
@@ -269,6 +278,7 @@ export async function runHeartbeatAgent(
     if (timeoutHandle) clearTimeout(timeoutHandle);
   }
 
+  task.succeed();
   return heartbeatLogFile;
 }
 

package/src/core/background/job-oneshot.ts

@@ -20,6 +20,7 @@ import {
   acquireBackendInstance,
   isModelValidForBackend,
 } from "../engine/backend-controller/index.js";
+import { taskTable } from "../tasks/index.js";
 import type { OneShotAgentParams } from "../types.js";
 import { runIsolatedAgent } from "./isolated-agent.js";
 import {
@@ -132,6 +133,15 @@ export async function runJobOneShot(
       params.model,
     );
 
+    const abortController = new AbortController();
+    const task = taskTable.begin({
+      kind: params.kind,
+      label: params.label,
+      chatId: params.chatId,
+      abort: () => abortController.abort(),
+    });
+    task.bind({ model: params.model, backendId: params.backendId });
+
     const oneShot: OneShotAgentParams = {
       prompt: params.payload,
       systemPrompt: buildJobSystemPrompt(
@@ -142,18 +152,24 @@ export async function runJobOneShot(
       contextLabel: JOB_CONTEXT_LABEL,
       workspace: dirs.workspace,
       model: params.model,
-      abortController: new AbortController(),
+      abortController,
       appendLog,
     };
 
-    await runIsolatedAgent({
-      background,
-      params: oneShot,
-      timeoutMs: params.timeoutMs ?? DEFAULT_JOB_TIMEOUT_MS,
-      // No evictLabel: the job context label is shared with heartbeat, so a
-      // sweep here could kill a concurrent heartbeat's subprocess. Bounded
-      // abort-grace is enough.
-    });
+    try {
+      await runIsolatedAgent({
+        background,
+        params: oneShot,
+        timeoutMs: params.timeoutMs ?? DEFAULT_JOB_TIMEOUT_MS,
+        // No evictLabel: the job context label is shared with heartbeat, so a
+        // sweep here could kill a concurrent heartbeat's subprocess. Bounded
+        // abort-grace is enough.
+      });
+      task.succeed();
+    } catch (err) {
+      task.fail(err);
+      throw err;
+    }
     log(
       params.kind === "cron" ? "cron" : "triggers",
       `isolated job "${params.label}" ran on ${params.backendId}/${params.model}`,

package/src/core/engine/gateway-actions/native.ts

@@ -25,7 +25,7 @@ import {
   writeFile,
 } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, extname, join } from "node:path";
 import { getMeshService } from "../../mesh/index.js";
 import {
   clearTeleport,
@@ -39,7 +39,12 @@ import {
 } from "../../../util/exec-output.js";
 import type { SharedActionHandlers } from "./types.js";
 
-type Result = { ok: boolean; text: string };
+type Result = {
+  ok: boolean;
+  text: string;
+  /** Set for image files so the tool result carries a viewable image block. */
+  image?: { data: string; mimeType: string };
+};
 
 /**
  * ripgrep binary, resolved from PATH (env-overridable for tests). NOT a
@@ -70,6 +75,21 @@ const TELEPORT_TIMEOUT_HINT =
   "background it in-shell instead: `cmd > /tmp/out.log 2>&1 &`, then poll the log " +
   "with read, or bound the command itself: `logcat -d`, `timeout 30 …`, `head -n 200`.)";
 const MAX_READ_LINES = 2_000;
+/**
+ * Image extensions the model can actually view, mapped to their MIME type.
+ * Reading one returns an image content block instead of the file's raw bytes
+ * decoded as (garbage) UTF-8 — so `read`ing a photo/screenshot/design shows
+ * the picture, not mojibake.
+ */
+const IMAGE_MIME: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+};
+/** Anthropic caps a single image around 5MB; refuse larger with a downscale hint. */
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
 /** Caps for the pure-JS glob/search fallbacks (rg unavailable). */
 const MAX_JS_RESULTS = 2_000;
 const MAX_JS_FILE_BYTES = 2 * 1024 * 1024;
@@ -437,23 +457,58 @@ async function read(
 ): Promise<Result> {
   const p = str(path);
   if (!p) return { ok: false, text: "A file path is required." };
+  const active = await getTeleport(chatId);
+  const where = active ? active.deviceName : "local";
+
+  // Image files: return a viewable image block, not the raw bytes decoded as
+  // UTF-8. Without this, `read`ing a photo/screenshot/design hands the model
+  // mojibake and it can't see the picture at all.
+  const mime = IMAGE_MIME[extname(p).toLowerCase()];
+  if (mime) {
+    let bytes: Buffer;
+    if (active) {
+      const res = await getMeshService().readFileBytes(active.deviceId, p);
+      if ("error" in res) return { ok: false, text: res.error };
+      bytes = res.data;
+    } else {
+      try {
+        bytes = await readFile(p);
+      } catch (err) {
+        return {
+          ok: false,
+          text: `Cannot read ${p}: ${(err as Error).message}`,
+        };
+      }
+    }
+    if (bytes.length > MAX_IMAGE_BYTES) {
+      return {
+        ok: false,
+        text:
+          `${p} [${where}] is ${(bytes.length / 1_048_576).toFixed(1)}MB — over the ` +
+          `${MAX_IMAGE_BYTES / 1_048_576}MB image limit. Downscale it first ` +
+          `(e.g. \`convert '${p}' -resize 1568x /tmp/small.jpg\`) and read that.`,
+      };
+    }
+    return {
+      ok: true,
+      text: `${p} [${where}] — image (${mime}, ${bytes.length} bytes)`,
+      image: { data: bytes.toString("base64"), mimeType: mime },
+    };
+  }
+
   const start = num(offset) ?? 0;
   const max = Math.min(num(limit) ?? MAX_READ_LINES, MAX_READ_LINES);
-  const active = await getTeleport(chatId);
   let content: string;
-  let where: string;
   if (active) {
     const res = await getMeshService().readFileBytes(active.deviceId, p);
     if ("error" in res) return { ok: false, text: res.error };
     content = res.data.toString("utf8");
-    where = active.deviceName;
   } else {
     try {
       content = await readFile(p, "utf8");
     } catch (err) {
       return { ok: false, text: `Cannot read ${p}: ${(err as Error).message}` };
     }
-    where = "local";
   }
   const lines = content.split("\n");
   const slice = lines.slice(start, start + max);

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 { taskTable } from "../tasks/index.js";
 import type { FrontendActionHandler } from "../types.js";
 import { BOT_MESSAGE_ACTIONS, noteBotMessage } from "../soul/taps.js";
 import type { Backend } from "../agent-runtime/capabilities.js";
@@ -395,6 +396,39 @@ export class Gateway {
           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.
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ ok: true, tasks: taskTable.list() }));
+          return;
+        }
+
+        if (req.method === "POST" && req.url === "/tasks/kill") {
+          // Abort one killable task by id — the transport for `talon kill`.
+          const chunks: Buffer[] = [];
+          for await (const chunk of req) chunks.push(chunk as Buffer);
+          let id: unknown;
+          try {
+            const body = JSON.parse(Buffer.concat(chunks).toString("utf-8"));
+            id = (body as { id?: unknown }).id;
+          } catch {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ ok: false, error: "Invalid JSON" }));
+            return;
+          }
+          if (typeof id !== "number" || !Number.isInteger(id)) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(
+              JSON.stringify({ ok: false, error: "id must be an integer" }),
+            );
+            return;
+          }
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(taskTable.kill(id)));
+          return;
+        }
+
         if (req.url?.startsWith(HUB_PATH_PREFIX)) {
           // MCP hub — daemon-hosted MCP-over-HTTP endpoints for every
           // backend (see core/mcp-hub). Same 127.0.0.1 trust boundary

package/src/core/tasks/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Task table — public surface.
+ *
+ * See table.ts for the registry and types.ts for the vocabulary. Wiring
+ * points: weaver (turns), heartbeat/agent, dream, background/job-oneshot
+ * (isolated cron/trigger jobs); read surfaces: gateway `GET /tasks` +
+ * `POST /tasks/kill`, CLI `talon ps` / `talon kill`.
+ */
+
+export { TaskTable, taskTable } from "./table.js";
+export type {
+  KillOutcome,
+  TaskBinding,
+  TaskHandle,
+  TaskKind,
+  TaskRecord,
+  TaskSpec,
+  TaskState,
+  TaskUsage,
+} from "./types.js";

package/src/core/tasks/table.ts

@@ -0,0 +1,161 @@
+/**
+ * TaskTable — live registry plus bounded history of agent-work runs.
+ *
+ * One instance (`taskTable`) serves the whole daemon. Call sites register a
+ * run with `begin`/`enqueue` and settle it through the returned TaskHandle;
+ * the gateway serves `list()` over HTTP and routes `talon kill` to `kill()`.
+ *
+ * The table is observational: it never schedules, retries, or times out a
+ * run — those disciplines stay with the owning module (weaver, heartbeat,
+ * dream, job-oneshot). In-memory only by design: a task is a live run, and
+ * a daemon restart ends every run, so persisted rows could only describe
+ * work that no longer exists.
+ */
+
+import type {
+  KillOutcome,
+  TaskBinding,
+  TaskHandle,
+  TaskRecord,
+  TaskSpec,
+  TaskState,
+  TaskUsage,
+} from "./types.js";
+
+/** Settled tasks kept for `list()` after they leave the live map. */
+const DEFAULT_HISTORY_LIMIT = 50;
+
+type MutableTaskRecord = {
+  -readonly [K in keyof TaskRecord]: TaskRecord[K];
+};
+
+interface LiveTask {
+  readonly record: MutableTaskRecord;
+  readonly abort?: () => void;
+  killRequested: boolean;
+}
+
+export class TaskTable {
+  private readonly live = new Map<number, LiveTask>();
+  private readonly history: TaskRecord[] = [];
+  private readonly historyLimit: number;
+  private nextId = 1;
+
+  constructor(historyLimit = DEFAULT_HISTORY_LIMIT) {
+    this.historyLimit = historyLimit;
+  }
+
+  /** Register a run that starts immediately. */
+  begin(spec: TaskSpec): TaskHandle {
+    const handle = this.enqueue(spec);
+    handle.start();
+    return handle;
+  }
+
+  /** Register a run that is waiting its turn (e.g. a chat's FIFO queue). */
+  enqueue(spec: TaskSpec): TaskHandle {
+    const id = this.nextId++;
+    const record: MutableTaskRecord = {
+      id,
+      kind: spec.kind,
+      label: spec.label,
+      state: "queued",
+      killable: spec.abort !== undefined,
+      queuedAt: Date.now(),
+    };
+    if (spec.chatId !== undefined) record.chatId = spec.chatId;
+    const task: LiveTask = {
+      record,
+      killRequested: false,
+      ...(spec.abort !== undefined ? { abort: spec.abort } : {}),
+    };
+    this.live.set(id, task);
+    return {
+      id,
+      start: () => this.start(id),
+      bind: (binding) => this.bind(id, binding),
+      succeed: (usage) => this.settle(id, "done", undefined, usage),
+      fail: (error) => this.settle(id, "failed", error),
+    };
+  }
+
+  /**
+   * Request an abort of a live killable task. Returns immediately — the
+   * task stays `running` until its owner's failure path lands, at which
+   * point it settles as `killed`. Repeat kills are no-ops that still
+   * report `ok` (the request stands); the abort hook fires only once.
+   */
+  kill(id: number): KillOutcome {
+    const task = this.live.get(id);
+    if (!task) {
+      return this.history.some((record) => record.id === id)
+        ? { ok: false, reason: "finished" }
+        : { ok: false, reason: "not-found" };
+    }
+    if (!task.abort) return { ok: false, reason: "not-killable" };
+    if (!task.killRequested) {
+      task.killRequested = true;
+      try {
+        task.abort();
+      } catch {
+        // The abort hook contract is "must not throw" — a violation must
+        // not break the kill path for the caller.
+      }
+    }
+    return { ok: true };
+  }
+
+  /**
+   * Every live task plus the bounded settled history, id-ascending.
+   * Snapshots are copies — callers can never mutate table state.
+   */
+  list(): TaskRecord[] {
+    const records: TaskRecord[] = this.history.map((record) => ({
+      ...record,
+    }));
+    for (const task of this.live.values()) records.push({ ...task.record });
+    return records.sort((a, b) => a.id - b.id);
+  }
+
+  private start(id: number): void {
+    const task = this.live.get(id);
+    if (!task || task.record.state !== "queued") return;
+    task.record.state = "running";
+    task.record.startedAt = Date.now();
+  }
+
+  private bind(id: number, binding: TaskBinding): void {
+    const task = this.live.get(id);
+    if (!task) return;
+    if (binding.model !== undefined) task.record.model = binding.model;
+    if (binding.backendId !== undefined)
+      task.record.backendId = binding.backendId;
+  }
+
+  private settle(
+    id: number,
+    state: Extract<TaskState, "done" | "failed">,
+    error?: unknown,
+    usage?: TaskUsage,
+  ): void {
+    const task = this.live.get(id);
+    if (!task) return;
+    const { record } = task;
+    // A kill only "takes" when the run actually dies: a run that completes
+    // despite the abort settles as done, one that unwinds settles as killed.
+    record.state = state === "failed" && task.killRequested ? "killed" : state;
+    record.endedAt = Date.now();
+    if (error !== undefined) {
+      record.error = error instanceof Error ? error.message : String(error);
+    }
+    if (usage !== undefined) record.usage = usage;
+    this.live.delete(id);
+    this.history.push(record);
+    if (this.history.length > this.historyLimit) {
+      this.history.splice(0, this.history.length - this.historyLimit);
+    }
+  }
+}
+
+/** The daemon-wide table. Tests needing isolation construct their own. */
+export const taskTable = new TaskTable();

package/src/core/tasks/types.ts

@@ -0,0 +1,100 @@
+/**
+ * Task table vocabulary — the daemon's registry of agent work.
+ *
+ * A task is one bounded run of agent work: a chat turn, a heartbeat pass, a
+ * dream consolidation, or an isolated cron/trigger job. The table gives every
+ * such run an id, a lifecycle, an owner chat, and — where the run can be
+ * aborted — a kill switch. It is the process-table analogue for the agent
+ * runtime, with tokens (not CPU) as the accounted resource.
+ *
+ * Deliberately NOT tasks: trigger watcher scripts (long-lived OS processes
+ * owned by the trigger store, which already tracks their pid/status), cron
+ * "message" jobs (a single send, no agent run), and the pulse ticker.
+ */
+
+/** Which unit of agent work a task represents. */
+export type TaskKind = "turn" | "heartbeat" | "dream" | "cron" | "trigger";
+
+/** Task lifecycle. `done`, `failed`, and `killed` are terminal. */
+export type TaskState = "queued" | "running" | "done" | "failed" | "killed";
+
+/**
+ * Token spend for the run, captured at settlement when the runner reports
+ * it. Chat turns report usage today; isolated one-shots run through
+ * `runOneShotAgent`, which returns no usage, so their tasks settle without.
+ */
+export interface TaskUsage {
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly cacheRead: number;
+  readonly cacheWrite: number;
+}
+
+/** What a call site declares when it registers a run with the table. */
+export interface TaskSpec {
+  readonly kind: TaskKind;
+  /**
+   * Short human label shown in `talon ps`: the turn source ("message",
+   * "trigger", …), the cron job or trigger name, or the heartbeat run
+   * number. Never message content — the listing must not leak chat text.
+   */
+  readonly label: string;
+  /** Chat the work belongs to, when it belongs to one. */
+  readonly chatId?: string;
+  /**
+   * Abort the run mid-flight (typically `AbortController.abort`). Present ⇒
+   * the task is killable via `TaskTable.kill`. Must not throw; the table
+   * swallows a throwing abort so a broken hook cannot break the kill path.
+   */
+  readonly abort?: () => void;
+}
+
+/** The model/backend a task actually resolved to, once known. */
+export interface TaskBinding {
+  readonly model?: string;
+  readonly backendId?: string;
+}
+
+/** Immutable snapshot of one task, as returned by `TaskTable.list()`. */
+export interface TaskRecord {
+  readonly id: number;
+  readonly kind: TaskKind;
+  readonly label: string;
+  readonly chatId?: string;
+  readonly state: TaskState;
+  readonly killable: boolean;
+  /** When the task entered the table (equal to `startedAt` unless queued). */
+  readonly queuedAt: number;
+  readonly startedAt?: number;
+  readonly endedAt?: number;
+  readonly model?: string;
+  readonly backendId?: string;
+  /** Failure detail. Also set for killed tasks (the abort's error). */
+  readonly error?: string;
+  readonly usage?: TaskUsage;
+}
+
+/**
+ * Mutator handed to the owning call site. Every transition is idempotent:
+ * once a task settles, later calls (including a duplicate settle) no-op, so
+ * error paths never need to guard against double settlement.
+ */
+export interface TaskHandle {
+  readonly id: number;
+  /** Move a queued task to running. No-op unless queued. */
+  start(): void;
+  /** Record the model/backend the run resolved to. No-op once settled. */
+  bind(binding: TaskBinding): void;
+  /** Settle as `done`, optionally recording token usage. */
+  succeed(usage?: TaskUsage): void;
+  /** Settle as `failed` — or `killed` when a kill was requested first. */
+  fail(error: unknown): void;
+}
+
+/** Result of `TaskTable.kill`. */
+export type KillOutcome =
+  | { readonly ok: true }
+  | {
+      readonly ok: false;
+      readonly reason: "not-found" | "finished" | "not-killable";
+    };

package/src/core/tools/bridge.ts

@@ -125,14 +125,39 @@ export function createBridge(
 
 /** Wrap a bridge result into the MCP content format. */
 export function textResult(result: unknown): {
-  content: Array<{ type: "text"; text: string }>;
+  content: Array<
+    | { type: "text"; text: string }
+    | { type: "image"; data: string; mimeType: string }
+  >;
   isError?: boolean;
 } {
-  const r = result as { ok?: boolean; text?: string; error?: string };
+  const r = result as {
+    ok?: boolean;
+    text?: string;
+    error?: string;
+    image?: { data?: unknown; mimeType?: unknown };
+  };
+  const content: Array<
+    | { type: "text"; text: string }
+    | { type: "image"; data: string; mimeType: string }
+  > = [{ type: "text" as const, text: r.text ?? JSON.stringify(result) }];
+  // A result may carry an image (e.g. `read` on a photo) — surface it as an
+  // MCP image block so the model actually sees the picture, not base64 text.
+  if (
+    r &&
+    typeof r === "object" &&
+    r.image &&
+    typeof r.image.data === "string" &&
+    typeof r.image.mimeType === "string"
+  ) {
+    content.push({
+      type: "image" as const,
+      data: r.image.data,
+      mimeType: r.image.mimeType,
+    });
+  }
   return {
-    content: [
-      { type: "text" as const, text: r.text ?? JSON.stringify(result) },
-    ],
+    content,
     // Gateway results carry ok:false on failure — mark those as tool errors
     // so the model treats the message as a failure, not a success payload.
     ...(r && typeof r === "object" && r.ok === false ? { isError: true } : {}),

package/src/core/types.ts

@@ -233,6 +233,12 @@ export type ActionResult = {
    * tool calls (react/edit/delete) that target this message.
    */
   message_id?: number | string;
+  /**
+   * Set by tools that return a viewable image (e.g. `read` on a photo). The
+   * MCP layer turns this into an image content block so the model sees the
+   * picture instead of base64 text.
+   */
+  image?: { data: string; mimeType: string };
   [key: string]: unknown;
 };
 

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 { taskTable, type TaskHandle } from "../tasks/index.js";
 import { log, logDebug, logWarn } from "../../util/log.js";
 import { Loom } from "./loom.js";
 import { prefetchMemory } from "./memory-prefetch.js";
@@ -80,7 +81,14 @@ export class Weaver {
 
   runTurn(params: ExecuteParams): Promise<ExecuteResult> {
     const thread = this.loom.thread(params.chatId);
-    return thread.enqueue(() => this.run(thread, params));
+    // Registered before enqueueing so a turn waiting in its chat's FIFO is
+    // visible as `queued` in the task table, not invisible until it runs.
+    const task = taskTable.enqueue({
+      kind: "turn",
+      label: params.source,
+      chatId: params.chatId,
+    });
+    return thread.enqueue(() => this.run(thread, params, task));
   }
 
   /** Number of turns currently running (not queued) across all chats. */
@@ -100,10 +108,22 @@ export class Weaver {
   private async run(
     thread: Thread,
     params: ExecuteParams,
+    task: TaskHandle,
   ): Promise<ExecuteResult> {
     this.activeCount++;
+    task.start();
     try {
-      return await this.executeInner(thread, params);
+      const result = await this.executeInner(thread, params, task);
+      task.succeed({
+        inputTokens: result.inputTokens,
+        outputTokens: result.outputTokens,
+        cacheRead: result.cacheRead,
+        cacheWrite: result.cacheWrite,
+      });
+      return result;
+    } catch (err) {
+      task.fail(err);
+      throw err;
     } finally {
       this.activeCount--;
     }
@@ -112,6 +132,7 @@ export class Weaver {
   private async executeInner(
     thread: Thread,
     params: ExecuteParams,
+    task: TaskHandle,
   ): Promise<ExecuteResult> {
     const { context, onActivity, retrieveMemory } = this.deps;
     const backend = this.deps.getBackend(params.chatId);
@@ -151,6 +172,7 @@ export class Weaver {
       overridden: warp.overridden,
       boundAt: Date.now(),
     });
+    task.bind({ model: warp.ref.id, backendId: warp.backendId });
     if (drifted && previous) {
       logDebug(
         "dispatcher",