@once-agent/sdk 0.1.4 → 0.1.6

package/dist-cjs/connect/binding.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectBindingError = void 0;
+exports.canonicalizeConnectPayload = canonicalizeConnectPayload;
+exports.fingerprintConnectPayload = fingerprintConnectPayload;
+exports.bindConnectOperation = bindConnectOperation;
+exports.assertConnectBindingMatch = assertConnectBindingMatch;
+const node_crypto_1 = require("node:crypto");
+class ConnectBindingError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "ConnectBindingError";
+        this.code = code;
+    }
+}
+exports.ConnectBindingError = ConnectBindingError;
+function canonicalize(value, path = "$") {
+    if (value === null) {
+        return "null";
+    }
+    const type = typeof value;
+    if (type === "string") {
+        return JSON.stringify(value);
+    }
+    if (type === "boolean") {
+        return value ? "true" : "false";
+    }
+    if (type === "number") {
+        const numberValue = value;
+        if (!Number.isFinite(numberValue)) {
+            throw new ConnectBindingError(`Unsupported non-finite number at ${path}.`, "UNSUPPORTED_PAYLOAD_VALUE");
+        }
+        if (Object.is(numberValue, -0)) {
+            return "0";
+        }
+        return JSON.stringify(numberValue);
+    }
+    if (Array.isArray(value)) {
+        return "[" +
+            value
+                .map((item, index) => canonicalize(item, `${path}[${index}]`))
+                .join(",") +
+            "]";
+    }
+    if (type === "object") {
+        const objectValue = value;
+        const prototype = Object.getPrototypeOf(objectValue);
+        if (prototype !== Object.prototype &&
+            prototype !== null) {
+            throw new ConnectBindingError(`Unsupported object type at ${path}.`, "UNSUPPORTED_PAYLOAD_VALUE");
+        }
+        const keys = Object.keys(objectValue).sort();
+        return "{" +
+            keys
+                .map((key) => `${JSON.stringify(key)}:${canonicalize(objectValue[key], `${path}.${key}`)}`)
+                .join(",") +
+            "}";
+    }
+    throw new ConnectBindingError(`Unsupported payload value at ${path}.`, "UNSUPPORTED_PAYLOAD_VALUE");
+}
+function canonicalizeConnectPayload(payload) {
+    if (payload === null ||
+        typeof payload !== "object" ||
+        Array.isArray(payload)) {
+        throw new ConnectBindingError("Once Connect payload must be a plain object.", "INVALID_PAYLOAD");
+    }
+    return canonicalize(payload);
+}
+function fingerprintConnectPayload(payload) {
+    const canonical = canonicalizeConnectPayload(payload);
+    const digest = (0, node_crypto_1.createHash)("sha256")
+        .update("once-connect-payload-v1\0", "utf8")
+        .update(canonical, "utf8")
+        .digest("hex");
+    return `once-connect-payload-v1:${digest}`;
+}
+function bindConnectOperation({ operationId, payload, }) {
+    if (typeof operationId !== "string" ||
+        operationId.trim() === "") {
+        throw new ConnectBindingError("Once Connect requires a stable operationId.", "INVALID_OPERATION_ID");
+    }
+    return Object.freeze({
+        operationId,
+        payloadFingerprint: fingerprintConnectPayload(payload),
+    });
+}
+function assertConnectBindingMatch(previousBinding, nextBinding) {
+    if (previousBinding.operationId !==
+        nextBinding.operationId) {
+        throw new ConnectBindingError("Operation identities do not match.", "OPERATION_ID_MISMATCH");
+    }
+    if (previousBinding.payloadFingerprint !==
+        nextBinding.payloadFingerprint) {
+        throw new ConnectBindingError("The same operationId was reused with a different consequential payload.", "PAYLOAD_DRIFT");
+    }
+    return true;
+}
+//# sourceMappingURL=binding.js.map

package/dist-cjs/connect/binding.js.map

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

package/dist-cjs/connect/classifier.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONNECT_DECISION = void 0;
+exports.classifyConnectOperation = classifyConnectOperation;
+exports.CONNECT_DECISION = Object.freeze({
+    PROTECT: "PROTECT",
+    BYPASS: "BYPASS",
+    REJECT: "REJECT",
+});
+function requireBoolean(value, name) {
+    if (typeof value !== "boolean") {
+        throw new TypeError(`Once Connect requires boolean "${name}".`);
+    }
+}
+function classifyConnectOperation(operation) {
+    if (!operation ||
+        typeof operation !== "object" ||
+        Array.isArray(operation)) {
+        return Object.freeze({
+            decision: exports.CONNECT_DECISION.REJECT,
+            reason: "INVALID_OPERATION",
+        });
+    }
+    const candidate = operation;
+    const { changesExternalState, retryPossible, ambiguousOutcomePossible, duplicateUndesirable, } = candidate;
+    try {
+        requireBoolean(changesExternalState, "changesExternalState");
+        requireBoolean(retryPossible, "retryPossible");
+        requireBoolean(ambiguousOutcomePossible, "ambiguousOutcomePossible");
+        requireBoolean(duplicateUndesirable, "duplicateUndesirable");
+    }
+    catch {
+        return Object.freeze({
+            decision: exports.CONNECT_DECISION.REJECT,
+            reason: "INCOMPLETE_SAFETY_DECLARATION",
+        });
+    }
+    const requiresProtection = changesExternalState &&
+        retryPossible &&
+        ambiguousOutcomePossible &&
+        duplicateUndesirable;
+    if (requiresProtection) {
+        return Object.freeze({
+            decision: exports.CONNECT_DECISION.PROTECT,
+            reason: "CONSEQUENTIAL_RETRY_RISK",
+        });
+    }
+    return Object.freeze({
+        decision: exports.CONNECT_DECISION.BYPASS,
+        reason: "PROTECTION_CONDITIONS_NOT_ALL_PRESENT",
+    });
+}
+//# sourceMappingURL=classifier.js.map

package/dist-cjs/connect/classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.js","sourceRoot":"","sources":["../../src/connect/classifier.ts"],"names":[],"mappings":";;;AAoCA,4DAqEC;AAzGY,QAAA,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC5C,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,MAAM,EAAE,QAAQ;CACR,CAAC,CAAC;AAqBZ,SAAS,cAAc,CACrB,KAAc,EACd,IAAY;IAEZ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,IAAI,SAAS,CACjB,kCAAkC,IAAI,IAAI,CAC3C,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAgB,wBAAwB,CACtC,SAAkB;IAElB,IACE,CAAC,SAAS;QACV,OAAO,SAAS,KAAK,QAAQ;QAC7B,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EACxB,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,QAAQ,EAAE,wBAAgB,CAAC,MAAM;YACjC,MAAM,EAAE,mBAAmB;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,MAAM,SAAS,GACb,SAAoC,CAAC;IAEvC,MAAM,EACJ,oBAAoB,EACpB,aAAa,EACb,wBAAwB,EACxB,oBAAoB,GACrB,GAAG,SAAS,CAAC;IAEd,IAAI,CAAC;QACH,cAAc,CACZ,oBAAoB,EACpB,sBAAsB,CACvB,CAAC;QAEF,cAAc,CACZ,aAAa,EACb,eAAe,CAChB,CAAC;QAEF,cAAc,CACZ,wBAAwB,EACxB,0BAA0B,CAC3B,CAAC;QAEF,cAAc,CACZ,oBAAoB,EACpB,sBAAsB,CACvB,CAAC;IACJ,CAAC;IACD,MAAM,CAAC;QACL,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,QAAQ,EAAE,wBAAgB,CAAC,MAAM;YACjC,MAAM,EAAE,+BAA+B;SACxC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,kBAAkB,GACtB,oBAAoB;QACpB,aAAa;QACb,wBAAwB;QACxB,oBAAoB,CAAC;IAEvB,IAAI,kBAAkB,EAAE,CAAC;QACvB,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,QAAQ,EAAE,wBAAgB,CAAC,OAAO;YAClC,MAAM,EAAE,0BAA0B;SACnC,CAAC,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,QAAQ,EAAE,wBAAgB,CAAC,MAAM;QACjC,MAAM,EAAE,uCAAuC;KAChD,CAAC,CAAC;AACL,CAAC"}

package/dist-cjs/connect/execute.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectExecutionError = void 0;
+exports.executeConnectOperation = executeConnectOperation;
+const classifier_js_1 = require("./classifier.js");
+const binding_js_1 = require("./binding.js");
+class ConnectExecutionError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "ConnectExecutionError";
+        this.code = code;
+    }
+}
+exports.ConnectExecutionError = ConnectExecutionError;
+/**
+ * Framework-neutral Connect orchestration boundary.
+ *
+ * Connect decides whether the proposed tool call requires
+ * Once protection. It does not implement execution safety.
+ *
+ * Protected execution is delegated to the existing Once
+ * runtime/kernel supplied by the caller.
+ */
+async function executeConnectOperation({ safety, operationId, payload, bypass, protect, }) {
+    const classification = (0, classifier_js_1.classifyConnectOperation)(safety);
+    if (classification.decision ===
+        classifier_js_1.CONNECT_DECISION.REJECT) {
+        throw new ConnectExecutionError("Once Connect rejected an incomplete or invalid safety declaration.", "CONNECT_REJECTED");
+    }
+    if (classification.decision ===
+        classifier_js_1.CONNECT_DECISION.BYPASS) {
+        if (typeof bypass !== "function") {
+            throw new ConnectExecutionError("Once Connect bypass execution is unavailable.", "BYPASS_HANDLER_MISSING");
+        }
+        return await bypass();
+    }
+    const binding = (0, binding_js_1.bindConnectOperation)({
+        operationId,
+        payload,
+    });
+    if (typeof protect !== "function") {
+        throw new ConnectExecutionError("Once Connect protected execution is unavailable.", "PROTECT_HANDLER_MISSING");
+    }
+    return await protect({
+        operationId: binding.operationId,
+        payload,
+        payloadFingerprint: binding.payloadFingerprint,
+        classification,
+    });
+}
+//# sourceMappingURL=execute.js.map

package/dist-cjs/connect/execute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.js","sourceRoot":"","sources":["../../src/connect/execute.ts"],"names":[],"mappings":";;;AAyDA,0DA0DC;AAnHD,mDAGyB;AAOzB,6CAEsB;AAuBtB,MAAa,qBAAsB,SAAQ,KAAK;IACrC,IAAI,CAAS;IAEtB,YACE,OAAe,EACf,IAAY;QAEZ,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAXD,sDAWC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,uBAAuB,CAAc,EACzD,MAAM,EACN,WAAW,EACX,OAAO,EACP,MAAM,EACN,OAAO,GACkB;IACzB,MAAM,cAAc,GAClB,IAAA,wCAAwB,EAAC,MAAM,CAAC,CAAC;IAEnC,IACE,cAAc,CAAC,QAAQ;QACvB,gCAAgB,CAAC,MAAM,EACvB,CAAC;QACD,MAAM,IAAI,qBAAqB,CAC7B,oEAAoE,EACpE,kBAAkB,CACnB,CAAC;IACJ,CAAC;IAED,IACE,cAAc,CAAC,QAAQ;QACvB,gCAAgB,CAAC,MAAM,EACvB,CAAC;QACD,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;YACjC,MAAM,IAAI,qBAAqB,CAC7B,+CAA+C,EAC/C,wBAAwB,CACzB,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,MAAM,EAAE,CAAC;IACxB,CAAC;IAED,MAAM,OAAO,GACX,IAAA,iCAAoB,EAAC;QACnB,WAAW;QACX,OAAO;KACR,CAAC,CAAC;IAEL,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QAClC,MAAM,IAAI,qBAAqB,CAC7B,kDAAkD,EAClD,yBAAyB,CAC1B,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,OAAO,CAAC;QACnB,WAAW,EACT,OAAO,CAAC,WAAW;QAErB,OAAO;QAEP,kBAAkB,EAChB,OAAO,CAAC,kBAAkB;QAE5B,cAAc;KACf,CAAC,CAAC;AACL,CAAC"}

package/dist-cjs/connect/kernel.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectExecutionError = exports.ConnectKernelError = void 0;
+exports.executeConnectWithOnce = executeConnectWithOnce;
+const execute_js_1 = require("./execute.js");
+Object.defineProperty(exports, "ConnectExecutionError", { enumerable: true, get: function () { return execute_js_1.ConnectExecutionError; } });
+class ConnectKernelError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "ConnectKernelError";
+        this.code = code;
+    }
+}
+exports.ConnectKernelError = ConnectKernelError;
+/**
+ * Route a proposed tool operation through Connect and, when protection
+ * is required, through the existing authoritative Once.execute() kernel.
+ *
+ * This adapter deliberately contains no execution-state machine,
+ * replay logic, reconciliation logic, or truth semantics.
+ */
+async function executeConnectWithOnce({ once, provider, safety, operationId, payload, action, bypass, }) {
+    if (!once ||
+        typeof once.execute !== "function") {
+        throw new ConnectKernelError("Once Connect requires an existing Once client.", "ONCE_CLIENT_REQUIRED");
+    }
+    return (0, execute_js_1.executeConnectOperation)({
+        safety,
+        operationId,
+        payload,
+        bypass,
+        protect: async (context) => {
+            if (typeof provider !== "string" ||
+                provider.trim() === "") {
+                throw new ConnectKernelError("Protected Connect execution requires a Once provider.", "PROVIDER_REQUIRED");
+            }
+            if (action === null ||
+                typeof action !== "object" ||
+                Array.isArray(action)) {
+                throw new ConnectKernelError("Protected Connect execution requires an action object.", "ACTION_REQUIRED");
+            }
+            return once.execute({
+                operationId: context.operationId,
+                provider,
+                action,
+            });
+        },
+    });
+}
+//# sourceMappingURL=kernel.js.map

package/dist-cjs/connect/kernel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernel.js","sourceRoot":"","sources":["../../src/connect/kernel.ts"],"names":[],"mappings":";;;AAmDA,wDA0DC;AA7GD,6CAGsB;AA6GpB,sGA9GA,kCAAqB,OA8GA;AAjFvB,MAAa,kBAAmB,SAAQ,KAAK;IAClC,IAAI,CAAS;IAEtB,YACE,OAAe,EACf,IAAY;QAEZ,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAXD,gDAWC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,sBAAsB,CAAc,EACxD,IAAI,EACJ,QAAQ,EACR,MAAM,EACN,WAAW,EACX,OAAO,EACP,MAAM,EACN,MAAM,GACgB;IACtB,IACE,CAAC,IAAI;QACL,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,EAClC,CAAC;QACD,MAAM,IAAI,kBAAkB,CAC1B,gDAAgD,EAChD,sBAAsB,CACvB,CAAC;IACJ,CAAC;IAED,OAAO,IAAA,oCAAuB,EAAc;QAC1C,MAAM;QACN,WAAW;QACX,OAAO;QAEP,MAAM;QAEN,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;YACzB,IACE,OAAO,QAAQ,KAAK,QAAQ;gBAC5B,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EACtB,CAAC;gBACD,MAAM,IAAI,kBAAkB,CAC1B,uDAAuD,EACvD,mBAAmB,CACpB,CAAC;YACJ,CAAC;YAED,IACE,MAAM,KAAK,IAAI;gBACf,OAAO,MAAM,KAAK,QAAQ;gBAC1B,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EACrB,CAAC;gBACD,MAAM,IAAI,kBAAkB,CAC1B,wDAAwD,EACxD,iBAAiB,CAClB,CAAC;YACJ,CAAC;YAED,OAAO,IAAI,CAAC,OAAO,CAAC;gBAClB,WAAW,EACT,OAAO,CAAC,WAAW;gBAErB,QAAQ;gBAER,MAAM;aACP,CAAC,CAAC;QACL,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist-cjs/connect/openai-agents.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIAgentsConnectError = void 0;
+exports.executeOpenAIAgentsConnectTool = executeOpenAIAgentsConnectTool;
+const kernel_js_1 = require("./kernel.js");
+class OpenAIAgentsConnectError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = "OpenAIAgentsConnectError";
+        this.code = code;
+    }
+}
+exports.OpenAIAgentsConnectError = OpenAIAgentsConnectError;
+/**
+ * Minimal OpenAI Agents -> Once Connect execution adapter.
+ *
+ * This adapter owns no execution-safety state machine.
+ * It validates the framework boundary and delegates to
+ * the existing Connect -> Once kernel.
+ *
+ * OpenAI tool-call IDs are intentionally not used as
+ * logical operation identity. The caller must provide a
+ * stable operationId representing the same real-world
+ * logical operation across retries.
+ */
+async function executeOpenAIAgentsConnectTool({ once, provider, safety, operationId, input, action, bypass, }) {
+    if (input === null ||
+        typeof input !== "object" ||
+        Array.isArray(input)) {
+        throw new OpenAIAgentsConnectError("Once Connect requires parsed OpenAI Agents tool input.", "INVALID_OPENAI_TOOL_INPUT");
+    }
+    return await (0, kernel_js_1.executeConnectWithOnce)({
+        once,
+        provider,
+        safety,
+        operationId,
+        /*
+         * Parsed consequential tool input becomes the payload
+         * bound to the stable logical operation identity.
+         */
+        payload: input,
+        action,
+        bypass,
+    });
+}
+//# sourceMappingURL=openai-agents.js.map

package/dist-cjs/connect/openai-agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-agents.js","sourceRoot":"","sources":["../../src/connect/openai-agents.ts"],"names":[],"mappings":";;;AAqDA,wEAqCC;AA1FD,2CAEqB;AA0BrB,MAAa,wBAAyB,SAAQ,KAAK;IACxC,IAAI,CAAS;IAEtB,YACE,OAAe,EACf,IAAY;QAEZ,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAXD,4DAWC;AAED;;;;;;;;;;;GAWG;AACI,KAAK,UAAU,8BAA8B,CAClD,EACE,IAAI,EACJ,QAAQ,EACR,MAAM,EACN,WAAW,EACX,KAAK,EACL,MAAM,EACN,MAAM,GACuB;IAE/B,IACE,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EACpB,CAAC;QACD,MAAM,IAAI,wBAAwB,CAChC,wDAAwD,EACxD,2BAA2B,CAC5B,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,IAAA,kCAAsB,EAAC;QAClC,IAAI;QACJ,QAAQ;QACR,MAAM;QACN,WAAW;QAEX;;;WAGG;QACH,OAAO,EAAE,KAAK;QAEd,MAAM;QACN,MAAM;KACP,CAAC,CAAC;AACL,CAAC"}

package/dist-cjs/index.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Once = exports.OnceNetworkError = exports.OnceTimeoutError = exports.OnceError = void 0;
+exports.executeOpenAIAgentsConnectTool = exports.OpenAIAgentsConnectError = exports.executeConnectWithOnce = exports.ConnectKernelError = exports.executeConnectOperation = exports.ConnectExecutionError = exports.assertConnectBindingMatch = exports.bindConnectOperation = exports.fingerprintConnectPayload = exports.canonicalizeConnectPayload = exports.ConnectBindingError = exports.classifyConnectOperation = exports.CONNECT_DECISION = exports.resolveHttpOperationIdentity = exports.decideHttpExecution = exports.prepareHttpExecution = exports.OnceRuntimeBlockedError = exports.installOnceFetchInterceptor = exports.createOnceFetchInterceptor = exports.Once = exports.OnceNetworkError = exports.OnceTimeoutError = exports.OnceRuntimeHttpShapeError = exports.OnceError = void 0;
+exports.createOnceRuntimeFetch = createOnceRuntimeFetch;
+exports.installOnceRuntimeFetch = installOnceRuntimeFetch;
 const node_buffer_1 = require("node:buffer");
 const node_crypto_1 = require("node:crypto");
+const fetch_interceptor_js_1 = require("./runtime/fetch-interceptor.js");
 const DEFAULT_BASE_URL = "https://once-q18-cloud.pennywatch.workers.dev";
 class OnceError extends Error {
     status;
@@ -21,6 +24,16 @@ class OnceError extends Error {
     }
 }
 exports.OnceError = OnceError;
+class OnceRuntimeHttpShapeError extends OnceError {
+    constructor(message, code = "unsupported_runtime_http_shape") {
+        super(message, {
+            code
+        });
+        this.name =
+            "OnceRuntimeHttpShapeError";
+    }
+}
+exports.OnceRuntimeHttpShapeError = OnceRuntimeHttpShapeError;
 class OnceTimeoutError extends OnceError {
     constructor(message = "Once request timed out", cause) {
         super(message, {
@@ -46,6 +59,7 @@ class Once {
     baseUrl;
     timeoutMs;
     networkRetries;
+    fetchImpl;
     constructor(options = {}) {
         const apiKey = options.apiKey ??
             process.env.ONCE_API_KEY;
@@ -62,6 +76,9 @@ class Once {
             options.timeoutMs ?? 10_000;
         this.networkRetries =
             options.networkRetries ?? 2;
+        this.fetchImpl =
+            options.fetchImpl ??
+                globalThis.fetch;
     }
     /**
      * Generate a deterministic Once operation ID.
@@ -170,8 +187,9 @@ class Once {
             const controller = new AbortController();
             const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
             try {
-                const response = await fetch(`${this.baseUrl}${path}`, {
+                const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
                     ...init,
+                    redirect: "error",
                     signal: controller.signal,
                     headers: {
                         authorization: `Bearer ${this.apiKey}`,
@@ -179,8 +197,8 @@ class Once {
                         ...init.headers
                     }
                 });
-                clearTimeout(timeout);
                 const raw = await response.text();
+                clearTimeout(timeout);
                 let body = null;
                 if (raw) {
                     try {
@@ -240,8 +258,269 @@ class Once {
     }
 }
 exports.Once = Once;
+function runtimeJsonContentType(request) {
+    const contentType = request.headers
+        .get("content-type")
+        ?.toLowerCase() ??
+        "";
+    return contentType.includes("application/json");
+}
+function assertRuntimeHeaderShape(request) {
+    const allowed = new Set([
+        "content-type",
+        "idempotency-key",
+        "x-idempotency-key"
+    ]);
+    for (const [name] of request.headers) {
+        if (!allowed.has(name.toLowerCase())) {
+            throw new OnceRuntimeHttpShapeError(`Once Runtime HTTP v0.1 cannot safely preserve target header "${name}".`);
+        }
+    }
+}
+function parseRuntimeReplay(value) {
+    if (value === null ||
+        typeof value !== "object" ||
+        Array.isArray(value)) {
+        throw new OnceError("Once confirmed the operation but did not return a replayable HTTP response.", {
+            code: "runtime_http_response_missing",
+            body: value
+        });
+    }
+    const candidate = value;
+    const status = Number(candidate.status);
+    /*
+     * Fetch Response constructors cannot represent
+     * informational 1xx responses.
+     */
+    if (!Number.isInteger(status) ||
+        status < 200 ||
+        status > 599) {
+        throw new OnceError("Once returned an HTTP replay with an unsupported status.", {
+            code: "runtime_http_response_invalid_status",
+            body: value
+        });
+    }
+    if (typeof candidate.body_text !==
+        "string") {
+        throw new OnceError("Once returned an HTTP replay without a valid text body.", {
+            code: "runtime_http_response_invalid_body",
+            body: value
+        });
+    }
+    if (candidate.headers === null ||
+        typeof candidate.headers !==
+            "object" ||
+        Array.isArray(candidate.headers)) {
+        throw new OnceError("Once returned an HTTP replay without valid headers.", {
+            code: "runtime_http_response_invalid_headers",
+            body: value
+        });
+    }
+    const headers = {};
+    for (const [name, headerValue] of Object.entries(candidate.headers)) {
+        if (typeof headerValue !==
+            "string") {
+            throw new OnceError("Once returned a non-string HTTP replay header.", {
+                code: "runtime_http_response_invalid_headers",
+                body: value
+            });
+        }
+        headers[name] =
+            headerValue;
+    }
+    const nullBody = status === 204 ||
+        status === 205 ||
+        status === 304;
+    if (nullBody &&
+        candidate.body_text.length > 0) {
+        throw new OnceError("Once returned a body for an HTTP status that cannot carry one.", {
+            code: "runtime_http_response_invalid_body",
+            body: value
+        });
+    }
+    return {
+        status,
+        body_text: candidate.body_text,
+        headers,
+        ...(typeof candidate.recorded_at ===
+            "string"
+            ? {
+                recorded_at: candidate.recorded_at
+            }
+            : {})
+    };
+}
+function createRuntimeCloudProtector(once) {
+    return async ({ request, decision, provider }) => {
+        if (decision.decision !==
+            "PROTECT") {
+            throw new OnceError("Runtime protector received a non-protected operation.", {
+                code: "runtime_invalid_protect_state"
+            });
+        }
+        if (!decision.operationId) {
+            throw new OnceError("Runtime protected operation is missing its resolved operation ID.", {
+                code: "runtime_operation_id_missing"
+            });
+        }
+        if (typeof provider !==
+            "string" ||
+            provider.trim().length ===
+                0) {
+            throw new OnceError("Runtime protected operation is missing its resolved provider.", {
+                code: "runtime_provider_missing"
+            });
+        }
+        const method = request.method
+            .trim()
+            .toUpperCase();
+        /*
+         * Classification recognizes POST/PUT/PATCH/DELETE as
+         * consequential. Execution v0.1 intentionally proves
+         * only POST + JSON.
+         */
+        if (method !== "POST") {
+            throw new OnceRuntimeHttpShapeError(`Once Runtime HTTP v0.1 only has a proven protected execution contract for POST, not ${method || "(empty)"}.`);
+        }
+        if (!runtimeJsonContentType(request)) {
+            throw new OnceRuntimeHttpShapeError("Once Runtime HTTP v0.1 only protects application/json POST bodies.");
+        }
+        assertRuntimeHeaderShape(request);
+        const bodyText = await request
+            .clone()
+            .text();
+        if (bodyText.trim().length ===
+            0) {
+            throw new OnceRuntimeHttpShapeError("Once Runtime HTTP v0.1 requires a non-empty JSON body.");
+        }
+        try {
+            JSON.parse(bodyText);
+        }
+        catch {
+            throw new OnceRuntimeHttpShapeError("Once Runtime HTTP v0.1 requires a valid JSON body.");
+        }
+        const result = await once.execute({
+            operationId: decision.operationId,
+            provider: provider.trim(),
+            action: {
+                type: "http_write_v1",
+                method: "POST",
+                url: request.url,
+                body_json: bodyText
+            }
+        });
+        const replay = parseRuntimeReplay(result.http_response);
+        const nullBody = replay.status === 204 ||
+            replay.status === 205 ||
+            replay.status === 304;
+        return new Response(nullBody
+            ? null
+            : replay.body_text, {
+            status: replay.status,
+            headers: replay.headers
+        });
+    };
+}
+/**
+ * Create a fetch-compatible Once Runtime.
+ *
+ * v0.1 proven protected execution shape:
+ * POST + application/json + stable identity.
+ */
+function createOnceRuntimeFetch(options = {}) {
+    const originalFetch = options.fetchImpl ??
+        globalThis.fetch;
+    if (typeof originalFetch !==
+        "function") {
+        throw new OnceError("Once Runtime requires a native fetch implementation.", {
+            code: "runtime_fetch_missing"
+        });
+    }
+    /*
+     * Once Cloud requests use the captured native fetch.
+     * They cannot recursively enter this interceptor.
+     */
+    const once = new Once({
+        apiKey: options.apiKey,
+        baseUrl: options.baseUrl,
+        timeoutMs: options.timeoutMs,
+        networkRetries: options.networkRetries,
+        fetchImpl: originalFetch
+    });
+    return (0, fetch_interceptor_js_1.createOnceFetchInterceptor)({
+        provider: options.provider,
+        shouldProtect: options.shouldProtect,
+        resolveProvider: options.resolveProvider,
+        resolveOperationId: options.resolveOperationId,
+        fetchImpl: originalFetch,
+        protect: createRuntimeCloudProtector(once)
+    });
+}
+/**
+ * Explicit reversible global fetch installation.
+ */
+function installOnceRuntimeFetch(options = {}) {
+    const previous = globalThis.fetch;
+    const intercepted = createOnceRuntimeFetch({
+        ...options,
+        fetchImpl: options.fetchImpl ??
+            previous
+    });
+    globalThis.fetch =
+        intercepted;
+    let restored = false;
+    return {
+        fetch: intercepted,
+        restore: () => {
+            if (restored) {
+                return;
+            }
+            if (globalThis.fetch ===
+                intercepted) {
+                globalThis.fetch =
+                    previous;
+            }
+            restored =
+                true;
+        }
+    };
+}
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
+var fetch_interceptor_js_2 = require("./runtime/fetch-interceptor.js");
+Object.defineProperty(exports, "createOnceFetchInterceptor", { enumerable: true, get: function () { return fetch_interceptor_js_2.createOnceFetchInterceptor; } });
+Object.defineProperty(exports, "installOnceFetchInterceptor", { enumerable: true, get: function () { return fetch_interceptor_js_2.installOnceFetchInterceptor; } });
+Object.defineProperty(exports, "OnceRuntimeBlockedError", { enumerable: true, get: function () { return fetch_interceptor_js_2.OnceRuntimeBlockedError; } });
+var pipeline_js_1 = require("./runtime/pipeline.js");
+Object.defineProperty(exports, "prepareHttpExecution", { enumerable: true, get: function () { return pipeline_js_1.prepareHttpExecution; } });
+var decision_js_1 = require("./runtime/decision.js");
+Object.defineProperty(exports, "decideHttpExecution", { enumerable: true, get: function () { return decision_js_1.decideHttpExecution; } });
+var identity_js_1 = require("./runtime/identity.js");
+Object.defineProperty(exports, "resolveHttpOperationIdentity", { enumerable: true, get: function () { return identity_js_1.resolveHttpOperationIdentity; } });
 exports.default = Once;
+/*
+ * Once Connect
+ *
+ * Framework-neutral execution-safety boundary for agent/tool integrations.
+ * Protected execution delegates to the existing Once kernel.
+ */
+var classifier_js_1 = require("./connect/classifier.js");
+Object.defineProperty(exports, "CONNECT_DECISION", { enumerable: true, get: function () { return classifier_js_1.CONNECT_DECISION; } });
+Object.defineProperty(exports, "classifyConnectOperation", { enumerable: true, get: function () { return classifier_js_1.classifyConnectOperation; } });
+var binding_js_1 = require("./connect/binding.js");
+Object.defineProperty(exports, "ConnectBindingError", { enumerable: true, get: function () { return binding_js_1.ConnectBindingError; } });
+Object.defineProperty(exports, "canonicalizeConnectPayload", { enumerable: true, get: function () { return binding_js_1.canonicalizeConnectPayload; } });
+Object.defineProperty(exports, "fingerprintConnectPayload", { enumerable: true, get: function () { return binding_js_1.fingerprintConnectPayload; } });
+Object.defineProperty(exports, "bindConnectOperation", { enumerable: true, get: function () { return binding_js_1.bindConnectOperation; } });
+Object.defineProperty(exports, "assertConnectBindingMatch", { enumerable: true, get: function () { return binding_js_1.assertConnectBindingMatch; } });
+var execute_js_1 = require("./connect/execute.js");
+Object.defineProperty(exports, "ConnectExecutionError", { enumerable: true, get: function () { return execute_js_1.ConnectExecutionError; } });
+Object.defineProperty(exports, "executeConnectOperation", { enumerable: true, get: function () { return execute_js_1.executeConnectOperation; } });
+var kernel_js_1 = require("./connect/kernel.js");
+Object.defineProperty(exports, "ConnectKernelError", { enumerable: true, get: function () { return kernel_js_1.ConnectKernelError; } });
+Object.defineProperty(exports, "executeConnectWithOnce", { enumerable: true, get: function () { return kernel_js_1.executeConnectWithOnce; } });
+var openai_agents_js_1 = require("./connect/openai-agents.js");
+Object.defineProperty(exports, "OpenAIAgentsConnectError", { enumerable: true, get: function () { return openai_agents_js_1.OpenAIAgentsConnectError; } });
+Object.defineProperty(exports, "executeOpenAIAgentsConnectTool", { enumerable: true, get: function () { return openai_agents_js_1.executeOpenAIAgentsConnectTool; } });
 //# sourceMappingURL=index.js.map