@mcoda/codali 0.1.87 → 0.1.89

package/dist/gateway/AppToolGatewayDispatcher.d.ts

@@ -0,0 +1,88 @@
+import type { CodaliRuntimeAppToolContract, CodaliRuntimeAppToolGatewayContract } from "../runtime/CodaliRuntime.js";
+export declare const CODALI_APP_TOOL_GATEWAY_VERSION = "codali.app_tool_gateway.v1";
+export type AppToolGatewayDispatchErrorCode = "GATEWAY_TOOL_NOT_ALLOWED" | "GATEWAY_TOOL_DENIED" | "GATEWAY_CONTRACT_NOT_READ_ONLY" | "GATEWAY_ENDPOINT_REQUIRED" | "GATEWAY_SIGNATURE_REQUIRED" | "GATEWAY_INVALID_ARGS" | "GATEWAY_SCOPE_OVERRIDE_BLOCKED" | "GATEWAY_HTTP_FAILED" | "GATEWAY_RESPONSE_MALFORMED";
+export declare class AppToolGatewayDispatchError extends Error {
+    readonly code: AppToolGatewayDispatchErrorCode;
+    readonly retryable: boolean;
+    readonly details?: Record<string, unknown>;
+    constructor(code: AppToolGatewayDispatchErrorCode, message: string, options?: {
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+    });
+}
+export interface CodaliAppToolGatewayScope extends Record<string, unknown> {
+    tenant_id?: string;
+    tenant_slug?: string;
+    docdex_repo_id?: string;
+}
+export interface CodaliAppToolGatewayRequesterScope extends Record<string, unknown> {
+    request_id?: string;
+    owner_user_id?: string;
+    api_key_id?: string;
+    agent_slug?: string;
+}
+export interface CodaliAppToolGatewayUnsignedRequest {
+    version: typeof CODALI_APP_TOOL_GATEWAY_VERSION;
+    run_id: string;
+    session_id?: string;
+    request_id?: string;
+    tenant_scope?: CodaliAppToolGatewayScope;
+    requester_scope?: CodaliAppToolGatewayRequesterScope;
+    tool_name: string;
+    validated_args: unknown;
+    timestamp: string;
+    nonce: string;
+    read_only: true;
+    call_schema?: Record<string, unknown>;
+    result_contract?: string;
+    result_sources?: string[];
+    source_paths?: string[];
+    source_types?: string[];
+}
+export interface CodaliAppToolGatewaySignedRequest extends CodaliAppToolGatewayUnsignedRequest {
+    signature: string;
+}
+export interface AppToolGatewayDispatchInput {
+    runId: string;
+    sessionId?: string;
+    requestId?: string;
+    tenantScope?: CodaliAppToolGatewayScope;
+    requesterScope?: CodaliAppToolGatewayRequesterScope;
+    toolName: string;
+    args: unknown;
+    contract: CodaliRuntimeAppToolContract;
+    gateway: CodaliRuntimeAppToolGatewayContract;
+    allowedTools?: string[];
+    deniedTools?: string[];
+    now?: () => Date;
+    nonce?: () => string;
+    fetchImpl?: typeof fetch;
+}
+export interface AppToolGatewayDispatchResult {
+    request: CodaliAppToolGatewaySignedRequest;
+    redactedRequest: unknown;
+    responseStatus: number;
+    responseText: string;
+    responsePayload: unknown;
+    evidencePayload: Record<string, unknown>;
+    redactedResponse: unknown;
+}
+export declare const canonicalizeAppToolGatewayPayload: (value: unknown) => string;
+export declare const signAppToolGatewayRequest: (request: CodaliAppToolGatewayUnsignedRequest, secret: string) => string;
+export declare const verifyAppToolGatewayRequestSignature: (request: CodaliAppToolGatewaySignedRequest, secret: string) => boolean;
+export declare const redactAppToolGatewayPayload: (value: unknown) => unknown;
+export declare const buildAppToolGatewaySignedRequest: (input: {
+    runId: string;
+    sessionId?: string;
+    requestId?: string;
+    tenantScope?: CodaliAppToolGatewayScope;
+    requesterScope?: CodaliAppToolGatewayRequesterScope;
+    toolName: string;
+    args: unknown;
+    contract: CodaliRuntimeAppToolContract;
+    timestamp: string;
+    nonce: string;
+    secret: string;
+}) => CodaliAppToolGatewaySignedRequest;
+export declare const dispatchAppToolGateway: (input: AppToolGatewayDispatchInput) => Promise<AppToolGatewayDispatchResult>;
+//# sourceMappingURL=AppToolGatewayDispatcher.d.ts.map

package/dist/gateway/AppToolGatewayDispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppToolGatewayDispatcher.d.ts","sourceRoot":"","sources":["../../src/gateway/AppToolGatewayDispatcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,4BAA4B,EAC5B,mCAAmC,EACpC,MAAM,6BAA6B,CAAC;AAGrC,eAAO,MAAM,+BAA+B,+BAA+B,CAAC;AAE5E,MAAM,MAAM,+BAA+B,GACvC,0BAA0B,GAC1B,qBAAqB,GACrB,gCAAgC,GAChC,2BAA2B,GAC3B,4BAA4B,GAC5B,sBAAsB,GACtB,gCAAgC,GAChC,qBAAqB,GACrB,4BAA4B,CAAC;AAEjC,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;IAC/C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGzC,IAAI,EAAE,+BAA+B,EACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAO;CAQ3E;AAED,MAAM,WAAW,yBAA0B,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kCAAmC,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACjF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mCAAmC;IAClD,OAAO,EAAE,OAAO,+BAA+B,CAAC;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,yBAAyB,CAAC;IACzC,eAAe,CAAC,EAAE,kCAAkC,CAAC;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,iCAAkC,SAAQ,mCAAmC;IAC5F,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,yBAAyB,CAAC;IACxC,cAAc,CAAC,EAAE,kCAAkC,CAAC;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,4BAA4B,CAAC;IACvC,OAAO,EAAE,mCAAmC,CAAC;IAC7C,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,iCAAiC,CAAC;IAC3C,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;IACzB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAsGD,eAAO,MAAM,iCAAiC,GAAI,OAAO,OAAO,KAAG,MAC5B,CAAC;AAExC,eAAO,MAAM,yBAAyB,GACpC,SAAS,mCAAmC,EAC5C,QAAQ,MAAM,KACb,MAGiB,CAAC;AAErB,eAAO,MAAM,oCAAoC,GAC/C,SAAS,iCAAiC,EAC1C,QAAQ,MAAM,KACb,OASF,CAAC;AAQF,eAAO,MAAM,2BAA2B,GAAI,OAAO,OAAO,KAAG,OAiB5D,CAAC;AA+NF,eAAO,MAAM,gCAAgC,GAAI,OAAO;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,yBAAyB,CAAC;IACxC,cAAc,CAAC,EAAE,kCAAkC,CAAC;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,4BAA4B,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,KAAG,iCAuBH,CAAC;AAEF,eAAO,MAAM,sBAAsB,GACjC,OAAO,2BAA2B,KACjC,OAAO,CAAC,4BAA4B,CAsGtC,CAAC"}

package/dist/gateway/AppToolGatewayDispatcher.js

@@ -0,0 +1,381 @@
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { CODALI_GATEWAY_RESERVED_TOOL_ARG_KEYS } from "./ToolCapabilityCompiler.js";
+export const CODALI_APP_TOOL_GATEWAY_VERSION = "codali.app_tool_gateway.v1";
+export class AppToolGatewayDispatchError extends Error {
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = "AppToolGatewayDispatchError";
+        this.code = code;
+        this.retryable = options.retryable ?? false;
+        this.details = options.details;
+    }
+}
+const EXTRA_RESERVED_ARG_KEYS = [
+    "authorization",
+    "credential",
+    "credentials",
+    "workspaceRoot",
+    "workspace_root",
+];
+const RESERVED_ARG_KEY_SET = new Set([...CODALI_GATEWAY_RESERVED_TOOL_ARG_KEYS, ...EXTRA_RESERVED_ARG_KEYS].map((key) => key.toLowerCase()));
+const SENSITIVE_KEY_PATTERN = /(?:authorization|api[_-]?key|bearer|credential|password|secret|signature|token)/i;
+const SENSITIVE_STRING_PATTERNS = [
+    [/(Bearer\s+)[A-Za-z0-9._~+/=-]+/gi, "$1[redacted]"],
+    [
+        /((?:api[_-]?key|token|signature|secret|password)=)[^&\s]+/gi,
+        "$1[redacted]",
+    ],
+];
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const hasOwn = (record, key) => Object.prototype.hasOwnProperty.call(record, key);
+const readString = (record, keys) => {
+    if (!record)
+        return undefined;
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim()) {
+            return value.trim();
+        }
+    }
+    return undefined;
+};
+const readBoolean = (record, keys) => {
+    if (!record)
+        return undefined;
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "boolean") {
+            return value;
+        }
+    }
+    return undefined;
+};
+const readStringArray = (record, keys) => {
+    for (const key of keys) {
+        const value = record[key];
+        if (Array.isArray(value)) {
+            return value.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
+        }
+    }
+    return [];
+};
+const normalizeRecord = (value) => isRecord(value) ? value : {};
+const compactObject = (value) => {
+    for (const key of Object.keys(value)) {
+        if (value[key] === undefined) {
+            delete value[key];
+        }
+    }
+    return value;
+};
+const canonicalValue = (value) => {
+    if (Array.isArray(value)) {
+        return value.map(canonicalValue);
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    const output = {};
+    for (const key of Object.keys(value).sort()) {
+        const entry = value[key];
+        if (entry !== undefined) {
+            output[key] = canonicalValue(entry);
+        }
+    }
+    return output;
+};
+export const canonicalizeAppToolGatewayPayload = (value) => JSON.stringify(canonicalValue(value));
+export const signAppToolGatewayRequest = (request, secret) => `sha256=${createHmac("sha256", secret)
+    .update(canonicalizeAppToolGatewayPayload(request))
+    .digest("hex")}`;
+export const verifyAppToolGatewayRequestSignature = (request, secret) => {
+    const { signature, ...unsigned } = request;
+    const expected = signAppToolGatewayRequest(unsigned, secret);
+    const signatureBuffer = Buffer.from(signature);
+    const expectedBuffer = Buffer.from(expected);
+    return (signatureBuffer.length === expectedBuffer.length &&
+        timingSafeEqual(signatureBuffer, expectedBuffer));
+};
+const redactSensitiveString = (value) => SENSITIVE_STRING_PATTERNS.reduce((output, [pattern, replacement]) => output.replace(pattern, replacement), value);
+export const redactAppToolGatewayPayload = (value) => {
+    if (Array.isArray(value)) {
+        return value.map(redactAppToolGatewayPayload);
+    }
+    if (typeof value === "string") {
+        return redactSensitiveString(value);
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    const output = {};
+    for (const [key, entry] of Object.entries(value)) {
+        output[key] = SENSITIVE_KEY_PATTERN.test(key)
+            ? "[redacted]"
+            : redactAppToolGatewayPayload(entry);
+    }
+    return output;
+};
+const findReservedArgKeys = (value, path = "$", matches = []) => {
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => findReservedArgKeys(entry, `${path}[${index}]`, matches));
+        return matches;
+    }
+    if (!isRecord(value)) {
+        return matches;
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        const childPath = `${path}.${key}`;
+        if (RESERVED_ARG_KEY_SET.has(key.toLowerCase())) {
+            matches.push(childPath);
+        }
+        findReservedArgKeys(entry, childPath, matches);
+    }
+    return matches;
+};
+const schemaTypeMatches = (value, type) => {
+    const types = Array.isArray(type) ? type : [type];
+    if (types.length === 0 || types.includes(undefined)) {
+        return true;
+    }
+    return types.some((entry) => {
+        if (entry === "array")
+            return Array.isArray(value);
+        if (entry === "integer")
+            return Number.isInteger(value);
+        if (entry === "null")
+            return value === null;
+        if (entry === "object")
+            return isRecord(value);
+        return typeof entry === "string" && typeof value === entry;
+    });
+};
+const validateArgsAgainstCallSchema = (toolName, args, schema) => {
+    const reserved = findReservedArgKeys(args);
+    if (reserved.length > 0) {
+        throw new AppToolGatewayDispatchError("GATEWAY_SCOPE_OVERRIDE_BLOCKED", "App tool gateway arguments cannot override tenant, repo, base URL, or credential scope.", { details: { tool: toolName, forbidden: reserved } });
+    }
+    if (!schema) {
+        return args;
+    }
+    if ((schema.type === undefined || schema.type === "object") && !isRecord(args)) {
+        throw new AppToolGatewayDispatchError("GATEWAY_INVALID_ARGS", "App tool gateway arguments must match the contract call schema.", { details: { tool: toolName, reason: "object_required" } });
+    }
+    const record = normalizeRecord(args);
+    const required = Array.isArray(schema.required)
+        ? schema.required.filter((entry) => typeof entry === "string")
+        : [];
+    const missing = required.filter((key) => record[key] === undefined);
+    if (missing.length > 0) {
+        throw new AppToolGatewayDispatchError("GATEWAY_INVALID_ARGS", "App tool gateway arguments are missing required contract fields.", { details: { tool: toolName, missing } });
+    }
+    const properties = isRecord(schema.properties) ? schema.properties : {};
+    if (schema.additionalProperties === false) {
+        const unexpected = Object.keys(record).filter((key) => !hasOwn(properties, key));
+        if (unexpected.length > 0) {
+            throw new AppToolGatewayDispatchError("GATEWAY_INVALID_ARGS", "App tool gateway arguments include fields outside the contract schema.", { details: { tool: toolName, unexpected } });
+        }
+    }
+    for (const [key, propertySchema] of Object.entries(properties)) {
+        if (!isRecord(propertySchema) || record[key] === undefined) {
+            continue;
+        }
+        if (!schemaTypeMatches(record[key], propertySchema.type)) {
+            throw new AppToolGatewayDispatchError("GATEWAY_INVALID_ARGS", "App tool gateway argument field type does not match the contract schema.", { details: { tool: toolName, field: key, expected: propertySchema.type } });
+        }
+    }
+    return args;
+};
+const gatewayEndpoint = (gateway) => readString(gateway, ["endpoint"]);
+const gatewaySigningSecret = (gateway) => readString(gateway, [
+    "signatureSecret",
+    "signature_secret",
+    "signingSecret",
+    "signing_secret",
+    "secret",
+    "signature",
+]);
+const assertReadOnlyContract = (contract, gateway, toolName) => {
+    const contractReadOnly = readBoolean(contract, ["readOnly", "read_only"]);
+    const gatewayReadOnly = readBoolean(gateway, ["readOnly", "read_only"]);
+    if (contractReadOnly !== true || gatewayReadOnly !== true) {
+        throw new AppToolGatewayDispatchError("GATEWAY_CONTRACT_NOT_READ_ONLY", "Direct app tool gateway dispatch requires explicit read-only contract and gateway flags.", {
+            details: {
+                tool: toolName,
+                contractReadOnly,
+                gatewayReadOnly,
+            },
+        });
+    }
+};
+const resultContractFor = (contract) => readString(contract, ["resultContract", "result_contract"]);
+const callSchemaFor = (contract) => {
+    const schema = contract.callSchema ?? contract.call_schema;
+    return isRecord(schema) ? schema : undefined;
+};
+const parseResponsePayload = (text) => {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return undefined;
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("["))
+        return text;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        throw new AppToolGatewayDispatchError("GATEWAY_RESPONSE_MALFORMED", "App tool gateway returned malformed JSON.", {
+            retryable: false,
+            details: { response: redactAppToolGatewayPayload({ body: text.slice(0, 1000) }) },
+        });
+    }
+};
+const buildEvidencePayload = (input) => {
+    const responseRecord = isRecord(input.responsePayload) ? input.responsePayload : undefined;
+    const payload = {
+        sourceType: "app_tool",
+        tenantScoped: true,
+        tool: input.toolName,
+        usedTool: input.toolName,
+        resultContract: resultContractFor(input.contract),
+        result_contract: resultContractFor(input.contract),
+        result: input.responsePayload,
+        rawExcerpt: typeof input.responsePayload === "string" ? input.responsePayload : undefined,
+        metadata: {
+            app_tool_gateway: {
+                version: input.request.version,
+                run_id: input.request.run_id,
+                session_id: input.request.session_id,
+                request_id: input.request.request_id,
+                timestamp: input.request.timestamp,
+                nonce: input.request.nonce,
+                response_status: input.responseStatus,
+            },
+        },
+    };
+    if (responseRecord) {
+        for (const key of [
+            "evidence",
+            "evidenceItems",
+            "evidence_items",
+            "facts",
+            "sources",
+            "sourceRecords",
+            "source_records",
+            "citations",
+            "results",
+            "hits",
+            "items",
+            "records",
+        ]) {
+            if (Array.isArray(responseRecord[key])) {
+                payload[key] = responseRecord[key];
+            }
+        }
+    }
+    else if (typeof input.responsePayload === "string" && input.responsePayload.trim()) {
+        payload.facts = [input.responsePayload.trim()];
+    }
+    else if (input.responseText.trim()) {
+        payload.facts = [input.responseText.trim()];
+    }
+    return compactObject(payload);
+};
+export const buildAppToolGatewaySignedRequest = (input) => {
+    const unsigned = compactObject({
+        version: CODALI_APP_TOOL_GATEWAY_VERSION,
+        run_id: input.runId,
+        session_id: input.sessionId,
+        request_id: input.requestId,
+        tenant_scope: input.tenantScope,
+        requester_scope: input.requesterScope,
+        tool_name: input.toolName,
+        validated_args: input.args,
+        timestamp: input.timestamp,
+        nonce: input.nonce,
+        read_only: true,
+        call_schema: callSchemaFor(input.contract),
+        result_contract: resultContractFor(input.contract),
+        result_sources: readStringArray(input.contract, ["resultSources", "result_sources"]),
+        source_paths: readStringArray(input.contract, ["sourcePaths", "source_paths"]),
+        source_types: readStringArray(input.contract, ["sourceTypes", "source_types"]),
+    });
+    return {
+        ...unsigned,
+        signature: signAppToolGatewayRequest(unsigned, input.secret),
+    };
+};
+export const dispatchAppToolGateway = async (input) => {
+    const allowedTools = new Set(input.allowedTools ?? []);
+    const deniedTools = new Set(input.deniedTools ?? []);
+    if (allowedTools.size > 0 && !allowedTools.has(input.toolName)) {
+        throw new AppToolGatewayDispatchError("GATEWAY_TOOL_NOT_ALLOWED", "App tool gateway tool is not in the allowed tool set.", { details: { tool: input.toolName } });
+    }
+    if (deniedTools.has(input.toolName)) {
+        throw new AppToolGatewayDispatchError("GATEWAY_TOOL_DENIED", "App tool gateway tool is blocked by denied tools policy.", { details: { tool: input.toolName } });
+    }
+    assertReadOnlyContract(input.contract, input.gateway, input.toolName);
+    const endpoint = gatewayEndpoint(input.gateway);
+    if (!endpoint) {
+        throw new AppToolGatewayDispatchError("GATEWAY_ENDPOINT_REQUIRED", "App tool gateway endpoint is not configured.", { details: { tool: input.toolName } });
+    }
+    const secret = gatewaySigningSecret(input.gateway);
+    if (!secret) {
+        throw new AppToolGatewayDispatchError("GATEWAY_SIGNATURE_REQUIRED", "App tool gateway signing material is required.", { details: { tool: input.toolName } });
+    }
+    const validatedArgs = validateArgsAgainstCallSchema(input.toolName, input.args, callSchemaFor(input.contract));
+    const request = buildAppToolGatewaySignedRequest({
+        runId: input.runId,
+        sessionId: input.sessionId,
+        requestId: input.requestId,
+        tenantScope: input.tenantScope,
+        requesterScope: input.requesterScope,
+        toolName: input.toolName,
+        args: validatedArgs,
+        contract: input.contract,
+        timestamp: (input.now ?? (() => new Date()))().toISOString(),
+        nonce: (input.nonce ?? randomUUID)(),
+        secret,
+    });
+    const body = JSON.stringify(request);
+    const fetchImpl = input.fetchImpl ?? globalThis.fetch;
+    const response = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "x-codali-app-tool-version": CODALI_APP_TOOL_GATEWAY_VERSION,
+            "x-codali-app-tool-signature": request.signature,
+            "x-codali-app-tool-timestamp": request.timestamp,
+            "x-codali-app-tool-nonce": request.nonce,
+        },
+        body,
+    });
+    const responseText = await response.text();
+    if (!response.ok) {
+        throw new AppToolGatewayDispatchError("GATEWAY_HTTP_FAILED", `App tool gateway failed with HTTP ${response.status}.`, {
+            retryable: response.status >= 500,
+            details: {
+                tool: input.toolName,
+                status: response.status,
+                request: redactAppToolGatewayPayload(request),
+                response: redactAppToolGatewayPayload({ body: responseText.slice(0, 1000) }),
+            },
+        });
+    }
+    const responsePayload = parseResponsePayload(responseText);
+    const evidencePayload = buildEvidencePayload({
+        toolName: input.toolName,
+        contract: input.contract,
+        request,
+        responseStatus: response.status,
+        responsePayload,
+        responseText,
+    });
+    return {
+        request,
+        redactedRequest: redactAppToolGatewayPayload(request),
+        responseStatus: response.status,
+        responseText,
+        responsePayload,
+        evidencePayload,
+        redactedResponse: redactAppToolGatewayPayload(responsePayload),
+    };
+};

package/dist/gateway/CodaliGateway.d.ts

@@ -0,0 +1,73 @@
+import type { Provider, ProviderMessage } from "../providers/ProviderTypes.js";
+import { type AgentTierResolution } from "./AgentTierResolver.js";
+import type { CodaliContextPack, CodaliGatewayClassifierOutput, CodaliGatewayPlannerOutput, CodaliGatewayRequest, CodaliGatewayResult } from "./CodaliGatewayTypes.js";
+import { type GatewayPolicyCompilation } from "./GatewayPolicyCompiler.js";
+import { CodaliGatewayPlanner, type CodaliGatewayPlanningResult, type CodaliGatewayPlannerOptions } from "./GatewayPlanner.js";
+import { type CodaliGatewayRunTrace, type CodaliGatewayStore } from "./CodaliGatewayStore.js";
+import { type CodaliGatewayReplayFixture, type CodaliGatewayReplayFixtureOptions, type CodaliGatewayTraceReadResult } from "./GatewayTraceReplay.js";
+import { CodaliGatewayStateMachine, type CodaliGatewayStateMachineOptions, type CodaliGatewayWorkerExecutionResult, type CodaliGatewayWorkerTaskRunner } from "./GatewayStateMachine.js";
+export interface CodaliGatewayFinalSynthesizerOptions {
+    maxTokens?: number;
+    temperature?: number;
+    retryAttempts?: number;
+}
+export interface CodaliGatewayOptions {
+    provider: Provider;
+    store?: CodaliGatewayStore;
+    planner?: CodaliGatewayPlanner;
+    plannerOptions?: CodaliGatewayPlannerOptions;
+    stateMachine?: CodaliGatewayStateMachine;
+    taskRunner?: CodaliGatewayWorkerTaskRunner;
+    workerOptions?: Omit<CodaliGatewayStateMachineOptions, "store" | "taskRunner">;
+    agentInventory?: unknown[];
+    agentResolution?: AgentTierResolution;
+    finalSynthesizerOptions?: CodaliGatewayFinalSynthesizerOptions;
+}
+export interface CodaliGatewayPlanResult {
+    runId: string;
+    policyCompilation: GatewayPolicyCompilation;
+    classifier: CodaliGatewayClassifierOutput;
+    planner: CodaliGatewayPlannerOutput;
+    planning: CodaliGatewayPlanningResult;
+    trace?: CodaliGatewayRunTrace;
+}
+export interface CodaliGatewayWorkerRunResult {
+    runId: string;
+    planning: CodaliGatewayPlanResult;
+    workers: CodaliGatewayWorkerExecutionResult;
+    trace?: CodaliGatewayRunTrace;
+}
+export interface CodaliGatewayFinalSynthesisInput {
+    runId: string;
+    request: CodaliGatewayRequest;
+    planning?: CodaliGatewayPlanResult;
+    workers?: CodaliGatewayWorkerExecutionResult;
+    contextPack?: CodaliContextPack;
+    agentResolution?: AgentTierResolution;
+}
+export declare const buildCodaliGatewayFinalSynthesizerMessages: (request: CodaliGatewayRequest, contextPack: CodaliContextPack) => ProviderMessage[];
+export declare class CodaliGateway {
+    private readonly options;
+    readonly store: CodaliGatewayStore;
+    private readonly planner;
+    constructor(options: CodaliGatewayOptions);
+    readTrace(runId: string): Promise<CodaliGatewayTraceReadResult | undefined>;
+    exportReplayFixture(runId: string, options?: CodaliGatewayReplayFixtureOptions): Promise<CodaliGatewayReplayFixture | undefined>;
+    plan(request: CodaliGatewayRequest): Promise<CodaliGatewayPlanResult>;
+    executeWorkerTasks(request: CodaliGatewayRequest): Promise<CodaliGatewayWorkerRunResult>;
+    run(request: CodaliGatewayRequest): Promise<CodaliGatewayResult>;
+    synthesizeFinalAnswer(input: CodaliGatewayFinalSynthesisInput): Promise<CodaliGatewayResult>;
+    private executePlannedWorkerTasks;
+    private resolveFinalAgent;
+    private validateRequiredFinalLargeModel;
+    private buildFinalPolicyBlockedResult;
+    private buildDegradedFinalResult;
+    private buildFailedFinalResult;
+    private updateRunPreservingMetadata;
+    private resolveStateMachine;
+}
+export declare const createCodaliGateway: (options: CodaliGatewayOptions) => CodaliGateway;
+export declare const runCodaliGatewayPlanning: (request: CodaliGatewayRequest, options: CodaliGatewayOptions) => Promise<CodaliGatewayPlanResult>;
+export declare const runCodaliGatewayWorkerTasks: (request: CodaliGatewayRequest, options: CodaliGatewayOptions) => Promise<CodaliGatewayWorkerRunResult>;
+export declare const runCodaliGateway: (request: CodaliGatewayRequest, options: CodaliGatewayOptions) => Promise<CodaliGatewayResult>;
+//# sourceMappingURL=CodaliGateway.d.ts.map

package/dist/gateway/CodaliGateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodaliGateway.d.ts","sourceRoot":"","sources":["../../src/gateway/CodaliGateway.ts"],"names":[],"mappings":"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"}