@soleri/core 2.8.0 → 2.9.0

package/src/__tests__/extensions.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect } from 'vitest';
+import { wrapWithMiddleware } from '../extensions/middleware.js';
+import type { FacadeConfig } from '../facades/types.js';
+import type { OpMiddleware, AgentExtensions } from '../extensions/types.js';
+
+describe('extensions', () => {
+  describe('AgentExtensions type', () => {
+    it('should accept empty extensions', () => {
+      const ext: AgentExtensions = {};
+      expect(ext.ops).toBeUndefined();
+      expect(ext.facades).toBeUndefined();
+      expect(ext.middleware).toBeUndefined();
+      expect(ext.hooks).toBeUndefined();
+    });
+
+    it('should accept extensions with ops', () => {
+      const ext: AgentExtensions = {
+        ops: [
+          {
+            name: 'custom_op',
+            description: 'A custom op',
+            auth: 'read',
+            handler: async () => ({ ok: true }),
+          },
+        ],
+      };
+      expect(ext.ops).toHaveLength(1);
+    });
+
+    it('should accept extensions with facades', () => {
+      const ext: AgentExtensions = {
+        facades: [
+          {
+            name: 'my_facade',
+            description: 'Custom facade',
+            ops: [
+              {
+                name: 'do_thing',
+                description: 'Does a thing',
+                auth: 'write',
+                handler: async () => ({ done: true }),
+              },
+            ],
+          },
+        ],
+      };
+      expect(ext.facades).toHaveLength(1);
+    });
+  });
+
+  describe('wrapWithMiddleware', () => {
+    it('should wrap facade ops with before middleware', async () => {
+      const calls: string[] = [];
+      const facade: FacadeConfig = {
+        name: 'test',
+        description: 'Test facade',
+        ops: [
+          {
+            name: 'greet',
+            description: 'Say hello',
+            auth: 'read',
+            handler: async (params) => {
+              calls.push('handler');
+              return { message: `Hello ${params.name}` };
+            },
+          },
+        ],
+      };
+
+      const mw: OpMiddleware = {
+        name: 'logger',
+        before: async (ctx) => {
+          calls.push(`before:${ctx.op}`);
+          return ctx.params;
+        },
+      };
+
+      wrapWithMiddleware([facade], [mw]);
+      const result = await facade.ops[0].handler({ name: 'World' });
+
+      expect(calls).toEqual(['before:greet', 'handler']);
+      expect(result).toEqual({ message: 'Hello World' });
+    });
+
+    it('should wrap facade ops with after middleware', async () => {
+      const facade: FacadeConfig = {
+        name: 'test',
+        description: 'Test facade',
+        ops: [
+          {
+            name: 'greet',
+            description: 'Say hello',
+            auth: 'read',
+            handler: async () => ({ message: 'Hello' }),
+          },
+        ],
+      };
+
+      const mw: OpMiddleware = {
+        name: 'enricher',
+        after: async (ctx) => {
+          const data = ctx.result as Record<string, unknown>;
+          return { ...data, enriched: true };
+        },
+      };
+
+      wrapWithMiddleware([facade], [mw]);
+      const result = await facade.ops[0].handler({});
+      expect(result).toEqual({ message: 'Hello', enriched: true });
+    });
+
+    it('should chain multiple middleware in order', async () => {
+      const order: string[] = [];
+      const facade: FacadeConfig = {
+        name: 'test',
+        description: 'Test',
+        ops: [
+          {
+            name: 'op1',
+            description: 'Op',
+            auth: 'read',
+            handler: async () => {
+              order.push('handler');
+              return { v: 1 };
+            },
+          },
+        ],
+      };
+
+      const mw1: OpMiddleware = {
+        name: 'first',
+        before: async (ctx) => {
+          order.push('first:before');
+          return ctx.params;
+        },
+        after: async (ctx) => {
+          order.push('first:after');
+          return ctx.result;
+        },
+      };
+      const mw2: OpMiddleware = {
+        name: 'second',
+        before: async (ctx) => {
+          order.push('second:before');
+          return ctx.params;
+        },
+        after: async (ctx) => {
+          order.push('second:after');
+          return ctx.result;
+        },
+      };
+
+      wrapWithMiddleware([facade], [mw1, mw2]);
+      await facade.ops[0].handler({});
+
+      expect(order).toEqual([
+        'first:before',
+        'second:before',
+        'handler',
+        'second:after',
+        'first:after',
+      ]);
+    });
+
+    it('should allow before middleware to modify params', async () => {
+      const facade: FacadeConfig = {
+        name: 'test',
+        description: 'Test',
+        ops: [
+          {
+            name: 'echo',
+            description: 'Echo',
+            auth: 'read',
+            handler: async (params) => params,
+          },
+        ],
+      };
+
+      const mw: OpMiddleware = {
+        name: 'injector',
+        before: async (ctx) => ({ ...ctx.params, injected: true }),
+      };
+
+      wrapWithMiddleware([facade], [mw]);
+      const result = await facade.ops[0].handler({ original: true });
+      expect(result).toEqual({ original: true, injected: true });
+    });
+
+    it('should handle empty middleware array (no-op)', async () => {
+      const facade: FacadeConfig = {
+        name: 'test',
+        description: 'Test',
+        ops: [
+          {
+            name: 'op',
+            description: 'Op',
+            auth: 'read',
+            handler: async () => ({ ok: true }),
+          },
+        ],
+      };
+
+      wrapWithMiddleware([facade], []);
+      const result = await facade.ops[0].handler({});
+      expect(result).toEqual({ ok: true });
+    });
+
+    it('should propagate middleware errors', async () => {
+      const facade: FacadeConfig = {
+        name: 'test',
+        description: 'Test',
+        ops: [
+          {
+            name: 'op',
+            description: 'Op',
+            auth: 'read',
+            handler: async () => ({ ok: true }),
+          },
+        ],
+      };
+
+      const mw: OpMiddleware = {
+        name: 'blocker',
+        before: async () => {
+          throw new Error('Blocked by policy');
+        },
+      };
+
+      wrapWithMiddleware([facade], [mw]);
+      await expect(facade.ops[0].handler({})).rejects.toThrow('Blocked by policy');
+    });
+  });
+});

package/src/__tests__/grading-ops.test.ts

@@ -3,7 +3,7 @@ import { mkdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { createAgentRuntime } from '../runtime/runtime.js';
-import { createCoreOps } from '../runtime/core-ops.js';
+import { createSemanticFacades } from '../runtime/facades/index.js';
 import type { AgentRuntime } from '../runtime/types.js';
 import type { OpDefinition } from '../facades/types.js';
 
@@ -20,7 +20,7 @@ describe('Grading Ops', () => {
       vaultPath: ':memory:',
       plansPath: join(plannerDir, 'plans.json'),
     });
-    ops = createCoreOps(runtime);
+    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
   });
 
   afterEach(() => {

package/src/__tests__/memory-cross-project-ops.test.ts

@@ -3,7 +3,7 @@ import { mkdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { createAgentRuntime } from '../runtime/runtime.js';
-import { createCoreOps } from '../runtime/core-ops.js';
+import { createSemanticFacades } from '../runtime/facades/index.js';
 import type { AgentRuntime } from '../runtime/types.js';
 import type { OpDefinition } from '../facades/types.js';
 
@@ -20,7 +20,7 @@ describe('Memory Cross-Project Ops', () => {
       vaultPath: ':memory:',
       plansPath: join(tempDir, 'plans.json'),
     });
-    ops = createCoreOps(runtime);
+    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
   });
 
   afterEach(() => {

package/src/__tests__/normalize.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+import { normalize, collect } from '../streams/normalize.js';
+
+describe('normalize', () => {
+  it('passes through a single value', async () => {
+    expect(await collect(normalize(42))).toEqual([42]);
+  });
+
+  it('flattens an array', async () => {
+    expect(await collect(normalize([1, 2, 3]))).toEqual([1, 2, 3]);
+  });
+
+  it('resolves a promise', async () => {
+    expect(await collect(normalize(Promise.resolve(99)))).toEqual([99]);
+  });
+
+  it('resolves a promise of array', async () => {
+    expect(await collect(normalize(Promise.resolve([4, 5])))).toEqual([4, 5]);
+  });
+
+  it('consumes an async iterable', async () => {
+    async function* gen() {
+      yield 'a';
+      yield 'b';
+    }
+    expect(await collect(normalize(gen()))).toEqual(['a', 'b']);
+  });
+
+  it('flattens nested arrays', async () => {
+    const input = [
+      [1, 2],
+      [3, [4, 5]],
+    ];
+    expect(await collect(normalize(input))).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  it('handles mixed nesting', async () => {
+    async function* gen() {
+      yield 30;
+    }
+    const input = [10, Promise.resolve(20), gen()];
+    expect(await collect(normalize(input))).toEqual([10, 20, 30]);
+  });
+
+  it('handles empty array', async () => {
+    expect(await collect(normalize([]))).toEqual([]);
+  });
+
+  it('handles string as leaf (not iterable)', async () => {
+    expect(await collect(normalize('hello'))).toEqual(['hello']);
+  });
+
+  it('handles deeply nested structure', async () => {
+    const input = [[[1]], [[2, [3]]]];
+    expect(await collect(normalize(input))).toEqual([1, 2, 3]);
+  });
+});
+
+describe('collect', () => {
+  it('collects async iterable to array', async () => {
+    async function* gen() {
+      yield 1;
+      yield 2;
+      yield 3;
+    }
+    expect(await collect(gen())).toEqual([1, 2, 3]);
+  });
+
+  it('returns empty for empty iterable', async () => {
+    async function* gen() {
+      /* empty */
+    }
+    expect(await collect(gen())).toEqual([]);
+  });
+});

package/src/__tests__/playbook.test.ts

@@ -7,7 +7,7 @@ import { validatePlaybook, parsePlaybookFromEntry } from '../vault/playbook.js';
 import type { Playbook } from '../vault/playbook.js';
 import type { IntelligenceEntry } from '../intelligence/types.js';
 import { createAgentRuntime } from '../runtime/runtime.js';
-import { createCoreOps } from '../runtime/core-ops.js';
+import { createSemanticFacades } from '../runtime/facades/index.js';
 import type { AgentRuntime, OpDefinition } from '../runtime/types.js';
 
 function makePlaybook(overrides: Partial<Playbook> = {}): Playbook {
@@ -189,7 +189,7 @@ describe('playbook_create op', () => {
       vaultPath: ':memory:',
       plansPath: join(plannerDir, 'plans.json'),
     });
-    ops = createCoreOps(runtime);
+    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
   });
 
   afterEach(() => {
@@ -300,7 +300,7 @@ describe('playbook_match op', () => {
       vaultPath: ':memory:',
       plansPath: join(plannerDir, 'plans.json'),
     });
-    ops = createCoreOps(runtime);
+    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
   });
 
   afterEach(() => {
@@ -356,7 +356,7 @@ describe('playbook_seed op', () => {
       vaultPath: ':memory:',
       plansPath: join(plannerDir, 'plans.json'),
     });
-    ops = createCoreOps(runtime);
+    ops = createSemanticFacades(runtime, 'test').flatMap(f => f.ops);
   });
 
   afterEach(() => {

package/src/__tests__/replayable-stream.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest';
+import { ReplayableStream } from '../streams/replayable-stream.js';
+
+async function* generate(items: number[]): AsyncIterable<number> {
+  for (const item of items) yield item;
+}
+
+let sourceCallCount = 0;
+async function* trackedGenerate(items: number[]): AsyncIterable<number> {
+  sourceCallCount++;
+  for (const item of items) yield item;
+}
+
+describe('ReplayableStream', () => {
+  it('single consumer iterates all items', async () => {
+    const stream = new ReplayableStream(generate([1, 2, 3]));
+    const result = await stream.collect();
+    expect(result).toEqual([1, 2, 3]);
+  });
+
+  it('multiple consumers each see full stream', async () => {
+    const stream = new ReplayableStream(generate([10, 20, 30]));
+    const a = stream.collect();
+    const b = stream.collect();
+    expect(await a).toEqual([10, 20, 30]);
+    expect(await b).toEqual([10, 20, 30]);
+  });
+
+  it('source executes exactly once', async () => {
+    sourceCallCount = 0;
+    const stream = new ReplayableStream(trackedGenerate([1, 2]));
+    await stream.collect();
+    await stream.collect();
+    await stream.collect();
+    expect(sourceCallCount).toBe(1);
+  });
+
+  it('bufferedCount tracks buffer size', async () => {
+    const stream = new ReplayableStream(generate([1, 2, 3]));
+    expect(stream.bufferedCount).toBe(0);
+    await stream.collect();
+    expect(stream.bufferedCount).toBe(3);
+  });
+
+  it('empty stream returns empty array', async () => {
+    const stream = new ReplayableStream(generate([]));
+    expect(await stream.collect()).toEqual([]);
+    expect(stream.isDone).toBe(true);
+  });
+
+  it('error propagates to all consumers', async () => {
+    async function* failing(): AsyncIterable<number> {
+      yield 1;
+      throw new Error('source failed');
+    }
+    const stream = new ReplayableStream(failing());
+    await expect(stream.collect()).rejects.toThrow('source failed');
+  });
+
+  it('for-await-of works', async () => {
+    const stream = new ReplayableStream(generate([5, 6]));
+    const items: number[] = [];
+    for await (const item of stream) items.push(item);
+    expect(items).toEqual([5, 6]);
+  });
+});

package/src/__tests__/vault-extra-ops.test.ts

@@ -48,7 +48,7 @@ describe('createVaultExtraOps', () => {
   }
 
   it('should return 23 ops', () => {
-    expect(ops.length).toBe(23);
+    expect(ops.length).toBe(25);
   });
 
   it('should have all expected op names', () => {

package/src/__tests__/vault.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { Vault } from '../vault/vault.js';
+import { computeContentHash } from '../vault/content-hash.js';
 import type { IntelligenceEntry } from '../intelligence/types.js';
 
 function makeEntry(overrides: Partial<IntelligenceEntry> = {}): IntelligenceEntry {
@@ -675,4 +676,75 @@ describe('Vault', () => {
       v.close();
     });
   });
+
+  describe('Content-addressable hashing', () => {
+    it('seed populates content_hash', () => {
+      vault.seed([
+        {
+          id: 'ch-1',
+          type: 'pattern',
+          domain: 'test',
+          title: 'Hash test',
+          severity: 'warning',
+          description: 'Desc',
+          tags: ['a'],
+        },
+      ]);
+      const hash = computeContentHash({
+        type: 'pattern',
+        domain: 'test',
+        title: 'Hash test',
+        description: 'Desc',
+        tags: ['a'],
+      });
+      expect(vault.findByContentHash(hash)).toBe('ch-1');
+    });
+
+    it('findByContentHash returns null for unknown hash', () => {
+      expect(vault.findByContentHash('0000000000000000000000000000000000000000')).toBeNull();
+    });
+
+    it('contentHashStats returns correct counts', () => {
+      vault.seed([
+        {
+          id: 'hs-1',
+          type: 'pattern',
+          domain: 'd',
+          title: 'T1',
+          severity: 'warning',
+          description: 'D1',
+          tags: ['a'],
+        },
+        {
+          id: 'hs-2',
+          type: 'rule',
+          domain: 'd',
+          title: 'T2',
+          severity: 'warning',
+          description: 'D2',
+          tags: ['b'],
+        },
+      ]);
+      const stats = vault.contentHashStats();
+      expect(stats.total).toBeGreaterThanOrEqual(2);
+      expect(stats.hashed).toBe(stats.total);
+      expect(stats.uniqueHashes).toBe(stats.total);
+    });
+
+    it('backfill hashes existing entries on re-initialize', () => {
+      vault.seed([
+        {
+          id: 'bf-1',
+          type: 'pattern',
+          domain: 'd',
+          title: 'Backfill',
+          severity: 'warning',
+          description: 'D',
+          tags: [],
+        },
+      ]);
+      const stats = vault.contentHashStats();
+      expect(stats.hashed).toBe(stats.total);
+    });
+  });
 });

package/src/extensions/index.ts

@@ -0,0 +1,2 @@
+export type { AgentExtensions, OpMiddleware, MiddlewareContext } from './types.js';
+export { wrapWithMiddleware } from './middleware.js';

package/src/extensions/middleware.ts

@@ -0,0 +1,53 @@
+import type { FacadeConfig } from '../facades/types.js';
+import type { OpMiddleware } from './types.js';
+
+/**
+ * Wrap all ops in the given facades with middleware.
+ *
+ * Middleware chain follows the onion model:
+ * - before hooks: first middleware → last middleware → handler
+ * - after hooks:  last middleware → first middleware (reverse)
+ *
+ * This mutates the facade ops in-place (replaces handlers).
+ */
+export function wrapWithMiddleware(facades: FacadeConfig[], middleware: OpMiddleware[]): void {
+  if (middleware.length === 0) return;
+
+  for (const facade of facades) {
+    for (const op of facade.ops) {
+      const originalHandler = op.handler;
+
+      op.handler = async (params: Record<string, unknown>) => {
+        // Run before hooks (first → last)
+        let currentParams = params;
+        for (const mw of middleware) {
+          if (mw.before) {
+            currentParams = await mw.before({
+              facade: facade.name,
+              op: op.name,
+              params: currentParams,
+            });
+          }
+        }
+
+        // Run original handler
+        let result = await originalHandler(currentParams);
+
+        // Run after hooks (last → first)
+        for (let i = middleware.length - 1; i >= 0; i--) {
+          const mw = middleware[i];
+          if (mw.after) {
+            result = await mw.after({
+              facade: facade.name,
+              op: op.name,
+              params: currentParams,
+              result,
+            });
+          }
+        }
+
+        return result;
+      };
+    }
+  }
+}

package/src/extensions/types.ts

@@ -0,0 +1,64 @@
+import type { OpDefinition, FacadeConfig } from '../facades/types.js';
+import type { AgentRuntime } from '../runtime/types.js';
+
+/**
+ * Middleware that wraps op execution with before/after hooks.
+ *
+ * - `before` runs before the op handler. Return modified params or throw to reject.
+ * - `after` runs after the op handler. Return modified result or throw.
+ *
+ * Multiple middleware are chained: before hooks run first→last,
+ * after hooks run last→first (onion model).
+ */
+export interface OpMiddleware {
+  /** Middleware name (for logging/debugging) */
+  name: string;
+  /** Runs before op handler. Return modified params or throw to reject. */
+  before?: (ctx: MiddlewareContext) => Promise<Record<string, unknown>>;
+  /** Runs after op handler. Return modified result or throw. */
+  after?: (ctx: MiddlewareContext & { result: unknown }) => Promise<unknown>;
+}
+
+export interface MiddlewareContext {
+  facade: string;
+  op: string;
+  params: Record<string, unknown>;
+}
+
+/**
+ * User-defined extensions for a Soleri agent.
+ *
+ * Extensions live in `src/extensions/` and are auto-discovered by the entry
+ * point at startup. Core ops from `@soleri/core` are never modified — extensions
+ * are additive (new ops, new facades) or decorative (middleware).
+ *
+ * @example
+ * ```ts
+ * // src/extensions/index.ts
+ * import type { AgentExtensions } from '@soleri/core';
+ * import type { AgentRuntime } from '@soleri/core';
+ *
+ * export default function loadExtensions(runtime: AgentRuntime): AgentExtensions {
+ *   return {
+ *     ops: [myCustomOp(runtime)],
+ *     facades: [myCustomFacade(runtime)],
+ *     middleware: [auditLogger],
+ *   };
+ * }
+ * ```
+ */
+export interface AgentExtensions {
+  /** Extra ops merged into the core facade */
+  ops?: OpDefinition[];
+  /** New facades registered as separate MCP tools */
+  facades?: FacadeConfig[];
+  /** Middleware applied to all ops across all facades */
+  middleware?: OpMiddleware[];
+  /** Lifecycle hooks */
+  hooks?: {
+    /** Called after runtime init, before MCP server starts */
+    onStartup?: (runtime: AgentRuntime) => Promise<void>;
+    /** Called on SIGTERM/SIGINT before process exits */
+    onShutdown?: (runtime: AgentRuntime) => Promise<void>;
+  };
+}