feat(dendrite): one registry, lifecycle and fork primitive for agents; admission, reader forks, the all-except scope and speech.locus (#232, #77, #270)

bench/dendrite/cache-acceptance.mjs

@@ -0,0 +1,180 @@
+/**
+ * Live acceptance run for the Dendrite rendering contract.
+ *
+ * The fork tests prove provider-formatted content identity up to the fork
+ * boundary. This script asks the real provider the question that test
+ * cannot: does a fork's FIRST request read the resident's cache?
+ *
+ *   phase 1  resident turn: writes the cache            (cache_creation ≈ prefix)
+ *   phase 2  resident turn: own reuse, the control      (cache_read ≈ prefix)
+ *   phase 3  fork at the boundary, first request        (cache_read ≈ prefix?)
+ *   phase 4  resident blocks in a tool call; a fork
+ *            derived mid-round, first request           (cache_read ≈ prefix?)
+ *
+ * Needs the local build (`npm run build`) and either ANTHROPIC_API_KEY, or
+ * GATE_TOKEN + GATE_URL for an Anthropic-compatible inference gateway.
+ *   node bench/dendrite/cache-acceptance.mjs [model]
+ * Nothing here prints the environment.
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Membrane, AnthropicAdapter, NativeFormatter } from '@animalabs/membrane';
+import { AgentFramework, AutobiographicalStrategy } from '../../dist/src/index.js';
+import { GateModule, until } from '../../dist/test/helpers/dendrite.js';
+
+const model = process.argv[2] ?? 'claude-sonnet-5-5';
+const viaGate = !!process.env.GATE_TOKEN;
+if (!viaGate && !process.env.ANTHROPIC_API_KEY) {
+  console.error('set ANTHROPIC_API_KEY, or GATE_TOKEN (+ GATE_URL) for a gateway');
+  process.exit(2);
+}
+const adapterConfig = viaGate
+  ? { apiKey: process.env.GATE_TOKEN, baseURL: process.env.GATE_URL ?? 'https://gate.animalabs.ai/anthropic' }
+  : {};
+
+const dir = mkdtempSync(join(tmpdir(), 'dendrite-cache-acceptance-'));
+const gates = new GateModule();
+// Native tools and roles, as residents run: the XML default is a prefill formatter, which Sonnet 5.5 rejects.
+const inner = new Membrane(new AnthropicAdapter(adapterConfig), { assistantParticipant: 'mira', formatter: new NativeFormatter() });
+
+// Record each request's shape next to the usage the provider reports for it.
+let phase = 'setup';
+const requests = [];
+const membrane = new Proxy(inner, {
+  get(target, prop, receiver) {
+    if (prop === 'streamYielding') {
+      return (request, options) => {
+        const built = new NativeFormatter().buildMessages(request.messages, {
+          participantMode: 'multiuser', assistantParticipant: request.assistantParticipant ?? 'mira', tools: request.tools,
+          systemPrompt: request.system, promptCaching: request.promptCaching ?? true,
+          cacheMarkers: request.cacheMarkers ?? 'membrane-system', cacheTtl: request.cacheTtl,
+        });
+        const marked = [];
+        built.messages.forEach((m, i) => {
+          const blocks = Array.isArray(m.content) ? m.content : [];
+          if (blocks.some((b) => b.cache_control)) marked.push(`${i}:${m.role}`);
+        });
+        const systemMarked = Array.isArray(built.system) && built.system.some((b) => b.cache_control);
+        requests.push({ phase, messages: request.messages.length, provider: built.messages.length, markers: `${systemMarked ? 'sys,' : ''}${marked.join(',') || 'none'}`, cacheMarkers: request.cacheMarkers ?? 'membrane-system', breakpoints: request.messages.filter((m) => m.cacheBreakpoint).length });
+        return target.streamYielding(request, options);
+      };
+    }
+    const value = Reflect.get(target, prop, receiver);
+    return typeof value === 'function' ? value.bind(target) : value;
+  },
+});
+
+// The production shape: a folding resident. Message cache breakpoints exist
+// only once there is a recall ladder (summaries) in the compiled view, so the
+// windows are small enough that this history folds; summaries are written by
+// the same model through the same route.
+const makeStrategy = () => new AutobiographicalStrategy({
+  compressionModel: model,
+  adaptiveResolution: true,
+  targetChunkTokens: 400,
+  recentWindowTokens: 1500,
+});
+
+const framework = await AgentFramework.create({
+  storePath: join(dir, 'store.chronicle'),
+  membrane,
+  agents: [{
+    name: 'mira',
+    model,
+    strategy: makeStrategy(),
+    systemPrompt: 'You are mira, a terse assistant used in an automated acceptance run. Follow instructions literally.',
+  }],
+  modules: [gates],
+  syncIntervalMs: 0,
+  maintenanceIntervalMs: 0,
+});
+
+const usage = []; // { phase, agent, input, cacheCreation, cacheRead }
+let completed = 0;
+framework.onTrace((event) => {
+  if (event.type === 'inference:usage') {
+    const u = event.tokenUsage;
+    usage.push({ phase, agent: event.agentName, input: u.input, cacheCreation: u.cacheCreation ?? 0, cacheRead: u.cacheRead ?? 0, output: u.output });
+  }
+  if (event.type === 'inference:completed') completed++;
+  if (event.type === 'inference:error') console.error('[inference:error]', JSON.stringify(event).slice(0, 400));
+});
+
+const cm = framework.getAgent('mira').getContextManager();
+// ~6k tokens of history: well past every model's minimum cacheable prefix.
+for (let i = 0; i < 40; i++) {
+  cm.addMessage(i % 2 ? 'mira' : 'user', [{ type: 'text', text: `Turn ${i}. ` + `The quick brown fox jumps over the lazy dog number ${i}. `.repeat(10) }]);
+}
+let ticks = 0;
+while (!cm.isReady()) { await cm.tick(); ticks++; }
+console.error(`history seeded; ${ticks} ticks to ready`);
+
+framework.start();
+const internals = framework; // pendingRequests is the same door the framework's own tests use
+async function residentTurn(text, label) {
+  phase = label;
+  cm.addMessage('user', [{ type: 'text', text }]);
+  const before = completed;
+  internals.pendingRequests.push({ agentName: 'mira', reason: 'acceptance', source: 'acceptance', timestamp: Date.now() });
+  await until(() => completed > before, `${label} to complete`, 60_000);
+}
+
+try {
+  await residentTurn('Reply with exactly one word: ready.', 'p1-resident-write');
+  await residentTurn('Reply with exactly one word: again.', 'p2-resident-reuse');
+
+  phase = 'p3-fork-at-boundary';
+  const forkA = await framework.deriveAgent({
+    name: 'fork-a',
+    from: 'mira',
+    strategy: makeStrategy(),
+    framing: [{ participant: 'user', content: [{ type: 'text', text: 'You are a fork of mira. Reply with exactly one word: forked.' }] }],
+  });
+  await framework.runEphemeralToCompletion(forkA.agent, forkA.contextManager);
+
+  // Mid-round: ask the resident for a tool call that blocks, derive while it waits.
+  phase = 'p4-resident-tool-call';
+  cm.addMessage('user', [{ type: 'text', text: 'Call the tool test--wait once with input {"gate": "g1"}. Say nothing else.' }]);
+  internals.pendingRequests.push({ agentName: 'mira', reason: 'acceptance', source: 'acceptance', timestamp: Date.now() });
+  let midRound = true;
+  try {
+    await until(() => gates.entered.has('g1'), 'mira to block in test--wait', 60_000);
+  } catch {
+    midRound = false;
+    console.error('mira did not call the tool; phase 4 skipped');
+  }
+  if (midRound) {
+    phase = 'p4-fork-mid-round';
+    const forkB = await framework.deriveAgent({
+      name: 'fork-b',
+      from: 'mira',
+      strategy: makeStrategy(),
+      framing: [{ participant: 'user', content: [{ type: 'text', text: 'Reply with exactly one word: forked.' }] }],
+    });
+    await framework.runEphemeralToCompletion(forkB.agent, forkB.contextManager);
+    phase = 'p4-resident-finish';
+    const before = completed;
+    gates.release('g1');
+    await until(() => completed > before, 'mira to finish her turn', 60_000);
+  }
+} finally {
+  await framework.stop();
+  rmSync(dir, { recursive: true, force: true });
+}
+
+console.log(`model: ${model}  route: ${viaGate ? 'gateway' : 'direct'}`);
+console.log('phase                      agent   msgs  input  cache_creation  cache_read  markers');
+for (const u of usage) {
+  const r = requests.find((q) => q.phase === u.phase);
+  if (!r) continue; // a tool-result continuation reports cumulative stream usage; not a request of its own
+  console.log(`${u.phase.padEnd(26)} ${u.agent.padEnd(7)} ${String(r?.messages ?? '?').padStart(4)} ${String(u.input).padStart(6)} ${String(u.cacheCreation).padStart(15)} ${String(u.cacheRead).padStart(11)}  ${r ? `${r.cacheMarkers} bp=${r.breakpoints} ${r.markers}` : ''}`);
+}
+const by = (p) => usage.find((u) => u.phase === p);
+const control = by('p2-resident-reuse')?.cacheRead ?? 0;
+for (const p of ['p3-fork-at-boundary', 'p4-fork-mid-round']) {
+  const u = by(p);
+  if (!u) continue;
+  const ratio = control ? (u.cacheRead / control) : 0;
+  console.log(`${p}: cache_read is ${(ratio * 100).toFixed(1)}% of the resident's own reuse (${u.cacheRead} / ${control})`);
+}

changelog.d/author-named.fixed.md

@@ -0,0 +1,13 @@
+- A channel message is stored as the model reads it: `author: body`. MCPL's
+  `channels/incoming` carries the author as a field and the body alone as
+  content; the framework stored the body under the anonymous participant
+  `user` with the author in metadata, and nothing between the store and the
+  wire wrote the name, so a spec-shaped server's message reached the model
+  as `user: <text>` with the author nowhere (Weft's rig, 2026-10-13). A
+  server that renders `Name: body` into the text itself (portal-mcpl) is
+  left as it is: the rule is idempotent, so the name appears once whichever
+  shape a server sends. The author stays in `metadata.author` as the
+  structured record. Exported as `presentAuthor` / `authorLine`.
+- A tune-out release line and the reader fork's backlog name an author
+  once. Both read `metadata.author`, so a message whose text a server had
+  already prefixed was shown as `Name: Name: body`.

changelog.d/dendrite-admission.added.md

@@ -0,0 +1,19 @@
+- The admission stage (Dendrite §D, issue #232 §3.5): every inbound channel
+  message and push event passes one decision — captured, recipients, body or
+  hold, wake, locus — before anything acts on it (`src/admission/admit.ts`,
+  traced as `admission:decided`). The wake gate runs after the hold, so a
+  held message never forms a debounce batch; for a held message it is only
+  probed, and that verdict preconditions the reader's wake. Gate batches
+  re-check the hold at delivery (`gate:held-dropped`).
+- `speech.locus` (`'delivery'` | `'latest-inbound'`): where plain prose goes
+  when nothing names a destination. The default `'delivery'` is the §3
+  carve-out: only the waking delivery, a fork's home or a channel the agent
+  opened this turn sets the locus; incoming traffic never moves it, between
+  turns or mid-turn; a turn without one keeps its prose private with a
+  `[routing]` notice. `'latest-inbound'` restores the previous rule.
+- Tune-out without a reader (#232 §3.3): the coordinator exists whenever
+  MCPL channels do, a persisted epoch is always resumed and released, and a
+  tune-out without a subconscious is a silent hold. `tuneOut.enabled` offers
+  `tune_out` to residents when no reader is configured.
+- `tune_out` and `cancel_tuneout` take `serverId`; a channel id that exists
+  on several servers is refused as ambiguous.

changelog.d/dendrite-admission.changed.md

@@ -0,0 +1,13 @@
+- `ChannelRegistry` no longer evaluates the wake gate or sets the publish
+  locus at ingestion: `shouldTriggerInference` is the per-server veto only,
+  and the framework reports delivered messages through `noteDelivered` after
+  admission. `channel_publish` without a `channelId` goes to the calling turn's
+  locus, else a conversation fork's home channel, else the turn's trigger
+  channel, else the registry's default, which an ephemeral agent (one
+  `createEphemeralAgent` or `resumeAgent` made, derivations included) or a
+  turn with no channel by design (`noChannel`, or a heartbeat) doesn't
+  take; the call is refused when none of these names a channel.
+- `TuneOutCoordinator.onIncoming` is split into `holdFor` (the pure lookup
+  admission uses) and `recordHeld` (the bookkeeping that follows a hold);
+  `cancel` takes the lifecycle state to return to; `enter` no longer
+  requires a reader.

changelog.d/dendrite-admission.fixed.md

@@ -0,0 +1,13 @@
+- Issue #232 §2 tune-out gaps, each with a regression test (gaps 1 to 10 on
+  the loopback MCPL server in `test/admission-e2e.test.ts`, gap 11 in
+  `test/tune-out-dump-fit.test.ts`): tuning out a DM now holds it
+  (1); held traffic never moves the speech locus (2); a debounced mention in
+  a tuned-out channel wakes the reader, not the resident (3); a release names
+  non-text blocks instead of dropping them (4); a held message that arrives
+  mid-turn is stored, never injected into the live turn (5); a release left
+  in the deferred queue is durable and re-wakes the resident at boot (6);
+  held messages still deferred at cancel are in the release (7); channel ids
+  resolve server-qualified (8); `channel_close` on a tuned-out channel is
+  refused, and the tune-out's cancel releases (9); the hold machinery runs
+  without a reader (10); the truncation note names a history tool the
+  resident has, or none (11).

changelog.d/dendrite-all-except.added.md

@@ -0,0 +1,21 @@
+- The all-except scope (issue #232 §3.2; focus folded into tune-out):
+  `tune_out` with `scope: 'all-except'`, or its alias `focus`, holds every
+  channel except one — DMs and channels registered later included — for a
+  mandatory `durationSeconds`. A turn with no delivery of its own speaks into
+  the excepted channel. `mode: 'check'` reports held counts per channel and
+  peeks one channel without releasing; release is per channel, each capped.
+  A per-channel epoch takes precedence; the reader may end the scope;
+  exhausting the reader's wake budget pauses reader wakes rather than ending
+  the hold (`tune-out:wake-budget-paused`); closing the excepted channel ends
+  it. Listed by `listPolicyEpochs()` as a tune-out epoch with
+  `scope: { kind: 'all-except', except }`.
+  Entry and release are announced in the excepted channel as one bracketed
+  line each under the resident's name (`tuneOut.announce`, default true;
+  traced `tune-out:announced` / `tune-out:announce-failed`).
+  Its end time and cadence hold any length: both run on timers no longer
+  than one holds, as a channel's tune-out does since 0.22.3, so a hold or a
+  cadence past 24.8 days ends or ticks when it should rather than at once.
+  `focus` reads its options as `tune_out` does: a value that gives no finite
+  number is refused, naming it, before anything changes; a numeric string is
+  read as its number; a `null` option counts as left out; and the duration
+  is still required.

changelog.d/dendrite-cache-acceptance.added.md

@@ -0,0 +1,9 @@
+- `bench/dendrite/cache-acceptance.mjs`: a live acceptance run for the Dendrite
+  rendering contract — a folding resident, a fork at the boundary and a fork
+  derived mid-tool-call, each request's `cache_creation`/`cache_read` against the
+  resident's own reuse. Measured 2026-10-10 on Claude Sonnet 5.5 (one model, one
+  route, a synthetic 40-message history): the fork at the boundary read 10,193
+  cached tokens and wrote 29; the fork derived mid-tool-call read 10,230 and
+  wrote 152; the resident's own reuse read 10,173. Reuse follows the cache markers
+  the strategy emits (autobiographical: messages; passthrough: system and
+  tools only).

changelog.d/dendrite-derivation-notice.added.md

@@ -0,0 +1,13 @@
+- A derived agent's source is told of it (#270, for Linn): by default every
+  derivation puts one host-framed `[Agent lifecycle: … was derived from you as a …]`
+  line in the context of the agent it was made from — the fork's name and
+  kind, whose weights run it, what it inherits, where its result goes and
+  what ends it; a resumption says so. Stamped `kind: 'agent-lifecycle'`
+  with the record's fields under `dendrite`. No wake; a host's
+  `dendrite.derivationNotice` can replace the line or send none. The fork
+  never inherits the notice about itself; an ended source is told nothing.
+  After `dendrite.collapseDerivationNoticesAfter` derivations of one kind
+  from one agent (default 10; 0 never collapses), the source hears a count
+  line every so many instead, with the latest described and
+  `dendrite.collapsed: { count, sinceLastNote }`; every derivation still
+  emits its `dendrite:agent-created` trace.

changelog.d/dendrite-derive.added.md

@@ -0,0 +1,7 @@
+- `deriveAgent({ name, from, mode?, solve?, strategy?, config?, framing?, resultTo?, ... })` derives a bounded agent from a live one: the parent's context at a checkpoint, a private continuation, and — unless overridden — the parent's whole configuration (model, thinking, cache TTL, provider params, system prompt, tools, live context budget). The parent keeps running. `mode: 'shared'` (default) gives the child the parent's messages and fold state through shared storage on a Chronicle branch of its own: nothing is copied, the child folds with the parent's memory tree, and neither can alter what the other reads. It requires `@animalabs/chronicle` with `JsStore.view` and `@animalabs/context-manager` with `ContextManager.derive`, and is refused with a clear error, never silently downgraded, where they are missing. `mode: 'copy'` is the historical compiled-context copy and works with the published packages. `solve: 'fresh'` deliberately re-solves the inherited context instead of reusing the parent's rendering. See `docs/dendrite.md`.
+- `AgentConfig.selfParticipants` and `AgentConfig.presentAs`: model-facing role assignment at request assembly. Stored participants named in `selfParticipants` are presented as the agent's own assistant turns, under `presentAs` (default: its name). Stored authorship is never rewritten. A shared-inheritance fork uses these so its parent's turns read as its own history and its request shares the parent's provider prefix.
+- `AgentConfig.denyToolsAtDispatch`: tools that stay advertised but are refused when the agent calls them, so a derived agent can be restricted without changing the tool block at the front of its request.
+- `resumeAgent(name, config)` brings an ended bounded job back as a new incarnation of the same identity on the context it left (its namespace, or a fork's own branch) — after a stop, a failure, or a restart. `inspectAgentContext(name, { atSequence? })` returns a snapshot of a live agent's context at the head or an earlier sequence without affecting the agent, or the context an ended agent left.
+- `deriveAgent({ inheritRefusals: true })` also inherits the parent's compression-refusal ledger (default off); the choice is recorded as `inherit.refusals` on the agent record and in `dendrite:agent-created`.
+- `getPendingAssistantRound(name)` returns the assistant turn an agent has produced but not yet stored (its tool calls in flight), for hosts that derive an agent from inside a tool call.
+- A derived agent that inherits its parent's tools shows the parent's tool presentation (resident-edited visibility and descriptions); only the owner can edit it.

changelog.d/dendrite-derive.changed.md

@@ -0,0 +1,2 @@
+- `createEphemeralAgent(config, spec)` with `spec.inherit.mode: 'shared'` opens the agent's context by derivation from the named agent instead of a fresh isolated namespace.
+- A mid-turn injected message whose participant is one of the receiving agent's `selfParticipants` is no longer injected into the live stream (it would render as an assistant turn); it stays window-only, as a message under the agent's own name already did.