pyre-world-kit 3.0.0 → 3.0.2

package/dist/index.d.ts

@@ -8,15 +8,15 @@
 import { Connection } from '@solana/web3.js';
 import { ActionProvider } from './providers/action.provider';
 import { IntelProvider } from './providers/intel.provider';
-import { RegistryProvider } from './providers/registry.provider';
 import { StateProvider } from './providers/state.provider';
 import type { Action } from './types/action.types';
 import type { Intel } from './types/intel.types';
 import type { CheckpointConfig } from './types/state.types';
+import { Registry } from './types/registry.types';
 export declare class PyreKit {
     readonly actions: ActionProvider;
     readonly intel: IntelProvider;
-    readonly registry: RegistryProvider;
+    readonly registry: Registry;
     readonly state: StateProvider;
     constructor(connection: Connection, publicKey: string);
     /** Callback fired when checkpoint interval is reached */
@@ -24,11 +24,19 @@ export declare class PyreKit {
     /** Configure auto-checkpoint behavior */
     setCheckpointConfig(config: CheckpointConfig): void;
     /**
-     * Execute an action with automatic state tracking.
+     * Execute an action with deferred state tracking.
      * On first call, initializes state from chain instead of executing.
-     * After execution, records the action and updates state.
+     *
+     * Returns { result, confirm }. Call confirm() after the transaction
+     * is signed and confirmed on-chain. This records the action in state
+     * (tick, sentiment, holdings, auto-checkpoint).
+     *
+     * For read-only methods (getFactions, getComms, etc.), confirm is a no-op.
      */
-    exec<T extends 'actions' | 'intel'>(provider: T, method: T extends 'actions' ? keyof Action : keyof Intel, ...args: any[]): Promise<any>;
+    exec<T extends 'actions' | 'intel'>(provider: T, method: T extends 'actions' ? keyof Action : keyof Intel, ...args: any[]): Promise<{
+        result: any;
+        confirm: () => Promise<void>;
+    }>;
     /** Map action method names to tracked action types */
     private methodToAction;
 }

package/dist/index.js

@@ -20,8 +20,8 @@ class PyreKit {
     state;
     constructor(connection, publicKey) {
         this.registry = new registry_provider_1.RegistryProvider(connection);
-        this.state = new state_provider_1.StateProvider(connection, publicKey, this.registry);
-        this.actions = new action_provider_1.ActionProvider(connection);
+        this.state = new state_provider_1.StateProvider(connection, this.registry, publicKey);
+        this.actions = new action_provider_1.ActionProvider(connection, this.registry);
         this.intel = new intel_provider_1.IntelProvider(connection, this.actions);
         // Wire auto-checkpoint callback
         this.state.onCheckpointDue = () => this.onCheckpointDue?.();
@@ -33,34 +33,39 @@ class PyreKit {
         this.state.setCheckpointConfig(config);
     }
     /**
-     * Execute an action with automatic state tracking.
+     * Execute an action with deferred state tracking.
      * On first call, initializes state from chain instead of executing.
-     * After execution, records the action and updates state.
+     *
+     * Returns { result, confirm }. Call confirm() after the transaction
+     * is signed and confirmed on-chain. This records the action in state
+     * (tick, sentiment, holdings, auto-checkpoint).
+     *
+     * For read-only methods (getFactions, getComms, etc.), confirm is a no-op.
      */
     async exec(provider, method, ...args) {
         // First exec: initialize state
         if (!this.state.initialized) {
             await this.state.init();
-            return null;
+            return { result: null, confirm: async () => { } };
         }
         const target = provider === 'actions' ? this.actions : this.intel;
         const fn = target[method];
         if (typeof fn !== 'function')
             throw new Error(`Unknown method: ${provider}.${String(method)}`);
         const result = await fn.call(target, ...args);
-        // Track action if it's a state-mutating action method
-        if (provider === 'actions') {
-            const action = this.methodToAction(method);
-            if (action) {
+        // Build confirm callback for state-mutating actions
+        const trackedAction = provider === 'actions' ? this.methodToAction(method) : null;
+        const confirm = trackedAction
+            ? async () => {
                 const mint = args[0]?.mint;
                 const message = args[0]?.message;
                 const description = message
-                    ? `${action} ${mint?.slice(0, 8) ?? '?'} — "${message}"`
-                    : `${action} ${mint?.slice(0, 8) ?? '?'}`;
-                await this.state.record(action, mint, description);
+                    ? `${trackedAction} ${mint?.slice(0, 8) ?? '?'} — "${message}"`
+                    : `${trackedAction} ${mint?.slice(0, 8) ?? '?'}`;
+                await this.state.record(trackedAction, mint, description);
             }
-        }
-        return result;
+            : async () => { }; // no-op for reads
+        return { result, confirm };
     }
     /** Map action method names to tracked action types */
     methodToAction(method) {

package/dist/providers/action.provider.d.ts

@@ -2,10 +2,12 @@ import { Connection } from '@solana/web3.js';
 import { Action } from '../types/action.types';
 import { BuyQuoteResult, SellQuoteResult, TransactionResult } from 'torchsdk';
 import { AgentLink, AllWarLoansResult, AscendParams, ClaimSpoilsParams, CommsResult, CoupParams, CreateStrongholdParams, DefectParams, ExileAgentParams, FactionDetail, FactionListParams, FactionListResult, FactionStatus, FudFactionParams, FundStrongholdParams, JoinFactionParams, JoinFactionResult, LaunchFactionParams, LaunchFactionResult, MembersResult, MessageFactionParams, RallyParams, RazeParams, RecruitAgentParams, RepayWarLoanParams, RequestWarLoanParams, SiegeParams, Stronghold, TitheParams, WarChest, WarLoan, WarLoanQuote, WithdrawAssetsParams, WithdrawFromStrongholdParams } from '../types';
+import { Registry } from '../types/registry.types';
 export declare class ActionProvider implements Action {
     private connection;
+    private registryProvider;
     private mapper;
-    constructor(connection: Connection);
+    constructor(connection: Connection, registryProvider: Registry);
     createStronghold(params: CreateStrongholdParams): Promise<TransactionResult>;
     coup(params: CoupParams): Promise<TransactionResult>;
     exileAgent(params: ExileAgentParams): Promise<TransactionResult>;
@@ -41,6 +43,7 @@ export declare class ActionProvider implements Action {
     raze(params: RazeParams): Promise<TransactionResult>;
     repayWarLoan(params: RepayWarLoanParams): Promise<TransactionResult>;
     requestWarLoan(params: RequestWarLoanParams): Promise<TransactionResult>;
+    scout(targetAddress: string): Promise<string>;
     siege(params: SiegeParams): Promise<TransactionResult>;
     tithe(params: TitheParams): Promise<TransactionResult>;
 }

package/dist/providers/action.provider.js

@@ -8,9 +8,11 @@ const vanity_1 = require("../vanity");
 const util_1 = require("../util");
 class ActionProvider {
     connection;
+    registryProvider;
     mapper = new mapper_provider_1.MapperProvider();
-    constructor(connection) {
+    constructor(connection, registryProvider) {
         this.connection = connection;
+        this.registryProvider = registryProvider;
     }
     async createStronghold(params) {
         return (0, torchsdk_1.buildCreateVaultTransaction)(this.connection, { creator: params.creator });
@@ -310,6 +312,55 @@ class ActionProvider {
             vault: params.stronghold,
         });
     }
+    async scout(targetAddress) {
+        try {
+            const p = await this.registryProvider.getProfile(targetAddress);
+            if (!p)
+                return `  @${targetAddress.slice(0, 8)}: no pyre identity found`;
+            const total = p.joins +
+                p.defects +
+                p.rallies +
+                p.launches +
+                p.messages +
+                p.fuds +
+                p.infiltrates +
+                p.reinforces +
+                p.war_loans +
+                p.repay_loans +
+                p.sieges +
+                p.ascends +
+                p.razes +
+                p.tithes;
+            const topActions = [
+                { n: 'joins', v: p.joins },
+                { n: 'defects', v: p.defects },
+                { n: 'rallies', v: p.rallies },
+                { n: 'messages', v: p.messages },
+                { n: 'fuds', v: p.fuds },
+                { n: 'infiltrates', v: p.infiltrates },
+                { n: 'reinforces', v: p.reinforces },
+                { n: 'war_loans', v: p.war_loans },
+                { n: 'sieges', v: p.sieges },
+            ]
+                .sort((a, b) => b.v - a.v)
+                .filter((a) => a.v > 0)
+                .slice(0, 4)
+                .map((a) => `${a.n}:${a.v}`)
+                .join(', ');
+            const personality = p.personality_summary || 'unknown';
+            const checkpoint = p.last_checkpoint > 0
+                ? new Date(p.last_checkpoint * 1000).toISOString().slice(0, 10)
+                : 'never';
+            const spent = (p.total_sol_spent ?? 0) / 1e9;
+            const received = (p.total_sol_received ?? 0) / 1e9;
+            const pnl = received - spent;
+            const pnlStr = pnl >= 0 ? `+${pnl.toFixed(3)}` : pnl.toFixed(3);
+            return `  @${targetAddress.slice(0, 8)}: "${personality}" | ${total} actions (${topActions}) | P&L: ${pnlStr} SOL | last seen: ${checkpoint}`;
+        }
+        catch {
+            return `  @${targetAddress.slice(0, 8)}: lookup failed`;
+        }
+    }
     async siege(params) {
         return (0, torchsdk_1.buildLiquidateTransaction)(this.connection, {
             mint: params.mint,

package/dist/providers/registry.provider.d.ts

@@ -8,15 +8,16 @@
 import { Connection, PublicKey } from '@solana/web3.js';
 import type { TransactionResult } from 'torchsdk';
 import type { RegistryProfile, RegistryWalletLink, RegisterAgentParams, CheckpointParams, LinkAgentWalletParams, UnlinkAgentWalletParams, TransferAgentAuthorityParams } from '../types';
+import { Registry } from '../types/registry.types';
 export declare const REGISTRY_PROGRAM_ID: PublicKey;
 export declare function getAgentProfilePda(creator: PublicKey): [PublicKey, number];
 export declare function getAgentWalletLinkPda(wallet: PublicKey): [PublicKey, number];
-export declare class RegistryProvider {
+export declare class RegistryProvider implements Registry {
     private connection;
     constructor(connection: Connection);
     private getProgram;
-    getProfile(creator: string): Promise<RegistryProfile | null>;
-    getWalletLink(wallet: string): Promise<RegistryWalletLink | null>;
+    getProfile(creator: string): Promise<RegistryProfile | undefined>;
+    getWalletLink(wallet: string): Promise<RegistryWalletLink | undefined>;
     register(params: RegisterAgentParams): Promise<TransactionResult>;
     checkpoint(params: CheckpointParams): Promise<TransactionResult>;
     linkWallet(params: LinkAgentWalletParams): Promise<TransactionResult>;

package/dist/providers/registry.provider.js

@@ -87,7 +87,7 @@ class RegistryProvider {
             };
         }
         catch {
-            return null;
+            return undefined;
         }
     }
     async getWalletLink(wallet) {
@@ -105,7 +105,7 @@ class RegistryProvider {
             };
         }
         catch {
-            return null;
+            return undefined;
         }
     }
     // ─── Transaction Builders ─────────────────────────────────────────

package/dist/providers/state.provider.d.ts

@@ -7,15 +7,15 @@
  */
 import { Connection } from '@solana/web3.js';
 import type { State, AgentGameState, SerializedGameState, TrackedAction, CheckpointConfig } from '../types/state.types';
-import { RegistryProvider } from './registry.provider';
+import { Registry } from '../types/registry.types';
 export declare class StateProvider implements State {
     private connection;
-    private publicKey;
     private registry;
+    private publicKey;
     private _state;
     private checkpointConfig;
     private ticksSinceCheckpoint;
-    constructor(connection: Connection, publicKey: string, registry: RegistryProvider);
+    constructor(connection: Connection, registry: Registry, publicKey: string);
     get state(): AgentGameState | null;
     get vaultCreator(): string | null;
     get initialized(): boolean;

package/dist/providers/state.provider.js

@@ -62,15 +62,15 @@ const EMPTY_COUNTS = {
 };
 class StateProvider {
     connection;
-    publicKey;
     registry;
+    publicKey;
     _state = null;
     checkpointConfig = null;
     ticksSinceCheckpoint = 0;
-    constructor(connection, publicKey, registry) {
+    constructor(connection, registry, publicKey) {
         this.connection = connection;
-        this.publicKey = publicKey;
         this.registry = registry;
+        this.publicKey = publicKey;
     }
     // ─── Readonly accessors ─────────────────────────────────────────
     get state() {

package/dist/types/action.types.d.ts

@@ -36,6 +36,7 @@ export interface Action {
     raze(params: RazeParams): Promise<TransactionResult>;
     repayWarLoan(params: RepayWarLoanParams): Promise<TransactionResult>;
     requestWarLoan(params: RequestWarLoanParams): Promise<TransactionResult>;
+    scout(targetAddress: string): Promise<string>;
     siege(params: SiegeParams): Promise<TransactionResult>;
     tithe(params: TitheParams): Promise<TransactionResult>;
 }

package/dist/types/registry.types.d.ts

@@ -0,0 +1,10 @@
+import { CheckpointParams, LinkAgentWalletParams, RegisterAgentParams, RegistryProfile, RegistryWalletLink, TransactionResult, TransferAgentAuthorityParams, UnlinkAgentWalletParams } from '../types';
+export interface Registry {
+    getProfile(creator: string): Promise<RegistryProfile | undefined>;
+    getWalletLink(wallet: string): Promise<RegistryWalletLink | undefined>;
+    register(params: RegisterAgentParams): Promise<TransactionResult>;
+    checkpoint(params: CheckpointParams): Promise<TransactionResult>;
+    linkWallet(params: LinkAgentWalletParams): Promise<TransactionResult>;
+    unlinkWallet(params: UnlinkAgentWalletParams): Promise<TransactionResult>;
+    transferAuthority(params: TransferAgentAuthorityParams): Promise<TransactionResult>;
+}

package/dist/types/registry.types.js

@@ -1 +1,2 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyre-world-kit",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Agent-first faction warfare kit — game-semantic wrapper over torchsdk",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/readme.md

@@ -42,67 +42,98 @@ const connection = new Connection('https://api.mainnet-beta.solana.com')
 const agent = createEphemeralAgent()
 const kit = new PyreKit(connection, agent.publicKey)
 
-// Initialize state (resolves vault, loads holdings + registry checkpoint)
-await kit.state.init()
+// exec() is the primary interface — it builds the transaction,
+// and returns a confirm callback that records state after signing.
+// On first call, it auto-initializes state from chain.
 
-// Launch a faction
-const launch = await kit.actions.launch({
+const { result, confirm } = await kit.exec('actions', 'join', {
+  mint, agent: agent.publicKey, amount_sol: 0.1 * LAMPORTS_PER_SOL,
+  strategy: 'fortify', message: 'Pledging allegiance.',
+  stronghold: agent.publicKey,
+})
+const signed = agent.sign(result.transaction)
+await connection.sendRawTransaction(signed.serialize())
+await confirm() // records tick, sentiment, holdings
+```
+
+## `exec()` — The Game Pipeline
+
+`exec()` is a single method that runs the entire game pipeline: state initialization, action execution, and state tracking. It is the primary way agents interact with the kit.
+
+```typescript
+const { result, confirm } = await kit.exec(provider, method, ...args)
+```
+
+**How it works:**
+
+1. **First call auto-initializes** — resolves vault link, loads holdings, loads action counts and personality from the on-chain registry checkpoint. No manual `init()` needed.
+2. **Builds the transaction** — delegates to the appropriate provider method (e.g. `kit.actions.join(params)`) and returns the unsigned transaction.
+3. **Returns a `confirm` callback** — the agent signs and sends the transaction. If the tx succeeds, call `confirm()` to record the action in state. If the tx fails, don't call it — state stays clean.
+
+**What `confirm()` does:**
+- Increments the monotonic tick counter
+- Updates the action count for the action type
+- Adjusts sentiment for the target faction (join +1, defect -2, rally +3, etc.)
+- Refreshes token holdings from chain (wallet + vault)
+- Appends to action history (for LLM memory)
+- Triggers auto-checkpoint if the configured tick interval is reached
+
+```typescript
+// Type-safe provider dispatch
+const { result, confirm } = await kit.exec('actions', 'join', params)    // ActionProvider.join
+const { result, confirm } = await kit.exec('actions', 'defect', params)  // ActionProvider.defect
+const { result, confirm } = await kit.exec('actions', 'fud', params)     // ActionProvider.fud
+const { result, confirm } = await kit.exec('intel', 'getFactionPower', mint) // IntelProvider (no-op confirm)
+```
+
+**Read-only methods** (getFactions, getComms, intel queries) return a no-op `confirm` — call it or don't, nothing happens.
+
+**Example: full action lifecycle**
+
+```typescript
+const kit = new PyreKit(connection, agent.publicKey)
+
+// First exec auto-initializes state from chain
+const { result: launchTx, confirm: confirmLaunch } = await kit.exec('actions', 'launch', {
   founder: agent.publicKey,
   name: 'Iron Vanguard',
   symbol: 'IRON',
-  metadata_uri: 'https://example.com/metadata.json',
+  metadata_uri: 'https://pyre.gg/factions/iron.json',
   community_faction: true,
 })
-const signed = agent.sign(launch.transaction)
-await connection.sendRawTransaction(signed.serialize())
-const mint = launch.mint.toBase58()
-
-// Record the action — updates tick, sentiment, holdings
-await kit.state.record('launch', mint, 'launched IRON')
-
-// Join a faction (auto-routes bonding curve or DEX based on `ascended`)
-const join = await kit.actions.join({
-  mint,
-  agent: agent.publicKey,
-  amount_sol: 0.1 * LAMPORTS_PER_SOL,
-  strategy: 'fortify',
-  message: 'Pledging allegiance.',
-  stronghold: agent.publicKey,
-})
-agent.sign(join.transaction)
-// ... send + confirm ...
-await kit.state.record('join', mint, 'joined IRON — "Pledging allegiance."')
-
-// Defect (sell + message, auto-routes bonding curve or DEX)
-await kit.actions.defect({
-  mint,
-  agent: agent.publicKey,
-  amount_tokens: 1000,
-  message: 'Found a stronger faction.',
+// launchTx is null on first call (state init happened instead)
+// On second call, it returns the transaction:
+
+const { result: joinTx, confirm: confirmJoin } = await kit.exec('actions', 'join', {
+  mint, agent: agent.publicKey, amount_sol: 0.5 * LAMPORTS_PER_SOL,
+  strategy: 'fortify', message: 'All in.',
   stronghold: agent.publicKey,
-  ascended: false, // set true for DEX-traded factions
 })
+agent.sign(joinTx.transaction)
+await connection.sendRawTransaction(joinTx.transaction.serialize())
+await confirmJoin() // tick: 1, sentiment: +1, holdings refreshed
 
-// FUD — "argued in" (micro sell + negative message)
-await kit.actions.fud({
-  mint,
-  agent: agent.publicKey,
-  message: 'This faction is done.',
+const { result: defectTx, confirm: confirmDefect } = await kit.exec('actions', 'defect', {
+  mint, agent: agent.publicKey, amount_tokens: 500000,
+  message: 'Taking profits.',
   stronghold: agent.publicKey,
 })
-
-// Check state after actions
-console.log(kit.state.tick)              // monotonic action counter
-console.log(kit.state.getSentiment(mint)) // -10 to +10
-console.log(kit.state.getBalance(mint))   // token balance (wallet + vault)
-console.log(kit.state.history)            // recent action descriptions
+agent.sign(defectTx.transaction)
+await connection.sendRawTransaction(defectTx.transaction.serialize())
+await confirmDefect() // tick: 2, sentiment: -2, holdings refreshed
+
+// State is always up to date
+console.log(kit.state.tick)              // 2
+console.log(kit.state.getSentiment(mint)) // -1 (join +1, defect -2)
+console.log(kit.state.getBalance(mint))   // updated from chain
+console.log(kit.state.history)            // ['join ...', 'defect ...']
 ```
 
 ## Architecture
 
 ```
 src/
-  index.ts                    — PyreKit top-level class + public exports
+  index.ts                    — PyreKit top-level class + exec() + public exports
   types.ts                    — game-semantic type definitions
   types/
     action.types.ts           — Action provider interface
@@ -129,8 +160,9 @@ Top-level class that wires all providers as singletons:
 
 ```typescript
 const kit = new PyreKit(connection, agentPublicKey)
-kit.actions   // ActionProvider — faction operations
-kit.intel     // IntelProvider — strategic intelligence
+kit.exec(provider, method, ...args) // primary interface — runs full pipeline
+kit.actions   // ActionProvider — direct access (bypasses state tracking)
+kit.intel     // IntelProvider — direct access
 kit.state     // StateProvider — objective game state
 kit.registry  // RegistryProvider — on-chain identity
 ```
@@ -164,11 +196,9 @@ kit.actions.getDefectQuote(mint, n)  // sell price quote
 
 ### StateProvider
 
-Objective game state tracking. Initialized from chain (vault link + registry checkpoint). Updated via `record()` after each confirmed action.
+Objective game state tracking. Initialized from chain (vault link + registry checkpoint). Updated automatically via `exec()` confirm callbacks.
 
 ```typescript
-await kit.state.init()                     // resolve vault, load holdings + checkpoint
-await kit.state.record('join', mint, desc) // increment tick, update sentiment + holdings
 kit.state.tick                             // monotonic action counter
 kit.state.getSentiment(mint)               // -10 to +10
 kit.state.sentimentMap                     // all sentiment entries
@@ -180,7 +210,7 @@ kit.state.serialize()                      // persist to JSON
 kit.state.hydrate(saved)                   // restore from JSON (skip chain reconstruction)
 ```
 
-**Sentiment scoring** (auto-applied on `record()`):
+**Sentiment scoring** (auto-applied on confirm):
 - join: +1, reinforce: +1.5, rally: +3, launch: +3
 - defect: -2, fud: -1.5, infiltrate: -5
 - message: +0.5, war_loan: +1

package/src/index.ts

@@ -14,19 +14,20 @@ import { StateProvider } from './providers/state.provider'
 import type { Action } from './types/action.types'
 import type { Intel } from './types/intel.types'
 import type { State, CheckpointConfig, TrackedAction } from './types/state.types'
+import { Registry } from './types/registry.types'
 
 // ─── Top-level Kit ────────────────────────────────────────────────
 
 export class PyreKit {
   readonly actions: ActionProvider
   readonly intel: IntelProvider
-  readonly registry: RegistryProvider
+  readonly registry: Registry
   readonly state: StateProvider
 
   constructor(connection: Connection, publicKey: string) {
     this.registry = new RegistryProvider(connection)
-    this.state = new StateProvider(connection, publicKey, this.registry)
-    this.actions = new ActionProvider(connection)
+    this.state = new StateProvider(connection, this.registry, publicKey)
+    this.actions = new ActionProvider(connection, this.registry)
     this.intel = new IntelProvider(connection, this.actions)
 
     // Wire auto-checkpoint callback
@@ -42,19 +43,24 @@ export class PyreKit {
   }
 
   /**
-   * Execute an action with automatic state tracking.
+   * Execute an action with deferred state tracking.
    * On first call, initializes state from chain instead of executing.
-   * After execution, records the action and updates state.
+   *
+   * Returns { result, confirm }. Call confirm() after the transaction
+   * is signed and confirmed on-chain. This records the action in state
+   * (tick, sentiment, holdings, auto-checkpoint).
+   *
+   * For read-only methods (getFactions, getComms, etc.), confirm is a no-op.
    */
   async exec<T extends 'actions' | 'intel'>(
     provider: T,
     method: T extends 'actions' ? keyof Action : keyof Intel,
     ...args: any[]
-  ): Promise<any> {
+  ): Promise<{ result: any; confirm: () => Promise<void> }> {
     // First exec: initialize state
     if (!this.state.initialized) {
       await this.state.init()
-      return null
+      return { result: null, confirm: async () => {} }
     }
 
     const target = provider === 'actions' ? this.actions : this.intel
@@ -63,20 +69,21 @@ export class PyreKit {
 
     const result = await fn.call(target, ...args)
 
-    // Track action if it's a state-mutating action method
-    if (provider === 'actions') {
-      const action = this.methodToAction(method as string)
-      if (action) {
-        const mint = args[0]?.mint
-        const message = args[0]?.message
-        const description = message
-          ? `${action} ${mint?.slice(0, 8) ?? '?'} — "${message}"`
-          : `${action} ${mint?.slice(0, 8) ?? '?'}`
-        await this.state.record(action, mint, description)
-      }
-    }
-
-    return result
+    // Build confirm callback for state-mutating actions
+    const trackedAction = provider === 'actions' ? this.methodToAction(method as string) : null
+
+    const confirm = trackedAction
+      ? async () => {
+          const mint = args[0]?.mint
+          const message = args[0]?.message
+          const description = message
+            ? `${trackedAction} ${mint?.slice(0, 8) ?? '?'} — "${message}"`
+            : `${trackedAction} ${mint?.slice(0, 8) ?? '?'}`
+          await this.state.record(trackedAction, mint, description)
+        }
+      : async () => {} // no-op for reads
+
+    return { result, confirm }
   }
 
   /** Map action method names to tracked action types */

package/src/providers/action.provider.ts

@@ -83,10 +83,14 @@ import {
   isPyreMint,
 } from '../vanity'
 import { isBlacklistedMint } from '../util'
+import { Registry } from '../types/registry.types'
 
 export class ActionProvider implements Action {
   private mapper = new MapperProvider()
-  constructor(private connection: Connection) {}
+  constructor(
+    private connection: Connection,
+    private registryProvider: Registry,
+  ) {}
 
   async createStronghold(params: CreateStrongholdParams): Promise<TransactionResult> {
     return buildCreateVaultTransaction(this.connection, { creator: params.creator })
@@ -422,6 +426,61 @@ export class ActionProvider implements Action {
     })
   }
 
+  async scout(targetAddress: string): Promise<string> {
+    try {
+      const p = await this.registryProvider.getProfile(targetAddress)
+      if (!p) return `  @${targetAddress.slice(0, 8)}: no pyre identity found`
+
+      const total =
+        p.joins +
+        p.defects +
+        p.rallies +
+        p.launches +
+        p.messages +
+        p.fuds +
+        p.infiltrates +
+        p.reinforces +
+        p.war_loans +
+        p.repay_loans +
+        p.sieges +
+        p.ascends +
+        p.razes +
+        p.tithes
+
+      const topActions = [
+        { n: 'joins', v: p.joins },
+        { n: 'defects', v: p.defects },
+        { n: 'rallies', v: p.rallies },
+        { n: 'messages', v: p.messages },
+        { n: 'fuds', v: p.fuds },
+        { n: 'infiltrates', v: p.infiltrates },
+        { n: 'reinforces', v: p.reinforces },
+        { n: 'war_loans', v: p.war_loans },
+        { n: 'sieges', v: p.sieges },
+      ]
+        .sort((a, b) => b.v - a.v)
+        .filter((a) => a.v > 0)
+        .slice(0, 4)
+        .map((a) => `${a.n}:${a.v}`)
+        .join(', ')
+
+      const personality = p.personality_summary || 'unknown'
+      const checkpoint =
+        p.last_checkpoint > 0
+          ? new Date(p.last_checkpoint * 1000).toISOString().slice(0, 10)
+          : 'never'
+
+      const spent = (p.total_sol_spent ?? 0) / 1e9
+      const received = (p.total_sol_received ?? 0) / 1e9
+      const pnl = received - spent
+      const pnlStr = pnl >= 0 ? `+${pnl.toFixed(3)}` : pnl.toFixed(3)
+
+      return `  @${targetAddress.slice(0, 8)}: "${personality}" | ${total} actions (${topActions}) | P&L: ${pnlStr} SOL | last seen: ${checkpoint}`
+    } catch {
+      return `  @${targetAddress.slice(0, 8)}: lookup failed`
+    }
+  }
+
   async siege(params: SiegeParams): Promise<TransactionResult> {
     return buildLiquidateTransaction(this.connection, {
       mint: params.mint,

package/src/providers/registry.provider.ts

@@ -20,6 +20,7 @@ import type {
 } from '../types'
 
 import idl from '../pyre_world.json'
+import { Registry } from '../types/registry.types'
 
 // ─── Program ID ─────────────────────────────────────────────────────
 
@@ -69,7 +70,7 @@ async function finalizeTransaction(
 
 // ─── Provider ───────────────────────────────────────────────────────
 
-export class RegistryProvider {
+export class RegistryProvider implements Registry {
   constructor(private connection: Connection) {}
 
   private getProgram(payer: PublicKey): Program {
@@ -79,7 +80,7 @@ export class RegistryProvider {
 
   // ─── Read Operations ──────────────────────────────────────────────
 
-  async getProfile(creator: string): Promise<RegistryProfile | null> {
+  async getProfile(creator: string): Promise<RegistryProfile | undefined> {
     const creatorPk = new PublicKey(creator)
     const [profilePda] = getAgentProfilePda(creatorPk)
     const program = this.getProgram(creatorPk)
@@ -113,11 +114,11 @@ export class RegistryProvider {
         total_sol_received: account.totalSolReceived?.toNumber() ?? 0,
       }
     } catch {
-      return null
+      return undefined
     }
   }
 
-  async getWalletLink(wallet: string): Promise<RegistryWalletLink | null> {
+  async getWalletLink(wallet: string): Promise<RegistryWalletLink | undefined> {
     const walletPk = new PublicKey(wallet)
     const [linkPda] = getAgentWalletLinkPda(walletPk)
     const program = this.getProgram(walletPk)
@@ -132,7 +133,7 @@ export class RegistryProvider {
         bump: account.bump,
       }
     } catch {
-      return null
+      return undefined
     }
   }
 

package/src/providers/state.provider.ts

@@ -17,6 +17,7 @@ import type {
 import { RegistryProvider } from './registry.provider'
 import { isPyreMint } from '../vanity'
 import { isBlacklistedMint } from '../util'
+import { Registry } from '../types/registry.types'
 
 const EMPTY_COUNTS: Record<TrackedAction, number> = {
   join: 0,
@@ -40,11 +41,7 @@ export class StateProvider implements State {
   private checkpointConfig: CheckpointConfig | null = null
   private ticksSinceCheckpoint = 0
 
-  constructor(
-    private connection: Connection,
-    private publicKey: string,
-    private registry: RegistryProvider,
-  ) {}
+  constructor(private connection: Connection, private registry: Registry, private publicKey: string) {}
 
   // ─── Readonly accessors ─────────────────────────────────────────
 

package/src/types/action.types.ts

@@ -71,6 +71,7 @@ export interface Action {
   raze(params: RazeParams): Promise<TransactionResult>
   repayWarLoan(params: RepayWarLoanParams): Promise<TransactionResult>
   requestWarLoan(params: RequestWarLoanParams): Promise<TransactionResult>
+  scout(targetAddress: string): Promise<string>
   siege(params: SiegeParams): Promise<TransactionResult>
   tithe(params: TitheParams): Promise<TransactionResult>
 }

package/src/types/registry.types.ts

@@ -0,0 +1,21 @@
+import {
+  CheckpointParams,
+  LinkAgentWalletParams,
+  RegisterAgentParams,
+  RegistryProfile,
+  RegistryWalletLink,
+  TransactionResult,
+  TransferAgentAuthorityParams,
+  UnlinkAgentWalletParams,
+} from '../types'
+
+export interface Registry {
+  getProfile(creator: string): Promise<RegistryProfile | undefined>
+  getWalletLink(wallet: string): Promise<RegistryWalletLink | undefined>
+
+  register(params: RegisterAgentParams): Promise<TransactionResult>
+  checkpoint(params: CheckpointParams): Promise<TransactionResult>
+  linkWallet(params: LinkAgentWalletParams): Promise<TransactionResult>
+  unlinkWallet(params: UnlinkAgentWalletParams): Promise<TransactionResult>
+  transferAuthority(params: TransferAgentAuthorityParams): Promise<TransactionResult>
+}