@animalabs/agent-framework 0.27.0 → 0.28.0

package/src/thinking-drops.ts

@@ -29,10 +29,11 @@ export interface CompiledForRequest {
   recordedAfter?: number;
 }
 
-/** What a stream's driver reads a call's dropped blocks against (`StartStreamResult`'s two fields, together). */
+/** What a stream's driver reads a call's dropped blocks against (`StartStreamResult`'s fields, together). */
 export interface StreamThinkingDrops {
   place: (entries: readonly ThinkingBindingEntry[]) => PlacedDrop[];
   recordedAfter?: number;
+  branch?: string;
 }
 
 /** A signed block's identity on the wire: a thinking block's signature, a redacted block's data. */
@@ -112,26 +113,19 @@ export function splitThinkingDrops(
 /** Binding failures the context manager's record doesn't track: the account's, not the conversation's. */
 const UNTRACKED_REASONS = new Set(['organization_binding_mismatch', 'end_user_binding_mismatch']);
 
-/**
- * When an agent's unexpected drops call for an operator alert: at the first call that shows any, and again only
- * when a call shows more than the alert last counted. Each call of a stream, and each stream until a strip takes
- * them out, drops the same blocks again, so an unchanged count isn't news. A call that shows no unexpected drop, its
- * report empty, absent or naming only expected ones, ends the incident: the blocks it counted no longer drop. The next
- * one alerts afresh. It's held in memory, so a restart mid-incident alerts once more, and an agent's removal ends its
- * incident (`forget`).
- */
 export class ThinkingLossIncidents {
-  private readonly alerted = new Map<string, number>();
+  private readonly alerted = new Map<string, { count: number; scope: string | undefined }>();
 
-  /** A call's report of `unexpected` drops for `agent`: the count to alert with, or undefined for no alert. */
-  observe(agent: string, unexpected: number): number | undefined {
-    if (unexpected === 0) {
+  /** A call's report of `count` drops for `agent` in `scope`: the count to alert with, or undefined for no alert. */
+  observe(agent: string, count: number, scope?: string): number | undefined {
+    const open = this.alerted.get(agent);
+    if (count === 0) {
       this.alerted.delete(agent);
       return undefined;
     }
-    if (unexpected <= (this.alerted.get(agent) ?? 0)) return undefined;
-    this.alerted.set(agent, unexpected);
-    return unexpected;
+    if (open && open.scope === scope && count <= open.count) return undefined;
+    this.alerted.set(agent, { count, scope });
+    return count;
   }
 
   /** The agent is gone: its incident, if one is open, ends with it. */

package/src/tool-args.ts

@@ -67,6 +67,39 @@ function shown(value: unknown): string {
   return head;
 }
 
+function notAnObject(input: unknown, field = 'input'): string {
+  return `its ${field} must be an object, and this call gave ${withArticle(kindOf(input))}`;
+}
+
+export function markedInputRefusal(call: { name: string; unparseableInput?: string }): string | undefined {
+  const text = call.unparseableInput;
+  if (text === undefined) return undefined;
+  // When a stream ends before a call's block stops, membrane marks the call
+  // with what had arrived of its arguments: nothing, a part, or a whole
+  // object. A block still open when a stream breaks the API's block order
+  // is marked the same way, and one that had stopped with its object's JSON,
+  // so the arguments may be another call's (ToolUseContent.unparseableInput).
+  if (/^[ \t\n\r]*$/.test(text)) return `Nothing was done: ${call.name} its arguments never arrived; call it again with them whole.`;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return `Nothing was done: ${call.name} its arguments must be one JSON object, and this call gave text that isn't JSON, which may have been cut off: ${shown(text)}; call it again with one JSON object.`;
+  }
+  if (parsed === null) return undefined;
+  if (typeof parsed !== 'object' || Array.isArray(parsed)) return `Nothing was done: ${call.name} ${notAnObject(parsed)}.`;
+  return `Nothing was done: ${call.name} its arguments came in a response that didn't arrive whole and in order, so they can't be taken as this call's; call it again.`;
+}
+
+export function cutOffRefusal(call: { name: string }): string {
+  return `Nothing was done: ${call.name} didn't run, because the response it was in was cut off at the output limit. ` +
+    'To make the call, send less in one response: shorter text before it, shorter arguments, or fewer calls at once.';
+}
+
+export function asCalled<T extends { name: string; input?: unknown; unparseableInput?: string }>(call: T): T {
+  return call.unparseableInput !== undefined && markedInputRefusal(call) === undefined ? { ...call, input: {} } : call;
+}
+
 /** A list in prose: `a`, `a or b`, `a, b or c`. */
 function oneOf(items: string[]): string {
   return items.length <= 1 ? items.join('') : `${items.slice(0, -1).join(', ')} or ${items[items.length - 1]}`;
@@ -169,7 +202,7 @@ export function toolArgsProblems(
   if (!schema) return [];
   const absent = input === undefined || input === null;
   if (!absent && (typeof input !== 'object' || Array.isArray(input))) {
-    return [`its ${options.field ?? 'input'} must be an object, and this call gave ${withArticle(kindOf(input))}`];
+    return [notAnObject(input, options.field)];
   }
   const obj = (absent ? {} : input) as Record<string, unknown>;
   const properties = (isMap(schema.properties) ? schema.properties : {}) as Record<string, { type?: unknown; nullable?: unknown; enum?: unknown } | undefined>;

package/src/tool-result-guard.ts

@@ -9,6 +9,14 @@ import { resultClaimsOf, rfc005TextOf, toolResultDataToHistoryString } from './t
 import { safeSlice } from './safe-slice.js';
 
 export const TOOL_RESULT_GUARD_NOTICE = 'Tool result withheld by the guard. The tool has already executed.';
+export type WithheldNoticeKind = 'ran' | 'refused' | 'error';
+const GUARD_NOTICES: Record<WithheldNoticeKind, string> = {
+  ran: TOOL_RESULT_GUARD_NOTICE,
+  refused: "Tool result withheld by the guard. The tool didn't run.",
+  error: "Tool result withheld by the guard. The call returned an error, and this notice can't say whether the tool ran.",
+};
+const noticeKind = (result: CompletedToolCall['result'] | undefined): WithheldNoticeKind =>
+  result?.refused === true ? 'refused' : result?.isError === true ? 'error' : 'ran';
 export const TOOL_RESULT_GUARD_AUDIT_STATE = 'framework/tool-result-guard';
 
 /** Where a withheld result's original went: a workspace path; the path a
@@ -54,9 +62,12 @@ export interface WithheldHost {
 }
 
 /**
- * The stub a withheld result settles to: #159's neutral notice, then where
- * the original is, then, when its tool marked any, the fields kept from its
- * result (`kept`, from keptWhenWithheld). It names no refusal and no
+ * The stub a withheld result settles to: #159's neutral notice for its
+ * `kind` (a result that isn't an error, a refused call's, or another error's),
+ * then where the original is, then, for an error whose original is in a file
+ * known written, a line telling the agent to read it, then, when its tool
+ * marked any, the fields kept from its result (`kept`, from
+ * keptWhenWithheld). It names no refusal and no
  * category (#159 keeps those in operational logs), so reading the rest back
  * is the agent's deliberate choice (agent-framework #277). The place holds
  * the result as stored, which for one over the inline cap is its capped
@@ -67,7 +78,7 @@ export interface WithheldHost {
  * save failed is still queued in memory, and a restart before its retry
  * loses it.
  */
-export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean, kept?: string): string {
+export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean, kept?: string, kind: WithheldNoticeKind = 'ran'): string {
   const audit = `the guard's audit record (${TOOL_RESULT_GUARD_AUDIT_STATE}), for an operator`;
   const keptIn = (only: string) => auditDurable
     ? `is kept ${only}in ${audit}`
@@ -80,8 +91,10 @@ export function withheldResultNotice(spill: WithheldSpill, auditDurable: boolean
       : spill.error === undefined
         ? `Its result is in workspace file ${spill.path}.`
         : `Writing its result to workspace file ${spill.path} failed, so it ${keptIn('only ')}.`;
+  const readable = kind === 'error' && !!spill && 'path' in spill && spill.error === undefined && !spill.unfinished;
+  const readFirst = readable ? ' Read it before calling again.' : '';
   const fields = kept === undefined ? '' : ` Kept from its result: ${kept}`;
-  return `${TOOL_RESULT_GUARD_NOTICE} ${place}${fields}`;
+  return `${GUARD_NOTICES[kind]} ${place}${readFirst}${fields}`;
 }
 
 /**
@@ -140,6 +153,7 @@ interface PendingBatch {
   /** What each result's stub keeps if the batch is withheld, by its index in
    *  content: the fields its tool marked (keptWhenWithheld). */
   kept: Map<number, string>;
+  notices: Map<string, WithheldNoticeKind>;
 }
 
 interface AuditOperation {
@@ -248,7 +262,7 @@ export class ToolResultGuard {
         if (block.type === 'image') images += 1;
         else chars += JSON.stringify(block).length;
       }
-      chars -= TOOL_RESULT_GUARD_NOTICE.length;
+      chars -= GUARD_NOTICES[pending.notices.get(result.toolUseId) ?? 'ran'].length;
     }
     return Math.max(0, Math.ceil(chars / 4) + images * 1600);
   }
@@ -361,12 +375,13 @@ export class ToolResultGuard {
       // with a placeholder if the audit cannot become durable below.
       console.error(`[tool-result-guard] agent=${this.agentName} staged audit write queued:`, error);
     }
+    const results = new Map(originals.map((call) => [call.id, call.result]));
+    const notices = new Map([...results].map(([id, result]) => [id, noticeKind(result)]));
     const withheld: ContentBlock[] = content.map((block) => block.type === 'tool_result'
-      ? { type: 'tool_result', toolUseId: block.toolUseId, content: TOOL_RESULT_GUARD_NOTICE, isError: block.isError }
+      ? { type: 'tool_result', toolUseId: block.toolUseId, content: GUARD_NOTICES[notices.get(block.toolUseId) ?? 'ran'], isError: block.isError }
       : block);
     // What each stub keeps if the batch is withheld, matched to its tool's
     // result by tool use id, keyed by index as the stubs and files are.
-    const results = new Map(originals.map((call) => [call.id, call.result]));
     const kept = new Map<number, string>();
     for (const [index, block] of content.entries()) {
       const result = block.type === 'tool_result' ? results.get(block.toolUseId) : undefined;
@@ -379,7 +394,7 @@ export class ToolResultGuard {
     // which is correct since a reopened guard has no pending batch.
     const messageId = this.cm.addMessage('user', withheld, metadata, undefined, { holdCompression: true });
     this.pending = { id, messageId, content, withheld, wireResults,
-      branch: this.cm.currentBranch().name, submitted: false, durable: false, kept };
+      branch: this.cm.currentBranch().name, submitted: false, durable: false, kept, notices };
     // Durability barrier: the audit must reach Chronicle's chain heads before
     // the originals can go to a provider. On a failed sync the batch fails
     // CLOSED: the placeholders go on the wire instead (the turn continues,
@@ -406,7 +421,7 @@ export class ToolResultGuard {
     if (pending.durable) { pending.submitted = true; return results; }
     const ids = new Set(pending.wireResults.map((result) => result.toolUseId));
     return results.map((result) => ids.has(result.toolUseId)
-      ? { ...result, content: TOOL_RESULT_GUARD_NOTICE } : result);
+      ? { ...result, content: GUARD_NOTICES[pending.notices.get(result.toolUseId) ?? 'ran'] } : result);
   }
 
   /** The stream carrying this batch ended without a clean round (abort or
@@ -603,7 +618,7 @@ export class ToolResultGuard {
           spills.set(index, spill);
         }
         const annotated: ContentBlock[] = pending.withheld.map((block, index) => block.type === 'tool_result'
-          ? { ...block, content: withheldResultNotice(spills.get(index) ?? null, pending.durable, pending.kept.get(index)) }
+          ? { ...block, content: withheldResultNotice(spills.get(index) ?? null, pending.durable, pending.kept.get(index), pending.notices.get(block.toolUseId)) }
           : block);
         try {
           this.append({

package/src/tune-out/tools.ts

@@ -113,7 +113,10 @@ export interface SubconsciousConfig {
    * agent-prefixed identifier.
    */
   name?: string;
-  /** Model id; defaults to the primary agent's (same-model side-process). */
+  /** Model id; defaults to the primary agent's (same-model side-process).
+   *  Another id, compared exactly, makes the subconscious leave out the
+   *  fields that describe the primary's model, its window and its thinking
+   *  binding (SUBCONSCIOUS_MODEL_FIELDS); nothing here sets its own. */
   model?: string;
   /**
    * The voice/criteria mode block — recipe-side and co-authored with the

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;
@@ -254,7 +255,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 +558,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;
@@ -597,11 +617,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

@@ -299,6 +299,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

@@ -232,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>;
 }
 

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 & {