talon-agent 3.33.0 → 3.33.2

package/src/backend/kilo/server.ts

@@ -1,19 +1,14 @@
 /**
- * Kilo server lifecycle — thin wrapper around `backend/remote-server/`.
+ * Kilo server lifecycle — the Kilo profile bound through
+ * `backend/remote-server/server-bindings.ts`.
  *
- * The MCP / session / provider plumbing is identical to OpenCode (Kilo
- * is a fork of OpenCode that exposes the same HTTP API), so this module
- * keeps only the Kilo-specific bits:
- *
- *   - Constants (port 4097, system-prompt suffix wording).
- *   - SDK-specific client factory (`createKiloClient` + `createKiloServer`).
- *   - Backend-specific model parser (the `kilo/` prefix hint).
- *   - Pre-warm hook that triggers immediately at init.
- *
- * The shared machinery (server spawn, MCP registration, session creation,
- * provider resolution) lives in `backend/remote-server/`. All the
- * existing exports from this module are preserved for back-compat with
- * the handler / tests / heartbeat code that already imports them.
+ * Kilo is a fork of OpenCode with the same HTTP API, so the server spawn,
+ * MCP registration, session creation, and provider resolution are the
+ * shared family implementation. This module holds only what is Kilo's:
+ * the SDK constructors, port 4097, the text-or-tools delivery contract,
+ * and the `kilo/`-prefix model parser. The exports keep their historical
+ * names — the models module, one-shot runner, tests, and
+ * `vi.mock("../backend/kilo/server.js")` all address them.
  */
 
 import {
@@ -21,243 +16,14 @@ import {
   createKiloServer,
   type KiloClient,
 } from "@kilocode/sdk/v2";
-import type { TalonConfig } from "../../util/config.js";
-import type { FrontendName } from "../../core/agent-runtime/backend-registry.js";
-import { buildDeliveryContract } from "../shared/delivery-contract.js";
-import {
-  guessProviderID,
-  getBucketPriority,
-} from "../remote-server/model-catalog/index.js";
 import {
-  createRemoteServerState,
-  ensureRemoteServer as ensureRemoteServerShared,
-  stopRemoteServer,
-  ensureChatMcpServer as ensureChatMcpServerShared,
-  ensurePluginMcpServers as ensurePluginMcpServersShared,
-  buildToolOverrides as buildToolOverridesShared,
-  disconnectChatMcpServer as disconnectChatMcpServerShared,
-  refreshPluginMcpServers as refreshPluginMcpServersShared,
-  ensureRemoteSession,
-  warmRemoteSession,
-  resolveProviderID as resolveProviderIDShared,
-  getRegisteredMcpServerNames as getRegisteredMcpServerNamesShared,
-  errMsg as sharedErrMsg,
-  type RemoteServerState,
-} from "../remote-server/index.js";
-
-// ── Constants ───────────────────────────────────────────────────────────────
-
-/** Loopback hostname Talon binds the Kilo server on — never exposed externally. */
-const KILO_HOSTNAME = "127.0.0.1";
-/** Default TCP port for the local Kilo server. Overridable via `KILO_PORT`
- *  env var so integration tests can spawn an isolated Kilo server alongside
- *  a running production Talon (which holds the default 4097). */
-const KILO_PORT = Number(process.env.KILO_PORT ?? 4097);
-/** Convenience URL composed from KILO_HOSTNAME + KILO_PORT. */
-export const KILO_BASE_URL = `http://${KILO_HOSTNAME}:${KILO_PORT}`;
-/**
- * System-prompt suffix appended to the user-configured system prompt.
- *
- * Kilo delivery model: the model's reply reaches the user via either
- *
- *   1. A `type: "text"` part — what most Kilo-routed models emit by
- *      default (DeepSeek, GLM, openrouter routes). Talon walks the
- *      `parts` list at end of turn and ships text-part content via
- *      `onTextBlock`. Reasoning parts are dropped as scratchpad.
- *
- *   2. A delivery tool — `end_turn` / `send` / `react`. The tool itself
- *      bridges to Telegram, so it's the right path when you need
- *      reply-to targeting, buttons, photos, polls, etc.
- *
- * Both routes work; pick whichever fits the message. The shared
- * text-or-tools contract (prompts/system/contract-text-or-tools.md)
- * documents the choice — the tool descriptions carry the detail.
- * Telegram-shaped tool names: this constant is static and the prior
- * hand-written text hardcoded the same names.
- */
-export function kiloSystemPromptSuffix(frontend: string): string {
-  return `\n\n${buildDeliveryContract("text-or-tools", frontend)}\n`;
-}
-
-/** Telegram-shaped default, kept for one-shot (cross-surface) paths. */
-export const KILO_SYSTEM_PROMPT_SUFFIX = kiloSystemPromptSuffix("telegram");
-
-// ── State ───────────────────────────────────────────────────────────────────
-
-const state: RemoteServerState<KiloClient> =
-  createRemoteServerState<KiloClient>({
-    label: "Kilo",
-    hostname: KILO_HOSTNAME,
-    port: KILO_PORT,
-  });
-
-function createStrictKiloClient(baseUrl: string): KiloClient {
-  return createKiloClient({
-    baseUrl,
-    throwOnError: true,
-  });
-}
-
-// ── Init / teardown ─────────────────────────────────────────────────────────
-
-/**
- * Initialise the Kilo backend.
- *
- * Stores the config + gateway-port resolver + frontend label needed by
- * downstream helpers. Does NOT spawn the Kilo server — that happens
- * lazily on the first `ensureServer()` call (so empty / heartbeat-only
- * Talon installs don't pay the startup cost until they need it).
- */
-export function initKiloAgent(
-  cfg: TalonConfig,
-  getGatewayPort?: () => number,
-  frontend?: FrontendName,
-): void {
-  state.config = cfg;
-  if (getGatewayPort) state.gatewayPortFn = getGatewayPort;
-  if (frontend) state.frontendName = frontend;
-}
-
-/**
- * Callbacks run when the server stops — cache invalidation lives with the
- * caches. The models module registers its clear here at load time, so the
- * server never has to import it (which would be a cycle).
- */
-const stopHooks = new Set<() => void>();
-
-/** Register a callback to run whenever the Kilo server is stopped. */
-export function onServerStop(hook: () => void): void {
-  stopHooks.add(hook);
-}
-
-/**
- * Stop the local Kilo server (if we own it) and clear caches.
- *
- * Idempotent: safe to call multiple times. If we reused a pre-existing
- * server, this leaves it running — we don't own it.
- */
-export function stopKiloServer(): void {
-  stopRemoteServer(state, () => {
-    for (const hook of stopHooks) hook();
-  });
-}
-
-// ── Server lifecycle ────────────────────────────────────────────────────────
-
-/**
- * Lazily start (or reuse) the local Kilo server and return a strict client.
- *
- * Delegates to the shared `ensureRemoteServer` helper which handles the
- * spawn-race, the reuse-existing-server probe (`/global/health`), and
- * the wrap-after-bind fallback.
- */
-export function ensureServer(): Promise<KiloClient> {
-  return ensureRemoteServerShared({
-    state,
-    createClient: createStrictKiloClient,
-    createServer: ({ hostname, port, timeout }) =>
-      createKiloServer({ hostname, port, timeout }),
-  });
-}
-
-// ── MCP server registration ─────────────────────────────────────────────────
-
-/**
- * Ensure the per-chat Talon MCP server is registered with Kilo. See
- * `backend/remote-server/mcp.ts` for the full rationale + visibility-model
- * explanation; this wrapper just passes the Kilo state through.
- */
-export function ensureChatMcpServer(
-  oc: KiloClient,
-  chatId: string,
-): Promise<string> {
-  return ensureChatMcpServerShared(oc, state, chatId);
-}
-
-/** Register all plugin-provided MCP servers with Kilo. */
-export function ensurePluginMcpServers(
-  oc: KiloClient,
-  chatId: string,
-): Promise<string[]> {
-  return ensurePluginMcpServersShared(oc, state, chatId);
-}
+  bindRemoteServer,
+  type RemoteModelSelection,
+} from "../remote-server/server-bindings.js";
 
 /**
- * Build a `tools` override map that enables ONLY this chat's Talon tools.
- *
- * Kilo's session-level `permission` rules cover *execution* hiding; this
- * `tools` map covers *visibility* — necessary because Kilo exposes every
- * registered MCP server's tools to every session by default.
- */
-export function buildToolOverrides(
-  oc: KiloClient,
-  chatServerName: string,
-  pluginServerNames: readonly string[] = [],
-): Promise<Record<string, boolean> | undefined> {
-  return buildToolOverridesShared(oc, state, chatServerName, pluginServerNames);
-}
-
-/** Disconnect a per-chat MCP server (explicit teardown for hot-swap paths). */
-export function disconnectChatMcpServer(
-  oc: KiloClient,
-  serverName: string,
-): Promise<void> {
-  return disconnectChatMcpServerShared(oc, state, serverName);
-}
-
-export async function refreshPluginMcpServers(chatId: string) {
-  const oc = await ensureServer();
-  return refreshPluginMcpServersShared(oc, state, chatId);
-}
-
-export function updateSystemPrompt(prompt: string): void {
-  if (state.config) state.config.systemPrompt = prompt;
-}
-
-// ── Session management ─────────────────────────────────────────────────────
-
-/**
- * Ensure a Kilo session exists for this chat. Resumes the stored session
- * id if `session.get` confirms it's still alive; otherwise resets and
- * creates a fresh session with Talon's standard permission ruleset.
- */
-export function ensureSession(oc: KiloClient, chatId: string): Promise<string> {
-  return ensureRemoteSession(oc, state, chatId);
-}
-
-/**
- * Front-load a chat's cold start after `/reset`. Mirrors the Claude
- * backend's `warmSession` so the `sessions` capability slot behaves the
- * same across backends. Never throws — see `warmRemoteSession`.
- */
-export function warmSession(chatId: string): Promise<void> {
-  return warmRemoteSession(state, chatId, {
-    ensureServer,
-    ensureSession,
-    ensureChatMcpServer,
-    ensurePluginMcpServers,
-  });
-}
-
-// ── Provider resolution ────────────────────────────────────────────────────
-
-/**
- * Resolve a model id to its provider id by querying Kilo's provider list.
- * The Kilo-specific bucket-priority + name-prefix heuristic comes from
- * `./models.ts`.
- */
-export function resolveProviderID(
-  oc: KiloClient,
-  modelID: string,
-): Promise<string> {
-  return resolveProviderIDShared(oc, state, modelID, {
-    guessProviderID,
-    getBucketPriority,
-  });
-}
-
-/**
- * Parse the stored model-selection string into a `{providerID?, modelID}` pair.
+ * 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`).
@@ -273,10 +39,9 @@ export function resolveProviderID(
  * its own provider in front, producing
  * `Model not found: opencode/kilo/deepseek/deepseek-v4-flash:free`.
  */
-export function parseStoredKiloModelSelection(value: string): {
-  providerID?: string;
-  modelID: string;
-} {
+export function parseStoredKiloModelSelection(
+  value: string,
+): RemoteModelSelection {
   const trimmed = value.trim();
   if (trimmed.startsWith("kilo/")) {
     return {
@@ -290,25 +55,43 @@ export function parseStoredKiloModelSelection(value: string): {
   };
 }
 
-// ── Internal accessors ─────────────────────────────────────────────────────
-
-export function getConfig(): TalonConfig {
-  if (!state.config) {
-    throw new Error("Kilo agent not initialized — call initKiloAgent first");
-  }
-  return state.config;
-}
-
 /**
- * Snapshot of the locally-cached MCP server registrations. Test-only:
- * Kilo's `GET /mcp` returns `{}` regardless of state, so integration
- * tests use this to assert concurrent chat registrations are retained.
+ * 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.
  */
-export function getRegisteredMcpServerNames(): string[] {
-  return getRegisteredMcpServerNamesShared(state);
-}
-
-/** Common error→message helper, re-exported for legacy importers. */
-export const errMsg = sharedErrMsg;
-
-// Re-export the model-helper imports for kilo-internal consumers
+const kilo = bindRemoteServer<KiloClient>({
+  label: "Kilo",
+  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,
+});
+
+export const KILO_BASE_URL = kilo.baseUrl;
+export const kiloSystemPromptSuffix = kilo.systemPromptSuffix;
+export const KILO_SYSTEM_PROMPT_SUFFIX = kilo.defaultSystemPromptSuffix;
+export const initKiloAgent = kilo.init;
+export const stopKiloServer = kilo.stop;
+export const {
+  onServerStop,
+  ensureServer,
+  ensureChatMcpServer,
+  ensurePluginMcpServers,
+  buildToolOverrides,
+  disconnectChatMcpServer,
+  refreshPluginMcpServers,
+  updateSystemPrompt,
+  ensureSession,
+  warmSession,
+  resolveProviderID,
+  getConfig,
+  getRegisteredMcpServerNames,
+  errMsg,
+} = kilo;

package/src/backend/kilo/sessions.ts

@@ -1,14 +1,7 @@
 /**
- * Kilo session helpers — thin wrapper around
- * `backend/remote-server/session-helpers.ts`.
- *
- * Kilo organises a session as an ordered list of `messages`, each with a
- * typed parts array (text / tool / reasoning / step-start / step-finish).
- * The wire format is identical to OpenCode (Kilo is a fork), so the
- * actual parsing, summarisation, snapshot construction, and question-
- * rejection logic lives in the shared module. This file binds the Kilo
- * backend label and re-exports under Kilo-named symbols for back-compat
- * with handler / index imports.
+ * Kilo session helpers — the shared `remote-server/session-helpers.ts`
+ * bound to the Kilo client, re-exported under Kilo-named symbols for the
+ * handler / index / test imports.
  */
 
 import type { KiloClient } from "@kilocode/sdk/v2";
@@ -16,100 +9,29 @@ import {
   extractPartsSummary as extractPartsSummaryShared,
   extractAssistantUsage as extractAssistantUsageShared,
   summarizeAssistantMessages,
-  getTurnSummary,
   getSessionSnapshot,
-  rejectPendingQuestions as rejectPendingQuestionsShared,
-  approvePendingPermissions as approvePendingPermissionsShared,
-  type RemoteAssistantInfo,
   type RemoteSessionSnapshot,
   type RemoteSessionClient,
 } from "../remote-server/session-helpers.js";
 import { ensureServer } from "./server.js";
 
-// ── Constants / type aliases (Kilo-named surface) ──────────────────────────
-
-/** Subset of Kilo's `Message.info` used by Talon for usage accounting. */
-export type KiloAssistantInfo = RemoteAssistantInfo;
-
 /** Snapshot of a Kilo session's lifetime + last-turn assistant info. */
 export type KiloSessionSnapshot = RemoteSessionSnapshot;
 
-// ── Re-exports of pure helpers ─────────────────────────────────────────────
-
 export const extractPartsSummary = extractPartsSummaryShared;
 export const extractAssistantUsage = extractAssistantUsageShared;
 
-/**
- * Summarise a batch of session messages into per-turn usage totals.
- * Re-exported under the Kilo-prefixed name for back-compat with
- * existing imports.
- */
+/** Summarise a batch of session messages into per-turn usage totals. */
 export const summarizeKiloAssistantMessages = summarizeAssistantMessages;
 
-// ── Session-messages aggregators ──────────────────────────────────────────
-
-/**
- * Aggregate the most recent turn's assistant messages into a usage
- * summary. Delegates to the shared helper with a Kilo-typed client.
- */
-export function getKiloTurnSummary(
-  oc: KiloClient,
-  sessionId: string,
-  minCreatedAt: number,
-): Promise<ReturnType<typeof summarizeAssistantMessages>> {
-  return getTurnSummary(
-    oc as unknown as RemoteSessionClient,
-    sessionId,
-    minCreatedAt,
-  );
-}
-
 /**
  * Build a {@link KiloSessionSnapshot} for the given session id.
- *
  * Returns `undefined` if no session id was provided.
  */
 export async function getKiloSessionSnapshot(
   sessionId: string | undefined,
 ): Promise<KiloSessionSnapshot | undefined> {
   if (!sessionId) return undefined;
-  const oc = await ensureServer();
+  const oc: KiloClient = await ensureServer();
   return getSessionSnapshot(oc as unknown as RemoteSessionClient, sessionId);
 }
-
-// ── Pending-question guard ─────────────────────────────────────────────────
-
-/**
- * Auto-respond to pending Kilo questions for this session. Delegates to
- * the shared helper with the Kilo backend label.
- */
-export function rejectPendingQuestions(
-  oc: KiloClient,
-  sessionId: string,
-  chatId: string,
-  seenQuestionIds: Set<string>,
-): Promise<void> {
-  return rejectPendingQuestionsShared(
-    oc as unknown as RemoteSessionClient,
-    sessionId,
-    chatId,
-    seenQuestionIds,
-    "Kilo",
-  );
-}
-
-/** Auto-approve pending Kilo permissions for this headless session. */
-export function approvePendingPermissions(
-  oc: KiloClient,
-  sessionId: string,
-  chatId: string,
-  seenPermissionIds: Set<string>,
-): Promise<void> {
-  return approvePendingPermissionsShared(
-    oc as unknown as RemoteSessionClient,
-    sessionId,
-    chatId,
-    seenPermissionIds,
-    "Kilo",
-  );
-}

package/src/backend/opencode/factory.ts

@@ -1,130 +1,53 @@
 /**
  * OpenCode backend factory — wires OpenCode into the registry.
  *
- * Mirrors the Kilo factory in structure. OpenCode and Kilo share the
- * same protocol shape (Kilo is a fork) so the adapter logic is nearly
- * identical — only the SDK import and a few constant names differ.
- *
- * Returns a composed `Backend` with capability slots for chat,
- * background, models, and usage.
+ * Side-effect import (`import "./factory.js"` from `bootstrap.ts`) calls
+ * `registerBackend(...)` at module load, making OpenCode available under
+ * `config.backend === "opencode"`. The capability wiring is the shared
+ * remote-server composition; only the bound functions are OpenCode's.
  */
 
 import { registerBackend } from "../../core/agent-runtime/backend-registry.js";
-import type { BackendFactory } from "../../core/agent-runtime/backend-registry.js";
-import { log } from "../../util/log.js";
-import { handlerToEvents } from "../shared/handler-to-events.js";
-import { interruptChatTurn } from "../shared/turn-interrupt.js";
-import {
-  composeBackend,
-  type ChatBackend,
-  type BackgroundRunner,
-  type ModelCatalog,
-  type SessionBackend,
-  type SystemControl,
-  type ToolRuntime,
-  type UsageTelemetry,
-} from "../../core/agent-runtime/capabilities.js";
-
+import { createRemoteBackendFactory } from "../remote-server/factory.js";
 import {
   initOpenCodeAgent,
   stopOpenCodeServer,
-  handleMessage as ocHandleMessage,
-  runOneShotAgent as ocRunOneShotAgent,
+  handleMessage,
+  runOneShotAgent,
   getOpenCodeSessionSnapshot,
-  resolveModel as ocResolveModel,
-  getModelInfo as ocGetModelInfo,
-  getSettingsPresentation as ocGetSettingsPresentation,
-  getProviders as ocGetProviders,
-  getProviderModels as ocGetProviderModels,
-  formatModelError as ocFormatModelError,
-  listModels as ocListModels,
-  refreshPluginMcpServers as ocRefreshPluginMcpServers,
-  updateSystemPrompt as ocUpdateSystemPrompt,
-  warmSession as ocWarmSession,
+  resolveModel,
+  getModelInfo,
+  getSettingsPresentation,
+  getProviders,
+  getProviderModels,
+  formatModelError,
+  listModels,
+  refreshPluginMcpServers,
+  updateSystemPrompt,
+  warmSession,
 } from "./index.js";
 
-const opencodeFactory: BackendFactory = {
-  id: "opencode",
-  label: "OpenCode",
-
-  async init(config, ctx) {
-    initOpenCodeAgent(config, ctx.getBridgePort, ctx.frontendName);
-    log("bot", "Backend: OpenCode (@opencode-ai/sdk)");
-
-    const chat: ChatBackend = {
-      runChatTurn: (params) =>
-        handlerToEvents((p) => ocHandleMessage(p), params),
-      interruptChatTurn: (chatId) => interruptChatTurn(chatId),
-    };
-
-    const background: BackgroundRunner = {
-      runOneShotAgent: (p) => ocRunOneShotAgent(p),
-    };
-
-    const models: ModelCatalog = {
-      resolveModelInfo: (q) => ocResolveModel(q),
-      // Catalog-driven backend with no canonical default.
-      getDefaultModelId: () => undefined,
-      getRawModelInfo: (id) => ocGetModelInfo(id),
-      getSettingsPresentation: (m, options) =>
-        ocGetSettingsPresentation(m, options),
-      getProviders: () => ocGetProviders(),
-      getProviderModels: (p, pg, ps) => ocGetProviderModels(p, pg, ps),
-      formatModelError: (q, r) => ocFormatModelError(q, r),
-      listModels: (f) => ocListModels(f),
-    };
-
-    const usage: UsageTelemetry = {
-      getSessionSnapshot: async (sessionId) => {
-        const snap = await getOpenCodeSessionSnapshot(sessionId);
-        if (!snap) return undefined;
-        return {
-          inputTokens: snap.usage?.totalInputTokens,
-          outputTokens: snap.usage?.totalOutputTokens,
-          cacheRead: snap.usage?.totalCacheRead,
-          cacheWrite: snap.usage?.totalCacheWrite,
-          contextModelId: snap.assistant?.modelID,
-        };
-      },
-    };
-
-    const tools: ToolRuntime = {
-      refreshTools: (chatId) => ocRefreshPluginMcpServers(chatId),
-    };
-
-    // Session state lives on the OpenCode server, and `/reset` already
-    // clears Talon's stored id centrally (storage/sessions.ts), so the
-    // next turn creates a fresh one — no `resetChat` needed. `warmSession`
-    // front-loads that creation plus the plugin-MCP sweep, matching what
-    // the Claude backend does after a reset.
-    const sessions: SessionBackend = {
-      warmSession: (chatId) => ocWarmSession(chatId),
-    };
-
-    const control: SystemControl = {
-      updateSystemPrompt: (prompt) => ocUpdateSystemPrompt(prompt),
-    };
-
-    const backend = composeBackend({
-      id: "opencode",
-      label: "OpenCode",
-      cacheMetrics: "readwrite",
-      chat,
-      background,
-      models,
-      sessions,
-      tools,
-      usage,
-      control,
-    });
-
-    return {
-      backend,
-      cleanup: () => {
-        stopOpenCodeServer();
-      },
-    };
-  },
-};
-
-registerBackend(opencodeFactory);
+registerBackend(
+  createRemoteBackendFactory({
+    id: "opencode",
+    label: "OpenCode",
+    sdkPackage: "@opencode-ai/sdk",
+    init: initOpenCodeAgent,
+    stop: stopOpenCodeServer,
+    handleMessage,
+    runOneShotAgent,
+    getSessionSnapshot: getOpenCodeSessionSnapshot,
+    models: {
+      resolveModel,
+      getModelInfo,
+      getSettingsPresentation,
+      getProviders,
+      getProviderModels,
+      formatModelError,
+      listModels,
+    },
+    refreshPluginMcpServers,
+    warmSession,
+    updateSystemPrompt,
+  }),
+);

package/src/backend/opencode/handler/index.ts

@@ -1,12 +1,2 @@
-/**
- * OpenCode message handler.
- *
- * Split by responsibility (parallel to the kilo handler/ layout):
- *   - `state`   — in-flight session registry (activeSessions)
- *   - `turn`    — runOpenCodeTurn + SSE subscription + last-assistant lookup
- *   - `message` — the handleMessage entry point + post-loop accounting
- *
- * Re-exports the same public surface the old single-file module exposed.
- */
-
+/** OpenCode message handler barrel. */
 export { handleMessage } from "./message.js";