talon-agent 5.1.0 → 5.2.1

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

@@ -0,0 +1,225 @@
+/**
+ * Bind one remote-server driver from a profile.
+ *
+ * Everything a member of this family does — spawn or reuse the local
+ * server, register the chat and plugin MCP servers, create sessions,
+ * fetch and render the model catalog, run a chat turn, run a one-shot
+ * turn, read back a session snapshot — is shared code in
+ * `backend/remote-server/`. What differs between OpenCode and its Kilo
+ * fork is a short list of constants and two SDK constructors.
+ *
+ * `bindRemoteProfile` is where that list becomes a driver. It closes the
+ * shared helpers over one profile's state and returns a single object
+ * that is simultaneously:
+ *
+ *   - the {@link RemoteServerBindings} the shared turn paths need,
+ *   - the bound model catalog + `Backend.models` adapter, and
+ *   - a `RemoteBackendFactoryInputs`, ready for
+ *     `createRemoteBackendFactory` in `backend/builtins.ts`.
+ *
+ * Before this module each backend carried a `server.ts`, `sessions.ts`,
+ * `models/index.ts`, `model-provider.ts`, `handler/message.ts`,
+ * `one-shot.ts`, `index.ts` and `factory.ts` whose entire content was
+ * re-exporting these bindings under backend-prefixed names. Those 16
+ * files are the profile objects in `./kilo.ts` and `./opencode.ts` now.
+ */
+
+import type { BackendId } from "../../../core/agent-runtime/model-ref.js";
+import type { OneShotAgentParams, OneShotUsage } from "../../../core/types.js";
+import type {
+  QueryParams,
+  QueryResult,
+} from "../../runtime/turn/handler-types.js";
+import type { DeliveryMode } from "../../runtime/prompt/delivery-contract.js";
+import { runRemoteChatTurn } from "../chat-turn.js";
+import type { RemoteAgentClient } from "../client.js";
+import type { RemoteBackendFactoryInputs } from "../factory.js";
+import {
+  createRemoteModelCatalogModule,
+  createRemoteModelProvider,
+  formatRemoteUnavailableModel,
+  getRemoteModelSelectionValue,
+  resolveRemoteModelInput,
+  type RemoteModelCatalogModule,
+  type RemoteProviderClient,
+} from "../model-catalog/index.js";
+import {
+  runRemoteOneShotAgent,
+  type RemoteOneShotClient,
+} from "../one-shot.js";
+import {
+  bindRemoteServer,
+  type RemoteModelSelection,
+  type RemoteServerBindings,
+} from "../server-bindings.js";
+import {
+  getSessionSnapshot,
+  type RemoteSessionClient,
+} from "../session-helpers.js";
+
+/**
+ * The client shape a profile's SDK must satisfy: the shared helper
+ * surface, the provider catalog, and the session lifecycle the one-shot
+ * runner drives directly. Both `OpencodeClient` and `KiloClient` match
+ * structurally.
+ */
+export type RemoteProfileClient = RemoteAgentClient &
+  RemoteOneShotClient &
+  RemoteProviderClient;
+
+/** Everything that differs between two members of this family. */
+export interface RemoteProfileDefinition<TClient extends RemoteProfileClient> {
+  /** Registry id — matches `config.backend` ("kilo"). */
+  id: BackendId;
+  /** Display label for log lines, headers and error text ("Kilo"). */
+  label: string;
+  /** npm package of the SDK, for the startup log line. */
+  sdkPackage: string;
+  /** Loopback port the local server listens on by default. */
+  defaultPort: number;
+  /**
+   * Env var that overrides the port, so integration tests can spawn an
+   * isolated server alongside a running production Talon that holds the
+   * default.
+   */
+  portEnv: string;
+  /** Delivery contract the system-prompt suffix carries. */
+  deliveryContract: DeliveryMode;
+  /** Strict SDK client over an already-running server URL. */
+  createClient(baseUrl: string): TClient;
+  /** Spawn a fresh local server; `close()` runs from `stop()`. */
+  createServer(args: {
+    hostname: string;
+    port: number;
+    timeout: number;
+  }): Promise<{ url: string; close(): void }>;
+  /**
+   * Split a stored model-selection string into provider/model ids. The
+   * one genuinely behavioural knob: the two upstream routers disagree
+   * about what a `provider/model` prefix means.
+   */
+  parseModelSelection(value: string): RemoteModelSelection;
+  /**
+   * Model-picker budget, set by the surface the picker renders through.
+   * Discord StringSelectMenu values hold 100 chars of anything; Telegram
+   * `callback_data` holds 64 bytes and the keyboard is tight.
+   */
+  maxCallbackIdLength: number;
+  allowCallbackSeparators: boolean;
+  quickPickLimit: number;
+}
+
+/**
+ * A bound driver: the server bindings, the catalog module, and the
+ * registry factory inputs, in one object.
+ */
+export type RemoteProfile<TClient extends RemoteProfileClient> =
+  RemoteServerBindings<TClient> &
+    RemoteBackendFactoryInputs & {
+      /** The bound catalog — cache, resolution, and picker rendering. */
+      catalog: RemoteModelCatalogModule;
+      /**
+       * The knobs this driver was built from. Kept on the result so a
+       * live-backend test can rebind the catalog to its own throwaway
+       * server without restating the profile's picker budget.
+       */
+      definition: RemoteProfileDefinition<TClient>;
+    };
+
+export function bindRemoteProfile<TClient extends RemoteProfileClient>(
+  definition: RemoteProfileDefinition<TClient>,
+): RemoteProfile<TClient> {
+  const { id, label, sdkPackage } = definition;
+
+  const server = bindRemoteServer<TClient>({
+    label,
+    defaultPort: definition.defaultPort,
+    portEnv: definition.portEnv,
+    deliveryContract: definition.deliveryContract,
+    createClient: definition.createClient,
+    createServer: definition.createServer,
+    parseModelSelection: definition.parseModelSelection,
+  });
+
+  const catalog = createRemoteModelCatalogModule({
+    label,
+    getClient: () => server.ensureServer(),
+    maxCallbackIdLength: definition.maxCallbackIdLength,
+    allowCallbackSeparators: definition.allowCallbackSeparators,
+    quickPickLimit: definition.quickPickLimit,
+  });
+  // A stopped server invalidates the catalog it served.
+  server.onServerStop(catalog.clearCache);
+
+  const models = createRemoteModelProvider({
+    label,
+    getCatalog: (forceRefresh) => catalog.getCatalog(forceRefresh),
+    getModelInfo: (modelId) => catalog.getModelInfo(modelId),
+    resolveModelInput: (query, cat) => resolveRemoteModelInput(query, cat),
+    getSelectionValue: (model, cat) => getRemoteModelSelectionValue(model, cat),
+    formatUnavailableModel: (model) => formatRemoteUnavailableModel(model),
+    getSettingsPresentation: (activeModel, pickerOptions) =>
+      catalog.getSettingsPresentation(activeModel, pickerOptions),
+  });
+
+  const handleMessage = (params: QueryParams): Promise<QueryResult> =>
+    runRemoteChatTurn(
+      {
+        id,
+        label,
+        getConfig: server.getConfig,
+        ensureServer: server.ensureServer,
+        trackActiveTurn: server.trackActiveTurn,
+        parseModelSelection: server.parseModelSelection,
+        resolveProviderID: server.resolveProviderID,
+        ensureSession: server.ensureSession,
+        ensureChatMcpServer: server.ensureChatMcpServer,
+        ensurePluginMcpServers: server.ensurePluginMcpServers,
+        buildToolOverrides: server.buildToolOverrides,
+        systemPromptSuffix: server.systemPromptSuffix,
+      },
+      params,
+    );
+
+  const runOneShotAgent = (
+    params: OneShotAgentParams,
+  ): Promise<OneShotUsage | void> =>
+    runRemoteOneShotAgent(
+      {
+        label,
+        // The one-shot runner has no frontend in hand (heartbeat and
+        // dream are cross-surface), so it carries the telegram-shaped
+        // suffix — the same one the per-backend runners passed.
+        systemPromptSuffix: server.defaultSystemPromptSuffix,
+        ensureServer: server.ensureServer,
+        parseModelSelection: server.parseModelSelection,
+        resolveProviderID: server.resolveProviderID,
+        ensureChatMcpServer: server.ensureChatMcpServer,
+        ensurePluginMcpServers: server.ensurePluginMcpServers,
+        buildToolOverrides: server.buildToolOverrides,
+        disconnectChatMcpServer: server.disconnectChatMcpServer,
+        errMsg: server.errMsg,
+      },
+      params,
+    );
+
+  return {
+    ...server,
+    id,
+    label,
+    sdkPackage,
+    definition,
+    catalog,
+    models,
+    handleMessage,
+    runOneShotAgent,
+    async getSessionSnapshot(sessionId) {
+      if (!sessionId) return undefined;
+      const oc = await server.ensureServer();
+      return getSessionSnapshot(
+        oc as unknown as RemoteSessionClient,
+        sessionId,
+      );
+    },
+  };
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Remote-server profiles — the drivers built from `./bind.ts`.
+ *
+ * One import for `backend/builtins.ts`, which is the only place that
+ * lists them (structure rule 4). Adding a member of this family is
+ * adding a profile module here and a line there.
+ */
+
+export { kiloProfile } from "./kilo.js";
+export { opencodeProfile } from "./opencode.js";

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",
+  );
+}