@soleri/core 9.0.3 → 9.2.0

package/src/facades/facade-factory.test.ts

@@ -0,0 +1,424 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import type { FacadeConfig, AuthPolicy } from './types.js';
+import { registerFacade, registerAllFacades } from './facade-factory.js';
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+function createFacade(overrides?: Partial<FacadeConfig>): FacadeConfig {
+  return {
+    name: 'test_facade',
+    description: 'Test facade',
+    ops: [
+      {
+        name: 'read_op',
+        description: 'Read',
+        auth: 'read',
+        handler: async () => ({ result: 'read' }),
+      },
+      {
+        name: 'write_op',
+        description: 'Write',
+        auth: 'write',
+        handler: async () => ({ result: 'write' }),
+      },
+      {
+        name: 'admin_op',
+        description: 'Admin',
+        auth: 'admin',
+        handler: async () => ({ result: 'admin' }),
+      },
+    ],
+    ...overrides,
+  };
+}
+
+type DispatchHandler = (args: { op: string; params: Record<string, unknown> }) => Promise<{
+  content: Array<{ type: string; text: string }>;
+}>;
+
+function captureHandler(facade: FacadeConfig, authPolicy?: () => AuthPolicy): DispatchHandler {
+  let captured: DispatchHandler | null = null;
+  const mockServer = {
+    tool: (_name: string, _desc: string, _schema: unknown, handler: unknown) => {
+      captured = handler as DispatchHandler;
+    },
+  };
+  registerFacade(mockServer as never, facade, authPolicy);
+  return captured!;
+}
+
+async function callOp(
+  handler: DispatchHandler,
+  op: string,
+  params: Record<string, unknown> = {},
+): Promise<{ success: boolean; error?: string; data?: unknown; op?: string; facade?: string }> {
+  const result = await handler({ op, params });
+  return JSON.parse(result.content[0].text);
+}
+
+// =============================================================================
+// dispatchOp — op routing
+// =============================================================================
+
+describe('facade-factory dispatchOp — colocated', () => {
+  it('returns error for unknown operation', async () => {
+    const handler = captureHandler(createFacade());
+    const result = await callOp(handler, 'nonexistent_op');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('Unknown operation');
+    expect(result.error).toContain('nonexistent_op');
+    expect(result.error).toContain('read_op');
+    expect(result.op).toBe('nonexistent_op');
+    expect(result.facade).toBe('test_facade');
+  });
+
+  it('dispatches to correct op handler and returns data', async () => {
+    const handler = captureHandler(createFacade());
+
+    const read = await callOp(handler, 'read_op');
+    expect(read.success).toBe(true);
+    expect(read.data).toEqual({ result: 'read' });
+    expect(read.op).toBe('read_op');
+    expect(read.facade).toBe('test_facade');
+  });
+
+  it('catches handler exceptions and returns error response', async () => {
+    const facade = createFacade({
+      ops: [{
+        name: 'failing_op',
+        description: 'Fails',
+        auth: 'read',
+        handler: async () => { throw new Error('Handler exploded'); },
+      }],
+    });
+    const handler = captureHandler(facade);
+
+    const result = await callOp(handler, 'failing_op');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Handler exploded');
+  });
+
+  it('catches non-Error throws and converts to string', async () => {
+    const facade = createFacade({
+      ops: [{
+        name: 'string_throw',
+        description: 'Throws string',
+        auth: 'read',
+        handler: async () => { throw 'raw string error'; },
+      }],
+    });
+    const handler = captureHandler(facade);
+
+    const result = await callOp(handler, 'string_throw');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('raw string error');
+  });
+});
+
+// =============================================================================
+// Schema validation
+// =============================================================================
+
+describe('facade-factory schema validation — colocated', () => {
+  it('validates params against op schema and rejects invalid', async () => {
+    const facade = createFacade({
+      ops: [{
+        name: 'validated_op',
+        description: 'Has schema',
+        auth: 'read',
+        schema: z.object({ query: z.string(), limit: z.number() }),
+        handler: async (params) => ({ echo: params }),
+      }],
+    });
+    const handler = captureHandler(facade);
+
+    const result = await callOp(handler, 'validated_op', { query: 123 as unknown as string });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('Invalid params');
+  });
+
+  it('passes validated params to handler', async () => {
+    const facade = createFacade({
+      ops: [{
+        name: 'validated_op',
+        description: 'Has schema',
+        auth: 'read',
+        schema: z.object({ query: z.string(), limit: z.number().optional() }),
+        handler: async (params) => ({ echo: params }),
+      }],
+    });
+    const handler = captureHandler(facade);
+
+    const result = await callOp(handler, 'validated_op', { query: 'test' });
+
+    expect(result.success).toBe(true);
+    expect((result.data as { echo: unknown }).echo).toEqual({ query: 'test' });
+  });
+
+  it('passes raw params when no schema defined', async () => {
+    const facade = createFacade({
+      ops: [{
+        name: 'no_schema',
+        description: 'No schema',
+        auth: 'read',
+        handler: async (params) => ({ echo: params }),
+      }],
+    });
+    const handler = captureHandler(facade);
+
+    const result = await callOp(handler, 'no_schema', { anything: 'goes' });
+
+    expect(result.success).toBe(true);
+    expect((result.data as { echo: unknown }).echo).toEqual({ anything: 'goes' });
+  });
+});
+
+// =============================================================================
+// Auth enforcement
+// =============================================================================
+
+describe('facade-factory auth — colocated', () => {
+  it('permissive mode allows all ops', async () => {
+    const handler = captureHandler(createFacade(), () => ({
+      mode: 'permissive',
+      callerLevel: 'read',
+    }));
+
+    expect((await callOp(handler, 'admin_op')).success).toBe(true);
+  });
+
+  it('enforce mode blocks higher-level ops', async () => {
+    const handler = captureHandler(createFacade(), () => ({
+      mode: 'enforce',
+      callerLevel: 'read',
+    }));
+
+    expect((await callOp(handler, 'read_op')).success).toBe(true);
+    expect((await callOp(handler, 'write_op')).success).toBe(false);
+    expect((await callOp(handler, 'admin_op')).success).toBe(false);
+  });
+
+  it('warn mode allows ops (does not block)', async () => {
+    const handler = captureHandler(createFacade(), () => ({
+      mode: 'warn',
+      callerLevel: 'read',
+    }));
+
+    expect((await callOp(handler, 'write_op')).success).toBe(true);
+    expect((await callOp(handler, 'admin_op')).success).toBe(true);
+  });
+
+  it('no auth policy defaults to permissive', async () => {
+    const handler = captureHandler(createFacade());
+    expect((await callOp(handler, 'admin_op')).success).toBe(true);
+  });
+
+  it('per-op overrides take precedence over op auth level', async () => {
+    const handler = captureHandler(createFacade(), () => ({
+      mode: 'enforce',
+      callerLevel: 'write',
+      overrides: { read_op: 'admin' },
+    }));
+
+    // read_op overridden to admin — blocked for write caller
+    expect((await callOp(handler, 'read_op')).success).toBe(false);
+    // write_op unchanged — allowed
+    expect((await callOp(handler, 'write_op')).success).toBe(true);
+  });
+
+  it('auth policy is evaluated per dispatch (mutable at runtime)', async () => {
+    let mode: AuthPolicy['mode'] = 'permissive';
+    const handler = captureHandler(createFacade(), () => ({
+      mode,
+      callerLevel: 'read',
+    }));
+
+    expect((await callOp(handler, 'write_op')).success).toBe(true);
+
+    mode = 'enforce';
+    expect((await callOp(handler, 'write_op')).success).toBe(false);
+  });
+});
+
+// =============================================================================
+// registerAllFacades + hot ops
+// =============================================================================
+
+describe('registerAllFacades — colocated', () => {
+  it('registers all facades on the server', () => {
+    const registered: string[] = [];
+    const mockServer = {
+      tool: (name: string) => { registered.push(name); },
+    };
+
+    registerAllFacades(mockServer as never, [
+      createFacade({ name: 'facade_a' }),
+      createFacade({ name: 'facade_b' }),
+    ]);
+
+    expect(registered).toContain('facade_a');
+    expect(registered).toContain('facade_b');
+  });
+
+  it('accepts legacy function auth policy', () => {
+    const registered: string[] = [];
+    const mockServer = {
+      tool: (name: string) => { registered.push(name); },
+    };
+
+    registerAllFacades(mockServer as never, [createFacade()], () => ({
+      mode: 'permissive' as const,
+      callerLevel: 'read' as const,
+    }));
+
+    expect(registered).toContain('test_facade');
+  });
+
+  it('promotes hot ops to standalone tools with agentId prefix', () => {
+    const registered: string[] = [];
+    const mockServer = {
+      tool: (name: string) => { registered.push(name); },
+    };
+
+    const facade = createFacade({
+      ops: [
+        { name: 'search', description: 'Search', auth: 'read', hot: true, handler: async () => ({}) },
+        { name: 'delete', description: 'Delete', auth: 'admin', handler: async () => ({}) },
+      ],
+    });
+
+    registerAllFacades(mockServer as never, [facade], { agentId: 'myagent' });
+
+    expect(registered).toContain('test_facade');
+    expect(registered).toContain('myagent_search');
+    expect(registered).not.toContain('myagent_delete');
+  });
+
+  it('promotes ops listed in hotOps option', () => {
+    const registered: string[] = [];
+    const mockServer = {
+      tool: (name: string) => { registered.push(name); },
+    };
+
+    registerAllFacades(mockServer as never, [createFacade()], {
+      agentId: 'agent',
+      hotOps: ['write_op'],
+    });
+
+    expect(registered).toContain('agent_write_op');
+    expect(registered).not.toContain('agent_read_op');
+  });
+
+  it('does not promote hot ops without agentId', () => {
+    const registered: string[] = [];
+    const mockServer = {
+      tool: (name: string) => { registered.push(name); },
+    };
+
+    const facade = createFacade({
+      ops: [
+        { name: 'search', description: 'Search', auth: 'read', hot: true, handler: async () => ({}) },
+      ],
+    });
+
+    registerAllFacades(mockServer as never, [facade]);
+
+    expect(registered).toEqual(['test_facade']);
+  });
+
+  it('hot op handler executes correctly', async () => {
+    let capturedHandler: ((params: unknown) => Promise<unknown>) | null = null;
+    const mockServer = {
+      tool: (name: string, _desc: string, _schema: unknown, handler: unknown) => {
+        if (name === 'agent_search') {
+          capturedHandler = handler as typeof capturedHandler;
+        }
+      },
+    };
+
+    const facade = createFacade({
+      ops: [{
+        name: 'search',
+        description: 'Search',
+        auth: 'read',
+        hot: true,
+        schema: z.object({ query: z.string() }),
+        handler: async (params) => ({ results: [], query: (params as { query: string }).query }),
+      }],
+    });
+
+    registerAllFacades(mockServer as never, [facade], { agentId: 'agent' });
+
+    expect(capturedHandler).not.toBeNull();
+    const result = await capturedHandler!({ query: 'hello' }) as { content: Array<{ text: string }> };
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.success).toBe(true);
+    expect(parsed.data.query).toBe('hello');
+  });
+
+  it('hot op handler catches errors gracefully', async () => {
+    let capturedHandler: ((params: unknown) => Promise<unknown>) | null = null;
+    const mockServer = {
+      tool: (name: string, _desc: string, _schema: unknown, handler: unknown) => {
+        if (name === 'agent_boom') {
+          capturedHandler = handler as typeof capturedHandler;
+        }
+      },
+    };
+
+    const facade = createFacade({
+      ops: [{
+        name: 'boom',
+        description: 'Explodes',
+        auth: 'read',
+        hot: true,
+        handler: async () => { throw new Error('Kaboom'); },
+      }],
+    });
+
+    registerAllFacades(mockServer as never, [facade], { agentId: 'agent' });
+
+    const result = await capturedHandler!({}) as { content: Array<{ text: string }> };
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.success).toBe(false);
+    expect(parsed.error).toBe('Kaboom');
+  });
+
+  it('hot op respects auth policy enforcement', async () => {
+    let capturedHandler: ((params: unknown) => Promise<unknown>) | null = null;
+    const mockServer = {
+      tool: (name: string, _desc: string, _schema: unknown, handler: unknown) => {
+        if (name === 'agent_admin_op') {
+          capturedHandler = handler as typeof capturedHandler;
+        }
+      },
+    };
+
+    const facade = createFacade({
+      ops: [{
+        name: 'admin_op',
+        description: 'Admin',
+        auth: 'admin',
+        hot: true,
+        handler: async () => ({ ok: true }),
+      }],
+    });
+
+    registerAllFacades(mockServer as never, [facade], {
+      agentId: 'agent',
+      authPolicy: () => ({ mode: 'enforce', callerLevel: 'read' }),
+    });
+
+    const result = await capturedHandler!({}) as { content: Array<{ text: string }> };
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.success).toBe(false);
+    expect(parsed.error).toContain('requires admin');
+  });
+});

package/src/flows/chain-runner.test.ts

@@ -0,0 +1,273 @@
+/**
+ * ChainRunner — colocated contract tests.
+ *
+ * Contract:
+ * - execute() runs steps sequentially, resolving $variable references between steps
+ * - Gates pause (user-approval) or fail (auto-test) execution
+ * - resume()/approve() continues from paused gate
+ * - getInstance()/list() retrieve persisted state
+ * - State persists to SQLite via PersistenceProvider
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ChainRunner, type DispatchFn } from './chain-runner.js';
+import type { ChainDef } from './chain-types.js';
+import type { PersistenceProvider } from '../persistence/types.js';
+
+// ---------------------------------------------------------------------------
+// Mock persistence provider (in-memory)
+// ---------------------------------------------------------------------------
+
+function createMockProvider(): PersistenceProvider {
+  const store = new Map<string, Record<string, unknown>>();
+
+  return {
+    backend: 'sqlite' as const,
+    execSql: vi.fn(),
+    run: vi.fn((sql: string, params?: unknown[]) => {
+      if (sql.includes('INSERT OR REPLACE') && Array.isArray(params)) {
+        store.set(params[0] as string, {
+          id: params[0],
+          chain_id: params[1],
+          chain_name: params[2],
+          status: params[3],
+          current_step: params[4],
+          paused_at_gate: params[5],
+          input: params[6],
+          context: params[7],
+          step_outputs: params[8],
+          steps_completed: params[9],
+          total_steps: params[10],
+          created_at: params[11],
+          updated_at: params[12],
+        });
+      }
+      return { changes: 1, lastInsertRowid: 1 };
+    }),
+    get: vi.fn((_sql: string, params?: unknown[]) => {
+      if (Array.isArray(params)) {
+        return store.get(params[0] as string) ?? undefined;
+      }
+      return undefined;
+    }),
+    all: vi.fn((_sql: string, _params?: unknown[]) => {
+      return [...store.values()];
+    }),
+    transaction: vi.fn((fn) => fn()),
+    ftsSearch: vi.fn(() => []),
+    ftsRebuild: vi.fn(),
+    close: vi.fn(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function twoStepChain(): ChainDef {
+  return {
+    id: 'test-chain',
+    name: 'Test Chain',
+    steps: [
+      { id: 'step-1', op: 'vault_search', params: { query: 'test' }, output: 'search' },
+      { id: 'step-2', op: 'brain_recommend', params: { context: '$search' } },
+    ],
+  };
+}
+
+function gatedChain(gate: 'user-approval' | 'auto-test'): ChainDef {
+  return {
+    id: 'gated-chain',
+    steps: [
+      { id: 'step-1', op: 'op-a', gate },
+      { id: 'step-2', op: 'op-b' },
+    ],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('ChainRunner', () => {
+  let provider: PersistenceProvider;
+  let runner: ChainRunner;
+
+  beforeEach(() => {
+    provider = createMockProvider();
+    runner = new ChainRunner(provider);
+  });
+
+  it('initializes the chain_instances table on construction', () => {
+    expect(provider.execSql).toHaveBeenCalledWith(
+      expect.stringContaining('CREATE TABLE IF NOT EXISTS chain_instances'),
+    );
+  });
+
+  describe('execute', () => {
+    it('runs all steps to completion', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({ result: 'ok' }));
+      const instance = await runner.execute(twoStepChain(), { q: 'hello' }, dispatch);
+
+      expect(instance.status).toBe('completed');
+      expect(instance.stepsCompleted).toBe(2);
+      expect(instance.totalSteps).toBe(2);
+      expect(instance.stepOutputs).toHaveLength(2);
+    });
+
+    it('stores step results in context for $variable resolution', async () => {
+      const dispatch: DispatchFn = vi.fn(async (op) => {
+        if (op === 'vault_search') return { items: ['a', 'b'] };
+        return { recommendation: 'use-a' };
+      });
+
+      const instance = await runner.execute(twoStepChain(), {}, dispatch);
+
+      expect(instance.context['step-1']).toEqual({ items: ['a', 'b'] });
+      expect(instance.context['search']).toEqual({ items: ['a', 'b'] });
+    });
+
+    it('passes resolved $variable params to subsequent steps', async () => {
+      const dispatch: DispatchFn = vi.fn(async (op) => {
+        if (op === 'vault_search') return { found: true };
+        return {};
+      });
+
+      await runner.execute(twoStepChain(), {}, dispatch);
+
+      // Second call should have resolved $search to the first step's result
+      expect(dispatch).toHaveBeenCalledTimes(2);
+      const secondCallParams = (dispatch as ReturnType<typeof vi.fn>).mock.calls[1][1];
+      expect(secondCallParams.context).toEqual({ found: true });
+    });
+
+    it('marks instance as failed when a step throws', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => {
+        throw new Error('kaboom');
+      });
+
+      const instance = await runner.execute(twoStepChain(), {}, dispatch);
+
+      expect(instance.status).toBe('failed');
+      expect(instance.stepsCompleted).toBe(0);
+      expect(instance.stepOutputs[0].status).toBe('failed');
+    });
+
+    it('starts from a specific step when startFromStep is provided', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({ ok: true }));
+      const instance = await runner.execute(twoStepChain(), {}, dispatch, undefined, 'step-2');
+
+      expect(dispatch).toHaveBeenCalledTimes(1);
+      expect(instance.stepsCompleted).toBe(1);
+    });
+
+    it('assigns input to context.input', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({}));
+      const input = { url: 'https://example.com' };
+      const instance = await runner.execute(twoStepChain(), input, dispatch);
+
+      expect(instance.context['input']).toEqual(input);
+    });
+  });
+
+  describe('gates', () => {
+    it('pauses on user-approval gate', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({ done: true }));
+      const instance = await runner.execute(gatedChain('user-approval'), {}, dispatch);
+
+      expect(instance.status).toBe('paused');
+      expect(instance.pausedAtGate).toBe('step-1');
+      expect(instance.stepsCompleted).toBe(1);
+      // step-2 should NOT have been called
+      expect(dispatch).toHaveBeenCalledTimes(1);
+    });
+
+    it('fails on auto-test gate when step returns error', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({ error: 'bad data' }));
+      const instance = await runner.execute(gatedChain('auto-test'), {}, dispatch);
+
+      expect(instance.status).toBe('failed');
+      expect(dispatch).toHaveBeenCalledTimes(1);
+    });
+
+    it('passes auto-test gate when step returns clean result', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({ data: 'clean' }));
+      const instance = await runner.execute(gatedChain('auto-test'), {}, dispatch);
+
+      expect(instance.status).toBe('completed');
+      expect(instance.stepsCompleted).toBe(2);
+    });
+
+    it('uses custom gateCheck for vault-check gate', async () => {
+      const chain: ChainDef = {
+        id: 'vault-gated',
+        steps: [
+          { id: 's1', op: 'op-a', gate: 'vault-check' },
+          { id: 's2', op: 'op-b' },
+        ],
+      };
+      const dispatch: DispatchFn = vi.fn(async () => ({ ok: true }));
+      const gateCheck = vi.fn(async () => ({ passed: false, message: 'vault says no' }));
+
+      const instance = await runner.execute(chain, {}, dispatch, gateCheck);
+
+      expect(instance.status).toBe('failed');
+      expect(gateCheck).toHaveBeenCalledWith('vault-check', 's1', { ok: true });
+    });
+  });
+
+  describe('resume / approve', () => {
+    it('resumes a paused chain from the next step', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({ ok: true }));
+      const chain = gatedChain('user-approval');
+      const paused = await runner.execute(chain, {}, dispatch);
+
+      expect(paused.status).toBe('paused');
+
+      const resumed = await runner.approve(paused.id, chain, dispatch);
+
+      expect(resumed.status).toBe('completed');
+      expect(resumed.stepsCompleted).toBe(2);
+    });
+
+    it('throws when resuming a non-existent instance', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({}));
+      await expect(runner.resume('nope', twoStepChain(), dispatch)).rejects.toThrow(
+        'Chain instance not found',
+      );
+    });
+
+    it('throws when resuming a completed (non-paused) chain', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({}));
+      const instance = await runner.execute(twoStepChain(), {}, dispatch);
+
+      await expect(runner.resume(instance.id, twoStepChain(), dispatch)).rejects.toThrow(
+        'not paused',
+      );
+    });
+  });
+
+  describe('getInstance / list', () => {
+    it('returns null for unknown instance', () => {
+      expect(runner.getInstance('unknown-id')).toBeNull();
+    });
+
+    it('retrieves a persisted instance by ID', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({}));
+      const instance = await runner.execute(twoStepChain(), {}, dispatch);
+
+      const retrieved = runner.getInstance(instance.id);
+      expect(retrieved).not.toBeNull();
+      expect(retrieved!.chainId).toBe('test-chain');
+    });
+
+    it('lists instances ordered by updated_at', async () => {
+      const dispatch: DispatchFn = vi.fn(async () => ({}));
+      await runner.execute(twoStepChain(), {}, dispatch);
+      await runner.execute(twoStepChain(), {}, dispatch);
+
+      const list = runner.list();
+      expect(list.length).toBe(2);
+    });
+  });
+});