@once-agent/sdk 0.1.10 → 0.1.12

package/dist/discovery/index.js

@@ -0,0 +1,8 @@
+export { discoverOpenAIAgentRuntime, discoverOpenAIResponsesModelVisibleTools, discoverVercelAiSdkRegisteredTools, discoverVercelAiSdkModelVisibleTools, mergeRuntimeToolEvidence, } from "../runtime-tool-discovery.js";
+export { discoverLangChainRegisteredTools, discoverLangChainModelVisibleTools, } from "../langchain-runtime-discovery.js";
+export { observeToolExecution, aggregateToolExecutions, executionToolFingerprint, promoteToolExecution, } from "../execution-observation.js";
+export { createOpenAIAgentsExecutionObserver, } from "../openai-agents-execution-observer.js";
+export { observeVercelAiSdkStepExecutions, } from "../vercel-execution-observer.js";
+export { createLangChainExecutionObserver, } from "../langchain-execution-observer.js";
+export { observeOtelGenAiToolExecutions, } from "../otel-execution-observer.js";
+//# sourceMappingURL=index.js.map

package/dist/discovery/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,wCAAwC,EACxC,kCAAkC,EAClC,oCAAoC,EACpC,wBAAwB,GACzB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,gCAAgC,EAChC,kCAAkC,GACnC,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,mCAAmC,GACpC,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EACL,gCAAgC,GACjC,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,gCAAgC,GACjC,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EACL,8BAA8B,GAC/B,MAAM,+BAA+B,CAAC"}

package/dist/execution-observation.d.ts

@@ -0,0 +1,122 @@
+import { type ToolEvidenceLevel, type ToolImportanceAssessment } from "./tool-importance.js";
+export type ToolExecutionStatus = "SUCCEEDED" | "FAILED" | "UNKNOWN";
+export type ToolExecutionSource = "framework_callback" | "otel" | "adapter";
+export type ToolExecutionObservationInput = {
+    eventId?: string;
+    toolId?: string;
+    namespacedName?: string;
+    descriptorFingerprint?: string;
+    canonicalName?: string;
+    framework?: string;
+    runtimeName?: string;
+    source: ToolExecutionSource;
+    status: ToolExecutionStatus;
+    observedAt?: string;
+    durationMs?: number;
+};
+export type ToolExecutionObservation = Readonly<{
+    eventId?: string;
+    toolId?: string;
+    namespacedName?: string;
+    descriptorFingerprint?: string;
+    canonicalName?: string;
+    framework?: string;
+    runtimeName?: string;
+    source: ToolExecutionSource;
+    status: ToolExecutionStatus;
+    observedAt: string;
+    durationMs?: number;
+}>;
+export type ToolExecutionObservationRejection = Readonly<{
+    accepted: false;
+    reason: "INVALID_EVENT" | "IDENTITY_REQUIRED" | "INVALID_STATUS" | "INVALID_SOURCE" | "INVALID_TIMESTAMP" | "INVALID_DURATION";
+}>;
+export type ToolExecutionObservationAcceptance = Readonly<{
+    accepted: true;
+    event: ToolExecutionObservation;
+}>;
+export type ToolExecutionObservationResult = ToolExecutionObservationAcceptance | ToolExecutionObservationRejection;
+export type ToolExecutionSummary = Readonly<{
+    identityKey: string;
+    toolId?: string;
+    namespacedName?: string;
+    descriptorFingerprint?: string;
+    canonicalName?: string;
+    framework?: string;
+    runtimeName?: string;
+    callCount: number;
+    succeededCount: number;
+    failedCount: number;
+    unknownCount: number;
+    firstObservedAt: string;
+    lastObservedAt: string;
+    latestStatus: ToolExecutionStatus;
+    totalDurationMs?: number;
+    averageDurationMs?: number;
+    sources: readonly ToolExecutionSource[];
+}>;
+export type ToolExecutionAggregate = Readonly<{
+    summaries: readonly ToolExecutionSummary[];
+    acceptedEventCount: number;
+    rejectedEventCount: number;
+    duplicateEventCount: number;
+}>;
+export type ExecutionPromotableTool = {
+    toolId: string;
+    namespacedName: string;
+    canonicalName: string;
+    description?: string;
+    toolType?: string;
+    inputSchema?: unknown;
+    safeMetadata?: unknown;
+    evidence: {
+        level: ToolEvidenceLevel;
+        source: string;
+    };
+    visibility: {
+        configured: boolean;
+        runtimeRegistered: boolean;
+        modelVisible: boolean;
+        executed: boolean;
+    };
+    once: ToolImportanceAssessment;
+};
+export type ExecutedToolObservation<T extends ExecutionPromotableTool> = Omit<T, "evidence" | "visibility" | "once"> & {
+    evidence: {
+        level: "EXECUTED";
+        source: string;
+    };
+    visibility: T["visibility"] & {
+        executed: true;
+    };
+    execution: ToolExecutionSummary;
+    once: ToolImportanceAssessment;
+};
+/**
+ * Stable fingerprint of the safe descriptor already retained by discovery.
+ * This closes same-name/toolId collision risk without reading executable or
+ * getter-backed runtime state.
+ */
+export declare function executionToolFingerprint(tool: ExecutionPromotableTool): string;
+/**
+ * Convert callback/telemetry metadata into a secret-minimal execution event.
+ *
+ * This function intentionally whitelists fields. Tool arguments, prompts,
+ * results, error messages, auth data, callbacks and runtime objects are never
+ * copied into the observation, even when present on the input object.
+ */
+export declare function observeToolExecution(input: unknown): ToolExecutionObservationResult;
+/**
+ * Aggregate already-observed execution metadata without retaining raw call data.
+ * Duplicate event IDs are ignored so replayed telemetry batches do not inflate
+ * observed execution counts.
+ */
+export declare function aggregateToolExecutions(inputs: readonly unknown[]): ToolExecutionAggregate;
+/**
+ * Promote a discovered tool to EXECUTED evidence only after exact identity
+ * correlation plus a safe-descriptor fingerprint match. Canonical/display
+ * names alone are never sufficient because same-named tools may exist in
+ * different agents, runtimes or servers and older discovery IDs may collide.
+ */
+export declare function promoteToolExecution<T extends ExecutionPromotableTool>(tool: T, summary: ToolExecutionSummary): ExecutedToolObservation<T> | undefined;
+//# sourceMappingURL=execution-observation.d.ts.map

package/dist/execution-observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-observation.d.ts","sourceRoot":"","sources":["../src/execution-observation.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC9B,MAAM,sBAAsB,CAAC;AAE9B,MAAM,MAAM,mBAAmB,GAC3B,WAAW,GACX,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,MAAM,mBAAmB,GAC3B,oBAAoB,GACpB,MAAM,GACN,SAAS,CAAC;AAEd,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AAEH,MAAM,MAAM,iCAAiC,GAAG,QAAQ,CAAC;IACvD,QAAQ,EAAE,KAAK,CAAC;IAChB,MAAM,EACF,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,gBAAgB,GAChB,mBAAmB,GACnB,kBAAkB,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,MAAM,kCAAkC,GAAG,QAAQ,CAAC;IACxD,QAAQ,EAAE,IAAI,CAAC;IACf,KAAK,EAAE,wBAAwB,CAAC;CACjC,CAAC,CAAC;AAEH,MAAM,MAAM,8BAA8B,GACtC,kCAAkC,GAClC,iCAAiC,CAAC;AAEtC,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,mBAAmB,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACzC,CAAC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,SAAS,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC3C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,EAAE;QACR,KAAK,EAAE,iBAAiB,CAAC;QACzB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,UAAU,EAAE;QACV,UAAU,EAAE,OAAO,CAAC;QACpB,iBAAiB,EAAE,OAAO,CAAC;QAC3B,YAAY,EAAE,OAAO,CAAC;QACtB,QAAQ,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,IAAI,EAAE,wBAAwB,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,CAAC,SAAS,uBAAuB,IACnE,IAAI,CAAC,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,MAAM,CAAC,GAAG;IAC5C,QAAQ,EAAE;QACR,KAAK,EAAE,UAAU,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,UAAU,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG;QAC5B,QAAQ,EAAE,IAAI,CAAC;KAChB,CAAC;IACF,SAAS,EAAE,oBAAoB,CAAC;IAChC,IAAI,EAAE,wBAAwB,CAAC;CAChC,CAAC;AAyGJ;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,uBAAuB,GAC5B,MAAM,CAaR;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,8BAA8B,CAyFhC;AAeD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,OAAO,EAAE,GACzB,sBAAsB,CAwFxB;AAyBD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,CAAC,SAAS,uBAAuB,EAEjC,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,oBAAoB,GAC5B,uBAAuB,CAAC,CAAC,CAAC,GAAG,SAAS,CAiCxC"}

package/dist/execution-observation.js

@@ -0,0 +1,324 @@
+import { createHash } from "node:crypto";
+import { assessToolImportance, } from "./tool-importance.js";
+const VALID_STATUS = new Set([
+    "SUCCEEDED",
+    "FAILED",
+    "UNKNOWN",
+]);
+const VALID_SOURCE = new Set([
+    "framework_callback",
+    "otel",
+    "adapter",
+]);
+function ownDataValue(value, key) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    return descriptor && "value" in descriptor
+        ? descriptor.value
+        : undefined;
+}
+function optionalString(value) {
+    return typeof value === "string" && value.trim() !== ""
+        ? value
+        : undefined;
+}
+function validTimestamp(value) {
+    if (value === undefined) {
+        return new Date().toISOString();
+    }
+    if (typeof value !== "string" || value.trim() === "") {
+        return undefined;
+    }
+    const time = Date.parse(value);
+    if (!Number.isFinite(time))
+        return undefined;
+    return new Date(time).toISOString();
+}
+function canonicalFingerprintValue(value, depth = 0, seen = new Set()) {
+    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 undefined;
+    }
+    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++) {
+                const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+                output.push(descriptor && "value" in descriptor
+                    ? canonicalFingerprintValue(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))
+                continue;
+            const child = canonicalFingerprintValue(descriptor.value, depth + 1, seen);
+            if (child !== undefined)
+                output[key] = child;
+        }
+        return output;
+    }
+    finally {
+        seen.delete(objectValue);
+    }
+}
+/**
+ * Stable fingerprint of the safe descriptor already retained by discovery.
+ * This closes same-name/toolId collision risk without reading executable or
+ * getter-backed runtime state.
+ */
+export function executionToolFingerprint(tool) {
+    const canonical = canonicalFingerprintValue({
+        namespacedName: tool.namespacedName,
+        canonicalName: tool.canonicalName,
+        description: tool.description ?? "",
+        toolType: tool.toolType ?? "",
+        inputSchema: tool.inputSchema,
+        safeMetadata: tool.safeMetadata,
+    });
+    return createHash("sha256")
+        .update(JSON.stringify(canonical))
+        .digest("hex");
+}
+/**
+ * Convert callback/telemetry metadata into a secret-minimal execution event.
+ *
+ * This function intentionally whitelists fields. Tool arguments, prompts,
+ * results, error messages, auth data, callbacks and runtime objects are never
+ * copied into the observation, even when present on the input object.
+ */
+export function observeToolExecution(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        return Object.freeze({
+            accepted: false,
+            reason: "INVALID_EVENT",
+        });
+    }
+    const toolId = optionalString(ownDataValue(input, "toolId"));
+    const namespacedName = optionalString(ownDataValue(input, "namespacedName"));
+    if (!toolId && !namespacedName) {
+        return Object.freeze({
+            accepted: false,
+            reason: "IDENTITY_REQUIRED",
+        });
+    }
+    const status = ownDataValue(input, "status");
+    if (typeof status !== "string" || !VALID_STATUS.has(status)) {
+        return Object.freeze({
+            accepted: false,
+            reason: "INVALID_STATUS",
+        });
+    }
+    const source = ownDataValue(input, "source");
+    if (typeof source !== "string" || !VALID_SOURCE.has(source)) {
+        return Object.freeze({
+            accepted: false,
+            reason: "INVALID_SOURCE",
+        });
+    }
+    const observedAt = validTimestamp(ownDataValue(input, "observedAt"));
+    if (!observedAt) {
+        return Object.freeze({
+            accepted: false,
+            reason: "INVALID_TIMESTAMP",
+        });
+    }
+    const rawDuration = ownDataValue(input, "durationMs");
+    if (rawDuration !== undefined &&
+        (typeof rawDuration !== "number" ||
+            !Number.isFinite(rawDuration) ||
+            rawDuration < 0)) {
+        return Object.freeze({
+            accepted: false,
+            reason: "INVALID_DURATION",
+        });
+    }
+    const eventId = optionalString(ownDataValue(input, "eventId"));
+    const descriptorFingerprint = optionalString(ownDataValue(input, "descriptorFingerprint"));
+    const canonicalName = optionalString(ownDataValue(input, "canonicalName"));
+    const framework = optionalString(ownDataValue(input, "framework"));
+    const runtimeName = optionalString(ownDataValue(input, "runtimeName"));
+    const event = Object.freeze({
+        ...(eventId ? { eventId } : {}),
+        ...(toolId ? { toolId } : {}),
+        ...(namespacedName ? { namespacedName } : {}),
+        ...(descriptorFingerprint ? { descriptorFingerprint } : {}),
+        ...(canonicalName ? { canonicalName } : {}),
+        ...(framework ? { framework } : {}),
+        ...(runtimeName ? { runtimeName } : {}),
+        source: source,
+        status: status,
+        observedAt,
+        ...(typeof rawDuration === "number"
+            ? { durationMs: rawDuration }
+            : {}),
+    });
+    return Object.freeze({
+        accepted: true,
+        event,
+    });
+}
+function identityKey(event) {
+    const identity = event.toolId
+        ? `tool:${event.toolId}`
+        : `name:${event.namespacedName}`;
+    return event.descriptorFingerprint
+        ? `${identity}:descriptor:${event.descriptorFingerprint}`
+        : identity;
+}
+function compareTimestamp(left, right) {
+    return Date.parse(left) - Date.parse(right);
+}
+/**
+ * Aggregate already-observed execution metadata without retaining raw call data.
+ * Duplicate event IDs are ignored so replayed telemetry batches do not inflate
+ * observed execution counts.
+ */
+export function aggregateToolExecutions(inputs) {
+    const accepted = [];
+    let rejectedEventCount = 0;
+    let duplicateEventCount = 0;
+    const seenEventIds = new Set();
+    for (const input of inputs) {
+        const result = observeToolExecution(input);
+        if (!result.accepted) {
+            rejectedEventCount += 1;
+            continue;
+        }
+        if (result.event.eventId) {
+            if (seenEventIds.has(result.event.eventId)) {
+                duplicateEventCount += 1;
+                continue;
+            }
+            seenEventIds.add(result.event.eventId);
+        }
+        accepted.push(result.event);
+    }
+    const groups = new Map();
+    for (const event of accepted) {
+        const key = identityKey(event);
+        const existing = groups.get(key);
+        if (existing) {
+            existing.push(event);
+        }
+        else {
+            groups.set(key, [event]);
+        }
+    }
+    const summaries = [];
+    for (const [key, events] of groups.entries()) {
+        const ordered = [...events].sort((left, right) => compareTimestamp(left.observedAt, right.observedAt));
+        const first = ordered[0];
+        const last = ordered[ordered.length - 1];
+        const durations = ordered
+            .map(event => event.durationMs)
+            .filter((value) => typeof value === "number");
+        const totalDurationMs = durations.reduce((sum, value) => sum + value, 0);
+        const sources = Object.freeze([
+            ...new Set(ordered.map(event => event.source)),
+        ]);
+        summaries.push(Object.freeze({
+            identityKey: key,
+            ...(last.toolId ? { toolId: last.toolId } : {}),
+            ...(last.namespacedName ? { namespacedName: last.namespacedName } : {}),
+            ...(last.descriptorFingerprint
+                ? { descriptorFingerprint: last.descriptorFingerprint }
+                : {}),
+            ...(last.canonicalName ? { canonicalName: last.canonicalName } : {}),
+            ...(last.framework ? { framework: last.framework } : {}),
+            ...(last.runtimeName ? { runtimeName: last.runtimeName } : {}),
+            callCount: ordered.length,
+            succeededCount: ordered.filter(event => event.status === "SUCCEEDED").length,
+            failedCount: ordered.filter(event => event.status === "FAILED").length,
+            unknownCount: ordered.filter(event => event.status === "UNKNOWN").length,
+            firstObservedAt: first.observedAt,
+            lastObservedAt: last.observedAt,
+            latestStatus: last.status,
+            ...(durations.length > 0
+                ? {
+                    totalDurationMs,
+                    averageDurationMs: totalDurationMs / durations.length,
+                }
+                : {}),
+            sources,
+        }));
+    }
+    summaries.sort((left, right) => left.identityKey.localeCompare(right.identityKey));
+    return Object.freeze({
+        summaries: Object.freeze(summaries),
+        acceptedEventCount: accepted.length,
+        rejectedEventCount,
+        duplicateEventCount,
+    });
+}
+function summaryMatchesTool(tool, summary) {
+    if (!summary.descriptorFingerprint)
+        return false;
+    if (summary.descriptorFingerprint !== executionToolFingerprint(tool)) {
+        return false;
+    }
+    if (summary.toolId && summary.toolId !== tool.toolId) {
+        return false;
+    }
+    if (summary.namespacedName &&
+        summary.namespacedName !== tool.namespacedName) {
+        return false;
+    }
+    return Boolean(summary.toolId || summary.namespacedName);
+}
+/**
+ * Promote a discovered tool to EXECUTED evidence only after exact identity
+ * correlation plus a safe-descriptor fingerprint match. Canonical/display
+ * names alone are never sufficient because same-named tools may exist in
+ * different agents, runtimes or servers and older discovery IDs may collide.
+ */
+export function promoteToolExecution(tool, summary) {
+    if (!summaryMatchesTool(tool, summary)) {
+        return undefined;
+    }
+    const visibility = Object.freeze({
+        ...tool.visibility,
+        executed: true,
+    });
+    const once = assessToolImportance({
+        name: tool.canonicalName,
+        description: tool.description,
+        sourceCategory: tool.toolType,
+        evidence: "EXECUTED",
+        qualification: tool.once.qualification,
+        protection: tool.once.protection,
+        readOnlyHint: tool.once.effectClass === "READ_ONLY"
+            ? true
+            : undefined,
+    });
+    return Object.freeze({
+        ...tool,
+        evidence: Object.freeze({
+            level: "EXECUTED",
+            source: `execution:${summary.sources.join(",")}`,
+        }),
+        visibility,
+        execution: summary,
+        once,
+    });
+}
+//# sourceMappingURL=execution-observation.js.map

package/dist/execution-observation.js.map

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

package/dist/gateway/index.d.ts

@@ -0,0 +1,9 @@
+export { GATEWAY_ROUTE, GATEWAY_PLAN_VERSION, gatewayDescriptorFingerprint, planGatewayToolset, } from "./planner.js";
+export { GatewayConnectionError, connectLocalGatewayToolsetAuto, } from "./local-toolset.js";
+export { bindGatewayPlanToToolGraph, } from "./tool-graph-binding.js";
+export { connectOpenAIAgentsFunctionToolsGatewayAuto, } from "./openai-function-tools.js";
+export type { GatewayRoute, GatewayPlanEntry, GatewayPlanSummary, GatewayPlan, } from "./planner.js";
+export type { LocalGatewayToolsetOptions, ConnectedLocalGatewayToolset, } from "./local-toolset.js";
+export type { GatewayToolGraphBinding, GatewayToolGraphBindingStatus, BoundGatewayPlanEntry, BoundGatewayPlanSummary, BoundGatewayPlan, } from "./tool-graph-binding.js";
+export type { GatewayOpenAIAgentsFunctionToolsOptions, GatewayOpenAIAgentsFunctionTools, } from "./openai-function-tools.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,sBAAsB,EACtB,8BAA8B,GAC/B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,0BAA0B,GAC3B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,2CAA2C,GAC5C,MAAM,4BAA4B,CAAC;AAEpC,YAAY,EACV,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,GACZ,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,uBAAuB,EACvB,6BAA6B,EAC7B,qBAAqB,EACrB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EACV,uCAAuC,EACvC,gCAAgC,GACjC,MAAM,4BAA4B,CAAC"}

package/dist/gateway/index.js

@@ -0,0 +1,5 @@
+export { GATEWAY_ROUTE, GATEWAY_PLAN_VERSION, gatewayDescriptorFingerprint, planGatewayToolset, } from "./planner.js";
+export { GatewayConnectionError, connectLocalGatewayToolsetAuto, } from "./local-toolset.js";
+export { bindGatewayPlanToToolGraph, } from "./tool-graph-binding.js";
+export { connectOpenAIAgentsFunctionToolsGatewayAuto, } from "./openai-function-tools.js";
+//# sourceMappingURL=index.js.map

package/dist/gateway/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/gateway/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,oBAAoB,EACpB,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,sBAAsB,EACtB,8BAA8B,GAC/B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,0BAA0B,GAC3B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,2CAA2C,GAC5C,MAAM,4BAA4B,CAAC"}

package/dist/gateway/local-toolset.d.ts

@@ -0,0 +1,32 @@
+import { type AutoLocalAgentToolsetOptions, type ConnectedLocalAgentToolRegistry, type LocalAgentToolRegistry } from "../connect/toolset.js";
+import { type GatewayPlan } from "./planner.js";
+import { type BoundGatewayPlan, type GatewayToolGraphBinding } from "./tool-graph-binding.js";
+export interface LocalGatewayToolsetOptions extends AutoLocalAgentToolsetOptions {
+    /** Optional exact Tool Graph identities for the selected runtime subset. */
+    toolGraphBindings?: readonly GatewayToolGraphBinding[];
+}
+export interface ConnectedLocalGatewayToolset<T extends LocalAgentToolRegistry> {
+    /** Frozen gateway route plan for exactly the supplied runtime-selected subset. */
+    plan: Readonly<GatewayPlan>;
+    /** Exact Tool Graph binding result when bindings were supplied. */
+    binding?: BoundGatewayPlan;
+    /** Frozen registry. Expose this registry to the runtime instead of the originals. */
+    tools: Readonly<ConnectedLocalAgentToolRegistry<T>>;
+}
+export declare class GatewayConnectionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Wire a complete runtime-selected local tool subset through the Once Gateway.
+ *
+ * This function intentionally contains no execution engine. It performs a
+ * gateway preflight, optionally binds exact Tool Graph identity, then delegates
+ * registry validation and wrapper creation to the existing Connect toolset.
+ *
+ * A selected subset containing BLOCK cannot be partially wired. Returning a
+ * mixed registry would leave an unprotected bypass surface for unresolved
+ * tools, so v1 fails the whole selected subset closed.
+ */
+export declare function connectLocalGatewayToolsetAuto<T extends LocalAgentToolRegistry>(tools: T, options: LocalGatewayToolsetOptions): Readonly<ConnectedLocalGatewayToolset<T>>;
+//# sourceMappingURL=local-toolset.d.ts.map

package/dist/gateway/local-toolset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-toolset.d.ts","sourceRoot":"","sources":["../../src/gateway/local-toolset.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,4BAA4B,EACjC,KAAK,+BAA+B,EACpC,KAAK,sBAAsB,EAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC7B,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,0BACf,SAAQ,4BAA4B;IACpC,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;CACxD;AAED,MAAM,WAAW,4BAA4B,CAC3C,CAAC,SAAS,sBAAsB;IAEhC,kFAAkF;IAClF,IAAI,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAC5B,mEAAmE;IACnE,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,qFAAqF;IACrF,KAAK,EAAE,QAAQ,CAAC,+BAA+B,CAAC,CAAC,CAAC,CAAC,CAAC;CACrD;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAInD;AA+CD;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,CAC5C,CAAC,SAAS,sBAAsB,EAEhC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,0BAA0B,GAClC,QAAQ,CAAC,4BAA4B,CAAC,CAAC,CAAC,CAAC,CAkD3C"}

package/dist/gateway/local-toolset.js

@@ -0,0 +1,79 @@
+import { connectLocalAgentToolsetAuto, } from "../connect/toolset.js";
+import { GATEWAY_ROUTE, planGatewayToolset, } from "./planner.js";
+import { bindGatewayPlanToToolGraph, } from "./tool-graph-binding.js";
+export class GatewayConnectionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "GatewayConnectionError";
+    }
+}
+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, connectPlan) {
+    if (gatewayPlan.entries.length !== connectPlan.entries.length) {
+        throw new GatewayConnectionError("GATEWAY_PLAN_MISMATCH", "Gateway and Connect disagree about the selected toolset length.");
+    }
+    for (let index = 0; index < gatewayPlan.entries.length; index += 1) {
+        const gateway = gatewayPlan.entries[index];
+        const connect = connectPlan.entries[index];
+        const expected = gateway.route === GATEWAY_ROUTE.DIRECT
+            ? "BYPASS"
+            : gateway.route === GATEWAY_ROUTE.PROTECT
+                ? "PROTECT"
+                : "UNKNOWN";
+        if (connect.decision !== expected) {
+            throw new GatewayConnectionError("GATEWAY_PLAN_MISMATCH", `Gateway and Connect disagree about route index ${index}.`);
+        }
+    }
+}
+/**
+ * Wire a complete runtime-selected local tool subset through the Once Gateway.
+ *
+ * This function intentionally contains no execution engine. It performs a
+ * gateway preflight, optionally binds exact Tool Graph identity, then delegates
+ * registry validation and wrapper creation to the existing Connect toolset.
+ *
+ * A selected subset containing BLOCK cannot be partially wired. Returning a
+ * mixed registry would leave an unprotected bypass surface for unresolved
+ * tools, so v1 fails the whole selected subset closed.
+ */
+export function connectLocalGatewayToolsetAuto(tools, options) {
+    if (!options || !("manifest" in options)) {
+        throw new GatewayConnectionError("INVALID_GATEWAY_MANIFEST", "Once Gateway needs the complete runtime-selected tool manifest before wiring.");
+    }
+    const plan = planGatewayToolset(options.manifest);
+    if (!plan.valid) {
+        throw new GatewayConnectionError("INVALID_GATEWAY_MANIFEST", "Once Gateway could not parse the supplied runtime-selected tool manifest.");
+    }
+    if (!plan.ready) {
+        throw new GatewayConnectionError("GATEWAY_BLOCKED", `Once Gateway refuses partial wiring while selected-tool routing is unresolved: ${blockedSummary(plan)}.`);
+    }
+    let binding;
+    if (options.toolGraphBindings !== undefined) {
+        if (!Array.isArray(options.toolGraphBindings)) {
+            throw new GatewayConnectionError("INVALID_TOOL_GRAPH_BINDINGS", "Once 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", `Once Gateway refuses wiring because selected tools do not match exact Tool Graph identity: ${bindingBlockedSummary(binding)}.`);
+        }
+    }
+    const connected = connectLocalAgentToolsetAuto(tools, options);
+    verifyConnectAgreement(plan, connected.plan);
+    return Object.freeze({
+        plan,
+        ...(binding ? { binding } : {}),
+        tools: connected.tools,
+    });
+}
+//# sourceMappingURL=local-toolset.js.map

package/dist/gateway/local-toolset.js.map

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