pyre-world-kit 3.0.1 → 3.0.3

package/dist/index.d.ts

@@ -6,17 +6,15 @@
  * so agents think in factions, not tokens.
  */
 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 { Action } from './types/action.types';
+import { Intel } from './types/intel.types';
+import { Registry } from './types/registry.types';
 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';
 export declare class PyreKit {
-    readonly actions: ActionProvider;
-    readonly intel: IntelProvider;
-    readonly registry: RegistryProvider;
+    readonly actions: Action;
+    readonly intel: Intel;
+    readonly registry: Registry;
     readonly state: StateProvider;
     constructor(connection: Connection, publicKey: string);
     /** Callback fired when checkpoint interval is reached */

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?.();

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

@@ -1,11 +1,13 @@
 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 { Action } from '../types/action.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/mapper.provider.d.ts

@@ -1,8 +1,3 @@
-/**
- * Pyre Kit Mappers
- *
- * Internal mapping functions between Torch SDK types and Pyre game types.
- */
 import type { AllLoanPositionsResult, BuyTransactionResult, CreateTokenResult, Holder, HoldersResult, LendingInfo, LoanPositionInfo, LoanPositionWithKey, MessagesResult, TokenDetail, TokenListResult, TokenMessage, TokenStatus, TokenSummary, VaultInfo, VaultWalletLinkInfo } from 'torchsdk';
 import type { FactionStatus, FactionStatusFilter, Strategy } from '../types';
 import { Mapper } from '../types/mapper.types';

package/dist/providers/mapper.provider.js

@@ -1,9 +1,4 @@
 "use strict";
-/**
- * Pyre Kit Mappers
- *
- * Internal mapping functions between Torch SDK types and Pyre game types.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MapperProvider = void 0;
 const mapper_types_1 = require("../types/mapper.types");

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

@@ -1,22 +1,16 @@
-/**
- * Pyre World Agent Registry Provider
- *
- * On-chain agent identity and state persistence.
- * Agents checkpoint their action distributions and personality summaries
- * so any machine with the wallet key can reconstruct the agent.
- */
 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

@@ -1,11 +1,4 @@
 "use strict";
-/**
- * Pyre World Agent Registry Provider
- *
- * On-chain agent identity and state persistence.
- * Agents checkpoint their action distributions and personality summaries
- * so any machine with the wallet key can reconstruct the agent.
- */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -16,19 +9,15 @@ exports.getAgentWalletLinkPda = getAgentWalletLinkPda;
 const web3_js_1 = require("@solana/web3.js");
 const anchor_1 = require("@coral-xyz/anchor");
 const pyre_world_json_1 = __importDefault(require("../pyre_world.json"));
-// ─── Program ID ─────────────────────────────────────────────────────
 exports.REGISTRY_PROGRAM_ID = new web3_js_1.PublicKey(pyre_world_json_1.default.address);
-// ─── PDA Seeds ──────────────────────────────────────────────────────
 const AGENT_SEED = 'pyre_agent';
 const AGENT_WALLET_SEED = 'pyre_agent_wallet';
-// ─── PDA Helpers ────────────────────────────────────────────────────
 function getAgentProfilePda(creator) {
     return web3_js_1.PublicKey.findProgramAddressSync([Buffer.from(AGENT_SEED), creator.toBuffer()], exports.REGISTRY_PROGRAM_ID);
 }
 function getAgentWalletLinkPda(wallet) {
     return web3_js_1.PublicKey.findProgramAddressSync([Buffer.from(AGENT_WALLET_SEED), wallet.toBuffer()], exports.REGISTRY_PROGRAM_ID);
 }
-// ─── Anchor Program Helper ──────────────────────────────────────────
 function makeDummyProvider(connection, payer) {
     const dummyWallet = {
         publicKey: payer,
@@ -42,7 +31,6 @@ async function finalizeTransaction(connection, tx, feePayer) {
     tx.recentBlockhash = blockhash;
     tx.feePayer = feePayer;
 }
-// ─── Provider ───────────────────────────────────────────────────────
 class RegistryProvider {
     connection;
     constructor(connection) {
@@ -52,7 +40,6 @@ class RegistryProvider {
         const provider = makeDummyProvider(this.connection, payer);
         return new anchor_1.Program(pyre_world_json_1.default, provider);
     }
-    // ─── Read Operations ──────────────────────────────────────────────
     async getProfile(creator) {
         const creatorPk = new web3_js_1.PublicKey(creator);
         const [profilePda] = getAgentProfilePda(creatorPk);
@@ -87,7 +74,7 @@ class RegistryProvider {
             };
         }
         catch {
-            return null;
+            return undefined;
         }
     }
     async getWalletLink(wallet) {
@@ -105,10 +92,9 @@ class RegistryProvider {
             };
         }
         catch {
-            return null;
+            return undefined;
         }
     }
-    // ─── Transaction Builders ─────────────────────────────────────────
     async register(params) {
         const creator = new web3_js_1.PublicKey(params.creator);
         const [profile] = getAgentProfilePda(creator);

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

@@ -1,21 +1,14 @@
-/**
- * Pyre Kit State Provider
- *
- * Objective game state tracking for an agent.
- * Owns holdings, action counts, vault resolution, tick counter.
- * Injected into ActionProvider so every action automatically updates state.
- */
 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;
@@ -24,9 +17,7 @@ export declare class StateProvider implements State {
     setCheckpointConfig(config: CheckpointConfig): void;
     init(): Promise<AgentGameState>;
     record(action: TrackedAction, mint?: string, description?: string): Promise<void>;
-    /** Update sentiment score for a faction based on action type */
     private updateSentiment;
-    /** Callback set by PyreKit to handle checkpoint triggers */
     onCheckpointDue: (() => void) | null;
     refreshHoldings(): Promise<void>;
     getSentiment(mint: string): number;

package/dist/providers/state.provider.js

@@ -1,11 +1,4 @@
 "use strict";
-/**
- * Pyre Kit State Provider
- *
- * Objective game state tracking for an agent.
- * Owns holdings, action counts, vault resolution, tick counter.
- * Injected into ActionProvider so every action automatically updates state.
- */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -62,17 +55,16 @@ 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() {
         return this._state;
     }
@@ -85,12 +77,10 @@ class StateProvider {
     get tick() {
         return this._state?.tick ?? 0;
     }
-    // ─── Configuration ──────────────────────────────────────────────
     /** Configure auto-checkpoint behavior */
     setCheckpointConfig(config) {
         this.checkpointConfig = config;
     }
-    // ─── Initialization ─────────────────────────────────────────────
     async init() {
         if (this._state?.initialized)
             return this._state;
@@ -113,7 +103,7 @@ class StateProvider {
             initialized: false,
         };
         this._state = state;
-        // Resolve vault link
+        // resolve vault link
         const { getVaultForWallet } = await Promise.resolve().then(() => __importStar(require('torchsdk')));
         try {
             const vault = await getVaultForWallet(this.connection, this.publicKey);
@@ -134,14 +124,12 @@ class StateProvider {
             }
         }
         catch { }
-        // Load registry profile — personality, action counts, SOL totals
         try {
             const profile = await this.registry.getProfile(this.publicKey);
             if (profile) {
                 state.personalitySummary = profile.personality_summary || null;
                 state.totalSolSpent = profile.total_sol_spent;
                 state.totalSolReceived = profile.total_sol_received;
-                // Seed action counts from on-chain checkpoint
                 state.actionCounts.join = Math.max(state.actionCounts.join, profile.joins);
                 state.actionCounts.defect = Math.max(state.actionCounts.defect, profile.defects);
                 state.actionCounts.rally = Math.max(state.actionCounts.rally, profile.rallies);
@@ -156,48 +144,39 @@ class StateProvider {
                 state.actionCounts.ascend = Math.max(state.actionCounts.ascend, profile.ascends);
                 state.actionCounts.raze = Math.max(state.actionCounts.raze, profile.razes);
                 state.actionCounts.tithe = Math.max(state.actionCounts.tithe, profile.tithes);
-                // Set tick to total actions from checkpoint
                 const totalFromCheckpoint = Object.values(state.actionCounts).reduce((a, b) => a + b, 0);
                 state.tick = totalFromCheckpoint;
             }
         }
         catch { }
-        // Load holdings (wallet + vault token accounts)
         await this.refreshHoldings();
         state.initialized = true;
         return state;
     }
-    // ─── Action Recording ───────────────────────────────────────────
     async record(action, mint, description) {
         if (!this._state)
             throw new Error('State not initialized — call init() first');
         this._state.tick++;
         this._state.actionCounts[action]++;
         this.ticksSinceCheckpoint++;
-        // Track founded factions
         if (action === 'launch' && mint) {
             this._state.founded.push(mint);
         }
-        // Update sentiment for the target faction
         if (mint) {
             this.updateSentiment(action, mint);
         }
-        // Track recent history for LLM memory block
         if (description) {
             this._state.recentHistory.push(description);
             if (this._state.recentHistory.length > 20) {
                 this._state.recentHistory = this._state.recentHistory.slice(-20);
             }
         }
-        // Refresh holdings after any trade action
         await this.refreshHoldings();
-        // Auto-checkpoint check
         if (this.checkpointConfig && this.ticksSinceCheckpoint >= this.checkpointConfig.interval) {
             this.ticksSinceCheckpoint = 0;
             this.onCheckpointDue?.();
         }
     }
-    /** Update sentiment score for a faction based on action type */
     updateSentiment(action, mint) {
         if (!this._state)
             return;
@@ -218,15 +197,12 @@ class StateProvider {
             this._state.sentiment.set(mint, Math.max(-10, Math.min(10, current + delta)));
         }
     }
-    /** Callback set by PyreKit to handle checkpoint triggers */
     onCheckpointDue = null;
-    // ─── Holdings ───────────────────────────────────────────────────
     async refreshHoldings() {
         if (!this._state)
             return;
         const { TOKEN_2022_PROGRAM_ID } = await Promise.resolve().then(() => __importStar(require('@solana/spl-token')));
         const walletPk = new web3_js_1.PublicKey(this.publicKey);
-        // Scan wallet token accounts
         let walletValues = [];
         try {
             const walletAccounts = await this.connection.getParsedTokenAccountsByOwner(walletPk, {
@@ -235,7 +211,6 @@ class StateProvider {
             walletValues = walletAccounts.value;
         }
         catch { }
-        // Scan vault token accounts
         let vaultValues = [];
         if (this._state.stronghold) {
             try {
@@ -247,7 +222,6 @@ class StateProvider {
             }
             catch { }
         }
-        // Merge balances
         const newHoldings = new Map();
         for (const a of [...walletValues, ...vaultValues]) {
             const mint = a.account.data.parsed.info.mint;
@@ -256,7 +230,6 @@ class StateProvider {
                 newHoldings.set(mint, (newHoldings.get(mint) ?? 0) + balance);
             }
         }
-        // Update — clear stale, set fresh
         this._state.holdings.clear();
         for (const [mint, balance] of newHoldings) {
             this._state.holdings.set(mint, balance);
@@ -274,7 +247,6 @@ class StateProvider {
     getBalance(mint) {
         return this._state?.holdings.get(mint) ?? 0;
     }
-    // ─── Dedup Guards ───────────────────────────────────────────────
     hasVoted(mint) {
         return this._state?.voted.has(mint) ?? false;
     }
@@ -287,7 +259,6 @@ class StateProvider {
     markRallied(mint) {
         this._state?.rallied.add(mint);
     }
-    // ─── Serialization ──────────────────────────────────────────────
     serialize() {
         if (!this._state) {
             return {

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.1",
+  "version": "3.0.3",
   "description": "Agent-first faction warfare kit — game-semantic wrapper over torchsdk",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/readme.md

@@ -192,6 +192,7 @@ kit.actions.getMembers(mint)         // top holders
 kit.actions.getComms(mint, opts)     // trade-bundled messages
 kit.actions.getJoinQuote(mint, sol)  // buy price quote
 kit.actions.getDefectQuote(mint, n)  // sell price quote
+kit.actions.scout(address)           // look up agent's on-chain identity (read-only)
 ```
 
 ### StateProvider
@@ -260,6 +261,8 @@ score = (market_cap_sol * 0.4) + (members * 0.2) + (war_chest_sol * 0.2)
 
 ## Tests
 
+46/46 passing tests.
+
 Requires [surfpool](https://github.com/txtx/surfpool) running a local Solana fork:
 
 ```bash

package/src/index.ts

@@ -7,26 +7,30 @@
  */
 
 import { Connection } from '@solana/web3.js'
+
+import { Action } from './types/action.types'
+import { Intel } from './types/intel.types'
+import { Registry } from './types/registry.types'
+
 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 { State, CheckpointConfig, TrackedAction } from './types/state.types'
+
+import type { CheckpointConfig, TrackedAction } from './types/state.types'
 
 // ─── Top-level Kit ────────────────────────────────────────────────
 
 export class PyreKit {
-  readonly actions: ActionProvider
-  readonly intel: IntelProvider
-  readonly registry: RegistryProvider
+  readonly actions: Action
+  readonly intel: Intel
+  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

package/src/providers/action.provider.ts

@@ -1,5 +1,4 @@
 import { Connection, GetProgramAccountsFilter, PublicKey } from '@solana/web3.js'
-import { Action } from '../types/action.types'
 import {
   buildBorrowTransaction,
   buildBuyTransaction,
@@ -37,6 +36,16 @@ import {
   SellQuoteResult,
   TransactionResult,
 } from 'torchsdk'
+
+import { MapperProvider } from './mapper.provider'
+import {
+  buildCreateFactionTransaction,
+  getBondingCurvePda,
+  getTokenTreasuryPda,
+  getTreasuryLockPda,
+  isPyreMint,
+} from '../vanity'
+import { isBlacklistedMint } from '../util'
 import {
   AgentLink,
   AllWarLoansResult,
@@ -74,19 +83,15 @@ import {
   WithdrawAssetsParams,
   WithdrawFromStrongholdParams,
 } from '../types'
-import { MapperProvider } from './mapper.provider'
-import {
-  buildCreateFactionTransaction,
-  getBondingCurvePda,
-  getTokenTreasuryPda,
-  getTreasuryLockPda,
-  isPyreMint,
-} from '../vanity'
-import { isBlacklistedMint } from '../util'
+import { Action } from '../types/action.types'
+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 +427,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/intel.provider.ts

@@ -1,5 +1,7 @@
 import { Connection, PublicKey } from '@solana/web3.js'
-import { MapperProvider } from './mapper.provider'
+
+import { getBondingCurvePda, getTokenTreasuryPda, getTreasuryLockPda, isPyreMint } from '../vanity'
+import { isBlacklistedMint } from '../util'
 import {
   AgentFactionPosition,
   AgentProfile,
@@ -13,8 +15,6 @@ import {
   RivalFaction,
 } from '../types'
 import { Intel } from '../types/intel.types'
-import { getBondingCurvePda, getTokenTreasuryPda, getTreasuryLockPda, isPyreMint } from '../vanity'
-import { isBlacklistedMint } from '../util'
 import { Action } from '../types/action.types'
 
 export class IntelProvider implements Intel {

package/src/providers/mapper.provider.ts

@@ -1,9 +1,3 @@
-/**
- * Pyre Kit Mappers
- *
- * Internal mapping functions between Torch SDK types and Pyre game types.
- */
-
 import type {
   AllLoanPositionsResult,
   BuyTransactionResult,

package/src/providers/registry.provider.ts

@@ -1,14 +1,7 @@
-/**
- * Pyre World Agent Registry Provider
- *
- * On-chain agent identity and state persistence.
- * Agents checkpoint their action distributions and personality summaries
- * so any machine with the wallet key can reconstruct the agent.
- */
-
 import { Connection, PublicKey, Transaction, SystemProgram } from '@solana/web3.js'
 import { BN, Program, AnchorProvider, type Wallet } from '@coral-xyz/anchor'
 import type { TransactionResult } from 'torchsdk'
+
 import type {
   RegistryProfile,
   RegistryWalletLink,
@@ -18,20 +11,14 @@ import type {
   UnlinkAgentWalletParams,
   TransferAgentAuthorityParams,
 } from '../types'
+import { Registry } from '../types/registry.types'
 
 import idl from '../pyre_world.json'
 
-// ─── Program ID ─────────────────────────────────────────────────────
-
 export const REGISTRY_PROGRAM_ID = new PublicKey(idl.address)
-
-// ─── PDA Seeds ──────────────────────────────────────────────────────
-
 const AGENT_SEED = 'pyre_agent'
 const AGENT_WALLET_SEED = 'pyre_agent_wallet'
 
-// ─── PDA Helpers ────────────────────────────────────────────────────
-
 export function getAgentProfilePda(creator: PublicKey): [PublicKey, number] {
   return PublicKey.findProgramAddressSync(
     [Buffer.from(AGENT_SEED), creator.toBuffer()],
@@ -46,8 +33,6 @@ export function getAgentWalletLinkPda(wallet: PublicKey): [PublicKey, number] {
   )
 }
 
-// ─── Anchor Program Helper ──────────────────────────────────────────
-
 function makeDummyProvider(connection: Connection, payer: PublicKey): AnchorProvider {
   const dummyWallet = {
     publicKey: payer,
@@ -67,9 +52,7 @@ async function finalizeTransaction(
   tx.feePayer = feePayer
 }
 
-// ─── Provider ───────────────────────────────────────────────────────
-
-export class RegistryProvider {
+export class RegistryProvider implements Registry {
   constructor(private connection: Connection) {}
 
   private getProgram(payer: PublicKey): Program {
@@ -77,9 +60,7 @@ export class RegistryProvider {
     return new Program(idl as any, provider)
   }
 
-  // ─── 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 +94,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,12 +113,10 @@ export class RegistryProvider {
         bump: account.bump,
       }
     } catch {
-      return null
+      return undefined
     }
   }
 
-  // ─── Transaction Builders ─────────────────────────────────────────
-
   async register(params: RegisterAgentParams): Promise<TransactionResult> {
     const creator = new PublicKey(params.creator)
     const [profile] = getAgentProfilePda(creator)

package/src/providers/state.provider.ts

@@ -1,12 +1,7 @@
-/**
- * Pyre Kit State Provider
- *
- * Objective game state tracking for an agent.
- * Owns holdings, action counts, vault resolution, tick counter.
- * Injected into ActionProvider so every action automatically updates state.
- */
-
 import { Connection, PublicKey } from '@solana/web3.js'
+
+import { isPyreMint } from '../vanity'
+import { isBlacklistedMint } from '../util'
 import type {
   State,
   AgentGameState,
@@ -14,9 +9,7 @@ import type {
   TrackedAction,
   CheckpointConfig,
 } from '../types/state.types'
-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,
@@ -42,12 +35,10 @@ export class StateProvider implements State {
 
   constructor(
     private connection: Connection,
+    private registry: Registry,
     private publicKey: string,
-    private registry: RegistryProvider,
   ) {}
 
-  // ─── Readonly accessors ─────────────────────────────────────────
-
   get state() {
     return this._state
   }
@@ -61,15 +52,11 @@ export class StateProvider implements State {
     return this._state?.tick ?? 0
   }
 
-  // ─── Configuration ──────────────────────────────────────────────
-
   /** Configure auto-checkpoint behavior */
   setCheckpointConfig(config: CheckpointConfig) {
     this.checkpointConfig = config
   }
 
-  // ─── Initialization ─────────────────────────────────────────────
-
   async init(): Promise<AgentGameState> {
     if (this._state?.initialized) return this._state
 
@@ -94,7 +81,7 @@ export class StateProvider implements State {
 
     this._state = state
 
-    // Resolve vault link
+    // resolve vault link
     const { getVaultForWallet } = await import('torchsdk')
     try {
       const vault = await getVaultForWallet(this.connection, this.publicKey)
@@ -115,14 +102,13 @@ export class StateProvider implements State {
       }
     } catch {}
 
-    // Load registry profile — personality, action counts, SOL totals
     try {
       const profile = await this.registry.getProfile(this.publicKey)
       if (profile) {
         state.personalitySummary = profile.personality_summary || null
         state.totalSolSpent = profile.total_sol_spent
         state.totalSolReceived = profile.total_sol_received
-        // Seed action counts from on-chain checkpoint
+
         state.actionCounts.join = Math.max(state.actionCounts.join, profile.joins)
         state.actionCounts.defect = Math.max(state.actionCounts.defect, profile.defects)
         state.actionCounts.rally = Math.max(state.actionCounts.rally, profile.rallies)
@@ -137,21 +123,17 @@ export class StateProvider implements State {
         state.actionCounts.ascend = Math.max(state.actionCounts.ascend, profile.ascends)
         state.actionCounts.raze = Math.max(state.actionCounts.raze, profile.razes)
         state.actionCounts.tithe = Math.max(state.actionCounts.tithe, profile.tithes)
-        // Set tick to total actions from checkpoint
+
         const totalFromCheckpoint = Object.values(state.actionCounts).reduce((a, b) => a + b, 0)
         state.tick = totalFromCheckpoint
       }
     } catch {}
 
-    // Load holdings (wallet + vault token accounts)
     await this.refreshHoldings()
-
     state.initialized = true
     return state
   }
 
-  // ─── Action Recording ───────────────────────────────────────────
-
   async record(action: TrackedAction, mint?: string, description?: string): Promise<void> {
     if (!this._state) throw new Error('State not initialized — call init() first')
 
@@ -159,17 +141,14 @@ export class StateProvider implements State {
     this._state.actionCounts[action]++
     this.ticksSinceCheckpoint++
 
-    // Track founded factions
     if (action === 'launch' && mint) {
       this._state.founded.push(mint)
     }
 
-    // Update sentiment for the target faction
     if (mint) {
       this.updateSentiment(action, mint)
     }
 
-    // Track recent history for LLM memory block
     if (description) {
       this._state.recentHistory.push(description)
       if (this._state.recentHistory.length > 20) {
@@ -177,22 +156,16 @@ export class StateProvider implements State {
       }
     }
 
-    // Refresh holdings after any trade action
     await this.refreshHoldings()
-
-    // Auto-checkpoint check
     if (this.checkpointConfig && this.ticksSinceCheckpoint >= this.checkpointConfig.interval) {
       this.ticksSinceCheckpoint = 0
       this.onCheckpointDue?.()
     }
   }
 
-  /** Update sentiment score for a faction based on action type */
   private updateSentiment(action: TrackedAction, mint: string): void {
     if (!this._state) return
-
     const current = this._state.sentiment.get(mint) ?? 0
-
     const SENTIMENT_DELTAS: Partial<Record<TrackedAction, number>> = {
       join: 1,
       reinforce: 1.5,
@@ -211,18 +184,14 @@ export class StateProvider implements State {
     }
   }
 
-  /** Callback set by PyreKit to handle checkpoint triggers */
   onCheckpointDue: (() => void) | null = null
 
-  // ─── Holdings ───────────────────────────────────────────────────
-
   async refreshHoldings(): Promise<void> {
     if (!this._state) return
 
     const { TOKEN_2022_PROGRAM_ID } = await import('@solana/spl-token')
     const walletPk = new PublicKey(this.publicKey)
 
-    // Scan wallet token accounts
     let walletValues: any[] = []
     try {
       const walletAccounts = await this.connection.getParsedTokenAccountsByOwner(walletPk, {
@@ -231,7 +200,6 @@ export class StateProvider implements State {
       walletValues = walletAccounts.value
     } catch {}
 
-    // Scan vault token accounts
     let vaultValues: any[] = []
     if (this._state.stronghold) {
       try {
@@ -243,7 +211,6 @@ export class StateProvider implements State {
       } catch {}
     }
 
-    // Merge balances
     const newHoldings = new Map<string, number>()
     for (const a of [...walletValues, ...vaultValues]) {
       const mint = a.account.data.parsed.info.mint as string
@@ -253,7 +220,6 @@ export class StateProvider implements State {
       }
     }
 
-    // Update — clear stale, set fresh
     this._state.holdings.clear()
     for (const [mint, balance] of newHoldings) {
       this._state.holdings.set(mint, balance)
@@ -276,8 +242,6 @@ export class StateProvider implements State {
     return this._state?.holdings.get(mint) ?? 0
   }
 
-  // ─── Dedup Guards ───────────────────────────────────────────────
-
   hasVoted(mint: string): boolean {
     return this._state?.voted.has(mint) ?? false
   }
@@ -294,8 +258,6 @@ export class StateProvider implements State {
     this._state?.rallied.add(mint)
   }
 
-  // ─── Serialization ──────────────────────────────────────────────
-
   serialize(): SerializedGameState {
     if (!this._state) {
       return {

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>
+}

package/tests/test_e2e.ts

@@ -345,6 +345,28 @@ async function main() {
   assert(kitRestored.state.state!.actionCounts.defect === kit.state.state!.actionCounts.defect, `hydrated defect count matches`)
   assert(kitRestored.state.history.length === kit.state.history.length, `hydrated history length matches: ${kitRestored.state.history.length}`)
 
+  // ═══════════════════════════════════════════════════════════════════
+  // TEST: SCOUT
+  // ═══════════════════════════════════════════════════════════════════
+
+  console.log('\n═══ TEST: Scout ═══')
+  // Scout agent 1 from agent 2's perspective
+  const scoutResult = await kit2.actions.scout(agent.publicKey)
+  console.log(`  ${scoutResult}`)
+  assert(typeof scoutResult === 'string', `scout returns string`)
+  assert(scoutResult.includes(agent.publicKey.slice(0, 8)), `scout result contains target address: ${agent.publicKey.slice(0, 8)}`)
+
+  // Scout a nonexistent address
+  const fakeAddress = 'FakeAddress1111111111111111111111111111111111'
+  const scoutFake = await kit2.actions.scout(fakeAddress)
+  console.log(`  ${scoutFake}`)
+  assert(scoutFake.includes('no pyre identity') || scoutFake.includes('lookup failed'), `scout handles unknown agent`)
+
+  // Scout via exec (read-only — no tick increment)
+  const { result: scoutExecResult } = await kit2.exec('actions', 'scout', agent.publicKey)
+  console.log(`  exec scout: ${scoutExecResult}`)
+  assert(kit2.state.tick === 2, `agent 2 tick unchanged after scout (read-only): ${kit2.state.tick}`)
+
   // ═══════════════════════════════════════════════════════════════════
   // TEST: MEMBERS
   // ═══════════════════════════════════════════════════════════════════