@mcoda/codali 0.1.87 → 0.1.89

package/dist/runtime/CodaliRuntime.js

@@ -6,12 +6,14 @@ import { OllamaRemoteProvider } from "../providers/OllamaRemoteProvider.js";
 import { CodexCliProvider } from "../providers/CodexCliProvider.js";
 import { MswarmWorkerProvider } from "../providers/MswarmWorkerProvider.js";
 import { DocdexClient, normalizeDocdexRuntimeOperation, } from "../docdex/DocdexClient.js";
+import { AppToolGatewayDispatchError, dispatchAppToolGateway, } from "../gateway/AppToolGatewayDispatcher.js";
 import { createDiffTool } from "../tools/diff/DiffTool.js";
 import { createDocdexTools } from "../tools/docdex/DocdexTools.js";
 import { createFileTools } from "../tools/filesystem/FileTools.js";
 import { createSearchTool } from "../tools/search/SearchTool.js";
 import { createShellTool } from "../tools/shell/ShellTool.js";
 import { ToolRegistry } from "../tools/ToolRegistry.js";
+import { ToolExecutionError, } from "../tools/ToolTypes.js";
 import { formatInstructionBlocks, loadInstructionBlocks } from "../session/InstructionLoader.js";
 import { SessionStore } from "../session/SessionStore.js";
 import { SubagentOrchestrator, } from "../subagents/SubagentOrchestrator.js";
@@ -30,6 +32,33 @@ const WEB_TOOL_NAMES = new Set(["docdex_web_research"]);
 const MEMORY_WRITE_TOOL_NAMES = new Set(["docdex_memory_save"]);
 const PROFILE_WRITE_TOOL_NAMES = new Set(["docdex_save_preference"]);
 const INDEX_REBUILD_TOOL_NAMES = new Set(["docdex_index_rebuild", "docdex_index_ingest"]);
+const READ_ONLY_DYNAMIC_BACKING_TOOLS = new Set([
+    "docdex_search",
+    "docdex_batch_search",
+    "docdex_open",
+    "docdex_files",
+    "docdex_tree",
+    "docdex_stats",
+]);
+const FORBIDDEN_DYNAMIC_ARG_KEYS = new Set([
+    "authorization",
+    "apiKey",
+    "api_key",
+    "baseUrl",
+    "base_url",
+    "credential",
+    "credentials",
+    "credentialSource",
+    "credential_source",
+    "repoId",
+    "repo_id",
+    "repoRoot",
+    "repo_root",
+    "tenantId",
+    "tenant_id",
+    "workspaceRoot",
+    "workspace_root",
+]);
 const DOCDEX_TOOL_OPERATIONS = new Map([
     ["docdex_health", ["health"]],
     ["docdex_initialize", ["initialize"]],
@@ -103,6 +132,424 @@ const stripUndefined = (input) => {
 const isRecord = (value) => {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 };
+const createDynamicToolRegistryState = () => ({
+    consideredTools: [],
+    registeredDynamicTools: [],
+    skippedDynamicTools: [],
+    dynamicToolCalls: [],
+});
+const pushUnique = (target, value) => {
+    if (!target.includes(value))
+        target.push(value);
+};
+const recordSkippedDynamicTool = (state, name, reason) => {
+    if (!state.skippedDynamicTools.some((entry) => entry.name === name && entry.reason === reason)) {
+        state.skippedDynamicTools.push({ name, reason });
+    }
+};
+const stringArrayFromUnknown = (value) => {
+    if (Array.isArray(value)) {
+        return value.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+    }
+    if (typeof value === "string" && value.trim()) {
+        return [value.trim()];
+    }
+    return [];
+};
+const toolNameFromRecord = (value) => {
+    for (const key of ["name", "tool", "toolName", "tool_name", "id"]) {
+        const entry = value[key];
+        if (typeof entry === "string" && entry.trim())
+            return entry.trim();
+    }
+    return undefined;
+};
+const toolNamesFromManifestEntries = (entries) => {
+    if (!Array.isArray(entries))
+        return [];
+    const names = [];
+    for (const entry of entries) {
+        if (typeof entry === "string" && entry.trim()) {
+            pushUnique(names, entry.trim());
+            continue;
+        }
+        if (isRecord(entry)) {
+            const name = toolNameFromRecord(entry);
+            if (name)
+                pushUnique(names, name);
+        }
+    }
+    return names;
+};
+const toolNamesFromManifest = (manifest) => {
+    if (!manifest)
+        return [];
+    const names = [];
+    for (const list of [
+        manifest.actualTools,
+        manifest.virtualTools,
+        manifest.actual_tools,
+        manifest.virtual_tools,
+    ]) {
+        for (const name of toolNamesFromManifestEntries(list))
+            pushUnique(names, name);
+    }
+    return names;
+};
+const normalizeRuntimeToolContractEntries = (contracts) => {
+    if (!contracts)
+        return [];
+    if (Array.isArray(contracts)) {
+        const entries = [];
+        for (const contract of contracts) {
+            if (!isRecord(contract))
+                continue;
+            const name = toolNameFromRecord(contract);
+            if (name)
+                entries.push([name, contract]);
+        }
+        return entries;
+    }
+    if (!isRecord(contracts))
+        return [];
+    const entries = [];
+    for (const [key, value] of Object.entries(contracts)) {
+        if (!key.trim())
+            continue;
+        const contract = isRecord(value)
+            ? { name: key, ...value }
+            : { name: key, metadata: { valueType: typeof value } };
+        entries.push([key, contract]);
+    }
+    return entries;
+};
+const contractString = (contract, camelKey, snakeKey) => {
+    const value = contract[camelKey] ?? contract[snakeKey];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+};
+const contractBoolean = (contract, camelKey, snakeKey) => {
+    const value = contract[camelKey] ?? contract[snakeKey];
+    return typeof value === "boolean" ? value : undefined;
+};
+const contractStringArray = (contract, camelKey, snakeKey) => {
+    return stringArrayFromUnknown(contract[camelKey] ?? contract[snakeKey]);
+};
+const contractCallSchema = (contract) => {
+    const schema = contract.callSchema ?? contract.call_schema;
+    if (isRecord(schema) && (schema.type === undefined || schema.type === "object")) {
+        return {
+            ...schema,
+            type: "object",
+        };
+    }
+    return { type: "object", additionalProperties: true };
+};
+const findForbiddenDynamicArgKeys = (value, path = "$", matches = []) => {
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => findForbiddenDynamicArgKeys(entry, `${path}[${index}]`, matches));
+        return matches;
+    }
+    if (!isRecord(value))
+        return matches;
+    for (const [key, entry] of Object.entries(value)) {
+        const childPath = `${path}.${key}`;
+        if (FORBIDDEN_DYNAMIC_ARG_KEYS.has(key)) {
+            matches.push(childPath);
+        }
+        findForbiddenDynamicArgKeys(entry, childPath, matches);
+    }
+    return matches;
+};
+const assertDynamicArgsStayInScope = (toolName, args) => {
+    const forbidden = findForbiddenDynamicArgKeys(args);
+    if (forbidden.length) {
+        throw new ToolExecutionError("tool_permission_denied", "Dynamic tool arguments cannot override tenant or repo scope", {
+            retryable: false,
+            details: { tool: toolName, forbidden },
+        });
+    }
+};
+const readStringArg = (args, keys) => {
+    for (const key of keys) {
+        const value = args[key];
+        if (typeof value === "string" && value.trim())
+            return value.trim();
+    }
+    return undefined;
+};
+const readStringArrayArg = (args, keys) => {
+    for (const key of keys) {
+        const values = stringArrayFromUnknown(args[key]);
+        if (values.length)
+            return values;
+    }
+    return [];
+};
+const readNumberArg = (args, keys) => {
+    for (const key of keys) {
+        const value = args[key];
+        if (typeof value === "number" && Number.isFinite(value))
+            return value;
+    }
+    return undefined;
+};
+const readBooleanArg = (args, keys) => {
+    for (const key of keys) {
+        const value = args[key];
+        if (typeof value === "boolean")
+            return value;
+    }
+    return undefined;
+};
+const selectDocdexBackingCall = (toolName, backingTools, args) => {
+    const record = isRecord(args) ? args : {};
+    const limit = readNumberArg(record, ["limit", "maxResults", "max_results"]);
+    const queries = readStringArrayArg(record, ["queries"]);
+    if (queries.length && backingTools.includes("docdex_batch_search")) {
+        return {
+            toolName: "docdex_batch_search",
+            args: stripUndefined({
+                queries,
+                limit,
+                includeLibs: readBooleanArg(record, ["includeLibs", "include_libs"]),
+            }),
+        };
+    }
+    const query = readStringArg(record, ["query", "q", "search", "question", "prompt", "text"]);
+    if (query && backingTools.includes("docdex_search")) {
+        return { toolName: "docdex_search", args: stripUndefined({ query, limit }) };
+    }
+    const path = readStringArg(record, ["path", "relPath", "rel_path", "file", "sourcePath", "source_path"]);
+    const docId = readStringArg(record, ["docId", "doc_id"]);
+    if ((path || docId) && backingTools.includes("docdex_open")) {
+        return {
+            toolName: "docdex_open",
+            args: stripUndefined({
+                path,
+                docId,
+                window: readNumberArg(record, ["window"]),
+                textOnly: readBooleanArg(record, ["textOnly", "text_only"]),
+                startLine: readNumberArg(record, ["startLine", "start_line"]),
+                endLine: readNumberArg(record, ["endLine", "end_line"]),
+                head: readNumberArg(record, ["head"]),
+                clamp: readBooleanArg(record, ["clamp"]),
+            }),
+        };
+    }
+    if (backingTools.includes("docdex_tree")) {
+        return {
+            toolName: "docdex_tree",
+            args: stripUndefined({
+                path,
+                maxDepth: readNumberArg(record, ["maxDepth", "max_depth"]),
+                dirsOnly: readBooleanArg(record, ["dirsOnly", "dirs_only"]),
+                includeHidden: readBooleanArg(record, ["includeHidden", "include_hidden"]),
+            }),
+        };
+    }
+    if (backingTools.includes("docdex_files")) {
+        return {
+            toolName: "docdex_files",
+            args: stripUndefined({
+                limit,
+                offset: readNumberArg(record, ["offset"]),
+            }),
+        };
+    }
+    if (backingTools.includes("docdex_stats")) {
+        return { toolName: "docdex_stats", args: {} };
+    }
+    throw new ToolExecutionError("tool_invalid_args", "Dynamic tool arguments do not match its read-only backing tools", {
+        retryable: false,
+        details: { tool: toolName, backingTools },
+    });
+};
+const createDocdexBackedDynamicTool = (options) => {
+    const { name, contract, registry, backingTools, state } = options;
+    const executionMode = contractString(contract, "executionMode", "execution_mode") ?? "server_supplied_snapshot_plus_docdex";
+    return {
+        name,
+        description: contract.description ??
+            `Read-only runtime tool. Uses ${backingTools.join(", ")} and returns ${contract.resultContract ?? contract.result_contract ?? "contracted app context"}.`,
+        inputSchema: contractCallSchema(contract),
+        handler: async (args, context) => {
+            const startedAt = Date.now();
+            let backingTool;
+            let recorded = false;
+            try {
+                assertDynamicArgsStayInScope(name, args);
+                const backingCall = selectDocdexBackingCall(name, backingTools, args);
+                backingTool = backingCall.toolName;
+                const result = await registry.execute(backingCall.toolName, backingCall.args, context);
+                if (!result.ok) {
+                    state.dynamicToolCalls.push({
+                        name,
+                        backingTool,
+                        status: "failed",
+                        latencyMs: Date.now() - startedAt,
+                        errorCode: result.error?.code,
+                        errorMessage: result.error?.message,
+                    });
+                    recorded = true;
+                    throw new ToolExecutionError(result.error?.code ?? "tool_execution_failed", result.error?.message ?? "Backing tool failed", {
+                        retryable: result.error?.retryable,
+                        details: { tool: name, backingTool, backingError: result.error?.details },
+                    });
+                }
+                const data = {
+                    tool: name,
+                    executionMode,
+                    resultContract: contract.resultContract ?? contract.result_contract,
+                    resultSources: contractStringArray(contract, "resultSources", "result_sources"),
+                    sourcePaths: contractStringArray(contract, "sourcePaths", "source_paths"),
+                    sourceTypes: contractStringArray(contract, "sourceTypes", "source_types"),
+                    suppliedSnapshots: contractStringArray(contract, "suppliedSnapshots", "supplied_snapshots"),
+                    backingTool,
+                    result: payloadForToolResult(result),
+                };
+                state.dynamicToolCalls.push({
+                    name,
+                    backingTool,
+                    status: "success",
+                    latencyMs: Date.now() - startedAt,
+                });
+                recorded = true;
+                return {
+                    output: JSON.stringify(data, null, 2),
+                    data,
+                };
+            }
+            catch (error) {
+                if (!recorded) {
+                    state.dynamicToolCalls.push({
+                        name,
+                        backingTool,
+                        status: "failed",
+                        latencyMs: Date.now() - startedAt,
+                        errorCode: error instanceof ToolExecutionError ? error.code : "tool_execution_failed",
+                        errorMessage: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                throw error;
+            }
+        },
+    };
+};
+const resolveGatewayContract = (contract, policyGateway) => {
+    const gateway = contract.gateway;
+    if (!gateway && !policyGateway)
+        return undefined;
+    return { ...(policyGateway ?? {}), ...(gateway ?? {}) };
+};
+const gatewayString = (gateway, keys) => {
+    if (!gateway)
+        return undefined;
+    for (const key of keys) {
+        const value = gateway[key];
+        if (typeof value === "string" && value.trim()) {
+            return value.trim();
+        }
+    }
+    return undefined;
+};
+const gatewayBoolean = (gateway, keys) => {
+    if (!gateway)
+        return undefined;
+    for (const key of keys) {
+        const value = gateway[key];
+        if (typeof value === "boolean") {
+            return value;
+        }
+    }
+    return undefined;
+};
+const gatewayEndpoint = (gateway) => gatewayString(gateway, ["endpoint"]);
+const gatewaySigningSecret = (gateway) => gatewayString(gateway, [
+    "signatureSecret",
+    "signature_secret",
+    "signingSecret",
+    "signing_secret",
+    "secret",
+    "signature",
+]);
+const appToolGatewayTenantScope = (input) => stripUndefined({
+    tenant_id: input.metadata?.tenantId,
+    docdex_repo_id: input.docdex?.repoId,
+});
+const appToolGatewayRequesterScope = (input) => stripUndefined({
+    request_id: input.metadata?.requestId,
+    owner_user_id: input.metadata?.ownerUserId,
+    api_key_id: input.metadata?.apiKeyId,
+    agent_slug: input.metadata?.agentSlug,
+});
+const gatewayDispatchToolErrorCode = (error) => {
+    if (error.code === "GATEWAY_INVALID_ARGS")
+        return "tool_invalid_args";
+    if (error.code === "GATEWAY_HTTP_FAILED" ||
+        error.code === "GATEWAY_RESPONSE_MALFORMED") {
+        return "tool_execution_failed";
+    }
+    return "tool_permission_denied";
+};
+const createGatewayDynamicTool = (options) => {
+    const { name, contract, gateway, input, state } = options;
+    return {
+        name,
+        description: contract.description ??
+            `Read-only app tool dispatched through the runtime app_tool_gateway for ${name}.`,
+        inputSchema: contractCallSchema(contract),
+        handler: async (args, context) => {
+            const startedAt = Date.now();
+            try {
+                assertDynamicArgsStayInScope(name, args);
+                const dispatched = await dispatchAppToolGateway({
+                    runId: context.runId ?? input.metadata?.requestId ?? input.metadata?.jobId ?? "codali-runtime",
+                    sessionId: input.session?.id,
+                    requestId: input.metadata?.requestId,
+                    tenantScope: appToolGatewayTenantScope(input),
+                    requesterScope: appToolGatewayRequesterScope(input),
+                    toolName: name,
+                    args,
+                    contract,
+                    gateway,
+                    allowedTools: input.policy.allowedTools,
+                    deniedTools: input.policy.deniedTools,
+                });
+                state.dynamicToolCalls.push({
+                    name,
+                    backingTool: "app_tool_gateway",
+                    status: "success",
+                    latencyMs: Date.now() - startedAt,
+                });
+                return {
+                    output: JSON.stringify(dispatched.evidencePayload, null, 2),
+                    data: dispatched.evidencePayload,
+                };
+            }
+            catch (error) {
+                const toolError = error instanceof AppToolGatewayDispatchError
+                    ? new ToolExecutionError(gatewayDispatchToolErrorCode(error), error.message, {
+                        retryable: error.retryable,
+                        details: stripUndefined({
+                            tool: name,
+                            gatewayErrorCode: error.code,
+                            gatewayDetails: error.details,
+                        }),
+                    })
+                    : error;
+                state.dynamicToolCalls.push({
+                    name,
+                    backingTool: "app_tool_gateway",
+                    status: "failed",
+                    latencyMs: Date.now() - startedAt,
+                    errorCode: toolError instanceof ToolExecutionError ? toolError.code : "tool_execution_failed",
+                    errorMessage: toolError instanceof Error ? toolError.message : String(toolError),
+                });
+                throw toolError;
+            }
+        },
+    };
+};
 const parseJsonPayload = (output) => {
     const trimmed = output.trim();
     if (!trimmed || (!trimmed.startsWith("{") && !trimmed.startsWith("[")))
@@ -619,13 +1066,137 @@ const isDocdexToolAllowed = (toolName, docdex) => {
     }
     return true;
 };
+const isImmutableDocdexRuntimeContext = (docdex) => docdex?.immutableRuntimeContext === true ||
+    docdex?.credentialSource === "attached_mswarm_api_key";
 const registerRuntimeTool = (registry, tool, policy, docdex) => {
     if (isRuntimeToolAllowed(tool.name, policy) && isDocdexToolAllowed(tool.name, docdex)) {
         registry.register(tool);
     }
 };
-const buildRuntimeToolRegistry = (input) => {
+const collectRuntimeToolContractCandidates = (input) => {
+    const contracts = new Map();
+    for (const [name, contract] of normalizeRuntimeToolContractEntries(input.policy.okacamToolContracts)) {
+        contracts.set(name, contract);
+    }
+    for (const [name, contract] of normalizeRuntimeToolContractEntries(input.policy.appToolContracts)) {
+        contracts.set(name, contract);
+    }
+    const names = new Set();
+    for (const name of toolNamesFromManifest(input.docdex?.toolManifest))
+        names.add(name);
+    for (const name of stringArrayFromUnknown(input.policy.okacamVirtualTools))
+        names.add(name);
+    for (const name of stringArrayFromUnknown(input.policy.appVirtualTools))
+        names.add(name);
+    for (const name of contracts.keys())
+        names.add(name);
+    return Array.from(names)
+        .sort()
+        .map((name) => ({ name, contract: contracts.get(name) }));
+};
+const registerRuntimeContractTools = (registry, input, state, warnings) => {
+    const candidates = collectRuntimeToolContractCandidates(input);
+    if (!candidates.length)
+        return;
+    const registryNames = new Set(registry.list().map((tool) => tool.name));
+    for (const candidate of candidates) {
+        const name = candidate.name.trim();
+        if (!name)
+            continue;
+        pushUnique(state.consideredTools, name);
+        if (!candidate.contract) {
+            if (!registryNames.has(name))
+                recordSkippedDynamicTool(state, name, "missing_contract");
+            continue;
+        }
+        if (candidate.contract.enabled === false) {
+            recordSkippedDynamicTool(state, name, "contract_disabled");
+            continue;
+        }
+        if (!isRuntimeToolAllowed(name, input.policy) || !isDocdexToolAllowed(name, input.docdex)) {
+            recordSkippedDynamicTool(state, name, "policy_disallowed");
+            continue;
+        }
+        if (registryNames.has(name)) {
+            recordSkippedDynamicTool(state, name, "already_registered");
+            continue;
+        }
+        const readOnly = contractBoolean(candidate.contract, "readOnly", "read_only");
+        if (readOnly === false) {
+            recordSkippedDynamicTool(state, name, "not_read_only");
+            continue;
+        }
+        const executionMode = contractString(candidate.contract, "executionMode", "execution_mode") ??
+            "server_supplied_snapshot_plus_docdex";
+        const gateway = resolveGatewayContract(candidate.contract, input.policy.appToolGateway);
+        const resolvedGatewayEndpoint = gatewayEndpoint(gateway);
+        if (executionMode === "app_tool_gateway" || resolvedGatewayEndpoint) {
+            if (!gateway) {
+                recordSkippedDynamicTool(state, name, "gateway_not_configured");
+                continue;
+            }
+            if (readOnly !== true) {
+                recordSkippedDynamicTool(state, name, "not_read_only");
+                continue;
+            }
+            if (gatewayBoolean(gateway, ["readOnly", "read_only"]) !== true) {
+                recordSkippedDynamicTool(state, name, "gateway_not_read_only");
+                continue;
+            }
+            if (!resolvedGatewayEndpoint) {
+                recordSkippedDynamicTool(state, name, "gateway_endpoint_missing");
+                continue;
+            }
+            if (!gatewaySigningSecret(gateway)) {
+                recordSkippedDynamicTool(state, name, "gateway_signature_missing");
+                continue;
+            }
+            registerRuntimeTool(registry, createGatewayDynamicTool({
+                name,
+                contract: candidate.contract,
+                gateway: { ...gateway, endpoint: resolvedGatewayEndpoint },
+                input,
+                state,
+            }), input.policy, input.docdex);
+            registryNames.add(name);
+            pushUnique(state.registeredDynamicTools, name);
+            continue;
+        }
+        const declaredBackingTools = contractStringArray(candidate.contract, "backingTools", "backing_tools");
+        if (!declaredBackingTools.length) {
+            recordSkippedDynamicTool(state, name, "missing_backing_tools");
+            continue;
+        }
+        const unsafeBackingTool = declaredBackingTools.find((toolName) => !READ_ONLY_DYNAMIC_BACKING_TOOLS.has(toolName));
+        if (unsafeBackingTool) {
+            recordSkippedDynamicTool(state, name, `unsafe_backing_tool:${unsafeBackingTool}`);
+            continue;
+        }
+        const availableBackingTools = declaredBackingTools.filter((toolName) => registryNames.has(toolName));
+        if (!availableBackingTools.length) {
+            recordSkippedDynamicTool(state, name, "backing_tool_unavailable");
+            continue;
+        }
+        registerRuntimeTool(registry, createDocdexBackedDynamicTool({
+            name,
+            contract: candidate.contract,
+            registry,
+            backingTools: availableBackingTools,
+            state,
+        }), input.policy, input.docdex);
+        registryNames.add(name);
+        pushUnique(state.registeredDynamicTools, name);
+    }
+    const warningSkips = state.skippedDynamicTools.filter((entry) => entry.reason !== "already_registered");
+    if (warningSkips.length) {
+        warnings.push(`Runtime tool contracts skipped: ${warningSkips
+            .map((entry) => `${entry.name}:${entry.reason}`)
+            .join(", ")}`);
+    }
+};
+const buildRuntimeToolRegistry = (input, dynamicToolState, warnings) => {
     if (input.toolRegistry) {
+        registerRuntimeContractTools(input.toolRegistry, input, dynamicToolState, warnings);
         return input.toolRegistry;
     }
     const registry = new ToolRegistry();
@@ -634,6 +1205,7 @@ const buildRuntimeToolRegistry = (input) => {
     if (explicitTools) {
         for (const tool of explicitTools)
             register(tool);
+        registerRuntimeContractTools(registry, input, dynamicToolState, warnings);
         return registry;
     }
     for (const tool of createFileTools())
@@ -643,19 +1215,26 @@ const buildRuntimeToolRegistry = (input) => {
     if (input.policy.allowShell) {
         register(createShellTool());
     }
+    const immutableDocdexContext = isImmutableDocdexRuntimeContext(input.docdex);
     const docdexClient = new DocdexClient({
-        baseUrl: input.docdex?.baseUrl ?? DEFAULT_DOCDEX_BASE_URL,
+        baseUrl: immutableDocdexContext
+            ? input.docdex?.baseUrl ?? ""
+            : input.docdex?.baseUrl ?? DEFAULT_DOCDEX_BASE_URL,
         repoId: input.docdex?.repoId,
-        repoRoot: input.docdex?.repoRoot ?? input.workspace.root,
+        repoRoot: immutableDocdexContext
+            ? undefined
+            : input.docdex?.repoRoot ?? input.workspace.root,
         dagSessionId: input.docdex?.dagSessionId ?? input.metadata?.requestId,
         apiKey: input.docdex?.apiKey,
         credentialSource: input.docdex?.credentialSource,
         required: input.docdex?.required,
         allowedOperations: input.docdex?.allowedOperations,
         capabilities: input.docdex?.capabilities,
+        immutableRuntimeContext: immutableDocdexContext,
     });
     for (const tool of createDocdexTools(docdexClient))
         register(tool);
+    registerRuntimeContractTools(registry, input, dynamicToolState, warnings);
     return registry;
 };
 const buildResponseFormat = (response) => {
@@ -930,6 +1509,25 @@ const emitRuntimeEvent = (event, sink, warnings) => {
         warnings.push(error instanceof Error ? error.message : String(error));
     }
 };
+const buildRuntimeTelemetry = (options) => {
+    const calledTools = [];
+    for (const event of options.events) {
+        if (event.type === "tool_call")
+            pushUnique(calledTools, event.name);
+    }
+    return {
+        runId: options.runId,
+        runtime: "codali",
+        mode: options.input.policy.mode,
+        toolCallCount: options.toolCallsExecuted,
+        calledTools,
+        consideredTools: [...options.dynamicToolState.consideredTools],
+        registeredDynamicTools: [...options.dynamicToolState.registeredDynamicTools],
+        skippedDynamicTools: [...options.dynamicToolState.skippedDynamicTools],
+        dynamicToolCalls: [...options.dynamicToolState.dynamicToolCalls],
+        warnings: [...options.warnings],
+    };
+};
 const createSubagentRunner = (options) => {
     const { input, registry, toolContext, runId, remainingToolBudget } = options;
     return async ({ spec }) => {
@@ -1322,6 +1920,7 @@ export const runCodaliTask = async (input) => {
     const touchedFiles = new Set();
     const warnings = [];
     const events = [];
+    const dynamicToolState = createDynamicToolRegistryState();
     let eventSequence = 0;
     const session = await initializeRuntimeSession(input, runId, warnings);
     const emit = (event) => {
@@ -1329,7 +1928,7 @@ export const runCodaliTask = async (input) => {
         emitRuntimeEvent(event, input.onEvent, warnings);
     };
     const provider = input.providerInstance ?? createRuntimeProvider(input.provider);
-    const registry = buildRuntimeToolRegistry(input);
+    const registry = buildRuntimeToolRegistry(input, dynamicToolState, warnings);
     const originalRecordTouchedFile = input.toolContext?.recordTouchedFile;
     const toolContext = {
         ...input.toolContext,
@@ -1385,6 +1984,14 @@ export const runCodaliTask = async (input) => {
                 warnings,
                 events,
                 runId,
+                telemetry: buildRuntimeTelemetry({
+                    input,
+                    runId,
+                    toolCallsExecuted: result.toolCallsExecuted,
+                    events,
+                    warnings,
+                    dynamicToolState,
+                }),
                 session: toSessionSummary(finalSession),
             };
         }
@@ -1436,6 +2043,14 @@ export const runCodaliTask = async (input) => {
             warnings,
             events,
             runId,
+            telemetry: buildRuntimeTelemetry({
+                input,
+                runId,
+                toolCallsExecuted: result.toolCallsExecuted,
+                events,
+                warnings,
+                dynamicToolState,
+            }),
             session: toSessionSummary(finalSession),
         };
     }