@animalabs/agent-framework 0.9.0 → 0.10.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/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).
    */
@@ -1919,6 +1960,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 +1993,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 +2006,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

@@ -40,6 +40,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 +75,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 +103,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 +123,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 +179,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),
+      });
     }
   }
 

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,11 @@ 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.
    */
-  proseRouting?: 'locus' | 'explicit';
+  proseRouting?: 'locus' | 'explicit' | 'hybrid';
 }
 
 /** 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