@agent-shield/plugin-elizaos 0.1.2 → 0.3.0

package/README.md

@@ -1,14 +1,14 @@
 # @agent-shield/plugin-elizaos
 
-AgentShield plugin for [ElizaOS](https://github.com/elizaOS/eliza) — provides DeFi actions, vault status providers, and policy evaluators for AI agents operating through permission-guarded Solana vaults.
+AgentShield plugin for [ElizaOS](https://github.com/elizaOS/eliza) — provides shield status actions, pause/resume controls, transaction history, spending providers, and policy evaluators for AI agents with client-side spending controls. Zero on-chain setup required.
 
 ## Installation
 
 ```bash
-npm install @agent-shield/plugin-elizaos @agent-shield/sdk
+npm install @agent-shield/plugin-elizaos @agent-shield/solana
 ```
 
-Peer dependencies: `@elizaos/core >=0.1.0`, `@agent-shield/sdk >=0.1.0`, `@solana/web3.js >=1.90.0`, `@coral-xyz/anchor >=0.30.0`
+Peer dependencies: `@elizaos/core >=0.1.0`, `@agent-shield/solana >=0.1.0`, `@solana/web3.js >=1.90.0`
 
 ## Quick Start
 
@@ -25,52 +25,238 @@ const character = {
 };
 ```
 
+The plugin reads environment variables to create a `ShieldedWallet` automatically. Event callbacks (`onDenied`, `onApproved`, `onPause`, `onResume`, `onPolicyUpdate`) are wired to the ElizaOS runtime logger.
+
 ## Environment Variables
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `AGENT_SHIELD_VAULT_OWNER` | Yes | Vault owner public key (base58) |
-| `AGENT_SHIELD_VAULT_ID` | Yes | Vault identifier (u64 as string) |
-| `SOLANA_RPC_URL` | Yes | Solana RPC endpoint |
-| `SOLANA_WALLET_PRIVATE_KEY` | Yes | Agent wallet private key (base58 or JSON array) |
-| `AGENT_SHIELD_PROGRAM_ID` | No | Custom program ID override |
+| Variable | Required | Description | Default |
+|----------|----------|-------------|---------|
+| `SOLANA_WALLET_PRIVATE_KEY` | Yes | Agent wallet private key (base58 or JSON array) | - |
+| `AGENT_SHIELD_MAX_SPEND` | No | Spending limit string | `"1000 USDC/day"` + `"1000 USDT/day"` + `"10 SOL/day"` |
+| `AGENT_SHIELD_BLOCK_UNKNOWN` | No | Block unknown programs | `"true"` |
+
+**Private key formats supported:**
+- Base58 string: `"4wBqp..."` (standard Solana CLI format)
+- JSON array: `"[104,29,171,...]"` (Uint8Array bytes)
 
 ## Actions
 
-The plugin provides 3 actions that agents can invoke conversationally:
+The plugin provides 4 actions that agents can invoke conversationally:
 
-| Action | Description |
-|--------|-------------|
-| `SHIELD_SWAP` | Execute a token swap through Jupiter, routed through the AgentShield vault with on-chain policy enforcement (spending caps, token whitelists) |
-| `SHIELD_OPEN_POSITION` | Open a leveraged perpetual position on Flash Trade through the vault. Enforces leverage limits and position count caps |
-| `SHIELD_CLOSE_POSITION` | Close an existing perpetual position on Flash Trade through the vault |
+### `SHIELD_STATUS`
+
+**Triggers:** "shield status", "spending status", "budget remaining", "check spending", "how much budget"
+
+Returns current spending summary including enforcement state, per-token usage with percentages, and rate limit status.
+
+**Example conversation:**
+```
+User: "What's my shield spending status?"
+Agent: "=== AgentShield Status ===
+Enforcement: ACTIVE
+
+USDC: 200000000 / 500000000 (40% used)
+  Remaining: 300000000
+
+Rate limit: 5/60 transactions (55 remaining)"
+```
+
+### `SHIELD_UPDATE_POLICY`
+
+**Triggers:** "update policy", "change limit", "change spending cap", "set budget", "update shield"
+
+Updates spending limits or program blocking at runtime.
+
+**Message parameters:**
+- `maxSpend` (string) — new spending limit, e.g. `"1000 USDC/day"`
+- `blockUnknownPrograms` (boolean) — whether to block unknown programs
+
+**Example conversation:**
+```
+User: "Update my shield limit to 1000 USDC per day"
+Agent: "Shield policies updated: maxSpend: 1000 USDC/day"
+```
+
+### `SHIELD_PAUSE_RESUME`
+
+**Triggers:** "pause shield", "resume shield", "pause enforcement", "resume enforcement", "disable shield", "enable shield"
+
+Pauses or resumes policy enforcement. The action infers the intent (pause vs resume) from the message text. When paused, transactions pass through without policy checks or spend recording.
+
+**Example conversations:**
+```
+User: "Pause the shield enforcement"
+Agent: "Shield enforcement paused. Transactions will pass through without policy checks."
+
+User: "Resume shield enforcement"
+Agent: "Shield enforcement resumed. Policy checks are active."
+```
+
+### `SHIELD_TRANSACTION_HISTORY`
+
+**Triggers:** "transaction history", "recent activity", "shield history", "spending history", "activity log"
+
+Returns a detailed per-token usage summary with percentages, remaining budgets, rolling window information, and rate limit status.
+
+**Example conversation:**
+```
+User: "Show me the transaction history"
+Agent: "=== 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"
+```
 
 ## Providers
 
-Providers inject vault context into the agent's memory before each response:
+Providers inject shield context into the agent's memory before each response, giving the agent continuous awareness of its spending state:
 
-| Provider | Description |
-|----------|-------------|
-| `vaultStatusProvider` | Injects current vault status, agent key, total volume, open positions, and fees collected into the agent's context |
-| `spendTrackingProvider` | Injects rolling 24h spending data per token and recent transaction history so the agent is aware of remaining budget |
+### `shieldStatusProvider`
+
+**Name:** `AGENT_SHIELD_STATUS`
+
+Injects into every conversation turn:
+- Wallet address
+- Enforcement state (ACTIVE or PAUSED)
+- Per-token spending summary with percentages
+- Rate limit usage
+
+**Returned data:**
+```typescript
+{
+  text: "AgentShield Status: ...",  // Human-readable for agent context
+  values: {
+    address: "...",
+    isPaused: false,
+    tokens: [...],
+    rateLimit: { ... },
+  }
+}
+```
+
+### `spendTrackingProvider`
+
+**Name:** `AGENT_SHIELD_SPEND_TRACKING`
+
+Injects per-token spending data with:
+- Usage percentages per token
+- Rolling window durations (in hours)
+- Remaining budget per token
+- Aggregate max usage percentage across all tokens
 
 ## Evaluators
 
-Evaluators run after shield actions to assess state:
+### `policyCheckEvaluator`
 
-| Evaluator | Description |
-|-----------|-------------|
-| `policyCheckEvaluator` | Runs after any shield action. Warns in agent memory when rolling 24h spend exceeds 80% of the daily cap, helping the agent self-regulate |
+**Name:** `AGENT_SHIELD_POLICY_CHECK`
 
-## How It Works
+Post-action evaluator that warns when any token's spending exceeds 80% of its cap. Helps the agent self-regulate and avoid hitting hard limits.
+
+**Triggers on:** Messages containing "agentshield", "shield", or "transaction:"
+
+**Behavior:**
+- Returns `null` if enforcement is paused (no warnings when paused)
+- Checks each token against the 80% threshold
+- Returns warning text with token name, usage percentage, and remaining budget
+- Silently fails on errors (evaluators should never block the agent)
+
+**Example warning:**
+```
+"[AgentShield Warning] USDC spending at 85% of cap (150000000 remaining)"
+```
+
+## Event Callback Wiring
+
+The plugin automatically wires shield event callbacks to the ElizaOS runtime logger:
 
-The plugin reads environment variables at runtime to create an `AgentShieldClient`. All actions build atomic composed transactions:
+| Event | Log Level | Message |
+|-------|-----------|---------|
+| `onDenied` | `warn` | `[AgentShield] Transaction denied: <reason>` |
+| `onApproved` | `info` | `[AgentShield] Transaction approved` |
+| `onPause` | `info` | `[AgentShield] Enforcement paused` |
+| `onResume` | `info` | `[AgentShield] Enforcement resumed` |
+| `onPolicyUpdate` | `info` | `[AgentShield] Policies updated` |
 
+Falls back to `console` if `runtime.logger` is not available.
+
+## Wallet Caching
+
+The plugin uses a `WeakMap` to cache `ShieldedWallet` instances per ElizaOS runtime. This ensures:
+- The same wallet is reused across all actions, providers, and evaluators within a runtime
+- Spending state is consistent across the entire agent lifecycle
+- Different runtime instances get independent wallets
+- Wallets are garbage-collected when the runtime is released
+
+## Exported API
+
+| Export | Description |
+|--------|-------------|
+| `agentShieldPlugin` | Plugin object for ElizaOS registration |
+| `getConfig(runtime)` | Read config from runtime settings |
+| `getOrCreateShieldedWallet(runtime)` | Get/create cached ShieldedWallet |
+| `statusAction` | SHIELD_STATUS action |
+| `updatePolicyAction` | SHIELD_UPDATE_POLICY action |
+| `pauseResumeAction` | SHIELD_PAUSE_RESUME action |
+| `transactionHistoryAction` | SHIELD_TRANSACTION_HISTORY action |
+| `shieldStatusProvider` | Shield status context provider |
+| `spendTrackingProvider` | Spend tracking context provider |
+| `policyCheckEvaluator` | Policy cap warning evaluator |
+| `ENV_KEYS` | Environment variable key constants |
+| `AgentShieldElizaConfig` | Config type interface |
+
+The plugin is also available as a default export for ElizaOS plugin loader compatibility.
+
+## How It Works
+
+```
+ElizaOS Runtime
+    │
+    ├── Providers (inject context before each response)
+    │   ├── shieldStatusProvider → "Budget: 60% used"
+    │   └── spendTrackingProvider → "USDC: 300M/500M remaining"
+    │
+    ├── Actions (agent invokes conversationally)
+    │   ├── SHIELD_STATUS → detailed spending report
+    │   ├── SHIELD_UPDATE_POLICY → change limits at runtime
+    │   ├── SHIELD_PAUSE_RESUME → toggle enforcement
+    │   └── SHIELD_TRANSACTION_HISTORY → per-token usage details
+    │
+    ├── Evaluators (run after actions)
+    │   └── policyCheckEvaluator → "Warning: USDC at 85%"
+    │
+    └── ShieldedWallet (wraps signTransaction)
+        └── Policy engine → spending caps, rate limits, allowlists
 ```
-[ValidateAndAuthorize, DeFi instruction(s), FinalizeSession]
+
+The `ShieldedWallet` wraps the agent's private key wallet and intercepts all `signTransaction` calls. Any DeFi action the agent takes — swaps, transfers, position opens — passes through the policy engine before the transaction is signed. If a policy is violated, the transaction is rejected with a descriptive error.
+
+Providers give the agent continuous budget awareness. The evaluator proactively warns when spending approaches limits. No on-chain vault setup is needed.
+
+## Testing
+
+```bash
+npm test
+# Runs 30 tests covering all actions, providers, evaluator, config, caching, and event wiring
 ```
 
-Providers run before agent responses to inject vault context. The evaluator runs after shield actions to track budget usage.
+## 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-solana-agent-kit`](https://www.npmjs.com/package/@agent-shield/plugin-solana-agent-kit) | Solana Agent Kit integration |
+| [`@agent-shield/sdk`](https://www.npmjs.com/package/@agent-shield/sdk) | On-chain vault SDK |
 
 ## License
 

package/dist/actions/index.d.ts

@@ -1,4 +1,5 @@
-export { swapAction } from "./swap";
-export { openPositionAction } from "./openPosition";
-export { closePositionAction } from "./closePosition";
+export { statusAction } from "./status";
+export { updatePolicyAction } from "./updatePolicy";
+export { pauseResumeAction } from "./pauseResume";
+export { transactionHistoryAction } from "./transactionHistory";
 //# sourceMappingURL=index.d.ts.map

package/dist/actions/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/actions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/actions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/actions/index.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.closePositionAction = exports.openPositionAction = exports.swapAction = void 0;
-var swap_1 = require("./swap");
-Object.defineProperty(exports, "swapAction", { enumerable: true, get: function () { return swap_1.swapAction; } });
-var openPosition_1 = require("./openPosition");
-Object.defineProperty(exports, "openPositionAction", { enumerable: true, get: function () { return openPosition_1.openPositionAction; } });
-var closePosition_1 = require("./closePosition");
-Object.defineProperty(exports, "closePositionAction", { enumerable: true, get: function () { return closePosition_1.closePositionAction; } });
+exports.transactionHistoryAction = exports.pauseResumeAction = exports.updatePolicyAction = exports.statusAction = void 0;
+var status_1 = require("./status");
+Object.defineProperty(exports, "statusAction", { enumerable: true, get: function () { return status_1.statusAction; } });
+var updatePolicy_1 = require("./updatePolicy");
+Object.defineProperty(exports, "updatePolicyAction", { enumerable: true, get: function () { return updatePolicy_1.updatePolicyAction; } });
+var pauseResume_1 = require("./pauseResume");
+Object.defineProperty(exports, "pauseResumeAction", { enumerable: true, get: function () { return pauseResume_1.pauseResumeAction; } });
+var transactionHistory_1 = require("./transactionHistory");
+Object.defineProperty(exports, "transactionHistoryAction", { enumerable: true, get: function () { return transactionHistory_1.transactionHistoryAction; } });
 //# sourceMappingURL=index.js.map

package/dist/actions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/actions/index.ts"],"names":[],"mappings":";;;AAAA,+BAAoC;AAA3B,kGAAA,UAAU,OAAA;AACnB,+CAAoD;AAA3C,kHAAA,kBAAkB,OAAA;AAC3B,iDAAsD;AAA7C,oHAAA,mBAAmB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/actions/index.ts"],"names":[],"mappings":";;;AAAA,mCAAwC;AAA/B,sGAAA,YAAY,OAAA;AACrB,+CAAoD;AAA3C,kHAAA,kBAAkB,OAAA;AAC3B,6CAAkD;AAAzC,gHAAA,iBAAiB,OAAA;AAC1B,2DAAgE;AAAvD,8HAAA,wBAAwB,OAAA"}

package/dist/actions/pauseResume.d.ts

@@ -0,0 +1,14 @@
+export declare const pauseResumeAction: {
+    name: string;
+    description: string;
+    similes: string[];
+    validate: (runtime: any, message: any) => Promise<boolean>;
+    handler: (runtime: any, message: any, _state: any, _options: any, callback: (response: any) => void) => Promise<void>;
+    examples: {
+        user: string;
+        content: {
+            text: string;
+        };
+    }[][];
+};
+//# sourceMappingURL=pauseResume.d.ts.map

package/dist/actions/pauseResume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pauseResume.d.ts","sourceRoot":"","sources":["../../src/actions/pauseResume.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,iBAAiB;;;;wBAcF,GAAG,WAAW,GAAG,KAAG,OAAO,CAAC,OAAO,CAAC;uBAoBnD,GAAG,WACH,GAAG,UACJ,GAAG,YACD,GAAG,YACH,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI;;;;;;;CAuDpC,CAAC"}

package/dist/actions/pauseResume.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pauseResumeAction = void 0;
+const client_factory_1 = require("../client-factory");
+exports.pauseResumeAction = {
+    name: "SHIELD_PAUSE_RESUME",
+    description: "Pause or resume AgentShield enforcement. When paused, transactions " +
+        "pass through without policy checks or spend recording.",
+    similes: [
+        "pause shield",
+        "resume shield",
+        "pause enforcement",
+        "resume enforcement",
+        "disable shield",
+        "enable shield",
+    ],
+    validate: async (runtime, message) => {
+        try {
+            (0, client_factory_1.getOrCreateShieldedWallet)(runtime);
+        }
+        catch {
+            return false;
+        }
+        const text = (message.content?.text || "").toLowerCase();
+        const keywords = [
+            "pause shield",
+            "resume shield",
+            "pause enforcement",
+            "resume enforcement",
+            "disable shield",
+            "enable shield",
+        ];
+        return keywords.some((kw) => text.includes(kw));
+    },
+    handler: async (runtime, message, _state, _options, callback) => {
+        try {
+            const { wallet } = (0, client_factory_1.getOrCreateShieldedWallet)(runtime);
+            const text = (message.content?.text || "").toLowerCase();
+            // Determine intent from message text
+            const resumeKeywords = ["resume", "enable", "unpause", "activate"];
+            const isResume = resumeKeywords.some((kw) => text.includes(kw));
+            if (isResume) {
+                wallet.resume();
+                callback({
+                    text: "Shield enforcement resumed. Policy checks are active.",
+                });
+            }
+            else {
+                wallet.pause();
+                callback({
+                    text: "Shield enforcement paused. Transactions will pass through without policy checks.",
+                });
+            }
+        }
+        catch (error) {
+            callback({
+                text: `Failed to pause/resume shield: ${error.message}`,
+                error: true,
+            });
+        }
+    },
+    examples: [
+        [
+            {
+                user: "{{user1}}",
+                content: { text: "Pause the shield enforcement" },
+            },
+            {
+                user: "{{agent}}",
+                content: {
+                    text: "Shield enforcement paused. Transactions will pass through without policy checks.",
+                },
+            },
+        ],
+        [
+            {
+                user: "{{user1}}",
+                content: { text: "Resume shield enforcement" },
+            },
+            {
+                user: "{{agent}}",
+                content: {
+                    text: "Shield enforcement resumed. Policy checks are active.",
+                },
+            },
+        ],
+    ],
+};
+//# sourceMappingURL=pauseResume.js.map

package/dist/actions/pauseResume.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pauseResume.js","sourceRoot":"","sources":["../../src/actions/pauseResume.ts"],"names":[],"mappings":";;;AAAA,sDAA8D;AAEjD,QAAA,iBAAiB,GAAG;IAC/B,IAAI,EAAE,qBAAqB;IAC3B,WAAW,EACT,qEAAqE;QACrE,wDAAwD;IAC1D,OAAO,EAAE;QACP,cAAc;QACd,eAAe;QACf,mBAAmB;QACnB,oBAAoB;QACpB,gBAAgB;QAChB,eAAe;KAChB;IAED,QAAQ,EAAE,KAAK,EAAE,OAAY,EAAE,OAAY,EAAoB,EAAE;QAC/D,IAAI,CAAC;YACH,IAAA,0CAAyB,EAAC,OAAO,CAAC,CAAC;QACrC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QACzD,MAAM,QAAQ,GAAG;YACf,cAAc;YACd,eAAe;YACf,mBAAmB;YACnB,oBAAoB;YACpB,gBAAgB;YAChB,eAAe;SAChB,CAAC;QACF,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,EAAE,KAAK,EACZ,OAAY,EACZ,OAAY,EACZ,MAAW,EACX,QAAa,EACb,QAAiC,EACjC,EAAE;QACF,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,GAAG,IAAA,0CAAyB,EAAC,OAAO,CAAC,CAAC;YACtD,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;YAEzD,qCAAqC;YACrC,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;YACnE,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;YAEhE,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,CAAC,MAAM,EAAE,CAAC;gBAChB,QAAQ,CAAC;oBACP,IAAI,EAAE,uDAAuD;iBAC9D,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,KAAK,EAAE,CAAC;gBACf,QAAQ,CAAC;oBACP,IAAI,EAAE,kFAAkF;iBACzF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,QAAQ,CAAC;gBACP,IAAI,EAAE,kCAAkC,KAAK,CAAC,OAAO,EAAE;gBACvD,KAAK,EAAE,IAAI;aACZ,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,QAAQ,EAAE;QACR;YACE;gBACE,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE,EAAE,IAAI,EAAE,8BAA8B,EAAE;aAClD;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE;oBACP,IAAI,EAAE,kFAAkF;iBACzF;aACF;SACF;QACD;YACE;gBACE,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE,EAAE,IAAI,EAAE,2BAA2B,EAAE;aAC/C;YACD;gBACE,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE;oBACP,IAAI,EAAE,uDAAuD;iBAC9D;aACF;SACF;KACF;CACF,CAAC"}

package/dist/actions/status.d.ts

@@ -0,0 +1,14 @@
+export declare const statusAction: {
+    name: string;
+    description: string;
+    similes: string[];
+    validate: (runtime: any, message: any) => Promise<boolean>;
+    handler: (runtime: any, _message: any, _state: any, _options: any, callback: (response: any) => void) => Promise<void>;
+    examples: {
+        user: string;
+        content: {
+            text: string;
+        };
+    }[][];
+};
+//# sourceMappingURL=status.d.ts.map

package/dist/actions/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/actions/status.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,YAAY;;;;wBAYG,GAAG,WAAW,GAAG,KAAG,OAAO,CAAC,OAAO,CAAC;uBAmBnD,GAAG,YACF,GAAG,UACL,GAAG,YACD,GAAG,YACH,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI;;;;;;;CAoDpC,CAAC"}

package/dist/actions/status.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.statusAction = void 0;
+const client_factory_1 = require("../client-factory");
+exports.statusAction = {
+    name: "SHIELD_STATUS",
+    description: "Show current AgentShield spending summary, rate limit usage, and enforcement state.",
+    similes: [
+        "shield status",
+        "spending status",
+        "budget remaining",
+        "check spending",
+        "how much budget",
+    ],
+    validate: async (runtime, message) => {
+        try {
+            (0, client_factory_1.getOrCreateShieldedWallet)(runtime);
+        }
+        catch {
+            return false;
+        }
+        const text = (message.content?.text || "").toLowerCase();
+        const keywords = [
+            "shield status",
+            "spending",
+            "budget",
+            "how much left",
+            "remaining",
+        ];
+        return keywords.some((kw) => text.includes(kw));
+    },
+    handler: async (runtime, _message, _state, _options, callback) => {
+        try {
+            const { wallet } = (0, client_factory_1.getOrCreateShieldedWallet)(runtime);
+            const summary = wallet.getSpendingSummary();
+            const lines = [
+                `=== AgentShield Status ===`,
+                `Enforcement: ${summary.isPaused ? "PAUSED" : "ACTIVE"}`,
+                ``,
+            ];
+            for (const t of summary.tokens) {
+                const label = t.symbol ?? t.mint.slice(0, 8) + "...";
+                const pct = t.limit > BigInt(0)
+                    ? Number((t.spent * BigInt(100)) / t.limit)
+                    : 0;
+                lines.push(`${label}: ${t.spent.toString()} / ${t.limit.toString()} (${pct}% used)`);
+                lines.push(`  Remaining: ${t.remaining.toString()}`);
+            }
+            lines.push(``, `Rate limit: ${summary.rateLimit.count}/${summary.rateLimit.limit} transactions (${summary.rateLimit.remaining} remaining)`);
+            callback({ text: lines.join("\n") });
+        }
+        catch (error) {
+            callback({
+                text: `Failed to get shield status: ${error.message}`,
+                error: true,
+            });
+        }
+    },
+    examples: [
+        [
+            {
+                user: "{{user1}}",
+                content: { text: "What's my shield spending status?" },
+            },
+            {
+                user: "{{agent}}",
+                content: {
+                    text: "=== AgentShield Status ===\nEnforcement: ACTIVE\n\nUSDC: 200000000 / 500000000 (40% used)\n  Remaining: 300000000",
+                },
+            },
+        ],
+    ],
+};
+//# sourceMappingURL=status.js.map

package/dist/actions/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/actions/status.ts"],"names":[],"mappings":"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"}

package/dist/actions/transactionHistory.d.ts

@@ -0,0 +1,14 @@
+export declare const transactionHistoryAction: {
+    name: string;
+    description: string;
+    similes: string[];
+    validate: (runtime: any, message: any) => Promise<boolean>;
+    handler: (runtime: any, _message: any, _state: any, _options: any, callback: (response: any) => void) => Promise<void>;
+    examples: {
+        user: string;
+        content: {
+            text: string;
+        };
+    }[][];
+};
+//# sourceMappingURL=transactionHistory.d.ts.map

package/dist/actions/transactionHistory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactionHistory.d.ts","sourceRoot":"","sources":["../../src/actions/transactionHistory.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,wBAAwB;;;;wBAaT,GAAG,WAAW,GAAG,KAAG,OAAO,CAAC,OAAO,CAAC;uBAmBnD,GAAG,YACF,GAAG,UACL,GAAG,YACD,GAAG,YACH,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI;;;;;;;CAgEpC,CAAC"}

package/dist/actions/transactionHistory.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transactionHistoryAction = void 0;
+const client_factory_1 = require("../client-factory");
+exports.transactionHistoryAction = {
+    name: "SHIELD_TRANSACTION_HISTORY",
+    description: "Show recent AgentShield transaction activity — per-token usage " +
+        "percentages and rate limit status.",
+    similes: [
+        "transaction history",
+        "recent activity",
+        "shield history",
+        "spending history",
+        "activity log",
+    ],
+    validate: async (runtime, message) => {
+        try {
+            (0, client_factory_1.getOrCreateShieldedWallet)(runtime);
+        }
+        catch {
+            return false;
+        }
+        const text = (message.content?.text || "").toLowerCase();
+        const keywords = [
+            "transaction history",
+            "recent activity",
+            "shield history",
+            "spending history",
+            "activity log",
+        ];
+        return keywords.some((kw) => text.includes(kw));
+    },
+    handler: async (runtime, _message, _state, _options, callback) => {
+        try {
+            const { wallet } = (0, client_factory_1.getOrCreateShieldedWallet)(runtime);
+            const summary = wallet.getSpendingSummary();
+            const lines = [
+                `=== AgentShield Transaction History ===`,
+                `Enforcement: ${summary.isPaused ? "PAUSED" : "ACTIVE"}`,
+                ``,
+                `--- Per-Token Usage ---`,
+            ];
+            if (summary.tokens.length === 0) {
+                lines.push("No spending limits configured.");
+            }
+            else {
+                for (const t of summary.tokens) {
+                    const label = t.symbol ?? t.mint.slice(0, 8) + "...";
+                    const pct = t.limit > BigInt(0)
+                        ? Number((t.spent * BigInt(100)) / t.limit)
+                        : 0;
+                    const windowHrs = t.windowMs / 3600000;
+                    lines.push(`  ${label}:`);
+                    lines.push(`    Spent: ${t.spent.toString()} / ${t.limit.toString()}`);
+                    lines.push(`    Usage: ${pct}%`);
+                    lines.push(`    Remaining: ${t.remaining.toString()}`);
+                    lines.push(`    Window: ${windowHrs}h rolling`);
+                }
+            }
+            lines.push("", `--- Rate Limit ---`);
+            lines.push(`  Transactions: ${summary.rateLimit.count} / ${summary.rateLimit.limit}`);
+            lines.push(`  Remaining: ${summary.rateLimit.remaining}`);
+            const rlWindowHrs = summary.rateLimit.windowMs / 3600000;
+            lines.push(`  Window: ${rlWindowHrs}h`);
+            callback({ text: lines.join("\n") });
+        }
+        catch (error) {
+            callback({
+                text: `Failed to get transaction history: ${error.message}`,
+                error: true,
+            });
+        }
+    },
+    examples: [
+        [
+            {
+                user: "{{user1}}",
+                content: { text: "Show me the transaction history" },
+            },
+            {
+                user: "{{agent}}",
+                content: {
+                    text: "=== AgentShield Transaction History ===\nEnforcement: ACTIVE\n\n--- Per-Token Usage ---\n  USDC:\n    Spent: 200000000 / 500000000\n    Usage: 40%\n    Remaining: 300000000\n    Window: 24h rolling",
+                },
+            },
+        ],
+    ],
+};
+//# sourceMappingURL=transactionHistory.js.map

package/dist/actions/transactionHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactionHistory.js","sourceRoot":"","sources":["../../src/actions/transactionHistory.ts"],"names":[],"mappings":"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"}