@purista/harness 1.2.6 → 1.5.0

package/dist/tools/mcp/stdio.d.ts

@@ -1,2 +1,8 @@
 import type { McpTransportRunner, ResolvedMcpStdioTool } from './runner.js';
-export declare function createStdioMcpTransportRunner(config: ResolvedMcpStdioTool): McpTransportRunner;
+export interface StdioRunnerHooks {
+    /** Invoked whenever the persistent server process is discarded (exit, handshake failure, close). */
+    onReset?: () => void;
+    /** Grace period before SIGKILL escalation on close (test override). */
+    closeGraceMs?: number;
+}
+export declare function createStdioMcpTransportRunner(config: ResolvedMcpStdioTool, hooks?: StdioRunnerHooks): McpTransportRunner;

package/dist/tools/mcp/stdio.js

@@ -3,12 +3,16 @@ import { isSpawnCapableSession } from '../../sandbox/index.js';
 import { HARNESS_VERSION } from '../../version.js';
 import { withMcpTimeout } from './runner.js';
 const protocolVersion = '2025-06-18';
-export function createStdioMcpTransportRunner(config) {
+/** Maximum number of recent stderr characters retained to enrich failure messages. */
+const STDERR_TAIL_LIMIT = 8_192;
+/** How long `close()` waits for a SIGTERM'd server before escalating to SIGKILL. */
+const DEFAULT_CLOSE_GRACE_MS = 2_000;
+export function createStdioMcpTransportRunner(config, hooks = {}) {
     // A spawn-capable sandbox hosts a single long-lived server multiplexed across
     // calls (server-side state is preserved); otherwise each call is a one-shot
     // exec exchange (leak-free but stateless). See spec 07.
     if (isSpawnCapableSession(config.sandbox)) {
-        return createPersistentStdioRunner(config, config.sandbox);
+        return createPersistentStdioRunner(config, config.sandbox, hooks);
     }
     return createOneShotStdioRunner(config);
 }
@@ -17,7 +21,15 @@ function createOneShotStdioRunner(config) {
     async function ensureInstalled(signal) {
         if (!config.install)
             return;
-        installPromise ??= runInstall(config, signal);
+        if (!installPromise) {
+            const promise = runInstall(config, signal);
+            // A transient/aborted install failure must not poison later calls.
+            void promise.catch(() => {
+                if (installPromise === promise)
+                    installPromise = undefined;
+            });
+            installPromise = promise;
+        }
         return installPromise;
     }
     return {
@@ -49,16 +61,26 @@ function createOneShotStdioRunner(config) {
  * `initialize` handshake a single time, and multiplexes every subsequent
  * request over the same pipe correlating responses by JSON-RPC id.
  */
-function createPersistentStdioRunner(config, session) {
+function createPersistentStdioRunner(config, session, hooks = {}) {
     let installPromise;
-    let session_proc;
+    let serverProcess;
     let readyPromise;
+    let stderrTail = '';
     let nextId = 1;
     const pending = new Map();
+    const closeGraceMs = hooks.closeGraceMs ?? DEFAULT_CLOSE_GRACE_MS;
     async function ensureInstalled(signal) {
         if (!config.install)
             return;
-        installPromise ??= runInstall(config, signal);
+        if (!installPromise) {
+            const promise = runInstall(config, signal);
+            // A transient/aborted install failure must not poison later calls.
+            void promise.catch(() => {
+                if (installPromise === promise)
+                    installPromise = undefined;
+            });
+            installPromise = promise;
+        }
         return installPromise;
     }
     function rejectAllPending(error) {
@@ -67,8 +89,13 @@ function createPersistentStdioRunner(config, session) {
         pending.clear();
     }
     function teardown() {
-        session_proc = undefined;
+        serverProcess = undefined;
         readyPromise = undefined;
+        hooks.onReset?.();
+    }
+    function stderrSuffix() {
+        const tail = stderrTail.trim();
+        return tail ? ` stderr: ${tail}` : '';
     }
     async function spawnAndInitialize(signal) {
         const proc = await session.spawn(config.command, {
@@ -76,7 +103,8 @@ function createPersistentStdioRunner(config, session) {
             ...(config.env ? { env: config.env } : {}),
             ...(signal ? { signal } : {})
         });
-        session_proc = proc;
+        serverProcess = proc;
+        stderrTail = '';
         // Consume stdout line-by-line, dispatching responses to pending requests.
         void (async () => {
             let buffer = '';
@@ -97,19 +125,42 @@ function createPersistentStdioRunner(config, session) {
                 // stdout ended or aborted; exit handler performs cleanup.
             }
         })();
+        // Drain stderr so the child never blocks on a full pipe; keep only a small
+        // tail to enrich failure messages.
+        void (async () => {
+            try {
+                for await (const chunk of proc.stderr) {
+                    stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_LIMIT);
+                }
+            }
+            catch {
+                // stderr ended or aborted; exit handler performs cleanup.
+            }
+        })();
         // When the process exits, fail every in-flight request and force a respawn.
         void proc.exit.then((result) => {
-            rejectAllPending(mapStdioError(config, 'call', new Error(`MCP server exited with code ${result.exitCode}.`)));
-            if (session_proc === proc)
+            rejectAllPending(mapStdioError(config, 'call', new Error(`MCP server exited with code ${result.exitCode}.${stderrSuffix()}`)));
+            if (serverProcess === proc)
                 teardown();
         });
-        await writeMessage(proc, {
-            jsonrpc: '2.0',
-            id: 0,
-            method: 'initialize',
-            params: { protocolVersion, capabilities: {}, clientInfo: { name: '@purista/harness', version: HARNESS_VERSION } }
-        }, pending, 0, signal);
-        await proc.writeStdin(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} })}\n`);
+        try {
+            const initResponse = await writeMessage(proc, {
+                jsonrpc: '2.0',
+                id: 0,
+                method: 'initialize',
+                params: { protocolVersion, capabilities: {}, clientInfo: { name: '@purista/harness', version: HARNESS_VERSION } }
+            }, pending, 0, signal);
+            if (initResponse.error) {
+                throw mapStdioError(config, 'connect', new Error(initResponse.error.message ?? 'MCP initialize failed.'));
+            }
+            await proc.writeStdin(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} })}\n`);
+        }
+        catch (error) {
+            // Never leave an orphaned server behind a failed handshake.
+            pending.delete(0);
+            await terminateProcess(proc, closeGraceMs);
+            throw error;
+        }
     }
     async function ensureReady(signal) {
         await ensureInstalled(signal);
@@ -120,9 +171,9 @@ function createPersistentStdioRunner(config, session) {
             });
         }
         await readyPromise;
-        if (!session_proc)
+        if (!serverProcess)
             throw mapStdioError(config, 'connect', new Error('MCP server is not running.'));
-        return session_proc;
+        return serverProcess;
     }
     async function request(method, params, phase, map, options) {
         return withMcpTimeout({ ...(options?.signal ? { signal: options.signal } : {}), timeoutMs: options?.timeoutMs ?? config.timeoutMs, scope: 'tool' }, async (signal) => {
@@ -156,15 +207,33 @@ function createPersistentStdioRunner(config, session) {
             return request('tools/call', { name, arguments: input }, 'call', (value) => value, options);
         },
         async close() {
-            const proc = session_proc;
+            const proc = serverProcess;
             teardown();
             installPromise = undefined;
             rejectAllPending(mapStdioError(config, 'call', new Error('MCP runner closed.')));
             if (proc)
-                await proc.kill('SIGTERM').catch(() => undefined);
+                await terminateProcess(proc, closeGraceMs);
         }
     };
 }
+/** SIGTERMs a server process and escalates to SIGKILL when it ignores the grace window. */
+async function terminateProcess(proc, graceMs) {
+    await proc.kill('SIGTERM').catch(() => undefined);
+    let timer;
+    const exited = await Promise.race([
+        proc.exit.then(() => true),
+        new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), graceMs);
+            timer.unref?.();
+        })
+    ]);
+    if (timer)
+        clearTimeout(timer);
+    if (!exited) {
+        await proc.kill('SIGKILL').catch(() => undefined);
+        await proc.exit;
+    }
+}
 /** Sends one JSON-RPC message and (when `id` is set) awaits the correlated response. */
 async function writeMessage(proc, message, pending, id, signal) {
     const response = new Promise((resolve, reject) => {
@@ -180,7 +249,16 @@ async function writeMessage(proc, message, pending, id, signal) {
                 signal.addEventListener('abort', onAbort, { once: true });
         }
     });
-    await proc.writeStdin(`${JSON.stringify(message)}\n`);
+    try {
+        await proc.writeStdin(`${JSON.stringify(message)}\n`);
+    }
+    catch (error) {
+        // Drop the orphaned pending entry and mark its promise handled so a later
+        // rejectAllPending/abort cannot surface an unhandled rejection.
+        pending.delete(id);
+        void response.catch(() => undefined);
+        throw error;
+    }
     return response;
 }
 function dispatchLine(line, pending) {
@@ -250,8 +328,9 @@ async function exchange(config, calls, signal, timeoutMs) {
         return parseResponses(result.stdout);
     }
     catch (error) {
+        // Timeouts propagate unwrapped — consistent with the persistent runner.
         if (error instanceof OperationTimeoutError)
-            throw mapStdioError(config, calls[0]?.method === 'tools/list' ? 'list' : 'call', error);
+            throw error;
         throw mapStdioError(config, calls[0]?.method === 'tools/list' ? 'list' : 'call', error);
     }
 }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Harness package version, used as the OpenTelemetry instrumentation scope version. */
-export declare const HARNESS_VERSION = "0.0.0";
+export declare const HARNESS_VERSION = "1.5.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Harness package version, used as the OpenTelemetry instrumentation scope version. */
-export const HARNESS_VERSION = '0.0.0';
+export const HARNESS_VERSION = '1.5.0';

package/dist/workspace/in-memory.d.ts

@@ -28,6 +28,7 @@ export declare class InMemoryDurableWorkspaceStore implements DurableWorkspaceSt
     private toHandle;
     private isExpired;
     private findWorkspaceByCheckpoint;
+    private evictWorkspaceOps;
     private requireLiveWorkspace;
 }
 /** Creates a fresh in-process durable workspace store. */

package/dist/workspace/in-memory.js

@@ -79,8 +79,10 @@ export class InMemoryDurableWorkspaceStore {
     async pauseWorkspace(opts) {
         throwIfAborted(opts.signal);
         const replay = this.opResults.get(opts.idempotencyKey);
-        if (replay)
-            return replay;
+        if (replay) {
+            assertReplayMatches(replay, 'pause', opts.handle.runId, opts.handle.sessionId);
+            return replay.result;
+        }
         const workspace = this.requireLiveWorkspace(opts.handle.workspaceRef);
         const payloadBytes = opts.checkpointPayload === undefined ? 0 : byteLength(opts.checkpointPayload);
         if (payloadBytes > QUOTA.maxCheckpointPayloadBytes) {
@@ -121,14 +123,16 @@ export class InMemoryDurableWorkspaceStore {
             }
         };
         workspace.checkpoints.push(checkpoint);
-        this.opResults.set(opts.idempotencyKey, checkpoint);
+        this.opResults.set(opts.idempotencyKey, { kind: 'pause', runId: opts.handle.runId, sessionId: opts.handle.sessionId, workspaceRef: workspace.workspaceRef, result: checkpoint });
         return checkpoint;
     }
     async resumeWorkspace(opts) {
         throwIfAborted(opts.signal);
         const replay = this.opResults.get(opts.idempotencyKey);
-        if (replay)
-            return replay;
+        if (replay) {
+            assertReplayMatches(replay, 'resume', opts.runId, opts.sessionId);
+            return replay.result;
+        }
         const workspace = this.workspaces.get(opts.workspaceRef);
         if (!workspace || workspace.state === 'cleaned') {
             throw new WorkspaceError('Workspace not found.', { reason: 'not_found', workspace_ref: opts.workspaceRef });
@@ -148,14 +152,16 @@ export class InMemoryDurableWorkspaceStore {
         workspace.attempt = opts.attempt;
         workspace.updatedAt = new Date().toISOString();
         const handle = this.toHandle(workspace);
-        this.opResults.set(opts.idempotencyKey, handle);
+        this.opResults.set(opts.idempotencyKey, { kind: 'resume', runId: opts.runId, sessionId: opts.sessionId, workspaceRef: workspace.workspaceRef, result: handle });
         return handle;
     }
     async abortWorkspace(opts) {
         throwIfAborted(opts.signal);
         const replay = this.opResults.get(opts.idempotencyKey);
-        if (replay)
-            return replay;
+        if (replay) {
+            assertReplayMatches(replay, 'abort', opts.runId, opts.sessionId);
+            return replay.result;
+        }
         const workspace = this.workspaces.get(opts.workspaceRef);
         if (!workspace || workspace.state === 'cleaned') {
             throw new WorkspaceError('Workspace not found.', { reason: 'not_found', workspace_ref: opts.workspaceRef });
@@ -165,31 +171,35 @@ export class InMemoryDurableWorkspaceStore {
         workspace.updatedAt = abortedAt;
         const cleanupEligibleAt = expiryFor('aborted', abortedAt);
         const result = { workspaceRef: opts.workspaceRef, state: 'aborted', abortedAt, ...(cleanupEligibleAt ? { cleanupEligibleAt } : {}) };
-        this.opResults.set(opts.idempotencyKey, result);
+        this.opResults.set(opts.idempotencyKey, { kind: 'abort', runId: opts.runId, sessionId: opts.sessionId, workspaceRef: opts.workspaceRef, result });
         return result;
     }
     async cleanupWorkspace(opts) {
         throwIfAborted(opts.signal);
         const replay = this.opResults.get(opts.idempotencyKey);
         if (replay)
-            return replay;
+            return replay.result;
         const workspace = this.workspaces.get(opts.workspaceRef);
         const completedAt = new Date().toISOString();
         // Cleanup is idempotent: an already-cleaned (or unknown) workspace returns a
         // terminal cleaned result rather than throwing.
         if (!workspace || workspace.state === 'cleaned') {
             const result = { workspaceRef: opts.workspaceRef, state: 'cleaned', completedAt, deletedBytes: 0, deletedFiles: 0 };
-            this.opResults.set(opts.idempotencyKey, result);
+            this.opResults.set(opts.idempotencyKey, { kind: 'cleanup', runId: workspace?.runId ?? '', sessionId: workspace?.sessionId ?? '', workspaceRef: opts.workspaceRef, result });
             return result;
         }
         const deletedBytes = workspace.bytes;
         const deletedFiles = workspace.checkpoints.length;
+        const { runId, sessionId } = workspace;
         workspace.state = 'cleaned';
         workspace.updatedAt = completedAt;
         workspace.checkpoints = [];
         workspace.bytes = 0;
+        // A cleaned workspace keeps only its slim terminal record; idempotency
+        // entries referencing it are evicted so the store does not grow unbounded.
+        this.evictWorkspaceOps(opts.workspaceRef);
         const result = { workspaceRef: opts.workspaceRef, state: 'cleaned', completedAt, deletedBytes, deletedFiles };
-        this.opResults.set(opts.idempotencyKey, result);
+        this.opResults.set(opts.idempotencyKey, { kind: 'cleanup', runId, sessionId, workspaceRef: opts.workspaceRef, result });
         return result;
     }
     async inspectWorkspace(opts) {
@@ -239,6 +249,16 @@ export class InMemoryDurableWorkspaceStore {
         }
         return found.workspaceRef;
     }
+    evictWorkspaceOps(workspaceRef) {
+        for (const [key, entry] of this.startKeys) {
+            if (entry.workspaceRef === workspaceRef)
+                this.startKeys.delete(key);
+        }
+        for (const [key, value] of this.opResults) {
+            if (value.workspaceRef === workspaceRef)
+                this.opResults.delete(key);
+        }
+    }
     requireLiveWorkspace(workspaceRef) {
         const workspace = this.workspaces.get(workspaceRef);
         if (!workspace || workspace.state === 'cleaned') {
@@ -250,6 +270,21 @@ export class InMemoryDurableWorkspaceStore {
         return workspace;
     }
 }
+/**
+ * Guards a persisted-op replay: a stored entry may only replay when it belongs
+ * to the same operation kind and run/session identity, otherwise the reused key
+ * is an `idempotency_conflict` (spec 21 §9).
+ */
+function assertReplayMatches(op, kind, runId, sessionId) {
+    if (op.kind !== kind || op.runId !== runId || op.sessionId !== sessionId) {
+        throw new WorkspaceError(`Workspace ${kind} idempotency key reused with a different operation or run/session.`, {
+            reason: 'idempotency_conflict',
+            workspace_ref: op.workspaceRef,
+            run_id: runId,
+            session_id: sessionId
+        });
+    }
+}
 function throwIfAborted(signal) {
     if (signal?.aborted) {
         throw new OperationCancelledError('Workspace operation was cancelled.', { scope: 'workspace' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purista/harness",
-  "version": "1.2.6",
+  "version": "1.5.0",
   "description": "Self-hosted enterprise agent harness for typed tools, agents, workflows, state, sandboxing, and telemetry.",
   "type": "module",
   "main": "dist/index.js",
@@ -71,6 +71,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opentelemetry/context-async-hooks": "^2.7.1",
     "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "^4.1.8",
     "just-bash": "^3.0.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.8"