@spunto/build 0.12.0 → 0.14.0

package/README.md

@@ -104,6 +104,22 @@ fields it has no feature for** — shared volumes are a Lite concept, the task s
 both optional. Dropping a field the target cannot honour is the correct outcome; refusing the file
 is not.
 
+**The project's prompt is a file of its own.** `taskAgentInstructions` is prose, and a JSON string
+is the worst place to read it. A spec may instead point at a sibling file
+(`taskAgentInstructionsFile: "prompt.md"`); a **bundle** is the spec plus what it points at, as a
+plain name → text map — zipping it, or picking both files at once, is the product's job.
+
+```ts
+import { buildProjectBundle, parseProjectBundle, projectBundleFilename } from "@spunto/build/spec"
+
+const files = buildProjectBundle(project)  // { "my-app.spunto-project.json": …, "prompt.md": … }
+const spec = parseProjectBundle(files)      // prompt back inline, as taskAgentInstructions
+```
+
+A project without a prompt is a one-file bundle whose spec is what `buildProjectSpec` writes, and a
+lone spec is a valid bundle — so every file exported before bundles existed imports as before. The
+inline `taskAgentInstructions` stays accepted too (it is what a single-JSON export writes).
+
 ### `@spunto/build/script` — turning a project spec into the shell a worker runs
 
 Four generators, one recipe: `buildImageScript` bakes the project image, `buildSetupScript` is the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/build",
-  "version": "0.12.0",
+  "version": "0.14.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
@@ -375,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") {
@@ -408,9 +419,12 @@ 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),
         },
       },
     ]
@@ -433,6 +447,11 @@ function adaptClaudeJson(obj: Record<string, unknown>): NormalizedEvent[] {
   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

@@ -31,6 +31,10 @@ export {
   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
+}

package/src/spec/index.ts

@@ -24,6 +24,15 @@
 // task settings are a Cloud one; both are optional, and importing a Cloud spec into Lite is
 // supposed to drop the task settings rather than fail. Losing a field the target cannot honour is
 // the correct outcome — refusing the file is not.
+//
+// **The prompt is a file of its own.** A project's agent prompt (`taskAgentInstructions`) is
+// prose — paragraphs, lists, code fences — and a JSON string is the worst place to read or edit
+// it. So a spec may *point* at it (`taskAgentInstructionsFile: "prompt.md"`) instead of holding it,
+// and a **bundle** is the spec plus the files it points at (`buildProjectBundle` /
+// `parseProjectBundle`). The bundle is a plain name → text map: how it is carried (a zip, two
+// files picked together, a folder in a repo) is the product's business, not this package's. The
+// inline form stays valid — it is what a single-file export writes, and every file written
+// before the pointer existed is a file with no prompt at all.
 
 import { z } from "zod"
 
@@ -102,6 +111,13 @@ export const SpecProjectSchema = z.object({
   taskCancelCommand: z.string().optional(),
   taskReviewMode: z.enum(["stop", "keep"]).optional(),
   taskAgentModel: z.string().optional(),
+  /** Spunto Cloud — what the project's task agents are told on top of the org's instruction. */
+  taskAgentInstructions: z.string().optional(),
+  /**
+   * The same prompt, as a sibling file of the bundle (`prompt.md`) rather than a string here.
+   * Resolved by `parseProjectBundle`; `parseProjectSpec` alone leaves it as a name.
+   */
+  taskAgentInstructionsFile: z.string().min(1).optional(),
 })
 
 export const ProjectSpecSchema = z.object({
@@ -160,3 +176,74 @@ export function parseProjectSpec(text: string): ProjectSpec {
       : "Not a Spunto project spec",
   )
 }
+
+/** Name of the prompt file in a bundle written by `buildProjectBundle`. */
+export const PROJECT_PROMPT_FILENAME = "prompt.md"
+
+/** A spec and the files it points at, by name. Text only — a bundle carries no binaries. */
+export type ProjectBundle = Record<string, string>
+
+/** Download filename for a project's bundle once zipped, e.g. `my-app.spunto-project.zip`. */
+export function projectBundleFilename(name: string): string {
+  return projectSpecFilename(name).replace(/\.json$/, ".zip")
+}
+
+/**
+ * The project as a bundle: its spec, plus the prompt as `prompt.md` when it has one.
+ *
+ * A project without a prompt is a one-file bundle whose spec is byte-for-byte what
+ * `buildProjectSpec` would have written — nothing changes for a reader that only knows the JSON.
+ */
+export function buildProjectBundle(project: SpecProject, now: Date = new Date()): ProjectBundle {
+  const { taskAgentInstructions, taskAgentInstructionsFile: _ignored, ...rest } = project
+  const specName = projectSpecFilename(project.name)
+  if (!taskAgentInstructions) return { [specName]: JSON.stringify(buildProjectSpec(rest, now), null, 2) + "\n" }
+  const spec = buildProjectSpec({ ...rest, taskAgentInstructionsFile: PROJECT_PROMPT_FILENAME }, now)
+  return {
+    [specName]: JSON.stringify(spec, null, 2) + "\n",
+    // A trailing newline, like any text file an editor saves; `parseProjectBundle` trims it back.
+    [PROJECT_PROMPT_FILENAME]: taskAgentInstructions.endsWith("\n") ? taskAgentInstructions : taskAgentInstructions + "\n",
+  }
+}
+
+/** `./prompt.md`, `dir/prompt.md` (a zip made from a folder) and `prompt.md` are the same file. */
+function bundleKey(path: string): string {
+  return path.replace(/\\/g, "/").split("/").filter((s) => s && s !== ".").pop() ?? ""
+}
+
+/**
+ * Reads a bundle back into a spec whose prompt, if any, is inline (`taskAgentInstructions`) and
+ * whose `taskAgentInstructionsFile` is gone — the shape a product creates a project from.
+ *
+ * The spec is the bundle's one `.json` file (a `*.spunto-project.json` wins if there are several);
+ * a lone spec is a valid bundle, which is what makes every file exported before bundles existed
+ * import exactly as before. Files are matched by base name, so a zip of a folder works too.
+ *
+ * Throws messages written for a toast, like `parseProjectSpec`.
+ */
+export function parseProjectBundle(bundle: ProjectBundle): ProjectSpec {
+  const files = new Map<string, string>()
+  for (const [path, text] of Object.entries(bundle)) {
+    const key = bundleKey(path)
+    // macOS archives carry `__MACOSX/._x` shadows of every file; they are never what was meant.
+    if (key && !key.startsWith("._") && !path.includes("__MACOSX")) files.set(key, text)
+  }
+
+  const jsons = [...files.keys()].filter((k) => k.toLowerCase().endsWith(".json"))
+  const preferred = jsons.filter((k) => k.toLowerCase().endsWith(".spunto-project.json"))
+  const candidates = preferred.length ? preferred : jsons
+  if (candidates.length === 0) throw new Error("No project spec (.json) in what was imported")
+  if (candidates.length > 1) throw new Error(`Several project specs to choose from: ${candidates.join(", ")}`)
+
+  const spec = parseProjectSpec(files.get(candidates[0])!)
+  const { taskAgentInstructionsFile: ref, ...project } = spec.project
+  if (!ref) return spec
+
+  const text = files.get(bundleKey(ref))
+  if (text === undefined) {
+    throw new Error(`The spec's prompt is in ${ref}, which was not imported with it — pick both files, or the .zip`)
+  }
+  // The file wins over an inline copy: it is the one a human edits.
+  const prompt = text.replace(/\s+$/, "")
+  return { ...spec, project: { ...project, ...(prompt ? { taskAgentInstructions: prompt } : {}) } }
+}