@animalabs/agent-framework 0.28.0 → 0.30.0

package/src/tune-out/tools.ts

@@ -1,3 +1,6 @@
+import type { ContentBlock } from '@animalabs/membrane';
+import { authorLine } from '../author-presentation.js';
+import type { StoredMessage } from '@animalabs/context-manager';
 /**
  * The subconscious's tool surface (issue #77).
  *
@@ -51,11 +54,13 @@ export const SUBCONSCIOUS_TOOLS: ToolDefinition[] = [
       'End the tune-out on a channel now — use when something needs the ' +
       'resident\'s full attention. The diverted backlog is delivered to ' +
       'them (capped), and normal attention resumes. Add your own note in ' +
-      '`text`; it arrives alongside the backlog, in your voice.',
+      '`text`; it arrives alongside the backlog, in your voice. If you were ' +
+      'started to read one hold, you can end only that hold.',
     inputSchema: {
       type: 'object',
       properties: {
-        channelId: { type: 'string' },
+        channelId: { type: 'string', description: 'A tuned-out channel, or a channel held by the all-except hold (which ends that hold, unless scope is "channel").' },
+        scope: { type: 'string', enum: ['channel', 'all-except'], description: '"all-except" ends the all-except hold outright; "channel" ends only the channel\'s own tune-out.' },
         text: {
           type: 'string',
           description: 'Your accompanying note to the resident (optional).',
@@ -86,10 +91,14 @@ export const SUBCONSCIOUS_TOOLS: ToolDefinition[] = [
   {
     name: 'speak_in_channel',
     description:
-      'Post a message into a tuned-out channel, clearly as yourself (not ' +
-      'as the resident). Use sparingly — e.g. to tell someone the resident ' +
-      'is tuned out and when to expect them. Disabled unless the resident\'s ' +
-      'configuration allows it.',
+      'Post a message into a tuned-out channel, in your own words and ' +
+      'clearly as yourself (not as the resident); it goes out through the ' +
+      'resident\'s publish path, so the channel sees it under their account. ' +
+      'Use sparingly — e.g. to tell someone the resident is tuned out and ' +
+      'when to expect them. If you were started to read one hold, you can ' +
+      'post only into a channel that hold still holds, and a post made once ' +
+      'it has ended is refused; your report can say it instead. Disabled unless ' +
+      'the resident\'s configuration allows it.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -102,11 +111,42 @@ export const SUBCONSCIOUS_TOOLS: ToolDefinition[] = [
 ];
 
 /**
- * Configuration for the subconscious resident (FrameworkConfig.subconscious).
+ * Configuration for the subconscious (FrameworkConfig.subconscious). Two
+ * shapes, by `reader`:
+ *
+ * - `'persistent'` (default): one persistent side-agent with an isolated
+ *   slot and a windowed read-only view of the residents' timeline, as
+ *   issue #77 built it. Its `systemPrompt` is a system prompt.
+ * - `'forks'`: a succession of forks of the resident (Dendrite). Each
+ *   cadence tick, coalesced wake and cancel derives a short-lived fork at
+ *   the resident's head — the resident's whole prefix, its refusals
+ *   included, ending with it — hands it the traffic held since the last
+ *   look as the first message after the fork point, and lets it report
+ *   back as attributed mail. No agent persists between invocations;
+ *   dispositions do, in the coordinator's state. Its `voice` is framing,
+ *   not a system prompt, and residents are shown the reader's four tools
+ *   in their tool block (refused at dispatch), so the fork's request is
+ *   the resident's up to the fork point.
  */
-export interface SubconsciousConfig {
+export type SubconsciousConfig = PersistentReaderConfig | ForkReaderConfig;
+
+interface SubconsciousConfigBase {
   /** Master switch. */
   enabled: boolean;
+  /**
+   * Allow speak_in_channel. Default false until the voice block has passed
+   * its canary round. A reader's post goes out through the resident's own
+   * publish path, so the channel sees it under the resident's account, in
+   * the reader's words; nothing in the request names the reader. With it
+   * off, a reader fork can post nowhere: every tool but its own is refused
+   * at dispatch (the block it is shown stays the resident's, for the
+   * shared prefix).
+   */
+  allowChannelSpeech?: boolean;
+}
+
+export interface PersistentReaderConfig extends SubconsciousConfigBase {
+  reader?: 'persistent';
   /**
    * Registry + participant name. Default 'Subconscious' — following the
    * Context Manager precedent: a title-case functional voice, not an
@@ -124,9 +164,110 @@ export interface SubconsciousConfig {
    * person toward the resident. Canary before fleet use (issue #77).
    */
   systemPrompt: string;
-  /** Allow speak_in_channel. Default false until the voice block has
-   *  passed its canary round. */
-  allowChannelSpeech?: boolean;
   /** WindowedPassthroughStrategy re-anchor fraction (default 0.5). */
   reAnchorFraction?: number;
 }
+
+export interface ForkReaderConfig extends SubconsciousConfigBase {
+  reader: 'forks';
+  /**
+   * Whose weights run the fork. Required, never defaulted: a fork holds the
+   * resident's whole prefix, and which model reads it is the one fact the
+   * resident's consent names. The resident's own model is the copy; another
+   * model is allowed when stated here. `create` refuses the omission.
+   */
+  model: string;
+  /**
+   * The reader's voice block — report-shaped, second person toward the
+   * resident, co-authored with them. Delivered as the first message after
+   * the fork point, with the notice, the standing dispositions and the held
+   * traffic; never a system prompt.
+   */
+  voice: string;
+  /**
+   * A fresh context strategy instance for each fork, same class and
+   * configuration as the resident's, so the fork reuses the resident's fold
+   * state and rendering. Required unless the resident runs a passthrough
+   * strategy.
+   */
+  strategyFactory?: () => import('@animalabs/context-manager').ContextStrategy;
+  /** Idle timeout for one reader fork (default 10 minutes). */
+  forkIdleTimeoutMs?: number;
+  /**
+   * How a reader fork is prompted: the content of the one message it
+   * receives after the fork point. Default `defaultReaderFraming`. The
+   * framework stores whatever this returns as a user message with
+   * `metadata.kind = 'tune-out-reader-framing'`; the notice, voice,
+   * dispositions and held traffic are in the context, and nothing else
+   * about the fork's prompt is fixed by the path.
+   */
+  framing?: (context: ReaderFramingContext) => ContentBlock[];
+}
+
+/** What a reader fork's framing is built from. */
+export interface ReaderFramingContext {
+  /** The resident the fork was derived from. */
+  resident: string;
+  /** The fork's own name. */
+  fork: string;
+  /** `ForkReaderConfig.voice`. */
+  voice: string;
+  channelId: string;
+  epochId: string;
+  trigger: 'cadence' | 'wake' | 'cancel';
+  /** The coordinator's notice for this invocation (`[Tune-out wake: …]` etc.). */
+  notice: string;
+  /** Standing dispositions recorded on the epoch, or null. */
+  dispositions: string | null;
+  /**
+   * The traffic held since the last look, oldest first; empty when nothing
+   * arrived. It includes the messages still queued behind the resident's
+   * turn (admitted, not yet stored), last: their ids are held handles and
+   * their sequences provisional, as a module's held rows are.
+   */
+  backlog: StoredMessage[];
+  /** How many of `backlog`'s last entries are still queued behind the resident's turn. Absent is none. */
+  queuedCount?: number;
+}
+
+/**
+ * The default reader-fork framing: a header naming the channel, epoch and
+ * trigger; the notice; the voice block; standing dispositions if any; then
+ * the held traffic as `author: text` lines with non-text blocks (images,
+ * documents) preserved in order as the source supplied them.
+ */
+export function defaultReaderFraming(ctx: ReaderFramingContext): ContentBlock[] {
+  const header =
+    `[Tune-out reader — ${ctx.channelId}, epoch ${ctx.epochId.slice(0, 8)}, ${ctx.trigger}]\n` +
+    `${ctx.notice}\n\n${ctx.voice}` +
+    (ctx.dispositions ? `\n\n[Standing dispositions]\n${ctx.dispositions}` : '');
+  const content: ContentBlock[] = [{ type: 'text', text: header }];
+  if (ctx.backlog.length === 0) {
+    content.push({ type: 'text', text: '\n[Nothing new has been held since your last look.]' });
+    return content;
+  }
+  const n = ctx.backlog.length;
+  const q = Math.min(Math.max(0, Math.floor(ctx.queuedCount ?? 0)), n);
+  const lines: string[] = [`\n[Held in ${ctx.channelId} since your last look: ${n} message${n === 1 ? '' : 's'}]`];
+  const flush = () => {
+    if (lines.length > 0) content.push({ type: 'text', text: lines.splice(0).join('\n') });
+  };
+  const which = q === n ? (q === 1 ? 'It' : 'They') : (q === 1 ? 'The last one' : `The last ${q}`);
+  const queuedNote = `[${which} arrived while ${ctx.resident}'s turn was running, so ${q === 1 ? 'it is' : 'they are'} still queued, not yet stored.]`;
+  for (const [i, message] of ctx.backlog.entries()) {
+    if (q > 0 && i === n - q) lines.push(queuedNote);
+    const author = (message.metadata as { author?: { name?: string } } | undefined)?.author?.name ?? message.participant;
+    const text = message.content
+      .filter((b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text')
+      .map((b) => b.text)
+      .join('\n');
+    lines.push(authorLine(author, text));
+    const media = message.content.filter((b) => b.type !== 'text');
+    if (media.length > 0) {
+      flush();
+      content.push(...media);
+    }
+  }
+  flush();
+  return content;
+}

package/src/types/agent.ts

@@ -55,13 +55,15 @@ export interface AgentConfig {
    * Enforced at dispatch for registered agent callers; omitted means 'all'.
    * - 'all': all available tools
    * - string[]: exact tool names, including module--utility names for utilities.
-   * Utilities aren't tools of their own: an agent's model and its scripts are
-   * offered them only through 'utils', whose run checks the utility's own
-   * name. An agent that should use a utility lists both 'utils' and
-   * 'module--utility'. The name alone passes the dispatch check for any call
-   * by that name, whether the host makes it with executeToolCall on the
-   * agent's behalf or the model or a script makes it without being offered
-   * it. The slot is hidden when no utility is permitted.
+   * Utilities and the host's other rarely-used tools are in the host's
+   * built-in toolset ("settings"), out of the tool list: the model reaches
+   * them with toolsets--open {toolset:"settings"} and toolsets--act, each
+   * checked under the tool's own name. An agent that should use a utility
+   * from its model lists 'toolsets--open', 'toolsets--act' and
+   * 'module--utility' (an agent without the two meta-tools keeps every other
+   * tool in its list, but no utility). The name alone passes the dispatch
+   * check for any call by that name, whether the host makes it with
+   * executeToolCall on the agent's behalf or the model or a script makes it.
    * Trusted module calls are exempt. Genuinely unidentified public callers,
    * including unknown legacy names, remain unrestricted. Framework-created
    * identities have tool authority only while registered.
@@ -338,6 +340,34 @@ export interface AgentConfig {
    */
   proseRouting?: 'locus' | 'explicit' | 'hybrid' | 'disabled';
 
+  /**
+   * Stored participants that are this agent's own voice, in addition to its
+   * name: their turns are presented to the model as this agent's assistant
+   * turns. A derived agent sets this to the agent it inherited from, so the
+   * parent's turns read as its own history. Model-facing role assignment
+   * only, applied at request assembly — stored authorship is never rewritten.
+   */
+  selfParticipants?: string[];
+
+  /**
+   * The participant name this agent's own turns are presented under at
+   * request assembly. Defaults to `name`. A derived agent that should share
+   * its parent's provider prefix sets the parent's name, so the two
+   * requests are identical in formatters that render participant names as
+   * well as in those that only assign roles. New turns are still STORED
+   * under the agent's own name.
+   */
+  presentAs?: string;
+
+  /**
+   * Tools refused when this agent calls them, although they stay advertised.
+   * Restricts a derived agent without changing the tool block at the front
+   * of its request — removing a tool from `allowedTools` instead would
+   * change those bytes and forfeit the provider prefix it shares with its
+   * parent.
+   */
+  denyToolsAtDispatch?: string[];
+
   /**
    * Fail-closed containment for a text response whose entire visible prose is
    * an invocation-shaped wrapper naming a tool registered on that exact turn.
@@ -580,8 +610,9 @@ export interface InferenceRequest {
    * the turn's auto-published plain-text speech here so a single TRUNK agent
    * replies in the channel it is answering — not the process-global most-recent-
    * inbound locus, which a concurrent message elsewhere can hijack (item-3
-   * redux). Undefined for non-channel wakes (heartbeat, timers, module events),
-   * which correctly fall back to the global default channel, except an
+   * redux). Undefined for non-channel wakes (heartbeat, timers, module events).
+   * A heartbeat's turn takes no channel at all, and holds its plain speech as
+   * drafts; any other falls back to the global default channel, except an
    * ephemeral run's (a subagent's), which takes no global fallback.
    */
   channelId?: string;
@@ -604,6 +635,17 @@ export interface InferenceRequest {
    * it starts. Hosts don't set it.
    */
   autoContinueRun?: AutoContinueRun;
+  /**
+   * Framework-set: whether this wake's turn is a heartbeat's, which has no
+   * channel and holds its plain speech as drafts. True on a wake that
+   * continues a heartbeat's turn with no channel of its own (an autoContinue
+   * continuation, a bounce's resend wake, a ` !` continuation, and a re-arm,
+   * which copies its trigger), and on a merged batch whose causes include a
+   * heartbeat's wake and name no channel; false on a merged batch with none,
+   * so the batch's first request doesn't decide it. Unset, a wake is a
+   * heartbeat's when its `source` is `heartbeat`. Hosts don't set it.
+   */
+  heartbeatTurn?: boolean;
   /**
    * True when the triggering message explicitly addressed the agent (mention,
    * reply-to-bot, DM — `chat:addressed` in MCPL RFC-001 terms). When a wake

package/src/types/framework.ts

@@ -116,6 +116,48 @@ export type ProviderHoldHook = (
 ) => ProviderHold | undefined;
 
 export interface FrameworkConfig {
+  /**
+   * Dendrite agent lifecycle options.
+   */
+  dendrite?: {
+    /**
+     * When an agent ends while task work it spawned is still running, the
+     * orphan is always told. With this on (the default), the first agent
+     * that could adopt it — its nearest live ancestor, else the primary —
+     * also receives a factual notice, which is what makes the reparenting
+     * offer visible to a model. Turn it off when the host makes adoption
+     * decisions itself from the `dendrite:agent-orphaned` trace.
+     */
+    announceOrphans?: boolean;
+    /**
+     * By default every derivation tells the agent it was made from, in one
+     * host-framed line. After this many derivations of one kind from one
+     * agent, that agent hears a count line every so many instead of a line
+     * per fork, so a reader loop that forks a hundred times a session doesn't
+     * fill its source's context with stamps; every derivation still emits its
+     * `dendrite:agent-created` trace. Default 10; 0 never collapses.
+     */
+    collapseDerivationNoticesAfter?: number;
+    /**
+     * A host's say over each derivation, ephemeral spawn and resume, before the
+     * agent or its new incarnation exists, given the spec of what is about to
+     * exist (name, kind, spawner, route, inheritance, metadata). A shared
+     * derivation's record then adds the child's branch, and names the
+     * parent's namespace as its own. Return nothing to allow, or `{ refuse }`
+     * with the reason, which the caller gets as the error. The framework
+     * attaches no meaning to the decision: consent, budget, hours, a mind's
+     * standing instruction, a use not yet imagined are all the host's.
+     */
+    beforeDerive?: (spec: import('../dendrite/types.js').AgentSpec) => void | { refuse: string };
+    /**
+     * What an agent is told when something is derived from it. Given the
+     * record, the agent it was derived from and the framework's default line,
+     * return the text to add, or null to add nothing. Absent, the default
+     * line is used. The `dendrite:agent-created` trace is emitted either way.
+     */
+    derivationNotice?: (record: import('../dendrite/types.js').AgentRecord, from: string, defaultText: string) => string | null;
+  };
+
   /**
    * The subconscious resident (issue #77): a persistent side-agent that
    * receives diverted traffic from tuned-out channels and reports to the
@@ -123,6 +165,46 @@ export interface FrameworkConfig {
    */
   subconscious?: import('../tune-out/tools.js').SubconsciousConfig;
 
+  /**
+   * Tune-out without a reader (issue #232 §3.3). The hold machinery always
+   * runs when MCPL channels exist, so a persisted epoch is resumed and
+   * released whatever the configuration; this switch only decides whether
+   * residents are offered `tune_out` when no reader is configured. Without
+   * a reader a tune-out is a silent hold: no cadence, no wake budget,
+   * mentions are acknowledged, the backlog is released on cancel.
+   */
+  tuneOut?: {
+    /** Offer `tune_out` without a subconscious. Default: only with one. */
+    enabled?: boolean;
+    /**
+     * Announce the all-except scope in the excepted channel: one bracketed
+     * line under the resident's name when it opens (who, for how long) and
+     * one when it closes. Default true — a hold the room cannot see is the
+     * failure the scope exists to prevent. `false` keeps both quiet.
+     */
+    announce?: boolean;
+  };
+
+  /**
+   * Where a turn's plain prose lands when nothing names a destination
+   * (architecture channel, 2026-10-06: the §3 carve-out accepted by the
+   * residents).
+   *
+   * - `'delivery'` (default): the locus comes only from the delivery that
+   *   woke the turn, a conversation fork's home channel, or a channel the
+   *   agent opened during the turn. Incoming traffic never moves it — not
+   *   between turns, not mid-turn. A turn with no such locus keeps its
+   *   prose private, and says so in a `[routing]` notice.
+   * - `'latest-inbound'`: the previous rule. The most recent delivered
+   *   inbound message is a global fallback locus for turns without one, and
+   *   an addressed message injected mid-turn re-pins the turn's locus.
+   *
+   * Held traffic never moves the locus under either rule.
+   */
+  speech?: {
+    locus?: 'delivery' | 'latest-inbound';
+  };
+
   /**
    * IANA zone of the agent's wall clock: it renders wall-clock times for the
    * agent, and it sets where clock rows' boundaries fall (AgentConfig.clock,
@@ -160,6 +242,26 @@ export interface FrameworkConfig {
    */
   deferredWritesPath?: string;
 
+  /**
+   * The Dendrite agent registry's recovery file: its live records and the
+   * results it holds for delivery, written atomically and fsynced, and read
+   * first at boot. Defaults to `<storePath>/recovery/dendrite-registry.json`.
+   * Outside the chronicle for the reason `hostModePath` is: a branch switch
+   * or historical rollback would otherwise take back held results. Set
+   * explicitly when providing an app-owned `store` without `storePath`;
+   * without either, the registry persists only in the branch-local store,
+   * with a warning at create.
+   */
+  agentRegistryPath?: string;
+
+  /**
+   * The registry's ended-record log recovery file (its newest records, as
+   * many as a restart reads). Defaults to
+   * `<storePath>/recovery/dendrite-ended.json`; same rationale and fallback
+   * as `agentRegistryPath`.
+   */
+  agentRegistryEndedPath?: string;
+
   /** Emoji used for branch-awareness markers (default: 💤). */
   discordAwarenessEmoji?: string;
 
@@ -218,6 +320,50 @@ export interface FrameworkConfig {
    */
   providerHold?: ProviderHoldHook;
 
+  /**
+   * Delays before a turn whose retries ran out is sent again, in ms (default
+   * `[120000, 480000, 1920000]`: 2, 8 and 32 minutes), or `false` never to.
+   * When a persistent agent's turn ends exhausted on a transient failure (a
+   * server error, an overload, a rate limit, a network failure, or a timeout
+   * membrane marks retryable and not as a deadline it reports as run out, such
+   * as a 408 or a socket's ETIMEDOUT), its trigger is queued again after the
+   * first delay, as a wake of its own. It opens where the exhausted turn's
+   * plain speech was going: its locus, where a message mid-turn may have moved
+   * it, else its trigger channel. Carrying that channel, it ranks as addressed
+   * in a merged wake's choice of channel, so a newer ambient wake from
+   * elsewhere doesn't take it; an autoContinue continuation's still yields its
+   * channel to any wake's, as it does on main; a continuation's, such as a
+   * budget restart's, names no author. A re-arm that would have to guess a
+   * channel isn't sent again: one whose turn was woken for a channel id that
+   * names no one registered channel and never found one, and whose request
+   * names none of its own. A failure that states a wait is held for that wait
+   * first, as any turn's is, and a deadline ends the turn as before, whether
+   * the host set it or membrane marks one as run out: the runtime's or
+   * undici's on a sent request, the Anthropic adapter's watchdogs, or the
+   * Anthropic SDK's timeout, which covers its connect timeout too. Until one
+   * of the re-armed turn's rounds has run or had its tool calls cut off, its
+   * failure gets no retries from the error policy: on another transient
+   * failure the next delay follows, until the list runs out, and a failure of
+   * any other kind ends the re-arming. A wake for the agent while it waits
+   * starts its turn at once, with the re-armed trigger merged in. That turn is
+   * the wake's: the error policy retries its failures. A completed turn starts
+   * the count again, and so does a message said to the agent: not a system
+   * message or notice; not an edit, reaction or deletion, unless an edit is
+   * the first version of a message the agent sees; not a message its own view
+   * leaves out, such as one a tune-out holds from it; and not the agent's own
+   * schedule, the heartbeat's tick or reminder, a self-wake timer it set, or a
+   * script's wake. A notice a module or an MCPL server stores as a message
+   * counts. A message in the residents' shared slot counts for each resident
+   * that reads it. Any other wake leaves the count going on. A re-armed turn's
+   * transient failure writes no `[inference-failed]` marker unless a round of
+   * it ran or had its tool calls cut off; any other failure of it writes one.
+   * Each counts toward the hard-down streak. Ephemeral runs and conversation
+   * forks are never re-armed. The wait and the count are kept in memory:
+   * `stop()` drops them, and so does a restart. The wait isn't a turn, so
+   * `abortInference()` doesn't end it.
+   */
+  exhaustedTurnRearmMs?: number[] | false;
+
   /** Interval for periodic store sync in milliseconds (default: 1000ms, 0 to disable) */
   syncIntervalMs?: number;
 

package/src/types/module.ts

@@ -72,10 +72,11 @@ export type ModuleMessage = StoredMessage & {
    * True on a message a tune-out holds from the residents: one that arrived
    * in a tuned-out channel, stamped `metadata.tuneOut` as it came in. The
    * store keeps it, but no resident is shown the row itself: no resident's
-   * compiled view includes it, during the tune-out or after it, and a tool
-   * boundary of a turn alive when it arrived stores it without injecting it
-   * into the live turn. The subconscious reads it. Its text can still reach
-   * a resident in rows of their own, which aren't marked, such as the
+   * compiled view includes it, during the tune-out or after it, and a
+   * resident's tool boundary of a turn alive when it arrived stores it
+   * without injecting it into the live turn. The subconscious reads it. Its
+   * text can still reach a resident in rows of their own, which aren't
+   * marked, such as the
    * cancel's `<tuned-out-backlog>` row, with the text of the tune-out's newest
    * messages, up to `backlogCap` of them and as many as fit in one of the
    * residents' messages, the stored ones first and then those still held;
@@ -142,16 +143,27 @@ export interface Module {
 
   /**
    * Utilities: agent-invocable operations that deliberately do NOT get a
-   * first-class tool slot. Every tool schema taxes every inference; a
-   * capability used twice a month shouldn't. Utilities are listed, described,
-   * and invoked through the framework's single `utils` tool instead — same
-   * ToolDefinition shape, same un-prefixed names, and dispatch arrives at the
-   * SAME handleToolCall as getTools() output, so a tool migrates between
-   * surfaces by moving its definition from one list to the other and nothing
-   * else. Optional; omitting it means the module contributes no utilities.
+   * slot in the tool list. Every tool schema taxes every inference; a
+   * capability used twice a month shouldn't. Utilities belong to the host's
+   * built-in toolset ("settings"): an agent sees them with
+   * `toolsets--look {toolset:"settings"}` and calls them with
+   * `toolsets--act` once it has opened it. Same ToolDefinition shape, same
+   * un-prefixed names, and dispatch arrives at the SAME handleToolCall as
+   * getTools() output. Optional; omitting it means the module contributes no
+   * utilities.
    */
   getUtilities?(): ToolDefinition[];
 
+  /**
+   * Where one of this module's tools (a getTools() name, unprefixed) is
+   * presented: in the agent's tool list (`'header'`, the default), or in the
+   * host's built-in toolset (`'builtin'`), out of the tool list, opened with
+   * `toolsets--open {toolset:"settings"}` and called with `toolsets--act`.
+   * For tools an agent uses rarely: settings, administration, status reads.
+   * Optional; omitting it keeps every tool in the tool list.
+   */
+  toolPlacement?(toolName: string): 'header' | 'builtin' | undefined;
+
   /**
    * Handle a tool call.
    * Tool name is without module prefix.

package/src/types/trace.ts

@@ -887,6 +887,156 @@ export type TraceEvent =
       since?: number;
     })
 
+  /** A reader fork ended in prose without `deliver_summary`; its final prose was delivered as its report. */
+  | (TraceEventBase & {
+      type: 'tune-out:reader-prose-delivered';
+      agentName: string;
+      serverId: string;
+      channelId: string;
+      epochId: string;
+      chars: number;
+    })
+
+  /** Bounded work the host's stop() cut off: left live for the next boot to end as `host-restart`. */
+  | (TraceEventBase & {
+      type: 'dendrite:agent-interrupted';
+      agentName: string;
+      kind: string;
+      incarnation: number;
+      reason: 'host-stop';
+    })
+
+  /** A tune-out reader fork was derived for one invocation (subconscious.reader: 'forks'). */
+  | (TraceEventBase & {
+      type: 'tune-out:reader-fork';
+      agentName: string;
+      serverId: string;
+      channelId: string;
+      epochId: string;
+      trigger: 'cadence' | 'wake' | 'cancel';
+      /** Held messages the fork was handed, stored and queued. */
+      held: number;
+      /** Of those, the ones still queued behind the resident's turn. */
+      queued: number;
+    })
+
+  /**
+   * A tune-out reader fork threw: its framing, its derive or its run. One
+   * that failed before it reported gives its held messages back to the
+   * channel's backlog while the epoch still holds the channel (`returned`
+   * counts them), so the next reader for the channel is handed them.
+   */
+  | (TraceEventBase & {
+      type: 'tune-out:reader-fork-failed';
+      agentName: string;
+      serverId: string;
+      channelId: string;
+      epochId: string;
+      trigger: 'cadence' | 'wake' | 'cancel';
+      error: string;
+      /** Whether the fork had reported through `deliver_summary` before it failed. */
+      reported: boolean;
+      returned: number;
+    })
+
+  // Dendrite: agent registry and lifecycle.
+  // `agent-created` is the consent event: it names the kind of agent, what
+  // ends it, and what happens to it when its spawner ends.
+  | (TraceEventBase & {
+      type: 'dendrite:agent-created';
+      agentName: string;
+      kind: string;
+      /** Whose weights; `inherit.from` is whose context. */
+      model?: string;
+      incarnation: number;
+      lifetime: import('../dendrite/types.js').AgentLifetime;
+      spawnedBy?: string;
+      onParentEnd?: import('../dendrite/types.js').ParentEndPolicy;
+      resultTo?: import('../dendrite/types.js').ResultRoute;
+      inherit?: import('../dendrite/types.js').ContextInheritance;
+    })
+  | (TraceEventBase & {
+      type: 'dendrite:agent-ended';
+      agentName: string;
+      kind: string;
+      incarnation: number;
+      reason: string;
+      by?: string;
+      /** The agent that spawned it, when its record names one. */
+      spawnedBy?: string;
+    })
+  | (TraceEventBase & {
+      /** The last event a replay of create()'s traces delivers when the
+       *  buffer kept only their first 1,000: how many came after. */
+      type: 'dendrite:early-traces-dropped';
+      dropped: number;
+    })
+  | (TraceEventBase & {
+      type: 'dendrite:agent-orphaned';
+      agentName: string;
+      formerParent: string;
+      reason: string;
+      /** Agents offered as a new parent, nearest first. */
+      candidates: string[];
+    })
+  | (TraceEventBase & {
+      type: 'dendrite:agent-reparented';
+      agentName: string;
+      parent: string;
+      by?: string;
+    })
+  | (TraceEventBase & {
+      type: 'dendrite:activation-cancelled';
+      agentName: string;
+      by?: string;
+      reason?: string;
+    })
+  /** The message entered the recipient's store (not merely queued for it). */
+  | (TraceEventBase & {
+      type: 'dendrite:mail-delivered';
+      mailId: string;
+      kind: string;
+      from: string;
+      to: string;
+    })
+  /** Queued for the recipient's next boundary; `mail-delivered` follows when it lands. */
+  | (TraceEventBase & {
+      type: 'dendrite:mail-deferred';
+      mailId: string;
+      kind: string;
+      from: string;
+      to: string;
+    })
+  | (TraceEventBase & {
+      type: 'dendrite:mail-held';
+      mailId: string;
+      kind: string;
+      from: string;
+      to: string;
+      reason: string;
+    })
+  /**
+   * The admission stage's decision for one inbound event (Dendrite §D):
+   * who may receive it, whether it is held (the epoch id) or delivered,
+   * whether it may wake them, and the gate's verdict.
+   */
+  | (TraceEventBase & {
+      type: 'admission:decided';
+      lane: 'channel' | 'push';
+      serverId: string;
+      channelId?: string;
+      messageId: string;
+      recipients: string[];
+      held: string | null;
+      wake: boolean;
+      gatePass: boolean;
+    })
+  /** Batched gate events dropped at delivery because their channel is held now. */
+  | (TraceEventBase & {
+      type: 'gate:held-dropped';
+      dropped: number;
+      channels: Array<string | undefined>;
+    })
   // Inbound acceptance observation (mcpl/inbound-source.ts): an installed
   // InboundAcceptanceObserver threw. Delivery is unaffected; the observer's
   // own coverage is interrupted for that acceptance.