@nifrajs/agent 3.5.0 → 4.0.0

package/src/deployment.ts

@@ -452,6 +452,8 @@ export class AgentDeployment {
   private handleRef: string | undefined
   private report: DeploymentCapabilityReport | undefined
   private readonly evidence: DeploymentEvidence[] = []
+  private queue: Promise<unknown> = Promise.resolve()
+  private starting: AbortController | undefined
 
   constructor(
     private readonly adapter: AgentDeploymentAdapter,
@@ -486,13 +488,25 @@ export class AgentDeployment {
     }
   }
 
-  async prepare(planInput: AgentDeploymentPlan | unknown): Promise<DeploymentPrepareResult> {
+  prepare(planInput: AgentDeploymentPlan | unknown): Promise<DeploymentPrepareResult> {
+    return this.serial(() => this.prepareNow(planInput))
+  }
+
+  private async prepareNow(planInput: unknown): Promise<DeploymentPrepareResult> {
     if (this.state !== "new") return this.fail("invalid_transition")
-    const plan = parseDeploymentPlan(planInput)
+    let plan: AgentDeploymentPlan
+    try {
+      plan = parseDeploymentPlan(planInput)
+    } catch (error) {
+      return this.fail(asDeploymentError(error, "invalid_plan").code)
+    }
     this.deploymentId = plan.deploymentId
     if (this.signal.aborted) return this.fail("cancelled")
-    const report = await this.capabilityReport()
-    assertCapabilityPlan(report, plan, this.authority, this.approved)
+    try {
+      assertCapabilityPlan(await this.capabilityReport(), plan, this.authority, this.approved)
+    } catch (error) {
+      return this.fail(asDeploymentError(error, "invalid_capabilities").code)
+    }
     try {
       const result = parsePrepare(
         await this.adapter.prepare({ plan, authority: this.authority, signal: this.signal }),
@@ -507,7 +521,11 @@ export class AgentDeployment {
     }
   }
 
-  async start(): Promise<DeploymentStartResult> {
+  start(): Promise<DeploymentStartResult> {
+    return this.serial(() => this.startNow())
+  }
+
+  private async startNow(): Promise<DeploymentStartResult> {
     if (
       this.state !== "prepared" ||
       this.preparedRef === undefined ||
@@ -515,13 +533,15 @@ export class AgentDeployment {
     )
       return this.fail("invalid_transition")
     if (this.signal.aborted) return this.fail("cancelled")
+    const starting = new AbortController()
+    this.starting = starting
     try {
       const result = parseStart(
         await this.adapter.start({
           deploymentId: this.deploymentId,
           preparedRef: this.preparedRef,
           authority: this.authority,
-          signal: this.signal,
+          signal: AbortSignal.any([this.signal, starting.signal]),
         }),
         this.deploymentId,
       )
@@ -530,11 +550,18 @@ export class AgentDeployment {
       this.evidence.push({ kind: "started", deploymentId: this.deploymentId, state: "running" })
       return result
     } catch (error) {
+      if (starting.signal.aborted) return this.fail("cancelled")
       return this.fail(asDeploymentError(error, "adapter_error").code)
+    } finally {
+      this.starting = undefined
     }
   }
 
-  async inspect(): Promise<DeploymentInspection> {
+  inspect(): Promise<DeploymentInspection> {
+    return this.serial(() => this.inspectNow())
+  }
+
+  private async inspectNow(): Promise<DeploymentInspection> {
     if (this.state === "new" || this.state === "disposed" || this.deploymentId === undefined)
       return this.fail("invalid_transition")
     try {
@@ -557,7 +584,16 @@ export class AgentDeployment {
     }
   }
 
-  async cancel(): Promise<DeploymentCancelResult> {
+  /**
+   * Cancel the deployment. A start still in flight is asked to stop through its signal, and the
+   * cancel runs once it settles, against the workload it left running, if any.
+   */
+  cancel(): Promise<DeploymentCancelResult> {
+    this.starting?.abort()
+    return this.serial(() => this.cancelNow())
+  }
+
+  private async cancelNow(): Promise<DeploymentCancelResult> {
     if ((this.state !== "prepared" && this.state !== "running") || this.deploymentId === undefined)
       return this.fail("invalid_transition")
     try {
@@ -579,7 +615,13 @@ export class AgentDeployment {
     }
   }
 
-  async dispose(): Promise<DeploymentDisposeResult> {
+  /** Dispose of the deployment; like {@link cancel}, it first asks a start in flight to stop. */
+  dispose(): Promise<DeploymentDisposeResult> {
+    this.starting?.abort()
+    return this.serial(() => this.disposeNow())
+  }
+
+  private async disposeNow(): Promise<DeploymentDisposeResult> {
     if (this.state === "disposed")
       return { deploymentId: this.deploymentId ?? this.id, state: "disposed" }
     try {
@@ -605,6 +647,13 @@ export class AgentDeployment {
     }
   }
 
+  /** Lifecycle calls run one at a time, so each one sees the state the previous one left. */
+  private serial<T>(operation: () => Promise<T>): Promise<T> {
+    const run = this.queue.then(operation)
+    this.queue = run.catch(() => {})
+    return run
+  }
+
   private fail(code: DeploymentErrorCode): never {
     this.evidence.push({
       kind: "failed",

package/src/events.ts

@@ -123,8 +123,28 @@ export interface AgentEvidenceLog {
   ): AgentEvidenceReplay | undefined | Promise<AgentEvidenceReplay | undefined>
 }
 
+/**
+ * A view of `log` holding one owner's turns: every turn id is recorded and replayed under `owner`
+ * (the caller's user or tenant id), so another owner's reconnect or reused turn id finds none of
+ * them. The HTTP seams apply it per request through their `evidenceOwner` option.
+ */
+export function scopeAgentEvidenceLog(log: AgentEvidenceLog, owner: string): AgentEvidenceLog {
+  if (typeof owner !== "string" || owner === "")
+    throw new TypeError("agent evidence log: owner must be a non-empty string")
+  // Turn ids never contain "/", and the encoded owner never does either, so keys cannot collide.
+  const prefix = `${encodeURIComponent(owner)}/`
+  return {
+    open: (turnId) => log.open(prefix + turnId),
+    finish: (turnId, result) => log.finish(prefix + turnId, result),
+    replay: (turnId, afterSeq) => log.replay(prefix + turnId, afterSeq),
+  }
+}
+
 export interface MemoryAgentEvidenceLogOptions {
-  /** Maximum retained turns; the oldest turn is evicted when a new one opens. Default 256. */
+  /**
+   * Maximum retained turns. Opening one more evicts the oldest finished turn, or the oldest turn when
+   * none has finished; an evicted running turn ends its rejoined replays with no result. Default 256.
+   */
   readonly maxTurns?: number
 }
 
@@ -155,16 +175,33 @@ export function createMemoryAgentEvidenceLog(
       record.resolveResult = resolve
     })
   }
+  const settle = (turn: MemoryTurnRecord, result: unknown): void => {
+    turn.finished = true
+    turn.resolveResult(result)
+    for (const subscriber of turn.subscribers) subscriber.complete()
+    turn.subscribers.clear()
+  }
+  const evictOne = (): void => {
+    let victim: string | undefined
+    for (const [id, turn] of turns) {
+      if (turn.finished) {
+        victim = id
+        break
+      }
+    }
+    victim ??= turns.keys().next().value
+    if (victim === undefined) return
+    const turn = turns.get(victim)
+    turns.delete(victim)
+    // Its finish() can no longer find it by id, so a rejoined replay would wait forever.
+    if (turn !== undefined && !turn.finished) settle(turn, undefined)
+  }
 
   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)
-        }
+        while (turns.size >= maxTurns) evictOne()
         turn = {
           evidence: [],
           finished: false,
@@ -190,10 +227,7 @@ export function createMemoryAgentEvidenceLog(
     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()
+      settle(turn, result)
     },
     replay(turnId, afterSeq) {
       const turn = turns.get(turnId)

package/src/execution-policy.ts

@@ -10,6 +10,16 @@ import {
 export const LOCAL_PROCESS_LIMITATION = "The local adapter is NOT a security boundary."
 
 const SIGKILL_GRACE_MS = 2000
+/** How long the pipes may stay open after the escalation kill before the run stops reading them. */
+const PIPE_RELEASE_MS = 200
+/** The longest delay setTimeout honors; past it the callback fires at once. */
+const MAX_TIMER_MS = 2_147_483_647
+// On POSIX each run leads its own process group, so a timeout, a cancel, the run's own end, or the
+// host's exit ends every process the command started, not only the direct child.
+const WINDOWS = process.platform === "win32"
+const PROCESS_GROUPS = !WINDOWS
+const liveGroups = new Set<number>()
+let exitHookInstalled = false
 
 export interface LocalProcessAdapterOptions {
   readonly cwd?: string
@@ -159,11 +169,19 @@ function spawnProcess(input: SpawnInput): Promise<LocalProcessResult> {
         env: input.env,
         shell: false,
         stdio: ["ignore", "pipe", "pipe"],
+        detached: PROCESS_GROUPS,
       })
     } catch {
       reject(new LocalProcessPolicyError("invalid_request"))
       return
     }
+    const group = PROCESS_GROUPS ? child.pid : undefined
+    if (group !== undefined) trackGroup(group)
+    const signalAll = (signal: NodeJS.Signals): void => {
+      if (group !== undefined && signalGroup(group, signal)) return
+      if (WINDOWS && child.pid !== undefined && child.exitCode === null) windowsTreeKill(child.pid)
+      else child.kill(signal)
+    }
     const stdout: Uint8Array[] = []
     const stderr: Uint8Array[] = []
     let timedOut = false
@@ -178,23 +196,38 @@ function spawnProcess(input: SpawnInput): Promise<LocalProcessResult> {
       outputUsed.value += selected.byteLength
     }
     if (child.stdout === null || child.stderr === null) {
-      child.kill()
+      signalAll("SIGKILL")
+      if (group !== undefined) liveGroups.delete(group)
       reject(new LocalProcessPolicyError("invalid_request"))
       return
     }
     child.stdout.on("data", (chunk: Uint8Array) => append(stdout, chunk))
     child.stderr.on("data", (chunk: Uint8Array) => append(stderr, chunk))
     let killTimer: ReturnType<typeof setTimeout> | undefined
+    let releaseTimer: ReturnType<typeof setTimeout> | undefined
     const terminate = (): void => {
-      child.kill("SIGTERM")
-      // A child that ignores SIGTERM would otherwise leave this promise pending forever,
+      signalAll("SIGTERM")
+      // A process that ignores SIGTERM would otherwise leave this promise pending forever,
       // making policy.timeMs advisory instead of a bound.
-      killTimer ??= setTimeout(() => child.kill("SIGKILL"), SIGKILL_GRACE_MS)
+      killTimer ??= setTimeout(() => {
+        signalAll("SIGKILL")
+        // A process that left the group (setsid) can still hold the pipes open; stop waiting.
+        releaseTimer = setTimeout(() => settle(child.exitCode, child.signalCode), PIPE_RELEASE_MS)
+      }, SIGKILL_GRACE_MS)
     }
-    const timer = setTimeout(() => {
-      timedOut = true
-      terminate()
-    }, input.policy.timeMs)
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const deadline = performance.now() + input.policy.timeMs
+    const arm = (): void => {
+      const remaining = deadline - performance.now()
+      timer =
+        remaining > MAX_TIMER_MS
+          ? setTimeout(arm, MAX_TIMER_MS)
+          : setTimeout(() => {
+              timedOut = true
+              terminate()
+            }, remaining)
+    }
+    arm()
     const cancel = (): void => {
       cancelled = true
       terminate()
@@ -202,6 +235,8 @@ function spawnProcess(input: SpawnInput): Promise<LocalProcessResult> {
     const cleanup = (): void => {
       clearTimeout(timer)
       if (killTimer !== undefined) clearTimeout(killTimer)
+      if (releaseTimer !== undefined) clearTimeout(releaseTimer)
+      if (group !== undefined) liveGroups.delete(group)
       input.signal?.removeEventListener("abort", cancel)
     }
     child.once("error", () => {
@@ -210,10 +245,14 @@ function spawnProcess(input: SpawnInput): Promise<LocalProcessResult> {
       cleanup()
       reject(new LocalProcessPolicyError("invalid_request"))
     })
-    child.once("close", (exitCode, signal) => {
+    const settle = (exitCode: number | null, signal: NodeJS.Signals | null): void => {
       if (settled) return
       settled = true
+      // A background process the command left behind ends with the run.
+      if (group !== undefined) signalGroup(group, "SIGKILL")
       cleanup()
+      child.stdout?.destroy()
+      child.stderr?.destroy()
       resolve({
         ok: !timedOut && !cancelled && exitCode === 0,
         exitCode,
@@ -224,12 +263,53 @@ function spawnProcess(input: SpawnInput): Promise<LocalProcessResult> {
         cancelled,
         limitations: input.limitations,
       })
-    })
+    }
+    child.once("close", settle)
     input.signal?.addEventListener("abort", cancel, { once: true })
     if (input.signal?.aborted === true) cancel() // close the precheck/listener-registration race
   })
 }
 
+/**
+ * End a Windows process and its descendants. Windows has no process groups, and a console child
+ * cannot be asked to stop, so the tree is terminated outright.
+ */
+export function windowsTreeKill(
+  pid: number,
+  run: (
+    command: string,
+    args: readonly string[],
+    options: { stdio: "ignore"; windowsHide: boolean },
+  ) => { on(event: "error", listener: () => void): unknown } = spawn,
+): void {
+  try {
+    run("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }).on(
+      "error",
+      () => {},
+    )
+  } catch {}
+}
+
+/** Signal a run's whole process group; false when the group is already gone. */
+function signalGroup(group: number, signal: NodeJS.Signals): boolean {
+  try {
+    process.kill(-group, signal)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function trackGroup(group: number): void {
+  liveGroups.add(group)
+  if (exitHookInstalled) return
+  exitHookInstalled = true
+  // A detached group outlives the host unless something ends it; runs still in flight end with it.
+  process.on("exit", () => {
+    for (const live of liveGroups) signalGroup(live, "SIGKILL")
+  })
+}
+
 function concat(chunks: readonly Uint8Array[]): Uint8Array {
   const size = chunks.reduce((total, chunk) => total + chunk.byteLength, 0)
   const result = new Uint8Array(size)

package/src/index.ts

@@ -148,6 +148,8 @@ export interface AgentTurnState {
     readonly kind: AgentPendingKind
     readonly tool?: string
     readonly effectId: string
+    /** SHA-256 of the suspended tool input, so a resume must replay that input and no other. */
+    readonly inputDigest?: string
   }
 }
 
@@ -587,6 +589,9 @@ export async function turn<
         kind: pending.kind,
         ...(pending.tool === undefined ? {} : { tool: pending.tool }),
         effectId: pending.effectId,
+        ...(pending.tool !== undefined && Object.hasOwn(pending, "input")
+          ? { inputDigest: await inputDigestOf(pending.input) }
+          : {}),
       },
       evidence,
     })
@@ -960,6 +965,20 @@ async function resumeTool<
     reason: "approval" | "budget" | "model" | "cancelled",
   ) => Promise<AgentTurnResult<NonNullable<OutputSchema["~standard"]["types"]>["output"]>>,
 ): Promise<AgentTurnResult<NonNullable<OutputSchema["~standard"]["types"]>["output"]>> {
+  // A resume continues the step this turn suspended on - that tool, that effect, that input. The
+  // continuation travels through the caller, so anything else in it is refused, not run.
+  const pending = state.pending
+  const continuation = resume.continuation
+  if (
+    pending?.tool === undefined ||
+    continuation.tool !== pending.tool ||
+    continuation.effectId !== pending.effectId ||
+    continuation.kind !== pending.kind ||
+    (pending.inputDigest !== undefined &&
+      pending.inputDigest !== (await inputDigestOf(continuation.input)))
+  ) {
+    throw new AgentResumeMismatchError()
+  }
   const tool =
     resume.continuation.tool === undefined
       ? undefined
@@ -976,8 +995,10 @@ async function resumeTool<
       },
       save,
     )
+  // The caller's decision answers only a step that suspended to await one; a step suspended for budget
+  // or cancellation asks the approval port as it would have.
   const approvalPorts: AgentPorts =
-    resume.approval === undefined
+    resume.approval === undefined || pending.kind !== "approval"
       ? ports
       : {
           ...ports,
@@ -1084,6 +1105,31 @@ function withTranscript<Output>(
   }
 }
 
+/** A resume whose continuation is not the step the turn suspended on. */
+export class AgentResumeMismatchError extends Error {
+  override readonly name = "AgentResumeMismatchError"
+  constructor() {
+    super("agent: the resume does not continue the step this turn suspended on")
+  }
+}
+
+async function inputDigestOf(input: unknown): Promise<string> {
+  const bytes = new TextEncoder().encode(canonicalJson(input))
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))
+  return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("")
+}
+
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`
+  if (value !== null && typeof value === "object") {
+    const entries = Object.entries(value)
+      .filter(([, field]) => field !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    return `{${entries.map(([key, field]) => `${JSON.stringify(key)}:${canonicalJson(field)}`).join(",")}}`
+  }
+  return JSON.stringify(value) ?? "null"
+}
+
 function freezeState(state: AgentTurnState): AgentTurnState {
   return Object.freeze({
     ...state,

package/src/mount.ts

@@ -19,7 +19,9 @@
  *   evidence and rejoin the still-running turn (or receive the stored terminal frame) - the run is
  *   never re-executed. Without the log the header is ignored and every POST starts a run.
  * - The seam performs no authentication or authorization. Wrap it with the app's own route guards, and
- *   scope the store/model returned by `ports` to the caller (RLS born in at the data layer).
+ *   scope the store/model returned by `ports` to the caller (RLS born in at the data layer). With an
+ *   `evidenceLog`, set `evidenceOwner` too: without it a turn id is a bearer capability, and any
+ *   caller who reaches the route with it replays that turn's evidence.
  */
 
 import {
@@ -35,6 +37,7 @@ import {
   type AgentEvidenceLog,
   type AgentEvidenceReplay,
   createAgentEvidenceStream,
+  scopeAgentEvidenceLog,
 } from "./events.ts"
 import {
   type AgentDefinition,
@@ -52,6 +55,7 @@ const DEFAULT_PATH = "/agent"
 const DEFAULT_MAX_BODY_BYTES = 1_000_000
 const PENDING_KINDS: readonly AgentPendingKind[] = ["approval", "budget", "model", "cancelled"]
 const LAST_EVENT_ID_PATTERN = /^\d{1,15}$/
+const TURN_ID_PATTERN = /^[a-zA-Z0-9._:-]{1,128}$/
 
 /** The structural slice of a route context the seam needs. Kept loose so core stays a peer dependency. */
 export interface AgentRouteContext {
@@ -86,6 +90,12 @@ export interface MountAgentOptions<
    * (`createMemoryAgentEvidenceLog`) is single-process; a durable log is an adapter concern.
    */
   readonly evidenceLog?: AgentEvidenceLog
+  /**
+   * Who a turn's recorded evidence belongs to - the caller's user or tenant id. Turns are recorded and
+   * replayed under it, so a reconnect or a reused `turnId` from another caller finds nothing of this
+   * caller's turns. It runs before a replay is served; throw to refuse the request.
+   */
+  readonly evidenceOwner?: (c: AgentRouteContext) => string | Promise<string>
 }
 
 /** Mount a single agent as `POST {path}`, negotiating an SSE evidence stream on `Accept`. */
@@ -120,10 +130,15 @@ async function execute<InputSchema extends StandardSchemaV1, OutputSchema extend
   if (body === undefined) return jsonResponse(400, { error: "body_must_be_object" })
 
   const turnIdRaw = typeof body.turnId === "string" ? body.turnId : undefined
+  if (turnIdRaw !== undefined && !TURN_ID_PATTERN.test(turnIdRaw))
+    return jsonResponse(400, { error: "invalid_turn_id" })
   const turnId = turnIdRaw ?? crypto.randomUUID()
 
   const resume = parseResume(body.resume)
-  const log = options.evidenceLog
+  const log =
+    options.evidenceLog === undefined || options.evidenceOwner === undefined
+      ? options.evidenceLog
+      : scopeAgentEvidenceLog(options.evidenceLog, await options.evidenceOwner(c))
   const wantsSse = (c.req.headers.get("accept") ?? "").includes("text/event-stream")
 
   // A reconnect replays recorded evidence and rejoins the turn; it never starts a second run.
@@ -140,11 +155,17 @@ async function execute<InputSchema extends StandardSchemaV1, OutputSchema extend
 
   const start = (
     telemetry?: AgentPorts["telemetry"],
+    disconnect?: AbortSignal,
   ): Promise<AgentRunResult<NonNullable<OutputSchema["~standard"]["types"]>["output"]>> => {
     // Compose rather than replace: an SSE evidence stream must not displace a telemetry port the
     // caller injected through `ports` (an exporter, a durable evidence log).
     const combined = combineAgentTelemetry(basePorts.telemetry, log?.open(turnId), telemetry)
-    const ports = combined === undefined ? basePorts : { ...basePorts, telemetry: combined }
+    const signal = withDisconnect(basePorts.signal, disconnect)
+    const ports = {
+      ...basePorts,
+      ...(combined === undefined ? {} : { telemetry: combined }),
+      ...(signal === undefined ? {} : { signal }),
+    }
     if (resume !== undefined) {
       return resumeAgent(options.agent, turnId, { value: body.input, resume }, ports, runOptions)
     }
@@ -174,16 +195,26 @@ async function execute<InputSchema extends StandardSchemaV1, OutputSchema extend
 
 function sseResponse<Output>(
   turnId: string,
-  start: (telemetry: AgentPorts["telemetry"]) => Promise<AgentRunResult<Output>>,
+  start: (
+    telemetry: AgentPorts["telemetry"],
+    disconnect: AbortSignal | undefined,
+  ) => Promise<AgentRunResult<Output>>,
   log: AgentEvidenceLog | undefined,
 ): Response {
   const stream = createAgentEvidenceStream()
   // `id:` frames are only meaningful when a log can serve the reconnect they invite.
   const withIds = log !== undefined
+  // A disconnect detaches the client. With a log the run keeps recording for a reconnect to replay;
+  // without one nothing can rejoin it, so the run is cancelled.
+  const disconnect = log === undefined ? new AbortController() : undefined
+  let detached = false
   const body = new ReadableStream<Uint8Array>({
     async start(controller) {
-      const send = sseSender(controller)
-      const run = start(stream)
+      const deliver = sseSender(controller)
+      const send: typeof deliver = (event, data, id) => {
+        if (!detached) deliver(event, data, id)
+      }
+      const run = start(stream, disconnect?.signal)
       // The evidence stream must terminate whether the run resolves or throws, or the `for await`
       // below would hang; the run result (or the error) is still reported in-band after it drains.
       run
@@ -204,13 +235,25 @@ function sseResponse<Output>(
         await finishQuietly(log, turnId, frame)
         send(frame.event, frame.data)
       } finally {
-        controller.close()
+        if (!detached) controller.close()
       }
     },
+    cancel() {
+      detached = true
+      disconnect?.abort()
+    },
   })
   return sseHeaders(body)
 }
 
+function withDisconnect(
+  signal: AbortSignal | undefined,
+  disconnect: AbortSignal | undefined,
+): AbortSignal | undefined {
+  if (signal === undefined || disconnect === undefined) return signal ?? disconnect
+  return AbortSignal.any([signal, disconnect])
+}
+
 function sseReplayResponse(turnId: string, replay: AgentEvidenceReplay): Response {
   const body = new ReadableStream<Uint8Array>({
     async start(controller) {