@animalabs/agent-framework 0.19.0 → 0.21.0

package/src/tool-result-guard.ts

@@ -0,0 +1,318 @@
+import { randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import type { ContextManager, MessageId } from '@animalabs/context-manager';
+import type { ContentBlock, NormalizedMessage, ToolResult } from '@animalabs/membrane';
+import type { CompletedToolCall } from './types/index.js';
+import { isStateExistsError } from './module-registry.js';
+
+export const TOOL_RESULT_GUARD_NOTICE = 'Tool result withheld by the guard. The tool has already executed.';
+export const TOOL_RESULT_GUARD_AUDIT_STATE = 'framework/tool-result-guard';
+
+interface PendingBatch {
+  id: string;
+  messageId: MessageId;
+  content: ContentBlock[];
+  withheld: ContentBlock[];
+  branch: string;
+  wireResults: ToolResult[];
+  submitted: boolean;
+  /** False when the audit sync failed: originals then never go on the wire. */
+  durable: boolean;
+}
+
+interface AuditOperation {
+  record: Record<string, unknown>;
+  /** Acceptance must finish this edit before its outcome can be recorded. */
+  admission?: { messageId: MessageId; content: ContentBlock[]; expected: ContentBlock[]; branch: string };
+  /** Retained while an acceptance edit needs retrying, not for audit-only retries. */
+  heldMessageId?: MessageId;
+}
+
+/**
+ * Admission of newly returned tool output to durable model-facing memory.
+ *
+ * Raw output is appended to a separate Chronicle audit slot BEFORE the
+ * placeholder enters the context manager. In particular, onNewMessage and
+ * speculative compression never see unaccepted output. Acceptance edits the
+ * placeholder through CM's versioned edit API; withholding only appends an
+ * audit event. Neither operation erases the original output or its blobs.
+ */
+export class ToolResultGuard {
+  private pending: PendingBatch | undefined;
+  private registered = false;
+  private override: boolean | undefined;
+  /** True until a recovery produces a clean response/new tool round. */
+  recovering = false;
+
+  constructor(
+    private readonly agentName: string,
+    private readonly cm: ContextManager,
+    private readonly configured = false,
+  ) {}
+
+  get enabled(): boolean { return this.override ?? this.configured; }
+  setOverride(value: boolean | undefined): void { this.override = value; }
+  get settingOverride(): boolean | undefined { return this.override; }
+  get hasPending(): boolean { return this.pending !== undefined; }
+  /** True only once the pending batch's originals were actually put on the
+   * wire. Guard effects (retry suppression, refusal claim, prose buffering)
+   * are scoped to this state; a merely staged batch never claims a refusal. */
+  get hasSubmittedPending(): boolean { return this.pending?.submitted === true; }
+
+  /** Extra input tokens the pending batch costs on the wire beyond the
+   * placeholder the strategy selected against (chars/4 + flat per image,
+   * the same heuristic as the physical-window projection). Compilation
+   * reserves this so substituting originals cannot exceed the budget. */
+  get pendingWireReserveTokens(): number {
+    const pending = this.pending;
+    if (!pending) return 0;
+    let chars = 0;
+    let images = 0;
+    for (const result of pending.wireResults) {
+      if (typeof result.content === 'string') chars += result.content.length;
+      else for (const block of result.content as ContentBlock[]) {
+        if (block.type === 'image') images += 1;
+        else chars += JSON.stringify(block).length;
+      }
+      chars -= TOOL_RESULT_GUARD_NOTICE.length;
+    }
+    return Math.max(0, Math.ceil(chars / 4) + images * 1600);
+  }
+
+  /** Ordered storage work, separate from batches awaiting a provider verdict.
+   * A failed acceptance edit retains both the payload and its compression
+   * hold here; it can never re-arm refusal handling or tool submission. */
+  private unrecorded: AuditOperation[] = [];
+
+  /** Retry edits and audit writes before a new activation, audit write,
+   * maintenance pass, or shutdown. A failed operation stays at the head. */
+  flushUnrecorded(): void {
+    while (this.unrecorded.length > 0) {
+      const operation = this.unrecorded[0];
+      try {
+        if (operation.admission) {
+          const { messageId, content, expected, branch } = operation.admission;
+          const sameBranch = this.cm.currentBranch().name === branch;
+          const current = sameBranch ? this.cm.getMessage(messageId) : null;
+          // A retry must not undo an operator's later edit/removal/rollback.
+          // Reapplying our own payload is safe if an earlier edit wrote the
+          // message and then failed while propagating to context entries.
+          // Chronicle normalizes object-key order and drops undefined fields.
+          if (!sameBranch || !current ||
+            (!isDeepStrictEqual(current.content, JSON.parse(JSON.stringify(expected)))
+              && !isDeepStrictEqual(current.content, JSON.parse(JSON.stringify(content))))) {
+            operation.record.historyUpdate = 'superseded';
+          } else {
+            this.cm.editMessage(messageId, content);
+          }
+          // An audit-only retry must not repeat an edit that already succeeded.
+          operation.admission = undefined;
+        }
+        this.write(operation.record);
+        this.unrecorded.shift();
+      } finally {
+        if (!operation.admission) this.releaseOperationHold(operation);
+      }
+    }
+  }
+
+  private append(record: Record<string, unknown>): void {
+    const stamped = { agentName: this.agentName, timestamp: Date.now(), ...record };
+    this.unrecorded.push({ record: stamped });
+    this.flushUnrecorded();
+  }
+
+  private write(record: Record<string, unknown>): void {
+    const store = this.cm.getStore();
+    if (!this.registered) {
+      try {
+        store.registerState({ id: TOOL_RESULT_GUARD_AUDIT_STATE, strategy: 'append_log' });
+      } catch (error) {
+        if (!isStateExistsError(error)) throw error;
+      }
+      this.registered = true;
+    }
+    store.appendToStateJson(TOOL_RESULT_GUARD_AUDIT_STATE, record);
+  }
+
+  private archive(value: unknown): unknown {
+    const json = JSON.stringify(value);
+    // Match inference-log storage: large payloads (especially images and
+    // pre-spill output) must not be copied into every append-log snapshot.
+    return json.length > 10_000
+      ? { blobId: this.cm.getStore().storeBlob(Buffer.from(json), 'application/json') }
+      : JSON.parse(json);
+  }
+
+  storeResults(content: ContentBlock[], wireResults: ToolResult[], originals: CompletedToolCall[]): MessageId {
+    if (!this.enabled) return this.cm.addMessage('user', content);
+    if (this.pending) {
+      // Idempotent for the same not-yet-submitted batch: a caller that
+      // retries after a failure between staging and submission (e.g. a
+      // transient compile error on the direct Agent API) must not wedge.
+      const same = !this.pending.submitted
+        && this.pending.wireResults.map((r) => r.toolUseId).join('\0')
+          === wireResults.map((r) => r.toolUseId).join('\0');
+      if (same) return this.pending.messageId;
+      throw new Error('Tool result guard already has a pending batch');
+    }
+    const id = randomUUID();
+    // Includes full pre-truncation/error/image payloads, not just the wire
+    // preview. This slot is audit data, never a context/compression source.
+    const staged = { type: 'staged', batchId: id,
+      originals: this.archive(originals), content: this.archive(content), wireResults: this.archive(wireResults) };
+    try {
+      this.append(staged);
+    } catch (error) {
+      // Keep the original in the retry queue, but let the tool loop continue
+      // with a placeholder if the audit cannot become durable below.
+      console.error(`[tool-result-guard] agent=${this.agentName} staged audit write queued:`, error);
+    }
+    const withheld: ContentBlock[] = content.map((block) => block.type === 'tool_result'
+      ? { type: 'tool_result', toolUseId: block.toolUseId, content: TOOL_RESULT_GUARD_NOTICE, isError: block.isError }
+      : block);
+    // Compression hold (CM >= 0.12): placed BEFORE onNewMessage fires, so no
+    // chunk is ever summarized from the placeholder; released after the
+    // settlement edit. Holds are in-memory only — a reopened manager has none,
+    // which is correct since a reopened guard has no pending batch.
+    const messageId = this.cm.addMessage('user', withheld, undefined, undefined, { holdCompression: true });
+    this.pending = { id, messageId, content, withheld, wireResults,
+      branch: this.cm.currentBranch().name, submitted: false, durable: false };
+    // 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,
+    // nothing is stranded), and the batch later settles as unsubmitted.
+    try {
+      // A linked-append failure follows the same fail-closed path as a sync
+      // failure. Throwing here would strand the stream awaiting its results.
+      this.append({ type: 'linked', batchId: id, messageId });
+      this.cm.getStore().sync();
+      this.pending.durable = true;
+    } catch (error) {
+      console.error(`[tool-result-guard] agent=${this.agentName} audit persistence failed; ` +
+        'submitting placeholders instead of originals:', error);
+    }
+    return messageId;
+  }
+
+  /** Results for a live continuation (provideToolResults). Marks the batch
+   * submitted and returns the originals only when the audit is durable;
+   * otherwise returns placeholder results and leaves it unsubmitted. */
+  submissionResults(results: ToolResult[]): ToolResult[] {
+    const pending = this.pending;
+    if (!pending) return results;
+    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);
+  }
+
+  /** The stream carrying this batch ended without a clean round (abort or
+   * exhausted errors). Settle conservatively — an interrupted submission
+   * does not establish acceptance — so a later turn neither resubmits the
+   * originals nor attributes its own refusal to this batch. */
+  abandon(reason: string): void {
+    const pending = this.pending;
+    this.recovering = false;
+    if (!pending) return;
+    this.settle(pending, { type: 'withheld', reason, submitted: pending.submitted }, false);
+  }
+
+
+  /** A budget/error restart compiles placeholders; restore pending output
+   * only in this provider request, never in the strategy's view. */
+  prepareRequest(messages: NormalizedMessage[], recordSubmission = false): NormalizedMessage[] {
+    const pending = this.pending;
+    if (!pending || !pending.durable) return messages;
+    const byId = new Map(pending.wireResults.map((result) => [result.toolUseId, result]));
+    const present = new Set(messages.flatMap((message) => message.content
+      .filter((block) => block.type === 'tool_result' && byId.has(block.toolUseId))
+      .map((block) => (block as ContentBlock & { toolUseId: string }).toolUseId)));
+    // A strategy may have folded the entire exchange away. Do not release
+    // content that was never submitted. Its originals remain in the audit.
+    const submitted = present.size === byId.size;
+    if (recordSubmission) pending.submitted = submitted;
+    if (!submitted) return messages;
+    return messages.map((message) => ({ ...message, content: message.content.map((block) => {
+      const result = block.type === 'tool_result' ? byId.get(block.toolUseId) : undefined;
+      return result ? { type: 'tool_result', toolUseId: result.toolUseId, content: result.content, isError: result.isError } : block;
+    }) }));
+  }
+
+  /** The turn ended (endTurn/skip_reply) before the batch was submitted:
+   * nothing was refused, so admit it exactly as an unguarded agent would.
+   * Leaving it pending would turn it into a permanent withheld notice on
+   * restart and disable ordinary refusal handling on the next turn. */
+  settleTurnEnded(): void {
+    const pending = this.pending;
+    if (!pending) return;
+    this.settle(pending, pending.durable
+      ? { type: 'accepted', reason: 'turn_ended' }
+      : { type: 'withheld', reason: 'audit_not_durable' }, pending.durable);
+  }
+
+  /** A refusal arrived while the pending batch was never on the wire (the
+   * strategy omitted the exchange). The guard cannot have caused it: record
+   * the batch as withheld, clear it, and let ordinary refusal handling run.
+   * Returns true when it settled such a batch. */
+  settleUnsubmitted(category: string): boolean {
+    const pending = this.pending;
+    if (!pending || pending.submitted) return false;
+    this.settle(pending, { type: 'withheld', reason: 'unsubmitted', category }, false);
+    return true;
+  }
+
+  /** A clean physical response accepts precisely the last submitted batch. */
+  accept(): void {
+    const pending = this.pending;
+    this.recovering = false;
+    if (!pending) return;
+    this.settle(pending, pending.submitted
+      ? { type: 'accepted' } : { type: 'withheld', reason: 'unsubmitted' }, pending.submitted);
+  }
+
+  /** At most one recovery per batch; no scanning/deleting older history. */
+  withhold(category: string): string[] | null {
+    const pending = this.pending;
+    if (!pending?.submitted) return null;
+    const ids = pending.wireResults.map((result) => result.toolUseId);
+    // Even a failed outcome-log write must never re-arm rejected output for
+    // a later submission. Its originals were archived before admission.
+    this.recovering = true;
+    this.settle(pending, { type: 'withheld', toolUseIds: ids, category }, false);
+    return ids;
+  }
+
+  /** Transfer ownership from provider admission to an ordered storage job.
+   * Failure retains the accepted payload and its hold until the edit succeeds.
+   * Withheld content is final already, so audit failures cannot keep it held. */
+  private settle(pending: PendingBatch, record: Record<string, unknown>, admit: boolean): void {
+    this.pending = undefined;
+    const operation: AuditOperation = {
+      record: { agentName: this.agentName, timestamp: Date.now(), ...record,
+        batchId: pending.id, messageId: pending.messageId, sourceBranch: pending.branch },
+      ...(admit ? { admission: { messageId: pending.messageId, content: pending.content,
+        expected: pending.withheld, branch: pending.branch } } : {}),
+      heldMessageId: pending.messageId,
+    };
+    this.unrecorded.push(operation);
+    try {
+      this.flushUnrecorded();
+    } catch (error) {
+      console.error(`[tool-result-guard] agent=${this.agentName} settlement queued for retry:`, error);
+    } finally {
+      if (!operation.admission) this.releaseOperationHold(operation);
+    }
+  }
+
+  private releaseOperationHold(operation: AuditOperation): void {
+    if (operation.heldMessageId !== undefined) {
+      this.releaseHold(operation.heldMessageId);
+      operation.heldMessageId = undefined;
+    }
+  }
+
+  private releaseHold(messageId: MessageId): void {
+    this.cm.releaseCompression([messageId]);
+  }
+}

package/src/types/agent.ts

@@ -170,6 +170,12 @@ export interface AgentConfig {
     announceHumanTurns?: boolean;
   };
 
+  /** Opt-in tool-output admission and one guarded retry after a provider
+   * refusal. Agents can persistently override this via agent_settings
+   * tool_result_guard. Full originals remain in Chronicle's audit history.
+   * Default false. Disabling does not restore previously withheld output. */
+  toolResultGuard?: boolean;
+
   /**
    * How the agent's PLAIN PROSE (non-tool output) reaches channels.
    * - 'locus' (default): host-inferred — the turn-frozen locus machinery.
@@ -296,6 +302,9 @@ export interface CompletedToolCall {
  * Inference request for an agent.
  */
 export interface InferenceRequest {
+  /** Host-owned identity for withdrawal of an unconsumed coalesced wake. */
+  coalescingSubject?: string;
+  coalescingEventId?: string;
   agentName: string;
   reason: string;
   source: string;
@@ -336,4 +345,10 @@ export interface InferenceRequest {
   wakeChannelId?: string;
   /** Timestamp of the event the wake provenance was taken from (ms). */
   wakeAt?: number;
+  /** Suppress every automatic plain-prose delivery for this logical turn.
+   * Explicit tool calls remain available. Used by authenticated silent wakes. */
+  suppressProse?: boolean;
+  /** Ephemeral system-position prompt for this turn only. Never written to
+   * Chronicle; callers must supply bounded non-secret control text. */
+  ephemeralSystemPrompt?: string;
 }

package/src/types/framework.ts

@@ -52,6 +52,12 @@ export interface CodeExecutionConfig {
   toolCallTimeoutMs?: number;
   /** Whole-script deadline: cancel → grace → SIGKILL (default 600_000 ms). */
   scriptTimeoutMs?: number;
+  /**
+   * Longest deadline an agent may ask for on one call with `time_limit_ms`
+   * (default: `scriptTimeoutMs`, so agents can only shorten it until this is
+   * raised). Longer requests are capped, and the result says so.
+   */
+  maxScriptTimeoutMs?: number;
   /**
    * Idle interpreter reclaim — script globals are lost after this much
    * inactivity (default 300_000 ms, mirroring ~5-minute container reclaim).
@@ -225,6 +231,23 @@ export interface FrameworkConfig {
    */
   toolResultInlineMaxChars?: number;
 
+  /**
+   * MCPL RFC-008 operator class overrides: RFC-007 §6.2 patterns over the
+   * model-facing tool name → classes. Highest-precedence source of a tool's
+   * effective class (first matching pattern wins); replaces, never merges
+   * with, what the providing server declared. Use it to correct or tighten a
+   * misclassed tool.
+   */
+  toolClassOverrides?: Record<string, string[]>;
+
+  /**
+   * MCPL RFC-008 host knowledge for tools the EMBEDDING host implements (its
+   * own modules), same shape as toolClassOverrides. Consulted before the
+   * framework's built-in table and never for MCPL-provided tools, whose
+   * class comes from an override or their server's `_meta["mcpl/class"]`.
+   */
+  hostToolClasses?: Record<string, string[]>;
+
   /** Inference routing policy for server-initiated inference (optional). */
   inferenceRouting?: InferenceRoutingPolicy;
 

package/src/types/trace.ts

@@ -48,6 +48,8 @@ export type TraceEvent =
        * activation with its channel without re-deriving routing.
        */
       channelId?: string;
+      /** True for a control-plane wake that must not surface typing/prose. */
+      silent?: boolean;
     })
   | (TraceEventBase & {
       type: 'inference:completed';
@@ -209,6 +211,21 @@ export type TraceEvent =
       messageId: string;
       source: string;
     })
+  /** An unread message withdrawn or replaced by its sender (RFC-006). */
+  | (TraceEventBase & {
+      type: 'message:removed';
+      messageId: string;
+      source: string;
+    })
+  /** RFC-006 coalescing decision record (received / displaced / removed /
+   *  rendered / revoked / render-cancelled / late-render / render-failed). */
+  | (TraceEventBase & {
+      type: 'mcpl:coalescing';
+      kind: string;
+      subject?: string;
+      eventId?: string;
+      [key: string]: unknown;
+    })
 
   // EventGate lifecycle
   | (TraceEventBase & {