@m6d/cortex-server 2.0.1 → 2.2.0

package/dist/src/lib/cc/registry.d.ts

@@ -1,9 +1,20 @@
 import type { ControlCenterClient } from "./client";
-import type { RuntimeAgentConfig } from "./types";
+import type { RuntimeAgentConfig, ToolEmbed } from "./types";
 export type CcToolBinding = {
     toolId: string;
     readOnly: boolean;
 };
+/**
+ * A client tool resolved for this turn. Declared to the model as a real
+ * client-executed tool — never a sandbox binding — so its call streams to the
+ * widget as a tool-call part and parks the run until the flow settles.
+ */
+export type CcClientTool = {
+    toolId: string;
+    signature: string;
+    embed: ToolEmbed;
+    inputSchema?: Record<string, unknown>;
+};
 /**
  * Turn-scoped and mutable: seeded from /resolve, extended by searchTools
  * mid-turn so a tool discovered at step 3 is callable at step 4.
@@ -13,6 +24,7 @@ export declare function registerCcTools(registry: CcToolRegistry, tools: {
     name: string;
     toolId: string;
     readOnly: boolean;
+    embed?: ToolEmbed;
 }[]): void;
 export declare function recordRecentCcTool(threadId: string, name: string): void;
 export declare function getRecentCcTools(threadId: string): string[];
@@ -22,6 +34,7 @@ export type CcRuntime = {
     agentId: string;
     config: RuntimeAgentConfig;
     registry: CcToolRegistry;
+    clientTools: Map<string, CcClientTool>;
     threadId: string;
     turnKey: string;
     userId: string;

package/dist/src/lib/cc/types.d.ts

@@ -1,5 +1,5 @@
 import z from "zod";
-export { AGENT_SLUG_PATTERN, executeResponseSchema, resolveResponseSchema, runtimeAgentConfigSchema, searchKnowledgeResponseSchema, searchServicesResponseSchema, searchToolsResponseSchema, type ExecuteRequest, type ResolveRequest, type ResolveResponse, type RuntimeAgentConfig, type SearchRequest, } from "../../../contracts/runtime";
+export { AGENT_SLUG_PATTERN, executeResponseSchema, resolveResponseSchema, runtimeAgentConfigSchema, searchKnowledgeResponseSchema, searchServicesResponseSchema, searchToolsResponseSchema, type ExecuteRequest, type ResolveRequest, type ResolveResponse, type RuntimeAgentConfig, type SearchRequest, type ToolEmbed, } from "../../../contracts/src/runtime";
 /**
  * The contract's error envelope, hardened for this consumer: a newer runtime may
  * answer with an error kind this build has never heard of, which must degrade to a

package/dist/src/lib/config.d.ts

@@ -1,12 +1,17 @@
-import type { AnyServerTool } from "@tanstack/ai";
+import type { AnyClientTool, AnyServerTool } from "@tanstack/ai";
 import type { DatabaseAdapter } from "./adapters/database/index";
 import type { StorageAdapter } from "./adapters/storage/index";
-import type { DomainDef } from "../../contracts/graph";
+import type { DomainDef } from "../../contracts/src/graph";
 import type { RequestInterceptorOptions } from "./ai/interceptors/request-interceptor";
 import type { ContextConfig } from "./ai/context/types";
 import type { ChatMessage, Thread } from "./types";
-/** An agent's tools, as `chat()` takes them. */
-export type ToolSet = ReadonlyArray<AnyServerTool>;
+/**
+ * An agent's tools, as `chat()` takes them. A tool with an `execute` function
+ * runs on the server; one without is a static client tool — declared to the
+ * model, streamed to the widget as a tool-call part, and answered by the host
+ * app (`hooks.onToolCall` or a `toolComponents` entry with `setOutput`).
+ */
+export type ToolSet = ReadonlyArray<AnyServerTool | AnyClientTool>;
 type ModelConfig = {
     baseURL: string;
     apiKey: string;

package/dist/src/lib/graph/index.d.ts

@@ -5,6 +5,6 @@
  * re-exported here so authoring a project's domains still needs exactly one
  * import path — nothing about the public surface moved.
  */
-export * from "../../../contracts/graph";
+export * from "../../../contracts/src/graph";
 export type { RerankerConfig, ResolverConfig, ResolvedEndpoint, ResolvedService, ResolvedContext, } from "./resolver";
 export { resolveFromGraph } from "./resolver";

package/dist/src/lib/graph/resolver.d.ts

@@ -5,7 +5,7 @@
  * All configuration is passed explicitly — no hardcoded model references
  * or environment variables.
  */
-import { type EmbedFn, type Neo4jClient } from "../../../contracts/graph";
+import { type EmbedFn, type Neo4jClient } from "../../../contracts/src/graph";
 export type RerankerConfig = {
     url: string;
     apiKey: string;

package/dist/src/lib/index.d.ts

@@ -7,7 +7,8 @@ export type { CortexInstance } from "./factory";
 export { createCortex } from "./factory";
 export type { ResolvedFile, RequestInterceptorOptions, } from "./ai/interceptors/request-interceptor";
 export { createRequestInterceptor } from "./ai/interceptors/request-interceptor";
+export { toolDefinition } from "@tanstack/ai";
 export { createQueryGraphTool } from "./ai/tools/query-graph.tool";
 export { createExecuteCodeTool } from "./ai/tools/execute-code.tool";
 export * from "./graph/index";
-export * from "../../contracts/wire";
+export * from "../../contracts/src/wire";

package/dist/src/lib/types.d.ts

@@ -2,8 +2,8 @@ import type { MessagePart } from "@tanstack/ai";
 import type { ResolvedCortexAgentConfig } from "./config";
 import type { InferSelectModel } from "drizzle-orm";
 import type { attachments, messages, threads } from "./db/schema.mssql";
-export type { CortexMessage, MessageMetadata, ThreadSummary, TokenUsage, } from "../../contracts/wire";
-import type { CortexMessage } from "../../contracts/wire";
+export type { CortexMessage, MessageMetadata, ThreadSummary, TokenUsage, } from "../../contracts/src/wire";
+import type { CortexMessage } from "../../contracts/src/wire";
 /** A message as cortex persists and serves it: SDK parts plus cortex's envelope. */
 export type ChatMessage = CortexMessage<MessagePart>;
 export type Thread = InferSelectModel<typeof threads>;

package/dist/src/lib/ws/connections.d.ts

@@ -1,5 +1,5 @@
 import type { WSContext } from "hono/ws";
-import type { WsEvent } from "../../../contracts/wire";
+import type { WsEvent } from "../../../contracts/src/wire";
 export declare function addConnection(userId: string, agentId: string, ws: WSContext): void;
 export declare function removeConnection(userId: string, agentId: string, ws: WSContext): void;
 export declare function notify(userId: string, agentId: string, event: WsEvent): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-server",
-    "version": "2.0.1",
+    "version": "2.2.0",
     "description": "Reusable AI agent chat server library for Hono + Bun",
     "license": "MIT",
     "type": "module",
@@ -24,7 +24,7 @@
         "!src/**/*.mock.ts"
     ],
     "scripts": {
-        "build": "bun run vendor && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && rm -rf contracts",
+        "build": "bun run vendor && rm -rf dist && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && rm -rf contracts",
         "check": "tsc --noEmit",
         "db:generate:mssql": "drizzle-kit generate --config=src/lib/db/drizzle.config.mssql.ts",
         "db:generate:pg": "drizzle-kit generate --config=src/lib/db/drizzle.config.pg.ts",
@@ -74,5 +74,8 @@
     },
     "publishConfig": {
         "access": "public"
-    }
+    },
+    "releaseWatchPaths": [
+        "internal/contracts"
+    ]
 }

package/src/lib/ai/cc-runtime.ts

@@ -1,7 +1,7 @@
 import type { ResolvedCortexAgentConfig } from "@/config";
 import type { Thread } from "@/types";
 import type { ControlCenterClient } from "@/cc/client";
-import type { CcRuntime, CcToolRegistry } from "@/cc/registry";
+import type { CcClientTool, CcRuntime, CcToolRegistry } from "@/cc/registry";
 import { registerCcTools } from "@/cc/registry";
 import type { ResolveResponse, RuntimeAgentConfig } from "@/cc/types";
 
@@ -35,6 +35,20 @@ export function createCcRuntime(options: CcRuntimeOptions) {
     const registry: CcToolRegistry = new Map();
     if (ccResolved) registerCcTools(registry, ccResolved.tools);
 
+    // Client tools resolved at turn start become client-executed LLM
+    // tools. Mid-turn search finds are excluded on purpose: the model's tool
+    // set is fixed once the turn starts, so declaring them is impossible.
+    const clientTools = new Map<string, CcClientTool>();
+    for (const tool of ccResolved?.tools ?? []) {
+        if (!tool.embed) continue;
+        clientTools.set(tool.name, {
+            toolId: tool.toolId,
+            signature: tool.signature,
+            embed: tool.embed,
+            inputSchema: tool.inputSchema,
+        });
+    }
+
     let currentStep = -1;
     let callIndex = 0;
 
@@ -43,6 +57,7 @@ export function createCcRuntime(options: CcRuntimeOptions) {
         agentId: config.agentId,
         config: ccConfig,
         registry,
+        clientTools,
         threadId: thread.id,
         turnKey: options.turnKey,
         userId,

package/src/lib/ai/client-tools.ts

@@ -0,0 +1,288 @@
+import { HTTPException } from "hono/http-exception";
+import { CLIENT_TOOL_ANSWERS_KEY } from "@cortex/contracts/wire";
+import type {
+    ClientToolAnswer,
+    ClientToolBinding,
+    ClientToolInitiateResult,
+} from "@cortex/contracts/wire";
+import type { ResolvedCortexAgentConfig } from "@/config";
+import type { ChatMessage, Thread } from "@/types";
+import { ControlCenterClient } from "@/cc/client";
+import type { CcRuntime } from "@/cc/registry";
+import { recordRecentCcTool } from "@/cc/registry";
+
+/**
+ * The wire-shape bindings stamped on the turn's final assistant message, so a
+ * parked client tool call can be initiated after any restart. Only names that
+ * actually won declaration merging are stamped — a call to a colliding
+ * consumer-owned tool must never be treated as a client tool. Undefined when
+ * nothing qualifies, keeping metadata lean.
+ */
+export function clientToolBindings(cc: CcRuntime | undefined, takenNames: ReadonlySet<string>) {
+    if (!cc) return undefined;
+    const entries = [...cc.clientTools]
+        .filter(([name]) => !takenNames.has(name))
+        .map(
+            ([name, tool]) =>
+                [name, { toolId: tool.toolId, ...tool.embed } satisfies ClientToolBinding] as const,
+        );
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+
+/** Null when the agent has no Control Center — every caller treats that as "skip". */
+export function createCcClient(config: ResolvedCortexAgentConfig) {
+    return config.controlCenter ? new ControlCenterClient(config.controlCenter) : null;
+}
+
+/**
+ * The `clientToolAnswers` a continuation request carried under
+ * `forwardedProps`, validated structurally — the widget is not the only
+ * possible author of a request body. All-or-nothing: `[]` means the request
+ * carried no answers at all, while `null` means it carried a payload with any
+ * malformed entry — the caller must not act on such a request, neither by
+ * settling its valid remainder nor by running a turn for it.
+ */
+export function clientToolAnswersFrom(forwardedProps: Record<string, unknown>) {
+    const raw = forwardedProps[CLIENT_TOOL_ANSWERS_KEY];
+    if (raw === undefined) return [];
+    if (!Array.isArray(raw)) return null;
+
+    const answers = raw.flatMap((item) => {
+        const record = asRecord(item);
+        if (!record || typeof record.toolCallId !== "string" || !("output" in record)) return [];
+        const state = record.state;
+        if (state !== "complete" && state !== "error") return [];
+        return [
+            {
+                toolCallId: record.toolCallId,
+                output: record.output,
+                state,
+            } satisfies ClientToolAnswer,
+        ];
+    });
+    return answers.length === raw.length ? answers : null;
+}
+
+/**
+ * Applies client tool answers to the stored messages carrying their calls,
+ * mirroring the SDK's own settle shape (call part gains output + state, a
+ * tool-result part is appended). Already-settled calls are skipped, so a
+ * replayed continuation is a no-op. Returns only the messages that changed.
+ */
+export function answerStoredToolCalls(stored: ChatMessage[], answers: ClientToolAnswer[]) {
+    const byCallId = new Map(answers.map((answer) => [answer.toolCallId, answer]));
+
+    return stored.flatMap((message) => {
+        const pending = message.parts.filter(
+            (part) =>
+                part.type === "tool-call" &&
+                byCallId.has(part.id) &&
+                part.state !== "complete" &&
+                part.state !== "error",
+        );
+        if (pending.length === 0) return [];
+
+        let parts = message.parts;
+        for (const part of pending) {
+            if (part.type !== "tool-call") continue;
+            const answer = byCallId.get(part.id)!;
+            const content =
+                typeof answer.output === "string" ? answer.output : JSON.stringify(answer.output);
+            parts = parts
+                .map((candidate) =>
+                    candidate === part
+                        ? { ...candidate, output: answer.output, state: answer.state }
+                        : candidate,
+                )
+                .concat([
+                    { type: "tool-result", toolCallId: part.id, content, state: answer.state },
+                ]);
+        }
+        return [{ ...message, parts }];
+    });
+}
+
+/**
+ * Whether an assistant reply already follows the message carrying the
+ * answered calls — the mark of a continuation that completed. A settled call
+ * with nothing after it means the continuation died before replying, so a
+ * retried delivery must run rather than be discarded as a replay. Ids that
+ * match no stored call count as replied: there is nothing to run for them.
+ */
+function repliedAfterAnswers(stored: ChatMessage[], answers: ClientToolAnswer[]) {
+    const ids = new Set(answers.map((answer) => answer.toolCallId));
+    const index = stored.findLastIndex((message) =>
+        message.parts.some((part) => part.type === "tool-call" && ids.has(part.id)),
+    );
+    if (index === -1) return true;
+    return stored.slice(index + 1).some((message) => message.role === "assistant");
+}
+
+/**
+ * The server-authoritative half of a client tool continuation: the widget
+ * sends `messages: []` plus the answers, and the transcript is updated in
+ * place — the answered assistant message never round-trips, so the id the
+ * SDK's park-boundary snapshot failed to preserve no longer matters.
+ * `settled` is how many messages the answers changed; with `replied` it lets
+ * the caller tell a true replay (nothing settled, reply already stored) from
+ * a retry after a continuation that died before replying.
+ */
+export async function applyClientToolAnswers(
+    config: ResolvedCortexAgentConfig,
+    userId: string,
+    threadId: string,
+    answers: ClientToolAnswer[],
+) {
+    const stored = (await config.db.messages.list(userId, threadId)).map((row) => row.content);
+
+    // An id matching no stored call — or repeated within the payload — voids
+    // the whole request: nothing settles, not even a valid remainder. A
+    // retry's ids always exist (settled by the attempt that died) and never
+    // repeat, so only a broken or forged request looks like this.
+    const storedCallIds = new Set(
+        stored.flatMap((message) =>
+            message.parts.flatMap((part) => (part.type === "tool-call" ? [part.id] : [])),
+        ),
+    );
+    const ids = answers.map((answer) => answer.toolCallId);
+    if (new Set(ids).size !== ids.length || !ids.every((id) => storedCallIds.has(id))) {
+        return { settled: 0, replied: true };
+    }
+
+    const updated = answerStoredToolCalls(stored, answers);
+    if (updated.length) await config.db.messages.upsert(threadId, updated);
+    return { settled: updated.length, replied: repliedAfterAnswers(stored, answers) };
+}
+
+/** How long initiate waits out the turn-commit race before giving up. */
+const PENDING_CALL_RETRIES = 6;
+const PENDING_CALL_RETRY_MS = 700;
+
+/**
+ * The widget initiates the moment its stream goes idle, which can beat the
+ * turn's commit to the database — so a missing call is retried briefly before
+ * it becomes a 404. An *answered* call 404s immediately: it was settled
+ * elsewhere (another tab) and the widget should fall back to its pill.
+ */
+async function findPendingClientToolCall(
+    config: ResolvedCortexAgentConfig,
+    userId: string,
+    threadId: string,
+    toolCallId: string,
+) {
+    for (let attempt = 0; ; attempt += 1) {
+        const stored = await config.db.messages.list(userId, threadId);
+        const messages = stored.map((row) => row.content);
+        const answered = messages.some((candidate) =>
+            candidate.parts.some(
+                (part) => part.type === "tool-result" && part.toolCallId === toolCallId,
+            ),
+        );
+        if (answered) return null;
+
+        for (const message of messages) {
+            const call = message.parts.find(
+                (part) => part.type === "tool-call" && part.id === toolCallId,
+            );
+            if (call?.type === "tool-call") return { message, call };
+        }
+
+        if (attempt >= PENDING_CALL_RETRIES) return null;
+        await new Promise((resolve) => setTimeout(resolve, PENDING_CALL_RETRY_MS));
+    }
+}
+
+/**
+ * `POST /chat/:chatId/tools/:toolCallId/initiate` — runs the interactive
+ * tool's initiate call (the tool's own endpoint) and hands the widget its
+ * embed payload. The model never sees this payload. The idempotency key is
+ * pinned to the tool call, so a reload mid-flow reuses the created session
+ * instead of opening a second one. The result the page later posts back is
+ * relayed to the agent as-is — verifying it is the integrating backend's job.
+ */
+export async function initiateClientTool(options: {
+    config: ResolvedCortexAgentConfig;
+    thread: Thread;
+    userId: string;
+    token: string;
+    toolCallId: string;
+}) {
+    const { config, thread, userId, token, toolCallId } = options;
+    const pending = await findPendingClientToolCall(config, userId, thread.id, toolCallId);
+    if (!pending) {
+        throw new HTTPException(404, { message: "No pending tool call with this id" });
+    }
+    const { message, call } = pending;
+
+    const binding = message.metadata?.clientTools?.[call.name];
+    const ccClient = createCcClient(config);
+    if (!binding || !ccClient) {
+        return { embed: false } satisfies ClientToolInitiateResult;
+    }
+
+    const result = await ccClient.execute(
+        config.agentId,
+        binding.toolId,
+        {
+            input: asRecord(call.input) ?? asRecord(parseJson(call.arguments)) ?? {},
+            context: { threadId: thread.id, userId },
+        },
+        {
+            readOnly: false,
+            endUserToken: token,
+            threadId: thread.id,
+            turnKey: toolCallId,
+            stepIndex: 0,
+            callIndex: 0,
+            idempotencyKey: `${thread.id}:${toolCallId}:initiate`,
+        },
+    );
+    if (!result) {
+        throw new HTTPException(502, { message: "The tool is temporarily unavailable" });
+    }
+    if ("error" in result) {
+        throw new HTTPException(502, { message: `initiate failed: ${result.error.kind}` });
+    }
+
+    const embedUrl = asRecord(result.output)?.embedUrl;
+    if (typeof embedUrl !== "string" || !isOnOrigin(embedUrl, binding.embedOrigin)) {
+        throw new HTTPException(502, {
+            message: "initiate did not return an embedUrl on the configured origin",
+        });
+    }
+
+    recordRecentCcTool(thread.id, call.name);
+
+    return {
+        embed: true,
+        embedUrl,
+        surface: binding.surface,
+        embedOrigin: binding.embedOrigin,
+    } satisfies ClientToolInitiateResult;
+}
+
+function parseJson(value: string | undefined) {
+    if (value === undefined) return undefined;
+    try {
+        return JSON.parse(value) as unknown;
+    } catch {
+        return undefined;
+    }
+}
+
+function asRecord(value: unknown) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? (value as Record<string, unknown>)
+        : undefined;
+}
+
+function isOnOrigin(url: string, origin: string) {
+    try {
+        const parsed = new URL(url);
+        // http(s) only: javascript:/data: URLs normalize to origin "null",
+        // which a bare equality check could otherwise be tricked into passing.
+        return ["http:", "https:"].includes(parsed.protocol) && parsed.origin === origin;
+    } catch {
+        return false;
+    }
+}

package/src/lib/ai/index.ts

@@ -15,7 +15,6 @@ import type { ResolvedCortexAgentConfig, ToolSet } from "@/config";
 import type { ChatMessage, MessageMetadata, Thread } from "@/types";
 import { createModel } from "./helpers";
 import { buildSystemPrompt, resolveSession } from "./prompt";
-import { ControlCenterClient } from "@/cc/client";
 import { getControlCenterConfig } from "@/cc/config-cache";
 import { buildPromptVariables } from "@/cc/format";
 import { getRecentCcTools } from "@/cc/registry";
@@ -30,7 +29,14 @@ import {
     buildTurnTools,
     createToolInstrumentation,
     hasDefaultAttachmentInterceptor,
+    clientToolDeclarations,
 } from "./turn-tools";
+import {
+    applyClientToolAnswers,
+    clientToolAnswersFrom,
+    createCcClient,
+    clientToolBindings,
+} from "./client-tools";
 import { createInspector } from "./inspector";
 import { commitBeforeTerminal } from "./commit-gate";
 import { finishTurn } from "./finish-turn";
@@ -52,20 +58,12 @@ export async function startTurn(
     requestContext: Record<string, unknown>,
     config: ResolvedCortexAgentConfig,
 ) {
+    if (await absorbContinuationAnswers(params, config, userId, thread.id)) return null;
+
     const run = await startRun(thread.id);
     try {
-        // The client owns its own messages, and the assistant turn it sends back
-        // once a client-side tool has answered — without that answer stored, the
-        // next turn replays an assistant message whose tool calls nothing ever
-        // resolved, and the provider rejects the thread from there on. Everything
-        // else the server generated stays the server's; the repository keeps the
-        // usage and model id only it ever knew.
-        const incoming = params.messages
-            .map((message) => toChatMessage(normalizeToUIMessage(message, generateMessageId)))
-            .filter((message) => message.role === "user" || answersToolCalls(message));
-        await config.db.messages.upsert(thread.id, incoming);
-
-        const lastUserMessage = incoming.findLast((message) => message.role === "user");
+        const lastUserMessage = await absorbIncoming(params, config, userId, thread.id);
+        const ccClient = createCcClient(config);
         const prompt = textOf(lastUserMessage);
         if (thread.title === null && prompt) {
             void generateTitle(thread.id, prompt, userId, config);
@@ -111,7 +109,7 @@ export async function startTurn(
         const turnKey = lastUserMessage?.id ?? "0";
 
         const inspector = createInspector();
-        const { model, embed, neo4j, ccClient } = createTurnProviders(config, inspector.fetch);
+        const { model, embed, neo4j } = createTurnProviders(config, inspector.fetch);
 
         // Run independent operations in parallel
         const [contextResult, resolved, session, ccConfig, ccResolved] = await Promise.all([
@@ -173,6 +171,10 @@ export async function startTurn(
             threadAttachments,
         };
         const tools = buildTurnTools(turnToolsOptions);
+        const consumerToolNames = new Set([
+            ...tools.map((tool) => tool.name),
+            ...params.tools.map((tool) => tool.name),
+        ]);
         const instrumentation = createToolInstrumentation({
             ...turnToolsOptions,
             onToolStart: (toolName, toolCallId) =>
@@ -212,8 +214,13 @@ export async function startTurn(
         const stream = chat({
             adapter: model,
             // Client tool declarations ride in on every request, so the server
-            // never re-declares them.
-            tools: mergeAgentTools(tools, params.tools),
+            // never re-declares them. CC client tools join them: also
+            // executor-less, answered by the widget. Consumer-owned names win
+            // the collision, and only names that won are treated as a client tool.
+            tools: mergeAgentTools(tools, [
+                ...params.tools,
+                ...clientToolDeclarations(cc, consumerToolNames),
+            ]),
             messages: convertMessagesToModelMessages(
                 fitToContextWindow(contextMessages, systemPrompt, tools, config),
             ),
@@ -265,6 +272,9 @@ export async function startTurn(
                     modelId: inspector.modelId,
                     isAborted: run.abortController.signal.aborted,
                     tokenUsage: inspector.tokenUsage,
+                    // Stamped so a parked client tool call can be initiated
+                    // after any reload or server restart.
+                    clientTools: clientToolBindings(cc, consumerToolNames),
                 } satisfies MessageMetadata,
             };
         }
@@ -298,20 +308,53 @@ function toChatMessage(message: UIMessage) {
 }
 
 /**
- * An assistant turn the client is sending back because it resolved a tool call.
- *
- * The wire fans that turn out into a `role: "tool"` message per result, and each
- * of those normalizes back into an assistant message carrying only the result,
- * under a freshly generated id. Stored as rows of their own they would replay as
- * assistant turns answering calls that no message makes, so the turn is picked
- * out by holding both halves of the exchange.
+ * Applies a parked client tool's answers to the stored messages carrying the
+ * calls — before the thread is claimed, because applying is idempotent and
+ * needs no run. True means the request was a stale replay: it settled
+ * nothing, the reply it would produce is already stored, and it carries no
+ * user message — so there is no turn to run, and claiming would only abort
+ * the legitimate run it duplicates. A retry whose earlier continuation died
+ * before replying settles nothing too, but has no stored reply, so it runs.
+ * A malformed payload voids the whole request the same way: nothing settles
+ * and no turn runs, so a broken client can neither partially settle a turn's
+ * calls nor mint an empty-message model turn.
  */
-function answersToolCalls(message: ChatMessage) {
-    return (
-        message.role === "assistant" &&
-        message.parts.some((part) => part.type === "tool-call") &&
-        message.parts.some((part) => part.type === "tool-result")
-    );
+async function absorbContinuationAnswers(
+    params: TurnParams,
+    config: ResolvedCortexAgentConfig,
+    userId: string,
+    threadId: string,
+) {
+    const answers = clientToolAnswersFrom(params.forwardedProps);
+    if (answers === null) return true;
+    if (!answers.length) return false;
+
+    const { settled, replied } = await applyClientToolAnswers(config, userId, threadId, answers);
+    return settled === 0 && replied && !params.messages.some((message) => message.role === "user");
+}
+
+/**
+ * What a request contributes to the stored transcript: the user messages the
+ * client wrote — nothing else, because the server owns history (a parked
+ * client tool's answers go through `absorbContinuationAnswers`; the answered
+ * assistant turn itself never crosses the wire, because the SDK's
+ * park-boundary snapshot does not preserve its message id and round-tripping
+ * it duplicated the stored message). Returns the newest user message, the
+ * turn's prompt, when the request carried one.
+ */
+async function absorbIncoming(
+    params: TurnParams,
+    config: ResolvedCortexAgentConfig,
+    userId: string,
+    threadId: string,
+) {
+    const incoming = params.messages
+        .map((message) => toChatMessage(normalizeToUIMessage(message, generateMessageId)))
+        .filter((message) => message.role === "user");
+
+    if (incoming.length) await config.db.messages.upsert(threadId, incoming);
+
+    return incoming.findLast((message) => message.role === "user");
 }
 
 function textOf(message: ChatMessage | undefined) {
@@ -338,7 +381,6 @@ function createTurnProviders(config: ResolvedCortexAgentConfig, fetch: typeof gl
         model: createModel(config.model, { fetch }),
         embed,
         neo4j: config.neo4j && embed ? createNeo4jClient(config.neo4j, embed) : undefined,
-        ccClient: config.controlCenter ? new ControlCenterClient(config.controlCenter) : null,
     };
 }
 

package/src/lib/ai/tools/search-tools.tool.ts

@@ -20,10 +20,14 @@ export function createSearchToolsTool(cc: CcRuntime) {
         if (!result) return "Tool search is temporarily unavailable. Try again later.";
 
         registerCcTools(cc.registry, result.tools);
-        if (result.tools.length === 0) return "No matching tools found.";
+        // Client tools cannot join a turn already underway (the model's
+        // tool set is fixed at turn start), so surfacing them here would only
+        // advertise dead ends.
+        const callable = result.tools.filter((tool) => !tool.embed);
+        if (callable.length === 0) return "No matching tools found.";
 
         const shapes =
             result.sharedShapes.length > 0 ? `${formatSharedShapes(result.sharedShapes)}\n\n` : "";
-        return shapes + formatToolSignatures(result.tools);
+        return shapes + formatToolSignatures(callable);
     });
 }