@animalabs/agent-framework 0.6.8 → 0.6.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "description": "Multi-agent framework with pluggable modules, persistent state, and concurrent tool execution",
   "repository": {
     "type": "git",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@animalabs/chronicle": "^0.2.2",
     "@animalabs/context-manager": "^0.5.13",
-    "@animalabs/membrane": "^0.5.73",
+    "@animalabs/membrane": "^0.5.74",
     "chokidar": "^4.0.3",
     "discord.js": "^14.25.1",
     "ws": "^8.18.0"
@@ -62,4 +62,4 @@
   "engines": {
     "node": ">=20.0.0"
   }
-}
+}

package/src/agent.ts

@@ -64,6 +64,10 @@ export class Agent {
   readonly refusalHandling: AgentConfig['refusalHandling'];
   /** Prompt-cache TTL forwarded to the provider (see AgentConfig.cacheTtl). */
   readonly cacheTtl: NonNullable<AgentConfig['cacheTtl']>;
+  /** Emit prompt-cache markers on requests (see AgentConfig.promptCaching). */
+  readonly promptCaching: boolean;
+  /** Prefill scaffold user message (see AgentConfig.prefillUserMessage). */
+  readonly prefillUserMessage?: string;
   /** Provider-specific request parameters forwarded unchanged by Membrane. */
   readonly providerParams?: Record<string, unknown>;
   readonly sameRoundThinkTextPolicy: AgentConfig['sameRoundThinkTextPolicy'];
@@ -101,6 +105,8 @@ export class Agent {
     this.thinking = config.thinking;
     this.refusalHandling = config.refusalHandling;
     this.cacheTtl = config.cacheTtl ?? '1h';
+    this.promptCaching = config.promptCaching ?? true;
+    this.prefillUserMessage = config.prefillUserMessage;
     this.providerParams = config.providerParams;
     this.sameRoundThinkTextPolicy = config.sameRoundThinkTextPolicy;
     this.maxStreamTokens = config.maxStreamTokens ?? 150_000;
@@ -638,8 +644,9 @@ export class Agent {
         ...(this.thinking !== undefined && { thinking: this.thinking }),
       },
       tools: availableTools.length > 0 ? availableTools : undefined,
-      promptCaching: true,
+      promptCaching: this.promptCaching,
       cacheTtl: this.cacheTtl,
+      ...(this.prefillUserMessage && { prefillUserMessage: this.prefillUserMessage }),
       ...(this.providerParams && { providerParams: this.providerParams }),
       assistantParticipant: this.name,
     };

package/src/framework.ts

@@ -66,6 +66,29 @@ import type { WorkspaceModule } from './modules/workspace/index.js';
 import { toolResultDataToHistoryString } from './tool-result-history.js';
 import { splitProseSegments } from './prose-segments.js';
 
+/** Detect a supported image media type from magic bytes (the model API
+ *  rejects mislabeled media types, so trust bytes over extensions).
+ *  Returns undefined for non-image content. */
+function sniffImageMediaType(data: Buffer): string | undefined {
+  if (data.length >= 4 && data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4e && data[3] === 0x47) {
+    return 'image/png';
+  }
+  if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) {
+    return 'image/jpeg';
+  }
+  if (data.length >= 3 && data[0] === 0x47 && data[1] === 0x49 && data[2] === 0x46) {
+    return 'image/gif';
+  }
+  if (
+    data.length >= 12 &&
+    data[0] === 0x52 && data[1] === 0x49 && data[2] === 0x46 && data[3] === 0x46 &&
+    data[8] === 0x57 && data[9] === 0x45 && data[10] === 0x42 && data[11] === 0x50
+  ) {
+    return 'image/webp';
+  }
+  return undefined;
+}
+
 /**
  * Tools whose presence suppresses auto-routing of the surrounding prose,
  * for two distinct reasons:
@@ -1134,7 +1157,9 @@ export class AgentFramework {
       ...channelTools,
       ...gateTools,
       this.buildAgentSettingsTool(),
-      ...(this.getWorkspaceModule() ? [AgentFramework.SAVE_IMAGE_TOOL] : []),
+      ...(this.getWorkspaceModule()
+        ? [AgentFramework.SAVE_IMAGE_TOOL, AgentFramework.READ_IMAGE_TOOL]
+        : []),
     ];
   }
 
@@ -1915,6 +1940,29 @@ export class AgentFramework {
     },
   };
 
+  /** Synthesized read_image tool — present when a workspace module is
+   *  registered. Returns the image as a native image block in the tool
+   *  result, so the agent SEES it in the live turn (history keeps a compact
+   *  placeholder via the standard tool-result serializer). */
+  private static readonly READ_IMAGE_TOOL: import('./types/index.js').ToolDefinition = {
+    name: 'read_image',
+    description:
+      'View an image file from a workspace mount. The image is returned into ' +
+      'your context so you can actually see it (e.g. after save_recent_image, ' +
+      'or for images placed in the workspace by other means). Path is ' +
+      'mount-prefixed, e.g. "project/photos/cat.png". Supports png/jpeg/gif/webp.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Mount-prefixed image path, e.g. "project/photos/name.png".',
+        },
+      },
+      required: ['path'],
+    },
+  };
+
   private static readonly AGENT_SETTINGS_TOOL: import('./types/index.js').ToolDefinition = {
     name: 'agent_settings',
     description:
@@ -3774,18 +3822,30 @@ export class AgentFramework {
         ? event.origin.messageId
         : event.eventId;
       const maxBackscroll = descriptor?.capabilities?.history?.maxMessages ?? 0;
+      // Resolve human-readable names from the event origin wherever the
+      // surface provided them — a mind reading this should see WHO addressed
+      // it WHERE, not a wall of snowflake ids. Raw ids remain only inside the
+      // tool-argument instructions, where they are the literal values to pass.
+      const origin = (event.origin ?? {}) as Record<string, unknown>;
+      const authorName = typeof origin.authorName === 'string' && origin.authorName ? origin.authorName : 'Someone';
+      const channelLabel = triggerChannel.label ? `#${triggerChannel.label}` : `"${triggerChannel.channelId}"`;
+      const place = typeof origin.guildName === 'string' && origin.guildName
+        ? `${channelLabel} in "${origin.guildName}"`
+        : channelLabel;
       content.push({
         type: 'text',
         text:
-          `\n[Channel invitation] You were addressed in closed channel ` +
-          `"${triggerChannel.label ?? triggerChannel.channelId}" (${triggerChannel.channelId}, server ${event.serverId}). ` +
-          `You received this one message without subscribing. ` +
+          `\n[Channel invitation] ${authorName} addressed you in ${place} — ` +
+          `a channel you haven't joined. You're seeing this one message; you won't receive more from it unless you join. ` +
+          `Your options:\n` +
+          `1. Reply without joining — simply write your reply as normal text this turn; it will be delivered to ${channelLabel}.\n` +
+          `2. Join the channel — call channel_open with channelId "${triggerChannel.channelId}" and serverId "${event.serverId}"` +
           (maxBackscroll > 0
-            ? `To subscribe, call channel_open with channelId, serverId "${event.serverId}", backscroll (0-${maxBackscroll}), and beforeMessageId "${messageId}". `
-            : `To subscribe, call channel_open with this channelId and serverId "${event.serverId}". `) +
-          `You may reply once without subscribing. To remain closed, call channel_decline ` +
-          `with channelId, serverId "${event.serverId}", and messageId "${messageId}"; ` +
-          `optionally set acknowledge to a surface value such as 👀.`,
+            ? `; to also read recent history, add backscroll (a number up to ${maxBackscroll}) and beforeMessageId "${messageId}".\n`
+            : `.\n`) +
+          `3. Stay out — call channel_decline with channelId "${triggerChannel.channelId}", serverId "${event.serverId}", ` +
+          `and messageId "${messageId}" (optionally set acknowledge to an emoji like 👀 so ${authorName} isn't left hanging).\n` +
+          `Doing nothing is also fine.`,
       });
       metadata.channelInvitation = true;
       metadata.channelOpen = false;
@@ -5111,6 +5171,11 @@ export class AgentFramework {
       return;
     }
 
+    if (enrichedCall.name === 'read_image') {
+      this.dispatchReadImageToolCall(agentName, enrichedCall);
+      return;
+    }
+
     // Route gate_status tool
     if (enrichedCall.name === 'gate_status' && this.eventGate) {
       this.dispatchGateToolCall(agentName, enrichedCall);
@@ -6934,6 +6999,19 @@ export class AgentFramework {
       .then((result) => {
         const durationMs = Date.now() - startTime;
         this.emitTrace({ type: 'tool:completed', module: 'channels', tool: call.name, callId: call.id, durationMs });
+        // A successful channel_open plants the agent's feet in the opened
+        // channel: pin it as this turn's reply locus so plain-text speech
+        // written right after opening routes THERE. Found live 2026-07-21
+        // (Aria bring-up): open → plain-text reply → "no locus (no
+        // home/active channel, defaultPublishChannel null)" on a turn with
+        // no channel trigger (post-restart continuation). Next turn start
+        // re-resolves the locus as usual (startAgentStream set/delete).
+        if (call.name === 'channel_open' && result?.success) {
+          const opened =
+            (result.data as { channelId?: string } | undefined)?.channelId
+            ?? (call.input as { channelId?: string } | undefined)?.channelId;
+          if (opened) this.activeTriggerChannels.set(agentName, opened);
+        }
         this.pushEvent({
           type: 'tool-result',
           callId: call.id,
@@ -7096,6 +7174,75 @@ export class AgentFramework {
     });
   }
 
+  /**
+   * Handle the synthesized `read_image` tool: read image bytes from a
+   * workspace mount and return them as a native MCP-shaped content array
+   * (`[{type:'text'…},{type:'image', data, mimeType}]`). The live-turn
+   * converter (tryNativeToolResultContent → membrane tool_result image
+   * blocks) delivers the actual image to the model; history storage keeps
+   * the standard compact `[image: …]` placeholder.
+   */
+  private dispatchReadImageToolCall(agentName: string, call: ToolCall): void {
+    this.emitTrace({ type: 'tool:started', module: 'workspace', tool: call.name, callId: call.id, input: call.input });
+    const finish = (result: ToolResult): void => {
+      this.emitTrace({
+        type: result.isError ? 'tool:failed' : 'tool:completed',
+        module: 'workspace',
+        tool: call.name,
+        callId: call.id,
+        durationMs: 0,
+        ...(result.isError ? { error: result.error } : {}),
+      });
+      this.pushEvent({ type: 'tool-result', callId: call.id, agentName, moduleName: 'workspace', result });
+    };
+    void (async (): Promise<void> => {
+      try {
+        const workspace = this.getWorkspaceModule();
+        if (!workspace || typeof workspace.readBinary !== 'function') {
+          throw new Error('read_image requires a workspace module');
+        }
+        const input = (call.input ?? {}) as { path?: unknown };
+        if (typeof input.path !== 'string' || input.path.length === 0) {
+          throw new Error('read_image: `path` (mount-prefixed) is required');
+        }
+        const read = await workspace.readBinary(input.path);
+        if ('error' in read) throw new Error(read.error);
+        const mediaType = sniffImageMediaType(read.data);
+        if (!mediaType) {
+          throw new Error(
+            `read_image: "${input.path}" does not look like a supported image ` +
+            '(png/jpeg/gif/webp — checked by magic bytes, not extension)',
+          );
+        }
+        // Anthropic rejects images >5MB (and >8000px); guard the hard byte
+        // limit here — resizing is out of scope without an image library.
+        const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+        if (read.data.byteLength > MAX_IMAGE_BYTES) {
+          throw new Error(
+            `read_image: "${input.path}" is ${read.data.byteLength} bytes — ` +
+            `over the ${MAX_IMAGE_BYTES}-byte model limit`,
+          );
+        }
+        finish({
+          success: true,
+          data: [
+            {
+              type: 'text',
+              text: `${input.path} (${mediaType}, ${Math.ceil(read.data.byteLength / 1024)} KB):`,
+            },
+            { type: 'image', data: read.data.toString('base64'), mimeType: mediaType },
+          ],
+        });
+      } catch (error) {
+        finish({
+          success: false,
+          error: error instanceof Error ? error.message : String(error),
+          isError: true,
+        });
+      }
+    })();
+  }
+
   /**
    * Handle the synthesized `save_recent_image` tool: locate the requested
    * image blocks in the calling agent's context (blobs re-inlined, counted

package/src/modules/workspace/index.ts

@@ -651,6 +651,15 @@ export class WorkspaceModule implements Module {
                 error: err.message,
               } as ProcessEvent);
             },
+            onReattach: () => {
+              mount.watcherError = null;
+              void this.initialScan(name);
+              this.ctx?.pushEvent({
+                type: 'workspace:watcher-reattached',
+                mount: name,
+                path: mount.config.path,
+              } as ProcessEvent);
+            },
           },
         );
         watcher.start();
@@ -1018,6 +1027,30 @@ export class WorkspaceModule implements Module {
     };
   }
 
+  /**
+   * Read a file's raw bytes from a mount (through the Chronicle tree, synced
+   * first like the `read` tool). Public API for the framework's synthesized
+   * `read_image` tool and other peer callers that need binary content.
+   */
+  async readBinary(
+    mountPrefixedPath: string,
+  ): Promise<{ data: Buffer } | { error: string }> {
+    let mount: MountState;
+    let relativePath: string;
+    try {
+      ({ mount, relativePath } = this.parsePath(mountPrefixedPath));
+    } catch (error) {
+      return { error: error instanceof Error ? error.message : String(error) };
+    }
+    const store = this.getStore();
+    await this.ensureSynced(mount, relativePath);
+    const entry = store.treeGet(mount.treeStateId, relativePath);
+    if (!entry) return { error: `File not found: ${mountPrefixedPath}` };
+    const blob = store.getBlob(entry.blobHash);
+    if (!blob) return { error: `Blob not found for: ${mountPrefixedPath}` };
+    return { data: blob };
+  }
+
   /**
    * Parse a mount-prefixed path into (mountName, relativePath).
    */
@@ -1662,8 +1695,20 @@ export class WorkspaceModule implements Module {
         mount.initialSyncDone = true;
       }
 
-      const prefix = relativePath ? relativePath + '/' : undefined;
-      const entries = store.treeList(mount.treeStateId, prefix);
+      // If `path` points at a single FILE, grep just that file. Otherwise treat
+      // `path` as a directory prefix (the original behaviour). Previously a file
+      // path produced an empty prefix like "notes.md/" and matched nothing, so
+      // grepping a specific file silently returned zero results.
+      let entries: Array<{ path: string; blobHash: string }>;
+      const fileNode = relativePath
+        ? (store.treeGet(mount.treeStateId, relativePath) as { blobHash?: string } | null)
+        : null;
+      if (fileNode && fileNode.blobHash) {
+        entries = [{ path: relativePath, blobHash: fileNode.blobHash }];
+      } else {
+        const prefix = relativePath ? relativePath + '/' : undefined;
+        entries = store.treeList(mount.treeStateId, prefix);
+      }
 
       for (const entry of entries) {
         if (fileGlob && !fileGlob.test(entry.path)) continue;

package/src/modules/workspace/types.ts

@@ -25,6 +25,8 @@ export interface MountConfig {
   watch?: 'always' | 'on-agent-action' | 'never';
   /** Debounce window in ms for watch: 'always' mode (default: 300) */
   watchDebounceMs?: number;
+  /** Poll interval in ms for checking watched root identity changes (default: 2000) */
+  watchRootPollMs?: number;
   /**
    * Simple ignore patterns (NOT full gitignore syntax). Supported forms:
    * - Exact name match: ".git", "node_modules"

package/src/modules/workspace/watcher.ts

@@ -6,7 +6,8 @@
  */
 
 import { watch, type FSWatcher } from 'chokidar';
-import { mkdirSync } from 'node:fs';
+import { mkdirSync, statSync } from 'node:fs';
+import { basename } from 'node:path';
 import { type MountConfig } from './types.js';
 
 export type FsOp = 'created' | 'modified' | 'deleted';
@@ -30,6 +31,14 @@ export interface WatcherLifecycle {
   onReady?: () => void;
   /** Fires on any chokidar-reported error (ENOENT, EACCES, platform faults). */
   onError?: (err: Error) => void;
+  /** Fires after the watcher re-attaches to a replaced root inode. */
+  onReattach?: () => void;
+}
+
+interface RootIdentity {
+  dev: number;
+  ino: number;
+  birthtimeMs: number;
 }
 
 /**
@@ -42,8 +51,13 @@ export class MountWatcher {
   // create -> modify collapses to 'created' (single batch); delete always wins.
   private pendingChanges = new Map<string, FsOp>();
   private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private rootPollTimer: ReturnType<typeof setInterval> | null = null;
   private suppressedPaths = new Set<string>();
   private suppressionTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  private rootIdentity: RootIdentity | null = null;
+  private detached = false;
+  private attaching = false;
+  private stopped = true;
   private readonly debounceMs: number;
   private readonly config: MountConfig;
   private readonly onChangeCallback: (changes: FsChange[]) => void;
@@ -64,8 +78,14 @@ export class MountWatcher {
    * Start watching the filesystem.
    */
   start(): void {
-    if (this.watcher) return;
+    if (this.watcher || this.rootPollTimer) return;
+
+    this.stopped = false;
+    this.attach();
+    this.startRootPolling();
+  }
 
+  private attach(): void {
     // Read-write mounts: ensure the path exists before chokidar attaches.
     // chokidar 4's fs.watch-based backend silently fails to fire events when
     // the watched path OR any of its parent directories don't exist at
@@ -110,21 +130,39 @@ export class MountWatcher {
     this.watcher.on('add', handleEvent('created'));
     this.watcher.on('change', handleEvent('modified'));
     this.watcher.on('unlink', handleEvent('deleted'));
+    this.watcher.on('unlinkDir', (dirPath) => {
+      if (this.isRootPath(dirPath)) {
+        this.detached = true;
+      }
+    });
 
     if (this.lifecycle.onReady) {
       this.watcher.once('ready', this.lifecycle.onReady);
     }
-    if (this.lifecycle.onError) {
-      this.watcher.on('error', (err) => {
-        this.lifecycle.onError?.(err instanceof Error ? err : new Error(String(err)));
-      });
-    }
+    this.watcher.on('error', (err) => {
+      this.reportError(err);
+    });
+    this.watcher.on('raw', (event: string, rawPath: string, _details: unknown) => {
+      if (event !== 'rename') return;
+      // A rename on the watched root's path/basename is the one signal that
+      // survives inode reuse on Linux, where unlinkDir/error never fire.
+      if (this.isRootPath(rawPath) || basename(rawPath) === basename(this.config.path)) {
+        void this.checkRootLiveness({ force: true });
+      }
+    });
+
+    this.captureRootIdentity();
   }
 
   /**
    * Stop watching.
    */
   async stop(): Promise<void> {
+    this.stopped = true;
+    if (this.rootPollTimer) {
+      clearInterval(this.rootPollTimer);
+      this.rootPollTimer = null;
+    }
     if (this.debounceTimer) {
       clearTimeout(this.debounceTimer);
       this.debounceTimer = null;
@@ -140,6 +178,9 @@ export class MountWatcher {
       await this.watcher.close();
       this.watcher = null;
     }
+    this.rootIdentity = null;
+    this.detached = false;
+    this.attaching = false;
   }
 
   /**
@@ -219,6 +260,108 @@ export class MountWatcher {
     }, this.debounceMs);
   }
 
+  private startRootPolling(): void {
+    const pollMs = this.config.watchRootPollMs ?? 2000;
+    this.rootPollTimer = setInterval(() => {
+      void this.checkRootLiveness();
+    }, pollMs);
+    this.rootPollTimer.unref();
+  }
+
+  private async checkRootLiveness(opts: { force?: boolean } = {}): Promise<void> {
+    if (this.stopped || this.attaching) return;
+
+    let current: RootIdentity;
+    try {
+      current = this.readRootIdentity();
+    } catch (err) {
+      if (this.isErrno(err, 'ENOENT')) {
+        this.detached = true;
+        if (this.config.mode === 'read-write') {
+          await this.reattach();
+        }
+        return;
+      }
+      this.reportError(err);
+      if (opts.force) {
+        this.detached = true;
+        await this.reattach();
+      }
+      return;
+    }
+
+    if (!this.rootIdentity && !this.detached) {
+      await this.reattach();
+      return;
+    }
+
+    if (!opts.force && !this.detached && this.rootIdentity
+      && this.sameIdentity(current, this.rootIdentity)) {
+      return;
+    }
+
+    await this.reattach();
+  }
+
+  private async reattach(): Promise<void> {
+    if (this.attaching || this.stopped) return;
+
+    this.attaching = true;
+    try {
+      const oldWatcher = this.watcher;
+      this.watcher = null;
+      if (oldWatcher) {
+        await oldWatcher.close();
+      }
+      if (this.stopped) return;
+
+      this.attach();
+      if (!this.detached && this.rootIdentity) {
+        this.lifecycle.onReattach?.();
+      }
+    } catch (err) {
+      this.reportError(err);
+    } finally {
+      this.attaching = false;
+    }
+  }
+
+  private captureRootIdentity(): void {
+    try {
+      this.rootIdentity = this.readRootIdentity();
+      this.detached = false;
+    } catch (err) {
+      if (this.isErrno(err, 'ENOENT')) {
+        this.rootIdentity = null;
+        this.detached = true;
+        return;
+      }
+      this.rootIdentity = null;
+      this.detached = false;
+      this.reportError(err);
+    }
+  }
+
+  private readRootIdentity(): RootIdentity {
+    const stat = statSync(this.config.path);
+    return { dev: stat.dev, ino: stat.ino, birthtimeMs: stat.birthtimeMs };
+  }
+
+  private sameIdentity(a: RootIdentity, b: RootIdentity): boolean {
+    // birthtimeMs is only a secondary tripwire: sub-millisecond replacements
+    // can reuse both the inode and timestamp, so raw rename remains essential.
+    return a.dev === b.dev && a.ino === b.ino && a.birthtimeMs === b.birthtimeMs;
+  }
+
+  private isErrno(err: unknown, code: string): boolean {
+    return typeof err === 'object' && err !== null && 'code' in err
+      && (err as NodeJS.ErrnoException).code === code;
+  }
+
+  private reportError(err: unknown): void {
+    this.lifecycle.onError?.(err instanceof Error ? err : new Error(String(err)));
+  }
+
   private toRelative(absolutePath: string): string | null {
     const base = this.config.path.endsWith('/')
       ? this.config.path
@@ -228,4 +371,14 @@ export class MountWatcher {
     }
     return null;
   }
+
+  private isRootPath(absolutePath: string): boolean {
+    const root = this.config.path.endsWith('/')
+      ? this.config.path.slice(0, -1)
+      : this.config.path;
+    const candidate = absolutePath.endsWith('/')
+      ? absolutePath.slice(0, -1)
+      : absolutePath;
+    return candidate === root;
+  }
 }

package/src/types/agent.ts

@@ -68,6 +68,23 @@ export interface AgentConfig {
    */
   cacheTtl?: '5m' | '1h';
 
+  /**
+   * Whether to emit prompt-cache markers (cache_control) on requests.
+   * Default true (Anthropic API). Set false for transports that reject
+   * cache_control — e.g. Bedrock legacy Claude models, which fail with
+   * "your request did not allow prompt caching".
+   */
+  promptCaching?: boolean;
+
+  /**
+   * Prefill-formatter support: a synthetic user message appended after the
+   * conversation (e.g. chapterx's `<cmd>cat untitled.txt</cmd>` CLI-sim
+   * scaffold). Forwarded verbatim to membrane's prefill formatters; ignored
+   * by native formatting. Part of reproducing a prefill-era bot's exact
+   * prompting structure when migrating it into a resident.
+   */
+  prefillUserMessage?: string;
+
   /** Provider-specific request parameters (for example Responses reasoning
    * and server-side compaction settings). */
   providerParams?: Record<string, unknown>;