@agirails/sdk 3.5.3 → 4.0.0-beta.0

package/dist/level1/Agent.d.ts

@@ -214,6 +214,13 @@ export declare class Agent extends EventEmitter {
      * Registered services
      */
     private services;
+    /**
+     * Hash-keyed mirror of `services`, populated alongside it in `provide()`.
+     * Key: `keccak256(toUtf8Bytes(name)).toLowerCase()`. Lookups match
+     * on-chain `tx.serviceHash` directly so BlockchainRuntime-sourced jobs
+     * route without depending on string `serviceDescription`. PRD §5.4.
+     */
+    private handlersByHash;
     /**
      * Active jobs
      *
@@ -261,6 +268,12 @@ export declare class Agent extends EventEmitter {
      * Polling interval ID (for job polling)
      */
     private pollingIntervalId?;
+    /**
+     * Cleanup function returned by `BlockchainRuntime.subscribeProviderJobs`,
+     * set by `subscribeIfBlockchain()` and cleared by `unsubscribe()`. Undefined
+     * means no live subscription. PRD §5.3.
+     */
+    private jobSubscriptionCleanup?;
     /**
      * Logger instance
      */
@@ -288,15 +301,32 @@ export declare class Agent extends EventEmitter {
     /**
      * Pause the agent
      *
-     * Stops accepting new jobs but keeps active jobs running.
+     * Stops accepting new jobs but keeps active jobs running. PRD §5.3:
+     * pause() now tears down the on-chain subscription as well — a paused
+     * agent must not silently keep dispatching jobs via the live event path.
+     * Behavior change from 3.5.3 (was a silent bug); see CHANGELOG /
+     * MIGRATION-4.0 bullet 4 for drain-on-pause migration guidance.
      */
     pause(): void;
     /**
      * Resume the agent
      *
-     * Resumes accepting new jobs after being paused.
+     * Resumes accepting new jobs after being paused. PRD §5.3: re-establishes
+     * the on-chain subscription that pause() tore down.
      */
     resume(): void;
+    /**
+     * Subscribe to live TransactionCreated events when the underlying runtime
+     * supports it (currently `BlockchainRuntime` only — `MockRuntime` providers
+     * receive jobs through polling). Idempotent: if a subscription is already
+     * active, this is a logged noop so a second `start()` on an already-running
+     * agent doesn't leak event listeners. PRD §5.3.
+     */
+    private subscribeIfBlockchain;
+    /**
+     * Tear down a live subscription if one is active. Idempotent. PRD §5.3.
+     */
+    private unsubscribe;
     /**
      * Restart the agent
      */
@@ -416,19 +446,43 @@ export declare class Agent extends EventEmitter {
      * the appropriate service handler.
      */
     private pollForJobs;
+    /**
+     * Shared per-transaction acceptance pipeline. Reached from two sources:
+     *   - `pollForJobs` — bounded sweep over INITIATED transactions
+     *   - `subscribeIfBlockchain` — live `TransactionCreated` events
+     *
+     * Atomic in single-threaded JS via `processingLocks` (Set). The lock
+     * release is in a `finally` so any error/throw — handler dispatch
+     * failure, linkEscrow revert, malformed payload — does not permanently
+     * occupy the slot. Poison TXs become re-tryable on the next sweep.
+     *
+     * Errors are emitted to consumers but never propagated; the caller loop
+     * must not be killed by a single bad TX. PRD §5.3.
+     */
+    private handleIncomingTransaction;
     /**
      * Find service handler for a transaction
      *
      *Security: Use exact field matching instead of substring search
      * to prevent service routing spoofing attacks.
      *
-     * Supports multiple formats (in priority order):
-     * 1. JSON: {"service":"name","input":...} - new structured format
-     * 2. Legacy: "service:name;input:..." - backward compatibility
-     * 3. Plain string exact match - simple service name
-     * 4. bytes32 hash - on-chain only (requires off-chain lookup)
+     * Dispatch order:
+     *   PRIMARY (PRD §5.4 — on-chain Layer B):
+     *     Match by `tx.serviceHash` against the `handlersByHash` map.
+     *     Skips ZeroHash (Level 0 `pay` semantics — no handler routing).
+     *   FALLBACK (preserves MockRuntime test fixtures + legacy clients):
+     *     5-step `serviceDescription` dispatch — JSON / legacy /
+     *     hash-only / string exact match.
      */
     private findServiceHandler;
+    /**
+     * Legacy string-based service dispatch — kept as a fallback for
+     * MockRuntime-style transactions where `serviceDescription` still carries
+     * the JSON / legacy / plain-name shape. PRD §5.4 routes by hash first;
+     * this method is only reached when the hash branch misses or the TX has
+     * `serviceHash === ZeroHash`.
+     */
+    private findServiceHandlerByString;
     /**
      * Check if job should be auto-accepted
      *
@@ -439,7 +493,17 @@ export declare class Agent extends EventEmitter {
      */
     private shouldAutoAccept;
     /**
-     * Create Job object from MockTransaction
+     * Create Job object from MockTransaction.
+     *
+     * `matched` is the handler entry returned by `findServiceHandler(tx)`.
+     * When supplied, `job.service` is taken from `matched.config.name` —
+     * this is the only correct source for hash-only TXs (BlockchainRuntime),
+     * where `serviceDescription` is empty and `extractServiceName(tx)` would
+     * return `'unknown'`. PRD §5.4.1.
+     *
+     * When `matched` is not supplied (e.g. shouldAutoAccept's autoAccept
+     * callback path before this commit, MockRuntime-only test fixtures),
+     * fall back to the legacy `extractServiceName` so behavior is unchanged.
      */
     private createJobFromTransaction;
     /**

package/dist/level1/Agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../src/level1/Agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../src/level1/Agent.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAKtC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAEhF,OAAO,EAAE,GAAG,EAAE,UAAU,EAAc,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAQ5D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;AAE9F;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACnD;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;OAEG;IACH,MAAM,CAAC,EAAE,aAAa,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;IAEjD;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAE9D;;OAEG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,EAAE;QACT;;WAEG;QACH,UAAU,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;QAElE;;WAEG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;QAErB;;WAEG;QACH,KAAK,CAAC,EAAE;YACN,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,KAAK,CAAC,EAAE,MAAM,CAAC;YACf,OAAO,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;SACpC,CAAC;KACH,CAAC;IAEF;;OAEG;IACH,WAAW,CAAC,EAAE;QACZ,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IAEF;;OAEG;IACH,OAAO,CAAC,EAAE;QACR,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;KAC7C,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,KAAM,SAAQ,YAAY;IACrC;;OAEG;IACH,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,SAAgB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErC;;OAEG;IACH,SAAgB,OAAO,EAAE,aAAa,CAAC;IAEvC;;OAEG;IACH,OAAO,CAAC,OAAO,CAAuB;IAEtC;;OAEG;IACH,OAAO,CAAC,OAAO,CAAC,CAAa;IAC7B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB,CAAC,CAAuB;IAErD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAqE;IACrF;;;;;OAKG;IACH,OAAO,CAAC,cAAc,CAAqE;IAE3F;;;;;OAKG;IACH,OAAO,CAAC,UAAU,CAAmC;IAErD;;;;;;OAMG;IACH,OAAO,CAAC,aAAa,CAAwC;IAE7D;;;;;;;OAOG;IACH,OAAO,CAAC,eAAe,CAAqB;IAE5C;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB,CAAa;IAEzC;;OAEG;IACH,OAAO,CAAC,MAAM,CAQZ;IAEF;;OAEG;IACH,OAAO,CAAC,QAAQ,CAKd;IAEF;;OAEG;IACH,OAAO,CAAC,MAAM,CAAc;IAE5B;;OAEG;IACH,OAAO,CAAC,iBAAiB,CAAC,CAAiB;IAC3C;;;;OAIG;IACH,OAAO,CAAC,sBAAsB,CAAC,CAAa;IAE5C;;OAEG;IACH,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;OAIG;gBACS,MAAM,EAAE,WAAW;IAiD/B;;;;;;OAMG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoD5B;;;;OAIG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B;;;;;;;;OAQG;IACH,KAAK,IAAI,IAAI;IAWb;;;;;OAKG;IACH,MAAM,IAAI,IAAI;IAsBd;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;IAyB7B;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CACL,eAAe,EAAE,MAAM,GAAG,aAAa,EACvC,OAAO,EAAE,UAAU,EACnB,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAC/B,IAAI;IAqCP;;;;;;OAMG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;IAwBhG;;OAEG;IACH,IAAI,MAAM,IAAI,WAAW,CAExB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,EAAE,CAE3B;IAED;;;;;OAKG;IACH,IAAI,IAAI,IAAI,GAAG,EAAE,CAEhB;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,UAAU,CAEtB;IAED;;;;;;OAMG;IACH,IAAI,OAAO,IAAI,YAAY,CAG1B;IAED;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC;IA0D9C;;OAEG;IACH,IAAI,MAAM,IAAI,UAAU,GAAG,SAAS,CAEnC;IAED;;;;;;;;OAQG;IACH,uBAAuB,CAAC,YAAY,EAAE,oBAAoB,GAAG,IAAI;IAQjE;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAQ5B;;OAEG;IACH,OAAO,CAAC,YAAY;IAapB;;OAEG;IACH,OAAO,CAAC,WAAW;IAOnB;;;;;;;;;;;;;OAaG;YACW,WAAW;IAsCzB;;;;;;;;;;;;OAYG;YACW,yBAAyB;IA6FvC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,kBAAkB;IAe1B;;;;;;OAMG;IACH,OAAO,CAAC,0BAA0B;IA2DlC;;;;;;;OAOG;YACW,gBAAgB;IA0L9B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,wBAAwB;IAehC;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB;IA6B1B;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IA4BvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAK7B;;;;;OAKG;YACW,UAAU;IA6HxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAsDxB;;OAEG;YACW,iBAAiB;YAejB,eAAe;YAsBf,aAAa;CAmC5B"}

package/dist/level1/Agent.js

@@ -83,6 +83,13 @@ class Agent extends events_1.EventEmitter {
          * Registered services
          */
         this.services = new Map();
+        /**
+         * Hash-keyed mirror of `services`, populated alongside it in `provide()`.
+         * Key: `keccak256(toUtf8Bytes(name)).toLowerCase()`. Lookups match
+         * on-chain `tx.serviceHash` directly so BlockchainRuntime-sourced jobs
+         * route without depending on string `serviceDescription`. PRD §5.4.
+         */
+        this.handlersByHash = new Map();
         /**
          * Active jobs
          *
@@ -173,6 +180,15 @@ class Agent extends events_1.EventEmitter {
      * @throws {AgentLifecycleError} If agent is not in idle or stopped state
      */
     async start() {
+        // PRD §5.3: idempotent start. Calling start() on a running or paused
+        // agent is a logged noop instead of a thrown AgentLifecycleError. This
+        // is a behavior change from 3.5.3 — see CHANGELOG / MIGRATION-4.0.
+        if (this._status === 'running' || this._status === 'paused') {
+            this.logger.warn('Agent.start() called on already-started agent — noop', {
+                status: this._status,
+            });
+            return;
+        }
         if (this._status !== 'idle' && this._status !== 'stopped') {
             throw new errors_1.AgentLifecycleError(this._status, 'start');
         }
@@ -195,10 +211,16 @@ class Agent extends events_1.EventEmitter {
                 rpcUrl,
             });
             this.startPolling();
+            this.subscribeIfBlockchain();
             this._status = 'running';
             this.emit('started');
         }
         catch (error) {
+            // PRD §5.3: a partial start (e.g. polling started, subscription threw,
+            // or ACTPClient.create rejected) must not leak the polling timer or
+            // a live subscription. Clean both before propagating.
+            this.stopPolling();
+            this.unsubscribe();
             this._status = 'stopped';
             this.emit('error', error);
             throw error;
@@ -215,8 +237,9 @@ class Agent extends events_1.EventEmitter {
         }
         this._status = 'stopping';
         this.emit('stopping');
-        // Stop polling
+        // Stop polling + tear down subscription. PRD §5.3.
         this.stopPolling();
+        this.unsubscribe();
         // Wait for active jobs to complete (with timeout)
         await this.waitForActiveJobs(30000); // 30s timeout
         this._status = 'stopped';
@@ -226,29 +249,85 @@ class Agent extends events_1.EventEmitter {
     /**
      * Pause the agent
      *
-     * Stops accepting new jobs but keeps active jobs running.
+     * Stops accepting new jobs but keeps active jobs running. PRD §5.3:
+     * pause() now tears down the on-chain subscription as well — a paused
+     * agent must not silently keep dispatching jobs via the live event path.
+     * Behavior change from 3.5.3 (was a silent bug); see CHANGELOG /
+     * MIGRATION-4.0 bullet 4 for drain-on-pause migration guidance.
      */
     pause() {
         if (this._status !== 'running') {
             throw new errors_1.AgentLifecycleError(this._status, 'pause');
         }
         this.stopPolling();
+        this.unsubscribe();
         this._status = 'paused';
         this.emit('paused');
     }
     /**
      * Resume the agent
      *
-     * Resumes accepting new jobs after being paused.
+     * Resumes accepting new jobs after being paused. PRD §5.3: re-establishes
+     * the on-chain subscription that pause() tore down.
      */
     resume() {
         if (this._status !== 'paused') {
             throw new errors_1.AgentLifecycleError(this._status, 'resume');
         }
-        this.startPolling();
+        // PRD §5.3.1: same partial-failure shape as start() — if subscription
+        // wiring throws after the polling timer is armed, tear both down before
+        // propagating so the agent doesn't leak a live timer while still in
+        // 'paused' status. Without this, the next resume() call would short-
+        // circuit on the state check and the orphaned timer would survive.
+        try {
+            this.startPolling();
+            this.subscribeIfBlockchain();
+        }
+        catch (err) {
+            this.stopPolling();
+            this.unsubscribe();
+            throw err;
+        }
         this._status = 'running';
         this.emit('resumed');
     }
+    /**
+     * Subscribe to live TransactionCreated events when the underlying runtime
+     * supports it (currently `BlockchainRuntime` only — `MockRuntime` providers
+     * receive jobs through polling). Idempotent: if a subscription is already
+     * active, this is a logged noop so a second `start()` on an already-running
+     * agent doesn't leak event listeners. PRD §5.3.
+     */
+    subscribeIfBlockchain() {
+        if (this.jobSubscriptionCleanup) {
+            this.logger.warn('Agent: subscription already active, refusing to double-subscribe');
+            return;
+        }
+        const runtime = this._client?.runtime;
+        if (!runtime || typeof runtime.subscribeProviderJobs !== 'function') {
+            return;
+        }
+        this.jobSubscriptionCleanup = runtime.subscribeProviderJobs(this.address, (tx) => {
+            this.handleIncomingTransaction(tx).catch((err) => this.emit('error', err));
+        });
+        this.logger.info('Subscribed to on-chain TransactionCreated events', {
+            provider: this.address,
+        });
+    }
+    /**
+     * Tear down a live subscription if one is active. Idempotent. PRD §5.3.
+     */
+    unsubscribe() {
+        if (this.jobSubscriptionCleanup) {
+            try {
+                this.jobSubscriptionCleanup();
+            }
+            catch (err) {
+                this.logger.warn('Subscription cleanup threw — continuing', { err });
+            }
+            this.jobSubscriptionCleanup = undefined;
+        }
+    }
     /**
      * Restart the agent
      */
@@ -300,7 +379,13 @@ class Agent extends events_1.EventEmitter {
         if (this.services.has(config.name)) {
             throw new errors_1.ServiceConfigError('name', `Service "${config.name}" already registered`);
         }
+        // PRD §5.4: derive the on-chain routing key alongside the string key.
+        // Same formula used by `actp request --service <name>` (see PRD §A.1 +
+        // AgentRegistry.computeServiceTypeHash), so BlockchainRuntime jobs match
+        // the same handler that MockRuntime tests register.
+        const hashKey = ethers_1.ethers.keccak256(ethers_1.ethers.toUtf8Bytes(config.name)).toLowerCase();
         this.services.set(config.name, { config, handler });
+        this.handlersByHash.set(hashKey, { config, handler });
         this.emit('service:registered', config.name);
         this.logger.info('Service registered', { service: config.name });
         return this;
@@ -506,101 +591,18 @@ class Agent extends events_1.EventEmitter {
         }
         try {
             // Security: Use filtered query instead of getAllTransactions
-            // This prevents DoS via memory exhaustion by only fetching relevant transactions
-            let pendingJobs = [];
-            // Check if runtime has the filtered query method
-            if ('getTransactionsByProvider' in this._client.runtime) {
-                // Use optimized filtered query (max 100 jobs per poll)
-                pendingJobs = await this._client.runtime.getTransactionsByProvider(this.address, 'INITIATED', 100);
-            }
-            else {
-                // Fallback to getAllTransactions (for older runtime versions)
-                const allTransactions = await this._client.runtime.getAllTransactions();
-                pendingJobs = allTransactions.filter((tx) => tx.provider === this.address && tx.state === 'INITIATED');
-            }
+            // This prevents DoS via memory exhaustion by only fetching relevant transactions.
+            // PRD §5.1: getTransactionsByProvider is now required on IACTPRuntime —
+            // the prior duck-type fallback to getAllTransactions is gone.
+            const pendingJobs = await this._client.runtime.getTransactionsByProvider(this.address, 'INITIATED', 100);
             this.logger.debug('Polling for jobs', {
                 pendingJobs: pendingJobs.length,
             });
-            // Process each pending job
+            // Process each pending job through the shared acceptance pipeline so
+            // poll and subscription paths converge on identical semantics
+            // (dedup, provider check, routing, auto-accept, linkEscrow, emit).
             for (const tx of pendingJobs) {
-                try {
-                    // Security: Check processingLocks first (atomic check)
-                    // This prevents race conditions where two poll cycles both try to process
-                    // the same job before either transitions the state
-                    if (this.processingLocks.has(tx.id) || this.processedJobs.has(tx.id)) {
-                        continue;
-                    }
-                    // IMMEDIATELY acquire lock (atomic in single-threaded JS)
-                    this.processingLocks.add(tx.id);
-                    // Security: Check if already in active jobs (LRUCache handles size limit)
-                    if (this.activeJobs.has(tx.id)) {
-                        this.processingLocks.delete(tx.id);
-                        continue;
-                    }
-                    // Security: Verify this agent is authorized to accept this transaction
-                    // Check that tx.provider matches our address (prevents unauthorized state transitions)
-                    if (tx.provider !== this.address) {
-                        this.logger.warn('Unauthorized transaction detected', {
-                            txId: tx.id,
-                            expectedProvider: this.address,
-                            actualProvider: tx.provider,
-                        });
-                        this.processingLocks.delete(tx.id);
-                        continue;
-                    }
-                    // Find matching service handler
-                    const serviceHandler = this.findServiceHandler(tx);
-                    if (!serviceHandler) {
-                        // No handler registered for this service type
-                        this.logger.debug('No handler for transaction', { txId: tx.id });
-                        this.processingLocks.delete(tx.id);
-                        continue;
-                    }
-                    // Check auto-accept behavior
-                    const shouldAccept = await this.shouldAutoAccept(tx);
-                    if (!shouldAccept) {
-                        this.logger.debug('Auto-accept declined', { txId: tx.id });
-                        this.processingLocks.delete(tx.id);
-                        continue;
-                    }
-                    // Create Job object from transaction
-                    const job = this.createJobFromTransaction(tx);
-                    // Security: Add to active jobs (LRUCache prevents unbounded growth)
-                    this.activeJobs.set(job.id, job);
-                    // Link escrow immediately to transition out of INITIATED state
-                    // This prevents polling from picking up this job again
-                    try {
-                        if (this._client && tx.state === 'INITIATED') {
-                            await this._client.runtime.linkEscrow(tx.id, tx.amount);
-                        }
-                        // Successfully processed - mark as processed and release lock
-                        this.processedJobs.set(job.id, true);
-                    }
-                    catch (escrowError) {
-                        // If linking escrow fails, remove from active jobs and release lock (allow retry)
-                        this.activeJobs.delete(job.id);
-                        this.logger.error('Failed to link escrow', { txId: tx.id }, escrowError);
-                        this.processingLocks.delete(tx.id);
-                        continue;
-                    }
-                    finally {
-                        // Always release the lock
-                        this.processingLocks.delete(tx.id);
-                    }
-                    this._stats.jobsReceived++;
-                    this.emit('job:received', job);
-                    this.logger.info('Job accepted', { jobId: job.id, service: job.service });
-                    // Process the job asynchronously (don't await here to continue polling)
-                    this.processJob(job, serviceHandler.handler).catch((error) => {
-                        this.logger.error('Job processing failed', { jobId: job.id }, error);
-                        this.emit('error', error);
-                    });
-                }
-                catch (error) {
-                    // Log error but continue processing other jobs
-                    this.logger.error('Error processing pending job', { txId: tx.id }, error);
-                    this.emit('error', error);
-                }
+                await this.handleIncomingTransaction(tx);
             }
             // Update cached balance (non-blocking, don't await)
             this.getBalanceAsync().catch(() => {
@@ -613,19 +615,137 @@ class Agent extends events_1.EventEmitter {
             this.emit('error', error);
         }
     }
+    /**
+     * Shared per-transaction acceptance pipeline. Reached from two sources:
+     *   - `pollForJobs` — bounded sweep over INITIATED transactions
+     *   - `subscribeIfBlockchain` — live `TransactionCreated` events
+     *
+     * Atomic in single-threaded JS via `processingLocks` (Set). The lock
+     * release is in a `finally` so any error/throw — handler dispatch
+     * failure, linkEscrow revert, malformed payload — does not permanently
+     * occupy the slot. Poison TXs become re-tryable on the next sweep.
+     *
+     * Errors are emitted to consumers but never propagated; the caller loop
+     * must not be killed by a single bad TX. PRD §5.3.
+     */
+    async handleIncomingTransaction(tx) {
+        // PRD §5.3.1: lifecycle status guard. Async polls and queued subscription
+        // callbacks can race with pause() / stop(). Drop the TX rather than
+        // accepting a new job into a paused or terminating agent.
+        //
+        // 'starting' is allowed: the subscription is wired inside start() before
+        // _status flips to 'running', and a fast on-chain event could fire in
+        // that window — dropping it would lose work.
+        if (this._status !== 'running' &&
+            this._status !== 'starting') {
+            this.logger.debug('Agent not accepting jobs, dropping incoming tx', {
+                txId: tx.id,
+                status: this._status,
+            });
+            return;
+        }
+        // Security: check dedup before acquiring the lock so a TX that finished
+        // on a prior pass returns immediately without disturbing state.
+        if (this.processingLocks.has(tx.id) || this.processedJobs.has(tx.id))
+            return;
+        if (this.activeJobs.has(tx.id))
+            return;
+        // Acquire lock (atomic in single-threaded JS). Released in finally below.
+        this.processingLocks.add(tx.id);
+        try {
+            // Authorization: TX provider must match this agent. Case-insensitive
+            // (PRD §5.3 carry-forward from §5.1 review): EventMonitor + runtime
+            // already normalize, but checksummed and lowercase forms can both
+            // reach here legitimately.
+            if (tx.provider.toLowerCase() !== this.address.toLowerCase()) {
+                this.logger.warn('Unauthorized transaction detected', {
+                    txId: tx.id,
+                    expectedProvider: this.address,
+                    actualProvider: tx.provider,
+                });
+                return;
+            }
+            // Routing (PRD §5.4): hash-first, string fallback.
+            const serviceHandler = this.findServiceHandler(tx);
+            if (!serviceHandler) {
+                this.logger.debug('No handler for transaction', { txId: tx.id });
+                return;
+            }
+            // Auto-accept evaluation. PRD §5.4.1: thread the matched handler so
+            // every Job built inside filter/pricing/autoAccept paths carries the
+            // correct service name.
+            const shouldAccept = await this.shouldAutoAccept(tx, serviceHandler);
+            if (!shouldAccept) {
+                this.logger.debug('Auto-accept declined', { txId: tx.id });
+                return;
+            }
+            // Build Job using the matched handler so hash-only TXs carry the
+            // registered service name. PRD §5.4.1.
+            const job = this.createJobFromTransaction(tx, serviceHandler);
+            this.activeJobs.set(job.id, job);
+            // Link escrow immediately to transition out of INITIATED state.
+            // This prevents the next poll / event from picking up this job again.
+            try {
+                if (this._client && tx.state === 'INITIATED') {
+                    await this._client.runtime.linkEscrow(tx.id, tx.amount);
+                }
+                this.processedJobs.set(job.id, true);
+            }
+            catch (escrowError) {
+                this.activeJobs.delete(job.id);
+                this.logger.error('Failed to link escrow', { txId: tx.id }, escrowError);
+                return;
+            }
+            this._stats.jobsReceived++;
+            this.emit('job:received', job);
+            this.logger.info('Job accepted', { jobId: job.id, service: job.service });
+            // Process the job asynchronously (don't await — handler runs out-of-band).
+            this.processJob(job, serviceHandler.handler).catch((error) => {
+                this.logger.error('Job processing failed', { jobId: job.id }, error);
+                this.emit('error', error);
+            });
+        }
+        catch (error) {
+            this.logger.error('Error processing pending job', { txId: tx.id }, error);
+            this.emit('error', error);
+        }
+        finally {
+            this.processingLocks.delete(tx.id);
+        }
+    }
     /**
      * Find service handler for a transaction
      *
      *Security: Use exact field matching instead of substring search
      * to prevent service routing spoofing attacks.
      *
-     * Supports multiple formats (in priority order):
-     * 1. JSON: {"service":"name","input":...} - new structured format
-     * 2. Legacy: "service:name;input:..." - backward compatibility
-     * 3. Plain string exact match - simple service name
-     * 4. bytes32 hash - on-chain only (requires off-chain lookup)
+     * Dispatch order:
+     *   PRIMARY (PRD §5.4 — on-chain Layer B):
+     *     Match by `tx.serviceHash` against the `handlersByHash` map.
+     *     Skips ZeroHash (Level 0 `pay` semantics — no handler routing).
+     *   FALLBACK (preserves MockRuntime test fixtures + legacy clients):
+     *     5-step `serviceDescription` dispatch — JSON / legacy /
+     *     hash-only / string exact match.
      */
     findServiceHandler(tx) {
+        // PRIMARY: on-chain hash routing (PRD §5.4).
+        const hash = typeof tx?.serviceHash === 'string' ? tx.serviceHash.toLowerCase() : undefined;
+        if (hash && hash !== ethers_1.ethers.ZeroHash.toLowerCase()) {
+            const byHash = this.handlersByHash.get(hash);
+            if (byHash)
+                return byHash;
+        }
+        // FALLBACK: existing 5-step string dispatch.
+        return this.findServiceHandlerByString(tx);
+    }
+    /**
+     * Legacy string-based service dispatch — kept as a fallback for
+     * MockRuntime-style transactions where `serviceDescription` still carries
+     * the JSON / legacy / plain-name shape. PRD §5.4 routes by hash first;
+     * this method is only reached when the hash branch misses or the TX has
+     * `serviceHash === ZeroHash`.
+     */
+    findServiceHandlerByString(tx) {
         const serviceDesc = tx.serviceDescription;
         if (!serviceDesc) {
             return undefined;
@@ -683,9 +803,11 @@ class Agent extends events_1.EventEmitter {
      * - Evaluates pricing strategy if configured
      * - Only accepts jobs that meet pricing requirements
      */
-    async shouldAutoAccept(tx) {
-        // Get the service config for this transaction
-        const serviceHandler = this.findServiceHandler(tx);
+    async shouldAutoAccept(tx, matched) {
+        // PRD §5.4.1: prefer the matched handler supplied by the caller so the
+        // hash-routed `config.name` flows into every internal Job object built
+        // below. Re-derive only when caller didn't pass it.
+        const serviceHandler = matched ?? this.findServiceHandler(tx);
         // Check service-level filters first (budget constraints)
         if (serviceHandler?.config.filter) {
             const filter = serviceHandler.config.filter;
@@ -712,7 +834,7 @@ class Agent extends events_1.EventEmitter {
                 }
                 // Check custom filter function
                 if (filter.custom && typeof filter.custom === 'function') {
-                    const job = this.createJobFromTransaction(tx);
+                    const job = this.createJobFromTransaction(tx, serviceHandler);
                     const customResult = await filter.custom(job);
                     if (!customResult) {
                         this.logger.debug('Job rejected: custom filter declined', { txId: tx.id });
@@ -722,7 +844,7 @@ class Agent extends events_1.EventEmitter {
             }
             // If filter is a function (legacy support)
             else if (typeof filter === 'function') {
-                const job = this.createJobFromTransaction(tx);
+                const job = this.createJobFromTransaction(tx, serviceHandler);
                 const filterResult = filter(job);
                 if (!filterResult) {
                     this.logger.debug('Job rejected: filter function declined', { txId: tx.id });
@@ -733,7 +855,7 @@ class Agent extends events_1.EventEmitter {
         // MVP: Check pricing strategy if configured
         if (serviceHandler?.config.pricing) {
             const { calculatePrice } = await Promise.resolve().then(() => __importStar(require('./pricing/PriceCalculator')));
-            const job = this.createJobFromTransaction(tx);
+            const job = this.createJobFromTransaction(tx, serviceHandler);
             try {
                 const calculation = calculatePrice(serviceHandler.config.pricing, job);
                 this.logger.debug('Pricing calculation', {
@@ -838,18 +960,28 @@ class Agent extends events_1.EventEmitter {
         }
         // It's a function - evaluate it
         if (typeof autoAccept === 'function') {
-            const job = this.createJobFromTransaction(tx);
+            const job = this.createJobFromTransaction(tx, serviceHandler);
             return await autoAccept(job);
         }
         return false;
     }
     /**
-     * Create Job object from MockTransaction
+     * Create Job object from MockTransaction.
+     *
+     * `matched` is the handler entry returned by `findServiceHandler(tx)`.
+     * When supplied, `job.service` is taken from `matched.config.name` —
+     * this is the only correct source for hash-only TXs (BlockchainRuntime),
+     * where `serviceDescription` is empty and `extractServiceName(tx)` would
+     * return `'unknown'`. PRD §5.4.1.
+     *
+     * When `matched` is not supplied (e.g. shouldAutoAccept's autoAccept
+     * callback path before this commit, MockRuntime-only test fixtures),
+     * fall back to the legacy `extractServiceName` so behavior is unchanged.
      */
-    createJobFromTransaction(tx) {
+    createJobFromTransaction(tx, matched) {
         return {
             id: tx.id,
-            service: this.extractServiceName(tx),
+            service: matched?.config.name ?? this.extractServiceName(tx),
             input: this.extractJobInput(tx),
             budget: this.convertAmountToNumber(tx.amount),
             deadline: new Date(tx.deadline * 1000), // Convert unix timestamp to Date