@animalabs/agent-framework 0.7.4 → 0.8.0

package/src/mcpl/channel-registry.ts

@@ -337,6 +337,21 @@ interface ChannelRegistryOptions {
 // ChannelRegistry
 // ============================================================================
 
+/**
+ * Who is actually making a channel tool call, as established by the
+ * framework's own dispatch — model-origin calls come through
+ * dispatchToolCall (which knows the agent), module calls come through
+ * ModuleContext.callTool. Tool INPUT can claim anything; this cannot.
+ */
+export type ChannelToolOrigin =
+  | { kind: 'module'; moduleName?: string }
+  | { kind: 'agent'; agentName: string };
+
+/** The machine decision sources a module-origin channel_close may record.
+ *  Closed on purpose: honest provenance means a small, auditable vocabulary,
+ *  not arbitrary self-description. */
+export const MACHINE_CLOSE_SOURCES = new Set(['subscription-gc', 'housekeeping']);
+
 export class ChannelRegistry {
   private serverRegistry: McplServerRegistry;
   private featureSetManager: FeatureSetManager;
@@ -855,8 +870,21 @@ export class ChannelRegistry {
 
   /**
    * Handle a call to one of the synthesized channel tools.
+   *
+   * `origin` is TRUSTED DISPATCH CONTEXT, supplied by the framework's own
+   * routing (dispatchChannelToolCall and the public executeToolCall for
+   * model-origin calls, the framework's private ModuleRegistry closure for
+   * module ctx.callTool) — never derived from tool input. Machine
+   * provenance on channel_close is honored only for module origin; a
+   * model-origin call carrying the same fields is recorded as the agent
+   * decision it actually is. Absent origin is treated as agent-origin (the
+   * untrusted-safe default).
    */
-  async handleChannelToolCall(toolName: string, input: unknown): Promise<ToolResult> {
+  async handleChannelToolCall(
+    toolName: string,
+    input: unknown,
+    origin?: ChannelToolOrigin,
+  ): Promise<ToolResult> {
     switch (toolName) {
       case 'channel_list':
         return this.handleToolList();
@@ -870,7 +898,15 @@ export class ChannelRegistry {
         });
 
       case 'channel_close':
-        return this.handleToolClose(input as { channelId: string; serverId?: string });
+        return this.handleToolClose(
+          input as {
+            channelId: string;
+            serverId?: string;
+            source?: string;
+            overrideExplicitOpen?: boolean;
+          },
+          origin,
+        );
 
       case 'channel_decline':
         return this.handleToolDecline(input as {
@@ -1588,7 +1624,25 @@ export class ChannelRegistry {
     }
   }
 
-  private async handleToolClose(input: { channelId: string; serverId?: string }): Promise<ToolResult> {
+  private async handleToolClose(
+    input: {
+      channelId: string;
+      serverId?: string;
+      /** Machine callers name their decision source ('subscription-gc',
+       *  'housekeeping') so the durable record carries honest provenance.
+       *  Honored ONLY for module-origin dispatch — tool input is untrusted,
+       *  so a model-origin call carrying this field is still recorded as
+       *  'agent-tool' (the resident may close their own channel; they may
+       *  not attribute the act to housekeeping). */
+      source?: string;
+      /** A machine close aimed at an explicitly-opened channel is refused
+       *  unless the caller certifies an explicit idle lease (a configured
+       *  per-channel budget is consent to close at that budget). Module
+       *  origin only, like `source`. */
+      overrideExplicitOpen?: boolean;
+    },
+    origin?: ChannelToolOrigin,
+  ): Promise<ToolResult> {
     const resolved = this.resolveToolChannelEntry(input.channelId, input.serverId);
     const entry = resolved.entry;
     if (!entry) {
@@ -1607,7 +1661,47 @@ export class ChannelRegistry {
       };
     }
 
-    this.setDesiredState(entry.serverId, input.channelId, 'closed', 'agent-tool');
+    // Provenance comes from trusted dispatch, not from self-description:
+    // only module-origin calls may record a machine source, and only from
+    // the closed vocabulary. Agent-origin (or origin-less — the safe
+    // default for any legacy caller) records 'agent-tool' and has its
+    // machine fields ignored entirely.
+    const isModuleOrigin = origin?.kind === 'module';
+    let closeSource = 'agent-tool';
+    if (isModuleOrigin && input.source !== undefined) {
+      if (!MACHINE_CLOSE_SOURCES.has(input.source)) {
+        return {
+          success: false,
+          isError: true,
+          error:
+            `Unknown machine close source '${input.source}'. Machine closes must use one of: ` +
+            `${[...MACHINE_CLOSE_SOURCES].join(', ')}.`,
+        };
+      }
+      closeSource = input.source;
+    }
+
+    // Housekeeping must not override stated intent (issue #5: GC closes wore
+    // the agent's badge and reset explicitly-opened doors). A machine-sourced
+    // close of a channel whose current desired state is an agent/operator
+    // 'open' is refused — structurally, so the caller can stand down rather
+    // than retry — unless it certifies an explicit idle lease.
+    if (isModuleOrigin && closeSource !== 'agent-tool' && !input.overrideExplicitOpen) {
+      const current = this.desiredStates.get(this.lifecycleKey(entry.serverId, input.channelId));
+      if (current?.state === 'open' && current.source === 'agent-tool') {
+        return {
+          success: false,
+          isError: false,
+          error:
+            `Channel ${input.channelId} was explicitly opened (source: agent-tool); ` +
+            `a '${closeSource}' close does not override stated intent. Machine closes ` +
+            `of explicit opens require an explicit idle lease (overrideExplicitOpen).`,
+          data: { refusal: 'explicit-open', channelId: input.channelId },
+        };
+      }
+    }
+
+    this.setDesiredState(entry.serverId, input.channelId, 'closed', closeSource);
     this.stopTyping(input.channelId);
 
     const server = this.serverRegistry.getServer(entry.serverId);

package/src/mcpl/transport.ts

@@ -200,8 +200,26 @@ export class WebSocketTransport extends McplTransport {
    * when `config.token` is set. Rejects on connect error / timeout (and tears
    * the socket down) so a failed dial never leaks an open handle.
    */
-  static open(config: McplServerConfig): Promise<WebSocketTransport> {
-    const url = buildWebSocketUrl(config);
+  static async open(config: McplServerConfig): Promise<WebSocketTransport> {
+    // Resolve the per-dial credential first: the provider runs on every
+    // connect AND reconnect, so rotation happens at the transport layer and
+    // nothing above it ever holds a credential.
+    let token: string | null = config.token ?? null;
+    if (config.accessProvider) {
+      try {
+        token = (await config.accessProvider()) ?? token;
+      } catch (err) {
+        // Fall back to the static token (if any) rather than failing the dial
+        // outright — the server will refuse a stale credential loudly anyway.
+        console.error(
+          `[mcpl] server "${config.id}": access provider failed (${err instanceof Error ? err.message : err}) — dialing with configured fallback`,
+        );
+      }
+    }
+    const url = buildWebSocketUrl(config, token);
+    // Error strings travel: traces, logs, tool results the model reads. They
+    // get the endpoint, never the credential.
+    const redacted = buildWebSocketUrl({ ...config, token: undefined }, null);
     const ws = new WebSocket(url);
 
     return new Promise<WebSocketTransport>((resolve, reject) => {
@@ -211,7 +229,7 @@ export class WebSocketTransport extends McplTransport {
         settled = true;
         ws.removeAllListeners();
         try { ws.terminate(); } catch { /* already gone */ }
-        reject(new Error(`MCPL server "${config.id}" WebSocket connect timed out after ${WS_OPEN_TIMEOUT_MS}ms (${url})`));
+        reject(new Error(`MCPL server "${config.id}" WebSocket connect timed out after ${WS_OPEN_TIMEOUT_MS}ms (${redacted})`));
       }, WS_OPEN_TIMEOUT_MS);
 
       ws.once('open', () => {
@@ -228,7 +246,7 @@ export class WebSocketTransport extends McplTransport {
         clearTimeout(timer);
         ws.removeAllListeners();
         try { ws.terminate(); } catch { /* already gone */ }
-        reject(new Error(`MCPL server "${config.id}" WebSocket connect failed: ${err.message} (${url})`));
+        reject(new Error(`MCPL server "${config.id}" WebSocket connect failed: ${err.message} (${redacted})`));
       });
     });
   }
@@ -261,7 +279,7 @@ export class WebSocketTransport extends McplTransport {
  * Build the dial URL: validate it's a ws(s):// URL and append the auth token as
  * a `token` query param when provided (preserving any existing query).
  */
-export function buildWebSocketUrl(config: McplServerConfig): string {
+export function buildWebSocketUrl(config: McplServerConfig, tokenOverride?: string | null): string {
   if (!config.url) {
     throw new Error(`MCPL server "${config.id}": websocket transport requires "url" (none provided)`);
   }
@@ -276,8 +294,9 @@ export function buildWebSocketUrl(config: McplServerConfig): string {
       `MCPL server "${config.id}": websocket url must be ws:// or wss://, got "${parsed.protocol}"`,
     );
   }
-  if (config.token) {
-    parsed.searchParams.set('token', config.token);
+  const token = tokenOverride !== undefined ? tokenOverride : config.token;
+  if (token) {
+    parsed.searchParams.set('token', token);
   }
   return parsed.toString();
 }

package/src/mcpl/types.ts

@@ -198,6 +198,17 @@ export interface McplServerConfig {
    */
   token?: string;
 
+  /**
+   * Lazily resolves the connection credential at EVERY dial — first connect
+   * and each background reconnect — overriding `token` when it returns a
+   * value (null/throw falls back to `token`). Host-attached plumbing, never
+   * serialized: the point is that credentials stay out of the agent's
+   * context entirely (the agent asks for access by name; the host fetches
+   * something fresh each redial, which also makes short-lived credentials
+   * viable where a static `token` forced long ones).
+   */
+  accessProvider?: () => Promise<string | null>;
+
   /** Feature sets to enable on connect */
   enabledFeatureSets?: string[];
 

package/src/module-registry.ts

@@ -75,6 +75,15 @@ export class ModuleRegistry {
   private pushEventFn: (event: ProcessEvent) => void;
   private onTraceFn: (listener: TraceEventListener) => () => void;
   private callToolFn: (call: ToolCall) => Promise<ToolResult>;
+  /** Framework ops-alert channel, surfaced to modules via
+   *  ModuleContext.notifyOps. Readonly-public so ModuleContextImpl can
+   *  delegate without another positional constructor parameter. */
+  readonly notifyOpsFn?: (
+    kind: string,
+    agentName: string,
+    message: string,
+    data?: Record<string, unknown>,
+  ) => void;
 
   constructor(
     store: JsStore,
@@ -89,6 +98,7 @@ export class ModuleRegistry {
       pushEvent: (event: ProcessEvent) => void;
       onTrace: (listener: TraceEventListener) => () => void;
       callTool: (call: ToolCall) => Promise<ToolResult>;
+      notifyOps?: (kind: string, agentName: string, message: string, data?: Record<string, unknown>) => void;
     }
   ) {
     this.store = store;
@@ -102,6 +112,7 @@ export class ModuleRegistry {
     this.pushEventFn = options.pushEvent;
     this.onTraceFn = options.onTrace;
     this.callToolFn = options.callTool;
+    this.notifyOpsFn = options.notifyOps;
   }
 
   /**
@@ -230,6 +241,25 @@ export class ModuleRegistry {
     return tools;
   }
 
+  /**
+   * All utilities from all modules, namespaced exactly like tools
+   * (`module--name`). See Module.getUtilities — these are deliberately kept
+   * out of the model-facing tool list and surfaced through the framework's
+   * `utils` meta-tool; dispatch goes through the same handleToolCall.
+   */
+  getAllUtilities(): ToolDefinition[] {
+    const utilities: ToolDefinition[] = [];
+    for (const module of this.modules.values()) {
+      for (const util of module.getUtilities?.() ?? []) {
+        utilities.push({
+          ...util,
+          name: `${module.name}--${util.name}`,
+        });
+      }
+    }
+    return utilities;
+  }
+
   /**
    * Handle a tool call by routing to the appropriate module.
    */
@@ -556,6 +586,10 @@ class ModuleContextImpl implements ModuleContext {
     return this.callToolFn(call);
   }
 
+  notifyOps(kind: string, agentName: string, message: string, data?: Record<string, unknown>): void {
+    this.registry.notifyOpsFn?.(kind, agentName, message, data);
+  }
+
   addMessage(
     participant: string,
     content: ContentBlock[],

package/src/modules/workspace/index.ts

@@ -34,7 +34,7 @@ import type {
 } from './types.js';
 import { WORKSPACE_FS_EVENT_TYPES, opToEventType } from './types.js';
 import { MountWatcher, type FsChange } from './watcher.js';
-import { syncFromFs, materializeToFs, hashContent, DEFAULT_MAX_FILE_SIZE, type ConflictInfo } from './sync.js';
+import { syncFromFs, materializeToFs, hashContent, isBinary, DEFAULT_MAX_FILE_SIZE, type ConflictInfo } from './sync.js';
 
 export type {
   WorkspaceConfig,
@@ -525,6 +525,11 @@ export class WorkspaceModule implements Module {
   private config: WorkspaceConfig;
   private mounts = new Map<string, MountState>();
   private watchers = new Map<string, MountWatcher>();
+  /** Persisted state decoded in start(), held until mounts exist to apply it
+   *  to — in the Host ordering start() runs before initStore() creates the
+   *  mounts, so restoration must be second-callback-safe like watcher
+   *  startup already is (issue #72). Cleared after application. */
+  private savedState: WorkspaceModuleState | null = null;
 
   constructor(config: WorkspaceConfig) {
     // Detect overlapping mount paths: if mount A contains mount B,
@@ -593,32 +598,47 @@ export class WorkspaceModule implements Module {
       this.mounts.set(mount.name, mountState);
     }
 
+    this.applySavedState();
     this.ensureRunning();
   }
 
   async start(ctx: ModuleContext): Promise<void> {
     this.ctx = ctx;
 
-    // Restore persisted state if restarting
+    // Decode persisted state if restarting; application waits until mounts
+    // exist (see applySavedState) — in the Host ordering they don't yet.
     if (ctx.isRestart) {
-      const saved = ctx.getState<WorkspaceModuleState>();
-      if (saved) {
-        for (const [name, meta] of Object.entries(saved.mounts)) {
-          const mount = this.mounts.get(name);
-          if (mount) {
-            mount.lastMaterializedSeq = meta.lastMaterializedSeq;
-            mount.lastMaterializedBranchId = meta.lastMaterializedBranchId ?? null;
-            // watcherReadyAt intentionally not restored — each session must
-            // observe its own watcher attach, otherwise a stale timestamp
-            // would hide a new-session attach failure.
-          }
-        }
-      }
+      this.savedState = ctx.getState<WorkspaceModuleState>() ?? null;
     }
 
+    this.applySavedState();
     this.ensureRunning();
   }
 
+  /**
+   * Apply persisted per-mount state once both halves of the lifecycle have
+   * happened. Like watcher startup, either callback may fire second, so both
+   * start() and initStore() call this; it runs to effect exactly once — the
+   * saved payload is cleared after application so stale persisted values can
+   * never overwrite newer runtime state (e.g. a materialization that already
+   * happened this session).
+   */
+  private applySavedState(): void {
+    if (!this.savedState || this.mounts.size === 0) return;
+
+    for (const [name, meta] of Object.entries(this.savedState.mounts)) {
+      const mount = this.mounts.get(name);
+      if (mount) {
+        mount.lastMaterializedSeq = meta.lastMaterializedSeq;
+        mount.lastMaterializedBranchId = meta.lastMaterializedBranchId ?? null;
+        // watcherReadyAt intentionally not restored — each session must
+        // observe its own watcher attach, otherwise a stale timestamp
+        // would hide a new-session attach failure.
+      }
+    }
+    this.savedState = null;
+  }
+
   /**
    * Start chokidar watchers and emit workspace:mounted events.
    * Idempotent: safe to call from both start() and initStore(), fires once
@@ -725,6 +745,15 @@ export class WorkspaceModule implements Module {
     this.ctx = null;
   }
 
+  /** Mount names + modes, for peer callers (framework spill/journal paths)
+   *  that need a writable mount without reaching into private state. */
+  getMounts(): Array<{ name: string; mode: 'read-write' | 'read-only' }> {
+    return [...this.mounts.values()].map((m) => ({
+      name: m.config.name,
+      mode: m.config.mode === 'read-only' ? 'read-only' : 'read-write',
+    }));
+  }
+
   // ==========================================================================
   // Tool Definitions
   // ==========================================================================
@@ -1308,6 +1337,11 @@ export class WorkspaceModule implements Module {
       if (!fileStat.isFile() || fileStat.size > maxSize) return;
 
       const buffer = await readFile(absolutePath);
+      // Binaries are never synced into the tree (mirrors syncFromFs): the old
+      // utf-8 round-trip here silently replaced non-UTF-8 bytes with U+FFFD,
+      // permanently mangling images in the blob store. Binary reads are served
+      // straight from disk (readImageFromFilesystem / read_image fallback).
+      if (isBinary(buffer)) return;
       const content = buffer.toString('utf-8');
       const blobHash = store.storeBlob(Buffer.from(content, 'utf-8'), 'text/plain');
 

package/src/modules/workspace/sync.ts

@@ -40,7 +40,7 @@ export function hashContent(content: string | Buffer): string {
 /**
  * Check if content appears to be binary.
  */
-function isBinary(buffer: Buffer): boolean {
+export function isBinary(buffer: Buffer): boolean {
   // Check for null bytes in first 8KB
   const check = buffer.subarray(0, 8192);
   for (let i = 0; i < check.length; i++) {

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 {

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;
 }
 
 /**