@agent-shield/plugin-solana-agent-kit 0.1.2 → 0.3.0

package/README.md

@@ -1,77 +1,219 @@
 # @agent-shield/plugin-solana-agent-kit
 
-AgentShield plugin for [Solana Agent Kit](https://github.com/sendaifun/solana-agent-kit) — routes agent DeFi actions through permission-guarded vaults with spending limits, token whitelists, and leverage controls.
+AgentShield plugin for [Solana Agent Kit](https://github.com/sendaifun/solana-agent-kit) — adds shield monitoring, management, and transaction history tools to any SAK agent. The shield wraps wallet signing transparently, so SAK's built-in swap/position tools are automatically policy-guarded without any code changes.
 
 ## Installation
 
 ```bash
-npm install @agent-shield/plugin-solana-agent-kit @agent-shield/sdk
+npm install @agent-shield/plugin-solana-agent-kit @agent-shield/solana
 ```
 
-Peer dependencies: `solana-agent-kit >=2.0.0`, `@agent-shield/sdk >=0.1.0`, `@solana/web3.js >=1.90.0`, `@coral-xyz/anchor >=0.30.0`
+Peer dependencies: `solana-agent-kit >=2.0.0`, `@agent-shield/solana >=0.1.0`, `@solana/web3.js >=1.90.0`
 
 ## Quick Start
 
+### Option A: Pre-created ShieldedWallet
+
 ```typescript
+import { shield } from "@agent-shield/solana";
 import { createAgentShieldPlugin } from "@agent-shield/plugin-solana-agent-kit";
 import { SolanaAgentKit } from "solana-agent-kit";
-import { PublicKey } from "@solana/web3.js";
-import { BN } from "@coral-xyz/anchor";
 
+// 1. Wrap your wallet with spending controls
+const protectedWallet = shield(wallet, { maxSpend: "500 USDC/day" });
+
+// 2. Create the plugin (provides monitoring tools)
+const plugin = createAgentShieldPlugin({ wallet: protectedWallet });
+
+// 3. Create the agent — all actions are now policy-guarded
+const agent = new SolanaAgentKit(protectedWallet, rpcUrl, {
+  plugins: [plugin],
+});
+```
+
+### Option B: Factory (auto-creates ShieldedWallet)
+
+```typescript
+import { createAgentShieldPlugin } from "@agent-shield/plugin-solana-agent-kit";
+
+// Pass a raw wallet + policies — the plugin creates the ShieldedWallet for you
 const plugin = createAgentShieldPlugin({
-  vaultOwner: new PublicKey("..."),  // vault owner pubkey
-  vaultId: new BN(1),               // vault identifier
+  rawWallet: keypairWallet,
+  policies: { maxSpend: "500 USDC/day" },
+  logger: console,
 });
 
-const agent = new SolanaAgentKit(wallet, rpcUrl, {
-  plugins: [plugin],
+// Event callbacks (onDenied, onApproved, onPause, onResume, onPolicyUpdate)
+// are automatically wired to the logger
+```
+
+### Standalone Factory
+
+```typescript
+import { createShieldedWallet } from "@agent-shield/plugin-solana-agent-kit";
+
+const protectedWallet = createShieldedWallet({
+  wallet: keypairWallet,
+  policies: { maxSpend: "500 USDC/day" },
+  logger: console,
+  options: {
+    onDenied: (err) => alertService.notify(err.message),
+  },
 });
 ```
 
 ## Tools
 
-The plugin registers 6 tools on the agent:
-
-### Trading
+The plugin registers 4 monitoring/management tools on the agent:
 
 | Tool | Description | Parameters |
 |------|-------------|------------|
-| `shield_swap` | Execute a token swap through Jupiter, routed through the AgentShield vault with policy enforcement | `inputMint`, `outputMint`, `amount`, `slippageBps` |
-| `shield_open_position` | Open a leveraged perpetual position on Flash Trade. Enforces leverage limits and position count caps | `collateralMint`, `targetMint`, `collateralAmount`, `side`, `leverage` |
-| `shield_close_position` | Close an existing perpetual position on Flash Trade | `positionMint`, `targetMint`, `side` |
+| `shield_status` | Check current spending vs limits, rate limit usage, and enforcement state | *(none)* |
+| `shield_update_policy` | Update spending limits or program blocking at runtime | `maxSpend?`, `blockUnknownPrograms?` |
+| `shield_pause_resume` | Pause or resume policy enforcement | `action: "pause" \| "resume"` |
+| `shield_transaction_history` | View per-token usage percentages and rate limit summary | *(none)* |
 
-### Read-Only
+### Tool Details
 
-| Tool | Description | Parameters |
-|------|-------------|------------|
-| `shield_check_policy` | Read the vault policy: spending caps, allowed tokens/protocols, leverage limits, fee BPS | *(none)* |
-| `shield_check_balance` | Read vault balances, status, and statistics (total volume, open positions, fees collected) | *(none)* |
-| `shield_check_spending` | Read the rolling 24h spending tracker: per-token spend vs daily cap, recent transaction history | *(none)* |
+#### `shield_status`
+
+Returns a formatted status report including:
+- Whether enforcement is paused or active
+- Per-token spending vs limits (with percentage used and window duration)
+- Remaining budget per token
+- Rate limit usage (transaction count vs limit, remaining, window)
+
+**Example output:**
+```
+=== AgentShield Status ===
+Paused: false
+
+--- Spending Limits ---
+  USDC: 200000000 / 500000000 (40% used, 24h window)
+    Remaining: 300000000
+  SOL: 1000000000 / 10000000000 (10% used, 24h window)
+    Remaining: 9000000000
+
+--- Rate Limit ---
+  Transactions: 5 / 60 (55 remaining)
+  Window: 1h
+```
+
+#### `shield_update_policy`
+
+Updates shield policies at runtime. Both parameters are optional — only provided fields are changed.
+
+**Schema:**
+```typescript
+{
+  maxSpend?: string;              // e.g. "1000 USDC/day"
+  blockUnknownPrograms?: boolean; // true or false
+}
+```
+
+#### `shield_pause_resume`
+
+Toggles enforcement on or off. When paused, transactions pass through without policy checks or spend recording.
+
+**Schema:**
+```typescript
+{
+  action: "pause" | "resume";
+}
+```
+
+#### `shield_transaction_history`
+
+Returns a detailed per-token usage summary with percentages and rolling window information, plus rate limit status.
+
+**Example output:**
+```
+=== AgentShield Transaction History ===
+Enforcement: ACTIVE
+
+--- Per-Token Usage ---
+  USDC:
+    Spent: 200000000 / 500000000
+    Usage: 40%
+    Remaining: 300000000
+    Window: 24h rolling
+
+--- Rate Limit ---
+  Transactions: 5 / 60
+  Remaining: 55
+  Window: 1h
+```
 
 ## Configuration
 
 ```typescript
 interface AgentShieldPluginConfig {
-  /** Vault owner public key */
-  vaultOwner: PublicKey;
-  /** Vault identifier (u64) */
-  vaultId: BN;
-  /** Optional program ID override (defaults to mainnet deployment) */
-  programId?: PublicKey;
+  // Option A: Pre-created ShieldedWallet
+  wallet?: ShieldedWallet;
+
+  // Option B: Auto-create from raw wallet
+  rawWallet?: WalletLike;
+  policies?: ShieldPolicies;
+  logger?: { info?: Function; warn?: Function };
+  options?: ShieldOptions;
 }
 ```
 
-The plugin creates an `AgentShieldClient` on initialization using the agent's connection and wallet. The client is cached per agent instance.
+You must provide either `wallet` or `rawWallet`. If both are provided, `wallet` takes precedence.
+
+When using `rawWallet`, the factory automatically wires event callbacks to the logger:
+- `onDenied` logs warnings with the denial reason
+- `onApproved`, `onPause`, `onResume`, `onPolicyUpdate` log info messages
+- Any callbacks in `options` are chained after logger callbacks
+
+## Exported Functions
+
+| Export | Description |
+|--------|-------------|
+| `createAgentShieldPlugin(config)` | Create the SAK plugin with 4 tools |
+| `createShieldedWallet(config)` | Standalone factory for ShieldedWallet creation |
+| `resolveWallet(config)` | Resolve config to a `{ wallet: ShieldedWallet }` |
+| `status(agent, config, input)` | Status tool handler (for custom use) |
+| `updatePolicy(agent, config, input)` | Update policy tool handler |
+| `pauseResume(agent, config, input)` | Pause/resume tool handler |
+| `transactionHistory(agent, config, input)` | Transaction history tool handler |
+
+All Zod schemas are also exported: `statusSchema`, `updatePolicySchema`, `pauseResumeSchema`, `transactionHistorySchema`.
 
 ## How It Works
 
-All trading tools (`shield_swap`, `shield_open_position`, `shield_close_position`) build atomic composed transactions:
+The `shield()` wrapper intercepts `signTransaction` and `signAllTransactions` on the wallet. When the agent calls any SAK tool (swap, transfer, open position, etc.), the transaction passes through the shield's policy engine before signing. If a policy is violated (spending cap, rate limit, unknown program, etc.), the transaction is rejected with a descriptive `ShieldDeniedError`.
 
+The plugin's tools give the agent visibility into spending state and the ability to manage enforcement — no DeFi execution tools are needed since the shield guards signing transparently.
+
+```
+Agent calls swap() → SAK builds transaction → shield() intercepts signTransaction
+                                                  ↓
+                                        Policy engine evaluates:
+                                        • Spending cap check
+                                        • Rate limit check
+                                        • Protocol allowlist
+                                        • Token allowlist
+                                                  ↓
+                                        Pass → sign with inner wallet
+                                        Fail → throw ShieldDeniedError
 ```
-[ValidateAndAuthorize, DeFi instruction(s), FinalizeSession]
+
+## Testing
+
+```bash
+npm test
+# Runs 23 tests covering all tools, factory, config resolution, and event wiring
 ```
 
-The on-chain program checks the agent's action against the vault policy (spending cap, token whitelist, protocol whitelist, leverage limits) before the DeFi instruction executes. If any check fails, the entire transaction reverts.
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@agent-shield/solana`](https://www.npmjs.com/package/@agent-shield/solana) | Core wallet wrapper (required) |
+| [`@agent-shield/core`](https://www.npmjs.com/package/@agent-shield/core) | Pure TypeScript policy engine |
+| [`@agent-shield/plugin-elizaos`](https://www.npmjs.com/package/@agent-shield/plugin-elizaos) | ElizaOS integration |
+| [`@agent-shield/sdk`](https://www.npmjs.com/package/@agent-shield/sdk) | On-chain vault SDK |
 
 ## License
 

package/dist/factory.d.ts

@@ -0,0 +1,29 @@
+import { type ShieldedWallet, type WalletLike, type ShieldPolicies, type ShieldOptions } from "@agent-shield/solana";
+export interface FactoryConfig {
+    /** Raw wallet to wrap with shield(). */
+    wallet: WalletLike;
+    /** Shield policies (string shorthand or full config). */
+    policies?: ShieldPolicies;
+    /** Optional logger for shield event callbacks. */
+    logger?: {
+        info?: (...args: any[]) => void;
+        warn?: (...args: any[]) => void;
+    };
+    /** Additional ShieldOptions (storage, custom callbacks). */
+    options?: ShieldOptions;
+}
+/**
+ * Convenience factory that creates a ShieldedWallet from a raw wallet.
+ * Auto-wires event callbacks to the provided logger.
+ *
+ * @example
+ * ```ts
+ * const wallet = createShieldedWallet({
+ *   wallet: keypairWallet,
+ *   policies: { maxSpend: '500 USDC/day' },
+ *   logger: console,
+ * });
+ * ```
+ */
+export declare function createShieldedWallet(config: FactoryConfig): ShieldedWallet;
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,MAAM,EAAE,UAAU,CAAC;IACnB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,kDAAkD;IAClD,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;QAChC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAC;KACjC,CAAC;IACF,4DAA4D;IAC5D,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CA8B1E"}

package/dist/factory.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createShieldedWallet = createShieldedWallet;
+const solana_1 = require("@agent-shield/solana");
+/**
+ * Convenience factory that creates a ShieldedWallet from a raw wallet.
+ * Auto-wires event callbacks to the provided logger.
+ *
+ * @example
+ * ```ts
+ * const wallet = createShieldedWallet({
+ *   wallet: keypairWallet,
+ *   policies: { maxSpend: '500 USDC/day' },
+ *   logger: console,
+ * });
+ * ```
+ */
+function createShieldedWallet(config) {
+    const log = config.logger ?? console;
+    const info = log.info ?? console.info;
+    const warn = log.warn ?? console.warn;
+    const options = {
+        ...config.options,
+        onDenied: (error) => {
+            warn("[AgentShield] Transaction denied:", error.message);
+            config.options?.onDenied?.(error);
+        },
+        onApproved: (txHash) => {
+            info("[AgentShield] Transaction approved", txHash ?? "");
+            config.options?.onApproved?.(txHash);
+        },
+        onPause: () => {
+            info("[AgentShield] Enforcement paused");
+            config.options?.onPause?.();
+        },
+        onResume: () => {
+            info("[AgentShield] Enforcement resumed");
+            config.options?.onResume?.();
+        },
+        onPolicyUpdate: (policies) => {
+            info("[AgentShield] Policies updated");
+            config.options?.onPolicyUpdate?.(policies);
+        },
+    };
+    return (0, solana_1.shield)(config.wallet, config.policies, options);
+}
+//# sourceMappingURL=factory.js.map

package/dist/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":";;AAmCA,oDA8BC;AAjED,iDAM8B;AAgB9B;;;;;;;;;;;;GAYG;AACH,SAAgB,oBAAoB,CAAC,MAAqB;IACxD,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC;IACrC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IACtC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAEtC,MAAM,OAAO,GAAkB;QAC7B,GAAG,MAAM,CAAC,OAAO;QACjB,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE;YAClB,IAAI,CAAC,mCAAmC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;YACzD,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QACD,UAAU,EAAE,CAAC,MAAM,EAAE,EAAE;YACrB,IAAI,CAAC,oCAAoC,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC;YACzD,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC,MAAM,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,EAAE,GAAG,EAAE;YACZ,IAAI,CAAC,kCAAkC,CAAC,CAAC;YACzC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;QAC9B,CAAC;QACD,QAAQ,EAAE,GAAG,EAAE;YACb,IAAI,CAAC,mCAAmC,CAAC,CAAC;YAC1C,MAAM,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,CAAC;QAC/B,CAAC;QACD,cAAc,EAAE,CAAC,QAAQ,EAAE,EAAE;YAC3B,IAAI,CAAC,gCAAgC,CAAC,CAAC;YACvC,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC,QAAQ,CAAC,CAAC;QAC7C,CAAC;KACF,CAAC;IAEF,OAAO,IAAA,eAAM,EAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AACzD,CAAC"}

package/dist/index.d.ts

@@ -1,21 +1,26 @@
 import { AgentShieldPluginConfig } from "./types";
-export { AgentShieldPluginConfig } from "./types";
-export { getOrCreateClient } from "./client-factory";
+export { AgentShieldPluginConfig, ResolvedConfig, resolveWallet, } from "./types";
+export { createShieldedWallet, type FactoryConfig } from "./factory";
 export * from "./tools";
 /**
  * Creates the AgentShield plugin for Solana Agent Kit.
  *
- * Usage:
+ * Usage with pre-created wallet:
  * ```ts
- * import { createAgentShieldPlugin } from "@agent-shield/plugin-solana-agent-kit";
+ * import { shield } from '@agent-shield/solana';
+ * import { createAgentShieldPlugin } from '@agent-shield/plugin-solana-agent-kit';
  *
- * const plugin = createAgentShieldPlugin({
- *   vaultOwner: ownerPubkey,
- *   vaultId: new BN(1),
- * });
+ * const protectedWallet = shield(wallet, { maxSpend: '500 USDC/day' });
+ * const plugin = createAgentShieldPlugin({ wallet: protectedWallet });
+ * const agent = new SolanaAgentKit(protectedWallet, RPC_URL, { plugins: [plugin] });
+ * ```
  *
- * const agent = new SolanaAgentKit(wallet, rpcUrl, {
- *   plugins: [plugin],
+ * Usage with factory (auto-creates ShieldedWallet):
+ * ```ts
+ * const plugin = createAgentShieldPlugin({
+ *   rawWallet: keypairWallet,
+ *   policies: { maxSpend: '500 USDC/day' },
+ *   logger: console,
  * });
  * ```
  */
@@ -23,118 +28,41 @@ export declare function createAgentShieldPlugin(config: AgentShieldPluginConfig)
     name: string;
     description: string;
     methods: {
-        shield_swap: {
+        shield_status: {
             description: string;
-            schema: import("zod").ZodObject<{
-                inputMint: import("zod").ZodString;
-                outputMint: import("zod").ZodString;
-                amount: import("zod").ZodString;
-                slippageBps: import("zod").ZodDefault<import("zod").ZodOptional<import("zod").ZodNumber>>;
-            }, "strip", import("zod").ZodTypeAny, {
-                inputMint: string;
-                outputMint: string;
-                amount: string;
-                slippageBps: number;
-            }, {
-                inputMint: string;
-                outputMint: string;
-                amount: string;
-                slippageBps?: number | undefined;
-            }>;
+            schema: import("zod").ZodObject<{}, "strip", import("zod").ZodTypeAny, {}, {}>;
             handler: (agent: any, input: any) => Promise<string>;
         };
-        shield_open_position: {
+        shield_update_policy: {
             description: string;
             schema: import("zod").ZodObject<{
-                targetSymbol: import("zod").ZodString;
-                collateralSymbol: import("zod").ZodString;
-                collateralAmount: import("zod").ZodString;
-                sizeAmount: import("zod").ZodString;
-                side: import("zod").ZodEnum<["long", "short"]>;
-                leverageBps: import("zod").ZodNumber;
-                price: import("zod").ZodString;
-                priceExponent: import("zod").ZodNumber;
+                maxSpend: import("zod").ZodOptional<import("zod").ZodString>;
+                blockUnknownPrograms: import("zod").ZodOptional<import("zod").ZodBoolean>;
             }, "strip", import("zod").ZodTypeAny, {
-                targetSymbol: string;
-                collateralSymbol: string;
-                collateralAmount: string;
-                sizeAmount: string;
-                side: "long" | "short";
-                leverageBps: number;
-                price: string;
-                priceExponent: number;
+                maxSpend?: string | undefined;
+                blockUnknownPrograms?: boolean | undefined;
             }, {
-                targetSymbol: string;
-                collateralSymbol: string;
-                collateralAmount: string;
-                sizeAmount: string;
-                side: "long" | "short";
-                leverageBps: number;
-                price: string;
-                priceExponent: number;
+                maxSpend?: string | undefined;
+                blockUnknownPrograms?: boolean | undefined;
             }>;
             handler: (agent: any, input: any) => Promise<string>;
         };
-        shield_close_position: {
+        shield_pause_resume: {
             description: string;
             schema: import("zod").ZodObject<{
-                targetSymbol: import("zod").ZodString;
-                collateralSymbol: import("zod").ZodString;
-                collateralAmount: import("zod").ZodString;
-                side: import("zod").ZodEnum<["long", "short"]>;
-                price: import("zod").ZodString;
-                priceExponent: import("zod").ZodNumber;
+                action: import("zod").ZodEnum<["pause", "resume"]>;
             }, "strip", import("zod").ZodTypeAny, {
-                targetSymbol: string;
-                collateralSymbol: string;
-                collateralAmount: string;
-                side: "long" | "short";
-                price: string;
-                priceExponent: number;
+                action: "pause" | "resume";
             }, {
-                targetSymbol: string;
-                collateralSymbol: string;
-                collateralAmount: string;
-                side: "long" | "short";
-                price: string;
-                priceExponent: number;
+                action: "pause" | "resume";
             }>;
             handler: (agent: any, input: any) => Promise<string>;
         };
-        shield_check_policy: {
+        shield_transaction_history: {
             description: string;
-            schema: import("zod").ZodObject<{
-                vaultAddress: import("zod").ZodOptional<import("zod").ZodString>;
-            }, "strip", import("zod").ZodTypeAny, {
-                vaultAddress?: string | undefined;
-            }, {
-                vaultAddress?: string | undefined;
-            }>;
-            handler: (agent: any, input: any) => Promise<string>;
-        };
-        shield_check_balance: {
-            description: string;
-            schema: import("zod").ZodObject<{
-                vaultAddress: import("zod").ZodOptional<import("zod").ZodString>;
-            }, "strip", import("zod").ZodTypeAny, {
-                vaultAddress?: string | undefined;
-            }, {
-                vaultAddress?: string | undefined;
-            }>;
-            handler: (agent: any, input: any) => Promise<string>;
-        };
-        shield_check_spending: {
-            description: string;
-            schema: import("zod").ZodObject<{
-                vaultAddress: import("zod").ZodOptional<import("zod").ZodString>;
-            }, "strip", import("zod").ZodTypeAny, {
-                vaultAddress?: string | undefined;
-            }, {
-                vaultAddress?: string | undefined;
-            }>;
+            schema: import("zod").ZodObject<{}, "strip", import("zod").ZodTypeAny, {}, {}>;
             handler: (agent: any, input: any) => Promise<string>;
         };
     };
-    initialize: (agent: any) => void;
 };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAUlD,OAAO,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,cAAc,SAAS,CAAC;AAExB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,uBAAuB;;;;;;;;;;;;;;;;;;;;;;6BAc9C,GAAG,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BAOf,GAAG,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;6BAMf,GAAG,SAAS,GAAG;;;;;;;;;;;6BAOf,GAAG,SAAS,GAAG;;;;;;;;;;;6BAOf,GAAG,SAAS,GAAG;;;;;;;;;;;6BAOf,GAAG,SAAS,GAAG;;;wBAIhB,GAAG;EAM1B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAiB,MAAM,SAAS,CAAC;AAYjE,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,oBAAoB,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AACrE,cAAc,SAAS,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,uBAAuB;;;;;;;6BAiB9C,GAAG,SAAS,GAAG;;;;;;;;;;;;;;6BAOf,GAAG,SAAS,GAAG;;;;;;;;;;;6BAQf,GAAG,SAAS,GAAG;;;;;6BAQf,GAAG,SAAS,GAAG;;;EAKvC"}

package/dist/index.js

@@ -14,76 +14,70 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getOrCreateClient = void 0;
+exports.createShieldedWallet = exports.resolveWallet = void 0;
 exports.createAgentShieldPlugin = createAgentShieldPlugin;
+const types_1 = require("./types");
 const tools_1 = require("./tools");
-var client_factory_1 = require("./client-factory");
-Object.defineProperty(exports, "getOrCreateClient", { enumerable: true, get: function () { return client_factory_1.getOrCreateClient; } });
+var types_2 = require("./types");
+Object.defineProperty(exports, "resolveWallet", { enumerable: true, get: function () { return types_2.resolveWallet; } });
+var factory_1 = require("./factory");
+Object.defineProperty(exports, "createShieldedWallet", { enumerable: true, get: function () { return factory_1.createShieldedWallet; } });
 __exportStar(require("./tools"), exports);
 /**
  * Creates the AgentShield plugin for Solana Agent Kit.
  *
- * Usage:
+ * Usage with pre-created wallet:
  * ```ts
- * import { createAgentShieldPlugin } from "@agent-shield/plugin-solana-agent-kit";
+ * import { shield } from '@agent-shield/solana';
+ * import { createAgentShieldPlugin } from '@agent-shield/plugin-solana-agent-kit';
  *
- * const plugin = createAgentShieldPlugin({
- *   vaultOwner: ownerPubkey,
- *   vaultId: new BN(1),
- * });
+ * const protectedWallet = shield(wallet, { maxSpend: '500 USDC/day' });
+ * const plugin = createAgentShieldPlugin({ wallet: protectedWallet });
+ * const agent = new SolanaAgentKit(protectedWallet, RPC_URL, { plugins: [plugin] });
+ * ```
  *
- * const agent = new SolanaAgentKit(wallet, rpcUrl, {
- *   plugins: [plugin],
+ * Usage with factory (auto-creates ShieldedWallet):
+ * ```ts
+ * const plugin = createAgentShieldPlugin({
+ *   rawWallet: keypairWallet,
+ *   policies: { maxSpend: '500 USDC/day' },
+ *   logger: console,
  * });
  * ```
  */
 function createAgentShieldPlugin(config) {
+    const resolved = (0, types_1.resolveWallet)(config);
     return {
         name: "agent-shield",
-        description: "AgentShield — Permission-guarded DeFi vault for AI agents on Solana. " +
-            "Routes swaps through Jupiter and perp trades through Flash Trade, " +
-            "enforcing spending caps, token whitelists, and leverage limits.",
+        description: "AgentShield — Client-side spending controls for AI agents on Solana. " +
+            "Provides monitoring tools to check spending status, update policies, " +
+            "pause/resume enforcement, and view transaction history. " +
+            "Shield wraps signing transparently.",
         methods: {
-            shield_swap: {
-                description: "Execute a token swap through Jupiter, routed through the AgentShield vault " +
-                    "with permission checks and spending limits enforced.",
-                schema: tools_1.swapSchema,
-                handler: (agent, input) => (0, tools_1.swap)(agent, config, input),
-            },
-            shield_open_position: {
-                description: "Open a leveraged perpetual position on Flash Trade through the AgentShield vault. " +
-                    "Enforces leverage limits and position count caps.",
-                schema: tools_1.openPositionSchema,
-                handler: (agent, input) => (0, tools_1.openPosition)(agent, config, input),
+            shield_status: {
+                description: "Check current shield status: spending vs limits, rate limit usage, " +
+                    "and whether enforcement is paused.",
+                schema: tools_1.statusSchema,
+                handler: (agent, input) => (0, tools_1.status)(agent, resolved, input),
             },
-            shield_close_position: {
-                description: "Close an existing perpetual position on Flash Trade through the AgentShield vault.",
-                schema: tools_1.closePositionSchema,
-                handler: (agent, input) => (0, tools_1.closePosition)(agent, config, input),
+            shield_update_policy: {
+                description: "Update shield policies at runtime. Can change spending limits " +
+                    "and unknown program blocking.",
+                schema: tools_1.updatePolicySchema,
+                handler: (agent, input) => (0, tools_1.updatePolicy)(agent, resolved, input),
             },
-            shield_check_policy: {
-                description: "Read the current vault policy: spending caps, allowed tokens/protocols, " +
-                    "leverage limits, and fee configuration.",
-                schema: tools_1.checkPolicySchema,
-                handler: (agent, input) => (0, tools_1.checkPolicy)(agent, config, input),
+            shield_pause_resume: {
+                description: "Pause or resume shield enforcement. When paused, transactions " +
+                    "pass through without policy checks or spend recording.",
+                schema: tools_1.pauseResumeSchema,
+                handler: (agent, input) => (0, tools_1.pauseResume)(agent, resolved, input),
             },
-            shield_check_balance: {
-                description: "Read vault balances, status, and high-level statistics (total volume, " +
-                    "open positions, fees collected).",
-                schema: tools_1.checkBalanceSchema,
-                handler: (agent, input) => (0, tools_1.checkBalance)(agent, config, input),
+            shield_transaction_history: {
+                description: "View recent transaction activity summary — per-token usage " +
+                    "percentages and rate limit status.",
+                schema: tools_1.transactionHistorySchema,
+                handler: (agent, input) => (0, tools_1.transactionHistory)(agent, resolved, input),
             },
-            shield_check_spending: {
-                description: "Read the rolling 24-hour spending tracker: per-token spend vs daily cap, " +
-                    "and recent transaction history.",
-                schema: tools_1.checkSpendingSchema,
-                handler: (agent, input) => (0, tools_1.checkSpending)(agent, config, input),
-            },
-        },
-        initialize: (agent) => {
-            // Eagerly create the client so connection errors surface early
-            const { getOrCreateClient: getClient } = require("./client-factory");
-            getClient(agent, config);
         },
     };
 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AA+BA,0DA0DC;AAxFD,mCAOiB;AAGjB,mDAAqD;AAA5C,mHAAA,iBAAiB,OAAA;AAC1B,0CAAwB;AAExB;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,uBAAuB,CAAC,MAA+B;IACrE,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EACT,uEAAuE;YACvE,oEAAoE;YACpE,iEAAiE;QAEnE,OAAO,EAAE;YACP,WAAW,EAAE;gBACX,WAAW,EACT,6EAA6E;oBAC7E,sDAAsD;gBACxD,MAAM,EAAE,kBAAU;gBAClB,OAAO,EAAE,CAAC,KAAU,EAAE,KAAU,EAAE,EAAE,CAAC,IAAA,YAAI,EAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC;aAChE;YACD,oBAAoB,EAAE;gBACpB,WAAW,EACT,oFAAoF;oBACpF,mDAAmD;gBACrD,MAAM,EAAE,0BAAkB;gBAC1B,OAAO,EAAE,CAAC,KAAU,EAAE,KAAU,EAAE,EAAE,CAAC,IAAA,oBAAY,EAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC;aACxE;YACD,qBAAqB,EAAE;gBACrB,WAAW,EACT,oFAAoF;gBACtF,MAAM,EAAE,2BAAmB;gBAC3B,OAAO,EAAE,CAAC,KAAU,EAAE,KAAU,EAAE,EAAE,CAAC,IAAA,qBAAa,EAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC;aACzE;YACD,mBAAmB,EAAE;gBACnB,WAAW,EACT,0EAA0E;oBAC1E,yCAAyC;gBAC3C,MAAM,EAAE,yBAAiB;gBACzB,OAAO,EAAE,CAAC,KAAU,EAAE,KAAU,EAAE,EAAE,CAAC,IAAA,mBAAW,EAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC;aACvE;YACD,oBAAoB,EAAE;gBACpB,WAAW,EACT,wEAAwE;oBACxE,kCAAkC;gBACpC,MAAM,EAAE,0BAAkB;gBAC1B,OAAO,EAAE,CAAC,KAAU,EAAE,KAAU,EAAE,EAAE,CAAC,IAAA,oBAAY,EAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC;aACxE;YACD,qBAAqB,EAAE;gBACrB,WAAW,EACT,2EAA2E;oBAC3E,iCAAiC;gBACnC,MAAM,EAAE,2BAAmB;gBAC3B,OAAO,EAAE,CAAC,KAAU,EAAE,KAAU,EAAE,EAAE,CAAC,IAAA,qBAAa,EAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC;aACzE;SACF;QAED,UAAU,EAAE,CAAC,KAAU,EAAE,EAAE;YACzB,+DAA+D;YAC/D,MAAM,EAAE,iBAAiB,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;YACrE,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC3B,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AA0CA,0DA6CC;AAvFD,mCAAiE;AACjE,mCASiB;AAEjB,iCAIiB;AADf,sGAAA,aAAa,OAAA;AAEf,qCAAqE;AAA5D,+GAAA,oBAAoB,OAAA;AAC7B,0CAAwB;AAExB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,uBAAuB,CAAC,MAA+B;IACrE,MAAM,QAAQ,GAAG,IAAA,qBAAa,EAAC,MAAM,CAAC,CAAC;IAEvC,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,WAAW,EACT,uEAAuE;YACvE,uEAAuE;YACvE,0DAA0D;YAC1D,qCAAqC;QAEvC,OAAO,EAAE;YACP,aAAa,EAAE;gBACb,WAAW,EACT,qEAAqE;oBACrE,oCAAoC;gBACtC,MAAM,EAAE,oBAAY;gBACpB,OAAO,EAAE,CAAC,KAAU,EAAE,KAAU,EAAE,EAAE,CAAC,IAAA,cAAM,EAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC;aACpE;YACD,oBAAoB,EAAE;gBACpB,WAAW,EACT,gEAAgE;oBAChE,+BAA+B;gBACjC,MAAM,EAAE,0BAAkB;gBAC1B,OAAO,EAAE,CAAC,KAAU,EAAE,KAAU,EAAE,EAAE,CAClC,IAAA,oBAAY,EAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC;aACvC;YACD,mBAAmB,EAAE;gBACnB,WAAW,EACT,gEAAgE;oBAChE,wDAAwD;gBAC1D,MAAM,EAAE,yBAAiB;gBACzB,OAAO,EAAE,CAAC,KAAU,EAAE,KAAU,EAAE,EAAE,CAClC,IAAA,mBAAW,EAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC;aACtC;YACD,0BAA0B,EAAE;gBAC1B,WAAW,EACT,6DAA6D;oBAC7D,oCAAoC;gBACtC,MAAM,EAAE,gCAAwB;gBAChC,OAAO,EAAE,CAAC,KAAU,EAAE,KAAU,EAAE,EAAE,CAClC,IAAA,0BAAkB,EAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC;aAC7C;SACF;KACF,CAAC;AACJ,CAAC"}