@animalabs/agent-framework 0.30.0 → 0.32.0

package/src/gate/recipe-reconcile.ts

@@ -40,6 +40,8 @@
  * rule with no name is never merged: the merge keys rules by name.
  */
 
+import { quotedValue } from '../supplied-text.js';
+
 /** What a start changed, by rule name, for its trace and its log line. */
 export interface RecipeChanges {
   added: string[];
@@ -173,11 +175,11 @@ export function reconcileWithRecipe(
   const agree = (a: unknown, b: unknown): boolean => meaningOf(a) === meaningOf(b);
   const liveDuplicate = duplicateName(live.rules);
   if (liveDuplicate !== undefined) {
-    throw new Error(`gate.json names the rule "${liveDuplicate}" twice`);
+    throw new Error(`gate.json names the rule ${quotedValue(liveDuplicate)} twice`);
   }
   const recipeDuplicate = duplicateName(recipe.rules);
   if (recipeDuplicate !== undefined) {
-    throw new Error(`the recipe names the rule "${recipeDuplicate}" twice`);
+    throw new Error(`the recipe names the rule ${quotedValue(recipeDuplicate)} twice`);
   }
 
   const changes = noChanges();
@@ -322,7 +324,7 @@ export function reconcileLine(changes: RecipeChanges): string | null {
     parts.push(`the recorded recipe couldn't be read (${changes.recordUnreadable}), so this start removed and redefined nothing`);
   }
   const list = (label: string, names: string[]) => {
-    if (names.length > 0) parts.push(`${label} ${names.join(', ')}`);
+    if (names.length > 0) parts.push(`${label} ${names.map((name) => quotedValue(name)).join(', ')}`);
   };
   list('added', changes.added);
   list('removed', changes.removed);
@@ -332,13 +334,13 @@ export function reconcileLine(changes: RecipeChanges): string | null {
   list('kept as edited, though the recipe changed or dropped it:', changes.keptEdited);
   if (changes.differsFromRecipe.length > 0) {
     parts.push(
-      `kept, though the recipe defines it otherwise: ${changes.differsFromRecipe.join(', ')} `
+      `kept, though the recipe defines it otherwise: ${changes.differsFromRecipe.map((name) => quotedValue(name)).join(', ')} `
         + '(remove such a rule, and the next start restores it from the recipe)',
     );
   }
   if (changes.outsideRecipe.length > 0) {
     parts.push(
-      `kept, not in the recipe: ${changes.outsideRecipe.join(', ')} `
+      `kept, not in the recipe: ${changes.outsideRecipe.map((name) => quotedValue(name)).join(', ')} `
         + "(a stale one can be removed, and no start brings it back)",
     );
   }

package/src/host-presentation.ts

@@ -29,7 +29,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import type { ToolDefinition } from './types/events.js';
-import { checkArgs, firstSentence, renderToolDefinition, signature } from './mcpl/tool-signature.js';
+import { checkArgs, renderToolDefinition, toolLine } from './mcpl/tool-signature.js';
 import { META_TOOL_NAMES } from './mcpl/toolset-host.js';
 
 /** The built-in toolset's name, as agents address it (`toolsets--open {toolset: "settings"}`). */
@@ -274,10 +274,7 @@ export class HostPresentation {
   private announce(label: string, tools: ToolDefinition[], closeHint: string): string {
     const lines = [`${label} open: call these with ${META_TOOL_NAMES.act} {tool, args}; they aren't in your tool list.`];
     if (!tools.length) lines.push('  (none right now)');
-    for (const t of tools) {
-      const sentence = firstSentence(t.description);
-      lines.push(`  ${signature(t)}${sentence ? ` — ${sentence}` : ''}`);
-    }
+    for (const t of tools) lines.push(toolLine(t));
     lines.push(`${closeHint} closes it.`);
     return lines.join('\n');
   }
@@ -318,7 +315,7 @@ export class HostPresentation {
       const open = this.isOpen(agentName, BUILTIN_TOOLSET);
       return [
         `${this.builtinLabel} ${open ? 'open' : 'closed'}${open ? '' : ` — ${META_TOOL_NAMES.open} {toolset:"${BUILTIN_TOOLSET}"} opens it`}`,
-        ...tools.map((t) => `  ${signature(t)}${firstSentence(t.description) ? ` — ${firstSentence(t.description)}` : ''}`),
+        ...tools.map((t) => toolLine(t)),
       ].join('\n');
     }
     const { serverId } = which;
@@ -329,7 +326,7 @@ export class HostPresentation {
     const head = mode === 'full'
       ? `${this.tabLabel(serverId)} in your tool list${tools.length ? `; its hidden tools (${open ? 'open' : 'closed'}):` : '.'}`
       : `${this.tabLabel(serverId)} a tab, connected, ${open ? 'open' : `hidden — ${META_TOOL_NAMES.open} {server:"${serverId}"} opens it`}:`;
-    return [head, ...tools.map((t) => `  ${signature(t)}${firstSentence(t.description) ? ` — ${firstSentence(t.description)}` : ''}`)].join('\n');
+    return [head, ...tools.map((t) => toolLine(t))].join('\n');
   }
 
   /** `toolsets--look {tool}` for a host toolset's tool, or null when no host toolset has it. */

package/src/index.ts

@@ -5,6 +5,7 @@ export * from './types/index.js';
 export { AgentFramework, AgentStoppedError, BudgetPreflightError, DefaultErrorPolicy, ProviderWaitNotSleptError, QuiesceBlockedError, ResumeBlockedError } from './framework.js';
 export type { RuntimeSettingsPreview, HostModeStatus, DeriveAgentOptions } from './framework.js';
 export { Agent } from './agent.js';
+export { FLAT_MINIMUM_MS, type InferenceBoundsOptions } from './inference-bounds.js';
 export { storedInjectionMarkOf, type StoredInjectionMark } from './stored-injections.js';
 export type { StartStreamResult } from './agent.js';
 export { ProcessQueueImpl } from './queue.js';

package/src/inference-bounds.ts

@@ -0,0 +1,111 @@
+import { MembraneError } from '@animalabs/membrane';
+import { PROGRESS_BOUNDS, resolveProgressBounds, type ProgressBounds } from '@animalabs/membrane/progress-bounds';
+
+/** FrameworkConfig.inferenceBounds: how long the framework lets a model call
+ *  go without progress. */
+export interface InferenceBoundsOptions {
+  /** Membrane's phase bounds for a stream whose adapter reports content
+   *  (Anthropic, Bedrock), and the values the flat and whole-call bounds
+   *  derive from: the larger of `beforeContentMs` and `betweenEventsMs`,
+   *  plus `max_tokens` at `thinkTokensPerSecond`. Each one given replaces
+   *  membrane's default (PROGRESS_BOUNDS). */
+  progressBounds?: Partial<ProgressBounds>;
+  /** The least the flat bound on a stream can be, from its last provider
+   *  event. Default FLAT_MINIMUM_MS. */
+  flatMinimumMs?: number;
+}
+
+export const FLAT_MINIMUM_MS = 1_862_000;
+
+export interface InferenceBounds {
+  readonly progressBounds: Readonly<ProgressBounds>;
+  readonly flatMinimumMs: number;
+}
+
+export function resolveInferenceBounds(option: false | InferenceBoundsOptions | undefined): InferenceBounds | null {
+  if (option === false) return null;
+  if (option !== undefined && (typeof option !== 'object' || option === null)) {
+    throw new TypeError(`[agent-framework] inferenceBounds must be false or an object, got ${option === null ? 'null' : typeof option}`);
+  }
+  const given = option?.progressBounds;
+  if (given !== undefined && (typeof given !== 'object' || given === null)) {
+    throw new TypeError(`[agent-framework] inferenceBounds.progressBounds must be an object of bounds, got ${given === null ? 'null' : typeof given}`);
+  }
+  let progressBounds: ProgressBounds;
+  try {
+    progressBounds = resolveProgressBounds(given ?? true) ?? { ...PROGRESS_BOUNDS };
+  } catch (refused) {
+    const why = refused instanceof Error ? refused.message.replace(/^\[membrane\] /, '') : String(refused);
+    throw new (refused instanceof TypeError ? TypeError : RangeError)(`[agent-framework] inferenceBounds.${why}`);
+  }
+  const flatMinimumMs: unknown = option?.flatMinimumMs === undefined ? FLAT_MINIMUM_MS : option.flatMinimumMs;
+  if (typeof flatMinimumMs !== 'number' || !Number.isFinite(flatMinimumMs) || flatMinimumMs <= 0) {
+    throw new RangeError(`[agent-framework] inferenceBounds.flatMinimumMs must be a finite number above 0, got ${String(flatMinimumMs)}`);
+  }
+  return Object.freeze({ progressBounds: Object.freeze(progressBounds), flatMinimumMs });
+}
+
+function allowanceMs(bounds: Readonly<ProgressBounds>, maxTokens: number | undefined): number {
+  return typeof maxTokens === 'number' && Number.isFinite(maxTokens) && maxTokens > 0
+    ? Math.ceil(maxTokens / bounds.thinkTokensPerSecond) * 1000
+    : 0;
+}
+
+function setupMs(bounds: Readonly<ProgressBounds>): number {
+  return Math.max(bounds.beforeContentMs, bounds.betweenEventsMs);
+}
+
+export function streamBounds(
+  bounds: InferenceBounds | null,
+  maxTokens: number | undefined,
+): { progressBounds?: Readonly<ProgressBounds>; progressTimeoutMs?: number } {
+  if (bounds === null) return {};
+  const phases = bounds.progressBounds;
+  return {
+    progressBounds: phases,
+    progressTimeoutMs: Math.max(setupMs(phases) + allowanceMs(phases, maxTokens), bounds.flatMinimumMs),
+  };
+}
+
+export function wholeCallMs(bounds: InferenceBounds, maxTokens: number | undefined): number {
+  if (!(typeof maxTokens === 'number' && Number.isFinite(maxTokens) && maxTokens > 0)) return Math.max(setupMs(bounds.progressBounds), bounds.flatMinimumMs);
+  return setupMs(bounds.progressBounds) + allowanceMs(bounds.progressBounds, maxTokens);
+}
+
+// membrane 0.8.0 marks a deadline it reports as run out with this registered
+// symbol (on a sent request, or the Anthropic SDK's timeout, which covers its
+// connect timeout too) and exports no reader or marker for it. The one reader:
+// the deadline class here and the transient-failure check of an exhausted
+// turn's re-arm both use it.
+const DEADLINE_EXPIRY = Symbol.for('membrane.deadlineExpiry');
+
+export function isDeadlineExpiry(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && (error as Record<symbol, unknown>)[DEADLINE_EXPIRY] === true;
+}
+
+/**
+ * Names the host setting for the bound a stream cut hit, read from the opening
+ * of membrane 0.8.0's message for it (its progress-bounds.ts and
+ * providers/utils.ts), so the reason an operator and the agent see names the
+ * host's setting for that bound, as the README's table maps them. A message it
+ * doesn't know is left as it is.
+ */
+export function withHostSetting(message: string): string {
+  const setting = message.includes('of a thinking block\'s start') ? 'progressBounds.thinkTokensPerSecond'
+    : message.startsWith('No content within ') ? 'progressBounds.beforeContentMs'
+    : message.startsWith('No provider event within ') ? 'progressBounds.betweenEventsMs'
+    : message.startsWith('No provider progress within ') ? 'flatMinimumMs'
+    : undefined;
+  return setting === undefined ? message : `${message} (the host's setting for this bound: \`inferenceBounds.${setting}\`)`;
+}
+
+export function deadlineCut(message: string | undefined): MembraneError {
+  const error = new MembraneError({
+    type: 'timeout',
+    retryable: false,
+    message: message === undefined ? 'The provider made no progress within the call\'s bound' : withHostSetting(message),
+    rawError: undefined,
+  });
+  Object.defineProperty(error, DEADLINE_EXPIRY, { value: true });
+  return error;
+}

package/src/line-reader.ts

@@ -4,12 +4,26 @@ import { StringDecoder } from 'node:string_decoder';
 const LF = 0x0a;
 const CR = 0x0d;
 
-export function readLines(input: Readable, onLine: (line: string) => void, onEnd?: () => void): () => void {
+export const MAX_LINE_CHARS = 100 * 1024 * 1024;
+
+export interface LineHandlers {
+  line: (line: string) => void;
+  end?: () => void;
+  tooLong: (maxChars: number) => void;
+}
+
+export function readLines(input: Readable, on: LineHandlers, maxChars = MAX_LINE_CHARS): () => void {
   const decoder = new StringDecoder('utf8');
   let partial = '';
   let lineEndedAtCr = false;
   let stopped = false;
 
+  const refuse = () => {
+    stop();
+    partial = '';
+    on.tooLong(maxChars);
+  };
+
   const take = (text: string) => {
     let from = 0;
     if (lineEndedAtCr && text.length > 0) {
@@ -19,6 +33,7 @@ export function readLines(input: Readable, onLine: (line: string) => void, onEnd
     for (let i = from; i < text.length && !stopped; i++) {
       const code = text.charCodeAt(i);
       if (code !== LF && code !== CR) continue;
+      if (partial.length + (i - from) > maxChars) return refuse();
       const line = partial + text.slice(from, i);
       partial = '';
       if (code === CR) {
@@ -26,9 +41,11 @@ export function readLines(input: Readable, onLine: (line: string) => void, onEnd
         else if (text.charCodeAt(i + 1) === LF) i++;
       }
       from = i + 1;
-      onLine(line);
+      on.line(line);
     }
-    if (!stopped) partial += text.slice(from);
+    if (stopped) return;
+    if (partial.length + (text.length - from) > maxChars) return refuse();
+    partial += text.slice(from);
   };
 
   const onData = (chunk: Buffer | string) => take(decoder.write(chunk));
@@ -37,11 +54,11 @@ export function readLines(input: Readable, onLine: (line: string) => void, onEnd
     if (!stopped && partial.length > 0) {
       const last = partial;
       partial = '';
-      onLine(last);
+      on.line(last);
     }
     if (stopped) return;
     stop();
-    onEnd?.();
+    on.end?.();
   };
   const stop = () => {
     stopped = true;

package/src/mcpl/errors.ts

@@ -68,6 +68,10 @@ export function boundedForLog(text: string, max = 200): string {
   return points.length > max ? `${points.slice(0, max).join('')}…` : points.join('');
 }
 
+export function hostStoppedWhileHandling(): JsonRpcError {
+  return { code: -32000, message: 'the host stopped while handling this request' };
+}
+
 /**
  * Create a "feature set not enabled" error.
  * Returned when a server sends a message tagged with a feature set

package/src/mcpl/inbound-source.ts

@@ -167,8 +167,8 @@ export function conversationKey(source: InboundSource): string | undefined {
  * well-formed is dropped (the store doesn't keep it). An `undefined` array
  * element is written as `null`, as JSON writes it: the store's append
  * refuses a body holding one, so no stored copy does. So a value
- * hashes alike however its keys were ordered (content read back from the
- * store has them in a different order than it was written), and alike
+ * hashes alike however its keys were ordered (a store on chronicle before
+ * 0.5.1 hands content back with its keys sorted), and alike
  * before and after the store. editMessage writes JSON instead, so an edited
  * copy can keep what an append wouldn't; it has changed anyway.
  *

package/src/mcpl/inference-router.ts

@@ -25,8 +25,10 @@ import type {
 } from './types.js';
 import type { FeatureSetManager } from './feature-set-manager.js';
 import { McplFeatureSetError } from './feature-set-manager.js';
+import { hostStoppedWhileHandling } from './errors.js';
 import type { HookOrchestrator } from './hook-orchestrator.js';
 import { logValue } from './log-value.js';
+import { streamBounds, wholeCallMs, withHostSetting, type InferenceBounds } from '../inference-bounds.js';
 
 // ============================================================================
 // Responder interface
@@ -41,6 +43,7 @@ interface Responder {
   /** Sends a streamed chunk on the transport the request came on, as its
    *  answer is sent. */
   sendChunk?(params: InferenceChunkParams): void;
+  signal?: AbortSignal;
 }
 
 // ============================================================================
@@ -186,6 +189,7 @@ export class InferenceRouter {
    *  server with no policy, and per server and feature set with one, so a
    *  server that keeps asking doesn't flood the operator's log. */
   private loggedRefusals = new Set<string>();
+  private running = new Set<{ serverId: string; stop: AbortController; answered: Promise<void> }>();
 
   constructor(
     membrane: Membrane,
@@ -193,6 +197,7 @@ export class InferenceRouter {
     featureSetManager: FeatureSetManager,
     routingPolicy: InferenceRoutingPolicy | null,
     emitTraceFn: (event: { type: string; [key: string]: unknown }) => void,
+    private readonly inferenceBounds: () => InferenceBounds | null = () => null,
   ) {
     this.membrane = membrane;
     this.hookOrchestrator = hookOrchestrator;
@@ -216,6 +221,31 @@ export class InferenceRouter {
     serverId: string,
     params: McplInferenceRequestParams,
     responder: Responder,
+  ): Promise<void> {
+    const stop = new AbortController();
+    let ended!: () => void;
+    const entry = { serverId, stop, answered: new Promise<void>((resolve) => { ended = resolve; }) };
+    this.running.add(entry);
+    try {
+      await this.answer(serverId, params, responder, stop.signal);
+    } finally {
+      this.running.delete(entry);
+      ended();
+    }
+  }
+
+  stopAll(): Array<{ label: string; promise: Promise<void> }> {
+    return [...this.running].map(({ serverId, stop, answered }) => {
+      stop.abort();
+      return { label: `inference/request:${serverId}`, promise: answered };
+    });
+  }
+
+  private async answer(
+    serverId: string,
+    params: McplInferenceRequestParams,
+    responder: Responder,
+    stopped: AbortSignal,
   ): Promise<void> {
     // 1. Validate feature set
     try {
@@ -295,6 +325,24 @@ export class InferenceRouter {
       return;
     }
 
+    const signal = responder.signal ? AbortSignal.any([stopped, responder.signal]) : stopped;
+    let stopAnswered = false;
+    const answerStop = () => {
+      if (responder.signal?.aborted) return;
+      stopAnswered = true;
+      const answer = hostStoppedWhileHandling();
+      this.emitTraceFn({ type: 'mcpl:inference_fail', serverId, model, error: answer.message, streamed });
+      // A throw from an abort listener would be uncaught.
+      try {
+        responder.respondError(answer.code, answer.message);
+      } catch {}
+    };
+    stopped.addEventListener('abort', answerStop, { once: true });
+    const settled = (): boolean => {
+      stopped.removeEventListener('abort', answerStop);
+      return stopAnswered;
+    };
+
     // Emit trace: inference start
     this.emitTraceFn({
       type: 'mcpl:inference_start',
@@ -319,12 +367,14 @@ export class InferenceRouter {
       },
     };
 
+    if (stopAnswered) return;
     try {
       // 5. Run inference. Both modes end in membrane's response, and one
       // builder makes the result from it.
       const response = chunkRequestId != null
-        ? await this.streamResponse(request, chunkRequestId, sendChunk!)
-        : await this.membrane.complete(request);
+        ? await this.streamResponse(request, chunkRequestId, sendChunk!, signal)
+        : await this.membrane.complete(request, { ...this.wholeCallBound(request), signal });
+      if (settled()) return;
 
       // 6. Answer
       const result = resultFrom(response, model);
@@ -344,22 +394,23 @@ export class InferenceRouter {
 
       responder.respond(result);
     } catch (err) {
+      if (settled()) return;
       // Every ending that isn't a completion lands here, in either mode:
       // membrane's error, a stream that stopped early, a tool call, or a
       // stop FinishReason can't name. The answer is the JSON-RPC error, never
       // a result carrying what arrived.
+      const transportClosed = responder.signal?.aborted === true;
       this.emitTraceFn({
         type: 'mcpl:inference_fail',
         serverId,
         model,
-        error: err instanceof Error ? err.message : String(err),
+        error: transportClosed ? 'the transport the request came on closed' : err instanceof Error ? err.message : String(err),
         streamed,
       });
 
-      responder.respondError(
-        -32603,
-        err instanceof Error ? err.message : 'Inference failed',
-      );
+      if (!transportClosed) {
+        responder.respondError(-32603, err instanceof Error ? err.message : 'Inference failed');
+      }
     }
   }
 
@@ -407,6 +458,11 @@ export class InferenceRouter {
   // Private: Streaming
   // ==========================================================================
 
+  private wholeCallBound(request: NormalizedRequest): { progressTimeoutMs?: number } {
+    const bounds = this.inferenceBounds();
+    return bounds === null ? {} : { progressTimeoutMs: wholeCallMs(bounds, request.config.maxTokens) };
+  }
+
   /**
    * Run the inference as a stream, sending each visible text delta to the
    * server as an inference/chunk, and return membrane's response once the
@@ -424,8 +480,9 @@ export class InferenceRouter {
     request: NormalizedRequest,
     requestId: string | number,
     sendChunk: (params: InferenceChunkParams) => void,
+    signal: AbortSignal,
   ): Promise<NormalizedResponse> {
-    const stream = this.membrane.streamYielding(request);
+    const stream = this.membrane.streamYielding(request, { ...streamBounds(this.inferenceBounds(), request.config.maxTokens), signal });
     let index = 0;
 
     for await (const event of stream) {
@@ -437,7 +494,7 @@ export class InferenceRouter {
           // XML tool mode the chunks can miss text the content holds: prose
           // naming a tag the stream parser opens a block for, or a thinking
           // block cut off before its close tag.
-          if (event.meta.visible) {
+          if (event.meta.visible && !signal.aborted) {
             sendChunk({ requestId, index: index++, delta: event.content });
           }
           break;
@@ -448,7 +505,7 @@ export class InferenceRouter {
         case 'error':
           throw event.error;
         case 'aborted':
-          throw new Error(`The inference stopped before it finished (${event.reason})`);
+          throw new Error(`The inference stopped before it finished (${event.reason}${event.message ? `: ${event.reason === 'timeout' ? withHostSetting(event.message) : event.message}` : ''})`);
       }
     }
     throw new Error('The inference stream ended without a result');