@m6d/cortex-server 2.0.0 → 2.1.0

package/dist/contracts/runtime.d.ts

@@ -3,14 +3,44 @@ import { z } from "zod";
 export declare const AGENT_SLUG_PATTERN: RegExp;
 /** Runtime contract §5: tool names become `tools.<name>()` sandbox bindings. */
 export declare const TOOL_NAME_PATTERN: RegExp;
-export declare const PROMPT_VARIABLES: readonly ["userName", "channel", "locale"];
+export declare const PROMPT_VARIABLES: readonly ["userName", "channel", "locale", "utcTime", "timezone"];
+/**
+ * One entry per prompt variable, driving editor autocomplete, validation, and
+ * runtime substitution alike. Adding a variable = extending the tuple above
+ * plus one entry here (the compiler enforces the pair); the consumer embedding
+ * the agent supplies the value in its session/request context under the same
+ * key. Descriptions are plain English on purpose: variables are code-like
+ * identifiers shown in an LTR suggestion list, not localized UI copy.
+ */
+export declare const PROMPT_VARIABLE_DEFINITIONS: {
+    userName: {
+        description: string;
+        example: string;
+    };
+    channel: {
+        description: string;
+        example: string;
+    };
+    locale: {
+        description: string;
+        example: string;
+    };
+    utcTime: {
+        description: string;
+        example: string;
+    };
+    timezone: {
+        description: string;
+        example: string;
+    };
+};
 export declare const RUNTIME_ERROR_KINDS: readonly ["timeout", "upstream_4xx", "upstream_5xx", "schema_mismatch", "rate_limited", "not_found", "unauthorized", "invalid_request", "egress_blocked", "internal"];
 /** The ways an execute output may disagree with the tool's declared schema. */
 export declare const JSON_SCHEMA_ISSUE_KINDS: readonly ["missing", "unexpected", "type_mismatch"];
 export declare const agentSlugSchema: z.ZodString;
 export declare const localeSchema: z.ZodEnum<{
-    en: "en";
     ar: "ar";
+    en: "en";
 }>;
 export declare const catalogVersionSchema: z.ZodString;
 export declare const sharedShapeSchema: z.ZodObject<{
@@ -30,6 +60,25 @@ export declare const knowledgeChunkSchema: z.ZodObject<{
         service: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+/**
+ * Runtime contract §5.4: present on signatures of `interactive` tools — flows
+ * the end user completes in an embedded surface inside the chat widget. The
+ * tool's endpoint fields act as the *initiate* call (returns the embed URL);
+ * `hasVerify` marks a second, server-trusted call that settles the result.
+ */
+export declare const toolInteractionSchema: z.ZodObject<{
+    surface: z.ZodEnum<{
+        inline: "inline";
+        modal: "modal";
+    }>;
+    embedOrigin: z.ZodURL;
+    hasVerify: z.ZodBoolean;
+    resultDelivery: z.ZodEnum<{
+        agent: "agent";
+        endpoint: "endpoint";
+        both: "both";
+    }>;
+}, z.core.$strip>;
 export declare const toolSignatureSchema: z.ZodObject<{
     toolId: z.ZodUUID;
     name: z.ZodString;
@@ -39,6 +88,20 @@ export declare const toolSignatureSchema: z.ZodObject<{
     signature: z.ZodString;
     score: z.ZodNullable<z.ZodNumber>;
     pinned: z.ZodBoolean;
+    interaction: z.ZodOptional<z.ZodObject<{
+        surface: z.ZodEnum<{
+            inline: "inline";
+            modal: "modal";
+        }>;
+        embedOrigin: z.ZodURL;
+        hasVerify: z.ZodBoolean;
+        resultDelivery: z.ZodEnum<{
+            agent: "agent";
+            endpoint: "endpoint";
+            both: "both";
+        }>;
+    }, z.core.$strip>>;
+    inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 export declare const serviceCardSchema: z.ZodObject<{
     serviceId: z.ZodUUID;
@@ -54,11 +117,13 @@ export declare const runtimeAgentConfigSchema: z.ZodObject<{
         userName: "userName";
         channel: "channel";
         locale: "locale";
+        utcTime: "utcTime";
+        timezone: "timezone";
     }>>;
     catalogBlurb: z.ZodString;
     defaultLocale: z.ZodEnum<{
-        en: "en";
         ar: "ar";
+        en: "en";
     }>;
     metaTools: z.ZodObject<{
         searchKnowledge: z.ZodBoolean;
@@ -76,8 +141,8 @@ export declare const runtimeAgentConfigSchema: z.ZodObject<{
 export declare const resolveRequestSchema: z.ZodObject<{
     query: z.ZodString;
     locale: z.ZodOptional<z.ZodEnum<{
-        en: "en";
         ar: "ar";
+        en: "en";
     }>>;
     hints: z.ZodOptional<z.ZodObject<{
         threadId: z.ZodOptional<z.ZodString>;
@@ -95,8 +160,8 @@ export declare const resolveResponseSchema: z.ZodObject<{
     resolveId: z.ZodUUID;
     catalogVersion: z.ZodString;
     locale: z.ZodEnum<{
-        en: "en";
         ar: "ar";
+        en: "en";
     }>;
     knowledge: z.ZodArray<z.ZodObject<{
         chunkId: z.ZodUUID;
@@ -120,6 +185,20 @@ export declare const resolveResponseSchema: z.ZodObject<{
         signature: z.ZodString;
         score: z.ZodNullable<z.ZodNumber>;
         pinned: z.ZodBoolean;
+        interaction: z.ZodOptional<z.ZodObject<{
+            surface: z.ZodEnum<{
+                inline: "inline";
+                modal: "modal";
+            }>;
+            embedOrigin: z.ZodURL;
+            hasVerify: z.ZodBoolean;
+            resultDelivery: z.ZodEnum<{
+                agent: "agent";
+                endpoint: "endpoint";
+                both: "both";
+            }>;
+        }, z.core.$strip>>;
+        inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
     services: z.ZodArray<z.ZodObject<{
         serviceId: z.ZodUUID;
@@ -142,8 +221,8 @@ export declare const searchRequestSchema: z.ZodObject<{
     query: z.ZodString;
     limit: z.ZodDefault<z.ZodNumber>;
     locale: z.ZodOptional<z.ZodEnum<{
-        en: "en";
         ar: "ar";
+        en: "en";
     }>>;
     threadId: z.ZodOptional<z.ZodString>;
     service: z.ZodOptional<z.ZodString>;
@@ -159,6 +238,20 @@ export declare const searchToolsResponseSchema: z.ZodObject<{
         signature: z.ZodString;
         score: z.ZodNullable<z.ZodNumber>;
         pinned: z.ZodBoolean;
+        interaction: z.ZodOptional<z.ZodObject<{
+            surface: z.ZodEnum<{
+                inline: "inline";
+                modal: "modal";
+            }>;
+            embedOrigin: z.ZodURL;
+            hasVerify: z.ZodBoolean;
+            resultDelivery: z.ZodEnum<{
+                agent: "agent";
+                endpoint: "endpoint";
+                both: "both";
+            }>;
+        }, z.core.$strip>>;
+        inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
     sharedShapes: z.ZodArray<z.ZodObject<{
         ref: z.ZodString;
@@ -183,6 +276,20 @@ export declare const searchServicesResponseSchema: z.ZodObject<{
         signature: z.ZodString;
         score: z.ZodNullable<z.ZodNumber>;
         pinned: z.ZodBoolean;
+        interaction: z.ZodOptional<z.ZodObject<{
+            surface: z.ZodEnum<{
+                inline: "inline";
+                modal: "modal";
+            }>;
+            embedOrigin: z.ZodURL;
+            hasVerify: z.ZodBoolean;
+            resultDelivery: z.ZodEnum<{
+                agent: "agent";
+                endpoint: "endpoint";
+                both: "both";
+            }>;
+        }, z.core.$strip>>;
+        inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
     sharedShapes: z.ZodArray<z.ZodObject<{
         ref: z.ZodString;
@@ -207,12 +314,16 @@ export declare const searchKnowledgeResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const executeRequestSchema: z.ZodObject<{
     input: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    phase: z.ZodOptional<z.ZodEnum<{
+        verify: "verify";
+        initiate: "initiate";
+    }>>;
     context: z.ZodOptional<z.ZodObject<{
         threadId: z.ZodOptional<z.ZodString>;
         userId: z.ZodOptional<z.ZodString>;
         locale: z.ZodOptional<z.ZodEnum<{
-            en: "en";
             ar: "ar";
+            en: "en";
         }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -270,6 +381,7 @@ export declare const runtimeErrorSchema: z.ZodObject<{
         upstreamStatus: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+export type ToolInteraction = z.infer<typeof toolInteractionSchema>;
 export type RuntimeAgentConfig = z.infer<typeof runtimeAgentConfigSchema>;
 export type ResolveRequest = z.input<typeof resolveRequestSchema>;
 export type ResolveResponse = z.infer<typeof resolveResponseSchema>;

package/dist/contracts/wire.d.ts

@@ -50,12 +50,28 @@ export type TokenUsage = {
     };
     total: number;
 };
+/**
+ * How to launch one interactive tool: stamped by the server, per tool name, on
+ * the metadata of an assistant message that may carry its pending call. Kept in
+ * the message so the binding survives server restarts while a run is parked.
+ */
+export type InteractiveToolBinding = {
+    toolId: string;
+    surface: "inline" | "modal";
+    embedOrigin: string;
+    hasVerify: boolean;
+    resultDelivery: "agent" | "endpoint" | "both";
+};
 export type MessageMetadata = {
     modelId?: string;
     providerMetadata?: unknown;
     isAborted?: boolean;
     tokenUsage?: TokenUsage;
     attachments?: AttachmentSummary[];
+    interactiveTools?: Record<string, InteractiveToolBinding>;
+    /** Per tool call: the trusted reference its initiate call returned. A
+     * verified completion must match it — the browser's word is never enough. */
+    interactiveReferences?: Record<string, string>;
 };
 /**
  * A stored message as it is persisted and served. TanStack AI's `UIMessage`
@@ -71,6 +87,20 @@ export type CortexMessage<TPart = unknown> = {
     parts: TPart[];
     metadata?: MessageMetadata;
 };
+/**
+ * Response of `POST /chat/:chatId/tools/:toolCallId/initiate`. `interactive:
+ * false` means the pending call is not an interactive CC tool — the widget
+ * falls back to its default rendering for the call. The payload is for the
+ * widget only; it never reaches the LLM.
+ */
+export type InteractiveInitiateResult = {
+    interactive: false;
+} | {
+    interactive: true;
+    embedUrl: string;
+    surface: "inline" | "modal";
+    embedOrigin: string;
+};
 export type ThreadCreatedEvent = {
     type: "thread:created";
     payload: {

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

@@ -34,6 +34,13 @@ export type DatabaseAdapter = {
         upsert(threadId: string, 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(requests: {

package/dist/src/lib/adapters/database/message-content.d.ts

@@ -16,6 +16,8 @@ export declare function withOwnedAttachments(messages: ChatMessage[], replaceAtt
         providerMetadata?: unknown;
         isAborted?: boolean;
         tokenUsage?: import("../../types").TokenUsage;
+        interactiveTools?: Record<string, import("../..").InteractiveToolBinding>;
+        interactiveReferences?: Record<string, string>;
     };
     id: string;
     role: "system" | "user" | "assistant";

package/dist/src/lib/adapters/database/mssql/index.d.ts

@@ -76,6 +76,7 @@ export declare function createMssqlAdapter(connectionString: string, storage?: S
         upsert(threadId: string, messagesToUpsert: import("../../../types").ChatMessage[], options?: {
             replaceAttachments?: boolean;
         }): Promise<void>;
+        mergeInteractiveReference(threadId: string, messageId: string, toolCallId: string, reference: string): Promise<void>;
     };
     llmRequests: {
         insert(requests: {

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

@@ -34,4 +34,5 @@ export declare function createMessagesRepository(db: MssqlDb): {
     upsert(threadId: string, messagesToUpsert: ChatMessage[], options?: {
         replaceAttachments?: boolean;
     }): Promise<void>;
+    mergeInteractiveReference(threadId: string, messageId: string, toolCallId: string, reference: string): Promise<void>;
 };

package/dist/src/lib/adapters/database/postgres/index.d.ts

@@ -76,6 +76,7 @@ export declare function createPostgresAdapter(connectionString: string, storage?
         upsert(threadId: string, messagesToUpsert: import("../../../types").ChatMessage[], options?: {
             replaceAttachments?: boolean;
         }): Promise<void>;
+        mergeInteractiveReference(threadId: string, messageId: string, toolCallId: string, reference: string): Promise<void>;
     };
     llmRequests: {
         insert(requests: {

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

@@ -34,4 +34,5 @@ export declare function createMessagesRepository(db: PostgresDb): {
     upsert(threadId: string, messagesToUpsert: ChatMessage[], options?: {
         replaceAttachments?: boolean;
     }): Promise<void>;
+    mergeInteractiveReference(threadId: string, messageId: string, toolCallId: string, reference: string): Promise<void>;
 };

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

@@ -1,7 +1,7 @@
 import type { ResolvedCortexAgentConfig } from "../config";
 import type { Thread } from "../types";
 import type { ControlCenterClient } from "../cc/client";
-import type { CcToolRegistry } from "../cc/registry";
+import type { CcInteractiveTool, CcToolRegistry } from "../cc/registry";
 import type { ResolveResponse, RuntimeAgentConfig } from "../cc/types";
 type CcRuntimeOptions = {
     ccClient: ControlCenterClient | null;
@@ -31,9 +31,9 @@ export declare function createCcRuntime(options: CcRuntimeOptions): {
     config: {
         agentId: string;
         systemPrompt: string;
-        promptVariables: ("userName" | "channel" | "locale")[];
+        promptVariables: ("userName" | "channel" | "locale" | "utcTime" | "timezone")[];
         catalogBlurb: string;
-        defaultLocale: "en" | "ar";
+        defaultLocale: "ar" | "en";
         metaTools: {
             searchKnowledge: boolean;
             searchTools: boolean;
@@ -48,10 +48,11 @@ export declare function createCcRuntime(options: CcRuntimeOptions): {
         publishedAt: string;
     };
     registry: CcToolRegistry;
+    interactiveTools: Map<string, CcInteractiveTool>;
     threadId: string;
     turnKey: string;
     userId: string;
-    locale: "en" | "ar";
+    locale: "ar" | "en";
     endUserToken: string;
     abortSignal: AbortSignal;
     getStepIndex: () => number;

package/dist/src/lib/ai/interactive.d.ts

@@ -0,0 +1,62 @@
+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 interactive call can be initiated and verified 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 interactive. Undefined
+ * when nothing qualifies, keeping metadata lean.
+ */
+export declare function interactiveToolBindings(cc: CcRuntime | undefined, takenNames: ReadonlySet<string>): {
+    [k: string]: {
+        surface: "inline" | "modal";
+        embedOrigin: string;
+        hasVerify: boolean;
+        resultDelivery: "agent" | "endpoint" | "both";
+        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;
+/**
+ * `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.
+ */
+export declare function initiateInteractiveTool(options: {
+    config: ResolvedCortexAgentConfig;
+    thread: Thread;
+    userId: string;
+    token: string;
+    toolCallId: string;
+}): Promise<{
+    interactive: false;
+    embedUrl?: undefined;
+    surface?: undefined;
+    embedOrigin?: undefined;
+} | {
+    interactive: true;
+    embedUrl: string;
+    surface: "inline" | "modal";
+    embedOrigin: string;
+}>;
+/**
+ * The trust boundary for interactive results: whatever the client submitted
+ * for a bound tool call is replaced wholesale — cancelled/failed pass through
+ * normalized, completed is re-established by the tool's verify call when it
+ * has one, and result delivery masking is applied before the model reads it.
+ * Runs before the answering turn is persisted, so both the stored transcript
+ * and the model context carry only settled results.
+ */
+export declare function settleInteractiveToolResults(options: {
+    messages: ChatMessage[];
+    thread: Thread;
+    userId: string;
+    token: string;
+    config: ResolvedCortexAgentConfig;
+    ccClient: ControlCenterClient | null;
+}): Promise<void>;

package/dist/src/lib/ai/tools/search-common.d.ts

@@ -10,7 +10,7 @@ export declare function searchRequest(cc: CcRuntime, input: {
     query: string;
     limit?: number;
 }): {
-    locale: "en" | "ar";
+    locale: "ar" | "en";
     threadId: string;
     query: string;
     limit?: number;

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

@@ -35,5 +35,19 @@ export declare function createToolInstrumentation(options: TurnToolsOptions & {
     onBeforeToolCall(_ctx: import("@tanstack/ai").ChatMiddlewareContext<unknown>, { toolName, toolCallId, args }: import("@tanstack/ai").ToolCallHookContext): void;
     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
+ * 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.
+ */
+export declare function interactiveToolDeclarations(cc: CcRuntime | undefined, takenNames: ReadonlySet<string>): {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}[];
 export declare function hasDefaultAttachmentInterceptor(config: ResolvedCortexAgentConfig): boolean;
 export {};

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

@@ -8,6 +8,9 @@ export type ExecuteOptions = {
     turnKey: string;
     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. */
+    idempotencyKey?: string;
     timeoutMs?: number;
     abortSignal?: AbortSignal;
 };
@@ -30,9 +33,9 @@ export declare class ControlCenterClient {
         readonly config: {
             agentId: string;
             systemPrompt: string;
-            promptVariables: ("userName" | "channel" | "locale")[];
+            promptVariables: ("userName" | "channel" | "locale" | "utcTime" | "timezone")[];
             catalogBlurb: string;
-            defaultLocale: "en" | "ar";
+            defaultLocale: "ar" | "en";
             metaTools: {
                 searchKnowledge: boolean;
                 searchTools: boolean;
@@ -51,7 +54,7 @@ export declare class ControlCenterClient {
     resolve(agentId: string, request: ResolveRequest, abortSignal?: AbortSignal): Promise<{
         resolveId: string;
         catalogVersion: string;
-        locale: "en" | "ar";
+        locale: "ar" | "en";
         knowledge: {
             chunkId: string;
             text: string;
@@ -74,6 +77,13 @@ export declare class ControlCenterClient {
             signature: string;
             score: number | null;
             pinned: boolean;
+            interaction?: {
+                surface: "inline" | "modal";
+                embedOrigin: string;
+                hasVerify: boolean;
+                resultDelivery: "agent" | "endpoint" | "both";
+            } | undefined;
+            inputSchema?: Record<string, unknown> | undefined;
         }[];
         services: {
             serviceId: string;
@@ -103,6 +113,13 @@ export declare class ControlCenterClient {
             signature: string;
             score: number | null;
             pinned: boolean;
+            interaction?: {
+                surface: "inline" | "modal";
+                embedOrigin: string;
+                hasVerify: boolean;
+                resultDelivery: "agent" | "endpoint" | "both";
+            } | undefined;
+            inputSchema?: Record<string, unknown> | undefined;
         }[];
         sharedShapes: {
             ref: string;
@@ -127,6 +144,13 @@ export declare class ControlCenterClient {
             signature: string;
             score: number | null;
             pinned: boolean;
+            interaction?: {
+                surface: "inline" | "modal";
+                embedOrigin: string;
+                hasVerify: boolean;
+                resultDelivery: "agent" | "endpoint" | "both";
+            } | undefined;
+            inputSchema?: Record<string, unknown> | undefined;
         }[];
         sharedShapes: {
             ref: string;

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

@@ -2,9 +2,9 @@ import type { ControlCenterClient } from "./client";
 export declare function getControlCenterConfig(cc: ControlCenterClient, agentId: string, abortSignal?: AbortSignal): Promise<{
     agentId: string;
     systemPrompt: string;
-    promptVariables: ("userName" | "channel" | "locale")[];
+    promptVariables: ("userName" | "channel" | "locale" | "utcTime" | "timezone")[];
     catalogBlurb: string;
-    defaultLocale: "en" | "ar";
+    defaultLocale: "ar" | "en";
     metaTools: {
         searchKnowledge: boolean;
         searchTools: boolean;

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, ToolInteraction } from "./types";
 export type CcToolBinding = {
     toolId: string;
     readOnly: boolean;
 };
+/**
+ * An interactive 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 = {
+    toolId: string;
+    signature: string;
+    interaction: ToolInteraction;
+    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;
+    interaction?: ToolInteraction;
 }[]): 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;
+    interactiveTools: Map<string, CcInteractiveTool>;
     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 ToolInteraction, } from "../../../contracts/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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-server",
-    "version": "2.0.0",
+    "version": "2.1.0",
     "description": "Reusable AI agent chat server library for Hono + Bun",
     "license": "MIT",
     "type": "module",
@@ -74,5 +74,8 @@
     },
     "publishConfig": {
         "access": "public"
-    }
+    },
+    "releaseWatchPaths": [
+        "internal/contracts"
+    ]
 }

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

@@ -42,6 +42,18 @@ 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, type InferInsertModel } from "drizzle-orm";
+import { and, desc, eq, getColumns, inArray, sql, 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,5 +88,32 @@ 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"];
 }