@animalabs/agent-framework 0.31.0 → 0.33.0

package/src/types/agent.ts

@@ -258,17 +258,10 @@ export interface AgentConfig {
      *   `thinking-binding-loss` ops alert, once per incident and again if a
      *   call drops more. The provider reports drops only on a request that
      *   carries the drop control; without it, such a block is refused;
-     * - the agent is told, in a `[reasoning] <agent>:` system notice of kind
-     *   `reasoning-loss` stored for it as the framework's other notices are,
-     *   when a committing compile leaves out a stored reply's reasoning at a
-     *   change of the request's head, at a branch's first compile, or in a
-     *   fold or other change to an earlier message that takes a reply of the
-     *   current turn, and, with `dropBlock` set too, when the provider drops
-     *   blocks it can place as the agent's stored replies or the stream's
-     *   rounds, once per incident and again when a call drops more. The
-     *   framework hears compiles through `Agent.onThinkingStrip` from the
-     *   agent's first stream on, unless a host has set its own, so an agent
-     *   driven only through the direct API is never told.
+     * - the agent is told nothing of reasoning left out or dropped: no line
+     *   about the mechanics of its own memory or reasoning is put in its
+     *   context. Hosts can observe compiles' strips through
+     *   `Agent.onThinkingStrip`;
      * The record and the notes
      * vouch for requests as agent-framework hands them to membrane, so a
      * membrane `beforeRequest` hook that changes a request must change every
@@ -337,8 +330,29 @@ export interface AgentConfig {
    * - 'disabled': generated prose is never published. Only explicit tools may
    *   send externally; prose remains in Chronicle, and a turn that wrote plain
    *   speech ends with a private `[delivered] plain speech → no channel` receipt.
+   * - 'locked': unprefixed prose goes to one destination the agent chose, on
+   *   every turn, and nothing moves it automatically: not the channel that
+   *   woke the turn, not an addressed message, a heartbeat or channel_open.
+   *   Only the `prose_locus` tool moves it, to a channel or to drafts (held,
+   *   never posted unless the agent resends them). The choice persists
+   *   across turns and restarts. Until the agent first makes one,
+   *   `proseLock` is the destination. It governs routing through the channel
+   *   registry: a module that handles final speech itself (`onAgentSpeech`,
+   *   such as the in-process Discord module) receives it in every mode, this
+   *   one included. See docs/locked-prose-routing.md.
    */
-  proseRouting?: 'locus' | 'explicit' | 'hybrid' | 'disabled';
+  proseRouting?: 'locus' | 'explicit' | 'hybrid' | 'disabled' | 'locked';
+
+  /**
+   * Locked mode's destination until the agent chooses one with `prose_locus`:
+   * `"#channel"`, `"@person"`, a channel id, or `"drafts"`. Resolved as a
+   * `>>` target is, at each turn's start, so a channel its server hasn't
+   * registered yet resolves once it has; until it resolves, plain speech is
+   * held as drafts. Left out, plain speech is held as drafts until the agent
+   * chooses. The agent's own choice, once made, takes its place. Ignored in
+   * the other modes.
+   */
+  proseLock?: string;
 
   /**
    * Stored participants that are this agent's own voice, in addition to its
@@ -431,6 +445,55 @@ export interface AgentConfig {
    *   view.
    */
   clock?: import('../clock-rows.js').ClockConfig;
+
+  /**
+   * Keep the rows that open a turn raw for the whole turn (on when left out):
+   * at a start that opens a turn, the framework pins raw the rows of the
+   * agent's window after its newest own message and its consumed mark
+   * (`pinRange`, named `agent-framework:turn-inputs`; the README says
+   * which rows exactly), and removes the pin when the turn ends, so the
+   * strategy doesn't compress the rows the turn opened with while it runs,
+   * unless a committing compile refuses as over budget with it held: the
+   * pin is then removed and the compile runs once more (README). `false` places no pin:
+   * the turn's opening rows are compressed as any others, and a pin of the
+   * name left from before (a crash's) is removed at the next start that opens
+   * a turn, as a silent start removes one.
+   */
+  turnInputsPin?: boolean;
+
+  /**
+   * The other configured agents whose own rows this agent's window takes
+   * (none when left out). Residents share one slot, and each is shown only
+   * its own rows and the rows meant for it: another resident's rounds,
+   * replies, tool results and notes stay out of its window (#291, decision
+   * 1; rows an earlier release stored carry no stamp and stay in the window
+   * written down from the record: 291-presentation-mandatory). A name here
+   * is an observe edge in this agent's registry record, on
+   * that agent (`{ agent: name }`, the path the subconscious's edge takes),
+   * and the presentation index presents that agent's own rows to this one
+   * at its points, as it does any arrival (bearingOf); the history tools
+   * leave them in for its calls (ModuleContext.observes). That agent's own
+   * rows this one's window doesn't hold yet, those stored before the edge
+   * was declared included, enter it at its next presentation point, after
+   * what it holds: an edge declared on a store with history hands the
+   * observer that agent's earlier rows at once, at the end of its window
+   * (`ObserveEdge.fromMessageId`, which would start the edge at a row, is
+   * read by nothing yet). Only own rows: mail and channel traffic meant for that agent, and its stored
+   * context injections, stay out. One way: `nova` observing `mira` shows
+   * nova mira's rows, not mira nova's. `create()` refuses a name that is
+   * this agent's own or no configured agent's. Read when a configured agent
+   * is created; a derived agent's spec carries its own edges.
+   */
+  observes?: string[];
+
+  /**
+   * How the rounds of an agent it observes (`observes`) go out in this
+   * agent's requests, as `PersistentReaderConfig.foreignRounds` for the
+   * persistent subconscious: `'transcript'` (the default), a line per tool
+   * call and per result and none of their thinking, or `'raw'`, as stored.
+   * Unread for an agent that observes no one.
+   */
+  foreignRounds?: 'transcript' | 'raw';
 }
 
 /** The intentionally small set of agent settings that may change in-process. */
@@ -585,22 +648,19 @@ export interface InferenceRequest {
    *  all of them without materializing content, the turn has no cause left
    *  and does not run. */
   coalescingBatchSubjects?: string[];
-  /** Host-owned: this wake's sole cause is this write, deferred for its
-   *  agent while a turn was alive: a coalesced render placed in its queue
+  /** Host-owned: this wake's sole cause is this row, by the stored row's
+   *  id: one stored for its agent as it arrived, or one stored and not
+   *  presented to its agent at its write, because a turn of the agent's was
+   *  alive: a coalesced render its turn being assembled doesn't read
    *  (wakeToRead), or a message, notice or event whose wake was queued with
-   *  it. Once a request that carried the write was answered and, for a wake
-   *  that carries a channel and isn't marked `ambient`, the agent has since
-   *  published into that channel having read it, or once the write is in
-   *  neither the agent's queue nor its store's current branch, the wake
-   *  starts no turn. */
-  readsDeferredWrite?: string;
-  /** Host-owned: this wake's sole cause is this message, stored in its
-   *  agent's store as it arrived, not deferred (its row's id). Once a
-   *  request that carried the message was answered and, for a wake that
-   *  carries a channel and isn't marked `ambient`, the agent has since
-   *  published into that channel having read it, or once the message isn't
-   *  on its store's current branch, the wake starts no turn. */
-  readsStoredMessage?: string;
+   *  it. Once a request that carried the row was answered (an answered
+   *  request's consumed watermark covers it, in the agent's window once its
+   *  context presents rows) and, for a wake that carries a channel and isn't
+   *  marked `ambient`, the agent has since published into that channel
+   *  having read it, or once the row is not on its store's current branch,
+   *  the wake starts no turn. A row stored and not yet presented to the
+   *  agent keeps its wake. */
+  readsRow?: string;
   agentName: string;
   reason: string;
   source: string;
@@ -660,10 +720,9 @@ export interface InferenceRequest {
    * (`chat:ambient`). A coalesced push's wake carries it only to read a
    * render, and only when every notice the render stands for was. Such a
    * message asked nothing of the agent, so a wake for it that carries
-   * `readsDeferredWrite` or `readsStoredMessage` is dropped once a request
-   * that carried the message was answered, with no publish asked of the
-   * agent. A message with neither tag is in doubt, and is judged as an
-   * addressed one.
+   * `readsRow` is dropped once a request that carried the message
+   * was answered, with no publish asked of the agent. A message with neither
+   * tag is in doubt, and is judged as an addressed one.
    */
   ambient?: true;
   /**

package/src/types/events.ts

@@ -349,6 +349,8 @@ export interface ToolCall {
  * Converted from wire-format McplContentBlock to membrane ContentBlock.
  */
 export interface McplPushEvent {
+  /** The occurrence's suppression, when a coalesced push's wake decided it (CoalescedOccurrence.suppressionDecision). */
+  suppressionDecision?: string | null;
   type: 'mcpl:push-event';
   serverId: string;
   featureSet: string;

package/src/types/framework.ts

@@ -131,12 +131,12 @@ export interface FrameworkConfig {
      */
     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.
+     * With a `derivationNotice`, after this many derivations of one kind from
+     * one agent, the line it's given is 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.
+     * Without a `derivationNotice` the source is told nothing.
      */
     collapseDerivationNoticesAfter?: number;
     /**
@@ -152,9 +152,11 @@ export interface FrameworkConfig {
     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.
+     * record, the agent it was derived from and the framework's own line,
+     * return the text to add (that line, or the host's own), or null to add
+     * nothing. Absent, nothing is added: an agent isn't told of derivations
+     * unless the host asks for it. The `dendrite:agent-created` trace is
+     * emitted either way.
      */
     derivationNotice?: (record: import('../dendrite/types.js').AgentRecord, from: string, defaultText: string) => string | null;
   };
@@ -167,16 +169,14 @@ 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.
+   * Tune-out settings. Residents are offered `tune_out` only with a reader
+   * (`subconscious`), or while a hold a failed release left is still on
+   * record to check or cancel: a hold nothing summarizes would hand the resident an
+   * undated backlog all at once when it ends. `enabled`, which offered one
+   * without a reader, was removed in 0.33.0: `enabled: true` is refused at
+   * `create` (`false` is still accepted, from JavaScript, and does nothing).
    */
   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
@@ -200,7 +200,9 @@ export interface FrameworkConfig {
    *   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.
+   * Held traffic never moves the locus under either rule. Neither rule
+   * applies to an agent under locked prose routing (AgentConfig.proseRouting
+   * 'locked'): its turns speak at its lock, whatever arrives.
    */
   speech?: {
     locus?: 'delivery' | 'latest-inbound';
@@ -237,9 +239,29 @@ export interface FrameworkConfig {
   hostModePath?: string;
 
   /**
-   * Branch-independent durable queue of context writes deferred while
-   * quiesced. Defaults to `<storePath>/recovery/deferred-writes.json`; same
-   * rationale and fallback as `hostModePath`.
+   * Where a release before #291 kept its durable queue of deferred context
+   * writes. Defaults to `<storePath>/recovery/deferred-writes.json`; without
+   * either, the store's `framework/deferred-writes` slot. This release keeps
+   * no durable queue: a write is stored when it is made, and enters each
+   * agent's window at that agent's presentation points. Two holds keep a
+   * write in memory instead, and a crash loses it: a live operator surgery
+   * (a rollback, a suppression, a branch switch), until its release stores
+   * it, and an agent's context manager refusing its work after a failed
+   * re-initialization, until a branch move (switchBranch, a rollback or a
+   * suppression) re-initializes it.
+   *
+   * create() reads the record once and stores its writes. A write for an
+   * agent no longer registered goes to the primary when it is a failed
+   * reply, a channel notice its reader could act on, or a module's write
+   * for a run or a fork, and is dropped otherwise, logged. It then rewrites
+   * the record with what it left for the next boot: a write it couldn't
+   * store, or couldn't tell had already landed, with that agent's later
+   * writes. A write the store refuses as malformed is dropped, logged, as an
+   * earlier release's flush dropped it. When the store doesn't sync after
+   * the import, the record is left as it was.
+   *
+   * @deprecated Read once at boot by the deferred-write importer; removed in
+   * the next release.
    */
   deferredWritesPath?: string;