@m6d/cortex-server 2.0.1 → 2.2.0

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 } =
@@ -110,6 +112,26 @@ export function createToolInstrumentation(
     } satisfies ChatMiddleware;
 }
 
+/**
+ * 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 function clientToolDeclarations(cc: CcRuntime | undefined, takenNames: ReadonlySet<string>) {
+    if (!cc) return [];
+    return [...cc.clientTools]
+        .filter(([name]) => !takenNames.has(name))
+        .map(([name, tool]) => ({
+            name,
+            description: tool.signature,
+            parameters: tool.inputSchema ?? { type: "object", additionalProperties: true },
+        }));
+}
+
 function createCcTools(cc: CcRuntime | undefined) {
     if (!cc) return [];
 

package/src/lib/cc/client.ts

@@ -21,6 +21,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;
 };
@@ -138,7 +141,8 @@ export class ControlCenterClient {
             if (!options.readOnly) {
                 headers.set(
                     "Idempotency-Key",
-                    `${options.threadId}:${options.turnKey}:${options.stepIndex}:${options.callIndex}`,
+                    options.idempotencyKey ??
+                        `${options.threadId}:${options.turnKey}:${options.stepIndex}:${options.callIndex}`,
                 );
             }
 

package/src/lib/cc/format.ts

@@ -74,10 +74,13 @@ export function buildCcSection(cc: CcPromptInput) {
         if (cc.resolved.sharedShapes.length > 0) {
             parts.push(`## Response Shapes\n${formatSharedShapes(cc.resolved.sharedShapes)}`);
         }
-        if (cc.resolved.tools.length > 0) {
+        // 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.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" +
-                    formatToolSignatures(cc.resolved.tools),
+                    formatToolSignatures(dynamicTools),
             );
         }
         if (cc.resolved.services.length > 0) {

package/src/lib/cc/registry.ts

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

package/src/lib/cc/types.ts

@@ -17,6 +17,7 @@ export {
     type ResolveResponse,
     type RuntimeAgentConfig,
     type SearchRequest,
+    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,6 +6,7 @@ import { HTTPException } from "hono/http-exception";
 import type { CortexAppEnv } from "@/types";
 import { requireAuth } from "@/auth/middleware";
 import { startTurn } from "@/ai/index";
+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";
@@ -91,6 +92,28 @@ export function createChatRoutes() {
         return resumeServerSentEventsResponse({ adapter: joinLog(chatId, runId) });
     });
 
+    /**
+     * 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) {
+        const config = c.get("agentConfig");
+        const { id: userId, token } = c.get("user");
+        const thread = await requireOwnedThread(c, c.req.param("chatId"));
+
+        return c.json(
+            await initiateClientTool({
+                config,
+                thread,
+                userId,
+                token,
+                toolCallId: c.req.param("toolCallId"),
+            }),
+        );
+    });
+
     app.post("/chat/:chatId/abort", requireAuth, async function (c) {
         const agentId = c.get("agentId");
         const userId = c.get("user").id;

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

package/contracts/graph.ts

@@ -1,36 +0,0 @@
-/**
- * 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 "./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";