@once-agent/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamie Oswald
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @once-agent/sdk
+
+Make side-effecting AI agent tools safe to retry.
+
+Once helps prevent duplicate payments, bookings, messages and other consequential actions when a request outcome is ambiguous.
+
+## Install
+
+npm install @once-agent/sdk
+
+## Configure
+
+Set ONCE_API_KEY in your environment.
+
+## Quick start
+
+import { Once } from "@once-agent/sdk";
+
+const once = new Once();
+
+const operationId = Once.id("refund", "order_123");
+
+const result = await once.execute({
+  operationId,
+  provider: "http_v1",
+  action: {
+    method: "POST",
+    path: "/refund",
+    body: { order_id: "123" }
+  }
+});
+
+console.log(result);
+
+## Check truth
+
+const truth = await once.truth(operationId);
+console.log(truth.ledger_state);
+
+## Safety model
+
+Once does not claim universal exactly-once execution.
+Guarantees depend on the provider adapter and authoritative provider truth.

package/dist/apply.d.ts

@@ -0,0 +1,9 @@
+export type ApplyResult = {
+    callsiteRef: string;
+    file: string;
+    backupPath: string;
+    sourceSha256: string;
+    appliedSha256: string;
+};
+export declare function applyProtectionPlan(requestedPath: string): Promise<ApplyResult>;
+//# sourceMappingURL=apply.d.ts.map

package/dist/apply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../src/apply.ts"],"names":[],"mappings":"AAiDA,MAAM,MAAM,WAAW,GAAG;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAuYF,wBAAsB,mBAAmB,CACvC,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,CAAC,CA4VtB"}

package/dist/apply.js

@@ -0,0 +1,265 @@
+import { createHash } from "node:crypto";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { buildHttpWritePatchV1 } from "./transformers/http-patch-plan-v1.js";
+function sha256(value) {
+    return createHash("sha256")
+        .update(value.replace(/\r\n/g, "\n"), "utf8")
+        .digest("hex");
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function extractAwaitFetchStatement(source, findingLine) {
+    const normalized = source.replace(/\r\n/g, "\n");
+    const lines = normalized.split("\n");
+    const target = Math.max(0, Math.min(lines.length - 1, findingLine - 1));
+    let startLine = -1;
+    for (let i = target; i >= Math.max(0, target - 12); i--) {
+        if (/\bawait\s+fetch\s*\(/.test(lines[i])) {
+            startLine = i;
+            break;
+        }
+    }
+    if (startLine < 0) {
+        return null;
+    }
+    let lineOffset = 0;
+    for (let i = 0; i < startLine; i++) {
+        lineOffset +=
+            lines[i].length + 1;
+    }
+    const fragment = normalized.slice(lineOffset);
+    const awaitMatch = fragment.match(/\bawait\s+fetch\s*\(/);
+    if (!awaitMatch ||
+        awaitMatch.index === undefined) {
+        return null;
+    }
+    const statementStart = awaitMatch.index;
+    const openParen = fragment.indexOf("(", statementStart);
+    if (openParen < 0) {
+        return null;
+    }
+    let depth = 0;
+    let quote = null;
+    let escaped = false;
+    let closeParen = -1;
+    for (let i = openParen; i < fragment.length; i++) {
+        const char = fragment[i];
+        if (quote) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (char === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (char === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (char === "`") {
+            return null;
+        }
+        if (char === "'" ||
+            char === '"') {
+            quote = char;
+            continue;
+        }
+        if (char === "(") {
+            depth++;
+            continue;
+        }
+        if (char === ")") {
+            depth--;
+            if (depth === 0) {
+                closeParen = i;
+                break;
+            }
+        }
+    }
+    if (closeParen < 0) {
+        return null;
+    }
+    let end = closeParen + 1;
+    while (end < fragment.length &&
+        /\s/.test(fragment[end])) {
+        end++;
+    }
+    if (fragment[end] === ";") {
+        end++;
+    }
+    return {
+        statement: fragment
+            .slice(statementStart, end)
+            .trim(),
+        startOffset: lineOffset +
+            statementStart
+    };
+}
+function extractFunctionSource(source, functionName, statementStart) {
+    const normalized = source.replace(/\r\n/g, "\n");
+    const before = normalized.slice(0, statementStart);
+    const pattern = new RegExp(String.raw `(?:export\s+)?(?:async\s+)?function\s+${escapeRegExp(functionName)}\s*\(`, "g");
+    let lastIndex = -1;
+    for (const match of before.matchAll(pattern)) {
+        if (match.index !== undefined) {
+            lastIndex =
+                match.index;
+        }
+    }
+    if (lastIndex < 0) {
+        return null;
+    }
+    return normalized.slice(lastIndex, Math.min(normalized.length, statementStart + 1));
+}
+async function readJson(file) {
+    const raw = await fs.readFile(file, "utf8");
+    return JSON.parse(raw.replace(/^\uFEFF/, ""));
+}
+async function verifyTypeScript(source, fileName) {
+    const ts = await import("typescript");
+    const result = ts.transpileModule(source, {
+        fileName,
+        reportDiagnostics: true,
+        compilerOptions: {
+            target: ts.ScriptTarget.ES2022,
+            module: ts.ModuleKind.ESNext
+        }
+    });
+    const errors = (result.diagnostics ??
+        []).filter(diagnostic => diagnostic.category ===
+        ts.DiagnosticCategory.Error);
+    if (errors.length > 0) {
+        const message = errors
+            .map(diagnostic => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"))
+            .join("\n");
+        throw new Error("TypeScript verification failed:\n" +
+            message);
+    }
+}
+export async function applyProtectionPlan(requestedPath) {
+    const root = path.resolve(requestedPath);
+    const onceDirectory = path.join(root, ".once");
+    const plan = await readJson(path.join(onceDirectory, "protect-plan.json"));
+    const config = await readJson(path.join(onceDirectory, "config.json"));
+    const manifest = await readJson(path.join(onceDirectory, "provider-capabilities.json"));
+    const provider = config.provider?.name?.trim();
+    if (!provider) {
+        throw new Error("Configured provider missing.");
+    }
+    if (plan.provider !== provider) {
+        throw new Error("Protect plan provider no longer matches configuration.");
+    }
+    if (manifest.schema_version !== 1 ||
+        manifest.provider !== provider) {
+        throw new Error("Provider capability manifest no longer matches configuration.");
+    }
+    const capability = manifest.capabilities?.some(item => item.category ===
+        "HTTP_WRITE" &&
+        item.action_type ===
+            "http_write_v1");
+    if (!capability) {
+        throw new Error("Required http_write_v1 capability is no longer declared.");
+    }
+    const patchable = plan.candidates.filter(candidate => candidate.automation_status ===
+        "PATCHABLE" &&
+        candidate.auto_apply_eligible ===
+            true);
+    if (patchable.length !== 1) {
+        throw new Error(`--apply requires exactly one PATCHABLE candidate; found ${patchable.length}.`);
+    }
+    const candidate = patchable[0];
+    if (candidate.category !==
+        "HTTP_WRITE" ||
+        candidate.transformer_id !==
+            "ts_fetch_post_void_v1" ||
+        candidate.patch_plan_id !==
+            "ts_fetch_post_void_patch_v1") {
+        throw new Error("Candidate is outside the supported v1.0 apply contract.");
+    }
+    if (!candidate.function_name ||
+        !candidate.source_sha256 ||
+        !candidate.proposed_source_sha256) {
+        throw new Error("Protect plan is missing required patch metadata.");
+    }
+    const sourcePath = path.resolve(root, candidate.file);
+    const relative = path.relative(root, sourcePath);
+    if (relative.startsWith("..") ||
+        path.isAbsolute(relative)) {
+        throw new Error("Candidate source path escaped the project root.");
+    }
+    const originalSource = await fs.readFile(sourcePath, "utf8");
+    if (sha256(originalSource) !==
+        candidate.source_sha256) {
+        throw new Error("Source changed after Protect planning. Refusing stale patch.");
+    }
+    const extracted = extractAwaitFetchStatement(originalSource, candidate.line);
+    if (!extracted) {
+        throw new Error("Could not re-identify the exact protected operation.");
+    }
+    const functionSource = extractFunctionSource(originalSource, candidate.function_name, extracted.startOffset);
+    if (!functionSource) {
+        throw new Error("Could not re-identify the surrounding function.");
+    }
+    const patch = buildHttpWritePatchV1({
+        source: originalSource,
+        statement: extracted.statement,
+        functionSource,
+        provider
+    });
+    if (!patch.eligible) {
+        throw new Error("Patch no longer satisfies transformer contract: " +
+            patch.reason);
+    }
+    if (patch.proposedSourceSha256 !==
+        candidate.proposed_source_sha256) {
+        throw new Error("Recomputed proposed-source fingerprint differs from Protect plan.");
+    }
+    await verifyTypeScript(patch.proposedSource, sourcePath);
+    const backupDirectory = path.join(onceDirectory, "backups", candidate.callsite_ref);
+    await fs.mkdir(backupDirectory, {
+        recursive: true
+    });
+    const stamp = new Date()
+        .toISOString()
+        .replace(/[:.]/g, "-");
+    const backupPath = path.join(backupDirectory, `${stamp}-${path.basename(sourcePath)}.bak`);
+    await fs.writeFile(backupPath, originalSource, "utf8");
+    const temporaryPath = path.join(path.dirname(sourcePath), `.once-${process.pid}-${Date.now()}-${path.basename(sourcePath)}.tmp`);
+    let replaced = false;
+    try {
+        await fs.writeFile(temporaryPath, patch.proposedSource, {
+            encoding: "utf8",
+            flag: "wx"
+        });
+        await fs.rename(temporaryPath, sourcePath);
+        replaced =
+            true;
+        const applied = await fs.readFile(sourcePath, "utf8");
+        if (sha256(applied) !==
+            patch.proposedSourceSha256) {
+            throw new Error("Applied source fingerprint differs from planned source.");
+        }
+        await verifyTypeScript(applied, sourcePath);
+        return {
+            callsiteRef: candidate.callsite_ref,
+            file: candidate.file,
+            backupPath,
+            sourceSha256: patch.sourceSha256,
+            appliedSha256: patch.proposedSourceSha256
+        };
+    }
+    catch (error) {
+        await fs.rm(temporaryPath, {
+            force: true
+        });
+        if (replaced) {
+            await fs.writeFile(sourcePath, originalSource, "utf8");
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=apply.js.map

package/dist/apply.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+import { randomUUID } from "node:crypto";
+import { Once, OnceError } from "./index.js";
+import { runScan } from "./scan.js";
+import { runSetup } from "./setup.js";
+import { runProtect } from "./protect.js";
+import { applyProtectionPlan } from "./apply.js";
+async function runDoctor() {
+    console.log("");
+    console.log("Once Doctor");
+    console.log("-----------");
+    if (!process.env.ONCE_API_KEY) {
+        console.log("✗ ONCE_API_KEY is not set");
+        console.log("");
+        console.log("Set ONCE_API_KEY and run again.");
+        process.exitCode = 1;
+        return;
+    }
+    console.log("✓ ONCE_API_KEY found");
+    try {
+        const once = new Once();
+        const operationId = "doctor-" +
+            randomUUID()
+                .replaceAll("-", "");
+        const truth = await once.truth(operationId);
+        console.log("✓ Once API reachable");
+        console.log("✓ API key accepted");
+        console.log("✓ Truth endpoint working");
+        if (truth.ledger_state !==
+            "ABSENT" ||
+            truth.side_effects !== 0) {
+            console.log("✗ Unexpected doctor probe result");
+            process.exitCode = 1;
+            return;
+        }
+        console.log("✓ Safety probe passed");
+        console.log("");
+        console.log("Once is ready.");
+    }
+    catch (error) {
+        if (error instanceof
+            OnceError) {
+            console.log(`✗ Once error: ${error.code ?? "unknown"}`);
+            if (error.status) {
+                console.log(`  HTTP ${error.status}`);
+            }
+        }
+        else {
+            console.log("✗ Unexpected error");
+            console.error(error);
+        }
+        process.exitCode = 1;
+    }
+}
+function printHelp() {
+    console.log("");
+    console.log("Once");
+    console.log("----");
+    console.log("");
+    console.log("Commands:");
+    console.log("  once protect [directory]");
+    console.log("      Review candidate operations for Once protection.");
+    console.log("      Use --all to include all confidence levels.");
+    console.log("      Use --write-plan to save .once/protect-plan.json.");
+    console.log("      Use --patch to generate .once/protect-preview.diff.");
+    console.log("      Use --snippets to generate per-callsite integration guidance.");
+    console.log("      Use --apply to transactionally apply exactly one PATCHABLE candidate.");
+    console.log("");
+    console.log("  once setup [directory]");
+    console.log("      Detect, configure and install Once.");
+    console.log("      Use --plan to preview without changes.");
+    console.log("");
+    console.log("  once scan [directory]");
+    console.log("      Find likely consequential operations locally.");
+    console.log("");
+    console.log("  once doctor");
+    console.log("      Verify your Once connection.");
+    console.log("");
+    console.log("Examples:");
+    console.log("  once protect .");
+    console.log("  once protect . --all --write-plan");
+    console.log("  once protect . --all --patch");
+    console.log("  once protect . --apply");
+    console.log("  once setup .");
+    console.log("  once scan .");
+    console.log("  once doctor");
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const command = (args.shift() ??
+        "doctor").toLowerCase();
+    switch (command) {
+        case "doctor":
+            await runDoctor();
+            return;
+        case "scan": {
+            const noEstimate = args.includes("--no-estimate");
+            const requestedPath = args.find(value => !value.startsWith("--")) ?? ".";
+            await runScan(requestedPath, !noEstimate);
+            return;
+        }
+        case "protect": {
+            const includeAll = args.includes("--all");
+            const writePlan = args.includes("--write-plan");
+            const writePatch = args.includes("--patch");
+            const writeSnippets = args.includes("--snippets");
+            const apply = args.includes("--apply");
+            const requestedPath = args.find(value => !value.startsWith("--")) ?? ".";
+            await runProtect(requestedPath, {
+                includeAll: apply
+                    ? true
+                    : includeAll,
+                writePlan: apply
+                    ? true
+                    : writePlan,
+                writePatch,
+                writeSnippets
+            });
+            if (apply) {
+                console.log("");
+                console.log("APPLYING PROTECTION");
+                console.log("-------------------");
+                let result;
+                try {
+                    result =
+                        await applyProtectionPlan(requestedPath);
+                }
+                catch (error) {
+                    const message = String(error instanceof Error
+                        ? error.message
+                        : error);
+                    /*
+                     * runProtect currently does not persist a plan
+                     * when zero candidates are selected.
+                     *
+                     * Because this apply path has just run Protect
+                     * successfully with writePlan=true, a missing
+                     * protect-plan here means there were zero
+                     * selected candidates.
+                     */
+                    if (message.includes("protect-plan.json") &&
+                        message.includes("ENOENT")) {
+                        throw new Error("--apply requires exactly one PATCHABLE candidate; found 0.");
+                    }
+                    throw error;
+                }
+                console.log(`Applied: ${result.file}`);
+                console.log(`Backup: ${result.backupPath}`);
+                console.log("TypeScript verification: PASS");
+                console.log("ONCE PROTECTION APPLIED");
+            }
+            return;
+        }
+        case "setup": {
+            const autoConfirm = args.includes("--yes");
+            const planOnly = args.includes("--plan");
+            const skipInstall = args.includes("--skip-install");
+            const requestedPath = args.find(value => !value.startsWith("--")) ?? ".";
+            await runSetup(requestedPath, {
+                autoConfirm,
+                planOnly,
+                skipInstall
+            });
+            return;
+        }
+        case "help":
+        case "--help":
+        case "-h":
+            printHelp();
+            return;
+        default:
+            console.log(`Unknown command: ${command}`);
+            printHelp();
+            process.exitCode = 1;
+    }
+}
+try {
+    await main();
+}
+catch (error) {
+    console.error("");
+    console.error("Once command failed.");
+    if (error instanceof Error) {
+        console.error(error.message);
+    }
+    else {
+        console.error(error);
+    }
+    process.exitCode = 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+export type OnceProvider = "blind_test" | "http_v1" | "stripe_v1" | (string & {});
+export interface OnceOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    networkRetries?: number;
+}
+export interface ExecuteInput {
+    operationId: string;
+    provider: OnceProvider;
+    action: Record<string, unknown>;
+}
+export interface ExecuteResponse {
+    operation_id: string;
+    result: string;
+    state: string;
+    ledger_state?: string;
+    attempts?: number;
+    side_effects?: number;
+    provider_executed?: boolean;
+    provider_executed_at?: string | null;
+    [key: string]: unknown;
+}
+export interface TruthResponse {
+    operation_id: string;
+    attempts?: number;
+    ledger_state: string;
+    state?: string;
+    side_effects?: number;
+    provider_executed?: boolean;
+    provider_executed_at?: string | null;
+    first_attempt_at?: string | null;
+    last_attempt_at?: string | null;
+    [key: string]: unknown;
+}
+export declare class OnceError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    readonly body?: unknown;
+    readonly retryAfter?: number;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        body?: unknown;
+        retryAfter?: number;
+        cause?: unknown;
+    });
+}
+export declare class OnceTimeoutError extends OnceError {
+    constructor(message?: string, cause?: unknown);
+}
+export declare class OnceNetworkError extends OnceError {
+    constructor(message?: string, cause?: unknown);
+}
+export declare class Once {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly timeoutMs: number;
+    readonly networkRetries: number;
+    constructor(options?: OnceOptions);
+    /**
+     * Generate a deterministic Once operation ID.
+     *
+     * Same inputs => same ID.
+     *
+     * Example:
+     * Once.id("refund", "order_123")
+     */
+    static id(...parts: Array<string | number>): string;
+    id(...parts: Array<string | number>): string;
+    execute(input: ExecuteInput): Promise<ExecuteResponse>;
+    truth(operationId: string): Promise<TruthResponse>;
+    private request;
+}
+export default Once;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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