@spendctl/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,83 @@
+spendctl Proprietary Software License
+
+Copyright (c) 2026 Mirai Studio, Inc. (株式会社みらいスタジオ), Tokyo, Japan.
+All rights reserved.
+
+This software and its documentation (the "Software") are licensed, not sold.
+By installing or running the Software you agree to these terms. If you do not
+agree, do not install or run it.
+
+1. Grant. Subject to these terms and to the spendctl Terms of Service
+   (https://spendctl.dev/terms), Mirai Studio grants you a non-exclusive,
+   non-transferable, non-sublicensable, revocable licence to install and run
+   the Software, in the form distributed by Mirai Studio (for example through
+   the npm registry or a container image), on systems you control, solely to
+   use the spendctl service within the limits of your plan.
+
+2. Restrictions. Except as expressly permitted by Mirai Studio in writing or
+   by applicable law notwithstanding this restriction, you may not:
+   (a) copy, modify, translate, adapt or create derivative works of the
+       Software;
+   (b) distribute, publish, sublicense, sell, rent, lease, lend or otherwise
+       make the Software available to third parties;
+   (c) reverse engineer, decompile, disassemble or otherwise attempt to derive
+       the source code of the Software;
+   (d) remove, obscure or alter any proprietary notice in the Software;
+   (e) circumvent or disable licence keys, plan limits, usage metering or
+       security measures in the Software;
+   (f) use the Software to build or train a product that competes with
+       spendctl.
+
+3. Third-party components. The Software incorporates third-party components
+   under their own licences. Their notices are provided with the distributed
+   package (THIRD_PARTY_NOTICES). Nothing in this licence limits your rights
+   under those licences. The spendctl client SDKs are separately licensed
+   under the Apache License 2.0 (https://github.com/miraistudio/spendctl-sdk).
+
+4. Ownership. The Software is protected by copyright and other laws. Mirai
+   Studio and its licensors retain all right, title and interest in the
+   Software. No rights are granted except those expressly stated here.
+
+5. Your data and keys. The Software signs payments with a wallet you control
+   and keeps its ledger on systems you control. The Software may send
+   licence-validation and billing metadata to Mirai Studio as described in
+   the documentation; it does not send private keys, signed payment
+   authorizations, request bodies or response bodies to Mirai Studio.
+
+6. Feedback. If you send suggestions about the Software, Mirai Studio may use
+   them without obligation to you.
+
+7. Term and termination. This licence remains in effect until terminated. It
+   terminates automatically if you breach these terms or if your plan ends.
+   On termination you must stop using and delete the Software. Sections 2,
+   4, 8, 9 and 10 survive termination.
+
+8. Disclaimer of warranty. THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE"
+   WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND
+   NON-INFRINGEMENT. Spend policies are a safeguard, not a guarantee: Mirai
+   Studio does not warrant that the Software will prevent every unauthorised,
+   unintended or erroneous payment, that sellers or facilitators will behave
+   correctly, or that any blockchain or payment network will be available.
+   You remain responsible for the policies you configure and for the wallets
+   you connect.
+
+9. Limitation of liability. TO THE MAXIMUM EXTENT PERMITTED BY LAW, MIRAI
+   STUDIO SHALL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
+   CONSEQUENTIAL OR PUNITIVE DAMAGES, OR FOR ANY LOSS OF FUNDS, PROFITS, DATA
+   OR GOODWILL, ARISING OUT OF OR RELATED TO THE SOFTWARE, EVEN IF ADVISED OF
+   THE POSSIBILITY. MIRAI STUDIO'S TOTAL LIABILITY UNDER THIS LICENCE SHALL
+   NOT EXCEED THE AMOUNT YOU PAID FOR THE SPENDCTL SERVICE IN THE TWELVE
+   MONTHS BEFORE THE CLAIM. Nothing here limits liability that cannot be
+   limited under applicable law.
+
+10. Governing law. This licence is governed by the laws of Japan. The Tokyo
+    District Court has exclusive jurisdiction in the first instance over any
+    dispute arising from it.
+
+11. Export and sanctions. You may not use the Software in violation of
+    applicable export-control or sanctions laws.
+
+12. Entire agreement. This licence and the Terms of Service are the entire
+    agreement about the Software. If any provision is unenforceable, the rest
+    remains in effect.

package/README.md

@@ -1,3 +1,14 @@
-# Temporary Holding Version
+# @spendctl/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Policy engine, budget ledger and approval broker behind [spendctl](https://spendctl.dev).
+
+```ts
+import { parseConfigText, evaluate, Ledger } from "@spendctl/core";
+```
+
+- `parseConfigText` / `loadConfig`: validate `spendctl.yaml` (zod) into a normalised policy.
+- `evaluate`: pure decision function — allow / deny / approve with reasons an LLM can read.
+- `Ledger`: SQLite ledger on `node:sqlite` or `bun:sqlite` (no native addon) with `BEGIN IMMEDIATE` budget reservations, CSV/JSON export.
+- `ApprovalBroker`: persisted approvals with wait/decide/expire.
+
+Proprietary — see LICENSE. Part of the spendctl sidecar; docs at https://spendctl.dev/docs/.

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,54 @@
+THIRD-PARTY NOTICES for @spendctl/core@0.1.0
+
+@spendctl/core is proprietary software of Mirai Studio, Inc. It depends on the open-source packages listed below, which are distributed under their own licences. This file reproduces those licences and any NOTICE files, as the licences require. Generated 2026-10-25 from the production dependency tree.
+
+==============================================================================
+1. PACKAGES
+==============================================================================
+
+yaml@2.9.1 — ISC — Eemeli Aro — https://eemeli.org/yaml/
+zod@4.6.7 — MIT — Colin McDonnell — https://zod.dev
+
+==============================================================================
+2. LICENSE TEXTS
+==============================================================================
+
+--- Applies to: yaml@2.9.1 ---
+
+Copyright Eemeli Aro <eemeli@gmail.com>
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.
+
+--- Applies to: zod@4.6.7 ---
+
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+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/dist/approvals.d.ts

@@ -0,0 +1,30 @@
+import type { Ledger } from "./ledger/ledger.js";
+import type { Approval, ApprovalStatus, Attempt, Reason } from "./types.js";
+export interface ApprovalBrokerOptions {
+    timeoutMs: number;
+    /** Called once when an approval is created (webhooks, logs). Errors are swallowed. */
+    notify?: (approval: Approval, attempt: Attempt) => Promise<void> | void;
+}
+/**
+ * Creates approval requests, lets a human decide them, and wakes up any
+ * request that is waiting. Decisions are persisted in the ledger first, so a
+ * restart never loses an approval.
+ */
+export declare class ApprovalBroker {
+    private readonly ledger;
+    private readonly options;
+    private readonly waiters;
+    constructor(ledger: Ledger, options: ApprovalBrokerOptions);
+    create(attempt: Attempt, reasons: Reason[]): Approval;
+    /**
+     * Resolves when the approval is decided or expires (whichever comes first). With `timeoutMs` it
+     * also resolves — with the still-pending approval — once that long has passed, and with `signal`
+     * it resolves the same way as soon as the signal aborts (the requester went away).
+     */
+    wait(id: string, timeoutMs?: number, signal?: AbortSignal): Promise<Approval>;
+    decide(id: string, status: Exclude<ApprovalStatus, "pending">, by: string, note?: string): Approval | undefined;
+    pending(): Approval[];
+    /** Marks pending approvals past their deadline as expired. */
+    expireStale(now?: number): Approval[];
+}
+//# sourceMappingURL=approvals.d.ts.map

package/dist/approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../src/approvals.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAI5E,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACzE;AAED;;;;GAIG;AACH,qBAAa,cAAc;IAIvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAE1D,YACmB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,qBAAqB,EAC7C;IAEJ,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,QAAQ,CAmBpD;IAED;;;;OAIG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAgD5E;IAED,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,cAAc,EAAE,SAAS,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAO9G;IAED,OAAO,IAAI,QAAQ,EAAE,CAEpB;IAED,8DAA8D;IAC9D,WAAW,CAAC,GAAG,SAAa,GAAG,QAAQ,EAAE,CASxC;CACF"}

package/dist/approvals.js

@@ -0,0 +1,114 @@
+import { newId } from "./ids.js";
+/**
+ * Creates approval requests, lets a human decide them, and wakes up any
+ * request that is waiting. Decisions are persisted in the ledger first, so a
+ * restart never loses an approval.
+ */
+export class ApprovalBroker {
+    ledger;
+    options;
+    waiters = new Map();
+    constructor(ledger, options) {
+        this.ledger = ledger;
+        this.options = options;
+    }
+    create(attempt, reasons) {
+        const now = Date.now();
+        const approval = {
+            id: newId("apr"),
+            attemptId: attempt.id,
+            agent: attempt.agent,
+            createdAt: now,
+            expiresAt: now + this.options.timeoutMs,
+            status: "pending",
+            usdMicros: attempt.usdMicros,
+            host: attempt.host,
+            path: attempt.path,
+            reasons,
+        };
+        this.ledger.insertApproval(approval);
+        if (this.options.notify) {
+            Promise.resolve(this.options.notify(approval, attempt)).catch(() => undefined);
+        }
+        return approval;
+    }
+    /**
+     * Resolves when the approval is decided or expires (whichever comes first). With `timeoutMs` it
+     * also resolves — with the still-pending approval — once that long has passed, and with `signal`
+     * it resolves the same way as soon as the signal aborts (the requester went away).
+     */
+    wait(id, timeoutMs, signal) {
+        const current = this.ledger.getApproval(id);
+        if (!current)
+            return Promise.reject(new Error(`Unknown approval ${id}`));
+        if (current.status !== "pending" || signal?.aborted)
+            return Promise.resolve(current);
+        // Wall-clock deadline: the approval's own expiry, or the caller's shorter timeout.
+        const deadline = Math.min(current.expiresAt, timeoutMs === undefined ? Number.POSITIVE_INFINITY : Date.now() + timeoutMs);
+        return new Promise((resolve) => {
+            let timer;
+            const settle = (approval) => {
+                clearTimeout(timer);
+                signal?.removeEventListener("abort", onAbort);
+                this.waiters.get(id)?.delete(waiter);
+                resolve(approval);
+            };
+            const waiter = (approval) => settle(approval);
+            const onAbort = () => settle(this.ledger.getApproval(id) ?? current);
+            const onTimer = () => {
+                const latest = this.ledger.getApproval(id);
+                if (latest?.status !== "pending") {
+                    settle(latest ?? current);
+                    return;
+                }
+                // Node timers run on a monotonic clock that can be a few milliseconds behind Date.now(),
+                // so the timer may fire before the wall-clock deadline. Re-arm instead of returning a
+                // still-pending approval, which the caller would otherwise read as a denial.
+                const left = deadline - Date.now();
+                if (left > 0) {
+                    timer = setTimeout(onTimer, left);
+                    return;
+                }
+                if (Date.now() >= latest.expiresAt) {
+                    settle(this.decide(id, "expired", "timeout") ?? latest);
+                }
+                else {
+                    settle(latest); // the caller's own timeout elapsed; the approval is still open
+                }
+            };
+            timer = setTimeout(onTimer, Math.max(0, deadline - Date.now()));
+            signal?.addEventListener("abort", onAbort, { once: true });
+            let set = this.waiters.get(id);
+            if (!set) {
+                set = new Set();
+                this.waiters.set(id, set);
+            }
+            set.add(waiter);
+        });
+    }
+    decide(id, status, by, note) {
+        const approval = this.ledger.decideApproval(id, status, by, note);
+        if (approval && approval.status !== "pending") {
+            for (const waiter of [...(this.waiters.get(id) ?? [])])
+                waiter(approval);
+            this.waiters.delete(id);
+        }
+        return approval;
+    }
+    pending() {
+        return this.ledger.listApprovals("pending");
+    }
+    /** Marks pending approvals past their deadline as expired. */
+    expireStale(now = Date.now()) {
+        const expired = [];
+        for (const approval of this.pending()) {
+            if (approval.expiresAt <= now) {
+                const decided = this.decide(approval.id, "expired", "timeout");
+                if (decided)
+                    expired.push(decided);
+            }
+        }
+        return expired;
+    }
+}
+//# sourceMappingURL=approvals.js.map

package/dist/approvals.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,234 @@
+import { z } from "zod";
+export declare const agentPolicySchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        "dry-run": "dry-run";
+        enforce: "enforce";
+    }>>;
+    budget: z.ZodOptional<z.ZodObject<{
+        perRequest: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        hourly: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        daily: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        weekly: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        monthly: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    }, z.core.$strict>>;
+    onBudgetExceeded: z.ZodOptional<z.ZodEnum<{
+        approve: "approve";
+        deny: "deny";
+    }>>;
+    requireApprovalAbove: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    payTo: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    protocols: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        mpp: "mpp";
+        x402: "x402";
+    }>>>;
+    networks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    assets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    maxChainDepth: z.ZodOptional<z.ZodNumber>;
+    firstPaymentMax: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    priceJumpFactor: z.ZodOptional<z.ZodNumber>;
+    maxTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const configSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    server: z.ZodDefault<z.ZodObject<{
+        host: z.ZodDefault<z.ZodString>;
+        port: z.ZodDefault<z.ZodNumber>;
+        connect: z.ZodDefault<z.ZodEnum<{
+            deny: "deny";
+            tunnel: "tunnel";
+        }>>;
+        upstreamTimeout: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    }, z.core.$strict>>;
+    signer: z.ZodDefault<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"mock">;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"cdp">;
+        accountName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"private-key">;
+        env: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "type">>;
+    agentAuth: z.ZodDefault<z.ZodEnum<{
+        header: "header";
+        token: "token";
+    }>>;
+    defaultAgent: z.ZodOptional<z.ZodString>;
+    defaults: z.ZodDefault<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            "dry-run": "dry-run";
+            enforce: "enforce";
+        }>>;
+        budget: z.ZodOptional<z.ZodObject<{
+            perRequest: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            hourly: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            daily: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            weekly: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            monthly: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>>;
+        onBudgetExceeded: z.ZodOptional<z.ZodEnum<{
+            approve: "approve";
+            deny: "deny";
+        }>>;
+        requireApprovalAbove: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        payTo: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+        protocols: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            mpp: "mpp";
+            x402: "x402";
+        }>>>;
+        networks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        assets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        maxChainDepth: z.ZodOptional<z.ZodNumber>;
+        firstPaymentMax: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        priceJumpFactor: z.ZodOptional<z.ZodNumber>;
+        maxTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    agents: z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            "dry-run": "dry-run";
+            enforce: "enforce";
+        }>>;
+        budget: z.ZodOptional<z.ZodObject<{
+            perRequest: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            hourly: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            daily: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            weekly: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            monthly: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        }, z.core.$strict>>;
+        onBudgetExceeded: z.ZodOptional<z.ZodEnum<{
+            approve: "approve";
+            deny: "deny";
+        }>>;
+        requireApprovalAbove: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deny: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        payTo: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+        protocols: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            mpp: "mpp";
+            x402: "x402";
+        }>>>;
+        networks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        assets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        maxChainDepth: z.ZodOptional<z.ZodNumber>;
+        firstPaymentMax: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        priceJumpFactor: z.ZodOptional<z.ZodNumber>;
+        maxTimeoutSeconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    approvals: z.ZodDefault<z.ZodObject<{
+        timeout: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        onTimeout: z.ZodDefault<z.ZodEnum<{
+            deny: "deny";
+        }>>;
+        hold: z.ZodDefault<z.ZodBoolean>;
+        holdMax: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        webhooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            format: z.ZodDefault<z.ZodEnum<{
+                discord: "discord";
+                json: "json";
+                slack: "slack";
+            }>>;
+            secretEnv: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        publicUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    circuitBreaker: z.ZodDefault<z.ZodObject<{
+        failures: z.ZodDefault<z.ZodNumber>;
+        cooldown: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    }, z.core.$strict>>;
+    assets: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        network: z.ZodString;
+        asset: z.ZodString;
+        symbol: z.ZodString;
+        decimals: z.ZodNumber;
+        usdPegged: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    ledger: z.ZodDefault<z.ZodObject<{
+        path: z.ZodDefault<z.ZodString>;
+    }, z.core.$strict>>;
+    idempotencyWindow: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+}, z.core.$strict>;
+export type RawConfig = z.input<typeof configSchema>;
+export type ParsedConfig = z.output<typeof configSchema>;
+export type RawAgentPolicy = z.input<typeof agentPolicySchema>;
+export interface Budget {
+    perRequest?: bigint;
+    hourly?: bigint;
+    daily?: bigint;
+    weekly?: bigint;
+    monthly?: bigint;
+}
+export interface AgentPolicy {
+    name: string;
+    description?: string;
+    mode: "enforce" | "dry-run";
+    budget: Budget;
+    onBudgetExceeded: "deny" | "approve";
+    requireApprovalAbove?: bigint;
+    allow?: string[];
+    deny: string[];
+    payTo: Record<string, string[]>;
+    protocols?: string[];
+    networks?: string[];
+    assets?: string[];
+    maxChainDepth?: number;
+    firstPaymentMax?: bigint;
+    priceJumpFactor?: number;
+    maxTimeoutSeconds: number;
+}
+export interface WebhookConfig {
+    url: string;
+    format: "json" | "slack" | "discord";
+    secretEnv?: string;
+}
+export type SignerConfig = ParsedConfig["signer"];
+export interface AssetConfig {
+    network: string;
+    asset: string;
+    symbol: string;
+    decimals: number;
+    usdPegged: boolean;
+}
+export interface Config {
+    server: {
+        host: string;
+        port: number;
+        connect: "tunnel" | "deny";
+        upstreamTimeoutMs: number;
+    };
+    signer: SignerConfig;
+    agentAuth: "header" | "token";
+    defaultAgent?: string;
+    agents: Record<string, AgentPolicy>;
+    approvals: {
+        timeoutMs: number;
+        onTimeout: "deny";
+        hold: boolean;
+        holdMaxMs: number;
+        webhooks: WebhookConfig[];
+        publicUrl?: string;
+    };
+    circuitBreaker: {
+        failures: number;
+        cooldownMs: number;
+    };
+    assets: AssetConfig[];
+    ledger: {
+        path: string;
+    };
+    idempotencyWindowMs: number;
+}
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/** Validates and normalises a raw config object (e.g. parsed YAML). */
+export declare function resolveConfig(raw: unknown): Config;
+export declare function parseConfigText(text: string): Config;
+export declare function loadConfig(path: string): Config;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

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