@animalabs/connectome-host 0.7.4 → 0.8.0

package/test/mcpl-child-env.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Host composition of stdio MCPL child env (composeMcplChildEnv): the
+ * framework's refusal-annotation baseline is injected for never-configured
+ * deployments, and an operator's explicit value always supersedes it — the
+ * host provides a default, never overrides a decision. The enforced
+ * precedence below this (file key incl. [] → legacy operator env → baseline)
+ * lives in the Discord adapter; what the host owns is that the injected
+ * value is EXACTLY the set the framework stamps (REFUSAL_REACTION_BASELINE,
+ * comma-joined) and that it rides in env — process plumbing below the model
+ * line, never agent-visible text.
+ */
+import { describe, test, expect } from 'bun:test';
+import { REFUSAL_REACTION_BASELINE } from '@animalabs/agent-framework';
+import { composeMcplChildEnv } from '../src/mcpl-config.js';
+
+const BASELINE = REFUSAL_REACTION_BASELINE.join(',');
+
+describe('composeMcplChildEnv', () => {
+  test('injects the framework baseline when the server entry does not set it', () => {
+    const env = composeMcplChildEnv({ SOME_VAR: 'x' }, 'UTC');
+    expect(env.DISCORD_SUPPRESSED_REACTIONS_BASELINE).toBe(BASELINE);
+    expect(env.SOME_VAR).toBe('x');
+  });
+
+  test('injected value round-trips to the exact framework annotation set', () => {
+    const env = composeMcplChildEnv(undefined, 'UTC');
+    expect(env.DISCORD_SUPPRESSED_REACTIONS_BASELINE!.split(',')).toEqual([
+      ...REFUSAL_REACTION_BASELINE,
+    ]);
+    expect(REFUSAL_REACTION_BASELINE.length).toBeGreaterThan(0);
+  });
+
+  test('operator-set baseline on the server entry supersedes the house value', () => {
+    const env = composeMcplChildEnv(
+      { DISCORD_SUPPRESSED_REACTIONS_BASELINE: '🈲' },
+      'UTC',
+    );
+    expect(env.DISCORD_SUPPRESSED_REACTIONS_BASELINE).toBe('🈲');
+  });
+
+  test('operator empty-string baseline is preserved, not re-defaulted', () => {
+    // An operator who explicitly set the var to empty chose "no baseline";
+    // the house value must not reappear underneath that decision.
+    const env = composeMcplChildEnv(
+      { DISCORD_SUPPRESSED_REACTIONS_BASELINE: '' },
+      'UTC',
+    );
+    expect(env.DISCORD_SUPPRESSED_REACTIONS_BASELINE).toBe('');
+  });
+
+  test('AGENT_TIMEZONE stays host-resolved (recipe wall clock, not a per-server knob)', () => {
+    const env = composeMcplChildEnv({ AGENT_TIMEZONE: 'Mars/Olympus' }, 'America/Los_Angeles');
+    expect(env.AGENT_TIMEZONE).toBe('America/Los_Angeles');
+  });
+
+  test('adds nothing beyond the two host-owned keys', () => {
+    const env = composeMcplChildEnv({ A: '1' }, 'UTC');
+    expect(Object.keys(env).sort()).toEqual([
+      'A',
+      'AGENT_TIMEZONE',
+      'DISCORD_SUPPRESSED_REACTIONS_BASELINE',
+    ]);
+  });
+});

package/test/nudge-command.test.ts

@@ -0,0 +1,47 @@
+/**
+ * /nudge — admin-level: run inference on the agent's CURRENT context without
+ * adding any message or event. Thin shim over framework.nudgeAgent(); these
+ * tests pin the argument pass-through and the operator-facing wording.
+ */
+import { describe, expect, test } from 'bun:test';
+import type { AgentFramework } from '@animalabs/agent-framework';
+import { handleCommand } from '../src/commands.js';
+
+function app(nudgeAgent: AgentFramework['nudgeAgent']): Parameters<typeof handleCommand>[1] {
+  return {
+    framework: { nudgeAgent } as AgentFramework,
+    sessionManager: {} as never,
+    recipe: { name: 'test' } as never,
+    branchState: {} as never,
+    switchSession: async () => {},
+  };
+}
+
+describe('/nudge', () => {
+  test('nudges the default agent and reports immediate run when idle', () => {
+    const calls: Array<[string | undefined, string | undefined]> = [];
+    const result = handleCommand('/nudge', app((name, by) => {
+      calls.push([name, by]);
+      return { ok: true, agentName: 'main', agentStatus: 'idle' };
+    }));
+    expect(calls).toEqual([[undefined, 'host-console']]);
+    expect(result.lines[0]?.text).toMatch(/Nudged main/);
+    expect(result.lines[0]?.text).toMatch(/no new events/);
+    expect(result.lines[0]?.text).toMatch(/running now/);
+  });
+
+  test('passes an explicit agent name and reports queueing when busy', () => {
+    const result = handleCommand('/nudge sidekick', app((name) => {
+      expect(name).toBe('sidekick');
+      return { ok: true, agentName: 'sidekick', agentStatus: 'streaming' };
+    }));
+    expect(result.lines[0]?.text).toMatch(/queued — runs when current turn settles \(agent is streaming\)/);
+  });
+
+  test('surfaces framework errors', () => {
+    const result = handleCommand('/nudge ghost', app(() => (
+      { ok: false, error: 'Unknown agent: ghost' }
+    )));
+    expect(result.lines[0]?.text).toBe('Nudge failed: Unknown agent: ghost');
+  });
+});

package/test/recipe-cache-keepalive.test.ts

@@ -0,0 +1,59 @@
+/**
+ * Tests for recipe.agent.cacheKeepalive validation.
+ *
+ * The load-bearing case is `refreshAfterMinutes >= the cache TTL`: such a
+ * keepalive always fires AFTER the entry has expired, so every poke pays a full
+ * 2x cache write instead of a 0.1x read — while still looking like a healthy
+ * successful call. That must fail at recipe-load time, not on a bill.
+ */
+import { describe, test, expect } from 'bun:test';
+import { validateRecipe } from '../src/recipe.js';
+
+function recipeWith(cacheKeepalive?: unknown, cacheTtl?: unknown) {
+  return {
+    name: 'keepalive-test',
+    agent: {
+      systemPrompt: 'sys',
+      ...(cacheTtl !== undefined && { cacheTtl }),
+      ...(cacheKeepalive !== undefined && { cacheKeepalive }),
+    },
+  };
+}
+
+describe('recipe agent.cacheKeepalive validation', () => {
+  test('omitting it is valid — keepalive is on by default', () => {
+    expect(validateRecipe(recipeWith()).agent.cacheKeepalive).toBeUndefined();
+  });
+
+  test('accepts an explicit opt-out', () => {
+    const r = validateRecipe(recipeWith({ enabled: false }));
+    expect(r.agent.cacheKeepalive?.enabled).toBe(false);
+  });
+
+  test('accepts sane tuning', () => {
+    const r = validateRecipe(recipeWith({ maxIdleHours: 12, refreshAfterMinutes: 50 }));
+    expect(r.agent.cacheKeepalive?.maxIdleHours).toBe(12);
+    expect(r.agent.cacheKeepalive?.refreshAfterMinutes).toBe(50);
+  });
+
+  test('rejects a refresh interval at or past the 1h TTL (every poke would be a cache WRITE)', () => {
+    expect(() => validateRecipe(recipeWith({ refreshAfterMinutes: 60 }, '1h'))).toThrow(/less than the 1h cache TTL/);
+    expect(() => validateRecipe(recipeWith({ refreshAfterMinutes: 90 }, '1h'))).toThrow(/less than the 1h cache TTL/);
+  });
+
+  test('rejects a refresh interval at or past the 5m TTL', () => {
+    expect(() => validateRecipe(recipeWith({ refreshAfterMinutes: 45 }, '5m'))).toThrow(/less than the 5m cache TTL/);
+    expect(validateRecipe(recipeWith({ refreshAfterMinutes: 4 }, '5m')).agent.cacheKeepalive?.refreshAfterMinutes).toBe(4);
+  });
+
+  test('rejects non-positive and non-numeric values', () => {
+    expect(() => validateRecipe(recipeWith({ refreshAfterMinutes: 0 }))).toThrow(/positive number/);
+    expect(() => validateRecipe(recipeWith({ refreshAfterMinutes: '45' }))).toThrow(/positive number/);
+    expect(() => validateRecipe(recipeWith({ maxIdleHours: -1 }))).toThrow(/positive number/);
+    expect(() => validateRecipe(recipeWith({ maxIdleHours: 'lots' }))).toThrow(/positive number/);
+  });
+
+  test('rejects a non-object', () => {
+    expect(() => validateRecipe(recipeWith('yes'))).toThrow(/must be an object/);
+  });
+});

package/test/recipe-compression-fallback.test.ts

@@ -13,9 +13,19 @@ describe('compression recall-curve recipe settings', () => {
     const parsed = validateRecipe(recipe({
       compressionRefusalCurveFallbacks: 3,
       compressionContextBudgetTokens: 200_000,
+      compressionRecallBudgetTokens: 40_000,
+      compressionSourceOnly: false,
+      compressionSourceOnlyFallback: true,
+      compressionMergeSourceOnly: false,
+      compressionMergeSourceOnlyFallback: true,
     }));
     expect(parsed.agent.strategy?.compressionRefusalCurveFallbacks).toBe(3);
     expect(parsed.agent.strategy?.compressionContextBudgetTokens).toBe(200_000);
+    expect(parsed.agent.strategy?.compressionRecallBudgetTokens).toBe(40_000);
+    expect(parsed.agent.strategy?.compressionSourceOnly).toBe(false);
+    expect(parsed.agent.strategy?.compressionSourceOnlyFallback).toBe(true);
+    expect(parsed.agent.strategy?.compressionMergeSourceOnly).toBe(false);
+    expect(parsed.agent.strategy?.compressionMergeSourceOnlyFallback).toBe(true);
   });
 
   test('accepts zero as an explicit fallback disable', () => {
@@ -32,5 +42,14 @@ describe('compression recall-curve recipe settings', () => {
       .toThrow(/compressionContextBudgetTokens/);
     expect(() => validateRecipe(recipe({ compressionContextBudgetTokens: '200000' })))
       .toThrow(/compressionContextBudgetTokens/);
+    expect(() => validateRecipe(recipe({ compressionRecallBudgetTokens: 0 })))
+      .toThrow(/compressionRecallBudgetTokens/);
+    expect(() => validateRecipe(recipe({ compressionRecallBudgetTokens: 1.5 })))
+      .toThrow(/compressionRecallBudgetTokens/);
+    expect(() => validateRecipe(recipe({ compressionRecallBudgetTokens: '40000' })))
+      .toThrow(/compressionRecallBudgetTokens/);
+    for (const key of ['compressionSourceOnly', 'compressionSourceOnlyFallback', 'compressionMergeSourceOnly', 'compressionMergeSourceOnlyFallback']) {
+      expect(() => validateRecipe(recipe({ [key]: 'yes' }))).toThrow(new RegExp(key));
+    }
   });
 });

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',