talon-agent 5.0.1 → 5.2.0

package/src/backend/remote-server/profiles/opencode.ts

@@ -0,0 +1,61 @@
+/**
+ * OpenCode — a remote-server profile.
+ *
+ * The whole driver is `bindRemoteProfile` over the constants below: the
+ * `@opencode-ai/sdk` constructors, port 4096, the text-preferred
+ * delivery contract, the fuzzy `provider/model` parser, and the
+ * Telegram-sized model picker budget.
+ *
+ * Text-preferred delivery: plain assistant text is the reply; tools only
+ * for genuine side effects. Single-sourced from the shared contract
+ * templates (prompts/system/contract-text-preferred.md).
+ */
+
+import {
+  createOpencodeClient,
+  createOpencodeServer,
+  type OpencodeClient,
+} from "@opencode-ai/sdk/v2";
+import {
+  normalizeModelLookup,
+  parseRemoteModelQuery,
+} from "../model-catalog/index.js";
+import type { RemoteModelSelection } from "../server-bindings.js";
+import { bindRemoteProfile, type RemoteProfile } from "./bind.js";
+
+/**
+ * Parse the stored model-selection string into a `{providerID?, modelID}`
+ * pair. The parser is fuzzy — it tries to extract a provider hint from the
+ * prefix while preserving the full model id when ambiguous. See
+ * `remote-server/model-catalog/` for the underlying `parseRemoteModelQuery`.
+ */
+function parseStoredOpenCodeModelSelection(
+  value: string,
+): RemoteModelSelection {
+  const { providerQuery, modelQuery } = parseRemoteModelQuery(value);
+  return {
+    providerID: providerQuery ? normalizeModelLookup(providerQuery) : undefined,
+    modelID: modelQuery,
+  };
+}
+
+export const opencodeProfile: RemoteProfile<OpencodeClient> =
+  bindRemoteProfile<OpencodeClient>({
+    id: "opencode",
+    label: "OpenCode",
+    sdkPackage: "@opencode-ai/sdk",
+    defaultPort: 4096,
+    portEnv: "OPENCODE_PORT",
+    deliveryContract: "text-preferred",
+    createClient: (baseUrl) =>
+      createOpencodeClient({ baseUrl, throwOnError: true }),
+    createServer: ({ hostname, port, timeout }) =>
+      createOpencodeServer({ hostname, port, timeout }),
+    parseModelSelection: parseStoredOpenCodeModelSelection,
+    // OpenCode's model picker renders through Telegram inline keyboards —
+    // callback_data caps at 64 bytes and the keyboard is tight, so quick
+    // picks stay at 4 and only short separator-free ids are embedded raw.
+    maxCallbackIdLength: 48,
+    allowCallbackSeparators: false,
+    quickPickLimit: 4,
+  });

package/src/backend/remote-server/server-bindings.ts

@@ -14,10 +14,9 @@
  * of hand-written pass-through wrappers around the shared helpers. They
  * drifted in the small ways copies do (one documented the port override,
  * the other didn't; one exported `errMsg`, the other aliased it) while
- * doing exactly the same thing. Now a backend's `server.ts` declares its
- * profile and re-exports these bindings under the historical names —
- * the surface the models module, the tests, and
- * `vi.mock("../backend/<name>/server.js")` all address.
+ * doing exactly the same thing. Those wrapper files are gone:
+ * `profiles/bind.ts` calls this once per driver and hands the result
+ * straight to `createRemoteBackendFactory`.
  */
 
 import type { TalonConfig } from "../../core/config/index.js";

package/src/backend/runtime/one-shot-hooks.ts

@@ -0,0 +1,45 @@
+/**
+ * One-shot run hooks — the shared, throw-proof call site for
+ * `OneShotAgentParams.onAssistantText`.
+ *
+ * Every backend's isolated runner (`BackgroundRunner.runOneShotAgent`) already
+ * renders the model's assistant text into the run log as markdown. The hook is
+ * the same text as data, so a caller (the sub-agent runner) can take a run's
+ * result without parsing the log back apart. It lives here rather than in each
+ * backend so all four report it identically: same "final answer only" meaning,
+ * same empty-string skip, same swallow-and-log on a throwing callback.
+ *
+ * Contract:
+ *   - Final assistant text only. Reasoning/thinking blocks and tool-call
+ *     payloads are log-only; they never reach the hook.
+ *   - Synchronous. The runner does not await the consumer, so a hook that
+ *     wants to do async work owns its own queueing.
+ *   - Never throws into the run. A consumer bug must not abort a heartbeat.
+ */
+
+import type { OneShotAgentParams } from "../../core/types.js";
+import { logWarn } from "../../util/log.js";
+
+/**
+ * Report one assistant text segment to the run's optional consumer.
+ *
+ * No-ops when there is no hook (the heartbeat/dream/cron path) or when the
+ * text is empty — the backends guard their log appends the same way, so the
+ * hook sees exactly the segments the log does.
+ */
+export function emitAssistantText(
+  onAssistantText: OneShotAgentParams["onAssistantText"],
+  text: string,
+): void {
+  if (!onAssistantText || !text) return;
+  try {
+    onAssistantText(text);
+  } catch (err) {
+    logWarn(
+      "agent",
+      `one-shot onAssistantText hook threw (ignored): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}

package/src/bootstrap.ts

@@ -33,6 +33,7 @@ import {
   initTriggers,
   resumeAfterRestart as resumeTriggersAfterRestart,
 } from "./core/background/triggers/index.js";
+import { initAgents } from "./core/agents/index.js";
 import { initDream, maybeStartDream } from "./core/background/dream/index.js";
 import { initHeartbeat } from "./core/background/heartbeat/index.js";
 import { log, logWarn, logDebug } from "./util/log.js";
@@ -464,7 +465,7 @@ export async function initBackendAndDispatcher(
       model: config.heartbeatModel ?? config.model ?? null,
     }),
   });
-  initTriggers({ execute: dispatcherExecute });
+  initWakeSubsystems(config);
   resumeTriggersAfterRestart().catch((err) =>
     log("triggers", `resumeAfterRestart failed: ${err}`),
   );
@@ -567,6 +568,19 @@ export async function initBackendAndDispatcher(
   return { backend };
 }
 
+/**
+ * Wire the two subsystems that wake a chat with a synthetic turn: trigger
+ * scripts firing, and sub-agents reporting. Same dependency (the dispatcher),
+ * same delivery shape, so they are wired together.
+ */
+function initWakeSubsystems(config: TalonConfig): void {
+  initTriggers({ execute: dispatcherExecute });
+  initAgents({
+    execute: dispatcherExecute,
+    ...(config.agents ? { caps: config.agents } : {}),
+  });
+}
+
 /**
  * Wire the admin notification seam to the admin's frontend, and start the
  * login-expiry monitor that rides it: the CLIs' "N days to log in again"

package/src/cli/chat.ts

@@ -47,4 +47,9 @@ export async function startChat(): Promise<void> {
     process.exit(0);
   });
   await frontend.start();
+  // start() resolves once the prompt is up (the frontend lifecycle
+  // contract); readline drives the session from its own callbacks after
+  // that, so hold this entry point open until /exit or SIGINT exits the
+  // process.
+  await new Promise<never>(() => {});
 }

package/src/cli/events.ts

@@ -35,6 +35,15 @@ function describe(event: TalonEvent): string {
       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}`;
+    case "agent.spawned":
+      return (
+        `${event.agentId} "${event.label}" ${event.backendId}/${event.model} ` +
+        `depth=${event.depth} parent=${event.parent}`
+      );
+    case "agent.settled":
+      return `${event.agentId} "${event.label}" → ${event.state} (${event.durationMs}ms)`;
+    case "agent.message":
+      return `${event.from} → ${event.to} (${event.kind})`;
   }
 }
 

package/src/core/agent-runtime/agent-host.ts

@@ -31,9 +31,10 @@
  * They are deliberately not the same types. Two client arguments do not
  * survive a process boundary and the wire shapes say so:
  *
- *   - `OneShotAgentParams` carries an `AbortController` and an
- *     `appendLog` callback. `HostOneShotParams` is the serialisable
- *     subset; Phase 2 maps `appendLog` onto `log` notices and the
+ *   - `OneShotAgentParams` carries an `AbortController` and two
+ *     callbacks (`appendLog`, `onAssistantText`). `HostOneShotParams`
+ *     is the serialisable subset; Phase 2 maps `appendLog` onto `log`
+ *     notices, `onAssistantText` onto a notice of its own, and the
  *     abort onto an `interrupt`-shaped request.
  *   - `hello.config` is the `claude-sdk` slice of `TalonConfig` as
  *     JSON. The in-process client takes the real `TalonConfig` object.
@@ -59,9 +60,9 @@ export const AGENT_HOST_PROTOCOL_VERSION = 1;
 // ── Shared payload shapes ───────────────────────────────────────────────────
 
 /**
- * The serialisable half of `OneShotAgentParams`. `abortController` and
- * `appendLog` are host-local concerns (see the file header); everything
- * else is exactly what a background run needs.
+ * The serialisable half of `OneShotAgentParams`. `abortController`,
+ * `appendLog` and `onAssistantText` are host-local concerns (see the file
+ * header); everything else is exactly what a background run needs.
  *
  * Unexported on purpose — it is reachable as
  * `Extract<HostRequest, { type: "one_shot" }>["params"]`, and a second

package/src/core/agent-runtime/capabilities.ts

@@ -103,6 +103,9 @@ export interface ChatBackend {
  *     trigger log-file producers keep their direct write path.
  *     Resolves with the run's token usage when the SDK reports it
  *     (the task table records it at settlement); void otherwise.
+ *     Implementations must also honour the optional `onAssistantText`
+ *     hook — the run's final answers as data, for callers (the
+ *     sub-agent runner) that need a result rather than a markdown log.
  *   - `evictOrphanSubprocesses(label)` — backends that spawn
  *     per-run subprocesses (Claude SDK) implement this so a hung
  *     run can be force-cleaned after the abort grace window.

package/src/core/agents/context.ts

@@ -0,0 +1,48 @@
+/**
+ * Sub-agent context vocabulary — the one place that knows what an
+ * `agent:<id>` context label looks like.
+ *
+ * A one-shot run carries a `contextLabel` (`OneShotAgentParams`) that every
+ * layer downstream keys on: the backend picks the MCP server set from it, the
+ * MCP hub binds a tool session to it, and the bridge sends it back to the
+ * gateway as `_chatId`. A sub-agent's label is `agent:<id>`, which is how the
+ * gateway recognises a tool call as coming from that agent rather than from a
+ * chat.
+ *
+ * Deliberately a dependency-free leaf: `backend/claude-sdk` and
+ * `core/engine/gateway` both import it, and routing either through
+ * `core/agents/index.ts` (which pulls in the runner, and with it the backend
+ * pool) would close an import cycle.
+ */
+
+/** Prefix of every sub-agent context label / chat key. */
+export const AGENT_CONTEXT_PREFIX = "agent:";
+
+/** The context label a sub-agent's one-shot run (and its tools) is bound to. */
+export function agentContextLabel(agentId: string): string {
+  return `${AGENT_CONTEXT_PREFIX}${agentId}`;
+}
+
+/** The agent id inside a context label, or null when it isn't one. */
+export function agentIdFromContextLabel(label: string): string | null {
+  if (!label.startsWith(AGENT_CONTEXT_PREFIX)) return null;
+  const id = label.slice(AGENT_CONTEXT_PREFIX.length);
+  return id.length > 0 ? id : null;
+}
+
+/**
+ * Whether a context label denotes a background run that gets the full
+ * cross-surface tool set: frontend tools (outbound with an explicit
+ * `chat_id`) plus every loaded plugin.
+ *
+ * Two labels qualify: `heartbeat` (also reused by isolated cron/trigger jobs,
+ * see `background/cron/job-prompt.ts`) and any `agent:<id>` sub-agent run.
+ * `dream` deliberately does not — it is a memory-consolidation pass with no
+ * business messaging anyone.
+ */
+export function isBackgroundToolContext(contextLabel: string): boolean {
+  return (
+    contextLabel === "heartbeat" ||
+    agentIdFromContextLabel(contextLabel) !== null
+  );
+}

package/src/core/agents/delivery.ts

@@ -0,0 +1,167 @@
+/**
+ * Delivery — moving text between a sub-agent and its parent, both ways.
+ *
+ * Downward (`deliverToAgent`) is a mailbox push the agent drains at its own
+ * milestones. Upward — a report or an interim note — has two parents, two
+ * channels, one shape:
+ *
+ *   - **A chat** is woken with a synthetic turn (`source: "agent"`), exactly
+ *     as a trigger fires one. The turn resumes the chat's own session, so
+ *     the model reads the report with full conversational context and
+ *     decides for itself whether the user hears about it.
+ *   - **An agent** gets the text pushed into its mailbox, which it drains
+ *     with `check_inbox`. A parent that has already settled has nowhere to
+ *     put it: the message is logged and dropped, because reviving a
+ *     finished run to hear late news is worse than losing the news.
+ *
+ * No batching: several settlements arriving while a chat is busy become
+ * several queued turns, and the weaver serialises per chat. That is the
+ * behaviour triggers already have, and the model handles it fine.
+ */
+
+import type { execute as dispatcherExecute } from "../engine/dispatcher.js";
+import { log, logWarn, logError } from "../../util/log.js";
+import { bus } from "../bus/index.js";
+import { agentRegistry } from "./registry.js";
+import { buildMessagePrompt, buildSettlementPrompt } from "./prompt.js";
+import type { AgentMessage, AgentParent, AgentRecord } from "./types.js";
+
+/** Injected at startup so this module knows nothing about the dispatcher. */
+export type AgentDeliveryDeps = {
+  /** Wakes a chat with a synthetic turn. */
+  execute: typeof dispatcherExecute;
+};
+
+/** Reassignable holder so a re-init (or a test) can swap the deps. */
+const deliveryDeps: { deps: AgentDeliveryDeps | null } = { deps: null };
+
+/** Wire the delivery path. Called once from the composition root. */
+export function initAgentDelivery(deps: AgentDeliveryDeps): void {
+  deliveryDeps.deps = deps;
+}
+
+/** Sender/recipient key of a parent, for the `agent.message` event. */
+function parentKey(parent: AgentParent): string {
+  return parent.kind === "chat" ? parent.chatId : parent.agentId;
+}
+
+/** Wake a chat with a synthetic agent turn. */
+async function wakeChat(
+  chatId: string,
+  numericChatId: number,
+  prompt: string,
+): Promise<void> {
+  const deps = deliveryDeps.deps;
+  if (!deps) {
+    logWarn(
+      "agents",
+      `delivery not initialised — dropped a report for ${chatId}`,
+    );
+    return;
+  }
+  try {
+    await deps.execute({
+      chatId,
+      numericChatId,
+      prompt,
+      senderName: "Agent",
+      isGroup: false,
+      source: "agent",
+    });
+  } catch (err) {
+    logError("agents", `wake dispatch failed for chat ${chatId}`, err);
+  }
+}
+
+/** Push into a live agent's mailbox, or say why it could not be delivered. */
+function pushToAgent(
+  parentAgentId: string,
+  message: AgentMessage,
+  what: string,
+): void {
+  if (!agentRegistry.isLive(parentAgentId)) {
+    logWarn(
+      "agents",
+      `dropped ${what} from ${message.from}: parent ${parentAgentId} has already settled`,
+    );
+    return;
+  }
+  if (!agentRegistry.push(parentAgentId, message)) {
+    logWarn(
+      "agents",
+      `dropped ${what} from ${message.from}: parent ${parentAgentId}'s inbox is full`,
+    );
+  }
+}
+
+/**
+ * Send an instruction down to a live agent. Returns false when the agent is
+ * gone or its mailbox is full — the caller turns that into a tool error, so
+ * a parent always learns that its instruction did not land.
+ */
+export function deliverToAgent(
+  from: string,
+  agentId: string,
+  text: string,
+): boolean {
+  if (!agentRegistry.isLive(agentId)) return false;
+  if (!agentRegistry.push(agentId, { from, text, at: Date.now() }))
+    return false;
+  bus.publish({
+    type: "agent.message",
+    from,
+    to: agentId,
+    kind: "message",
+  });
+  return true;
+}
+
+/** Deliver a settled agent's report to its parent. */
+export async function deliverSettlement(record: AgentRecord): Promise<void> {
+  const prompt = buildSettlementPrompt(record);
+  bus.publish({
+    type: "agent.message",
+    from: record.id,
+    to: parentKey(record.parent),
+    kind: "result",
+  });
+  if (record.parent.kind === "chat") {
+    log(
+      "agents",
+      `${record.id} "${record.label}" ${record.state} — waking chat ${record.parent.chatId}`,
+    );
+    await wakeChat(record.parent.chatId, record.parent.numericChatId, prompt);
+    return;
+  }
+  pushToAgent(
+    record.parent.agentId,
+    { from: record.id, text: prompt, at: Date.now() },
+    "a report",
+  );
+}
+
+/** Deliver an interim `message_parent` note. */
+export async function deliverMessage(
+  record: AgentRecord,
+  text: string,
+): Promise<void> {
+  bus.publish({
+    type: "agent.message",
+    from: record.id,
+    to: parentKey(record.parent),
+    kind: "message",
+  });
+  if (record.parent.kind === "chat") {
+    await wakeChat(
+      record.parent.chatId,
+      record.parent.numericChatId,
+      buildMessagePrompt(record, text),
+    );
+    return;
+  }
+  pushToAgent(
+    record.parent.agentId,
+    { from: record.id, text: buildMessagePrompt(record, text), at: Date.now() },
+    "a message",
+  );
+}

package/src/core/agents/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Sub-agents — the public surface.
+ *
+ * Talon's own delegation mechanism: any chat turn, on any backend, can spawn
+ * an isolated agent with its own backend and model, talk to it while it runs,
+ * and be woken with its report. See `docs/agents.md` for the model and
+ * `registry` / `runner` / `delivery` for the three moving parts.
+ *
+ * Wiring points: `initAgents` at the composition root (bootstrap),
+ * `shutdownAgents` on daemon teardown (app), the `agents` tool family
+ * (`core/tools/ops/agents.ts`) through `core/engine/gateway-actions/agents/`,
+ * and `GET /agents` on the gateway.
+ *
+ * `context.ts` is imported directly by `backend/claude-sdk` and the gateway:
+ * it is a dependency-free leaf on purpose, so knowing what an `agent:<id>`
+ * label looks like never drags the runner (and the backend pool) along.
+ */
+
+export { agentContextLabel, agentIdFromContextLabel } from "./context.js";
+export { AgentRegistry, agentRegistry } from "./registry.js";
+export {
+  DEFAULT_AGENT_CAPS,
+  clampTimeout,
+  getAgentCaps,
+  initAgents,
+  killAgent,
+  shutdownAgents,
+  spawnAgent,
+} from "./runner.js";
+export {
+  deliverMessage,
+  deliverSettlement,
+  deliverToAgent,
+  initAgentDelivery,
+} from "./delivery.js";
+export { describeParent } from "./prompt.js";
+export type { AgentCaps, AgentParent, AgentRecord } from "./types.js";

package/src/core/agents/prompt.ts

@@ -0,0 +1,116 @@
+/**
+ * Pure helpers for a sub-agent run — its system prompt, its activation
+ * prompt, its log path and the prompt headers its parent sees.
+ *
+ * Kept free of side effects (no fs, no backend, no registry) so the wording
+ * every other subsystem asserts on is trivially unit-testable, and so the
+ * runner stays about lifecycle.
+ */
+
+import { resolve } from "node:path";
+import { dirs } from "../../util/paths.js";
+import { loadSystemTemplate } from "../prompt/templates.js";
+import type { AgentParent, AgentRecord } from "./types.js";
+
+/** Where sub-agent run logs live: `~/.talon/workspace/logs/agents/`. */
+const AGENT_LOGS_DIR = resolve(dirs.logs, "agents");
+
+/** Absolute path of one agent's run log. */
+export function agentLogPath(agentId: string): string {
+  return resolve(AGENT_LOGS_DIR, `${agentId}.md`);
+}
+
+/** How a parent is named to its child and in wake prompts. */
+export function describeParent(parent: AgentParent): string {
+  return parent.kind === "chat"
+    ? `chat ${parent.chatId}`
+    : `sub-agent ${parent.agentId}`;
+}
+
+/**
+ * The agent's system prompt: who it is, how to report, how to talk to its
+ * parent, and what it may not do. The brief itself is the *user* prompt —
+ * same split as the isolated cron/trigger jobs, so the framing half stays
+ * identical (and cacheable) across every run.
+ */
+export function buildAgentSystemPrompt(args: {
+  agentId: string;
+  label: string;
+  parent: AgentParent;
+  depth: number;
+  maxDepth: number;
+}): string {
+  return loadSystemTemplate("agent-brief", {
+    agentId: args.agentId,
+    label: args.label,
+    parent: describeParent(args.parent),
+    depth: String(args.depth),
+    maxDepth: String(args.maxDepth),
+    canSpawn: args.depth < args.maxDepth ? "yes" : "",
+  });
+}
+
+/** The activation prompt — the brief, framed as the job to start on. */
+export function buildAgentPrompt(brief: string): string {
+  return (
+    `[System: AGENT BRIEF. Work this to a conclusion, then call ` +
+    `report_result exactly once.]\n\n${brief}`
+  );
+}
+
+/** Header line of a run log. */
+export function agentLogHeader(record: AgentRecord, model: string): string {
+  return (
+    `# sub-agent ${record.id} "${record.label}" — ${new Date().toISOString()}\n` +
+    `**Parent:** ${describeParent(record.parent)} ` +
+    `**Backend:** ${record.backendId} **Model:** ${model} ` +
+    `**Depth:** ${record.depth}\n\n` +
+    `## Brief\n\n${record.brief}\n\n`
+  );
+}
+
+/** One-line token summary for the report a parent chat is woken with. */
+function usageLine(record: AgentRecord): string {
+  const usage = record.usage;
+  if (!usage) return "";
+  return (
+    `\n\nTokens: in=${usage.inputTokens} out=${usage.outputTokens} ` +
+    `cache_read=${usage.cacheRead} cache_write=${usage.cacheWrite}`
+  );
+}
+
+/**
+ * The wake prompt a parent chat receives when one of its agents settles.
+ * Shaped like the trigger wake-up: a `[System: …]` header telling the model
+ * what this is and that it must decide what to do, then the payload.
+ */
+export function buildSettlementPrompt(record: AgentRecord): string {
+  const body = record.result
+    ? record.result.details
+      ? `${record.result.summary}\n\n${record.result.details}`
+      : record.result.summary
+    : (record.error ?? "(the agent produced no result)");
+  const duration = record.endedAt
+    ? Math.round(
+        (record.endedAt - (record.startedAt ?? record.createdAt)) / 1000,
+      )
+    : 0;
+  return (
+    `[System: AGENT FINISHED. Sub-agent ${record.id} "${record.label}" ` +
+    `ended as "${record.state}" after ${duration}s. This is the report from ` +
+    `an agent you spawned earlier. Decide whether to act on it, tell the ` +
+    `user, or do nothing.]\n\n` +
+    `[Agent "${record.label}" (${record.id}) — ${record.state}]\n\n` +
+    `${body}${usageLine(record)}`
+  );
+}
+
+/** The wake prompt for an interim `message_parent` note. */
+export function buildMessagePrompt(record: AgentRecord, text: string): string {
+  return (
+    `[System: AGENT MESSAGE from ${record.id} "${record.label}". ` +
+    `This is an interim note from an agent you spawned; it is still ` +
+    `running. Decide whether to act, reply with send_to_agent, or do ` +
+    `nothing.]\n\n${text}`
+  );
+}