@nifrajs/coding-agent 4.0.0 → 5.0.0

package/src/host.ts

@@ -4,11 +4,14 @@ import {
   type AgentBackend,
   type AgentEvent,
   type AgentEventPayload,
+  type AgentExtensionEvent,
   type AgentSessionSnapshot,
   agentError,
+  agentEventProblem,
   type CreateSessionInput,
   type ForkSessionResult,
   isAgentEvent,
+  isAgentExtensionEventType,
   type ReloadResult,
 } from "@nifrajs/agent-protocol"
 import {
@@ -50,19 +53,31 @@ export interface CodingAgentHostOptions {
   >
   /** Retain bounded exception stacks for trusted local diagnostics. */
   readonly exposeErrorStacks?: boolean
+  /**
+   * Checks for a backend's extension events (`x-<vendor>.<name>`), by type. An event whose check
+   * returns false or throws fails the turn like a malformed protocol event; a type with no check
+   * passes through as long as it stays inside the protocol's bounds.
+   */
+  readonly extensionEvents?: Readonly<Record<string, (event: AgentExtensionEvent) => boolean>>
 }
 
 /** Small lifecycle host shared by the CLI, RPC server, and future Workbench. */
 export class CodingAgentHost {
   readonly backend: AgentBackend
   private session: AgentSessionSnapshot | undefined
+  private starting: Promise<AgentSessionSnapshot> | undefined
+  // Bumped by every start and stop: a start that finds it changed was superseded by a stop.
+  private lifecycle = 0
   private readonly sessionStore: SessionStore | undefined
   private readonly context: ContextWindow
   private readonly extensions: ExtensionHost | undefined
   readonly approvals: ApprovalManager
+  /** Approvals {@link resolveApproval} is settling; it forwards those itself, once the broker accepts. */
+  private readonly resolving = new Set<string>()
   private readonly verifyAfterTurn: readonly ("check" | "assure" | "test")[]
   private readonly maxRepairAttempts: number
   private readonly exposeErrorStacks: boolean
+  private readonly extensionChecks: ReadonlyMap<string, (event: AgentExtensionEvent) => boolean>
   private readonly verification:
     | Pick<VerificationOptions, "command" | "commandArgs" | "timeoutMs" | "maxOutputBytes" | "env">
     | undefined
@@ -72,7 +87,28 @@ export class CodingAgentHost {
     this.sessionStore = options.sessionStore
     this.context = new ContextWindow(options.contextWindow)
     this.extensions = options.extensions
-    this.approvals = new ApprovalManager(options.approvals)
+    const onResolved = options.approvals?.onResolved
+    this.approvals = new ApprovalManager({
+      ...options.approvals,
+      // A denial the broker reaches on its own (timeout, expiry, close) goes to the backend too, or a
+      // backend holding the approval open longer than the host could still act on it.
+      onResolved: async (decision) => {
+        const sessionId = this.session?.id
+        if (!decision.approved && !this.resolving.has(decision.approvalId) && sessionId) {
+          try {
+            await this.backend.resolveApproval?.(
+              sessionId,
+              decision.approvalId,
+              false,
+              decision.reason,
+            )
+          } catch {
+            // The broker's denial stands whether or not the backend still knew the approval.
+          }
+        }
+        await onResolved?.(decision)
+      },
+    })
     this.verifyAfterTurn = Object.freeze([...(options.verifyAfterTurn ?? [])])
     this.maxRepairAttempts = options.maxRepairAttempts ?? 2
     if (
@@ -83,11 +119,39 @@ export class CodingAgentHost {
       throw new RangeError("coding agent: maxRepairAttempts must be between 0 and 8")
     this.exposeErrorStacks = options.exposeErrorStacks === true
     this.verification = options.verification
+    const checks = new Map<string, (event: AgentExtensionEvent) => boolean>()
+    for (const [type, check] of Object.entries(options.extensionEvents ?? {})) {
+      if (!isAgentExtensionEventType(type))
+        throw new TypeError(`coding agent: extension event type must be x-<vendor>.<name>: ${type}`)
+      if (typeof check !== "function")
+        throw new TypeError(`coding agent: the check for ${type} must be a function`)
+      checks.set(type, check)
+    }
+    this.extensionChecks = checks
   }
 
   async start(input: CreateSessionInput): Promise<AgentSessionSnapshot> {
-    if (this.session !== undefined) throw new Error("coding agent: a session is already active")
+    if (this.session !== undefined || this.starting !== undefined)
+      throw new Error("coding agent: a session is already active")
+    const starting = this.startSession(input, ++this.lifecycle)
+    this.starting = starting
+    try {
+      return await starting
+    } finally {
+      if (this.starting === starting) this.starting = undefined
+    }
+  }
+
+  private async startSession(
+    input: CreateSessionInput,
+    generation: number,
+  ): Promise<AgentSessionSnapshot> {
     const created = await this.backend.createSession(input)
+    if (generation !== this.lifecycle) {
+      await this.backend.cancel(created.id, "host stopped").catch(() => {})
+      await this.backend.close(created.id).catch(() => {})
+      throw new Error("coding agent: the host stopped while the session was starting")
+    }
     this.session = created
     try {
       let history: readonly import("./sessions.ts").SessionLogEntry[] = []
@@ -100,6 +164,8 @@ export class CodingAgentHost {
       this.nextSeq = nextSequence(created, history)
       await this.extensions?.reload()
       await this.sessionStore?.append(created.id, "session.started", created)
+      if (generation !== this.lifecycle)
+        throw new Error("coding agent: the host stopped while the session was starting")
       return created
     } catch (error) {
       // Session creation may allocate a process or other external resource. If history, extension
@@ -157,13 +223,11 @@ export class CodingAgentHost {
 
   private acceptBackendEvent(rawEvent: unknown): AgentEvent {
     const session = this.requireSession()
-    if (!isAgentEvent(rawEvent) || rawEvent.sessionId !== session.id) {
-      return this.createEvent({
-        type: "session.failed",
-        error: agentError("BACKEND_PROTOCOL", "backend emitted an invalid agent event"),
-        recoverable: false,
-      })
-    }
+    // agentEventProblem re-walks the event, so it runs only once the event is known to be bad.
+    if (!isAgentEvent(rawEvent))
+      return this.protocolFailure(agentEventProblem(rawEvent) ?? "event is invalid")
+    const problem = this.acceptedEventProblem(rawEvent, session.id)
+    if (problem !== undefined) return this.protocolFailure(problem)
     const event = Object.freeze({
       ...rawEvent,
       sessionId: session.id,
@@ -210,6 +274,28 @@ export class CodingAgentHost {
     return event
   }
 
+  private protocolFailure(problem: string): AgentEvent {
+    return this.createEvent({
+      type: "session.failed",
+      error: agentError("BACKEND_PROTOCOL", `backend emitted an invalid agent event: ${problem}`),
+      recoverable: false,
+    })
+  }
+
+  private acceptedEventProblem(event: AgentEvent, sessionId: string): string | undefined {
+    if (event.sessionId !== sessionId) return "sessionId is not this session's"
+    if (!isExtensionEvent(event)) return undefined
+    const check = this.extensionChecks.get(event.type)
+    if (check === undefined) return undefined
+    let accepted = false
+    try {
+      accepted = check(event) === true
+    } catch {
+      accepted = false
+    }
+    return accepted ? undefined : `${event.type} failed its registered check`
+  }
+
   private async verifyTurn(): Promise<{
     readonly events: readonly AgentEvent[]
     readonly tasks: readonly VerificationRepairTask[]
@@ -376,6 +462,9 @@ export class CodingAgentHost {
   }
 
   async stop(reason = "stopped"): Promise<void> {
+    // A start still in flight is superseded: wait for it to roll its session back.
+    this.lifecycle++
+    await this.starting?.catch(() => {})
     if (this.session === undefined) return
     const id = this.session.id
     this.session = undefined
@@ -420,10 +509,19 @@ export class CodingAgentHost {
     approved: boolean,
     reason?: string,
   ): Promise<ApprovalDecision | undefined> {
+    // The broker decides first: an approval it no longer holds (unknown, expired, already settled,
+    // or bound to a coordinate) never reaches the backend.
+    this.resolving.add(approvalId)
+    let decision: ApprovalDecision | undefined
+    try {
+      decision = this.approvals.resolve(approvalId, approved, reason)
+    } finally {
+      this.resolving.delete(approvalId)
+    }
+    if (decision === undefined) return undefined
     if (this.session !== undefined && this.backend.resolveApproval !== undefined)
-      await this.backend.resolveApproval(this.session.id, approvalId, approved, reason)
-    const decision = this.approvals.resolve(approvalId, approved, reason)
-    if (decision !== undefined && this.session !== undefined)
+      await this.backend.resolveApproval(this.session.id, approvalId, decision.approved, reason)
+    if (this.session !== undefined)
       await this.sessionStore?.append(this.session.id, "approval.resolved", decision, {
         pinned: true,
       })
@@ -517,8 +615,14 @@ function boundedHostToken(value: unknown): value is string {
   return typeof value === "string" && /^[A-Za-z0-9._:/-]{1,128}$/.test(value)
 }
 
+function isExtensionEvent(event: AgentEvent): event is AgentExtensionEvent {
+  return isAgentExtensionEventType(event.type)
+}
+
 /** Default session evidence is content-free; live protocol consumers still receive the full event. */
 function eventEvidence(event: AgentEvent): unknown {
+  // An extension event's data is the backend's own content; evidence keeps only where it belongs.
+  if (isExtensionEvent(event)) return event.turnId === undefined ? {} : { turnId: event.turnId }
   switch (event.type) {
     case "session.started":
     case "session.updated":
@@ -533,7 +637,25 @@ function eventEvidence(event: AgentEvent): unknown {
       return { turnId: event.turnId }
     case "assistant.delta":
     case "assistant.message":
+    case "reasoning.delta":
       return { turnId: event.turnId }
+    case "plan.updated":
+      return {
+        turnId: event.turnId,
+        entries: event.entries.length,
+        completed: event.entries.filter((entry) => entry.status === "completed").length,
+      }
+    case "context.usage": {
+      const {
+        version: _version,
+        sessionId: _sessionId,
+        seq: _seq,
+        at: _at,
+        type: _type,
+        ...counts
+      } = event
+      return counts
+    }
     case "tool.started":
       return { turnId: event.turnId, callId: event.callId, name: event.name }
     case "tool.delta":

package/src/index.ts

@@ -153,6 +153,7 @@ export {
 export {
   createVerificationRepairTask,
   isSafeReviewDiff,
+  isVerificationAvailable,
   type ReviewExecutionErrorCode,
   type ReviewExecutionResult,
   type ReviewOptions,

package/src/native.ts

@@ -5,17 +5,21 @@ import {
   structuredOutputParser,
 } from "@nifrajs/agent"
 import {
+  AGENT_MAX_PAYLOAD_STRING,
   type AgentBackend,
   type AgentBackendInfo,
   type AgentEvent,
   type AgentEventStream,
   type AgentSessionSnapshot,
   agentError,
+  boundAgentText,
+  boundAgentValue,
   type CreateSessionInput,
   createAgentEventStream,
   isAgentEvent,
   type ReloadResult,
   type SendMessageInput,
+  splitAgentText,
 } from "@nifrajs/agent-protocol"
 
 export interface NativeMessage {
@@ -49,6 +53,18 @@ export type NativeModelResponse =
 
 export type NativeModelChunk =
   | { readonly type: "text_delta"; readonly text: string }
+  | { readonly type: "reasoning_delta"; readonly text: string; readonly itemId?: string }
+  /** Token counts for the request; becomes a `context.usage` event. */
+  | {
+      readonly type: "usage"
+      readonly usedTokens: number
+      readonly windowTokens?: number
+      readonly inputTokens?: number
+      readonly outputTokens?: number
+      readonly cachedInputTokens?: number
+      readonly reasoningTokens?: number
+      readonly estimated?: boolean
+    }
   | { readonly type: "response"; readonly response: NativeModelResponse }
 
 export interface NativeModelPort {
@@ -122,7 +138,14 @@ export interface NifraBackendOptions {
   /** Maximum time a protocol-visible native approval may remain unresolved. */
   readonly approvalTimeoutMs?: number
   readonly maxSteps?: number
+  /** Longest message `send` accepts (default 64 KiB). */
   readonly maxMessageChars?: number
+  /**
+   * Longest reply the model may give in one turn (default 1 MiB); past it the reply is cut with
+   * a marker. A reply longer than one event's text travels as consecutive `assistant.message`
+   * events, and the model's history keeps it whole.
+   */
+  readonly maxReplyChars?: number
   /**
    * Character budget for the conversation a session sends to the model (default 1 MiB). Past it,
    * whole earlier turns are dropped, oldest first; the current turn is always sent in full.
@@ -186,7 +209,7 @@ export class NifraBackend implements AgentBackend {
     capabilities: Object.freeze(["sessions", "extensions", "reload", "approvals", "streaming"]),
   })
   private readonly options: Required<
-    Pick<NifraBackendOptions, "maxSteps" | "maxMessageChars" | "maxHistoryChars">
+    Pick<NifraBackendOptions, "maxSteps" | "maxMessageChars" | "maxReplyChars" | "maxHistoryChars">
   > &
     NifraBackendOptions
   private readonly sessions = new Map<string, NativeSession>()
@@ -197,6 +220,7 @@ export class NifraBackend implements AgentBackend {
       ...options,
       maxSteps: options.maxSteps ?? 32,
       maxMessageChars: options.maxMessageChars ?? 64 * 1024,
+      maxReplyChars: options.maxReplyChars ?? 1024 * 1024,
       maxHistoryChars: options.maxHistoryChars ?? 1024 * 1024,
       tools: Object.freeze([...(options.tools ?? [])]),
     })
@@ -208,6 +232,8 @@ export class NifraBackend implements AgentBackend {
       throw new RangeError("nifra backend: maxSteps must be between 1 and 512")
     if (!Number.isSafeInteger(this.options.maxMessageChars) || this.options.maxMessageChars < 256)
       throw new RangeError("nifra backend: maxMessageChars must be at least 256")
+    if (!Number.isSafeInteger(this.options.maxReplyChars) || this.options.maxReplyChars < 256)
+      throw new RangeError("nifra backend: maxReplyChars must be at least 256")
     if (!Number.isSafeInteger(this.options.maxHistoryChars) || this.options.maxHistoryChars < 256)
       throw new RangeError("nifra backend: maxHistoryChars must be at least 256")
     if (
@@ -387,9 +413,10 @@ export class NifraBackend implements AgentBackend {
       return
     }
     this.update(session, "running", turnId)
-    this.emit(session, { type: "turn.started", turnId, prompt: message })
-    this.remember(session, { role: "user", text: message })
     try {
+      // The event carries a display copy; the model gets the whole message.
+      this.emit(session, { type: "turn.started", turnId, prompt: boundAgentText(message) })
+      this.remember(session, { role: "user", text: message })
       for (let step = 0; step < this.options.maxSteps; step++) {
         this.assertCurrentTurn(session, stream, turnId, signal)
         this.trimHistory(session)
@@ -409,9 +436,10 @@ export class NifraBackend implements AgentBackend {
         const response = await this.consumeModel(raw, session, stream, turnId, signal)
         this.assertCurrentTurn(session, stream, turnId, signal)
         if (response.type === "text") {
-          const text = boundedText(response.text, this.options.maxMessageChars)
+          const text = boundedText(response.text, this.options.maxReplyChars)
           this.remember(session, { role: "assistant", text })
-          this.emit(session, { type: "assistant.message", turnId, text })
+          for (const piece of splitAgentText(text))
+            this.emit(session, { type: "assistant.message", turnId, text: piece })
           this.finish(session, stream)
           return
         }
@@ -421,22 +449,28 @@ export class NifraBackend implements AgentBackend {
             type: "tool.completed",
             turnId,
             callId: crypto.randomUUID(),
-            name: response.name,
+            name: boundedApprovalToken(response.name) ? response.name : "unknown",
             ok: false,
-            error: agentError("UNKNOWN_TOOL", `unknown native tool: ${response.name}`),
+            error: agentError(
+              "UNKNOWN_TOOL",
+              boundAgentText(`unknown native tool: ${response.name}`, 512),
+            ),
           })
           this.remember(session, { role: "tool", name: response.name, text: "unknown tool" })
           continue
         }
         const callId = crypto.randomUUID()
         const execute = tool.execute
-        this.emit(session, {
+        // The event carries a display copy; the approval and the tool get the whole input.
+        const started: ToolStartedPayload = {
           type: "tool.started",
           turnId,
           callId,
           name: tool.name,
-          input: response.input,
-        })
+        }
+        const shown = boundAgentValue(response.input)
+        if (shown !== undefined) started.input = shown
+        this.emit(session, started)
         const needsApproval =
           typeof tool.requiresApproval === "function"
             ? await tool.requiresApproval(response.input)
@@ -477,14 +511,12 @@ export class NifraBackend implements AgentBackend {
             callId,
             name: tool.name,
             ok: true,
-            output: text,
+            output: boundAgentText(text, AGENT_MAX_PAYLOAD_STRING),
           })
         } catch (error) {
           if (signal.aborted || !this.isCurrentTurn(session, stream, turnId, signal)) throw error
-          const message = boundedText(
-            error instanceof Error ? error.message : error,
-            this.options.maxMessageChars,
-          )
+          const message =
+            boundedText(error instanceof Error ? error.message : error) || "native tool failed"
           this.remember(session, { role: "tool", name: tool.name, text: message })
           this.emit(session, {
             type: "tool.completed",
@@ -492,7 +524,7 @@ export class NifraBackend implements AgentBackend {
             callId,
             name: tool.name,
             ok: false,
-            error: agentError("TOOL_FAILED", message),
+            error: agentError("TOOL_FAILED", boundAgentText(message)),
           })
         }
       }
@@ -511,7 +543,10 @@ export class NifraBackend implements AgentBackend {
         type: "session.failed",
         error: agentError(
           "NATIVE_TURN_FAILED",
-          boundedText(error instanceof Error ? error.message : error, 4_096),
+          boundAgentText(
+            boundedText(error instanceof Error ? error.message : error, 4_096) ||
+              "native turn failed",
+          ),
         ),
         recoverable: true,
       })
@@ -529,11 +564,30 @@ export class NifraBackend implements AgentBackend {
   ): Promise<NativeModelResponse> {
     if (isAsyncIterable<NativeModelChunk>(raw)) {
       let response: NativeModelResponse | undefined
+      // Streamed text stops where the final reply is cut, so the deltas never outgrow it.
+      let room = this.options.maxReplyChars
       for await (const chunk of raw) {
         this.assertCurrentTurn(session, stream, turnId, signal)
-        if (chunk.type === "text_delta")
-          this.emit(session, { type: "assistant.delta", turnId, text: chunk.text })
-        else response = chunk.response
+        if (chunk.type === "response") {
+          response = chunk.response
+          continue
+        }
+        if (chunk.type === "reasoning_delta") {
+          const itemId = isEventToken(chunk.itemId) ? { itemId: chunk.itemId } : {}
+          for (const piece of splitAgentText(chunk.text))
+            this.emit(session, { type: "reasoning.delta", turnId, ...itemId, text: piece })
+          continue
+        }
+        if (chunk.type === "usage") {
+          const usage = nativeUsage(chunk)
+          if (usage !== undefined) this.emit(session, { type: "context.usage", turnId, ...usage })
+          continue
+        }
+        if (room <= 0) continue
+        const text = chunk.text.slice(0, room)
+        room -= text.length
+        for (const piece of splitAgentText(text))
+          this.emit(session, { type: "assistant.delta", turnId, text: piece })
       }
       if (response === undefined) throw new Error("native model stream ended without a response")
       this.assertCurrentTurn(session, stream, turnId, signal)
@@ -692,7 +746,7 @@ export class NifraBackend implements AgentBackend {
       return
     const stream = session.active
     const turnId = session.turnId
-    const stopReason = boundedText(reason, 512) || "cancelled"
+    const stopReason = boundAgentText(boundedText(reason, 512) || "cancelled")
     session.cancelled = true
     this.clearTurnSignal(session)
     try {
@@ -812,6 +866,14 @@ export class NifraBackend implements AgentBackend {
   }
 }
 
+interface ToolStartedPayload {
+  type: "tool.started"
+  turnId: string
+  callId: string
+  name: string
+  input?: unknown
+}
+
 function messageChars(message: NativeMessage): number {
   return message.text.length + (message.name?.length ?? 0)
 }
@@ -875,3 +937,38 @@ function removeActiveTurn(
   const { activeTurnId: _activeTurnId, ...withoutActiveTurn } = snapshot
   return withoutActiveTurn
 }
+
+function isEventToken(value: unknown): value is string {
+  return typeof value === "string" && /^[A-Za-z0-9._:/-]{1,128}$/.test(value)
+}
+
+const USAGE_COUNTS = [
+  "windowTokens",
+  "inputTokens",
+  "outputTokens",
+  "cachedInputTokens",
+  "reasoningTokens",
+] as const
+
+type NativeUsage = {
+  -readonly [Key in keyof Omit<Extract<NativeModelChunk, { type: "usage" }>, "type">]: Extract<
+    NativeModelChunk,
+    { type: "usage" }
+  >[Key]
+}
+
+// A model port is application code; a count it gets wrong is dropped, never a failed turn.
+function nativeUsage(chunk: Extract<NativeModelChunk, { type: "usage" }>): NativeUsage | undefined {
+  if (!isTokenCount(chunk.usedTokens)) return undefined
+  const usage: NativeUsage = { usedTokens: chunk.usedTokens }
+  for (const key of USAGE_COUNTS) {
+    const count = chunk[key]
+    if (isTokenCount(count)) usage[key] = count
+  }
+  if (chunk.estimated === true) usage.estimated = true
+  return usage
+}
+
+function isTokenCount(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+}

package/src/orchestration/dispatch.ts

@@ -15,7 +15,11 @@ export const DISPATCH_JOB_NAME = "nifra.agent.run-node"
 export const MAX_DISPATCH_STRING = 256
 export const MAX_DISPATCH_ATTEMPTS = 16
 
-export type DispatchBoundary = "before-effect" | "after-effect"
+/**
+ * `before-effect`: no side effect has happened, so a redelivery may run the effect. `effect-started`:
+ * the effect was invoked and may have acted, so a redelivery needs a proof. `after-effect`: it acted.
+ */
+export type DispatchBoundary = "before-effect" | "effect-started" | "after-effect"
 export type DispatchState =
   | "queued"
   | "leased"
@@ -300,7 +304,7 @@ export function parseRunCheckpoint(value: unknown): RunCheckpoint {
   if (input.version !== RUN_DISPATCH_VERSION)
     throw new TypeError("run checkpoint.version is unsupported")
   const boundary = input.boundary
-  if (boundary !== "before-effect" && boundary !== "after-effect")
+  if (boundary !== "before-effect" && boundary !== "effect-started" && boundary !== "after-effect")
     throw new TypeError("run checkpoint.boundary is invalid")
   return Object.freeze({
     version: RUN_DISPATCH_VERSION,

package/src/orchestration/evidence-store.ts

@@ -10,6 +10,7 @@
  * evidence only, and the file store persists exactly the content-free record it parsed.
  */
 
+import { createHash } from "node:crypto"
 import { appendFile } from "node:fs/promises"
 import type { ArtifactRef, RunEvidence } from "@nifrajs/agent-protocol"
 import { assertEvidenceSize, parseRunEvidence } from "@nifrajs/agent-protocol"
@@ -41,12 +42,10 @@ export interface EvidenceStore {
 }
 
 const DEFAULT_MAX_LIVE = 1024
-const encoder = new TextEncoder()
 
-async function sha256Bytes(text: string): Promise<Uint8Array> {
-  const digest = await crypto.subtle.digest("SHA-256", encoder.encode(text))
-  return new Uint8Array(digest)
-}
+// Synchronous: `crypto.subtle` hands every record to a worker thread and back, which on a loaded
+// machine made a 10k-record run take seconds.
+const sha256Bytes = (text: string): Uint8Array => createHash("sha256").update(text).digest()
 
 /**
  * The identity of one record for the terminal digest: node outcome only. `seq`, `durationMs`, and
@@ -97,7 +96,7 @@ class EvidenceAccumulator {
     } else this.failedCount++
     if (record.artifacts !== undefined)
       for (const ref of record.artifacts) this.artifactRefs.push(ref)
-    const hash = await sha256Bytes(digestKey(record))
+    const hash = sha256Bytes(digestKey(record))
     let carry = 0
     for (let i = 31; i >= 0; i--) {
       const sum = (this.acc[i] as number) + (hash[i] as number) + carry