vellum 0.0.16 → 0.2.0

package/src/tools/host-terminal/cli-discover.ts

@@ -0,0 +1,179 @@
+import { spawn } from 'node:child_process';
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('cli-discover');
+
+/**
+ * Common business CLIs checked when no explicit list is provided.
+ * Kept intentionally broad — the tool only reports what's on PATH.
+ */
+const DEFAULT_CLIS = [
+  // Version control & code hosting
+  'gh', 'git', 'gitlab',
+  // Project management
+  'linear', 'jira',
+  // Communication
+  'slack',
+  // Cloud providers
+  'aws', 'gcloud', 'az',
+  // Containers & infra
+  'docker', 'kubectl', 'terraform',
+  // Package managers / runtimes
+  'node', 'bun', 'deno', 'python3', 'pip3',
+  // HTTP clients
+  'curl', 'httpie',
+  // Misc dev tools
+  'vercel', 'netlify', 'fly', 'heroku', 'railway',
+] as const;
+
+/**
+ * Known auth-check commands. Each entry maps a CLI binary name to the
+ * command + args that report authentication status without side effects.
+ */
+const AUTH_CHECK_COMMANDS: Record<string, string[]> = {
+  gh: ['gh', 'auth', 'status'],
+  aws: ['aws', 'sts', 'get-caller-identity'],
+  gcloud: ['gcloud', 'auth', 'list', '--filter=status:ACTIVE', '--format=value(account)'],
+  az: ['az', 'account', 'show'],
+  vercel: ['vercel', 'whoami'],
+  netlify: ['netlify', 'status'],
+  fly: ['fly', 'auth', 'whoami'],
+  heroku: ['heroku', 'auth:whoami'],
+  railway: ['railway', 'whoami'],
+};
+
+interface CliResult {
+  name: string;
+  found: boolean;
+  path?: string;
+  version?: string;
+  authenticated?: boolean;
+  authInfo?: string;
+}
+
+/**
+ * Run a command with a short timeout and return stdout (trimmed) or null on failure.
+ */
+function runQuick(command: string, args: string[], timeoutMs = 5000): Promise<string | null> {
+  return new Promise((resolve) => {
+    const chunks: Buffer[] = [];
+    const child = spawn(command, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: timeoutMs,
+    });
+
+    child.stdout.on('data', (data: Buffer) => chunks.push(data));
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve(Buffer.concat(chunks).toString().trim());
+      } else {
+        resolve(null);
+      }
+    });
+
+    child.on('error', () => resolve(null));
+  });
+}
+
+class CliDiscoverTool implements Tool {
+  name = 'cli_discover';
+  description = 'Discover which CLI tools are installed, their versions, and authentication status';
+  category = 'host-terminal';
+  defaultRiskLevel = RiskLevel.Low;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          names: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'CLI binary names to check. Defaults to a broad set of common business CLIs if omitted.',
+          },
+          check_auth: {
+            type: 'boolean',
+            description: 'Whether to run auth-status checks for known CLIs (default: true)',
+          },
+        },
+        required: [],
+      },
+    };
+  }
+
+  async execute(input: Record<string, unknown>, _context: ToolContext): Promise<ToolExecutionResult> {
+    const rawNames = input.names;
+    const names: string[] = Array.isArray(rawNames) && rawNames.every((n) => typeof n === 'string')
+      ? rawNames as string[]
+      : [...DEFAULT_CLIS];
+    const checkAuth = input.check_auth !== false;
+
+    log.info({ count: names.length, checkAuth }, 'Discovering CLIs');
+
+    const results: CliResult[] = [];
+
+    for (const name of names) {
+      const path = Bun.which(name);
+      if (!path) {
+        results.push({ name, found: false });
+        continue;
+      }
+
+      const result: CliResult = { name, found: true, path };
+
+      // Version check
+      const version = await runQuick(name, ['--version']);
+      if (version) {
+        // Take first line only — some tools emit multi-line version info
+        result.version = version.split('\n')[0];
+      }
+
+      // Auth check
+      if (checkAuth && AUTH_CHECK_COMMANDS[name]) {
+        const [cmd, ...args] = AUTH_CHECK_COMMANDS[name];
+        const authOutput = await runQuick(cmd, args);
+        result.authenticated = authOutput !== null && authOutput.length > 0;
+        if (authOutput) {
+          // Keep auth info brief — first line, max 200 chars
+          result.authInfo = authOutput.split('\n')[0].slice(0, 200);
+        }
+      }
+
+      results.push(result);
+    }
+
+    const found = results.filter((r) => r.found);
+    const notFound = results.filter((r) => !r.found);
+
+    const lines: string[] = [];
+
+    if (found.length > 0) {
+      lines.push('## Available CLIs\n');
+      for (const r of found) {
+        let line = `- **${r.name}** (${r.path})`;
+        if (r.version) line += ` — ${r.version}`;
+        if (r.authenticated === true) line += ` [authenticated${r.authInfo ? `: ${r.authInfo}` : ''}]`;
+        else if (r.authenticated === false) line += ' [not authenticated]';
+        lines.push(line);
+      }
+    }
+
+    if (notFound.length > 0) {
+      if (lines.length > 0) lines.push('');
+      lines.push(`## Not found: ${notFound.map((r) => r.name).join(', ')}`);
+    }
+
+    return {
+      content: lines.join('\n'),
+      isError: false,
+    };
+  }
+}
+
+export const cliDiscoverTool: Tool = new CliDiscoverTool();

package/src/tools/host-terminal/host-shell.ts

@@ -0,0 +1,181 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute } from 'node:path';
+import { RiskLevel } from '../../permissions/types.js';
+import type { Tool, ToolContext, ToolExecutionResult } from '../types.js';
+import type { ToolDefinition } from '../../providers/types.js';
+import { getConfig } from '../../config/loader.js';
+import { getLogger } from '../../util/logger.js';
+import { redactSecrets } from '../../security/secret-scanner.js';
+import { formatShellOutput } from '../shared/shell-output.js';
+
+const log = getLogger('host-shell-tool');
+
+const SAFE_ENV_VARS = [
+  'PATH',
+  'HOME',
+  'TERM',
+  'LANG',
+  'EDITOR',
+  'SHELL',
+  'USER',
+  'TMPDIR',
+  'LC_ALL',
+  'LC_CTYPE',
+  'XDG_RUNTIME_DIR',
+  'DISPLAY',
+  'COLORTERM',
+  'TERM_PROGRAM',
+  'SSH_AUTH_SOCK',
+  'SSH_AGENT_PID',
+  'GPG_TTY',
+  'GNUPGHOME',
+] as const;
+
+function buildSanitizedEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of SAFE_ENV_VARS) {
+    if (process.env[key] != null) {
+      env[key] = process.env[key]!;
+    }
+  }
+  return env;
+}
+
+class HostShellTool implements Tool {
+  name = 'host_bash';
+  description = 'Execute a shell command on the host machine';
+  category = 'host-terminal';
+  defaultRiskLevel = RiskLevel.Medium;
+
+  getDefinition(): ToolDefinition {
+    return {
+      name: this.name,
+      description: this.description,
+      input_schema: {
+        type: 'object',
+        properties: {
+          command: {
+            type: 'string',
+            description: 'The host shell command to execute',
+          },
+          reason: {
+            type: 'string',
+            description: 'Brief human-readable explanation of what this command does and why, shown to the user in the permission prompt (e.g. "to find available location services")',
+          },
+          working_dir: {
+            type: 'string',
+            description: 'Optional absolute host working directory (defaults to user home)',
+          },
+          timeout_seconds: {
+            type: 'number',
+            description: 'Optional timeout in seconds. Uses configured default and max limits.',
+          },
+        },
+        required: ['command', 'reason'],
+      },
+    };
+  }
+
+  async execute(input: Record<string, unknown>, context: ToolContext): Promise<ToolExecutionResult> {
+    const command = input.command as string;
+    if (!command || typeof command !== 'string') {
+      return { content: 'Error: command is required and must be a string', isError: true };
+    }
+    if (command.includes('\0')) {
+      return { content: 'Error: command contains null bytes', isError: true };
+    }
+
+    const rawWorkingDir = input.working_dir;
+    if (rawWorkingDir != null && typeof rawWorkingDir !== 'string') {
+      return { content: 'Error: working_dir must be a string when provided', isError: true };
+    }
+    if (typeof rawWorkingDir === 'string' && rawWorkingDir.includes('\0')) {
+      return { content: 'Error: working_dir contains null bytes', isError: true };
+    }
+    if (typeof rawWorkingDir === 'string' && !isAbsolute(rawWorkingDir)) {
+      return { content: `Error: working_dir must be absolute for host command execution: ${rawWorkingDir}`, isError: true };
+    }
+    const workingDir = typeof rawWorkingDir === 'string' ? rawWorkingDir : homedir();
+
+    const config = getConfig();
+    const { shellDefaultTimeoutSec, shellMaxTimeoutSec } = config.timeouts;
+    const requestedSec = typeof input.timeout_seconds === 'number' ? input.timeout_seconds : shellDefaultTimeoutSec;
+    const timeoutSec = Math.max(1, Math.min(requestedSec, shellMaxTimeoutSec));
+    const timeoutMs = timeoutSec * 1000;
+
+    log.info({ command: redactSecrets(command), cwd: workingDir, timeoutSec, sessionId: context.sessionId }, 'Executing host shell command');
+
+    return new Promise<ToolExecutionResult>((resolve) => {
+      const stdoutChunks: Buffer[] = [];
+      const stderrChunks: Buffer[] = [];
+      let timedOut = false;
+
+      const child = spawn('bash', ['-c', '--', command], {
+        cwd: workingDir,
+        env: buildSanitizedEnv(),
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill('SIGKILL');
+      }, timeoutMs);
+
+      // Cooperative cancellation via AbortSignal
+      const onAbort = () => {
+        child.kill('SIGKILL');
+      };
+      if (context.signal) {
+        if (context.signal.aborted) {
+          child.kill('SIGKILL');
+        } else {
+          context.signal.addEventListener('abort', onAbort, { once: true });
+        }
+      }
+
+      child.stdout.on('data', (data: Buffer) => {
+        stdoutChunks.push(data);
+        context.onOutput?.(data.toString());
+      });
+
+      child.stderr.on('data', (data: Buffer) => {
+        stderrChunks.push(data);
+        context.onOutput?.(data.toString());
+      });
+
+      child.on('close', (code) => {
+        clearTimeout(timer);
+        context.signal?.removeEventListener('abort', onAbort);
+
+        const stdout = Buffer.concat(stdoutChunks).toString();
+        const stderr = Buffer.concat(stderrChunks).toString();
+        const result = formatShellOutput(stdout, stderr, code, timedOut, timeoutSec);
+
+        resolve({
+          content: result.content,
+          isError: result.isError,
+          status: result.status,
+        });
+      });
+
+      child.on('error', (err) => {
+        clearTimeout(timer);
+        context.signal?.removeEventListener('abort', onAbort);
+        let hint = '';
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+          hint = !existsSync(workingDir)
+            ? `. The working directory does not exist: ${workingDir}`
+            : '. The command was not found — check that it is installed and in PATH.';
+        }
+        resolve({
+          content: `Error spawning command: ${err.message}${hint}`,
+          isError: true,
+        });
+      });
+    });
+  }
+}
+
+export const hostShellTool: Tool = new HostShellTool();

package/src/tools/memory/definitions.ts

@@ -0,0 +1,69 @@
+import type { ToolDefinition } from '../../providers/types.js';
+
+export const memorySearchDefinition: ToolDefinition = {
+  name: 'memory_search',
+  description: 'Search your memory for previously saved facts, preferences, decisions, and other information. Use this when you need to recall something from past conversations.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'Natural language search query describing what you want to recall',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of results to return (default: 5)',
+      },
+    },
+    required: ['query'],
+  },
+};
+
+export const memorySaveDefinition: ToolDefinition = {
+  name: 'memory_save',
+  description: 'Save a fact, preference, decision, or other noteworthy information to memory for future recall. Use this when the user shares something worth remembering.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      statement: {
+        type: 'string',
+        description: 'The fact or preference to remember (1-2 sentences)',
+      },
+      kind: {
+        type: 'string',
+        enum: ['preference', 'fact', 'decision', 'profile', 'relationship', 'event', 'opinion', 'instruction', 'style', 'playbook', 'learning'],
+        description: 'Category of the memory item',
+      },
+      subject: {
+        type: 'string',
+        description: 'Short subject/topic label (2-8 words)',
+      },
+    },
+    required: ['statement', 'kind'],
+  },
+};
+
+export const memoryUpdateDefinition: ToolDefinition = {
+  name: 'memory_update',
+  description: 'Update or correct an existing memory item. Use this when previously saved information needs to be changed.',
+  input_schema: {
+    type: 'object',
+    properties: {
+      memory_id: {
+        type: 'string',
+        description: 'ID of the memory item to update (from memory_search results)',
+      },
+      statement: {
+        type: 'string',
+        description: 'The updated statement to replace the existing one',
+      },
+    },
+    required: ['memory_id', 'statement'],
+  },
+};
+
+export const memoryToolDefinitions: ToolDefinition[] = [
+  memorySearchDefinition,
+  memorySaveDefinition,
+  memoryUpdateDefinition,
+];

package/src/tools/memory/handlers.ts

@@ -0,0 +1,245 @@
+import { and, eq } from 'drizzle-orm';
+import { v4 as uuid } from 'uuid';
+import type { AssistantConfig } from '../../config/types.js';
+import { getLogger } from '../../util/logger.js';
+import { getDb } from '../../memory/db.js';
+import { computeMemoryFingerprint } from '../../memory/fingerprint.js';
+import { memoryItems } from '../../memory/schema.js';
+import { enqueueMemoryJob } from '../../memory/jobs-store.js';
+import { searchMemoryItems, formatRelativeTime } from '../../memory/retriever.js';
+import type { ScopePolicyOverride } from '../../memory/search/types.js';
+import type { ToolExecutionResult } from '../types.js';
+
+const log = getLogger('memory-tools');
+
+// ── memory_search ────────────────────────────────────────────────────
+
+export async function handleMemorySearch(
+  args: Record<string, unknown>,
+  config: AssistantConfig,
+  scopeId?: string,
+): Promise<ToolExecutionResult> {
+  const query = args.query;
+  if (typeof query !== 'string' || query.trim().length === 0) {
+    return { content: 'Error: query is required and must be a non-empty string', isError: true };
+  }
+
+  const limit = typeof args.limit === 'number' && args.limit > 0
+    ? Math.min(args.limit, 20)
+    : 5;
+
+  // Private threads should always fall back to default scope for search
+  const scopePolicyOverride: ScopePolicyOverride | undefined =
+    scopeId && scopeId.startsWith('private:')
+      ? { scopeId, fallbackToDefault: true }
+      : undefined;
+
+  try {
+    const results = await searchMemoryItems(query, limit, config, scopeId, scopePolicyOverride);
+
+    if (results.length === 0) {
+      return { content: 'No matching memories found.', isError: false };
+    }
+
+    const lines: string[] = [`Found ${results.length} memory item(s):\n`];
+    for (const result of results) {
+      const timeAgo = formatRelativeTime(result.createdAt);
+      lines.push(`- **[${result.kind}]** ${result.text}`);
+      lines.push(`  _ID: ${result.id} | source: ${result.type} | ${timeAgo} | confidence: ${result.confidence.toFixed(2)} | importance: ${result.importance.toFixed(2)}_`);
+    }
+
+    return { content: lines.join('\n'), isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error({ err, query }, 'memory_search failed');
+    return { content: `Error: Memory search failed: ${msg}`, isError: true };
+  }
+}
+
+// ── memory_save ──────────────────────────────────────────────────────
+
+export async function handleMemorySave(
+  args: Record<string, unknown>,
+  _config: AssistantConfig,
+  conversationId: string,
+  messageId: string | undefined,
+  scopeId: string = 'default',
+): Promise<ToolExecutionResult> {
+  const statement = args.statement;
+  if (typeof statement !== 'string' || statement.trim().length === 0) {
+    return { content: 'Error: statement is required and must be a non-empty string', isError: true };
+  }
+
+  const kind = args.kind;
+  const validKinds = new Set([
+    'preference', 'fact', 'decision', 'profile',
+    'relationship', 'event', 'opinion', 'instruction', 'style',
+    'playbook', 'learning',
+  ]);
+  if (typeof kind !== 'string' || !validKinds.has(kind)) {
+    return {
+      content: `Error: kind is required and must be one of: ${[...validKinds].join(', ')}`,
+      isError: true,
+    };
+  }
+
+  const subject = typeof args.subject === 'string' && args.subject.trim().length > 0
+    ? args.subject.trim().slice(0, 80)
+    : inferSubjectFromStatement(statement.trim());
+
+  try {
+    const db = getDb();
+    const id = uuid();
+    const now = Date.now();
+    const trimmedStatement = statement.trim().slice(0, 500);
+
+    const fingerprint = computeMemoryFingerprint(scopeId, kind, subject, trimmedStatement);
+
+    const existing = db
+      .select()
+      .from(memoryItems)
+      .where(and(eq(memoryItems.fingerprint, fingerprint), eq(memoryItems.scopeId, scopeId)))
+      .get();
+
+    if (existing) {
+      db.update(memoryItems)
+        .set({
+          status: 'active',
+          importance: 0.8,
+          lastSeenAt: now,
+          verificationState: 'user_confirmed',
+        })
+        .where(eq(memoryItems.id, existing.id))
+        .run();
+
+      enqueueMemoryJob('embed_item', { itemId: existing.id });
+      return {
+        content: `Memory already exists (ID: ${existing.id}). Updated and refreshed.`,
+        isError: false,
+      };
+    }
+
+    db.insert(memoryItems).values({
+      id,
+      kind,
+      subject,
+      statement: trimmedStatement,
+      status: 'active',
+      confidence: 0.95,     // explicit saves have high confidence
+      importance: 0.8,       // explicit saves are high importance
+      fingerprint,
+      verificationState: 'user_confirmed',
+      scopeId,
+      firstSeenAt: now,
+      lastSeenAt: now,
+      lastUsedAt: null,
+    }).run();
+
+    enqueueMemoryJob('embed_item', { itemId: id });
+
+    log.debug({ id, kind, subject, conversationId, messageId }, 'Memory item saved via tool');
+    return {
+      content: `Saved to memory (ID: ${id}).\nKind: ${kind}\nSubject: ${subject}\nStatement: ${trimmedStatement}`,
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error({ err }, 'memory_save failed');
+    return { content: `Error: Failed to save memory: ${msg}`, isError: true };
+  }
+}
+
+// ── memory_update ────────────────────────────────────────────────────
+
+export async function handleMemoryUpdate(
+  args: Record<string, unknown>,
+  _config: AssistantConfig,
+  scopeId: string = 'default',
+): Promise<ToolExecutionResult> {
+  const rawMemoryId = args.memory_id;
+  if (typeof rawMemoryId !== 'string' || rawMemoryId.trim().length === 0) {
+    return { content: 'Error: memory_id is required and must be a non-empty string', isError: true };
+  }
+
+  // Accept both bare IDs and typed IDs (e.g. "item:abc-123" -> "abc-123")
+  const memoryId = stripTypedIdPrefix(rawMemoryId.trim());
+
+  const statement = args.statement;
+  if (typeof statement !== 'string' || statement.trim().length === 0) {
+    return { content: 'Error: statement is required and must be a non-empty string', isError: true };
+  }
+
+  try {
+    const db = getDb();
+
+    // Constrain lookup to the current scope so threads cannot mutate
+    // memory items belonging to a different scope.
+    const existing = db
+      .select()
+      .from(memoryItems)
+      .where(and(eq(memoryItems.id, memoryId), eq(memoryItems.scopeId, scopeId)))
+      .get();
+
+    if (!existing) {
+      return { content: `Error: Memory item with ID "${memoryId}" not found`, isError: true };
+    }
+
+    const now = Date.now();
+    const trimmedStatement = statement.trim().slice(0, 500);
+
+    const fingerprint = computeMemoryFingerprint(scopeId, existing.kind, existing.subject, trimmedStatement);
+
+    // Collision detection also constrained to the current scope.
+    const collision = db
+      .select({ id: memoryItems.id })
+      .from(memoryItems)
+      .where(and(eq(memoryItems.fingerprint, fingerprint), eq(memoryItems.scopeId, scopeId)))
+      .get();
+    if (collision && collision.id !== existing.id) {
+      return {
+        content: `Error: Another memory item (ID: ${collision.id}) already contains this statement. Use memory_search to find it.`,
+        isError: true,
+      };
+    }
+
+    db.update(memoryItems)
+      .set({
+        statement: trimmedStatement,
+        fingerprint,
+        lastSeenAt: now,
+        importance: 0.8,
+        verificationState: 'user_confirmed',
+      })
+      .where(eq(memoryItems.id, existing.id))
+      .run();
+
+    enqueueMemoryJob('embed_item', { itemId: existing.id });
+
+    log.debug({ id: existing.id, kind: existing.kind }, 'Memory item updated via tool');
+    return {
+      content: `Updated memory (ID: ${existing.id}).\nKind: ${existing.kind}\nSubject: ${existing.subject}\nNew statement: ${trimmedStatement}`,
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error({ err, memoryId }, 'memory_update failed');
+    return { content: `Error: Failed to update memory: ${msg}`, isError: true };
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+function inferSubjectFromStatement(statement: string): string {
+  // Take first few words as a subject label
+  const words = statement.split(/\s+/).slice(0, 6).join(' ');
+  return words.slice(0, 80);
+}
+
+/**
+ * Strip a typed ID prefix (e.g. "item:abc-123" -> "abc-123") so that IDs
+ * copied from memory_search output work in memory_update.
+ */
+function stripTypedIdPrefix(id: string): string {
+  const match = id.match(/^(?:item|segment|summary):(.+)$/);
+  return match ? match[1] : id;
+}