open-agents-ai 0.106.0 → 0.108.0

package/dist/index.js

@@ -7557,10 +7557,54 @@ var init_repl = __esm({
       setLlmQueryHandler(handler) {
         this.llmQueryHandler = handler;
       }
+      /** Callback for retrieving externalized handle content (RLM Context OS) */
+      handleResolver = null;
+      /** Set the handle resolver for retrieve() in the REPL (COHERE Layer 2) */
+      setHandleResolver(resolver) {
+        this.handleResolver = resolver;
+      }
       /** Get the number of sub-calls made this session */
       getSubCallCount() {
         return this.subCallCount;
       }
+      /**
+       * Pre-load a large context string into the REPL as the `context` variable.
+       * Used by prompt externalization (RLM paper §2, Principle 1: symbolic handle).
+       * The context is stored as a Python string variable — the model can then
+       * slice, search, and process it via repl_exec without it entering the LLM context.
+       */
+      async loadContext(content) {
+        if (!this.proc || this.proc.killed || this.proc.exitCode !== null) {
+          await this.startProcess();
+        }
+        const tempFile = join18(tmpdir3(), `oa-repl-ctx-${randomBytes2(6).toString("hex")}.txt`);
+        const { writeFileSync: writeFs, unlinkSync: unlinkFs } = await import("node:fs");
+        writeFs(tempFile, content, "utf8");
+        const result = await this.executeCode(`with open(${JSON.stringify(tempFile)}, "r") as _f:
+    context = _f.read()
+import os; os.unlink(${JSON.stringify(tempFile)})
+print(f"Context loaded: {len(context)} chars")`);
+        try {
+          unlinkFs(tempFile);
+        } catch {
+        }
+        return result.success;
+      }
+      /**
+       * Read a variable's value from the REPL environment.
+       * Used by FINAL_VAR to extract the task output (RLM paper §2, Principle 2).
+       */
+      async readVariable(varName) {
+        if (!this.proc || this.proc.killed || this.proc.exitCode !== null)
+          return null;
+        const result = await this.executeCode(`try:
+    print(str(${varName}))
+except NameError:
+    print("__OA_VAR_NOT_FOUND__")`);
+        if (!result.success || result.output.includes("__OA_VAR_NOT_FOUND__"))
+          return null;
+        return result.output.trim();
+      }
       async execute(args) {
         const code = String(args.code ?? "");
         const reset = Boolean(args.reset);
@@ -7646,6 +7690,45 @@ def llm_query(prompt, context=""):
     finally:
         sock.close()
 
+def retrieve(handle_id):
+    """Retrieve full content of an externalized tool output by its handle ID.
+    Use this to access large outputs that were stored as handles instead of
+    being shown inline. Returns the full content as a string.
+    Args:
+        handle_id: The handle ID (e.g., 'a1b2c3d4')
+    Returns: Full content string, or error message if not found
+    """
+    sock_path = os.environ.get("OA_LLM_QUERY_SOCKET", "")
+    if not sock_path:
+        return "[retrieve unavailable: no IPC socket]"
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    try:
+        sock.connect(sock_path)
+        request = json.dumps({"op": "retrieve", "handle_id": str(handle_id)})
+        data = request.encode("utf-8")
+        sock.sendall(len(data).to_bytes(4, "big") + data)
+        length_bytes = b""
+        while len(length_bytes) < 4:
+            chunk = sock.recv(4 - len(length_bytes))
+            if not chunk:
+                return "[retrieve: connection closed]"
+            length_bytes += chunk
+        resp_len = int.from_bytes(length_bytes, "big")
+        resp_data = b""
+        while len(resp_data) < resp_len:
+            chunk = sock.recv(min(resp_len - len(resp_data), 65536))
+            if not chunk:
+                break
+            resp_data += chunk
+        result = json.loads(resp_data.decode("utf-8"))
+        if "error" in result:
+            return f"[retrieve error: {result['error']}]"
+        return result.get("content", "")
+    except Exception as e:
+        return f"[retrieve error: {e}]"
+    finally:
+        sock.close()
+
 # Signal REPL ready
 print("__OA_REPL_READY__")
 `.trim();
@@ -7687,14 +7770,27 @@ print("__OA_REPL_READY__")
           let response;
           try {
             const req = JSON.parse(msgData);
-            if (!this.llmQueryHandler) {
-              response = { error: "llm_query handler not configured" };
-            } else if (this.subCallCount >= this.maxSubCalls) {
-              response = { error: `Sub-call limit reached (${this.maxSubCalls})` };
+            if (req.op === "retrieve") {
+              if (!this.handleResolver) {
+                response = { error: "Handle resolver not configured" };
+              } else {
+                const content = this.handleResolver(req.handle_id ?? "");
+                if (content !== null) {
+                  response = { content };
+                } else {
+                  response = { error: `Handle '${req.handle_id}' not found` };
+                }
+              }
             } else {
-              this.subCallCount++;
-              const result = await this.llmQueryHandler(req.prompt, req.context);
-              response = { response: result };
+              if (!this.llmQueryHandler) {
+                response = { error: "llm_query handler not configured" };
+              } else if (this.subCallCount >= this.maxSubCalls) {
+                response = { error: `Sub-call limit reached (${this.maxSubCalls})` };
+              } else {
+                this.subCallCount++;
+                const result = await this.llmQueryHandler(req.prompt ?? "", req.context);
+                response = { response: result };
+              }
             }
           } catch (err) {
             response = { error: err instanceof Error ? err.message : String(err) };
@@ -19313,7 +19409,8 @@ var init_agenticRunner = __esm({
           modelTier: options?.modelTier ?? "large",
           contextWindowSize: options?.contextWindowSize ?? 0,
           personality: options?.personality ?? PERSONALITY_PRESETS.balanced,
-          personalityName: options?.personalityName ?? ""
+          personalityName: options?.personalityName ?? "",
+          finalVarResolver: options?.finalVarResolver ?? void 0
         };
       }
       /** Update context window size (e.g. after querying Ollama /api/show) */
@@ -19953,8 +20050,29 @@ If you're stuck, try a completely different approach. Do NOT repeat what failed
                 }
               }
               const { toolOutputMaxChars: maxLen } = this.contextLimits();
-              const output = result.success ? result.output.length > maxLen ? this.foldOutput(result.output, maxLen) : result.output : `Error: ${result.error || "unknown error"}
+              let output;
+              if (!result.success) {
+                output = `Error: ${result.error || "unknown error"}
 ${result.output.length > maxLen ? this.foldOutput(result.output, maxLen) : result.output}`;
+              } else if (result.output.length > maxLen) {
+                const handleId = this.quickHash(tc.name + String(tc.arguments?.["path"] ?? "") + String(turn));
+                const lineCount = (result.output.match(/\n/g) || []).length + 1;
+                const preview = result.output.slice(0, 500).replace(/\n/g, " ");
+                this._memexArchive.set(handleId, {
+                  id: handleId,
+                  toolName: tc.name,
+                  summary: `${tc.name} output (${lineCount} lines, ${result.output.length} chars)`,
+                  fullContent: result.output,
+                  turn,
+                  timestamp: (/* @__PURE__ */ new Date()).toISOString()
+                });
+                output = `[Output externalized \u2014 ${result.output.length} chars, ${lineCount} lines]
+Handle: ${handleId}
+Preview: ${preview}...
+Full content available via: repl_exec(code="data = retrieve('${handleId}')")  or  memex_retrieve(id="${handleId}")`;
+              } else {
+                output = result.output;
+              }
               this.emit({
                 type: "tool_result",
                 toolName: tc.name,
@@ -20344,9 +20462,29 @@ Integrate this guidance into your current approach. Continue working on the task
                   }
                 }
                 const { toolOutputMaxChars: maxLen2 } = this.contextLimits();
-                const output = result.success ? result.output.length > maxLen2 ? result.output.slice(0, maxLen2) + `
-...(truncated)` : result.output : `Error: ${result.error || "unknown error"}
+                let output;
+                if (!result.success) {
+                  output = `Error: ${result.error || "unknown error"}
 ${result.output}`;
+                } else if (result.output.length > maxLen2) {
+                  const handleId = this.quickHash(tc.name + String(tc.arguments?.["path"] ?? "") + String(turn));
+                  const lineCount = (result.output.match(/\n/g) || []).length + 1;
+                  const preview = result.output.slice(0, 500).replace(/\n/g, " ");
+                  this._memexArchive.set(handleId, {
+                    id: handleId,
+                    toolName: tc.name,
+                    summary: `${tc.name} output (${lineCount} lines, ${result.output.length} chars)`,
+                    fullContent: result.output,
+                    turn,
+                    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+                  });
+                  output = `[Output externalized \u2014 ${result.output.length} chars, ${lineCount} lines]
+Handle: ${handleId}
+Preview: ${preview}...
+Full content available via: repl_exec(code="data = retrieve('${handleId}')")  or  memex_retrieve(id="${handleId}")`;
+                } else {
+                  output = result.output;
+                }
                 this.emit({ type: "tool_result", toolName: tc.name, content: output.slice(0, 200), success: result.success, turn, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
                 const enoentTools2 = /* @__PURE__ */ new Set(["file_read", "list_directory", "find_files"]);
                 if (!result.success && enoentTools2.has(tc.name) && /ENOENT|no such file|does not exist|not found/i.test(result.error ?? result.output)) {
@@ -20382,6 +20520,17 @@ ${result.output}`;
                 summary = content;
                 break;
               }
+              const finalVarMatch = content.match(/FINAL_VAR\s*\(\s*["']?(\w+)["']?\s*\)/);
+              if (finalVarMatch && this.options.finalVarResolver) {
+                const varName = finalVarMatch[1];
+                const varValue = await this.options.finalVarResolver(varName);
+                if (varValue !== null) {
+                  completed = true;
+                  summary = varValue;
+                  this.emit({ type: "status", content: `FINAL_VAR(${varName}): resolved ${varValue.length} chars from REPL`, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+                  break;
+                }
+              }
               if (consecutiveTextOnly >= MAX_CONSECUTIVE_TEXT_ONLY) {
                 this.emit({
                   type: "status",
@@ -50240,6 +50389,20 @@ ${context}` : prompt;
       });
     }
   }
+  for (const tool of tools) {
+    if ("setHandleResolver" in tool && typeof tool.setHandleResolver === "function") {
+      tool.setHandleResolver((handleId) => {
+        const entry = runner.getMemexEntry(handleId);
+        return entry?.fullContent ?? null;
+      });
+    }
+  }
+  const replToolForFinalVar = tools.find((t) => t.name === "repl_exec");
+  if (replToolForFinalVar && "readVariable" in replToolForFinalVar) {
+    runner.options.finalVarResolver = async (varName) => {
+      return replToolForFinalVar.readVariable(varName);
+    };
+  }
   runner.registerTools(tools);
   runner.registerTool({
     name: "memex_retrieve",
@@ -50698,7 +50861,30 @@ ${entry.fullContent}`
 
 ${emotionContext}` : `Working directory: ${repoRoot}`;
   resetNarrationContext();
-  const promise = runner.run(task, systemContext).then((result) => {
+  let effectiveTask = task;
+  const estimatedTaskTokens = Math.ceil(task.length / 4);
+  const externalizeThreshold = contextWindowSize ? Math.floor(contextWindowSize * 0.4) : 3e4;
+  if (estimatedTaskTokens > externalizeThreshold) {
+    const replTool = tools.find((t) => t.name === "repl_exec");
+    if (replTool && "loadContext" in replTool) {
+      replTool.loadContext(task);
+      const prefix = task.slice(0, 500).replace(/\n/g, " ");
+      effectiveTask = `[RLM MODE \u2014 Large input externalized to REPL]
+Your input has been stored as the variable \`context\` in the persistent Python REPL.
+Context length: ${task.length} characters (~${estimatedTaskTokens} tokens)
+Prefix: "${prefix}..."
+
+Use repl_exec to examine and process the context. For example:
+  repl_exec(code="print(context[:1000])")  # see the beginning
+  repl_exec(code="print(len(context))")    # check length
+  repl_exec(code="chunks = context.split('\\n\\n')")  # split into chunks
+
+Use llm_query(prompt, chunk) inside repl_exec to analyze chunks.
+When done, either call task_complete with your answer, or use FINAL_VAR(variable_name) to return a REPL variable as the output.`;
+      contentWrite(() => renderInfo(`RLM: Externalized ${task.length} chars (~${estimatedTaskTokens} tokens) to REPL context variable`));
+    }
+  }
+  const promise = runner.run(effectiveTask, systemContext).then((result) => {
     const tokens = { total: result.totalTokens, estimated: result.estimatedTokens };
     contentWrite(() => {
       if (result.completed) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-agents-ai",
-  "version": "0.106.0",
+  "version": "0.108.0",
   "description": "AI coding agent powered by open-source models (Ollama/vLLM) — interactive TUI with agentic tool-calling loop",
   "type": "module",
   "main": "./dist/index.js",

package/prompts/agentic/system-large.md

@@ -462,3 +462,28 @@ Entries in a directory listing are RELATIVE to the directory you listed.
 - If an entry is marked "d" (directory), use list_directory on it — NOT file_read
 - list_directory output includes full relative paths you can copy directly into your next tool call
 - Prefer list_directory over shell ls — it shows full relative paths you can copy directly into your next tool call
+
+## RLM Context Operating System
+
+The repl_exec tool provides a persistent Python REPL where variables persist between calls. Use it for:
+
+**Data Processing**: When you need to process, transform, or analyze data across multiple steps, use repl_exec. Variables, functions, and imports survive between calls.
+
+**Recursive LLM Calls**: Inside the REPL, `llm_query(prompt, context="")` invokes the language model on a sub-prompt. Use it in loops to analyze chunks of large content:
+```python
+# Example: analyze each file in a list
+results = []
+for filename in filenames:
+    with open(filename) as f:
+        content = f.read()
+    summary = llm_query("Summarize the key purpose of this code", content)
+    results.append(f"{filename}: {summary}")
+```
+
+**Externalized Context**: When your input is very large, it may be stored as the `context` variable in the REPL. Use `print(context[:1000])` to examine it, slice it, and process chunks with llm_query().
+
+**Handle Retrieval**: When a tool output is too large for context, it's stored as a handle. Access it via `data = retrieve('handle_id')` in the REPL.
+
+**Output Construction**: For very long outputs, build the result as a REPL variable and return it with FINAL_VAR(variable_name) instead of autoregressive generation.
+
+**Provenance**: Based on "Recursive Language Models" (Zhang, Kraska, Khattab — MIT CSAIL, arxiv:2512.24601) and Project COHERE Layer 2 architecture.