@myagentroam/agent 0.9.107 → 0.9.108

package/dist/tools/exec.d.ts

@@ -30,6 +30,8 @@ export interface ExecResult {
     stderrBytes: number;
     stdoutDroppedBytes: number;
     stderrDroppedBytes: number;
+    /** A terminal snapshot replay rather than new process output. */
+    cached?: boolean;
 }
 export declare const execToolDefinition: ClientToolDefinition;
 export declare class ExecTool {

package/dist/tools/exec.js

@@ -6,7 +6,7 @@ import { TOOL_EXECUTION_LIMITS } from './execution-limits.js';
 export const execToolDefinition = {
     name: 'exec',
     parallelSafety: 'safe',
-    description: 'Unrestricted general system execution. Providing command starts any platform-native command, script, text/file tool, builder, generator, network client, or program in workspace/default cwd; action may be omitted for start. poll waits up to yieldMs for new output or termination and returns only output produced since the prior result; write sends stdin; cancel terminates the process tree. Returns status, processId, incremental stdout/stderr, cumulative stdoutBytes/stderrBytes, per-result dropped bytes, exitCode, and truncated; a completed status does not imply exitCode 0. Always inspect stderr/exitCode and consume terminal output or cancel.',
+    description: 'Unrestricted general system execution. Providing command starts any platform-native command, script, text/file tool, builder, generator, network client, or program in workspace/default cwd; action may be omitted for start. poll waits up to yieldMs for new output or termination and returns incremental output while running; after termination, poll returns a bounded cached result with earlier output for up to five minutes while the Session remains hosted. write sends stdin to running processes; cancel terminates a running process or removes a completed result. Returns status, processId, stdout/stderr, cumulative stdoutBytes/stderrBytes, per-result dropped bytes, exitCode, and truncated; a completed status does not imply exitCode 0. Always inspect stderr/exitCode and consume terminal output or cancel.',
     outputSchema: {
         type: 'object',
         required: ['content', 'data'],
@@ -34,7 +34,8 @@ export const execToolDefinition = {
                     stdoutBytes: { type: 'number' },
                     stderrBytes: { type: 'number' },
                     stdoutDroppedBytes: { type: 'number' },
-                    stderrDroppedBytes: { type: 'number' }
+                    stderrDroppedBytes: { type: 'number' },
+                    cached: { type: 'boolean' }
                 }
             }
         }
@@ -77,6 +78,7 @@ export class ExecTool {
     shell;
     processExecutor;
     #processes = new Map();
+    #completed = new Map();
     #startingProcesses = new Set();
     constructor(paths, maxOutputBytes = TOOL_EXECUTION_LIMITS.execDefaultMaxOutputBytes, maxProcesses = TOOL_EXECUTION_LIMITS.maxProcesses, environment = process.env, shell, processExecutor = directLocalProcessExecutor) {
         this.paths = paths;
@@ -92,6 +94,16 @@ export class ExecTool {
         const input = parseExecInput(arguments_);
         if ('processId' in input) {
             const process = this.#processes.get(input.processId);
+            const completed = this.#completed.get(input.processId);
+            if (completed) {
+                if (owner !== undefined && completed.ownerSessionId !== owner.sessionId)
+                    throw new MarAgentError('MAR_AGENT_PROCESS_NOT_FOUND', 'Managed process was not found.');
+                if (input.action === 'write')
+                    throw new MarAgentError('MAR_AGENT_TOOL_INPUT_INVALID', 'Completed process cannot accept input.');
+                if (input.action === 'cancel')
+                    this.#removeCompleted(input.processId);
+                return { ...completed.result, cached: true };
+            }
             if (!process || (owner !== undefined && process.ownerSessionId !== owner.sessionId))
                 throw new MarAgentError('MAR_AGENT_PROCESS_NOT_FOUND', 'Managed process was not found.');
             if (input.action === 'poll' && input.yieldMs)
@@ -101,8 +113,11 @@ export class ExecTool {
             if (input.action === 'cancel')
                 await this.#terminate(process, true);
             const result = this.#result(input.processId, process);
-            if (process.status !== 'running')
-                this.#processes.delete(input.processId);
+            if (process.status !== 'running') {
+                this.#retainCompleted(input.processId, process);
+                if (input.action === 'cancel')
+                    this.#removeCompleted(input.processId);
+            }
             return result;
         }
         if (this.#processes.size + this.#startingProcesses.size >= this.maxProcesses)
@@ -137,6 +152,8 @@ export class ExecTool {
                 cwd: cwd.displayPath,
                 stdout: createOutputBuffer(),
                 stderr: createOutputBuffer(),
+                stdoutHistory: createOutputBuffer(),
+                stderrHistory: createOutputBuffer(),
                 status: 'running',
                 exited: new Promise((resolve) => (resolveExited = resolve)),
                 settled: new Promise((resolve) => (resolveSettled = resolve)),
@@ -155,53 +172,65 @@ export class ExecTool {
         child.stdout.on('data', (chunk) => {
             if (managed.finalized)
                 return;
-            appendOutput(managed.stdout, Buffer.from(managed.stdout.decoder.write(chunk)), this.maxOutputBytes, chunk.length);
+            const decoded = Buffer.from(managed.stdout.decoder.write(chunk));
+            appendOutput(managed.stdout, decoded, this.maxOutputBytes, chunk.length);
+            appendOutput(managed.stdoutHistory, decoded, this.maxOutputBytes, chunk.length);
             notifyProcessChange(managed);
         });
         child.stderr.on('data', (chunk) => {
             if (managed.finalized)
                 return;
-            appendOutput(managed.stderr, Buffer.from(managed.stderr.decoder.write(chunk)), this.maxOutputBytes, chunk.length);
+            const decoded = Buffer.from(managed.stderr.decoder.write(chunk));
+            appendOutput(managed.stderr, decoded, this.maxOutputBytes, chunk.length);
+            appendOutput(managed.stderrHistory, decoded, this.maxOutputBytes, chunk.length);
             notifyProcessChange(managed);
         });
         child.once('exit', (code) => {
             managed.exitObserved = true;
             managed.exitCode = code;
             managed.resolveExited();
-            void finalizeAfterOutputGrace(managed, this.maxOutputBytes);
+            void finalizeAfterOutputGrace(managed, this.maxOutputBytes).then(() => this.#retainCompleted(id, managed));
         });
         child.once('close', (code) => {
             managed.exitObserved = true;
             managed.resolveExited();
             finalizeManagedProcess(managed, this.maxOutputBytes, code);
+            this.#retainCompleted(id, managed);
         });
         child.once('error', (error) => {
             if (managed.finalized)
                 return;
-            appendOutput(managed.stderr, Buffer.from(error.message), this.maxOutputBytes);
+            const message = Buffer.from(error.message);
+            appendOutput(managed.stderr, message, this.maxOutputBytes);
+            appendOutput(managed.stderrHistory, message, this.maxOutputBytes);
             notifyProcessChange(managed);
         });
         managed.timer = setTimeout(() => {
-            void this.#terminate(managed, true);
+            void this.#terminate(managed, true).then(() => this.#retainCompleted(id, managed));
         }, Math.min(input.timeoutMs ?? TOOL_EXECUTION_LIMITS.execDefaultTimeoutMs, TOOL_EXECUTION_LIMITS.execMaxTimeoutMs));
         managed.timer.unref();
         await waitForExitOrDelay(managed.settled, Math.min(input.yieldMs ?? TOOL_EXECUTION_LIMITS.execDefaultYieldMs, TOOL_EXECUTION_LIMITS.execMaxYieldMs), signal);
         const result = this.#result(id, managed);
         if (managed.status !== 'running')
-            this.#processes.delete(id);
+            this.#retainCompleted(id, managed);
         return result;
     }
     listSessionResources(sessionId) {
-        return [...this.#processes.entries()].flatMap(([processId, process]) => process.ownerSessionId === sessionId
-            ? [
-                {
-                    processId,
-                    status: process.status,
-                    command: process.command,
-                    cwd: process.cwd
-                }
-            ]
-            : []);
+        return [
+            ...[...this.#processes.entries()].flatMap(([processId, process]) => process.ownerSessionId === sessionId
+                ? [{ processId, status: process.status, command: process.command, cwd: process.cwd }]
+                : []),
+            ...[...this.#completed.entries()].flatMap(([processId, process]) => process.ownerSessionId === sessionId
+                ? [
+                    {
+                        processId,
+                        status: process.result.status,
+                        command: process.command,
+                        cwd: process.cwd
+                    }
+                ]
+                : [])
+        ];
     }
     async disposeSession(sessionId) {
         await Promise.all([...this.#startingProcesses]
@@ -211,6 +240,45 @@ export class ExecTool {
         await Promise.all(owned.map(([, process]) => process.status === 'running' ? this.#terminate(process, false) : process.settled));
         for (const [processId] of owned)
             this.#processes.delete(processId);
+        for (const [processId, process] of this.#completed)
+            if (process.ownerSessionId === sessionId)
+                this.#removeCompleted(processId);
+    }
+    #removeCompleted(id) {
+        const completed = this.#completed.get(id);
+        if (!completed)
+            return;
+        clearTimeout(completed.timer);
+        this.#completed.delete(id);
+    }
+    #retainCompleted(id, process) {
+        if (process.status === 'running' || !process.finalized || this.#processes.get(id) !== process)
+            return;
+        this.#processes.delete(id);
+        const stdout = consumeOutput(process.stdoutHistory);
+        const stderr = consumeOutput(process.stderrHistory);
+        const timer = setTimeout(() => this.#removeCompleted(id), TOOL_EXECUTION_LIMITS.execCompletedRetentionMs);
+        timer.unref();
+        this.#completed.set(id, {
+            ...(process.ownerSessionId === undefined ? {} : { ownerSessionId: process.ownerSessionId }),
+            command: process.command,
+            cwd: process.cwd,
+            timer,
+            result: {
+                status: process.status,
+                processId: id,
+                stdout: stdout.value,
+                stderr: stderr.value,
+                ...(process.exitCode === undefined ? {} : { exitCode: process.exitCode }),
+                truncated: stdout.droppedBytes > 0 || stderr.droppedBytes > 0,
+                stdoutBytes: process.stdout.totalBytes,
+                stderrBytes: process.stderr.totalBytes,
+                stdoutDroppedBytes: stdout.droppedBytes,
+                stderrDroppedBytes: stderr.droppedBytes
+            }
+        });
+        while (this.#completed.size > TOOL_EXECUTION_LIMITS.execMaxCompletedResults)
+            this.#removeCompleted(this.#completed.keys().next().value);
     }
     async #terminate(managed, waitForOutputClose) {
         if (managed.terminate)
@@ -252,7 +320,7 @@ export class ExecTool {
         const stderr = consumeOutput(process.stderr);
         return {
             status: process.status,
-            ...(process.status === 'running' ? { processId: id } : {}),
+            processId: id,
             stdout: stdout.value,
             stderr: stderr.value,
             ...(process.exitCode === undefined ? {} : { exitCode: process.exitCode }),
@@ -267,6 +335,8 @@ export class ExecTool {
         await Promise.all([...this.#startingProcesses].map((process) => process.settled));
         await Promise.all([...this.#processes.values()].map((process) => process.status === 'running' ? this.#terminate(process, false) : process.settled));
         this.#processes.clear();
+        for (const id of this.#completed.keys())
+            this.#removeCompleted(id);
     }
 }
 function createOutputBuffer() {
@@ -283,8 +353,12 @@ function finalizeManagedProcess(managed, maximumOutputBytes, exitCode) {
     if (managed.finalized)
         return;
     managed.finalized = true;
-    appendOutput(managed.stdout, Buffer.from(managed.stdout.decoder.end()), maximumOutputBytes);
-    appendOutput(managed.stderr, Buffer.from(managed.stderr.decoder.end()), maximumOutputBytes);
+    const stdoutEnd = Buffer.from(managed.stdout.decoder.end());
+    const stderrEnd = Buffer.from(managed.stderr.decoder.end());
+    appendOutput(managed.stdout, stdoutEnd, maximumOutputBytes);
+    appendOutput(managed.stderr, stderrEnd, maximumOutputBytes);
+    appendOutput(managed.stdoutHistory, stdoutEnd, maximumOutputBytes);
+    appendOutput(managed.stderrHistory, stderrEnd, maximumOutputBytes);
     managed.status = managed.status === 'cancelled' ? 'cancelled' : 'completed';
     if (exitCode !== undefined)
         managed.exitCode = exitCode;

package/dist/tools/execution-limits.d.ts

@@ -13,6 +13,8 @@ export declare const TOOL_EXECUTION_LIMITS: Readonly<{
     execTerminationGraceMs: 1000;
     execDefaultMaxOutputBytes: 1000000;
     maxProcesses: 8;
+    execMaxCompletedResults: 16;
+    execCompletedRetentionMs: 300000;
     codeMaxInputBytes: 1048576;
     codeMaxOutputBytes: 1048576;
     codeMaxFrameBytes: 33554432;

package/dist/tools/execution-limits.js

@@ -13,6 +13,8 @@ export const TOOL_EXECUTION_LIMITS = Object.freeze({
     execTerminationGraceMs: 1_000,
     execDefaultMaxOutputBytes: 1_000_000,
     maxProcesses: 8,
+    execMaxCompletedResults: 16,
+    execCompletedRetentionMs: 300_000,
     codeMaxInputBytes: 1_048_576,
     codeMaxOutputBytes: 1_048_576,
     codeMaxFrameBytes: 33_554_432,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/agent",
-  "version": "0.9.107",
+  "version": "0.9.108",
   "description": "Embeddable MAR coding agent SDK and CLI.",
   "license": "Apache-2.0",
   "type": "module",