@kjerneverk/agentic 1.0.5-dev.0

package/.kodrdriv-test-cache.json

@@ -0,0 +1,6 @@
+{
+  "/Users/tobrien/gitw/kjerneverk/agentic": {
+    "lastTestRun": 1768074127850,
+    "lastCommitHash": "23023678fc20be16cd36468b537213576446dfb4"
+  }
+}

package/LICENSE

@@ -0,0 +1,18 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2025 Tim O'Brien
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/README.md

@@ -0,0 +1,167 @@
+# agentic
+
+Components for building agentic AI workflows - tool registry, context management, and conversation state tracking.
+
+## Installation
+
+```bash
+npm install agentic
+```
+
+## Features
+
+- **ToolRegistry** - Register, execute, and manage tools with usage tracking
+- **ContextManager** - Track and deduplicate injected context
+- **OpenAI/Anthropic Format** - Export tools in provider-specific formats
+
+## Usage
+
+### Tool Registry
+
+```typescript
+import { ToolRegistry, type Tool } from 'agentic';
+
+// Create registry
+const registry = ToolRegistry.create({
+  workingDirectory: process.cwd(),
+});
+
+// Register a tool
+registry.register({
+  name: 'read_file',
+  description: 'Read contents of a file',
+  parameters: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'File path to read' },
+    },
+    required: ['path'],
+  },
+  execute: async ({ path }) => {
+    const fs = await import('fs/promises');
+    return await fs.readFile(path, 'utf-8');
+  },
+  category: 'filesystem',
+  cost: 'cheap',
+});
+
+// Execute a tool
+const content = await registry.execute('read_file', { path: './README.md' });
+
+// Export for OpenAI
+const openAITools = registry.toOpenAIFormat();
+
+// Export for Anthropic
+const anthropicTools = registry.toAnthropicFormat();
+
+// Get usage statistics
+const stats = registry.getUsageStats();
+console.log(stats.get('read_file')); // { calls: 5, failures: 0, successRate: 1 }
+```
+
+### Context Manager
+
+```typescript
+import { ContextManager } from 'agentic';
+
+const context = new ContextManager();
+
+// Track context with deduplication
+context.track({
+  id: 'file:main.ts',
+  content: fileContent,
+  title: 'Main File',
+  category: 'source-code',
+  priority: 'high',
+}, 5); // position in conversation
+
+// Check for duplicates
+if (context.hasContext('file:main.ts')) {
+  console.log('Already provided');
+}
+
+// Query by category
+const sourceFiles = context.getByCategory('source-code');
+
+// Get statistics
+const stats = context.getStats();
+console.log(stats.totalItems);
+console.log(stats.byCategory);
+```
+
+### Tool Definition
+
+```typescript
+interface Tool {
+  name: string;
+  description: string;
+  parameters: {
+    type: 'object';
+    properties: Record<string, ToolParameter>;
+    required?: string[];
+  };
+  execute: (params: any, context?: ToolContext) => Promise<any>;
+  category?: string;
+  cost?: 'cheap' | 'moderate' | 'expensive';
+  examples?: ToolExample[];
+}
+```
+
+### Context Item
+
+```typescript
+interface DynamicContentItem {
+  content: string;
+  title?: string;
+  weight?: number;
+  id?: string;
+  category?: string;
+  source?: string;
+  priority?: 'high' | 'medium' | 'low';
+  timestamp?: Date;
+}
+```
+
+## API Reference
+
+### ToolRegistry
+
+| Method | Description |
+|--------|-------------|
+| `create(context?)` | Create a new registry |
+| `register(tool)` | Register a tool |
+| `registerAll(tools)` | Register multiple tools |
+| `execute(name, params)` | Execute a tool |
+| `executeBatch(calls)` | Execute multiple tools |
+| `toOpenAIFormat()` | Export for OpenAI |
+| `toAnthropicFormat()` | Export for Anthropic |
+| `getUsageStats()` | Get usage statistics |
+| `getMostUsed(limit)` | Get most used tools |
+| `getByCategory(category)` | Filter by category |
+
+### ContextManager
+
+| Method | Description |
+|--------|-------------|
+| `track(item, position)` | Track a context item |
+| `hasContext(id)` | Check if ID exists |
+| `hasContentHash(content)` | Check by content hash |
+| `hasSimilarContent(content)` | Fuzzy content match |
+| `getByCategory(category)` | Filter by category |
+| `getByPriority(priority)` | Filter by priority |
+| `getStats()` | Get statistics |
+| `remove(id)` | Remove by ID |
+| `clear()` | Clear all |
+
+## Related Packages
+
+- `execution` - Core provider interfaces
+- `execution-openai` - OpenAI provider
+- `execution-anthropic` - Anthropic provider
+- `execution-gemini` - Gemini provider
+
+## License
+
+Apache-2.0
+
+<!-- v1.0.0 -->

package/SECURITY.md

@@ -0,0 +1,94 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.x.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly.
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+## Security Features
+
+The agentic package includes security features for tool execution:
+
+### Tool Validation (ToolGuard)
+
+```typescript
+import { ToolGuard } from '@riotprompt/agentic';
+import { z } from 'zod';
+
+const guard = new ToolGuard({
+  enabled: true,
+  validateParams: true,
+  detectPrototypePollution: true,
+});
+
+// Register tool schemas
+guard.registerSchema('read_file', z.object({
+  path: z.string().max(1000),
+  encoding: z.enum(['utf8', 'base64']).optional(),
+}));
+
+// Validate before execution
+const result = guard.validate('read_file', params);
+if (!result.valid) {
+  // Handle validation failure
+}
+```
+
+### Tool Sandboxing (ToolSandbox)
+
+```typescript
+import { ToolSandbox } from '@riotprompt/agentic';
+
+const sandbox = new ToolSandbox({
+  enabled: true,
+  maxExecutionTime: 30000,
+  maxConcurrent: 5,
+  maxOutputSize: 1024 * 1024, // 1MB
+});
+
+// Execute with sandboxing
+const result = await sandbox.execute(
+  'my_tool',
+  async (signal) => {
+    // Tool implementation
+    // Check signal.aborted for cancellation
+  }
+);
+```
+
+### Security Features
+
+- **Parameter Validation**: Zod schema validation for all tool parameters
+- **Prototype Pollution Prevention**: Blocks `__proto__`, `constructor`, `prototype`
+- **Execution Timeouts**: Configurable timeouts for tool execution
+- **Concurrency Limits**: Limit concurrent tool executions
+- **Output Size Limits**: Prevent memory exhaustion from large outputs
+- **Allow/Deny Lists**: Control which tools can be executed
+- **Silent Logging**: Library logging disabled by default
+
+## Environment Variables
+
+```bash
+# Enable agentic logging
+AGENTIC_LOGGING=true
+
+# Or use DEBUG pattern
+DEBUG=*agentic*
+```
+
+## Security Checklist
+
+- [ ] Define Zod schemas for all tool parameters
+- [ ] Enable prototype pollution detection
+- [ ] Set appropriate execution timeouts
+- [ ] Configure concurrency limits
+- [ ] Use allow/deny lists for tools in production
+- [ ] Monitor tool execution metrics
+