@animalabs/agent-framework 0.26.1 → 0.27.0

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
@@ -304,11 +334,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 +416,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 +583,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 +625,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;
     })
@@ -146,7 +155,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 +180,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 +194,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 +472,20 @@ export type TraceEvent =
       policyName: string;
       eventCount: 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 +549,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 +558,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 +589,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 +622,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;