@avow-finance/sdk 0.0.0-stage → 0.2.0

package/dist/session/world.d.ts

@@ -0,0 +1,188 @@
+import type { BuyerSideReference, ChargeKind, ChargePauseCause, ComputeOffer, ComputeOffers, DeliveryResult, GpuReservationTerms, JobOffer, OrderScenario, OrderState, PinnedBlock, QuoteRequest, RailState, ReasonCode, RefusalAmounts, RefusalLayer, TestCustomerProfile } from '@avow-finance/spec';
+import type { Hex } from 'viem';
+import type { JobAcceptance } from '../job/accept.js';
+import type { ReservedJob } from './service.js';
+import type { ChainSnapshot } from './service-check.js';
+/**
+ * Everything the agent session does to the outside world, behind one seam. The live sandbox
+ * implements it with the SDK, Avow's API, the test customer and Tempo's testnet. The fixture world
+ * implements it in memory with the same rules for tests and the eval, and anything it draws says
+ * so. The tool layer, the executor and the session run the same code against either. Nothing here
+ * hands out a key, and every result is public data.
+ */
+export interface JobWorld {
+    /** `live` on testnet, or `fixture` in memory for tests and the eval. */
+    readonly kind: 'live' | 'fixture';
+    /** Avow's test customer, as its profile names it. */
+    readonly customer: TestCustomerProfile;
+    /** The supplier the agent books compute from. */
+    readonly computeSupplier: string;
+    /** The business as the job's supplier, which the customer's lock has to name. */
+    readonly supplier: ReservedJob['supplier'];
+    /** The token the business's and the customer's locks hold. */
+    readonly token: ReservedJob['token'];
+    /**
+     * Asks the test customer for a new order. With a scenario, the customer plays it out, as when it
+     * cancels the job after its start.
+     */
+    pullOrder(scenario?: OrderScenario): Promise<JobOffer>;
+    /** The compute supplier's offers for an order's window. */
+    offers(order: JobOffer): Promise<ComputeOffers>;
+    /**
+     * Books `gpus` of an offer through the SDK, which checks the mandate, has Avow approve, funds the
+     * reserve and waits for the supplier's acceptance. A refusal names its layer, and no money moved.
+     */
+    book(offer: ComputeOffer, gpus: number): Promise<BookOutcome>;
+    /** The agent's authority now, from the lock and the account's keychain. */
+    authority(): Promise<AuthorityNow>;
+    /** Reads a commitment on its lock at the latest finalized block. */
+    read(reference: BuyerSideReference): Promise<LockRead | null>;
+    /**
+     * Quotes an order with terms naming the booking, or none, signed by the supplier signing key. A
+     * refusal is the customer's, before it started checking.
+     */
+    quote(order: JobOffer, booking: WorldBooking | null): Promise<QuoteOutcome>;
+    /** Where an order stands now, as the test customer reports it. */
+    orderState(orderId: string): Promise<OrderState>;
+    /**
+     * Checks the customer's commitment again with Avow's authorization and accepts it on the
+     * customer's lock, as `acceptJob` does. A send whose outcome is unknown throws.
+     */
+    accept(order: JobOffer, quote: QuoteRequest): Promise<JobAcceptance>;
+    /** Which of these transactions landed and succeeded, with its block, or null for none. */
+    landed(hashes: readonly Hex[]): Promise<{
+        transactionHash: Hex;
+        blockNumber: bigint;
+    } | null>;
+    /** Reports delivery, handing over the result. */
+    deliver(orderId: string, result: DeliveryResult): Promise<void>;
+    /**
+     * Reports a charge of one kind on the customer's reserve for an order, for the most the job's
+     * terms allow, signed by the supplier signing key. The verifier builds the report only when the
+     * lock would take it. A send whose outcome is unknown throws.
+     */
+    reportCharge(order: JobOffer, kind: ChargeKind): Promise<ChargeReport>;
+    /** Where a report stands on the customer's lock now. */
+    charge(order: JobOffer, report: ReportedCharge): Promise<ChargeStanding>;
+    /**
+     * Cancels a booking on the lock, which needs the business's root key, or says why it can't here.
+     */
+    cancel(booking: WorldBooking): Promise<CancelOutcome>;
+    /** Where `checkBeforeWork` reads the chain from, in its own process. */
+    chainFor(job: ReservedJob): Promise<ChildChain>;
+    /** The clock, in unix seconds. */
+    now(): bigint;
+    /** Waits, so a fixture world can run its clock instead. */
+    sleep(ms: number): Promise<void>;
+}
+/**
+ * Where the process that runs `checkBeforeWork` reads the chain. A live run gives it Tempo's RPC
+ * to read for itself. The fixture world's chain lives in memory, so it hands over what it holds at
+ * one block, which the checks read through the same interfaces.
+ */
+export type ChildChain = {
+    kind: 'rpc';
+    url: string;
+    chainId: number;
+    factory: Hex;
+} | {
+    kind: 'snapshot';
+    snapshot: ChainSnapshot;
+};
+/** A compute booking the session made, with what anyone can check about it. */
+export interface WorldBooking {
+    /** The session's own name for it, which the model uses. */
+    id: string;
+    offer: ComputeOffer;
+    gpus: number;
+    reference: BuyerSideReference;
+    terms: GpuReservationTerms;
+    salt: Hex;
+    /** The reserve, in micros. */
+    reserve: bigint;
+    /** The usage price for the whole window, in micros, paid apart from the reserve. */
+    price: bigint;
+    /** The transaction that funded the reserve, when the chain showed it. */
+    reservedIn: Hex | null;
+    /** The booking on its lock once the supplier accepted, as read then. */
+    read: LockRead;
+}
+/** A commitment as its lock held it at one block. */
+export interface LockRead {
+    state: RailState;
+    block: PinnedBlock;
+    freeCancelBy: bigint;
+    releaseDate: bigint;
+}
+export type BookOutcome = {
+    ok: true;
+    booking: Omit<WorldBooking, 'id'>;
+} | {
+    ok: false;
+    code: ReasonCode;
+    layer: RefusalLayer;
+    amounts: RefusalAmounts;
+};
+export type QuoteOutcome = {
+    ok: true;
+    quote: QuoteRequest;
+} | {
+    ok: false;
+    code: ReasonCode;
+    layer: 'customer' | 'service';
+};
+/** A report the customer's lock took. */
+export interface ReportedCharge {
+    /** The charge reported, in micros. */
+    amount: bigint;
+    /** Which of the commitment's reports it is, 1 or 2. */
+    reportNumber: number;
+    transactionHash: Hex;
+    /** The time of the block the report landed in, which Avow's deadline to answer counts from. */
+    reportedAt: bigint;
+}
+export type ChargeReport = ({
+    ok: true;
+} & ReportedCharge) | {
+    ok: false;
+    code: ReasonCode;
+    layer: 'service' | 'lock';
+};
+/**
+ * Where a reported charge stands. `waiting` is a report Avow hasn't answered. `confirmed` is one
+ * Avow confirmed, which the customer can contest until `contestableUntil` and which is payable
+ * then. `paused` waits for a ruling. `paid` reached the business, and `ended` is a report withdrawn
+ * or a commitment that ended another way.
+ */
+export type ChargeStanding = {
+    state: 'waiting';
+} | {
+    state: 'confirmed';
+    contestableUntil: bigint;
+} | {
+    state: 'paused';
+    cause: ChargePauseCause;
+} | {
+    state: 'paid';
+} | {
+    state: 'ended';
+};
+export type CancelOutcome = {
+    ok: true;
+    transactionHash: Hex;
+} | {
+    ok: false;
+    code: ReasonCode;
+    layer: RefusalLayer;
+    why: string;
+};
+/** The agent's limits now, in micros. */
+export interface AuthorityNow {
+    capPerCommitment: bigint;
+    capOpenReserves: bigint;
+    openReservesLeft: bigint;
+    dailyLimit: bigint | null;
+    dailyLeft: bigint | null;
+    suppliers: readonly string[];
+}
+//# sourceMappingURL=world.d.ts.map

package/dist/session/world.d.ts.map

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

package/dist/session/world.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=world.js.map

package/dist/session/world.js.map

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

package/dist/sign.d.ts

@@ -0,0 +1,19 @@
+import { type AvowDomain, type HashSigner, type HumanApproval, type Mandate, type Signed } from '@avow-finance/spec';
+import { type Address, type Hex, type TypedData, type TypedDataDefinition } from 'viem';
+/**
+ * Signs for a business account with its root key or an admin key. Every signature comes out in
+ * Tempo's keychain V2 envelope, which the lock's `verifyKeychainAdmin` check and Avow's API need.
+ * A browser passkey from viem's `Account.fromWebAuthnP256` signs bare, so pass it here as `key`
+ * and the envelope is added for it.
+ */
+export interface AccountSigner {
+    readonly account: Address;
+    signDigest(digest: Hex): Promise<Hex>;
+    signTypedData<const T extends TypedData | Record<string, unknown>, P extends keyof T | 'EIP712Domain'>(typedData: TypedDataDefinition<T, P>): Promise<Hex>;
+}
+export declare function accountSigner(account: Address, key: HashSigner): AccountSigner;
+/** The administrator signs a mandate for one agent, as the business account. */
+export declare function signMandate(mandate: Mandate, d: AvowDomain, signer: AccountSigner): Promise<Signed<Mandate>>;
+/** The administrator approves one reserve in person, as the business account. */
+export declare function signHumanApproval(approval: HumanApproval, d: AvowDomain, signer: AccountSigner): Promise<Signed<HumanApproval>>;
+//# sourceMappingURL=sign.d.ts.map

package/dist/sign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.d.ts","sourceRoot":"","sources":["../src/sign.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,aAAa,EAElB,KAAK,OAAO,EAGZ,KAAK,MAAM,EAEZ,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,GAAG,EAGR,KAAK,SAAS,EACd,KAAK,mBAAmB,EACzB,MAAM,MAAM,CAAA;AAEb;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,UAAU,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IACrC,aAAa,CACX,KAAK,CAAC,CAAC,SAAS,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnD,CAAC,SAAS,MAAM,CAAC,GAAG,cAAc,EAClC,SAAS,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;CACtD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,GAAG,aAAa,CAM9E;AAkBD,gFAAgF;AAChF,wBAAsB,WAAW,CAC/B,OAAO,EAAE,OAAO,EAChB,CAAC,EAAE,UAAU,EACb,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAM1B;AAED,iFAAiF;AACjF,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,aAAa,EACvB,CAAC,EAAE,UAAU,EACb,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAGhC"}

package/dist/sign.js

@@ -0,0 +1,33 @@
+import { humanApprovalTypedData, MESSAGE_VERSIONS, mandateTypedData, signForAccount, } from '@avow-finance/spec';
+import { hashTypedData, isAddressEqual, } from 'viem';
+export function accountSigner(account, key) {
+    return {
+        account,
+        signDigest: (digest) => signForAccount(account, digest, key),
+        signTypedData: (typedData) => signForAccount(account, hashTypedData(typedData), key),
+    };
+}
+function envelope(type, d, message, signature) {
+    return {
+        type,
+        schemaVersion: MESSAGE_VERSIONS[type],
+        chainId: d.chainId,
+        lock: d.verifyingContract,
+        message,
+        signature,
+    };
+}
+/** The administrator signs a mandate for one agent, as the business account. */
+export async function signMandate(mandate, d, signer) {
+    if (!isAddressEqual(mandate.account, signer.account)) {
+        throw new Error("The mandate names another account than the signer's");
+    }
+    const signature = await signer.signTypedData(mandateTypedData(mandate, d));
+    return envelope('Mandate', d, mandate, signature);
+}
+/** The administrator approves one reserve in person, as the business account. */
+export async function signHumanApproval(approval, d, signer) {
+    const signature = await signer.signTypedData(humanApprovalTypedData(approval, d));
+    return envelope('HumanApproval', d, approval, signature);
+}
+//# sourceMappingURL=sign.js.map

package/dist/sign.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sign.js","sourceRoot":"","sources":["../src/sign.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,sBAAsB,EAEtB,gBAAgB,EAChB,gBAAgB,EAEhB,cAAc,GACf,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAGL,aAAa,EACb,cAAc,GAGf,MAAM,MAAM,CAAA;AAiBb,MAAM,UAAU,aAAa,CAAC,OAAgB,EAAE,GAAe;IAC7D,OAAO;QACL,OAAO;QACP,UAAU,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC;QAC5D,aAAa,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,EAAE,GAAG,CAAC;KACrF,CAAA;AACH,CAAC;AAED,SAAS,QAAQ,CACf,IAAuB,EACvB,CAAa,EACb,OAAU,EACV,SAAc;IAEd,OAAO;QACL,IAAI;QACJ,aAAa,EAAE,gBAAgB,CAAC,IAAI,CAAC;QACrC,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,IAAI,EAAE,CAAC,CAAC,iBAAiB;QACzB,OAAO;QACP,SAAS;KACV,CAAA;AACH,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAgB,EAChB,CAAa,EACb,MAAqB;IAErB,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAA;IACxE,CAAC;IACD,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAA;IAC1E,OAAO,QAAQ,CAAC,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,CAAA;AACnD,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAuB,EACvB,CAAa,EACb,MAAqB;IAErB,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,sBAAsB,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAA;IACjF,OAAO,QAAQ,CAAC,eAAe,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAA;AAC1D,CAAC"}

package/dist/supplier.d.ts

@@ -0,0 +1,41 @@
+import { type AgreementOffer, type Signed, type StartReceipt, type SupplierProfile } from '@avow-finance/spec';
+import type { Hex } from 'viem';
+/**
+ * The agent's channel to one supplier. The supplier's own integration implements it, and a
+ * scripted supplier implements it for a demo or a test. Over HTTP, a supplier's adapter serves
+ * the profile and the agreement at the routes `SUPPLIER_ADAPTER_PATHS` names, with the bodies the
+ * spec's `parseSupplierProfile`, `parseAgreementOffer` and `parseAgreementSignature` read.
+ */
+export interface SupplierConnection {
+    /** The supplier's business id, account, signing key and payout address. */
+    readonly profile: SupplierProfile;
+    /**
+     * Asks the supplier to sign the terms agreement. The supplier checks that the terms and salt
+     * give the agreement's terms hash and that the terms are ones it offers, then signs the
+     * agreement with its signing key and returns the signature.
+     */
+    signAgreement(offer: AgreementOffer): Promise<Hex>;
+    /** Asks the supplier to start the job, which returns its signed start receipt. */
+    startJob(request: {
+        commitmentId: Hex;
+        startRequestHash: Hex;
+        requestedAt: bigint;
+    }): Promise<Signed<StartReceipt>>;
+}
+/**
+ * A supplier declining to sign an agreement, with the status it answered, such as over its most
+ * for one booking or past its limit of open bookings. Nothing was reserved.
+ */
+export declare class SupplierDeclined extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * The agent's channel to a supplier's adapter, over the routes and bodies the spec fixes for
+ * every adapter. The profile comes from the supplier, and the agent checks every signature it gets
+ * back against the signing key in that profile before it relies on it. The SDK refuses a booking
+ * whose agreement another key signed, and Avow's API checks the profile against what it recorded
+ * for the supplier.
+ */
+export declare function httpSupplier(url: string, send?: typeof fetch): Promise<SupplierConnection>;
+//# sourceMappingURL=supplier.d.ts.map

package/dist/supplier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supplier.d.ts","sourceRoot":"","sources":["../src/supplier.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EAInB,KAAK,MAAM,EACX,KAAK,YAAY,EAEjB,KAAK,eAAe,EAErB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AAE/B;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IAClD,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE;QAChB,YAAY,EAAE,GAAG,CAAA;QACjB,gBAAgB,EAAE,GAAG,CAAA;QACrB,WAAW,EAAE,MAAM,CAAA;KACpB,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAA;CAClC;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAGvC,QAAQ,CAAC,MAAM,EAAE,MAAM;IAFzB,YACE,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EAIxB;CACF;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,OAAO,KAAa,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAiC7B"}

package/dist/supplier.js

@@ -0,0 +1,57 @@
+import { parseAgreementSignature, parseSupplierProfile, parseSupplierRefusal, SUPPLIER_ADAPTER_PATHS, toWire, } from '@avow-finance/spec';
+/**
+ * A supplier declining to sign an agreement, with the status it answered, such as over its most
+ * for one booking or past its limit of open bookings. Nothing was reserved.
+ */
+export class SupplierDeclined extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'SupplierDeclined';
+    }
+}
+/**
+ * The agent's channel to a supplier's adapter, over the routes and bodies the spec fixes for
+ * every adapter. The profile comes from the supplier, and the agent checks every signature it gets
+ * back against the signing key in that profile before it relies on it. The SDK refuses a booking
+ * whose agreement another key signed, and Avow's API checks the profile against what it recorded
+ * for the supplier.
+ */
+export async function httpSupplier(url, send = fetch) {
+    const base = url.replace(/\/+$/, '');
+    const answer = await send(`${base}${SUPPLIER_ADAPTER_PATHS.profile}`, {
+        signal: AbortSignal.timeout(15_000),
+    });
+    const profile = parseSupplierProfile(await answer.json().catch(() => null));
+    if (!answer.ok || !profile.ok)
+        throw new Error(`${base} gave no supplier profile`);
+    return {
+        profile: profile.value,
+        async signAgreement(offer) {
+            const signed = await send(`${base}${SUPPLIER_ADAPTER_PATHS.agreements}`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(toWire(offer)),
+                signal: AbortSignal.timeout(30_000),
+            });
+            const body = await signed.json().catch(() => null);
+            if (!signed.ok) {
+                const why = parseSupplierRefusal(body)?.error ?? String(signed.status);
+                // A 4xx is the supplier's answer, and anything else is a supplier that couldn't answer.
+                if (signed.status < 500) {
+                    throw new SupplierDeclined(`The supplier refused the agreement: ${why}`, signed.status);
+                }
+                throw new Error(`The supplier couldn't answer the agreement: ${why}`);
+            }
+            const parsed = parseAgreementSignature(body);
+            if (!parsed.ok)
+                throw new Error(`The supplier answered with no signature (${parsed.reason})`);
+            return parsed.value.signature;
+        },
+        async startJob() {
+            throw new Error("The supplier adapter's routes don't start a job yet");
+        },
+    };
+}
+//# sourceMappingURL=supplier.js.map

package/dist/supplier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supplier.js","sourceRoot":"","sources":["../src/supplier.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EAGpB,sBAAsB,EAEtB,MAAM,GACP,MAAM,oBAAoB,CAAA;AA0B3B;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAG9B,MAAM;IAFjB,YACE,OAAe,EACN,MAAc;QAEvB,KAAK,CAAC,OAAO,CAAC,CAAA;sBAFL,MAAM;QAGf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAA;IAChC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,GAAW,EACX,IAAI,GAAiB,KAAK;IAE1B,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACpC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,sBAAsB,CAAC,OAAO,EAAE,EAAE;QACpE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC;KACpC,CAAC,CAAA;IACF,MAAM,OAAO,GAAG,oBAAoB,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAA;IAC3E,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,2BAA2B,CAAC,CAAA;IAClF,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,KAAK;QACtB,KAAK,CAAC,aAAa,CAAC,KAAK;YACvB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,sBAAsB,CAAC,UAAU,EAAE,EAAE;gBACvE,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACnC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC;aACpC,CAAC,CAAA;YACF,MAAM,IAAI,GAAY,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAA;YAC3D,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;gBACf,MAAM,GAAG,GAAG,oBAAoB,CAAC,IAAI,CAAC,EAAE,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;gBACtE,wFAAwF;gBACxF,IAAI,MAAM,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;oBACxB,MAAM,IAAI,gBAAgB,CAAC,uCAAuC,GAAG,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;gBACzF,CAAC;gBACD,MAAM,IAAI,KAAK,CAAC,+CAA+C,GAAG,EAAE,CAAC,CAAA;YACvE,CAAC;YACD,MAAM,MAAM,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAA;YAC5C,IAAI,CAAC,MAAM,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,4CAA4C,MAAM,CAAC,MAAM,GAAG,CAAC,CAAA;YAC7F,OAAO,MAAM,CAAC,KAAK,CAAC,SAAS,CAAA;QAC/B,CAAC;QACD,KAAK,CAAC,QAAQ;YACZ,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAA;QACxE,CAAC;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@avow-finance/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "TypeScript SDK for agents making commitments backed by Avow reserves",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": "./dist/node.js",
+      "default": "./dist/index.js"
+    },
+    "./agent": {
+      "types": "./dist/agent-entry.d.ts",
+      "node": "./dist/node-agent.js",
+      "default": "./dist/agent-entry.js"
+    },
+    "./service": {
+      "types": "./dist/service-entry.d.ts",
+      "default": "./dist/service-entry.js"
+    },
+    "./cli": "./dist/node/cli.js"
+  },
+  "bin": {
+    "avow-sandbox": "./dist/node/cli.js",
+    "avow-sandbox-mcp": "./dist/node/mcp.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Avow-Finance/avow.git",
+    "directory": "packages/sdk"
+  },
+  "dependencies": {
+    "ox": "0.14.57",
+    "uqr": "0.1.3",
+    "viem": "2.57.11",
+    "@avow-finance/spec": "0.2.0",
+    "@avow-finance/terminal": "0.2.0",
+    "@avow-finance/verifier": "0.2.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }