@animalabs/agent-framework 0.26.2 → 0.28.0

package/src/types/framework.ts

@@ -16,6 +16,13 @@ export type { TraceEvent, TraceEventListener } from './trace.js';
 export interface ModuleProcessResponse {
   moduleName: string;
   response: EventResponse;
+  /**
+   * Set when applying the response threw: the operation it threw at, such
+   * as `the edit of <id>`, and the error's message. What the response asked
+   * for before that was applied, that operation may have taken effect in
+   * part or whole, and the rest of it wasn't (EventResponse).
+   */
+  threw?: { at: string; error: string };
 }
 
 /**
@@ -241,8 +248,9 @@ export interface FrameworkConfig {
    * workspace file under `tool-results/` (deterministic `<date>-<callId>.txt`
    * name, overwritten on collision, retained until the workspace owner
    * deletes it — never auto-GC'd) and replaced inline by a bounded preview
-   * plus the file reference; with no writable mount without an include, the
-   * fallback is explicit plain truncation. Default 24000 (house-safe; issue #89). Must be
+   * plus the file reference; with no writable mount without an include that
+   * keeps its files in the store (not configured direct), the fallback is
+   * explicit plain truncation. Default 24000 (house-safe; issue #89). Must be
    * >= 1000. A resident's own agent_settings value
    * `tool_result_inline_max_chars` (durable, persisted in framework state)
    * takes precedence over this for that agent; the EFFECTIVE cap for every
@@ -276,11 +284,36 @@ export interface FrameworkConfig {
    */
   hostToolClasses?: Record<string, string[]>;
 
-  /** Inference routing policy for server-initiated inference (optional). */
+  /**
+   * Inference routing policy for server-initiated inference (optional): the
+   * model an MCPL server's inference/request runs on. Without one, each such
+   * request is refused with -32603 and a message naming this setting; the
+   * framework doesn't choose a model for a server. A server's effective
+   * grant can still list `inferenceRequest` then, since the grant comes from
+   * what the server advertises and `enabledCapabilities`, not from this
+   * policy. A policy that names no model for a request's feature set (no
+   * override, byFeature or wildcards entry that names one, and an empty
+   * `default`) refuses that request the same way, naming the feature set.
+   */
   inferenceRouting?: InferenceRoutingPolicy;
 
   /** EventGate config. If omitted, all events trigger inference (unchanged default). */
   gate?: GateOptions;
+  /**
+   * The heartbeat: the agent's own periodic check-in and reminders, kept by
+   * the framework (src/heartbeat/heartbeat.ts), with the tools
+   * `heartbeat--heartbeat_status`, `heartbeat--heartbeat_configure`,
+   * `heartbeat--heartbeat_trigger`, `heartbeat--reminder_add`,
+   * `heartbeat--reminder_list` and `heartbeat--reminder_cancel`. `true` turns it
+   * on with its defaults; `false`, null or leaving it out leaves it off. Its
+   * wakes go to the gate as heartbeat-mcpl's pushes did, from the server id
+   * `heartbeat`, so the agent's rules decide them and a sleep lets them
+   * through. It replaces the heartbeat-mcpl server, which is refused beside it
+   * (by its id, a heartbeat tool prefix, or its command), at create and at a
+   * runtime connect: both would wake the agent. `importFrom` brings that
+   * server's schedule and reminders along.
+   */
+  heartbeat?: boolean | null | import('../heartbeat/heartbeat.js').HeartbeatOptions;
 
   /**
    * Liveness watchdog: fail hard (and let the supervisor restart) if the main

package/src/types/module.ts

@@ -25,6 +25,29 @@ export interface MessageQuery {
   metadata?: Record<string, unknown>;
 }
 
+/**
+ * A context injection a module gathers (Module.gatherContext).
+ *
+ * An `afterUser` one is stored in the agent's window, as the message
+ * `compile()` would have placed after the last user message, where it then
+ * stays: so the replies after it keep their thinking, and the cache keeps the
+ * turns before it. The same source's unchanged content isn't stored again
+ * while the copy the agent will read as current has it whole: the one its
+ * last request held, or a newer one a start stored whose compile then
+ * didn't record. Once a fold has summarized it or a strategy's window has
+ * scrolled past it, it's stored again, as one more row. (See
+ * stored-injections.ts.)
+ *
+ * `placedEachCompile: true` opts out: `compile()` places the injection after
+ * the last user message at each start, near the end, as before it was
+ * stored. That's for context meant to stay near the end, such as
+ * instructions moved off `system`. Its cost: it moves, and on a model that
+ * binds a reply's thinking to everything before it, every reply after its old
+ * place loses its thinking. It has no effect on a `system` or `beforeUser`
+ * injection, which `compile()` always places.
+ */
+export type ModuleContextInjection = ContextInjection & { placedEachCompile?: true };
+
 /**
  * A message as a module context's reads answer it: a stored row, or a row
  * for a write the framework holds (`held`). Either is marked
@@ -159,9 +182,16 @@ export interface Module {
    * Called before each inference to collect data (e.g., HUD overlays, game state)
    * that should be injected into the compiled context.
    * Complementary to MCPL push-based hooks — modules pull via gatherContext.
+   * An `afterUser` injection is appended to the agent's window, where it
+   * then stays, unless the copy the agent will read as current has the same
+   * content, every part of it (the one its last request held, or a newer
+   * one a start stored whose compile then didn't record), or it opts out
+   * (ModuleContextInjection.placedEachCompile). At a
+   * turn's start or a restart after tool results, that's where `compile()`
+   * would have placed it.
    * Adapted from Anarchid/agent-framework@mcpl-module-proto.
    */
-  gatherContext?(agentName: string): Promise<ContextInjection[]>;
+  gatherContext?(agentName: string): Promise<ModuleContextInjection[]>;
 
   /**
    * Called once an agent's tool batch has completed — when the round's last
@@ -202,13 +232,16 @@ export interface AgentSettingsExtension {
   properties: Record<string, unknown>;
   /** The setting keys this extension owns (must match `properties` keys). */
   keys: string[];
-  /** Current values for the extension's keys. */
+  /** Current values for the extension's keys. A refused agent_settings call
+   *  names what changed by comparing every field this returns, before the
+   *  call and at its refusal. */
   get(agentName: string): Record<string, unknown>;
   /** Apply a partial update (only this extension's keys present) and return
    *  the new values. Throw to surface a validation error to the agent. */
   update(agentName: string, patch: Record<string, unknown>): Record<string, unknown>;
   /** Restore the listed keys (or all when omitted) to defaults and return the
-   *  new values. Optional — extensions without reset semantics are skipped. */
+   *  new values. Optional: without it, a reset of every setting skips the
+   *  extension, and a reset that names one of its keys is refused. */
   reset?(agentName: string, keys?: string[]): Record<string, unknown>;
 }
 
@@ -304,11 +337,43 @@ export interface ModuleContext {
    * (ModuleMessage.held). The writes a process held, and keeps across a
    * restart, show to the next process's modules once create() has restored
    * them, which is after every module's start().
+   *
+   * With `opts.forAgent`, it's added to the named agent's window instead: a
+   * conversation fork's or a running sub-agent's own store, or, for an
+   * ordinary resident, the residents' shared slot. It's held while that
+   * agent's turn is alive, as a write for the primary is while the
+   * primary's is. A name that isn't a registered agent when the write is
+   * made, or the empty name, throws, naming the registered ones, so a write
+   * for a launcher that has gone is heard. For an ephemeral run (a
+   * sub-agent's run) or a conversation fork, whose window nothing reads
+   * after it's released, a write it never read goes to the primary at its
+   * release, as the write itself, through the primary's own delivery. It's
+   * read as the framework reads a notice: once it's below the target's
+   * consumed watermark, which a compile built to send moves when it
+   * commits (a row that compile's strategy left out counts as read too),
+   * and a tool round moves when it injects messages into a stream that
+   * declares it carries them. So one that waited for its target's end (a
+   * run's end, or a fork's last turn), one stored while it was idle and
+   * never sent, one stored at a tool round that ended the turn, and one
+   * injected into a stream that didn't declare it carries injections go to
+   * the primary. The framework's own
+   * writes for a run or a fork are unchanged: they stay in its store,
+   * unless they're notices the primary already takes in their place (a
+   * failed reply, or a channel notice its reader could act on). getMessage,
+   * editMessage and removeMessage read the delivery agent's window (the
+   * primary's, or the first agent's when none is primary): they don't take
+   * an id or handle for a row in a fork's or a sub-agent's window, and don't
+   * find it (read it with queryMessages and the same forAgent). The
+   * residents' shared slot is the primary's window too, for a primary
+   * that's an ordinary resident, so there they do.
+   * `metadata.external` with a target throws: its id map is read in the
+   * primary's window.
    */
   addMessage(
     participant: string,
     content: ContentBlock[],
-    metadata?: MessageMetadata & { external?: ExternalIdRef }
+    metadata?: MessageMetadata & { external?: ExternalIdRef },
+    opts?: { forAgent?: string },
   ): MessageId;
 
   /**
@@ -354,8 +419,17 @@ export interface ModuleContext {
    * restored them, after every module's start() (addMessage). A message a
    * tune-out holds from the residents is among the rows, marked
    * `heldFromResidents` (ModuleMessage).
+   *
+   * It reads the primary's window (the first registered agent's when none
+   * is primary), or with `opts.forAgent`, the named agent's: a conversation
+   * fork's or a running sub-agent's own store, or, for an ordinary resident,
+   * the residents' shared slot. For the subconscious, it's the
+   * subconscious's own store, not the residents' slot its compile merges
+   * in. A name that isn't a registered agent, or the empty name, throws,
+   * naming the registered ones, so a typo is heard rather than read as an
+   * empty window.
    */
-  queryMessages(filter: MessageQuery): MessageQueryResult;
+  queryMessages(filter: MessageQuery, opts?: { forAgent?: string }): MessageQueryResult;
 
   /**
    * Get info about all agents.
@@ -512,7 +586,15 @@ export interface AgentInfo {
 export type AgentStatus = 'idle' | 'inferring' | 'streaming' | 'waiting_for_tools' | 'ready';
 
 /**
- * Response from a module's event handler.
+ * Response from a module's event handler. The framework applies it in this
+ * order: its messages added, edited and removed, then its stateUpdate, then
+ * its inference request. When one of these throws, such as an edit of a
+ * message the store doesn't hold, what came before it stays applied, the
+ * operation that threw may have taken effect in part or whole (a store can
+ * throw after it wrote), the rest of the response isn't, and a line names
+ * the module and where it threw; the event's other responses, a tool call's dispatch and its trace
+ * go on. Content the framework finds malformed refuses the whole response
+ * before any of it applies.
  */
 export interface EventResponse {
   /**
@@ -546,9 +628,9 @@ export interface EventResponse {
   toolsChanged?: boolean;
 
   /**
-   * Module state update. Applied atomically with message operations.
-   * The framework will call setState() with this value after applying
-   * message changes, ensuring consistent state.
+   * Module state update. The framework calls setState() with this value
+   * after applying the response's message changes, and not when one of
+   * them threw.
    */
   stateUpdate?: unknown;
 }

package/src/types/trace.ts

@@ -1,3 +1,4 @@
+import type { ThinkingBindingEntry } from '@animalabs/membrane';
 import type { ProcessEvent } from './events.js';
 import type { ModuleProcessResponse } from './framework.js';
 import type { SessionUsage } from '../usage/types.js';
@@ -66,6 +67,14 @@ export type TraceEvent =
        * without re-deriving routing.
        */
       channelId?: string;
+      /**
+       * The server that registers `channelId`, given with it. Two MCPL
+       * servers may register one channel id, so a tap that posts back to the
+       * turn's channel, such as a host telling it the turn failed, passes this
+       * server with the id. The streaming traces, `inference:tokens` and
+       * `inference:content_block`, carry the id alone.
+       */
+      serverId?: string;
       /** True for a control-plane wake that must not surface typing/prose. */
       silent?: boolean;
     })
@@ -105,6 +114,23 @@ export type TraceEvent =
       /** Bounded like `error`. */
       stack?: string;
     })
+  | (TraceEventBase & {
+      /**
+       * A turn waiting out its error policy's delay before a retry says so:
+       * as the wait begins, with when it is due to end, and again every 60
+       * seconds while it lasts, while its agent is the one registered under
+       * its name, and never after the wait ends (its time coming, a stop, or
+       * an abort). The failure being retried is the `inference:failed` just
+       * before it. A host watching for agents gone quiet can tell a waiting
+       * one from a stuck one by it.
+       */
+      type: 'inference:waiting';
+      agentName: string;
+      /** When the wait is due to end (epoch ms): it counts down by its
+       *  timers, so a stalled event loop can end it later. Absent for a wait
+       *  too long for a date. */
+      until?: number;
+    })
   | (TraceEventBase & {
       type: 'inference:exhausted';
       agentName: string;
@@ -146,7 +172,9 @@ export type TraceEvent =
        *  content in it or its retry after a refusal, and a tool result the
        *  boundary reports carries the channel of the round it answers. In
        *  hybrid mode a `>>>` envelope can send the text itself elsewhere.
-       *  Explicit mode: the channel the start's wake came from. */
+       *  Explicit mode: the channel its typing shows, where the start's wake
+       *  came from, or, at a start whose wake names none, such as a budget
+       *  restart, the one the turn already shows. */
       channelId?: string;
     })
   | (TraceEventBase & {
@@ -169,7 +197,9 @@ export type TraceEvent =
        *  content in it or its retry after a refusal, and a tool result the
        *  boundary reports carries the channel of the round it answers. In
        *  hybrid mode a `>>>` envelope can send the text itself elsewhere.
-       *  Explicit mode: the channel the start's wake came from. */
+       *  Explicit mode: the channel its typing shows, where the start's wake
+       *  came from, or, at a start whose wake names none, such as a budget
+       *  restart, the one the turn already shows. */
       channelId?: string;
     })
   | (TraceEventBase & {
@@ -181,6 +211,20 @@ export type TraceEvent =
       type: 'inference:usage';
       agentName: string;
       tokenUsage: { input: number; output: number; cacheCreation?: number; cacheRead?: number };
+      /**
+       * The provider's report on the signed thinking of the call this event
+       * closes (membrane's `RoundReport.thinking`): blocks it dropped before
+       * the model saw them, and blocks it showed the model anyway because the
+       * check isn't enforced. `tokenUsage` beside it is the stream's running
+       * total, not this call's. The provider reports them for a request that
+       * carried the binding control, whoever asked for it:
+       * `thinkingBinding.dropBlock`, or a thinking config the host sends
+       * itself. Present only when the report names any block.
+       */
+      thinking?: {
+        dropped: ThinkingBindingEntry[];
+        mismatchAllowed: ThinkingBindingEntry[];
+      };
     })
   | (TraceEventBase & {
       type: 'inference:stream_resumed';
@@ -445,6 +489,38 @@ export type TraceEvent =
       policyName: string;
       eventCount: number;
     })
+  | (TraceEventBase & {
+      /** The reply judge's verdict on a `judge` rule's batch. `verdict`:
+       *  `reply` or `wait` as the judge answered, `error` when it failed,
+       *  timed out or answered nothing usable; `woke` is whether the batch
+       *  then woke the agent (an error does by the host's onError).
+       *  The judge's reason is in the agent's gate_status, not here: it's
+       *  written from the agent's context. */
+      type: 'gate:judge-verdict';
+      policyName: string;
+      verdict: 'reply' | 'wait' | 'error';
+      woke: boolean;
+      eventCount: number;
+      durationMs: number;
+      model?: string;
+      inputTokens?: number;
+      cacheReadTokens?: number;
+      outputTokens?: number;
+    })
+  | (TraceEventBase & {
+      /** A batched wake's turn started without its `[Gate: …]` line (the
+       *  gate hands the line to the wake when its message is the newest at
+       *  the fire, EventGate isNewestEntry, and the turn's start decides).
+       *  `reason`: `newest`, on the delivery agent's start the message was
+       *  still the newest entry in the window; `held`, the host was quiesced
+       *  or another reader of the residents' shared slot had a turn alive,
+       *  so no line could be written then. */
+      type: 'gate:wake-line-omitted';
+      reason: 'newest' | 'held';
+      policyNames: string[];
+      eventType: string;
+      channelId?: string;
+    })
   | (TraceEventBase & {
       type: 'gate:config-reloaded';
       configPath: string;
@@ -508,6 +584,8 @@ export type TraceEvent =
   | (TraceEventBase & {
       type: 'mcpl:conversation-spawned';
       channelId: string;
+      /** The channel's server: a channel id is unique only within one server. */
+      serverId: string;
       agentName: string;
       generation: number;
       template: string;
@@ -515,22 +593,30 @@ export type TraceEvent =
   | (TraceEventBase & {
       type: 'mcpl:conversation-spawn-failed';
       channelId: string;
+      /** The channel's server: a channel id is unique only within one server. */
+      serverId: string;
       agentName: string;
       error: string;
     })
   | (TraceEventBase & {
       type: 'mcpl:conversation-unrouted';
       channelId: string;
+      /** The channel's server: a channel id is unique only within one server. */
+      serverId: string;
       messageId: string;
     })
   | (TraceEventBase & {
       type: 'mcpl:conversation-binding-orphaned';
       channelId: string;
+      /** The channel's server: a channel id is unique only within one server. */
+      serverId: string;
       agentName: string;
     })
   | (TraceEventBase & {
       type: 'mcpl:conversation-closed';
       channelId: string;
+      /** The channel's server: a channel id is unique only within one server. */
+      serverId: string;
       agentName: string;
       reason: 'idle-ttl';
     })
@@ -538,6 +624,8 @@ export type TraceEvent =
       type: 'mcpl:conversation-disposed';
       agentName: string;
       channelId?: string;
+      /** The home channel's server, beside its channelId. */
+      serverId?: string;
     })
 
   // Host-owned speech routing (ChannelRegistry.routeSpeech). One trace per
@@ -569,6 +657,9 @@ export type TraceEvent =
       type: 'mcpl:speech-route-failed';
       /** Agent / conversation whose speech failed to route. */
       conversationId: string;
+      /** The channel's server, where the destination, or the caller, named
+       *  one: a channel id is unique only within one server. */
+      serverId?: string;
       /** Empty string when the failure was "no locus at all". */
       channelId: string;
       reason: string;
@@ -780,7 +871,7 @@ export type TraceEvent =
       parkedAdmissions?: number;
       /** True when undrained turns were force-cancelled (abandon). */
       abandoned?: boolean;
-      /** Agents whose turn the abandon had not ended when its grace ran out: a token held with no stream and no check ahead (a puppet tool turn, a store surgery's reservation, a turn finishing its last delivery), or a turn that hadn't reached its next check, the tool-result guard's wait for its speech included. A turn whose stream the abandon cancelled while it was still streaming isn't listed, even one still running when the grace ran out. */
+      /** Agents whose turn the abandon had not ended when its grace ran out: a token held with no stream and no check ahead (a puppet tool turn, a store surgery's reservation, a turn finishing its last delivery), or a turn that hadn't reached its next check, the tool-result guard's wait for its speech included, or a turn whose stream's cancel threw with no check ahead, so that its stream goes on. A turn whose stream the abandon cancelled while it was still streaming isn't listed, even one still running when the grace ran out. */
       unabandonable?: string[];
     })
   | (TraceEventBase & {