@animalabs/agent-framework 0.29.0 → 0.31.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"}`). */
@@ -72,6 +72,8 @@ export interface HostPresentationDeps {
   isUtility(toolName: string): boolean;
   /** The resident agents of this host (no forks, ephemeral runs or the subconscious). */
   residents(): string[];
+  /** The agent whose presentation this one is shown: a derived agent that shows its parent's tool list, its parent; anyone else, itself. */
+  ownerOf?(agentName: string): string;
 }
 
 interface AgentState {
@@ -198,10 +200,15 @@ export class HostPresentation {
     return server?.configured === 'closed-tab' && !server.connected;
   }
 
+  /** The agent whose presentation `agentName` is shown (HostPresentationDeps.ownerOf). */
+  ownerOf(agentName: string): string {
+    return this.deps.ownerOf?.(agentName) ?? agentName;
+  }
+
   /** How a server is presented to an agent now. */
   presentation(agentName: string, serverId: string): ServerPresentation {
     if (this.isClosedTab(serverId)) return 'closed-tab';
-    const chosen = this.doc.agents[agentName]?.servers[serverId];
+    const chosen = this.doc.agents[this.ownerOf(agentName)]?.servers[serverId];
     if (chosen) return chosen;
     const configured = this.server(serverId)?.configured ?? 'full';
     return configured === 'closed-tab' ? 'tab' : configured;
@@ -218,7 +225,7 @@ export class HostPresentation {
   }
 
   isOpen(agentName: string, key: string): boolean {
-    return this.doc.agents[agentName]?.open.includes(key) ?? false;
+    return this.doc.agents[this.ownerOf(agentName)]?.open.includes(key) ?? false;
   }
 
   private setOpen(agentName: string, key: string, open: boolean): void {
@@ -267,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');
   }
@@ -311,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;
@@ -322,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. */
@@ -578,7 +582,7 @@ export class HostPresentation {
   openMarkers(agentName: string): Array<{ marker: string; reminder: () => string; dueWhenAbsent: true }> {
     if (!this.active(agentName)) return [];
     const out: Array<{ marker: string; reminder: () => string; dueWhenAbsent: true }> = [];
-    for (const key of this.doc.agents[agentName]?.open ?? []) {
+    for (const key of this.doc.agents[this.ownerOf(agentName)]?.open ?? []) {
       if (key === BUILTIN_TOOLSET) {
         out.push({
           marker: `${this.builtinLabel} open`,

package/src/index.ts

@@ -2,9 +2,10 @@
 export * from './types/index.js';
 
 // Core classes
-export { AgentFramework, BudgetPreflightError, DefaultErrorPolicy, ProviderWaitNotSleptError, QuiesceBlockedError, ResumeBlockedError } from './framework.js';
-export type { RuntimeSettingsPreview, HostModeStatus } from './framework.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';
@@ -15,6 +16,9 @@ export { CLOCK_ROW_KIND, resolveClockConfig } from './clock-rows.js';
 export type { ClockConfig, ClockStamp, ResolvedClockConfig } from './clock-rows.js';
 export { REFUSAL_REACTIONS, REFUSAL_REACTION_FALLBACK, REFUSAL_REACTION_BASELINE } from './refusal-reactions.js';
 
+// Dendrite: agent registry, lifecycle and presets
+export * from './dendrite/index.js';
+
 // Built-in modules
 export * from './modules/index.js';
 
@@ -196,6 +200,16 @@ export type {
 } from './recovery/offline-branch.js';
 
 export * from "./tool-presentation.js";
+
+// Tune-out: the subconscious configuration and the default reader-fork framing.
+export { presentAuthor, authorLine, authorNamed, ANONYMOUS_PARTICIPANT } from './author-presentation.js';
+export {
+  defaultReaderFraming,
+  type SubconsciousConfig,
+  type PersistentReaderConfig,
+  type ForkReaderConfig,
+  type ReaderFramingContext,
+} from './tune-out/tools.js';
 export {
   SILENT_HEARTBEAT_SEPARATOR,
   silentHeartbeatOf,

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;