@animalabs/agent-framework 0.7.3 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/agent-framework",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Multi-agent framework with pluggable modules, persistent state, and concurrent tool execution",
   "repository": {
     "type": "git",

package/src/agent.ts

@@ -270,7 +270,11 @@ export class Agent {
 
     if (patch.contextBudgetTokens !== undefined) {
       const live = this.contextBudgetTokens ?? DEFAULT_CONTEXT_BUDGET_TOKENS;
-      if (patch.contextBudgetTokens >= live) {
+      if (patch.contextBudgetTokens >= live || patch.immediate) {
+        // Increases are always immediate. Decreases take this path only with
+        // the explicit `immediate` flag: the next compile plans straight at
+        // the new budget — one-shot fold-down, KV invalidation paid this
+        // turn — and any in-flight descent is cancelled.
         nextContextBudget = patch.contextBudgetTokens;
         nextContextTarget = undefined;
         if (this.getHotContextSettings()) hotPatch.preparedWindowTokens = null;
@@ -298,6 +302,7 @@ export class Agent {
     }
     for (const [key, value] of Object.entries(patch)) {
       if (key === 'sameRoundThinkTextPolicy') continue;
+      if (key === 'immediate') continue; // a mode for this apply, never a persisted setting
       if (value !== undefined) (this.runtimeSettingsOverrides as Record<string, unknown>)[key] = value;
     }
     if (patch.sameRoundThinkTextPolicy !== undefined) {
@@ -706,6 +711,31 @@ export class Agent {
    * Called by framework when stream completes.
    */
   addAssistantResponse(content: ContentBlock[]): void {
+    // A turn whose entire output is thinking blocks produced NOTHING: no
+    // speech, no tool call. That is what a refusal looks like on the wire —
+    // the provider returns signed thinking (often with empty text, the
+    // fable-5 hidden-CoT packaging) and no content. Persisting it records an
+    // action that never happened, and two such records landing adjacent are
+    // actively toxic: formatters merge consecutive same-role messages
+    // (membrane `mergeConsecutiveRoles`), producing one assistant message
+    // carrying signed thinking from two different responses, which the
+    // provider cannot verify — 400 "`thinking` or `redacted_thinking` blocks
+    // in the latest assistant message cannot be modified", unrecoverable by
+    // retry (labclaude, 2026-07-27: hard down ~4h on exactly this pair).
+    //
+    // Refused turns are surfaced by the refusal path (stderr, failures.log,
+    // the [inference-failed] notice); the store does not also need a
+    // content-free artifact of them. Loud, never silent.
+    if (content.length > 0 && content.every(
+      (b) => b.type === 'thinking' || b.type === 'redacted_thinking',
+    )) {
+      console.error(
+        `[assistant-persist] agent=${this.name}: refusing to store a thinking-only assistant ` +
+        `message (${content.length} block(s), no text and no tool_use) — the turn produced no ` +
+        `output. See the refusal/inference-failed record for why.`,
+      );
+      return;
+    }
     this.contextManager.addMessage(this.name, content);
   }
 

package/src/code-execution/index.ts

@@ -14,6 +14,7 @@ export type {
   ExecResult,
   PyRunnerOptions,
   ScriptToolCallHandler,
+  BackgroundExecOptions,
 } from './py-runner.js';
 export { PYTHON_RUNTIME_SOURCE } from './runtime-py.js';
 export { buildCodeExecutionToolDefinition, CODE_EXECUTION_TOOL_NAME } from './tool-definition.js';

package/src/code-execution/py-runner.ts

@@ -34,6 +34,23 @@ export interface ExecResult {
   returnCode: number;
   /** Set when the host killed the script (deadline / abort / crash). */
   aborted?: boolean;
+  /** Background execs: rolling tail of interleaved stdout+stderr (for the
+   *  crash/finish envelope; the full journal is in the log file). */
+  tail?: string;
+}
+
+/** Per-exec options for background (daemon) scripts. */
+export interface BackgroundExecOptions {
+  /** Absolute path for the line-buffered stdout+stderr journal (null: tail only). */
+  logPath: string | null;
+  /**
+   * Called on each wake_agent() from the script. Resolve with null to ack
+   * (deliver), or an error string to refuse (raises RuntimeError in-script).
+   * May resolve late — rate limiting backpressures inside wake_agent().
+   */
+  onWake: (line: number, payload: unknown) => Promise<string | null>;
+  /** Overrides the runner's scriptTimeoutMs (background lifetime). */
+  lifetimeMs: number;
 }
 
 /** Resolves inner tool calls. Must never reject — map errors to strings. */
@@ -76,6 +93,7 @@ export class PyRunner {
   private readonly onToolCall: ScriptToolCallHandler;
   private readonly label: string;
 
+  private onWake: ((line: number, payload: unknown) => Promise<string | null>) | null = null;
   private child: ChildProcessWithoutNullStreams | null = null;
   private childReady: Promise<void> | null = null;
   private reader: Interface | null = null;
@@ -102,8 +120,13 @@ export class PyRunner {
    * Run one script. Tools are (re-)injected before every exec so the
    * interpreter always reflects the current tool surface (list_changed etc.).
    * Never rejects: every failure mode resolves to an ExecResult.
+   *
+   * With `background` options the exec is a daemon: output journals to the
+   * log file, wake_agent() is available in-script, and the deadline is the
+   * background lifetime. A background runner should be DEDICATED to that one
+   * script (the framework creates one per background script).
    */
-  async exec(code: string, tools: InjectedTool[]): Promise<ExecResult> {
+  async exec(code: string, tools: InjectedTool[], background?: BackgroundExecOptions): Promise<ExecResult> {
     if (this.disposed) {
       return { stdout: '', stderr: 'code_execution runner disposed', returnCode: 1, aborted: true };
     }
@@ -131,6 +154,8 @@ export class PyRunner {
     }
 
     const execId = `e${++this.execCounter}`;
+    const deadlineMs = background?.lifetimeMs ?? this.scriptTimeoutMs;
+    this.onWake = background?.onWake ?? null;
     const result = await new Promise<ExecResult>((resolve) => {
       const pending: PendingExec = {
         id: execId,
@@ -148,23 +173,29 @@ export class PyRunner {
         pending.killTimer = setTimeout(() => {
           this.settlePending({
             stdout: '',
-            stderr: `script killed after exceeding ${Math.round(this.scriptTimeoutMs / 1000)}s deadline`,
+            stderr: `script killed after exceeding ${Math.round(deadlineMs / 1000)}s deadline`,
             returnCode: 1,
             aborted: true,
           });
           this.reclaim('deadline-kill');
         }, CANCEL_GRACE_MS);
-      }, this.scriptTimeoutMs);
+      }, deadlineMs);
+      // A day-scale background deadline must not hold the process open.
+      if (background) pending.deadlineTimer.unref?.();
 
       this.send({
         op: 'init',
         tools: tools.map((t) => ({ py_name: t.pyName, tool_name: t.toolName })),
         call_timeout_s: Math.round(this.toolCallTimeoutMs / 1000),
+        ...(background
+          ? { background: true, log_path: background.logPath ?? null }
+          : {}),
       });
       this.send({ op: 'exec', id: execId, code });
     });
 
-    this.armIdleTimer();
+    this.onWake = null;
+    if (!background) this.armIdleTimer();
     return result;
   }
 
@@ -308,12 +339,33 @@ export class PyRunner {
         return;
       }
 
+      case 'wake': {
+        const wakeId = msg.id;
+        if (!wakeId) return;
+        const line = typeof (msg as { line?: unknown }).line === 'number'
+          ? (msg as { line: number }).line
+          : -1;
+        const payload = (msg as { payload?: unknown }).payload;
+        const handler = this.onWake;
+        const refuse = handler
+          ? handler(line, payload).catch((err: unknown) =>
+              `wake handler failed: ${err instanceof Error ? err.message : String(err)}`)
+          : Promise.resolve('this script is not allowed to wake the agent');
+        void refuse.then((error) => {
+          this.send({ op: 'wake_ack', id: wakeId, ...(error ? { error } : {}) });
+        });
+        return;
+      }
+
       case 'exec_result': {
         if (this.pending && msg.id === this.pending.id) {
           this.settlePending({
             stdout: msg.stdout ?? '',
             stderr: msg.stderr ?? '',
             returnCode: typeof msg.return_code === 'number' ? msg.return_code : 1,
+            ...(typeof (msg as { tail?: unknown }).tail === 'string'
+              ? { tail: (msg as { tail: string }).tail }
+              : {}),
           });
         }
         return;

package/src/code-execution/runtime-py.ts

@@ -12,17 +12,30 @@
  *     same message shape the managed runtime produces
  *   - interpreter globals persist across execs (container-reuse semantics)
  *
+ * BACKGROUND MODE (model-authored daemons): when init carries
+ * `background: true`, the exec additionally gets:
+ *   - `wake_agent(payload)` — async; reports the caller's line number (which
+ *     indexes into the agent-authored script — self-correlation) and delivers
+ *     the payload to the host, which injects it into the agent's context and
+ *     triggers inference. Awaits a host ack so rate limiting backpressures
+ *     inside the script instead of dropping wakes.
+ *   - stdout/stderr tee'd line-buffered to `log_path` (agent-readable via
+ *     their file tools) with an in-memory tail kept for the crash envelope.
+ *
  * Embedded as a TS string because tsc does not copy non-TS assets to dist/;
  * PyRunner materializes it to a temp file at spawn.
  *
  * Protocol (JSON lines):
- *   host -> py : {op:"init", tools:[{py_name,tool_name}], call_timeout_s}
+ *   host -> py : {op:"init", tools:[{py_name,tool_name}], call_timeout_s,
+ *                 background?, log_path?, tail_chars?}
  *                {op:"exec", id, code}
  *                {op:"tool_result", id, result}
+ *                {op:"wake_ack", id, error?}
  *                {op:"cancel", id, reason?}
  *   py -> host : {op:"ready"}
  *                {op:"tool_call", id, exec_id, name, args}
- *                {op:"exec_result", id, stdout, stderr, return_code}
+ *                {op:"wake", id, exec_id, line, payload}
+ *                {op:"exec_result", id, stdout, stderr, return_code, tail?}
  *
  * IMPORTANT: the python source below must not contain backticks or the
  * sequence dollar+brace (TS template literal syntax). String.raw preserves
@@ -35,6 +48,7 @@ import asyncio
 import inspect
 import io
 import json
+import os
 import sys
 import threading
 import traceback
@@ -43,6 +57,11 @@ PROTO_OUT = sys.stdout          # protocol channel (real stdout)
 REAL_STDERR = sys.stderr        # runtime diagnostics outside execs
 CALL_TIMEOUT_S = 270.0
 OUTPUT_CAP_CHARS = 2_000_000
+LOG_FILE_CAP_BYTES = 50_000_000
+
+BACKGROUND = False
+LOG_PATH = None
+TAIL_CHARS = 4000
 
 _send_lock = threading.Lock()
 
@@ -75,13 +94,78 @@ class CappedIO(io.StringIO):
         return super().write(s)
 
 
+class LogTee:
+    """Background-mode writer: line-buffered file append + rolling tail.
+
+    The file is the agent-readable journal (their read/grep/shell tools work
+    on it); the tail rides the exec_result so the host can build a crash
+    envelope without re-reading the file.
+    """
+
+    def __init__(self, path, tail_chars):
+        self._fh = None
+        self._written = 0
+        self._tail = ""
+        self._tail_chars = tail_chars
+        self.truncated = False
+        if path:
+            try:
+                os.makedirs(os.path.dirname(path), exist_ok=True)
+                self._fh = open(path, "a", encoding="utf-8", errors="replace")
+            except Exception as exc:
+                REAL_STDERR.write("[pytc-runtime] cannot open log file: " + str(exc) + "\n")
+                REAL_STDERR.flush()
+
+    def write(self, s):
+        if not isinstance(s, str):
+            s = str(s)
+        self._tail = (self._tail + s)[-self._tail_chars:]
+        if self._fh is not None and not self.truncated:
+            if self._written + len(s) > LOG_FILE_CAP_BYTES:
+                self.truncated = True
+                try:
+                    self._fh.write("\n[log capped at " + str(LOG_FILE_CAP_BYTES) + " bytes]\n")
+                    self._fh.flush()
+                except Exception:
+                    pass
+            else:
+                try:
+                    self._fh.write(s)
+                    if "\n" in s:
+                        self._fh.flush()
+                    self._written += len(s)
+                except Exception:
+                    pass
+        return len(s)
+
+    def flush(self):
+        if self._fh is not None:
+            try:
+                self._fh.flush()
+            except Exception:
+                pass
+
+    def close(self):
+        if self._fh is not None:
+            try:
+                self._fh.close()
+            except Exception:
+                pass
+            self._fh = None
+
+    def tail(self):
+        return self._tail
+
+
 # Persistent interpreter state (mirrors container reuse: variables survive
 # between exec calls until the host reclaims the interpreter).
 SCRIPT_GLOBALS = {"__name__": "__main__", "__builtins__": __builtins__}
 _injected_py_names = set()
 
 _pending_tool_futures = {}
+_pending_wake_futures = {}
 _next_tool_call_id = 0
+_next_wake_id = 0
 _current_exec_id = None
 _current_exec_task = None
 
@@ -116,7 +200,6 @@ def _make_tool_fn(tool_name, py_name):
             )
         finally:
             _pending_tool_futures.pop(call_id, None)
-
     tool_fn.__name__ = py_name
     tool_fn.__qualname__ = py_name
     tool_fn.__doc__ = (
@@ -126,11 +209,47 @@ def _make_tool_fn(tool_name, py_name):
     return tool_fn
 
 
+async def wake_agent(payload=None):
+    """Wake the agent: deliver payload into their context and trigger a turn.
+
+    Reports the caller's line number (indexes into the script the agent
+    wrote). Awaits the host ack — rate limiting backpressures here rather
+    than dropping wakes. Raises RuntimeError when the host refuses (wake cap
+    exceeded, script cancelled).
+    """
+    global _next_wake_id
+    frame = inspect.currentframe()
+    line = frame.f_back.f_lineno if frame is not None and frame.f_back is not None else -1
+    _next_wake_id += 1
+    wake_id = "w" + str(_next_wake_id)
+    fut = asyncio.get_running_loop().create_future()
+    _pending_wake_futures[wake_id] = fut
+    send({
+        "op": "wake",
+        "id": wake_id,
+        "exec_id": _current_exec_id,
+        "line": line,
+        "payload": payload,
+    })
+    try:
+        error = await fut
+        if error:
+            raise RuntimeError("wake_agent refused by host: " + str(error))
+        return None
+    finally:
+        _pending_wake_futures.pop(wake_id, None)
+
+
 def handle_init(msg):
-    global CALL_TIMEOUT_S
+    global CALL_TIMEOUT_S, BACKGROUND, LOG_PATH, TAIL_CHARS
     timeout = msg.get("call_timeout_s")
     if isinstance(timeout, (int, float)) and timeout > 0:
         CALL_TIMEOUT_S = float(timeout)
+    BACKGROUND = bool(msg.get("background"))
+    LOG_PATH = msg.get("log_path") or None
+    tail = msg.get("tail_chars")
+    if isinstance(tail, int) and tail > 0:
+        TAIL_CHARS = tail
 
     # Remove functions injected by a previous init that are no longer present
     # (tool list changed) without touching user-defined globals.
@@ -152,12 +271,22 @@ def handle_init(msg):
     _injected_py_names.update(new_py_names)
     # Exact-name escape hatch: tools["mcpl--server--tool"]({...})
     SCRIPT_GLOBALS["tools"] = tools_dict
+    # The doorbell exists only in background mode — a foreground script's
+    # agent is already awake (mid-turn).
+    if BACKGROUND:
+        SCRIPT_GLOBALS["wake_agent"] = wake_agent
+    else:
+        SCRIPT_GLOBALS.pop("wake_agent", None)
 
 
 async def _run_script(exec_id, code):
     global _current_exec_id, _current_exec_task
-    out = CappedIO(OUTPUT_CAP_CHARS)
-    err = CappedIO(OUTPUT_CAP_CHARS)
+    if BACKGROUND:
+        out = LogTee(LOG_PATH, TAIL_CHARS)
+        err = out  # interleave, terminal-style; tail is shared
+    else:
+        out = CappedIO(OUTPUT_CAP_CHARS)
+        err = CappedIO(OUTPUT_CAP_CHARS)
     old_out, old_err, old_in = sys.stdout, sys.stderr, sys.stdin
     sys.stdout, sys.stderr = out, err
     sys.stdin = io.StringIO("")  # input() must not steal the protocol channel
@@ -177,11 +306,27 @@ async def _run_script(exec_id, code):
         sys.stdout, sys.stderr, sys.stdin = old_out, old_err, old_in
         _current_exec_id = None
         _current_exec_task = None
-        # Fail any tool futures still pending: their exec is gone.
         for fut in list(_pending_tool_futures.values()):
             if not fut.done():
                 fut.cancel()
         _pending_tool_futures.clear()
+        for fut in list(_pending_wake_futures.values()):
+            if not fut.done():
+                fut.cancel()
+        _pending_wake_futures.clear()
+
+    if BACKGROUND:
+        out.flush()
+        out.close()
+        send({
+            "op": "exec_result",
+            "id": exec_id,
+            "stdout": "",
+            "stderr": "",
+            "tail": out.tail(),
+            "return_code": return_code,
+        })
+        return
 
     stdout_text = out.getvalue()
     if out.truncated:
@@ -245,6 +390,10 @@ async def main():
             fut = _pending_tool_futures.get(msg.get("id"))
             if fut is not None and not fut.done():
                 fut.set_result(str(msg.get("result", "")))
+        elif op == "wake_ack":
+            fut = _pending_wake_futures.get(msg.get("id"))
+            if fut is not None and not fut.done():
+                fut.set_result(msg.get("error") or None)
         elif op == "cancel":
             if _current_exec_task is not None and not _current_exec_task.done():
                 _current_exec_task.cancel()

package/src/code-execution/tool-definition.ts

@@ -39,7 +39,19 @@ export function buildCodeExecutionToolDefinition(opts?: {
       'Use this when fanning out across many items, looping over tool calls, or when tool ' +
       'results are large and you only need a slice or summary. Call tools directly (not via ' +
       'code) when a single call answers the question or when you need to reason about each ' +
-      'result before deciding the next step.',
+      'result before deciding the next step. ' +
+      'BACKGROUND MODE: pass background=true to run the script as a detached watcher that ' +
+      'outlives this turn — the tool returns immediately with a script_id and you can end ' +
+      'your turn (e.g. sleep). Inside a background script, await wake_agent(payload) wakes ' +
+      'you: the payload plus provenance (script id, the line number in your script, elapsed ' +
+      'time) is delivered into your context and starts a turn for you. A script that ends ' +
+      'without calling wake_agent wakes nobody — that silence is the point (poll cheaply, ' +
+      'wake only on signal). If your background script CRASHES you are woken with the error. ' +
+      'Its print() output streams to a workspace log file you can read any time. Wakes are ' +
+      'rate-limited (early wakes are delayed, not dropped) and capped per script. ' +
+      'CAUTION: background scripts die silently if the host process restarts — for a wake ' +
+      'you absolutely must not miss, also arm a wake rule as backup. ' +
+      'Manage your scripts with {"action": "list"} and {"action": "cancel", "script_id": "..."}.',
     inputSchema: {
       type: 'object' as const,
       properties: {
@@ -47,8 +59,21 @@ export function buildCodeExecutionToolDefinition(opts?: {
           type: 'string',
           description: 'Python code to execute. Top-level await is allowed.',
         },
+        background: {
+          type: 'boolean',
+          description: 'Run detached as a background watcher with wake_agent() available (default false).',
+        },
+        action: {
+          type: 'string',
+          enum: ['run', 'list', 'cancel'],
+          description: 'run (default) executes `code`; list shows your background scripts; cancel stops one.',
+        },
+        script_id: {
+          type: 'string',
+          description: 'Background script id (for action: cancel).',
+        },
       },
-      required: ['code'],
+      required: [],
     },
   };
 }