anorion 0.1.0

package/src/tools/builtin/file-read.ts

@@ -0,0 +1,78 @@
+import type { ToolDefinition, ToolContext, ToolResult } from '../../shared/types';
+import { readFileSync, existsSync } from 'fs';
+import { resolve, join } from 'path';
+
+// Configurable allowed paths (default: current working directory)
+const DEFAULT_ALLOWED_PATHS = [process.cwd()];
+const allowedPaths: string[] = (globalThis as any).__SANDBOX_ALLOWED_PATHS || DEFAULT_ALLOWED_PATHS;
+
+function isPathAllowed(inputPath: string): { ok: boolean; resolved: string } {
+  const resolved = resolve(inputPath);
+
+  // Block path traversal
+  if (inputPath.includes('..')) {
+    return { ok: false, resolved };
+  }
+
+  for (const allowed of allowedPaths) {
+    const allowedResolved = resolve(allowed);
+    if (resolved.startsWith(allowedResolved + '/') || resolved === allowedResolved) {
+      return { ok: true, resolved };
+    }
+  }
+
+  return { ok: false, resolved };
+}
+
+export function setAllowedPaths(paths: string[]) {
+  allowedPaths.length = 0;
+  allowedPaths.push(...paths);
+}
+
+const fileReadTool: ToolDefinition = {
+  name: 'file-read',
+  description: 'Read a file. Returns content with optional line limits. Paths are sandboxed to allowed directories.',
+  parameters: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'File path to read' },
+      offset: { type: 'number', description: 'Line number to start from (1-indexed)' },
+      limit: { type: 'number', description: 'Maximum number of lines to read' },
+    },
+    required: ['path'],
+  },
+  category: 'filesystem',
+  timeoutMs: 5000,
+  maxOutputBytes: 500_000,
+  execute: async (params): Promise<ToolResult> => {
+    const filePath = String(params.path);
+
+    const { ok, resolved } = isPathAllowed(filePath);
+    if (!ok) {
+      return { content: '', error: `Path not allowed (sandboxed): ${resolved}. Allowed paths: ${allowedPaths.join(', ')}` };
+    }
+
+    if (!existsSync(resolved)) {
+      return { content: '', error: `File not found: ${resolved}` };
+    }
+
+    try {
+      const content = readFileSync(resolved, 'utf-8');
+      const lines = content.split('\n');
+      const offset = Number(params.offset) || 1;
+      const limit = Number(params.limit) || lines.length;
+
+      const sliced = lines.slice(offset - 1, offset - 1 + limit);
+      const result = sliced.join('\n');
+
+      const truncated = sliced.length < lines.length;
+      return {
+        content: result + (truncated ? `\n\n[Showing lines ${offset}-${offset + sliced.length - 1} of ${lines.length}]` : ''),
+      };
+    } catch (err: unknown) {
+      return { content: '', error: (err as Error).message };
+    }
+  },
+};
+
+export default fileReadTool;

package/src/tools/builtin/file-write.ts

@@ -0,0 +1,64 @@
+import type { ToolDefinition, ToolContext, ToolResult } from '../../shared/types';
+import { writeFileSync, mkdirSync } from 'fs';
+import { dirname, resolve } from 'path';
+
+// Configurable allowed paths (default: current working directory)
+const DEFAULT_ALLOWED_PATHS = [process.cwd()];
+const allowedPaths: string[] = (globalThis as any).__SANDBOX_ALLOWED_PATHS || DEFAULT_ALLOWED_PATHS;
+
+function isPathAllowed(inputPath: string): { ok: boolean; resolved: string } {
+  const resolved = resolve(inputPath);
+
+  // Block path traversal
+  if (inputPath.includes('..')) {
+    return { ok: false, resolved };
+  }
+
+  for (const allowed of allowedPaths) {
+    const allowedResolved = resolve(allowed);
+    if (resolved.startsWith(allowedResolved + '/') || resolved === allowedResolved) {
+      return { ok: true, resolved };
+    }
+  }
+
+  return { ok: false, resolved };
+}
+
+export function setAllowedPaths(paths: string[]) {
+  allowedPaths.length = 0;
+  allowedPaths.push(...paths);
+}
+
+const fileWriteTool: ToolDefinition = {
+  name: 'file-write',
+  description: 'Write content to a file. Creates directories if needed. Paths are sandboxed to allowed directories.',
+  parameters: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'File path to write' },
+      content: { type: 'string', description: 'Content to write' },
+    },
+    required: ['path', 'content'],
+  },
+  category: 'filesystem',
+  timeoutMs: 5000,
+  execute: async (params): Promise<ToolResult> => {
+    const filePath = String(params.path);
+    const content = String(params.content);
+
+    const { ok, resolved } = isPathAllowed(filePath);
+    if (!ok) {
+      return { content: '', error: `Path not allowed (sandboxed): ${resolved}. Allowed paths: ${allowedPaths.join(', ')}` };
+    }
+
+    try {
+      mkdirSync(dirname(resolved), { recursive: true });
+      writeFileSync(resolved, content, 'utf-8');
+      return { content: `Written ${content.length} bytes to ${resolved}` };
+    } catch (err: unknown) {
+      return { content: '', error: (err as Error).message };
+    }
+  },
+};
+
+export default fileWriteTool;

package/src/tools/builtin/http-request.ts

@@ -0,0 +1,63 @@
+import type { ToolDefinition, ToolContext, ToolResult } from '../../shared/types';
+
+const httpRequestTool: ToolDefinition = {
+  name: 'http-request',
+  description: 'Make an HTTP request. Returns status code, headers, and body.',
+  parameters: {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: 'The URL to request' },
+      method: { type: 'string', description: 'HTTP method (default GET)' },
+      headers: { type: 'object', description: 'Request headers' },
+      body: { type: 'string', description: 'Request body (for POST/PUT)' },
+      timeout: { type: 'number', description: 'Timeout in milliseconds (default 15000)' },
+    },
+    required: ['url'],
+  },
+  category: 'system',
+  timeoutMs: 30000,
+  maxOutputBytes: 500_000,
+  execute: async (params, ctx): Promise<ToolResult> => {
+    const url = String(params.url);
+    const method = String(params.method || 'GET').toUpperCase();
+    const headers = (params.headers as Record<string, string>) || {};
+    const body = params.body ? String(params.body) : undefined;
+    const timeout = Number(params.timeout) || 15000;
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    const signal = ctx.signal || controller.signal;
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body,
+        signal,
+      });
+
+      const responseHeaders: Record<string, string> = {};
+      response.headers.forEach((v, k) => {
+        responseHeaders[k] = v;
+      });
+
+      const responseText = await response.text();
+
+      return {
+        content: JSON.stringify({
+          status: response.status,
+          statusText: response.statusText,
+          headers: responseHeaders,
+          body: responseText.slice(0, 100_000),
+        }, null, 2),
+      };
+    } catch (err: unknown) {
+      const e = err as Error;
+      return { content: '', error: e.name === 'AbortError' ? `Request timed out after ${timeout}ms` : e.message };
+    } finally {
+      clearTimeout(timer);
+    }
+  },
+};
+
+export default httpRequestTool;

package/src/tools/builtin/memory.ts

@@ -0,0 +1,71 @@
+import type { ToolDefinition, ToolContext, ToolResult } from '../shared/types';
+import { memoryManager, type MemoryCategory } from '../../memory/store';
+import { logger } from '../../shared/logger';
+
+const VALID_CATEGORIES: MemoryCategory[] = ['identity', 'preference', 'fact', 'lesson', 'context'];
+
+export const memorySaveTool: ToolDefinition = {
+  name: 'memory-save',
+  description: 'Save a memory entry for later recall. Use this to remember important facts, preferences, or context.',
+  parameters: {
+    type: 'object',
+    properties: {
+      key: { type: 'string', description: 'Short identifier for the memory' },
+      value: { type: 'string', description: 'The content to remember' },
+      category: {
+        type: 'string',
+        enum: VALID_CATEGORIES,
+        description: 'Category: identity (who), preference (likes/dislikes), fact (things known), lesson (learned rules), context (situational)',
+      },
+    },
+    required: ['key', 'value'],
+  },
+  execute: async (params: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult> => {
+    const { key, value, category } = params;
+    if (!key || !value) return { content: 'Error: key and value are required', error: 'missing fields' };
+
+    const cat = (VALID_CATEGORIES.includes(category as MemoryCategory) ? category : 'fact') as MemoryCategory;
+    const entry = memoryManager.save(ctx.agentId, cat, String(key), String(value));
+    return { content: `Memory saved: [${entry.category}] ${entry.key}` };
+  },
+};
+
+export const memorySearchTool: ToolDefinition = {
+  name: 'memory-search',
+  description: 'Search through saved memories by keyword.',
+  parameters: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Search terms' },
+    },
+    required: ['query'],
+  },
+  execute: async (params: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult> => {
+    const results = memoryManager.search(ctx.agentId, String(params.query || ''));
+    if (results.length === 0) return { content: 'No matching memories found.' };
+    const lines = results.map((r) => `[${r.category}] ${r.key}: ${typeof r.value === 'string' ? r.value : JSON.stringify(r.value)}`);
+    return { content: lines.join('\n') };
+  },
+};
+
+export const memoryListTool: ToolDefinition = {
+  name: 'memory-list',
+  description: 'List all saved memories, optionally filtered by category.',
+  parameters: {
+    type: 'object',
+    properties: {
+      category: { type: 'string', enum: VALID_CATEGORIES, description: 'Optional category filter' },
+    },
+  },
+  execute: async (params: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult> => {
+    let entries;
+    if (params.category && VALID_CATEGORIES.includes(params.category as MemoryCategory)) {
+      entries = memoryManager.loadByCategory(ctx.agentId, params.category as MemoryCategory);
+    } else {
+      entries = memoryManager.load(ctx.agentId);
+    }
+    if (entries.length === 0) return { content: 'No memories saved.' };
+    const lines = entries.map((e) => `[${e.category}] ${e.key}: ${typeof e.value === 'string' ? e.value : JSON.stringify(e.value)}`);
+    return { content: lines.join('\n') };
+  },
+};

package/src/tools/builtin/shell.ts

@@ -0,0 +1,94 @@
+import type { ToolDefinition, ToolContext, ToolResult } from '../../shared/types';
+import { resolve } from 'path';
+
+// Configurable blocked commands
+const DEFAULT_BLOCKED_COMMANDS = ['rm -rf /', 'mkfs', 'dd if='];
+const blockedCommands: string[] = [...DEFAULT_BLOCKED_COMMANDS];
+
+// Configurable allowed directories for cwd
+const DEFAULT_ALLOWED_DIRS: string[] = [];
+let allowedDirectories: string[] = [...DEFAULT_ALLOWED_DIRS];
+
+export function setBlockedCommands(commands: string[]) {
+  blockedCommands.length = 0;
+  blockedCommands.push(...commands);
+}
+
+export function setAllowedDirectories(dirs: string[]) {
+  allowedDirectories = dirs.map(d => resolve(d));
+}
+
+function isCommandBlocked(command: string): boolean {
+  const lowerCmd = command.toLowerCase().trim();
+  return blockedCommands.some(blocked => lowerCmd.includes(blocked.toLowerCase()));
+}
+
+function isCwdAllowed(cwd: string | undefined): boolean {
+  if (!cwd || allowedDirectories.length === 0) return true; // no cwd or no restrictions
+  const resolved = resolve(cwd);
+  return allowedDirectories.some(allowed => resolved.startsWith(allowed + '/') || resolved === allowed);
+}
+
+const shellTool: ToolDefinition = {
+  name: 'shell',
+  description: 'Execute a shell command. Certain dangerous commands are blocked. cwd can be restricted to allowed directories.',
+  parameters: {
+    type: 'object',
+    properties: {
+      command: { type: 'string', description: 'The shell command to execute' },
+      timeout: { type: 'number', description: 'Timeout in milliseconds (default 30000)' },
+      cwd: { type: 'string', description: 'Working directory' },
+    },
+    required: ['command'],
+  },
+  category: 'system',
+  timeoutMs: 60000,
+  execute: async (params, _ctx): Promise<ToolResult> => {
+    const command = String(params.command);
+    const timeout = Number(params.timeout) || 30000;
+    const cwd = params.cwd ? String(params.cwd) : undefined;
+
+    // Check blocked commands
+    if (isCommandBlocked(command)) {
+      return { content: '', error: `Command blocked (sandboxed): "${command}"` };
+    }
+
+    // Check allowed directories for cwd
+    if (cwd && !isCwdAllowed(cwd)) {
+      return { content: '', error: `Working directory not allowed (sandboxed): ${cwd}` };
+    }
+
+    try {
+      const proc = Bun.spawn(['sh', '-c', command], {
+        cwd,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      });
+
+      const exitCode = await Promise.race([
+        proc.exited,
+        new Promise<null>((_, reject) => setTimeout(() => { proc.kill(); reject(new Error('timeout')); }, timeout)),
+      ]);
+
+      const stdout = await new Response(proc.stdout).text();
+      const stderr = await new Response(proc.stderr).text();
+      const output = [stdout.trim(), stderr.trim()].filter(Boolean).join('\n');
+
+      if (exitCode === null) {
+        return { content: output, error: `Command timed out after ${timeout}ms` };
+      }
+      if (exitCode !== 0) {
+        return { content: output || '', error: `Exit code ${exitCode}` };
+      }
+      return { content: output || '(no output)' };
+    } catch (err: unknown) {
+      const e = err as { message?: string };
+      if (e.message === 'timeout') {
+        return { content: '', error: `Command timed out after ${timeout}ms` };
+      }
+      return { content: '', error: e.message || 'Unknown error' };
+    }
+  },
+};
+
+export default shellTool;

package/src/tools/builtin/web-search.ts

@@ -0,0 +1,22 @@
+import type { ToolDefinition, ToolContext, ToolResult } from '../../shared/types';
+import { logger } from '../../shared/logger';
+
+const webSearchTool: ToolDefinition = {
+  name: 'web-search',
+  description: 'Search the web. (Placeholder — Brave API integration coming soon.)',
+  parameters: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Search query' },
+    },
+    required: ['query'],
+  },
+  category: 'search',
+  timeoutMs: 5000,
+  execute: async (params): Promise<ToolResult> => {
+    logger.info({ query: params.query }, 'Web search requested (not yet configured)');
+    return { content: 'Web search is not yet configured. Configure a Brave API key to enable searching.' };
+  },
+};
+
+export default webSearchTool;

package/src/tools/executor.ts

@@ -0,0 +1,126 @@
+import type { ToolDefinition, ToolContext, ToolResult } from '../shared/types';
+import { logger } from '../shared/logger';
+
+// ── Tool result cache ──
+
+interface CacheEntry {
+  result: ToolResult;
+  expiresAt: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+function cacheKey(toolName: string, params: Record<string, unknown>): string {
+  return `${toolName}:${JSON.stringify(params)}`;
+}
+
+function getCached(tool: ToolDefinition, params: Record<string, unknown>): ToolResult | null {
+  if (!tool.cacheable) return null;
+  const entry = cache.get(cacheKey(tool.name, params));
+  if (!entry) return null;
+  if (Date.now() > entry.expiresAt) {
+    cache.delete(cacheKey(tool.name, params));
+    return null;
+  }
+  return entry.result;
+}
+
+function setCache(tool: ToolDefinition, params: Record<string, unknown>, result: ToolResult): void {
+  if (!tool.cacheable) return;
+  cache.set(cacheKey(tool.name, params), {
+    result,
+    expiresAt: Date.now() + (tool.cacheTtlMs ?? 60_000),
+  });
+}
+
+// ── Single tool execution ──
+
+export async function executeTool(
+  tool: ToolDefinition,
+  params: Record<string, unknown>,
+  ctx: Partial<ToolContext> & { agentId: string; sessionId: string },
+): Promise<ToolResult> {
+  // Check cache first
+  const cached = getCached(tool, params);
+  if (cached) {
+    logger.debug({ tool: tool.name }, 'Tool cache hit');
+    return cached;
+  }
+
+  const timeout = tool.timeoutMs ?? 30_000;
+  const maxBytes = tool.maxOutputBytes ?? 1_000_000;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+
+  // Link parent signal if provided
+  if (ctx.signal) {
+    if (ctx.signal.aborted) {
+      clearTimeout(timer);
+      return { content: '', error: 'Parent signal already aborted' };
+    }
+    ctx.signal.addEventListener('abort', () => controller.abort(), { once: true });
+  }
+
+  try {
+    const fullCtx: ToolContext = {
+      agentId: ctx.agentId,
+      sessionId: ctx.sessionId,
+      signal: controller.signal,
+    };
+
+    const startMs = Date.now();
+    const result = await tool.execute(params, fullCtx);
+    const durationMs = Date.now() - startMs;
+
+    if (result.content.length > maxBytes) {
+      result.content = result.content.slice(0, maxBytes) + '\n[TRUNCATED]';
+    }
+
+    logger.info({ tool: tool.name, durationMs, cached: false }, 'Tool executed');
+    setCache(tool, params, result);
+    return result;
+  } catch (err) {
+    const error = err as Error;
+    if (error.name === 'AbortError') {
+      return { content: '', error: `Tool timed out after ${timeout}ms` };
+    }
+    logger.error({ tool: tool.name, error: error.message }, 'Tool execution failed');
+    return { content: '', error: error.message };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ── Parallel tool execution ──
+
+export interface ParallelToolCall {
+  tool: ToolDefinition;
+  params: Record<string, unknown>;
+}
+
+export async function executeToolsParallel(
+  calls: ParallelToolCall[],
+  ctx: Partial<ToolContext> & { agentId: string; sessionId: string },
+): Promise<ToolResult[]> {
+  if (calls.length === 0) return [];
+
+  // Execute all in parallel — each tool gets its own AbortController
+  const results = await Promise.all(
+    calls.map((call) => executeTool(call.tool, call.params, ctx)),
+  );
+
+  return results;
+}
+
+// ── Cache management ──
+
+export function clearToolCache(toolName?: string): void {
+  if (!toolName) {
+    cache.clear();
+    return;
+  }
+  for (const key of cache.keys()) {
+    if (key.startsWith(`${toolName}:`)) cache.delete(key);
+  }
+}

package/src/tools/registry.ts

@@ -0,0 +1,56 @@
+import type { ToolDefinition, ToolContext, ToolResult } from '../shared/types';
+import { logger } from '../shared/logger';
+
+class ToolRegistry {
+  private tools = new Map<string, ToolDefinition>();
+  private perAgent = new Map<string, Set<string>>();
+
+  register(def: ToolDefinition): void {
+    if (this.tools.has(def.name)) {
+      throw new Error(`Tool already registered: ${def.name}`);
+    }
+    this.tools.set(def.name, def);
+    logger.debug({ tool: def.name }, 'Tool registered');
+  }
+
+  get(name: string): ToolDefinition | undefined {
+    return this.tools.get(name);
+  }
+
+  list(): ToolDefinition[] {
+    return [...this.tools.values()];
+  }
+
+  listForAgent(agentId: string): ToolDefinition[] {
+    const allowed = this.perAgent.get(agentId);
+    if (!allowed) return [];
+    return [...allowed].map((name) => this.tools.get(name)!).filter(Boolean);
+  }
+
+  getToolNamesForAgent(agentId: string): string[] {
+    return [...(this.perAgent.get(agentId) || [])];
+  }
+
+  bindTools(agentId: string, toolNames: string[]): void {
+    const bound = new Set<string>();
+    for (const name of toolNames) {
+      if (!this.tools.has(name)) {
+        logger.warn({ tool: name }, 'Tool not found, skipping');
+        continue;
+      }
+      bound.add(name);
+    }
+    this.perAgent.set(agentId, bound);
+    logger.debug({ agentId, tools: [...bound] }, 'Tools bound to agent');
+  }
+
+  getSchemasForAgent(agentId: string) {
+    return this.listForAgent(agentId).map((t) => ({
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+    }));
+  }
+}
+
+export const toolRegistry = new ToolRegistry();