@animalabs/agent-framework 0.7.0 → 0.7.2

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