@nifrajs/coding-agent 4.0.0 → 5.0.0

package/src/sessions.ts

@@ -57,6 +57,9 @@ export class FileSessionStore implements SessionStore {
   private readonly maxEntries: number
   private readonly maxBytes: number
   private readonly sequences = new Map<string, number>()
+  // Entries and bytes in each session file this store has written, so an append under the caps
+  // needs no read of the log to know it.
+  private readonly tallies = new Map<string, { entries: number; bytes: number }>()
   private readonly locks = new Map<string, Promise<void>>()
 
   constructor(options: FileSessionStoreOptions) {
@@ -109,14 +112,21 @@ export class FileSessionStore implements SessionStore {
       if (Buffer.byteLength(line, "utf8") > this.maxEntryBytes)
         throw new RangeError("session store: event exceeds maxEntryBytes")
       const path = this.pathFor(sessionId)
+      const tally = await this.tallyOf(sessionId)
       const file = await openSessionFile(path, O_APPEND | O_CREAT | O_WRONLY, 0o600)
       try {
         await file.writeFile(`${line}\n`, "utf8")
+      } catch (error) {
+        this.tallies.delete(sessionId)
+        throw error
       } finally {
         await file.close()
       }
+      tally.entries += 1
+      tally.bytes += Buffer.byteLength(line, "utf8") + 1
       this.sequences.set(sessionId, nextSeq)
-      await this.compactIfNeeded(sessionId)
+      if (tally.entries > this.maxEntries || tally.bytes > this.maxBytes)
+        await this.compact(sessionId, tally)
       return entry
     })
   }
@@ -173,6 +183,7 @@ export class FileSessionStore implements SessionStore {
         mode: 0o600,
       })
       this.sequences.set(targetSessionId, Math.max(0, lines.length - 1))
+      this.tallies.delete(targetSessionId)
       return targetSessionId
     })
   }
@@ -188,40 +199,63 @@ export class FileSessionStore implements SessionStore {
     return (entries.at(-1)?.seq ?? -1) + 1
   }
 
-  private async compactIfNeeded(sessionId: string): Promise<void> {
+  /** The session file's tally, read once: its size, and how many entries its bounded tail holds. */
+  private async tallyOf(sessionId: string): Promise<{ entries: number; bytes: number }> {
+    const cached = this.tallies.get(sessionId)
+    if (cached !== undefined) return cached
+    const tally = { entries: 0, bytes: 0 }
     const path = this.pathFor(sessionId)
-    const file = await openSessionFile(path, O_RDONLY)
-    let size: number
     try {
-      size = (await file.stat()).size
-    } finally {
-      await file.close()
-    }
-    if (size <= this.maxBytes) {
-      const recent = parseSessionEntries(
-        await this.readTailText(path, this.maxEntries + 1, this.maxBytes),
+      const file = await openSessionFile(path, O_RDONLY)
+      try {
+        tally.bytes = (await file.stat()).size
+      } finally {
+        await file.close()
+      }
+      tally.entries = parseSessionEntries(
+        await this.readTailText(path, this.maxEntries + 1, this.maxBytes + this.maxEntryBytes),
         sessionId,
-      )
-      if (recent.length <= this.maxEntries) return
+      ).length
+    } catch (error) {
+      if (!isNotFound(error)) throw error
     }
+    this.tallies.set(sessionId, tally)
+    return tally
+  }
+
+  /**
+   * Rewrite the log down to a low-water mark below both caps, so the next rewrite is a quarter of the
+   * caps of appends away rather than the very next append.
+   */
+  private async compact(
+    sessionId: string,
+    tally: { entries: number; bytes: number },
+  ): Promise<void> {
+    const path = this.pathFor(sessionId)
     // The tail read is bounded by the retention cap plus one maximum-sized line. This keeps
     // compaction memory bounded even if a pre-existing log is already oversized.
     const recent = parseSessionEntries(
       await this.readTailText(path, this.maxEntries + 1, this.maxBytes + this.maxEntryBytes),
       sessionId,
     )
-    const retained = retainEntries(recent, this.maxEntries, this.maxBytes)
+    const retained = retainEntries(
+      recent,
+      Math.max(1, Math.floor((this.maxEntries * 3) / 4)),
+      Math.max(Math.floor((this.maxBytes * 3) / 4), this.maxEntryBytes + 1),
+    )
     if (retained.length === 0) return
     const content = `${retained.map((entry) => JSON.stringify(entry)).join("\n")}\n`
-    if (Buffer.byteLength(content, "utf8") >= size && size <= this.maxBytes) return
     const temporary = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`
     await writeFile(temporary, content, { encoding: "utf8", flag: "wx", mode: 0o600 })
     try {
       await rename(temporary, path)
     } catch (error) {
       await unlink(temporary).catch(() => {})
+      this.tallies.delete(sessionId)
       throw error
     }
+    tally.entries = retained.length
+    tally.bytes = Buffer.byteLength(content, "utf8")
     this.sequences.set(sessionId, retained.at(-1)!.seq)
   }
 
@@ -237,17 +271,19 @@ export class FileSessionStore implements SessionStore {
       let remaining = Math.min(size, maxBytes)
       const chunks: Buffer[] = []
       const chunkBytes = 64 * 1024
+      let newlines = 0
       while (remaining > 0) {
         const take = Math.min(remaining, chunkBytes)
         end -= take
         const bytes = Buffer.allocUnsafe(take)
         const result = await file.read(bytes, 0, take, end)
-        chunks.unshift(bytes.subarray(0, result.bytesRead))
+        const chunk = bytes.subarray(0, result.bytesRead)
+        chunks.unshift(chunk)
         remaining -= result.bytesRead
-        const text = Buffer.concat(chunks).toString("utf8")
-        const lines = text.split("\n")
-        const completeLines = end > 0 ? lines.length - 1 : lines.length
-        if (completeLines >= minimumLines || end === 0 || result.bytesRead === 0) return text
+        for (let at = chunk.indexOf(10); at !== -1; at = chunk.indexOf(10, at + 1)) newlines++
+        // Before the start of the file the first line may be partial, so it does not count.
+        const completeLines = end > 0 ? newlines : newlines + 1
+        if (completeLines >= minimumLines || end === 0 || result.bytesRead === 0) break
       }
       return Buffer.concat(chunks).toString("utf8")
     } finally {
@@ -309,7 +345,11 @@ export interface ContextWindowOptions {
   readonly summarize?: (records: readonly ContextRecord[], maxChars: number) => string
 }
 
-/** In-memory prompt window with automatic, deterministic compaction and a hard size ceiling. */
+/**
+ * In-memory prompt window with automatic, deterministic compaction and a hard size ceiling. Pinned
+ * and authoritative records survive compaction, newest first, within half of `maxTokens`; older ones
+ * are folded into the summary like any other record. The session store keeps every one of them.
+ */
 export class ContextWindow {
   private readonly maxTokens: number
   private readonly keepRecent: number
@@ -361,19 +401,21 @@ export class ContextWindow {
     if (this.records.length <= this.keepRecent) return { before, after: before, removed: 0, reason }
     // A compacted summary is replaceable context, not authoritative evidence. Keeping old pinned
     // summaries in `protectedRecords` would make every threshold compaction grow the live window.
-    const protectedRecords = this.records.filter(
-      (record) =>
-        record.kind !== "memory.summary" &&
-        (record.pinned === true || isAuthoritative(record.kind)),
+    const protectedRecords = newestWithin(
+      this.records.filter(
+        (record) =>
+          record.kind !== "memory.summary" &&
+          (record.pinned === true || isAuthoritative(record.kind)),
+      ),
+      Math.floor(this.maxTokens / 2),
     )
     const recent = this.records.slice(-this.keepRecent)
     const retained = new Set([...protectedRecords, ...recent])
     const omitted = this.records.filter((record) => !retained.has(record))
     if (omitted.length === 0) return { before, after: before, removed: 0, reason }
-    const summary = this.summarizeRecord(omitted, this.maxSummaryChars).slice(
-      0,
-      this.maxSummaryChars,
-    )
+    // A summary longer than the window it lives in would defeat the window.
+    const summaryChars = Math.min(this.maxSummaryChars, this.maxTokens)
+    const summary = this.summarizeRecord(omitted, summaryChars).slice(0, summaryChars)
     this.records = [
       ...protectedRecords,
       { kind: "memory.summary", content: summary, pinned: true },
@@ -456,6 +498,33 @@ function isSessionLogEntry(value: unknown, sessionId: string): value is SessionL
   )
 }
 
+/**
+ * A row `migrateLegacySession` wrote: the same identity and order, with the event type as `code` and
+ * no payload. Read as an entry of that type, so a host pointed at a migrated directory keeps the
+ * history and continues its sequence.
+ */
+function evidenceEntry(value: unknown, sessionId: string): SessionLogEntry | undefined {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return undefined
+  const field = (key: string): unknown => Reflect.get(value, key)
+  const seq = field("seq")
+  const at = field("at")
+  const code = field("code")
+  if (
+    field("version") !== 1 ||
+    field("sessionId") !== sessionId ||
+    typeof seq !== "number" ||
+    !Number.isSafeInteger(seq) ||
+    typeof at !== "number" ||
+    typeof code !== "string" ||
+    field("count") !== 1 ||
+    typeof field("digest") !== "string" ||
+    "type" in value
+  )
+    return undefined
+  const entry = { version: 1, sessionId, seq, at, type: code } as const
+  return field("pinned") === true ? { ...entry, pinned: true } : entry
+}
+
 function parseSessionEntries(text: string, sessionId: string): SessionLogEntry[] {
   const entries: SessionLogEntry[] = []
   for (const line of text.split("\n")) {
@@ -463,6 +532,10 @@ function parseSessionEntries(text: string, sessionId: string): SessionLogEntry[]
     try {
       const value: unknown = JSON.parse(line)
       if (isSessionLogEntry(value, sessionId)) entries.push(Object.freeze(value))
+      else {
+        const migrated = evidenceEntry(value, sessionId)
+        if (migrated !== undefined) entries.push(Object.freeze(migrated))
+      }
     } catch {
       // A tail read can begin in the middle of an old line. Invalid records are ignored so a
       // damaged/partially rotated log cannot turn every history request into an unbounded retry.
@@ -517,6 +590,19 @@ function estimateTokens(records: readonly ContextRecord[]): number {
   )
 }
 
+/** The newest `records` whose estimated tokens fit `budget`, in their original order; at least one. */
+function newestWithin(records: readonly ContextRecord[], budget: number): ContextRecord[] {
+  const kept: ContextRecord[] = []
+  let tokens = 0
+  for (let index = records.length - 1; index >= 0; index--) {
+    const record = records[index]!
+    tokens += estimateTokens([record])
+    if (tokens > budget && kept.length > 0) break
+    kept.unshift(record)
+  }
+  return kept
+}
+
 function isAuthoritative(kind: string): boolean {
   return (
     kind.startsWith("approval") || kind.startsWith("verification") || kind === "session.checkpoint"

package/src/subagents.ts

@@ -214,8 +214,17 @@ export class BoundedSubagentRunner {
             error: "subagent workspace is not in an allowed root",
           }
       }
-      if (this.options.workspace?.isolatedWorktree !== undefined) {
-        workspace = await this.options.workspace.isolatedWorktree(spec, controller.signal)
+      const isolatedWorktree = this.options.workspace?.isolatedWorktree
+      if (isolatedWorktree !== undefined) {
+        // The deadline covers acquiring the workspace too. A lease that lands after it is released
+        // without any work starting in it.
+        const acquiring = Promise.resolve().then(() => isolatedWorktree(spec, controller.signal))
+        try {
+          workspace = await untilAborted(acquiring, controller.signal, stopped)
+        } catch (error) {
+          if (controller.signal.aborted) acquiring.then((late) => late.cleanup?.()).catch(() => {})
+          throw error
+        }
       } else if (requestedCwd !== undefined) {
         workspace = { cwd: requestedCwd }
       }

package/src/turn-replay.ts

@@ -0,0 +1,151 @@
+export interface TurnReplayLimits {
+  readonly maxEvents: number
+  readonly maxBytes: number
+}
+
+interface HeldFrame {
+  readonly seq: number
+  readonly bytes: Uint8Array
+}
+
+interface TurnListener {
+  frame(bytes: Uint8Array): void
+  end(terminal: Uint8Array | undefined): void
+}
+
+/**
+ * One `turn.send`'s SSE frames, held so a client that dropped can read what it missed and follow
+ * the rest. Cursors are the host's event seqs; one older than what is held needs a resync.
+ */
+export class ReplayableTurn {
+  private readonly held: HeldFrame[] = []
+  private heldBytes = 0
+  private droppedThrough: number
+  private lastSeq: number
+  private ended = false
+  private terminal: Uint8Array | undefined
+  private readonly listeners = new Set<TurnListener>()
+
+  /**
+   * @param startedAfter the last seq before this turn: a cursor there reads the whole turn.
+   * @param onListeners told how many clients follow the turn whenever that changes while it runs.
+   */
+  constructor(
+    private readonly startedAfter: number,
+    private readonly limits: TurnReplayLimits,
+    private readonly onListeners: (count: number) => void,
+  ) {
+    this.droppedThrough = startedAfter
+    this.lastSeq = startedAfter
+  }
+
+  get done(): boolean {
+    return this.ended
+  }
+
+  get latestSeq(): number {
+    return this.lastSeq
+  }
+
+  get following(): number {
+    return this.listeners.size
+  }
+
+  push(seq: number, frame: Uint8Array): void {
+    if (this.ended) return
+    this.held.push({ seq, bytes: frame })
+    this.heldBytes += frame.byteLength
+    this.lastSeq = seq
+    // The newest frame always stays, even past maxBytes, so a client can follow a large event.
+    while (
+      this.held.length > this.limits.maxEvents ||
+      (this.heldBytes > this.limits.maxBytes && this.held.length > 1)
+    ) {
+      const dropped = this.held.shift()
+      if (dropped === undefined) break
+      this.heldBytes -= dropped.bytes.byteLength
+      this.droppedThrough = dropped.seq
+    }
+    for (const listener of [...this.listeners]) {
+      try {
+        listener.frame(frame)
+      } catch {
+        this.detach(listener)
+      }
+    }
+  }
+
+  end(terminal?: Uint8Array): void {
+    if (this.ended) return
+    this.ended = true
+    this.terminal = terminal
+    const listeners = [...this.listeners]
+    this.listeners.clear()
+    for (const listener of listeners) {
+      try {
+        listener.end(terminal)
+      } catch {
+        // That client already went away.
+      }
+    }
+  }
+
+  /**
+   * The frames after `afterSeq` (the whole turn when omitted), then the live ones until the turn
+   * ends. `undefined` when the cursor is older than what is held, or newer than any frame sent.
+   */
+  attach(afterSeq?: number): ReadableStream<Uint8Array> | undefined {
+    const cursor = afterSeq ?? this.startedAfter
+    if (cursor < this.droppedThrough || cursor > this.lastSeq) return undefined
+    return this.open(cursor)
+  }
+
+  /** The whole turn from its first frame; always available to the client that started it. */
+  follow(): ReadableStream<Uint8Array> {
+    return this.open(this.startedAfter)
+  }
+
+  private open(cursor: number): ReadableStream<Uint8Array> {
+    let listener: TurnListener | undefined
+    // The queue counts bytes, so it can tell a follower that stopped reading: one more than the held
+    // budget behind the held frames is dropped, and can attach again from the last seq it read.
+    const behind = -this.limits.maxBytes
+    return new ReadableStream<Uint8Array>(
+      {
+        start: (controller) => {
+          for (const frame of this.held) if (frame.seq > cursor) controller.enqueue(frame.bytes)
+          if (this.ended) {
+            if (this.terminal !== undefined) controller.enqueue(this.terminal)
+            controller.close()
+            return
+          }
+          listener = {
+            frame: (bytes) => {
+              if ((controller.desiredSize ?? 0) < behind) {
+                const reason = new Error("turn follower fell behind")
+                controller.error(reason)
+                throw reason
+              }
+              controller.enqueue(bytes)
+            },
+            end: (terminal) => {
+              if (terminal !== undefined) controller.enqueue(terminal)
+              controller.close()
+            },
+          }
+          this.listeners.add(listener)
+          this.onListeners(this.listeners.size)
+        },
+        cancel: () => {
+          if (listener !== undefined) this.detach(listener)
+        },
+      },
+      new ByteLengthQueuingStrategy({ highWaterMark: this.limits.maxBytes }),
+    )
+  }
+
+  private detach(listener: TurnListener): void {
+    if (!this.listeners.delete(listener) || this.ended) return
+    this.onListeners(this.listeners.size)
+  }
+}

package/src/ui.ts

@@ -91,47 +91,105 @@ export class UiExtensionHost {
   }
 }
 
+const UI_SLOTS: ReadonlySet<unknown> = new Set([
+  "sidebar",
+  "main",
+  "timeline",
+  "diff",
+  "workflow",
+  "status",
+])
+const UI_TONES: ReadonlySet<unknown> = new Set(["neutral", "positive", "warning", "danger"])
+const UI_DENSITIES: ReadonlySet<unknown> = new Set(["compact", "comfortable"])
+
+type Mutable<T> = { -readonly [K in keyof T]: T[K] }
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+const matches = (pattern: RegExp, value: unknown): value is string =>
+  typeof value === "string" && pattern.test(value)
+const isSlot = (value: unknown): value is UiExtensionSlot => UI_SLOTS.has(value)
+const isTone = (value: unknown): value is NonNullable<UiStatusWidget["tone"]> => UI_TONES.has(value)
+const isDensity = (value: unknown): value is NonNullable<UiThemeDescriptor["density"]> =>
+  UI_DENSITIES.has(value)
+
+// Manifests come from extension code, often parsed JSON: every field is type-checked, and only the
+// known fields are copied into the frozen result.
 function validateManifests(
-  manifests: readonly UiExtensionManifest[],
+  manifests: unknown,
   options: UiExtensionHostOptions & { readonly maxExtensions: number },
 ): readonly UiExtensionManifest[] {
+  if (!Array.isArray(manifests)) throw new Error("UI extension manifests must be an array")
   if (manifests.length > options.maxExtensions) throw new Error("ui extension limit exceeded")
   const trusted = new Set(options.trustedCapabilities ?? [])
   const ids = new Set<string>()
   return Object.freeze(
-    manifests.map((manifest) => {
-      if (!/^[a-z][a-z0-9._:-]{0,63}$/.test(manifest.id))
-        throw new Error(`invalid UI extension id: ${manifest.id}`)
-      if (!/^[a-zA-Z0-9._:-]{1,64}$/.test(manifest.revision))
-        throw new Error(`invalid UI extension revision: ${manifest.id}`)
-      if (!manifest.label || manifest.label.length > 120)
-        throw new Error(`invalid UI extension label: ${manifest.id}`)
-      if (manifest.theme !== undefined) {
-        if (!/^[a-z][a-z0-9._-]{0,31}$/.test(manifest.theme.name))
-          throw new Error(`invalid UI theme: ${manifest.id}`)
-        if (manifest.theme.accent !== undefined && !/^#[0-9a-fA-F]{6}$/.test(manifest.theme.accent))
-          throw new Error(`invalid UI theme accent: ${manifest.id}`)
+    manifests.map((manifest: unknown): UiExtensionManifest => {
+      if (!isRecord(manifest) || !matches(/^[a-z][a-z0-9._:-]{0,63}$/, manifest.id))
+        throw new Error("invalid UI extension id")
+      const id = manifest.id
+      const revision = manifest.revision
+      if (!matches(/^[a-zA-Z0-9._:-]{1,64}$/, revision))
+        throw new Error(`invalid UI extension revision: ${id}`)
+      const slot = manifest.slot
+      if (!isSlot(slot)) throw new Error(`invalid UI extension slot: ${id}`)
+      const label = manifest.label
+      if (typeof label !== "string" || label.length === 0 || label.length > 120)
+        throw new Error(`invalid UI extension label: ${id}`)
+      const capabilities = manifest.capabilities ?? []
+      if (
+        !Array.isArray(capabilities) ||
+        !capabilities.every((capability): capability is string => typeof capability === "string")
+      )
+        throw new Error(`invalid UI extension capabilities: ${id}`)
+      const result: Mutable<UiExtensionManifest> = {
+        id,
+        revision,
+        slot,
+        label,
+        capabilities: Object.freeze([...capabilities]),
       }
-      if (manifest.status !== undefined) {
-        if (!manifest.status.text || manifest.status.text.length > 160)
-          throw new Error(`invalid UI status widget: ${manifest.id}`)
-        if (
-          manifest.status.tone !== undefined &&
-          !["neutral", "positive", "warning", "danger"].includes(manifest.status.tone)
-        )
-          throw new Error(`invalid UI status tone: ${manifest.id}`)
-      }
-      if (ids.has(manifest.id)) throw new Error(`duplicate UI extension: ${manifest.id}`)
-      ids.add(manifest.id)
-      const denied = (manifest.capabilities ?? []).find((capability) => !trusted.has(capability))
+      if (manifest.theme !== undefined) result.theme = uiTheme(manifest.theme, id)
+      if (manifest.status !== undefined) result.status = uiStatus(manifest.status, id)
+      if (ids.has(id)) throw new Error(`duplicate UI extension: ${id}`)
+      ids.add(id)
+      const denied = capabilities.find((capability) => !trusted.has(capability))
       if (denied !== undefined)
-        throw new Error(`UI extension ${manifest.id} requires untrusted capability: ${denied}`)
-      return Object.freeze({
-        ...manifest,
-        capabilities: Object.freeze([...(manifest.capabilities ?? [])]),
-        ...(manifest.theme === undefined ? {} : { theme: Object.freeze({ ...manifest.theme }) }),
-        ...(manifest.status === undefined ? {} : { status: Object.freeze({ ...manifest.status }) }),
-      })
+        throw new Error(`UI extension ${id} requires untrusted capability: ${denied}`)
+      return Object.freeze(result)
     }),
   )
 }
+
+function uiTheme(value: unknown, id: string): UiThemeDescriptor {
+  if (!isRecord(value) || !matches(/^[a-z][a-z0-9._-]{0,31}$/, value.name))
+    throw new Error(`invalid UI theme: ${id}`)
+  const theme: Mutable<UiThemeDescriptor> = { name: value.name }
+  const { accent, density } = value
+  if (accent !== undefined) {
+    if (!matches(/^#[0-9a-fA-F]{6}$/, accent)) throw new Error(`invalid UI theme accent: ${id}`)
+    theme.accent = accent
+  }
+  if (density !== undefined) {
+    if (!isDensity(density)) throw new Error(`invalid UI theme density: ${id}`)
+    theme.density = density
+  }
+  return Object.freeze(theme)
+}
+
+function uiStatus(value: unknown, id: string): UiStatusWidget {
+  if (
+    !isRecord(value) ||
+    typeof value.text !== "string" ||
+    value.text.length === 0 ||
+    value.text.length > 160
+  )
+    throw new Error(`invalid UI status widget: ${id}`)
+  const status: Mutable<UiStatusWidget> = { text: value.text }
+  const tone = value.tone
+  if (tone !== undefined) {
+    if (!isTone(tone)) throw new Error(`invalid UI status tone: ${id}`)
+    status.tone = tone
+  }
+  return Object.freeze(status)
+}