@nifrajs/coding-agent 3.3.0 → 4.0.0

package/dist/workflows.js

@@ -2,6 +2,7 @@ import { publicErrorDetails } from "./errors.js";
 /** Bounded orchestration primitives. The kernel knows no provider, UI, or framework package. */
 export class WorkflowRunner {
     options;
+    signal;
     values = new Map();
     completed = [];
     steps = 0;
@@ -11,6 +12,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)
@@ -36,12 +38,12 @@ export class WorkflowRunner {
             };
         }
     }
-    context() {
+    context(depth) {
         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),
         };
     }
     async execute(step, depth) {
@@ -53,9 +55,9 @@ export class WorkflowRunner {
             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}`);
@@ -63,18 +65,18 @@ export class WorkflowRunner {
             }
             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 = [];
                 for (const child of step.steps)
@@ -82,11 +84,16 @@ export class WorkflowRunner {
                 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;
                 for (let attempt = 0; attempt < attempts; attempt++) {
                     try {
@@ -94,14 +101,14 @@ export class WorkflowRunner {
                     }
                     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
@@ -134,15 +141,25 @@ export class WorkflowRunner {
             throw new RangeError("workflow: maxConcurrency must be positive");
         const outputs = 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;
         const worker = async () => {
-            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;
     }
     async emit(event) {
@@ -151,18 +168,33 @@ export class WorkflowRunner {
 }
 async function delay(ms, signal) {
     await new Promise((resolve, reject) => {
-        const timer = setTimeout(resolve, ms);
+        let settled = false;
+        let timer;
+        let onAbort;
+        const cleanup = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            if (signal !== undefined && onAbort !== undefined)
+                signal.removeEventListener("abort", onAbort);
+        };
+        const settle = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (error === undefined)
+                resolve();
+            else
+                reject(error);
+        };
+        timer = setTimeout(() => settle(), ms);
         if (signal === undefined)
             return;
-        if (signal.aborted) {
-            clearTimeout(timer);
-            reject(new Error("workflow cancelled"));
-            return;
-        }
-        signal.addEventListener("abort", () => {
-            clearTimeout(timer);
-            reject(new Error("workflow cancelled"));
-        }, { once: true });
+        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();
     });
 }
 function isVerificationResult(value) {

package/dist/workflows.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../src/workflows.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../src/workflows.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/coding-agent",
-  "version": "3.3.0",
+  "version": "4.0.0",
   "description": "Standalone, extensible Nifra coding-agent host and CLI.",
   "keywords": [
     "bun",
@@ -12,6 +12,9 @@
     "workflows"
   ],
   "type": "module",
+  "nifra": {
+    "environment": "backend"
+  },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -67,10 +70,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/agent": "3.3.0",
-    "@nifrajs/agent-protocol": "3.3.0",
-    "@nifrajs/jobs": "3.3.0",
-    "@nifrajs/pi": "3.3.0"
+    "@nifrajs/agent": "4.0.0",
+    "@nifrajs/agent-review": "4.0.0",
+    "@nifrajs/agent-protocol": "4.0.0",
+    "@nifrajs/jobs": "4.0.0",
+    "@nifrajs/pi": "4.0.0"
   },
   "repository": {
     "type": "git",

package/src/approvals.ts

@@ -52,10 +52,16 @@ export interface ApprovalManagerOptions {
 
 interface PendingApproval {
   readonly request: ApprovalRequest
-  readonly resolve: (approved: boolean) => void
+  /** 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>
 }
 
+/** The agent protocol's token alphabet, so every protocol-valid id is accepted here too. */
+const ID_TOKEN = /^[A-Za-z0-9._:/-]{1,128}$/
+const MAX_ACTION_LENGTH = 512
+
 /**
  * Small approval broker shared by RPC, Workbench, and workflow extensions.
  *
@@ -89,38 +95,37 @@ export class ApprovalManager {
 
   /** Convert a streamed backend approval event into a resolvable pending request. */
   async observe(event: AgentApprovalRequiredEvent): Promise<ApprovalRequest | undefined> {
-    if (this.pendingApprovals.has(event.approvalId))
-      return this.pendingApprovals.get(event.approvalId)?.request
-    return this.create({
+    const existing = this.pendingApprovals.get(event.approvalId)
+    if (existing !== undefined) return existing.request
+    const pending = await this.create({
       id: event.approvalId,
       sessionId: event.sessionId,
       turnId: event.turnId,
-      action: event.action,
+      // The protocol bounds text more loosely; a long label must not fail the backend's turn.
+      action: event.action.slice(0, MAX_ACTION_LENGTH),
       capability: event.capability,
       ...(event.reason === undefined ? {} : { reason: event.reason }),
     })
+    return pending?.request
   }
 
-  /** Publish a pending approval without waiting for its decision (useful for transports). */
+  /**
+   * Publish a pending approval without waiting for its decision (useful for transports). Returns
+   * `undefined` when the broker is full or an approval with the same id is still pending.
+   */
   async offer(
     input: Omit<ApprovalRequest, "createdAt" | "expiresAt">,
   ): Promise<ApprovalRequest | undefined> {
-    return this.create(input)
+    return (await this.create(input))?.request
   }
 
-  /** Create a host-owned approval that can be awaited by a workflow or extension. */
+  /**
+   * Create a host-owned approval that can be awaited by a workflow or extension. Resolves `false`
+   * when the broker is full or an approval with the same id is still pending.
+   */
   async request(input: Omit<ApprovalRequest, "createdAt" | "expiresAt">): Promise<boolean> {
-    const request = await this.offer(input)
-    if (request === undefined) return false
-    const pending = this.pendingApprovals.get(request.id)
-    if (pending === undefined) return false
-    return new Promise<boolean>((resolve) => {
-      // Replace the resolver only for this host-owned request; observed backend requests are
-      // intentionally notification-only and are resolved through `resolve`.
-      const current = this.pendingApprovals.get(request.id)
-      if (current === undefined) return resolve(false)
-      this.pendingApprovals.set(request.id, { ...current, resolve })
-    })
+    const pending = await this.create(input)
+    return pending === undefined ? false : pending.decided
   }
 
   /**
@@ -145,49 +150,68 @@ export class ApprovalManager {
         code: bound.vector !== coordinate.vector ? "stale_vector" : "identity_mismatch",
       }
     if (!coordinateIsFresh(bound, now)) {
-      this.resolve(coordinate.requestId, false, "approval expired")
+      this.settle(coordinate.requestId, false, "approval expired")
       return { ok: false, code: "expired" }
     }
     if (nextApprovalState("pending", approved ? "approve" : "deny") === undefined)
       return { ok: false, code: "illegal_transition" }
-    const decision = this.resolve(coordinate.requestId, approved)
+    const decision = this.settle(coordinate.requestId, approved)
     if (decision === undefined) return { ok: false, code: "unknown_boundary" }
     return { ok: true, decision }
   }
 
+  /**
+   * Settle a pending approval by id. An approval opened with a coordinate is approved only through
+   * {@link resolveMatched}; this untyped path can still deny it, and returns `undefined` for an
+   * approve.
+   */
   resolve(approvalId: string, approved: boolean, reason?: string): ApprovalDecision | undefined {
+    if (
+      approved === true &&
+      this.pendingApprovals.get(approvalId)?.request.coordinate !== undefined
+    )
+      return undefined
+    return this.settle(approvalId, approved, reason)
+  }
+
+  close(): void {
+    for (const approvalId of this.pendingApprovals.keys())
+      this.settle(approvalId, false, "approval manager closed")
+  }
+
+  private settle(
+    approvalId: string,
+    approved: boolean,
+    reason?: string,
+  ): ApprovalDecision | undefined {
     const pending = this.pendingApprovals.get(approvalId)
     if (pending === undefined) return undefined
     clearTimeout(pending.timer)
     this.pendingApprovals.delete(approvalId)
-    pending.resolve(approved === true)
+    pending.settle(approved === true)
     const decision: ApprovalDecision = {
       approvalId,
       approved: approved === true,
       ...(reason === undefined ? {} : { reason: reason.slice(0, 512) }),
       at: Date.now(),
     }
-    void this.options.onResolved?.(decision)
+    // A failing broadcast must not become an unhandled rejection in the host.
+    Promise.resolve(this.options.onResolved?.(decision)).catch(() => {})
     return decision
   }
 
-  close(): void {
-    for (const approvalId of this.pendingApprovals.keys())
-      this.resolve(approvalId, false, "approval manager closed")
-  }
-
   private async create(
     input: Omit<ApprovalRequest, "createdAt" | "expiresAt">,
-  ): Promise<ApprovalRequest | undefined> {
+  ): Promise<PendingApproval | undefined> {
     if (this.pendingApprovals.size >= this.options.maxPending) return undefined
-    if (!/^[A-Za-z0-9._:-]{1,128}$/.test(input.id))
-      throw new TypeError("approvals: approval id is invalid")
-    if (!/^[A-Za-z0-9._:-]{1,128}$/.test(input.sessionId))
-      throw new TypeError("approvals: session id is invalid")
-    if (!input.action || input.action.length > 512)
+    if (!ID_TOKEN.test(input.id)) throw new TypeError("approvals: approval id is invalid")
+    if (!ID_TOKEN.test(input.sessionId)) throw new TypeError("approvals: session id is invalid")
+    if (!input.action || input.action.length > MAX_ACTION_LENGTH)
       throw new TypeError("approvals: action is empty or too long")
     if (!input.capability || input.capability.length > 128)
       throw new TypeError("approvals: capability is empty or too long")
+    // Replacing a pending id would orphan the waiter of the request already holding it.
+    if (this.pendingApprovals.has(input.id)) return undefined
     const createdAt = Date.now()
     const request: ApprovalRequest = Object.freeze({
       ...input,
@@ -197,22 +221,15 @@ export class ApprovalManager {
       createdAt,
       expiresAt: createdAt + this.options.timeoutMs,
     })
-    let resolveApproval = (_approved: boolean): void => {}
+    const { promise: decided, resolve: settle } = Promise.withResolvers<boolean>()
     const timer = setTimeout(() => {
-      this.resolve(request.id, false, "approval timed out")
+      this.settle(request.id, false, "approval timed out")
     }, this.options.timeoutMs)
     ;(timer as unknown as { unref?: () => void }).unref?.()
-    const pending: PendingApproval = {
-      request,
-      resolve: (approved) => resolveApproval(approved),
-      timer,
-    }
+    const pending: PendingApproval = { request, decided, settle, timer }
     this.pendingApprovals.set(request.id, pending)
     await this.options.onRequired?.(request)
-    // A backend-observed request is resolved through `resolve`; a host request swaps this closure
-    // from the promise below before returning to the workflow.
-    resolveApproval = (_approved: boolean): void => {}
-    return request
+    return pending
   }
 }
 

package/src/cli.ts

@@ -25,10 +25,13 @@ Usage:
   nifra-agent [--backend pi|replay] [--cwd <dir>] [--once <prompt>]
               [--json] [--no-session] [--session-dir <dir>] [--session-id <id>]
               [--verify-after-turn check,assure] [--max-repair-attempts <n>]
-              [--pi <command>] [--replay <file>]
+              [--pi <command>] [--replay <file>] [--extensions]
   nifra-agent --migrate-session <id> --migrate-from <dir> --migrate-to <dir> [--json]
   nifra-agent --rpc [--cwd <dir>] [--host 127.0.0.1] [--port 0] [--expose-error-stacks]
 
+--extensions loads and runs .nifra/extensions/** from --cwd. That is the project's own code: pass it
+only for a repository you trust. Without it no extension is loaded.
+
 Commands in interactive mode:
   /reload       reload Pi or Nifra extensions
   /compact      compact the bounded prompt window
@@ -64,6 +67,7 @@ export interface CliOptions {
   readonly migrationTarget?: string
   readonly verifyAfterTurn: readonly ("check" | "assure" | "test")[]
   readonly maxRepairAttempts: number
+  readonly extensions: boolean
 }
 
 export function parseArgs(args: readonly string[]): CliOptions {
@@ -72,6 +76,7 @@ export function parseArgs(args: readonly string[]): CliOptions {
   let once: string | undefined
   let json = false
   let noSession = false
+  let extensions = false
   let piCommand = "pi"
   let replayFile: string | undefined
   let sessionDir: string | undefined
@@ -93,6 +98,7 @@ export function parseArgs(args: readonly string[]): CliOptions {
     else if (arg === "--once" || arg === "--message") once = args[++index]
     else if (arg === "--json") json = true
     else if (arg === "--no-session") noSession = true
+    else if (arg === "--extensions") extensions = true
     else if (arg === "--session-dir") sessionDir = resolve(args[++index] ?? "")
     else if (arg === "--session-id") sessionId = args[++index]
     else if (arg === "--migrate-session") migrateSession = args[++index]
@@ -142,6 +148,7 @@ export function parseArgs(args: readonly string[]): CliOptions {
     ...(once === undefined ? {} : { once }),
     json,
     noSession,
+    extensions,
     piCommand,
     ...(replayFile === undefined ? {} : { replayFile }),
     ...(sessionDir === undefined ? {} : { sessionDir }),
@@ -215,7 +222,9 @@ async function main(): Promise<void> {
           enableNifraTools: true,
           ...(options.sessionDir === undefined ? {} : { sessionDir: options.sessionDir }),
         })
-  const extensionRoots = await discoverExtensions(options.cwd)
+  // A module's top-level code runs as soon as it is imported, before any capability check can refuse
+  // it, so a cloned repository's extensions load only when the user asks.
+  const extensionRoots = options.extensions ? await discoverExtensions(options.cwd) : []
   const extensions = new ExtensionHost({
     cwd: options.cwd,
     roots: extensionRoots,

package/src/context.ts

@@ -72,10 +72,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/diff.ts

@@ -72,9 +72,47 @@ export async function readProjectDiff(options: ProjectDiffOptions): Promise<Proj
 
 function safeEnv(): Record<string, string> {
   const result: Record<string, string> = {}
-  for (const name of ["PATH", "HOME", "LANG", "LC_ALL", "TERM", "GIT_PAGER"]) {
-    const value = name === "GIT_PAGER" ? "cat" : process.env[name]
+  const names = [
+    "PATH",
+    "HOME",
+    "LANG",
+    "LC_ALL",
+    "TERM",
+    "GIT_PAGER",
+    ...(process.platform === "win32"
+      ? [
+          "SystemRoot",
+          "WINDIR",
+          "TEMP",
+          "TMP",
+          "USERPROFILE",
+          "LOCALAPPDATA",
+          "APPDATA",
+          "COMSPEC",
+          "PATHEXT",
+          "BUN_INSTALL",
+          "HOMEDRIVE",
+          "HOMEPATH",
+          "USERNAME",
+          "USERDOMAIN",
+          "ProgramData",
+          "ProgramFiles",
+          "ProgramFiles(x86)",
+        ]
+      : []),
+  ]
+  for (const name of names) {
+    const value = name === "GIT_PAGER" ? "cat" : 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/handoffs.ts

@@ -27,6 +27,8 @@ import type { ApprovalManager } from "./approvals.ts"
 import { ChildVectorTracker } from "./orchestration/policy.ts"
 
 const ID_TOKEN = /^[A-Za-z0-9._:-]{1,128}$/
+/** The agent protocol's token alphabet, which the approval broker accepts for session ids. */
+const SESSION_TOKEN = /^[A-Za-z0-9._:/-]{1,128}$/
 
 /** Stable, content-free reasons the coordinator refuses a handoff request or decision. */
 export type HandoffRejection =
@@ -136,7 +138,8 @@ export class HandoffCoordinator {
       !input.capability ||
       input.capability.length > 128 ||
       !input.from ||
-      input.from.length > 128
+      input.from.length > 128 ||
+      (input.sessionId !== undefined && !SESSION_TOKEN.test(input.sessionId))
     )
       throw new HandoffError("invalid_handoff")
     if (this.records.has(input.requestId)) throw new HandoffError("duplicate")
@@ -162,13 +165,18 @@ export class HandoffCoordinator {
     }
     this.records.set(input.requestId, record)
 
+    // The mirror carries the boundary's coordinate, so only a matched decision approves it. It is a
+    // notification: a broker that is full or fails to broadcast leaves the handoff itself intact.
     if (record.requireApproval && this.approvals !== undefined)
-      void this.approvals.offer({
-        id: input.requestId,
-        sessionId: input.sessionId ?? input.runId,
-        action: "handoff",
-        capability: input.capability,
-      })
+      this.approvals
+        .offer({
+          id: input.requestId,
+          sessionId: input.sessionId ?? input.runId,
+          action: "handoff",
+          capability: input.capability,
+          coordinate,
+        })
+        .catch(() => {})
     return this.view(record)
   }
 
@@ -264,7 +272,11 @@ export class HandoffCoordinator {
 
   private settleApproval(record: HandoffRecord, op: string): void {
     if (!record.requireApproval || this.approvals === undefined) return
-    this.approvals.resolve(record.coordinate.requestId, op === "accept" || op === "resolve")
+    this.approvals.resolveMatched(
+      record.coordinate,
+      op === "accept" || op === "resolve",
+      this.now(),
+    )
   }
 
   private isTerminal(state: HandoffLifecycleState): boolean {