pyre-world-kit 3.0.0 → 3.0.1

package/dist/index.d.ts

@@ -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

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pyre-world-kit",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "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

@@ -42,19 +42,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 +68,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 */