@animalabs/agent-framework 0.7.4 → 0.9.0

package/dist/src/code-execution/runtime-py.js

@@ -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
@@ -34,6 +47,7 @@ import asyncio
 import inspect
 import io
 import json
+import os
 import sys
 import threading
 import traceback
@@ -42,6 +56,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()
 
@@ -74,13 +93,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
 
@@ -115,7 +199,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__ = (
@@ -125,11 +208,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.
@@ -151,12 +270,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
@@ -176,11 +305,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:
@@ -244,6 +389,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/dist/src/code-execution/runtime-py.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-py.js","sourceRoot":"","sources":["../../../src/code-execution/runtime-py.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAW,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyOtD,CAAC"}
+{"version":3,"file":"runtime-py.js","sourceRoot":"","sources":["../../../src/code-execution/runtime-py.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAW,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiXtD,CAAC"}

package/dist/src/code-execution/tool-definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-definition.d.ts","sourceRoot":"","sources":["../../../src/code-execution/tool-definition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,wBAAgB,gCAAgC,CAAC,IAAI,CAAC,EAAE;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GAAG,cAAc,CAoCjB"}
+{"version":3,"file":"tool-definition.d.ts","sourceRoot":"","sources":["../../../src/code-execution/tool-definition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,wBAAgB,gCAAgC,CAAC,IAAI,CAAC,EAAE;IACtD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,GAAG,cAAc,CA6DjB"}

package/dist/src/code-execution/tool-definition.js

@@ -31,7 +31,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',
             properties: {
@@ -39,8 +51,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: [],
         },
     };
 }

package/dist/src/code-execution/tool-definition.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-definition.js","sourceRoot":"","sources":["../../../src/code-execution/tool-definition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,CAAC,MAAM,wBAAwB,GAAG,gBAAgB,CAAC;AAEzD,MAAM,UAAU,gCAAgC,CAAC,IAGhD;IACC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,aAAa,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IACvF,MAAM,kBAAkB,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,iBAAiB,IAAI,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACnF,OAAO;QACL,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EACT,mEAAmE;YACnE,kFAAkF;YAClF,8EAA8E;YAC9E,2CAA2C;YAC3C,0FAA0F;YAC1F,oEAAoE;YACpE,sFAAsF;YACtF,0FAA0F;YAC1F,6FAA6F;YAC7F,8EAA8E;YAC9E,yFAAyF;YACzF,0FAA0F;YAC1F,uFAAuF;YACvF,iCAAiC,WAAW,8CAA8C;YAC1F,oBAAoB,kBAAkB,2CAA2C;YACjF,qFAAqF;YACrF,uFAAuF;YACvF,sFAAsF;YACtF,uCAAuC;QACzC,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,qDAAqD;iBACnE;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,CAAC;SACnB;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"tool-definition.js","sourceRoot":"","sources":["../../../src/code-execution/tool-definition.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,CAAC,MAAM,wBAAwB,GAAG,gBAAgB,CAAC;AAEzD,MAAM,UAAU,gCAAgC,CAAC,IAGhD;IACC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,aAAa,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IACvF,MAAM,kBAAkB,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,iBAAiB,IAAI,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACnF,OAAO;QACL,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EACT,mEAAmE;YACnE,kFAAkF;YAClF,8EAA8E;YAC9E,2CAA2C;YAC3C,0FAA0F;YAC1F,oEAAoE;YACpE,sFAAsF;YACtF,0FAA0F;YAC1F,6FAA6F;YAC7F,8EAA8E;YAC9E,yFAAyF;YACzF,0FAA0F;YAC1F,uFAAuF;YACvF,iCAAiC,WAAW,8CAA8C;YAC1F,oBAAoB,kBAAkB,2CAA2C;YACjF,qFAAqF;YACrF,uFAAuF;YACvF,sFAAsF;YACtF,wCAAwC;YACxC,qFAAqF;YACrF,qFAAqF;YACrF,sFAAsF;YACtF,uFAAuF;YACvF,qFAAqF;YACrF,qFAAqF;YACrF,wFAAwF;YACxF,sFAAsF;YACtF,6EAA6E;YAC7E,qFAAqF;YACrF,gEAAgE;YAChE,2FAA2F;QAC7F,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,qDAAqD;iBACnE;gBACD,UAAU,EAAE;oBACV,IAAI,EAAE,SAAS;oBACf,WAAW,EAAE,mFAAmF;iBACjG;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC;oBAC/B,WAAW,EAAE,sFAAsF;iBACpG;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,4CAA4C;iBAC1D;aACF;YACD,QAAQ,EAAE,EAAE;SACb;KACF,CAAC;AACJ,CAAC"}