@animalabs/agent-framework 0.7.4 → 0.9.0

package/src/types/framework.ts

@@ -58,6 +58,16 @@ export interface CodeExecutionConfig {
    * 0 disables reclaim.
    */
   idleReclaimMs?: number;
+  /** Max concurrent background (daemon) scripts per agent (default 3). */
+  maxBackgroundScripts?: number;
+  /** Background script lifetime ceiling, ms (default 86_400_000 = 24h). */
+  backgroundMaxLifetimeMs?: number;
+  /** Minimum interval between wake_agent() deliveries, ms (default 60_000).
+   *  Early wakes are delayed, not dropped (backpressure inside the script). */
+  wakeMinIntervalMs?: number;
+  /** Max wake_agent() calls per background script (default 100); further
+   *  calls raise RuntimeError inside the script. */
+  maxWakesPerScript?: number;
 }
 
 export interface FrameworkConfig {
@@ -128,6 +138,23 @@ export interface FrameworkConfig {
    */
   codeExecution?: CodeExecutionConfig;
 
+  /**
+   * Durable inline cap (chars) for tool results — successes AND errors — and
+   * background-script wake payloads. Content over the cap is written to a
+   * workspace file under `tool-results/` (deterministic `<date>-<callId>.txt`
+   * name, overwritten on collision, retained until the workspace owner
+   * deletes it — never auto-GC'd) and replaced inline by a bounded preview
+   * plus the file reference; with no writable workspace the fallback is
+   * explicit plain truncation. Default 5000 (house-safe; issue #89). Must be
+   * >= 1000. A resident's own agent_settings value
+   * `tool_result_inline_max_chars` (durable, persisted in framework state)
+   * takes precedence over this for that agent; the EFFECTIVE cap for every
+   * source is min(desired, strategy bound) — desired values above the
+   * strategy-derived bound (maxMessageTokens * 4) are hard-clamped to it,
+   * with the clamp reported via agent_settings get.
+   */
+  toolResultInlineMaxChars?: number;
+
   /** Inference routing policy for server-initiated inference (optional). */
   inferenceRouting?: InferenceRoutingPolicy;
 

package/src/types/module.ts

@@ -63,6 +63,18 @@ export interface Module {
    */
   getTools(): ToolDefinition[];
 
+  /**
+   * 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.
+   */
+  getUtilities?(): ToolDefinition[];
+
   /**
    * Handle a tool call.
    * Tool name is without module prefix.
@@ -298,6 +310,18 @@ export interface ModuleContext {
    * leaking listeners across teardown/recreate (e.g. session switch).
    */
   onTrace(listener: TraceEventListener): () => void;
+
+  /**
+   * Raise an operator-facing ops alert through the framework's ops channel
+   * (failures.log + `ops:alert` trace + the ops webhook, when configured).
+   * For module actions that change durable state the operator would otherwise
+   * discover by surprise — e.g. subscription GC closing a channel. Keep the
+   * message privacy-minimal: identifiers and thresholds, not content.
+   *
+   * Optional so modules built against this version degrade gracefully on an
+   * older framework: call as `ctx.notifyOps?.(...)`.
+   */
+  notifyOps?(kind: string, agentName: string, message: string, data?: Record<string, unknown>): void;
 }
 
 /**

package/src/types/trace.ts

@@ -169,6 +169,19 @@ export type TraceEvent =
       agentStatus: string;
       result: unknown;
     })
+  | (TraceEventBase & {
+      /**
+       * A writable workspace existed but the oversized-result spill write
+       * failed (size cap, storeBlob failure, …) — the over-cap tail was NOT
+       * retained. Distinct from the no-workspace fallback, which is silent
+       * by design (nothing unexpected happened).
+       */
+      type: 'tool:spill_failed';
+      label: string;
+      path: string;
+      contentLength: number;
+      error: string;
+    })
 
   // Module lifecycle
   | (TraceEventBase & { type: 'module:added'; moduleName: string })
@@ -339,6 +352,15 @@ export type TraceEvent =
       /** True when a background reconnect loop will keep retrying. */
       willRetry: boolean;
     })
+  | (TraceEventBase & {
+      /** §17.6: the ONE normalized receipt per manifest change — closed
+       *  host-derived impact vocabulary, never a server-authored flag. */
+      type: 'mcpl:manifest-change-receipt';
+      serverId: string;
+      revision: string | null;
+      announcedDomains: string[];
+      impacts: Array<{ impact: string; subject: string; disposition: string }>;
+    })
   | (TraceEventBase & {
       type: 'mcpl:server-reconnected';
       serverId: string;