@nifrajs/agent 3.1.0 → 3.3.0

package/src/events.ts

@@ -83,3 +83,128 @@ export function createAgentEvidenceStream(
   }
   return stream
 }
+
+// ---------------------------------------------------------------------------
+// Resumable evidence log
+// ---------------------------------------------------------------------------
+
+/** One turn's replayable evidence view - see {@link AgentEvidenceLog.replay}. */
+export interface AgentEvidenceReplay {
+  /** Evidence already recorded with `seq` greater than the requested cursor, in order. */
+  readonly evidence: readonly AgentStepEvidence[]
+  /** Live continuation while the turn is still running; `undefined` once it has finished. */
+  readonly live: AgentEvidenceStream | undefined
+  /** Resolves with the value passed to {@link AgentEvidenceLog.finish} when the turn ends. */
+  readonly result: Promise<unknown>
+}
+
+/**
+ * Seam for resumable evidence streams. An HTTP seam records one turn's step evidence through
+ * `open`, stores the terminal wire frame through `finish`, and serves SSE reconnects through
+ * `replay` (`Last-Event-ID` maps to evidence `seq`). The stored result value is opaque to the log -
+ * each seam stores whatever it needs to re-emit its own terminal frames.
+ *
+ * {@link createMemoryAgentEvidenceLog} is the single-process dev/test reference; a durable,
+ * multi-process log is an adapter concern behind the same interface.
+ */
+export interface AgentEvidenceLog {
+  /**
+   * Telemetry port recording one turn's evidence - combine it into `ports.telemetry` with
+   * `combineAgentTelemetry`. Opening a finished turn reopens it (a resume of a suspended run):
+   * evidence keeps appending and late replays await the new result.
+   */
+  open(turnId: string): AgentTelemetryPort
+  /** Mark the turn finished: live replays complete and `result` is stored for late reconnects. */
+  finish(turnId: string, result: unknown): void | Promise<void>
+  /** The turn's evidence after `afterSeq`, or `undefined` for an unknown turn. */
+  replay(
+    turnId: string,
+    afterSeq: number,
+  ): AgentEvidenceReplay | undefined | Promise<AgentEvidenceReplay | undefined>
+}
+
+export interface MemoryAgentEvidenceLogOptions {
+  /** Maximum retained turns; the oldest turn is evicted when a new one opens. Default 256. */
+  readonly maxTurns?: number
+}
+
+interface MemoryTurnRecord {
+  readonly evidence: AgentStepEvidence[]
+  finished: boolean
+  resultPromise: Promise<unknown>
+  resolveResult: (value: unknown) => void
+  readonly subscribers: Set<AgentEvidenceStream>
+}
+
+/**
+ * In-memory {@link AgentEvidenceLog} reference for local development and tests. Single-process by
+ * construction: replay only sees runs recorded by this instance. Retention is bounded by
+ * `maxTurns` with oldest-first eviction, so a reconnect to an evicted turn reports
+ * replay-unavailable rather than growing memory without bound.
+ */
+export function createMemoryAgentEvidenceLog(
+  options: MemoryAgentEvidenceLogOptions = {},
+): AgentEvidenceLog {
+  const maxTurns = options.maxTurns ?? 256
+  if (!Number.isSafeInteger(maxTurns) || maxTurns < 1)
+    throw new RangeError("agent evidence log: maxTurns must be a positive safe integer")
+  const turns = new Map<string, MemoryTurnRecord>()
+
+  const deferred = (record: MemoryTurnRecord): void => {
+    record.resultPromise = new Promise<unknown>((resolve) => {
+      record.resolveResult = resolve
+    })
+  }
+
+  return {
+    open(turnId) {
+      let turn = turns.get(turnId)
+      if (turn === undefined) {
+        while (turns.size >= maxTurns) {
+          const oldest = turns.keys().next().value
+          if (oldest === undefined) break
+          turns.delete(oldest)
+        }
+        turn = {
+          evidence: [],
+          finished: false,
+          resultPromise: Promise.resolve(undefined),
+          resolveResult: () => {},
+          subscribers: new Set(),
+        }
+        deferred(turn)
+        turns.set(turnId, turn)
+      } else if (turn.finished) {
+        // A resume reopens the turn: the next finish() resolves a fresh result for new replays.
+        turn.finished = false
+        deferred(turn)
+      }
+      const opened = turn
+      return {
+        step(evidence) {
+          opened.evidence.push(evidence)
+          for (const subscriber of opened.subscribers) subscriber.step(evidence)
+        },
+      }
+    },
+    finish(turnId, result) {
+      const turn = turns.get(turnId)
+      if (turn === undefined || turn.finished) return
+      turn.finished = true
+      turn.resolveResult(result)
+      for (const subscriber of turn.subscribers) subscriber.complete()
+      turn.subscribers.clear()
+    },
+    replay(turnId, afterSeq) {
+      const turn = turns.get(turnId)
+      if (turn === undefined) return undefined
+      const evidence = turn.evidence.filter((item) => item.seq > afterSeq)
+      if (turn.finished) return { evidence, live: undefined, result: turn.resultPromise }
+      // Snapshot and subscribe in the same synchronous step, so no evidence item can land between
+      // the filtered history and the live stream.
+      const live = createAgentEvidenceStream()
+      turn.subscribers.add(live)
+      return { evidence, live, result: turn.resultPromise }
+    },
+  }
+}

package/src/execution-policy.ts

@@ -199,19 +199,21 @@ function spawnProcess(input: SpawnInput): Promise<LocalProcessResult> {
       cancelled = true
       terminate()
     }
-    input.signal?.addEventListener("abort", cancel, { once: true })
+    const cleanup = (): void => {
+      clearTimeout(timer)
+      if (killTimer !== undefined) clearTimeout(killTimer)
+      input.signal?.removeEventListener("abort", cancel)
+    }
     child.once("error", () => {
       if (settled) return
       settled = true
-      clearTimeout(timer)
-      if (killTimer !== undefined) clearTimeout(killTimer)
+      cleanup()
       reject(new LocalProcessPolicyError("invalid_request"))
     })
     child.once("close", (exitCode, signal) => {
       if (settled) return
       settled = true
-      clearTimeout(timer)
-      if (killTimer !== undefined) clearTimeout(killTimer)
+      cleanup()
       resolve({
         ok: !timedOut && !cancelled && exitCode === 0,
         exitCode,
@@ -223,6 +225,8 @@ function spawnProcess(input: SpawnInput): Promise<LocalProcessResult> {
         limitations: input.limitations,
       })
     })
+    input.signal?.addEventListener("abort", cancel, { once: true })
+    if (input.signal?.aborted === true) cancel() // close the precheck/listener-registration race
   })
 }