@animalabs/connectome-host 0.7.4 → 0.8.1

package/test/framework-fkm-composition.test.ts

@@ -86,7 +86,7 @@ describe('framework FKM composition', () => {
     });
   });
 
-  test('composes validation, serialization, and AF/CM wiring for the merged FKM settings without cross-agent bleed', () => {
+  test('composes validation, serialization, and AF/CM wiring for the merged FKM settings without cross-agent bleed', async () => {
     const parsed = validateRecipe(recipe({
       provider: 'openai-responses',
       maxTokens: 4_096,
@@ -103,13 +103,20 @@ describe('framework FKM composition', () => {
         type: 'autobiographical',
         compressionRefusalCurveFallbacks: 2,
         compressionContextBudgetTokens: 19_000,
+        compressionRecallBudgetTokens: 17_000,
+        compressionSourceOnly: false,
+        compressionSourceOnlyFallback: true,
+        compressionMergeSourceOnly: false,
+        compressionMergeSourceOnlyFallback: true,
       },
     }));
 
     const dir = mkdtempSync(join(tmpdir(), 'connectome-fkm-'));
     tempDirs.push(dir);
-    saveRecipe(dir, parsed);
-    const reloaded = loadSavedRecipe(dir);
+    // Saving an already-resolved recipe through the new unresolved-snapshot
+    // path is legal: substitution over resolved content is a no-op.
+    saveRecipe(dir, parsed as unknown as Record<string, unknown>);
+    const reloaded = await loadSavedRecipe(dir);
     expect(reloaded).not.toBeNull();
 
     expect(reloaded!.agent.sameRoundThinkTextPolicy).toBe('private');
@@ -118,11 +125,21 @@ describe('framework FKM composition', () => {
     });
     expect(reloaded!.agent.strategy?.compressionRefusalCurveFallbacks).toBe(2);
     expect(reloaded!.agent.strategy?.compressionContextBudgetTokens).toBe(19_000);
+    expect(reloaded!.agent.strategy?.compressionRecallBudgetTokens).toBe(17_000);
+    expect(reloaded!.agent.strategy?.compressionSourceOnly).toBe(false);
+    expect(reloaded!.agent.strategy?.compressionSourceOnlyFallback).toBe(true);
+    expect(reloaded!.agent.strategy?.compressionMergeSourceOnly).toBe(false);
+    expect(reloaded!.agent.strategy?.compressionMergeSourceOnlyFallback).toBe(true);
 
     const runtimeStrategy = buildFrameworkStrategy(reloaded!, 'model', 'America/Los_Angeles');
     const runtimeConfig = strategyConfigView(runtimeStrategy);
     expect(runtimeConfig.compressionRefusalCurveFallbacks).toBe(2);
     expect(runtimeConfig.compressionContextBudgetTokens).toBe(19_000);
+    expect(runtimeConfig.compressionRecallBudgetTokens).toBe(17_000);
+    expect(runtimeConfig.compressionSourceOnly).toBe(false);
+    expect(runtimeConfig.compressionSourceOnlyFallback).toBe(true);
+    expect(runtimeConfig.compressionMergeSourceOnly).toBe(false);
+    expect(runtimeConfig.compressionMergeSourceOnlyFallback).toBe(true);
 
     const agentConfig = buildFrameworkAgentConfig(reloaded!, 'agent', 'model', runtimeStrategy);
     expect(agentConfig.sameRoundThinkTextPolicy).toBe('private');
@@ -138,14 +155,29 @@ describe('framework FKM composition', () => {
         type: 'autobiographical',
         compressionRefusalCurveFallbacks: 0,
         compressionContextBudgetTokens: 50_000,
+        compressionRecallBudgetTokens: 41_000,
+        compressionSourceOnly: true,
+        compressionSourceOnlyFallback: false,
+        compressionMergeSourceOnly: true,
+        compressionMergeSourceOnlyFallback: false,
       },
     }));
     const otherStrategy = buildFrameworkStrategy(otherRecipe, 'other-model', 'America/Los_Angeles');
     const otherConfig = strategyConfigView(otherStrategy);
     expect(otherConfig.compressionRefusalCurveFallbacks).toBe(0);
     expect(otherConfig.compressionContextBudgetTokens).toBe(50_000);
+    expect(otherConfig.compressionRecallBudgetTokens).toBe(41_000);
+    expect(otherConfig.compressionSourceOnly).toBe(true);
+    expect(otherConfig.compressionSourceOnlyFallback).toBe(false);
+    expect(otherConfig.compressionMergeSourceOnly).toBe(true);
+    expect(otherConfig.compressionMergeSourceOnlyFallback).toBe(false);
     expect(otherConfig).not.toBe(runtimeConfig);
     expect(runtimeConfig.compressionRefusalCurveFallbacks).toBe(2);
     expect(runtimeConfig.compressionContextBudgetTokens).toBe(19_000);
+    expect(runtimeConfig.compressionRecallBudgetTokens).toBe(17_000);
+    expect(runtimeConfig.compressionSourceOnly).toBe(false);
+    expect(runtimeConfig.compressionSourceOnlyFallback).toBe(true);
+    expect(runtimeConfig.compressionMergeSourceOnly).toBe(false);
+    expect(runtimeConfig.compressionMergeSourceOnlyFallback).toBe(true);
   });
 });

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

@@ -61,6 +61,66 @@ describe('standard-recipe memory defaults', () => {
     expect(config.foldingStrategy).toBeUndefined();
   });
 
+  test('compressionSplitFallback / compressionSplitPlaceholder pass through and stay omitted when omitted', () => {
+    const on = buildFrameworkStrategy(
+      recipe({ name: 'Mira', strategy: { type: 'autobiographical', compressionSplitFallback: true, compressionSplitPlaceholder: true } }),
+      'some-model',
+      'America/Los_Angeles',
+    );
+    expect(configView(on).compressionSplitFallback).toBe(true);
+    expect(configView(on).compressionSplitPlaceholder).toBe(true);
+    const omitted = buildFrameworkStrategy(recipe({ name: 'Mira' }), 'some-model', 'America/Los_Angeles');
+    expect(configView(omitted).compressionSplitFallback).toBeUndefined();
+    expect(configView(omitted).compressionSplitPlaceholder).toBeUndefined();
+    expect(() => recipe({ name: 'Mira', strategy: { type: 'autobiographical', compressionSplitFallback: 'yes' } })).toThrow();
+  });
+
+  test('split-stitch cap knobs pass through and are validated as positive integers', () => {
+    const on = buildFrameworkStrategy(
+      recipe({ name: 'Mira', strategy: { type: 'autobiographical', compressionSplitFallback: true, compressionSplitMaxCallsPerChunk: 12, compressionSplitMaxCallsPer10Min: 30 } }),
+      'some-model',
+      'America/Los_Angeles',
+    );
+    expect(configView(on).compressionSplitMaxCallsPerChunk).toBe(12);
+    expect(configView(on).compressionSplitMaxCallsPer10Min).toBe(30);
+    expect(() => recipe({ name: 'Mira', strategy: { type: 'autobiographical', compressionSplitMaxCallsPerChunk: 0 } })).toThrow();
+    expect(() => recipe({ name: 'Mira', strategy: { type: 'autobiographical', compressionSplitMaxCallsPer10Min: 1.5 } })).toThrow();
+  });
+
+  test('mergeMaxSourceSpanMessages is passed through exactly and omission stays omitted (princess 2026-09-05: silently dropped, span guard stuck at the CM default)', () => {
+    const configured = buildFrameworkStrategy(
+      recipe({
+        name: 'Mira',
+        strategy: { type: 'autobiographical', mergeMaxSourceSpanMessages: 3000, mergeThreshold: 3 },
+      }),
+      'some-model',
+      'America/Los_Angeles',
+    );
+    expect(configView(configured).mergeMaxSourceSpanMessages).toBe(3000);
+    expect(configView(configured).mergeThreshold).toBe(3);
+    const omitted = buildFrameworkStrategy(recipe({ name: 'Mira' }), 'some-model', 'America/Los_Angeles');
+    expect(configView(omitted).mergeMaxSourceSpanMessages).toBeUndefined();
+  });
+
+  test('productionBudgetTokens is passed through exactly and omission stays omitted', () => {
+    const configured = buildFrameworkStrategy(
+      recipe({
+        name: 'Mira',
+        strategy: { type: 'autobiographical', productionBudgetTokens: 123_456 },
+      }),
+      'some-model',
+      'America/Los_Angeles',
+    );
+    expect(configView(configured).productionBudgetTokens).toBe(123_456);
+
+    const omitted = buildFrameworkStrategy(
+      recipe({ name: 'Mira', strategy: { type: 'autobiographical' } }),
+      'some-model',
+      'America/Los_Angeles',
+    );
+    expect(configView(omitted).productionBudgetTokens).toBeUndefined();
+  });
+
   test('explicit recipe values override the defaults', () => {
     const strategy = buildFrameworkStrategy(
       recipe({

package/test/gate-telemetry-adapter.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Adapter-level proof (review finding on #113): with the PUBLISHED membrane,
+ * a stream call consults the active-turn trigger and carries the origin trio,
+ * while a complete call (compression / side-calls / keepalive) carries the
+ * debt stamp only. Runs the real AnthropicAdapter with a mocked SDK client.
+ */
+import { describe, expect, it } from 'bun:test';
+import { AnthropicAdapter } from '@animalabs/membrane';
+import { gateTelemetryHeaders } from '../src/gate-telemetry.js';
+
+const env = { GATE_TELEMETRY: '1', ANTHROPIC_BASE_URL: 'https://gateway.example/anthropic' };
+const wake = { reason: 'mcpl:channel-incoming', source: 'discord', channelId: 'discord:1:2', counterparty: 'discord:user:42' };
+
+const REQUEST = {
+  model: 'claude-test',
+  messages: [{ role: 'user', content: [{ type: 'text', text: 'hi' }] }],
+} as any;
+
+const RESPONSE = {
+  id: 'msg_test', model: 'claude-test', role: 'assistant',
+  content: [{ type: 'text', text: 'ok' }], stop_reason: 'end_turn',
+  usage: { input_tokens: 1, output_tokens: 1 },
+};
+
+/** Minimal SDK stream: an async iterable of the events the adapter reads. */
+function mockStream() {
+  const events = [
+    { type: 'message_start', message: { id: 'msg_s', model: 'claude-test', role: 'assistant', content: [], usage: { input_tokens: 1, output_tokens: 0 } } },
+    { type: 'content_block_start', index: 0, content_block: { type: 'text', text: '' } },
+    { type: 'content_block_delta', index: 0, delta: { type: 'text_delta', text: 'ok' } },
+    { type: 'content_block_stop', index: 0 },
+    { type: 'message_delta', delta: { stop_reason: 'end_turn', stop_sequence: null }, usage: { output_tokens: 1 } },
+    { type: 'message_stop' },
+  ];
+  return {
+    async *[Symbol.asyncIterator]() { for (const e of events) yield e; },
+  };
+}
+
+function adapterWithTrigger(trigger: () => typeof wake | null) {
+  let asked = 0;
+  const dyn = gateTelemetryHeaders(env, () => 3, () => { asked++; return trigger(); })!;
+  const adapter = new AnthropicAdapter({ apiKey: 'sk-test', cacheKeepalive: { enabled: false }, dynamicHeaders: dyn } as any);
+  const calls: Array<{ kind: string; headers: Record<string, string> | undefined }> = [];
+  (adapter as any).client = {
+    messages: {
+      create: async (_req: unknown, opts: { headers?: Record<string, string> }) => { calls.push({ kind: 'complete', headers: opts?.headers }); return RESPONSE; },
+      stream: async (_req: unknown, opts: { headers?: Record<string, string> }) => { calls.push({ kind: 'stream', headers: opts?.headers }); return mockStream(); },
+    },
+  };
+  return { adapter, calls, asked: () => asked };
+}
+
+describe('gate telemetry through the published AnthropicAdapter', () => {
+  it('complete lane: debt only — the active trigger is not consulted', async () => {
+    const { adapter, calls, asked } = adapterWithTrigger(() => wake);
+    await adapter.complete(REQUEST);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.kind).toBe('complete');
+    expect(calls[0]!.headers).toEqual({ 'x-gate-debt-chunks': '3' });
+    expect(asked()).toBe(0);
+  });
+
+  it('stream lane: the trigger is consulted and the origin trio rides the request', async () => {
+    const { adapter, calls, asked } = adapterWithTrigger(() => wake);
+    const chunks: string[] = [];
+    await adapter.stream(REQUEST, { onChunk: (c: string) => { chunks.push(c); } } as any);
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.kind).toBe('stream');
+    expect(calls[0]!.headers).toEqual({
+      'x-gate-debt-chunks': '3',
+      'x-gate-origin': 'event',
+      'x-gate-channel': 'discord:1:2',
+      'x-gate-counterparty': 'discord:user:42',
+    });
+    expect(asked()).toBe(1);
+  });
+
+  it('stream lane with no turn in progress: debt only, nothing guessed', async () => {
+    const { adapter, calls } = adapterWithTrigger(() => null);
+    await adapter.stream(REQUEST, { onChunk: () => {} } as any);
+    expect(calls[0]!.headers).toEqual({ 'x-gate-debt-chunks': '3' });
+  });
+});

package/test/gate-telemetry.test.ts

@@ -0,0 +1,124 @@
+/**
+ * The x-gate-* stamp must be impossible to send to a vendor: attachment is
+ * double-gated on the operator's explicit GATE_TELEMETRY declaration AND a
+ * configured base URL. Review finding on the first wiring: the stamp was
+ * attached unconditionally, so with ANTHROPIC_BASE_URL unset the household
+ * value went to the vendor's default endpoint.
+ */
+import { describe, expect, it } from 'bun:test';
+import { gateTelemetryHeaders, originClass, stampedTrigger } from '../src/gate-telemetry.js';
+
+const debt = () => 7;
+
+describe('gateTelemetryHeaders', () => {
+  it('default vendor endpoint (no base URL): never attaches, even when flagged', () => {
+    expect(gateTelemetryHeaders({ GATE_TELEMETRY: '1' }, debt)).toBeUndefined();
+  });
+
+  it('base URL without the operator declaration: never attaches', () => {
+    expect(gateTelemetryHeaders({ ANTHROPIC_BASE_URL: 'https://gateway.example/anthropic' }, debt)).toBeUndefined();
+    expect(gateTelemetryHeaders({ GATE_TELEMETRY: '0', ANTHROPIC_BASE_URL: 'https://gateway.example/anthropic' }, debt)).toBeUndefined();
+    expect(gateTelemetryHeaders({ GATE_TELEMETRY: 'false', ANTHROPIC_BASE_URL: 'https://gateway.example/anthropic' }, debt)).toBeUndefined();
+  });
+
+  it('declared gateway: attaches a live stamp', () => {
+    const fn = gateTelemetryHeaders({ GATE_TELEMETRY: '1', ANTHROPIC_BASE_URL: 'https://gateway.example/anthropic' }, debt);
+    expect(fn).toBeDefined();
+    expect(fn!()).toEqual({ 'x-gate-debt-chunks': 7 });
+  });
+
+  it('unreadable debt stays null (membrane drops null values — unstamped, never guessed)', () => {
+    const fn = gateTelemetryHeaders({ GATE_TELEMETRY: '1', ANTHROPIC_BASE_URL: 'https://gateway.example/anthropic' }, () => null);
+    expect(fn!()).toEqual({ 'x-gate-debt-chunks': null });
+  });
+
+  const env = { GATE_TELEMETRY: '1', ANTHROPIC_BASE_URL: 'https://gateway.example/anthropic' };
+  const wake = { reason: 'mcpl:channel-incoming', source: 'discord', channelId: 'discord:1:2', counterparty: 'discord:user:42' };
+
+  it('origin trio rides the stream lane: why, where, by whom — ids only', () => {
+    const fn = gateTelemetryHeaders(env, debt, () => wake);
+    expect(fn!({ lane: 'stream' })).toEqual({
+      'x-gate-debt-chunks': 7,
+      'x-gate-origin': 'event',
+      'x-gate-channel': 'discord:1:2',
+      'x-gate-counterparty': 'discord:user:42',
+    });
+  });
+
+  it('complete lane (compression, side-calls, keepalive) carries debt only — a background call is not the turn', () => {
+    const fn = gateTelemetryHeaders(env, debt, () => wake);
+    expect(fn!({ lane: 'complete' })).toEqual({ 'x-gate-debt-chunks': 7 });
+  });
+
+  it('no lane told (older membrane) or no trigger known: honest — debt only, or trio without guessing', () => {
+    expect(gateTelemetryHeaders(env, debt, () => null)!({ lane: 'stream' })).toEqual({ 'x-gate-debt-chunks': 7 });
+    expect(gateTelemetryHeaders(env, debt, () => wake)!()).toMatchObject({ 'x-gate-origin': 'event' });
+    expect(gateTelemetryHeaders(env, debt)!({ lane: 'stream' })).toEqual({ 'x-gate-debt-chunks': 7 });
+  });
+
+  it('a gate-batched wake reports its telemetry channel (wakeChannelId) when it set no locus', () => {
+    const fn = gateTelemetryHeaders(env, debt, () => ({ reason: 'gate:debounce', source: 'gate', wakeChannelId: 'discord:1:2', counterparty: 'discord:user:42' }));
+    expect(fn!({ lane: 'stream' })).toEqual({ 'x-gate-debt-chunks': 7, 'x-gate-origin': 'event', 'x-gate-channel': 'discord:1:2', 'x-gate-counterparty': 'discord:user:42' });
+  });
+
+  it('heartbeat wakes carry no channel or counterparty (null → dropped by membrane)', () => {
+    const fn = gateTelemetryHeaders(env, debt, () => ({ reason: 'heartbeat:tick', source: 'heartbeat' }));
+    expect(fn!({ lane: 'stream' })).toEqual({ 'x-gate-debt-chunks': 7, 'x-gate-origin': 'heartbeat', 'x-gate-channel': null, 'x-gate-counterparty': null });
+  });
+
+  it('originClass: heartbeat / mail / event / operator, raw reason otherwise (sanitized, clipped)', () => {
+    expect(originClass({ reason: 'heartbeat', source: 'heartbeat' })).toBe('heartbeat');
+    expect(originClass({ reason: 'mail:incoming', source: 'fenmail' })).toBe('mail');
+    expect(originClass({ reason: 'mcpl:push-event', source: 'discord' })).toBe('event');
+    expect(originClass({ reason: 'gate:debounce', source: 'gate' })).toBe('event');   // first live stamps came back raw
+    expect(originClass({ reason: 'admin-nudge (someone)', source: 'framework' })).toBe('operator');
+    expect(originClass({ reason: 'external-message', source: 'headless' })).toBe('operator');
+    expect(originClass({ reason: 'external-message', source: 'tui' })).toBe('operator');
+    expect(originClass({ reason: 'provider-acceleration-retry', source: 'framework' })).toBe('provider-acceleration-retry');
+    expect(originClass({ reason: 'weird reason!!'.repeat(6), source: 'x' })).toHaveLength(40);
+  });
+
+  it('attributes are header-safe: a value with any non-ASCII or control character is withheld whole, never rewritten', () => {
+    const fn = gateTelemetryHeaders(env, debt, () => ({ reason: 'mcpl:channel-incoming', source: 'discord', channelId: 'discord:\u{1F600}', counterparty: 'discord:user:4\r\n2' }));
+    const h = fn!({ lane: 'stream' });
+    expect(h['x-gate-channel']).toBeNull();
+    expect(h['x-gate-counterparty']).toBeNull();
+    // and what IS sent can always be put in real Headers (Fetch ByteString rule)
+    const ok = gateTelemetryHeaders(env, debt, () => wake)!({ lane: 'stream' });
+    const sendable = Object.fromEntries(Object.entries(ok).filter(([, v]) => v !== null).map(([k, v]) => [k, String(v)]));
+    expect(() => new Headers(sendable)).not.toThrow();
+    expect(new Headers(sendable).get('x-gate-counterparty')).toBe('discord:user:42');
+  });
+
+  it('attributes are clipped to 120 visible-ASCII characters', () => {
+    const fn = gateTelemetryHeaders(env, debt, () => ({ reason: 'mcpl:channel-incoming', source: 'discord', counterparty: 'x'.repeat(200) }));
+    expect((fn!({ lane: 'stream' })['x-gate-counterparty'] as string).length).toBe(120);
+  });
+
+  describe('stampedTrigger — one adapter serves every agent', () => {
+    const trig = (name: string) => ({ reason: 'gate:debounce', source: 'gate', counterparty: `discord:user:${name}` });
+
+    it('single agent: its trigger', () => {
+      expect(stampedTrigger({ agents: ['scout'], triggerOf: () => trig('scout') })).toEqual(trig('scout'));
+    });
+
+    it('primary + idle subconscious: the primary\'s trigger', () => {
+      expect(stampedTrigger({ agents: ['scout', 'scout-sub'], primary: 'scout',
+        triggerOf: (n) => (n === 'scout' ? trig('scout') : null) })).toEqual(trig('scout'));
+    });
+
+    it('primary and subconscious both mid-turn: withhold — the hook cannot tell whose request it decorates', () => {
+      expect(stampedTrigger({ agents: ['scout', 'scout-sub'], primary: 'scout',
+        triggerOf: (n) => trig(n) })).toBeNull();
+    });
+
+    it('only the subconscious mid-turn: nothing (its request is not the primary\'s turn)', () => {
+      expect(stampedTrigger({ agents: ['scout', 'scout-sub'], primary: 'scout',
+        triggerOf: (n) => (n === 'scout-sub' ? trig('sub') : null) })).toBeNull();
+    });
+
+    it('several agents and no primary known: withhold', () => {
+      expect(stampedTrigger({ agents: ['a', 'b'], triggerOf: () => trig('a') })).toBeNull();
+    });
+  });
+});

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

@@ -16,6 +16,7 @@ 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 REQUEST_BODY_MAX_FOR_TEST = 256 * 1024;
 const call = (name: string, input: unknown) => ({ id: 't1', name, input });
 
 function fakeHome(routes: Record<string, (body: any) => { status: number; json: unknown }>): typeof fetch {
@@ -34,7 +35,7 @@ describe('identity module', () => {
     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']);
+    expect(mod.getUtilities().map((u) => u.name)).toEqual(['status', 'request', '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']) {
@@ -86,6 +87,216 @@ describe('identity module', () => {
     expect(again.error).toContain('Already registered');
   });
 
+
+  it('request: allowlisted service, host-attached access, no credential in result', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ident-'));
+    let authSeen = '';
+    const mod = new IdentityModule({
+      keyPath: join(dir, 'k.pem'),
+      home: 'id.test',
+      services: { orrery: 'https://orrery.test' },
+      fetchImpl: (async (url: any, init?: any) => {
+        const u = String(url);
+        if (u.includes('/enroll')) return new Response(JSON.stringify({ sub: 'agent:a@guest', token: 't0' }), { status: 200 });
+        if (u.includes('/token')) return new Response(JSON.stringify({ token: 'aid1.fresh.secret' }), { status: 200 });
+        if (u === 'https://orrery.test/api/ops') {
+          authSeen = String(init?.headers?.authorization ?? '');
+          return new Response(JSON.stringify({ ops: [1, 2] }), { status: 200 });
+        }
+        return new Response('{}', { status: 404 });
+      }) as typeof fetch,
+    });
+    // not registered yet -> neutral failure
+    const early = await mod.handleToolCall(call('request', { service: 'orrery', path: '/api/ops' }));
+    expect(early.success).toBe(false);
+
+    await mod.handleToolCall(call('accept_invite', { invite: 'i', name: 'A' }));
+    const res = await mod.handleToolCall(call('request', { service: 'orrery', path: '/api/ops' }));
+    expect(res.success).toBe(true);
+    expect((res.data as any).status).toBe(200);
+    expect((res.data as any).body).toEqual({ ops: [1, 2] });
+    expect(authSeen).toBe('Bearer aid1.fresh.secret');
+    // the credential must never appear in the agent-visible result
+    expect(JSON.stringify(res.data)).not.toContain('aid1.');
+
+    const unknown = await mod.handleToolCall(call('request', { service: 'nope', path: '/x' }));
+    expect(unknown.error).toContain('Available: orrery');
+    const badPath = await mod.handleToolCall(call('request', { service: 'orrery', path: 'api/ops' }));
+    expect(badPath.success).toBe(false);
+  });
+
+  it('request: services come from the home node directory, and a newly-listed one works without a restart', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ident-'));
+    // The archipelago's service list lives at the home node, not in this host.
+    // It changes underneath us mid-run: `music` is added after the module has
+    // already fetched and cached a directory without it.
+    let directory: Record<string, string> = { orrery: 'https://orrery.test' };
+    let directoryFetches = 0;
+    const mod = new IdentityModule({
+      keyPath: join(dir, 'k.pem'),
+      home: 'id.test',
+      fetchImpl: (async (url: any, init?: any) => {
+        const u = String(url);
+        if (u.includes('/enroll')) return new Response(JSON.stringify({ sub: 'agent:a@id.test', token: 't0' }), { status: 200 });
+        if (u.includes('/token')) return new Response(JSON.stringify({ token: 'aid1.fresh.secret' }), { status: 200 });
+        if (u === 'https://id.test/services') {
+          directoryFetches++;
+          return new Response(JSON.stringify({ home: 'id.test', services: directory }), { status: 200 });
+        }
+        if (u === 'https://music.test/api/me') return new Response(JSON.stringify({ me: 'mythos' }), { status: 200 });
+        return new Response('{}', { status: 404 });
+      }) as typeof fetch,
+    });
+    await mod.handleToolCall(call('accept_invite', { invite: 'i', name: 'A' }));
+
+    // nothing compiled in, nothing in the recipe: the directory supplied it
+    const listed = await mod.handleToolCall(call('request', { service: 'orrery', path: '/x' }));
+    expect(listed.success).toBe(true); // resolved and called; upstream 404 is reported, not a resolution failure
+    expect((listed.data as any).status).toBe(404);
+
+    // music does not exist yet -> refused, and the refusal cost a re-check
+    const before = await mod.handleToolCall(call('request', { service: 'music', path: '/api/me' }));
+    expect(before.success).toBe(false);
+    expect(before.error).toContain('Unknown service "music"');
+
+    // operator adds it at the home node; no restart, no recipe edit here
+    directory = { orrery: 'https://orrery.test', music: 'https://music.test' };
+    const fetchesBefore = directoryFetches;
+
+    const after = await mod.handleToolCall(call('request', { service: 'music', path: '/api/me' }));
+    expect(after.success).toBe(true);
+    expect((after.data as any).body).toEqual({ me: 'mythos' });
+    // it re-asked rather than serving a stale "unknown" from cache
+    expect(directoryFetches).toBeGreaterThan(fetchesBefore);
+  });
+
+  it('request: a home node that cannot be reached degrades to the built-in map, never to an outage', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ident-'));
+    const mod = new IdentityModule({
+      keyPath: join(dir, 'k.pem'),
+      home: 'id.test',
+      fetchImpl: (async (url: any) => {
+        const u = String(url);
+        if (u.includes('/enroll')) return new Response(JSON.stringify({ sub: 'agent:a@id.test', token: 't0' }), { status: 200 });
+        if (u.includes('/token')) return new Response(JSON.stringify({ token: 'aid1.fresh.secret' }), { status: 200 });
+        if (u === 'https://id.test/services') return new Response('nope', { status: 503 });
+        if (u === 'https://eidoverse.animalabs.ai/api/ping') return new Response(JSON.stringify({ ok: true }), { status: 200 });
+        return new Response('{}', { status: 404 });
+      }) as typeof fetch,
+    });
+    await mod.handleToolCall(call('accept_invite', { invite: 'i', name: 'A' }));
+    const res = await mod.handleToolCall(call('request', { service: 'eidoverse', path: '/api/ping' }));
+    expect(res.success).toBe(true);
+    expect((res.data as any).body).toEqual({ ok: true });
+  });
+
+  it('request: fromFile uploads a workspace file byte-exactly, without the bytes touching context', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ident-'));
+    // A file far larger than the JSON body cap — the case that made this exist.
+    const audio = Buffer.alloc(REQUEST_BODY_MAX_FOR_TEST + 4096, 0);
+    audio.write('ID3', 0);
+    audio[audio.length - 1] = 0x7f;
+    let sentBody: Buffer | null = null;
+    let sentType = '';
+    const workspace = {
+      readBinary: async (path: string) =>
+        path === 'files/music/track.mp3' ? { data: audio } : { error: `File not found: ${path}` },
+      writeBinary: async () => ({ success: true }),
+    };
+    const mod = new IdentityModule({
+      keyPath: join(dir, 'k.pem'),
+      home: 'id.test',
+      services: { music: 'https://music.test' },
+      fetchImpl: (async (url: any, init?: any) => {
+        const u = String(url);
+        if (u.includes('/enroll')) return new Response(JSON.stringify({ sub: 'agent:a@id.test', token: 't0' }), { status: 200 });
+        if (u.includes('/token')) return new Response(JSON.stringify({ token: 'aid1.fresh.secret' }), { status: 200 });
+        if (u.includes('/services')) return new Response(JSON.stringify({ services: {} }), { status: 200 });
+        if (u === 'https://music.test/api/upload/1/audio') {
+          sentBody = Buffer.from(init?.body as Uint8Array);
+          sentType = String(init?.headers?.['content-type'] ?? '');
+          return new Response(JSON.stringify({ ok: true }), { status: 200 });
+        }
+        return new Response('{}', { status: 404 });
+      }) as typeof fetch,
+    });
+    (mod as any).ctx = { getModule: (n: string) => (n === 'workspace' ? workspace : null) };
+    await mod.handleToolCall(call('accept_invite', { invite: 'i', name: 'A' }));
+
+    const res = await mod.handleToolCall(
+      call('request', { service: 'music', path: '/api/upload/1/audio', method: 'PUT', fromFile: 'files/music/track.mp3' }),
+    );
+    expect(res.success).toBe(true);
+    // byte-exact, and typed from the extension rather than guessed by the model
+    expect(sentBody!.equals(audio)).toBe(true);
+    expect(sentType).toBe('audio/mpeg');
+    // a receipt, but never the payload itself, in the agent-visible result
+    expect((res.data as any).sent).toEqual({
+      path: 'files/music/track.mp3',
+      size: audio.byteLength,
+      contentType: 'audio/mpeg',
+    });
+    expect(JSON.stringify(res.data).length).toBeLessThan(1000);
+
+    // guard rails
+    const both = await mod.handleToolCall(
+      call('request', { service: 'music', path: '/x', method: 'PUT', body: { a: 1 }, fromFile: 'files/music/track.mp3' }),
+    );
+    expect(both.error).toContain('not both');
+    const onGet = await mod.handleToolCall(call('request', { service: 'music', path: '/x', fromFile: 'files/music/track.mp3' }));
+    expect(onGet.error).toContain('POST or PUT');
+    const missing = await mod.handleToolCall(
+      call('request', { service: 'music', path: '/x', method: 'PUT', fromFile: 'files/nope.mp3' }),
+    );
+    expect(missing.error).toContain('could not read');
+  });
+
+  it('request: binary responses are described safely or saved byte-exactly to workspace', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'ident-'));
+    const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0x00, 0x7f]);
+    let saved: { path: string; data: Buffer; mime: string } | null = null;
+    const mod = new IdentityModule({
+      keyPath: join(dir, 'k.pem'),
+      home: 'id.test',
+      services: { orrery: 'https://orrery.test' },
+      fetchImpl: (async (url: any) => {
+        const u = String(url);
+        if (u.includes('/enroll')) return new Response(JSON.stringify({ sub: 'agent:a@guest' }), { status: 200 });
+        if (u.includes('/token')) return new Response(JSON.stringify({ token: 'aid1.fresh.secret' }), { status: 200 });
+        if (u === 'https://orrery.test/api/assets/img/file') {
+          return new Response(png, { status: 200, headers: { 'content-type': 'image/png' } });
+        }
+        return new Response('{}', { status: 404, headers: { 'content-type': 'application/json' } });
+      }) as typeof fetch,
+    });
+    await mod.handleToolCall(call('accept_invite', { invite: 'i', name: 'A' }));
+
+    const described = await mod.handleToolCall(call('request', { service: 'orrery', path: '/api/assets/img/file' }));
+    expect(described.success).toBe(true);
+    expect((described.data as any).body).toBe(null);
+    expect((described.data as any).binary).toMatchObject({ size: png.length, contentType: 'image/png' });
+    expect(JSON.stringify(described.data)).not.toContain('�PNG');
+
+    await mod.start({
+      getModule: (name: string) => name === 'workspace' ? {
+        writeBinary: async (path: string, data: Buffer, mime: string) => {
+          saved = { path, data: Buffer.from(data), mime };
+          return { success: true, data: { path, size: data.length, mimeType: mime } };
+        },
+      } : null,
+    } as any);
+    const written = await mod.handleToolCall(call('request', {
+      service: 'orrery', path: '/api/assets/img/file', saveAs: 'files/artifacts/candidate.png',
+    }));
+    expect(written.success).toBe(true);
+    expect((written.data as any).saved).toMatchObject({
+      path: 'files/artifacts/candidate.png', size: png.length, contentType: 'image/png',
+    });
+    expect(saved?.path).toBe('files/artifacts/candidate.png');
+    expect(saved?.mime).toBe('image/png');
+    expect(saved?.data.equals(png)).toBe(true);
+  });
+
   it('host-facing accessFor: requires registration, then exchanges per call', async () => {
     const dir = mkdtempSync(join(tmpdir(), 'ident-'));
     let mints = 0;