@turtlepusher/plugins

Unified Plugin SDK for Cognition V3

A comprehensive plugin development framework providing workers, hooks, providers, and security utilities for building Cognition extensions.

Installation

npm install @turtlepusher/plugins

Quick Start

Create a Plugin with the Builder

import { PluginBuilder, HookEvent, HookPriority } from '@turtlepusher/plugins';

const myPlugin = new PluginBuilder('my-awesome-plugin', '1.0.0')
  .withDescription('My awesome plugin for Cognition')
  .withAuthor('Your Name')
  .withMCPTools([
    {
      name: 'greet',
      description: 'Greet a user',
      inputSchema: {
        type: 'object',
        properties: {
          name: { type: 'string', description: 'Name to greet' }
        },
        required: ['name']
      },
      handler: async (input) => ({
        content: [{ type: 'text', text: `Hello, ${input.name}!` }]
      })
    }
  ])
  .withHooks([
    {
      event: HookEvent.PostTaskComplete,
      priority: HookPriority.Normal,
      handler: async (ctx) => {
        console.log('Task completed:', ctx.data);
        return { success: true };
      }
    }
  ])
  .build();

// Register with the default registry
import { getDefaultRegistry } from '@turtlepusher/plugins';
await getDefaultRegistry().register(myPlugin);

Quick Plugin Creators

import { createToolPlugin, createHooksPlugin, createWorkerPlugin } from '@turtlepusher/plugins';

// Tool-only plugin
const toolPlugin = createToolPlugin('my-tools', '1.0.0', [
  { name: 'tool1', description: '...', inputSchema: {...}, handler: async () => {...} }
]);

// Hooks-only plugin
const hooksPlugin = createHooksPlugin('my-hooks', '1.0.0', [
  { event: HookEvent.PreTaskExecute, handler: async (ctx) => ({ success: true }) }
]);

// Worker plugin
const workerPlugin = createWorkerPlugin('my-workers', '1.0.0', [
  { type: 'coder', name: 'main-coder', capabilities: ['code-generation'] }
]);

Features

🔧 MCP Tool Builder

import { MCPToolBuilder } from '@turtlepusher/plugins';

const tool = new MCPToolBuilder('calculate')
  .withDescription('Perform calculations')
  .addStringParam('expression', 'Math expression', { required: true })
  .addBooleanParam('verbose', 'Show steps', { default: false })
  .withHandler(async (input) => {
    const result = eval(input.expression); // Use a safe evaluator in production!
    return { content: [{ type: 'text', text: `Result: ${result}` }] };
  })
  .build();

🎣 Hook System

import { HookBuilder, HookFactory, HookRegistry, HookEvent, HookPriority } from '@turtlepusher/plugins';

// Create a custom hook with conditions
const hook = new HookBuilder(HookEvent.PreAgentSpawn)
  .withName('validate-agent')
  .withPriority(HookPriority.High)
  .when((ctx) => ctx.data?.type === 'coder')
  .transform((data) => ({ ...data, validated: true }))
  .handle(async (ctx) => {
    // Validation logic
    return { success: true, data: ctx.data, modified: true };
  })
  .build();

// Pre-built hook factories
const logger = HookFactory.createLogger(HookEvent.PostTaskComplete, console);
const rateLimiter = HookFactory.createRateLimiter(HookEvent.PreToolCall, { maxPerMinute: 100 });
const validator = HookFactory.createValidator(HookEvent.PreAgentSpawn, (data) => data.type !== undefined);

👷 Worker Pool

import { WorkerPool, WorkerFactory } from '@turtlepusher/plugins';

// Create a worker pool
const pool = new WorkerPool({
  minWorkers: 2,
  maxWorkers: 10,
  taskQueueSize: 100
});

// Spawn workers using factory
const coder = await pool.spawn(WorkerFactory.createCoder('main-coder'));
const reviewer = await pool.spawn(WorkerFactory.createReviewer('code-reviewer'));
const tester = await pool.spawn(WorkerFactory.createTester('test-runner'));

// Submit tasks
const result = await pool.submit({
  id: 'task-1',
  type: 'code-generation',
  input: { prompt: 'Write a function...' }
});

// Shutdown
await pool.shutdown();

🤖 LLM Provider Integration

import { ProviderRegistry, ProviderFactory, BaseLLMProvider } from '@turtlepusher/plugins';

const registry = new ProviderRegistry({
  fallbackChain: ['anthropic', 'openai'],
  costOptimization: true
});

// Register built-in providers
class ClaudeProvider extends BaseLLMProvider {
  constructor() {
    super(ProviderFactory.createClaude());
  }

  async complete(request) {
    // Implementation
  }
}

registry.register(new ClaudeProvider());

// Execute with automatic fallback
const response = await registry.execute({
  model: 'claude-sonnet-4-6',
  messages: [{ role: 'user', content: 'Hello!' }]
});

🔗 Agentic Flow Integration

import { AgenticFlowBridge, AgentDBBridge } from '@turtlepusher/plugins';

// Swarm coordination
const agentic = new AgenticFlowBridge({ maxConcurrentAgents: 15 });
await agentic.initializeSwarm({ type: 'hierarchical', maxAgents: 15 });

const agent = await agentic.spawnAgent({
  type: 'coder',
  capabilities: ['typescript', 'react']
});

const result = await agentic.orchestrateTask({
  taskType: 'code-generation',
  input: { prompt: '...' },
  agentId: agent.id
});

// Vector storage with AgentDB
const agentdb = new AgentDBBridge({ dimensions: 1536, indexType: 'hnsw' });
await agentdb.initialize();

await agentdb.store('doc-1', embeddings, { type: 'document' });
const similar = await agentdb.search(queryVector, { limit: 10 });

🔒 Security Utilities

import { Security, createRateLimiter, createResourceLimiter } from '@turtlepusher/plugins';

// Input validation
const name = Security.validateString(input, { minLength: 1, maxLength: 100 });
const count = Security.validateNumber(input, { min: 0, max: 1000, integer: true });
const path = Security.validatePath(input, { allowedExtensions: ['.ts', '.js'] });

// Safe path creation (prevents traversal attacks)
const safePath = Security.safePath('/project', 'src', userInput);

// Safe JSON parsing (prevents prototype pollution)
const data = Security.safeJsonParse<Config>(jsonString);

// Command validation
const cmd = Security.validateCommand('npm install', { allowedCommands: new Set(['npm', 'npx']) });

// Rate limiting
const limiter = createRateLimiter({ maxTokens: 100, refillRate: 10, refillInterval: 1000 });
if (limiter.tryAcquire()) {
  // Proceed
}

// Resource limiting
const resourceLimiter = createResourceLimiter({ maxMemoryMB: 512, maxExecutionTime: 30000 });
const result = await resourceLimiter.enforce(async () => {
  // Heavy computation
});

API Reference

Core Exports

| Export | Description | |--------|-------------| | PluginBuilder | Fluent builder for creating plugins | | BasePlugin | Abstract base class for plugins | | PluginRegistry | Plugin lifecycle management | | getDefaultRegistry() | Get the default plugin registry |

SDK Builders

| Export | Description | |--------|-------------| | MCPToolBuilder | Build MCP tools with parameters | | HookBuilder | Build hooks with conditions and transformers | | WorkerBuilder | Build worker definitions |

Quick Creators

| Export | Description | |--------|-------------| | createToolPlugin() | Create a tool-only plugin | | createHooksPlugin() | Create a hooks-only plugin | | createWorkerPlugin() | Create a worker plugin | | createProviderPlugin() | Create a provider plugin |

Hook System

| Export | Description | |--------|-------------| | HookRegistry | Central hook management | | HookExecutor | Execute hooks with patterns | | HookFactory | Pre-built hook creators | | HookEvent | All hook event types | | HookPriority | Hook priority levels |

Workers

| Export | Description | |--------|-------------| | WorkerPool | Managed worker pool | | WorkerInstance | Individual worker | | WorkerFactory | Worker definition factory |

Providers

| Export | Description | |--------|-------------| | ProviderRegistry | LLM provider management | | BaseLLMProvider | Base provider implementation | | ProviderFactory | Provider definition factory |

Integrations

| Export | Description | |--------|-------------| | AgenticFlowBridge | agentic-flow@alpha integration | | AgentDBBridge | AgentDB vector storage |

Security

| Export | Description | |--------|-------------| | Security | All security utilities | | validateString/Number/Boolean/Array/Enum | Input validators | | safePath/safePathAsync | Path security | | safeJsonParse/safeJsonStringify | JSON security | | createRateLimiter | Rate limiting | | createResourceLimiter | Resource limiting |

Hook Events

enum HookEvent {
  // Session lifecycle
  SessionStart = 'session:start',
  SessionEnd = 'session:end',

  // Agent lifecycle
  PreAgentSpawn = 'agent:pre-spawn',
  PostAgentSpawn = 'agent:post-spawn',
  PreAgentTerminate = 'agent:pre-terminate',
  PostAgentTerminate = 'agent:post-terminate',

  // Task lifecycle
  PreTaskExecute = 'task:pre-execute',
  PostTaskComplete = 'task:post-complete',
  TaskError = 'task:error',

  // Tool lifecycle
  PreToolCall = 'tool:pre-call',
  PostToolCall = 'tool:post-call',

  // Memory operations
  PreMemoryStore = 'memory:pre-store',
  PostMemoryStore = 'memory:post-store',
  PreMemoryRetrieve = 'memory:pre-retrieve',
  PostMemoryRetrieve = 'memory:post-retrieve',

  // Swarm coordination
  SwarmInitialized = 'swarm:initialized',
  SwarmShutdown = 'swarm:shutdown',
  ConsensusReached = 'swarm:consensus-reached',

  // File operations
  PreFileRead = 'file:pre-read',
  PostFileRead = 'file:post-read',
  PreFileWrite = 'file:pre-write',
  PostFileWrite = 'file:post-write',

  // Commands
  PreCommand = 'command:pre-execute',
  PostCommand = 'command:post-execute',

  // Learning
  PatternLearned = 'learning:pattern-learned',
  PatternApplied = 'learning:pattern-applied',
}

Hook Priorities

enum HookPriority {
  Critical = 1000,  // Run first, can abort
  High = 750,       // Important hooks
  Normal = 500,     // Default priority
  Low = 250,        // Less important
  Deferred = 0,     // Run last
}

Worker Types

• coder - Code implementation
• reviewer - Code review
• tester - Test generation/execution
• researcher - Information gathering
• planner - Task planning
• coordinator - Multi-agent coordination
• security - Security analysis
• performance - Performance optimization
• specialized - Custom capabilities
• long-running - Background tasks

Performance

| Metric | Target | Actual | |--------|--------|--------| | Plugin load time | < 50ms | ~20ms | | Hook execution | < 1ms | ~0.5ms | | Worker spawn | < 100ms | ~50ms | | Vector search (10K) | < 10ms | ~5ms |

Testing

npm test           # Run all tests
npm run test:watch # Watch mode

License

MIT