@m6d/cortex-server 2.1.0 → 2.3.0

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

@@ -0,0 +1,84 @@
+import type { ClientToolAnswer } from "../../../contracts/src/wire";
+import type { ResolvedCortexAgentConfig } from "../config";
+import type { ChatMessage, Thread } from "../types";
+import { ControlCenterClient } from "../cc/client";
+import type { CcRuntime } 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 declare function clientToolBindings(cc: CcRuntime | undefined, takenNames: ReadonlySet<string>): {
+    [k: string]: {
+        surface: "inline" | "modal";
+        embedOrigin: string;
+        toolId: string;
+    };
+} | undefined;
+/** Null when the agent has no Control Center — every caller treats that as "skip". */
+export declare function createCcClient(config: ResolvedCortexAgentConfig): ControlCenterClient | 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 declare function clientToolAnswersFrom(forwardedProps: Record<string, unknown>): {
+    toolCallId: string;
+    output: unknown;
+    state: "complete" | "error";
+}[] | 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 declare function answerStoredToolCalls(stored: ChatMessage[], answers: ClientToolAnswer[]): {
+    parts: import("@tanstack/ai").MessagePart[];
+    id: string;
+    role: "system" | "user" | "assistant";
+    metadata?: import("../types").MessageMetadata;
+}[];
+/**
+ * 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 declare function applyClientToolAnswers(config: ResolvedCortexAgentConfig, userId: string, threadId: string, answers: ClientToolAnswer[]): Promise<{
+    settled: number;
+    replied: boolean;
+}>;
+/**
+ * `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 declare function initiateClientTool(options: {
+    config: ResolvedCortexAgentConfig;
+    thread: Thread;
+    userId: string;
+    token: string;
+    toolCallId: string;
+}): Promise<{
+    embed: false;
+    embedUrl?: undefined;
+    surface?: undefined;
+    embedOrigin?: undefined;
+} | {
+    embed: true;
+    embedUrl: string;
+    surface: "inline" | "modal";
+    embedOrigin: string;
+}>;

package/dist/src/lib/ai/tools/query-graph.tool.d.ts

@@ -1,5 +1,5 @@
 import z from "zod";
-import type { Neo4jClient } from "../../../../contracts/graph";
+import type { Neo4jClient } from "../../../../contracts/src/graph";
 export declare function createQueryGraphTool(neo4j: Neo4jClient): import("@tanstack/ai").ServerTool<z.ZodObject<{
     query: z.ZodString;
     parameters: z.ZodOptional<z.ZodString>;

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

@@ -2,7 +2,7 @@ import type { AnyServerTool } from "@tanstack/ai";
 import type { ResolvedCortexAgentConfig } from "../config";
 import type { Attachment, Thread } from "../types";
 import type { CcRuntime } from "../cc/registry";
-import type { Neo4jClient } from "../../../contracts/graph";
+import type { Neo4jClient } from "../../../contracts/src/graph";
 type TurnToolsOptions = {
     config: ResolvedCortexAgentConfig;
     cc: CcRuntime | undefined;
@@ -19,9 +19,11 @@ 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 declare function buildTurnTools(options: TurnToolsOptions): AnyServerTool[];
+export declare function buildTurnTools(options: TurnToolsOptions): (AnyServerTool | import("@tanstack/ai").AnyClientTool)[];
 /**
  * Instruments tool calls for the callbacks an agent configured. Returns
  * `undefined` when nothing is listening, so the caller can skip the middleware
@@ -36,15 +38,15 @@ export declare function createToolInstrumentation(options: TurnToolsOptions & {
     onAfterToolCall(_ctx: import("@tanstack/ai").ChatMiddlewareContext<unknown>, { toolName, toolCallId }: import("@tanstack/ai").AfterToolCallInfo): void;
 } | undefined;
 /**
- * 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 declare function interactiveToolDeclarations(cc: CcRuntime | undefined, takenNames: ReadonlySet<string>): {
+export declare function clientToolDeclarations(cc: CcRuntime | undefined, takenNames: ReadonlySet<string>): {
     name: string;
     description: string;
     parameters: Record<string, unknown>;

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

@@ -9,7 +9,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;
@@ -34,7 +34,6 @@ export declare class ControlCenterClient {
             agentId: string;
             systemPrompt: string;
             promptVariables: ("userName" | "channel" | "locale" | "utcTime" | "timezone")[];
-            catalogBlurb: string;
             defaultLocale: "ar" | "en";
             metaTools: {
                 searchKnowledge: boolean;
@@ -77,11 +76,9 @@ export declare class ControlCenterClient {
             signature: string;
             score: number | null;
             pinned: boolean;
-            interaction?: {
+            embed?: {
                 surface: "inline" | "modal";
                 embedOrigin: string;
-                hasVerify: boolean;
-                resultDelivery: "agent" | "endpoint" | "both";
             } | undefined;
             inputSchema?: Record<string, unknown> | undefined;
         }[];
@@ -113,11 +110,9 @@ export declare class ControlCenterClient {
             signature: string;
             score: number | null;
             pinned: boolean;
-            interaction?: {
+            embed?: {
                 surface: "inline" | "modal";
                 embedOrigin: string;
-                hasVerify: boolean;
-                resultDelivery: "agent" | "endpoint" | "both";
             } | undefined;
             inputSchema?: Record<string, unknown> | undefined;
         }[];
@@ -144,11 +139,9 @@ export declare class ControlCenterClient {
             signature: string;
             score: number | null;
             pinned: boolean;
-            interaction?: {
+            embed?: {
                 surface: "inline" | "modal";
                 embedOrigin: string;
-                hasVerify: boolean;
-                resultDelivery: "agent" | "endpoint" | "both";
             } | undefined;
             inputSchema?: Record<string, unknown> | undefined;
         }[];

package/dist/src/lib/cc/config-cache.d.ts

@@ -3,7 +3,6 @@ export declare function getControlCenterConfig(cc: ControlCenterClient, agentId:
     agentId: string;
     systemPrompt: string;
     promptVariables: ("userName" | "channel" | "locale" | "utcTime" | "timezone")[];
-    catalogBlurb: string;
     defaultLocale: "ar" | "en";
     metaTools: {
         searchKnowledge: boolean;

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

@@ -1,18 +1,18 @@
 import type { ControlCenterClient } from "./client";
-import type { RuntimeAgentConfig, ToolInteraction } from "./types";
+import type { RuntimeAgentConfig, ToolEmbed } from "./types";
 export type CcToolBinding = {
     toolId: string;
     readOnly: boolean;
 };
 /**
- * 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>;
 };
 /**
@@ -24,7 +24,7 @@ export declare function registerCcTools(registry: CcToolRegistry, tools: {
     name: string;
     toolId: string;
     readOnly: boolean;
-    interaction?: ToolInteraction;
+    embed?: ToolEmbed;
 }[]): void;
 export declare function recordRecentCcTool(threadId: string, name: string): void;
 export declare function getRecentCcTools(threadId: string): string[];
@@ -34,7 +34,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/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, type ToolInteraction, } 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.1.0",
+    "version": "2.3.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",

package/src/lib/adapters/database/index.ts

@@ -42,18 +42,6 @@ export type DatabaseAdapter = {
             messages: ChatMessage[],
             options?: { replaceAttachments?: boolean },
         ): Promise<void>;
-        /**
-         * Atomically merges one anchored interactive reference into the
-         * message's metadata as a single-statement JSON merge — safe under
-         * concurrent writers across replicas, unlike a read-modify-write of
-         * the whole message.
-         */
-        mergeInteractiveReference(
-            threadId: string,
-            messageId: string,
-            toolCallId: string,
-            reference: string,
-        ): Promise<void>;
     };
     llmRequests: {
         insert(

package/src/lib/adapters/database/mssql/messages.ts

@@ -1,5 +1,5 @@
 // fallow-ignore-file duplicate-export -- mssql twin of the postgres repository, same factory name by design
-import { and, desc, eq, getColumns, inArray, sql, type InferInsertModel } from "drizzle-orm";
+import { and, desc, eq, getColumns, inArray, type InferInsertModel } from "drizzle-orm";
 import { threads, messages } from "@/db/schema.mssql";
 import type { ChatMessage } from "@/types";
 import type { DatabaseAdapter } from "@/adapters/database/index";
@@ -88,32 +88,5 @@ export function createMessagesRepository(db: MssqlDb) {
                     .execute();
             }
         },
-
-        async mergeInteractiveReference(threadId, messageId, toolCallId, reference) {
-            // JSON path keys are quoted strings; the id lands inside one.
-            const escapedKey = toolCallId.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
-            const anchorPath = `lax $.metadata.interactiveReferences."${escapedKey}"`;
-            await db
-                .update(messages)
-                .set({
-                    // All JSON_QUERY reads see the row's pre-update value, so
-                    // the statement is one atomic merge.
-                    content: sql`JSON_MODIFY(
-                        JSON_MODIFY(
-                            JSON_MODIFY(
-                                ${messages.content},
-                                'lax $.metadata',
-                                JSON_QUERY(COALESCE(JSON_QUERY(${messages.content}, '$.metadata'), '{}'))
-                            ),
-                            'lax $.metadata.interactiveReferences',
-                            JSON_QUERY(COALESCE(JSON_QUERY(${messages.content}, '$.metadata.interactiveReferences'), '{}'))
-                        ),
-                        ${anchorPath},
-                        ${reference}
-                    )`,
-                })
-                .where(and(eq(messages.id, messageId), eq(messages.threadId, threadId)))
-                .execute();
-        },
     } satisfies DatabaseAdapter["messages"];
 }

package/src/lib/adapters/database/postgres/messages.ts

@@ -1,6 +1,6 @@
 // fallow-ignore-file code-duplication -- mirrors ../mssql/messages.ts by design;
 // Drizzle types query builders per dialect. See DatabaseAdapter in ../index.ts.
-import { and, desc, eq, getColumns, inArray, sql, type InferInsertModel } from "drizzle-orm";
+import { and, desc, eq, getColumns, inArray, type InferInsertModel } from "drizzle-orm";
 import { threads, messages } from "@/db/schema.pg";
 import type { ChatMessage } from "@/types";
 import type { DatabaseAdapter } from "@/adapters/database/index";
@@ -88,26 +88,5 @@ export function createMessagesRepository(db: PostgresDb) {
                     .execute();
             }
         },
-
-        async mergeInteractiveReference(threadId, messageId, toolCallId, reference) {
-            await db
-                .update(messages)
-                .set({
-                    content: sql`jsonb_set(
-                        jsonb_set(
-                            ${messages.content},
-                            '{metadata}',
-                            coalesce(${messages.content}->'metadata', '{}'::jsonb),
-                            true
-                        ),
-                        '{metadata,interactiveReferences}',
-                        coalesce(${messages.content}->'metadata'->'interactiveReferences', '{}'::jsonb)
-                            || jsonb_build_object(${toolCallId}::text, ${reference}::text),
-                        true
-                    )`,
-                })
-                .where(and(eq(messages.id, messageId), eq(messages.threadId, threadId)))
-                .execute();
-        },
     } satisfies DatabaseAdapter["messages"];
 }

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 { CcInteractiveTool, 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,16 +35,16 @@ export function createCcRuntime(options: CcRuntimeOptions) {
     const registry: CcToolRegistry = new Map();
     if (ccResolved) registerCcTools(registry, ccResolved.tools);
 
-    // Interactive tools resolved at turn start become client-executed LLM
+    // 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 interactiveTools = new Map<string, CcInteractiveTool>();
+    const clientTools = new Map<string, CcClientTool>();
     for (const tool of ccResolved?.tools ?? []) {
-        if (!tool.interaction) continue;
-        interactiveTools.set(tool.name, {
+        if (!tool.embed) continue;
+        clientTools.set(tool.name, {
             toolId: tool.toolId,
             signature: tool.signature,
-            interaction: tool.interaction,
+            embed: tool.embed,
             inputSchema: tool.inputSchema,
         });
     }
@@ -57,7 +57,7 @@ export function createCcRuntime(options: CcRuntimeOptions) {
         agentId: config.agentId,
         config: ccConfig,
         registry,
-        interactiveTools,
+        clientTools,
         threadId: thread.id,
         turnKey: options.turnKey,
         userId,