@dot-ai/core 0.5.2 → 0.7.0

package/src/__tests__/format.test.ts

@@ -1,6 +1,7 @@
-import { describe, it, expect } from 'vitest';
-import { formatContext } from '../format.js';
+import { describe, it, expect, vi } from 'vitest';
+import { formatContext, formatToolHints } from '../format.js';
 import type { EnrichedContext, Identity, MemoryEntry, Skill, Tool } from '../types.js';
+import type { Capability } from '../capabilities.js';
 
 function makeContext(overrides?: Partial<EnrichedContext>): EnrichedContext {
   return {
@@ -15,6 +16,8 @@ function makeContext(overrides?: Partial<EnrichedContext>): EnrichedContext {
   };
 }
 
+const makeEmptyContext = makeContext;
+
 function makeIdentity(overrides?: Partial<Identity>): Identity {
   return {
     type: 'agents',
@@ -244,4 +247,206 @@ describe('formatContext', () => {
     expect(result).toContain('Real content');
     expect(result).not.toContain('no-content');
   });
+
+  describe('format stability (determinism)', () => {
+    it('produces identical output for same inputs called twice', () => {
+      const ctx = makeContext({
+        identities: [
+          makeIdentity({ content: 'Identity A', priority: 80, type: 'user' }),
+          makeIdentity({ content: 'Identity B', priority: 100, type: 'agents' }),
+        ],
+        memories: [
+          makeMemory({ content: 'Memory 1', date: '2025-01-01' }),
+          makeMemory({ content: 'Memory 2', date: '2025-03-01' }),
+        ],
+        skills: [
+          makeSkill({ name: 'zebra-skill', content: 'Zebra content' }),
+          makeSkill({ name: 'alpha-skill', content: 'Alpha content' }),
+        ],
+        tools: [
+          makeTool({ name: 'z-tool', description: 'Z tool' }),
+          makeTool({ name: 'a-tool', description: 'A tool' }),
+        ],
+      });
+
+      const result1 = formatContext(ctx);
+      const result2 = formatContext(ctx);
+
+      expect(result1).toBe(result2);
+    });
+
+    it('produces same output regardless of input ordering (skills sorted by name)', () => {
+      const ctxA = makeContext({
+        skills: [
+          makeSkill({ name: 'zebra-skill', content: 'Zebra content' }),
+          makeSkill({ name: 'alpha-skill', content: 'Alpha content' }),
+          makeSkill({ name: 'middle-skill', content: 'Middle content' }),
+        ],
+      });
+
+      const ctxB = makeContext({
+        skills: [
+          makeSkill({ name: 'middle-skill', content: 'Middle content' }),
+          makeSkill({ name: 'alpha-skill', content: 'Alpha content' }),
+          makeSkill({ name: 'zebra-skill', content: 'Zebra content' }),
+        ],
+      });
+
+      expect(formatContext(ctxA)).toBe(formatContext(ctxB));
+    });
+
+    it('sorts skills by name alphabetically', () => {
+      const ctx = makeContext({
+        skills: [
+          makeSkill({ name: 'zebra-skill', content: 'Zebra content' }),
+          makeSkill({ name: 'alpha-skill', content: 'Alpha content' }),
+          makeSkill({ name: 'middle-skill', content: 'Middle content' }),
+        ],
+      });
+
+      const result = formatContext(ctx);
+      const alphaPos = result.indexOf('alpha-skill');
+      const middlePos = result.indexOf('middle-skill');
+      const zebraPos = result.indexOf('zebra-skill');
+
+      expect(alphaPos).toBeLessThan(middlePos);
+      expect(middlePos).toBeLessThan(zebraPos);
+    });
+
+    it('sorts memories by date DESC (most recent first)', () => {
+      const ctx = makeContext({
+        memories: [
+          makeMemory({ content: 'Oldest memory', date: '2024-01-01' }),
+          makeMemory({ content: 'Newest memory', date: '2025-12-31' }),
+          makeMemory({ content: 'Middle memory', date: '2025-06-15' }),
+        ],
+      });
+
+      const result = formatContext(ctx);
+      const newestPos = result.indexOf('Newest memory');
+      const middlePos = result.indexOf('Middle memory');
+      const oldestPos = result.indexOf('Oldest memory');
+
+      expect(newestPos).toBeLessThan(middlePos);
+      expect(middlePos).toBeLessThan(oldestPos);
+    });
+
+    it('produces same output for memories regardless of input ordering', () => {
+      const ctxA = makeContext({
+        memories: [
+          makeMemory({ content: 'Old memory', date: '2024-01-01' }),
+          makeMemory({ content: 'New memory', date: '2025-12-31' }),
+        ],
+      });
+
+      const ctxB = makeContext({
+        memories: [
+          makeMemory({ content: 'New memory', date: '2025-12-31' }),
+          makeMemory({ content: 'Old memory', date: '2024-01-01' }),
+        ],
+      });
+
+      expect(formatContext(ctxA)).toBe(formatContext(ctxB));
+    });
+
+    it('sorts identities by priority DESC then type alphabetically', () => {
+      const ctx = makeContext({
+        identities: [
+          makeIdentity({ content: 'Type z same priority', priority: 50, type: 'z-type' }),
+          makeIdentity({ content: 'Type a same priority', priority: 50, type: 'a-type' }),
+          makeIdentity({ content: 'High priority identity', priority: 100, type: 'agents' }),
+        ],
+      });
+
+      const result = formatContext(ctx);
+      const highPos = result.indexOf('High priority identity');
+      const typeAPos = result.indexOf('Type a same priority');
+      const typeZPos = result.indexOf('Type z same priority');
+
+      // High priority first
+      expect(highPos).toBeLessThan(typeAPos);
+      // Same priority: 'a-type' before 'z-type' alphabetically
+      expect(typeAPos).toBeLessThan(typeZPos);
+    });
+  });
+});
+
+describe('formatToolHints', () => {
+  it('returns empty string when no capabilities have hints', () => {
+    expect(formatToolHints([])).toBe('');
+    const cap: Capability = { name: 'test', description: 'x', parameters: {}, execute: vi.fn() };
+    expect(formatToolHints([cap])).toBe('');
+  });
+
+  it('formats promptSnippet', () => {
+    const caps: Capability[] = [{
+      name: 'memory_recall',
+      description: 'Search memory',
+      parameters: {},
+      execute: vi.fn(),
+      promptSnippet: 'Use memory_recall to search stored memories.',
+    }];
+    const result = formatToolHints(caps);
+    expect(result).toContain('## Tool Hints');
+    expect(result).toContain('### memory_recall');
+    expect(result).toContain('Use memory_recall to search stored memories.');
+  });
+
+  it('formats promptGuidelines', () => {
+    const caps: Capability[] = [{
+      name: 'task_list',
+      description: 'List tasks',
+      parameters: {},
+      execute: vi.fn(),
+      promptGuidelines: 'Always check tasks before starting work.',
+    }];
+    const result = formatToolHints(caps);
+    expect(result).toContain('> Always check tasks before starting work.');
+  });
+
+  it('formats both snippet and guidelines', () => {
+    const caps: Capability[] = [{
+      name: 'tool',
+      description: 'd',
+      parameters: {},
+      execute: vi.fn(),
+      promptSnippet: 'snippet text',
+      promptGuidelines: 'guideline text',
+    }];
+    const result = formatToolHints(caps);
+    expect(result).toContain('snippet text');
+    expect(result).toContain('> guideline text');
+  });
+
+  it('only includes capabilities with hints', () => {
+    const caps: Capability[] = [
+      { name: 'no-hints', description: 'd', parameters: {}, execute: vi.fn() },
+      { name: 'with-hint', description: 'd', parameters: {}, execute: vi.fn(), promptSnippet: 'hint' },
+    ];
+    const result = formatToolHints(caps);
+    expect(result).not.toContain('no-hints');
+    expect(result).toContain('with-hint');
+  });
+});
+
+describe('skillDisclosure: progressive', () => {
+  it('shows only description, not content, in progressive mode', () => {
+    const ctx = makeEmptyContext();
+    ctx.skills = [
+      { name: 'my-skill', description: 'Does something useful', labels: [], content: 'Full skill body here' },
+    ];
+    const result = formatContext(ctx, { skillDisclosure: 'progressive' });
+    expect(result).toContain('### my-skill');
+    expect(result).toContain('Does something useful');
+    expect(result).not.toContain('Full skill body here');
+  });
+
+  it('defaults to full disclosure (shows content)', () => {
+    const ctx = makeEmptyContext();
+    ctx.skills = [
+      { name: 'my-skill', description: 'Desc', labels: [], content: 'Full body' },
+    ];
+    const result = formatContext(ctx);
+    expect(result).toContain('Full body');
+  });
 });

package/src/__tests__/runtime.test.ts

@@ -0,0 +1,141 @@
+import { describe, it, expect, vi } from 'vitest';
+import { DotAiRuntime } from '../runtime.js';
+
+describe('DotAiRuntime', () => {
+  describe('boot', () => {
+    it('boots and is idempotent', async () => {
+      const runtime = new DotAiRuntime({ workspaceRoot: '/tmp/nonexistent' });
+      await runtime.boot();
+      expect(runtime.isBooted).toBe(true);
+      // Second boot is a no-op
+      await runtime.boot();
+      expect(runtime.isBooted).toBe(true);
+    });
+
+    it('isBooted is false before boot', () => {
+      const runtime = new DotAiRuntime({ workspaceRoot: '/tmp/nonexistent' });
+      expect(runtime.isBooted).toBe(false);
+    });
+
+    it('auto-boots on processPrompt', async () => {
+      const runtime = new DotAiRuntime({ workspaceRoot: '/tmp/nonexistent' });
+      expect(runtime.isBooted).toBe(false);
+      await runtime.processPrompt('hello');
+      expect(runtime.isBooted).toBe(true);
+    });
+  });
+
+  describe('processPrompt', () => {
+    it('returns sections, labels, formatted, enriched, capabilities', async () => {
+      const runtime = new DotAiRuntime({ workspaceRoot: '/tmp/nonexistent' });
+      await runtime.boot();
+      const result = await runtime.processPrompt('hello world');
+      expect(result.formatted).toBeDefined();
+      expect(result.enriched).toBeDefined();
+      expect(result.capabilities).toBeDefined();
+      expect(result.labels).toBeDefined();
+      expect(result.sections).toBeDefined();
+    });
+  });
+
+  describe('learn', () => {
+    it('fires agent_end without throwing', async () => {
+      const runtime = new DotAiRuntime({ workspaceRoot: '/tmp/nonexistent' });
+      await runtime.boot();
+      await runtime.learn('test response');
+    });
+  });
+
+  describe('event firing', () => {
+    it('fire returns empty when not booted', async () => {
+      const runtime = new DotAiRuntime({ workspaceRoot: '/tmp/nonexistent' });
+      const results = await runtime.fire('any');
+      expect(results).toEqual([]);
+    });
+
+    it('fire returns empty with no extensions', async () => {
+      const runtime = new DotAiRuntime({ workspaceRoot: '/tmp/nonexistent' });
+      await runtime.boot();
+      const results = await runtime.fire('custom_event', { data: 1 });
+      expect(results).toEqual([]);
+    });
+
+    it('fireToolCall returns null when not booted', async () => {
+      const runtime = new DotAiRuntime({ workspaceRoot: '/tmp/nonexistent' });
+      const result = await runtime.fireToolCall({ tool: 'test', input: {} });
+      expect(result).toBeNull();
+    });
+
+    it('fireToolCall returns null with no extensions', async () => {
+      const runtime = new DotAiRuntime({ workspaceRoot: '/tmp/nonexistent' });
+      await runtime.boot();
+      const result = await runtime.fireToolCall({ tool: 'test', input: {} });
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('shutdown', () => {
+    it('fires session_end and flushes', async () => {
+      const flushFn = vi.fn().mockResolvedValue(undefined);
+      const runtime = new DotAiRuntime({
+        workspaceRoot: '/tmp/nonexistent',
+        logger: { log: vi.fn(), flush: flushFn },
+      });
+      await runtime.boot();
+      await runtime.shutdown();
+      expect(flushFn).toHaveBeenCalledOnce();
+    });
+
+    it('works without boot', async () => {
+      const flushFn = vi.fn().mockResolvedValue(undefined);
+      const runtime = new DotAiRuntime({
+        workspaceRoot: '/tmp/nonexistent',
+        logger: { log: vi.fn(), flush: flushFn },
+      });
+      await runtime.shutdown();
+      expect(flushFn).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('flush', () => {
+    it('flushes logger', async () => {
+      const flushFn = vi.fn().mockResolvedValue(undefined);
+      const runtime = new DotAiRuntime({
+        workspaceRoot: '/tmp/nonexistent',
+        logger: { log: vi.fn(), flush: flushFn },
+      });
+      await runtime.flush();
+      expect(flushFn).toHaveBeenCalledOnce();
+    });
+  });
+
+  describe('accessors', () => {
+    it('runner is available after boot', async () => {
+      const runtime = new DotAiRuntime({ workspaceRoot: '/tmp/nonexistent' });
+      await runtime.boot();
+      expect(runtime.runner).not.toBeNull();
+    });
+
+    it('commands returns empty array when no extensions', async () => {
+      const runtime = new DotAiRuntime({ workspaceRoot: '/tmp/nonexistent' });
+      await runtime.boot();
+      expect(runtime.commands).toEqual([]);
+    });
+
+    it('diagnostics include vocabulary size', async () => {
+      const runtime = new DotAiRuntime({ workspaceRoot: '/tmp/nonexistent' });
+      await runtime.boot();
+      const diag = runtime.diagnostics;
+      expect(diag.vocabularySize).toBeDefined();
+      expect(diag.capabilityCount).toBe(0); // no extensions = no tools
+      expect(diag.extensions).toEqual([]);
+    });
+
+    it('diagnostics before boot', () => {
+      const runtime = new DotAiRuntime({ workspaceRoot: '/tmp/nonexistent' });
+      const diag = runtime.diagnostics;
+      expect(diag.extensions).toEqual([]);
+      expect(diag.capabilityCount).toBe(0);
+    });
+  });
+});

package/src/boot-cache.ts

@@ -0,0 +1,104 @@
+import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+
+/**
+ * Cached boot data — vocabulary, extension paths, tool schemas.
+ * Stored at .ai/.cache/boot.json for fast hook startup.
+ */
+export interface BootCacheData {
+  /** Cache format version */
+  version: 1;
+  /** Checksum of inputs that produced this cache */
+  checksum: string;
+  /** Label vocabulary from resources_discover */
+  vocabulary: string[];
+  /** Extension paths that were loaded */
+  extensionPaths: string[];
+  /** Tool names + descriptions from registered tools */
+  tools: Array<{ name: string; description: string }>;
+  /** Timestamp of cache creation */
+  createdAt: string;
+}
+
+const CACHE_DIR = '.ai/.cache';
+const CACHE_FILE = 'boot.json';
+
+/**
+ * Compute a checksum from file modification times.
+ * Used to invalidate the cache when extensions or config change.
+ */
+export async function computeChecksum(
+  workspaceRoot: string,
+  extensionPaths: string[],
+): Promise<string> {
+  const hash = createHash('sha256');
+
+  // Include settings.json mtime (or dot-ai.yml)
+  for (const configName of ['settings.json', 'dot-ai.yml']) {
+    try {
+      const s = await stat(join(workspaceRoot, '.ai', configName));
+      hash.update(`config:${configName}:${s.mtimeMs}`);
+    } catch { /* not found */ }
+  }
+
+  // Include .ai/extensions/ dir mtime
+  try {
+    const s = await stat(join(workspaceRoot, '.ai', 'extensions'));
+    hash.update(`extdir:${s.mtimeMs}`);
+  } catch { /* not found */ }
+
+  // Include each extension file's mtime
+  for (const extPath of extensionPaths.sort()) {
+    try {
+      const s = await stat(extPath);
+      hash.update(`ext:${extPath}:${s.mtimeMs}`);
+    } catch { /* not found */ }
+  }
+
+  return hash.digest('hex').slice(0, 16);
+}
+
+/**
+ * Try to load cached boot data.
+ * Returns null if cache is missing, invalid, or checksum doesn't match.
+ */
+export async function loadBootCache(
+  workspaceRoot: string,
+  currentChecksum: string,
+): Promise<BootCacheData | null> {
+  try {
+    const cachePath = join(workspaceRoot, CACHE_DIR, CACHE_FILE);
+    const raw = await readFile(cachePath, 'utf-8');
+    const data = JSON.parse(raw) as BootCacheData;
+
+    if (data.version !== 1) return null;
+    if (data.checksum !== currentChecksum) return null;
+
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write boot cache to disk.
+ */
+export async function writeBootCache(
+  workspaceRoot: string,
+  data: BootCacheData,
+): Promise<void> {
+  const cacheDir = join(workspaceRoot, CACHE_DIR);
+  await mkdir(cacheDir, { recursive: true });
+  const cachePath = join(cacheDir, CACHE_FILE);
+  await writeFile(cachePath, JSON.stringify(data, null, 2), 'utf-8');
+}
+
+/**
+ * Clear the boot cache.
+ */
+export async function clearBootCache(workspaceRoot: string): Promise<void> {
+  const { rm } = await import('node:fs/promises');
+  const cacheDir = join(workspaceRoot, CACHE_DIR);
+  await rm(cacheDir, { recursive: true, force: true });
+}

package/src/capabilities.ts

@@ -0,0 +1,49 @@
+import type { ToolDefinition } from './extension-types.js';
+
+/**
+ * The result returned by a capability execution.
+ */
+export interface CapabilityResult {
+  text: string;
+  details?: Record<string, unknown>;
+}
+
+/**
+ * An interactive tool (capability) that an extension exposes to agents.
+ * Adapters translate these into the agent's native tool format.
+ */
+export interface Capability {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>; // JSON Schema
+  execute(params: Record<string, unknown>): Promise<CapabilityResult>;
+  /** Capability category */
+  category?: 'memory' | 'tasks' | string;
+  /** Whether this capability only reads data (no side effects) */
+  readOnly?: boolean;
+  /** Whether the adapter should ask for user confirmation before executing */
+  confirmationRequired?: boolean;
+  /** Capability version — incremented when parameter schema changes */
+  version?: number;
+  /** Injected into system prompt when tool is active */
+  promptSnippet?: string;
+  /** Guidelines for the LLM when using this tool */
+  promptGuidelines?: string;
+}
+
+/**
+ * Convert an extension ToolDefinition into a Capability.
+ */
+export function toolDefinitionToCapability(tool: ToolDefinition): Capability {
+  return {
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.parameters,
+    promptSnippet: tool.promptSnippet,
+    promptGuidelines: tool.promptGuidelines,
+    async execute(params: Record<string, unknown>): Promise<CapabilityResult> {
+      const result = await tool.execute(params);
+      return { text: result.content, details: result.details as Record<string, unknown> | undefined };
+    },
+  };
+}