Skip to content

Version 2.0.0-alpha.1

Pre-release
Pre-release

Choose a tag to compare

View all tags
@sajeerzeji sajeerzeji released this 02 May 15:57
· 51 commits to main since this release
2.0.0-alpha.1
1d773c0

Toolpack SDK v2.0.0-alpha.1

Date: 2026-05-02

Highlights

  • Context window management primitives: token counter, message pruner, rolling summary utilities, and state manager with tests.
  • First-class SQLite-backed conversation store (SQLiteConversationStore) with optional FTS, plus improved in-memory store.
  • New OpenRouter provider adapter and tests.
  • Large suite of GitHub tools added (PR review, diffs, files, GraphQL, comments, etc.).
  • Refined tool orchestration and provider logging.
  • New examples demonstrating context window usage.

Breaking changes

  • Internal conversation modules were restructured. If you imported deep paths directly, update to use the public entry points:
    • Import types and stores from toolpack-sdk (re-exported) instead of toolpack-sdk/src/conversation/....
    • Public exports now include:
      • InMemoryConversationStore, SQLiteConversationStore
      • Types: ConversationScope, StoredMessage, GetOptions, ConversationStore, PromptMessage, AssembledPrompt
  • Message pruner behavior: when an assistant message with tool_calls is pruned, its paired tool result messages are also removed to avoid orphaned tool results that some providers reject. This is a behavioral change that should be API-compatible and reduce provider errors.

New features

  • Conversation stores
    • SQLiteConversationStore (WAL by default, optional FTS, pruning helpers, tested).
    • Reworked InMemoryConversationStore built on a generic LRU cache.
  • Context window management
    • utils/token-counter, utils/context-window-state, utils/message-pruner, utils/message-summarizer, plus related errors and tests.
  • Providers
    • New openrouter provider adapter and unit tests.
    • Improved provider logger and configuration surface.
  • Tools
    • GitHub tool family: content retrieval, PR diffs/files, GraphQL execution, PR reviews, replies, threads, comments, and more.
  • Examples
    • examples/context-window-*.ts showing basic, monitoring, multi-conversation, and summarization workflows.

Improvements

  • Cleaner public exports for conversation types/stores (src/conversation/index.ts).
  • More robust history querying/limiting in stores.
  • Better handling of duplicate or empty user messages in agent flows (paired work in agents package).

Configuration and environment

  • OpenRouter provider requires OPENROUTER_API_KEY.
  • GitHub tools require authentication via one of:
    • GITHUB_PAT (Personal Access Token), or
    • GitHub App credentials: GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY (with installation resolved from repo).

Fixes

  • Pruning now removes orphaned tool result messages with their originating assistant turn, preventing provider validation errors.

Migration notes

  • Replace any deep imports from src/conversation/{store,conv-types,participant} with the top-level toolpack-sdk exports. Example:
    • Before: import { InMemoryConversationStore } from 'toolpack-sdk/src/conversation/store'
    • After: import { InMemoryConversationStore, SQLiteConversationStore } from 'toolpack-sdk'
  • If you relied on keeping tool result messages when pruning assistant turns, note the new coupled removal.

Compatibility

  • Node.js >= 20

Install

  • npm i toolpack-sdk@alpha

@toolpack-sdk/knowledge v2.0.0-alpha.1

Date: 2026-05-02

Highlights

  • Hybrid retrieval: combine semantic and keyword search with tunable weighting.
  • New data sources: JSON, SQLite, and Postgres.
  • New embedder: OpenRouterEmbedder (routes to supported embedding models via OpenRouter).
  • Smarter persistent storage path resolution with seamless migration from old path.
  • Streaming batch ingestion with progress callbacks and single-item add() API.

Breaking/behavioral changes

  • knowledge_search default similarity threshold is now 0.3 (was 0.7) to improve recall for short queries. You can override per-call.
  • knowledge_search now uses hybrid retrieval by default (semantic + keyword) for more robust matching; you can set searchType explicitly if you prefer a single mode.
  • The PersistentKnowledgeProvider default base path is now ~/.toolpack/db/knowledge.
    • If an existing DB is found in the old path ~/.toolpack/knowledge, it will be used automatically (no manual migration needed).
  • Tool runtime logs were removed from knowledge_search to reduce console noise. Use your own logging or wrap the tool for diagnostics.

New features

  • Retrieval
    • searchType: semantic | keyword | hybrid with semanticWeight composition.
    • Hybrid result combiner with thresholding and metadata/vector inclusion options.
  • Sources
    • JSONSource, SQLiteSource, PostgresSource.
  • Embedders
    • OpenRouterEmbedder (alongside existing OpenAI and Ollama embedders).
  • Ingestion & operations
    • streamingBatchSize option for Knowledge.create and onEmbeddingProgress callback.
    • add(content, metadata?) for on-the-fly additions without full re-sync.
    • Provider getAllChunks()/keywordQuery() hooks and in-memory fallbacks.

Improvements

  • Safer provider initialization (dimension validation), robust batch fallback to per-chunk embedding on errors.
  • Consistent return mapping for tool results: content, score, metadata.

Migration notes

  • If you relied on the higher default threshold, set threshold: 0.7 explicitly in tool calls.
  • For storage paths customized previously, no action is needed; the provider continues to respect an explicit storagePath.

Compatibility

  • Node.js >= 20

Configuration

  • Embeddings: use OpenAIEmbedder (OpenAI) or OpenRouterEmbedder (requires OPENROUTER_API_KEY). Anthropic does not provide embeddings.

Install

  • npm i @toolpack-sdk/knowledge@alpha

@toolpack-sdk/agents v2.0.0-alpha.1

Date: 2026-05-02

Introduction

Initial alpha release of the Agent layer for Toolpack. Build, compose, and deploy AI agents with a consistent, extensible pattern on top of toolpack-sdk.

Highlights

  • Core framework
    • BaseAgent with event lifecycle, tool orchestration, mode support, and pluggable interceptors.
    • AgentRegistry for multi-agent composition and transport.
    • Capability agents: IntentClassifierAgent, SummarizerAgent.
  • Channels (ingress/egress)
    • Slack, Telegram, Discord, Email, SMS, Webhook, and Scheduled (cron) channels.
    • Typed configs and comprehensive tests across channels.
  • Conversation history
    • Pluggable history capture via interceptors, addressed-only mode, and conversation-aware prompt assembly.
    • Optional ConversationSearch tool exposure per conversation to fetch past turns.
  • Interceptor system
    • Dedup, noise filter, self-filter, rate-limit, participant resolver, capture, address-check, depth guard, tracer.
    • Composable chains with strong typing and skip semantics.
  • Testing utilities
    • Mocks and helpers to unit-test agents and channels.

Notable behaviors

  • Avoids emitting duplicate inbound user messages in assembled prompts and skips empty user messages (prevents provider errors).
  • Designed to pair with toolpack-sdk context-window primitives (token counter, pruner, summarizer) for robust long-running conversations.

Getting started

  • Install: npm i @toolpack-sdk/agents@alpha
  • Minimal code:
import { AgentRegistry, BaseAgent } from '@toolpack-sdk/agents';
  • See package README for Slack setup and multi-agent orchestration examples.

Configuration and environment

  • Channels require provider tokens/secrets as applicable (see README examples):
    • Slack: SLACK_BOT_TOKEN, SLACK_SIGNING_SECRET
    • Telegram: Bot token
    • Discord: Bot token
    • Email: SMTP creds (Nodemailer)
    • SMS: Twilio creds
  • If using knowledge tools with agents, ensure embeddings are configured via OPENAI_API_KEY or OPENROUTER_API_KEY in your app.
  • Tool usage can be guided or constrained via the SDK’s mode config (allowedToolCategories, allowedTools, and tool search settings).

Compatibility

  • Node.js >= 20
  • Peer dependencies: toolpack-sdk@^2.0.0-alpha, @toolpack-sdk/knowledge@^2.0.0-alpha (optional), plus channel-specific SDKs.
Assets 2
Loading