suzi-cli 0.1.1 → 0.1.2

package/dist/lib/suzi-guide.js

@@ -0,0 +1,427 @@
+"use strict";
+// Shared suzi-guide content used by both skills.ts and create.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUZI_GUIDE_CONTENT = void 0;
+exports.SUZI_GUIDE_CONTENT = `---
+name: suzi-guide
+description: >
+  Comprehensive guide for the Suzi CLI and agent platform. Use this skill when
+  the user asks about Suzi commands, how to create/deploy/manage agents, available
+  protocols and actions, agent code patterns, or anything related to the Suzi
+  autonomous agent platform for blockchain protocols.
+---
+
+# Suzi CLI & Agent Platform Guide
+
+## IMPORTANT: Always Use the CLI for Live Data
+
+**NEVER rely on hardcoded data from this skill for questions about protocols, actions, balances, agents, or any runtime state.** Always run the appropriate \`suzi\` CLI command and use its output. This ensures the user gets up-to-date information.
+
+| User asks about... | Run this command |
+|---------------------|-----------------|
+| Available protocols / actions | \`suzi list-tools --verbose\` |
+| Actions for a specific protocol | \`suzi list-tools --protocol <name>\` |
+| Their agents | \`suzi agents\` |
+| Agent details / triggers / config | \`suzi agents view <id>\` |
+| Agent logs | \`suzi agents logs <id>\` |
+| Wallet addresses | \`suzi wallet address\` |
+| Balances | \`suzi wallet balance\` |
+| Portfolio | \`suzi portfolio --all\` |
+| Transactions | \`suzi transactions\` |
+| Current user / auth status | \`suzi whoami\` |
+
+**Do NOT answer "what protocols are available?" or "what actions does polymarket have?" from memory. Run the CLI.**
+
+---
+
+## What is Suzi?
+
+Suzi is an autonomous agent platform for creating and executing intelligent agents that interact with blockchain protocols. Users write TypeScript agents with triggers (manual, cron, event-based) that execute actions against protocols in a sandboxed environment.
+
+---
+
+## Installing the Suzi CLI
+
+\\\`\\\`\\\`bash
+pnpm add suzi
+
+# Verify installation
+suzi --version
+\\\`\\\`\\\`
+
+### First-time setup
+
+\\\`\\\`\\\`bash
+# 1. Point to the Suzi API (production)
+suzi login --api-url https://api-3ihwe.ondigitalocean.app
+
+# 2. Browser opens for Google OAuth sign-in
+# 3. After auth, CLI shows your wallet address + QR code
+# 4. Send SOL to the displayed address to fund your wallet
+# 5. CLI auto-detects the deposit and shows your portfolio
+\\\`\\\`\\\`
+
+### Requirements
+
+- Node.js 22.x
+- pnpm 9.15.0
+
+---
+
+## CLI Commands Reference
+
+### Authentication
+
+\`\`\`bash
+suzi login                    # Sign in with Google (OAuth2.0). Shows QR code for wallet funding.
+suzi login --api-url <url>    # Override API endpoint
+suzi login --web-url <url>    # Override web app URL
+suzi logout                   # Sign out and clear stored credentials
+suzi whoami                   # Show current authenticated user, wallet addresses
+\`\`\`
+
+### Wallet Management
+
+\`\`\`bash
+suzi wallet                   # Show wallet overview (SOL + EVM addresses)
+suzi wallet address           # Show full wallet addresses (for copying)
+suzi wallet balance           # Show balances (ALWAYS run this for balance questions)
+suzi wallet fund              # Show deposit instructions with full addresses
+\`\`\`
+
+### Portfolio
+
+\`\`\`bash
+suzi portfolio                # View SOL + top 3 assets across chains
+suzi portfolio --all          # Full portfolio including Hyperliquid perp positions
+\`\`\`
+
+### Agent Management
+
+\`\`\`bash
+suzi agents                         # List all agents (ALWAYS run this for agent questions)
+suzi agents view <id>               # View agent details (spec, triggers, resources, config)
+suzi agents activate <id>           # Activate agent (allocates wallets, registers triggers)
+suzi agents deactivate <id>         # Deactivate agent
+suzi agents execute <id> [trigger]  # Manually execute a trigger (prompts if multiple)
+suzi agents logs <id>               # View agent logs (default: last 20)
+suzi agents logs <id> -n 50         # View more log entries
+suzi agents logs <id> --level error # Filter by level: info|warn|error|debug
+suzi agents delete <id>             # Delete agent (with confirmation)
+suzi agents delete <id> -f          # Delete without confirmation
+\`\`\`
+
+### Agent Deployment
+
+\`\`\`bash
+suzi deploy                         # Deploy agent (auto-discovers agent.ts, src/agent.ts, index.ts)
+suzi deploy ./path/to/agent.ts      # Deploy specific file
+suzi deploy -t "My Agent"           # Set title
+suzi deploy -d "Description here"   # Set description
+suzi deploy --activate              # Activate immediately after deployment
+suzi deploy --update <agentId>      # Update existing agent's code
+\`\`\`
+
+### Agent Templates & Validation
+
+\`\`\`bash
+suzi subagents                      # List agent.md and agent.ts files in current directory
+suzi subagents init                 # Create template agent.md + agent.ts files
+suzi subagents init --dir ./myagent # Create templates in specific directory
+suzi subagents validate             # Validate agent.md (checks Meta, Resources, Triggers sections)
+suzi subagents validate ./agent.md  # Validate specific file
+\`\`\`
+
+### Agent Import (Sharing)
+
+\`\`\`bash
+suzi import <slug>                  # Clone a shared agent by its share slug
+\`\`\`
+
+### Transactions
+
+\`\`\`bash
+suzi transactions                   # View recent transactions across all agents (alias: suzi txns)
+suzi txns -n 30                     # Show more entries
+suzi txns --type order              # Filter: order|cancel|transfer|swap|bridge|liquidity
+suzi txns --protocol polymarket     # Filter by protocol
+suzi txns --agent <id>              # Filter by specific agent
+suzi tx-confirm <agentId>           # Show latest execution details (input/output)
+\`\`\`
+
+### Tools & Protocols
+
+\`\`\`bash
+suzi list-tools                     # List all protocols (ALWAYS run for protocol questions)
+suzi list-tools --verbose           # Show ALL actions per protocol with descriptions
+suzi list-tools --protocol <name>   # Show actions for a specific protocol
+\`\`\`
+
+### Preferences
+
+\`\`\`bash
+suzi preferences                    # View current preferences (alias: suzi prefs)
+suzi prefs set-username [name]      # Set display username
+suzi prefs telegram                 # Connect Telegram for notifications
+suzi prefs api-url <url>            # Set API server URL
+\`\`\`
+
+### Help & Suggestions
+
+\`\`\`bash
+suzi suggest                        # Interactive command suggestions (alias: suzi help-me)
+suzi --help                         # Show all commands
+\`\`\`
+
+### Skills
+
+\`\`\`bash
+suzi skills                         # List available skills
+suzi skills show <name>             # Show skill details and sections
+suzi skills add <name>              # Install a skill to ~/.claude/skills/
+suzi skills add --all               # Install all available skills
+\`\`\`
+
+---
+
+## Creating Agents
+
+### Quick Start
+
+\`\`\`bash
+# 1. Initialize a template
+suzi subagents init
+
+# 2. Edit agent.ts with your logic
+
+# 3. Deploy
+suzi deploy ./agent.ts
+
+# 4. Activate
+suzi agents activate <agent-id>
+
+# 5. Execute manually
+suzi agents execute <agent-id>
+\`\`\`
+
+### Agent File Structure
+
+Agent files must default-export a \`defineAgent()\` call. The file is self-contained — **no imports allowed** (the runtime provides \`defineAgent\`, \`on\`, \`resource\`, \`config\`, \`requirement\` as globals).
+
+\`\`\`typescript
+export default defineAgent({
+  meta: { ... },        // Required: name, version
+  resources: { ... },   // Optional: wallet requirements
+  config: { ... },      // Optional: user-configurable parameters
+  activationRequirements: { ... },  // Optional: balance checks before activation
+  lifecycle: { ... },   // Optional: onActivate, onDeactivate hooks
+  triggers: { ... },    // Required: at least one trigger
+});
+\`\`\`
+
+### Minimal Agent
+
+\`\`\`typescript
+export default defineAgent({
+  meta: {
+    name: 'My Agent',
+    version: '0.1.0',
+  },
+  triggers: {
+    manual: on.suzi.manual(async (ctx, input) => {
+      await ctx.actions.suzi.log({ message: 'Hello from my agent!' });
+      return { ok: true };
+    }),
+  },
+});
+\`\`\`
+
+### Full Agent Template
+
+\`\`\`typescript
+export default defineAgent({
+  meta: {
+    name: 'My Trading Agent',
+    version: '0.1.0',
+    description: 'Automated trading strategy',
+    tags: ['trading', 'solana'],
+  },
+
+  // Wallet resources the agent needs
+  resources: {
+    svmWallet: resource.wallet('svm'),   // Solana wallet
+    evmWallet: resource.wallet('evm'),   // Ethereum wallet (for Hyperliquid/Polymarket)
+  },
+
+  // User-configurable parameters (set during activation)
+  config: {
+    capital: config.number({
+      description: 'Initial capital in USDC',
+      min: 100,
+      max: 10000,
+      required: true,
+      default: 1000,
+    }),
+  },
+
+  // Balance checks before agent can activate
+  activationRequirements: {
+    __min_usdc: requirement.svmTokenBalance({
+      token: 'USDC',
+      minAmount: { $ref: 'config.capital' },  // References config value
+      description: 'Minimum USDC required',
+    }),
+    __min_sol: requirement.svmNativeBalance({
+      minAmount: 0.5,
+      description: 'Minimum SOL for transaction fees',
+    }),
+  },
+
+  // Lifecycle hooks
+  lifecycle: {
+    onActivate: async (ctx) => {
+      const { capital } = ctx.config as { capital: number };
+      await ctx.actions.suzi.log({ message: \`Activating with $\${capital} USDC\` });
+      const svmResult = await ctx.actions.suzi.get_svm_address({});
+      await ctx.actions.suzi.set_to_store({ key: 'initial_capital', value: capital });
+    },
+
+    onDeactivate: async (ctx) => {
+      await ctx.actions.suzi.log({ message: 'Deactivating — closing positions...' });
+    },
+  },
+
+  triggers: {
+    // Manual trigger — executed from dashboard or CLI
+    manual: on.suzi.manual(async (ctx, input) => {
+      await ctx.actions.suzi.log({ message: 'Manual execution' });
+      return { ok: true };
+    }),
+
+    // Cron trigger — runs on schedule
+    rebalance: on.suzi.cron(
+      { schedule: '*/5 * * * *' },  // Every 5 minutes (standard cron syntax)
+      async (ctx) => {
+        await ctx.actions.suzi.log({ message: 'Rebalancing...' });
+        return { ok: true, action: 'rebalanced' };
+      }
+    ),
+  },
+});
+\`\`\`
+
+### Agent Context (ctx)
+
+Available in all trigger handlers and lifecycle hooks:
+
+\`\`\`typescript
+ctx.actions.<protocol>.<action>()  // Call any protocol action
+ctx.config                         // Access config values
+\`\`\`
+
+**To see what protocols and actions are available, run \`suzi list-tools --verbose\`.**
+Actions are called as \`ctx.actions.<protocol>.<action_name>({ ...params })\`.
+
+### Validation Rules
+
+- Agent **must** default-export via \`defineAgent({})\`
+- **No imports/requires** — agent code must be self-contained
+- \`triggers\` object is **required** with at least one trigger
+- Each trigger must have a \`type\` (e.g., \`suzi.manual\`, \`suzi.cron\`)
+- Config fields need \`type\` and \`description\`
+- The file is transpiled from TypeScript to JavaScript and executed in a VM2 sandbox
+
+### Agent Statuses
+
+| Status | Description |
+|--------|-------------|
+| \`draft\` | Created but not activated. No wallets allocated. |
+| \`active\` | Running. Cron triggers fire on schedule, event triggers are subscribed. |
+| \`inactive\` | Deactivated. Triggers stopped. Can be reactivated. |
+| \`deleted\` | Soft-deleted. Not recoverable from CLI. |
+
+---
+
+## Trigger Types
+
+| Trigger | Syntax | Description |
+|---------|--------|-------------|
+| Manual | \`on.suzi.manual(handler)\` | Triggered from dashboard or \`suzi agents execute\` |
+| Cron | \`on.suzi.cron({ schedule }, handler)\` | Runs on cron schedule (e.g., \`'*/5 * * * *'\`) |
+| Event | \`on.<protocol>.event(config, handler)\` | Triggered by realtime protocol events |
+
+### Cron Schedule Examples
+
+| Schedule | Meaning |
+|----------|---------|
+| \`*/1 * * * *\` | Every minute |
+| \`*/5 * * * *\` | Every 5 minutes |
+| \`0 * * * *\` | Every hour |
+| \`0 */4 * * *\` | Every 4 hours |
+| \`0 0 * * *\` | Daily at midnight |
+
+---
+
+## Common Workflows
+
+### Deploy & Activate in One Command
+
+\`\`\`bash
+suzi deploy ./agent.ts --activate
+\`\`\`
+
+### Update Running Agent Code
+
+\`\`\`bash
+suzi deploy ./agent.ts --update <agent-id>
+\`\`\`
+
+### Monitor Agent
+
+\`\`\`bash
+suzi agents logs <id>               # View recent logs
+suzi agents logs <id> --level error  # Check for errors
+suzi txns --agent <id>               # View transactions
+\`\`\`
+
+### Typical Development Loop
+
+\`\`\`bash
+# 1. Create template
+suzi subagents init --dir ./my-agent
+
+# 2. Edit agent.ts — write your logic
+
+# 3. Deploy as draft
+suzi deploy ./my-agent/agent.ts
+
+# 4. Review
+suzi agents view <id>
+
+# 5. Activate
+suzi agents activate <id>
+
+# 6. Test manually
+suzi agents execute <id>
+
+# 7. Check results
+suzi agents logs <id>
+
+# 8. Iterate — update code
+suzi deploy ./my-agent/agent.ts --update <id>
+\`\`\`
+
+---
+
+## Tips & Best Practices
+
+1. **Start simple** — begin with a manual trigger, test it, then add cron/event triggers
+2. **Use \`suzi.log\`** liberally — logs are your debugging tool since agents run in a sandbox
+3. **Use \`suzi.set_to_store / get_from_store\`** for state that persists across trigger executions
+4. **Activation requirements** prevent agents from starting without sufficient funds
+5. **Kill switches** — add a cron trigger that checks drawdown and calls \`request_deactivation\` if needed
+6. **No imports** — all code must be self-contained. Use \`ctx.actions\` for all external interactions
+7. **Test with manual triggers first**, then add cron schedules
+8. **Connect Telegram** (\`suzi prefs telegram\`) for \`suzi.notify\` alerts
+`;
+//# sourceMappingURL=suzi-guide.js.map

package/dist/lib/suzi-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suzi-guide.js","sourceRoot":"","sources":["../../src/lib/suzi-guide.ts"],"names":[],"mappings":";AAAA,iEAAiE;;;AAEpD,QAAA,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqajC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "suzi-cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Suzi CLI by SendAI",
   "main": "dist/index.js",
   "bin": {
@@ -11,7 +11,14 @@
     "url": "https://github.com/sendaifun"
   },
   "homepage": "https://github.com/sendaifun",
-  "keywords": ["suzi", "sendai", "cli", "blockchain", "agents", "autonomous"],
+  "keywords": [
+    "suzi",
+    "sendai",
+    "cli",
+    "blockchain",
+    "agents",
+    "autonomous"
+  ],
   "license": "MIT",
   "author": "SendAI",
   "scripts": {
@@ -31,13 +38,15 @@
     "inquirer": "^8.2.6",
     "open": "^8.4.2",
     "ora": "^5.4.1",
-    "qrcode-terminal": "^0.12.0"
+    "qrcode-terminal": "^0.12.0",
+    "update-notifier": "^5.1.0"
   },
   "devDependencies": {
     "@types/express": "^4.17.21",
     "@types/inquirer": "^8.2.10",
     "@types/node": "^22.10.5",
     "@types/qrcode-terminal": "^0.12.2",
+    "@types/update-notifier": "^6.0.8",
     "eslint": "^9.18.0",
     "tsx": "^4.19.2",
     "typescript": "^5.7.3"