pyre-world-kit 3.0.2 → 3.0.4

package/dist/index.d.ts

@@ -6,16 +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 { 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';
-import { Registry } from './types/registry.types';
 export declare class PyreKit {
-    readonly actions: ActionProvider;
-    readonly intel: IntelProvider;
+    readonly connection: Connection;
+    readonly actions: Action;
+    readonly intel: Intel;
     readonly registry: Registry;
     readonly state: StateProvider;
     constructor(connection: Connection, publicKey: string);

package/dist/index.js

@@ -14,11 +14,13 @@ const registry_provider_1 = require("./providers/registry.provider");
 const state_provider_1 = require("./providers/state.provider");
 // ─── Top-level Kit ────────────────────────────────────────────────
 class PyreKit {
+    connection;
     actions;
     intel;
     registry;
     state;
     constructor(connection, publicKey) {
+        this.connection = connection;
         this.registry = new registry_provider_1.RegistryProvider(connection);
         this.state = new state_provider_1.StateProvider(connection, this.registry, publicKey);
         this.actions = new action_provider_1.ActionProvider(connection, this.registry);

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

@@ -1,7 +1,7 @@
 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;

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,10 +1,3 @@
-/**
- * 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';

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);
@@ -108,7 +95,6 @@ class RegistryProvider {
             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,10 +1,3 @@
-/**
- * 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 { Registry } from '../types/registry.types';
@@ -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);
@@ -72,7 +65,6 @@ class StateProvider {
         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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyre-world-kit",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "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,24 +7,29 @@
  */
 
 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 { Registry } from './types/registry.types'
+
+import type { CheckpointConfig, TrackedAction } from './types/state.types'
 
 // ─── Top-level Kit ────────────────────────────────────────────────
 
 export class PyreKit {
-  readonly actions: ActionProvider
-  readonly intel: IntelProvider
+  readonly connection: Connection
+  readonly actions: Action
+  readonly intel: Intel
   readonly registry: Registry
   readonly state: StateProvider
 
   constructor(connection: Connection, publicKey: string) {
+    this.connection = connection
     this.registry = new RegistryProvider(connection)
     this.state = new StateProvider(connection, this.registry, publicKey)
     this.actions = new ActionProvider(connection, this.registry)

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,15 +83,7 @@ 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 {

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,21 +11,14 @@ import type {
   UnlinkAgentWalletParams,
   TransferAgentAuthorityParams,
 } from '../types'
-
-import idl from '../pyre_world.json'
 import { Registry } from '../types/registry.types'
 
-// ─── Program ID ─────────────────────────────────────────────────────
+import idl from '../pyre_world.json'
 
 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()],
@@ -47,8 +33,6 @@ export function getAgentWalletLinkPda(wallet: PublicKey): [PublicKey, number] {
   )
 }
 
-// ─── Anchor Program Helper ──────────────────────────────────────────
-
 function makeDummyProvider(connection: Connection, payer: PublicKey): AnchorProvider {
   const dummyWallet = {
     publicKey: payer,
@@ -68,8 +52,6 @@ async function finalizeTransaction(
   tx.feePayer = feePayer
 }
 
-// ─── Provider ───────────────────────────────────────────────────────
-
 export class RegistryProvider implements Registry {
   constructor(private connection: Connection) {}
 
@@ -78,8 +60,6 @@ export class RegistryProvider implements Registry {
     return new Program(idl as any, provider)
   }
 
-  // ─── Read Operations ──────────────────────────────────────────────
-
   async getProfile(creator: string): Promise<RegistryProfile | undefined> {
     const creatorPk = new PublicKey(creator)
     const [profilePda] = getAgentProfilePda(creatorPk)
@@ -137,8 +117,6 @@ export class RegistryProvider implements Registry {
     }
   }
 
-  // ─── 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,6 @@ 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> = {
@@ -41,9 +33,11 @@ export class StateProvider implements State {
   private checkpointConfig: CheckpointConfig | null = null
   private ticksSinceCheckpoint = 0
 
-  constructor(private connection: Connection, private registry: Registry, private publicKey: string) {}
-
-  // ─── Readonly accessors ─────────────────────────────────────────
+  constructor(
+    private connection: Connection,
+    private registry: Registry,
+    private publicKey: string,
+  ) {}
 
   get state() {
     return this._state
@@ -58,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
 
@@ -91,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)
@@ -112,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)
@@ -134,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')
 
@@ -156,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) {
@@ -174,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,
@@ -208,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, {
@@ -228,7 +200,6 @@ export class StateProvider implements State {
       walletValues = walletAccounts.value
     } catch {}
 
-    // Scan vault token accounts
     let vaultValues: any[] = []
     if (this._state.stronghold) {
       try {
@@ -240,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
@@ -250,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)
@@ -273,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
   }
@@ -291,8 +258,6 @@ export class StateProvider implements State {
     this._state?.rallied.add(mint)
   }
 
-  // ─── Serialization ──────────────────────────────────────────────
-
   serialize(): SerializedGameState {
     if (!this._state) {
       return {

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
   // ═══════════════════════════════════════════════════════════════════