talon-agent 5.1.0 → 5.2.0

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

@@ -0,0 +1,82 @@
+/**
+ * Kilo — a remote-server profile.
+ *
+ * Kilo is a fork of OpenCode and exposes the same HTTP API, so the whole
+ * driver is `bindRemoteProfile` over the constants below: the
+ * `@kilocode/sdk` constructors, port 4097, the text-or-tools delivery
+ * contract, the `kilo/`-prefix model parser, and the Discord-sized model
+ * picker budget.
+ *
+ * Kilo delivery model: the reply reaches the user either as a `text`
+ * part (what most Kilo-routed models emit by default — DeepSeek, GLM,
+ * openrouter routes) or through a delivery tool (`end_turn` / `send` /
+ * `react`) when reply-to targeting, buttons, photos, or polls are
+ * needed. Both routes work; the shared text-or-tools contract documents
+ * the choice.
+ *
+ * Note: the model catalog's internal type names are `Remote*` and its
+ * wire shape is OpenCode's — Kilo's provider-bucket API is forked from
+ * it, so the names match what the upstream actually emits.
+ */
+
+import {
+  createKiloClient,
+  createKiloServer,
+  type KiloClient,
+} from "@kilocode/sdk/v2";
+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.
+ *
+ * Kilo model ids frequently contain `/` and `:` inside the model.id itself
+ * (e.g. `inclusionai/ling-2.6-1t:free`, `deepseek/deepseek-v4-flash:free`).
+ * A naive `provider/model` splitter mis-treats those vendor prefixes as
+ * the provider, so we generally return the whole string as the model id
+ * and let `resolveProviderID` look up the real provider from the live
+ * catalog.
+ *
+ * Exception: if the value starts with the literal `kilo/` prefix
+ * (Talon's old hint that "this is a kilo-routed model"), strip it AND
+ * pin providerID to `"kilo"`. Otherwise the upstream Kilo router gets
+ * `kilo/deepseek/deepseek-v4-flash:free` as the model id and concats
+ * its own provider in front, producing
+ * `Model not found: opencode/kilo/deepseek/deepseek-v4-flash:free`.
+ */
+function parseStoredKiloModelSelection(value: string): RemoteModelSelection {
+  const trimmed = value.trim();
+  if (trimmed.startsWith("kilo/")) {
+    return {
+      providerID: "kilo",
+      modelID: trimmed.slice("kilo/".length),
+    };
+  }
+  return {
+    providerID: undefined,
+    modelID: trimmed,
+  };
+}
+
+export const kiloProfile: RemoteProfile<KiloClient> =
+  bindRemoteProfile<KiloClient>({
+    id: "kilo",
+    label: "Kilo",
+    sdkPackage: "@kilocode/sdk",
+    defaultPort: 4097,
+    portEnv: "KILO_PORT",
+    deliveryContract: "text-or-tools",
+    createClient: (baseUrl) =>
+      createKiloClient({ baseUrl, throwOnError: true }),
+    createServer: ({ hostname, port, timeout }) =>
+      createKiloServer({ hostname, port, timeout }),
+    parseModelSelection: parseStoredKiloModelSelection,
+    // Kilo's model picker renders through Discord StringSelectMenus,
+    // which allow 25 options and values up to 100 chars with any
+    // characters — Kilo ids routinely contain "/" and ":" (e.g.
+    // "inclusionai/ling-2.6-1t:free").
+    maxCallbackIdLength: 90,
+    allowCallbackSeparators: true,
+    quickPickLimit: 24,
+  });

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/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/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}`
+  );
+}