@soleri/core 9.11.0 → 9.13.0

package/src/dream/cron-manager.ts

@@ -0,0 +1,137 @@
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const CRON_TAG = '# soleri:dream';
+const SOLERI_DIR = join(homedir(), '.soleri');
+const LOG_PATH = join(SOLERI_DIR, 'dream-cron.log');
+
+export interface CronSchedule {
+  isScheduled: boolean;
+  time: string | null;
+  logPath: string | null;
+  projectDir: string | null;
+}
+
+function ensureSoleriDir(): void {
+  if (!existsSync(SOLERI_DIR)) {
+    mkdirSync(SOLERI_DIR, { recursive: true });
+  }
+}
+
+function getCurrentCrontab(): string {
+  try {
+    return execSync('crontab -l 2>/dev/null', { encoding: 'utf-8' });
+  } catch {
+    return '';
+  }
+}
+
+function writeCrontab(content: string): void {
+  execSync(`echo ${JSON.stringify(content)} | crontab -`, { encoding: 'utf-8' });
+}
+
+function resolveClaudePath(): string {
+  try {
+    const result = execSync('which claude 2>/dev/null', { encoding: 'utf-8' }).trim();
+    if (result) return result;
+  } catch {
+    // fall through to default
+  }
+  return join(homedir(), '.claude', 'local', 'claude');
+}
+
+function parseDreamLine(line: string): { minute: string; hour: string; projectDir: string } | null {
+  if (!line.includes(CRON_TAG)) return null;
+  const parts = line.trim().split(/\s+/);
+  if (parts.length < 6) return null;
+  const minute = parts[0];
+  const hour = parts[1];
+  // Extract --project-dir value from the line
+  const projDirMatch = line.match(/--project-dir\s+(\S+)/);
+  const projectDir = projDirMatch ? projDirMatch[1] : '';
+  return { minute, hour, projectDir };
+}
+
+export function getSchedule(): CronSchedule {
+  try {
+    const crontab = getCurrentCrontab();
+    const dreamLine = crontab.split('\n').find((l) => l.includes(CRON_TAG));
+    if (!dreamLine) {
+      return { isScheduled: false, time: null, logPath: null, projectDir: null };
+    }
+    const parsed = parseDreamLine(dreamLine);
+    if (!parsed) {
+      return { isScheduled: false, time: null, logPath: null, projectDir: null };
+    }
+    const time = `${parsed.hour.padStart(2, '0')}:${parsed.minute.padStart(2, '0')}`;
+    return {
+      isScheduled: true,
+      time,
+      logPath: LOG_PATH,
+      projectDir: parsed.projectDir || null,
+    };
+  } catch {
+    return { isScheduled: false, time: null, logPath: null, projectDir: null };
+  }
+}
+
+export function schedule(time: string, projectDir: string): CronSchedule {
+  ensureSoleriDir();
+
+  const match = time.match(/^(\d{1,2}):(\d{2})$/);
+  if (!match) {
+    return { isScheduled: false, time: null, logPath: null, projectDir: null };
+  }
+
+  const hour = parseInt(match[1], 10);
+  let minute = parseInt(match[2], 10);
+
+  // Add a few minutes offset to avoid running exactly on the hour
+  if (minute === 0) {
+    minute = 3;
+  }
+
+  const claudePath = resolveClaudePath();
+  const cronLine = `${minute} ${hour} * * * ${claudePath} --dangerously-skip-permissions -p "Run /ernesto-dream" --project-dir ${projectDir} >> ${LOG_PATH} 2>&1 ${CRON_TAG}`;
+
+  try {
+    const crontab = getCurrentCrontab();
+    // Remove any existing dream lines (idempotent)
+    const filtered = crontab
+      .split('\n')
+      .filter((l) => !l.includes(CRON_TAG))
+      .join('\n');
+
+    const newCrontab = filtered.endsWith('\n')
+      ? `${filtered}${cronLine}\n`
+      : `${filtered}\n${cronLine}\n`;
+    writeCrontab(newCrontab);
+
+    const formattedTime = `${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}`;
+    return {
+      isScheduled: true,
+      time: formattedTime,
+      logPath: LOG_PATH,
+      projectDir,
+    };
+  } catch {
+    return { isScheduled: false, time: null, logPath: null, projectDir: null };
+  }
+}
+
+export function unschedule(): CronSchedule {
+  try {
+    const crontab = getCurrentCrontab();
+    const filtered = crontab
+      .split('\n')
+      .filter((l) => !l.includes(CRON_TAG))
+      .join('\n');
+
+    writeCrontab(filtered);
+  } catch {
+    // Graceful degradation — if crontab fails, just return unscheduled
+  }
+  return { isScheduled: false, time: null, logPath: null, projectDir: null };
+}

package/src/dream/dream-engine.ts

@@ -0,0 +1,119 @@
+import type { PersistenceProvider } from '../persistence/types.js';
+import type { Vault } from '../vault/vault.js';
+import type { Curator } from '../curator/curator.js';
+
+export interface DreamReport {
+  durationMs: number;
+  duplicatesFound: number;
+  staleArchived: number;
+  contradictionsFound: number;
+  totalDreams: number;
+  timestamp: string;
+}
+
+export interface DreamStatus {
+  sessionsSinceLastDream: number;
+  lastDreamAt: string | null;
+  lastDreamDurationMs: number | null;
+  totalDreams: number;
+  gateEligible: boolean;
+}
+
+export class DreamEngine {
+  private provider: PersistenceProvider;
+
+  constructor(
+    vault: Vault,
+    private curator: Curator,
+    private sessionThreshold: number = 5,
+    private hourThreshold: number = 24,
+  ) {
+    this.provider = vault.getProvider();
+  }
+
+  run(): DreamReport {
+    const start = Date.now();
+    const result = this.curator.consolidate({
+      dryRun: false,
+      staleDaysThreshold: 90,
+      duplicateThreshold: 0.45,
+      contradictionThreshold: 0.4,
+    });
+    const durationMs = Date.now() - start;
+    const now = new Date().toISOString();
+
+    this.provider.run(
+      `UPDATE dream_meta SET
+        sessions_since_last_dream = 0,
+        last_dream_at = ?,
+        last_dream_duration_ms = ?,
+        last_dream_report = ?,
+        total_dreams = total_dreams + 1,
+        updated_at = ?
+      WHERE id = 1`,
+      [now, durationMs, JSON.stringify(result), now],
+    );
+
+    const meta = this.getMeta();
+    return {
+      durationMs,
+      duplicatesFound: result.duplicates?.length ?? 0,
+      staleArchived: result.staleEntries?.length ?? 0,
+      contradictionsFound: result.contradictions?.length ?? 0,
+      totalDreams: meta.total_dreams as number,
+      timestamp: now,
+    };
+  }
+
+  incrementSessionCount(): void {
+    this.provider.run(
+      "UPDATE dream_meta SET sessions_since_last_dream = sessions_since_last_dream + 1, updated_at = datetime('now') WHERE id = 1",
+    );
+  }
+
+  getStatus(): DreamStatus {
+    const meta = this.getMeta();
+    return {
+      sessionsSinceLastDream: meta.sessions_since_last_dream as number,
+      lastDreamAt: meta.last_dream_at as string | null,
+      lastDreamDurationMs: meta.last_dream_duration_ms as number | null,
+      totalDreams: meta.total_dreams as number,
+      gateEligible: this.isGateEligible(meta),
+    };
+  }
+
+  checkGate(): { eligible: boolean; reason: string } {
+    const meta = this.getMeta();
+    const sessions = meta.sessions_since_last_dream as number;
+    const lastDream = meta.last_dream_at as string | null;
+    if (sessions < this.sessionThreshold) {
+      return {
+        eligible: false,
+        reason: `Only ${sessions}/${this.sessionThreshold} sessions since last dream`,
+      };
+    }
+    if (lastDream) {
+      const hoursSince = (Date.now() - new Date(lastDream).getTime()) / (1000 * 60 * 60);
+      if (hoursSince < this.hourThreshold) {
+        return {
+          eligible: false,
+          reason: `Only ${Math.round(hoursSince)}h/${this.hourThreshold}h since last dream`,
+        };
+      }
+    }
+    return { eligible: true, reason: 'Gate conditions met' };
+  }
+
+  private isGateEligible(meta: Record<string, unknown>): boolean {
+    const sessions = meta.sessions_since_last_dream as number;
+    const lastDream = meta.last_dream_at as string | null;
+    if (sessions < this.sessionThreshold) return false;
+    if (!lastDream) return true;
+    const hoursSince = (Date.now() - new Date(lastDream).getTime()) / (1000 * 60 * 60);
+    return hoursSince >= this.hourThreshold;
+  }
+
+  private getMeta(): Record<string, unknown> {
+    return this.provider.get('SELECT * FROM dream_meta WHERE id = 1') as Record<string, unknown>;
+  }
+}

package/src/dream/dream-ops.ts

@@ -0,0 +1,56 @@
+/**
+ * Dream runtime ops — facade operations for the dream engine.
+ * dream_run, dream_status, dream_check_gate.
+ */
+
+import { z } from 'zod';
+import type { OpDefinition } from '../facades/types.js';
+import type { AgentRuntime } from '../runtime/types.js';
+import { DreamEngine } from './dream-engine.js';
+import { ensureDreamSchema } from './schema.js';
+
+export function createDreamOps(runtime: AgentRuntime): OpDefinition[] {
+  const { vault, curator } = runtime;
+  ensureDreamSchema(vault.getProvider());
+  const engine = new DreamEngine(vault, curator);
+
+  return [
+    {
+      name: 'dream_run',
+      description:
+        'Run a dream cycle — consolidate vault knowledge (duplicates, stale entries, contradictions). Checks gate unless force=true.',
+      auth: 'write',
+      schema: z.object({
+        force: z.boolean().optional().describe('Skip gate check. Default false.'),
+      }),
+      handler: async (params) => {
+        const force = (params.force as boolean) ?? false;
+        if (!force) {
+          const gate = engine.checkGate();
+          if (!gate.eligible) {
+            return { skipped: true, reason: gate.reason, status: engine.getStatus() };
+          }
+        }
+        return engine.run();
+      },
+    },
+    {
+      name: 'dream_status',
+      description:
+        'Dream status — sessions since last dream, last dream timestamp, gate eligibility.',
+      auth: 'read',
+      handler: async () => {
+        return engine.getStatus();
+      },
+    },
+    {
+      name: 'dream_check_gate',
+      description:
+        'Check whether dream gate conditions are met (session threshold + time threshold).',
+      auth: 'read',
+      handler: async () => {
+        return engine.checkGate();
+      },
+    },
+  ];
+}

package/src/dream/dream.test.ts

@@ -0,0 +1,182 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { Vault } from '../vault/vault.js';
+import { Curator } from '../curator/curator.js';
+import { ensureDreamSchema } from './schema.js';
+import { DreamEngine } from './dream-engine.js';
+import { createDreamOps } from './dream-ops.js';
+import type { AgentRuntime } from '../runtime/types.js';
+
+describe('dream schema', () => {
+  let vault: Vault;
+  beforeEach(() => {
+    vault = new Vault(':memory:');
+  });
+  afterEach(() => {
+    vault.close();
+  });
+
+  it('creates dream_meta table', () => {
+    ensureDreamSchema(vault.getProvider());
+    const info = vault
+      .getProvider()
+      .get("SELECT name FROM sqlite_master WHERE type='table' AND name='dream_meta'");
+    expect(info).toBeTruthy();
+  });
+
+  it('initializes single row with defaults', () => {
+    ensureDreamSchema(vault.getProvider());
+    const row = vault.getProvider().get('SELECT * FROM dream_meta WHERE id = 1') as Record<
+      string,
+      unknown
+    >;
+    expect(row.sessions_since_last_dream).toBe(0);
+    expect(row.total_dreams).toBe(0);
+    expect(row.last_dream_at).toBeNull();
+  });
+});
+
+describe('DreamEngine', () => {
+  let vault: Vault;
+  let curator: Curator;
+  let engine: DreamEngine;
+
+  beforeEach(() => {
+    vault = new Vault(':memory:');
+    ensureDreamSchema(vault.getProvider());
+    curator = new Curator(vault);
+    engine = new DreamEngine(vault, curator);
+  });
+  afterEach(() => {
+    vault.close();
+  });
+
+  it('run() returns a dream report', () => {
+    const report = engine.run();
+    expect(report).toHaveProperty('durationMs');
+    expect(report).toHaveProperty('duplicatesFound');
+    expect(report).toHaveProperty('staleArchived');
+    expect(report).toHaveProperty('contradictionsFound');
+    expect(report).toHaveProperty('totalDreams');
+    expect(report.totalDreams).toBe(1);
+  });
+
+  it('run() resets sessions_since_last_dream to 0', () => {
+    for (let i = 0; i < 5; i++) engine.incrementSessionCount();
+    expect(engine.getStatus().sessionsSinceLastDream).toBe(5);
+    engine.run();
+    expect(engine.getStatus().sessionsSinceLastDream).toBe(0);
+  });
+
+  it('incrementSessionCount increases counter', () => {
+    expect(engine.getStatus().sessionsSinceLastDream).toBe(0);
+    engine.incrementSessionCount();
+    expect(engine.getStatus().sessionsSinceLastDream).toBe(1);
+    engine.incrementSessionCount();
+    expect(engine.getStatus().sessionsSinceLastDream).toBe(2);
+  });
+
+  it('getStatus returns current dream state', () => {
+    const status = engine.getStatus();
+    expect(status.sessionsSinceLastDream).toBe(0);
+    expect(status.lastDreamAt).toBeNull();
+    expect(status.totalDreams).toBe(0);
+    expect(status.gateEligible).toBe(false);
+  });
+
+  describe('gate conditions', () => {
+    it('not eligible with 0 sessions', () => {
+      const gate = engine.checkGate();
+      expect(gate.eligible).toBe(false);
+      expect(gate.reason).toContain('0/5');
+    });
+
+    it('eligible after 5 sessions and no prior dream', () => {
+      for (let i = 0; i < 5; i++) engine.incrementSessionCount();
+      const gate = engine.checkGate();
+      expect(gate.eligible).toBe(true);
+    });
+
+    it('not eligible if dreamed less than 24h ago', () => {
+      for (let i = 0; i < 5; i++) engine.incrementSessionCount();
+      engine.run();
+      for (let i = 0; i < 5; i++) engine.incrementSessionCount();
+      const gate = engine.checkGate();
+      expect(gate.eligible).toBe(false);
+      expect(gate.reason).toContain('h/24h');
+    });
+
+    it('force run works regardless of gate', () => {
+      const gate = engine.checkGate();
+      expect(gate.eligible).toBe(false);
+      const report = engine.run();
+      expect(report.totalDreams).toBe(1);
+    });
+  });
+});
+
+describe('dream ops', () => {
+  let vault: Vault;
+  let ops: ReturnType<typeof createDreamOps>;
+
+  function findOp(name: string) {
+    const op = ops.find((o) => o.name === name);
+    if (!op) throw new Error(`Op ${name} not found`);
+    return op;
+  }
+
+  beforeEach(() => {
+    vault = new Vault(':memory:');
+    const curator = new Curator(vault);
+    const runtime = { vault, curator } as unknown as AgentRuntime;
+    ops = createDreamOps(runtime);
+  });
+  afterEach(() => {
+    vault.close();
+  });
+
+  it('creates 3 ops with correct names', () => {
+    expect(ops).toHaveLength(3);
+    expect(ops.map((o) => o.name).sort()).toEqual(
+      ['dream_check_gate', 'dream_run', 'dream_status'].sort(),
+    );
+  });
+
+  it('dream_status returns status', async () => {
+    const result = (await findOp('dream_status').handler({})) as Record<string, unknown>;
+    expect(result).toHaveProperty('sessionsSinceLastDream');
+    expect(result).toHaveProperty('gateEligible');
+    expect(result.sessionsSinceLastDream).toBe(0);
+  });
+
+  it('dream_check_gate returns gate info', async () => {
+    const result = (await findOp('dream_check_gate').handler({})) as Record<string, unknown>;
+    expect(result).toHaveProperty('eligible');
+    expect(result).toHaveProperty('reason');
+    expect(result.eligible).toBe(false);
+  });
+
+  it('dream_run skips when gate not met and force=false', async () => {
+    const result = (await findOp('dream_run').handler({})) as Record<string, unknown>;
+    expect(result.skipped).toBe(true);
+    expect(result.reason).toBeDefined();
+    expect(result.status).toBeDefined();
+  });
+
+  it('dream_run executes when force=true', async () => {
+    const result = (await findOp('dream_run').handler({ force: true })) as Record<string, unknown>;
+    expect(result.skipped).toBeUndefined();
+    expect(result).toHaveProperty('durationMs');
+    expect(result).toHaveProperty('totalDreams');
+    expect(result.totalDreams).toBe(1);
+  });
+
+  it('dream_run executes when gate is met', async () => {
+    // Increment sessions to meet threshold (default 5)
+    const engine = new DreamEngine(vault, new Curator(vault));
+    for (let i = 0; i < 5; i++) engine.incrementSessionCount();
+
+    const result = (await findOp('dream_run').handler({})) as Record<string, unknown>;
+    expect(result.skipped).toBeUndefined();
+    expect(result).toHaveProperty('totalDreams');
+  });
+});

package/src/dream/index.ts

@@ -0,0 +1,6 @@
+export { ensureDreamSchema } from './schema.js';
+export { DreamEngine } from './dream-engine.js';
+export type { DreamReport, DreamStatus } from './dream-engine.js';
+export { createDreamOps } from './dream-ops.js';
+export { getSchedule, schedule, unschedule } from './cron-manager.js';
+export type { CronSchedule } from './cron-manager.js';

package/src/dream/schema.ts

@@ -0,0 +1,17 @@
+import type { PersistenceProvider } from '../persistence/types.js';
+
+export function ensureDreamSchema(provider: PersistenceProvider): void {
+  provider.execSql(`
+    CREATE TABLE IF NOT EXISTS dream_meta (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      sessions_since_last_dream INTEGER NOT NULL DEFAULT 0,
+      last_dream_at TEXT,
+      last_dream_duration_ms INTEGER,
+      last_dream_report TEXT,
+      total_dreams INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+  provider.run('INSERT OR IGNORE INTO dream_meta (id) VALUES (1)');
+}

package/src/embeddings/openai-provider.ts

@@ -0,0 +1,158 @@
+/**
+ * OpenAI Embedding Provider — generates dense vector embeddings via the
+ * OpenAI embeddings API. Supports key pool rotation and batch chunking.
+ */
+
+import type { EmbeddingProvider, EmbeddingResult, EmbeddingConfig } from './types.js';
+import type { KeyPool } from '../llm/key-pool.js';
+import { LLMError } from '../llm/types.js';
+import { retry } from '../llm/utils.js';
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const DEFAULT_MODEL = 'text-embedding-3-small';
+const DEFAULT_DIMENSIONS = 1536;
+const DEFAULT_BATCH_SIZE = 2048;
+const DEFAULT_BASE_URL = 'https://api.openai.com';
+const REQUEST_TIMEOUT_MS = 60_000;
+
+// =============================================================================
+// RESPONSE TYPES
+// =============================================================================
+
+interface OpenAIEmbeddingResponse {
+  data: Array<{ embedding: number[]; index: number }>;
+  usage: { prompt_tokens: number; total_tokens: number };
+  model: string;
+}
+
+// =============================================================================
+// PROVIDER
+// =============================================================================
+
+/**
+ * Embedding provider that calls the OpenAI `/v1/embeddings` endpoint.
+ *
+ * Supports optional {@link KeyPool} for key rotation — on 429 responses the
+ * pool is rotated so the next call uses a fresh key. If no pool is provided,
+ * falls back to `config.apiKey`.
+ */
+export class OpenAIEmbeddingProvider implements EmbeddingProvider {
+  readonly providerName = 'openai';
+  readonly model: string;
+  readonly dimensions: number;
+
+  private readonly apiUrl: string;
+  private readonly batchSize: number;
+  private readonly apiKey?: string;
+  private readonly keyPool?: KeyPool;
+
+  constructor(config: EmbeddingConfig, keyPool?: KeyPool) {
+    this.model = config.model || DEFAULT_MODEL;
+    this.dimensions = DEFAULT_DIMENSIONS;
+    this.batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE;
+    this.apiKey = config.apiKey;
+    this.keyPool = keyPool;
+
+    const baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+    this.apiUrl = `${baseUrl}/v1/embeddings`;
+
+    if (!this.keyPool?.hasKeys && !this.apiKey) {
+      throw new LLMError(
+        'OpenAI embedding provider requires an API key — provide config.apiKey or a KeyPool with keys',
+        { retryable: false },
+      );
+    }
+  }
+
+  /**
+   * Embed one or more texts, returning one vector per input text.
+   * Automatically chunks requests that exceed {@link batchSize}.
+   */
+  async embed(texts: string[]): Promise<EmbeddingResult> {
+    if (texts.length === 0) {
+      return { vectors: [], tokensUsed: 0, model: this.model };
+    }
+
+    // Single batch — no chunking needed
+    if (texts.length <= this.batchSize) {
+      return this.callApi(texts);
+    }
+
+    // Chunk into batches and concatenate results
+    const allVectors: number[][] = [];
+    let totalTokens = 0;
+
+    for (let offset = 0; offset < texts.length; offset += this.batchSize) {
+      const chunk = texts.slice(offset, offset + this.batchSize);
+      // oxlint-disable-next-line eslint(no-await-in-loop)
+      const result = await this.callApi(chunk);
+      allVectors.push(...result.vectors);
+      totalTokens += result.tokensUsed;
+    }
+
+    return { vectors: allVectors, tokensUsed: totalTokens, model: this.model };
+  }
+
+  // ===========================================================================
+  // INTERNALS
+  // ===========================================================================
+
+  private resolveApiKey(): string {
+    if (this.keyPool?.hasKeys) {
+      return this.keyPool.getActiveKey().expose();
+    }
+    if (this.apiKey) {
+      return this.apiKey;
+    }
+    throw new LLMError('No API key available for OpenAI embeddings', { retryable: false });
+  }
+
+  private async callApi(texts: string[]): Promise<EmbeddingResult> {
+    const doRequest = async (): Promise<EmbeddingResult> => {
+      const apiKey = this.resolveApiKey();
+
+      const response = await fetch(this.apiUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          model: this.model,
+          input: texts,
+        }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+      });
+
+      if (!response.ok) {
+        // Rotate key on rate limit
+        if (response.status === 429 && this.keyPool && this.keyPool.poolSize > 1) {
+          this.keyPool.rotateOnError();
+        }
+
+        const errorBody = await response.text();
+        throw new LLMError(`OpenAI Embeddings API error: ${response.status} - ${errorBody}`, {
+          retryable: response.status === 429 || response.status >= 500,
+          statusCode: response.status,
+        });
+      }
+
+      const data = (await response.json()) as OpenAIEmbeddingResponse;
+
+      // OpenAI returns data sorted by index, but sort defensively
+      const sorted = [...data.data].sort((a, b) => a.index - b.index);
+      const vectors = sorted.map((d) => d.embedding);
+
+      return {
+        vectors,
+        tokensUsed: data.usage?.total_tokens ?? 0,
+        model: this.model,
+      };
+    };
+
+    return retry(doRequest, { maxAttempts: 3 });
+  }
+}