@nifrajs/coding-agent 5.0.0 → 5.1.0

package/src/approvals.ts

@@ -21,9 +21,44 @@ export interface ApprovalRequest {
    */
   readonly coordinate?: DecisionCoordinate
   readonly createdAt: number
+  /**
+   * Absolute epoch-ms after which the approval is denied as timed out. An approval opened with a
+   * `"never"` timeout reports {@link APPROVAL_NEVER_EXPIRES_AT}, so `now < expiresAt` keeps treating
+   * it as live.
+   */
   readonly expiresAt: number
 }
 
+/**
+ * How long an approval may wait: whole milliseconds from 1 ms to 24 h, or `"never"` for no timer. A
+ * `"never"` approval still settles on an answer, a cancel, the end of its turn, and close.
+ */
+export type ApprovalTimeout = number | "never"
+
+/**
+ * The `expiresAt` of an approval that never times out: the largest epoch-ms a `Date` holds
+ * (+275760-09-13). It survives JSON, unlike `Infinity`, and `new Date(expiresAt)` stays valid.
+ */
+export const APPROVAL_NEVER_EXPIRES_AT = 8_640_000_000_000_000
+
+const DEFAULT_APPROVAL_TIMEOUT_MS = 5 * 60_000
+const MAX_APPROVAL_TIMEOUT_MS = 24 * 60 * 60_000
+
+/** True for `"never"` or a whole number of milliseconds from 1 ms to 24 h. */
+export function isApprovalTimeout(value: unknown): value is ApprovalTimeout {
+  return (
+    value === "never" ||
+    (typeof value === "number" &&
+      Number.isSafeInteger(value) &&
+      value >= 1 &&
+      value <= MAX_APPROVAL_TIMEOUT_MS)
+  )
+}
+
+function approvalExpiresAt(createdAt: number, timeoutMs: ApprovalTimeout): number {
+  return timeoutMs === "never" ? APPROVAL_NEVER_EXPIRES_AT : createdAt + timeoutMs
+}
+
 /** Stable, content-free reasons a coordinate-matched resolution is refused. */
 export type ApprovalMatchRejection =
   | "unknown_boundary"
@@ -45,7 +80,11 @@ export interface ApprovalDecision {
 
 export interface ApprovalManagerOptions {
   readonly maxPending?: number
-  readonly timeoutMs?: number
+  /**
+   * How long an approval waits before it is denied as timed out (default 5 minutes, at most 24 h).
+   * `"never"` removes the timer; `maxPending` still bounds how many approvals can wait.
+   */
+  readonly timeoutMs?: ApprovalTimeout
   readonly onRequired?: (request: ApprovalRequest) => void | PromiseLike<void>
   readonly onResolved?: (decision: ApprovalDecision) => void | PromiseLike<void>
 }
@@ -55,7 +94,7 @@ interface PendingApproval {
   /** Settles with the decision; it exists before `onRequired` runs, so no decision can miss it. */
   readonly decided: Promise<boolean>
   readonly settle: (approved: boolean) => void
-  readonly timer: ReturnType<typeof setTimeout>
+  readonly timer: ReturnType<typeof setTimeout> | undefined
 }
 
 /** The agent protocol's token alphabet, so every protocol-valid id is accepted here too. */
@@ -77,16 +116,17 @@ export class ApprovalManager {
     this.options = {
       ...options,
       maxPending: options.maxPending ?? 32,
-      timeoutMs: options.timeoutMs ?? 5 * 60_000,
+      timeoutMs: options.timeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS,
     }
     if (!Number.isSafeInteger(this.options.maxPending) || this.options.maxPending < 1)
       throw new RangeError("approvals: maxPending must be positive")
-    if (
-      !Number.isSafeInteger(this.options.timeoutMs) ||
-      this.options.timeoutMs < 1 ||
-      this.options.timeoutMs > 24 * 60 * 60_000
-    )
-      throw new RangeError("approvals: timeoutMs must be between 1ms and 24h")
+    if (!isApprovalTimeout(this.options.timeoutMs))
+      throw new RangeError('approvals: timeoutMs must be between 1ms and 24h, or "never"')
+  }
+
+  /** The configured timeout, for {@link approvalRequestFromEvent}. */
+  get timeoutMs(): ApprovalTimeout {
+    return this.options.timeoutMs
   }
 
   get pending(): readonly ApprovalRequest[] {
@@ -219,13 +259,17 @@ export class ApprovalManager {
       ...(input.reason === undefined ? {} : { reason: input.reason.slice(0, 512) }),
       ...(input.coordinate === undefined ? {} : { coordinate: input.coordinate }),
       createdAt,
-      expiresAt: createdAt + this.options.timeoutMs,
+      expiresAt: approvalExpiresAt(createdAt, this.options.timeoutMs),
     })
     const { promise: decided, resolve: settle } = Promise.withResolvers<boolean>()
-    const timer = setTimeout(() => {
-      this.settle(request.id, false, "approval timed out")
-    }, this.options.timeoutMs)
-    ;(timer as unknown as { unref?: () => void }).unref?.()
+    const timeoutMs = this.options.timeoutMs
+    let timer: ReturnType<typeof setTimeout> | undefined
+    if (timeoutMs !== "never") {
+      timer = setTimeout(() => {
+        this.settle(request.id, false, "approval timed out")
+      }, timeoutMs)
+      ;(timer as unknown as { unref?: () => void }).unref?.()
+    }
     const pending: PendingApproval = { request, decided, settle, timer }
     this.pendingApprovals.set(request.id, pending)
     await this.options.onRequired?.(request)
@@ -233,7 +277,17 @@ export class ApprovalManager {
   }
 }
 
-export function approvalRequestFromEvent(event: AgentApprovalRequiredEvent): ApprovalRequest {
+/**
+ * Project a backend approval event into a request. Pass the broker's timeout
+ * (`ApprovalManager.timeoutMs`) so `expiresAt` matches when it will actually be denied; the default
+ * is the broker's default of 5 minutes.
+ */
+export function approvalRequestFromEvent(
+  event: AgentApprovalRequiredEvent,
+  timeoutMs: ApprovalTimeout = DEFAULT_APPROVAL_TIMEOUT_MS,
+): ApprovalRequest {
+  if (!isApprovalTimeout(timeoutMs))
+    throw new RangeError('approvals: timeoutMs must be between 1ms and 24h, or "never"')
   return Object.freeze({
     id: event.approvalId,
     sessionId: event.sessionId,
@@ -242,7 +296,7 @@ export function approvalRequestFromEvent(event: AgentApprovalRequiredEvent): App
     capability: event.capability,
     ...(event.reason === undefined ? {} : { reason: event.reason }),
     createdAt: event.at,
-    expiresAt: event.at + 5 * 60_000,
+    expiresAt: approvalExpiresAt(event.at, timeoutMs),
   })
 }
 

package/src/extensions.ts

@@ -1,5 +1,5 @@
 import { existsSync, realpathSync } from "node:fs"
-import { join, relative, resolve } from "node:path"
+import { isAbsolute, join, relative, resolve, sep } from "node:path"
 import {
   type WorkflowEvent,
   type WorkflowResult,
@@ -398,5 +398,9 @@ function isWithin(root: string, candidate: string): boolean {
     }
   }
   const relativePath = relative(canonical(root), canonical(candidate))
-  return relativePath === "" || (!relativePath.startsWith("..") && !relativePath.includes("/.."))
+  // On Windows a path on another drive has no relative form, so `relative` returns it absolute.
+  return (
+    relativePath === "" ||
+    (relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath))
+  )
 }

package/src/host.ts

@@ -191,31 +191,40 @@ export class CodingAgentHost {
     const sessionId = this.session.id
     let nextMessage = message
     let repairAttempts = 0
-    for (;;) {
-      const stream = this.backend.send({
-        sessionId,
-        message: nextMessage,
-        ...(signal === undefined ? {} : { signal }),
-      })
-      for await (const rawEvent of stream) {
-        const event = this.acceptBackendEvent(rawEvent)
-        await this.recordEvent(event)
-        yield event
-        if (event.type === "session.stopped") return
-        if (event.type === "session.failed") {
-          if (event.error.code === "BACKEND_PROTOCOL")
-            await this.backend.cancel(sessionId, "backend protocol error").catch(() => {})
-          return
+    // A reader that leaves early (an RPC client disconnecting) never records the backend's
+    // `approval.resolved`, so the turn's approvals are denied here instead of waiting on a timer.
+    const raised = new Set<string>()
+    try {
+      for (;;) {
+        const stream = this.backend.send({
+          sessionId,
+          message: nextMessage,
+          ...(signal === undefined ? {} : { signal }),
+        })
+        for await (const rawEvent of stream) {
+          const event = this.acceptBackendEvent(rawEvent)
+          await this.recordEvent(event)
+          if (event.type === "approval.required") raised.add(event.approvalId)
+          yield event
+          if (event.type === "session.stopped") return
+          if (event.type === "session.failed") {
+            if (event.error.code === "BACKEND_PROTOCOL")
+              await this.backend.cancel(sessionId, "backend protocol error").catch(() => {})
+            return
+          }
         }
-      }
-      if (signal?.aborted === true) return
+        if (signal?.aborted === true) return
 
-      const repairTasks = await this.verifyTurn()
-      for (const event of repairTasks.events) yield event
-      if (repairTasks.tasks.length === 0 || repairAttempts >= this.maxRepairAttempts) return
+        const repairTasks = await this.verifyTurn()
+        for (const event of repairTasks.events) yield event
+        if (repairTasks.tasks.length === 0 || repairAttempts >= this.maxRepairAttempts) return
 
-      repairAttempts++
-      nextMessage = createRepairPrompt(repairTasks.tasks, repairAttempts, this.maxRepairAttempts)
+        repairAttempts++
+        nextMessage = createRepairPrompt(repairTasks.tasks, repairAttempts, this.maxRepairAttempts)
+      }
+    } finally {
+      for (const approvalId of raised)
+        this.approvals.resolve(approvalId, false, "approval turn ended")
     }
   }
 

package/src/index.ts

@@ -1,11 +1,13 @@
 export { PiBackend, type PiBackendOptions } from "@nifrajs/pi"
 export {
+  APPROVAL_NEVER_EXPIRES_AT,
   type ApprovalDecision,
   ApprovalManager,
   type ApprovalManagerOptions,
   type ApprovalMatchRejection,
   type ApprovalMatchResult,
   type ApprovalRequest,
+  type ApprovalTimeout,
   approvalRequestFromEvent,
   approvalResolvedEvent,
 } from "./approvals.ts"

package/src/isolated.ts

@@ -1,5 +1,5 @@
 import { realpathSync } from "node:fs"
-import { isAbsolute, relative, resolve } from "node:path"
+import { isAbsolute, relative, resolve, sep } from "node:path"
 import { fileURLToPath } from "node:url"
 import { readBoundedText } from "./process.ts"
 
@@ -321,7 +321,8 @@ export class IsolatedExtensionWorker {
 
 function isWithin(root: string, candidate: string): boolean {
   const path = relative(resolve(root), resolve(candidate))
-  return path === "" || (!path.startsWith("..") && !path.includes("/.."))
+  // On Windows a path on another drive has no relative form, so `relative` returns it absolute.
+  return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path))
 }
 
 function isValidPort(value: unknown): value is number {

package/src/native.ts

@@ -21,6 +21,7 @@ import {
   type SendMessageInput,
   splitAgentText,
 } from "@nifrajs/agent-protocol"
+import { type ApprovalTimeout, isApprovalTimeout } from "./approvals.ts"
 
 export interface NativeMessage {
   readonly role: "user" | "assistant" | "tool"
@@ -135,8 +136,12 @@ export interface NifraBackendOptions {
   readonly model: NativeModelPort
   readonly tools?: readonly NativeTool[]
   readonly approval?: NativeApprovalPort
-  /** Maximum time a protocol-visible native approval may remain unresolved. */
-  readonly approvalTimeoutMs?: number
+  /**
+   * Maximum time a protocol-visible native approval may remain unresolved (default 5 minutes, at
+   * most 24 h). `"never"` removes the timer: the approval waits for an answer, a cancel, the end of
+   * its turn, or session close.
+   */
+  readonly approvalTimeoutMs?: ApprovalTimeout
   readonly maxSteps?: number
   /** Longest message `send` accepts (default 64 KiB). */
   readonly maxMessageChars?: number
@@ -175,7 +180,7 @@ interface NativePendingApproval {
   readonly action: string
   readonly capability: string
   readonly resolve: (resolution: NativeApprovalResolution) => void
-  readonly timer: ReturnType<typeof setTimeout>
+  readonly timer: ReturnType<typeof setTimeout> | undefined
   readonly onAbort: () => void
   readonly signal: AbortSignal
 }
@@ -238,11 +243,11 @@ export class NifraBackend implements AgentBackend {
       throw new RangeError("nifra backend: maxHistoryChars must be at least 256")
     if (
       this.options.approvalTimeoutMs !== undefined &&
-      (!Number.isSafeInteger(this.options.approvalTimeoutMs) ||
-        this.options.approvalTimeoutMs < 1 ||
-        this.options.approvalTimeoutMs > 24 * 60 * 60_000)
+      !isApprovalTimeout(this.options.approvalTimeoutMs)
     )
-      throw new RangeError("nifra backend: approvalTimeoutMs must be between 1ms and 24h")
+      throw new RangeError(
+        'nifra backend: approvalTimeoutMs must be between 1ms and 24h, or "never"',
+      )
   }
 
   async createSession(input: CreateSessionInput): Promise<AgentSessionSnapshot> {
@@ -627,13 +632,14 @@ export class NifraBackend implements AgentBackend {
           session.closed ? "APPROVAL_CLOSED" : "APPROVAL_CANCELLED",
         )
       }
-      const timer = setTimeout(
-        () => {
+      const timeoutMs = this.options.approvalTimeoutMs ?? 5 * 60_000
+      let timer: ReturnType<typeof setTimeout> | undefined
+      if (timeoutMs !== "never") {
+        timer = setTimeout(() => {
           this.settleApproval(session, approvalId, false, "approval timed out", "APPROVAL_TIMEOUT")
-        },
-        this.options.approvalTimeoutMs ?? 5 * 60_000,
-      )
-      ;(timer as unknown as { unref?: () => void }).unref?.()
+        }, timeoutMs)
+        ;(timer as unknown as { unref?: () => void }).unref?.()
+      }
       pending = {
         id: approvalId,
         sessionId: session.id,

package/src/process.ts

@@ -70,13 +70,15 @@ export interface BoundedProcessResult {
 }
 
 const KILL_GRACE_MS = 2_000
+// How long the pipes are still read once the child has exited, for output it wrote just before.
+const DRAIN_GRACE_MS = 2_000
 const PROCESS_GROUPS = process.platform !== "win32"
 
 /**
  * Run a trusted command to completion within `timeoutMs`. On POSIX the child leads its own process
  * group, so a timeout reaches every process it started: SIGTERM, then SIGKILL after a grace period.
- * Once the child is gone, pipes still held open by something outside the group are no longer
- * waited on, so the call always settles.
+ * The call settles when the child exits: a process it left running that still holds the pipes open
+ * is read from for a short grace and then no longer waited on, and `timedOut` stays `false`.
  */
 export async function runBoundedProcess(
   argv: readonly string[],
@@ -110,15 +112,25 @@ export async function runBoundedProcess(
       void proc.exited.then(() => reading.abort())
     }, graceMs)
   }, options.timeoutMs)
+  let drain: ReturnType<typeof setTimeout> | undefined
+  // Awaited below, so the drain timer is armed before the `finally` that clears it can run.
+  const exited = proc.exited.then((status) => {
+    if (!timedOut) {
+      clearTimeout(timer)
+      drain = setTimeout(() => reading.abort(), DRAIN_GRACE_MS)
+    }
+    return status
+  })
   try {
     const [stdout, stderr, status] = await Promise.all([
       readBoundedText(proc.stdout, options.maxStdoutBytes, reading.signal),
       readBoundedText(proc.stderr, options.maxStderrBytes, reading.signal),
-      proc.exited,
+      exited,
     ])
     return { stdout, stderr, status, timedOut }
   } finally {
     clearTimeout(timer)
     clearTimeout(escalation)
+    clearTimeout(drain)
   }
 }

package/src/rpc.ts

@@ -37,6 +37,12 @@ export interface CodingAgentRpcServerOptions {
   readonly maxRepairAttempts?: number
   readonly verification?: CodingAgentHostOptions["verification"]
   readonly extensionEvents?: CodingAgentHostOptions["extensionEvents"]
+  /**
+   * The host's approval broker: how long an approval or a tool's question waits for its answer
+   * (`timeoutMs`, default 5 minutes, or `"never"`), how many may wait (`maxPending`, default 32),
+   * and its `onRequired`/`onResolved` hooks.
+   */
+  readonly approvals?: CodingAgentHostOptions["approvals"]
   /**
    * Keep a `turn.send` running when its client disconnects, and let a client that comes back read
    * what it missed with `turn.attach` (an `afterSeq` cursor, or `Last-Event-ID`). The newest
@@ -124,6 +130,7 @@ export class CodingAgentRpcServer {
       ...(options.extensionEvents === undefined
         ? {}
         : { extensionEvents: options.extensionEvents }),
+      ...(options.approvals === undefined ? {} : { approvals: options.approvals }),
     })
     this.resumable = resumableTurnConfig(options.resumableTurns)
     this.token = options.authToken ?? randomAuthToken()