@nifrajs/coding-agent 3.3.0 → 4.0.0

package/src/subagents.ts

@@ -1,4 +1,5 @@
-import { relative, resolve, sep } from "node:path"
+import { realpath } from "node:fs/promises"
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 
 export interface SubagentSpec {
   readonly id: string
@@ -28,6 +29,10 @@ export interface SubagentExecutor {
 
 export interface SubagentWorkspaceLease {
   readonly cwd: string
+  /**
+   * Runs once the executor has settled. A run that times out or is cancelled returns at once, but
+   * its workspace stays until the executor finishes, so a child never loses its cwd mid-run.
+   */
   readonly cleanup?: () => void | PromiseLike<void>
 }
 
@@ -41,6 +46,22 @@ export interface SubagentWorkspacePolicy {
   ) => SubagentWorkspaceLease | PromiseLike<SubagentWorkspaceLease>
 }
 
+/** A run that returned while its executor kept running, having ignored its abort signal. */
+export interface SubagentAbandonment {
+  readonly spec: SubagentSpec
+  readonly reason: "timeout" | "cancelled"
+  /** The workspace the executor was given; undefined when it had none. */
+  readonly cwd: string | undefined
+  /** Settles once the executor does; its workspace lease is cleaned up after that. */
+  readonly settled: Promise<void>
+}
+
+/** Abandoned executors still running. Runners sharing one ledger are counted, and bounded by
+ * `maxAbandoned`, together. */
+export interface SubagentAbandonmentLedger {
+  abandoned: number
+}
+
 export interface SubagentRunnerOptions {
   readonly maxChildren?: number
   readonly maxDepth?: number
@@ -48,6 +69,25 @@ export interface SubagentRunnerOptions {
   readonly signal?: AbortSignal
   readonly allowedCapabilities?: readonly string[]
   readonly workspace?: SubagentWorkspacePolicy
+  /**
+   * Called when a run returns while its executor keeps running: it timed out or was cancelled and
+   * ignored its abort signal. Use it to stop the executor another way, such as ending its process.
+   */
+  readonly onAbandoned?: (abandonment: SubagentAbandonment) => void
+  /** Refuse new children while this many abandoned executors are still running. Default: no bound. */
+  readonly maxAbandoned?: number
+  /** Where abandoned executors are counted. Default: a ledger of this runner's own. */
+  readonly abandonment?: SubagentAbandonmentLedger
+}
+
+/** `work`'s outcome, or `stopped()` as soon as `signal` aborts, even when `work` ignores it. */
+function untilAborted<T>(work: Promise<T>, signal: AbortSignal, stopped: () => Error): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const stop = (): void => reject(stopped())
+    if (signal.aborted) return stop()
+    signal.addEventListener("abort", stop, { once: true })
+    work.then(resolve, reject).finally(() => signal.removeEventListener("abort", stop))
+  })
 }
 
 /** Explicitly bounded child execution. Recursive fan-out is impossible without a caller budget. */
@@ -58,6 +98,7 @@ export class BoundedSubagentRunner {
   > &
     SubagentRunnerOptions
   private children = 0
+  private readonly ledger: SubagentAbandonmentLedger
 
   constructor(executor: SubagentExecutor, options: SubagentRunnerOptions = {}) {
     this.executor = executor
@@ -67,15 +108,37 @@ export class BoundedSubagentRunner {
       maxDepth: options.maxDepth ?? 2,
       depth: options.depth ?? 0,
     }
-    if (this.options.maxChildren < 1 || this.options.maxDepth < 0 || this.options.depth < 0)
+    this.ledger = options.abandonment ?? { abandoned: 0 }
+    if (
+      this.options.maxChildren < 1 ||
+      this.options.maxDepth < 0 ||
+      this.options.depth < 0 ||
+      (options.maxAbandoned !== undefined &&
+        (!Number.isSafeInteger(options.maxAbandoned) || options.maxAbandoned < 0))
+    )
       throw new RangeError(
         "subagents: limits must be non-negative and maxChildren must be positive",
       )
   }
 
+  /** Executors this runner's ledger holds as abandoned and still running. */
+  get abandoned(): number {
+    return this.ledger.abandoned
+  }
+
   async run(spec: SubagentSpec): Promise<SubagentResult> {
     if (!/^[a-z][a-z0-9._:-]{0,63}$/.test(spec.id))
       return { id: spec.id, role: spec.role, ok: false, error: "invalid subagent id" }
+    if (
+      this.options.maxAbandoned !== undefined &&
+      this.ledger.abandoned >= this.options.maxAbandoned
+    )
+      return {
+        id: spec.id,
+        role: spec.role,
+        ok: false,
+        error: "subagent abandoned-executor limit reached",
+      }
     if (++this.children > this.options.maxChildren)
       return { id: spec.id, role: spec.role, ok: false, error: "subagent child limit exceeded" }
     if (this.options.depth > this.options.maxDepth)
@@ -110,13 +173,23 @@ export class BoundedSubagentRunner {
       }
     const controller = new AbortController()
     const onAbort = (): void => controller.abort(this.options.signal?.reason)
-    this.options.signal?.addEventListener("abort", onAbort, { once: true })
+    if (this.options.signal?.aborted === true) onAbort()
+    else this.options.signal?.addEventListener("abort", onAbort, { once: true })
+    let timedOut = false
     const timeout =
       spec.timeoutMs === undefined
         ? undefined
-        : setTimeout(() => controller.abort("timeout"), spec.timeoutMs)
+        : setTimeout(() => {
+            timedOut = true
+            controller.abort("timeout")
+          }, spec.timeoutMs)
+    const stopped = (): Error => new Error(timedOut ? "subagent timed out" : "subagent cancelled")
     let workspace: SubagentWorkspaceLease | undefined
+    let cwd: string | undefined
+    let executorDone: Promise<void> | undefined
+    let executorSettled = false
     try {
+      if (controller.signal.aborted) throw stopped()
       const requestedCwd =
         spec.cwd === undefined
           ? this.options.workspace?.root
@@ -124,7 +197,8 @@ export class BoundedSubagentRunner {
             ? resolve(spec.cwd)
             : resolve(this.options.workspace.root, spec.cwd)
       if (requestedCwd !== undefined && this.options.workspace !== undefined) {
-        if (!within(this.options.workspace.root, requestedCwd))
+        const requested = await physicalPath(requestedCwd)
+        if (!(await within(this.options.workspace.root, requested)))
           return {
             id: spec.id,
             role: spec.role,
@@ -132,7 +206,7 @@ export class BoundedSubagentRunner {
             error: "subagent workspace escapes policy root",
           }
         const allowedRoots = this.options.workspace.allowedRoots ?? [this.options.workspace.root]
-        if (!allowedRoots.some((root) => within(root, requestedCwd)))
+        if (!(await withinAny(allowedRoots, requested)))
           return {
             id: spec.id,
             role: spec.role,
@@ -145,11 +219,15 @@ export class BoundedSubagentRunner {
       } else if (requestedCwd !== undefined) {
         workspace = { cwd: requestedCwd }
       }
+      cwd = workspace?.cwd
       if (workspace !== undefined && this.options.workspace !== undefined) {
+        // The executor gets the path that was checked, with its links already resolved, so a link
+        // swapped after the check cannot move it out of the policy root.
+        cwd = await physicalPath(workspace.cwd)
         const allowedRoots = this.options.workspace.allowedRoots ?? [this.options.workspace.root]
         if (
-          !within(this.options.workspace.root, workspace.cwd) ||
-          !allowedRoots.some((root) => within(root, workspace!.cwd))
+          !(await within(this.options.workspace.root, cwd)) ||
+          !(await withinAny(allowedRoots, cwd))
         )
           return {
             id: spec.id,
@@ -158,11 +236,20 @@ export class BoundedSubagentRunner {
             error: "isolated worktree escapes workspace policy",
           }
       }
-      const output = await this.executor.run({
-        spec,
-        signal: controller.signal,
-        ...(workspace === undefined ? {} : { cwd: workspace.cwd }),
-      })
+      if (controller.signal.aborted) throw stopped()
+      const work = Promise.resolve().then(() =>
+        this.executor.run({
+          spec,
+          signal: controller.signal,
+          ...(cwd === undefined ? {} : { cwd }),
+        }),
+      )
+      // Registered before untilAborted's reaction, so a settled executor is seen as settled below.
+      const settle = (): void => {
+        executorSettled = true
+      }
+      executorDone = work.then(settle, settle)
+      const output = await untilAborted(work, controller.signal, stopped)
       return { id: spec.id, role: spec.role, ok: true, output }
     } catch (error) {
       return {
@@ -172,9 +259,29 @@ export class BoundedSubagentRunner {
         error: error instanceof Error ? error.message : String(error),
       }
     } finally {
-      await workspace?.cleanup?.()
       if (timeout !== undefined) clearTimeout(timeout)
       this.options.signal?.removeEventListener("abort", onAbort)
+      const cleanup = workspace?.cleanup
+      // An executor that honours the abort settles within a few ticks; give it one turn before
+      // calling it abandoned.
+      if (executorDone !== undefined && !executorSettled)
+        await Promise.race([executorDone, new Promise((resolve) => setTimeout(resolve, 0))])
+      if (executorDone !== undefined && !executorSettled) {
+        // The executor is counted until it settles, and may still be writing to its workspace, so
+        // the release waits for it too.
+        const ledger = this.ledger
+        ledger.abandoned++
+        const settled = executorDone.then(() => {
+          ledger.abandoned--
+        })
+        if (cleanup !== undefined) settled.then(() => cleanup()).catch(() => {})
+        this.options.onAbandoned?.({
+          spec,
+          reason: timedOut ? "timeout" : "cancelled",
+          cwd,
+          settled,
+        })
+      } else if (cleanup !== undefined) await cleanup()
     }
   }
 
@@ -201,10 +308,33 @@ export class BoundedSubagentRunner {
   }
 }
 
-function within(root: string, candidate: string): boolean {
-  const relativePath = relative(resolve(root), resolve(candidate))
+/** Whether `physical`, a path whose links are already resolved, lies inside the physical root, so a
+ * symlink inside the root cannot lead out of it. */
+async function within(root: string, physical: string): Promise<boolean> {
+  const relativePath = relative(await physicalPath(root), physical)
   return (
     relativePath === "" ||
-    (relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !relativePath.startsWith("/"))
+    (relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath))
   )
 }
+
+async function withinAny(roots: readonly string[], physical: string): Promise<boolean> {
+  for (const root of roots) if (await within(root, physical)) return true
+  return false
+}
+
+/** The path with its existing part's symlinks resolved; a part not created yet is kept as written. */
+async function physicalPath(path: string): Promise<string> {
+  const missing: string[] = []
+  let existing = resolve(path)
+  for (;;) {
+    try {
+      return join(await realpath(existing), ...missing)
+    } catch {
+      const parent = dirname(existing)
+      if (parent === existing) return resolve(path)
+      missing.unshift(basename(existing))
+      existing = parent
+    }
+  }
+}

package/src/verification.ts

@@ -53,12 +53,124 @@ export interface VerificationOptions {
   readonly exposeErrorStacks?: boolean
 }
 
-/** Run an existing Nifra gate without importing the large framework CLI into the agent runtime. */
+export type ReviewExecutionErrorCode =
+  | "timeout"
+  | "output-truncated"
+  | "invalid-report"
+  | "spawn-failed"
+
+export interface ReviewOptions {
+  readonly cwd: string
+  readonly command?: string
+  readonly commandArgs?: readonly string[]
+  readonly strict?: boolean
+  readonly diff?: string
+  readonly timeoutMs?: number
+  readonly maxOutputBytes?: number
+  readonly env?: Readonly<Record<string, string | undefined>>
+}
+
+export interface ReviewExecutionResult {
+  readonly name: "review"
+  readonly ok: boolean
+  readonly status: number | null
+  /** A parsed, content-free ReviewReport. Raw stdout/stderr is intentionally never returned. */
+  readonly report?: unknown
+  readonly errorCode?: ReviewExecutionErrorCode
+}
+
+const REVIEW_GIT_REF = /^[A-Za-z0-9][A-Za-z0-9._/@+-]{0,255}$/
+
+/** Validate the only repository selector exposed by the host review RPC. */
+export function isSafeReviewDiff(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    REVIEW_GIT_REF.test(value) &&
+    !value.includes("..") &&
+    !value.includes("@{") &&
+    !value.includes("//") &&
+    !value.endsWith(".") &&
+    !value.endsWith("/") &&
+    !value
+      .split("/")
+      .some((part) => part.length === 0 || part === "." || part === ".." || part.startsWith("."))
+  )
+}
+
+/** Run `nifra review --json` with the same bounded process discipline as the existing gates. */
+export async function runNifraReview(options: ReviewOptions): Promise<ReviewExecutionResult> {
+  if (options.strict !== undefined && typeof options.strict !== "boolean")
+    throw new TypeError("review strict must be a boolean")
+  if (options.diff !== undefined && !isSafeReviewDiff(options.diff))
+    throw new TypeError("review diff is not a safe Git ref")
+  const command = options.command ?? "nifra"
+  const commandArgs = options.commandArgs ?? []
+  const args = ["review", "--json"]
+  if (options.strict === true) args.push("--strict")
+  if (options.diff !== undefined) args.push("--diff", options.diff)
+  let proc: ReturnType<typeof Bun.spawn>
+  try {
+    proc = Bun.spawn([command, ...commandArgs, ...args], {
+      cwd: options.cwd,
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+      env: safeEnv(options.env),
+    })
+  } catch {
+    return { name: "review", ok: false, status: null, errorCode: "spawn-failed" }
+  }
+  const timeoutMs = options.timeoutMs ?? 120_000
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    proc.kill()
+  }, timeoutMs)
+  try {
+    const [stdout, stderr, status] = await Promise.all([
+      readBoundedText(proc.stdout, options.maxOutputBytes ?? 1_048_576),
+      readBoundedText(proc.stderr, options.maxOutputBytes ?? 1_048_576),
+      proc.exited,
+    ])
+    void stderr
+    if (timedOut) return { name: "review", ok: false, status, errorCode: "timeout" }
+    if (stdout.truncated || stderr.truncated)
+      return { name: "review", ok: false, status, errorCode: "output-truncated" }
+    try {
+      const raw = JSON.parse(stdout.text) as unknown
+      const { parseReviewReport } = await import("@nifrajs/agent-review")
+      const report = await parseReviewReport(raw)
+      return {
+        name: "review",
+        ok: status === 0 && report.ok,
+        status,
+        report,
+      }
+    } catch {
+      return { name: "review", ok: false, status, errorCode: "invalid-report" }
+    }
+  } catch {
+    return {
+      name: "review",
+      ok: false,
+      status: null,
+      errorCode: timedOut ? "timeout" : "spawn-failed",
+    }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Run an existing Nifra gate without importing the large framework CLI into the agent runtime.
+ * `check` and `assure` are `nifra` commands; `test` is the project's own suite, run with `bun test`
+ * by the Bun this agent runs on.
+ */
 export async function runNifraVerification(
   name: "check" | "assure" | "test",
   options: VerificationOptions,
 ): Promise<VerificationResult> {
-  const command = options.command ?? "nifra"
+  const command = options.command ?? (name === "test" ? process.execPath : "nifra")
   const commandArgs = options.commandArgs ?? []
   const args = name === "test" ? ["test"] : [name, "--json"]
   const proc = Bun.spawn([command, ...commandArgs, ...args], {
@@ -124,10 +236,41 @@ function safeEnv(
     "LC_ALL",
     "TERM",
     "CI",
+    ...(process.platform === "win32"
+      ? [
+          "SystemRoot",
+          "WINDIR",
+          "TEMP",
+          "TMP",
+          "USERPROFILE",
+          "LOCALAPPDATA",
+          "APPDATA",
+          "COMSPEC",
+          "PATHEXT",
+          "BUN_INSTALL",
+          "HOMEDRIVE",
+          "HOMEPATH",
+          "USERNAME",
+          "USERDOMAIN",
+          "ProgramData",
+          "ProgramFiles",
+          "ProgramFiles(x86)",
+        ]
+      : []),
     ...Object.keys(overrides ?? {}),
   ])) {
-    const value = overrides?.[name] ?? process.env[name]
+    const value =
+      overrides !== undefined && Object.hasOwn(overrides, name) ? overrides[name] : readEnv(name)
     if (value !== undefined) result[name] = value
   }
   return result
 }
+
+function readEnv(name: string): string | undefined {
+  const exact = process.env[name]
+  if (exact !== undefined || process.platform !== "win32") return exact
+  const key = Object.keys(process.env).find(
+    (candidate) => candidate.toLowerCase() === name.toLowerCase(),
+  )
+  return key === undefined ? undefined : process.env[key]
+}

package/src/workflows.ts

@@ -88,6 +88,7 @@ export interface WorkflowResult {
 export class WorkflowRunner {
   private readonly options: Required<Pick<WorkflowRunnerOptions, "maxSteps" | "maxDepth">> &
     WorkflowRunnerOptions
+  private readonly signal: AbortSignal
   private readonly values = new Map<string, unknown>()
   private readonly completed: string[] = []
   private steps = 0
@@ -98,6 +99,7 @@ export class WorkflowRunner {
       maxSteps: options.maxSteps ?? 128,
       maxDepth: options.maxDepth ?? 8,
     }
+    this.signal = options.signal ?? new AbortController().signal
     if (!Number.isSafeInteger(this.options.maxSteps) || this.options.maxSteps < 1)
       throw new RangeError("workflow: maxSteps must be positive")
     if (!Number.isSafeInteger(this.options.maxDepth) || this.options.maxDepth < 1)
@@ -128,12 +130,12 @@ export class WorkflowRunner {
     }
   }
 
-  private context(): WorkflowContext {
+  private context(depth: number): WorkflowContext {
     return {
-      signal: this.options.signal ?? new AbortController().signal,
+      signal: this.signal,
       values: this.values,
       set: (name, value) => this.values.set(name, value),
-      run: (step) => this.execute(step, 1),
+      run: (step) => this.execute(step, depth + 1),
     }
   }
 
@@ -143,51 +145,55 @@ export class WorkflowRunner {
     if (this.options.signal?.aborted) throw new Error("workflow cancelled")
     switch (step.type) {
       case "task":
-        return this.single(step.id, () => step.run(this.context()))
+        return this.single(step.id, () => step.run(this.context(depth)))
       case "verify": {
-        const result = await this.single(step.id, () => step.run(this.context()))
+        const result = await this.single(step.id, () => step.run(this.context(depth)))
         const ok = typeof result === "boolean" ? result : isVerificationResult(result) && result.ok
         if (!ok) throw new Error(`verification failed: ${step.id}`)
         return result
       }
       case "approve": {
         await this.emit({ type: "approval.required", id: step.id, reason: step.reason })
-        const approved = await this.single(step.id, () => step.run(this.context()))
+        const approved = await this.single(step.id, () => step.run(this.context(depth)))
         if (approved !== true) throw new Error(`approval denied: ${step.id}`)
         return approved
       }
       case "checkpoint": {
-        const result = await this.single(step.id, () => step.run(this.context()))
+        const result = await this.single(step.id, () => step.run(this.context(depth)))
         await this.emit({ type: "checkpoint.created", id: step.id })
         return result
       }
       case "handoff":
-        return this.single(step.id, () => step.run(this.context()))
+        return this.single(step.id, () => step.run(this.context(depth)))
       case "sequence": {
         const results: unknown[] = []
         for (const child of step.steps) results.push(await this.execute(child, depth + 1))
         return results
       }
       case "parallel":
+        if (step.steps.length === 0) return []
         return this.parallel(step.steps, step.maxConcurrency ?? step.steps.length, depth)
       case "retry": {
         const attempts = step.attempts ?? 3
         if (!Number.isSafeInteger(attempts) || attempts < 1 || attempts > 16)
           throw new RangeError("workflow: attempts must be between 1 and 16")
+        const backoffMs = step.backoffMs ?? 0
+        if (!Number.isSafeInteger(backoffMs) || backoffMs < 0)
+          throw new RangeError("workflow: backoffMs must be a non-negative safe integer")
         let last: unknown
         for (let attempt = 0; attempt < attempts; attempt++) {
           try {
             return await this.execute(step.step, depth + 1)
           } catch (error) {
             last = error
-            if (attempt + 1 < attempts && (step.backoffMs ?? 0) > 0)
-              await delay(Math.min(step.backoffMs! * (attempt + 1), 10_000), this.options.signal)
+            if (attempt + 1 < attempts && backoffMs > 0)
+              await delay(Math.min(backoffMs * (attempt + 1), 10_000), this.options.signal)
           }
         }
         throw last instanceof Error ? last : new Error(String(last))
       }
       case "branch": {
-        const selected = await this.single(step.id, () => step.when(this.context()))
+        const selected = await this.single(step.id, () => step.when(this.context(depth)))
         return selected === true
           ? this.execute(step.then, depth + 1)
           : step.otherwise === undefined
@@ -229,16 +235,24 @@ export class WorkflowRunner {
       throw new RangeError("workflow: maxConcurrency must be positive")
     const outputs: unknown[] = new Array(steps.length)
     let next = 0
+    // The first failure starts no further step, and the group settles only once the steps already
+    // running have, so nothing runs on after the workflow reports its failure.
+    let failure: { readonly error: unknown } | undefined
     const worker = async (): Promise<void> => {
-      for (;;) {
+      while (failure === undefined) {
         const index = next++
         if (index >= steps.length) return
-        outputs[index] = await this.execute(steps[index]!, depth + 1)
+        try {
+          outputs[index] = await this.execute(steps[index]!, depth + 1)
+        } catch (error) {
+          failure ??= { error }
+        }
       }
     }
     await Promise.all(
       Array.from({ length: Math.min(maxConcurrency, steps.length) }, () => worker()),
     )
+    if (failure !== undefined) throw failure.error
     return outputs
   }
 
@@ -249,21 +263,27 @@ export class WorkflowRunner {
 
 async function delay(ms: number, signal: AbortSignal | undefined): Promise<void> {
   await new Promise<void>((resolve, reject) => {
-    const timer = setTimeout(resolve, ms)
-    if (signal === undefined) return
-    if (signal.aborted) {
-      clearTimeout(timer)
-      reject(new Error("workflow cancelled"))
-      return
+    let settled = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let onAbort: (() => void) | undefined
+    const cleanup = (): void => {
+      if (timer !== undefined) clearTimeout(timer)
+      if (signal !== undefined && onAbort !== undefined)
+        signal.removeEventListener("abort", onAbort)
     }
-    signal.addEventListener(
-      "abort",
-      () => {
-        clearTimeout(timer)
-        reject(new Error("workflow cancelled"))
-      },
-      { once: true },
-    )
+    const settle = (error?: Error): void => {
+      if (settled) return
+      settled = true
+      cleanup()
+      if (error === undefined) resolve()
+      else reject(error)
+    }
+    timer = setTimeout(() => settle(), ms)
+    if (signal === undefined) return
+    onAbort = () => settle(new Error("workflow cancelled"))
+    signal.addEventListener("abort", onAbort, { once: true })
+    // Abort can race listener registration; check again after subscribing.
+    if (signal.aborted) onAbort()
   })
 }