@nifrajs/coding-agent 4.0.2 → 5.1.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
@@ -125,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")
     }
   }
 
@@ -157,13 +232,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 +283,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 +471,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 +518,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 +624,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 +646,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

@@ -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"
@@ -153,6 +155,7 @@ export {
 export {
   createVerificationRepairTask,
   isSafeReviewDiff,
+  isVerificationAvailable,
   type ReviewExecutionErrorCode,
   type ReviewExecutionResult,
   type ReviewOptions,

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

@@ -5,18 +5,23 @@ 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"
+import { type ApprovalTimeout, isApprovalTimeout } from "./approvals.ts"
 
 export interface NativeMessage {
   readonly role: "user" | "assistant" | "tool"
@@ -49,6 +54,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 {
@@ -119,10 +136,21 @@ 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
+  /**
+   * 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.
@@ -152,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
 }
@@ -186,7 +214,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 +225,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,15 +237,17 @@ 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 (
       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> {
@@ -387,9 +418,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 +441,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 +454,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 +516,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 +529,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 +548,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 +569,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)
@@ -573,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,
@@ -692,7 +752,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 +872,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 +943,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
+}