@agirails/sdk 2.3.1 → 2.4.0

package/README.md

@@ -436,15 +436,14 @@ npm run test:coverage
 ```typescript
 import { ServiceDirectory, request, provide } from '@agirails/sdk';
 
-// Register a service
-const directory = new ServiceDirectory();
-directory.register('text-gen', {
-  providerAddress: '0x...',
-  capabilities: ['gpt-4']
-});
-
-// Find providers
-const providers = directory.find({ capabilities: ['gpt-4'] });
+// Register a provider for a service
+const { serviceDirectory } = require('@agirails/sdk');
+// serviceDirectory is an in-memory, per-process singleton
+// Provider registers automatically when calling provide()
+
+// Find providers for a service
+const providers = serviceDirectory.findProviders('text-gen');
+// Returns string[] of provider addresses
 ```
 
 ### Level 1 - Agent Framework
@@ -456,11 +455,10 @@ import { Agent, AgentConfig } from '@agirails/sdk';
 const agent = new Agent({
   name: 'my-agent',
   network: 'testnet',
-  services: ['text-generation'],
 });
 
-// Handle jobs
-agent.onJob(async (job) => {
+// Register services via agent.provide()
+agent.provide('text-generation', async (job) => {
   return { result: `Processed: ${job.input}` };
 });
 

package/dist/ACTPClient.d.ts

@@ -11,10 +11,9 @@
  *
  * @example
  * ```typescript
- * // Create client in mock mode
+ * // Create client (auto-detects wallet from .actp/keystore.json or env vars)
  * const client = await ACTPClient.create({
  *   mode: 'mock',
- *   requesterAddress: '0x1234...',
  * });
  *
  * // Basic API - simplest approach
@@ -34,6 +33,7 @@
  * const tx = await client.advanced.getTransaction(txId);
  * ```
  */
+import { ethers } from 'ethers';
 import { IACTPRuntime } from './runtime/IACTPRuntime';
 import { BasicAdapter } from './adapters/BasicAdapter';
 import { StandardAdapter } from './adapters/StandardAdapter';
@@ -42,6 +42,42 @@ import { UnifiedPayParams, UnifiedPayResult } from './types/adapter';
 import { EASHelper, EASConfig } from './protocol/EASHelper';
 import { ReputationReporter } from './erc8004/ReputationReporter';
 import { IWalletProvider } from './wallet/IWalletProvider';
+import { SmartWalletCall } from './wallet/aa/constants';
+import { ActivationScenario } from './wallet/aa/TransactionBatcher';
+import { PendingPublish } from './config/pendingPublish';
+/**
+ * Validates that a state directory path is safe to use.
+ *
+ * SECURITY: Prevents path traversal attacks by ensuring:
+ * 1. No '..' components in the path
+ * 2. No symbolic links that could escape the intended directory
+ * 3. Path resolves to a location within home directory or current working directory
+ *
+ * @param stateDirectory - The directory path to validate
+ * @throws Error if path is unsafe
+ */
+/** On-chain agent state from AgentRegistry. */
+export interface OnChainAgentState {
+    registeredAt: bigint;
+    configHash: string;
+    listed: boolean;
+}
+/**
+ * Read the on-chain agent state from AgentRegistry.
+ * Returns registeredAt, configHash, and listed fields.
+ */
+export declare function getOnChainAgentState(provider: ethers.JsonRpcProvider, registryAddress: string, agentAddress: string): Promise<OnChainAgentState>;
+/**
+ * Detect the lazy publish activation scenario.
+ *
+ * Decision matrix:
+ * - A: Not registered + has pending → first-time activation
+ * - B1: Registered + pending hash != on-chain hash + not listed → re-publish + list
+ * - B2: Registered + pending hash != on-chain hash + already listed → re-publish only
+ * - C: Pending hash == on-chain hash → stale pending, delete it
+ * - none: No pending publish file
+ */
+export declare function detectLazyPublishScenario(onChainState: OnChainAgentState, pendingPublish: PendingPublish | null): ActivationScenario;
 /**
  * Supported modes for ACTPClient.
  *
@@ -358,6 +394,34 @@ export declare class ACTPClient {
      * @internal
      */
     private readonly walletProvider?;
+    /**
+     * Lazy Publish: Current activation scenario.
+     * Set during create(), consumed during first payACTPBatched().
+     * @internal
+     */
+    private lazyScenario;
+    /**
+     * Lazy Publish: Cached pending publish data.
+     * @internal
+     */
+    private pendingPublish;
+    /**
+     * AgentRegistry address (for lazy activation calls).
+     * @internal
+     */
+    private agentRegistryAddress?;
+    /**
+     * Network identifier (e.g. 'base-sepolia', 'base-mainnet').
+     * Used for chain-scoped pending-publish file operations.
+     * @internal
+     */
+    private networkId?;
+    /**
+     * Whether the pending publish config is stale (AGIRAILS.md changed since last publish).
+     * When true, getActivationCalls() returns empty to prevent stale config going on-chain.
+     * @internal
+     */
+    private pendingIsStale;
     /**
      * Private constructor - use ACTPClient.create() factory method.
      */
@@ -657,7 +721,7 @@ export declare class ACTPClient {
      * @example
      * ```typescript
      * // Register a custom x402 adapter
-     * client.registerAdapter(new X402Adapter(client.runtime, requesterAddress));
+     * client.registerAdapter(new X402Adapter(requesterAddress, { expectedNetwork, transferFn }));
      * ```
      */
     registerAdapter(adapter: IAdapter): void;
@@ -705,6 +769,19 @@ export declare class ACTPClient {
      * or sending custom batched transactions.
      */
     getWalletProvider(): IWalletProvider | undefined;
+    /**
+     * Get activation calls for lazy publish.
+     *
+     * Returns SmartWalletCall[] to prepend to the first payment UserOp,
+     * plus an onSuccess callback that deletes pending-publish.json.
+     *
+     * Returns empty calls if no activation is needed (scenario C/none).
+     * @internal
+     */
+    getActivationCalls(): {
+        calls: SmartWalletCall[];
+        onSuccess: () => void;
+    };
     /**
      * Non-blocking drift detection for AGIRAILS.md config.
      * Checks if local AGIRAILS.md matches on-chain config hash.

package/dist/ACTPClient.d.ts.map

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

package/dist/ACTPClient.js

@@ -12,10 +12,9 @@
  *
  * @example
  * ```typescript
- * // Create client in mock mode
+ * // Create client (auto-detects wallet from .actp/keystore.json or env vars)
  * const client = await ACTPClient.create({
  *   mode: 'mock',
- *   requesterAddress: '0x1234...',
  * });
  *
  * // Basic API - simplest approach
@@ -59,7 +58,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ACTPClient = void 0;
+exports.ACTPClient = exports.detectLazyPublishScenario = exports.getOnChainAgentState = void 0;
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const fs = __importStar(require("fs"));
@@ -76,29 +75,15 @@ const ReputationReporter_1 = require("./erc8004/ReputationReporter");
 const networks_1 = require("./config/networks");
 const EOAWalletProvider_1 = require("./wallet/EOAWalletProvider");
 const AutoWalletProvider_1 = require("./wallet/AutoWalletProvider");
+const TransactionBatcher_1 = require("./wallet/aa/TransactionBatcher");
+const pendingPublish_1 = require("./config/pendingPublish");
 const Logger_1 = require("./utils/Logger");
-// ============================================================================
-// Security: Path Validation
-// ============================================================================
-/**
- * Validates that a state directory path is safe to use.
- *
- * SECURITY: Prevents path traversal attacks by ensuring:
- * 1. No '..' components in the path
- * 2. No symbolic links that could escape the intended directory
- * 3. Path resolves to a location within home directory or current working directory
- *
- * @param stateDirectory - The directory path to validate
- * @throws Error if path is unsafe
- */
+const ZERO_HASH = '0x' + '0'.repeat(64);
 /**
- * Check if an agent is registered on AgentRegistry.
- * Lightweight read-only check — no signer needed.
- *
- * Uses minimal ABI fragment to avoid importing the full AgentRegistry class.
- * Checks registeredAt field of AgentProfile struct (> 0 means registered).
+ * Read the on-chain agent state from AgentRegistry.
+ * Returns registeredAt, configHash, and listed fields.
  */
-async function checkRegistration(provider, registryAddress, agentAddress) {
+async function getOnChainAgentState(provider, registryAddress, agentAddress) {
     const contract = new ethers_1.ethers.Contract(registryAddress, [
         'function getAgent(address agentAddress) view returns ' +
             '(tuple(address agentAddress, string did, string endpoint, bytes32[] serviceTypes, ' +
@@ -107,8 +92,42 @@ async function checkRegistration(provider, registryAddress, agentAddress) {
             'uint256 updatedAt, bool isActive, bytes32 configHash, string configCID, bool listed))',
     ], provider);
     const profile = await contract.getAgent(agentAddress);
-    return profile.registeredAt > 0n;
+    return {
+        registeredAt: profile.registeredAt,
+        configHash: profile.configHash,
+        listed: profile.listed,
+    };
+}
+exports.getOnChainAgentState = getOnChainAgentState;
+/**
+ * Detect the lazy publish activation scenario.
+ *
+ * Decision matrix:
+ * - A: Not registered + has pending → first-time activation
+ * - B1: Registered + pending hash != on-chain hash + not listed → re-publish + list
+ * - B2: Registered + pending hash != on-chain hash + already listed → re-publish only
+ * - C: Pending hash == on-chain hash → stale pending, delete it
+ * - none: No pending publish file
+ */
+function detectLazyPublishScenario(onChainState, pendingPublish) {
+    if (!pendingPublish)
+        return 'none';
+    const isRegistered = onChainState.registeredAt > 0n;
+    const pendingHash = pendingPublish.configHash;
+    const onChainHash = onChainState.configHash;
+    if (!isRegistered) {
+        // Not registered — scenario A: full activation
+        return 'A';
+    }
+    // Registered — check if pending hash differs from on-chain
+    if (pendingHash !== onChainHash) {
+        // Config differs — need to publish
+        return onChainState.listed ? 'B2' : 'B1';
+    }
+    // Hash matches — stale pending
+    return 'C';
 }
+exports.detectLazyPublishScenario = detectLazyPublishScenario;
 function validateStateDirectory(stateDirectory) {
     // Check for path traversal characters
     if (stateDirectory.includes('..')) {
@@ -224,13 +243,34 @@ class ACTPClient {
     /**
      * Private constructor - use ACTPClient.create() factory method.
      */
-    constructor(runtime, requesterAddress, info, easHelper, erc8004Bridge, reputationReporter, walletProvider, contractAddresses) {
+    constructor(runtime, requesterAddress, info, easHelper, erc8004Bridge, reputationReporter, walletProvider, contractAddresses, lazyScenario = 'none', pendingPublish = null, agentRegistryAddress, networkId) {
+        /**
+         * Lazy Publish: Current activation scenario.
+         * Set during create(), consumed during first payACTPBatched().
+         * @internal
+         */
+        this.lazyScenario = 'none';
+        /**
+         * Lazy Publish: Cached pending publish data.
+         * @internal
+         */
+        this.pendingPublish = null;
+        /**
+         * Whether the pending publish config is stale (AGIRAILS.md changed since last publish).
+         * When true, getActivationCalls() returns empty to prevent stale config going on-chain.
+         * @internal
+         */
+        this.pendingIsStale = false;
         this.runtime = runtime;
         this.info = info;
         this.easHelper = easHelper;
         this.reputationReporter = reputationReporter;
         this.walletProvider = walletProvider;
-        this.basic = new BasicAdapter_1.BasicAdapter(runtime, requesterAddress, easHelper, walletProvider, contractAddresses);
+        this.lazyScenario = lazyScenario;
+        this.pendingPublish = pendingPublish;
+        this.agentRegistryAddress = agentRegistryAddress;
+        this.networkId = networkId;
+        this.basic = new BasicAdapter_1.BasicAdapter(runtime, requesterAddress, easHelper, walletProvider, contractAddresses, this);
         this.standard = new StandardAdapter_1.StandardAdapter(runtime, requesterAddress, easHelper);
         // Initialize registry and router
         this.registry = new AdapterRegistry_1.AdapterRegistry();
@@ -284,6 +324,10 @@ class ACTPClient {
         let walletProvider;
         let requesterAddress;
         let contractAddresses;
+        let lazyScenario = 'none';
+        let lazyPending = null;
+        let registryAddr;
+        let networkId;
         // If custom runtime provided, use it directly
         if (config.runtime) {
             // Custom runtime: requesterAddress is mandatory
@@ -301,15 +345,17 @@ class ACTPClient {
             // Initialize runtime based on mode
             switch (config.mode) {
                 case 'mock': {
-                    // Mock mode: requesterAddress is mandatory
-                    if (!config.requesterAddress) {
-                        throw new Error('requesterAddress is required for mock mode');
+                    // Mock mode: requesterAddress is optional (auto-generate if missing)
+                    if (config.requesterAddress) {
+                        if (!/^0x[a-fA-F0-9]{40}$/.test(config.requesterAddress)) {
+                            throw new Error(`Invalid requesterAddress: "${config.requesterAddress}". ` +
+                                'Must be a valid Ethereum address (0x-prefixed, 40 hex chars)');
+                        }
+                        requesterAddress = config.requesterAddress;
                     }
-                    if (!/^0x[a-fA-F0-9]{40}$/.test(config.requesterAddress)) {
-                        throw new Error(`Invalid requesterAddress: "${config.requesterAddress}". ` +
-                            'Must be a valid Ethereum address (0x-prefixed, 40 hex chars)');
+                    else {
+                        requesterAddress = ethers_1.ethers.Wallet.createRandom().address;
                     }
-                    requesterAddress = config.requesterAddress;
                     // SECURITY FIX: Enhanced path validation to prevent path traversal attacks
                     if (config.stateDirectory) {
                         validateStateDirectory(config.stateDirectory);
@@ -323,12 +369,25 @@ class ACTPClient {
                 }
                 case 'testnet':
                 case 'mainnet': {
-                    // Validate required parameters for blockchain modes
+                    // Auto-detect private key from keystore / env var if not provided
                     if (!config.privateKey) {
-                        throw new Error(`privateKey is required for ${config.mode} mode`);
+                        const { resolvePrivateKey } = await Promise.resolve().then(() => __importStar(require('./wallet/keystore')));
+                        const resolved = await resolvePrivateKey(config.stateDirectory);
+                        if (resolved) {
+                            config = { ...config, privateKey: resolved };
+                        }
+                        else {
+                            throw new Error(`No wallet found for ${config.mode} mode.\n\n` +
+                                'Provide a private key via one of:\n' +
+                                '  1. ACTP_KEY_PASSWORD env var + .actp/keystore.json (recommended)\n' +
+                                '  2. ACTP_PRIVATE_KEY env var\n' +
+                                '  3. privateKey option in ACTPClient.create()\n' +
+                                '  4. Run "actp publish" to generate a wallet automatically');
+                        }
                     }
                     // Map mode to network config
                     const network = config.mode === 'testnet' ? 'base-sepolia' : 'base-mainnet';
+                    networkId = network;
                     const networkConfig = (0, networks_1.getNetwork)(network);
                     // Default RPC URL from network config if not provided
                     const rpcUrl = config.rpcUrl ?? networkConfig.rpcUrl;
@@ -338,7 +397,8 @@ class ACTPClient {
                     }
                     // Create ethers provider and signer
                     const provider = new ethers_1.ethers.JsonRpcProvider(rpcUrl);
-                    const signer = new ethers_1.ethers.Wallet(config.privateKey, provider);
+                    const privateKey = config.privateKey; // Guaranteed by auto-detect above
+                    const signer = new ethers_1.ethers.Wallet(privateKey, provider);
                     // ====================================================================
                     // AIP-12: Wallet Provider Selection
                     // ====================================================================
@@ -374,40 +434,66 @@ class ACTPClient {
                                 backupUrl: networkConfig.aa.paymasterUrls.pimlico,
                             },
                         });
-                        // Check AgentRegistry — gasless only for registered agents
+                        // Check AgentRegistry + Lazy Publish scenario
                         const smartWalletAddress = autoWallet.getAddress();
-                        const agentRegistryAddress = config.contracts?.agentRegistry
+                        registryAddr = config.contracts?.agentRegistry
                             ?? networkConfig.contracts.agentRegistry;
-                        let isRegistered = false;
-                        if (agentRegistryAddress) {
+                        // Load pending publish (may be null) — chain-scoped
+                        try {
+                            lazyPending = (0, pendingPublish_1.loadPendingPublish)(network);
+                        }
+                        catch {
+                            // Ignore file read errors
+                        }
+                        let useAutoWallet = false;
+                        if (registryAddr) {
                             try {
-                                isRegistered = await checkRegistration(provider, agentRegistryAddress, smartWalletAddress);
+                                const onChainState = await getOnChainAgentState(provider, registryAddr, smartWalletAddress);
+                                lazyScenario = detectLazyPublishScenario(onChainState, lazyPending);
+                                // Scenario C: stale pending — delete immediately
+                                if (lazyScenario === 'C') {
+                                    (0, pendingPublish_1.deletePendingPublish)(network);
+                                    lazyPending = null;
+                                    lazyScenario = 'none';
+                                }
+                                // Gate: configHash != ZERO || hasPendingPublish → use AutoWallet
+                                const hasOnChainConfig = onChainState.configHash !== ZERO_HASH;
+                                const hasPendingPublish = lazyPending !== null;
+                                if (hasOnChainConfig || hasPendingPublish) {
+                                    useAutoWallet = true;
+                                }
                             }
                             catch {
-                                // Registry check failed (e.g. RPC down) — allow AA anyway.
-                                // Rationale: don't punish legit registered agents for infra issues.
-                                // Paymaster contract allowlist + rate limits prevent abuse.
-                                isRegistered = true;
-                                Logger_1.sdkLogger.warn('AgentRegistry check failed, proceeding with AA wallet');
+                                // Registry check failed (e.g. RPC down).
+                                // Fail-open only if pending publish exists (agent did `actp publish` → legitimate intent).
+                                // Fail-closed otherwise to prevent unregistered agents getting free gas.
+                                if (lazyPending) {
+                                    useAutoWallet = true;
+                                    Logger_1.sdkLogger.warn('AgentRegistry check failed, but pending publish found — proceeding with AA.');
+                                }
+                                else {
+                                    Logger_1.sdkLogger.warn('AgentRegistry check failed and no pending publish — falling back to EOA.');
+                                }
                             }
                         }
                         else {
                             // No registry deployed — skip check (early testnet)
-                            isRegistered = true;
+                            useAutoWallet = true;
                         }
-                        if (isRegistered) {
+                        if (useAutoWallet) {
                             walletProvider = autoWallet;
                             requesterAddress = smartWalletAddress;
                         }
                         else {
-                            // Not registered — fall back to EOA with warning
-                            Logger_1.sdkLogger.warn('Agent not registered on AgentRegistry. ' +
+                            // Not published and no pending — fall back to EOA with warning
+                            Logger_1.sdkLogger.warn('Agent not published on AgentRegistry and no pending publish found. ' +
                                 'Falling back to EOA wallet (gas not sponsored). ' +
-                                'Run "actp register" for gas-free transactions.');
+                                'Run "actp publish" for gas-free transactions.');
                             walletProvider = new EOAWalletProvider_1.EOAWalletProvider(signer, networkConfig.chainId);
-                            // Force signer.address — config.requesterAddress may be the Smart Wallet
-                            // address (set by `actp init --wallet auto`), which would be wrong for EOA.
                             requesterAddress = signer.address;
+                            // Reset since we're not using auto wallet
+                            lazyScenario = 'none';
+                            lazyPending = null;
                         }
                     }
                     else {
@@ -472,8 +558,29 @@ class ACTPClient {
             stateDirectory,
             walletTier: walletProvider?.getWalletInfo().tier,
         };
-        // Pass wallet provider and contract addresses to constructor
-        const client = new ACTPClient(runtime, normalizedAddress, info, easHelper, erc8004Bridge, reputationReporter, walletProvider, contractAddresses);
+        // Staleness check: recompute hash if AGIRAILS.md exists and we have a pending publish
+        let pendingIsStale = false;
+        if (lazyPending && lazyScenario !== 'none' && lazyScenario !== 'C') {
+            try {
+                const mdPath = path.join(process.cwd(), 'AGIRAILS.md');
+                if (fs.existsSync(mdPath)) {
+                    const { computeConfigHash } = await Promise.resolve().then(() => __importStar(require('./config/agirailsmd')));
+                    const content = fs.readFileSync(mdPath, 'utf-8');
+                    const { configHash: currentHash } = computeConfigHash(content);
+                    if (currentHash !== lazyPending.configHash) {
+                        pendingIsStale = true;
+                        Logger_1.sdkLogger.warn('AGIRAILS.md changed since last publish. Activation skipped. ' +
+                            'Run "actp publish" to update.');
+                    }
+                }
+            }
+            catch {
+                // Best-effort: staleness check should not block operation
+            }
+        }
+        // Pass wallet provider, contract addresses, and lazy publish state to constructor
+        const client = new ACTPClient(runtime, normalizedAddress, info, easHelper, erc8004Bridge, reputationReporter, walletProvider, contractAddresses, lazyScenario, lazyPending, registryAddr, networkId);
+        client.pendingIsStale = pendingIsStale;
         // Drift detection: non-blocking check for AGIRAILS.md sync status
         if (config.mode !== 'mock') {
             client.checkConfigDrift(config).catch(() => {
@@ -844,7 +951,7 @@ class ACTPClient {
      * @example
      * ```typescript
      * // Register a custom x402 adapter
-     * client.registerAdapter(new X402Adapter(client.runtime, requesterAddress));
+     * client.registerAdapter(new X402Adapter(requesterAddress, { expectedNetwork, transferFn }));
      * ```
      */
     registerAdapter(adapter) {
@@ -900,6 +1007,48 @@ class ACTPClient {
     getWalletProvider() {
         return this.walletProvider;
     }
+    /**
+     * Get activation calls for lazy publish.
+     *
+     * Returns SmartWalletCall[] to prepend to the first payment UserOp,
+     * plus an onSuccess callback that deletes pending-publish.json.
+     *
+     * Returns empty calls if no activation is needed (scenario C/none).
+     * @internal
+     */
+    getActivationCalls() {
+        if (this.lazyScenario === 'none' || this.lazyScenario === 'C' || !this.agentRegistryAddress) {
+            return { calls: [], onSuccess: () => { } };
+        }
+        // Staleness check: AGIRAILS.md changed since last publish → skip activation
+        if (this.pendingIsStale) {
+            return { calls: [], onSuccess: () => { } };
+        }
+        const pending = this.pendingPublish;
+        if (!pending) {
+            return { calls: [], onSuccess: () => { } };
+        }
+        // Build activation batch params
+        const params = {
+            scenario: this.lazyScenario,
+            agentRegistryAddress: this.agentRegistryAddress,
+            cid: pending.cid,
+            configHash: pending.configHash,
+            listed: true,
+        };
+        // For scenario A, extract registration params from pending publish
+        if (this.lazyScenario === 'A') {
+            params.endpoint = pending.endpoint;
+            params.serviceDescriptors = pending.serviceDescriptors;
+        }
+        const calls = (0, TransactionBatcher_1.buildActivationBatch)(params);
+        const onSuccess = () => {
+            (0, pendingPublish_1.deletePendingPublish)(this.networkId);
+            this.lazyScenario = 'none';
+            this.pendingPublish = null;
+        };
+        return { calls, onSuccess };
+    }
     /**
      * Non-blocking drift detection for AGIRAILS.md config.
      * Checks if local AGIRAILS.md matches on-chain config hash.
@@ -913,7 +1062,14 @@ class ACTPClient {
             // Look for AGIRAILS.md in cwd
             const agirailsMdPath = join(process.cwd(), 'AGIRAILS.md');
             if (!existsSync(agirailsMdPath)) {
-                return; // No local file — nothing to check
+                // No local file — try cached hash from pending-publish.json
+                const { loadPendingPublish: loadPP } = await Promise.resolve().then(() => __importStar(require('./config/pendingPublish')));
+                const driftNetwork = config.mode === 'testnet' ? 'base-sepolia' : 'base-mainnet';
+                const pp = loadPP(driftNetwork);
+                if (pp) {
+                    Logger_1.sdkLogger.info('[AGIRAILS] No AGIRAILS.md found, using cached config hash from pending-publish.json');
+                }
+                return;
             }
             const network = config.mode === 'testnet' ? 'base-sepolia' : 'base-mainnet';
             const networkConfig = (0, networks_1.getNetwork)(network);