@m6d/cortex-server 2.0.1 → 2.2.0

package/README.md

@@ -64,6 +64,30 @@ Only `database`, `model`, and `agents` are required for a minimal setup. `storag
 
 Each key in `agents` becomes a route prefix (e.g. `assistant` → `/agents/assistant/...`). Agents can define per-agent `systemPrompt`, `tools`, `backendFetch`, `loadSessionData`, `resolveRequestContext`, and lifecycle hooks (`onToolCall`, `onStreamFinish`).
 
+## Client tools
+
+A tool in an agent's `tools` with an `execute` function runs on the server. One
+without is a static client tool: it is declared to the model, the call streams
+to the widget, and the host app answers it via `hooks.onToolCall` (or a
+`toolComponents` entry calling `setOutput`).
+
+```ts
+const getBrowserTimezone = toolDefinition({
+    name: "getBrowserTimezone",
+    description: "Read the user's IANA time zone from their browser.",
+    inputSchema: z.object({}),
+}).client();
+// agents.sample.tools = [getBrowserTimezone]
+```
+
+Control-Center tools published with type "embedded" are the dynamic client
+tools: declared the same way, but the widget first calls
+`POST /chat/:chatId/tools/:toolCallId/initiate`, which runs the tool's endpoint
+server-to-server and hands the widget its embed payload (never the model).
+The result the embedded page reports back is relayed to the agent as-is —
+verifying it is the integrating backend's job. See
+`apps/cortex-cc/docs/client-tools.md` for authoring them.
+
 ## Requirements
 
 - Bun >= 1.0.0

package/contracts/README.md

@@ -4,18 +4,32 @@ The shapes both sides of a cortex boundary must agree on. Private on purpose —
 it never publishes; each publishable package carries its own copy:
 
 - `@m6d/cortex-server` and `@m6d/cortex-cli` publish raw source, so their
-  `prepack` vendors a copy of this directory into the tarball (`contracts/` and
+  `prepack` vendors a copy of `src/` into the tarball (`contracts/src/` and
   `src/contracts/` respectively), resolved there by their shipped tsconfig paths.
 - `@m6d/cortex-angular` and `@m6d/cortex-react` compile the parts they import
-  into their build artifacts.
+  into their build artifacts (angular's `vendor` copies the seam directories
+  into `src/internal/`).
 
-Three boundaries, one subpath each:
+## Layout
 
-| import                      | boundary                                                      |
-| --------------------------- | ------------------------------------------------------------- |
-| `@cortex/contracts/wire`    | chat client ↔ server (HTTP/WebSocket types)                   |
-| `@cortex/contracts/runtime` | cortex-cc console ↔ server runtime API (zod schemas)          |
-| `@cortex/contracts/graph`   | graph authoring (cli) ↔ server (vocabulary, helpers, clients) |
+Every seam is a directory: `src/<seam>/index.ts`, split into focused files
+under the directory where that helps (see `graph/`). The `exports` map is a
+single wildcard (`"./*": "./src/*/index.ts"`), so adding a seam is adding a
+directory — no manifest edit, no consumer tsconfig edit for wildcard-mapped
+consumers (server, cli, sample-server, cc).
+
+| import                           | boundary                                             | consumers                                               |
+| -------------------------------- | ---------------------------------------------------- | ------------------------------------------------------- |
+| `@cortex/contracts/wire`         | chat client ↔ server (HTTP/WebSocket types)          | server, client SDKs (`internal/client`, angular, react) |
+| `@cortex/contracts/client-tools` | embedded page ↔ chat widget handshake                | server, client SDKs                                     |
+| `@cortex/contracts/runtime`      | cortex-cc console ↔ server runtime API (zod schemas) | server, cortex-cc                                       |
+| `@cortex/contracts/rich-text`    | prompt/description grammar (mentions, variables)     | server, cortex-cc                                       |
+| `@cortex/contracts/graph`        | graph authoring (cli) ↔ server (vocabulary, helpers) | server, cortex-cli                                      |
+
+`src/graph/clients/` is the one deliberate exception to "contracts only":
+`neo4j.ts` and `embed.ts` are runtime I/O clients shared by the CLI and the
+server. They live here so there is exactly one copy, vendored the same way as
+everything else; they are re-exported through `@cortex/contracts/graph`.
 
 Everything is consumed as TypeScript source — no build, no dist. Nothing here
 has a runtime dependency beyond zod (for `/runtime`), and nothing here may grow

package/contracts/src/client-tools/index.ts

@@ -0,0 +1,56 @@
+/**
+ * The embed ↔ widget handshake for client tools.
+ *
+ * A page embedded by the chat widget (a hosted checkout, signing page, …)
+ * reports its outcome with:
+ *
+ *     window.parent.postMessage(
+ *         { type: "cortex:client-tool", status: "completed", reference: "session_123" },
+ *         "*",
+ *     );
+ *
+ * The widget accepts the message only when the event's origin matches the
+ * tool's configured `embedOrigin`. The payload is the page's claim, relayed to
+ * the agent as-is: cortex does not verify it, and anything that must actually
+ * be true lives in the integrating backend's own records.
+ *
+ * Like the wire seam, this file is compiled into the client SDKs and must stay
+ * free of runtime dependencies. It is also the spec any future SDK (Flutter)
+ * reimplements against.
+ */
+
+export const CLIENT_TOOL_MESSAGE_TYPE = "cortex:client-tool";
+
+export const CLIENT_TOOL_STATUSES = ["completed", "cancelled", "failed"] as const;
+
+export type ClientToolStatus = (typeof CLIENT_TOOL_STATUSES)[number];
+
+export type ClientToolHandshake = {
+    type: typeof CLIENT_TOOL_MESSAGE_TYPE;
+    status: ClientToolStatus;
+    /** Opaque id for the integrating backend's own bookkeeping (session id, envelope id, …). */
+    reference?: string;
+    /** Optional payload passed through to the agent as part of the tool result. */
+    result?: unknown;
+};
+
+/**
+ * Parse a `message` event into a handshake, or null when the origin doesn't
+ * match the tool's `embedOrigin` or the payload isn't a well-formed handshake.
+ * Call from the widget's `message` listener with `event.data` / `event.origin`.
+ */
+export function parseClientToolHandshake(data: unknown, origin: string, embedOrigin: string) {
+    if (origin !== embedOrigin) return null;
+    if (typeof data !== "object" || data === null) return null;
+    const message = data as Record<string, unknown>;
+    if (message["type"] !== CLIENT_TOOL_MESSAGE_TYPE) return null;
+    const status = CLIENT_TOOL_STATUSES.find((known) => known === message["status"]);
+    if (!status) return null;
+    const reference = message["reference"];
+    return {
+        type: CLIENT_TOOL_MESSAGE_TYPE,
+        status,
+        ...(typeof reference === "string" ? { reference } : {}),
+        ...(message["result"] !== undefined ? { result: message["result"] } : {}),
+    } satisfies ClientToolHandshake;
+}

package/contracts/src/graph/index.ts

@@ -0,0 +1,30 @@
+/**
+ * The graph contract — the knowledge-graph vocabulary, authoring types and
+ * clients that `@m6d/cortex-cli` writes with and `@m6d/cortex-server` reads
+ * with. `@m6d/cortex-server` re-exports all of it, so a project authoring
+ * domains still has exactly one import path.
+ */
+
+export type { GraphSchema } from "./schema";
+export { GRAPH_SCHEMA, GRAPH_SCHEMA_VERSION } from "./schema";
+
+export type {
+    EndpointScalarType,
+    EndpointProperty,
+    ResponseKind,
+    AutoGenerated,
+    ConceptDef,
+    EndpointDef,
+    EndpointInput,
+    ServiceDef,
+    RuleDef,
+    DomainDef,
+} from "./types";
+
+export { defineConcept, defineRule, defineService, defineDomain, defineEndpoint } from "./helpers";
+
+export type { Neo4jConfig, Neo4jClient } from "./clients/neo4j";
+export { createNeo4jClient } from "./clients/neo4j";
+
+export type { EmbedFn, EmbeddingProviderConfig } from "./clients/embed";
+export { createEmbedder } from "./clients/embed";

package/contracts/{runtime.ts → src/runtime/index.ts}

@@ -89,6 +89,18 @@ export const knowledgeChunkSchema = z.object({
     }),
 });
 
+/**
+ * Runtime contract §5.4: present on signatures of `embedded` 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);
+ * the result the page reports back is relayed as-is — verifying it is the
+ * integrating backend's job.
+ */
+export const toolEmbedSchema = z.object({
+    surface: z.enum(["inline", "modal"]),
+    embedOrigin: z.url(),
+});
+
 export const toolSignatureSchema = z.object({
     toolId: z.uuid(),
     name: z.string().regex(TOOL_NAME_PATTERN),
@@ -98,6 +110,11 @@ export const toolSignatureSchema = z.object({
     signature: z.string(),
     score: z.number().nullable(),
     pinned: z.boolean(),
+    embed: toolEmbedSchema.optional(),
+    /** Client tools only: the published input JSON Schema, verbatim.
+     * Client-executed declarations need a real schema — the rendered
+     * `signature` text alone is not enough for function calling. */
+    inputSchema: z.record(z.string(), z.unknown()).optional(),
 });
 
 export const serviceCardSchema = z.object({
@@ -236,6 +253,7 @@ export const runtimeErrorSchema = z.object({
     }),
 });
 
+export type ToolEmbed = z.infer<typeof toolEmbedSchema>;
 export type RuntimeAgentConfig = z.infer<typeof runtimeAgentConfigSchema>;
 export type ResolveRequest = z.input<typeof resolveRequestSchema>;
 export type ResolveResponse = z.infer<typeof resolveResponseSchema>;

package/contracts/{wire.ts → src/wire/index.ts}

@@ -70,12 +70,24 @@ export type TokenUsage = {
     total: number;
 };
 
+/**
+ * How to launch one client 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 ClientToolBinding = {
+    toolId: string;
+    surface: "inline" | "modal";
+    embedOrigin: string;
+};
+
 export type MessageMetadata = {
     modelId?: string;
     providerMetadata?: unknown;
     isAborted?: boolean;
     tokenUsage?: TokenUsage;
     attachments?: AttachmentSummary[];
+    clientTools?: Record<string, ClientToolBinding>;
 };
 
 /**
@@ -93,6 +105,38 @@ export type CortexMessage<TPart = unknown> = {
     metadata?: MessageMetadata;
 };
 
+/**
+ * Key under the AG-UI request's `forwardedProps` carrying the answers to
+ * parked client tool calls on a continuation request. The server owns the
+ * transcript (a continuation sends `messages: []`), so the answered assistant
+ * message itself never crosses the wire — the SDK's park-boundary snapshot
+ * does not preserve its id, and round-tripping it duplicated the stored
+ * message.
+ */
+export const CLIENT_TOOL_ANSWERS_KEY = "clientToolAnswers";
+
+/** One answered client tool call, applied to the stored transcript server-side. */
+export type ClientToolAnswer = {
+    toolCallId: string;
+    output: unknown;
+    state: "complete" | "error";
+};
+
+/**
+ * Response of `POST /chat/:chatId/tools/:toolCallId/initiate`. `embed:
+ * false` means the pending call is not a CC client 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 ClientToolInitiateResult =
+    | { embed: false }
+    | {
+          embed: true;
+          embedUrl: string;
+          surface: "inline" | "modal";
+          embedOrigin: string;
+      };
+
 export type ThreadCreatedEvent = {
     type: "thread:created";
     payload: { thread: ThreadSummary };

package/dist/contracts/{graph.d.ts → src/graph/index.d.ts}

@@ -4,11 +4,11 @@
  * with. `@m6d/cortex-server` re-exports all of it, so a project authoring
  * domains still has exactly one import path.
  */
-export type { GraphSchema } from "./graph/schema";
-export { GRAPH_SCHEMA, GRAPH_SCHEMA_VERSION } from "./graph/schema";
-export type { EndpointScalarType, EndpointProperty, ResponseKind, AutoGenerated, ConceptDef, EndpointDef, EndpointInput, ServiceDef, RuleDef, DomainDef, } from "./graph/types";
-export { defineConcept, defineRule, defineService, defineDomain, defineEndpoint, } from "./graph/helpers";
-export type { Neo4jConfig, Neo4jClient } from "./graph/neo4j";
-export { createNeo4jClient } from "./graph/neo4j";
-export type { EmbedFn, EmbeddingProviderConfig } from "./graph/embed";
-export { createEmbedder } from "./graph/embed";
+export type { GraphSchema } from "./schema";
+export { GRAPH_SCHEMA, GRAPH_SCHEMA_VERSION } from "./schema";
+export type { EndpointScalarType, EndpointProperty, ResponseKind, AutoGenerated, ConceptDef, EndpointDef, EndpointInput, ServiceDef, RuleDef, DomainDef, } from "./types";
+export { defineConcept, defineRule, defineService, defineDomain, defineEndpoint } from "./helpers";
+export type { Neo4jConfig, Neo4jClient } from "./clients/neo4j";
+export { createNeo4jClient } from "./clients/neo4j";
+export type { EmbedFn, EmbeddingProviderConfig } from "./clients/embed";
+export { createEmbedder } from "./clients/embed";

package/dist/contracts/{runtime.d.ts → src/runtime/index.d.ts}

@@ -60,6 +60,20 @@ 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 `embedded` 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);
+ * the result the page reports back is relayed as-is — verifying it is the
+ * integrating backend's job.
+ */
+export declare const toolEmbedSchema: z.ZodObject<{
+    surface: z.ZodEnum<{
+        inline: "inline";
+        modal: "modal";
+    }>;
+    embedOrigin: z.ZodURL;
+}, z.core.$strip>;
 export declare const toolSignatureSchema: z.ZodObject<{
     toolId: z.ZodUUID;
     name: z.ZodString;
@@ -69,6 +83,14 @@ export declare const toolSignatureSchema: z.ZodObject<{
     signature: z.ZodString;
     score: z.ZodNullable<z.ZodNumber>;
     pinned: z.ZodBoolean;
+    embed: z.ZodOptional<z.ZodObject<{
+        surface: z.ZodEnum<{
+            inline: "inline";
+            modal: "modal";
+        }>;
+        embedOrigin: z.ZodURL;
+    }, z.core.$strip>>;
+    inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 export declare const serviceCardSchema: z.ZodObject<{
     serviceId: z.ZodUUID;
@@ -152,6 +174,14 @@ export declare const resolveResponseSchema: z.ZodObject<{
         signature: z.ZodString;
         score: z.ZodNullable<z.ZodNumber>;
         pinned: z.ZodBoolean;
+        embed: z.ZodOptional<z.ZodObject<{
+            surface: z.ZodEnum<{
+                inline: "inline";
+                modal: "modal";
+            }>;
+            embedOrigin: z.ZodURL;
+        }, z.core.$strip>>;
+        inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
     services: z.ZodArray<z.ZodObject<{
         serviceId: z.ZodUUID;
@@ -191,6 +221,14 @@ export declare const searchToolsResponseSchema: z.ZodObject<{
         signature: z.ZodString;
         score: z.ZodNullable<z.ZodNumber>;
         pinned: z.ZodBoolean;
+        embed: z.ZodOptional<z.ZodObject<{
+            surface: z.ZodEnum<{
+                inline: "inline";
+                modal: "modal";
+            }>;
+            embedOrigin: z.ZodURL;
+        }, z.core.$strip>>;
+        inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
     sharedShapes: z.ZodArray<z.ZodObject<{
         ref: z.ZodString;
@@ -215,6 +253,14 @@ export declare const searchServicesResponseSchema: z.ZodObject<{
         signature: z.ZodString;
         score: z.ZodNullable<z.ZodNumber>;
         pinned: z.ZodBoolean;
+        embed: z.ZodOptional<z.ZodObject<{
+            surface: z.ZodEnum<{
+                inline: "inline";
+                modal: "modal";
+            }>;
+            embedOrigin: z.ZodURL;
+        }, z.core.$strip>>;
+        inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
     sharedShapes: z.ZodArray<z.ZodObject<{
         ref: z.ZodString;
@@ -302,6 +348,7 @@ export declare const runtimeErrorSchema: z.ZodObject<{
         upstreamStatus: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+export type ToolEmbed = z.infer<typeof toolEmbedSchema>;
 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 → src/wire/index.d.ts}

@@ -50,12 +50,23 @@ export type TokenUsage = {
     };
     total: number;
 };
+/**
+ * How to launch one client 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 ClientToolBinding = {
+    toolId: string;
+    surface: "inline" | "modal";
+    embedOrigin: string;
+};
 export type MessageMetadata = {
     modelId?: string;
     providerMetadata?: unknown;
     isAborted?: boolean;
     tokenUsage?: TokenUsage;
     attachments?: AttachmentSummary[];
+    clientTools?: Record<string, ClientToolBinding>;
 };
 /**
  * A stored message as it is persisted and served. TanStack AI's `UIMessage`
@@ -71,6 +82,35 @@ export type CortexMessage<TPart = unknown> = {
     parts: TPart[];
     metadata?: MessageMetadata;
 };
+/**
+ * Key under the AG-UI request's `forwardedProps` carrying the answers to
+ * parked client tool calls on a continuation request. The server owns the
+ * transcript (a continuation sends `messages: []`), so the answered assistant
+ * message itself never crosses the wire — the SDK's park-boundary snapshot
+ * does not preserve its id, and round-tripping it duplicated the stored
+ * message.
+ */
+export declare const CLIENT_TOOL_ANSWERS_KEY = "clientToolAnswers";
+/** One answered client tool call, applied to the stored transcript server-side. */
+export type ClientToolAnswer = {
+    toolCallId: string;
+    output: unknown;
+    state: "complete" | "error";
+};
+/**
+ * Response of `POST /chat/:chatId/tools/:toolCallId/initiate`. `embed:
+ * false` means the pending call is not a CC client 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 ClientToolInitiateResult = {
+    embed: false;
+} | {
+    embed: true;
+    embedUrl: string;
+    surface: "inline" | "modal";
+    embedOrigin: string;
+};
 export type ThreadCreatedEvent = {
     type: "thread:created";
     payload: {

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

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

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 { CcClientTool, CcToolRegistry } from "../cc/registry";
 import type { ResolveResponse, RuntimeAgentConfig } from "../cc/types";
 type CcRuntimeOptions = {
     ccClient: ControlCenterClient | null;
@@ -48,6 +48,7 @@ export declare function createCcRuntime(options: CcRuntimeOptions): {
         publishedAt: string;
     };
     registry: CcToolRegistry;
+    clientTools: Map<string, CcClientTool>;
     threadId: string;
     turnKey: string;
     userId: string;

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
@@ -35,5 +37,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;
+/**
+ * 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 client tools.
+ */
+export declare function clientToolDeclarations(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 initiate per tool call across reloads. */
+    idempotencyKey?: string;
     timeoutMs?: number;
     abortSignal?: AbortSignal;
 };
@@ -74,6 +77,11 @@ export declare class ControlCenterClient {
             signature: string;
             score: number | null;
             pinned: boolean;
+            embed?: {
+                surface: "inline" | "modal";
+                embedOrigin: string;
+            } | undefined;
+            inputSchema?: Record<string, unknown> | undefined;
         }[];
         services: {
             serviceId: string;
@@ -103,6 +111,11 @@ export declare class ControlCenterClient {
             signature: string;
             score: number | null;
             pinned: boolean;
+            embed?: {
+                surface: "inline" | "modal";
+                embedOrigin: string;
+            } | undefined;
+            inputSchema?: Record<string, unknown> | undefined;
         }[];
         sharedShapes: {
             ref: string;
@@ -127,6 +140,11 @@ export declare class ControlCenterClient {
             signature: string;
             score: number | null;
             pinned: boolean;
+            embed?: {
+                surface: "inline" | "modal";
+                embedOrigin: string;
+            } | undefined;
+            inputSchema?: Record<string, unknown> | undefined;
         }[];
         sharedShapes: {
             ref: string;