@pushchain/core 6.0.25 → 6.0.27-alpha.0

package/src/lib/agentic/execution/svm-send.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareSvmAgentExecution = prepareSvmAgentExecution;
+exports.sendSvmAgentWire = sendSvmAgentWire;
+const svm_quote_1 = require("./svm-quote");
+/** Prepared-wire agent execution used by the public Solana route. */
+const viem_1 = require("viem");
+const common_1 = require("../management/common");
+const snapshot_1 = require("../reads/snapshot");
+const svm_1 = require("../reads/svm");
+const svm_context_1 = require("../management/svm-context");
+const svm_outbound_1 = require("./svm-outbound");
+const svm_instruction_1 = require("./svm-instruction");
+const errors_1 = require("../errors");
+const svm_2 = require("../management/svm");
+async function prepareSvmAgentExecution(runtime, gen, input, metadata) {
+    (0, common_1.assertCanSign)(runtime, 'internal SVM send');
+    await (0, svm_2.verifySvmWallet)(runtime, gen, input.wallet);
+    const snap = await snapshot_1.Snapshot.at(runtime.reader);
+    const stored = await (0, svm_1.readSvmRule)(snap, gen, input.wallet, input.rulesId, runtime.pushChainNamespace);
+    if ((0, viem_1.getAddress)(stored.agent) !== (0, viem_1.getAddress)(runtime.signerPushAccount()))
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.NOT_OWNER_OR_AGENT, 'signer is not this SVM rule agent');
+    const chain = stored.chainNamespace;
+    const resolved = await (0, svm_context_1.resolveSvmContext)(snap, input.wallet, stored.chainNamespace, stored.config.assets, metadata);
+    if (resolved.expectedCEA.toLowerCase() !==
+        stored.config.expectedCEA.toLowerCase() ||
+        resolved.gatewayProgram.toLowerCase() !==
+            stored.config.gatewayProgram.toLowerCase() ||
+        resolved.ceaAccounts.some((a) => !stored.config.ceaAccounts.some((b) => a.toLowerCase() === b.toLowerCase())))
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'stored SVM context does not cover the wallet and every asset');
+    const instruction = (0, svm_instruction_1.resolveAgwSvmInstruction)({
+        wallet: input.wallet,
+        chain,
+        program: input.program,
+        instructionData: input.instructionData,
+        accounts: input.accounts,
+    }, stored.config);
+    const quote = await (0, svm_quote_1.quoteSvmRequest)(runtime, snap, input.wallet, (0, viem_1.getAddress)(input.token), chain, input.gasLimit, input.amount);
+    const call = (0, svm_outbound_1.buildAgwSvmAction)({
+        ...input,
+        gateway: gen.addresses.gateway,
+        recipient: instruction.recipient,
+        payload: instruction.payload,
+        gasLimit: quote.gasLimitUsed,
+        protocolFee: quote.protocolFee,
+        maxPCForGas: quote.nativeValueForGas,
+    });
+    const walletPc = await runtime.reader.getBalance({
+        address: input.wallet,
+        blockNumber: snap.blockNumber,
+    });
+    if (walletPc < call.value)
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.WALLET_BALANCE_INSUFFICIENT, 'wallet PC is below the SVM outbound quote');
+    if (input.amount > BigInt(0)) {
+        const balance = await snap.read(input.token, viem_1.erc20Abi, 'balanceOf', [input.wallet]);
+        if (balance < input.amount)
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.WALLET_BALANCE_INSUFFICIENT, 'wallet token balance is below the SVM amount');
+        const allowance = await snap.read(input.token, viem_1.erc20Abi, 'allowance', [input.wallet, gen.addresses.gateway]);
+        if (allowance < input.amount)
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.GATEWAY_ALLOWANCE_INSUFFICIENT, 'owner must establish the SVM gateway allowance separately');
+    }
+    const signerPc = await runtime.signerBalance();
+    const gasReserve = (await runtime.getGasPrice()) * BigInt(10_000_000);
+    if ((await runtime.signerAccountDeployed()) && signerPc < gasReserve)
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.AGENT_GAS_INSUFFICIENT, 'deployed SVM agent identity has no Push gas balance');
+    return {
+        stored,
+        call,
+        instruction,
+        quote,
+        data: gen.contracts.encodeExecuteAsAgent(input.rulesId, call),
+    };
+}
+async function sendSvmAgentWire(runtime, gen, input, metadata) {
+    const prepared = await prepareSvmAgentExecution(runtime, gen, input, metadata);
+    try {
+        const tx = await runtime.execute({
+            to: input.wallet,
+            value: BigInt(0),
+            data: prepared.data,
+        });
+        // Return the ordinary signer response and explicit wire context internally.
+        // The public wrapper applies the response presentation.
+        return { tx, context: prepared.stored, instruction: prepared.instruction };
+    }
+    catch (error) {
+        throw (0, common_1.wrapSendError)(error);
+    }
+}
+//# sourceMappingURL=svm-send.js.map

package/src/lib/agentic/index.d.ts

@@ -0,0 +1,5 @@
+export type { AgenticAddress, AgenticHex, AgenticDoor, AgenticNamespace, AgenticProgressHook, AgenticTxMetadata, AgenticWallet, RuleCall as AllowedCall, RuleAsset as AssetCap, Checkpoint, CheckpointKind, CreateOptions, CreateResult, ForeignChainNamespace, DecodedSolanaRule, Rule, RuleInput, Pin, Spent, WalletMarker, RulesRecord, Selector, WalletInfo, WalletSummary, } from './agentic.types';
+export { AGENTIC_ERROR_CODE, AgenticError, AgenticRevertError } from './errors';
+export type { AgenticErrorCode } from './errors';
+export { AGENTIC } from './constants';
+export type { Preset, PresetCategory, PresetAsset, PresetOptions, ReadyPresetOptions, PresetRuleTemplate, AgenticPresets, } from './presets/types';

package/src/lib/agentic/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENTIC = exports.AgenticRevertError = exports.AgenticError = exports.AGENTIC_ERROR_CODE = void 0;
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "AGENTIC_ERROR_CODE", { enumerable: true, get: function () { return errors_1.AGENTIC_ERROR_CODE; } });
+Object.defineProperty(exports, "AgenticError", { enumerable: true, get: function () { return errors_1.AgenticError; } });
+Object.defineProperty(exports, "AgenticRevertError", { enumerable: true, get: function () { return errors_1.AgenticRevertError; } });
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "AGENTIC", { enumerable: true, get: function () { return constants_1.AGENTIC; } });
+//# sourceMappingURL=index.js.map

package/src/lib/agentic/management/common.d.ts

@@ -0,0 +1,29 @@
+import { type Address, type Hex, type Log } from 'viem';
+import type { MultiCall, UniversalTxResponse } from '../../orchestrator/orchestrator.types';
+import { PROGRESS_HOOK } from '../../progress-hook/progress-hook.types';
+import type { AgenticGeneration } from '../deployments';
+import type { AgenticRuntime } from '../runtime';
+import type { AgenticProgressHook } from '../agentic.types';
+import { Snapshot } from '../reads/snapshot';
+export declare function emitAgentic(runtime: AgenticRuntime, perCall: AgenticProgressHook | undefined, id: PROGRESS_HOOK, ...args: unknown[]): void;
+export declare function assertCanSign(runtime: AgenticRuntime, operation: string): void;
+/** Owner-only management writes: the connected signer's Push identity must be the stored owner. */
+export declare function assertOwner(runtime: AgenticRuntime, gen: AgenticGeneration, wallet: Address, snap: Snapshot): Promise<Address>;
+/**
+ * Send owner calls through the signer's ordinary transaction path: one call
+ * as a plain transaction, several as the signer's batch (UEA multicall,
+ * EIP-7702 atomic batch, or the documented sequential fallback for a Push EOA
+ * without 7702 — reported through `atomic` / `transactionHashes`).
+ */
+export declare function sendOwnerCalls(runtime: AgenticRuntime, calls: MultiCall[], progressHook: AgenticProgressHook | undefined): Promise<UniversalTxResponse>;
+/**
+ * Wait for every Push transaction the operation produced and return their
+ * logs in submission order. A reverted transaction raises AgenticRevertError
+ * carrying all hashes.
+ */
+export declare function confirmedLogs(runtime: AgenticRuntime, tx: UniversalTxResponse): Promise<{
+    logs: Log[];
+    hashes: Hex[];
+}>;
+/** Normalize a send failure: keep batch hashes and decoded revert data. */
+export declare function wrapSendError(err: unknown): unknown;

package/src/lib/agentic/management/common.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitAgentic = emitAgentic;
+exports.assertCanSign = assertCanSign;
+exports.assertOwner = assertOwner;
+exports.sendOwnerCalls = sendOwnerCalls;
+exports.confirmedLogs = confirmedLogs;
+exports.wrapSendError = wrapSendError;
+const tslib_1 = require("tslib");
+const viem_1 = require("viem");
+const errors_1 = require("../../orchestrator/internals/errors");
+const progress_hook_1 = tslib_1.__importDefault(require("../../progress-hook/progress-hook"));
+const errors_2 = require("../errors");
+const revert_1 = require("../revert");
+function emitAgentic(runtime, perCall, id, ...args) {
+    runtime.emit(progress_hook_1.default[id](...args), perCall);
+}
+function assertCanSign(runtime, operation) {
+    if (runtime.isReadOnly) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.READ_ONLY, `${operation} needs a signer; this client was initialized read-only`);
+    }
+}
+/** Owner-only management writes: the connected signer's Push identity must be the stored owner. */
+async function assertOwner(runtime, gen, wallet, snap) {
+    const owner = (0, viem_1.getAddress)(await snap.read(wallet, gen.contracts.abis.wallet, 'owner'));
+    const signer = runtime.signerPushAccount();
+    if (owner !== signer) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.NOT_WALLET_OWNER, `${signer} is not the owner of ${wallet} (owner is ${owner})`, { hint: 'Rule and label writes are owner-only. Initialize with the owner signer.' });
+    }
+    return owner;
+}
+/**
+ * Send owner calls through the signer's ordinary transaction path: one call
+ * as a plain transaction, several as the signer's batch (UEA multicall,
+ * EIP-7702 atomic batch, or the documented sequential fallback for a Push EOA
+ * without 7702 — reported through `atomic` / `transactionHashes`).
+ */
+async function sendOwnerCalls(runtime, calls, progressHook) {
+    if (calls.length === 0)
+        throw new Error('sendOwnerCalls needs at least one call');
+    const options = progressHook ? { progressHook } : undefined;
+    if (calls.length === 1) {
+        return runtime.execute({ to: calls[0].to, value: calls[0].value, data: calls[0].data }, options);
+    }
+    return runtime.execute({ to: calls[0].to, value: BigInt(0), data: calls }, options);
+}
+/**
+ * Wait for every Push transaction the operation produced and return their
+ * logs in submission order. A reverted transaction raises AgenticRevertError
+ * carrying all hashes.
+ */
+async function confirmedLogs(runtime, tx) {
+    const hashes = (tx.transactionHashes ?? [tx.hash]);
+    const unavailable = (cause) => new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.RECEIPT_UNAVAILABLE, `submitted ${tx.hash} but could not read its receipt: ${cause instanceof Error ? cause.message : String(cause)}`, {
+        hint: 'The transaction may still land. Check these hashes before retrying.',
+        details: { txHash: tx.hash, transactionHashes: hashes },
+        cause,
+    });
+    let receipt;
+    try {
+        receipt = await tx.wait();
+    }
+    catch (cause) {
+        throw unavailable(cause);
+    }
+    if (hashes.length === 1) {
+        if (receipt.status !== 1) {
+            throw new errors_2.AgenticRevertError(`Push transaction ${tx.hash} reverted`, {
+                transactionHashes: hashes,
+            });
+        }
+        return { logs: receipt.logs, hashes };
+    }
+    const logs = [];
+    for (const hash of hashes) {
+        let r;
+        try {
+            r = await runtime.reader.getTransactionReceipt({ hash });
+        }
+        catch (cause) {
+            throw unavailable(cause);
+        }
+        if (r.status !== 'success') {
+            throw new errors_2.AgenticRevertError(`Push transaction ${hash} reverted`, { transactionHashes: hashes });
+        }
+        logs.push(...r.logs);
+    }
+    return { logs, hashes };
+}
+/** Normalize a send failure: keep batch hashes and decoded revert data. */
+function wrapSendError(err) {
+    if (err instanceof errors_2.AgenticError || err instanceof errors_2.AgenticRevertError)
+        return err;
+    const decoded = (0, revert_1.decodeAgenticRevert)(err);
+    if (err instanceof errors_1.PushChainBatchExecutionError) {
+        return new errors_2.AgenticRevertError(err.message, {
+            decodedError: decoded ?? err.decodedError,
+            transactionHashes: err.transactionHashes,
+            pendingTransactionHash: err.pendingTransactionHash,
+            cause: err,
+        });
+    }
+    if (decoded || err instanceof errors_1.PushChainExecutionError) {
+        const e = err;
+        return new errors_2.AgenticRevertError(e?.message ?? decoded?.name ?? 'AGW revert', {
+            decodedError: decoded ?? e?.decodedError,
+            gatewayTxHash: e?.gatewayTxHash,
+            agenticCode: decoded?.name,
+            cause: err,
+        });
+    }
+    return err;
+}
+//# sourceMappingURL=common.js.map

package/src/lib/agentic/management/create.d.ts

@@ -0,0 +1,16 @@
+import type { AgenticRuntime } from '../runtime';
+import type { InternalCreateOptions, CreateResult } from '../agentic.types';
+/**
+ * client.agentic.create(label, { rules }): deploy + grants only. Funding and
+ * approvals are separate ordinary sends. Every input is validated and every
+ * prediction re-read immediately before signing; IDs are returned from
+ * receipts in input order.
+ *
+ * Strategy follows the signer: an external owner's UEA batches atomically, a
+ * Push EOA uses an EIP-7702 batch when available and otherwise the documented
+ * sequential fallback. A sequential failure raises CREATE_PARTIAL with the
+ * deployed wallet, confirmed/pending hashes and granted IDs so the caller can
+ * finish with `wallet(w).rules.add(remaining)` — the SDK never deploys another
+ * wallet on its own.
+ */
+export declare function createWallet(runtime: AgenticRuntime, label: string, options: InternalCreateOptions): Promise<CreateResult>;

package/src/lib/agentic/management/create.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWallet = createWallet;
+const duplicates_1 = require("./duplicates");
+const viem_1 = require("viem");
+const progress_hook_types_1 = require("../../progress-hook/progress-hook.types");
+const errors_1 = require("../../orchestrator/internals/errors");
+const capabilities_1 = require("../capabilities");
+const deployments_1 = require("../deployments");
+const ids_1 = require("../codec/ids");
+const prepare_1 = require("./prepare");
+const label_1 = require("./label");
+const errors_2 = require("../errors");
+const snapshot_1 = require("../reads/snapshot");
+const wallets_1 = require("../reads/wallets");
+const common_1 = require("./common");
+/**
+ * client.agentic.create(label, { rules }): deploy + grants only. Funding and
+ * approvals are separate ordinary sends. Every input is validated and every
+ * prediction re-read immediately before signing; IDs are returned from
+ * receipts in input order.
+ *
+ * Strategy follows the signer: an external owner's UEA batches atomically, a
+ * Push EOA uses an EIP-7702 batch when available and otherwise the documented
+ * sequential fallback. A sequential failure raises CREATE_PARTIAL with the
+ * deployed wallet, confirmed/pending hashes and granted IDs so the caller can
+ * finish with `wallet(w).rules.add(remaining)` — the SDK never deploys another
+ * wallet on its own.
+ */
+async function createWallet(runtime, label, options) {
+    const hook = options?.progressHook;
+    (0, label_1.assertLabel)(label);
+    if (!options || !Array.isArray(options.rules)) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INVALID_RULE, 'options.rules is required (use [] for a bare wallet)');
+    }
+    (0, common_1.assertCanSign)(runtime, 'agentic.create');
+    const gen = (0, deployments_1.currentGeneration)(runtime.network);
+    (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.WALLET_READS);
+    await (0, deployments_1.verifyFactoryWiring)(runtime.reader, gen);
+    const owner = runtime.signerPushAccount();
+    const snap = await snapshot_1.Snapshot.at(runtime.reader);
+    const index = await (0, wallets_1.walletCount)(snap, gen, owner);
+    const [predicted, deployed] = await snap.read(gen.addresses.factory, gen.contracts.abis.factory, 'predictWallet', [owner, index]);
+    const wallet = (0, viem_1.getAddress)(predicted);
+    const mirror = (0, ids_1.deriveWallet)({
+        factory: gen.addresses.factory,
+        walletImplementation: gen.addresses.walletImplementation,
+        owner,
+        index,
+    });
+    if (wallet !== mirror || deployed || (await snap.code(wallet))) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INDEX_RACE, `next wallet slot ${index} for ${owner} is not a fresh counterfactual address`, { details: { wallet, mirror, deployed } });
+    }
+    const prepared = await (0, prepare_1.prepareWalletRules)(runtime, gen, owner, wallet, options.rules, snap);
+    (0, duplicates_1.assertNoDuplicateRules)(prepared);
+    const selfTarget = prepared.findIndex((p) => p.nativeTerms?.some((t) => t.target === wallet));
+    if (selfTarget >= 0) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INVALID_RULE, `rules[${selfTarget}].target is the wallet being created; the contracts refuse it as a native target`);
+    }
+    (0, common_1.emitAgentic)(runtime, hook, progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_101, wallet, Number(index), false);
+    // A fresh wallet's grant nonce starts at 0 and increments per grant.
+    const predictedIds = prepared.map((p, i) => (0, ids_1.rulesId)({
+        validator: gen.addresses.sessionValidator,
+        agent: p.agent,
+        grantNonce: BigInt(i),
+    }));
+    const calls = [
+        // Index-bound: reverts (nothing committed) if another creation took this slot.
+        {
+            to: gen.addresses.factory,
+            value: BigInt(0),
+            data: gen.contracts.encodeDeployWalletAt(owner, index, wallet, label),
+        },
+        ...prepared.map((p) => ({
+            to: wallet,
+            value: BigInt(0),
+            data: gen.contracts.encodeGrantRules(p.session),
+        })),
+    ];
+    const strategy = calls.length === 1
+        ? 'single'
+        : runtime.signerIsPushNative()
+            ? 'push-eoa-batch'
+            : 'uea-multicall';
+    (0, common_1.emitAgentic)(runtime, hook, progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_102, wallet, strategy);
+    let tx;
+    try {
+        tx = await (0, common_1.sendOwnerCalls)(runtime, calls, hook);
+    }
+    catch (err) {
+        const wrapped = await createFailure(runtime, gen, wallet, Number(index), owner, label, err);
+        emitFailure(runtime, hook, wrapped);
+        throw wrapped;
+    }
+    let logs;
+    try {
+        ({ logs } = await (0, common_1.confirmedLogs)(runtime, tx));
+    }
+    catch (err) {
+        const wrapped = await createFailure(runtime, gen, wallet, Number(index), owner, label, err);
+        emitFailure(runtime, hook, wrapped);
+        throw wrapped;
+    }
+    const deployedEv = gen.contracts.parseWalletDeployed(logs, gen.addresses.factory);
+    const granted = gen.contracts
+        .parseRulesGranted(logs, wallet)
+        .map((g) => g.rulesId);
+    if (deployedEv.length !== 1 ||
+        deployedEv[0].wallet !== wallet ||
+        deployedEv[0].index !== index) {
+        const err = new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INDEX_RACE, `deployWallet produced ${deployedEv.map((d) => `${d.wallet}#${d.index}`).join(', ') ||
+            'no wallet'}, expected ${wallet}#${index}; grants targeted ${wallet}`, {
+            hint: 'Another deployment by this owner raced this call. Inspect both wallets with client.agentic.list() before retrying.',
+            details: {
+                expected: wallet,
+                deployed: deployedEv,
+                grantedRulesIds: granted,
+                txHash: tx.hash,
+            },
+        });
+        emitFailure(runtime, hook, err);
+        throw err;
+    }
+    if (!sameIds(granted, predictedIds)) {
+        const err = new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.RECEIPT_MISMATCH, 'RulesGranted events do not match the requested rules in order', { details: { granted, predicted: predictedIds, txHash: tx.hash } });
+        emitFailure(runtime, hook, err);
+        throw err;
+    }
+    if (granted.length > 0)
+        (0, common_1.emitAgentic)(runtime, hook, progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_104, granted);
+    (0, common_1.emitAgentic)(runtime, hook, progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_199_01, 'create', tx.hash);
+    return {
+        wallet,
+        index: Number(index),
+        rulesIds: granted,
+        tx,
+    };
+}
+function sameIds(a, b) {
+    return (a.length === b.length &&
+        a.every((x, i) => x.toLowerCase() === b[i].toLowerCase()));
+}
+const RACE_ERRORS = new Set(['IndexMismatch', 'IntentWalletMismatch']);
+/**
+ * Turn a create failure into an exact report. What committed is derived from
+ * THIS operation's own receipts, never from a later state read; when those
+ * receipts cannot be fetched the outcome is reported as unknown so callers do
+ * not retry a creation that may have landed.
+ */
+async function createFailure(runtime, gen, wallet, index, owner, label, err) {
+    const wrapped = (0, common_1.wrapSendError)(err);
+    const batch = err instanceof errors_1.PushChainBatchExecutionError ? err : undefined;
+    const confirmed = (batch?.transactionHashes ?? []);
+    const pending = batch?.pendingTransactionHash;
+    const receiptUnavailable = wrapped instanceof errors_2.AgenticError &&
+        wrapped.code === errors_2.AGENTIC_ERROR_CODE.RECEIPT_UNAVAILABLE;
+    // The index-bound deploy reverted: another creation took the slot first and
+    // nothing from this call committed.
+    const decodedName = wrapped
+        .decodedError?.name;
+    if (confirmed.length === 0 &&
+        !pending &&
+        decodedName &&
+        RACE_ERRORS.has(decodedName)) {
+        return new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INDEX_RACE, `wallet slot ${index} (${wallet}) was taken by a concurrent creation; nothing was committed`, {
+            hint: 'Retry agentic.create; it re-reads the next slot.',
+            details: { wallet, index, committed: false },
+            cause: wrapped,
+        });
+    }
+    if (confirmed.length === 0 && !pending && !receiptUnavailable) {
+        // Some send paths flatten the factory revert to a generic execution
+        // error, losing the IndexMismatch selector. If the owner's next index has
+        // moved and immutable deployment metadata proves another label owns the
+        // predicted slot, this call could not have deployed or granted.
+        try {
+            const snap = await snapshot_1.Snapshot.at(runtime.reader);
+            const next = await (0, wallets_1.walletCount)(snap, gen, owner);
+            if (next > BigInt(index)) {
+                const competing = await (0, wallets_1.walletInfo)(runtime.reader, gen, wallet);
+                // label() is mutable in v5: only the immutable deploy event proves
+                // which creation occupied this slot. A later rename proves nothing.
+                const logs = await (0, snapshot_1.scanLogs)(runtime.reader, {
+                    address: gen.addresses.factory,
+                    event: gen.contracts.events.walletDeployed,
+                    args: { wallet },
+                }, gen.startBlock, snap.blockNumber);
+                const deployed = gen.contracts
+                    .parseWalletDeployed(logs, gen.addresses.factory)
+                    .find((entry) => entry.wallet === wallet);
+                const competingLabel = deployed?.label;
+                if (competing.deployed &&
+                    competing.index === index &&
+                    (0, viem_1.getAddress)(competing.owner) === owner &&
+                    competingLabel !== undefined &&
+                    competingLabel !== label) {
+                    return new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INDEX_RACE, 'wallet slot ' + index + ' was consumed by a concurrent deployment', {
+                        hint: 'Slot ' +
+                            index +
+                            ' belongs to "' +
+                            competingLabel +
+                            '". No wallet or rules from this create call were committed; retry agentic.create to use the next slot.',
+                        details: {
+                            wallet,
+                            index,
+                            committed: false,
+                            competingLabel,
+                        },
+                        cause: wrapped,
+                    });
+                }
+            }
+        }
+        catch {
+            // If the owner counter/event cannot be reconciled, preserve the original
+            // error; never infer that a retry is safe from an incomplete read.
+        }
+        // Nothing was confirmed (pre-broadcast failure or a reverted atomic batch).
+        return wrapped;
+    }
+    let walletDeployed = 'unknown';
+    let grantedRulesIds;
+    let recoveryError;
+    if (!receiptUnavailable) {
+        try {
+            const logs = [];
+            for (const hash of confirmed) {
+                const r = await runtime.reader.getTransactionReceipt({ hash });
+                if (r.status === 'success')
+                    logs.push(...r.logs);
+            }
+            const deployed = gen.contracts
+                .parseWalletDeployed(logs, gen.addresses.factory)
+                .some((d) => d.wallet === wallet);
+            grantedRulesIds = gen.contracts
+                .parseRulesGranted(logs, wallet)
+                .map((g) => g.rulesId);
+            // A pending hash may itself be the deployment; only a confirmed deploy is certain.
+            walletDeployed = deployed ? true : pending ? 'unknown' : false;
+        }
+        catch (e) {
+            recoveryError = e instanceof Error ? e.message : String(e);
+        }
+    }
+    const hint = walletDeployed === true
+        ? `Wallet ${wallet} is deployed. Do not call create again; once any pending hash settles, finish with client.agentic.wallet('${wallet}').rules.add(<remaining rules>).`
+        : walletDeployed === false
+            ? 'No wallet was deployed by this call; it is safe to retry.'
+            : 'The outcome is unknown. Do not retry create until the listed hashes are reconciled (client.agentic.list() shows deployed wallets).';
+    return new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.CREATE_PARTIAL, `agentic.create did not complete: ${wrapped?.message ?? String(err)}`, {
+        hint,
+        details: {
+            wallet,
+            index,
+            walletDeployed,
+            grantedRulesIds,
+            confirmedHashes: confirmed,
+            pendingHash: pending,
+            ...(receiptUnavailable
+                ? { submitted: wrapped.details }
+                : {}),
+            ...(recoveryError ? { recoveryError } : {}),
+        },
+        cause: wrapped,
+    });
+}
+function emitFailure(runtime, hook, err) {
+    const e = err;
+    (0, common_1.emitAgentic)(runtime, hook, progress_hook_types_1.PROGRESS_HOOK.AGENTIC_TX_199_02, 'create', e?.code ?? 'UNKNOWN', e?.message ?? String(err), e?.decodedError);
+}
+//# sourceMappingURL=create.js.map

package/src/lib/agentic/management/duplicates.d.ts

@@ -0,0 +1,4 @@
+import type { PreparedRule } from '../codec/rules';
+import type { ActiveRule } from '../reads/rules';
+/** SDK creation policy; existing contract overlaps still use AMBIGUOUS_RULE at send. */
+export declare function assertNoDuplicateRules(prepared: readonly PreparedRule[], existing?: readonly ActiveRule[]): void;

package/src/lib/agentic/management/duplicates.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertNoDuplicateRules = assertNoDuplicateRules;
+const viem_1 = require("viem");
+const rules_1 = require("../codec/rules");
+const errors_1 = require("../errors");
+/** SDK creation policy; existing contract overlaps still use AMBIGUOUS_RULE at send. */
+function assertNoDuplicateRules(prepared, existing = []) {
+    const keys = new Set(existing.map((r) => `${(0, viem_1.getAddress)(r.agent)}:${r.chainHash}`));
+    for (const rule of prepared) {
+        const key = `${(0, viem_1.getAddress)(rule.agent)}:${(0, rules_1.chainHash)(rule.chainNamespace)}`;
+        if (keys.has(key))
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.DUPLICATE_RULE, `an enabled rule already names ${rule.agent} for ${rule.chainNamespace}`, {
+                hint: 'Put multiple allowed calls in one rule or update the existing rule.',
+                details: { agent: rule.agent, chainNamespace: rule.chainNamespace },
+            });
+        keys.add(key);
+    }
+}
+//# sourceMappingURL=duplicates.js.map

package/src/lib/agentic/management/label.d.ts

@@ -0,0 +1,3 @@
+/** AGW MAX_LABEL_BYTES. Empty resets the default; lengths count UTF-8 bytes. */
+export declare const MAX_LABEL_BYTES = 64;
+export declare function assertLabel(label: string): void;

package/src/lib/agentic/management/label.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_LABEL_BYTES = void 0;
+exports.assertLabel = assertLabel;
+const errors_1 = require("../errors");
+/** AGW MAX_LABEL_BYTES. Empty resets the default; lengths count UTF-8 bytes. */
+exports.MAX_LABEL_BYTES = 64;
+function assertLabel(label) {
+    if (typeof label !== 'string') {
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'label must be a string');
+    }
+    const length = new TextEncoder().encode(label).length;
+    if (length > exports.MAX_LABEL_BYTES) {
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `label must be at most ${exports.MAX_LABEL_BYTES} UTF-8 bytes (received ${length})`, { details: { length, maxLength: exports.MAX_LABEL_BYTES } });
+    }
+}
+//# sourceMappingURL=label.js.map

package/src/lib/agentic/management/prepare.d.ts

@@ -0,0 +1,7 @@
+import { type Address } from 'viem';
+import { type AgenticGeneration } from '../deployments';
+import type { InternalRule } from '../agentic.types';
+import type { AgenticRuntime } from '../runtime';
+import { Snapshot } from '../reads/snapshot';
+/** Resolve wallet-dependent wire inputs without signing or mutating authority. */
+export declare function prepareWalletRules(runtime: AgenticRuntime, gen: AgenticGeneration, owner: Address, wallet: Address, inputs: readonly InternalRule[], snap: Snapshot): Promise<import("../codec/rules").PreparedRule[]>;