@shroud-fi/agent-runtime 0.1.0

package/dist/cjs/browser.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * createShroudAgentFromBrowserWallet — browser / EIP-1193 wallet entry point.
+ *
+ * Flow:
+ *   1. Ask the wallet to sign BROWSER_KEY_MESSAGE via personal_sign.
+ *   2. HKDF the signature bytes to a deterministic 32-byte master seed.
+ *   3. Delegate to createShroudAgent.
+ *
+ * The same wallet always produces the same agent identity — no localStorage,
+ * no persistence. Bumping BROWSER_KEY_MESSAGE forks the identity space.
+ *
+ * Privacy invariants:
+ *   - No console.* anywhere.
+ *   - The signature bytes never appear in error messages or stack frames.
+ *   - The derived master seed is passed to createShroudAgent and immediately
+ *     consumed by createAgentIdentity; no caller-visible reference is retained.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HKDF_BROWSER_INFO = exports.HKDF_BROWSER_SALT = exports.BROWSER_KEY_MESSAGE = void 0;
+exports.createShroudAgentFromBrowserWallet = createShroudAgentFromBrowserWallet;
+const hkdf_1 = require("@noble/hashes/hkdf");
+const sha256_1 = require("@noble/hashes/sha256");
+const factory_js_1 = require("./factory.js");
+const constants_js_1 = require("./constants.js");
+const errors_js_1 = require("./errors.js");
+var constants_js_2 = require("./constants.js");
+Object.defineProperty(exports, "BROWSER_KEY_MESSAGE", { enumerable: true, get: function () { return constants_js_2.BROWSER_KEY_MESSAGE; } });
+Object.defineProperty(exports, "HKDF_BROWSER_SALT", { enumerable: true, get: function () { return constants_js_2.HKDF_BROWSER_SALT; } });
+Object.defineProperty(exports, "HKDF_BROWSER_INFO", { enumerable: true, get: function () { return constants_js_2.HKDF_BROWSER_INFO; } });
+/**
+ * Decode a 0x-prefixed hex string (e.g. an EIP-191 signature) into bytes.
+ * Returns null on malformed input — callers map this to a privacy-safe error
+ * rather than surfacing the raw value.
+ */
+function hexToBytesSafe(hex) {
+    if (typeof hex !== 'string')
+        return null;
+    const stripped = hex.startsWith('0x') ? hex.slice(2) : hex;
+    if (stripped.length === 0 || stripped.length % 2 !== 0)
+        return null;
+    const out = new Uint8Array(stripped.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        const byte = parseInt(stripped.slice(i * 2, i * 2 + 2), 16);
+        if (Number.isNaN(byte))
+            return null;
+        out[i] = byte;
+    }
+    return out;
+}
+/**
+ * Build a ShroudAgent from a browser wallet adapter (e.g. MetaMask).
+ *
+ * @throws MissingBrowserWalletError if the adapter is missing required fields.
+ * @throws BrowserWalletSignatureRejectedError if the signature request is rejected.
+ */
+async function createShroudAgentFromBrowserWallet(args) {
+    const wallet = args.wallet;
+    if (wallet === undefined ||
+        wallet === null ||
+        typeof wallet.signMessage !== 'function' ||
+        typeof wallet.address !== 'string' ||
+        !wallet.address.startsWith('0x')) {
+        throw new errors_js_1.MissingBrowserWalletError();
+    }
+    let signature;
+    try {
+        signature = await wallet.signMessage(constants_js_1.BROWSER_KEY_MESSAGE);
+    }
+    catch {
+        // Never surface the underlying rejection reason — could embed wallet
+        // metadata or user prompt text.
+        throw new errors_js_1.BrowserWalletSignatureRejectedError();
+    }
+    const sigBytes = hexToBytesSafe(signature);
+    if (sigBytes === null || sigBytes.length === 0) {
+        throw new errors_js_1.BrowserWalletSignatureRejectedError();
+    }
+    // HKDF-SHA256: extract + expand the signature into a deterministic 32-byte
+    // master seed. The signature is the IKM, not the salt — salt and info are
+    // constant version tags.
+    const masterSeed = (0, hkdf_1.hkdf)(sha256_1.sha256, sigBytes, constants_js_1.HKDF_BROWSER_SALT, constants_js_1.HKDF_BROWSER_INFO, constants_js_1.BROWSER_MASTER_SEED_LENGTH);
+    const config = {
+        masterSeed,
+        transport: args.transport,
+        startBlock: args.startBlock,
+        ...(args.stealthContract !== undefined
+            ? { stealthContract: args.stealthContract }
+            : {}),
+        ...(args.finality !== undefined ? { finality: args.finality } : {}),
+    };
+    return (0, factory_js_1.createShroudAgent)(config);
+}
+//# sourceMappingURL=browser.js.map

package/dist/cjs/browser.js.map

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

package/dist/cjs/constants.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Agent runtime constants.
+ *
+ * BROWSER_KEY_MESSAGE is the personal-sign payload the browser factory asks
+ * MetaMask (or any EIP-1193 wallet) to sign. It is HKDF'd into a deterministic
+ * 32-byte master seed so the same wallet always produces the same agent
+ * identity — no localStorage, no key persistence.
+ *
+ * Versioning the message string is load-bearing: bumping `-v1` to `-v2` will
+ * derive a different identity even for the same wallet. Treat as a one-way
+ * cryptographic input; never rename without a migration story.
+ */
+export declare const BROWSER_KEY_MESSAGE = "ShroudFi-Demo-Key-Derivation-v1";
+export declare const HKDF_BROWSER_SALT: Uint8Array<ArrayBuffer>;
+export declare const HKDF_BROWSER_INFO: Uint8Array<ArrayBuffer>;
+export declare const BROWSER_MASTER_SEED_LENGTH = 32;
+//# sourceMappingURL=constants.d.ts.map

package/dist/cjs/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,mBAAmB,oCACG,CAAC;AAEpC,eAAO,MAAM,iBAAiB,yBAA+C,CAAC;AAC9E,eAAO,MAAM,iBAAiB,yBAAgD,CAAC;AAE/E,eAAO,MAAM,0BAA0B,KAAK,CAAC"}

package/dist/cjs/constants.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Agent runtime constants.
+ *
+ * BROWSER_KEY_MESSAGE is the personal-sign payload the browser factory asks
+ * MetaMask (or any EIP-1193 wallet) to sign. It is HKDF'd into a deterministic
+ * 32-byte master seed so the same wallet always produces the same agent
+ * identity — no localStorage, no key persistence.
+ *
+ * Versioning the message string is load-bearing: bumping `-v1` to `-v2` will
+ * derive a different identity even for the same wallet. Treat as a one-way
+ * cryptographic input; never rename without a migration story.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BROWSER_MASTER_SEED_LENGTH = exports.HKDF_BROWSER_INFO = exports.HKDF_BROWSER_SALT = exports.BROWSER_KEY_MESSAGE = void 0;
+exports.BROWSER_KEY_MESSAGE = 'ShroudFi-Demo-Key-Derivation-v1';
+exports.HKDF_BROWSER_SALT = new TextEncoder().encode('ShroudFi-Demo-v1');
+exports.HKDF_BROWSER_INFO = new TextEncoder().encode('agent-master-seed');
+exports.BROWSER_MASTER_SEED_LENGTH = 32;
+//# sourceMappingURL=constants.js.map

package/dist/cjs/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;AAEU,QAAA,mBAAmB,GAC9B,iCAAiC,CAAC;AAEvB,QAAA,iBAAiB,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;AACjE,QAAA,iBAAiB,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAElE,QAAA,0BAA0B,GAAG,EAAE,CAAC"}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Privacy-safe error classes for @shroud-fi/agent-runtime.
+ *
+ * Invariants (mirrored from @shroud-fi/scanning + @shroud-fi/payments):
+ *   - No 32-byte hex (key material) in any message.
+ *   - No ephemeral pubkey bytes in any message.
+ *   - No raw signature bytes in any message.
+ *   - No transfer amounts in any message.
+ *   - Messages carry short, structured reasons only.
+ */
+export declare class AgentRuntimeError extends Error {
+    readonly name: string;
+    constructor(message: string);
+}
+export declare class AgentNotStartedError extends AgentRuntimeError {
+    readonly name: string;
+    constructor();
+}
+export declare class AgentAlreadyStartedError extends AgentRuntimeError {
+    readonly name: string;
+    constructor();
+}
+export declare class MissingBrowserWalletError extends AgentRuntimeError {
+    readonly name: string;
+    constructor();
+}
+export declare class BrowserWalletSignatureRejectedError extends AgentRuntimeError {
+    readonly name: string;
+    constructor();
+}
+/**
+ * Thrown when `sweepViaRelayer` is called but no relayer contract has been
+ * registered for the agent's chain. Callers can pass an explicit
+ * `relayerContract` to override the lookup.
+ */
+export declare class RelayerContractNotConfiguredError extends AgentRuntimeError {
+    readonly name: string;
+    constructor();
+}
+/**
+ * P5.1 — thrown when the caller tries to use the ETH gasless sweep path but
+ * has not provided a `selfHostEndpoint`. ETH gasless requires a self-host
+ * relayer service that builds + broadcasts the EIP-7702 type-0x04 tx; there
+ * is no third-party fallback (Gelato's 7702 surface is wallet-shaped, not
+ * relayer-shaped).
+ */
+export declare class EthRelayerEndpointRequiredError extends AgentRuntimeError {
+    readonly name: string;
+    constructor();
+}
+/**
+ * P5.1 — thrown when no ShroudFiEthRelayer contract has been registered for
+ * the agent's chain and the caller did not pass `ethRelayerContract` to
+ * override the manifest lookup.
+ */
+export declare class EthRelayerContractNotConfiguredError extends AgentRuntimeError {
+    readonly name: string;
+    constructor();
+}
+/**
+ * @deprecated Retained as a soft-removed export — callers updated to use
+ * EthRelayerEndpointRequiredError or the gasless ETH path directly. P5.1
+ * activated the previously-stubbed ETH-via-relayer path.
+ */
+export declare class RelayerNotAvailableForETHError extends AgentRuntimeError {
+    readonly name: string;
+    constructor();
+}
+/**
+ * M3 — thrown when `register()` is called but the agent's registrant wallet
+ * already has a non-empty stealth meta-address on file in the canonical
+ * ERC-6538 registry for scheme 1. Callers should treat this as benign and
+ * skip the registration tx; `ensureRegistered` does this automatically.
+ *
+ * Privacy: the registrant wallet address is NOT placed in `.message` — it
+ * would link the agent's runtime wallet to the error log. Callers who need
+ * to display the wallet must source it from `transport.walletClient.account`
+ * themselves.
+ */
+export declare class AlreadyRegisteredError extends AgentRuntimeError {
+    readonly name: string;
+    constructor();
+}
+/**
+ * M3 — wraps an underlying error thrown while `ensureRegistered` runs inside
+ * `agent.sendToWallet` with `autoRegister: true`. Preserves the original via
+ * the standard `cause` chain so callers can introspect without parsing
+ * strings.
+ *
+ * Privacy: the inner error MUST itself comply with the runtime's no-amount /
+ * no-wallet / no-key rule. This wrapper never inlines key, signature, or
+ * amount material into its own message.
+ */
+export declare class AutoRegistrationFailedError extends AgentRuntimeError {
+    readonly name: string;
+    constructor(cause?: unknown);
+}
+/**
+ * M3 — thrown when `register()` is invoked on a transport that has no
+ * `walletClient` (or no account on the walletClient). Registration is a state
+ * change tx that needs a signer; read-only transports cannot register.
+ */
+export declare class RegistrationRequiresWalletError extends AgentRuntimeError {
+    readonly name: string;
+    constructor();
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAkB,IAAI,EAAE,MAAM,CAAuB;gBACzC,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,oBAAqB,SAAQ,iBAAiB;IACzD,SAAkB,IAAI,EAAE,MAAM,CAA0B;;CAIzD;AAED,qBAAa,wBAAyB,SAAQ,iBAAiB;IAC7D,SAAkB,IAAI,EAAE,MAAM,CAA8B;;CAI7D;AAED,qBAAa,yBAA0B,SAAQ,iBAAiB;IAC9D,SAAkB,IAAI,EAAE,MAAM,CAA+B;;CAI9D;AAED,qBAAa,mCAAoC,SAAQ,iBAAiB;IACxE,SAAkB,IAAI,EAAE,MAAM,CAAyC;;CAIxE;AAED;;;;GAIG;AACH,qBAAa,iCAAkC,SAAQ,iBAAiB;IACtE,SAAkB,IAAI,EAAE,MAAM,CAAuC;;CAItE;AAED;;;;;;GAMG;AACH,qBAAa,+BAAgC,SAAQ,iBAAiB;IACpE,SAAkB,IAAI,EAAE,MAAM,CAAqC;;CAMpE;AAED;;;;GAIG;AACH,qBAAa,oCAAqC,SAAQ,iBAAiB;IACzE,SAAkB,IAAI,EAAE,MAAM,CAA0C;;CAIzE;AAED;;;;GAIG;AACH,qBAAa,8BAA+B,SAAQ,iBAAiB;IACnE,SAAkB,IAAI,EAAE,MAAM,CAAoC;;CAInE;AAED;;;;;;;;;;GAUG;AACH,qBAAa,sBAAuB,SAAQ,iBAAiB;IAC3D,SAAkB,IAAI,EAAE,MAAM,CAA4B;;CAI3D;AAED;;;;;;;;;GASG;AACH,qBAAa,2BAA4B,SAAQ,iBAAiB;IAChE,SAAkB,IAAI,EAAE,MAAM,CAAiC;gBACnD,KAAK,CAAC,EAAE,OAAO;CAS5B;AAED;;;;GAIG;AACH,qBAAa,+BAAgC,SAAQ,iBAAiB;IACpE,SAAkB,IAAI,EAAE,MAAM,CAAqC;;CAIpE"}

package/dist/cjs/errors.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * Privacy-safe error classes for @shroud-fi/agent-runtime.
+ *
+ * Invariants (mirrored from @shroud-fi/scanning + @shroud-fi/payments):
+ *   - No 32-byte hex (key material) in any message.
+ *   - No ephemeral pubkey bytes in any message.
+ *   - No raw signature bytes in any message.
+ *   - No transfer amounts in any message.
+ *   - Messages carry short, structured reasons only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegistrationRequiresWalletError = exports.AutoRegistrationFailedError = exports.AlreadyRegisteredError = exports.RelayerNotAvailableForETHError = exports.EthRelayerContractNotConfiguredError = exports.EthRelayerEndpointRequiredError = exports.RelayerContractNotConfiguredError = exports.BrowserWalletSignatureRejectedError = exports.MissingBrowserWalletError = exports.AgentAlreadyStartedError = exports.AgentNotStartedError = exports.AgentRuntimeError = void 0;
+class AgentRuntimeError extends Error {
+    name = 'AgentRuntimeError';
+    constructor(message) {
+        super(message);
+    }
+}
+exports.AgentRuntimeError = AgentRuntimeError;
+class AgentNotStartedError extends AgentRuntimeError {
+    name = 'AgentNotStartedError';
+    constructor() {
+        super('Agent has not been started — call start() first');
+    }
+}
+exports.AgentNotStartedError = AgentNotStartedError;
+class AgentAlreadyStartedError extends AgentRuntimeError {
+    name = 'AgentAlreadyStartedError';
+    constructor() {
+        super('Agent already started — call stop() before start() again');
+    }
+}
+exports.AgentAlreadyStartedError = AgentAlreadyStartedError;
+class MissingBrowserWalletError extends AgentRuntimeError {
+    name = 'MissingBrowserWalletError';
+    constructor() {
+        super('Browser wallet adapter missing required signMessage or address');
+    }
+}
+exports.MissingBrowserWalletError = MissingBrowserWalletError;
+class BrowserWalletSignatureRejectedError extends AgentRuntimeError {
+    name = 'BrowserWalletSignatureRejectedError';
+    constructor() {
+        super('Browser wallet rejected signature request');
+    }
+}
+exports.BrowserWalletSignatureRejectedError = BrowserWalletSignatureRejectedError;
+/**
+ * Thrown when `sweepViaRelayer` is called but no relayer contract has been
+ * registered for the agent's chain. Callers can pass an explicit
+ * `relayerContract` to override the lookup.
+ */
+class RelayerContractNotConfiguredError extends AgentRuntimeError {
+    name = 'RelayerContractNotConfiguredError';
+    constructor() {
+        super('Relayer contract not configured for this chain');
+    }
+}
+exports.RelayerContractNotConfiguredError = RelayerContractNotConfiguredError;
+/**
+ * P5.1 — thrown when the caller tries to use the ETH gasless sweep path but
+ * has not provided a `selfHostEndpoint`. ETH gasless requires a self-host
+ * relayer service that builds + broadcasts the EIP-7702 type-0x04 tx; there
+ * is no third-party fallback (Gelato's 7702 surface is wallet-shaped, not
+ * relayer-shaped).
+ */
+class EthRelayerEndpointRequiredError extends AgentRuntimeError {
+    name = 'EthRelayerEndpointRequiredError';
+    constructor() {
+        super('ETH gasless sweep requires a self-host relayer endpoint — pass relayerOptions.selfHostEndpoint');
+    }
+}
+exports.EthRelayerEndpointRequiredError = EthRelayerEndpointRequiredError;
+/**
+ * P5.1 — thrown when no ShroudFiEthRelayer contract has been registered for
+ * the agent's chain and the caller did not pass `ethRelayerContract` to
+ * override the manifest lookup.
+ */
+class EthRelayerContractNotConfiguredError extends AgentRuntimeError {
+    name = 'EthRelayerContractNotConfiguredError';
+    constructor() {
+        super('ShroudFiEthRelayer contract not configured for this chain');
+    }
+}
+exports.EthRelayerContractNotConfiguredError = EthRelayerContractNotConfiguredError;
+/**
+ * @deprecated Retained as a soft-removed export — callers updated to use
+ * EthRelayerEndpointRequiredError or the gasless ETH path directly. P5.1
+ * activated the previously-stubbed ETH-via-relayer path.
+ */
+class RelayerNotAvailableForETHError extends AgentRuntimeError {
+    name = 'RelayerNotAvailableForETHError';
+    constructor() {
+        super('Relayer sweep does not support ETH — use direct sweep or ERC-20');
+    }
+}
+exports.RelayerNotAvailableForETHError = RelayerNotAvailableForETHError;
+/**
+ * M3 — thrown when `register()` is called but the agent's registrant wallet
+ * already has a non-empty stealth meta-address on file in the canonical
+ * ERC-6538 registry for scheme 1. Callers should treat this as benign and
+ * skip the registration tx; `ensureRegistered` does this automatically.
+ *
+ * Privacy: the registrant wallet address is NOT placed in `.message` — it
+ * would link the agent's runtime wallet to the error log. Callers who need
+ * to display the wallet must source it from `transport.walletClient.account`
+ * themselves.
+ */
+class AlreadyRegisteredError extends AgentRuntimeError {
+    name = 'AlreadyRegisteredError';
+    constructor() {
+        super('Agent is already registered in the ERC-6538 registry');
+    }
+}
+exports.AlreadyRegisteredError = AlreadyRegisteredError;
+/**
+ * M3 — wraps an underlying error thrown while `ensureRegistered` runs inside
+ * `agent.sendToWallet` with `autoRegister: true`. Preserves the original via
+ * the standard `cause` chain so callers can introspect without parsing
+ * strings.
+ *
+ * Privacy: the inner error MUST itself comply with the runtime's no-amount /
+ * no-wallet / no-key rule. This wrapper never inlines key, signature, or
+ * amount material into its own message.
+ */
+class AutoRegistrationFailedError extends AgentRuntimeError {
+    name = 'AutoRegistrationFailedError';
+    constructor(cause) {
+        super('Auto-registration failed');
+        // Use the standard ES2022 `cause` slot. Avoid serializing the inner
+        // error into the message itself — the privacy invariant tests would
+        // catch a leak if the wrapped error embedded sensitive bytes.
+        if (cause !== undefined) {
+            this.cause = cause;
+        }
+    }
+}
+exports.AutoRegistrationFailedError = AutoRegistrationFailedError;
+/**
+ * M3 — thrown when `register()` is invoked on a transport that has no
+ * `walletClient` (or no account on the walletClient). Registration is a state
+ * change tx that needs a signer; read-only transports cannot register.
+ */
+class RegistrationRequiresWalletError extends AgentRuntimeError {
+    name = 'RegistrationRequiresWalletError';
+    constructor() {
+        super('Registration requires a walletClient with an account');
+    }
+}
+exports.RegistrationRequiresWalletError = RegistrationRequiresWalletError;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAEH,MAAa,iBAAkB,SAAQ,KAAK;IACxB,IAAI,GAAW,mBAAmB,CAAC;IACrD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AALD,8CAKC;AAED,MAAa,oBAAqB,SAAQ,iBAAiB;IACvC,IAAI,GAAW,sBAAsB,CAAC;IACxD;QACE,KAAK,CAAC,iDAAiD,CAAC,CAAC;IAC3D,CAAC;CACF;AALD,oDAKC;AAED,MAAa,wBAAyB,SAAQ,iBAAiB;IAC3C,IAAI,GAAW,0BAA0B,CAAC;IAC5D;QACE,KAAK,CAAC,0DAA0D,CAAC,CAAC;IACpE,CAAC;CACF;AALD,4DAKC;AAED,MAAa,yBAA0B,SAAQ,iBAAiB;IAC5C,IAAI,GAAW,2BAA2B,CAAC;IAC7D;QACE,KAAK,CAAC,gEAAgE,CAAC,CAAC;IAC1E,CAAC;CACF;AALD,8DAKC;AAED,MAAa,mCAAoC,SAAQ,iBAAiB;IACtD,IAAI,GAAW,qCAAqC,CAAC;IACvE;QACE,KAAK,CAAC,2CAA2C,CAAC,CAAC;IACrD,CAAC;CACF;AALD,kFAKC;AAED;;;;GAIG;AACH,MAAa,iCAAkC,SAAQ,iBAAiB;IACpD,IAAI,GAAW,mCAAmC,CAAC;IACrE;QACE,KAAK,CAAC,gDAAgD,CAAC,CAAC;IAC1D,CAAC;CACF;AALD,8EAKC;AAED;;;;;;GAMG;AACH,MAAa,+BAAgC,SAAQ,iBAAiB;IAClD,IAAI,GAAW,iCAAiC,CAAC;IACnE;QACE,KAAK,CACH,gGAAgG,CACjG,CAAC;IACJ,CAAC;CACF;AAPD,0EAOC;AAED;;;;GAIG;AACH,MAAa,oCAAqC,SAAQ,iBAAiB;IACvD,IAAI,GAAW,sCAAsC,CAAC;IACxE;QACE,KAAK,CAAC,2DAA2D,CAAC,CAAC;IACrE,CAAC;CACF;AALD,oFAKC;AAED;;;;GAIG;AACH,MAAa,8BAA+B,SAAQ,iBAAiB;IACjD,IAAI,GAAW,gCAAgC,CAAC;IAClE;QACE,KAAK,CAAC,iEAAiE,CAAC,CAAC;IAC3E,CAAC;CACF;AALD,wEAKC;AAED;;;;;;;;;;GAUG;AACH,MAAa,sBAAuB,SAAQ,iBAAiB;IACzC,IAAI,GAAW,wBAAwB,CAAC;IAC1D;QACE,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAChE,CAAC;CACF;AALD,wDAKC;AAED;;;;;;;;;GASG;AACH,MAAa,2BAA4B,SAAQ,iBAAiB;IAC9C,IAAI,GAAW,6BAA6B,CAAC;IAC/D,YAAY,KAAe;QACzB,KAAK,CAAC,0BAA0B,CAAC,CAAC;QAClC,oEAAoE;QACpE,oEAAoE;QACpE,8DAA8D;QAC9D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACvB,IAA4B,CAAC,KAAK,GAAG,KAAK,CAAC;QAC9C,CAAC;IACH,CAAC;CACF;AAXD,kEAWC;AAED;;;;GAIG;AACH,MAAa,+BAAgC,SAAQ,iBAAiB;IAClD,IAAI,GAAW,iCAAiC,CAAC;IACnE;QACE,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAChE,CAAC;CACF;AALD,0EAKC"}

package/dist/cjs/factory.d.ts

@@ -0,0 +1,19 @@
+/**
+ * createShroudAgent — server / Node entry point.
+ *
+ * Validates configuration, resolves the stealth contract address from the
+ * transport's chain, builds an AgentIdentity from the optional master seed,
+ * and constructs a ShroudAgent.
+ *
+ * Privacy: no seed or key bytes ever appear in error messages. Validation
+ * errors are short structured reasons only.
+ */
+import { ShroudAgent } from './agent.js';
+import type { ShroudAgentConfig } from './types.js';
+/**
+ * Build a fully-wired ShroudAgent from a config.
+ *
+ * @throws AgentRuntimeError on missing/invalid transport or negative startBlock.
+ */
+export declare function createShroudAgent(config: ShroudAgentConfig): ShroudAgent;
+//# sourceMappingURL=factory.d.ts.map

package/dist/cjs/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CA2BxE"}

package/dist/cjs/factory.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * createShroudAgent — server / Node entry point.
+ *
+ * Validates configuration, resolves the stealth contract address from the
+ * transport's chain, builds an AgentIdentity from the optional master seed,
+ * and constructs a ShroudAgent.
+ *
+ * Privacy: no seed or key bytes ever appear in error messages. Validation
+ * errors are short structured reasons only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createShroudAgent = createShroudAgent;
+const core_1 = require("@shroud-fi/core");
+const transport_1 = require("@shroud-fi/transport");
+const agent_js_1 = require("./agent.js");
+const errors_js_1 = require("./errors.js");
+/**
+ * Build a fully-wired ShroudAgent from a config.
+ *
+ * @throws AgentRuntimeError on missing/invalid transport or negative startBlock.
+ */
+function createShroudAgent(config) {
+    if (config.transport === undefined || config.transport.publicClient === undefined) {
+        throw new errors_js_1.AgentRuntimeError('transport.publicClient is required');
+    }
+    if (config.startBlock < 0n) {
+        throw new errors_js_1.AgentRuntimeError('startBlock must be non-negative');
+    }
+    const chainId = config.transport.chain.id;
+    const stealthContract = config.stealthContract ?? (0, transport_1.getShroudFiStealth)(chainId);
+    const identity = (0, core_1.createAgentIdentity)(config.masterSeed);
+    const opts = {
+        identity,
+        transport: config.transport,
+        stealthContract,
+        startBlock: config.startBlock,
+        ...(config.finality !== undefined ? { finality: config.finality } : {}),
+        ...(config.announcer !== undefined ? { announcer: config.announcer } : {}),
+        ...(config.autoRegister !== undefined
+            ? { autoRegister: config.autoRegister }
+            : {}),
+    };
+    return new agent_js_1.ShroudAgent(opts);
+}
+//# sourceMappingURL=factory.js.map

package/dist/cjs/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/factory.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AAcH,8CA2BC;AAvCD,0CAAsD;AACtD,oDAA0D;AAC1D,yCAAyC;AAEzC,2CAAgD;AAGhD;;;;GAIG;AACH,SAAgB,iBAAiB,CAAC,MAAyB;IACzD,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QAClF,MAAM,IAAI,6BAAiB,CAAC,oCAAoC,CAAC,CAAC;IACpE,CAAC;IACD,IAAI,MAAM,CAAC,UAAU,GAAG,EAAE,EAAE,CAAC;QAC3B,MAAM,IAAI,6BAAiB,CAAC,iCAAiC,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;IAC1C,MAAM,eAAe,GACnB,MAAM,CAAC,eAAe,IAAI,IAAA,8BAAkB,EAAC,OAAO,CAAC,CAAC;IAExD,MAAM,QAAQ,GAAG,IAAA,0BAAmB,EAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAExD,MAAM,IAAI,GAA+B;QACvC,QAAQ;QACR,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,eAAe;QACf,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,GAAG,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1E,GAAG,CAAC,MAAM,CAAC,YAAY,KAAK,SAAS;YACnC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE;YACvC,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;IAEF,OAAO,IAAI,sBAAW,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC"}

package/dist/cjs/index.d.ts

@@ -0,0 +1,6 @@
+export { ShroudAgent } from './agent.js';
+export { createShroudAgent } from './factory.js';
+export { createShroudAgentFromBrowserWallet, BROWSER_KEY_MESSAGE, HKDF_BROWSER_SALT, HKDF_BROWSER_INFO, } from './browser.js';
+export type { ShroudAgentConfig, ShroudAgentStartOptions, BrowserWalletAdapter, AgentSweepResult, AgentRelayerSweepOptions, AgentRelayerSweepResult, AgentRelayerEthSweepOptions, AgentRelayerEthSweepResult, } from './types.js';
+export { AgentRuntimeError, AgentNotStartedError, AgentAlreadyStartedError, MissingBrowserWalletError, BrowserWalletSignatureRejectedError, RelayerNotAvailableForETHError, RelayerContractNotConfiguredError, EthRelayerEndpointRequiredError, EthRelayerContractNotConfiguredError, AlreadyRegisteredError, AutoRegistrationFailedError, RegistrationRequiresWalletError, } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,kCAAkC,EAClC,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,EACxB,uBAAuB,EACvB,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,EACzB,mCAAmC,EACnC,8BAA8B,EAC9B,iCAAiC,EACjC,+BAA+B,EAC/B,oCAAoC,EACpC,sBAAsB,EACtB,2BAA2B,EAC3B,+BAA+B,GAChC,MAAM,aAAa,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,37 @@
+"use strict";
+// Public surface — @shroud-fi/agent-runtime
+//
+// Phase 4: ergonomic wrapper around @shroud-fi/core + @shroud-fi/payments +
+// @shroud-fi/scanning + @shroud-fi/transport. Two construction paths:
+//   - createShroudAgent(config) — server / Node / AI agent (deterministic seed)
+//   - createShroudAgentFromBrowserWallet(args) — browser (MetaMask-derived seed)
+//
+// Re-exports trimmed to what callers actually need; deeper helpers stay
+// inside the upstream packages.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegistrationRequiresWalletError = exports.AutoRegistrationFailedError = exports.AlreadyRegisteredError = exports.EthRelayerContractNotConfiguredError = exports.EthRelayerEndpointRequiredError = exports.RelayerContractNotConfiguredError = exports.RelayerNotAvailableForETHError = exports.BrowserWalletSignatureRejectedError = exports.MissingBrowserWalletError = exports.AgentAlreadyStartedError = exports.AgentNotStartedError = exports.AgentRuntimeError = exports.HKDF_BROWSER_INFO = exports.HKDF_BROWSER_SALT = exports.BROWSER_KEY_MESSAGE = exports.createShroudAgentFromBrowserWallet = exports.createShroudAgent = exports.ShroudAgent = void 0;
+// Class + factories
+var agent_js_1 = require("./agent.js");
+Object.defineProperty(exports, "ShroudAgent", { enumerable: true, get: function () { return agent_js_1.ShroudAgent; } });
+var factory_js_1 = require("./factory.js");
+Object.defineProperty(exports, "createShroudAgent", { enumerable: true, get: function () { return factory_js_1.createShroudAgent; } });
+var browser_js_1 = require("./browser.js");
+Object.defineProperty(exports, "createShroudAgentFromBrowserWallet", { enumerable: true, get: function () { return browser_js_1.createShroudAgentFromBrowserWallet; } });
+Object.defineProperty(exports, "BROWSER_KEY_MESSAGE", { enumerable: true, get: function () { return browser_js_1.BROWSER_KEY_MESSAGE; } });
+Object.defineProperty(exports, "HKDF_BROWSER_SALT", { enumerable: true, get: function () { return browser_js_1.HKDF_BROWSER_SALT; } });
+Object.defineProperty(exports, "HKDF_BROWSER_INFO", { enumerable: true, get: function () { return browser_js_1.HKDF_BROWSER_INFO; } });
+// Errors
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "AgentRuntimeError", { enumerable: true, get: function () { return errors_js_1.AgentRuntimeError; } });
+Object.defineProperty(exports, "AgentNotStartedError", { enumerable: true, get: function () { return errors_js_1.AgentNotStartedError; } });
+Object.defineProperty(exports, "AgentAlreadyStartedError", { enumerable: true, get: function () { return errors_js_1.AgentAlreadyStartedError; } });
+Object.defineProperty(exports, "MissingBrowserWalletError", { enumerable: true, get: function () { return errors_js_1.MissingBrowserWalletError; } });
+Object.defineProperty(exports, "BrowserWalletSignatureRejectedError", { enumerable: true, get: function () { return errors_js_1.BrowserWalletSignatureRejectedError; } });
+Object.defineProperty(exports, "RelayerNotAvailableForETHError", { enumerable: true, get: function () { return errors_js_1.RelayerNotAvailableForETHError; } });
+Object.defineProperty(exports, "RelayerContractNotConfiguredError", { enumerable: true, get: function () { return errors_js_1.RelayerContractNotConfiguredError; } });
+Object.defineProperty(exports, "EthRelayerEndpointRequiredError", { enumerable: true, get: function () { return errors_js_1.EthRelayerEndpointRequiredError; } });
+Object.defineProperty(exports, "EthRelayerContractNotConfiguredError", { enumerable: true, get: function () { return errors_js_1.EthRelayerContractNotConfiguredError; } });
+Object.defineProperty(exports, "AlreadyRegisteredError", { enumerable: true, get: function () { return errors_js_1.AlreadyRegisteredError; } });
+Object.defineProperty(exports, "AutoRegistrationFailedError", { enumerable: true, get: function () { return errors_js_1.AutoRegistrationFailedError; } });
+Object.defineProperty(exports, "RegistrationRequiresWalletError", { enumerable: true, get: function () { return errors_js_1.RegistrationRequiresWalletError; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA,4CAA4C;AAC5C,EAAE;AACF,4EAA4E;AAC5E,sEAAsE;AACtE,gFAAgF;AAChF,iFAAiF;AACjF,EAAE;AACF,wEAAwE;AACxE,gCAAgC;;;AAEhC,oBAAoB;AACpB,uCAAyC;AAAhC,uGAAA,WAAW,OAAA;AACpB,2CAAiD;AAAxC,+GAAA,iBAAiB,OAAA;AAC1B,2CAKsB;AAJpB,gIAAA,kCAAkC,OAAA;AAClC,iHAAA,mBAAmB,OAAA;AACnB,+GAAA,iBAAiB,OAAA;AACjB,+GAAA,iBAAiB,OAAA;AAenB,SAAS;AACT,yCAaqB;AAZnB,8GAAA,iBAAiB,OAAA;AACjB,iHAAA,oBAAoB,OAAA;AACpB,qHAAA,wBAAwB,OAAA;AACxB,sHAAA,yBAAyB,OAAA;AACzB,gIAAA,mCAAmC,OAAA;AACnC,2HAAA,8BAA8B,OAAA;AAC9B,8HAAA,iCAAiC,OAAA;AACjC,4HAAA,+BAA+B,OAAA;AAC/B,iIAAA,oCAAoC,OAAA;AACpC,mHAAA,sBAAsB,OAAA;AACtB,wHAAA,2BAA2B,OAAA;AAC3B,4HAAA,+BAA+B,OAAA"}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}