@animalabs/agent-framework 0.32.0 → 0.34.0

package/src/types/agent.ts

@@ -221,11 +221,15 @@ export interface AgentConfig {
      * counts it. After a fold, each block after the stretch it rewrote is
      * bound to a conversation the request no longer holds. Where the context
      * strategy still sends such a block, the provider drops it on every call
-     * until a later fold takes it out of the context, and while such blocks
-     * are sent, no stream gives a sample and the calibration keeps the value
-     * it had. A strategy that leaves that thinking out at the fold sends none
-     * to drop. The direct API carries the control too, but reads no report: it
-     * traces no usage and feeds no calibration.
+     * until a later fold takes it out of the context, or, with `binds` set
+     * too, until the next compile after a note lands: the stream tells the
+     * context manager which stored reply's thinking was dropped
+     * (`noteThinkingDropped`), and once a note lands, the next compile sends
+     * that reply without it. While such blocks are sent,
+     * no stream gives a sample and the calibration keeps the value it had. A
+     * strategy that leaves that thinking out at the fold sends none to drop.
+     * The direct API carries the control too, but reads no report: it traces
+     * no usage, feeds no calibration and notes nothing.
      *
      * Default false: nothing is sent, and the account's default applies.
      */
@@ -249,6 +253,11 @@ export interface AgentConfig {
      *   thinking is kept at the next compile. The direct API
      *   (`runInference`) notes nothing, so each of its replies' thinking is
      *   left out at the compile after it's stored;
+     * - with `dropBlock` set too, each framework stream tells the context
+     *   manager which stored replies' thinking the provider reports dropping
+     *   (`noteThinkingDropped`), naming the compile it was built from, so
+     *   once a note lands, the next compile sends those replies without their
+     *   thinking;
      * - with `physicalWindowTokens` set too, `maxStreamTokens` no longer
      *   starts a new stream mid-turn, since the new stream's compile can take
      *   the turn's earlier reasoning out of the request;
@@ -330,8 +339,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
@@ -424,6 +454,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. */
@@ -578,22 +657,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;
@@ -653,10 +729,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;
   /**
@@ -687,6 +762,28 @@ export interface InferenceRequest {
    * channel (ambient-only batches leave it unset).
    */
   wakeChannelId?: string;
+  /**
+   * Framework-set on a gate wake whose batch held no message that addressed
+   * the agent, and which so took no route: the channels its messages came
+   * from (a `chat:system` notice names none, unless it's a coalesced
+   * render's latest occurrence), each once. A start merged from several
+   * requests carries every one's channels, or, when any of them comes from
+   * outside the framework, isn't a silent heartbeat tick and brought
+   * channels, only those requests' channels. A request a quiesce keeps in
+   * another's place, and one a provider hold takes another into, carry both
+   * requests' channels.
+   * The framework's own wakes that continue a
+   * turn (a restart, a re-inference, a continuation, a retry, a bounce, a
+   * re-arm), unless its own wake named a channel that resolves to none,
+   * carry the channels the turn's starts gathered, whether or not the turn
+   * had a locus, so a turn's trigger can name channels from several batches,
+   * and a turn they open with no locus can name them too.
+   * When such a turn's plain speech, or a sleep's announcement, is routed
+   * with no locus, the agent is told these channels, unless the turn's own
+   * wake named a channel that resolves to none, or the turn is an ephemeral
+   * run's, which is told nothing.
+   */
+  wakeChannels?: Array<{ serverId: string; channelId: string }>;
   /** Timestamp of the event the wake provenance was taken from (ms). */
   wakeAt?: number;
   /** Batched-wake lines the gate handed to this wake rather than wrote

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

@@ -169,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
@@ -193,16 +191,23 @@ export interface FrameworkConfig {
    * (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.
+   * - `'delivery'` (default): the locus comes from the delivery that woke
+   *   the turn, a conversation fork's home channel, or a channel the agent
+   *   opened during the turn, and past those only from an open all-except
+   *   hold's channel or `unpromptedChannel` (below), each for the turns that
+   *   take it. 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.
+   * Held traffic never moves the locus under either rule. Under either, a
+   * turn the agent's own timer starts takes `unpromptedChannel` where it's
+   * set, after an all-except hold's channel and before both rules' own
+   * fallbacks. 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';
@@ -239,9 +244,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;
 
@@ -482,6 +507,35 @@ export interface FrameworkConfig {
    */
   inferenceRouting?: InferenceRoutingPolicy;
 
+  /**
+   * The channel for a turn the agent's own timer starts, which no message
+   * prompted: the wake `skip_reply` schedules, or the end of a `sleep`. Plain
+   * speech in locus or hybrid prose routing goes there, and so does
+   * `channel_publish` naming no channel in any prose routing mode but locked,
+   * which servers are told as the turn's default outgoing channel. An
+   * all-except hold's channel still comes first while one is open, and without
+   * the setting such a turn follows `speech.locus`. A turn the framework opens
+   * to continue such a turn that had no locus of its own, as in explicit or
+   * disabled routing, takes it too: a `!` continuation, autoContinue's next
+   * turn, or a bounced reply's wake. No other turn takes it: not one a message
+   * prompted, from a channel, a module, a person at a console or another agent;
+   * not a heartbeat's or a reminder's (its plain speech is held as drafts); not
+   * a conversation fork's or an ephemeral run's; not a locked agent's, which
+   * speaks at its lock or holds its speech as drafts; and not a start merged
+   * from a timer's wake and any other cause. One value, for every agent on the
+   * framework. A registered channel's id, e.g. `discord:{guildId}:{channelId}`,
+   * or, to pick one server's where two register that id,
+   * `{serverId}:{channelId}`. `create()` refuses a value that is neither a
+   * string nor null, or is blank; null reads as not set. A value that names no
+   * registered channel, several, or one its server declared inbound-only, when
+   * a turn would take it, is logged, and logged again only after a turn has
+   * used it since; the turn takes what it would without the setting.
+   * `channel_publish`'s description adds a default for such turns only on a
+   * framework with an event gate, the only one with such turns; on any other
+   * the description is as it is without the setting.
+   */
+  unpromptedChannel?: string | null;
+
   /** EventGate config. If omitted, all events trigger inference (unchanged default). */
   gate?: GateOptions;
   /**
@@ -657,6 +711,8 @@ export interface InferenceLogEntry {
   success: boolean;
   /** Why it didn't succeed: the failure's message, or what stopped it */
   error?: string;
+  /** `error` in the framework's words, with no provider's text: what an agent may be shown of it */
+  errorWords?: string;
   /** Request data or blob ID if large. A stream the framework ended at a
    *  tool boundary (stopReason 'turn_ended', 'context_budget' or
    *  'physical_window') records a note in place of the body. */

package/src/types/inference-log.ts

@@ -54,6 +54,7 @@ export interface InferenceLogSummary {
   requestId: string;
   success: boolean;
   error?: string;
+  errorWords?: string;
   durationMs: number;
   tokenUsage?: { input: number; output: number; cacheCreation?: number; cacheRead?: number };
   stopReason?: string;