talon-agent 3.33.0 → 3.33.2

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

@@ -0,0 +1,232 @@
+/**
+ * Bind one remote-server backend from its profile.
+ *
+ * Kilo is a fork of OpenCode and exposes the same HTTP API, so everything
+ * a backend in this family does — spawn or reuse the local server,
+ * register the chat and plugin MCP servers, create sessions, resolve a
+ * model's provider — is shared code acting on a per-backend
+ * `RemoteServerState`. What actually differs between the two backends is
+ * the handful of fields on `RemoteBackendProfile`: the SDK's client and
+ * server constructors, the loopback port, the delivery contract, and how
+ * a stored model string splits into provider/model ids.
+ *
+ * Before this module each backend carried its own ~300-line `server.ts`
+ * 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.
+ */
+
+import type { TalonConfig } from "../../util/config.js";
+import type { FrontendName } from "../../core/agent-runtime/backend-registry.js";
+import {
+  buildDeliveryContract,
+  type DeliveryMode,
+} from "../shared/delivery-contract.js";
+import type { RemoteAgentClient } from "./client.js";
+import { createRemoteServerState, errMsg } from "./state.js";
+import { ensureRemoteServer, stopRemoteServer } from "./lifecycle.js";
+import {
+  ensureChatMcpServer as ensureChatMcpServerShared,
+  ensurePluginMcpServers as ensurePluginMcpServersShared,
+  buildToolOverrides as buildToolOverridesShared,
+  disconnectChatMcpServer as disconnectChatMcpServerShared,
+  refreshPluginMcpServers as refreshPluginMcpServersShared,
+  getRegisteredMcpServerNames as getRegisteredMcpServerNamesShared,
+} from "./mcp.js";
+import { ensureRemoteSession, warmRemoteSession } from "./sessions.js";
+import { resolveProviderID as resolveProviderIDShared } from "./providers.js";
+import { guessProviderID, getBucketPriority } from "./model-catalog/index.js";
+
+/** Every backend in the family binds to loopback — never exposed externally. */
+const LOOPBACK_HOSTNAME = "127.0.0.1";
+
+/** A stored model value split into the ids the server's prompt API wants. */
+export interface RemoteModelSelection {
+  providerID?: string;
+  modelID: string;
+}
+
+/** The per-backend seams. Everything else in the family is shared. */
+export interface RemoteBackendProfile<TClient extends RemoteAgentClient> {
+  /** Display label for log lines and error text ("Kilo", "OpenCode"). */
+  label: 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. */
+  parseModelSelection(value: string): RemoteModelSelection;
+}
+
+/** The bound backend: the shared helpers closed over this backend's state. */
+export interface RemoteServerBindings<TClient extends RemoteAgentClient> {
+  /** `http://127.0.0.1:<port>` — where the local server is expected. */
+  readonly baseUrl: string;
+  /** Delivery-contract suffix for a given frontend's tool names. */
+  systemPromptSuffix(frontend: string): string;
+  /** Telegram-shaped suffix, kept for one-shot (cross-surface) paths. */
+  readonly defaultSystemPromptSuffix: string;
+  /**
+   * Store the config, gateway-port resolver, and frontend label. Does
+   * NOT spawn the server — that happens lazily on the first
+   * `ensureServer()` so heartbeat-only installs don't pay for it.
+   */
+  init(
+    cfg: TalonConfig,
+    getGatewayPort?: () => number,
+    frontend?: FrontendName,
+  ): void;
+  /**
+   * Register a callback to run whenever the server is stopped. Cache
+   * invalidation lives with the caches: the models module registers its
+   * clear here at load time, so the server never imports it (a cycle).
+   */
+  onServerStop(hook: () => void): void;
+  /**
+   * Stop the local server if we own it and clear caches. Idempotent; a
+   * reused pre-existing server is left running.
+   */
+  stop(): void;
+  /** Lazily start (or reuse) the local server and return a strict client. */
+  ensureServer(): Promise<TClient>;
+  ensureChatMcpServer(oc: TClient, chatId: string): Promise<string>;
+  ensurePluginMcpServers(oc: TClient, chatId: string): Promise<string[]>;
+  /**
+   * A `tools` override map enabling ONLY this chat's Talon tools. Session
+   * permission rules cover execution; this covers visibility, because the
+   * server exposes every registered MCP server's tools to every session.
+   */
+  buildToolOverrides(
+    oc: TClient,
+    chatServerName: string,
+    pluginServerNames?: readonly string[],
+  ): Promise<Record<string, boolean> | undefined>;
+  disconnectChatMcpServer(oc: TClient, serverName: string): Promise<void>;
+  refreshPluginMcpServers(chatId: string): Promise<{
+    added: string[];
+    removed: string[];
+    errors: Record<string, string>;
+  }>;
+  updateSystemPrompt(prompt: string): void;
+  /**
+   * Resume the stored session id if the server confirms it is alive;
+   * otherwise create a fresh one with Talon's standard permission ruleset.
+   */
+  ensureSession(oc: TClient, chatId: string): Promise<string>;
+  /** Front-load a chat's cold start after `/reset`. Never throws. */
+  warmSession(chatId: string): Promise<void>;
+  /** Resolve a model id to its provider id against the live catalog. */
+  resolveProviderID(oc: TClient, modelID: string): Promise<string>;
+  parseModelSelection(value: string): RemoteModelSelection;
+  /** Throws if `init` has not run. */
+  getConfig(): TalonConfig;
+  /**
+   * Locally-cached MCP registrations. Test-only: `GET /mcp` returns `{}`
+   * regardless of state on both servers.
+   */
+  getRegisteredMcpServerNames(): string[];
+  errMsg(e: unknown): string;
+}
+
+export function bindRemoteServer<TClient extends RemoteAgentClient>(
+  profile: RemoteBackendProfile<TClient>,
+): RemoteServerBindings<TClient> {
+  const port = Number(process.env[profile.portEnv] ?? profile.defaultPort);
+  const state = createRemoteServerState<TClient>({
+    label: profile.label,
+    hostname: LOOPBACK_HOSTNAME,
+    port,
+  });
+  const stopHooks = new Set<() => void>();
+
+  const systemPromptSuffix = (frontend: string): string =>
+    `\n\n${buildDeliveryContract(profile.deliveryContract, frontend)}\n`;
+
+  const ensureServer = (): Promise<TClient> =>
+    ensureRemoteServer({
+      state,
+      createClient: profile.createClient,
+      createServer: profile.createServer,
+    });
+  const ensureSession = (oc: TClient, chatId: string): Promise<string> =>
+    ensureRemoteSession(oc, state, chatId);
+  const ensureChatMcpServer = (oc: TClient, chatId: string): Promise<string> =>
+    ensureChatMcpServerShared(oc, state, chatId);
+  const ensurePluginMcpServers = (
+    oc: TClient,
+    chatId: string,
+  ): Promise<string[]> => ensurePluginMcpServersShared(oc, state, chatId);
+
+  return {
+    baseUrl: state.baseUrl,
+    systemPromptSuffix,
+    defaultSystemPromptSuffix: systemPromptSuffix("telegram"),
+    init(cfg, getGatewayPort, frontend) {
+      state.config = cfg;
+      if (getGatewayPort) state.gatewayPortFn = getGatewayPort;
+      if (frontend) state.frontendName = frontend;
+    },
+    onServerStop(hook) {
+      stopHooks.add(hook);
+    },
+    stop() {
+      stopRemoteServer(state, () => {
+        for (const hook of stopHooks) hook();
+      });
+    },
+    ensureServer,
+    ensureChatMcpServer,
+    ensurePluginMcpServers,
+    buildToolOverrides: (oc, chatServerName, pluginServerNames = []) =>
+      buildToolOverridesShared(oc, state, chatServerName, pluginServerNames),
+    disconnectChatMcpServer: (oc, serverName) =>
+      disconnectChatMcpServerShared(oc, state, serverName),
+    refreshPluginMcpServers: async (chatId) =>
+      refreshPluginMcpServersShared(await ensureServer(), state, chatId),
+    updateSystemPrompt(prompt) {
+      if (state.config) state.config.systemPrompt = prompt;
+    },
+    ensureSession,
+    warmSession: (chatId) =>
+      warmRemoteSession(state, chatId, {
+        ensureServer,
+        ensureSession,
+        ensureChatMcpServer,
+        ensurePluginMcpServers,
+      }),
+    resolveProviderID: (oc, modelID) =>
+      resolveProviderIDShared(oc, state, modelID, {
+        guessProviderID,
+        getBucketPriority,
+      }),
+    parseModelSelection: profile.parseModelSelection,
+    getConfig() {
+      if (!state.config) {
+        throw new Error(
+          `${profile.label} agent not initialized — call init${profile.label}Agent first`,
+        );
+      }
+      return state.config;
+    },
+    getRegisteredMcpServerNames: () => getRegisteredMcpServerNamesShared(state),
+    errMsg,
+  };
+}

package/src/backend/{kilo/handler → remote-server}/turn.ts

@@ -1,29 +1,60 @@
 /**
- * Run one Kilo turn over the HTTP API + SSE event stream.
+ * Run one turn over the remote server's HTTP API + SSE event stream.
  *
- * `runKiloTurn` subscribes to SSE before issuing the prompt (so no early
- * events are lost), fires `promptAsync`, awaits the SSE close, then reads the
- * authoritative parts list. `subscribeToTurnEvents` translates relevant SSE
- * events into shared stream-state mutations and observes natural turn idle.
+ * `runRemoteTurn` subscribes to SSE before issuing the prompt (so no early
+ * events are lost), fires `promptAsync`, awaits the SSE close, then reads
+ * the authoritative parts list. `subscribeToTurnEvents` translates the
+ * relevant SSE events into shared stream-state mutations and observes the
+ * turn going idle.
+ *
+ * Kilo and OpenCode share the SSE schema (Kilo is a fork), so this is one
+ * implementation parameterised by the backend label. The two per-backend
+ * copies it replaces had already drifted apart in comments only.
  */
 
-import type { KiloClient } from "@kilocode/sdk/v2";
-import { logWarn } from "../../../util/log.js";
-import { errMsg } from "../server.js";
+import { logWarn } from "../../util/log.js";
+import { createStreamState, recordTokens, sleep } from "../shared/index.js";
+import { processStreamEvent, finalizePartsIntoState } from "./events.js";
+import { findLastAssistantMessage } from "./messages.js";
 import {
   approvePendingPermissions,
   extractAssistantUsage,
+  extractPartsSummary,
   rejectPendingQuestions,
-  type KiloAssistantInfo,
-} from "../sessions.js";
-import { createStreamState, recordTokens, sleep } from "../../shared/index.js";
-import { processStreamEvent, finalizePartsIntoState } from "../events.js";
-import { subscribeSseStream } from "../../remote-server/sse-stream.js";
-import { awaitRemoteTurn } from "../../remote-server/turn-timeout.js";
-import { findLastAssistantMessage as findLastAssistantMessageShared } from "../../remote-server/messages.js";
+  type RemoteAssistantInfo,
+  type RemoteSessionClient,
+} from "./session-helpers.js";
+import {
+  subscribeSseStream,
+  type SseSubscribableClient,
+} from "./sse-stream.js";
+import { errMsg } from "./state.js";
+import { awaitRemoteTurn, type RemoteTurnAbortClient } from "./turn-timeout.js";
 
-export interface RunKiloTurnInputs {
-  oc: KiloClient;
+/**
+ * The slice of the SDK client a turn touches. Both concrete SDK clients
+ * satisfy it structurally; callers holding a typed SDK client cast.
+ */
+export interface RemoteTurnClient
+  extends SseSubscribableClient, RemoteTurnAbortClient {
+  session: RemoteTurnAbortClient["session"] & {
+    promptAsync(args: {
+      sessionID: string;
+      parts: Array<{ type: "text"; text: string }>;
+      model: { providerID: string; modelID: string };
+      system: string;
+      tools?: Record<string, boolean>;
+    }): Promise<unknown>;
+    messages(args: { sessionID: string }): Promise<{ data?: unknown }>;
+  };
+  question: RemoteSessionClient["question"];
+  permission: RemoteSessionClient["permission"];
+}
+
+export interface RunRemoteTurnInputs {
+  /** Backend label for log lines ("Kilo", "OpenCode"). */
+  label: string;
+  oc: RemoteTurnClient;
   sessionId: string;
   prompt: string;
   systemPrompt: string;
@@ -41,21 +72,24 @@ export interface RunKiloTurnInputs {
 }
 
 /**
- * Run one Kilo turn end-to-end.
+ * Run one turn end-to-end.
  *
  * Strategy:
  *   1. Subscribe to SSE BEFORE issuing the prompt so no early events are
  *      lost. The subscription tracks state mutations and resolves when the
  *      turn ends (`session.turn.close` / `session.idle` / `session.error`).
  *   2. Fire the prompt via `session.promptAsync` — returns immediately;
- *      Kilo runs the model task in the background and emits SSE events.
+ *      the server runs the model task in the background and emits SSE.
  *   3. Await the SSE close event — Talon's await is on event iteration we
  *      control, never on a long-running HTTP call we can't interrupt.
  *   4. Read the authoritative parts list via `session.messages` and drain
  *      it through `finalizePartsIntoState`.
  */
-export async function runKiloTurn(inputs: RunKiloTurnInputs): Promise<void> {
+export async function runRemoteTurn(
+  inputs: RunRemoteTurnInputs,
+): Promise<void> {
   const {
+    label,
     oc,
     sessionId,
     prompt,
@@ -72,12 +106,14 @@ export async function runKiloTurn(inputs: RunKiloTurnInputs): Promise<void> {
     onTextBlock,
     onToolUse,
   } = inputs;
+  const sessionClient = oc as unknown as RemoteSessionClient;
 
-  // SSE subscription FIRST — Kilo can fire `session.turn.open` and early
-  // `message.part.updated` events immediately after promptAsync returns,
-  // so the iterator must already be alive.
+  // SSE subscription FIRST — `session.turn.open` and early
+  // `message.part.updated` events can fire immediately after promptAsync
+  // returns, so the iterator must already be alive.
   const sseAbort = new AbortController();
   const sseDone = subscribeToTurnEvents({
+    label,
     oc,
     sessionId,
     state,
@@ -91,13 +127,27 @@ export async function runKiloTurn(inputs: RunKiloTurnInputs): Promise<void> {
 
   // Headless-interaction watchdog: resolve upstream questions and any
   // permission requests that escaped the session ruleset.
+  const settlePending = (): Promise<unknown> =>
+    Promise.all([
+      rejectPendingQuestions(
+        sessionClient,
+        sessionId,
+        chatId,
+        seenQuestionIds,
+        label,
+      ),
+      approvePendingPermissions(
+        sessionClient,
+        sessionId,
+        chatId,
+        seenPermissionIds,
+        label,
+      ),
+    ]);
   const questionWatchdog = (async () => {
     while (!sseAbort.signal.aborted) {
       try {
-        await Promise.all([
-          rejectPendingQuestions(oc, sessionId, chatId, seenQuestionIds),
-          approvePendingPermissions(oc, sessionId, chatId, seenPermissionIds),
-        ]);
+        await settlePending();
       } catch (err) {
         logWarn(
           "agent",
@@ -121,11 +171,9 @@ export async function runKiloTurn(inputs: RunKiloTurnInputs): Promise<void> {
           system: systemPrompt,
           ...(toolOverrides ? { tools: toolOverrides } : {}),
         });
-
-        // Await turn completion via SSE.
         await sseDone;
       })(),
-      { client: oc, sessionId, chatId, label: "Kilo" },
+      { client: oc, sessionId, chatId, label },
     );
 
     // Read authoritative final state from the messages endpoint. The SSE
@@ -135,7 +183,8 @@ export async function runKiloTurn(inputs: RunKiloTurnInputs): Promise<void> {
     const messages = Array.isArray(messagesResp.data)
       ? (messagesResp.data as Array<Record<string, unknown>>)
       : [];
-    const lastAssistant = findLastAssistantMessage(messages);
+    const lastAssistant =
+      findLastAssistantMessage<RemoteAssistantInfo>(messages);
     const parts = lastAssistant?.parts ?? [];
     const assistantInfo = lastAssistant?.info;
 
@@ -143,6 +192,7 @@ export async function runKiloTurn(inputs: RunKiloTurnInputs): Promise<void> {
       parts,
       state,
       seenToolCallIds,
+      extractPartsSummary,
       onToolUse,
     });
 
@@ -171,30 +221,16 @@ export async function runKiloTurn(inputs: RunKiloTurnInputs): Promise<void> {
     await Promise.race([sseDone.catch(() => {}), sleep(1_000)]);
     await questionWatchdog.catch(() => {});
     try {
-      await Promise.all([
-        rejectPendingQuestions(oc, sessionId, chatId, seenQuestionIds),
-        approvePendingPermissions(oc, sessionId, chatId, seenPermissionIds),
-      ]);
+      await settlePending();
     } catch {
       /* noop */
     }
   }
 }
 
-/**
- * Find the most recent assistant message in a session-messages list and
- * surface its parts + assistant info. Kilo's `session.messages` returns the
- * full chronological list; we only care about the last assistant message.
- */
-const findLastAssistantMessage = (
-  messages: Array<Record<string, unknown>>,
-): {
-  parts: Array<Record<string, unknown>>;
-  info?: KiloAssistantInfo;
-} | null => findLastAssistantMessageShared<KiloAssistantInfo>(messages);
-
 interface SubscribeInputs {
-  oc: KiloClient;
+  label: string;
+  oc: RemoteTurnClient;
   sessionId: string;
   state: ReturnType<typeof createStreamState>;
   chatId: string;
@@ -206,13 +242,15 @@ interface SubscribeInputs {
 }
 
 /**
- * Subscribe to Kilo's global SSE event stream and translate relevant events
- * into stream-state mutations / callback firings. Only events scoped to our
- * `sessionId` are processed; others are dropped silently. Errors are logged
- * but do not propagate (the messages endpoint is the source-of-truth fallback).
+ * Subscribe to the server's global SSE event stream and translate relevant
+ * events into stream-state mutations / callback firings. Only events scoped
+ * to our `sessionId` are processed; others are dropped silently. Errors are
+ * logged but do not propagate — the messages endpoint is the source of
+ * truth for the turn result.
  */
 async function subscribeToTurnEvents(inputs: SubscribeInputs): Promise<void> {
   const {
+    label,
     oc,
     sessionId,
     state,
@@ -228,20 +266,18 @@ async function subscribeToTurnEvents(inputs: SubscribeInputs): Promise<void> {
   // subscribe-failed warning. Returns `undefined` for both "subscribe
   // rejected" and "no iterable in the response shape".
   const stream = await subscribeSseStream(oc, chatId);
-  if (!stream) throw new Error("Kilo SSE connection unavailable");
+  if (!stream) throw new Error(`${label} SSE connection unavailable`);
 
   try {
     for await (const evt of stream) {
       if (abortSignal.aborted) break;
       if (!evt || typeof evt !== "object") continue;
 
-      // Kilo's SSE wire format wraps every event in
-      // `{payload: {type, properties}}`. Unwrap here so type/properties
-      // land where the rest of the loop expects them.
+      // The SSE wire format wraps every event in `{payload: {type,
+      // properties}}`. Unwrap here so type/properties land where the rest
+      // of the loop expects them.
       const payload =
-        evt && typeof evt === "object" && "payload" in evt
-          ? (evt as { payload?: unknown }).payload
-          : evt;
+        "payload" in evt ? (evt as { payload?: unknown }).payload : evt;
       if (!payload || typeof payload !== "object") continue;
       const event = payload as {
         type?: string;
@@ -249,9 +285,10 @@ async function subscribeToTurnEvents(inputs: SubscribeInputs): Promise<void> {
       };
 
       // session.error is observed here for logging; everything else goes
-      // through the shared pure helper. Kilo's SSE stream is global, so
+      // through the shared pure helper. The SSE stream is global, so
       // scope-filter to our own sessionId before attributing the error to
-      // this chat.
+      // this chat — a heartbeat session.error would otherwise pollute the
+      // chat's log.
       if (event.type === "session.error") {
         const props = event.properties ?? {};
         const evtSessionID =
@@ -280,14 +317,14 @@ async function subscribeToTurnEvents(inputs: SubscribeInputs): Promise<void> {
           ]
             .filter(Boolean)
             .join(" ");
-          logWarn("agent", `[${chatId}] Kilo session.error: ${detail}`);
+          logWarn("agent", `[${chatId}] ${label} session.error: ${detail}`);
           // Stash the error message so the handler's delivery branch can
-          // surface it as `⚠️ Kilo: <message>` instead of silence.
+          // surface it as `⚠️ <label>: <message>` instead of silence.
           const msg = errProp.message ?? errProp.name;
           if (msg) state.syntheticError = msg;
         }
-        // session.error for OUR session ends the turn — Kilo isn't going
-        // to produce more events for this prompt.
+        // session.error for OUR session ends the turn — the server isn't
+        // going to produce more events for this prompt.
         return;
       }
 
@@ -296,6 +333,7 @@ async function subscribeToTurnEvents(inputs: SubscribeInputs): Promise<void> {
         sessionId,
         state,
         seenToolCallIds,
+        backendLabel: label,
         onStreamDelta,
         onTextBlock,
         onToolUse,
@@ -316,8 +354,6 @@ async function subscribeToTurnEvents(inputs: SubscribeInputs): Promise<void> {
       }
     }
   } catch (err) {
-    // SSE iteration errors are non-fatal — the messages endpoint is the
-    // source of truth for the turn result.
     if (!abortSignal.aborted) {
       logWarn("agent", `[${chatId}] SSE iteration failed: ${errMsg(err)}`);
     }