@animalabs/agent-framework 0.29.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

@@ -340,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.

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;
 

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.