talon-agent 5.1.0 → 5.2.0

package/src/core/mesh/{teleport.ts → devices/teleport.ts}

@@ -13,8 +13,8 @@
 
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
-import { dirs } from "../../util/paths.js";
-import { writePrivateJson } from "./persist.js";
+import { dirs } from "../../../util/paths.js";
+import { writePrivateJson } from "../persist.js";
 
 export type TeleportState = {
   /** Target device id (as registered in the mesh). */

package/src/core/mesh/index.ts

@@ -6,5 +6,9 @@
  * from here.
  */
 
-export { MeshRegistry } from "./registry.js";
-export { MeshService, getMeshService, setMeshService } from "./service.js";
+export { MeshRegistry } from "./devices/registry.js";
+export {
+  MeshService,
+  getMeshService,
+  setMeshService,
+} from "./devices/service.js";

package/src/core/mesh/{bridge-links.ts → links/bridge-links.ts}

@@ -16,7 +16,7 @@ import {
   pairPage,
   type CompanionPairPayload,
 } from "./companion-pairing.js";
-import { formatBytes, type MeshToolResult } from "./common.js";
+import { formatBytes, type MeshToolResult } from "../tool-surface.js";
 import {
   NODE_TARGETS,
   normalizeGoarch,

package/src/core/mesh/{companion-pairing.ts → links/companion-pairing.ts}

@@ -11,7 +11,7 @@
  * So the daemon mints a grant and hands out ONE link. The bridge serves it
  * on a route that must work pre-auth — the phone holds no credential yet, so
  * the grant token IS the authorization, the same trust model as node
- * provisioning (node-provision.ts) and streamed transfers (transfers.ts):
+ * provisioning (node-provision.ts) and streamed transfers (transfers/transfers.ts):
  * random 192-bit, single-use, expiring unused.
  *
  *   GET /pair?grant=<token>              → the pairing page (once)

package/src/core/mesh/{node-binaries.ts → links/node-binaries.ts}

@@ -34,11 +34,11 @@ import {
   writeFile,
 } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { TalonError } from "../errors.js";
-import { getRepoRoot } from "../update/self-update.js";
-import { dirs } from "../../util/paths.js";
-import { talonVersion } from "../../util/version.js";
-import type { DevicePlatform } from "./types.js";
+import { TalonError } from "../../errors.js";
+import { getRepoRoot } from "../../update/self-update.js";
+import { dirs } from "../../../util/paths.js";
+import { talonVersion } from "../../../util/version.js";
+import type { DevicePlatform } from "../types.js";
 
 /** A cross-compile target, named exactly as Go (and the release assets) do. */
 export type NodeTarget = {

package/src/core/mesh/{node-provision.ts → links/node-provision.ts}

@@ -11,7 +11,7 @@
  *
  * The routes must work pre-auth — the whole point is a host that holds no
  * bridge credential yet — so the grant token IS the authorization, exactly
- * like streamed-transfer tokens (transfers.ts): random 192-bit, single-use
+ * like streamed-transfer tokens (transfers/transfers.ts): random 192-bit, single-use
  * per leg, expiring unused. The script carries the bridge bearer token and
  * pinned TLS fingerprint into the node's config, verifies the downloaded
  * binary against the grant's digest (integrity is the script's own sha256

package/src/core/mesh/{common.ts → tool-surface.ts}

@@ -1,6 +1,11 @@
 /**
- * Small helpers shared by the mesh service and its collaborators
- * (device-files.ts, bridge-links.ts).
+ * The mesh's model-facing tool surface — the vocabulary every mesh tool
+ * answers in: the result shape, the timeout a single device filesystem
+ * command runs under, and the formatters those answer texts are written
+ * with.
+ *
+ * All three concerns speak it (devices/service.ts, links/bridge-links.ts,
+ * transfers/device-files.ts), so it sits at the component root.
  */
 
 /** The model-facing shape every mesh tool answers with. */

package/src/core/mesh/{device-files.ts → transfers/device-files.ts}

@@ -21,20 +21,20 @@ import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve } from "node:path";
 import type { Readable } from "node:stream";
-import { dirs } from "../../util/paths.js";
+import { dirs } from "../../../util/paths.js";
 import {
   formatBytes,
   FS_COMMAND_TIMEOUT_MS,
   requirePath,
   type MeshToolResult,
-} from "./common.js";
+} from "../tool-surface.js";
 import {
   normalizeGoarch,
   platformToGoos,
   type NodeBinaryResolver,
-} from "./node-binaries.js";
+} from "../links/node-binaries.js";
 import { TransferStore } from "./transfers.js";
-import type { DeviceCommandResult, DeviceInfo } from "./types.js";
+import type { DeviceCommandResult, DeviceInfo } from "../types.js";
 
 /** The slice of MeshService a transfer needs. */
 export interface DeviceFilesHost {
@@ -531,7 +531,7 @@ export class DeviceFiles {
    *
    * With no binary_path, the replacement is auto-resolved for the node's
    * registered platform/arch (source build in a dev checkout, else the
-   * version-matched release download — see node-binaries.ts).
+   * version-matched release download — see links/node-binaries.ts).
    */
   async updateNodeBinary(
     query: unknown,

package/src/core/prompt/embedded-prompts.ts

@@ -19,24 +19,25 @@ import asset5 from "../../../prompts/identity.md" with { type: "file" };
 import asset6 from "../../../prompts/mem0.md" with { type: "file" };
 import asset7 from "../../../prompts/mempalace.md" with { type: "file" };
 import asset8 from "../../../prompts/native.md" with { type: "file" };
-import asset9 from "../../../prompts/system/contract-text-or-tools.md" with { type: "file" };
-import asset10 from "../../../prompts/system/contract-text-preferred.md" with { type: "file" };
-import asset11 from "../../../prompts/system/contract-tool-only.md" with { type: "file" };
-import asset12 from "../../../prompts/system/cron.md" with { type: "file" };
-import asset13 from "../../../prompts/system/daily-memory.md" with { type: "file" };
-import asset14 from "../../../prompts/system/goals.md" with { type: "file" };
-import asset15 from "../../../prompts/system/heartbeat-agent.md" with { type: "file" };
-import asset16 from "../../../prompts/system/live-state.md" with { type: "file" };
-import asset17 from "../../../prompts/system/memory-core-view.md" with { type: "file" };
-import asset18 from "../../../prompts/system/memory-recall.md" with { type: "file" };
-import asset19 from "../../../prompts/system/persistent-memory.md" with { type: "file" };
-import asset20 from "../../../prompts/system/skills.md" with { type: "file" };
-import asset21 from "../../../prompts/system/triggers.md" with { type: "file" };
-import asset22 from "../../../prompts/system/workspace.md" with { type: "file" };
-import asset23 from "../../../prompts/teams.md" with { type: "file" };
-import asset24 from "../../../prompts/telegram.md" with { type: "file" };
-import asset25 from "../../../prompts/terminal.md" with { type: "file" };
-import asset26 from "../../../prompts/whatsapp.md" with { type: "file" };
+import asset9 from "../../../prompts/system/agent-brief.md" with { type: "file" };
+import asset10 from "../../../prompts/system/contract-text-or-tools.md" with { type: "file" };
+import asset11 from "../../../prompts/system/contract-text-preferred.md" with { type: "file" };
+import asset12 from "../../../prompts/system/contract-tool-only.md" with { type: "file" };
+import asset13 from "../../../prompts/system/cron.md" with { type: "file" };
+import asset14 from "../../../prompts/system/daily-memory.md" with { type: "file" };
+import asset15 from "../../../prompts/system/goals.md" with { type: "file" };
+import asset16 from "../../../prompts/system/heartbeat-agent.md" with { type: "file" };
+import asset17 from "../../../prompts/system/live-state.md" with { type: "file" };
+import asset18 from "../../../prompts/system/memory-core-view.md" with { type: "file" };
+import asset19 from "../../../prompts/system/memory-recall.md" with { type: "file" };
+import asset20 from "../../../prompts/system/persistent-memory.md" with { type: "file" };
+import asset21 from "../../../prompts/system/skills.md" with { type: "file" };
+import asset22 from "../../../prompts/system/triggers.md" with { type: "file" };
+import asset23 from "../../../prompts/system/workspace.md" with { type: "file" };
+import asset24 from "../../../prompts/teams.md" with { type: "file" };
+import asset25 from "../../../prompts/telegram.md" with { type: "file" };
+import asset26 from "../../../prompts/terminal.md" with { type: "file" };
+import asset27 from "../../../prompts/whatsapp.md" with { type: "file" };
 
 /** rel path (posix, under prompts/) → embedded file path (/$bunfs/… when compiled). */
 const ASSETS: Record<string, string> = {
@@ -49,24 +50,25 @@ const ASSETS: Record<string, string> = {
   "mem0.md": asset6,
   "mempalace.md": asset7,
   "native.md": asset8,
-  "system/contract-text-or-tools.md": asset9,
-  "system/contract-text-preferred.md": asset10,
-  "system/contract-tool-only.md": asset11,
-  "system/cron.md": asset12,
-  "system/daily-memory.md": asset13,
-  "system/goals.md": asset14,
-  "system/heartbeat-agent.md": asset15,
-  "system/live-state.md": asset16,
-  "system/memory-core-view.md": asset17,
-  "system/memory-recall.md": asset18,
-  "system/persistent-memory.md": asset19,
-  "system/skills.md": asset20,
-  "system/triggers.md": asset21,
-  "system/workspace.md": asset22,
-  "teams.md": asset23,
-  "telegram.md": asset24,
-  "terminal.md": asset25,
-  "whatsapp.md": asset26,
+  "system/agent-brief.md": asset9,
+  "system/contract-text-or-tools.md": asset10,
+  "system/contract-text-preferred.md": asset11,
+  "system/contract-tool-only.md": asset12,
+  "system/cron.md": asset13,
+  "system/daily-memory.md": asset14,
+  "system/goals.md": asset15,
+  "system/heartbeat-agent.md": asset16,
+  "system/live-state.md": asset17,
+  "system/memory-core-view.md": asset18,
+  "system/memory-recall.md": asset19,
+  "system/persistent-memory.md": asset20,
+  "system/skills.md": asset21,
+  "system/triggers.md": asset22,
+  "system/workspace.md": asset23,
+  "teams.md": asset24,
+  "telegram.md": asset25,
+  "terminal.md": asset26,
+  "whatsapp.md": asset27,
 };
 
 /** Read an embedded prompt by its rel path (e.g. "system/cron.md"). */

package/src/core/tasks/types.ts

@@ -2,7 +2,7 @@
  * 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
+ * dream consolidation, an isolated cron/trigger job, or a sub-agent run. 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.
@@ -13,7 +13,7 @@
  */
 
 /** Which unit of agent work a task represents. */
-type TaskKind = "turn" | "heartbeat" | "dream" | "cron" | "trigger";
+type TaskKind = "turn" | "heartbeat" | "dream" | "cron" | "trigger" | "agent";
 
 /** Task lifecycle. `done`, `failed`, and `killed` are terminal. */
 export type TaskState = "queued" | "running" | "done" | "failed" | "killed";

package/src/core/tools/index.ts

@@ -15,6 +15,7 @@ import { mediaTools } from "./chat/media.js";
 import { stickerTools } from "./chat/stickers.js";
 import { schedulingTools } from "./ops/scheduling.js";
 import { triggerTools } from "./ops/triggers.js";
+import { agentTools } from "./ops/agents.js";
 import { goalTools } from "./ops/goals.js";
 import { memoryTools } from "./content/memory.js";
 import { scriptTools } from "./ops/scripts.js";
@@ -49,6 +50,10 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...crossSendTools,
   ...whatsappTools,
   ...moderationTools,
+  // Appended, not inserted: ALL_TOOLS is serialised into the prompt-cache
+  // prefix, so a new family goes on the end or every live chat re-bills its
+  // system prompt (see compose-tools.test.ts).
+  ...agentTools,
 ];
 
 /**

package/src/core/tools/ops/agents.ts

@@ -0,0 +1,195 @@
+/**
+ * Sub-agent tools — delegate work to isolated agents and talk to them.
+ *
+ * Two halves. The **parent** half (`spawn_agent`, `list_agents`,
+ * `agent_status`, `wait_for_agent`, `send_to_agent`, `kill_agent`) is what a
+ * chat turn — or an agent that is itself delegating — uses. The **agent**
+ * half (`report_result`, `message_parent`, `check_inbox`) only works inside a
+ * sub-agent run; called from a chat it is refused, because there is no parent
+ * to report to.
+ *
+ * Talon owns the mechanism, not the backend: a sub-agent is an isolated
+ * one-shot run, so this works identically on Claude, Codex, Kilo and
+ * OpenCode, and a chat on one backend can spawn an agent on another.
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "../types.js";
+
+const SPAWN_DESCRIPTION = `Delegate a self-contained piece of work to a sub-agent and keep working.
+
+The agent runs isolated: its own backend, model, context window and tool
+surface, no conversation history, only the brief you write. It reports back
+by calling report_result, which wakes this chat with a system message
+carrying its summary — you do NOT have to wait for it.
+
+Write the brief as if to a capable colleague who knows nothing about this
+conversation: the objective, the context they need, what "done" looks like,
+and what to report. Everything they should know must be in the brief.
+
+Good uses: research that would flood this context, a long build/test/verify
+loop, several independent investigations at once, work that should run on a
+different model than this chat.
+
+Bad uses: anything needing a back-and-forth with the user, trivial work you
+could do in one tool call, or work whose result you need in the next second
+(spawning costs a model cold-start).
+
+Backend and model default to this chat's; pass them to put the agent
+somewhere else (e.g. a cheap model for a mechanical sweep, or a backend with
+a bigger context window). Returns the agent id immediately.`;
+
+export const agentTools: ToolDefinition[] = [
+  {
+    name: "spawn_agent",
+    description: SPAWN_DESCRIPTION,
+    schema: {
+      brief: z
+        .string()
+        .min(1)
+        .describe(
+          "The full instructions for the agent. Self-contained: it has no history, only this.",
+        ),
+      label: z
+        .string()
+        .min(1)
+        .max(48)
+        .describe(
+          "Short content-free name for listings and logs (e.g. 'pr-triage', 'docs-audit'). Never message content.",
+        ),
+      backend: z
+        .string()
+        .optional()
+        .describe(
+          "Backend id to run on. Unset = this chat's backend (agents inherit their parent's). Must have a background capability.",
+        ),
+      model: z
+        .string()
+        .optional()
+        .describe(
+          "Model id on the chosen backend. Unset = that backend's default model. Call list_models for valid ids.",
+        ),
+      effort: z
+        .enum(["minimal", "low", "medium", "high", "xhigh"])
+        .optional()
+        .describe(
+          "Reasoning effort, where the backend has that knob (Claude, Codex). Ignored elsewhere.",
+        ),
+      timeout_s: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe(
+          "Hard wall-clock cap in seconds (default 900, min 30, max 3600). On timeout the agent is aborted and you are told.",
+        ),
+    },
+    execute: (params, bridge) => bridge("spawn_agent", params),
+    tag: "agents",
+  },
+
+  {
+    name: "list_agents",
+    description:
+      "List this chat's sub-agents (descendants included) with their state, backend, model, age and whether a result is available.",
+    schema: {},
+    execute: (_params, bridge) => bridge("list_agents", {}),
+    tag: "agents",
+  },
+
+  {
+    name: "agent_status",
+    description:
+      "Full status of one sub-agent: state, backend/model, timings, inbox depth, children, and its result or error once it has settled.",
+    schema: {
+      agent_id: z.string().describe("Agent id returned by spawn_agent"),
+    },
+    execute: (params, bridge) => bridge("agent_status", params),
+    tag: "agents",
+  },
+
+  {
+    name: "wait_for_agent",
+    description:
+      "Block until one agent settles, or until the timeout — whichever comes first. This is a convenience for short waits only: the primary completion channel is the wake-up message the agent's report triggers, which arrives whether or not anyone is waiting. Prefer finishing your turn and letting the report wake you; use this only when the very next thing you do depends on the answer.",
+    schema: {
+      agent_id: z.string().describe("Agent id to wait on"),
+      timeout_s: z
+        .number()
+        .int()
+        .positive()
+        .max(120)
+        .optional()
+        .describe(
+          "Seconds to wait (default 60, max 120). Returns the current state on timeout.",
+        ),
+    },
+    execute: (params, bridge) => bridge("wait_for_agent", params),
+    tag: "agents",
+  },
+
+  {
+    name: "send_to_agent",
+    description:
+      "Put an instruction in a running agent's inbox. The agent sees it the next time it calls check_inbox — this is not an interrupt, so do not expect an immediate change of course.",
+    schema: {
+      agent_id: z.string().describe("Agent id to message"),
+      text: z.string().min(1).describe("The instruction or context to send"),
+    },
+    execute: (params, bridge) => bridge("send_to_agent", params),
+    tag: "agents",
+  },
+
+  {
+    name: "kill_agent",
+    description:
+      "Abort a running agent. It settles as 'killed' and you are still told — with whatever it had reported before it died.",
+    schema: {
+      agent_id: z.string().describe("Agent id to abort"),
+    },
+    execute: (params, bridge) => bridge("kill_agent", params),
+    tag: "agents",
+  },
+
+  // ── Agent-side: only valid inside a sub-agent run ─────────────────────────
+
+  {
+    name: "report_result",
+    description:
+      "Sub-agents only. Report your result to whoever spawned you. Call this exactly once, when you are done — it is the ONLY channel your result reaches your parent through. Reporting a failure with what you tried is a valid result; silence is not. Calling this outside a sub-agent run is an error.",
+    schema: {
+      summary: z
+        .string()
+        .min(1)
+        .describe(
+          "A few sentences your parent can act on: what you found or did.",
+        ),
+      details: z
+        .string()
+        .optional()
+        .describe("Optional evidence: paths, commands, numbers, excerpts."),
+    },
+    execute: (params, bridge) => bridge("report_result", params),
+    tag: "agents",
+  },
+
+  {
+    name: "message_parent",
+    description:
+      "Sub-agents only. Send an interim note to whoever spawned you — a finding worth acting on now, a question, or a heads-up. It wakes them, so use it sparingly. It does not end your run and does not count as your result.",
+    schema: {
+      text: z.string().min(1).describe("The note to send"),
+    },
+    execute: (params, bridge) => bridge("message_parent", params),
+    tag: "agents",
+  },
+
+  {
+    name: "check_inbox",
+    description:
+      "Sub-agents only. Drain any instructions your parent has sent you. Messages are delivered no other way, so check at milestones: after a phase of work, before a long operation, and before you report.",
+    schema: {},
+    execute: (_params, bridge) => bridge("check_inbox", {}),
+    tag: "agents",
+  },
+];

package/src/core/tools/ops/bridge.ts

@@ -20,6 +20,10 @@ const DEFAULT_TIMEOUT_MS = 120_000;
  * engaged, so they inherit transfer-grade budgets too.
  */
 const LONG_ACTION_TIMEOUTS_MS: Record<string, number> = {
+  // `wait_for_agent` blocks for up to its own 120s cap; the bridge budget
+  // must sit above it so the layer that gives up is the tool (which reports
+  // the agent's live state), never the transport.
+  wait_for_agent: 180_000,
   device_pull_file: 3_600_000,
   device_push_file: 3_600_000,
   device_read_file: 3_600_000,

package/src/core/tools/types.ts

@@ -21,6 +21,7 @@ export type ToolTag =
   | "stickers"
   | "scheduling"
   | "triggers"
+  | "agents"
   | "goals"
   | "memory"
   | "scripts"

package/src/core/types.ts

@@ -230,7 +230,7 @@ export type ExecuteParams = {
   isGroup: boolean;
   /** Provider message ID. Numeric for Telegram, string snowflake for Discord. */
   messageId?: number | string;
-  source: "message" | "pulse" | "cron" | "trigger";
+  source: "message" | "pulse" | "cron" | "trigger" | "agent";
   /**
    * Optional per-run model override (a model id valid on the chat's backend).
    * When set and resolvable, the turn runs on this model instead of the chat's

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

@@ -16,7 +16,7 @@ import type { TalonConfig } from "../../../core/config/index.js";
 import { collectPlanUsage } from "../../presentation/plan-usage-report.js";
 import { getLoadedPlugins } from "../../../core/plugin/index.js";
 import { getMeshService } from "../../../core/mesh/index.js";
-import type { MeshPingResult } from "../../../core/mesh/service.js";
+import type { MeshPingResult } from "../../../core/mesh/devices/service.js";
 import { reply } from "./interaction.js";
 
 export async function handleStart(

package/src/frontend/discord/render.ts

@@ -19,7 +19,7 @@ import {
   splitMessage,
 } from "./formatting.js";
 import type { DoctorReport } from "../../core/doctor/index.js";
-import type { MeshPingResult } from "../../core/mesh/service.js";
+import type { MeshPingResult } from "../../core/mesh/devices/service.js";
 import type { BackendUsageEntry } from "../presentation/plan-usage-report.js";
 import {
   renderDoctorReport,

package/src/frontend/native/bridge/routes/mesh.ts

@@ -3,7 +3,7 @@ import type { BridgeRoutes } from "./table.js";
 import type { ServerResponse } from "node:http";
 import { deviceIdParam } from "./params.js";
 
-// Streamed device file transfers (see core/mesh/transfers.ts). The
+// Streamed device file transfers (see core/mesh/transfers/transfers.ts). The
 // one-time `transfer` token authorizes exactly one direction+path; the
 // caller names itself so the token's device binding can be checked.
 function transferToken(

package/src/frontend/native/index.ts

@@ -195,6 +195,8 @@ export function createNativeFrontend(
       });
     },
 
+    // Nothing to run: init() already bound the bridge server, so the
+    // frontend is listening the moment start() is called.
     async start() {
       log(
         "native",

package/src/frontend/presentation/reports.ts

@@ -23,7 +23,7 @@
  */
 
 import type { DoctorReport } from "../../core/doctor/index.js";
-import type { MeshPingResult } from "../../core/mesh/service.js";
+import type { MeshPingResult } from "../../core/mesh/devices/service.js";
 import type { BackendUsageEntry } from "./plan-usage-report.js";
 import {
   DEFAULT_PULSE_INTERVAL_MS,

package/src/frontend/teams/index.ts

@@ -97,10 +97,11 @@ export function createTeamsFrontend(
         `Receive: Graph API chat polling every ${runtime.pollIntervalMs / 1000}s`,
       );
 
+      // The receive side is a timer on the runtime, not a loop to sit in:
+      // once the first poll is done the frontend is listening, and
+      // start() is finished. (It used to park on a promise that never
+      // resolved, which made the boot end at shutdown.)
       await startPolling(runtime, chatId);
-
-      // Hold process open
-      await new Promise(() => {});
     },
 
     async stop() {