@animalabs/agent-framework 0.27.0 → 0.29.0

package/src/types/agent.ts

@@ -14,8 +14,9 @@ export type SameRoundThinkTextPolicySource =
 export interface AutoContinueRun {
   /** How the agent stops, as the row puts it ("call skip_reply"). */
   stop: string;
-  /** The turn before ended in words that were held, not sent, because it
-   *  had already sent with a send tool. */
+  /** The turn before ended in words some or all of which were held, not
+   *  sent, because a send in it may already have posted where they were
+   *  going. */
   heldAfterSend?: boolean;
   /** Set by the scheduler: the continuation is the turn's only cause. */
   sole?: boolean;
@@ -54,13 +55,15 @@ export interface AgentConfig {
    * Enforced at dispatch for registered agent callers; omitted means 'all'.
    * - 'all': all available tools
    * - string[]: exact tool names, including module--utility names for utilities.
-   * Utilities aren't tools of their own: an agent's model and its scripts are
-   * offered them only through 'utils', whose run checks the utility's own
-   * name. An agent that should use a utility lists both 'utils' and
-   * 'module--utility'. The name alone passes the dispatch check for any call
-   * by that name, whether the host makes it with executeToolCall on the
-   * agent's behalf or the model or a script makes it without being offered
-   * it. The slot is hidden when no utility is permitted.
+   * Utilities and the host's other rarely-used tools are in the host's
+   * built-in toolset ("settings"), out of the tool list: the model reaches
+   * them with toolsets--open {toolset:"settings"} and toolsets--act, each
+   * checked under the tool's own name. An agent that should use a utility
+   * from its model lists 'toolsets--open', 'toolsets--act' and
+   * 'module--utility' (an agent without the two meta-tools keeps every other
+   * tool in its list, but no utility). The name alone passes the dispatch
+   * check for any call by that name, whether the host makes it with
+   * executeToolCall on the agent's behalf or the model or a script makes it.
    * Trusted module calls are exempt. Genuinely unidentified public callers,
    * including unknown legacy names, remain unrestricted. Framework-created
    * identities have tool authority only while registered.
@@ -254,7 +257,18 @@ export interface AgentConfig {
      *   that the record doesn't account for raises the
      *   `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.
+     *   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 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
@@ -546,10 +560,18 @@ export interface InferenceRequest {
    *  agent while a turn was alive: a coalesced render placed in its queue
    *  (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, 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. */
+   *  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;
   agentName: string;
   reason: string;
   source: string;
@@ -560,8 +582,9 @@ export interface InferenceRequest {
    * the turn's auto-published plain-text speech here so a single TRUNK agent
    * replies in the channel it is answering — not the process-global most-recent-
    * inbound locus, which a concurrent message elsewhere can hijack (item-3
-   * redux). Undefined for non-channel wakes (heartbeat, timers, module events),
-   * which correctly fall back to the global default channel, except an
+   * redux). Undefined for non-channel wakes (heartbeat, timers, module events).
+   * A heartbeat's turn takes no channel at all, and holds its plain speech as
+   * drafts; any other falls back to the global default channel, except an
    * ephemeral run's (a subagent's), which takes no global fallback.
    */
   channelId?: string;
@@ -584,6 +607,17 @@ export interface InferenceRequest {
    * it starts. Hosts don't set it.
    */
   autoContinueRun?: AutoContinueRun;
+  /**
+   * Framework-set: whether this wake's turn is a heartbeat's, which has no
+   * channel and holds its plain speech as drafts. True on a wake that
+   * continues a heartbeat's turn with no channel of its own (an autoContinue
+   * continuation, a bounce's resend wake, a ` !` continuation, and a re-arm,
+   * which copies its trigger), and on a merged batch whose causes include a
+   * heartbeat's wake and name no channel; false on a merged batch with none,
+   * so the batch's first request doesn't decide it. Unset, a wake is a
+   * heartbeat's when its `source` is `heartbeat`. Hosts don't set it.
+   */
+  heartbeatTurn?: boolean;
   /**
    * True when the triggering message explicitly addressed the agent (mention,
    * reply-to-bot, DM — `chat:addressed` in MCPL RFC-001 terms). When a wake
@@ -597,11 +631,22 @@ 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` 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.
+   * `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.
    */
   ambient?: true;
+  /**
+   * Host-owned: true when the triggering message's server marked it a
+   * `chat:system` notice (RFC-001 rev 3): an event about the place, such as
+   * a join or the weather changing, not something anyone said. Such a wake
+   * names no channel for its turn's plain speech, though it carries
+   * `channelId`: a turn it starts alone resolves its locus as a heartbeat's
+   * does. Like an ambient one, a wake to read it is done once read. Never
+   * set on a coalesced render's wake, which may fold messages too.
+   */
+  systemNotice?: true;
   /**
    * Who spoke the message that triggered this inference, as an adapter-
    * namespaced opaque id (`<serverId>:user:<authorId>`) — never a display

package/src/types/events.ts

@@ -211,14 +211,17 @@ export interface ToolResult {
   /** Whether this was an error (for LLM) */
   isError?: boolean;
   /**
-   * The dispatcher refused the call before it opened, RFC-007's refusal, so
-   * nothing ran and the call certainly had no effect. Only the dispatcher's
-   * path, the model's calls and a script's, sets it: the caller may not use
-   * the tool (allowedTools), a `skip_reply` wake was refused, the call's MCPL
-   * server is absent or still connecting, the host's policy for that server
-   * denies the tool, or a fork reached outside its channel. RFC-007's
-   * lifecycle refuses the call from the same place, so observers see no
-   * events for it. A check made after the call opened, such as a module's
+   * The call was refused before it opened, RFC-007's refusal, so nothing ran
+   * and the call certainly had no effect. The dispatcher's path, the model's
+   * calls and a script's, sets it: the caller may not use the tool
+   * (allowedTools), a `skip_reply` wake was refused, the call's MCPL server is
+   * absent or still connecting, the host's policy for that server denies the
+   * tool, or a fork reached outside its channel. RFC-007's lifecycle refuses
+   * the call from the same place, so observers see no events for it. The
+   * framework also sets it on the result it stores for each call in the last
+   * round of a response the output limit cut off: such a call was never
+   * dispatched or opened, and its result goes into the context with the reply,
+   * not through a tool-result event. A check made after the call opened, such as a module's
    * answer for a name it has no tool for or arguments that don't fit a
    * schema, is a failure whose text says nothing was done, as is an MCPL
    * request that couldn't be written. A programmatic call (`executeToolCall`,
@@ -270,6 +273,13 @@ export interface ToolCall {
   name: string;
   /** Tool input */
   input: unknown;
+  /**
+   * membrane's marker (ToolUseContent.unparseableInput), present when `input`
+   * isn't the model's arguments. The framework refuses such a call without
+   * running it, except one whose text is JSON `null`, which runs as a call
+   * with no arguments.
+   */
+  unparseableInput?: string;
   /** The agent that made this tool call. Set by the framework dispatch layer. */
   callerAgentName?: string;
   /**

package/src/types/framework.ts

@@ -218,6 +218,50 @@ export interface FrameworkConfig {
    */
   providerHold?: ProviderHoldHook;
 
+  /**
+   * Delays before a turn whose retries ran out is sent again, in ms (default
+   * `[120000, 480000, 1920000]`: 2, 8 and 32 minutes), or `false` never to.
+   * When a persistent agent's turn ends exhausted on a transient failure (a
+   * server error, an overload, a rate limit, a network failure, or a timeout
+   * membrane marks retryable and not as a deadline it reports as run out, such
+   * as a 408 or a socket's ETIMEDOUT), its trigger is queued again after the
+   * first delay, as a wake of its own. It opens where the exhausted turn's
+   * plain speech was going: its locus, where a message mid-turn may have moved
+   * it, else its trigger channel. Carrying that channel, it ranks as addressed
+   * in a merged wake's choice of channel, so a newer ambient wake from
+   * elsewhere doesn't take it; an autoContinue continuation's still yields its
+   * channel to any wake's, as it does on main; a continuation's, such as a
+   * budget restart's, names no author. A re-arm that would have to guess a
+   * channel isn't sent again: one whose turn was woken for a channel id that
+   * names no one registered channel and never found one, and whose request
+   * names none of its own. A failure that states a wait is held for that wait
+   * first, as any turn's is, and a deadline ends the turn as before, whether
+   * the host set it or membrane marks one as run out: the runtime's or
+   * undici's on a sent request, the Anthropic adapter's watchdogs, or the
+   * Anthropic SDK's timeout, which covers its connect timeout too. Until one
+   * of the re-armed turn's rounds has run or had its tool calls cut off, its
+   * failure gets no retries from the error policy: on another transient
+   * failure the next delay follows, until the list runs out, and a failure of
+   * any other kind ends the re-arming. A wake for the agent while it waits
+   * starts its turn at once, with the re-armed trigger merged in. That turn is
+   * the wake's: the error policy retries its failures. A completed turn starts
+   * the count again, and so does a message said to the agent: not a system
+   * message or notice; not an edit, reaction or deletion, unless an edit is
+   * the first version of a message the agent sees; not a message its own view
+   * leaves out, such as one a tune-out holds from it; and not the agent's own
+   * schedule, the heartbeat's tick or reminder, a self-wake timer it set, or a
+   * script's wake. A notice a module or an MCPL server stores as a message
+   * counts. A message in the residents' shared slot counts for each resident
+   * that reads it. Any other wake leaves the count going on. A re-armed turn's
+   * transient failure writes no `[inference-failed]` marker unless a round of
+   * it ran or had its tool calls cut off; any other failure of it writes one.
+   * Each counts toward the hard-down streak. Ephemeral runs and conversation
+   * forks are never re-armed. The wait and the count are kept in memory:
+   * `stop()` drops them, and so does a restart. The wait isn't a turn, so
+   * `abortInference()` doesn't end it.
+   */
+  exhaustedTurnRearmMs?: number[] | false;
+
   /** Interval for periodic store sync in milliseconds (default: 1000ms, 0 to disable) */
   syncIntervalMs?: number;
 
@@ -299,6 +343,21 @@ export interface FrameworkConfig {
 
   /** 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

@@ -72,10 +72,11 @@ export type ModuleMessage = StoredMessage & {
    * True on a message a tune-out holds from the residents: one that arrived
    * in a tuned-out channel, stamped `metadata.tuneOut` as it came in. The
    * store keeps it, but no resident is shown the row itself: no resident's
-   * compiled view includes it, during the tune-out or after it, and a tool
-   * boundary of a turn alive when it arrived stores it without injecting it
-   * into the live turn. The subconscious reads it. Its text can still reach
-   * a resident in rows of their own, which aren't marked, such as the
+   * compiled view includes it, during the tune-out or after it, and a
+   * resident's tool boundary of a turn alive when it arrived stores it
+   * without injecting it into the live turn. The subconscious reads it. Its
+   * text can still reach a resident in rows of their own, which aren't
+   * marked, such as the
    * cancel's `<tuned-out-backlog>` row, with the text of the tune-out's newest
    * messages, up to `backlogCap` of them and as many as fit in one of the
    * residents' messages, the stored ones first and then those still held;
@@ -142,16 +143,27 @@ export interface Module {
 
   /**
    * Utilities: agent-invocable operations that deliberately do NOT get a
-   * first-class tool slot. Every tool schema taxes every inference; a
-   * capability used twice a month shouldn't. Utilities are listed, described,
-   * and invoked through the framework's single `utils` tool instead — same
-   * ToolDefinition shape, same un-prefixed names, and dispatch arrives at the
-   * SAME handleToolCall as getTools() output, so a tool migrates between
-   * surfaces by moving its definition from one list to the other and nothing
-   * else. Optional; omitting it means the module contributes no utilities.
+   * slot in the tool list. Every tool schema taxes every inference; a
+   * capability used twice a month shouldn't. Utilities belong to the host's
+   * built-in toolset ("settings"): an agent sees them with
+   * `toolsets--look {toolset:"settings"}` and calls them with
+   * `toolsets--act` once it has opened it. Same ToolDefinition shape, same
+   * un-prefixed names, and dispatch arrives at the SAME handleToolCall as
+   * getTools() output. Optional; omitting it means the module contributes no
+   * utilities.
    */
   getUtilities?(): ToolDefinition[];
 
+  /**
+   * Where one of this module's tools (a getTools() name, unprefixed) is
+   * presented: in the agent's tool list (`'header'`, the default), or in the
+   * host's built-in toolset (`'builtin'`), out of the tool list, opened with
+   * `toolsets--open {toolset:"settings"}` and called with `toolsets--act`.
+   * For tools an agent uses rarely: settings, administration, status reads.
+   * Optional; omitting it keeps every tool in the tool list.
+   */
+  toolPlacement?(toolName: string): 'header' | 'builtin' | undefined;
+
   /**
    * Handle a tool call.
    * Tool name is without module prefix.
@@ -232,13 +244,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>;
 }
 

package/src/types/trace.ts

@@ -114,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;
@@ -472,6 +489,24 @@ 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
@@ -836,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 & {