talon-agent 5.0.1 → 5.2.0

package/src/backend/claude-sdk/one-shot.ts

@@ -19,7 +19,9 @@ import { log, logWarn } from "../../util/log.js";
 import { ALLOWED_TOOLS_BACKGROUND } from "../../core/constants.js";
 import { EFFORT_MAP } from "./constants.js";
 import { buildMcpServers, buildPluginMcpServers } from "./options.js";
+import { isBackgroundToolContext } from "../../core/agents/context.js";
 import { warnIfBelowCacheMinimum } from "../runtime/cache/cache-telemetry.js";
+import { emitAssistantText } from "../runtime/one-shot-hooks.js";
 
 const DEFAULT_SUBPROCESS_KILL_GRACE_MS = 5 * 1000;
 
@@ -65,6 +67,7 @@ export async function runOneShotAgent(
     contextLabel,
     abortController,
     appendLog,
+    onAssistantText,
   } = params;
 
   // Reasoning effort is opt-in for background runs (config `heartbeatEffort`
@@ -126,7 +129,7 @@ export async function runOneShotAgent(
   // settlement figure the task table records.
   let usage: OneShotUsage | undefined;
   for await (const msg of qi) {
-    await formatAndAppendMessage(appendLog, msg);
+    await formatAndAppendMessage(appendLog, msg, onAssistantText);
     if (msg.type === "result") {
       const u = msg.usage;
       usage = {
@@ -142,8 +145,12 @@ export async function runOneShotAgent(
 
 /**
  * Per-context MCP server selection.
- * - "heartbeat": frontend tools + all loaded plugins (full surface so the
- *   heartbeat agent can post messages, react, read history, etc.).
+ * - background tool contexts (`heartbeat`, and every `agent:<id>` sub-agent
+ *   run — see `core/agents/context.ts`): frontend tools + all loaded plugins,
+ *   the full surface these runs need to post messages, react, read history
+ *   and reach their own agent tools. The servers are keyed by the context
+ *   label itself, so each sub-agent gets its own hub session and its tool
+ *   calls arrive at the gateway identified as that agent.
  * - "dream": only mempalace (when configured) — dream is a memory
  *   consolidation pass and shouldn't be doing outbound messaging.
  * - anything else: empty (treat unknown contexts as plugin-free).
@@ -154,16 +161,19 @@ export async function runOneShotAgent(
  * servers still load and the agent runs normally.
  */
 function assembleMcpServers(contextLabel: string): Record<string, unknown> {
-  if (contextLabel === "heartbeat") {
+  if (isBackgroundToolContext(contextLabel)) {
     let frontendServers: Record<string, unknown> = {};
     try {
-      frontendServers = buildMcpServers("heartbeat") as Record<string, unknown>;
+      frontendServers = buildMcpServers(contextLabel) as Record<
+        string,
+        unknown
+      >;
     } catch {
       frontendServers = {};
     }
     let pluginServers: Record<string, unknown> = {};
     try {
-      pluginServers = buildPluginMcpServers("heartbeat");
+      pluginServers = buildPluginMcpServers(contextLabel);
     } catch {
       pluginServers = {};
     }
@@ -183,6 +193,7 @@ function assembleMcpServers(contextLabel: string): Record<string, unknown> {
 async function formatAndAppendMessage(
   appendLog: (text: string) => Promise<void>,
   msg: SDKMessage,
+  onAssistantText?: OneShotAgentParams["onAssistantText"],
 ): Promise<void> {
   try {
     const ts = new Date().toISOString().slice(11, 19);
@@ -200,7 +211,11 @@ async function formatAndAppendMessage(
           });
 
         if (textBlocks.length > 0) {
-          await appendLog(`\n## [${ts}] Assistant\n${textBlocks.join("\n")}\n`);
+          const assistantText = textBlocks.join("\n");
+          // Report before the log write: an append failure (full disk, closed
+          // handle) must not also swallow the run's result for a hook caller.
+          emitAssistantText(onAssistantText, assistantText);
+          await appendLog(`\n## [${ts}] Assistant\n${assistantText}\n`);
         }
         if (toolUseBlocks.length > 0) {
           await appendLog(`\n${toolUseBlocks.join("\n\n")}\n`);
@@ -208,6 +223,14 @@ async function formatAndAppendMessage(
         break;
       }
       case "result": {
+        // Deliberately NOT reported through `onAssistantText`. The SDK's
+        // terminal `result` message restates the last assistant turn's text
+        // (`subtype: "success"`) or carries an error string (the
+        // `error_*` subtypes) — never anything the `assistant` case above
+        // has not already emitted. Reporting it too would hand every hook
+        // caller a duplicate final segment, and the truncated copy at that
+        // (2000 chars, below). The log keeps it because a run log wants the
+        // settlement line; a sub-agent result does not.
         const result =
           "result" in msg
             ? (msg as { result: string }).result

package/src/backend/claude-sdk/stream.ts

@@ -422,6 +422,15 @@ function readResultError(msg: SDKResultMessage, state: StreamState): void {
       .filter((e) => typeof e === "string" && !e.startsWith("[ede_diagnostic]"))
       .join("; ")
       .slice(0, 500);
+    // A known startup failure (SDK ≥ 0.3.274) names its cause — the CLI
+    // never ran a turn, so nothing else in the result says why. Lead with
+    // it; the diagnostics text is the same line stderr carried.
+    if (msg.startup_failure_reason) {
+      state.resultErrorText =
+        `Claude Code failed to start (${msg.startup_failure_reason})` +
+        (diagnostics ? `: ${diagnostics}` : "");
+      return;
+    }
     state.resultErrorText =
       state.lastTrailingText.trim() ||
       diagnostics ||

package/src/backend/codex/one-shot.ts

@@ -20,6 +20,7 @@
 import type { OneShotAgentParams, OneShotUsage } from "../../core/types.js";
 import { log, logWarn } from "../../util/log.js";
 import { appendBackendSuffix } from "../runtime/index.js";
+import { emitAssistantText } from "../runtime/one-shot-hooks.js";
 import { ensureCodex, getCodexAuthInfo } from "./init.js";
 import {
   CODEX_SYSTEM_PROMPT_SUFFIX,
@@ -79,6 +80,7 @@ export async function runOneShotAgent(
     contextLabel,
     abortController,
     appendLog,
+    onAssistantText,
   } = params;
 
   const codex = ensureCodex(contextLabel);
@@ -143,7 +145,7 @@ export async function runOneShotAgent(
     let usage: OneShotUsage | undefined;
     for await (const event of events) {
       if (abortController.signal.aborted) break;
-      await appendCodexEvent(appendLog, event);
+      await appendCodexEvent(appendLog, event, onAssistantText);
       if (event.type === "turn.completed") {
         const u = (event as { usage?: Record<string, number> }).usage;
         if (u) {
@@ -217,6 +219,7 @@ export async function runOneShotAgent(
 async function appendCodexEvent(
   appendLog: (text: string) => Promise<void>,
   event: { type: string } & Record<string, unknown>,
+  onAssistantText?: OneShotAgentParams["onAssistantText"],
 ): Promise<void> {
   const ts = new Date().toISOString().slice(11, 19);
 
@@ -260,7 +263,7 @@ async function appendCodexEvent(
     case "item.completed": {
       const item = (event as unknown as { item?: Record<string, unknown> })
         .item;
-      if (item) await appendCodexItem(appendLog, item, ts);
+      if (item) await appendCodexItem(appendLog, item, ts, onAssistantText);
       return;
     }
     default:
@@ -268,17 +271,28 @@ async function appendCodexEvent(
   }
 }
 
-/** Append one `ThreadItem` to the run log. */
+/**
+ * Append one `ThreadItem` to the run log, and report the model's final
+ * answers to the run's optional `onAssistantText` consumer.
+ *
+ * Only `agent_message` items are reported: `reasoning` items are the model's
+ * thinking and the rest are tool/command/diff payloads, none of which is the
+ * run's answer.
+ */
 async function appendCodexItem(
   appendLog: (text: string) => Promise<void>,
   item: Record<string, unknown>,
   ts: string,
+  onAssistantText?: OneShotAgentParams["onAssistantText"],
 ): Promise<void> {
   const type = typeof item.type === "string" ? item.type : "unknown";
 
   if (type === "agent_message") {
     const text = typeof item.text === "string" ? item.text : "";
-    if (text) await appendLog(`\n## [${ts}] Assistant\n${text}\n`);
+    if (text) {
+      emitAssistantText(onAssistantText, text);
+      await appendLog(`\n## [${ts}] Assistant\n${text}\n`);
+    }
     return;
   }
 

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

@@ -1,7 +1,7 @@
 /**
  * Shared remote-server backend framework — barrel re-export.
  *
- * Helpers used by `backend/opencode` and `backend/kilo` (both wrap a
+ * Helpers used by the OpenCode and Kilo drivers (both wrap a
  * long-running upstream agent server that exposes a common HTTP API
  * for MCP registration, session lifecycle, tool listing, and provider
  * resolution).
@@ -21,9 +21,11 @@
  *     the chat-turn orchestration, and the registry factory composition.
  *     This is where the code that used to be copied per backend lives.
  *
- *   - Concrete backends (`backend/opencode`, `backend/kilo`) — a
- *     `RemoteBackendProfile` (SDK constructors, port, delivery contract,
- *     model-selection parser) plus re-exports under historical names.
+ *   - Profiles (`profiles/bind.ts` + `profiles/{kilo,opencode}.ts`) —
+ *     `bindRemoteProfile` closes all of the above over one driver's
+ *     state, and each driver is one file of constants: SDK
+ *     constructors, port, delivery contract, model-selection parser,
+ *     model-picker budget.
  *
  * What's NOT here (intentionally):
  *

package/src/backend/remote-server/model-catalog/index.ts

@@ -3,9 +3,9 @@
  * family (OpenCode + its Kilo fork). Both servers expose identical
  * `/provider/list` + `/provider/auth` wire formats, so the catalog cache,
  * query resolution, presentation, and the `Backend.models` adapter live here
- * once. Each backend calls `createRemoteModelCatalogModule` with its own SDK
- * client + branding/UI knobs and re-exports the bound functions under its
- * historical names.
+ * once. `profiles/bind.ts` calls `createRemoteModelCatalogModule` with each
+ * driver's SDK client + branding/picker knobs and hangs the result off that
+ * profile.
  */
 
 import {
@@ -23,13 +23,7 @@ import type {
   RemoteProviderClient,
 } from "./types.js";
 
-export type {
-  ModelButton,
-  RemoteModelCatalog,
-  RemoteModelCatalogEntry,
-  RemoteModelResolution,
-} from "./types.js";
-export { sortCatalogModels } from "./catalog.js";
+export type { RemoteProviderClient } from "./types.js";
 export {
   getBucketPriority,
   getRemoteModelSelectionValue,

package/src/backend/remote-server/model-catalog/provider.ts

@@ -3,9 +3,9 @@
  * interface (resolveModel, getModelInfo, getProviders, …).
  *
  * One implementation for the whole OpenCode family. The catalog surface is
- * injected (rather than captured from the module factory) so each backend's
- * `model-provider.ts` binds its own `models/index.js` — which also keeps that
- * module the single seam tests mock.
+ * injected (rather than captured from the module factory) so
+ * `profiles/bind.ts` can point it at that driver's own cached catalog —
+ * and so a test can point it at a static fixture without a module mock.
  */
 
 import type {

package/src/backend/remote-server/one-shot.ts

@@ -42,6 +42,7 @@ import {
   type RemoteAssistantInfo,
 } from "./session-helpers.js";
 import { appendBackendSuffix, sleep } from "../runtime/index.js";
+import { emitAssistantText } from "../runtime/one-shot-hooks.js";
 import { buildPermissionRuleset } from "./sessions.js";
 
 // ── Client surface ──────────────────────────────────────────────────────────
@@ -108,6 +109,7 @@ export async function runRemoteOneShotAgent<
     contextLabel,
     abortController,
     appendLog,
+    onAssistantText,
   } = params;
   const { label, errMsg } = bindings;
 
@@ -210,7 +212,7 @@ export async function runRemoteOneShotAgent<
       : [];
 
     for (const part of parts) {
-      await appendResponsePart(appendLog, part);
+      await appendResponsePart(appendLog, part, onAssistantText);
     }
 
     // The prompt response's assistant info carries the run's token usage —
@@ -250,17 +252,28 @@ export async function runRemoteOneShotAgent<
 
 // ── Run-log rendering ───────────────────────────────────────────────────────
 
-/** Render one response part into the Markdown run log. */
+/**
+ * Render one response part into the Markdown run log, and report the
+ * assistant's final text to the run's optional `onAssistantText` consumer.
+ *
+ * Only the `text` parts are reported: `reasoning` parts are the model's
+ * thinking and tool parts are call payloads, neither of which is the run's
+ * answer.
+ */
 async function appendResponsePart(
   appendLog: (text: string) => Promise<void>,
   part: Record<string, unknown>,
+  onAssistantText?: OneShotAgentParams["onAssistantText"],
 ): Promise<void> {
   const ts = new Date().toISOString().slice(11, 19);
   const type = typeof part.type === "string" ? part.type : "unknown";
 
   if (type === "text") {
     const text = typeof part.text === "string" ? part.text : "";
-    if (text) await appendLog(`\n## [${ts}] Assistant\n${text}\n`);
+    if (text) {
+      emitAssistantText(onAssistantText, text);
+      await appendLog(`\n## [${ts}] Assistant\n${text}\n`);
+    }
     return;
   }
 

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