@animalabs/connectome-host 0.7.2 → 0.7.3

package/src/recipe.ts

@@ -71,16 +71,19 @@ export interface RecipeStrategy {
   /** kv-stable: quality-gap override threshold (§13.4). Default 0.35. */
   kvStableQualityGapRatio?: number;
   compressionSlackRatio?: number;
+  /** Adaptive-resolution fold planner. The host defaults this to 'kv-stable'
+   *  (cache-stable compile plans; see buildFrameworkStrategy) — set explicitly
+   *  only to opt into the legacy planners. */
   foldingStrategy?: 'flat-profile' | 'oldest-first' | 'kv-stable';
   speculativeProduction?: boolean;
   /** L1 production holdback: keep the newest N closed chunks out of the
    *  speculative compression queue (default 1); demand still overrides. */
   l1HoldbackChunks?: number;
-  // Self-voice / compression framing. When the agent's name differs from
-  // 'Claude' (the strategy default for summaryParticipant), these MUST be set
-  // (especially summaryParticipant: <agent.name>) — otherwise self-recollections
-  // are stored under a stranger's participant and surface in the compiled prompt
-  // as another voice speaking in first person about the agent.
+  // Self-voice / compression framing. The host defaults summaryParticipant to
+  // `agent.name` (buildFrameworkStrategy), so self-recollections speak as the
+  // agent itself. Set explicitly only to voice summaries as someone else —
+  // a mismatched participant surfaces in the compiled prompt as another voice
+  // speaking in first person about the agent.
   summaryParticipant?: string;
   summarySystemPrompt?: string;
   summaryUserPrompt?: string;
@@ -121,8 +124,18 @@ export interface RecipeAgent {
    *  ContextManager default (100k) applies. Raise for large-context models. */
   contextBudgetTokens?: number;
   /** Prompt-cache TTL ('5m' | '1h') forwarded to the provider. Defaults to
-   *  '1h'; set '5m' explicitly for high-frequency, sub-5-minute workloads. */
+   *  '1h'; set '5m' explicitly for high-frequency, sub-5-minute workloads.
+   *  Not forwarded on bedrock — that transport only has the default 5m
+   *  cache and rejects the ttl field. */
   cacheTtl?: '5m' | '1h';
+  /**
+   * Explicit prompt-caching override. Unset means provider-appropriate
+   * default: on for everything except bedrock models that predate caching
+   * support there (see bedrockModelSupportsPromptCaching). Set false if a
+   * transport/account rejects cache_control markers — AWS's "your request
+   * did not allow prompt caching" can also be account/region-dependent.
+   */
+  promptCaching?: boolean;
   /**
    * Same-round routing policy for ordinary text emitted beside think().
    * Omitted preserves the compatibility carry-forward in Agent Framework.
@@ -150,6 +163,13 @@ export interface RecipeAgent {
   thinking?: {
     enabled: boolean;
     budgetTokens?: number;
+    /** 'enabled' (explicit budget, legacy) or 'adaptive' (model-managed;
+     * required by opus-4-7+ / fable-5 era models). */
+    type?: 'enabled' | 'adaptive';
+    /** 'summarized' returns readable reasoning summaries in `thinking`;
+     * 'omitted' returns empty text + signature only. Models 4.7+ default
+     * to 'omitted' server-side. */
+    display?: 'summarized' | 'omitted';
   };
   /** OpenAI Responses settings. Reasoning applies to both OpenAI providers;
    * compaction and serviceTier are API-key transport settings. */
@@ -188,6 +208,12 @@ export interface RecipeMcpServer {
   transport?: 'stdio' | 'websocket';
   /** Bearer token for WebSocket auth (appended as ?token= query param). */
   token?: string;
+  /**
+   * Name of a host-managed access grant (archipelago audience, e.g.
+   * "eidoverse"). Requires the `identity` module. The host resolves fresh
+   * credentials per dial; neither the recipe nor the agent holds one.
+   */
+  access?: string;
   toolPrefix?: string;
   enabledFeatureSets?: string[];
   disabledFeatureSets?: string[];
@@ -382,8 +408,22 @@ export interface RecipeWorkspaceMount {
 }
 
 export interface RecipeModules {
+  /**
+   * Subagent forking (spawn/fork parallel agents). OPT-IN — defaults to off
+   * and is not part of the standard recipe.
+   */
   subagents?: boolean | { defaultModel?: string; defaultMaxTokens?: number };
+  /**
+   * Lesson library (persistent knowledge store + lesson tools). OPT-IN —
+   * defaults to off and is not part of the standard recipe.
+   */
   lessons?: boolean;
+  /**
+   * Lesson retrieval-injection (requires `lessons`). OPT-IN — defaults to off
+   * and is deliberately not part of the standard recipe: it injects
+   * context-dependent content into every compile and spends two Haiku calls
+   * per turn. Enable only for agents that actually curate a lesson library.
+   */
   retrieval?: boolean | { model?: string; maxInjected?: number };
   wake?: boolean | import('@animalabs/agent-framework').GateConfig;
   workspace?: boolean | { mounts: RecipeWorkspaceMount[]; configMount?: boolean };
@@ -404,8 +444,23 @@ export interface RecipeModules {
    *
    * SECURITY: `mcpl_deploy` spawns arbitrary commands as the host user —
    * enabling this module means trusting the agent with code execution.
+   *
+   * `{ surface: 'utilities' }` keeps the module but parks its four tools
+   * behind the framework's single `utils` meta-tool (mcpl management is
+   * rare; it needn't cost four schemas on every inference). `true` keeps
+   * the historical first-class surface.
    */
-  mcplAdmin?: boolean;
+  mcplAdmin?: boolean | { surface?: 'tools' | 'utilities' };
+
+  /**
+   * The agent's own archipelago-home identity (connectome docs/home-node.md):
+   * an ed25519 keypair in the data dir, enrolled at the home node via an
+   * operator invite, exchanged for fresh aid1 audience tokens on demand.
+   * Utilities-only (`utils run identity--status/enroll/token`) — costs no
+   * tool slots. `home` defaults to id.animalabs.ai; `audience` is the
+   * default for `token` calls.
+   */
+  identity?: boolean | { home?: string; audience?: string };
   /**
    * Cross-process child fleet.  When true (shorthand), FleetModule is attached
    * with no pre-configured children.  When an object, declares children the
@@ -485,6 +540,13 @@ export interface RecipeModules {
 export interface RecipeWebUi {
   port?: number;
   host?: string;
+  /**
+   * Where the observer grant tools (observers--get/grant/revoke) surface:
+   * 'tools' (default, historical) or 'utilities' (behind the `utils`
+   * meta-tool — grant edits are rare). Consent semantics unchanged: the
+   * agent holds the pen either way.
+   */
+  observersSurface?: 'tools' | 'utilities';
   /**
    * Basic-Auth credentials. Required whenever the bind host is non-loopback
    * (which is the default). `${VAR}`-substitutable from .env.
@@ -651,13 +713,13 @@ export const DEFAULT_RECIPE: Recipe = {
       'You are a helpful assistant. You have access to tools provided by connected MCP servers.',
       'Use them to help the user with their tasks.',
       '',
-      'You can fork subagents for parallel work, create persistent notes, and write files to `products/` as outputs of your work.',
+      'You can create persistent notes and write files to `products/` as outputs of your work.',
     ].join('\n'),
   },
   modules: {
-    subagents: true,
-    lessons: true,
-    retrieval: true,
+    // subagents + lessons + retrieval deliberately omitted — all opt-in only
+    // (retrieval additionally adds per-turn context churn + Haiku costs);
+    // see the RecipeModules field docs.
     wake: true,
     workspace: true,
   },
@@ -914,6 +976,12 @@ export function validateRecipe(raw: unknown): Recipe {
   }
   agent.cacheTtl ??= '1h';
 
+  if (agent.promptCaching !== undefined && typeof agent.promptCaching !== 'boolean') {
+    throw new Error(
+      `Recipe agent.promptCaching must be a boolean, got ${JSON.stringify(agent.promptCaching)}.`,
+    );
+  }
+
   if (
     agent.sameRoundThinkTextPolicy !== undefined &&
     agent.sameRoundThinkTextPolicy !== 'public' &&
@@ -938,6 +1006,12 @@ export function validateRecipe(raw: unknown): Recipe {
     if (thinking.budgetTokens !== undefined && (typeof thinking.budgetTokens !== 'number' || thinking.budgetTokens <= 0)) {
       throw new Error('Recipe agent.thinking.budgetTokens must be a positive number.');
     }
+    if (thinking.type !== undefined && thinking.type !== 'enabled' && thinking.type !== 'adaptive') {
+      throw new Error('Recipe agent.thinking.type must be "enabled" or "adaptive".');
+    }
+    if (thinking.display !== undefined && thinking.display !== 'summarized' && thinking.display !== 'omitted') {
+      throw new Error('Recipe agent.thinking.display must be "summarized" or "omitted".');
+    }
     if (thinking.enabled === true && typeof thinking.budgetTokens === 'number' && typeof agent.maxTokens === 'number') {
       if (thinking.budgetTokens >= agent.maxTokens) {
         throw new Error(

package/test/bedrock-prompt-caching.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Bedrock prompt caching is model-gated, not suppressed transport-wide
+ * (issue #35). The deny-list is the pre-GA FAMILIES (Claude v2/instant,
+ * Claude 3, 3.5 Sonnet — Bedrock's caching GA never covered them), matched
+ * at the family boundary so dated ids, bare aliases, -latest, and
+ * inference-profile forms all resolve the same. Everything currently
+ * invokable on Bedrock caches (verified by live probe 2026-07-31; the
+ * 3.5 era is EOL there). The old blanket promptCaching:false made every
+ * modern Bedrock agent re-pay its full context on every call.
+ *
+ * The recipe override must land at BOTH layers — per-agent config for
+ * agent inference AND Membrane defaultPromptCaching for internal callers
+ * (compression/merge) — on every provider, per Sol's #69 review.
+ */
+import { describe, expect, test } from 'bun:test';
+import { validateRecipe } from '../src/recipe.js';
+import {
+  buildFrameworkAgentConfig,
+  bedrockModelSupportsPromptCaching,
+  membraneCachingOverride,
+} from '../src/framework-agent-config.js';
+
+function recipe(agent: Record<string, unknown> = {}) {
+  return { name: 'bedrock-caching-test', agent: { systemPrompt: 'sys', ...agent } };
+}
+
+describe('bedrockModelSupportsPromptCaching', () => {
+  test('ids without GA caching support are gated off', () => {
+    for (const id of [
+      'anthropic.claude-3-opus-20240229-v1:0',
+      'anthropic.claude-3-sonnet-20240229-v1:0',
+      'anthropic.claude-3-haiku-20240307-v1:0',
+      'us.anthropic.claude-3-5-sonnet-20240620-v1:0',
+      // "3.6" — its caching was preview-only on Bedrock, dropped at GA
+      // (and the model itself is EOL there as of 7/2026).
+      'us.anthropic.claude-3-5-sonnet-20241022-v2:0',
+      'claude-3-5-sonnet-20241022',
+      'claude-3-opus-20240229',
+      'anthropic.claude-v2:1',
+      'anthropic.claude-instant-v1',
+    ]) {
+      expect(bedrockModelSupportsPromptCaching(id)).toBe(false);
+    }
+  });
+
+  test('the deny-list matches families, not single dated spellings', () => {
+    // Sol's #69 review: bare aliases, -latest, and profile forms of the
+    // pre-GA families must not fall through to caching-on.
+    for (const id of [
+      'claude-3-opus',
+      'claude-3-opus-latest',
+      'claude-3-sonnet',
+      'claude-3-haiku-latest',
+      'claude-3-5-sonnet',
+      'claude-3-5-sonnet-latest',
+      'us.anthropic.claude-3-opus-latest-v1:0',
+      'apac.anthropic.claude-3-5-sonnet-v2:0',
+      'CLAUDE-3-OPUS',
+    ]) {
+      expect(bedrockModelSupportsPromptCaching(id)).toBe(false);
+    }
+  });
+
+  test('models with GA Bedrock caching support stay on', () => {
+    for (const id of [
+      'anthropic.claude-3-5-haiku-20241022-v1:0',
+      'claude-3-5-haiku-latest',
+      'us.anthropic.claude-3-7-sonnet-20250219-v1:0',
+      'claude-3-7-sonnet',
+      'us.anthropic.claude-sonnet-4-20250514-v1:0',
+      'claude-sonnet-4-20250514',
+      'claude-opus-4-6',
+      'bedrock:us.anthropic.claude-opus-4-20250514-v1:0',
+    ]) {
+      expect(bedrockModelSupportsPromptCaching(id)).toBe(true);
+    }
+  });
+
+  test('non-Claude Bedrock ids are conservatively off, not accidentally on', () => {
+    for (const id of ['amazon.nova-pro-v1:0', 'meta.llama3-70b-instruct-v1:0', 'mistral.mistral-large-2402-v1:0']) {
+      expect(bedrockModelSupportsPromptCaching(id)).toBe(false);
+    }
+  });
+});
+
+describe('bedrock agent config', () => {
+  test('GA-supported bedrock model gets caching on, without cacheTtl', () => {
+    const parsed = validateRecipe(recipe({ provider: 'bedrock' }));
+    const config = buildFrameworkAgentConfig(
+      parsed, 'agent', 'us.anthropic.claude-3-7-sonnet-20250219-v1:0', undefined,
+    );
+    expect(config.promptCaching).toBe(true);
+    // Bedrock rejects cache_control.ttl; the recipe default ('1h') must not
+    // ride along even though membrane also strips it.
+    expect(Object.prototype.hasOwnProperty.call(config, 'cacheTtl')).toBe(false);
+  });
+
+  test('legacy bedrock model keeps caching suppressed', () => {
+    const parsed = validateRecipe(recipe({ provider: 'bedrock' }));
+    const config = buildFrameworkAgentConfig(
+      parsed, 'agent', 'us.anthropic.claude-3-5-sonnet-20240620-v1:0', undefined,
+    );
+    expect(config.promptCaching).toBe(false);
+  });
+
+  test('recipe promptCaching overrides the model gate in both directions', () => {
+    const forcedOff = buildFrameworkAgentConfig(
+      validateRecipe(recipe({ provider: 'bedrock', promptCaching: false })),
+      'agent', 'us.anthropic.claude-3-7-sonnet-20250219-v1:0', undefined,
+    );
+    expect(forcedOff.promptCaching).toBe(false);
+
+    // Explicit opt-in for an account/region whose entitlements differ
+    // from the GA table (the gate is a default, not a hard ceiling).
+    const forcedOn = buildFrameworkAgentConfig(
+      validateRecipe(recipe({ provider: 'bedrock', promptCaching: true })),
+      'agent', 'us.anthropic.claude-3-5-sonnet-20241022-v2:0', undefined,
+    );
+    expect(forcedOn.promptCaching).toBe(true);
+  });
+
+  test('explicit override lands at BOTH layers on any provider (composition)', () => {
+    // Anthropic recipe, explicit false: agent config off AND membrane
+    // default off — internal callers (compression/merge) read the latter.
+    const anthOff = validateRecipe(recipe({ promptCaching: false }));
+    expect(buildFrameworkAgentConfig(anthOff, 'agent', 'claude-opus-4-6', undefined).promptCaching).toBe(false);
+    expect(membraneCachingOverride(anthOff, 'claude-opus-4-6')).toEqual({ defaultPromptCaching: false });
+
+    // Bedrock explicit true and false: both layers agree with the override.
+    const bedOn = validateRecipe(recipe({ provider: 'bedrock', promptCaching: true }));
+    expect(buildFrameworkAgentConfig(bedOn, 'agent', 'us.anthropic.claude-3-5-sonnet-20241022-v2:0', undefined).promptCaching).toBe(true);
+    expect(membraneCachingOverride(bedOn, 'us.anthropic.claude-3-5-sonnet-20241022-v2:0')).toEqual({ defaultPromptCaching: true });
+
+    const bedOff = validateRecipe(recipe({ provider: 'bedrock', promptCaching: false }));
+    expect(buildFrameworkAgentConfig(bedOff, 'agent', 'us.anthropic.claude-opus-4-1-20250805-v1:0', undefined).promptCaching).toBe(false);
+    expect(membraneCachingOverride(bedOff, 'us.anthropic.claude-opus-4-1-20250805-v1:0')).toEqual({ defaultPromptCaching: false });
+
+    // Bedrock with no explicit override: the model gate supplies the
+    // answer at both layers too.
+    const bedGate = validateRecipe(recipe({ provider: 'bedrock' }));
+    expect(membraneCachingOverride(bedGate, 'us.anthropic.claude-3-7-sonnet-20250219-v1:0')).toEqual({ defaultPromptCaching: true });
+    expect(membraneCachingOverride(bedGate, 'anthropic.claude-3-opus-20240229-v1:0')).toEqual({ defaultPromptCaching: false });
+
+    // Anthropic with no override: BOTH layers stay silent — membrane's
+    // own default (on) governs, and we don't bake it in here.
+    const anthDefault = validateRecipe(recipe());
+    expect(Object.prototype.hasOwnProperty.call(
+      buildFrameworkAgentConfig(anthDefault, 'agent', 'claude-opus-4-6', undefined), 'promptCaching',
+    )).toBe(false);
+    expect(membraneCachingOverride(anthDefault, 'claude-opus-4-6')).toEqual({});
+  });
+
+  test('non-bedrock providers keep prior behavior: caching omitted, cacheTtl forwarded', () => {
+    const parsed = validateRecipe(recipe());
+    const config = buildFrameworkAgentConfig(parsed, 'agent', 'claude-opus-4-6', undefined);
+    expect(Object.prototype.hasOwnProperty.call(config, 'promptCaching')).toBe(false);
+    expect(config.cacheTtl).toBe('1h');
+  });
+
+  test('recipe promptCaching applies on non-bedrock providers too', () => {
+    const parsed = validateRecipe(recipe({ promptCaching: false }));
+    const config = buildFrameworkAgentConfig(parsed, 'agent', 'claude-opus-4-6', undefined);
+    expect(config.promptCaching).toBe(false);
+  });
+
+  test('non-boolean promptCaching is rejected at validation', () => {
+    expect(() => validateRecipe(recipe({ promptCaching: 'yes' }))).toThrow(/promptCaching/);
+    expect(() => validateRecipe(recipe({ promptCaching: 1 }))).toThrow(/promptCaching/);
+  });
+});

package/test/framework-strategy-defaults.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Standard-recipe memory defaults (buildFrameworkStrategy).
+ *
+ * A recipe that omits strategy tuning must get the fleet-standard shape:
+ * autobiographical + adaptiveResolution + kv-stable folding + same-model
+ * compression + summaries voiced as the agent itself. Explicit recipe values
+ * always win. DEFAULT_RECIPE must not enable the opt-in modules
+ * (subagents/lessons/retrieval).
+ */
+import { describe, expect, test } from 'bun:test';
+import { buildFrameworkStrategy } from '../src/framework-strategy.js';
+import { DEFAULT_RECIPE, validateRecipe } from '../src/recipe.js';
+
+function recipe(agent: Record<string, unknown> = {}) {
+  return validateRecipe({
+    name: 'framework-strategy-defaults',
+    agent: {
+      systemPrompt: 'sys',
+      ...agent,
+    },
+  });
+}
+
+function configView(strategy: object): Record<string, unknown> {
+  return (strategy as { config?: Record<string, unknown> }).config ?? {};
+}
+
+describe('standard-recipe memory defaults', () => {
+  test('omitted strategy gets kv-stable folding, same-model compression, and agent-voiced summaries', () => {
+    const strategy = buildFrameworkStrategy(
+      recipe({ name: 'Mira' }),
+      'some-model',
+      'America/Los_Angeles',
+    );
+    const config = configView(strategy);
+    expect(config.adaptiveResolution).toBe(true);
+    expect(config.foldingStrategy).toBe('kv-stable');
+    expect(config.compressionModel).toBe('some-model');
+    expect(config.summaryParticipant).toBe('Mira');
+  });
+
+  test('explicit recipe values override the defaults', () => {
+    const strategy = buildFrameworkStrategy(
+      recipe({
+        name: 'Mira',
+        strategy: {
+          type: 'autobiographical',
+          foldingStrategy: 'flat-profile',
+          compressionModel: 'pinned-model',
+          summaryParticipant: 'Someone Else',
+        },
+      }),
+      'some-model',
+      'America/Los_Angeles',
+    );
+    const config = configView(strategy);
+    expect(config.foldingStrategy).toBe('flat-profile');
+    expect(config.compressionModel).toBe('pinned-model');
+    expect(config.summaryParticipant).toBe('Someone Else');
+  });
+
+  test('adaptiveResolution opt-out leaves foldingStrategy unset', () => {
+    const strategy = buildFrameworkStrategy(
+      recipe({ strategy: { type: 'autobiographical', adaptiveResolution: false } }),
+      'some-model',
+      'America/Los_Angeles',
+    );
+    const config = configView(strategy);
+    expect(config.adaptiveResolution).toBe(false);
+    expect(config.foldingStrategy).toBeUndefined();
+  });
+
+  test("without an agent name the summary voice falls back to the library's 'Claude' default", () => {
+    const strategy = buildFrameworkStrategy(
+      recipe(),
+      'some-model',
+      'America/Los_Angeles',
+    );
+    expect(configView(strategy).summaryParticipant).toBe('Claude');
+  });
+
+  test('DEFAULT_RECIPE does not enable the opt-in modules', () => {
+    const modules = DEFAULT_RECIPE.modules ?? {};
+    expect(modules).not.toHaveProperty('subagents');
+    expect(modules).not.toHaveProperty('lessons');
+    expect(modules).not.toHaveProperty('retrieval');
+  });
+});

package/test/identity-and-surfaces.test.ts

@@ -0,0 +1,157 @@
+// Identity module (archipelago-home client) + the tools↔utilities surface
+// flags on mcpl-admin and observers. See docs/home-node.md §4 and the af
+// utils meta-tool (Module.getUtilities).
+//
+// Design under test: the AGENT surface is credential-free (status /
+// accept_invite, no tokens in any result); credentials exist only on the
+// HOST-facing API (accessFor/httpAuthFor) that the MCPL dial provider
+// and HTTP helpers consume outside model context.
+import { describe, it, expect } from 'bun:test';
+import { mkdtempSync, existsSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createPublicKey, verify as cryptoVerify } from 'node:crypto';
+
+import { IdentityModule } from '../src/modules/identity-module.ts';
+import { McplAdminModule } from '../src/modules/mcpl-admin-module.ts';
+import { ObserversModule } from '../src/modules/observers-module.ts';
+
+const call = (name: string, input: unknown) => ({ id: 't1', name, input });
+
+function fakeHome(routes: Record<string, (body: any) => { status: number; json: unknown }>): typeof fetch {
+  return (async (url: string | URL | Request, init?: RequestInit) => {
+    const path = new URL(String(url)).pathname;
+    const handler = routes[path];
+    if (!handler) return new Response('{}', { status: 404 });
+    const body = JSON.parse(String(init?.body ?? '{}'));
+    const { status, json } = handler(body);
+    return new Response(JSON.stringify(json), { status });
+  }) as typeof fetch;
+}
+
+describe('identity module', () => {
+  it('is utilities-only, and the agent surface never mentions or returns credentials', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ident-'));
+    const mod = new IdentityModule({ keyPath: join(dir, 'identity-key.pem'), home: 'id.test' });
+    expect(mod.getTools()).toEqual([]);
+    expect(mod.getUtilities().map((u) => u.name)).toEqual(['status', 'accept_invite']);
+    // Framing check: no crypto/credential vocabulary in agent-visible text.
+    const visible = JSON.stringify(mod.getUtilities()).toLowerCase();
+    for (const scary of ['token', 'key', 'sign', 'proof', 'ed25519', 'mint', 'bearer']) {
+      expect(visible).not.toContain(scary);
+    }
+
+    const res = await mod.handleToolCall(call('status', {}));
+    expect(res.success).toBe(true);
+    const data = res.data as { registeredAs: unknown; note: string };
+    expect(data.registeredAs).toBe(null);
+    expect(data.note).toContain('invitation code');
+    expect(JSON.stringify(res.data)).not.toContain('ed25519'); // key exists on disk, not in results
+    expect(existsSync(join(dir, 'identity-key.pem'))).toBe(true);
+  });
+
+  it('accept_invite registers, echoes NO credential, and is one-time', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ident-'));
+    let seen: any = null;
+    const mod = new IdentityModule({
+      keyPath: join(dir, 'k.pem'),
+      home: 'id.test',
+      fetchImpl: fakeHome({
+        '/enroll': (body) => {
+          seen = body;
+          return { status: 200, json: { sub: 'agent:ferro@guest', token: 'aid1.SECRET.x' } };
+        },
+      }),
+    });
+    const res = await mod.handleToolCall(call('accept_invite', { invite: 'inv_1', name: 'Ferro' }));
+    expect(res.success).toBe(true);
+    expect((res.data as any).id).toBe('agent:ferro@guest');
+    // The home node's response token must NOT reach the agent.
+    expect(JSON.stringify(res.data)).not.toContain('aid1.');
+
+    // Wire-level: the signed statement is the spec's, verifiable by the module's own key.
+    const raw = Buffer.from(seen.id.slice('ed25519:'.length), 'base64url');
+    const key = createPublicKey({
+      key: Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), raw]),
+      format: 'der', type: 'spki',
+    });
+    const statement = `archipelago-enroll|v1|id.test|inv_1|${seen.timestamp}`;
+    expect(cryptoVerify(null, Buffer.from(statement), key, Buffer.from(seen.proof, 'base64url'))).toBe(true);
+
+    const rec = JSON.parse(readFileSync(join(dir, 'k.json'), 'utf8'));
+    expect(rec.sub).toBe('agent:ferro@guest');
+
+    const again = await mod.handleToolCall(call('accept_invite', { invite: 'inv_2', name: 'Ferro2' }));
+    expect(again.success).toBe(false);
+    expect(again.error).toContain('Already registered');
+  });
+
+  it('host-facing accessFor: requires registration, then exchanges per call', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ident-'));
+    let mints = 0;
+    const mod = new IdentityModule({
+      keyPath: join(dir, 'k.pem'),
+      home: 'id.test',
+      defaultAudience: 'eidoverse',
+      fetchImpl: fakeHome({
+        '/enroll': () => ({ status: 200, json: { sub: 'agent:a@guest', token: 't0' } }),
+        '/token': (body) => body.audience === 'eidoverse'
+          ? { status: 200, json: { token: `aid1.fresh.${++mints}` } }
+          : { status: 400, json: { error: 'unknown audience' } },
+      }),
+    });
+    await expect(mod.accessFor()).rejects.toThrow(/not registered/);
+
+    await mod.handleToolCall(call('accept_invite', { invite: 'i', name: 'A' }));
+    expect(await mod.accessFor()).toBe('aid1.fresh.1');
+    expect(await mod.accessFor('eidoverse')).toBe('aid1.fresh.2'); // fresh per call — dial-time rotation
+    expect((await mod.httpAuthFor()).authorization).toBe('Bearer aid1.fresh.3');
+    await expect(mod.accessFor('nope')).rejects.toThrow(/unknown audience/);
+    expect(mod.isEnrolled()).toBe(true);
+    expect(mod.sub()).toBe('agent:a@guest');
+  });
+});
+
+describe('mcpl-admin access grants', () => {
+  it('deploy with `access` requires identity wiring, and stores the NAME not a credential', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'mcpl-'));
+    const mod = new McplAdminModule({ overlayPath: join(dir, 'overlay.json') });
+    // stub framework so the deploy reaches the access check
+    mod.setFramework({
+      listMcplServers: () => [],
+      connectMcplServer: async () => {},
+      restartMcplServer: async () => {},
+      disconnectMcplServer: async () => {},
+    } as any);
+
+    // no identity wired → clear bounce
+    const refused = await mod.handleToolCall(call('mcpl_deploy', {
+      id: 'worlds', url: 'wss://example.test/mcpl', access: 'eidoverse',
+    }) as any);
+    expect(refused.success).toBe(false);
+    expect(refused.error).toContain('identity');
+  });
+
+  it('surface flags: default keeps four first-class tools; utilities parks them', () => {
+    const asTools = new McplAdminModule({});
+    expect(asTools.getTools().length).toBe(4);
+    expect(asTools.getUtilities().length).toBe(0);
+
+    const asUtils = new McplAdminModule({ surface: 'utilities' });
+    expect(asUtils.getTools().length).toBe(0);
+    expect(asUtils.getUtilities().map((u) => u.name).sort()).toEqual(
+      ['mcpl_deploy', 'mcpl_list', 'mcpl_restart', 'mcpl_unload'],
+    );
+  });
+});
+
+describe('observers surface flag', () => {
+  it('same definitions on either surface', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'obs-'));
+    const asTools = new ObserversModule({ path: join(dir, 'observers.json') });
+    const asUtils = new ObserversModule({ path: join(dir, 'observers.json'), surface: 'utilities' });
+    expect(asTools.getTools().map((t) => t.name)).toEqual(asUtils.getUtilities().map((u) => u.name));
+    expect(asTools.getUtilities().length).toBe(0);
+    expect(asUtils.getTools().length).toBe(0);
+  });
+});