@spunto/build 0.11.0 → 0.13.0

package/README.md

@@ -12,6 +12,8 @@ on*.
 npm install @spunto/build
 ```
 
+**Documentation: https://spunto.net/documentation/packages/build**
+
 ## What's in it
 
 ### `@spunto/build/steps` — the build-log protocol

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/build",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Spunto's shared Build engine — the devcontainer image protocol and VS Code extension registry clients, with no database, no HTTP framework and no UI.",
   "type": "module",
   "license": "MIT",

package/src/agent-stream/agent-stream.ts

@@ -20,6 +20,7 @@
  */
 
 import { contextWindowOf } from "./model-window"
+import { claudeTurnLimit } from "./turn-limit"
 
 export const AGENT_PROTOCOLS = ["none", "claude-json", "claude-stream", "jsonl"] as const
 export type AgentProtocol = (typeof AGENT_PROTOCOLS)[number]
@@ -39,7 +40,10 @@ export const TASK_EVENT_TYPES = [
   // { scope: "call" | "session", model?, inputTokens?, outputTokens?, cacheReadTokens?,
   //   cacheCreationTokens?, contextTokens?, costUsd?, turns?, durationMs? } — see `summarizeUsage`
   "usage",
-  "session.ended",   // { status, stopReason?, summary? }
+  // { status, stopReason?, summary?, limit? } — `limit` ({ kind, status, message, resetsAt }) when
+  // the turn ended because the account hit a usage/rate limit or the API was overloaded, see
+  // `turn-limit.ts`
+  "session.ended",
   // { tasks: [{ id, kind, description }] } — what the harness still runs in the background, whole
   "session.background",
   "raw",             // anything an adapter could not place
@@ -122,6 +126,37 @@ export function interruptLine(protocol: AgentProtocol, requestId: string): strin
   return `${JSON.stringify({ type: "control_request", request_id: requestId, request: { subtype: "interrupt" } })}\n`
 }
 
+/**
+ * Ask the harness to **name the conversation**, or null for a dialect that cannot be asked.
+ *
+ * Claude Code used to do this on its own within seconds of the first turn, headless included —
+ * that title is what `sessionTitleProbe` reads. Measured on 2.1.296 (October 2026), it no longer
+ * does for a session driven over `--input-format stream-json`: the transcript gets `atis-latch`
+ * and `last-prompt` lines and never an `ai-title`, so every task kept its placeholder. What it
+ * still answers is the SDK's own `generate_session_title` control request — the call its
+ * TypeScript SDK makes — with `{"title":…}` in a `control_response` on stdout, and `persist`
+ * writes the same `ai-title` line to the transcript as before.
+ *
+ * Asking is not naming: the harness still picks the words, from the human's prompt (the
+ * `description`), exactly as it would have unprompted. Nothing of ours ends up in the title.
+ *
+ * The request id carries `TITLE_REQUEST_PREFIX` so the answer can be told apart from every other
+ * `control_response` (an interrupt's, say) without keeping state between write and read.
+ */
+export function sessionTitleRequestLine(protocol: AgentProtocol, requestId: string, description: string): string | null {
+  if (protocol !== "claude-stream") return null
+  const text = description.trim()
+  if (!text) return null
+  return `${JSON.stringify({
+    type: "control_request",
+    request_id: `${TITLE_REQUEST_PREFIX}${requestId}`,
+    request: { subtype: "generate_session_title", description: text, persist: true },
+  })}\n`
+}
+
+/** Marks the `control_request`s that ask for a title, and so the `control_response`s that answer. */
+const TITLE_REQUEST_PREFIX = "spunto-title-"
+
 /**
  * A shell that prints the line where the harness wrote **the name it gave the conversation**, or
  * null for a dialect that has no such thing.
@@ -143,6 +178,9 @@ export function interruptLine(protocol: AgentProtocol, requestId: string): strin
  * `--no-session-persistence` writes no transcript, and then this finds nothing — which is a
  * normal answer, not an error.
  *
+ * Since Claude Code 2.1.296 an interactive session only writes that line once asked
+ * (`sessionTitleRequestLine`); a one-shot `claude-json` run has no stdin to be asked on.
+ *
  * `jsonl` gets no probe on purpose: a harness speaking our vocabulary says the name in band,
  * `{"type":"session.title","title":"…"}`, and pays nothing for it.
  */
@@ -341,6 +379,13 @@ function adaptClaudeJson(obj: Record<string, unknown>): NormalizedEvent[] {
         }
       }
     }
+    // The synthetic message Claude Code writes when the API refused the call carries the one
+    // structured reset time of a usage limit; the `result` that follows does not. Kept on the
+    // message so ingestion can carry it over to the turn's end (`stampLimitReset`).
+    if (type === "assistant") {
+      const limit = claudeTurnLimit(obj)
+      if (limit) for (const e of events) if (e.type === "message") e.payload.limit = limit
+    }
     // What the call that produced this message cost, and how full the context was when it ran.
     // Only assistant messages carry it — a `user` line is tool results being handed back.
     if (type === "assistant") {
@@ -374,21 +419,39 @@ function adaptClaudeJson(obj: Record<string, unknown>): NormalizedEvent[] {
       {
         type: "session.ended",
         payload: {
-          status: obj.subtype === "success" ? "succeeded" : "failed",
+          // `is_error` too: a turn the API refused (a usage limit, measured) still says
+          // `subtype: "success"` — it is the *harness* that ended cleanly, not the turn.
+          status: obj.subtype === "success" && obj.is_error !== true ? "succeeded" : "failed",
           stopReason: typeof obj.stop_reason === "string" ? obj.stop_reason : null,
           summary: clip(obj.result).text,
+          ...limitField(obj),
         },
       },
     ]
     return events
   }
 
+  // The answer to `sessionTitleRequestLine`. Only ours, recognised by request id: a
+  // `control_response` is also how an interrupt is acknowledged, and that one is no name.
+  if (type === "control_response") {
+    const response = (obj.response ?? {}) as Record<string, unknown>
+    const inner = (response.response ?? {}) as Record<string, unknown>
+    const requestId = typeof response.request_id === "string" ? response.request_id : ""
+    const title = response.subtype === "success" && requestId.startsWith(TITLE_REQUEST_PREFIX) ? cleanTitle(inner.title) : null
+    if (title) return [{ type: "session.title", payload: { title } }]
+  }
+
   // Known-but-uninteresting (`rate_limit_event`, `system/thinking_tokens`) and anything the CLI
   // grows next land here rather than being dropped: an unknown event is information about the
   // harness, and the UI keeps it behind a toggle.
   return [{ type: "raw", payload: { json: obj } }]
 }
 
+function limitField(obj: Record<string, unknown>): { limit?: ReturnType<typeof claudeTurnLimit> } {
+  const limit = claudeTurnLimit(obj)
+  return limit ? { limit } : {}
+}
+
 function num(value: unknown): number | null {
   return typeof value === "number" && Number.isFinite(value) ? value : null
 }

package/src/agent-stream/index.ts

@@ -25,11 +25,16 @@ export {
   parseStreamLine,
   readsTitleOutOfBand,
   sessionTitleProbe,
+  sessionTitleRequestLine,
   splitCompleteLines,
   summarizeUsage,
   TASK_EVENT_TYPES,
   userTurnLine,
 } from "./agent-stream"
+// Turns that ended on a usage/rate limit rather than on finished work, and when the limit lifts.
+export { claudeTurnLimit, resetFromText, TURN_LIMIT_KINDS } from "./turn-limit"
+export type { TurnLimit, TurnLimitKind } from "./turn-limit"
+
 export type {
   AgentProtocol,
   NormalizedEvent,

package/src/agent-stream/turn-limit.ts

@@ -0,0 +1,197 @@
+/**
+ * A turn that ended because the **account** ran out, not because the work did.
+ *
+ * Measured on 2026-10-17, when every running task of an org stopped within the same three minutes:
+ * Claude Code ends the turn with a `result` that says `subtype: "success"` — and, next to it,
+ * `is_error: true`, `api_error_status: 429`, `api_error: "usage_limit_reached"` and, as `result`,
+ * the sentence the terminal would have printed (« You've hit your session limit · resets 9pm
+ * (UTC) »). Read as a success, that put every task in review as if it had finished, and someone
+ * had to type "continue" into each conversation once the quota came back.
+ *
+ * Three kinds, because they do not wait the same way:
+ *
+ *  - `usage` — the plan's quota (five-hour session limit, weekly limit, out of extra usage). Comes
+ *    back at a time the harness usually knows (`resetsAt`), and not a minute before;
+ *  - `rate` — a 429 that is not a quota: a burst limit on an API key. Seconds to minutes;
+ *  - `overloaded` — the API's 529. The CLI already retried on its own before giving up, so this
+ *    is a "later", not a "never".
+ *
+ * Anything else that ends a turn on an API error (a 401, a 500, an invalid request) is **not** a
+ * limit: waiting would not fix it, and pretending it might would hide it behind a countdown.
+ *
+ * Pure functions: the clock is always a parameter.
+ */
+
+export const TURN_LIMIT_KINDS = ["usage", "rate", "overloaded"] as const
+export type TurnLimitKind = (typeof TURN_LIMIT_KINDS)[number]
+
+export type TurnLimit = {
+  kind: TurnLimitKind
+  /** The HTTP status the harness reported, when it did (429, 529). */
+  status: number | null
+  /** What the harness said, as it said it — shown to a human, never parsed again. */
+  message: string
+  /** When the limit lifts, ISO 8601, if the line said so in a form we can trust. */
+  resetsAt: string | null
+}
+
+const USAGE_TEXT =
+  /usage limit|session limit|weekly limit|opus limit|(?:5|five)[- ]hour limit|limit reached|out of extra usage|hit your limit/i
+const RATE_TEXT = /rate[ _-]?limit|too many requests|\b429\b/i
+const OVERLOADED_TEXT = /overloaded|\b529\b/i
+
+/**
+ * The limit a Claude Code stream line reports, or null.
+ *
+ * Read off three shapes, all recorded on 2026-10-17 (see `turn-limit.test.ts`):
+ *
+ *  - the `result` that ends the turn — what decides the task, but it carries no reset time;
+ *  - the synthetic assistant message just before it (`model: "<synthetic>"`,
+ *    `is_api_error_message: true`), which does: `api_error_params.rate_limit_info.resetsAt`,
+ *    in unix seconds;
+ *  - the older single-string form, `Claude AI usage limit reached|<unix seconds>`.
+ *
+ * A `result` that is not an error is never a limit, whatever its text says: an agent that writes
+ * "I hit the rate limit of the GitHub API" in its summary has finished its turn.
+ */
+export function claudeTurnLimit(obj: Record<string, unknown>): TurnLimit | null {
+  if (obj.type === "result") {
+    const failed = obj.is_error === true || (typeof obj.subtype === "string" && obj.subtype !== "success")
+    if (!failed) return null
+    return classify({
+      status: num(obj.api_error_status),
+      code: str(obj.api_error),
+      text: str(obj.result) ?? "",
+      resetsAt: null,
+    })
+  }
+
+  if (obj.type === "assistant") {
+    const message = (obj.message ?? {}) as Record<string, unknown>
+    const synthetic = obj.is_api_error_message === true || message.model === "<synthetic>"
+    if (!synthetic) return null
+    const params = (obj.api_error_params ?? {}) as Record<string, unknown>
+    const info = (params.rate_limit_info ?? {}) as Record<string, unknown>
+    const content = Array.isArray(message.content) ? message.content : []
+    const text = content
+      .map((b) => (b && typeof b === "object" && (b as Record<string, unknown>).type === "text" ? str((b as Record<string, unknown>).text) : null))
+      .filter(Boolean)
+      .join("\n")
+    return classify({
+      status: num(obj.api_error_status),
+      code: str(obj.api_error) ?? str(obj.error),
+      text,
+      resetsAt: epochToIso(info.resetsAt),
+    })
+  }
+
+  return null
+}
+
+function classify(input: { status: number | null; code: string | null; text: string; resetsAt: string | null }): TurnLimit | null {
+  const { status, code, text } = input
+  // The old one-line form carries its own reset: `Claude AI usage limit reached|1760000000`.
+  const piped = /\|(\d{10})\s*$/.exec(text)
+  const message = (piped ? text.slice(0, piped.index) : text).trim().slice(0, 500)
+  const resetsAt = input.resetsAt ?? (piped ? epochToIso(Number(piped[1])) : null)
+
+  let kind: TurnLimitKind | null = null
+  if (code === "usage_limit_reached" || USAGE_TEXT.test(text)) kind = "usage"
+  else if (status === 529 || code === "overloaded_error" || OVERLOADED_TEXT.test(text)) kind = "overloaded"
+  else if (status === 429 || code === "rate_limit" || code === "rate_limit_error" || RATE_TEXT.test(text)) kind = "rate"
+  if (!kind) return null
+  return { kind, status, message, resetsAt }
+}
+
+/**
+ * When the limit lifts, read out of the sentence the harness printed — « resets 9pm (UTC) »,
+ * « resets 9:30pm (Europe/Paris) », « resets Oct 20, 5am (UTC) » — relative to `now` (the moment
+ * the line was written, not the moment it is read).
+ *
+ * The fallback for a turn whose structured reset time we never saw. A time with no date is the
+ * next one at or after `now`; a zone we cannot resolve is a null, not a guess — a countdown to the
+ * wrong hour is worse than "unknown", which the caller already knows how to wait out.
+ */
+export function resetFromText(text: string, now: Date): string | null {
+  const m =
+    /resets?\s+(?:at\s+)?(?:([A-Za-z]{3,9})\.?\s+(\d{1,2}),?\s+(?:at\s+)?)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\s*(?:\(([^)]+)\))?/i.exec(text)
+  if (!m) return null
+  const [, monthName, dayText, hourText, minuteText, meridiem, zoneText] = m
+  let hour = Number(hourText)
+  const minute = minuteText ? Number(minuteText) : 0
+  if (!meridiem && !minuteText) return null // « resets 3 » is not a time
+  if (meridiem) {
+    if (hour < 1 || hour > 12) return null
+    hour = (hour % 12) + (meridiem.toLowerCase() === "pm" ? 12 : 0)
+  }
+  if (hour > 23 || minute > 59) return null
+  const zone = zoneText?.trim() || "UTC"
+  if (!isZone(zone)) return null
+
+  const today = partsIn(now.getTime(), zone)
+  if (monthName && dayText) {
+    const month = MONTHS.indexOf(monthName.slice(0, 3).toLowerCase())
+    if (month < 0) return null
+    // Same year, unless that date is already well behind us — then it is next year's.
+    let at = zonedToUtc(today.year, month, Number(dayText), hour, minute, zone)
+    if (at < now.getTime() - 24 * 3600_000) at = zonedToUtc(today.year + 1, month, Number(dayText), hour, minute, zone)
+    return new Date(at).toISOString()
+  }
+  let at = zonedToUtc(today.year, today.month, today.day, hour, minute, zone)
+  if (at <= now.getTime()) at = zonedToUtc(today.year, today.month, today.day + 1, hour, minute, zone)
+  return new Date(at).toISOString()
+}
+
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"]
+
+function isZone(zone: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: zone })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Wall-clock fields of an instant in a zone. `month` is 0-based, like `Date.UTC`. */
+function partsIn(t: number, zone: string): { year: number; month: number; day: number; hour: number; minute: number } {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone: zone,
+    hourCycle: "h23",
+    year: "numeric",
+    month: "numeric",
+    day: "numeric",
+    hour: "numeric",
+    minute: "numeric",
+  }).formatToParts(new Date(t))
+  const get = (type: string) => Number(parts.find((p) => p.type === type)?.value ?? 0)
+  return { year: get("year"), month: get("month") - 1, day: get("day"), hour: get("hour"), minute: get("minute") }
+}
+
+/** The instant a wall-clock time in `zone` names. Two passes settle a DST edge. */
+function zonedToUtc(year: number, month: number, day: number, hour: number, minute: number, zone: string): number {
+  const wanted = Date.UTC(year, month, day, hour, minute)
+  let guess = wanted
+  for (let i = 0; i < 2; i++) {
+    const p = partsIn(guess, zone)
+    const seen = Date.UTC(p.year, p.month, p.day, p.hour, p.minute)
+    guess += wanted - seen
+  }
+  return guess
+}
+
+function epochToIso(value: unknown): string | null {
+  const n = num(value)
+  // Seconds since the epoch, sanity-bounded (2020 – 2100): a field that changed unit would
+  // otherwise produce a reset in 1970 or in the year 50 000.
+  if (n === null || n < 1_577_836_800 || n > 4_102_444_800) return null
+  return new Date(n * 1000).toISOString()
+}
+
+function num(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null
+}
+
+function str(value: unknown): string | null {
+  return typeof value === "string" && value ? value : null
+}