@animalabs/connectome-host 0.7.3 → 0.8.0

package/test/recipe-save-unresolved.test.ts

@@ -0,0 +1,244 @@
+/**
+ * Tests for unresolved recipe persistence: the `.recipe.json` snapshot in
+ * $DATA_DIR must never contain substituted secrets.
+ *
+ * Motivating finding (external recipe review against a production VM):
+ * loadRecipe substituted every `${VAR}` — including access tokens — into the
+ * recipe, and resolveRecipe then serialised the RESOLVED recipe to
+ * $DATA_DIR/.recipe.json, a directory deployments bind-mount and back up.
+ *
+ * Contract under test:
+ *   - loadRecipeDetailed returns the resolved recipe for the runtime AND a
+ *     `persistable` pre-substitution form; saveRecipe writes the latter, so
+ *     the on-disk snapshot keeps `${VAR}` literals, never the secret values.
+ *   - loadSavedRecipe re-runs substitution against the CURRENT environment
+ *     (secret rotation takes effect on restart), hard-failing when a
+ *     required var has gone missing.
+ *   - Legacy snapshots (saved fully resolved by older versions, no marker)
+ *     still load verbatim — including ones with a literal `${...}` in prose.
+ *   - The snapshot file is chmod'd 0600 even when overwriting a legacy file.
+ *   - A URL systemPrompt is persisted as the URL and re-fetched on resume.
+ */
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, statSync, chmodSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import {
+  loadRecipe,
+  loadRecipeDetailed,
+  saveRecipe,
+  loadSavedRecipe,
+  SAVED_RECIPE_UNRESOLVED_KEY,
+} from '../src/recipe.js';
+
+const SECRET = 'tok-glpat-supersecret-12345';
+
+describe('unresolved recipe persistence', () => {
+  const originalEnv = process.env;
+  const originalFetch = globalThis.fetch;
+  let tmpDir: string;
+  let dataDir: string;
+  let recipePath: string;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    tmpDir = mkdtempSync(join(tmpdir(), 'conhost-save-unresolved-'));
+    dataDir = join(tmpDir, 'data');
+    recipePath = join(tmpDir, 'recipe.json');
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    globalThis.fetch = originalFetch;
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* noop */ }
+  });
+
+  function writeSecretRecipe(): void {
+    writeFileSync(recipePath, JSON.stringify({
+      name: 'Secret Test',
+      agent: { systemPrompt: 'be helpful' },
+      mcpServers: {
+        gitlab: {
+          command: 'node',
+          env: { GITLAB_PERSONAL_ACCESS_TOKEN: '${CONHOST_TEST_SECRET}' },
+        },
+      },
+    }), 'utf-8');
+  }
+
+  test('resolved recipe carries the secret in memory; persistable keeps the ${VAR} literal', async () => {
+    process.env.CONHOST_TEST_SECRET = SECRET;
+    writeSecretRecipe();
+
+    const { recipe, persistable } = await loadRecipeDetailed(recipePath);
+    expect((recipe.mcpServers as any).gitlab.env.GITLAB_PERSONAL_ACCESS_TOKEN).toBe(SECRET);
+    expect((persistable.mcpServers as any).gitlab.env.GITLAB_PERSONAL_ACCESS_TOKEN)
+      .toBe('${CONHOST_TEST_SECRET}');
+  });
+
+  test('the saved .recipe.json never contains the substituted secret', async () => {
+    process.env.CONHOST_TEST_SECRET = SECRET;
+    writeSecretRecipe();
+
+    const { persistable } = await loadRecipeDetailed(recipePath);
+    saveRecipe(dataDir, persistable);
+
+    const onDisk = readFileSync(join(dataDir, '.recipe.json'), 'utf-8');
+    expect(onDisk).not.toContain(SECRET);
+    expect(onDisk).toContain('${CONHOST_TEST_SECRET}');
+    expect(JSON.parse(onDisk)[SAVED_RECIPE_UNRESOLVED_KEY]).toBe(true);
+  });
+
+  test('loadSavedRecipe re-resolves against the CURRENT environment (secret rotation)', async () => {
+    process.env.CONHOST_TEST_SECRET = SECRET;
+    writeSecretRecipe();
+    const { persistable } = await loadRecipeDetailed(recipePath);
+    saveRecipe(dataDir, persistable);
+
+    process.env.CONHOST_TEST_SECRET = 'tok-rotated-67890';
+    const resumed = await loadSavedRecipe(dataDir);
+    expect(resumed).not.toBeNull();
+    expect((resumed!.mcpServers as any).gitlab.env.GITLAB_PERSONAL_ACCESS_TOKEN)
+      .toBe('tok-rotated-67890');
+  });
+
+  test('loadSavedRecipe throws (not null) when a required var disappeared from the environment', async () => {
+    process.env.CONHOST_TEST_SECRET = SECRET;
+    writeSecretRecipe();
+    const { persistable } = await loadRecipeDetailed(recipePath);
+    saveRecipe(dataDir, persistable);
+
+    delete process.env.CONHOST_TEST_SECRET;
+    await expect(loadSavedRecipe(dataDir)).rejects.toThrow(/CONHOST_TEST_SECRET/);
+  });
+
+  test('saveRecipe writes the snapshot with mode 0600, and chmods a pre-existing looser file', async () => {
+    process.env.CONHOST_TEST_SECRET = SECRET;
+    writeSecretRecipe();
+    const { persistable } = await loadRecipeDetailed(recipePath);
+
+    saveRecipe(dataDir, persistable);
+    const path = join(dataDir, '.recipe.json');
+    expect(statSync(path).mode & 0o777).toBe(0o600);
+
+    // Legacy deployments have a world-readable resolved snapshot; an
+    // overwrite must tighten it even though writeFileSync's mode only
+    // applies at creation.
+    chmodSync(path, 0o644);
+    expect(statSync(path).mode & 0o777).toBe(0o644);
+    saveRecipe(dataDir, persistable);
+    expect(statSync(path).mode & 0o777).toBe(0o600);
+  });
+
+  test('round-trip with no ${} patterns is a faithful no-op resolution', async () => {
+    writeFileSync(recipePath, JSON.stringify({
+      name: 'Plain',
+      description: 'no env refs',
+      agent: { systemPrompt: 'hello', model: 'claude-opus-4-6' },
+    }), 'utf-8');
+    const { recipe, persistable } = await loadRecipeDetailed(recipePath);
+    saveRecipe(dataDir, persistable);
+    const resumed = await loadSavedRecipe(dataDir);
+    expect(resumed).not.toBeNull();
+    expect(resumed!.name).toBe('Plain');
+    expect(resumed!.agent.systemPrompt).toBe(recipe.agent.systemPrompt);
+    expect(resumed!.agent.model).toBe('claude-opus-4-6');
+  });
+
+  test('relative fleet child recipe paths are persisted absolute (resume has no source base)', async () => {
+    writeFileSync(recipePath, JSON.stringify({
+      name: 'Fleet Parent',
+      agent: { systemPrompt: 'parent' },
+      modules: {
+        fleet: { children: [{ name: 'child-a', recipe: 'child.json' }] },
+      },
+    }), 'utf-8');
+
+    const { recipe, persistable } = await loadRecipeDetailed(recipePath);
+    const expected = resolve(tmpDir, 'child.json');
+    expect((recipe.modules!.fleet as any).children[0].recipe).toBe(expected);
+    expect(((persistable.modules as any).fleet.children[0]).recipe).toBe(expected);
+
+    saveRecipe(dataDir, persistable);
+    const resumed = await loadSavedRecipe(dataDir);
+    expect((resumed!.modules!.fleet as any).children[0].recipe).toBe(expected);
+  });
+
+  describe('URL systemPrompt', () => {
+    test('persisted as the URL and re-fetched on resume, picking up prompt updates', async () => {
+      let fetchCount = 0;
+      globalThis.fetch = (async (input: any) => {
+        expect(String(input)).toBe('https://prompts.example/agent.txt');
+        fetchCount++;
+        return new Response(fetchCount === 1 ? 'FETCHED PROMPT v1' : 'FETCHED PROMPT v2');
+      }) as typeof fetch;
+
+      writeFileSync(recipePath, JSON.stringify({
+        name: 'URL Prompt',
+        agent: { systemPrompt: 'https://prompts.example/agent.txt' },
+      }), 'utf-8');
+
+      const { recipe, persistable } = await loadRecipeDetailed(recipePath);
+      expect(recipe.agent.systemPrompt).toBe('FETCHED PROMPT v1');
+      expect((persistable.agent as any).systemPrompt).toBe('https://prompts.example/agent.txt');
+
+      saveRecipe(dataDir, persistable);
+      const onDisk = readFileSync(join(dataDir, '.recipe.json'), 'utf-8');
+      expect(onDisk).not.toContain('FETCHED PROMPT');
+
+      const resumed = await loadSavedRecipe(dataDir);
+      expect(resumed!.agent.systemPrompt).toBe('FETCHED PROMPT v2');
+      expect(fetchCount).toBe(2);
+    });
+  });
+
+  describe('legacy resolved snapshots (no marker)', () => {
+    test('load verbatim with no substitution', async () => {
+      // Simulate an older host's save: fully resolved, no marker.
+      const legacy = {
+        name: 'Legacy',
+        agent: { systemPrompt: 'resolved prompt' },
+        mcpServers: { gitlab: { command: 'node', env: { TOKEN: SECRET } } },
+      };
+      mkdirSync(dataDir, { recursive: true });
+      writeFileSync(join(dataDir, '.recipe.json'), JSON.stringify(legacy, null, 2) + '\n', 'utf-8');
+
+      const resumed = await loadSavedRecipe(dataDir);
+      expect(resumed).not.toBeNull();
+      expect((resumed!.mcpServers as any).gitlab.env.TOKEN).toBe(SECRET);
+    });
+
+    test('a surviving literal ${...} in prose does not hard-fail the load', async () => {
+      delete process.env.DEFINITELY_NOT_SET_ANYWHERE;
+      const legacy = {
+        name: 'Legacy Prose',
+        agent: {
+          systemPrompt: 'To configure, set ${DEFINITELY_NOT_SET_ANYWHERE} in your .env file.',
+        },
+      };
+      mkdirSync(dataDir, { recursive: true });
+      writeFileSync(join(dataDir, '.recipe.json'), JSON.stringify(legacy) + '\n', 'utf-8');
+
+      const resumed = await loadSavedRecipe(dataDir);
+      expect(resumed).not.toBeNull();
+      expect(resumed!.agent.systemPrompt).toContain('${DEFINITELY_NOT_SET_ANYWHERE}');
+    });
+
+    test('corrupt JSON still returns null rather than throwing', async () => {
+      mkdirSync(dataDir, { recursive: true });
+      writeFileSync(join(dataDir, '.recipe.json'), '{not json', 'utf-8');
+      expect(await loadSavedRecipe(dataDir)).toBeNull();
+    });
+
+    test('missing snapshot returns null', async () => {
+      expect(await loadSavedRecipe(dataDir)).toBeNull();
+    });
+  });
+
+  test('loadRecipe wrapper still returns the resolved recipe', async () => {
+    process.env.CONHOST_TEST_SECRET = SECRET;
+    writeSecretRecipe();
+    const recipe = await loadRecipe(recipePath);
+    expect((recipe.mcpServers as any).gitlab.env.GITLAB_PERSONAL_ACCESS_TOKEN).toBe(SECRET);
+  });
+});

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

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test';
+import { validateRecipe } from '../src/recipe.js';
+import { buildFrameworkStrategy } from '../src/framework-strategy.js';
+
+function recipe(strategy: Record<string, unknown>) {
+  return {
+    name: 'source-only-test',
+    agent: { systemPrompt: 'sys', strategy: { type: 'autobiographical', ...strategy } },
+  };
+}
+
+describe('compressionSourceOnly recipe flag', () => {
+  test('preserves the flag through validation', () => {
+    expect(validateRecipe(recipe({ compressionSourceOnly: true }))
+      .agent.strategy?.compressionSourceOnly).toBe(true);
+    expect(validateRecipe(recipe({ compressionSourceOnly: false }))
+      .agent.strategy?.compressionSourceOnly).toBe(false);
+    // absent stays undefined — every other resident is unaffected
+    expect(validateRecipe(recipe({})).agent.strategy?.compressionSourceOnly).toBeUndefined();
+  });
+
+  test('rejects a non-boolean value', () => {
+    expect(() => validateRecipe(recipe({ compressionSourceOnly: 'yes' })))
+      .toThrow(/compressionSourceOnly/);
+    expect(() => validateRecipe(recipe({ compressionSourceOnly: 1 })))
+      .toThrow(/compressionSourceOnly/);
+  });
+
+  test('plumbs through PASSTHROUGH_KEYS into the built strategy config', () => {
+    const parsed = validateRecipe(recipe({ compressionSourceOnly: true, summaryParticipant: 'mythos' }));
+    const built = buildFrameworkStrategy(parsed, 'claude-fable-5', 'UTC');
+    // buildFrameworkStrategy copies PASSTHROUGH_KEYS onto the strategy options;
+    // the flag must reach the AutobiographicalStrategy config.
+    const cfg = (built as unknown as { config?: Record<string, unknown> }).config
+      ?? (built as unknown as Record<string, unknown>);
+    expect(cfg.compressionSourceOnly).toBe(true);
+  });
+});

package/test/release-changelog.test.ts

@@ -0,0 +1,202 @@
+// Black-box coverage of scripts/release-changelog.ts: each case runs the
+// real script in a throwaway directory, so assembly, validation, and the
+// deletion of consumed fragments are all exercised exactly as `npm version`
+// would run them.
+import { test } from "bun:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT = fileURLToPath(
+  new URL("../scripts/release-changelog.ts", import.meta.url),
+);
+
+const BASE_CHANGELOG = [
+  "# Changelog",
+  "",
+  "Intro that mentions ## Unreleased inline, which must not count as a heading.",
+  "",
+  "## Unreleased",
+  "",
+  "## 1.0.0 — 2026-01-01",
+  "",
+  "### Fixed",
+  "",
+  "- Old entry.",
+  "",
+].join("\n");
+
+interface Fixture {
+  version?: string;
+  changelog?: string;
+  fragments?: Record<string, string>;
+}
+
+function setup(f: Fixture): string {
+  const dir = mkdtempSync(join(tmpdir(), "release-changelog-"));
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({ name: "fixture", version: f.version ?? "1.1.0" }),
+  );
+  writeFileSync(join(dir, "CHANGELOG.md"), f.changelog ?? BASE_CHANGELOG);
+  mkdirSync(join(dir, "changelog.d"));
+  writeFileSync(join(dir, "changelog.d", "README.md"), "# Pending fragments\n");
+  for (const [name, body] of Object.entries(f.fragments ?? {})) {
+    const path = join(dir, "changelog.d", name);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, body);
+  }
+  return dir;
+}
+
+function run(dir: string): { status: number; stdout: string; stderr: string } {
+  try {
+    const stdout = execFileSync(process.execPath, [SCRIPT], {
+      cwd: dir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { status: 0, stdout, stderr: "" };
+  } catch (e) {
+    const err = e as { status: number; stdout?: string; stderr?: string };
+    return { status: err.status, stdout: err.stdout ?? "", stderr: err.stderr ?? "" };
+  }
+}
+
+function section(text: string, version: string): string {
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => l.startsWith(`## ${version} — `));
+  assert.notEqual(start, -1, `no '## ${version}' section in:\n${text}`);
+  const rest = lines.slice(start + 1);
+  const end = rest.findIndex((l) => l.startsWith("## "));
+  return rest.slice(0, end === -1 ? undefined : end).join("\n").trim();
+}
+
+const changelog = (dir: string) => readFileSync(join(dir, "CHANGELOG.md"), "utf8");
+const pending = (dir: string) => readdirSync(join(dir, "changelog.d")).sort();
+
+test("folds fragments into a versioned section in canonical order and deletes them", () => {
+  const dir = setup({
+    fragments: {
+      "z-later.fixed.md": "- Fixed thing.\n",
+      "a-first.added.md": "- Added thing,\n  continued on an indented line.\n",
+      "m.breaking.md": "- **Module authors:** breaking thing.\n",
+    },
+  });
+  const r = run(dir);
+  assert.equal(r.status, 0, r.stderr);
+  const text = changelog(dir);
+  assert.equal(
+    section(text, "1.1.0"),
+    [
+      "### Breaking",
+      "",
+      "- **Module authors:** breaking thing.",
+      "",
+      "### Added",
+      "",
+      "- Added thing,",
+      "  continued on an indented line.",
+      "",
+      "### Fixed",
+      "",
+      "- Fixed thing.",
+    ].join("\n"),
+  );
+  assert.match(text, /^## Unreleased\n\n## 1\.1\.0 — \d{4}-\d{2}-\d{2}\n/m, "fresh empty Unreleased above the cut");
+  assert.ok(text.startsWith("# Changelog\n\nIntro that mentions"), "file header preserved");
+  assert.equal(section(text, "1.0.0"), "### Fixed\n\n- Old entry.", "older section untouched");
+  assert.deepEqual(pending(dir), ["README.md"], "consumed fragments deleted, README kept");
+});
+
+test("merges fragments into directly-filed Unreleased entries, reordering subsections canonically", () => {
+  const dir = setup({
+    changelog: BASE_CHANGELOG.replace(
+      "## Unreleased\n",
+      "## Unreleased\n\n### Fixed\n\n- Manual fix.\n\n### Added\n\n- Manual add.\n",
+    ),
+    fragments: { "x.fixed.md": "- Fragment fix.\n" },
+  });
+  const r = run(dir);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(
+    section(changelog(dir), "1.1.0"),
+    "### Added\n\n- Manual add.\n\n### Fixed\n\n- Manual fix.\n\n- Fragment fix.",
+  );
+});
+
+test("breaking fragments join an audience-qualified Breaking heading", () => {
+  const dir = setup({
+    changelog: BASE_CHANGELOG.replace(
+      "## Unreleased\n",
+      "## Unreleased\n\n### Fixed\n\n- Manual fix.\n\n### Breaking (module authors only)\n\n- Manual break.\n",
+    ),
+    fragments: { "b.breaking.md": "- Fragment break.\n" },
+  });
+  const r = run(dir);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(
+    section(changelog(dir), "1.1.0"),
+    "### Breaking (module authors only)\n\n- Manual break.\n\n- Fragment break.\n\n### Fixed\n\n- Manual fix.",
+  );
+});
+
+test("accepts nested bullets and multi-line continuations", () => {
+  const dir = setup({
+    fragments: { "n.fixed.md": "- one\n  - nested\n  more text\n- two\n" },
+  });
+  const r = run(dir);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(section(changelog(dir), "1.1.0"), "### Fixed\n\n- one\n  - nested\n  more text\n- two");
+});
+
+test("accepts bullet content that merely resembles headings or rules", () => {
+  const body = "- **Module authors:** bold opener.\n- -1 is now the sentinel.\n- #123 is referenced inline.\n- ***emphasis*** then text.\n";
+  const dir = setup({ fragments: { "r.fixed.md": body } });
+  const r = run(dir);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(section(changelog(dir), "1.1.0"), `### Fixed\n\n${body.trim()}`);
+});
+
+const refusals: Array<[string, Fixture, RegExp]> = [
+  ["nothing to release", {}, /nothing to release as 1\.1\.0/],
+  ["duplicate version section", { version: "1.0.0", fragments: { "a.fixed.md": "- x\n" } }, /'## 1\.0\.0' section already exists/],
+  ["unrecognized category suffix", { fragments: { "oops.md": "- x\n" } }, /changelog\.d\/oops\.md: unrecognized file/],
+  ["stray non-markdown file", { fragments: { "notes.txt": "hi\n", "a.fixed.md": "- x\n" } }, /changelog\.d\/notes\.txt: unrecognized file/],
+  ["empty fragment", { fragments: { "e.fixed.md": "\n" } }, /changelog\.d\/e\.fixed\.md: empty fragment/],
+  ["fragment nested under a branch-name directory", { fragments: { "fix/foo.fixed.md": "- x\n", "a.fixed.md": "- y\n" } }, /changelog\.d\/fix: not a file/],
+  ["plain prose", { fragments: { "p.fixed.md": "prose only\n" } }, /offending line: 'prose only'/],
+  ["prose after a valid bullet", { fragments: { "p.fixed.md": "- ok\nrogue prose\n" } }, /offending line: 'rogue prose'/],
+  ["top-level heading after a bullet", { fragments: { "h.fixed.md": "- ok\n\n## 9.9.9 — fake\n" } }, /offending line: '## 9\.9\.9 — fake'/],
+  ["indented ATX heading", { fragments: { "h.fixed.md": "- ok\n  ## 8.8.8 — injected\n  - beneath\n" } }, /offending line: '  ## 8\.8\.8 — injected'/],
+  ["indented setext underline / rule", { fragments: { "s.fixed.md": "- ok\n  ---\n" } }, /offending line: '  ---'/],
+  ["spaced thematic break shaped like a bullet", { fragments: { "s.fixed.md": "- ok\n- - -\n" } }, /offending line: '- - -'/],
+  ["asterisk thematic break with spaces", { fragments: { "s.fixed.md": "- ok\n* * *\n" } }, /offending line: '\* \* \*'/],
+  ["rule as bullet content", { fragments: { "s.fixed.md": "- ---\n" } }, /offending line: '- ---'/],
+  ["heading as bullet content", { fragments: { "h.fixed.md": "- ## 9.9.9 — embedded heading\n" } }, /offending line: '- ## 9\.9\.9 — embedded heading'/],
+  ["heading as nested bullet content", { fragments: { "h.fixed.md": "- ok\n  - ### nested heading\n" } }, /offending line: '  - ### nested heading'/],
+  ["tab-indented continuation", { fragments: { "t.fixed.md": "- ok\n\tcontinued\n" } }, /offending line: '\tcontinued'/],
+  ["no Unreleased heading", { changelog: "# Changelog\n\n## 1.0.0 — 2026-01-01\n\n- x\n", fragments: { "a.fixed.md": "- x\n" } }, /no '## Unreleased' section/],
+  ["two Unreleased headings", { changelog: BASE_CHANGELOG + "\n## Unreleased\n\n- stranded\n", fragments: { "a.fixed.md": "- x\n" } }, /2 '## Unreleased' headings/],
+];
+
+for (const [name, fixture, message] of refusals) {
+  test(`refuses ${name} without touching anything`, () => {
+    const dir = setup(fixture);
+    const before = { changelog: changelog(dir), pending: pending(dir) };
+    const r = run(dir);
+    assert.equal(r.status, 1, `expected refusal, got exit ${r.status}:\n${r.stdout}${r.stderr}`);
+    assert.match(r.stderr, message);
+    assert.equal(changelog(dir), before.changelog, "CHANGELOG.md must be untouched");
+    assert.deepEqual(pending(dir), before.pending, "no fragment may be deleted on refusal");
+  });
+}

package/test/retrieval-auth-loopback.test.ts

@@ -0,0 +1,49 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { ModuleContext } from '@animalabs/agent-framework';
+import {
+  WebUiModule,
+  __getSharedServerPortForTests,
+  __resetSharedServerForTests,
+} from '../src/modules/web-ui-module.js';
+
+describe('retrieval operator authentication on credential-free loopback', () => {
+  let webUiModule: WebUiModule | undefined;
+  let root: string;
+  let baseUrl: string;
+
+  beforeAll(async () => {
+    root = mkdtempSync(join(tmpdir(), 'retrieval-auth-loopback-'));
+    const staticRoot = join(root, 'web');
+    mkdirSync(staticRoot);
+    writeFileSync(join(staticRoot, 'index.html'), '<!doctype html><title>loopback</title>');
+    webUiModule = new WebUiModule({
+      port: 0,
+      host: '127.0.0.1',
+      staticDir: staticRoot,
+    });
+    await webUiModule.start({} as ModuleContext);
+    const port = __getSharedServerPortForTests();
+    if (!port) throw new Error('webui server not bound; did start() succeed?');
+    baseUrl = `http://127.0.0.1:${port}`;
+  });
+
+  afterAll(async () => {
+    await webUiModule?.stop();
+    await __resetSharedServerForTests();
+    if (root) rmSync(root, { recursive: true, force: true });
+  });
+
+  test('denies both retrieval routes without changing ordinary loopback routes', async () => {
+    expect((await fetch(`${baseUrl}/`)).status).toBe(200);
+    expect((await fetch(`${baseUrl}/debug/context`)).status).toBe(503);
+
+    for (const path of ['/debug/retrieval', '/debug/retrieval/view']) {
+      const response = await fetch(`${baseUrl}${path}`);
+      expect(response.status).toBe(401);
+      expect(response.headers.get('cache-control')).toBe('no-store');
+    }
+  });
+});

package/test/retrieval-config.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'bun:test';
+import type { Membrane } from '@animalabs/membrane';
+import { validateRecipe } from '../src/recipe.js';
+import { buildRetrievalModuleConfig } from '../src/retrieval-config.js';
+
+const membrane = {} as Membrane;
+
+function recipe(retrieval: unknown, provider: string = 'openai-codex') {
+  return {
+    name: 'retrieval-config-test',
+    agent: { systemPrompt: 'sys', provider },
+    modules: { retrieval },
+  };
+}
+
+describe('retrieval recipe config', () => {
+  test('accepts and maps provider reasoning settings', () => {
+    const parsed = validateRecipe(recipe({
+      model: 'test-model',
+      maxInjected: 7,
+      reasoningEffort: 'minimal',
+    }));
+
+    expect(parsed.modules?.retrieval).toEqual({
+      model: 'test-model',
+      maxInjected: 7,
+      reasoningEffort: 'minimal',
+    });
+    expect(buildRetrievalModuleConfig(membrane, parsed.modules!.retrieval!, 'openai-codex')).toEqual({
+      membrane,
+      retrievalModel: 'test-model',
+      maxInjectedLessons: 7,
+      retrievalReasoning: { effort: 'minimal' },
+    });
+  });
+
+  test('preserves boolean shorthand and omits unconfigured reasoning', () => {
+    expect(validateRecipe(recipe(true)).modules?.retrieval).toBe(true);
+    expect(validateRecipe(recipe(false)).modules?.retrieval).toBe(false);
+    expect(buildRetrievalModuleConfig(membrane, { model: 'test-model' }, 'anthropic')).toEqual({
+      membrane,
+      retrievalModel: 'test-model',
+    });
+  });
+
+  test('rejects malformed retrieval reasoning settings', () => {
+    expect(() => validateRecipe(recipe(null))).toThrow(/modules\.retrieval must be a boolean or object/);
+    expect(() => validateRecipe(recipe([]))).toThrow(/modules\.retrieval must be a boolean or object/);
+    expect(() => validateRecipe(recipe({ reasoningEffort: 'ultra' }))).toThrow(/reasoningEffort/);
+    expect(() => validateRecipe(recipe({ reasoningEffort: ['high'] }))).toThrow(/reasoningEffort/);
+    expect(() => validateRecipe(recipe({ reasoningContext: 'current_turn' }))).toThrow(
+      /independent one-shot requests/,
+    );
+    expect(() => validateRecipe(recipe({ reasoningEffort: 'high' }, 'anthropic'))).toThrow(
+      /requires agent\.provider/,
+    );
+    expect(() => buildRetrievalModuleConfig(
+      membrane,
+      { reasoningEffort: 'high' },
+      'anthropic',
+    )).toThrow(/requires agent\.provider/);
+    expect(() => validateRecipe(recipe({ reasoningEffort: 'high' }))).toThrow(
+      /model must be a non-empty string/,
+    );
+    expect(() => validateRecipe(recipe({ model: '  ', reasoningEffort: 'high' }))).toThrow(
+      /model must be a non-empty string/,
+    );
+    expect(() => buildRetrievalModuleConfig(
+      membrane,
+      { reasoningEffort: 'high' },
+      'openai-codex',
+    )).toThrow(/model must be a non-empty string/);
+  });
+});