@animalabs/agent-framework 0.9.0 → 0.11.0

package/src/mcpl/prose-stream-router.ts

@@ -30,7 +30,7 @@ export interface RoutedDelta {
   delta: string;
 }
 
-type State = 'line-start' | 'maybe-prefix' | 'prefix-token' | 'after-token' | 'body';
+type State = 'line-start' | 'hybrid-indent' | 'maybe-prefix' | 'prefix-gap' | 'prefix-token' | 'after-token' | 'body';
 
 export class ProseStreamRouter {
   private target: string | null;
@@ -42,8 +42,8 @@ export class ProseStreamRouter {
 
   constructor(
     private opts: {
-      /** 'explicit' parses `>>` prefixes; 'locus' is pure passthrough. */
-      mode: 'explicit' | 'locus';
+      /** explicit parses `>>`; hybrid parses `>>>` while retaining locus fallback. */
+      mode: 'explicit' | 'hybrid' | 'locus';
       /** Initial destination: the frozen turn locus (locus mode) or null. */
       initialTarget: string | null;
       /** Resolve a `>>spec` to a channelId, or null (unresolved/ambiguous). */
@@ -87,7 +87,12 @@ export class ProseStreamRouter {
    *  no body — dropped, matching delivery which would deliver empty body). */
   finish(): RoutedDelta[] {
     const out: RoutedDelta[] = [];
-    if (this.state === 'maybe-prefix') this.emit(this.held, out); // "" | ">" | ">>"
+    if (this.state === 'hybrid-indent') this.emit(this.held, out);
+    if (this.state === 'maybe-prefix') {
+      const full = this.opts.mode === 'hybrid' ? '>>>' : '>>';
+      const arrows = this.opts.mode === 'hybrid' ? this.held.trimStart() : this.held;
+      if (arrows !== full) this.emit(this.held, out);
+    }
     // prefix-token / after-token at EOF: prefix without body — nothing to emit.
     this.held = '';
     this.state = 'line-start';
@@ -97,7 +102,7 @@ export class ProseStreamRouter {
   private step(ch: string, out: RoutedDelta[]): void {
     switch (this.state) {
       case 'body':
-        if (ch === '\n' && this.opts.mode === 'explicit') {
+        if (ch === '\n' && this.opts.mode !== 'locus') {
           this.emit('\n', out);
           this.state = 'line-start';
         } else {
@@ -106,34 +111,63 @@ export class ProseStreamRouter {
         return;
 
       case 'line-start':
+        if (this.opts.mode === 'hybrid' && (ch === ' ' || ch === '\t')) {
+          this.state = 'hybrid-indent';
+          this.held = ch;
+          return;
+        }
         if (ch === '>') { this.state = 'maybe-prefix'; this.held = '>'; return; }
         this.state = 'body';
         this.step(ch, out);
         return;
 
-      case 'maybe-prefix':
-        if (this.held === '>' && ch === '>') { this.held = '>>'; return; }
-        if (this.held === '>>') {
+      case 'hybrid-indent':
+        if (ch === ' ' || ch === '\t') { this.held += ch; return; }
+        if (ch === '>') { this.held += ch; this.state = 'maybe-prefix'; return; }
+        this.emit(this.held, out);
+        this.held = '';
+        this.state = 'body';
+        this.step(ch, out);
+        return;
+
+      case 'maybe-prefix': {
+        const prefix = this.opts.mode === 'hybrid' ? '>>>' : '>>';
+        const arrows = this.opts.mode === 'hybrid' ? this.held.trimStart() : this.held;
+        if (ch === '>' && arrows.length < prefix.length) {
+          this.held += '>';
+          return;
+        }
+        if (arrows === prefix) {
+          if (this.opts.mode === 'hybrid' && (ch === ' ' || ch === '\t')) {
+            this.held = '';
+            this.state = 'prefix-gap';
+            return;
+          }
           if (ch === '\n' || ch === ' ' || ch === '\t') {
-            // `>> quoted arrow` / bare `>>`: body text, not a prefix.
-            this.emit(this.held, out);
+            if (this.opts.mode === 'explicit') this.emit(this.held, out);
             this.held = '';
-            this.state = 'body';
-            this.step(ch, out);
+            this.state = ch === '\n' ? 'line-start' : 'body';
+            if (ch !== '\n') this.step(ch, out);
             return;
           }
-          // real prefix begins
           this.state = 'prefix-token';
           this.token = ch;
           this.held = '';
           return;
         }
-        // held === '>' and ch !== '>': plain body starting with '>'
         this.emit(this.held, out);
         this.held = '';
         this.state = 'body';
         this.step(ch, out);
         return;
+      }
+
+      case 'prefix-gap':
+        if (ch === ' ' || ch === '\t') return;
+        if (ch === '\n') { this.target = null; this.state = 'line-start'; return; }
+        this.state = 'prefix-token';
+        this.token = ch;
+        return;
 
       case 'prefix-token':
         if (ch === ' ' || ch === '\t') { this.applyTarget(); this.state = 'after-token'; this.sawBang = false; return; }

package/src/modules/discord/index.ts

@@ -754,7 +754,7 @@ export class DiscordModule implements Module {
     });
 
     // Build a map of stored message external IDs -> internal data
-    const storedMessageMap = new Map<string, { internalId: string; content: string }>();
+    const storedMessageMap = new Map<string, { internalId: string; content: string; sourceTimestamp?: number }>();
     for (const msg of storedMessages) {
       const external = msg.metadata?.external as { id?: string } | undefined;
       if (external?.id) {
@@ -766,6 +766,9 @@ export class DiscordModule implements Module {
         storedMessageMap.set(external.id, {
           internalId: msg.id,
           content: textContent,
+          sourceTimestamp: typeof msg.metadata?.timestamp === 'number'
+            ? msg.metadata.timestamp
+            : undefined,
         });
       }
     }
@@ -774,8 +777,10 @@ export class DiscordModule implements Module {
     let editedMessages = 0;
     let deletedMessages = 0;
 
-    // Process Discord messages - check for new/edited
-    for (const discordMsg of discordMessages) {
+    // Discord history is newest-first, while addMessage appends to the stored
+    // conversation. Process oldest-first so missed messages retain chronology.
+    const chronologicalMessages = [...discordMessages].reverse();
+    for (const discordMsg of chronologicalMessages) {
       const stored = storedMessageMap.get(discordMsg.id);
       
       if (!stored) {
@@ -810,10 +815,23 @@ export class DiscordModule implements Module {
       }
     }
 
-    // Check for deletes - messages we have that Discord doesn't
-    // Only consider messages within the scrollback window (recent ones)
+    // Check for deletes only inside the history we actually fetched. A short
+    // response covers complete available history; a full page has an older
+    // boundary whose tied millisecond must be preserved.
+    const fetchedCompleteHistory = discordMessages.length < scrollback;
+    const oldestFetchedTimestamp = discordMessages.length > 0
+      ? Math.min(...discordMessages.map((msg) => msg.timestamp.getTime()))
+      : undefined;
     for (const [externalId, stored] of storedMessageMap) {
-      if (!discordMessageMap.has(externalId)) {
+      const isInsideFetchedWindow = fetchedCompleteHistory || (
+        stored.sourceTimestamp !== undefined &&
+        oldestFetchedTimestamp !== undefined &&
+        // Discord timestamps are millisecond-precise, so an older message just
+        // beyond the page can tie the oldest fetched timestamp. Preserve ties
+        // rather than guessing that an unseen boundary message was deleted.
+        stored.sourceTimestamp > oldestFetchedTimestamp
+      );
+      if (isInsideFetchedWindow && !discordMessageMap.has(externalId)) {
         // Message exists in our store but not in Discord - it was deleted
         // Note: This only catches deletes within the scrollback window
         this.ctx.removeMessage(stored.internalId);

package/src/modules/workspace/index.ts

@@ -1080,6 +1080,47 @@ export class WorkspaceModule implements Module {
     return { data: blob };
   }
 
+  /**
+   * Read a file's raw bytes straight from the mount's filesystem, bypassing
+   * the Chronicle tree.
+   *
+   * For material that is *passing through* rather than being kept: an upload,
+   * a render being shipped somewhere, a file handed to a service. The store
+   * path (`readBinary`) is append-only, so reading through it means every
+   * byte is retained forever and the mount's `maxFileSize` guard applies —
+   * correct for the resident's memory, wrong for egress, where paying a
+   * permanent cost to send something once is the wrong trade.
+   *
+   * Same mount boundary and traversal guard as every other path here: only
+   * declared mounts, nothing above their root. Deliberately does NOT sync,
+   * register, or hash anything — it reads and returns.
+   */
+  async readBinaryFromDisk(
+    mountPrefixedPath: string,
+    opts: { maxBytes?: number } = {},
+  ): Promise<{ data: Buffer; absolutePath: string } | { 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 absolutePath = resolve(mount.config.path, relativePath);
+    try {
+      const info = await stat(absolutePath);
+      if (!info.isFile()) return { error: `Not a file: ${mountPrefixedPath}` };
+      if (opts.maxBytes !== undefined && info.size > opts.maxBytes) {
+        return { error: `File too large: ${info.size} > ${opts.maxBytes} bytes` };
+      }
+      return { data: await readFile(absolutePath), absolutePath };
+    } catch (error) {
+      const code = (error as { code?: string }).code;
+      if (code === 'ENOENT') return { error: `File not found on disk: ${mountPrefixedPath}` };
+      return { error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
   /**
    * Parse a mount-prefixed path into (mountName, relativePath).
    */
@@ -1093,10 +1134,12 @@ export class WorkspaceModule implements Module {
       throw new Error(`Unknown mount: "${mountName}". Available: ${[...this.mounts.keys()].join(', ')}`);
     }
 
-    // Path traversal guard (CWE-22): ensure resolved path stays within mount
+    // Path traversal guard (CWE-22): ensure resolved path stays within mount.
+    // Containment must compare with the PLATFORM separator (isContainedPath):
+    // resolve() emits backslashes on Windows, so a '/'-suffixed root never
+    // prefix-matches there and every in-mount path was rejected as traversal.
     const resolved = resolve(mount.config.path, relativePath);
-    const mountRoot = mount.config.path.endsWith('/') ? mount.config.path : mount.config.path + '/';
-    if (resolved !== mount.config.path && !resolved.startsWith(mountRoot)) {
+    if (!isContainedPath(mount.config.path, resolved)) {
       throw new Error(`Path traversal detected: "${path}" resolves outside mount "${mountName}"`);
     }
 
@@ -1919,6 +1962,7 @@ export class WorkspaceModule implements Module {
   private async handleSync(input: SyncInput): Promise<ToolResult> {
     const store = this.getStore();
     const allResults: Array<{ mount: string; synced: string[]; conflicts: ConflictInfo[] }> = [];
+    const allSkipped: Array<{ mount: string; path: string; reason: string }> = [];
 
     let mountsToSync: Array<{ name: string; mount: MountState }>;
     if (input.mount) {
@@ -1951,6 +1995,11 @@ export class WorkspaceModule implements Module {
         });
         this.emitFsEvents(name, result.synced, result.conflicts);
       }
+      // Skips were previously computed and dropped, so "nothing synced" and
+      // "your file was refused" looked identical from the outside. Say which.
+      for (const s of result.skipped) {
+        allSkipped.push({ mount: name, path: s.path, reason: s.reason });
+      }
     }
 
     return {
@@ -1959,6 +2008,7 @@ export class WorkspaceModule implements Module {
         results: allResults,
         totalSynced: allResults.reduce((sum, r) => sum + r.synced.length, 0),
         totalConflicts: allResults.reduce((sum, r) => sum + r.conflicts.length, 0),
+        ...(allSkipped.length > 0 ? { skipped: allSkipped } : {}),
       },
     };
   }

package/src/modules/workspace/sync.ts

@@ -8,7 +8,7 @@
 
 import { createHash } from 'node:crypto';
 import { readFile, writeFile, mkdir, readdir, stat, access } from 'node:fs/promises';
-import { join, dirname, relative, resolve } from 'node:path';
+import { join, dirname, relative, resolve, sep } from 'node:path';
 import type { JsStore, JsTreeEntry } from '@animalabs/chronicle';
 import type { MountState } from './types.js';
 
@@ -19,8 +19,11 @@ export const DEFAULT_MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB
  * Returns the absolute path, or null if the path is outside the mount.
  */
 function safePath(mountPath: string, relativePath: string): string | null {
+  // Compare with the PLATFORM separator: resolve() emits backslashes on
+  // Windows, so a '/'-suffixed root never prefix-matches there and every
+  // in-mount path was reported as outside the mount.
   const resolved = resolve(mountPath, relativePath);
-  const root = mountPath.endsWith('/') ? mountPath : mountPath + '/';
+  const root = mountPath.endsWith(sep) ? mountPath : mountPath + sep;
   if (resolved !== mountPath && !resolved.startsWith(root)) {
     return null;
   }
@@ -40,6 +43,13 @@ export function hashContent(content: string | Buffer): string {
 /**
  * Check if content appears to be binary.
  */
+export interface SkippedFile {
+  /** Relative path of the file that was not synced */
+  path: string;
+  /** Why, in words the resident can act on */
+  reason: string;
+}
+
 export function isBinary(buffer: Buffer): boolean {
   // Check for null bytes in first 8KB
   const check = buffer.subarray(0, 8192);
@@ -68,8 +78,11 @@ export interface SyncResult {
   synced: SyncedPath[];
   /** Paths that conflicted (both agent and user modified) — filesystem wins */
   conflicts: ConflictInfo[];
-  /** Paths that were skipped (binary, too large, etc.) */
-  skipped: string[];
+  /** Paths that were skipped, each with the reason — a silently skipped file
+   *  is indistinguishable from one that synced cleanly, which is how a
+   *  resident ends up believing a file is in their workspace when it never
+   *  arrived. */
+  skipped: SkippedFile[];
 }
 
 /**
@@ -93,7 +106,7 @@ export async function syncFromFs(
   for (const relativePath of filesToSync) {
     const absolutePath = safePath(mount.config.path, relativePath);
     if (!absolutePath) {
-      result.skipped.push(relativePath);
+      result.skipped.push({ path: relativePath, reason: 'path resolves outside the mount' });
       continue;
     }
 
@@ -113,13 +126,23 @@ export async function syncFromFs(
       const fileStat = await stat(absolutePath);
       if (!fileStat.isFile()) continue;
       if (fileStat.size > maxSize) {
-        result.skipped.push(relativePath);
+        result.skipped.push({
+          path: relativePath,
+          reason: `too large: ${fileStat.size} bytes > maxFileSize ${maxSize}`,
+        });
         continue;
       }
 
       const buffer = await readFile(absolutePath);
       if (isBinary(buffer)) {
-        result.skipped.push(relativePath);
+        // Disk -> store sync is text-only, at ANY size: the tree stores text
+        // blobs. Binary that must live in the store has to be written through
+        // writeBinary; binary that is only passing through should be read with
+        // readBinaryFromDisk instead of synced at all.
+        result.skipped.push({
+          path: relativePath,
+          reason: 'binary file — disk sync stores text only (read it from disk, or write it via a binary-aware tool)',
+        });
         continue;
       }
 
@@ -159,8 +182,11 @@ export async function syncFromFs(
 
       store.treeSet(mount.treeStateId, relativePath, entry);
       result.synced.push({ path: relativePath, op: existing ? 'modified' : 'created' });
-    } catch {
-      result.skipped.push(relativePath);
+    } catch (error) {
+      result.skipped.push({
+        path: relativePath,
+        reason: error instanceof Error ? error.message : String(error),
+      });
     }
   }
 
@@ -276,7 +302,10 @@ async function walkDirectory(
       if (results.length >= maxFiles) break;
 
       const fullPath = join(dir, entry.name);
-      const relativePath = relative(basePath, fullPath);
+      // Logical workspace paths are '/'-separated everywhere (mount-prefixed
+      // paths, chronicle tree paths); node's relative() emits backslashes on
+      // Windows, so normalize. No-op on POSIX (sep === '/').
+      const relativePath = relative(basePath, fullPath).split(sep).join('/');
 
       // Check ignore patterns (simple glob matching)
       if (shouldIgnore(relativePath, entry.name, ignorePatterns)) continue;

package/src/modules/workspace/watcher.ts

@@ -7,7 +7,7 @@
 
 import { watch, type FSWatcher } from 'chokidar';
 import { mkdirSync, statSync } from 'node:fs';
-import { basename } from 'node:path';
+import { basename, sep } from 'node:path';
 import { type MountConfig } from './types.js';
 
 export type FsOp = 'created' | 'modified' | 'deleted';
@@ -363,20 +363,23 @@ export class MountWatcher {
   }
 
   private toRelative(absolutePath: string): string | null {
-    const base = this.config.path.endsWith('/')
+    // Chokidar hands back platform-separated absolute paths; compare with
+    // the platform separator and normalize the result to the '/'-separated
+    // logical form the rest of the workspace uses. No-op on POSIX.
+    const base = this.config.path.endsWith(sep)
       ? this.config.path
-      : this.config.path + '/';
+      : this.config.path + sep;
     if (absolutePath.startsWith(base)) {
-      return absolutePath.slice(base.length);
+      return absolutePath.slice(base.length).split(sep).join('/');
     }
     return null;
   }
 
   private isRootPath(absolutePath: string): boolean {
-    const root = this.config.path.endsWith('/')
+    const root = this.config.path.endsWith(sep)
       ? this.config.path.slice(0, -1)
       : this.config.path;
-    const candidate = absolutePath.endsWith('/')
+    const candidate = absolutePath.endsWith(sep)
       ? absolutePath.slice(0, -1)
       : absolutePath;
     return candidate === root;

package/src/queue.ts

@@ -22,8 +22,14 @@ export class ProcessQueueImpl implements ProcessQueue {
     if (waiter) {
       waiter(event);
     } else if (event.type === 'external-message') {
-      // User input jumps to front so it's processed before queued internal events
-      this.queue.unshift(event);
+      // User input stays ahead of queued internal work, but joins the end of
+      // the external-message lane so rapid messages retain arrival order.
+      const firstInternal = this.queue.findIndex((queued) => queued.type !== 'external-message');
+      if (firstInternal === -1) {
+        this.queue.push(event);
+      } else {
+        this.queue.splice(firstInternal, 0, event);
+      }
     } else {
       this.queue.push(event);
     }

package/src/tool-result-history.ts

@@ -20,10 +20,20 @@ import { safeSlice } from './safe-slice.js';
  * House-safe default inline cap (chars) for tool results, error results, and
  * background-script wake payloads (issue #89: a resident should never eat a
  * 42k blob they didn't ask for). Durable per-residence value comes from
- * `FrameworkConfig.toolResultInlineMaxChars`; a temporary per-agent lift from
+ * `FrameworkConfig.toolResultInlineMaxChars`; a per-agent value from
  * agent_settings `tool_result_inline_max_chars`.
+ *
+ * Raised 5000 → 24000 (2026-08-07) on production evidence rather than taste.
+ * The first residence to actually run the 5000 default spilled 48 results in
+ * 23h, 71% of them ordinary shell output from source review — `git diff`, test
+ * runs, `sed -n '450,590p'`-style excerpts, which routinely land at 5–15k. A
+ * 5000-char cap is tuned for conversation and turns every file read into a
+ * spill round-trip for a resident doing code work. Measured on that corpus:
+ * 20000 keeps 76% inline, 24000 keeps 88%, 32000 only reaches 90% — 24000 is
+ * the elbow. Genuinely large payloads (full histories, channel registries,
+ * broad greps) still spill, which is the point.
  */
-export const DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS = 5000;
+export const DEFAULT_TOOL_RESULT_INLINE_MAX_CHARS = 24000;
 
 export function toolResultDataToHistoryString(data: unknown, maxChars?: number): string {
   const fromArray = tryHistoryStringFromContentArray(data);

package/src/types/agent.ts

@@ -177,8 +177,13 @@ export interface AgentConfig {
    *   (`>>#channel` / `>>@person` / `>>skip_reply`); unprefixed prose is never
    *   delivered — it bounces to a clipboard for a cheap prefixed resend.
    *   See docs/explicit-prose-routing.md.
+   * - 'hybrid': unprefixed prose keeps locus routing; `>>>destination` routes
+   *   that publication envelope through the same authorized resolver.
+   *   See docs/hybrid-prose-routing.md.
+   * - 'disabled': generated prose is never published. Only explicit tools may
+   *   send externally; prose remains in Chronicle with a private suppression receipt.
    */
-  proseRouting?: 'locus' | 'explicit';
+  proseRouting?: 'locus' | 'explicit' | 'hybrid' | 'disabled';
 }
 
 /** The intentionally small set of agent settings that may change in-process. */

package/src/types/framework.ts

@@ -145,7 +145,7 @@ export interface FrameworkConfig {
    * 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
+   * explicit plain truncation. Default 24000 (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

package/src/types/trace.ts

@@ -340,6 +340,19 @@ export type TraceEvent =
       textLen: number;
     })
 
+  // Admin puppet: an operator executed a tool AS an agent and stored the
+  // tool_use + tool_result pair in that agent's window (Framework.
+  // puppetToolCall). Provenance lives HERE and in the host log — the stored
+  // messages deliberately byte-match a model-initiated call.
+  | (TraceEventBase & {
+      type: 'puppet:tool-call';
+      agentName: string;
+      toolName: string;
+      toolUseId: string;
+      isError: boolean;
+      durationMs: number;
+    })
+
   // MCPL server connection lifecycle (spawn / handshake / reconnect health).
   // Previously these outcomes were visible only on the host process's own
   // stderr, so a server that lost the boot handshake race just went missing.