@pushchain/core 6.0.26 → 6.0.27-alpha.0

package/src/lib/agentic/reads/rules.js

@@ -0,0 +1,286 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readActiveRules = readActiveRules;
+exports.chainFromHash = chainFromHash;
+exports.selectRuleForSend = selectRuleForSend;
+exports.decodeActiveRule = decodeActiveRule;
+exports.readNativeSpend = readNativeSpend;
+exports.readUniversalSpend = readUniversalSpend;
+exports.listRules = listRules;
+exports.getRule = getRule;
+const svm_1 = require("./svm");
+const prc20_metadata_1 = require("../contracts/prc20-metadata");
+const viem_1 = require("viem");
+const enums_1 = require("../../constants/enums");
+const capabilities_1 = require("../capabilities");
+const ids_1 = require("../codec/ids");
+const native_1 = require("../codec/native");
+const defaults_1 = require("../codec/defaults");
+const public_rule_1 = require("../public-rule");
+const errors_1 = require("../errors");
+const prc20_metadata_2 = require("../contracts/prc20-metadata");
+const rules_1 = require("../codec/rules");
+const errors_2 = require("../errors");
+const MODE_UNIVERSAL = 0;
+const MODE_NATIVE = 1;
+/** Enabled rule IDs with their agent and governed chain, all at one block. */
+async function readActiveRules(snap, gen, wallet) {
+    const ids = await snap.read(gen.addresses.sessionEngine, gen.contracts.abis.engine, 'getPermissionIDs', [wallet]);
+    return Promise.all(ids.map((id) => readActiveRule(snap, gen, wallet, id)));
+}
+async function readActiveRule(snap, gen, wallet, rulesId) {
+    const [agent, actionIds] = await Promise.all([
+        snap.read(wallet, gen.contracts.abis.wallet, 'agentOf', [rulesId]),
+        snap.read(gen.addresses.sessionEngine, gen.contracts.abis.engine, 'getEnabledActions', [wallet, rulesId]),
+    ]);
+    if (actionIds.length === 0) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INCONSISTENT_READ, `enabled rule ${rulesId} has no enabled actions`);
+    }
+    const modes = await Promise.all(actionIds.map((a) => snap.read(gen.addresses.rulesPolicy, gen.contracts.abis.policy, 'getMode', [(0, ids_1.configId)(wallet, rulesId, a), wallet])));
+    const first = modes[0];
+    if (!modes.every((m) => m.initialized &&
+        m.chainHash === first.chainHash &&
+        m.mode === first.mode)) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INCONSISTENT_READ, `rule ${rulesId} has uninitialized or mixed-chain policy configs`);
+    }
+    return {
+        rulesId,
+        agent: (0, viem_1.getAddress)(agent),
+        actionIds,
+        mode: Number(first.mode),
+        vm: Number(first.vm),
+        chainHash: first.chainHash,
+    };
+}
+/** Map a stored chain hash back to its CAIP-2 string from known chains. */
+function chainFromHash(hash, pushChainNamespace) {
+    const known = [pushChainNamespace, ...Object.values(enums_1.CHAIN)];
+    return known.find((c) => (0, rules_1.chainHash)(c) === hash);
+}
+/**
+ * Agent-door rule selection for one send (spec 2.a): enabled rules whose agent
+ * is the signer and whose chain is the destination, read uncached at one
+ * block. Expiry, caps and policy remain on-chain checks.
+ */
+async function selectRuleForSend(snap, gen, wallet, agent, destinationChain) {
+    const active = await readActiveRules(snap, gen, wallet);
+    const want = (0, rules_1.chainHash)(destinationChain);
+    const matches = active.filter((r) => r.agent === (0, viem_1.getAddress)(agent) && r.chainHash === want);
+    if (matches.length === 0) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.NO_RULES_FOR_CHAIN, `no enabled rule on ${wallet} names ${agent} for ${destinationChain}`, {
+            details: {
+                wallet,
+                agent,
+                destinationChain,
+                blockNumber: snap.blockNumber,
+            },
+        });
+    }
+    if (matches.length > 1) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.AMBIGUOUS_RULE, `${matches.length} enabled rules on ${wallet} name ${agent} for ${destinationChain}`, {
+            hint: 'Multiple enabled rules match this agent and chain. Inspect details.rulesIds and ask the owner to resolve the overlap; no transaction was submitted.',
+            details: { rulesIds: matches.map((m) => m.rulesId) },
+        });
+    }
+    return matches[0];
+}
+/** Decode one active rule into the public record. */
+async function decodeActiveRule(snap, gen, wallet, rule, pushChainNamespace) {
+    if (rule.mode === MODE_UNIVERSAL) {
+        if (rule.vm === 1) {
+            (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.UNIVERSAL_SVM_RULES);
+            const stored = await (0, svm_1.readSvmConfig)(snap, gen, wallet, rule, pushChainNamespace);
+            const cfg = stored.config;
+            const gas = await (0, prc20_metadata_1.readGasPrc20)(snap, stored.chainNamespace);
+            const assets = await Promise.all(cfg.assets.map(async (a) => ({
+                token: (0, viem_1.getAddress)(a.token) === gas
+                    ? viem_1.zeroAddress
+                    : await (0, prc20_metadata_1.readSvmSourceToken)(snap, a.token, stored.chainNamespace, gen.network),
+                maxPerCall: a.maxPerCall,
+                maxTotal: a.maxTotal,
+            })));
+            return {
+                rulesId: rule.rulesId,
+                enabled: true,
+                agent: rule.agent,
+                chainNamespace: stored.chainNamespace,
+                validUntil: Number(cfg.validUntil),
+                spent: {
+                    kind: 'universal',
+                    assets: assets.map((a, i) => ({
+                        token: a.token,
+                        spent: cfg.assets[i].spent,
+                    })),
+                },
+                rule: {
+                    format: 'decoded',
+                    agent: rule.agent,
+                    chainNamespace: stored.chainNamespace,
+                    validUntil: Number(cfg.validUntil),
+                    expectedCEA: cfg.expectedCEA,
+                    gatewayProgram: cfg.gatewayProgram,
+                    maxGasPerCall: cfg.maxGasPerCall,
+                    assets,
+                    ceaAccounts: cfg.ceaAccounts,
+                    programs: cfg.programs,
+                    pins: cfg.pins,
+                    dataPins: cfg.dataPins,
+                },
+            };
+        }
+        if (rule.vm !== 0)
+            throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.RULE_READ_FAILED, 'unknown universal VM');
+        (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.UNIVERSAL_EVM_RULES);
+        const chain = chainFromHash(rule.chainHash, pushChainNamespace);
+        if (!chain || !chain.startsWith('eip155:'))
+            throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.RULE_READ_FAILED, 'unknown EVM rule chain');
+        const cfg = await snap.read(gen.addresses.rulesPolicy, gen.contracts.abis.policy, 'getConfig', [(0, ids_1.configId)(wallet, rule.rulesId, rule.actionIds[0]), wallet]);
+        if (!cfg.initialized)
+            throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INCONSISTENT_READ, 'uninitialized universal rule');
+        if (!cfg.assets.length ||
+            cfg.assets.length > 8 ||
+            !cfg.allowedCalls.length ||
+            cfg.allowedCalls.length > 32 ||
+            cfg.expectedCEA === viem_1.zeroAddress)
+            throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INCONSISTENT_READ, 'invalid stored universal rule shape');
+        const tokens = await Promise.all(cfg.assets.map((a) => (0, prc20_metadata_2.readOriginToken)(snap, a.token, chain)));
+        return {
+            rulesId: rule.rulesId,
+            enabled: true,
+            chainNamespace: chain,
+            agent: rule.agent,
+            validUntil: Number(cfg.validUntil),
+            spent: {
+                kind: 'universal',
+                assets: tokens.map((token, i) => ({
+                    token,
+                    spent: cfg.assets[i].spent,
+                })),
+            },
+            rule: {
+                agent: rule.agent,
+                chainNamespace: chain,
+                validUntil: Number(cfg.validUntil),
+                maxGasPerCall: cfg.maxGasPerCall,
+                assets: cfg.assets.map((a, i) => ({
+                    token: tokens[i],
+                    maxPerCall: a.maxPerCall,
+                    maxTotal: a.maxTotal,
+                })),
+                allowedCalls: cfg.allowedCalls.map((c) => ({
+                    target: c.target,
+                    selector: c.selector,
+                    maxValue: c.maxValue,
+                    pins: c.hasBeneficiary
+                        ? [{ arg: storedArg(c.beneficiaryOffset), expected: public_rule_1.WALLET }]
+                        : [],
+                })),
+            },
+        };
+    }
+    if (rule.mode !== MODE_NATIVE) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.RULE_READ_FAILED, `rule ${rule.rulesId} has unknown mode ${rule.mode}`);
+    }
+    // One stored config per action, read at the same block, in engine order.
+    const configs = await Promise.all(rule.actionIds.map((action) => snap.read(gen.addresses.rulesPolicy, gen.contracts.abis.policy, 'getNativeConfig', [(0, ids_1.configId)(wallet, rule.rulesId, action), wallet])));
+    if (configs.some((c) => !c.initialized)) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INCONSISTENT_READ, `native config for ${rule.rulesId} is not initialized`);
+    }
+    const decoded = (0, native_1.nativeActionTermsToRule)(configs, rule.agent);
+    if (configs.some((c) => c.maxValueTotal !== defaults_1.UINT256_MAX ||
+        Number(c.maxCalls) !== 0 ||
+        (c.amount.enabled && c.amount.maxTotal !== defaults_1.UINT256_MAX) ||
+        Number(c.validUntil) !== decoded.validUntil)) {
+        throw (0, errors_1.capabilityUnavailable)('nativeRuleRead', 'stored lifetime limits or differing action expiries cannot be represented by section-6 rules without losing constraints');
+    }
+    const allowedCalls = configs.map((c) => ({
+        target: (0, viem_1.getAddress)(c.target),
+        selector: c.selector === '0xffffffff' ? 'value-only' : c.selector,
+        maxValue: c.maxValuePerCall,
+        pins: [
+            ...c.pins.map((p) => ({
+                arg: storedArg(p.offset),
+                expected: p.expected.toLowerCase() ===
+                    `0x${wallet.slice(2).toLowerCase().padStart(64, '0')}`
+                    ? public_rule_1.WALLET
+                    : p.expected,
+            })),
+            ...(c.amount.enabled
+                ? [{ arg: storedArg(c.amount.offset), max: c.amount.maxPerCall }]
+                : []),
+        ],
+    }));
+    const counters = configs.map((c, i) => ({
+        target: allowedCalls[i].target,
+        selector: allowedCalls[i].selector,
+        valueSpent: c.valueSpent,
+        amountSpent: c.amountSpent,
+        callsUsed: Number(c.callsUsed),
+    }));
+    if (rule.agent === (0, viem_1.getAddress)(`0x${'00'.repeat(20)}`)) {
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INCONSISTENT_READ, `enabled rule ${rule.rulesId} does not resolve to an agent`);
+    }
+    return {
+        rulesId: rule.rulesId,
+        enabled: true,
+        chainNamespace: pushChainNamespace,
+        agent: rule.agent,
+        validUntil: decoded.validUntil,
+        rule: { agent: rule.agent, validUntil: decoded.validUntil, allowedCalls },
+        spent: counters.length === 1
+            ? {
+                kind: 'native',
+                valueSpent: counters[0].valueSpent,
+                amountSpent: counters[0].amountSpent,
+                callsUsed: counters[0].callsUsed,
+            }
+            : { kind: 'native', actions: counters },
+    };
+}
+/** Native spend counters for the update assertion. */
+async function readNativeSpend(snap, gen, wallet, rule, action = rule.actionIds[0]) {
+    const id = (0, ids_1.configId)(wallet, rule.rulesId, action);
+    const cfg = await snap.read(gen.addresses.rulesPolicy, gen.contracts.abis.policy, 'getNativeConfig', [id, wallet]);
+    return {
+        configId: id,
+        valueSpent: cfg.valueSpent,
+        amountSpent: cfg.amountSpent,
+        callsUsed: Number(cfg.callsUsed),
+    };
+}
+async function readUniversalSpend(snap, gen, wallet, rule) {
+    const id = (0, ids_1.configId)(wallet, rule.rulesId, rule.actionIds[0]);
+    const fn = rule.vm === 1 ? 'getSvmConfig' : 'getConfig';
+    const cfg = await snap.read(gen.addresses.rulesPolicy, gen.contracts.abis.policy, fn, [id, wallet]);
+    if (!cfg.initialized)
+        throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.INCONSISTENT_READ, 'uninitialized universal spend config');
+    return { configId: id, expectedSpent: cfg.assets.map((a) => a.spent) };
+}
+async function listRules(snap, gen, wallet, pushChainNamespace) {
+    (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.ACTIVE_RULE_READS);
+    const active = await readActiveRules(snap, gen, wallet);
+    const records = [];
+    for (const r of active)
+        records.push(await decodeActiveRule(snap, gen, wallet, r, pushChainNamespace));
+    return records;
+}
+/**
+ * rules.get returns enabled records only. Unknown/revoked IDs are deliberately
+ * indistinguishable without historical reconstruction, which is outside v1.
+ */
+async function getRule(snap, gen, wallet, rulesId, pushChainNamespace) {
+    (0, capabilities_1.requireCapability)(gen.capabilities, capabilities_1.AgenticCapability.ACTIVE_RULE_READS);
+    const enabled = await snap.read(gen.addresses.sessionEngine, gen.contracts.abis.engine, 'isPermissionEnabled', [rulesId, wallet]);
+    if (enabled) {
+        const active = await readActiveRule(snap, gen, wallet, rulesId);
+        return decodeActiveRule(snap, gen, wallet, active, pushChainNamespace);
+    }
+    throw new errors_2.AgenticError(errors_2.AGENTIC_ERROR_CODE.RULE_NOT_FOUND, `rule ${rulesId} is not enabled on ${wallet} (unknown or revoked; v1 has no rule history)`);
+}
+/** With a raw selector, arg denotes its ABI head-word position. */
+function storedArg(offset) {
+    if (offset < 4 || (offset - 4) % 32 !== 0)
+        throw (0, errors_1.capabilityUnavailable)('argumentLayout', 'stored pin is not aligned to an ABI argument word');
+    return (offset - 4) / 32;
+}
+//# sourceMappingURL=rules.js.map

package/src/lib/agentic/reads/snapshot.d.ts

@@ -0,0 +1,28 @@
+import type { AbiEvent, Address, Log } from 'viem';
+import type { ChainReader } from '../contracts/reader';
+import { type AgenticErrorCode } from '../errors';
+/**
+ * All reads of one logical operation are pinned to a single block so dependent
+ * reads (enumerate IDs → per-ID config) observe one state. An RPC failure is
+ * surfaced as an error; it is never treated as "empty".
+ */
+export declare class Snapshot {
+    readonly reader: ChainReader;
+    readonly blockNumber: bigint;
+    private readonly failCode;
+    constructor(reader: ChainReader, blockNumber: bigint, failCode?: AgenticErrorCode);
+    static at(reader: ChainReader, failCode?: AgenticErrorCode): Promise<Snapshot>;
+    read<T>(address: Address, abi: readonly unknown[], functionName: string, args?: readonly unknown[]): Promise<T>;
+    code(address: Address): Promise<boolean>;
+}
+/** Max block span per eth_getLogs request. */
+export declare const LOG_PAGE_BLOCKS: bigint;
+/**
+ * Paginated log scan [fromBlock, toBlock] inclusive. A failed page fails the
+ * whole scan; partial results are never returned.
+ */
+export declare function scanLogs(reader: ChainReader, args: {
+    address: Address;
+    event: AbiEvent;
+    args?: Record<string, unknown>;
+}, fromBlock: bigint, toBlock: bigint, page?: bigint): Promise<Log[]>;

package/src/lib/agentic/reads/snapshot.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOG_PAGE_BLOCKS = exports.Snapshot = void 0;
+exports.scanLogs = scanLogs;
+const errors_1 = require("../errors");
+/**
+ * All reads of one logical operation are pinned to a single block so dependent
+ * reads (enumerate IDs → per-ID config) observe one state. An RPC failure is
+ * surfaced as an error; it is never treated as "empty".
+ */
+class Snapshot {
+    reader;
+    blockNumber;
+    failCode;
+    constructor(reader, blockNumber, failCode = errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED) {
+        this.reader = reader;
+        this.blockNumber = blockNumber;
+        this.failCode = failCode;
+    }
+    static async at(reader, failCode = errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED) {
+        let block;
+        try {
+            block = await reader.getBlockNumber();
+        }
+        catch (cause) {
+            throw new errors_1.AgenticError(failCode, 'could not read the current Push block number', { cause });
+        }
+        return new Snapshot(reader, block, failCode);
+    }
+    async read(address, abi, functionName, args = []) {
+        try {
+            return (await this.reader.readContract({
+                address,
+                abi,
+                functionName,
+                args,
+                blockNumber: this.blockNumber,
+            }));
+        }
+        catch (cause) {
+            throw new errors_1.AgenticError(this.failCode, `${functionName} read on ${address} failed at block ${this.blockNumber}`, {
+                cause,
+                details: { address, functionName, blockNumber: this.blockNumber },
+            });
+        }
+    }
+    async code(address) {
+        try {
+            const code = await this.reader.getCode({
+                address,
+                blockNumber: this.blockNumber,
+            });
+            return !!code && code !== '0x';
+        }
+        catch (cause) {
+            throw new errors_1.AgenticError(this.failCode, `getCode(${address}) failed`, {
+                cause,
+            });
+        }
+    }
+}
+exports.Snapshot = Snapshot;
+/** Max block span per eth_getLogs request. */
+// Donut's public RPC limits eth_getLogs ranges to a distance of 1,000 blocks.
+exports.LOG_PAGE_BLOCKS = BigInt(1_000);
+/**
+ * Paginated log scan [fromBlock, toBlock] inclusive. A failed page fails the
+ * whole scan; partial results are never returned.
+ */
+async function scanLogs(reader, args, fromBlock, toBlock, page = exports.LOG_PAGE_BLOCKS) {
+    const out = [];
+    if (fromBlock > toBlock)
+        return out;
+    for (let start = fromBlock; start <= toBlock; start += page) {
+        const end = start + page - BigInt(1) > toBlock ? toBlock : start + page - BigInt(1);
+        try {
+            out.push(...(await reader.getLogs({ ...args, fromBlock: start, toBlock: end })));
+        }
+        catch (cause) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_READ_FAILED, `log scan for ${args.event.name} failed for blocks ${start}-${end}`, { cause });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=snapshot.js.map

package/src/lib/agentic/reads/svm.d.ts

@@ -0,0 +1,17 @@
+/** Internal lossless SVM state shared by public reads and execution. */
+import type { Address, Hex } from 'viem';
+import type { AgenticGeneration } from '../deployments';
+import type { SvmConfigRead } from '../contracts/v5';
+import { type ActiveRule } from './rules';
+import type { Snapshot } from './snapshot';
+export interface SvmRuleSnapshot {
+    wallet: Address;
+    rulesId: Hex;
+    agent: Address;
+    chainNamespace: `solana:${string}`;
+    configId: Hex;
+    config: SvmConfigRead;
+    blockNumber: bigint;
+}
+export declare function readSvmRule(snap: Snapshot, gen: AgenticGeneration, wallet: Address, rulesId: Hex, pushChainNamespace: string): Promise<SvmRuleSnapshot>;
+export declare function readSvmConfig(snap: Snapshot, gen: AgenticGeneration, wallet: Address, active: ActiveRule, pushChainNamespace: string): Promise<SvmRuleSnapshot>;

package/src/lib/agentic/reads/svm.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSvmRule = readSvmRule;
+exports.readSvmConfig = readSvmConfig;
+const errors_1 = require("../errors");
+const ids_1 = require("../codec/ids");
+const v5_1 = require("../contracts/v5");
+const svm_terms_1 = require("../codec/svm-terms");
+const rules_1 = require("./rules");
+async function readSvmRule(snap, gen, wallet, rulesId, pushChainNamespace) {
+    const active = (await (0, rules_1.readActiveRules)(snap, gen, wallet)).find((r) => r.rulesId.toLowerCase() === rulesId.toLowerCase());
+    if (!active)
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.RULE_NOT_FOUND, `no enabled SVM rule ${rulesId} on ${wallet}`);
+    return readSvmConfig(snap, gen, wallet, active, pushChainNamespace);
+}
+async function readSvmConfig(snap, gen, wallet, active, pushChainNamespace) {
+    const chain = (0, rules_1.chainFromHash)(active.chainHash, pushChainNamespace);
+    const expectedAction = (0, ids_1.actionId)(gen.addresses.gateway, v5_1.SEND_OUTBOUND_SELECTOR);
+    if (active.mode !== 0 ||
+        active.vm !== 1 ||
+        !chain?.startsWith('solana:') ||
+        active.actionIds.length !== 1 ||
+        active.actionIds[0].toLowerCase() !== expectedAction.toLowerCase())
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INCONSISTENT_READ, 'rule is not a single gateway SVM action');
+    const id = (0, ids_1.configId)(wallet, active.rulesId, active.actionIds[0]);
+    const cfg = await snap.read(gen.addresses.rulesPolicy, gen.contracts.abis.policy, 'getSvmConfig', [id, wallet]);
+    try {
+        if (!cfg.initialized)
+            throw new Error('uninitialized SVM config');
+        // Stored expired rules remain readable. Grant-time validation still checks expiry.
+        (0, svm_terms_1.validateSvmTerms)(cfg, -1);
+        for (const cap of cfg.assets) {
+            if (typeof cap.spent !== 'bigint' ||
+                cap.spent < BigInt(0) ||
+                cap.spent > cap.maxTotal)
+                throw new Error('invalid stored asset counter');
+        }
+    }
+    catch (cause) {
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INCONSISTENT_READ, 'malformed stored SVM config', { cause });
+    }
+    return {
+        wallet,
+        rulesId: active.rulesId,
+        agent: active.agent,
+        chainNamespace: chain,
+        configId: id,
+        config: cfg,
+        blockNumber: snap.blockNumber,
+    };
+}
+//# sourceMappingURL=svm.js.map

package/src/lib/agentic/reads/wallets.d.ts

@@ -0,0 +1,25 @@
+import { type Address } from 'viem';
+import type { AgenticGeneration } from '../deployments';
+import type { ChainReader } from '../contracts/reader';
+import type { WalletInfo, WalletSummary } from '../agentic.types';
+import { Snapshot } from './snapshot';
+export declare function walletCount(snap: Snapshot, gen: AgenticGeneration, owner: Address): Promise<bigint>;
+/** client.agentic.derive: default index is the owner's next unused slot. */
+export declare function deriveForOwner(reader: ChainReader, gen: AgenticGeneration, owner: Address, index?: number): Promise<{
+    address: Address;
+    index: number;
+    deployed: boolean;
+}>;
+export declare function rulesCount(snap: Snapshot, gen: AgenticGeneration, wallet: Address): Promise<number>;
+/**
+ * client.agentic.list: every deployed slot plus the next undeployed slot
+ * (deployed=false, rulesCount=0), as in the spec example.
+ */
+export declare function listForOwner(reader: ChainReader, gen: AgenticGeneration, owner: Address): Promise<WalletSummary[]>;
+/** w.owner(): the owner as the wallet stores it. */
+export declare function walletOwner(reader: ChainReader, gen: AgenticGeneration, wallet: Address): Promise<Address>;
+/**
+ * w.info(). A deployed wallet is read from chain. An undeployed address is
+ * only describable when it is `signerIdentity`'s next predicted slot.
+ */
+export declare function walletInfo(reader: ChainReader, gen: AgenticGeneration, wallet: Address, signerIdentity?: Address): Promise<WalletInfo>;

package/src/lib/agentic/reads/wallets.js

@@ -0,0 +1,122 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.walletCount = walletCount;
+exports.deriveForOwner = deriveForOwner;
+exports.rulesCount = rulesCount;
+exports.listForOwner = listForOwner;
+exports.walletOwner = walletOwner;
+exports.walletInfo = walletInfo;
+const viem_1 = require("viem");
+const ids_1 = require("../codec/ids");
+const errors_1 = require("../errors");
+const snapshot_1 = require("./snapshot");
+/** Factory-predicted address for (owner, index), cross-checked against the pure mirror. */
+async function predict(snap, gen, owner, index) {
+    const [address, deployed] = await snap.read(gen.addresses.factory, gen.contracts.abis.factory, 'predictWallet', [owner, index]);
+    const mirror = (0, ids_1.deriveWallet)({
+        factory: gen.addresses.factory,
+        walletImplementation: gen.addresses.walletImplementation,
+        owner,
+        index,
+    });
+    if ((0, viem_1.getAddress)(address) !== mirror) {
+        // Derivation drift between the SDK mirror and the factory (obligation 13).
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INCONSISTENT_READ, `factory predicted ${address} for (${owner}, ${index}) but the SDK derives ${mirror}`, { details: { generation: gen.id } });
+    }
+    return { address: (0, viem_1.getAddress)(address), deployed };
+}
+async function walletCount(snap, gen, owner) {
+    return BigInt(await snap.read(gen.addresses.factory, gen.contracts.abis.factory, 'walletCount', [owner]));
+}
+/** client.agentic.derive: default index is the owner's next unused slot. */
+async function deriveForOwner(reader, gen, owner, index) {
+    const snap = await snapshot_1.Snapshot.at(reader);
+    const next = await walletCount(snap, gen, owner);
+    let target = next;
+    if (index !== undefined) {
+        if (!Number.isInteger(index) || index < 0) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, 'index must be a non-negative integer');
+        }
+        target = BigInt(index);
+        if (target > next) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INVALID_RULE, `index ${index} is beyond the owner's next unused index ${next}; the factory only predicts up to the next slot`);
+        }
+    }
+    const p = await predict(snap, gen, owner, target);
+    return { address: p.address, index: Number(target), deployed: p.deployed };
+}
+async function rulesCount(snap, gen, wallet) {
+    const ids = await snap.read(gen.addresses.sessionEngine, gen.contracts.abis.engine, 'getPermissionIDs', [wallet]);
+    return ids.length;
+}
+/**
+ * client.agentic.list: every deployed slot plus the next undeployed slot
+ * (deployed=false, rulesCount=0), as in the spec example.
+ */
+async function listForOwner(reader, gen, owner) {
+    const snap = await snapshot_1.Snapshot.at(reader);
+    const count = await walletCount(snap, gen, owner);
+    const out = [];
+    for (let i = BigInt(0); i <= count; i++) {
+        const p = await predict(snap, gen, owner, i);
+        const deployed = i < count;
+        if (deployed !== p.deployed) {
+            throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.INCONSISTENT_READ, `factory reports slot ${i} deployed=${p.deployed} but walletCount is ${count}`);
+        }
+        const label = deployed
+            ? await snap.read(p.address, gen.contracts.abis.wallet, 'label')
+            : '';
+        out.push({
+            address: p.address,
+            index: Number(i),
+            label,
+            deployed,
+            rulesCount: deployed ? await rulesCount(snap, gen, p.address) : 0,
+        });
+    }
+    return out;
+}
+/** w.owner(): the owner as the wallet stores it. */
+async function walletOwner(reader, gen, wallet) {
+    const snap = await snapshot_1.Snapshot.at(reader);
+    return (0, viem_1.getAddress)(await snap.read(wallet, gen.contracts.abis.wallet, 'owner'));
+}
+/**
+ * w.info(). A deployed wallet is read from chain. An undeployed address is
+ * only describable when it is `signerIdentity`'s next predicted slot.
+ */
+async function walletInfo(reader, gen, wallet, signerIdentity) {
+    const snap = await snapshot_1.Snapshot.at(reader);
+    const deployed = await snap.code(wallet);
+    if (!deployed) {
+        if (signerIdentity) {
+            const next = await walletCount(snap, gen, signerIdentity);
+            const p = await predict(snap, gen, signerIdentity, next);
+            if (p.address === (0, viem_1.getAddress)(wallet)) {
+                return {
+                    address: p.address,
+                    label: '',
+                    index: Number(next),
+                    owner: (0, viem_1.getAddress)(signerIdentity),
+                    deployed: false,
+                    rulesCount: 0,
+                };
+            }
+        }
+        throw new errors_1.AgenticError(errors_1.AGENTIC_ERROR_CODE.WALLET_NOT_DEPLOYED, `${wallet} is not deployed and is not the connected owner's next wallet slot`);
+    }
+    const [owner, index] = await Promise.all([
+        snap.read(wallet, gen.contracts.abis.wallet, 'owner'),
+        snap.read(gen.addresses.factory, gen.contracts.abis.factory, 'indexOf', [wallet]),
+    ]);
+    const label = await snap.read(wallet, gen.contracts.abis.wallet, 'label');
+    return {
+        address: (0, viem_1.getAddress)(wallet),
+        label,
+        index: Number(index),
+        owner: (0, viem_1.getAddress)(owner),
+        deployed: true,
+        rulesCount: await rulesCount(snap, gen, wallet),
+    };
+}
+//# sourceMappingURL=wallets.js.map

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

@@ -0,0 +1,41 @@
+import { type Address, type Hex } from 'viem';
+import { CHAIN } from '../constants/enums';
+import type { TransactionRouteType, UniversalTxResponse } from '../orchestrator/orchestrator.types';
+import type { AgenticRuntime } from './runtime';
+import type { AgenticTxMetadata } from './agentic.types';
+export interface LogicalCall {
+    to: string;
+    data: string;
+    value: bigint;
+}
+/**
+ * Present an AGW send as the wallet's own transaction: `from` is the AGW and
+ * `to`/`data`/`value` are the logical call. The signer's `origin`, hashes,
+ * nonce, gas and the on-chain `raw` fields are kept untouched; the wrapped
+ * call the signer actually sent is recorded in `agentic.rawTo/rawData`.
+ * Mutates in place so `wait()` (which reads these fields) reports the same
+ * identity on the receipt.
+ */
+export declare function adaptAgenticResponse(resp: UniversalTxResponse, meta: Omit<AgenticTxMetadata, 'rawTo' | 'rawData'> & {
+    logical: LogicalCall;
+    route?: TransactionRouteType;
+    chain?: CHAIN;
+}): UniversalTxResponse;
+/**
+ * trackTransaction replay: if the tracked Push tx called execute/executeAsAgent
+ * on a wallet of a registered, verified generation, restore the same logical
+ * identity a live send reports. Anything unrecognised is returned unchanged.
+ */
+export declare function adaptTrackedResponse(runtime: Pick<AgenticRuntime, 'reader' | 'network'>, resp: UniversalTxResponse): Promise<UniversalTxResponse>;
+/**
+ * Canonical outbound summary for both send and replay: the first actual
+ * destination call. The complete ordered calls live in agentic.destinationCalls.
+ * Identical calldata can come from explicit calls or generated transfers, so
+ * never infer the original input shape from a selector. For an unrecognized
+ * historical payload, retain the actual gateway call instead of inventing one.
+ */
+export declare function outboundResponseCall(calls: readonly {
+    to: Address;
+    value: bigint;
+    data: Hex;
+}[], fallback: LogicalCall): LogicalCall;