@once-agent/sdk 0.1.11 → 0.1.12

package/dist/gateway/openai-function-tools.js

@@ -0,0 +1,117 @@
+import { connectOpenAIAgentsFunctionToolsAuto, } from "../connect/openai-function-tools.js";
+import { GatewayConnectionError, } from "./local-toolset.js";
+import { GATEWAY_ROUTE, planGatewayToolset, } from "./planner.js";
+import { bindGatewayPlanToToolGraph, } from "./tool-graph-binding.js";
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isFunctionToolLike(value) {
+    return isObject(value) &&
+        value.type === "function" &&
+        typeof value.name === "string" &&
+        value.name.trim() !== "" &&
+        typeof value.description === "string" &&
+        Object.prototype.hasOwnProperty.call(value, "parameters") &&
+        typeof value.invoke === "function";
+}
+function descriptorFor(tool, override) {
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.parameters,
+        ...(override?.annotations !== undefined
+            ? { annotations: override.annotations }
+            : {}),
+        ...(override?._meta !== undefined
+            ? { _meta: override._meta }
+            : {}),
+    };
+}
+function blockedSummary(plan) {
+    return plan.blocked
+        .map(entry => `${entry.name ?? `#${entry.index}`}:${entry.connectReason}`)
+        .join(", ");
+}
+function bindingBlockedSummary(plan) {
+    return plan.blocked
+        .map(entry => `${entry.name ?? `#${entry.index}`}:${entry.bindingStatus}`)
+        .join(", ");
+}
+function verifyConnectAgreement(gatewayPlan, connectEntries) {
+    if (gatewayPlan.entries.length !== connectEntries.length) {
+        throw new GatewayConnectionError("GATEWAY_PLAN_MISMATCH", "OpenAI Gateway and Connect disagree about the FunctionTool subset length.");
+    }
+    for (let index = 0; index < gatewayPlan.entries.length; index += 1) {
+        const gateway = gatewayPlan.entries[index];
+        const expected = gateway.route === GATEWAY_ROUTE.DIRECT
+            ? "BYPASS"
+            : gateway.route === GATEWAY_ROUTE.PROTECT
+                ? "PROTECT"
+                : "UNKNOWN";
+        if (connectEntries[index]?.decision !== expected) {
+            throw new GatewayConnectionError("GATEWAY_PLAN_MISMATCH", `OpenAI Gateway and Connect disagree about FunctionTool route index ${index}.`);
+        }
+    }
+}
+/**
+ * Route an already-selected OpenAI Agents FunctionTool subset through Once.
+ *
+ * Gateway owns only preflight/routing identity. Actual FunctionTool wrapping,
+ * protected input parsing, logical-operation identity, payload binding,
+ * replay and reconciliation remain delegated to the existing proven Connect
+ * adapter. The supplied subset is never expanded with Tool Graph catalog
+ * entries.
+ */
+export function connectOpenAIAgentsFunctionToolsGatewayAuto(tools, options = {}) {
+    if (!Array.isArray(tools)) {
+        throw new GatewayConnectionError("INVALID_OPENAI_GATEWAY_TOOLSET", "Once Gateway needs the runtime-selected OpenAI Agents FunctionTool array.");
+    }
+    const manifest = [];
+    const names = new Set();
+    for (const candidate of tools) {
+        if (!isFunctionToolLike(candidate)) {
+            throw new GatewayConnectionError("UNSUPPORTED_OPENAI_GATEWAY_TOOL_TYPE", "Once Gateway v1 supports only OpenAI Agents FunctionTool objects in this adapter.");
+        }
+        if (names.has(candidate.name)) {
+            throw new GatewayConnectionError("DUPLICATE_OPENAI_GATEWAY_TOOL_NAME", `Once Gateway cannot safely map duplicate OpenAI FunctionTool name "${candidate.name}".`);
+        }
+        names.add(candidate.name);
+        manifest.push(descriptorFor(candidate, options.overrides?.[candidate.name]));
+    }
+    if (options.overrides) {
+        for (const name of Object.keys(options.overrides)) {
+            if (!names.has(name)) {
+                throw new GatewayConnectionError("UNDECLARED_OPENAI_GATEWAY_OVERRIDE", `Gateway override "${name}" does not correspond to a supplied FunctionTool.`);
+            }
+        }
+    }
+    const plan = planGatewayToolset(manifest);
+    if (!plan.valid) {
+        throw new GatewayConnectionError("INVALID_OPENAI_GATEWAY_TOOLSET", "Once Gateway could not plan the supplied OpenAI FunctionTool subset.");
+    }
+    if (!plan.ready) {
+        throw new GatewayConnectionError("GATEWAY_BLOCKED", `Once Gateway refuses unresolved OpenAI FunctionTool routing: ${blockedSummary(plan)}.`);
+    }
+    let binding;
+    if (options.toolGraphBindings !== undefined) {
+        if (!Array.isArray(options.toolGraphBindings)) {
+            throw new GatewayConnectionError("INVALID_TOOL_GRAPH_BINDINGS", "OpenAI Gateway Tool Graph bindings must be an array of safe identity records.");
+        }
+        binding = bindGatewayPlanToToolGraph(plan, options.toolGraphBindings);
+        if (!binding.ready) {
+            throw new GatewayConnectionError("GATEWAY_TOOL_GRAPH_BLOCKED", `OpenAI Gateway refuses stale or ambiguous Tool Graph identity: ${bindingBlockedSummary(binding)}.`);
+        }
+    }
+    const { toolGraphBindings: _toolGraphBindings, ...connectOptions } = options;
+    const connected = connectOpenAIAgentsFunctionToolsAuto(tools, connectOptions);
+    verifyConnectAgreement(plan, connected.plan.entries);
+    if (connected.tools.length !== tools.length) {
+        throw new GatewayConnectionError("GATEWAY_SUBSET_MISMATCH", "OpenAI Gateway changed the size of the runtime-selected FunctionTool subset.");
+    }
+    return Object.freeze({
+        plan,
+        ...(binding ? { binding } : {}),
+        tools: connected.tools,
+    });
+}
+//# sourceMappingURL=openai-function-tools.js.map

package/dist/gateway/openai-function-tools.js.map

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

package/dist/gateway/planner.d.ts

@@ -0,0 +1,53 @@
+import { type ConnectManifestToolSource } from "../connect/manifest.js";
+import { type ConnectToolClassificationReason, type ConnectToolDecision } from "../connect/tool-classifier.js";
+export declare const GATEWAY_ROUTE: Readonly<{
+    readonly DIRECT: "DIRECT";
+    readonly PROTECT: "PROTECT";
+    readonly BLOCK: "BLOCK";
+}>;
+export type GatewayRoute = (typeof GATEWAY_ROUTE)[keyof typeof GATEWAY_ROUTE];
+export declare const GATEWAY_PLAN_VERSION: "once-gateway-plan-v1";
+export interface GatewayPlanEntry {
+    index: number;
+    name: string | null;
+    source: ConnectManifestToolSource;
+    route: GatewayRoute;
+    descriptorFingerprint: string;
+    connectDecision: ConnectToolDecision;
+    connectReason: ConnectToolClassificationReason;
+    signals: readonly string[];
+}
+export interface GatewayPlanSummary {
+    total: number;
+    direct: number;
+    protect: number;
+    blocked: number;
+}
+export interface GatewayPlan {
+    version: typeof GATEWAY_PLAN_VERSION;
+    valid: boolean;
+    ready: boolean;
+    reason: "PLANNED" | "INVALID_MANIFEST";
+    entries: readonly Readonly<GatewayPlanEntry>[];
+    direct: readonly Readonly<GatewayPlanEntry>[];
+    protect: readonly Readonly<GatewayPlanEntry>[];
+    blocked: readonly Readonly<GatewayPlanEntry>[];
+    summary: Readonly<GatewayPlanSummary>;
+}
+/**
+ * Stable, secret-safe fingerprint of the exact descriptor shape used for
+ * gateway routing. Getter-backed/non-plain runtime state is never evaluated.
+ */
+export declare function gatewayDescriptorFingerprint(descriptor: unknown): string;
+/**
+ * Plan how a runtime-selected tool subset should cross the Once Gateway.
+ *
+ * This is a pure control-plane operation. It does not execute tools, resolve
+ * per-invocation operation identity/effect payload, open local protection
+ * state, contact MCP/providers, or retain executable implementations.
+ *
+ * Existing Connect classification remains authoritative:
+ * BYPASS -> DIRECT, PROTECT -> PROTECT, UNKNOWN -> BLOCK.
+ */
+export declare function planGatewayToolset(manifest: unknown): Readonly<GatewayPlan>;
+//# sourceMappingURL=planner.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../src/gateway/planner.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAEL,KAAK,+BAA+B,EACpC,KAAK,mBAAmB,EACzB,MAAM,+BAA+B,CAAC;AAEvC,eAAO,MAAM,aAAa;;;;EAIf,CAAC;AAEZ,MAAM,MAAM,YAAY,GACtB,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,OAAO,aAAa,CAAC,CAAC;AAErD,eAAO,MAAM,oBAAoB,EAAG,sBAA+B,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,yBAAyB,CAAC;IAClC,KAAK,EAAE,YAAY,CAAC;IACpB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,eAAe,EAAE,mBAAmB,CAAC;IACrC,aAAa,EAAE,+BAA+B,CAAC;IAC/C,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,oBAAoB,CAAC;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,kBAAkB,CAAC;IACvC,OAAO,EAAE,SAAS,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;IAC/C,MAAM,EAAE,SAAS,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;IAC9C,OAAO,EAAE,SAAS,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;IAC/C,OAAO,EAAE,SAAS,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;IAC/C,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC;CACvC;AAwED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,OAAO,GAClB,MAAM,CAKR;AAyCD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,OAAO,GAChB,QAAQ,CAAC,WAAW,CAAC,CAyDvB"}

package/dist/gateway/planner.js

@@ -0,0 +1,155 @@
+import { createHash } from "node:crypto";
+import { normalizeConnectToolManifest, planConnectToolManifest, } from "../connect/manifest.js";
+import { CONNECT_TOOL_DECISION, } from "../connect/tool-classifier.js";
+export const GATEWAY_ROUTE = Object.freeze({
+    DIRECT: "DIRECT",
+    PROTECT: "PROTECT",
+    BLOCK: "BLOCK",
+});
+export const GATEWAY_PLAN_VERSION = "once-gateway-plan-v1";
+const secretNamePattern = /(?:^|[_-])(authorization|api[_-]?key|token|password|passwd|secret|credential|cookie)(?:$|[_-])/i;
+function canonicalGatewayValue(value, depth = 0, seen = new Set(), secretContext = false) {
+    if (secretContext)
+        return "<redacted>";
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : null;
+    }
+    if (typeof value !== "object" || depth > 12) {
+        return "<opaque>";
+    }
+    const objectValue = value;
+    if (seen.has(objectValue))
+        return "<cycle>";
+    seen.add(objectValue);
+    try {
+        if (Array.isArray(value)) {
+            const output = [];
+            for (let index = 0; index < value.length; index += 1) {
+                const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+                output.push(descriptor && "value" in descriptor
+                    ? canonicalGatewayValue(descriptor.value, depth + 1, seen)
+                    : "<opaque>");
+            }
+            return output;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            return "<opaque>";
+        }
+        const output = {};
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        for (const key of Object.keys(descriptors).sort()) {
+            const descriptor = descriptors[key];
+            if (!("value" in descriptor)) {
+                output[key] = "<opaque>";
+                continue;
+            }
+            output[key] = canonicalGatewayValue(descriptor.value, depth + 1, seen, secretNamePattern.test(key));
+        }
+        return output;
+    }
+    finally {
+        seen.delete(objectValue);
+    }
+}
+/**
+ * Stable, secret-safe fingerprint of the exact descriptor shape used for
+ * gateway routing. Getter-backed/non-plain runtime state is never evaluated.
+ */
+export function gatewayDescriptorFingerprint(descriptor) {
+    const canonical = canonicalGatewayValue(descriptor);
+    return createHash("sha256")
+        .update(JSON.stringify(canonical))
+        .digest("hex");
+}
+function mapRoute(decision) {
+    if (decision === CONNECT_TOOL_DECISION.BYPASS) {
+        return GATEWAY_ROUTE.DIRECT;
+    }
+    if (decision === CONNECT_TOOL_DECISION.PROTECT) {
+        return GATEWAY_ROUTE.PROTECT;
+    }
+    return GATEWAY_ROUTE.BLOCK;
+}
+function freezeEntry(entry) {
+    return Object.freeze({
+        ...entry,
+        signals: Object.freeze([...entry.signals]),
+    });
+}
+function invalidPlan() {
+    const entries = Object.freeze([]);
+    const summary = Object.freeze({
+        total: 0,
+        direct: 0,
+        protect: 0,
+        blocked: 0,
+    });
+    return Object.freeze({
+        version: GATEWAY_PLAN_VERSION,
+        valid: false,
+        ready: false,
+        reason: "INVALID_MANIFEST",
+        entries,
+        direct: entries,
+        protect: entries,
+        blocked: entries,
+        summary,
+    });
+}
+/**
+ * Plan how a runtime-selected tool subset should cross the Once Gateway.
+ *
+ * This is a pure control-plane operation. It does not execute tools, resolve
+ * per-invocation operation identity/effect payload, open local protection
+ * state, contact MCP/providers, or retain executable implementations.
+ *
+ * Existing Connect classification remains authoritative:
+ * BYPASS -> DIRECT, PROTECT -> PROTECT, UNKNOWN -> BLOCK.
+ */
+export function planGatewayToolset(manifest) {
+    const normalized = normalizeConnectToolManifest(manifest);
+    const connectPlan = planConnectToolManifest(manifest);
+    if (!normalized ||
+        !connectPlan.valid ||
+        normalized.length !== connectPlan.entries.length) {
+        return invalidPlan();
+    }
+    const entries = connectPlan.entries.map((connectEntry, index) => {
+        const normalizedEntry = normalized[index];
+        return freezeEntry({
+            index,
+            name: connectEntry.name,
+            source: connectEntry.source,
+            route: mapRoute(connectEntry.decision),
+            descriptorFingerprint: gatewayDescriptorFingerprint(normalizedEntry.descriptor),
+            connectDecision: connectEntry.decision,
+            connectReason: connectEntry.reason,
+            signals: connectEntry.signals,
+        });
+    });
+    const direct = entries.filter(entry => entry.route === GATEWAY_ROUTE.DIRECT);
+    const protect = entries.filter(entry => entry.route === GATEWAY_ROUTE.PROTECT);
+    const blocked = entries.filter(entry => entry.route === GATEWAY_ROUTE.BLOCK);
+    const summary = Object.freeze({
+        total: entries.length,
+        direct: direct.length,
+        protect: protect.length,
+        blocked: blocked.length,
+    });
+    return Object.freeze({
+        version: GATEWAY_PLAN_VERSION,
+        valid: true,
+        ready: blocked.length === 0,
+        reason: "PLANNED",
+        entries: Object.freeze(entries),
+        direct: Object.freeze(direct),
+        protect: Object.freeze(protect),
+        blocked: Object.freeze(blocked),
+        summary,
+    });
+}
+//# sourceMappingURL=planner.js.map

package/dist/gateway/planner.js.map

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

package/dist/gateway/tool-graph-binding.d.ts

@@ -0,0 +1,51 @@
+import type { ToolEvidenceLevel, ToolProtectionState } from "../tool-importance.js";
+import { type GatewayPlan, type GatewayRoute } from "./planner.js";
+export type GatewayToolGraphBinding = Readonly<{
+    toolId: string;
+    namespacedName: string;
+    canonicalName: string;
+    descriptorFingerprint: string;
+    evidenceLevel: ToolEvidenceLevel;
+    actionPriorityScore?: number;
+    protection?: ToolProtectionState;
+}>;
+export type GatewayToolGraphBindingStatus = "MATCHED" | "MISSING" | "FINGERPRINT_MISMATCH" | "AMBIGUOUS" | "NOT_ROUTABLE";
+export type BoundGatewayPlanEntry = Readonly<{
+    index: number;
+    name: string | null;
+    plannedRoute: GatewayRoute;
+    route: GatewayRoute;
+    descriptorFingerprint: string;
+    bindingStatus: GatewayToolGraphBindingStatus;
+    toolGraph?: GatewayToolGraphBinding;
+}>;
+export type BoundGatewayPlanSummary = Readonly<{
+    total: number;
+    matched: number;
+    missing: number;
+    fingerprintMismatch: number;
+    ambiguous: number;
+    blocked: number;
+}>;
+export type BoundGatewayPlan = Readonly<{
+    valid: boolean;
+    ready: boolean;
+    entries: readonly BoundGatewayPlanEntry[];
+    matched: readonly BoundGatewayPlanEntry[];
+    blocked: readonly BoundGatewayPlanEntry[];
+    summary: BoundGatewayPlanSummary;
+}>;
+/**
+ * Bind a gateway route plan to safe Tool Graph identity records.
+ *
+ * Binding is intentionally stricter than name matching: one and only one
+ * Tool Graph record must match both canonical name and the exact gateway
+ * descriptor fingerprint. Evidence/protection state is retained only for
+ * reporting; it never downgrades a PROTECT route to DIRECT.
+ *
+ * The caller may pass a larger/global Tool Graph binding set. Unrelated
+ * entries are ignored, so binding the selected runtime subset does not force
+ * the global catalog into model context or into the returned plan.
+ */
+export declare function bindGatewayPlanToToolGraph(plan: Readonly<GatewayPlan>, bindings: readonly unknown[]): BoundGatewayPlan;
+//# sourceMappingURL=tool-graph-binding.d.ts.map

package/dist/gateway/tool-graph-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-graph-binding.d.ts","sourceRoot":"","sources":["../../src/gateway/tool-graph-binding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,WAAW,EAEhB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,iBAAiB,CAAC;IACjC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,mBAAmB,CAAC;CAClC,CAAC,CAAC;AAEH,MAAM,MAAM,6BAA6B,GACrC,SAAS,GACT,SAAS,GACT,sBAAsB,GACtB,WAAW,GACX,cAAc,CAAC;AAEnB,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,YAAY,EAAE,YAAY,CAAC;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,6BAA6B,CAAC;IAC7C,SAAS,CAAC,EAAE,uBAAuB,CAAC;CACrC,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC1C,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC1C,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC1C,OAAO,EAAE,uBAAuB,CAAC;CAClC,CAAC,CAAC;AA+EH;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,QAAQ,CAAC,WAAW,CAAC,EAC3B,QAAQ,EAAE,SAAS,OAAO,EAAE,GAC3B,gBAAgB,CA8DlB"}

package/dist/gateway/tool-graph-binding.js

@@ -0,0 +1,123 @@
+import { GATEWAY_ROUTE, } from "./planner.js";
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+function validScore(value) {
+    return value === undefined ||
+        (typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 100);
+}
+const evidenceLevels = new Set([
+    "EXECUTED",
+    "MODEL_VISIBLE",
+    "RUNTIME_REGISTERED",
+    "SERVER_AUTHORITATIVE",
+    "HOST_CONFIGURED",
+    "SOURCE_DISCOVERED",
+    "REGISTRY_CANDIDATE",
+]);
+const protectionStates = new Set([
+    "NONE",
+    "NATIVE_IDEMPOTENCY",
+    "AUTHORITATIVE_RECONCILIATION",
+    "ONCE_HEALTHY",
+    "ONCE_UNVERIFIED",
+]);
+function normalizeBinding(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const record = value;
+    if (!nonEmptyString(record.toolId) ||
+        !nonEmptyString(record.namespacedName) ||
+        !nonEmptyString(record.canonicalName) ||
+        !nonEmptyString(record.descriptorFingerprint) ||
+        !evidenceLevels.has(record.evidenceLevel) ||
+        !validScore(record.actionPriorityScore) ||
+        (record.protection !== undefined &&
+            !protectionStates.has(record.protection))) {
+        return undefined;
+    }
+    return Object.freeze({
+        toolId: record.toolId,
+        namespacedName: record.namespacedName,
+        canonicalName: record.canonicalName,
+        descriptorFingerprint: record.descriptorFingerprint,
+        evidenceLevel: record.evidenceLevel,
+        ...(record.actionPriorityScore !== undefined
+            ? { actionPriorityScore: record.actionPriorityScore }
+            : {}),
+        ...(record.protection !== undefined
+            ? { protection: record.protection }
+            : {}),
+    });
+}
+function blockedEntry(entry, bindingStatus) {
+    return Object.freeze({
+        index: entry.index,
+        name: entry.name,
+        plannedRoute: entry.route,
+        route: GATEWAY_ROUTE.BLOCK,
+        descriptorFingerprint: entry.descriptorFingerprint,
+        bindingStatus,
+    });
+}
+/**
+ * Bind a gateway route plan to safe Tool Graph identity records.
+ *
+ * Binding is intentionally stricter than name matching: one and only one
+ * Tool Graph record must match both canonical name and the exact gateway
+ * descriptor fingerprint. Evidence/protection state is retained only for
+ * reporting; it never downgrades a PROTECT route to DIRECT.
+ *
+ * The caller may pass a larger/global Tool Graph binding set. Unrelated
+ * entries are ignored, so binding the selected runtime subset does not force
+ * the global catalog into model context or into the returned plan.
+ */
+export function bindGatewayPlanToToolGraph(plan, bindings) {
+    const normalized = Array.isArray(bindings)
+        ? bindings
+            .map(normalizeBinding)
+            .filter((binding) => Boolean(binding))
+        : [];
+    const entries = plan.entries.map(entry => {
+        if (entry.route === GATEWAY_ROUTE.BLOCK || !entry.name) {
+            return blockedEntry(entry, "NOT_ROUTABLE");
+        }
+        const sameName = normalized.filter(binding => binding.canonicalName === entry.name);
+        const exact = sameName.filter(binding => binding.descriptorFingerprint === entry.descriptorFingerprint);
+        if (exact.length > 1) {
+            return blockedEntry(entry, "AMBIGUOUS");
+        }
+        if (exact.length === 0) {
+            return blockedEntry(entry, sameName.length > 0 ? "FINGERPRINT_MISMATCH" : "MISSING");
+        }
+        return Object.freeze({
+            index: entry.index,
+            name: entry.name,
+            plannedRoute: entry.route,
+            route: entry.route,
+            descriptorFingerprint: entry.descriptorFingerprint,
+            bindingStatus: "MATCHED",
+            toolGraph: exact[0],
+        });
+    });
+    const matched = entries.filter(entry => entry.bindingStatus === "MATCHED");
+    const blocked = entries.filter(entry => entry.route === GATEWAY_ROUTE.BLOCK);
+    const summary = Object.freeze({
+        total: entries.length,
+        matched: matched.length,
+        missing: entries.filter(entry => entry.bindingStatus === "MISSING").length,
+        fingerprintMismatch: entries.filter(entry => entry.bindingStatus === "FINGERPRINT_MISMATCH").length,
+        ambiguous: entries.filter(entry => entry.bindingStatus === "AMBIGUOUS").length,
+        blocked: blocked.length,
+    });
+    return Object.freeze({
+        valid: plan.valid,
+        ready: plan.valid && plan.ready && blocked.length === 0,
+        entries: Object.freeze(entries),
+        matched: Object.freeze(matched),
+        blocked: Object.freeze(blocked),
+        summary,
+    });
+}
+//# sourceMappingURL=tool-graph-binding.js.map

package/dist/gateway/tool-graph-binding.js.map

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

package/dist/langchain-execution-observer.d.ts

@@ -0,0 +1,22 @@
+import { type ToolExecutionObservation } from "./execution-observation.js";
+import type { LangChainModelVisibleToolSnapshot } from "./langchain-runtime-discovery.js";
+export type LangChainExecutionObserver = Readonly<{
+    name: "once-execution-observer";
+    handleToolStart: (...args: unknown[]) => void;
+    handleToolEnd: (...args: unknown[]) => void;
+    handleToolError: (...args: unknown[]) => void;
+    events: () => readonly ToolExecutionObservation[];
+    drain: () => readonly ToolExecutionObservation[];
+    pendingCount: () => number;
+}>;
+/**
+ * Create a dependency-free object compatible with LangChain callback handler
+ * methods for tool execution observation.
+ *
+ * The observer never invokes a tool and never retains input, output, errors,
+ * tags, metadata or parent run state. A matching handleToolStart establishes
+ * exact tool identity; handleToolEnd/handleToolError close that run as
+ * SUCCEEDED/FAILED respectively.
+ */
+export declare function createLangChainExecutionObserver(visibleSnapshot: LangChainModelVisibleToolSnapshot): LangChainExecutionObserver;
+//# sourceMappingURL=langchain-execution-observer.d.ts.map

package/dist/langchain-execution-observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"langchain-execution-observer.d.ts","sourceRoot":"","sources":["../src/langchain-execution-observer.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EACV,iCAAiC,EAElC,MAAM,kCAAkC,CAAC;AAU1C,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,IAAI,EAAE,yBAAyB,CAAC;IAChC,eAAe,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAC9C,aAAa,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAC5C,eAAe,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAC9C,MAAM,EAAE,MAAM,SAAS,wBAAwB,EAAE,CAAC;IAClD,KAAK,EAAE,MAAM,SAAS,wBAAwB,EAAE,CAAC;IACjD,YAAY,EAAE,MAAM,MAAM,CAAC;CAC5B,CAAC,CAAC;AAyDH;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAC9C,eAAe,EAAE,iCAAiC,GACjD,0BAA0B,CAyE5B"}