@animalabs/agent-framework 0.6.10 → 0.7.2

package/src/mcpl/prose-grammar.ts

@@ -0,0 +1,40 @@
+/**
+ * Explicit-prose routing grammar — the SINGLE definition shared by the
+ * delivery path (framework.deliverProse*) and the outgoing-stream router
+ * (prose-stream-router.ts). Extracted from framework.ts verbatim so the two
+ * parsers cannot drift: a streamed chunk and its eventual delivery must agree
+ * on what is a prefix, what is a modifier, and what is body.
+ *
+ * Grammar (docs/explicit-prose-routing.md):
+ *   `>>target [!] [body…]`  — target = channel spec or `skip_reply`
+ *   The ` !` continuation modifier must immediately follow the target,
+ *   whitespace-separated. Body may start on the same line or the next.
+ *   A line's `>>` counts only when immediately followed by a target token
+ *   (`>> quoted arrow` stays body text).
+ */
+
+export interface ProsePrefix {
+  kind: 'target' | 'private' | 'none';
+  target?: string;
+  continueTurn: boolean;
+  body: string;
+}
+
+/** A REAL prefix line: `>>` immediately followed by a target token. */
+export const PROSE_PREFIX_LINE = /^>>\S/;
+
+export function parseProsePrefix(text: string): ProsePrefix {
+  const m = /^>>(\S+)([ \t]+!)?[ \t]*\n?/.exec(text);
+  if (!m) return { kind: 'none', continueTurn: false, body: text };
+  const target = m[1]!;
+  const continueTurn = m[2] !== undefined;
+  const body = text.slice(m[0].length);
+  // `skip_reply` mirrors the tool the model already knows: text stays in
+  // context, nothing is delivered. (Deliberately NOT called "private"/"note" —
+  // that vocabulary sat adjacent to signed thinking in a live window and drew
+  // a reasoning_extraction classifier hit, 2026-07-24 Fable.)
+  if (target === 'skip_reply') {
+    return { kind: 'private', continueTurn, body };
+  }
+  return { kind: 'target', target, continueTurn, body };
+}

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

@@ -0,0 +1,161 @@
+/**
+ * Incremental prose router: turns a stream of text deltas into a stream of
+ * (channelId, delta) pairs AS THE MODEL GENERATES, so downstream surfaces
+ * (voice synthesis, streamed message rendering, future platforms) can act on
+ * speech before the turn completes. This is the emission half of MCPL Spec
+ * 14.3 (`channels/outgoing/chunk`) — the notification has existed in the
+ * wire types since the spec landed; this class is what finally produces it.
+ *
+ * Correctness contract: routing decisions here MUST agree with the delivery
+ * path (deliverProse/parseProsePrefix). Both use prose-grammar.ts; this
+ * router additionally holds back exactly as much text as needed to make each
+ * line's decision — the start of a line is buffered only until it either
+ * cannot be a `>>` prefix (flush as body) or its prefix token (+ optional
+ * ` !` modifier) completes (switch target, swallow the prefix). Body text
+ * after the decision point streams through with zero added latency.
+ *
+ * Suppression is fail-closed: text whose destination is unknown (explicit
+ * mode before the first `>>`, unresolvable/ambiguous targets, `>>skip_reply`)
+ * emits NOTHING — the delivery path will bounce/retain it; a stream consumer
+ * must never see text that delivery would refuse to send.
+ *
+ * Two modes, mirroring proseRouting:
+ *  - explicit: parse `>>` prefixes; initial target null (suppressed).
+ *  - locus:    NO prefix parsing (locus mode's `>>` lines are plain text);
+ *              everything streams to the frozen turn locus.
+ */
+
+export interface RoutedDelta {
+  channelId: string;
+  delta: string;
+}
+
+type State = 'line-start' | 'maybe-prefix' | 'prefix-token' | 'after-token' | 'body';
+
+export class ProseStreamRouter {
+  private target: string | null;
+  private state: State = 'line-start';
+  private held = '';      // text held while a line's decision is pending
+  private token = '';     // the >>spec token being accumulated
+  private sawBang = false;
+  private accumulated = new Map<string, string>();
+
+  constructor(
+    private opts: {
+      /** 'explicit' parses `>>` prefixes; 'locus' is pure passthrough. */
+      mode: 'explicit' | 'locus';
+      /** Initial destination: the frozen turn locus (locus mode) or null. */
+      initialTarget: string | null;
+      /** Resolve a `>>spec` to a channelId, or null (unresolved/ambiguous). */
+      resolve: (spec: string) => string | null;
+    },
+  ) {
+    this.target = opts.initialTarget;
+    if (opts.mode === 'locus') this.state = 'body';
+  }
+
+  /** Per-channel full text emitted so far (for outgoing/complete). */
+  byChannel(): ReadonlyMap<string, string> {
+    return this.accumulated;
+  }
+
+  feed(delta: string): RoutedDelta[] {
+    const out: RoutedDelta[] = [];
+    for (const ch of delta) this.step(ch, out);
+    return coalesce(out);
+  }
+
+  /** End of stream: flush any held line-start text (it can no longer become a
+   *  complete prefix; an unterminated `>>tok` at EOF is routing metadata with
+   *  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); // "" | ">" | ">>"
+    // prefix-token / after-token at EOF: prefix without body — nothing to emit.
+    this.held = '';
+    this.state = 'line-start';
+    return coalesce(out);
+  }
+
+  private step(ch: string, out: RoutedDelta[]): void {
+    switch (this.state) {
+      case 'body':
+        if (ch === '\n' && this.opts.mode === 'explicit') {
+          this.emit('\n', out);
+          this.state = 'line-start';
+        } else {
+          this.emit(ch, out);
+        }
+        return;
+
+      case 'line-start':
+        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 === '>>') {
+          if (ch === '\n' || ch === ' ' || ch === '\t') {
+            // `>> quoted arrow` / bare `>>`: body text, not a prefix.
+            this.emit(this.held, out);
+            this.held = '';
+            this.state = 'body';
+            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-token':
+        if (ch === ' ' || ch === '\t') { this.applyTarget(); this.state = 'after-token'; this.sawBang = false; return; }
+        if (ch === '\n') { this.applyTarget(); this.state = 'line-start'; return; }
+        this.token += ch;
+        return;
+
+      case 'after-token':
+        // Grammar: `([ \t]+!)?[ \t]*` — one optional `!` immediately after the
+        // first whitespace run is the continue-turn modifier, not body.
+        if (ch === ' ' || ch === '\t') return;
+        if (ch === '\n') { this.state = 'line-start'; return; }
+        if (ch === '!' && !this.sawBang) { this.sawBang = true; return; }
+        this.state = 'body';
+        this.step(ch, out);
+        return;
+    }
+  }
+
+  private applyTarget(): void {
+    const spec = this.token;
+    this.token = '';
+    if (spec === 'skip_reply') { this.target = null; return; }
+    this.target = this.opts.resolve(spec);
+  }
+
+  private emit(text: string, out: RoutedDelta[]): void {
+    if (this.target === null || !text) return;
+    out.push({ channelId: this.target, delta: text });
+    this.accumulated.set(this.target, (this.accumulated.get(this.target) ?? '') + text);
+  }
+}
+
+function coalesce(deltas: RoutedDelta[]): RoutedDelta[] {
+  const out: RoutedDelta[] = [];
+  for (const d of deltas) {
+    const last = out[out.length - 1];
+    if (last && last.channelId === d.channelId) last.delta += d.delta;
+    else out.push({ ...d });
+  }
+  return out;
+}

package/src/modules/workspace/index.ts

@@ -733,13 +733,13 @@ export class WorkspaceModule implements Module {
     return [
       {
         name: 'read',
-        description: 'Read a file from the workspace. Returns content with line numbers.',
+        description: 'Read a file from the workspace. Returns content with line numbers. Reads at most 2000 lines per call by default — use offset/limit to page through larger files.',
         inputSchema: {
           type: 'object' as const,
           properties: {
             path: { type: 'string', description: 'File path (mount-prefixed, e.g., "project/src/main.ts")' },
             offset: { type: 'number', description: 'Starting line number (1-indexed)' },
-            limit: { type: 'number', description: 'Maximum number of lines to return' },
+            limit: { type: 'number', description: 'Maximum number of lines to return (default 2000)' },
           },
           required: ['path'],
         },
@@ -1344,10 +1344,16 @@ export class WorkspaceModule implements Module {
     const content = blob.toString('utf-8');
     const lines = content.split('\n');
 
-    // Apply offset/limit
+    // Apply offset/limit. An unlimited read of a large file would inject the
+    // whole thing into the turn (a 2MB file ≈ 600k tokens → the request blows
+    // past the model context and 400s), so an omitted limit falls back to a
+    // default cap; the result reports total/from/to so the agent can page.
+    const DEFAULT_READ_LINE_LIMIT = 2000;
     const startLine = (input.offset ?? 1) - 1; // Convert to 0-indexed
-    const endLine = input.limit ? startLine + input.limit : lines.length;
+    const effectiveLimit = input.limit ?? DEFAULT_READ_LINE_LIMIT;
+    const endLine = startLine + effectiveLimit;
     const slice = lines.slice(startLine, endLine);
+    const truncated = endLine < lines.length;
 
     // Format with line numbers (cat -n style)
     const formatted = slice
@@ -1361,6 +1367,9 @@ export class WorkspaceModule implements Module {
         totalLines: lines.length,
         fromLine: startLine + 1,
         toLine: Math.min(endLine, lines.length),
+        ...(truncated
+          ? { note: `Truncated at ${effectiveLimit} lines (file has ${lines.length}). Use offset/limit to read more.` }
+          : {}),
         content: formatted,
       },
     };

package/src/types/agent.ts

@@ -133,6 +133,16 @@ export interface AgentConfig {
      */
     announceHumanTurns?: boolean;
   };
+
+  /**
+   * How the agent's PLAIN PROSE (non-tool output) reaches channels.
+   * - 'locus' (default): host-inferred — the turn-frozen locus machinery.
+   * - 'explicit': the model prefixes prose with a destination
+   *   (`>>#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.
+   */
+  proseRouting?: 'locus' | 'explicit';
 }
 
 /** The intentionally small set of agent settings that may change in-process. */
@@ -239,4 +249,12 @@ export interface InferenceRequest {
    * which correctly fall back to the global default channel.
    */
   channelId?: string;
+  /**
+   * True when the triggering message explicitly addressed the agent (mention,
+   * reply-to-bot, DM — `chat:addressed` in MCPL RFC-001 terms). When a wake
+   * batch spans several channels, an addressed channel outranks ambient
+   * chatter for the turn's frozen speech locus: overheard conversation must
+   * not capture the agent's voice just by being newest.
+   */
+  addressed?: boolean;
 }

package/src/types/framework.ts

@@ -31,6 +31,35 @@ export interface ProcessLoggingConfig {
 /**
  * Configuration for the agent framework.
  */
+/**
+ * Client-side programmatic tool calling: a synthesized `code_execution` tool
+ * that runs model-authored Python on the host, with every framework tool
+ * injected as an async function. Mirrors the trained surface of Anthropic's
+ * server-side PTC; inner tool results never enter the model context.
+ *
+ * Robustness boundary, not a security sandbox (same doctrine as gate.js —
+ * the agent already has broader host access through its tools).
+ */
+export interface CodeExecutionConfig {
+  /** Master switch — the tool is only synthesized when true. */
+  enabled: boolean;
+  /** Python interpreter to spawn (default: 'python3' from PATH). */
+  pythonPath?: string;
+  /**
+   * Per-inner-tool-call timeout; exceeding it raises TimeoutError inside the
+   * script (default 270_000 ms, mirroring the managed runtime's message).
+   */
+  toolCallTimeoutMs?: number;
+  /** Whole-script deadline: cancel → grace → SIGKILL (default 600_000 ms). */
+  scriptTimeoutMs?: number;
+  /**
+   * Idle interpreter reclaim — script globals are lost after this much
+   * inactivity (default 300_000 ms, mirroring ~5-minute container reclaim).
+   * 0 disables reclaim.
+   */
+  idleReclaimMs?: number;
+}
+
 export interface FrameworkConfig {
   /**
    * IANA zone used only when rendering wall-clock times for the agent.
@@ -93,6 +122,12 @@ export interface FrameworkConfig {
   /** MCPL server configurations. If omitted or empty, no MCPL subsystems are created. */
   mcplServers?: McplServerConfig[];
 
+  /**
+   * Client-side programmatic tool calling (`code_execution` tool). Omitted or
+   * `enabled: false` → tool absent, no python is ever spawned.
+   */
+  codeExecution?: CodeExecutionConfig;
+
   /** Inference routing policy for server-initiated inference (optional). */
   inferenceRouting?: InferenceRoutingPolicy;
 

package/src/types/trace.ts

@@ -37,7 +37,18 @@ export type TraceEvent =
     })
 
   // Inference lifecycle
-  | (TraceEventBase & { type: 'inference:started'; agentName: string })
+  | (TraceEventBase & {
+      type: 'inference:started';
+      agentName: string;
+      /**
+       * The turn-frozen outbound locus (see turnLocusPins) — the channel this
+       * turn's plain prose will be routed to. Omitted for turns with no locus
+       * (heartbeats with no default channel). Observability only, like every
+       * trace field; lets external taps (e.g. a TTS relay) tag the whole
+       * activation with its channel without re-deriving routing.
+       */
+      channelId?: string;
+    })
   | (TraceEventBase & {
       type: 'inference:completed';
       agentName: string;
@@ -82,6 +93,8 @@ export type TraceEvent =
       blockType: 'text' | 'thinking' | 'tool_call' | 'tool_result';
       /** 0-indexed block position in the current assistant turn. */
       blockIndex: number;
+      /** Turn-frozen outbound locus for this turn (see inference:started). */
+      channelId?: string;
     })
   | (TraceEventBase & {
       /**
@@ -95,6 +108,8 @@ export type TraceEvent =
       phase: 'block_start' | 'block_complete';
       blockType: 'text' | 'thinking' | 'tool_call' | 'tool_result';
       blockIndex: number;
+      /** Turn-frozen outbound locus for this turn (see inference:started). */
+      channelId?: string;
     })
   | (TraceEventBase & {
       type: 'inference:tool_calls_yielded';
@@ -281,6 +296,37 @@ export type TraceEvent =
       channelId?: string;
     })
 
+  // Host-owned speech routing (ChannelRegistry.routeSpeech). One trace per
+  // delivered prose segment. `text` is the segment verbatim — the same content
+  // already on the bus chunk-by-chunk via inference:tokens, and mcpl:* traces
+  // are 'ops'-scoped on the webui wire — and `messageId` is the surface's id
+  // for the posted message (when the MCPL server reports one). Together they
+  // give external taps the (channelId, messageId, text) tuple needed to edit
+  // a just-posted message, e.g. a TTS interruption truncating a reply to the
+  // words actually voiced.
+  | (TraceEventBase & {
+      type: 'mcpl:speech-routed';
+      /** Agent / conversation whose speech was routed. */
+      conversationId: string;
+      serverId: string;
+      channelId: string;
+      delivered: boolean;
+      textLen: number;
+      /** The routed prose segment, verbatim. */
+      text: string;
+      /** Surface message id (e.g. Discord message id), when reported. */
+      messageId?: string;
+    })
+  | (TraceEventBase & {
+      type: 'mcpl:speech-route-failed';
+      /** Agent / conversation whose speech failed to route. */
+      conversationId: string;
+      /** Empty string when the failure was "no locus at all". */
+      channelId: string;
+      reason: string;
+      textLen: 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.