@dot-ai/core 0.5.2

package/src/engine.ts

@@ -0,0 +1,145 @@
+import type {
+  MemoryProvider,
+  SkillProvider,
+  IdentityProvider,
+  RoutingProvider,
+  TaskProvider,
+  ToolProvider,
+} from './contracts.js';
+import type { EnrichedContext, Identity, Skill } from './types.js';
+import type { Logger } from './logger.js';
+import { extractLabels, buildVocabulary } from './labels.js';
+
+/**
+ * All providers needed by the engine.
+ */
+export interface Providers {
+  memory: MemoryProvider;
+  skills: SkillProvider;
+  identity: IdentityProvider;
+  routing: RoutingProvider;
+  tasks: TaskProvider;
+  tools: ToolProvider;
+}
+
+/**
+ * Cached data from boot phase. Reused across prompts.
+ */
+export interface BootCache {
+  identities: Identity[];
+  vocabulary: string[];
+  skills: Skill[];
+}
+
+/**
+ * Boot phase — run once per session.
+ * Loads identities, indexes skills/tools, builds label vocabulary.
+ */
+export async function boot(providers: Providers, logger?: Logger): Promise<BootCache> {
+  const start = performance.now();
+
+  const [identities, skills, tools] = await Promise.all([
+    providers.identity.load(),
+    providers.skills.list(),
+    providers.tools.list(),
+  ]);
+
+  // Build vocabulary from skill labels, skill triggers (excluding meta-triggers), and tool labels
+  const META_TRIGGERS = new Set(['always', 'auto', 'manual', 'boot', 'heartbeat', 'pipeline', 'audit']);
+  const skillTriggers = skills.map((s) =>
+    (s.triggers ?? []).filter((t) => !META_TRIGGERS.has(t)),
+  );
+
+  const vocabulary = buildVocabulary(
+    [...skills.map((s) => s.labels), ...skillTriggers],
+    tools.map((t) => t.labels),
+  );
+
+  logger?.log({
+    timestamp: new Date().toISOString(),
+    level: 'info',
+    phase: 'boot',
+    event: 'boot_complete',
+    data: { identityCount: identities.length, skillCount: skills.length, vocabularySize: vocabulary.length },
+    durationMs: Math.round(performance.now() - start),
+  });
+
+  return { identities, vocabulary, skills };
+}
+
+/**
+ * Enrich a prompt — run per prompt.
+ * Calls all providers to build an EnrichedContext.
+ */
+export async function enrich(
+  prompt: string,
+  providers: Providers,
+  cache: BootCache,
+  logger?: Logger,
+): Promise<EnrichedContext> {
+  const start = performance.now();
+
+  // 1. Extract labels from prompt against known vocabulary
+  const labels = extractLabels(prompt, cache.vocabulary);
+
+  logger?.log({
+    timestamp: new Date().toISOString(),
+    level: 'info',
+    phase: 'enrich',
+    event: 'labels_extracted',
+    data: { labels: labels.map(l => l.name), vocabularySize: cache.vocabulary.length },
+    durationMs: Math.round(performance.now() - start),
+  });
+
+  // 2. Search memory + match skills + match tools + route — all in parallel
+  const [memories, matchedSkills, matchedTools, routing] = await Promise.all([
+    providers.memory.search(prompt, labels.map((l) => l.name)),
+    providers.skills.match(labels),
+    providers.tools.match(labels),
+    providers.routing.route(labels),
+  ]);
+
+  logger?.log({
+    timestamp: new Date().toISOString(),
+    level: 'info',
+    phase: 'enrich',
+    event: 'enrich_complete',
+    data: {
+      labelCount: labels.length,
+      memoryCount: memories.length,
+      skillCount: matchedSkills.length,
+      routing: routing.model,
+    },
+    durationMs: Math.round(performance.now() - start),
+  });
+
+  return {
+    prompt,
+    labels,
+    identities: cache.identities,
+    memories,
+    skills: matchedSkills,
+    tools: matchedTools,
+    routing,
+  };
+}
+
+/**
+ * Learn phase — run after agent response.
+ * Stores learnings in memory.
+ */
+export async function learn(
+  response: string,
+  providers: Providers,
+): Promise<void> {
+  const MAX_LEARN_LENGTH = 500;
+  const truncated = response.length > MAX_LEARN_LENGTH
+    ? response.slice(0, MAX_LEARN_LENGTH) + '…'
+    : response;
+
+  await providers.memory.store({
+    content: truncated,
+    type: 'log',
+    date: new Date().toISOString().slice(0, 10),
+  });
+}

package/src/format.ts

@@ -0,0 +1,113 @@
+import type { EnrichedContext, MemoryEntry, Skill, Tool, RoutingResult } from './types.js';
+import type { Logger } from './logger.js';
+
+export interface FormatOptions {
+  /** Skip identity sections (useful when already injected at session start) */
+  skipIdentities?: boolean;
+  /** Max chars per skill content. Truncated skills get a [...truncated] marker. Default: unlimited */
+  maxSkillLength?: number;
+  /** Max number of skills to include (already sorted by match relevance). Default: unlimited */
+  maxSkills?: number;
+  /** Optional logger for tracing */
+  logger?: Logger;
+}
+
+/**
+ * Format an EnrichedContext into markdown sections for injection into agent context.
+ * Sections are ordered by priority: identity > memory > skills > tools > routing.
+ */
+export function formatContext(ctx: EnrichedContext, options?: FormatOptions): string {
+  const start = performance.now();
+  const sections: string[] = [];
+
+  // Identity sections (sorted by priority, highest first)
+  if (!options?.skipIdentities) {
+    const sortedIdentities = [...ctx.identities].sort((a, b) => b.priority - a.priority);
+    for (const identity of sortedIdentities) {
+      if (identity.content) {
+        sections.push(identity.content);
+      }
+    }
+  }
+
+  // Memory section
+  if (ctx.memories.length > 0) {
+    sections.push(formatMemory(ctx.memories));
+  }
+
+  // Skills section
+  let loadedSkills = ctx.skills.filter(s => s.content);
+  if (options?.maxSkills != null) {
+    loadedSkills = loadedSkills.slice(0, options.maxSkills);
+  }
+  if (loadedSkills.length > 0) {
+    sections.push(formatSkills(loadedSkills, options?.maxSkillLength));
+  }
+
+  // Tools section
+  if (ctx.tools.length > 0) {
+    sections.push(formatTools(ctx.tools));
+  }
+
+  // Routing hint
+  if (ctx.routing.model !== 'default') {
+    sections.push(formatRouting(ctx.routing));
+  }
+
+  const result = sections.join('\n\n---\n\n');
+
+  options?.logger?.log({
+    timestamp: new Date().toISOString(),
+    level: 'info',
+    phase: 'format',
+    event: 'format_complete',
+    data: {
+      outputChars: result.length,
+      estimatedTokens: Math.round(result.length / 4),
+      skillsIncluded: loadedSkills.map(s => s.name),
+      truncatedSkills: loadedSkills
+        .filter(s => options?.maxSkillLength != null && (s.content?.length ?? 0) > options.maxSkillLength)
+        .map(s => s.name),
+    },
+    durationMs: Math.round(performance.now() - start),
+  });
+
+  return result;
+}
+
+function formatMemory(memories: MemoryEntry[]): string {
+  const lines = ['## Relevant Memory\n'];
+  for (const m of memories.slice(0, 10)) { // Limit to 10 most relevant
+    const date = m.date ? ` (${m.date})` : '';
+    lines.push(`- ${m.content}${date}`);
+  }
+  return lines.join('\n');
+}
+
+function formatSkills(skills: Skill[], maxLength?: number): string {
+  const lines = ['## Active Skills\n'];
+  for (const s of skills) {
+    lines.push(`### ${s.name}`);
+    if (s.content) {
+      if (maxLength != null && s.content.length > maxLength) {
+        lines.push(s.content.slice(0, maxLength) + '\n\n[...truncated]');
+      } else {
+        lines.push(s.content);
+      }
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+function formatTools(tools: Tool[]): string {
+  const lines = ['## Available Tools\n'];
+  for (const t of tools) {
+    lines.push(`- **${t.name}**: ${t.description}`);
+  }
+  return lines.join('\n');
+}
+
+function formatRouting(routing: RoutingResult): string {
+  return `## Model Routing\n\nRecommended model: **${routing.model}** (${routing.reason})`;
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+/**
+ * @dot-ai/core v4 — Contracts and types for the dot-ai convention.
+ *
+ * dot-ai = contracts (interfaces) + providers (pluggable implementations) + adapters (agent integration).
+ * Core defines WHAT, providers define HOW, adapters define WHERE.
+ */
+
+// ── Types ──
+export type {
+  Label,
+  Node,
+  MemoryEntry,
+  Skill,
+  Identity,
+  Task,
+  Tool,
+  RoutingResult,
+  EnrichedContext,
+  TaskFilter,
+  DotAiConfig,
+  DebugConfig,
+  ProviderConfig,
+  WorkspaceConfig,
+} from './types.js';
+
+// ── Contracts ──
+export type {
+  MemoryProvider,
+  SkillProvider,
+  IdentityProvider,
+  RoutingProvider,
+  TaskProvider,
+  ToolProvider,
+  ProviderFactory,
+} from './contracts.js';
+
+// ── Engine ──
+export { boot, enrich, learn } from './engine.js';
+export type { Providers, BootCache } from './engine.js';
+
+// ── Config ──
+export { loadConfig, resolveConfig, injectRoot } from './config.js';
+export type { ResolvedConfig } from './config.js';
+
+// ── Format ──
+export { formatContext } from './format.js';
+export type { FormatOptions } from './format.js';
+
+// ── Logger ──
+export type { LogLevel, LogEntry, Logger } from './logger.js';
+export { NoopLogger, JsonFileLogger, StderrLogger } from './logger.js';
+
+// ── Loader ──
+export { registerProvider, clearProviders, createProviders } from './loader.js';
+
+// ── Labels ──
+export { extractLabels, buildVocabulary } from './labels.js';
+
+// ── Nodes ──
+export { discoverNodes, parseScanDirs } from './nodes.js';
+
+// ── registerDefaults ──
+export { registerDefaults } from './loader.js';

package/src/labels.ts

@@ -0,0 +1,40 @@
+import type { Label } from './types.js';
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Extract labels from a prompt using word-boundary keyword matching.
+ * No LLM — pure deterministic pattern matching.
+ * Returns matched Label[] from a known vocabulary.
+ */
+export function extractLabels(prompt: string, vocabulary: string[]): Label[] {
+  const labels: Label[] = [];
+  const seen = new Set<string>();
+
+  for (const word of vocabulary) {
+    if (seen.has(word)) continue;
+    const regex = new RegExp(`\\b${escapeRegex(word)}\\b`, 'i');
+    if (regex.test(prompt)) {
+      seen.add(word);
+      labels.push({ name: word, source: 'extract' });
+    }
+  }
+
+  return labels;
+}
+
+/**
+ * Build a vocabulary from skill labels and any other known labels.
+ * This is called once at boot to build the label dictionary.
+ */
+export function buildVocabulary(skillLabels: string[][], toolLabels: string[][]): string[] {
+  const set = new Set<string>();
+  for (const labels of [...skillLabels, ...toolLabels]) {
+    for (const label of labels) {
+      set.add(label);
+    }
+  }
+  return Array.from(set);
+}

package/src/loader.ts

@@ -0,0 +1,152 @@
+import type { DotAiConfig, Task } from './types.js';
+import type {
+  MemoryProvider,
+  SkillProvider,
+  IdentityProvider,
+  RoutingProvider,
+  TaskProvider,
+  ToolProvider,
+} from './contracts.js';
+import type { Providers } from './engine.js';
+import { resolveConfig } from './config.js';
+/**
+ * Registry of provider factories.
+ * Adapters register their providers here before boot.
+ */
+const registry = new Map<string, (options: Record<string, unknown>) => unknown>();
+
+/**
+ * Register a provider factory.
+ * Call this before createProviders().
+ *
+ * @example
+ * registerProvider('@dot-ai/cockpit-memory', (opts) => new CockpitMemory(opts.url));
+ */
+export function registerProvider(
+  name: string,
+  factory: (options: Record<string, unknown>) => unknown,
+): void {
+  registry.set(name, factory);
+}
+
+/**
+ * Clear all registered providers.
+ * Useful for testing.
+ */
+export function clearProviders(): void {
+  registry.clear();
+}
+
+/**
+ * Register all default file-based providers.
+ * Call this at startup if you want file-based defaults available.
+ */
+export function registerDefaults(): void {
+  // Default providers are now separate packages (@dot-ai/provider-file-memory, etc.)
+  // They are resolved via auto-discovery in resolve() → tryImportProvider()
+  // No explicit registration needed — the package names match the config defaults.
+}
+
+/**
+ * Create all providers from config.
+ * Falls back to no-op providers for any missing registration.
+ */
+export async function createProviders(config: DotAiConfig): Promise<Providers> {
+  const resolved = resolveConfig(config);
+
+  return {
+    memory: await resolve<MemoryProvider>(resolved.memory.use, resolved.memory.with ?? {}, noopMemory),
+    skills: await resolve<SkillProvider>(resolved.skills.use, resolved.skills.with ?? {}, noopSkills),
+    identity: await resolve<IdentityProvider>(resolved.identity.use, resolved.identity.with ?? {}, noopIdentity),
+    routing: await resolve<RoutingProvider>(resolved.routing.use, resolved.routing.with ?? {}, noopRouting),
+    tasks: await resolve<TaskProvider>(resolved.tasks.use, resolved.tasks.with ?? {}, noopTasks),
+    tools: await resolve<ToolProvider>(resolved.tools.use, resolved.tools.with ?? {}, noopTools),
+  };
+}
+
+async function resolve<T>(name: string, options: Record<string, unknown>, fallback: T): Promise<T> {
+  let factory = registry.get(name);
+
+  if (!factory) {
+    // Auto-discovery: try dynamic import
+    factory = await tryImportProvider(name);
+    if (factory) {
+      registry.set(name, factory); // Cache for next time
+    }
+  }
+
+  if (!factory) return fallback;
+  return factory(options) as T;
+}
+
+/**
+ * Try to import a provider package dynamically.
+ * Looks for: default export factory, createXxxProvider function, or XxxProvider class.
+ */
+async function tryImportProvider(
+  name: string,
+): Promise<((options: Record<string, unknown>) => unknown) | undefined> {
+  try {
+    const mod = await import(name);
+
+    // 1. Check for default export (function)
+    if (typeof mod.default === 'function') {
+      return mod.default as (options: Record<string, unknown>) => unknown;
+    }
+
+    // 2. Check for createXxxProvider factory function
+    for (const [key, value] of Object.entries(mod)) {
+      if (key.startsWith('create') && key.endsWith('Provider') && typeof value === 'function') {
+        return value as (options: Record<string, unknown>) => unknown;
+      }
+    }
+
+    // 3. Check for XxxProvider class (constructor)
+    for (const [key, value] of Object.entries(mod)) {
+      if (key.endsWith('Provider') && typeof value === 'function') {
+        return (opts: Record<string, unknown>) => new (value as new (opts: Record<string, unknown>) => unknown)(opts);
+      }
+    }
+
+    return undefined;
+  } catch {
+    // Package not found or import error — not a problem, fall back to noop
+    return undefined;
+  }
+}
+
+// ── No-op providers (safe fallbacks) ────────────────────────────────────────
+
+const noopMemory: MemoryProvider = {
+  async search(_query: string, _labels?: string[]) { return []; },
+  async store(_entry) {},
+};
+
+const noopSkills: SkillProvider = {
+  async list() { return []; },
+  async match(_labels) { return []; },
+  async load(_name: string) { return null; },
+};
+
+const noopIdentity: IdentityProvider = {
+  async load() { return []; },
+};
+
+const noopRouting: RoutingProvider = {
+  async route(_labels) { return { model: 'default', reason: 'no routing provider' }; },
+};
+
+const noopTasks: TaskProvider = {
+  async list(_filter?) { return []; },
+  async get(_id: string) { return null; },
+  async create(task): Promise<Task> { return { id: crypto.randomUUID(), ...task }; },
+  async update(id: string, patch: Partial<Task>): Promise<Task> {
+    return { id, text: '', status: '', ...patch };
+  },
+};
+
+const noopTools: ToolProvider = {
+  async list() { return []; },
+  async match(_labels) { return []; },
+  async load(_name: string) { return null; },
+};

package/src/logger.ts

@@ -0,0 +1,49 @@
+import { appendFile } from 'node:fs/promises';
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export interface LogEntry {
+  timestamp: string;
+  level: LogLevel;
+  phase: 'boot' | 'enrich' | 'learn' | 'format';
+  event: string;
+  data?: Record<string, unknown>;
+  durationMs?: number;
+}
+
+export interface Logger {
+  log(entry: LogEntry): void;
+  flush(): Promise<void>;
+}
+
+export class NoopLogger implements Logger {
+  log(_entry: LogEntry): void {}
+  async flush(): Promise<void> {}
+}
+
+export class JsonFileLogger implements Logger {
+  private buffer: string[] = [];
+  private filePath: string;
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+  }
+
+  log(entry: LogEntry): void {
+    this.buffer.push(JSON.stringify(entry));
+  }
+
+  async flush(): Promise<void> {
+    if (this.buffer.length === 0) return;
+    const data = this.buffer.join('\n') + '\n';
+    this.buffer = [];
+    await appendFile(this.filePath, data, 'utf-8');
+  }
+}
+
+export class StderrLogger implements Logger {
+  log(entry: LogEntry): void {
+    process.stderr.write(JSON.stringify(entry) + '\n');
+  }
+  async flush(): Promise<void> {}
+}

package/src/nodes.ts

@@ -0,0 +1,46 @@
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { Node } from './types.js';
+
+/**
+ * Discover all .ai/ directories in a workspace.
+ * Always includes root. Scans configurable directories for sub-nodes.
+ *
+ * @param root - workspace root (absolute path)
+ * @param scanDirs - directories to scan for sub-nodes (default: ["projects"])
+ */
+export function discoverNodes(root: string, scanDirs: string[] = ['projects']): Node[] {
+  const nodes: Node[] = [
+    { name: 'root', path: join(root, '.ai'), root: true },
+  ];
+
+  for (const dir of scanDirs) {
+    const scanPath = join(root, dir);
+    try {
+      const entries = readdirSync(scanPath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const aiPath = join(scanPath, entry.name, '.ai');
+        try {
+          readdirSync(aiPath); // existence check
+          nodes.push({ name: entry.name, path: aiPath, root: false });
+        } catch {
+          // No .ai/ in this directory
+        }
+      }
+    } catch {
+      // Scan directory doesn't exist
+    }
+  }
+
+  return nodes;
+}
+
+/**
+ * Parse scanDirs from a config string value.
+ * Returns empty array if not configured.
+ */
+export function parseScanDirs(value: unknown): string[] {
+  if (!value || typeof value !== 'string') return [];
+  return value.split(',').map(s => s.trim()).filter(Boolean);
+}