@animalabs/connectome-host 0.7.3 → 0.8.0

package/test/recipe-hybrid-prose-routing.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'bun:test';
+import { validateRecipe } from '../src/recipe.js';
+const base = (proseRouting?: unknown) => ({ name: 'test', agent: { systemPrompt: '', ...(proseRouting === undefined ? {} : { proseRouting }) } });
+describe('prose routing recipe', () => {
+  it('accepts locus, explicit, hybrid, disabled, and omission', () => {
+    expect(validateRecipe(base()).agent.proseRouting).toBeUndefined();
+    for (const mode of ['locus', 'explicit', 'hybrid', 'disabled'] as const) expect(validateRecipe(base(mode)).agent.proseRouting).toBe(mode);
+  });
+  it('rejects unknown modes', () => {
+    expect(() => validateRecipe(base('triple-magic'))).toThrow(/proseRouting/);
+  });
+});

package/test/recipe-instructions.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, test } from 'bun:test';
+import { validateRecipe } from '../src/recipe.js';
+
+function recipe(modules?: Record<string, unknown>) {
+  return {
+    name: 'instructions-test',
+    agent: { systemPrompt: 'test' },
+    ...(modules === undefined ? {} : { modules }),
+  };
+}
+
+/** A workspace declaration that satisfies the instructions cross-check for
+ *  the given mount name: read-write + autoMaterialize (the validated shape
+ *  for a mount agents curate). */
+function wsFor(mountName: string) {
+  return {
+    mounts: [
+      { name: mountName, path: `./${mountName}`, mode: 'read-write', autoMaterialize: true },
+    ],
+  };
+}
+
+describe('recipe modules.instructions validation', () => {
+  test('allows the field to be omitted', () => {
+    expect(validateRecipe(recipe()).modules?.instructions).toBeUndefined();
+  });
+
+  test('accepts boolean shorthand', () => {
+    expect(validateRecipe(recipe({ instructions: true, workspace: wsFor('instructions') }))
+      .modules?.instructions).toBe(true);
+    expect(validateRecipe(recipe({ instructions: false })).modules?.instructions).toBe(false);
+  });
+
+  test('accepts a full object config', () => {
+    const parsed = validateRecipe(recipe({
+      workspace: wsFor('shared'),
+      instructions: {
+        path: 'shared/HOUSE-RULES.md',
+        header: '## House rules',
+        maxBytes: 4096,
+        position: 'afterUser',
+      },
+    }));
+    expect(parsed.modules?.instructions).toEqual({
+      path: 'shared/HOUSE-RULES.md',
+      header: '## House rules',
+      maxBytes: 4096,
+      position: 'afterUser',
+    });
+  });
+
+  test('accepts an empty object (all defaults)', () => {
+    expect(validateRecipe(recipe({ instructions: {}, workspace: wsFor('instructions') }))
+      .modules?.instructions).toEqual({});
+  });
+
+  test('rejects non-boolean, non-object values', () => {
+    expect(() => validateRecipe(recipe({ instructions: 'yes' }))).toThrow(/boolean or object/);
+    expect(() => validateRecipe(recipe({ instructions: ['x'] }))).toThrow(/boolean or object/);
+  });
+
+  test('rejects unknown fields', () => {
+    expect(() => validateRecipe(recipe({ instructions: { file: 'AGENTS.md' } })))
+      .toThrow(/unknown field "file"/);
+  });
+
+  test('rejects a path without a "<mountName>/<relativePath>" shape', () => {
+    expect(() => validateRecipe(recipe({ instructions: { path: 'AGENTS.md' } })))
+      .toThrow(/<mountName>\/<relativePath>/);
+    expect(() => validateRecipe(recipe({ instructions: { path: '/etc/passwd' } })))
+      .toThrow(/<mountName>\/<relativePath>/);
+    expect(() => validateRecipe(recipe({ instructions: { path: 'mount/' } })))
+      .toThrow(/<mountName>\/<relativePath>/);
+    expect(() => validateRecipe(recipe({ instructions: { path: '' } })))
+      .toThrow(/non-empty string/);
+  });
+
+  test('rejects invalid maxBytes', () => {
+    expect(() => validateRecipe(recipe({ instructions: { maxBytes: 0 } })))
+      .toThrow(/positive integer/);
+    expect(() => validateRecipe(recipe({ instructions: { maxBytes: 1.5 } })))
+      .toThrow(/positive integer/);
+    expect(() => validateRecipe(recipe({ instructions: { maxBytes: '32768' } })))
+      .toThrow(/positive integer/);
+  });
+
+  test('rejects invalid position', () => {
+    expect(() => validateRecipe(recipe({ instructions: { position: 'prepend' } })))
+      .toThrow(/'system', 'beforeUser', or 'afterUser'/);
+  });
+
+  test('rejects non-string header', () => {
+    expect(() => validateRecipe(recipe({ instructions: { header: 42 } })))
+      .toThrow(/header must be a string/);
+  });
+
+  test('rejects instructions when workspace is disabled', () => {
+    expect(() => validateRecipe(recipe({ instructions: true, workspace: false })))
+      .toThrow(/requires modules\.workspace/);
+    expect(() => validateRecipe(recipe({ instructions: {}, workspace: false })))
+      .toThrow(/requires modules\.workspace/);
+  });
+
+  test('accepts a properly declared instructions mount (rw + autoMaterialize)', () => {
+    expect(() => validateRecipe(recipe({
+      instructions: true,
+      workspace: wsFor('instructions'),
+    }))).not.toThrow();
+  });
+
+  test('cross-checks the path mount against explicitly declared workspace mounts', () => {
+    const mounts = [
+      { name: 'input', path: './input', mode: 'read-only' },
+      { name: 'products', path: './output', mode: 'read-write' },
+    ];
+    // Default path 'instructions/AGENTS.md' names a mount that isn't declared.
+    expect(() => validateRecipe(recipe({ instructions: true, workspace: { mounts } })))
+      .toThrow(/requires a workspace mount named\s+"instructions"/);
+    // Same for an explicit path with a typo'd mount name.
+    expect(() => validateRecipe(recipe({
+      instructions: { path: 'shared/AGENTS.md' },
+      workspace: { mounts },
+    }))).toThrow(/names workspace mount "shared"/);
+    // A read-only declared mount passes without autoMaterialize (disk is its
+    // only write path).
+    expect(() => validateRecipe(recipe({
+      instructions: { path: 'input/AGENTS.md' },
+      workspace: { mounts },
+    }))).not.toThrow();
+    // The '_config' mount exists under configMount but is rejected for
+    // instructions: it does not auto-materialize (agent edits reach disk only
+    // after branch-changing commands), so the injection would serve stale
+    // content — the same split-brain the autoMaterialize check prevents.
+    expect(() => validateRecipe(recipe({
+      instructions: { path: '_config/AGENTS.md' },
+      workspace: { mounts, configMount: true },
+    }))).toThrow(/host-managed "_config"/);
+  });
+
+  test('rejects a read-write instructions mount without autoMaterialize (split-brain guard)', () => {
+    // Workspace writes are Chronicle-first; the injection reads disk. A rw
+    // mount that never materializes would silently freeze the injection at
+    // the pre-curation content.
+    expect(() => validateRecipe(recipe({
+      instructions: { path: 'products/AGENTS.md' },
+      workspace: { mounts: [{ name: 'products', path: './output', mode: 'read-write' }] },
+    }))).toThrow(/autoMaterialize/);
+    // Mode defaults to read-write, so an unmoded mount needs it too.
+    expect(() => validateRecipe(recipe({
+      instructions: true,
+      workspace: { mounts: [{ name: 'instructions', path: './instructions' }] },
+    }))).toThrow(/autoMaterialize/);
+  });
+
+  test('cross-checks against the implicit default workspace too', () => {
+    // `instructions: true` with the implicit workspace (mounts input +
+    // products) can never inject — the default path's mount cannot exist.
+    // That used to validate and be dead config; now it fails at load.
+    expect(() => validateRecipe(recipe({ instructions: true })))
+      .toThrow(/implicit default\s+mounts/);
+    expect(() => validateRecipe(recipe({ instructions: true, workspace: true })))
+      .toThrow(/implicit default\s+mounts/);
+    // The implicit read-only 'input' mount is a valid target (file maintained
+    // outside the agent).
+    expect(() => validateRecipe(recipe({ instructions: { path: 'input/AGENTS.md' } })))
+      .not.toThrow();
+    // The implicit 'products' mount is rw without autoMaterialize — and the
+    // implicit workspace cannot set it, so this directs to explicit mounts.
+    expect(() => validateRecipe(recipe({ instructions: { path: 'products/AGENTS.md' } })))
+      .toThrow(/implicit default workspace cannot/);
+  });
+
+  test('allows instructions: false alongside workspace: false', () => {
+    expect(() => validateRecipe(recipe({ instructions: false, workspace: false }))).not.toThrow();
+  });
+});

package/test/recipe-kv-unified.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from 'bun:test';
+import { buildFrameworkStrategy } from '../src/framework-strategy.js';
+import { validateRecipe, type RecipeKvUnifiedConfig } from '../src/recipe.js';
+
+function config(): RecipeKvUnifiedConfig {
+  return {
+    policy: {
+      alpha: 0.7,
+      budgetLowRatio: 0.7,
+      budgetHighRatio: 0.935,
+      budgetUnderLambda: 1_000,
+      budgetOverLambda: 4_000,
+      cacheLambda: 1,
+      cacheScale: 100_000,
+      cacheReadPrice: 0.1,
+      cacheWritePrice: 1.25,
+      continuityLambda: 1,
+      continuityScale: 100_000,
+      continuityRecencyHalfLifeTokens: 100_000,
+      continuityRecencyFloor: 0.2,
+      continuityStableHalfLife: 16,
+      continuityStableFloor: 0.25,
+    },
+    tokenBucketSize: 10_000,
+    continuityBucketSize: 50_000,
+    fidelityBucketSize: 100_000,
+    labelCeiling: 100_000,
+    adoptEpsilon: 2_000,
+    treeifyNonContiguousSummaries: false,
+  };
+}
+
+function recipe(kvUnified: unknown = config()) {
+  return {
+    name: 'kv-unified-test',
+    agent: {
+      name: 'fable',
+      systemPrompt: 'system',
+      strategy: {
+        type: 'autobiographical',
+        foldingStrategy: 'kv-unified',
+        kvUnified,
+      },
+    },
+  };
+}
+
+describe('kv-unified recipe plumbing', () => {
+  test('forwards the complete fail-closed policy unchanged', () => {
+    const validated = validateRecipe(recipe());
+    const strategy = buildFrameworkStrategy(validated, 'model', 'UTC') as unknown as {
+      config: { foldingStrategy?: string; kvUnified?: RecipeKvUnifiedConfig };
+    };
+    expect(strategy.config.foldingStrategy).toBe('kv-unified');
+    expect(strategy.config.kvUnified).toEqual(config());
+  });
+
+  test('rejects selecting kv-unified without a complete policy', () => {
+    const missing = recipe() as ReturnType<typeof recipe>;
+    delete (missing.agent.strategy as { kvUnified?: unknown }).kvUnified;
+    expect(() => validateRecipe(missing)).toThrow(/complete.*kvUnified/i);
+    const incomplete = config() as unknown as Record<string, unknown>;
+    incomplete.policy = { ...(incomplete.policy as object) };
+    delete (incomplete.policy as Record<string, unknown>).cacheLambda;
+    expect(() => validateRecipe(recipe(incomplete))).toThrow(/cacheLambda/);
+  });
+
+  test('rejects invalid bands, grids, and implicit treeification', () => {
+    const badBand = config();
+    badBand.policy.budgetLowRatio = 0.95;
+    expect(() => validateRecipe(recipe(badBand))).toThrow(/budget ratios/);
+
+    const badGrid = config();
+    badGrid.tokenBucketSize = 0;
+    expect(() => validateRecipe(recipe(badGrid))).toThrow(/tokenBucketSize/);
+
+    const missingTreeification = config() as unknown as Record<string, unknown>;
+    delete missingTreeification.treeifyNonContiguousSummaries;
+    expect(() => validateRecipe(recipe(missingTreeification))).toThrow(/explicit boolean/);
+  });
+
+  test('rejects a kvUnified object when another solver is selected', () => {
+    const raw = recipe() as ReturnType<typeof recipe>;
+    raw.agent.strategy.foldingStrategy = 'kv-stable';
+    expect(() => validateRecipe(raw)).toThrow(/requires foldingStrategy/);
+  });
+});

package/test/recipe-mcp-source.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Tests for mcpServers.<id>.source validation: both of connectome-cook's
+ * source grammars (git `url` form and registry `npm` form) must pass — the
+ * shipped knowledge-miner recipe uses `source.npm` for its gitlab server,
+ * and a validator that only accepts `url` makes that recipe unloadable.
+ */
+import { describe, test, expect } from 'bun:test';
+import { validateRecipe } from '../src/recipe.js';
+
+function recipeWithSource(source: unknown) {
+  return {
+    name: 'source-test',
+    agent: { systemPrompt: 'sys' },
+    mcpServers: {
+      srv: {
+        command: 'npx',
+        args: ['-y', 'some-pkg'],
+        ...(source !== undefined ? { source } : {}),
+      },
+    },
+  };
+}
+
+describe('mcpServers source validation', () => {
+  test('accepts the git url form', () => {
+    expect(() => validateRecipe(recipeWithSource({
+      url: 'https://github.com/x/y.git',
+      install: 'npm',
+    }))).not.toThrow();
+  });
+
+  test('accepts the npm registry form', () => {
+    expect(() => validateRecipe(recipeWithSource({
+      npm: '@zereight/mcp-gitlab@2.1.25',
+    }))).not.toThrow();
+  });
+
+  test('rejects a source with neither url nor npm', () => {
+    expect(() => validateRecipe(recipeWithSource({ install: 'npm' })))
+      .toThrow(/source must have a non-empty "url" \(git clone\) or "npm"/);
+  });
+
+  test('rejects a source with both url and npm', () => {
+    expect(() => validateRecipe(recipeWithSource({
+      url: 'https://github.com/x/y.git',
+      npm: 'y@1.0.0',
+    }))).toThrow(/must not set both "url" and "npm"/);
+  });
+
+  test('rejects empty-string url and npm', () => {
+    expect(() => validateRecipe(recipeWithSource({ url: '' }))).toThrow(/source/);
+    expect(() => validateRecipe(recipeWithSource({ npm: '' }))).toThrow(/source/);
+  });
+});

package/test/recipe-openai-compatible.test.ts

@@ -0,0 +1,54 @@
+/**
+ * `agent.provider: 'openai-compatible'` — membrane has shipped a generic
+ * OpenAI chat-completions adapter (Ollama, vLLM, Together, Groq, local
+ * servers...) that no host wired. The recipe must name the endpoint and the
+ * model, and both must be checked at load time: a missing baseUrl would
+ * otherwise surface as a fetch to `undefined/chat/completions` at first
+ * inference, and a missing model as whatever the endpoint's default happens
+ * to be.
+ */
+import { describe, expect, test } from 'bun:test';
+import { validateRecipe } from '../src/recipe.js';
+
+function recipe(agent: Record<string, unknown>) {
+  return { name: 'compat-test', agent: { systemPrompt: 'sys', ...agent } };
+}
+
+describe('recipe agent.provider openai-compatible', () => {
+  test('accepts an http local endpoint with a model', () => {
+    const r = validateRecipe(recipe({ provider: 'openai-compatible', baseUrl: 'http://localhost:11434/v1', model: 'qwen3:32b' }));
+    expect(r.agent.provider).toBe('openai-compatible');
+    expect(r.agent.baseUrl).toBe('http://localhost:11434/v1');
+    expect(r.agent.model).toBe('qwen3:32b');
+  });
+
+  test('accepts an https gateway', () => {
+    const r = validateRecipe(recipe({ provider: 'openai-compatible', baseUrl: 'https://nano-gpt.com/api/v1', model: 'xiaomi/mimo-v2.5-pro:thinking' }));
+    expect(r.agent.baseUrl).toBe('https://nano-gpt.com/api/v1');
+  });
+
+  test('requires baseUrl', () => {
+    expect(() => validateRecipe(recipe({ provider: 'openai-compatible', model: 'm' }))).toThrow(/agent\.baseUrl is required/);
+    expect(() => validateRecipe(recipe({ provider: 'openai-compatible', baseUrl: '   ', model: 'm' }))).toThrow(/agent\.baseUrl is required/);
+  });
+
+  test('requires an absolute http(s) URL', () => {
+    expect(() => validateRecipe(recipe({ provider: 'openai-compatible', baseUrl: 'localhost:11434/v1', model: 'm' }))).toThrow(/absolute http\(s\) URL|http or https/);
+    expect(() => validateRecipe(recipe({ provider: 'openai-compatible', baseUrl: 'ftp://host/v1', model: 'm' }))).toThrow(/http or https/);
+  });
+
+  test('requires an explicit model (no default for an arbitrary endpoint)', () => {
+    expect(() => validateRecipe(recipe({ provider: 'openai-compatible', baseUrl: 'http://localhost:11434/v1' }))).toThrow(/agent\.model is required/);
+  });
+
+  test('rejects baseUrl with any other provider', () => {
+    expect(() => validateRecipe(recipe({ provider: 'anthropic', baseUrl: 'http://x/v1' }))).toThrow(/only applies to agent\.provider 'openai-compatible'/);
+    expect(() => validateRecipe(recipe({ baseUrl: 'http://x/v1' }))).toThrow(/got provider "anthropic"/);
+    expect(() => validateRecipe(recipe({ provider: 'openai-codex', baseUrl: 'http://x/v1' }))).toThrow(/got provider "openai-codex"/);
+  });
+
+  test('other providers are untouched', () => {
+    expect(validateRecipe(recipe({ provider: 'openai-codex', model: 'gpt-5.4' })).agent.baseUrl).toBeUndefined();
+    expect(validateRecipe(recipe({})).agent.provider ?? 'anthropic').toBe('anthropic');
+  });
+});

package/test/recipe-path-resolution.test.ts

@@ -8,7 +8,7 @@
 import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
 import { mkdtempSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadRecipe, resolveRecipeRelative, type Recipe } from '../src/recipe.js';
 
@@ -48,15 +48,26 @@ describe('resolveRecipeRelative', () => {
   });
 
   test('bare filename resolves against parent dir', () => {
-    expect(resolveRecipeRelative('child.json', { kind: 'file', dir: '/opt/recipes' }))
-      .toBe('/opt/recipes/child.json');
+    const dir = resolve('/opt/recipes');
+    const out = resolveRecipeRelative('child.json', { kind: 'file', dir });
+
+    expect(isAbsolute(out)).toBe(true);
+    expect(dirname(out)).toBe(dir);
+    expect(basename(out)).toBe('child.json');
   });
 
   test('dotted prefix resolves against parent dir', () => {
-    expect(resolveRecipeRelative('./child.json', { kind: 'file', dir: '/opt/recipes' }))
-      .toBe('/opt/recipes/child.json');
-    expect(resolveRecipeRelative('../other/child.json', { kind: 'file', dir: '/opt/recipes' }))
-      .toBe('/opt/other/child.json');
+    const dir = resolve('/opt/recipes');
+
+    const here = resolveRecipeRelative('./child.json', { kind: 'file', dir });
+    expect(dirname(here)).toBe(dir);
+    expect(basename(here)).toBe('child.json');
+
+    // `..` must climb out of `dir` and land in a sibling directory.
+    const up = resolveRecipeRelative('../other/child.json', { kind: 'file', dir });
+    expect(basename(up)).toBe('child.json');
+    expect(basename(dirname(up))).toBe('other');
+    expect(dirname(dirname(up))).toBe(dirname(dir));
   });
 
   test('URL base resolves relative child to sibling URL', () => {
@@ -97,7 +108,7 @@ describe('loadRecipe — children[].recipe resolution', () => {
 
     const originalCwd = process.cwd();
     try {
-      process.chdir('/tmp');
+      process.chdir(tmpdir());
       const a = await loadRecipe(parentPath);
       process.chdir(tmpDir);
       const b = await loadRecipe(parentPath);

package/test/recipe-provider.test.ts

@@ -14,6 +14,20 @@ describe('recipe provider validation', () => {
       .toBe('openai-codex');
   });
 
+  test('accepts the mock provider and its settings', () => {
+    expect(validateRecipe(recipe({ provider: 'mock' })).agent.provider).toBe('mock');
+    expect(validateRecipe(recipe({
+      provider: 'mock',
+      mock: { echoMode: false, defaultResponse: 'canned' },
+    })).agent.mock).toEqual({ echoMode: false, defaultResponse: 'canned' });
+  });
+
+  test('rejects malformed mock settings', () => {
+    expect(() => validateRecipe(recipe({ mock: 'echo' }))).toThrow(/agent.mock/);
+    expect(() => validateRecipe(recipe({ mock: { echoMode: 'yes' } }))).toThrow(/echoMode/);
+    expect(() => validateRecipe(recipe({ mock: { defaultResponse: '' } }))).toThrow(/defaultResponse/);
+  });
+
   test('accepts Codex subscription settings', () => {
     expect(validateRecipe(recipe({
       provider: 'openai-codex',