@gea-ai/agent-sdk 0.1.260925-alpha.1 → 0.1.261003-alpha.0

package/dist/agent-core.js

@@ -7,6 +7,9 @@ let compiled;
 export function agentCore(options = {}) {
     return {
         ...options,
+        // A silent model stream must not retain a Run until the provider hard deadline.
+        // Explicit timeout options (including {}) retain caller-owned policy.
+        timeout: options.timeout ?? { chunkMs: 5 * 60_000 },
         output: options.output === undefined
             ? undefined
             : toAgentCoreOutput(options.output),

package/dist/agent-message-history.d.ts

@@ -0,0 +1,3 @@
+/** Old Core policy denials lacked the rejected approval required by AI SDK.
+ * Repair only their presentation; persisted Core decisions still own execution. */
+export declare function repairLegacyToolDenials(message: unknown): unknown;

package/dist/agent-message-history.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+const assistantHistorySchema = z
+    .object({
+    role: z.literal("assistant"),
+    parts: z.array(z.unknown()),
+})
+    .passthrough();
+const legacyDenialSchema = z
+    .object({
+    type: z.union([z.literal("dynamic-tool"), z.string().startsWith("tool-")]),
+    toolCallId: z.string(),
+    state: z.literal("output-denied"),
+    approval: z
+        .object({ id: z.string(), approved: z.literal(true) })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+/** Old Core policy denials lacked the rejected approval required by AI SDK.
+ * Repair only their presentation; persisted Core decisions still own execution. */
+export function repairLegacyToolDenials(message) {
+    const history = assistantHistorySchema.safeParse(message);
+    if (!history.success)
+        return message;
+    return {
+        ...history.data,
+        parts: history.data.parts.map((part) => {
+            const denied = legacyDenialSchema.safeParse(part);
+            return denied.success
+                ? {
+                    ...denied.data,
+                    state: "output-error",
+                    errorText: "Tool execution was denied by policy.",
+                }
+                : part;
+        }),
+    };
+}

package/dist/agent-remote-run.js

@@ -57,60 +57,114 @@ export async function cancelRemoteRun(fetch, run) {
     const response = await fetch(`/runs/${run.id}/cancel`, { method: "POST" });
     await responseJson(response);
 }
+class RemoteRunReadError extends TaggedError("RemoteRunReadError")() {
+}
+async function waitForRemoteRead(ms, signal) {
+    signal.throwIfAborted();
+    await new Promise((resolve, reject) => {
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", abort, { once: true });
+        if (signal.aborted)
+            abort();
+    });
+}
+/** Only idempotent reads retry. Admission and Tool execution are never repeated here. */
+async function readRemoteRunPage(fetch, path, signal) {
+    for (let attempt = 0;; attempt++) {
+        signal.throwIfAborted();
+        const response = await Result.tryPromise(() => fetch(path, { signal }));
+        signal.throwIfAborted();
+        let status;
+        let delay = 250 * 2 ** attempt;
+        if (response.isOk()) {
+            if (response.value.ok)
+                return response.value.json();
+            status = response.value.status;
+            const retryAfter = response.value.headers.get("retry-after");
+            if (retryAfter) {
+                const requestedDelay = /^\d+$/u.test(retryAfter)
+                    ? Number(retryAfter) * 1000
+                    : Date.parse(retryAfter) - Date.now();
+                if (Number.isFinite(requestedDelay))
+                    delay = Math.max(delay, requestedDelay);
+            }
+            await response.value.body?.cancel();
+        }
+        if (attempt >= 2 ||
+            delay > 5000 ||
+            (status !== undefined && status !== 408 && status !== 429 && status < 500))
+            throw new RemoteRunReadError({
+                message: "Remote Run read failed.",
+                status,
+            });
+        await waitForRemoteRead(delay, signal);
+    }
+}
 export async function observeRemoteRun(fetch, run, signal, onInputRequired) {
     let reportedInput;
-    while (true) {
-        signal.throwIfAborted();
-        const record = agentHttpRunSchema.parse(await responseJson(await fetch(`/runs/${run.id}`, { signal })));
-        if (record.id !== run.id || record.session_id !== run.sessionId)
-            throw new Error("Remote Run identity mismatch.");
-        const terminal = ["finished", "error", "aborted", "interrupted"].includes(record.status);
-        const inputMessageId = record.status === "waiting" ? record.input_message_id : null;
-        if (terminal || (onInputRequired && inputMessageId)) {
-            const text = [];
-            let cursor = null;
-            do {
-                const page = messagesSchema.parse(await responseJson(await fetch(`/sessions/${run.sessionId}/messages?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`, { signal })));
-                for (const message of page.items)
-                    if (message.run_id === run.id && message.role === "assistant") {
-                        if (!terminal && message.id === inputMessageId && onInputRequired) {
-                            const input = agentApplicationAssistantMessageSchema.parse({
-                                id: message.id,
-                                role: message.role,
-                                parts: message.parts,
-                            });
-                            const key = agentInputRequestKey(input);
-                            if (key !== reportedInput) {
-                                await onInputRequired(input);
-                                reportedInput = key;
+    try {
+        while (true) {
+            signal.throwIfAborted();
+            const record = agentHttpRunSchema.parse(await readRemoteRunPage(fetch, `/runs/${run.id}`, signal));
+            if (record.id !== run.id || record.session_id !== run.sessionId)
+                throw new Error("Remote Run identity mismatch.");
+            const terminal = ["finished", "error", "aborted", "interrupted"].includes(record.status);
+            const inputMessageId = record.status === "waiting" ? record.input_message_id : null;
+            if (terminal || (onInputRequired && inputMessageId)) {
+                const text = [];
+                let cursor = null;
+                do {
+                    const page = messagesSchema.parse(await readRemoteRunPage(fetch, `/sessions/${run.sessionId}/messages?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`, signal));
+                    for (const message of page.items)
+                        if (message.run_id === run.id && message.role === "assistant") {
+                            if (!terminal &&
+                                message.id === inputMessageId &&
+                                onInputRequired) {
+                                const input = agentApplicationAssistantMessageSchema.parse({
+                                    id: message.id,
+                                    role: message.role,
+                                    parts: message.parts,
+                                });
+                                const key = agentInputRequestKey(input);
+                                if (key !== reportedInput) {
+                                    await onInputRequired(input);
+                                    reportedInput = key;
+                                }
                             }
+                            for (const part of message.parts)
+                                if (part.type === "text" && typeof part.text === "string")
+                                    text.push(part.text);
                         }
-                        for (const part of message.parts)
-                            if (part.type === "text" && typeof part.text === "string")
-                                text.push(part.text);
-                    }
-                cursor = page.next_cursor;
-            } while (cursor);
-            if (terminal)
-                return {
-                    status: record.status,
-                    text: text.join("\n").slice(0, 200_000),
-                };
+                    cursor = page.next_cursor;
+                } while (cursor);
+                if (terminal)
+                    return {
+                        status: record.status,
+                        text: text.join("\n").slice(0, 200_000),
+                    };
+            }
+            if (!["queued", "running", "waiting"].includes(record.status))
+                throw new Error("Unknown remote Run status.");
+            await waitForRemoteRead(1000, signal);
         }
-        if (!["queued", "running", "waiting"].includes(record.status))
-            throw new Error("Unknown remote Run status.");
-        await new Promise((resolve, reject) => {
-            const abort = () => {
-                clearTimeout(timer);
-                reject(signal.reason);
-            };
-            const timer = setTimeout(() => {
-                signal.removeEventListener("abort", abort);
-                resolve();
-            }, 1000);
-            signal.addEventListener("abort", abort, { once: true });
-            if (signal.aborted)
-                abort();
-        });
+    }
+    catch (error) {
+        // Stop only this parent-owned observation. The remote execution/directory is untouched.
+        // Host shutdown leaves the relation pending so another dispatcher can resume it.
+        signal.throwIfAborted();
+        const status = RemoteRunReadError.is(error) && error.status
+            ? ` (HTTP ${error.status})`
+            : "";
+        return {
+            status: "interrupted",
+            text: `Remote observation interrupted${status}; execution outcome is unknown. Run ${run.id}, Session ${run.sessionId}. Do not resubmit the task; inspect this existing Run.`,
+        };
     }
 }

package/dist/agent-run-host.d.ts

@@ -20,7 +20,7 @@ export declare class AgentRunHost {
             response: Response;
             dispose?: () => void;
         }>;
-        cancelChild(run: AgentChildRun): Promise<void>;
+        cancelChild(run: AgentChildRun): Promise<boolean | void>;
         onError(error: unknown, identity?: {
             runId?: string;
             sessionId?: string;

package/dist/agent-run-host.js

@@ -161,9 +161,7 @@ export class AgentRunHost {
     dispatch(run, inboxExecution) {
         if (this.closed)
             throw new Error("Run dispatcher is stopping.");
-        if (this.executions.has(run.id) ||
-            run.outcome ||
-            (run.cancelRequested && run.destination.type !== "remote"))
+        if (this.executions.has(run.id) || run.outcome)
             return;
         const cancellation = new AbortController();
         this.executions.set(run.id, cancellation);
@@ -207,8 +205,18 @@ export class AgentRunHost {
                         });
                 }
                 else {
-                    cancellation.abort();
-                    return;
+                    // Keep admission alive until the Session has received cancellation.
+                    // Aborting the request earlier can strand an uninitialized child.
+                    const cancelled = await Result.tryPromise(() => this.host.cancelChild(run));
+                    if (cancelled.isOk() && cancelled.value !== false) {
+                        cancellation.abort();
+                        return;
+                    }
+                    if (cancelled.isErr())
+                        this.host.onError(cancelled.error, {
+                            runId: run.id,
+                            sessionId: run.sessionId,
+                        });
                 }
             }
             timer = setTimeout(() => {
@@ -284,8 +292,9 @@ export class AgentRunHost {
                 this.dispatch(run);
             }
             else {
-                this.executions.get(runId)?.abort();
-                await this.host.cancelChild(run);
+                this.dispatch(run);
+                if ((await this.host.cancelChild(run)) !== false)
+                    this.executions.get(runId)?.abort();
             }
         }
         return Response.json({

package/dist/agent-session-execution.js

@@ -444,6 +444,15 @@ export async function handleAgentSessionExecutionRequest(request, storage) {
                 handlerMs = performance.now() - handlerStartedAt;
                 return response;
             });
+            console.info("AgentSession lease release completed", {
+                event: "agent.session.lease_released",
+                runId: input.runId,
+                attemptId: input.attemptId,
+                executionId: input.inbox.executionId,
+                inputWait: Boolean(input.inbox.inputWait),
+                status: response.status,
+                elapsedMs: Math.round(performance.now() - startedAt),
+            });
             response.headers.set("server-timing", `session-handler;dur=${handlerMs.toFixed(1)}, session-transaction;dur=${(performance.now() - startedAt).toFixed(1)}`);
             return response;
         }
@@ -683,7 +692,15 @@ export async function handleAgentSessionExecutionRequest(request, storage) {
                 .parse(await readBody(request, storage));
             const result = await storage.transaction(async (tx) => {
                 const active = await tx.get(key("active-turn"));
-                if (!active || active.runId !== input.runId)
+                if (!active) {
+                    // A local logical Run can execute or wait without a managed lease. The
+                    // inbox still owns its descendants and fences cancellation by Run ID.
+                    const state = await getAgentSessionRunState(tx, input.runId);
+                    return {
+                        requested: state?.status === "waiting" || state?.status === "running",
+                    };
+                }
+                if (active.runId !== input.runId)
                     return { requested: false };
                 if (!active.cancelRequestedAt) {
                     const turn = {

package/dist/agent-session-inbox.js

@@ -467,6 +467,20 @@ async function finishInbox(tx, state, runs, input) {
             await save(tx, state, runs);
             return Response.json({ error: "execution_not_expired" }, { status: 409 });
         }
+        console.warn("AgentSession execution lease expired", {
+            event: "agent.session.lease_expired",
+            sessionId: state.identity.sessionId,
+            runId: turn.runId,
+            attemptId: turn.attemptId,
+            requestId: turn.requestId,
+            executionId: state.execution.id,
+            leaseOwner: turn.leaseOwner,
+            leaseExpiresAt: turn.leaseExpiresAt,
+            started: state.started,
+            waiting: state.wait !== null,
+            pendingChildren: runs.filter((run) => !run.outcome).length,
+            pendingStarts: state.pendingStarts.length,
+        });
     }
     if (inputWait && !outcome && !state.stopped) {
         state.inputWait = {

package/dist/agent-worker.d.ts

@@ -135,6 +135,7 @@ export type AgentToolRuntimeDefinition = {
             input: unknown;
             sdk: AgentToolRuntimeSdk;
         }): Promise<unknown>;
+        scriptRuntime?: ReturnType<typeof import("./script-tools").getScriptToolRuntime>;
         inputSchema: z.ZodType;
         toModelOutput?: import("./index").DefinedCustomTool["toModelOutput"];
     }>;

package/dist/agent-worker.js

@@ -1,6 +1,10 @@
+import { AGENT_WORKER_TOOL_METADATA_HEADER, AGENT_WORKER_TOOL_METADATA_VERSION, } from "@gea-ai/contract/agent-worker-tools";
+import { isAgentConnectorExposed } from "@gea-ai/contract/agent-packages";
+import { createCodeMode } from "./code-mode.js";
 import { AGENT_SUBAGENT_CONCURRENCY_HEADER } from "@gea-ai/contract/agent-worker-tools";
 import { DEFAULT_MAX_CONCURRENT_SUBAGENTS } from "@gea-ai/contract/agent-packages";
 import { batchAgentStreamEvents, coalesceAgentTextDeltas, } from "./agent-stream-coalescing.js";
+import { repairLegacyToolDenials } from "./agent-message-history.js";
 import { sendAgentSessionRequest } from "./agent-session-transport.js";
 import { agentSessionOverridesSchema } from "@gea-ai/contract/agent-session-overrides";
 import { resolveModelOptions } from "@gea-ai/contract/model-options";
@@ -184,7 +188,11 @@ async function runPreparedConnectorAuthorization(input, environment) {
     }
     const [identityValue, initializationValue] = await Promise.all([
         requireHostJson(environment.IDENTITY, "/context"),
-        requireHostJson(environment.TOOLS, "/tools/initialize"),
+        requireHostJson(environment.TOOLS, "/tools/initialize", {
+            headers: {
+                [AGENT_WORKER_TOOL_METADATA_HEADER]: AGENT_WORKER_TOOL_METADATA_VERSION,
+            },
+        }),
     ]);
     const identity = agentToolIdentitySchema.parse(identityValue);
     const initialization = agentWorkerToolInitializationSchema.parse(initializationValue);
@@ -299,6 +307,7 @@ async function runPreparedAgent(runtime, agentKey, request, environment, startup
                     "content-type": "application/json",
                     "x-gea-agent-runs": "1",
                     "x-gea-session-inbox": "1",
+                    [AGENT_WORKER_TOOL_METADATA_HEADER]: AGENT_WORKER_TOOL_METADATA_VERSION,
                     ...Object.fromEntries([...request.headers.entries()].filter(([name]) => ["traceparent", "tracestate", "x-gea-request-id"].includes(name))),
                 },
                 body: JSON.stringify({ metadata: parsed.data.metadata }),
@@ -2184,6 +2193,7 @@ function createHostBackedAgentTools(input) {
             execute: async (toolInput, options) => await invokeHostTool({
                 host: input.host,
                 messages: options.messages,
+                signal: options.abortSignal,
                 toolCallId: options.toolCallId,
                 toolInput,
                 toolName: definition.hostToolName ?? name,
@@ -2250,7 +2260,7 @@ function createHostBackedAgentTools(input) {
             continue;
         }
         const declaredOperation = grant.definition.operations.find((operation) => operation.name === descriptor.operation);
-        if (!grant.exposeToModel ||
+        if (!isAgentConnectorExposed(grant, input.snapshot.codeMode) ||
             (grant.definition.runtime.type !== "mcp" && !declaredOperation)) {
             throw new Error("Agent Worker Connector operation is not granted.");
         }
@@ -2264,11 +2274,21 @@ function createHostBackedAgentTools(input) {
                 .join("\n"),
             inputSchema: jsonSchema(descriptor.inputSchema),
             ...(grant.definition.runtime.type === "mcp"
-                ? { toModelOutput: mcpToolModelOutput }
+                ? {
+                    toModelOutput: mcpToolModelOutput,
+                    ...(descriptor.outputSchema === undefined
+                        ? {}
+                        : {
+                            providerOptions: {
+                                gea: { mcpOutputSchema: descriptor.outputSchema },
+                            },
+                        }),
+                }
                 : {}),
             execute: async (toolInput, options) => await invokeHostTool({
                 host: input.host,
                 messages: options.messages,
+                signal: options.abortSignal,
                 toolCallId: options.toolCallId,
                 toolInput,
                 toolName,
@@ -3089,7 +3109,10 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
                 !!Object.keys(input.snapshot.agentReferences ?? {}).length ||
                 requiresToolInitialization(input.snapshot, input.hookRuntime)
                 ? startupTracing.withSpan("agent.startup.tools", () => requireHostJson(host, "/tools/initialize", {
-                    headers: { "x-gea-agent-runs": "1" },
+                    headers: {
+                        "x-gea-agent-runs": "1",
+                        [AGENT_WORKER_TOOL_METADATA_HEADER]: AGENT_WORKER_TOOL_METADATA_VERSION,
+                    },
                 }).then((value) => agentWorkerToolInitializationSchema.parse(value)))
                 : Promise.resolve(agentWorkerToolInitializationSchema.parse({
                     connectors: [],
@@ -3146,13 +3169,19 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
     const submittedUser = payload.currentTurn.some((message) => message.role === "user")
         ? inputUser
         : undefined;
-    if (input.inboxExecution && submittedUser)
-        await appendSessionValue({
-            body: { message: submittedUser, runId: payload.runId },
-            chatId: payload.chatId,
-            namespace: input.sessionNamespace,
-            path: "/v1/messages",
-        });
+    if (input.inboxExecution && submittedUser) {
+        if (sessionExecution) {
+            await mutateSession({ messages: [{ ...submittedUser }] });
+        }
+        else {
+            await appendSessionValue({
+                body: { message: submittedUser, runId: payload.runId },
+                chatId: payload.chatId,
+                namespace: input.sessionNamespace,
+                path: "/v1/messages",
+            });
+        }
+    }
     // Tool continuations still need the current user's durable file references
     // when reconstructing model messages from saved UI history.
     const submittedFiles = inputUser?.parts.flatMap((part) => (part.type === "file" ? [part] : [])) ??
@@ -3306,7 +3335,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
         if (!runtime) {
             throw new Error(`Custom Connector runtime is missing: ${definition.alias}`);
         }
-        if (!definition.exposeToModel)
+        if (!isAgentConnectorExposed(definition, input.snapshot.codeMode))
             continue;
         if (definition.authorization === "interactive") {
             registerAgentWorkerTool(tools, `${definition.alias}__connect`, tool({
@@ -3615,7 +3644,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
             schema: z.object({ message: z.unknown() }),
         });
         const [message] = await validateUIMessages({
-            messages: [saved.message],
+            messages: [repairLegacyToolDenials(saved.message)],
         });
         if (!message || message.role !== "assistant")
             throw new Error("Suspended response is not an assistant message.");
@@ -3740,14 +3769,9 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
             .filter((file) => file.mediaType.startsWith("image/"))
             .map(({ url: _url, ...file }) => file);
     const turnImages = new Map();
-    const addImage = async (file) => {
-        const reference = file.id ?? file.key;
-        if (turnImages.has(reference))
-            return;
+    const readImage = async (file) => {
         if (!artifactScope)
             throw new Error("Images require Agent Artifacts.");
-        if (turnImages.size >= MAX_AGENT_ARTIFACT_IMAGES)
-            throw new Error(`At most ${MAX_AGENT_ARTIFACT_IMAGES} images can be viewed in one user turn.`);
         const response = await host.fetch(`${HOST_PATH}/tools/attachments/read`, {
             method: "POST",
             headers: { "content-type": "application/json" },
@@ -3762,11 +3786,19 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
         const bytes = new Uint8Array(await response.arrayBuffer());
         if (bytes.byteLength > MAX_AGENT_ARTIFACT_IMAGE_BYTES)
             throw new Error("Prepared image exceeds the model image limit.");
-        turnImages.set(reference, {
+        return {
             type: "file",
             data: { type: "data", data: bytes },
             mediaType: response.headers.get("content-type") ?? file.mediaType,
-        });
+        };
+    };
+    const addImage = async (file) => {
+        const reference = file.id ?? file.key;
+        if (turnImages.has(reference))
+            return;
+        if (turnImages.size >= MAX_AGENT_ARTIFACT_IMAGES)
+            throw new Error(`At most ${MAX_AGENT_ARTIFACT_IMAGES} images can be viewed in one user turn.`);
+        turnImages.set(reference, await readImage(file));
         context.metadata.turnImages ??= [];
         if (!context.metadata.turnImages.some((image) => (image.id ?? image.key) === reference))
             context.metadata.turnImages.push(file);
@@ -4040,12 +4072,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
     const coreConnections = new Map([[configuredModel, coreConnection]]);
     const coreCacheStates = new Map([[configuredModel, promptCacheState]]);
     const preparePrompt = async (messages) => {
-        messages = await resolveToolArtifacts(messages, (toolName, toolCallId) => artifactScope
-            ? createAgentArtifacts({
-                scope: artifactScope,
-                invoke: (operation) => invokeArtifact(operation, toolName, { toolCallId }),
-            })
-            : undefined);
+        messages = await resolveToolArtifacts(messages, (id, mediaType) => readImage({ id, mediaType }));
         const instructionCount = payload.instructions.length;
         const prepared = addCacheControlToMessages([...payload.instructions, ...messages], (coreModel === configuredModel
             ? payload.cacheControlProvider
@@ -4293,6 +4320,33 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
             },
         };
     };
+    if (input.snapshot.codeMode) {
+        const configured = await createCodeMode({
+            scriptRuntime: input.toolRuntime.actions.executeJavaScript?.scriptRuntime,
+            scriptToolNames: Object.entries(input.toolRuntime.actions)
+                .filter(([, action]) => action.scriptRuntime)
+                .map(([name]) => name),
+            readArtifact: artifactScope
+                ? async (id, execution) => createAgentArtifacts({
+                    scope: artifactScope,
+                    invoke: (operation) => invokeArtifact(operation, "executeJavaScript", execution),
+                }).readText({ id })
+                : undefined,
+            tools,
+            snapshot: input.snapshot,
+            approval: toolApproval,
+            messages: () => context.messages,
+            guardrail: engine?.guardrail,
+            sdk: {
+                tracing: createAgentTracing(),
+                auth: initialization.runtime.auth,
+                env: agentEnvironment,
+                environment: initialization.runtime.environment,
+                identity,
+            },
+        });
+        tools = configured.tools;
+    }
     let stream;
     if (engine) {
         if (!coreConnection || !coreModule)
@@ -4657,6 +4711,7 @@ async function executeAgentWorkerRequest(input, waitUntil, ownComputer, ownSessi
             async execute({ writer }) {
                 for await (const chunk of projectAgentCoreEvents(tracked, {
                     messageId,
+                    approvals: pending?.pendingStep.approvals,
                     tools,
                     messageMetadata: {
                         trace: invocationTrace,

package/dist/code-mode-discovery.d.ts

@@ -0,0 +1,38 @@
+import type { AgentToolNamespace } from "@gea-ai/contract/agent-packages";
+export type CodeModeCatalogEntry = {
+    name: string;
+    namespace: string;
+    description: string;
+    inputSchema: unknown;
+    outputSchema?: unknown;
+    structuredContentSchema?: unknown;
+    declaration: string;
+    mcp: boolean;
+};
+type Namespace = AgentToolNamespace & {
+    name: string;
+};
+/** Bounded hints, never a substitute for validation by the original tool schema. */
+export declare function codeModeDeclaration(name: string, input: unknown, output: unknown, mcp: boolean): string;
+/** Pi-compatible helper shapes, implemented against the GEA callable snapshot. */
+export declare function createCodeModeDiscovery(catalog: CodeModeCatalogEntry[], namespaces: Namespace[]): {
+    allTools: {
+        name: string;
+        description: string;
+    }[];
+    searchTools(query: string, options?: {
+        limit?: number;
+        namespace?: string | null;
+    } | null): {
+        name: string;
+        description: string;
+    }[];
+    describeTool(name: string): string | undefined;
+    describeNamespace(name: string): {
+        description?: string | undefined;
+        instructions?: string | undefined;
+        name: string;
+        tools: string[];
+    } | undefined;
+};
+export {};