@once-agent/sdk 0.1.0

package/dist/transformers/http-patch-plan-v1.js

@@ -0,0 +1,149 @@
+import { createHash } from "node:crypto";
+import { transformHttpWriteV1 } from "./http-write-v1.js";
+import { bindOnceCallSiteV1 } from "./once-binding-v1.js";
+export const HTTP_WRITE_PATCH_PLAN_ID = "ts_fetch_post_void_patch_v1";
+function sha256(value) {
+    return createHash("sha256")
+        .update(value, "utf8")
+        .digest("hex");
+}
+function countExact(source, needle) {
+    if (!needle) {
+        return 0;
+    }
+    let count = 0;
+    let offset = 0;
+    while (true) {
+        const index = source.indexOf(needle, offset);
+        if (index < 0) {
+            break;
+        }
+        count++;
+        offset =
+            index +
+                needle.length;
+    }
+    return count;
+}
+function indentReplacement(source, index, replacement) {
+    const lineStart = source.lastIndexOf("\n", Math.max(0, index - 1)) + 1;
+    const prefix = source.slice(lineStart, index);
+    /*
+     * We only replace a standalone statement.
+     * Anything executable before it on the same
+     * line is outside the proven patch model.
+     */
+    if (!/^[ \t]*$/.test(prefix)) {
+        return null;
+    }
+    return replacement
+        .split("\n")
+        .map((line, lineIndex) => lineIndex === 0
+        ? line
+        : prefix + line)
+        .join("\n");
+}
+export function buildHttpWritePatchV1(input) {
+    const source = input.source.replace(/\r\n/g, "\n");
+    const statement = input.statement
+        .replace(/\r\n/g, "\n")
+        .trim();
+    if (!statement) {
+        return {
+            eligible: false,
+            reason: "The source statement is empty."
+        };
+    }
+    const transformer = transformHttpWriteV1({
+        statement,
+        functionSource: input.functionSource,
+        provider: input.provider
+    });
+    if (!transformer.eligible) {
+        return {
+            eligible: false,
+            reason: transformer.reason
+        };
+    }
+    /*
+     * Fail closed if the exact statement occurs
+     * more than once. An automatic patch must
+     * have one unambiguous target.
+     */
+    const originalOccurrences = countExact(source, statement);
+    if (originalOccurrences !== 1) {
+        return {
+            eligible: false,
+            reason: `Expected exactly one exact source statement; found ${originalOccurrences}.`
+        };
+    }
+    const binding = bindOnceCallSiteV1(source, transformer.replacement);
+    if (!binding.eligible) {
+        return {
+            eligible: false,
+            reason: binding.reason
+        };
+    }
+    const sourceWithImport = binding.sourceWithImport;
+    const occurrencesAfterImport = countExact(sourceWithImport, statement);
+    if (occurrencesAfterImport !== 1) {
+        return {
+            eligible: false,
+            reason: "Import insertion changed or duplicated the target statement."
+        };
+    }
+    const index = sourceWithImport.indexOf(statement);
+    if (index < 0) {
+        return {
+            eligible: false,
+            reason: "Exact source statement disappeared before replacement."
+        };
+    }
+    const replacement = indentReplacement(sourceWithImport, index, binding.boundReplacement);
+    if (!replacement) {
+        return {
+            eligible: false,
+            reason: "Target statement is not isolated on its source line."
+        };
+    }
+    const proposedSource = sourceWithImport.slice(0, index) +
+        replacement +
+        sourceWithImport.slice(index +
+            statement.length);
+    if (countExact(proposedSource, statement) !== 0) {
+        return {
+            eligible: false,
+            reason: "Original consequential statement remains after transformation."
+        };
+    }
+    const importCount = countExact(proposedSource, binding.importStatement);
+    if (importCount !== 1) {
+        return {
+            eligible: false,
+            reason: `Expected one Once SDK import; found ${importCount}.`
+        };
+    }
+    const executionCount = (proposedSource.match(/\bnew\s+__OnceAgentClient\(\)\.execute\s*\(/g) ?? []).length;
+    if (executionCount !== 1) {
+        return {
+            eligible: false,
+            reason: `Expected one bound Once execution; found ${executionCount}.`
+        };
+    }
+    if (/\bawait\s+once\.execute\s*\(/.test(proposedSource)) {
+        return {
+            eligible: false,
+            reason: "Unbound transformer call remains in proposed source."
+        };
+    }
+    return {
+        eligible: true,
+        patchPlan: HTTP_WRITE_PATCH_PLAN_ID,
+        transformerId: transformer.transformer,
+        bindingStrategy: "call-site-constructor",
+        proposedSource,
+        sourceSha256: sha256(source),
+        proposedSourceSha256: sha256(proposedSource)
+    };
+}
+//# sourceMappingURL=http-patch-plan-v1.js.map

package/dist/transformers/http-patch-plan-v1.js.map

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

package/dist/transformers/http-write-v1.d.ts

@@ -0,0 +1,23 @@
+export declare const HTTP_WRITE_TRANSFORMER_ID: "ts_fetch_post_void_v1";
+export type HttpWriteTransformInput = {
+    statement: string;
+    functionSource: string;
+    provider: string;
+};
+export type HttpWriteTransformSuccess = {
+    eligible: true;
+    transformer: typeof HTTP_WRITE_TRANSFORMER_ID;
+    replacement: string;
+    actionType: "http_write_v1";
+    method: "POST";
+    url: string;
+    bodyExpression: string;
+    requiresOnceBinding: true;
+};
+export type HttpWriteTransformFailure = {
+    eligible: false;
+    reason: string;
+};
+export type HttpWriteTransformResult = HttpWriteTransformSuccess | HttpWriteTransformFailure;
+export declare function transformHttpWriteV1(input: HttpWriteTransformInput): HttpWriteTransformResult;
+//# sourceMappingURL=http-write-v1.d.ts.map

package/dist/transformers/http-write-v1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-write-v1.d.ts","sourceRoot":"","sources":["../../src/transformers/http-write-v1.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,yBAAyB,EACpC,uBAAgC,CAAC;AAEnC,MAAM,MAAM,uBAAuB,GAAG;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,EAAE,IAAI,CAAC;IACf,WAAW,EACT,OAAO,yBAAyB,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,eAAe,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,IAAI,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,EAAE,KAAK,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAChC,yBAAyB,GACzB,yBAAyB,CAAC;AA4C9B,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,uBAAuB,GAC7B,wBAAwB,CAqM1B"}

package/dist/transformers/http-write-v1.js

@@ -0,0 +1,134 @@
+export const HTTP_WRITE_TRANSFORMER_ID = "ts_fetch_post_void_v1";
+function hasOperationIdParameter(functionSource) {
+    const match = functionSource.match(/\(([^)]*)\)/);
+    if (!match) {
+        return false;
+    }
+    const parameters = match[1]
+        .split(",")
+        .map(parameter => parameter
+        .trim()
+        .replace(/^\.\.\./, "")
+        .split(/[:=]/)[0]
+        .trim());
+    return parameters.includes("operationId");
+}
+function quote(value) {
+    return JSON.stringify(value);
+}
+export function transformHttpWriteV1(input) {
+    const provider = input.provider.trim();
+    if (!provider) {
+        return {
+            eligible: false,
+            reason: "A configured provider is required."
+        };
+    }
+    if (!hasOperationIdParameter(input.functionSource)) {
+        return {
+            eligible: false,
+            reason: "The surrounding function must already receive a stable operationId parameter."
+        };
+    }
+    const statement = input.statement
+        .replace(/\r\n/g, "\n")
+        .trim();
+    /*
+     * Deliberately require an unused-response
+     * await fetch(...) expression statement.
+     *
+     * return await fetch(...)
+     * const x = await fetch(...)
+     *
+     * are not accepted because Once.execute()
+     * does not have the same return contract as
+     * the native Fetch Response object.
+     */
+    if (!/^await\s+fetch\s*\(/.test(statement)) {
+        return {
+            eligible: false,
+            reason: "Only an unused-response `await fetch(...)` statement is supported."
+        };
+    }
+    const callMatch = statement.match(/^await\s+fetch\s*\(\s*(["'])(https:\/\/[^"'\\]+)\1\s*,\s*\{([\s\S]*)\}\s*\)\s*;?$/);
+    if (!callMatch) {
+        return {
+            eligible: false,
+            reason: "Only a literal HTTPS URL and an inline fetch options object are supported."
+        };
+    }
+    const url = callMatch[2];
+    const options = callMatch[3];
+    /*
+     * v0.6 allows exactly two fetch options:
+     *
+     * method
+     * body
+     *
+     * Anything else requires a richer
+     * semantics-preserving transformer.
+     */
+    const keys = Array.from(options.matchAll(/(?:^|,|\n)\s*([A-Za-z_$][A-Za-z0-9_$]*)\s*:/g), match => match[1]);
+    const uniqueKeys = Array.from(new Set(keys)).sort();
+    if (uniqueKeys.length !== 2 ||
+        uniqueKeys[0] !== "body" ||
+        uniqueKeys[1] !== "method") {
+        return {
+            eligible: false,
+            reason: "v0.6 supports exactly the fetch options `method` and `body`."
+        };
+    }
+    const methodMatch = options.match(/\bmethod\s*:\s*(["'])POST\1/);
+    if (!methodMatch) {
+        return {
+            eligible: false,
+            reason: "v0.6 supports only literal POST requests."
+        };
+    }
+    const bodyMatch = options.match(/\bbody\s*:\s*JSON\.stringify\(\s*([A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*)\s*\)/);
+    if (!bodyMatch) {
+        return {
+            eligible: false,
+            reason: "v0.6 requires body: JSON.stringify(<simple expression>)."
+        };
+    }
+    const bodyExpression = bodyMatch[1];
+    /*
+     * Ensure the recognized expressions account
+     * for the expected option values rather than
+     * accepting an object containing additional
+     * unsupported executable syntax.
+     */
+    const methodOccurrences = (options.match(/\bmethod\s*:/g) ?? []).length;
+    const bodyOccurrences = (options.match(/\bbody\s*:/g) ?? []).length;
+    if (methodOccurrences !== 1 ||
+        bodyOccurrences !== 1) {
+        return {
+            eligible: false,
+            reason: "Duplicate method/body options are not supported."
+        };
+    }
+    const replacement = [
+        "await once.execute({",
+        "  operationId,",
+        `  provider: ${quote(provider)},`,
+        "  action: {",
+        '    type: "http_write_v1",',
+        '    method: "POST",',
+        `    url: ${quote(url)},`,
+        `    body_json: JSON.stringify(${bodyExpression})`,
+        "  }",
+        "});"
+    ].join("\n");
+    return {
+        eligible: true,
+        transformer: HTTP_WRITE_TRANSFORMER_ID,
+        replacement,
+        actionType: "http_write_v1",
+        method: "POST",
+        url,
+        bodyExpression,
+        requiresOnceBinding: true
+    };
+}
+//# sourceMappingURL=http-write-v1.js.map

package/dist/transformers/http-write-v1.js.map

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

package/dist/transformers/once-binding-v1.d.ts

@@ -0,0 +1,17 @@
+export declare const ONCE_CLIENT_ALIAS: "__OnceAgentClient";
+export declare const ONCE_IMPORT: "import { Once as __OnceAgentClient } from \"@once-agent/sdk\";";
+export type OnceBindingSuccess = {
+    eligible: true;
+    importStatement: typeof ONCE_IMPORT;
+    clientAlias: typeof ONCE_CLIENT_ALIAS;
+    sourceWithImport: string;
+    boundReplacement: string;
+    constructorTiming: "call-site";
+};
+export type OnceBindingFailure = {
+    eligible: false;
+    reason: string;
+};
+export type OnceBindingResult = OnceBindingSuccess | OnceBindingFailure;
+export declare function bindOnceCallSiteV1(source: string, replacement: string): OnceBindingResult;
+//# sourceMappingURL=once-binding-v1.d.ts.map

package/dist/transformers/once-binding-v1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"once-binding-v1.d.ts","sourceRoot":"","sources":["../../src/transformers/once-binding-v1.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,EAC5B,mBAA4B,CAAC;AAE/B,eAAO,MAAM,WAAW,EACtB,gEAAuE,CAAC;AAE1E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,IAAI,CAAC;IACf,eAAe,EACb,OAAO,WAAW,CAAC;IACrB,WAAW,EACT,OAAO,iBAAiB,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,WAAW,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,KAAK,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,kBAAkB,CAAC;AA+MvB,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,iBAAiB,CAiFnB"}

package/dist/transformers/once-binding-v1.js

@@ -0,0 +1,134 @@
+export const ONCE_CLIENT_ALIAS = "__OnceAgentClient";
+export const ONCE_IMPORT = 'import { Once as __OnceAgentClient } from "@once-agent/sdk";';
+function hasEsmSyntax(source) {
+    return (/(^|\n)\s*import\s+/m.test(source) ||
+        /(^|\n)\s*export\s+/m.test(source));
+}
+function aliasExists(source) {
+    return new RegExp(`\\b${ONCE_CLIENT_ALIAS}\\b`).test(source);
+}
+function findImportInsertionOffset(source) {
+    let cursor = source.charCodeAt(0) ===
+        0xFEFF
+        ? 1
+        : 0;
+    /*
+     * Preserve a Node shebang.
+     */
+    if (source.startsWith("#!", cursor)) {
+        const newline = source.indexOf("\n", cursor);
+        cursor =
+            newline < 0
+                ? source.length
+                : newline + 1;
+    }
+    /*
+     * Preserve the directive prologue:
+     *
+     * "use client";
+     * "use strict";
+     *
+     * Comments and whitespace do not end a directive
+     * prologue, so skip them while searching.
+     */
+    let search = cursor;
+    let lastDirectiveEnd = cursor;
+    while (search <
+        source.length) {
+        const whitespace = source
+            .slice(search)
+            .match(/^[ \t\r\n]+/);
+        if (whitespace) {
+            search +=
+                whitespace[0].length;
+        }
+        if (source.startsWith("//", search)) {
+            const newline = source.indexOf("\n", search);
+            search =
+                newline < 0
+                    ? source.length
+                    : newline + 1;
+            continue;
+        }
+        if (source.startsWith("/*", search)) {
+            const close = source.indexOf("*/", search + 2);
+            if (close < 0) {
+                return cursor;
+            }
+            search =
+                close + 2;
+            continue;
+        }
+        const directive = source
+            .slice(search)
+            .match(/^(["'])(?:\\.|(?!\1)[^\\\r\n])*\1\s*;?/);
+        if (!directive) {
+            break;
+        }
+        search +=
+            directive[0].length;
+        /*
+         * Include the remainder of the directive line.
+         */
+        const newline = source.indexOf("\n", search);
+        lastDirectiveEnd =
+            newline < 0
+                ? source.length
+                : newline + 1;
+        search =
+            lastDirectiveEnd;
+    }
+    return lastDirectiveEnd;
+}
+function insertOnceImport(source) {
+    const offset = findImportInsertionOffset(source);
+    const before = source.slice(0, offset);
+    const after = source.slice(offset);
+    const separatorBefore = before.length > 0 &&
+        !before.endsWith("\n")
+        ? "\n"
+        : "";
+    return (before +
+        separatorBefore +
+        ONCE_IMPORT +
+        "\n" +
+        after);
+}
+export function bindOnceCallSiteV1(source, replacement) {
+    if (!hasEsmSyntax(source)) {
+        return {
+            eligible: false,
+            reason: "v0.8 automatic binding supports ESM TypeScript modules only."
+        };
+    }
+    if (aliasExists(source)) {
+        return {
+            eligible: false,
+            reason: `Reserved Once client alias ${ONCE_CLIENT_ALIAS} already exists in the source file.`
+        };
+    }
+    const calls = replacement.match(/\bawait\s+once\.execute\s*\(/g) ?? [];
+    if (calls.length !== 1) {
+        return {
+            eligible: false,
+            reason: "Expected exactly one transformer-generated await once.execute(...) call."
+        };
+    }
+    const boundReplacement = replacement.replace(/\bawait\s+once\.execute\s*\(/, `await new ${ONCE_CLIENT_ALIAS}().execute(`);
+    if (/\bconst\s+once\b/.test(boundReplacement) ||
+        /\blet\s+once\b/.test(boundReplacement)) {
+        return {
+            eligible: false,
+            reason: "Generated binding unexpectedly introduced a persistent once variable."
+        };
+    }
+    return {
+        eligible: true,
+        importStatement: ONCE_IMPORT,
+        clientAlias: ONCE_CLIENT_ALIAS,
+        sourceWithImport: insertOnceImport(source),
+        boundReplacement,
+        constructorTiming: "call-site"
+    };
+}
+//# sourceMappingURL=once-binding-v1.js.map

package/dist/transformers/once-binding-v1.js.map

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

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@once-agent/sdk",
+  "version": "0.1.0",
+  "description": "Execution safety for side-effecting AI agent tools.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "benchmark:scan": "npm run build && node ./scripts/scan-benchmark.mjs",
+    "test:contract": "npm run build && tsc --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext --strict --types node ./scripts/sdk-contract-types.ts && node ./scripts/sdk-contract-runtime.mjs",
+    "test:release": "npm run benchmark:scan && npm run test:scanner-declarations && npm run test:contract && npm run test:protect && npm run test:capabilities && npm run test:transformer && npm run test:binding && npm run test:patch-planner && npm run test:transformer-protect && npm run test:apply && npm run test:id-conformance && npm run test:consumer && npm run test:package",
+    "test:protect": "npm run build && node ./scripts/protect-regression.mjs",
+    "test:capabilities": "npm run build && node ./scripts/capability-regression.mjs",
+    "test:transformer": "npm run build && node ./scripts/http-transformer-regression.mjs",
+    "test:scanner-declarations": "npm run build && node ./scripts/scanner-declaration-regression.mjs",
+    "test:transformer-protect": "npm run build && node ./scripts/transformer-protect-regression.mjs",
+    "test:binding": "npm run build && node ./scripts/once-binding-regression.mjs",
+    "test:patch-planner": "npm run build && node ./scripts/http-patch-planner-regression.mjs",
+    "test:apply": "npm run build && node ./scripts/apply-engine-regression.mjs && node ./scripts/apply-regression.mjs",
+    "test:package": "npm run build && node ./scripts/package-isolation-regression.mjs",
+    "test:consumer": "npm run build && node ./scripts/consumer-package-regression.mjs",
+    "test:id-conformance": "npm run build && node ./scripts/id-conformance-regression.mjs"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "idempotency",
+    "reliability",
+    "execution-safety"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.1"
+  },
+  "bin": {
+    "once": "./dist/cli.js"
+  },
+  "dependencies": {
+    "typescript": "^5.9.0"
+  }
+}