@m6d/cortex-server 2.1.0 → 2.3.0

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

@@ -29,13 +29,14 @@ import {
     buildTurnTools,
     createToolInstrumentation,
     hasDefaultAttachmentInterceptor,
-    interactiveToolDeclarations,
+    clientToolDeclarations,
 } from "./turn-tools";
 import {
+    applyClientToolAnswers,
+    clientToolAnswersFrom,
     createCcClient,
-    interactiveToolBindings,
-    settleInteractiveToolResults,
-} from "./interactive";
+    clientToolBindings,
+} from "./client-tools";
 import { createInspector } from "./inspector";
 import { commitBeforeTerminal } from "./commit-gate";
 import { finishTurn } from "./finish-turn";
@@ -57,33 +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));
-
-        // Interactive tool answers are untrusted client input: re-establish
-        // them via the tool's verify call and apply result masking before
-        // anything — transcript or model — reads them.
+        const lastUserMessage = await absorbIncoming(params, config, userId, thread.id);
         const ccClient = createCcClient(config);
-        await settleInteractiveToolResults({
-            messages: incoming,
-            thread,
-            userId,
-            token,
-            config,
-            ccClient,
-        });
-        await config.db.messages.upsert(thread.id, incoming);
-
-        const lastUserMessage = incoming.findLast((message) => message.role === "user");
         const prompt = textOf(lastUserMessage);
         if (thread.title === null && prompt) {
             void generateTitle(thread.id, prompt, userId, config);
@@ -234,12 +214,12 @@ export async function startTurn(
         const stream = chat({
             adapter: model,
             // Client tool declarations ride in on every request, so the server
-            // never re-declares them. Interactive CC tools join them: also
+            // 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 interactive.
+            // the collision, and only names that won are treated as a client tool.
             tools: mergeAgentTools(tools, [
                 ...params.tools,
-                ...interactiveToolDeclarations(cc, consumerToolNames),
+                ...clientToolDeclarations(cc, consumerToolNames),
             ]),
             messages: convertMessagesToModelMessages(
                 fitToContextWindow(contextMessages, systemPrompt, tools, config),
@@ -292,9 +272,9 @@ export async function startTurn(
                     modelId: inspector.modelId,
                     isAborted: run.abortController.signal.aborted,
                     tokenUsage: inspector.tokenUsage,
-                    // Stamped so a parked interactive call can be initiated and
-                    // verified after any reload or server restart.
-                    interactiveTools: interactiveToolBindings(cc, consumerToolNames),
+                    // Stamped so a parked client tool call can be initiated
+                    // after any reload or server restart.
+                    clientTools: clientToolBindings(cc, consumerToolNames),
                 } satisfies MessageMetadata,
             };
         }
@@ -328,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) {

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

@@ -20,10 +20,10 @@ export function createSearchToolsTool(cc: CcRuntime) {
         if (!result) return "Tool search is temporarily unavailable. Try again later.";
 
         registerCcTools(cc.registry, result.tools);
-        // Interactive tools cannot join a turn already underway (the model's
+        // 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.interaction);
+        const callable = result.tools.filter((tool) => !tool.embed);
         if (callable.length === 0) return "No matching tools found.";
 
         const shapes =

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

@@ -29,7 +29,9 @@ type TurnToolsOptions = {
  * configured, then the agent's own tools.
  *
  * User tools are appended last and deliberately win on name collision — an agent
- * must be able to replace a built-in it doesn't want.
+ * must be able to replace a built-in it doesn't want. A user tool without an
+ * `execute` function is a static client tool: it passes through to the model
+ * declaration untouched, and the runtime streams its calls to the widget.
  */
 export function buildTurnTools(options: TurnToolsOptions) {
     const { config, cc, neo4j, thread, userId, token, session, requestContext, threadAttachments } =
@@ -111,20 +113,17 @@ export function createToolInstrumentation(
 }
 
 /**
- * Interactive CC tools are declared like the request's client tools: no
+ * CC client tools are declared like the request's client tools: no
  * executor, so the call streams to the widget as a tool-call part and the run
  * parks until the widget answers. The declaration carries the tool's published
  * input schema — function-calling models ignore schemas described only in
  * prose — with a permissive object as the fallback for older Control Centers.
  * Names the consumer already claimed are skipped: those calls belong to the
- * consumer's tool, and must neither be declared nor stamped as interactive.
+ * consumer's tool, and must neither be declared nor stamped as client tools.
  */
-export function interactiveToolDeclarations(
-    cc: CcRuntime | undefined,
-    takenNames: ReadonlySet<string>,
-) {
+export function clientToolDeclarations(cc: CcRuntime | undefined, takenNames: ReadonlySet<string>) {
     if (!cc) return [];
-    return [...cc.interactiveTools]
+    return [...cc.clientTools]
         .filter(([name]) => !takenNames.has(name))
         .map(([name, tool]) => ({
             name,

package/src/lib/cc/client.ts

@@ -22,7 +22,7 @@ export type ExecuteOptions = {
     stepIndex: number;
     callIndex: number;
     /** Overrides the composed key — used where stability must outlive the turn
-     * counters, e.g. one interactive initiate per tool call across reloads. */
+     * counters, e.g. one initiate per tool call across reloads. */
     idempotencyKey?: string;
     timeoutMs?: number;
     abortSignal?: AbortSignal;

package/src/lib/cc/format.ts

@@ -66,17 +66,13 @@ export function buildCcSection(cc: CcPromptInput) {
     const prompt = substituteVariables(cc.config.systemPrompt, cc.variables).trim();
     if (prompt) parts.push(prompt);
 
-    if (cc.config.catalogBlurb) {
-        parts.push(`## Capabilities\n${cc.config.catalogBlurb}`);
-    }
-
     if (cc.resolved) {
         if (cc.resolved.sharedShapes.length > 0) {
             parts.push(`## Response Shapes\n${formatSharedShapes(cc.resolved.sharedShapes)}`);
         }
-        // Interactive tools are declared to the model as real tools, so they
+        // Client tools are declared to the model as real tools, so they
         // stay out of the sandbox-only Dynamic Tools section.
-        const dynamicTools = cc.resolved.tools.filter((tool) => !tool.interaction);
+        const dynamicTools = cc.resolved.tools.filter((tool) => !tool.embed);
         if (dynamicTools.length > 0) {
             parts.push(
                 "## Dynamic Tools\nCall these from executeCode via the `tools` global, e.g. `await tools.name(input)`.\n\n" +

package/src/lib/cc/registry.ts

@@ -1,5 +1,5 @@
 import type { ControlCenterClient } from "./client";
-import type { RuntimeAgentConfig, ToolInteraction } from "./types";
+import type { RuntimeAgentConfig, ToolEmbed } from "./types";
 
 export type CcToolBinding = {
     toolId: string;
@@ -7,14 +7,14 @@ export type CcToolBinding = {
 };
 
 /**
- * An interactive tool resolved for this turn. Declared to the model as a real
+ * 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 CcInteractiveTool = {
+export type CcClientTool = {
     toolId: string;
     signature: string;
-    interaction: ToolInteraction;
+    embed: ToolEmbed;
     inputSchema?: Record<string, unknown>;
 };
 
@@ -26,10 +26,10 @@ export type CcToolRegistry = Map<string, CcToolBinding>;
 
 export function registerCcTools(
     registry: CcToolRegistry,
-    tools: { name: string; toolId: string; readOnly: boolean; interaction?: ToolInteraction }[],
+    tools: { name: string; toolId: string; readOnly: boolean; embed?: ToolEmbed }[],
 ) {
     for (const tool of tools) {
-        if (tool.interaction) continue;
+        if (tool.embed) continue;
         registry.set(tool.name, { toolId: tool.toolId, readOnly: tool.readOnly });
     }
 }
@@ -63,7 +63,7 @@ export type CcRuntime = {
     agentId: string;
     config: RuntimeAgentConfig;
     registry: CcToolRegistry;
-    interactiveTools: Map<string, CcInteractiveTool>;
+    clientTools: Map<string, CcClientTool>;
     threadId: string;
     turnKey: string;
     userId: string;

package/src/lib/cc/types.ts

@@ -17,7 +17,7 @@ export {
     type ResolveResponse,
     type RuntimeAgentConfig,
     type SearchRequest,
-    type ToolInteraction,
+    type ToolEmbed,
 } from "@cortex/contracts/runtime";
 
 const knownRuntimeErrorKinds = new Set<string>(RUNTIME_ERROR_KINDS);

package/src/lib/config.ts

@@ -1,4 +1,4 @@
-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 "@cortex/contracts/graph";
@@ -6,8 +6,13 @@ import type { RequestInterceptorOptions } from "./ai/interceptors/request-interc
 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;

package/src/lib/index.ts

@@ -33,6 +33,10 @@ export type {
 } from "./ai/interceptors/request-interceptor";
 export { createRequestInterceptor } from "./ai/interceptors/request-interceptor";
 
+// Re-exported so consumers define tools (server or static client) without a
+// direct @tanstack/ai import.
+export { toolDefinition } from "@tanstack/ai";
+
 // Tools (consumers may register custom tools or use built-in ones)
 export { createQueryGraphTool } from "./ai/tools/query-graph.tool";
 export { createExecuteCodeTool } from "./ai/tools/execute-code.tool";

package/src/lib/routes/chat.ts

@@ -6,7 +6,7 @@ import { HTTPException } from "hono/http-exception";
 import type { CortexAppEnv } from "@/types";
 import { requireAuth } from "@/auth/middleware";
 import { startTurn } from "@/ai/index";
-import { initiateInteractiveTool } from "@/ai/interactive";
+import { initiateClientTool } from "@/ai/client-tools";
 import { abortRun, getRunId, joinLog, offsetBelongsToRun } from "@/ai/active-runs";
 import { notify } from "@/ws/connections";
 import { requireOwnedThread } from "./owned-thread";
@@ -93,9 +93,9 @@ export function createChatRoutes() {
     });
 
     /**
-     * Runs an interactive tool's initiate call for a pending tool call and
-     * returns the widget's embed payload. `interactive: false` tells the
-     * widget the call is not an interactive CC tool — fall back to its
+     * Runs a client tool's initiate call for a pending tool call and
+     * returns the widget's embed payload. `embed: false` tells the
+     * widget the call is not an CC client tool — fall back to its
      * default rendering. The payload never reaches the model.
      */
     app.post("/chat/:chatId/tools/:toolCallId/initiate", requireAuth, async function (c) {
@@ -104,7 +104,7 @@ export function createChatRoutes() {
         const thread = await requireOwnedThread(c, c.req.param("chatId"));
 
         return c.json(
-            await initiateInteractiveTool({
+            await initiateClientTool({
                 config,
                 thread,
                 userId,

package/tsconfig.json

@@ -23,7 +23,7 @@
             // `vendor` copies them into ./contracts for build and pack. The first
             // candidate exists only then (and in the published tarball) — inside
             // the repo resolution falls through to the workspace source.
-            "@cortex/contracts/*": ["./contracts/*", "../../internal/contracts/*"],
+            "@cortex/contracts/*": ["./contracts/src/*", "../../internal/contracts/src/*"],
             // Internal-only. tsc does not rewrite aliases on emit, so `build` runs
             // tsc-alias to turn these back into relative paths in dist/**/*.d.ts —
             // a consumer's tsc knows nothing about our `@/`. The published raw src