ctxpkg 0.0.1 → 0.0.4

package/{src/tools/tools.types.ts → dist/tools/tools.types.d.ts}

@@ -1,5 +1,4 @@
 import * as z from 'zod';
-
 /**
  * Common tool definition format that can be converted to Langchain or MCP tools.
  *
@@ -7,29 +6,24 @@ import * as z from 'zod';
  * be adapted to different tool runtime environments.
  */
 type ToolDefinition<TInput extends z.ZodType = z.ZodType, TOutput = unknown> = {
-  /** Unique name for the tool */
-  name: string;
-  /** Description of what the tool does */
-  description: string;
-  /** Zod schema for input validation */
-  schema: TInput;
-  /** The handler function that executes the tool */
-  handler: (input: z.infer<TInput>) => Promise<TOutput>;
+    /** Unique name for the tool */
+    name: string;
+    /** Description of what the tool does */
+    description: string;
+    /** Zod schema for input validation */
+    schema: TInput;
+    /** The handler function that executes the tool */
+    handler: (input: z.infer<TInput>) => Promise<TOutput>;
 };
-
 /**
  * A collection of tool definitions - using eslint-disable for any here since
  * the specific tool types are erased when collecting into a record
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 type ToolDefinitions = Record<string, ToolDefinition<any, any>>;
-
 /**
  * Helper to create a type-safe tool definition
  */
-const defineTool = <TInput extends z.ZodType, TOutput>(
-  definition: ToolDefinition<TInput, TOutput>,
-): ToolDefinition<TInput, TOutput> => definition;
-
+declare const defineTool: <TInput extends z.ZodType, TOutput>(definition: ToolDefinition<TInput, TOutput>) => ToolDefinition<TInput, TOutput>;
 export { defineTool };
 export type { ToolDefinition, ToolDefinitions };
+//# sourceMappingURL=tools.types.d.ts.map

package/dist/tools/tools.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.types.d.ts","sourceRoot":"","sources":["../../src/tools/tools.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB;;;;;GAKG;AACH,KAAK,cAAc,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI;IAC7E,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD,CAAC;AAEF;;;GAGG;AAEH,KAAK,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAEhE;;GAEG;AACH,QAAA,MAAM,UAAU,GAAI,MAAM,SAAS,CAAC,CAAC,OAAO,EAAE,OAAO,EACnD,YAAY,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1C,cAAc,CAAC,MAAM,EAAE,OAAO,CAAe,CAAC;AAEjD,OAAO,EAAE,UAAU,EAAE,CAAC;AACtB,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC"}

package/dist/tools/tools.types.js

@@ -0,0 +1,7 @@
+import * as z from 'zod';
+/**
+ * Helper to create a type-safe tool definition
+ */
+const defineTool = (definition) => definition;
+export { defineTool };
+//# sourceMappingURL=tools.types.js.map

package/dist/tools/tools.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.types.js","sourceRoot":"","sources":["../../src/tools/tools.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AA0BzB;;GAEG;AACH,MAAM,UAAU,GAAG,CACjB,UAA2C,EACV,EAAE,CAAC,UAAU,CAAC;AAEjD,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/exports.ts","../src/agent/agent.prompts.ts","../src/agent/agent.test-runner.schemas.ts","../src/agent/agent.test-runner.ts","../src/agent/agent.ts","../src/agent/agent.types.ts","../src/backend/backend.protocol.ts","../src/backend/backend.schemas.ts","../src/backend/backend.services.ts","../src/backend/backend.ts","../src/backend/backend.types.ts","../src/cli/cli.agent.ts","../src/cli/cli.chat.ts","../src/cli/cli.client.ts","../src/cli/cli.collections.ts","../src/cli/cli.config.ts","../src/cli/cli.daemon.ts","../src/cli/cli.documents.ts","../src/cli/cli.mcp.ts","../src/cli/cli.ts","../src/cli/cli.utils.ts","../src/client/client.adapters.ts","../src/client/client.ts","../src/client/client.types.ts","../src/collections/collections.schemas.ts","../src/collections/collections.ts","../src/config/config.ts","../src/daemon/daemon.config.ts","../src/daemon/daemon.manager.ts","../src/daemon/daemon.schemas.ts","../src/daemon/daemon.ts","../src/database/database.ts","../src/database/migrations/migrations.001-init.ts","../src/database/migrations/migrations.002-fts5.ts","../src/database/migrations/migrations.ts","../src/database/migrations/migrations.types.ts","../src/documents/documents.schemas.ts","../src/documents/documents.ts","../src/embedder/embedder.ts","../src/mcp/mcp.ts","../src/tools/tools.langchain.ts","../src/tools/tools.mcp.ts","../src/tools/tools.types.ts","../src/tools/agent/agent.ts","../src/tools/documents/documents.ts","../src/utils/utils.services.ts"],"version":"5.9.3"}

package/dist/utils/utils.services.d.ts

@@ -0,0 +1,14 @@
+declare const destroy: unique symbol;
+declare const instanceKey: unique symbol;
+type ServiceDependency<T> = new (services: Services) => T & {
+    [destroy]?: () => Promise<void> | void;
+};
+declare class Services {
+    [instanceKey]: Map<ServiceDependency<unknown>, unknown>;
+    constructor();
+    get: <T>(service: ServiceDependency<T>) => T;
+    set: <T>(service: ServiceDependency<T>, instance: Partial<T>) => void;
+    destroy: () => Promise<void>;
+}
+export { Services, destroy };
+//# sourceMappingURL=utils.services.d.ts.map

package/dist/utils/utils.services.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.services.d.ts","sourceRoot":"","sources":["../../src/utils/utils.services.ts"],"names":[],"mappings":"AAAA,QAAA,MAAM,OAAO,eAAoB,CAAC;AAClC,QAAA,MAAM,WAAW,eAAsB,CAAC;AAExC,KAAK,iBAAiB,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,QAAQ,KAAK,CAAC,GAAG;IAC1D,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACxC,CAAC;AAEF,cAAM,QAAQ;IACZ,CAAC,WAAW,CAAC,EAAE,GAAG,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;;IAMjD,GAAG,GAAI,CAAC,EAAE,SAAS,iBAAiB,CAAC,CAAC,CAAC,KAQzB,CAAC,CACpB;IAEK,GAAG,GAAI,CAAC,EAAE,SAAS,iBAAiB,CAAC,CAAC,CAAC,EAAE,UAAU,OAAO,CAAC,CAAC,CAAC,UAElE;IAEK,OAAO,sBAaZ;CACH;AAED,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC"}

package/dist/utils/utils.services.js

@@ -0,0 +1,33 @@
+const destroy = Symbol('destroy');
+const instanceKey = Symbol('instances');
+class Services {
+    [instanceKey];
+    constructor() {
+        this[instanceKey] = new Map();
+    }
+    get = (service) => {
+        if (!this[instanceKey].has(service)) {
+            this[instanceKey].set(service, new service(this));
+        }
+        const instance = this[instanceKey].get(service);
+        if (!instance) {
+            throw new Error('Could not generate instance');
+        }
+        return instance;
+    };
+    set = (service, instance) => {
+        this[instanceKey].set(service, instance);
+    };
+    destroy = async () => {
+        await Promise.all(Array.from(this[instanceKey].values()).map(async (instance) => {
+            if (typeof instance === 'object' &&
+                instance &&
+                destroy in instance &&
+                typeof instance[destroy] === 'function') {
+                await instance[destroy]();
+            }
+        }));
+    };
+}
+export { Services, destroy };
+//# sourceMappingURL=utils.services.js.map

package/dist/utils/utils.services.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.services.js","sourceRoot":"","sources":["../../src/utils/utils.services.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;AAClC,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;AAMxC,MAAM,QAAQ;IACZ,CAAC,WAAW,CAAC,CAA2C;IAExD;QACE,IAAI,CAAC,WAAW,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC;IAChC,CAAC;IAEM,GAAG,GAAG,CAAI,OAA6B,EAAE,EAAE;QAChD,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACpD,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAChD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,QAAa,CAAC;IACvB,CAAC,CAAC;IAEK,GAAG,GAAG,CAAI,OAA6B,EAAE,QAAoB,EAAE,EAAE;QACtE,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC,CAAC;IAEK,OAAO,GAAG,KAAK,IAAI,EAAE;QAC1B,MAAM,OAAO,CAAC,GAAG,CACf,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;YAC5D,IACE,OAAO,QAAQ,KAAK,QAAQ;gBAC5B,QAAQ;gBACR,OAAO,IAAI,QAAQ;gBACnB,OAAO,QAAQ,CAAC,OAAO,CAAC,KAAK,UAAU,EACvC,CAAC;gBACD,MAAM,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,CAAC;QACH,CAAC,CAAC,CACH,CAAC;IACJ,CAAC,CAAC;CACH;AAED,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC"}

package/package.json

@@ -1,11 +1,14 @@
 {
   "type": "module",
   "main": "dist/exports.js",
+  "repository": {
+    "url": "https://github.com/morten-olsen/ctxpkg"
+  },
   "bin": {
     "ctxpkg": "./bin/cli.js"
   },
   "files": [
-    "src",
+    "dist",
     "bin"
   ],
   "exports": {
@@ -31,7 +34,7 @@
     "vitest": "4.0.17"
   },
   "name": "ctxpkg",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "license": "AGPL-3.0",
   "imports": {
     "#root/*": "./src/*"

package/src/agent/AGENTS.md

@@ -1,249 +0,0 @@
-# Agent — Agent Guidelines
-
-This document describes the agent module architecture for AI agents working on this codebase.
-
-## Overview
-
-The agent module provides a LangChain-based agent that uses document tools to search and synthesize information. It's designed to reduce token/context costs by consolidating multiple tool calls into a single, synthesized answer.
-
-## File Structure
-
-| File | Purpose |
-|------|---------|
-| `agent.ts` | Main agent implementation, factory, and retry logic |
-| `agent.types.ts` | TypeScript types and Zod schemas |
-| `agent.prompts.ts` | System prompts and templates |
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                        DocumentAgent                                │
-│  ┌───────────────────────────────────────────────────────────────┐  │
-│  │                    LangGraph React Agent                      │  │
-│  │                                                               │  │
-│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐   │  │
-│  │  │   search    │  │ get_section │  │ get_document, etc.  │   │  │
-│  │  └─────────────┘  └─────────────┘  └─────────────────────┘   │  │
-│  │                                                               │  │
-│  │  Uses configured LLM (OpenAI-compatible API)                  │  │
-│  └───────────────────────────────────────────────────────────────┘  │
-│                                                                     │
-│  Features:                                                          │
-│  • Verbose mode with step callbacks                                 │
-│  • Conversation history for multi-turn chat                         │
-│  • Collection filtering via system prompt                           │
-│  • Retry logic with exponential backoff                             │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-## Usage
-
-### Creating an Agent
-
-```typescript
-import { createDocumentAgent, getLLMConfigFromAppConfig } from '#root/agent/agent.ts';
-import { createClient } from '#root/client/client.ts';
-
-const client = await createClient({ mode: 'daemon' });
-const llmConfig = await getLLMConfigFromAppConfig();
-
-const agent = createDocumentAgent({
-  client,
-  llmConfig,
-  aliasMap: new Map([['docs', 'pkg:file://./docs/manifest.json']]),
-  collections: ['docs'],  // Optional: restrict to specific collections
-  onStep: (step) => console.log(step),  // Optional: verbose callbacks
-});
-
-// One-shot query (stateless)
-const response = await agent.ask(
-  'How do I implement streaming?',
-  'Building a chatbot that streams responses'
-);
-
-console.log(response.answer);
-console.log(response.sources);
-console.log(response.confidence);
-```
-
-### Multi-turn Conversation
-
-```typescript
-// First message
-const response1 = await agent.chat(
-  'What authentication methods are available?',
-  'Building a secure API'
-);
-
-// Follow-up (maintains conversation context)
-const response2 = await agent.chat(
-  'How do I implement the OAuth2 option?',
-  'Building a secure API'
-);
-
-// Clear history when starting new topic
-agent.clearHistory();
-```
-
-### Verbose Mode
-
-```typescript
-const agent = createDocumentAgent({
-  client,
-  llmConfig,
-  onStep: (step) => {
-    switch (step.type) {
-      case 'thinking':
-        console.log(`[thinking] ${step.content}`);
-        break;
-      case 'tool_call':
-        console.log(`[tool] ${step.toolName}`);
-        console.log(`  Input: ${JSON.stringify(step.toolInput)}`);
-        break;
-      case 'tool_result':
-        console.log(`[result] ${step.content}`);
-        break;
-      case 'error':
-        console.log(`[retry] ${step.content}`);
-        break;
-    }
-  },
-});
-```
-
-### Agent Response Format
-
-```typescript
-type AgentResponse = {
-  answer: string;           // Synthesized answer
-  sources: Array<{          // References used
-    collection: string;
-    document: string;
-    section?: string;
-  }>;
-  confidence: 'high' | 'medium' | 'low';
-  note?: string;            // Optional note
-};
-```
-
-## LLM Configuration
-
-The agent uses configuration from `config.ts`:
-
-```typescript
-llm: {
-  provider: string;    // OpenAI-compatible API base URL
-  model: string;       // Model identifier
-  apiKey: string;      // API key
-  temperature: number; // 0-2
-  maxTokens: number;   // Max response tokens
-}
-```
-
-Configure via CLI:
-
-```bash
-ctxpkg config set llm.apiKey sk-...
-ctxpkg config set llm.model gpt-4o
-ctxpkg config set llm.provider https://api.openai.com/v1
-```
-
-Or via environment variables:
-
-```bash
-export CTXPKG_LLM_API_KEY=sk-...
-export CTXPKG_LLM_MODEL=gpt-4o
-```
-
-## Agent Design
-
-### Tool Selection
-
-The agent uses LangGraph's React agent pattern with these tools:
-
-- `documents_search` — Semantic search across collections
-- `documents_list_documents` — Browse collection contents
-- `documents_get_outline` — Get document structure
-- `documents_get_section` — Get specific sections
-- `documents_get_document` — Get full documents
-- `documents_list_collections` — List available collections
-- `documents_search_batch` — Batch searches
-- `documents_find_related` — Find related content
-
-### Termination
-
-The agent stops when:
-
-1. It has synthesized a complete answer (JSON response)
-2. Maximum iterations reached (default: 15)
-3. No more relevant information to find
-
-### Response Parsing
-
-The agent is prompted to respond in JSON format. The parser:
-
-1. Looks for ```json code blocks
-2. Tries to parse the whole content as JSON
-3. Falls back to treating content as plain answer
-
-### Retry Logic
-
-The agent automatically retries on transient errors:
-
-- **Rate limits**: 429 errors
-- **Server errors**: 500, 502, 503, 504
-- **Network errors**: ECONNRESET, ETIMEDOUT
-
-Retry configuration:
-- Max retries: 3
-- Initial delay: 1000ms
-- Max delay: 30000ms
-- Backoff multiplier: 2x
-
-```typescript
-import { withRetry, isRetryableError } from '#root/agent/agent.ts';
-
-// Use retry logic for custom async operations
-const result = await withRetry(
-  () => someAsyncOperation(),
-  { maxRetries: 3, initialDelayMs: 1000, maxDelayMs: 30000, backoffMultiplier: 2 },
-  (attempt, error, delayMs) => console.log(`Retry ${attempt}: ${error.message}`)
-);
-```
-
-## Key Patterns
-
-### Lazy Config Loading
-
-Config is loaded dynamically to avoid circular imports:
-
-```typescript
-const getLLMConfigFromAppConfig = async (): Promise<LLMConfig> => {
-  const { config } = await import('#root/config/config.ts');
-  // ...
-};
-```
-
-### Tool Conversion
-
-Document tools are defined once and converted for LangChain:
-
-```typescript
-const toolDefinitions = createDocumentToolDefinitions({ client, aliasMap });
-const langchainTools = toLangchainTools(toolDefinitions);
-```
-
-### Collection Filtering
-
-Collections can be restricted via the `collections` option:
-
-```typescript
-const agent = createDocumentAgent({
-  client,
-  llmConfig,
-  collections: ['my-docs', 'api-docs'],  // Only search these
-});
-```
-
-This adds instructions to the system prompt telling the agent to pass these collections in all search calls.

package/src/agent/agent.test-runner.schemas.ts

@@ -1,158 +0,0 @@
-import * as z from 'zod';
-
-/**
- * Validation modes for test assertions
- */
-export const validationModeSchema = z.enum(['semantic', 'llm', 'keywords']);
-export type ValidationMode = z.infer<typeof validationModeSchema>;
-
-/**
- * Individual test case
- */
-export const testCaseSchema = z.object({
-  /** Unique identifier for the test */
-  id: z.string(),
-
-  /** The question to ask the agent */
-  query: z.string(),
-
-  /** Use case context for the question */
-  useCase: z.string(),
-
-  /** Expected answer description or reference answer */
-  expected: z.string(),
-
-  /** Keywords that should appear in the answer (for keywords mode) */
-  keywords: z.array(z.string()).optional(),
-
-  /** Override validation mode for this specific test */
-  validationMode: validationModeSchema.optional(),
-
-  /** Custom validation instructions for LLM mode */
-  validationInstructions: z.string().optional(),
-
-  /** Override pass threshold for this specific test (0-1) */
-  passThreshold: z.number().min(0).max(1).optional(),
-
-  /** Whether this test is currently skipped */
-  skip: z.boolean().optional(),
-});
-
-export type TestCase = z.infer<typeof testCaseSchema>;
-
-/**
- * Collection specification (same as context.json format)
- */
-export const collectionSpecSchema = z.object({
-  url: z.string(),
-});
-
-export type CollectionSpec = z.infer<typeof collectionSpecSchema>;
-
-/**
- * Test suite options
- */
-export const testOptionsSchema = z.object({
-  /** Default validation mode (default: semantic) */
-  validationMode: validationModeSchema.optional().default('semantic'),
-
-  /** Pass threshold for semantic similarity (0-1, default: 0.75) */
-  passThreshold: z.number().min(0).max(1).optional().default(0.75),
-
-  /** Default validation instructions for LLM mode */
-  validationInstructions: z.string().optional(),
-
-  /** Maximum time per test in milliseconds (default: 60000) */
-  timeoutMs: z.number().optional().default(60000),
-});
-
-export type TestOptions = z.infer<typeof testOptionsSchema>;
-
-/**
- * Complete test suite file structure
- */
-export const testSuiteSchema = z.object({
-  /** Name of the test suite */
-  name: z.string(),
-
-  /** Description of what this test suite covers */
-  description: z.string().optional(),
-
-  /** Collections to sync before running tests */
-  collections: z.record(z.string(), collectionSpecSchema),
-
-  /** Test suite options */
-  options: testOptionsSchema.optional(),
-
-  /** Test cases */
-  tests: z.array(testCaseSchema).min(1),
-});
-
-export type TestSuite = z.infer<typeof testSuiteSchema>;
-
-/**
- * Result of a single test case
- */
-export const testResultSchema = z.object({
-  /** Test case ID */
-  id: z.string(),
-
-  /** Whether the test passed */
-  passed: z.boolean(),
-
-  /** Score (0-1) for semantic/llm validation */
-  score: z.number().optional(),
-
-  /** The agent's actual answer */
-  actualAnswer: z.string(),
-
-  /** Validation reasoning (from LLM mode) or match details */
-  reasoning: z.string().optional(),
-
-  /** Keywords found (for keywords mode) */
-  keywordsFound: z.array(z.string()).optional(),
-
-  /** Keywords missing (for keywords mode) */
-  keywordsMissing: z.array(z.string()).optional(),
-
-  /** Time taken in milliseconds */
-  durationMs: z.number(),
-
-  /** Error message if the test failed to run */
-  error: z.string().optional(),
-
-  /** Whether the test was skipped */
-  skipped: z.boolean().optional(),
-});
-
-export type TestResult = z.infer<typeof testResultSchema>;
-
-/**
- * Complete test run results
- */
-export const testRunResultSchema = z.object({
-  /** Test suite name */
-  suiteName: z.string(),
-
-  /** When the test run started */
-  startedAt: z.string(),
-
-  /** When the test run completed */
-  completedAt: z.string(),
-
-  /** Total duration in milliseconds */
-  durationMs: z.number(),
-
-  /** Summary statistics */
-  summary: z.object({
-    total: z.number(),
-    passed: z.number(),
-    failed: z.number(),
-    skipped: z.number(),
-  }),
-
-  /** Individual test results */
-  results: z.array(testResultSchema),
-});
-
-export type TestRunResult = z.infer<typeof testRunResultSchema>;