@terminusagents/agents 0.1.0

package/README.md

@@ -0,0 +1,192 @@
+# Terminus Agents Node
+
+Run a Terminus agent on your machine, receive jobs from the control plane, and earn for completed work.
+
+This package supports:
+- challenge-signature websocket auth
+- Grok / Ollama / OpenAI-compatible providers
+- testnet/mainnet/local network profiles
+- one-command diagnostics with `doctor`
+
+## Install Without Cloning
+
+### Option 1: npm global install
+
+```bash
+npm install -g @terminusagents/agents
+```
+
+Then run:
+
+```bash
+terminus-agent init
+```
+
+### Option 2: One-line installer (curl)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Terminusagents/agents/main/scripts/install.sh | bash
+```
+
+This script:
+- checks Node.js/NPM prerequisites
+- installs `@terminusagents/agents` globally
+- prints next commands (`init`, `doctor`, `run`)
+
+## 3-Minute Onboarding
+
+1. Clone and install:
+
+```bash
+git clone https://github.com/Terminusagents/agents.git
+cd agents
+pnpm install
+pnpm build
+```
+
+2. Configure agent (interactive):
+
+```bash
+npx terminus-agent init
+```
+
+3. Export required runtime secrets:
+
+```bash
+export TERMINUS_WALLET_PRIVATE_KEY=0x...
+export TERMINUS_GROK_API_KEY=xai-...   # only if using Grok
+```
+
+4. Run diagnostics:
+
+```bash
+npx terminus-agent doctor --full
+```
+
+5. Start node:
+
+```bash
+npx terminus-agent run
+```
+
+## Non-Interactive Setup (Automation Friendly)
+
+Use this for scripted onboarding:
+
+```bash
+export TERMINUS_WALLET_PRIVATE_KEY=0x...
+export TERMINUS_GROK_API_KEY=xai-...
+
+npx terminus-agent init \
+  --yes \
+  --force \
+  --profile testnet \
+  --agent-type travel-planner \
+  --wallet 0x1234567890abcdef1234567890abcdef12345678 \
+  --llm-provider grok
+```
+
+Then:
+
+```bash
+npx terminus-agent doctor
+npx terminus-agent run
+```
+
+## CLI Commands
+
+```bash
+npx terminus-agent init      # setup or reconfigure
+npx terminus-agent doctor    # readiness diagnostics
+npx terminus-agent status    # show current config and health hints
+npx terminus-agent run       # start agent client
+```
+
+## Network Presets
+
+`init` can select `local`, `testnet`, or `mainnet` profile.
+
+Optional preset environment variables:
+
+```bash
+export TERMINUS_CONTROL_PLANE_URL_LOCAL=ws://localhost:8084
+export TERMINUS_CONTROL_PLANE_URL_TESTNET=wss://<sepolia-control-plane>
+export TERMINUS_CONTROL_PLANE_URL_MAINNET=wss://<mainnet-control-plane>
+```
+
+Notes:
+- `mainnet` profile requires `wss://`
+- if `REQUIRE_WSS=true`, plain `ws://` is rejected
+
+## Security Defaults
+
+- private key is never written to `~/.terminus/config.json`
+- config directory/file permissions are hardened (`0700` / `0600` where supported)
+- wallet/private key mismatch is rejected by default
+- shared-secret fallback is only usable when `ALLOW_DEV_SHARED_SECRET=true`
+- prompt/tool-parameter snippets are not logged in client output
+
+## Configuration File
+
+Config path:
+
+```bash
+~/.terminus/config.json
+```
+
+Example:
+
+```json
+{
+  "agentType": "travel-planner",
+  "wallet": "0x1234567890abcdef1234567890abcdef12345678",
+  "apiKey": "__ENV__",
+  "controlPlaneUrl": "wss://example-control-plane",
+  "nodeId": "travel-planner-123456-a1b2c3d4",
+  "llmProvider": "grok",
+  "networkProfile": "testnet"
+}
+```
+
+`"apiKey": "__ENV__"` means runtime key from `TERMINUS_GROK_API_KEY` or `XAI_API_KEY`.
+
+## Troubleshooting
+
+### `Connection failed`
+- run `npx terminus-agent doctor --full`
+- verify control plane URL and firewall
+- for mainnet, verify URL starts with `wss://`
+
+### `Auth failed`
+- verify `TERMINUS_WALLET_PRIVATE_KEY` is set
+- verify private key signer address matches configured wallet
+- rerun `npx terminus-agent init --force` if wallet changed
+
+### `Grok key missing`
+- set one of:
+  - `TERMINUS_GROK_API_KEY`
+  - `XAI_API_KEY`
+- or store key directly during `init`
+
+### `Ollama not reachable`
+- start server:
+
+```bash
+ollama serve
+```
+
+- verify:
+
+```bash
+curl http://localhost:11434/api/tags
+```
+
+## Support
+
+- GitHub: [https://github.com/Terminusagents/agents](https://github.com/Terminusagents/agents)
+- Organization: [https://github.com/Terminusagents](https://github.com/Terminusagents)
+- X: [https://x.com/terminus_agents](https://x.com/terminus_agents)
+
+## License
+
+MIT

package/bin/terminus-agent.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';

package/dist/agent/executor.d.ts

@@ -0,0 +1,24 @@
+import { AgentConfig } from '../config/store.js';
+export interface ExecutionResult {
+    response: string;
+    toolsUsed?: Array<{
+        name: string;
+        params: unknown;
+        result: unknown;
+    }>;
+    llmProvider?: string;
+    tokensUsed?: number;
+}
+export declare class AgentExecutor {
+    private config;
+    private agentDefinition;
+    private llmProvider;
+    constructor(config: AgentConfig);
+    getAgentInfo(): {
+        id: string;
+        name: string;
+        description: string;
+        tools: string[];
+    };
+    execute(userQuery: string): Promise<ExecutionResult>;
+}

package/dist/agent/executor.js

@@ -0,0 +1,96 @@
+// =============================================================================
+// TERMINUS AGENT - Agent Executor
+// =============================================================================
+// Executes agent logic: calls LLM, invokes tools, returns response.
+// Supports multiple LLM backends via provider abstraction.
+// =============================================================================
+import { createLLMProvider } from '../llm/provider.js';
+import { AGENTS, getAgentById, executeAgentTool } from '../agents/index.js';
+export class AgentExecutor {
+    config;
+    agentDefinition;
+    llmProvider;
+    constructor(config) {
+        this.config = config;
+        // Get agent definition from registry
+        const agentDef = getAgentById(config.agentType);
+        if (!agentDef) {
+            throw new Error(`Unknown agent type: ${config.agentType}. Available: ${AGENTS.map(a => a.id).join(', ')}`);
+        }
+        this.agentDefinition = agentDef;
+        // Create LLM provider based on config
+        this.llmProvider = createLLMProvider({
+            provider: config.llmProvider || 'grok',
+            apiKey: config.apiKey,
+            baseUrl: config.llmBaseUrl,
+            model: config.llmModel,
+        });
+        console.log(`🤖 Agent executor initialized`);
+        console.log(`   Agent: ${this.agentDefinition.name} (${this.agentDefinition.id})`);
+        console.log(`   LLM Provider: ${this.llmProvider.name}`);
+        console.log(`   Tools: ${this.agentDefinition.tools.map(t => t.name).join(', ')}`);
+    }
+    getAgentInfo() {
+        return {
+            id: this.agentDefinition.id,
+            name: this.agentDefinition.name,
+            description: this.agentDefinition.description,
+            tools: this.agentDefinition.tools.map(t => t.name),
+        };
+    }
+    async execute(userQuery) {
+        const toolsUsed = [];
+        // Build system prompt with tools info
+        const toolsInfo = this.agentDefinition.tools
+            .map(t => `- ${t.name}: ${t.description} (params: ${t.parameters.join(', ')})`)
+            .join('\n');
+        const systemPrompt = `${this.agentDefinition.systemPrompt}
+
+You have access to the following tools:
+${toolsInfo}
+
+When you need to use a tool, respond with a JSON block like this:
+\`\`\`json
+{"tool": "toolName", "params": {"param1": "value1"}}
+\`\`\`
+
+After receiving tool results, incorporate them into your response to help the user.`;
+        // Initial LLM call
+        let response = await this.llmProvider.chat([
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: userQuery },
+        ], { maxTokens: 1024, temperature: 0.7 });
+        // Check if LLM wants to use a tool
+        const toolMatch = response.content.match(/```json\s*(\{[\s\S]*?\})\s*```/);
+        if (toolMatch) {
+            try {
+                const toolCall = JSON.parse(toolMatch[1]);
+                console.log(`🔧 Tool call detected: ${toolCall.tool}`);
+                // Execute the tool
+                const toolResult = await executeAgentTool(this.agentDefinition.id, toolCall.tool, toolCall.params);
+                toolsUsed.push({
+                    name: toolCall.tool,
+                    params: toolCall.params,
+                    result: toolResult.data,
+                });
+                // Follow-up LLM call with tool result
+                const followUp = await this.llmProvider.chat([
+                    { role: 'system', content: systemPrompt },
+                    { role: 'user', content: userQuery },
+                    { role: 'assistant', content: response.content },
+                    { role: 'user', content: `Tool result for ${toolCall.tool}:\n${JSON.stringify(toolResult.data, null, 2)}\n\nPlease provide a helpful response based on this information.` },
+                ], { maxTokens: 1024, temperature: 0.7 });
+                response = followUp;
+            }
+            catch (e) {
+                console.error('Failed to parse tool call:', e);
+            }
+        }
+        return {
+            response: response.content,
+            toolsUsed: toolsUsed.length > 0 ? toolsUsed : undefined,
+            llmProvider: this.llmProvider.name,
+            tokensUsed: response.tokensUsed,
+        };
+    }
+}

package/dist/agents/budget-planner.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition, ToolParams } from './types.js';
+export declare const BudgetPlannerAgent: AgentDefinition;
+export declare const BudgetPlannerTools: Record<string, (params: ToolParams) => Promise<unknown>>;

package/dist/agents/budget-planner.js

@@ -0,0 +1,43 @@
+// =============================================================================
+// TERMINUS AGENTS - Budget Planner Agent
+// =============================================================================
+// =============================================================================
+// Agent Definition
+// =============================================================================
+export const BudgetPlannerAgent = {
+    id: 'budget-planner',
+    name: 'Budget Planner',
+    description: 'Helps with budgeting, finding deals, and cost comparisons',
+    systemPrompt: `You are a financial budget expert. Help users find affordable options and manage their spending.`,
+    keywords: ['budget', 'cheap', 'affordable', 'cost', 'price', 'deal', 'discount', 'save', 'money'],
+    tools: [
+        { name: 'calculateBudget', description: 'Calculate total budget', parameters: ['items', 'currency'] },
+        { name: 'findDeals', description: 'Find best deals', parameters: ['category', 'maxPrice'] },
+        { name: 'comparePrices', description: 'Compare prices', parameters: ['product', 'sources'] },
+    ],
+};
+// =============================================================================
+// Tool Implementations
+// =============================================================================
+export const BudgetPlannerTools = {
+    calculateBudget: async (p) => ({
+        total: Array.isArray(p.items) ? p.items.reduce((a, b) => a + b, 0) : 0,
+        currency: p.currency || 'USD',
+        breakdown: p.items
+    }),
+    findDeals: async (p) => ({
+        deals: [
+            { name: `Best ${p.category} Deal`, discount: '30%', originalPrice: 100, salePrice: 70 },
+            { name: `Premium ${p.category}`, discount: '20%', originalPrice: 200, salePrice: 160 },
+        ],
+        category: p.category
+    }),
+    comparePrices: async (p) => ({
+        product: p.product,
+        prices: [
+            { source: 'Amazon', price: 99.99 },
+            { source: 'eBay', price: 89.99 },
+            { source: 'Trendyol', price: 949.00, currency: 'TRY' },
+        ]
+    }),
+};

package/dist/agents/career-coach.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition, ToolParams } from './types.js';
+export declare const CareerCoachAgent: AgentDefinition;
+export declare const CareerCoachTools: Record<string, (params: ToolParams) => Promise<unknown>>;

package/dist/agents/career-coach.js

@@ -0,0 +1,43 @@
+// =============================================================================
+// TERMINUS AGENTS - Career Coach Agent
+// =============================================================================
+// =============================================================================
+// Agent Definition
+// =============================================================================
+export const CareerCoachAgent = {
+    id: 'career-coach',
+    name: 'Career Coach',
+    description: 'Helps with job search and career development',
+    systemPrompt: `You are a career coach. Help users find jobs, improve resumes, and prepare for interviews.`,
+    keywords: ['job', 'career', 'resume', 'interview', 'salary', 'hire', 'work', 'profession'],
+    tools: [
+        { name: 'searchJobs', description: 'Search jobs', parameters: ['title', 'location', 'remote'] },
+        { name: 'reviewResume', description: 'Review resume', parameters: ['resumeText'] },
+        { name: 'prepareInterview', description: 'Prepare interview', parameters: ['company', 'role'] },
+    ],
+};
+// =============================================================================
+// Tool Implementations
+// =============================================================================
+export const CareerCoachTools = {
+    searchJobs: async (p) => ({
+        jobs: [
+            { title: p.title, company: 'Google', location: p.location, salary: '$150K' },
+            { title: p.title, company: 'Microsoft', location: p.location, salary: '$140K' },
+        ]
+    }),
+    reviewResume: async (p) => ({
+        score: 78,
+        strengths: ['Clear formatting', 'Strong experience section'],
+        improvements: ['Add more metrics', 'Update skills section']
+    }),
+    prepareInterview: async (p) => ({
+        company: p.company,
+        questions: [
+            'Tell me about yourself',
+            'Why do you want to work here?',
+            'What are your strengths and weaknesses?'
+        ],
+        tips: ['Research the company', 'Prepare STAR examples']
+    }),
+};

package/dist/agents/crypto-advisor.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition, ToolParams } from './types.js';
+export declare const CryptoAdvisorAgent: AgentDefinition;
+export declare const CryptoAdvisorTools: Record<string, (params: ToolParams) => Promise<unknown>>;

package/dist/agents/crypto-advisor.js

@@ -0,0 +1,49 @@
+// =============================================================================
+// TERMINUS AGENTS - Crypto Advisor Agent
+// =============================================================================
+// =============================================================================
+// Agent Definition
+// =============================================================================
+export const CryptoAdvisorAgent = {
+    id: 'crypto-advisor',
+    name: 'Crypto Advisor',
+    description: 'Provides cryptocurrency analysis and advice',
+    systemPrompt: `You are a cryptocurrency expert. Analyze crypto markets, tokens, and provide insights on the crypto ecosystem.`,
+    keywords: ['crypto', 'bitcoin', 'ethereum', 'token', 'blockchain', 'defi', 'nft', 'coin', 'kripto', 'bitcoin', 'altcoin'],
+    tools: [
+        { name: 'getCryptoPrice', description: 'Get crypto price', parameters: ['symbol'] },
+        { name: 'analyzeToken', description: 'Analyze token', parameters: ['address', 'chain'] },
+        { name: 'getMarketCap', description: 'Get market data', parameters: ['symbol'] },
+        { name: 'getDeFiStats', description: 'Get DeFi stats', parameters: ['protocol'] },
+    ],
+};
+// =============================================================================
+// Tool Implementations
+// =============================================================================
+export const CryptoAdvisorTools = {
+    getCryptoPrice: async (p) => ({
+        symbol: p.symbol,
+        price: p.symbol === 'BTC' ? 42500 : p.symbol === 'ETH' ? 2250 : 100,
+        change24h: 3.5,
+        volume24h: '25B'
+    }),
+    analyzeToken: async (p) => ({
+        address: p.address,
+        chain: p.chain,
+        holders: 15000,
+        liquidity: '$2.5M',
+        score: 75
+    }),
+    getMarketCap: async (p) => ({
+        symbol: p.symbol,
+        marketCap: '$850B',
+        rank: 1,
+        dominance: '52%'
+    }),
+    getDeFiStats: async (p) => ({
+        protocol: p.protocol,
+        tvl: '$5.2B',
+        apy: '8.5%',
+        users: 150000
+    }),
+};

package/dist/agents/event-planner.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition, ToolParams } from './types.js';
+export declare const EventPlannerAgent: AgentDefinition;
+export declare const EventPlannerTools: Record<string, (params: ToolParams) => Promise<unknown>>;

package/dist/agents/event-planner.js

@@ -0,0 +1,41 @@
+// =============================================================================
+// TERMINUS AGENTS - Event Planner Agent
+// =============================================================================
+// =============================================================================
+// Agent Definition
+// =============================================================================
+export const EventPlannerAgent = {
+    id: 'event-planner',
+    name: 'Event Planner',
+    description: 'Plans events and finds venues',
+    systemPrompt: `You are an event planning expert. Help users plan and organize events of all types.`,
+    keywords: ['event', 'party', 'wedding', 'venue', 'conference', 'meeting', 'celebration'],
+    tools: [
+        { name: 'searchVenues', description: 'Find venues', parameters: ['location', 'capacity', 'type'] },
+        { name: 'findCaterer', description: 'Find catering', parameters: ['location', 'cuisine', 'headcount'] },
+        { name: 'bookTickets', description: 'Book tickets', parameters: ['event', 'quantity'] },
+    ],
+};
+// =============================================================================
+// Tool Implementations
+// =============================================================================
+export const EventPlannerTools = {
+    searchVenues: async (p) => ({
+        venues: [
+            { name: 'Grand Ballroom', capacity: p.capacity, price: 5000 },
+            { name: 'Rooftop Terrace', capacity: p.capacity, price: 3500 },
+        ]
+    }),
+    findCaterer: async (p) => ({
+        caterers: [
+            { name: 'Gourmet Events', pricePerPerson: 85 },
+            { name: 'Catering Plus', pricePerPerson: 65 },
+        ]
+    }),
+    bookTickets: async (p) => ({
+        event: p.event,
+        tickets: p.quantity,
+        total: p.quantity * 50,
+        confirmation: 'TICKET-' + Math.random().toString(36).slice(2, 8).toUpperCase()
+    }),
+};

package/dist/agents/fitness-coach.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition, ToolParams } from './types.js';
+export declare const FitnessCoachAgent: AgentDefinition;
+export declare const FitnessCoachTools: Record<string, (params: ToolParams) => Promise<unknown>>;

package/dist/agents/fitness-coach.js

@@ -0,0 +1,43 @@
+// =============================================================================
+// TERMINUS AGENTS - Fitness Coach Agent
+// =============================================================================
+// =============================================================================
+// Agent Definition
+// =============================================================================
+export const FitnessCoachAgent = {
+    id: 'fitness-coach',
+    name: 'Fitness Coach',
+    description: 'Creates workout plans and fitness advice',
+    systemPrompt: `You are a fitness coach. Create workout plans and provide health and fitness guidance.`,
+    keywords: ['fitness', 'workout', 'exercise', 'gym', 'weight', 'muscle', 'cardio', 'training', 'spor', 'egzersiz', 'antrenman', 'kilo'],
+    tools: [
+        { name: 'createWorkout', description: 'Create workout plan', parameters: ['goal', 'level', 'equipment'] },
+        { name: 'calculateCalories', description: 'Calculate calories', parameters: ['activity', 'duration'] },
+        { name: 'trackProgress', description: 'Track progress', parameters: ['metrics'] },
+    ],
+};
+// =============================================================================
+// Tool Implementations
+// =============================================================================
+export const FitnessCoachTools = {
+    createWorkout: async (p) => ({
+        goal: p.goal,
+        level: p.level,
+        workout: [
+            { exercise: 'Squats', sets: 3, reps: 12 },
+            { exercise: 'Push-ups', sets: 3, reps: 15 },
+            { exercise: 'Lunges', sets: 3, reps: 10 },
+            { exercise: 'Plank', duration: '60 seconds' },
+        ]
+    }),
+    calculateCalories: async (p) => ({
+        activity: p.activity,
+        duration: p.duration,
+        caloriesBurned: 350
+    }),
+    trackProgress: async (p) => ({
+        metrics: p.metrics,
+        trend: 'improving',
+        recommendation: 'Keep up the good work!'
+    }),
+};

package/dist/agents/food-expert.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition, ToolParams } from './types.js';
+export declare const FoodExpertAgent: AgentDefinition;
+export declare const FoodExpertTools: Record<string, (params: ToolParams) => Promise<unknown>>;

package/dist/agents/food-expert.js

@@ -0,0 +1,43 @@
+// =============================================================================
+// TERMINUS AGENTS - Food Expert Agent
+// =============================================================================
+// =============================================================================
+// Agent Definition
+// =============================================================================
+export const FoodExpertAgent = {
+    id: 'food-expert',
+    name: 'Food Expert',
+    description: 'Recommends restaurants and provides recipes',
+    systemPrompt: `You are a food and restaurant expert. Help users find great places to eat and provide recipe suggestions.`,
+    keywords: ['food', 'restaurant', 'recipe', 'cook', 'eat', 'cuisine', 'delivery', 'meal', 'yemek', 'restoran', 'tarif', 'mutfak'],
+    tools: [
+        { name: 'searchRestaurants', description: 'Find restaurants', parameters: ['location', 'cuisine', 'priceRange'] },
+        { name: 'getRecipes', description: 'Get recipes', parameters: ['dish', 'diet'] },
+        { name: 'findDelivery', description: 'Find delivery options', parameters: ['location', 'cuisine'] },
+    ],
+};
+// =============================================================================
+// Tool Implementations
+// =============================================================================
+export const FoodExpertTools = {
+    searchRestaurants: async (p) => ({
+        restaurants: [
+            { name: 'Nusret', cuisine: p.cuisine || 'Steakhouse', rating: 4.5, priceRange: '$$$' },
+            { name: 'Mikla', cuisine: 'Turkish', rating: 4.8, priceRange: '$$$$' },
+            { name: 'Harbor Kitchen', cuisine: 'Traditional', rating: 4.6, priceRange: '$$' },
+        ]
+    }),
+    getRecipes: async (p) => ({
+        dish: p.dish,
+        recipes: [
+            { name: `Classic ${p.dish}`, time: '30 min', difficulty: 'Easy' },
+            { name: `Gourmet ${p.dish}`, time: '60 min', difficulty: 'Medium' },
+        ]
+    }),
+    findDelivery: async (p) => ({
+        options: [
+            { service: 'Yemeksepeti', deliveryTime: '30-45 min', fee: 15 },
+            { service: 'Getir Yemek', deliveryTime: '20-30 min', fee: 10 },
+        ]
+    }),
+};

package/dist/agents/fundamental-analyst.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition, ToolParams } from './types.js';
+export declare const FundamentalAnalystAgent: AgentDefinition;
+export declare const FundamentalAnalystTools: Record<string, (params: ToolParams) => Promise<unknown>>;