OpenSIN SDK

The @opensin/sdk package provides the core building blocks for creating AI agents, tools, and workflows.

Installation

npm install @opensin/sdk

Module Overview

Module	Description
Agent Loop	ReAct loop with tool calling, streaming, and turn management
Tool System	Define, validate, and execute tools with JSON Schema parameters
Model Routing	Smart model selection based on task complexity
Memory Manager	Persistent memory with search, tags, and access tracking
Context Management	Token-aware context compression and sliding windows
Safety & Permissions	Destructive command detection and permission gates
Session Persistence	Save and restore agent sessions across restarts
Hooks & Lifecycle	Event-driven lifecycle hooks for agent customization
Parallel Execution	Concurrent tool execution with path-scoped locking
Usage & Pricing	Token counting and cost estimation per model

Quick Start

import {
  AgentLoop,
  ToolRegistry,
  SmartModelRouter,
  PermissionManager,
  SessionManager,
  ContextCompressor,
  SafetyDetector,
  UsagePricing,
} from '@opensin/sdk'

// 1. Set up model routing
const router = new SmartModelRouter({
  models: {
    trivial: 'gpt-4o-mini',
    simple: 'gpt-4o-mini',
    moderate: 'gpt-4o',
    complex: 'claude-sonnet-4-6',
    expert: 'claude-opus-4-6',
  },
})

// 2. Register tools
const tools = new ToolRegistry()
tools.register({
  name: 'read_file',
  description: 'Read a file from the workspace',
  parameters: {
    type: 'object',
    properties: {
      path: { type: 'string' },
    },
    required: ['path'],
  },
  execute: async ({ path }) => {
    const content = await fs.readFile(path, 'utf-8')
    return { content }
  },
})

// 3. Create the agent loop
const agent = new AgentLoop({
  model: router,
  tools,
  permissions: new PermissionManager({ mode: 'interactive' }),
  session: new SessionManager({ persistence: 'file' }),
  context: new ContextCompressor({ maxTokens: 8000 }),
  safety: new SafetyDetector(),
  pricing: new UsagePricing(),
  maxTurns: 25,
})

// 4. Run
const result = await agent.run('Read the README and summarize it')

Architecture

┌─────────────────────────────────────────────────┐
│                   Agent Loop                     │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │  Model   │  │  Tool    │  │   Context     │  │
│  │  Router  │  │  System  │  │   Compressor  │  │
│  └──────────┘  └──────────┘  └───────────────┘  │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Session  │  │ Safety   │  │   Permission  │  │
│  │ Manager  │  │ Detector │  │   Manager     │  │
│  └──────────┘  └──────────┘  └───────────────┘  │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │  Memory  │  │  Hooks   │  │   Usage       │  │
│  │  Manager │  │  System  │  │   Pricing     │  │
│  └──────────┘  └──────────┘  └───────────────┘  │
└─────────────────────────────────────────────────┘

Package Exports

All modules are exported from the main package entry:

import {
  // Agent Loop
  AgentLoop,
  
  // Tool System
  ToolRegistry,
  MCPStdioClient,
  
  // Intelligence
  SmartModelRouter,
  ContextCompressor,
  MemoryManager,
  FileMemoryProvider,
  
  // Safety
  SafetyDetector,
  PermissionManager,
  
  // Infrastructure
  SessionManager,
  HookSystem,
  ParallelToolExecutor,
  UsagePricing,
  
  // Prompt Building
  PromptBuilder,
  
  // Skills
  SkillSystem,
} from '@opensin/sdk'

Test Coverage

The SDK has 573+ passing tests across all modules, verified with Vitest:

cd packages/opensin-sdk
npm test

# Output:
# Test Files  15 passed
# Tests       573 passed
# Duration    4.2s