@m6d/cortex-server 2.0.0 → 2.1.0

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, type InferInsertModel } from "drizzle-orm";
+import { and, desc, eq, getColumns, inArray, sql, 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,5 +88,26 @@ 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 { CcRuntime, CcToolRegistry } from "@/cc/registry";
+import type { CcInteractiveTool, CcRuntime, CcToolRegistry } from "@/cc/registry";
 import { registerCcTools } from "@/cc/registry";
 import type { ResolveResponse, RuntimeAgentConfig } from "@/cc/types";
 
@@ -35,6 +35,20 @@ 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
+    // 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>();
+    for (const tool of ccResolved?.tools ?? []) {
+        if (!tool.interaction) continue;
+        interactiveTools.set(tool.name, {
+            toolId: tool.toolId,
+            signature: tool.signature,
+            interaction: tool.interaction,
+            inputSchema: tool.inputSchema,
+        });
+    }
+
     let currentStep = -1;
     let callIndex = 0;
 
@@ -43,6 +57,7 @@ export function createCcRuntime(options: CcRuntimeOptions) {
         agentId: config.agentId,
         config: ccConfig,
         registry,
+        interactiveTools,
         threadId: thread.id,
         turnKey: options.turnKey,
         userId,

package/src/lib/ai/index.ts

@@ -15,7 +15,6 @@ import type { ResolvedCortexAgentConfig, ToolSet } from "@/config";
 import type { ChatMessage, MessageMetadata, Thread } from "@/types";
 import { createModel } from "./helpers";
 import { buildSystemPrompt, resolveSession } from "./prompt";
-import { ControlCenterClient } from "@/cc/client";
 import { getControlCenterConfig } from "@/cc/config-cache";
 import { buildPromptVariables } from "@/cc/format";
 import { getRecentCcTools } from "@/cc/registry";
@@ -30,7 +29,13 @@ import {
     buildTurnTools,
     createToolInstrumentation,
     hasDefaultAttachmentInterceptor,
+    interactiveToolDeclarations,
 } from "./turn-tools";
+import {
+    createCcClient,
+    interactiveToolBindings,
+    settleInteractiveToolResults,
+} from "./interactive";
 import { createInspector } from "./inspector";
 import { commitBeforeTerminal } from "./commit-gate";
 import { finishTurn } from "./finish-turn";
@@ -63,6 +68,19 @@ export async function startTurn(
         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 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");
@@ -111,7 +129,7 @@ export async function startTurn(
         const turnKey = lastUserMessage?.id ?? "0";
 
         const inspector = createInspector();
-        const { model, embed, neo4j, ccClient } = createTurnProviders(config, inspector.fetch);
+        const { model, embed, neo4j } = createTurnProviders(config, inspector.fetch);
 
         // Run independent operations in parallel
         const [contextResult, resolved, session, ccConfig, ccResolved] = await Promise.all([
@@ -173,6 +191,10 @@ export async function startTurn(
             threadAttachments,
         };
         const tools = buildTurnTools(turnToolsOptions);
+        const consumerToolNames = new Set([
+            ...tools.map((tool) => tool.name),
+            ...params.tools.map((tool) => tool.name),
+        ]);
         const instrumentation = createToolInstrumentation({
             ...turnToolsOptions,
             onToolStart: (toolName, toolCallId) =>
@@ -190,6 +212,13 @@ export async function startTurn(
                       config: cc.config,
                       resolved: ccResolved,
                       variables: buildPromptVariables(cc.config.promptVariables, {
+                          // Computed per request; consumer-supplied context
+                          // with the same key wins via the spreads below. No
+                          // such default for `timezone`: the server's zone is
+                          // not the session's, so guessing would feed the
+                          // model wrong user context — only the consumer can
+                          // supply it.
+                          utcTime: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
                           ...session,
                           ...requestContext,
                           locale: cc.locale,
@@ -205,8 +234,13 @@ export async function startTurn(
         const stream = chat({
             adapter: model,
             // Client tool declarations ride in on every request, so the server
-            // never re-declares them.
-            tools: mergeAgentTools(tools, params.tools),
+            // never re-declares them. Interactive CC 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.
+            tools: mergeAgentTools(tools, [
+                ...params.tools,
+                ...interactiveToolDeclarations(cc, consumerToolNames),
+            ]),
             messages: convertMessagesToModelMessages(
                 fitToContextWindow(contextMessages, systemPrompt, tools, config),
             ),
@@ -258,6 +292,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),
                 } satisfies MessageMetadata,
             };
         }
@@ -331,7 +368,6 @@ function createTurnProviders(config: ResolvedCortexAgentConfig, fetch: typeof gl
         model: createModel(config.model, { fetch }),
         embed,
         neo4j: config.neo4j && embed ? createNeo4jClient(config.neo4j, embed) : undefined,
-        ccClient: config.controlCenter ? new ControlCenterClient(config.controlCenter) : null,
     };
 }
 

package/src/lib/ai/interactive.ts

@@ -0,0 +1,364 @@
+import { HTTPException } from "hono/http-exception";
+import type { InteractiveInitiateResult, MessageMetadata } from "@cortex/contracts/wire";
+import { INTERACTIVE_STATUSES } from "@cortex/contracts/interactive";
+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";
+
+type InteractiveBinding = NonNullable<MessageMetadata["interactiveTools"]>[string];
+
+/**
+ * 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 function interactiveToolBindings(
+    cc: CcRuntime | undefined,
+    takenNames: ReadonlySet<string>,
+) {
+    if (!cc) return undefined;
+    const entries = [...cc.interactiveTools]
+        .filter(([name]) => !takenNames.has(name))
+        .map(
+            ([name, tool]) =>
+                [
+                    name,
+                    { toolId: tool.toolId, ...tool.interaction } satisfies InteractiveBinding,
+                ] 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;
+}
+
+/** 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 findPendingInteractiveCall(
+    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.
+ */
+export async function initiateInteractiveTool(options: {
+    config: ResolvedCortexAgentConfig;
+    thread: Thread;
+    userId: string;
+    token: string;
+    toolCallId: string;
+}) {
+    const { config, thread, userId, token, toolCallId } = options;
+    const pending = await findPendingInteractiveCall(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?.interactiveTools?.[call.name];
+    const ccClient = createCcClient(config);
+    if (!binding || !ccClient) {
+        return { interactive: false } satisfies InteractiveInitiateResult;
+    }
+
+    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",
+        });
+    }
+
+    // Anchor the trusted reference to this call: a verified completion may
+    // only settle against the session this initiate created, never against
+    // whichever reference the browser chooses to report.
+    if (binding.hasVerify) {
+        const reference = asRecord(result.output)?.reference;
+        if (typeof reference !== "string" || !reference) {
+            throw new HTTPException(502, {
+                message: "initiate did not return the reference its verify endpoint needs",
+            });
+        }
+        await config.db.messages.mergeInteractiveReference(
+            thread.id,
+            message.id,
+            toolCallId,
+            reference,
+        );
+    }
+
+    return {
+        interactive: true,
+        embedUrl,
+        surface: binding.surface,
+        embedOrigin: binding.embedOrigin,
+    } satisfies InteractiveInitiateResult;
+}
+
+/**
+ * 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 async function settleInteractiveToolResults(options: {
+    messages: ChatMessage[];
+    thread: Thread;
+    userId: string;
+    token: string;
+    config: ResolvedCortexAgentConfig;
+    ccClient: ControlCenterClient | null;
+}) {
+    // Deliberately no early-out on a missing CC client: normalization must run
+    // for every bound result regardless — only the verify call needs CC, and
+    // without it a claimed completion fails rather than passing through.
+    const { messages, thread, userId, token, config, ccClient } = options;
+    const answering = messages.filter(
+        (message) =>
+            message.role === "assistant" &&
+            message.parts.some((part) => part.type === "tool-result"),
+    );
+    if (answering.length === 0) return;
+
+    const stored = await config.db.messages.list(userId, thread.id);
+    const storedMessages = stored.map((row) => row.content);
+    const pendingCalls = collectPendingCalls(storedMessages);
+    if (pendingCalls.size === 0) return;
+
+    const context = {
+        ccClient,
+        agentId: config.agentId,
+        threadId: thread.id,
+        userId,
+        token,
+        references: collectReferences(storedMessages),
+    };
+    for (const message of answering) {
+        await settleMessage(message, pendingCalls, context);
+    }
+}
+
+async function settleMessage(
+    message: ChatMessage,
+    pendingCalls: Map<string, PendingInteractiveCall>,
+    context: SettleContext,
+) {
+    for (const part of message.parts) {
+        if (part.type !== "tool-result") continue;
+        const pending = pendingCalls.get(part.toolCallId);
+        if (!pending) continue;
+
+        recordRecentCcTool(context.threadId, pending.name);
+        const settled = await settleOne(pending.binding, part.content, part.toolCallId, context);
+        part.content = JSON.stringify(settled);
+    }
+}
+
+type PendingInteractiveCall = { name: string; binding: InteractiveBinding };
+
+/**
+ * The authoritative view of what may settle: stored, unanswered tool calls
+ * whose own message carries a binding for their name, keyed by call id. The
+ * incoming message's tool-call parts are client-authored and never consulted —
+ * a fabricated call/result pair matches nothing here.
+ */
+function collectPendingCalls(messages: ChatMessage[]) {
+    const answered = answeredCallIds(messages);
+    const pending = new Map<string, PendingInteractiveCall>();
+    for (const message of messages) {
+        const bindings = message.metadata?.interactiveTools;
+        if (!bindings) continue;
+        for (const part of message.parts) {
+            if (part.type !== "tool-call" || answered.has(part.id)) continue;
+            const binding = bindings[part.name];
+            if (binding) pending.set(part.id, { name: part.name, binding });
+        }
+    }
+    return pending;
+}
+
+function answeredCallIds(messages: ChatMessage[]) {
+    const answered = new Set<string>();
+    for (const message of messages) {
+        for (const part of message.parts) {
+            if (part.type === "tool-result") answered.add(part.toolCallId);
+        }
+    }
+    return answered;
+}
+
+/** The references initiate anchored, keyed by tool call id. */
+function collectReferences(messages: ChatMessage[]) {
+    const references = new Map<string, string>();
+    for (const message of messages) {
+        for (const [toolCallId, reference] of Object.entries(
+            message.metadata?.interactiveReferences ?? {},
+        )) {
+            references.set(toolCallId, reference);
+        }
+    }
+    return references;
+}
+
+type SettleContext = {
+    ccClient: ControlCenterClient | null;
+    agentId: string;
+    threadId: string;
+    userId: string;
+    token: string;
+    references: Map<string, string>;
+};
+
+async function settleOne(
+    binding: InteractiveBinding,
+    content: string | unknown[],
+    toolCallId: string,
+    context: SettleContext,
+) {
+    const reported = parseReported(content);
+    if (reported.status === "cancelled") return { status: "cancelled" };
+    if (reported.status !== "completed") return { status: "failed" };
+
+    if (!binding.hasVerify) {
+        // A completion the server cannot re-establish is just the browser's
+        // word. Current Control Centers always configure verification, so this
+        // only fires against a foreign runtime — refuse rather than trust.
+        return { status: "failed", detail: "verification required" };
+    }
+    const anchored = context.references.get(toolCallId);
+    if (!anchored || reported.reference !== anchored) {
+        return { status: "failed", detail: "completion does not match the initiated session" };
+    }
+    if (!context.ccClient) {
+        return { status: "failed", detail: "verification unavailable" };
+    }
+
+    const result = await context.ccClient.execute(
+        context.agentId,
+        binding.toolId,
+        {
+            input: { reference: anchored },
+            phase: "verify",
+            context: { threadId: context.threadId, userId: context.userId },
+        },
+        {
+            readOnly: true,
+            endUserToken: context.token,
+            threadId: context.threadId,
+            turnKey: "verify",
+            stepIndex: 0,
+            callIndex: 0,
+        },
+    );
+    if (!result) return { status: "failed", detail: "verification unavailable" };
+    if ("error" in result) return { status: "failed", detail: result.error.kind };
+    return deliver(binding, reported.reference, result.output);
+}
+
+function deliver(binding: InteractiveBinding, reference: string | undefined, output: unknown) {
+    return binding.resultDelivery === "endpoint"
+        ? { status: "completed", reference }
+        : { status: "completed", reference, result: output };
+}
+
+function parseReported(content: string | unknown[]) {
+    const record = asRecord(typeof content === "string" ? parseJson(content) : content);
+    const status = INTERACTIVE_STATUSES.find((known) => known === record?.status);
+    return {
+        status,
+        reference: typeof record?.reference === "string" ? record.reference : undefined,
+    };
+}
+
+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/tools/search-tools.tool.ts

@@ -20,10 +20,14 @@ export function createSearchToolsTool(cc: CcRuntime) {
         if (!result) return "Tool search is temporarily unavailable. Try again later.";
 
         registerCcTools(cc.registry, result.tools);
-        if (result.tools.length === 0) return "No matching tools found.";
+        // Interactive 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);
+        if (callable.length === 0) return "No matching tools found.";
 
         const shapes =
             result.sharedShapes.length > 0 ? `${formatSharedShapes(result.sharedShapes)}\n\n` : "";
-        return shapes + formatToolSignatures(result.tools);
+        return shapes + formatToolSignatures(callable);
     });
 }

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

@@ -110,6 +110,29 @@ export function createToolInstrumentation(
     } satisfies ChatMiddleware;
 }
 
+/**
+ * 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 function interactiveToolDeclarations(
+    cc: CcRuntime | undefined,
+    takenNames: ReadonlySet<string>,
+) {
+    if (!cc) return [];
+    return [...cc.interactiveTools]
+        .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 interactive 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

@@ -1,3 +1,5 @@
+import { substituteVariables } from "@cortex/contracts/rich-text";
+
 import type { ResolveResponse, RuntimeAgentConfig } from "./types";
 
 type SharedShape = ResolveResponse["sharedShapes"][number];
@@ -5,12 +7,6 @@ type ToolSignature = ResolveResponse["tools"][number];
 type ServiceCard = ResolveResponse["services"][number];
 type KnowledgeChunk = ResolveResponse["knowledge"][number];
 
-function substitutePromptVariables(template: string, variables: Record<string, string>) {
-    return template.replace(/\{\{(\w+)\}\}/g, function replaceVariable(match, name: string) {
-        return variables[name] ?? match;
-    });
-}
-
 /** Values for the published prompt's `{{variable}}` placeholders, read from session/request context. */
 export function buildPromptVariables(
     promptVariables: RuntimeAgentConfig["promptVariables"],
@@ -67,7 +63,7 @@ export type CcPromptInput = {
 export function buildCcSection(cc: CcPromptInput) {
     const parts: string[] = [];
 
-    const prompt = substitutePromptVariables(cc.config.systemPrompt, cc.variables).trim();
+    const prompt = substituteVariables(cc.config.systemPrompt, cc.variables).trim();
     if (prompt) parts.push(prompt);
 
     if (cc.config.catalogBlurb) {
@@ -78,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) {
+        // Interactive 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);
+        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) {