@spunto/build 0.21.1 → 0.23.0

package/src/agent-stream/draft.ts

@@ -0,0 +1,156 @@
+// What the agent is writing *right now*, before it has finished saying it.
+//
+// The vocabulary (`agent-stream.ts`) is made of finished facts: a message lands once, whole. A
+// harness that streams tokens says the same message a second time, piecemeal, ahead of it —
+// Claude's `stream_event` lines (`includePartialMessages` in the Agent SDK,
+// `--include-partial-messages` on the CLI). Those pieces are **not events**: storing one row per
+// token would bury a session under thousands of rows that the finished message then repeats in
+// full. So they fold into one transient value instead — the draft — which the finished message
+// replaces the moment it lands, and which nothing persists.
+//
+// Pure like the rest of the package: lines in, draft out. Where the draft is kept between two
+// reads (memory, for the API) is the caller's business.
+
+import type { AgentProtocol } from "./agent-stream"
+
+/** The text block being written. `null` = nothing in flight. */
+export type AgentDraft = { text: string; truncated: boolean }
+
+/**
+ * Same ceiling as a stored `message` (`clip` in `agent-stream.ts`): a draft that ran past what
+ * the finished message will keep would visibly shrink the instant it lands.
+ */
+const MAX_DRAFT = 8_000
+
+function append(draft: AgentDraft | null, text: string): AgentDraft {
+  const base = draft ?? { text: "", truncated: false }
+  if (base.truncated) return base
+  const next = base.text + text
+  return next.length > MAX_DRAFT ? { text: next.slice(0, MAX_DRAFT), truncated: true } : { text: next, truncated: false }
+}
+
+/** Claude's dialects print token deltas; Codex's prints the message so far on `item.updated`; the contract, `message.delta`. */
+function streamsPartials(protocol: AgentProtocol): boolean {
+  return (
+    protocol === "agent-v1" ||
+    protocol === "claude-runner" ||
+    protocol === "claude-stream" ||
+    protocol === "claude-json" ||
+    protocol === "codex-runner"
+  )
+}
+
+/** What closes a draft in the contract: the finished text, or anything that comes after it in the turn. */
+const CLOSES_DRAFT = new Set(["message", "thinking", "tool.call", "tool.result", "session.ended"])
+
+/**
+ * The contract (`agent-v1`): `message.delta` with `start` opens a fresh draft, without it grows the
+ * one in flight. The runner already chose what is a draft (a subagent's words are not), so this
+ * only folds — whichever harness it was.
+ */
+function foldContract(lines: string[], draft: AgentDraft | null): AgentDraft | null {
+  let current = draft
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith("{")) continue
+    // Cheap pre-filter, before parsing a line that may carry megabytes.
+    if (!trimmed.includes('"message') && !trimmed.includes('"thinking"') && !trimmed.includes('"tool.') && !trimmed.includes('"session.ended"')) continue
+    let obj: Record<string, unknown>
+    try {
+      const parsed = JSON.parse(trimmed)
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue
+      obj = parsed as Record<string, unknown>
+    } catch {
+      continue
+    }
+    if (obj.type === "message.delta" && typeof obj.text === "string") {
+      current = append(obj.start === true ? null : current, obj.text)
+    } else if (typeof obj.type === "string" && CLOSES_DRAFT.has(obj.type)) {
+      current = null
+    }
+  }
+  return current
+}
+
+/**
+ * Codex: an `agent_message` item carries its whole text so far, not a delta — `item.started` and
+ * `item.updated` *are* the draft, `item.completed` (stored as the `message`) or the end of the
+ * turn closes it. Whether the SDK sends updates of a message mid-write is its business; the runner
+ * prints every event it gets, so this costs nothing when it does not.
+ */
+function foldCodex(lines: string[], draft: AgentDraft | null): AgentDraft | null {
+  let current = draft
+  for (const line of lines) {
+    const trimmed = line.trim()
+    if (!trimmed.startsWith("{")) continue
+    if (!trimmed.includes('"agent_message"') && !trimmed.includes('"turn.')) continue
+    let obj: Record<string, unknown>
+    try {
+      const parsed = JSON.parse(trimmed)
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue
+      obj = parsed as Record<string, unknown>
+    } catch {
+      continue
+    }
+    if (obj.type === "turn.completed" || obj.type === "turn.failed") {
+      current = null
+      continue
+    }
+    const item = (obj.item ?? {}) as Record<string, unknown>
+    if (item.type !== "agent_message") continue
+    if (obj.type === "item.completed") current = null
+    else if ((obj.type === "item.started" || obj.type === "item.updated") && typeof item.text === "string")
+      current = item.text ? append(null, item.text) : null
+  }
+  return current
+}
+
+/**
+ * Fold whole lines of a session's stdout into the draft, starting from `draft` (the value left
+ * by the previous read). Lines that say nothing about the text in flight leave it as it was.
+ *
+ *  - a text block starting opens a fresh draft — one draft is one block, as one stored `message`
+ *    is one block;
+ *  - a `text_delta` grows it;
+ *  - the finished `assistant` message, or the turn's `result`, closes it: from there on the
+ *    timeline has the real thing.
+ *
+ * A subagent's partials (`parent_tool_use_id` set) are skipped: what it writes is not what the
+ * session says to the reader, and interleaving it would garble the draft of the main thread.
+ */
+export function foldDraft(protocol: AgentProtocol, lines: string[], draft: AgentDraft | null): AgentDraft | null {
+  if (!streamsPartials(protocol)) return null
+  if (protocol === "agent-v1") return foldContract(lines, draft)
+  if (protocol === "codex-runner") return foldCodex(lines, draft)
+  let current = draft
+  for (const line of lines) {
+    const trimmed = line.trim()
+    // Cheap pre-filter: most lines are not about the draft, and some carry megabytes.
+    if (!trimmed.startsWith("{")) continue
+    if (!trimmed.includes('"stream_event"') && !trimmed.includes('"assistant"') && !trimmed.includes('"result"')) continue
+    let obj: Record<string, unknown>
+    try {
+      const parsed = JSON.parse(trimmed)
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue
+      obj = parsed as Record<string, unknown>
+    } catch {
+      continue
+    }
+    if (obj.parent_tool_use_id) continue
+
+    if (obj.type === "assistant" || obj.type === "result") {
+      current = null
+      continue
+    }
+    if (obj.type !== "stream_event") continue
+    const event = (obj.event ?? {}) as Record<string, unknown>
+    if (event.type === "content_block_start") {
+      const block = (event.content_block ?? {}) as Record<string, unknown>
+      if (block.type === "text") current = append(null, typeof block.text === "string" ? block.text : "")
+    } else if (event.type === "content_block_delta") {
+      const delta = (event.delta ?? {}) as Record<string, unknown>
+      if (delta.type === "text_delta" && typeof delta.text === "string") current = append(current, delta.text)
+    }
+  }
+  return current
+}

package/src/agent-stream/index.ts

@@ -33,6 +33,9 @@ export {
   TASK_EVENT_TYPES,
   userTurnLine,
 } from "./agent-stream"
+// The text block a streaming harness is still writing — folded from its partial messages, never stored.
+export { foldDraft } from "./draft"
+export type { AgentDraft } from "./draft"
 // 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"