@sjawhar/claude-envoy 1.18.0 → 1.19.0

package/src/agent-stream-runner.ts

@@ -0,0 +1,340 @@
+// The Agents page's live view of one Claude Code session (INFRA-1026): the mod's events as the
+// conversation, the two header frames read off the mod's own `$` calls, and the control subject a
+// viewer takes this session on. It is driven by the channel server (`./envoy-channel-server`),
+// which gives it the link and the session's NATS connection, and it reaches nothing of that
+// server's: a subject is a string, and every collaborator arrives as an option.
+import {
+  AGENT_STREAM_WATCH_INTERVAL_MS,
+  type AgentStreamCommand,
+  type AgentStreamControlMessage,
+  agentStreamControlSubject,
+  agentStreamFramesSubject,
+} from "@legion/contracts"
+import { messageFor } from "@legion/envoy-client/errors"
+import { AgentStreamPublisher } from "@legion/pi-shared/agent-stream"
+import type { ModConfigRow, ModEffort, ModEvent } from "../hooks/mod-protocol"
+import { claudeAgentStreamCommands, createClaudeAgentStream } from "./agent-stream-claude"
+import { rememberBounded } from "./bounded-set"
+import type { ChannelForwarderConnection, ChannelTopicSubscription } from "./channel-forwarder"
+import type { ModLink } from "./mod-link"
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+/** How long the live view waits for the mod to answer one of its reads (`$.session.model()`,
+ *  `$.config.list()`, `$.command.list()`). Each is served out of the session's own memory, so a
+ *  wait this long means the mod is gone rather than busy, and the header keeps its last values. */
+const AGENT_STREAM_CALL_TIMEOUT_MS = 5_000
+/** How long the live view waits before taking its control subject again after the subscription's
+ *  iterator ended, which is what a dropped connection looks like from here. */
+const AGENT_STREAM_RESUBSCRIBE_MS = 1_000
+
+/**
+ * The most row ids this stream remembers having read, so a row that arrives twice is read once.
+ *
+ * The mod reports every row it appends itself, because Claude Code does not re-enter a mod's
+ * own `session.append` hook for one (`../hooks/mod.ts`); a host that does fire that hook as
+ * well would send the row twice, and the view would draw it twice and the session would read
+ * the same `command` row twice (`./mod-session`). The two copies are a moment apart, so a few
+ * hundred ids is past any window one could cross, and the record is bounded (`rememberBounded`)
+ * rather than kept for the session's life.
+ */
+const AGENT_STREAM_SEEN_ROWS_MAX = 512
+
+export interface AgentStreamOptions {
+  /** The link to this session's Claude Code mod (`./mod-link`): its events are the conversation,
+   *  and its `$` calls are what the header's two frames are built from. */
+  readonly link: ModLink
+  /** The session's own NATS connection: the frames go out on it, and the control subject is
+   *  taken on it. The session's NATS user may already publish and subscribe to both. */
+  readonly connection: ChannelForwarderConnection
+  /** The session id the Agents page knows this session by, which both subjects name. */
+  readonly sessionId: string
+  /**
+   * Whether the stream follows the session id the mod reports. Claude Code mints a new one on
+   * `/clear` and the channel rebinds to it (`adoptHandoff`), so the two are the same id; under
+   * the `ENVOY_SESSION_ID` override the session registers a fixed id of its own and the Claude
+   * id names nothing Dispatch knows, so the stream stays where it started.
+   */
+  readonly followsSessionId: boolean
+  /** Whether this session is a Legion pane, whose first command the daemon's bridge writes
+   *  rather than a person (`./agent-stream-claude`, `PANE_SEEDED_COMMAND`). */
+  readonly isPane?: boolean
+  readonly now?: () => number
+  /** Where a failure that must not stop the session is written; the server's stderr by default. */
+  readonly warn?: (text: string) => void
+  /**
+   * Takes every event this stream reads, before the stream records it. The link's events have one
+   * consumer and this is it, so whatever else needs them - the router of a person's messages, and
+   * the turn tracking behind it - is handed them here.
+   */
+  readonly observe?: (event: ModEvent) => void
+  /** The Dispatch message a row of the conversation is, which tags that row so the Agents page
+   *  shows a person's own message once rather than beside its stored copy. */
+  readonly tagFor?: (row: string) => string | undefined
+  /** Whether a row of the `command` door is the echo row a `$.command.run` of this session's
+   *  claimed (`./mod-session`, `runsCommandRow`), asked by the row's own id: the view draws
+   *  nothing of it, since Claude Code echoes the command it ran rather than the one the person
+   *  sent. The order below is what makes it answer for the row being recorded - `observe`
+   *  hands the session each event before this stream records it. */
+  readonly runsCommandRow?: (row: string) => boolean
+  /** Whether a row of the `prompt` door is the row Claude Code wrote for this session's prompt
+   *  at the messages a turn never read (`./mod-session`, `runsUnreadPrompt`), asked by the
+   *  row's own id: the view draws nothing of it, since that prompt quotes rows it has already
+   *  drawn. Answered for the row being recorded by the same order `runsCommandRow` relies on. */
+  readonly runsUnreadPrompt?: (row: string) => boolean
+  /** Whether a row is the row one message this session was handed became (`./mod-session`,
+   *  `appendedRow`), asked by the row's own id: the one `isMeta` row the view draws, since a
+   *  card appended into the turn running is such a row and nothing else. Answered for the row
+   *  being recorded by the same order `runsCommandRow` relies on — the session takes the row's
+   *  event and claims it there, before the view records that event
+   *  (`./envoy-channel-server`). The claim rides on that event rather than on the answer of the
+   *  call that wrote the row, because the two cross: the mod holds an event behind a post
+   *  already in flight while a call's result goes out on a fetch of its own, so either can land
+   *  first (`../hooks/mod.ts`, `flush`). */
+  readonly appendedRow?: (row: string) => boolean
+}
+
+export interface AgentStreamRunner {
+  /** Stop answering the control subject. The mod's events end with the link itself. */
+  readonly stop: () => void
+  /** Read the session's model and levels again and publish them: a pick has just changed one,
+   *  and the header must show it before the reply naming it reaches the page. */
+  readonly refresh: () => void
+  /** The effort a person's pick put in force, shown by the header at once: Claude Code reports
+   *  an effort only on a request of its own, and an idle session makes none. */
+  readonly pickedEffort: (effort: ModEffort) => void
+}
+
+/**
+ * Publish this session's conversation for the Agents page's live view (INFRA-1026).
+ *
+ * The mod's events become messages on the shared publisher (`./agent-stream-claude`), and this
+ * answers the viewer's control subject the way every Oh My Pi session does (`packages/pi-envoy`,
+ * `pumpAgentStreamControl`): a message that is neither `replay` nor `watch` is ignored, the
+ * replay answer is taken before the message arms anything, so a bare replay from a client that
+ * never attached a viewer gets an empty history, and every message runs inside a guard, since
+ * one throw out of the iterator would leave the session deaf until the resubscribe.
+ *
+ * What differs from an Oh My Pi session is where the header's values come from. That host reads
+ * its model, its levels and its commands out of its own memory; here they are three calls on the
+ * mod, over a socket, which a session with no mod never answers. So a refresh is asked for and
+ * not waited on: a control message is answered from what the mod said last, and a changed answer
+ * reaches the viewer as its own frame a moment later. A session whose mod never connects
+ * publishes no settings and no commands, and its conversation stays empty.
+ */
+export function startAgentStream(options: AgentStreamOptions): AgentStreamRunner {
+  const { connection, link } = options
+  const now = options.now ?? Date.now
+  const warn =
+    options.warn ?? ((text: string): void => void process.stderr.write(`envoy-channel: ${text}\n`))
+  const publisher = new AgentStreamPublisher({
+    now,
+    publish: (subject, payload) => connection.publish(subject, encoder.encode(payload)),
+  })
+  const stream = createClaudeAgentStream({
+    isPane: options.isPane === true,
+    now,
+    publisher,
+    ...(options.appendedRow === undefined ? {} : { appendedRow: options.appendedRow }),
+    ...(options.runsCommandRow === undefined ? {} : { runsCommandRow: options.runsCommandRow }),
+    ...(options.runsUnreadPrompt === undefined
+      ? {}
+      : { runsUnreadPrompt: options.runsUnreadPrompt }),
+    ...(options.tagFor === undefined ? {} : { tagFor: options.tagFor }),
+  })
+  /** The id both subjects name now; it moves with the mod's own id after a `/clear`. */
+  let session = options.sessionId
+  let subscription: ChannelTopicSubscription | undefined
+  let stopped = false
+  /** What the mod last said of the session's model, its `/config` rows and its commands. They
+   *  survive a session id change: the process and its model do not change with the id. */
+  let model: string | undefined
+  let configRows: readonly ModConfigRow[] | undefined
+  let listedCommands: readonly AgentStreamCommand[] | undefined
+  let readingSettings = false
+  let readingCommands = false
+  /** Whether a viewer has ever armed this session, and when a watch last refreshed the commands:
+   *  both as the Oh My Pi pump keeps them. */
+  let viewerAttached = false
+  let commandsRefreshedOnWatchAt = Number.NEGATIVE_INFINITY
+  /** Whether the mod has said anything at all, which is when its reads are first worth making. */
+  let primed = false
+
+  /** The rows this stream has read, newest last and bounded by `AGENT_STREAM_SEEN_ROWS_MAX`:
+   *  what the duplicate guard below answers from. */
+  const seenRows = new Set<string>()
+
+  /** Whether this row has been read already, remembering it when it has not. Every event of the
+   *  link passes here, which is the one place both readers below are behind. */
+  const readTwice = (uuid: string): boolean => {
+    if (seenRows.has(uuid)) return true
+    rememberBounded(seenRows, uuid, AGENT_STREAM_SEEN_ROWS_MAX)
+    return false
+  }
+
+  const framesSubject = (): string => agentStreamFramesSubject(session)
+
+  const publishSettings = (): void => {
+    publisher.setSettings(framesSubject(), stream.settings(model, configRows))
+  }
+
+  const publishCommands = (): void => {
+    if (listedCommands !== undefined) publisher.setCommands(framesSubject(), listedCommands)
+  }
+
+  /** Read the session's model and its `/config` rows, and publish what they say. One read at a
+   *  time: a watch arrives every ten seconds and the answers rarely change. */
+  const refreshSettings = (): void => {
+    if (stopped || readingSettings || !link.connected()) return
+    readingSettings = true
+    void Promise.all([
+      link.request("session.model", undefined, { timeoutMs: AGENT_STREAM_CALL_TIMEOUT_MS }),
+      link.request("config.list", undefined, { timeoutMs: AGENT_STREAM_CALL_TIMEOUT_MS }),
+    ])
+      .then(([answeredModel, rows]) => {
+        model = answeredModel
+        configRows = rows
+        if (!stopped) publishSettings()
+      })
+      .catch((error: unknown) => {
+        warn(`the live view could not read this session's model — ${messageFor(error)}`)
+      })
+      .finally(() => {
+        readingSettings = false
+      })
+  }
+
+  const refreshCommands = (): void => {
+    if (stopped || readingCommands || !link.connected()) return
+    readingCommands = true
+    void link
+      .request("command.list", undefined, { timeoutMs: AGENT_STREAM_CALL_TIMEOUT_MS })
+      .then((commands) => {
+        listedCommands = claudeAgentStreamCommands(commands)
+        if (!stopped) publishCommands()
+      })
+      .catch((error: unknown) => {
+        warn(`the live view could not read this session's commands — ${messageFor(error)}`)
+      })
+      .finally(() => {
+        readingCommands = false
+      })
+  }
+
+  const pump = async (taken: ChannelTopicSubscription, forSession: string): Promise<void> => {
+    try {
+      for await (const message of taken) {
+        // Any client on the bus can publish here. A `null` payload parses cleanly and then
+        // throws on `.type`, and a reply over the server's max_payload throws out of the
+        // publish; either would end the iterator and take the session deaf with it.
+        try {
+          const parsed: unknown = JSON.parse(decoder.decode(message.data))
+          if (typeof parsed !== "object" || parsed === null) continue
+          const request = parsed as AgentStreamControlMessage
+          if (request.type !== "replay" && request.type !== "watch") continue
+          refreshSettings()
+          if (
+            request.type === "replay" ||
+            !viewerAttached ||
+            now() - commandsRefreshedOnWatchAt >= AGENT_STREAM_WATCH_INTERVAL_MS
+          ) {
+            refreshCommands()
+            if (request.type === "watch" && viewerAttached) commandsRefreshedOnWatchAt = now()
+          }
+          // Taken before this message arms anything, so a bare replay from a client that never
+          // attached a viewer gets an empty history rather than the ring.
+          const reply = message.reply
+          const answer =
+            request.type === "replay" && reply !== undefined
+              ? JSON.stringify(publisher.replay(forSession))
+              : undefined
+          const arming = !publisher.watched
+          publisher.noteViewer()
+          viewerAttached = true
+          if (arming) publisher.publishState(agentStreamFramesSubject(forSession))
+          if (answer === undefined || reply === undefined) continue
+          connection.publish(reply, encoder.encode(answer))
+        } catch (error) {
+          warn(`a live view control message failed — ${messageFor(error)}`)
+        }
+      }
+    } catch {
+      // A dead iterator is a dropped connection, taken again below.
+    }
+    if (subscription === taken) subscription = undefined
+    if (stopped || session !== forSession) return
+    const retry = setTimeout(() => {
+      if (stopped || session !== forSession) return
+      subscribe()
+    }, AGENT_STREAM_RESUBSCRIBE_MS)
+    retry.unref()
+  }
+
+  function subscribe(): void {
+    if (stopped) return
+    subscription?.unsubscribe()
+    const taken = connection.subscribe(agentStreamControlSubject(session))
+    subscription = taken
+    void pump(taken, session)
+  }
+
+  // A `/clear` ends the conversation and the process goes on under a new id: the ring holds the
+  // previous one, and a viewer opening the new id must not be served it.
+  link.onSessionId((next: string) => {
+    if (stopped || !options.followsSessionId || next === session) return
+    session = next
+    publisher.reset()
+    stream.reset()
+    viewerAttached = false
+    commandsRefreshedOnWatchAt = Number.NEGATIVE_INFINITY
+    // `reset` dropped the two header frames with the conversation; what the mod already said
+    // still holds, so they are put back under the new id rather than read again.
+    publishSettings()
+    publishCommands()
+    subscribe()
+  })
+
+  const reading = (async (): Promise<void> => {
+    for await (const event of link.events) {
+      if (!primed) {
+        primed = true
+        refreshSettings()
+        refreshCommands()
+      }
+      // A row that has been read already is read no second time, whoever sent it twice
+      // (`AGENT_STREAM_SEEN_ROWS_MAX`).
+      if (event.kind === "append" && readTwice(event.uuid)) continue
+      if (event.kind === "model") model = event.model
+      // Before the stream records it: an event can be the row a person's message turned out to
+      // be, and that row is tagged with the message it is.
+      options.observe?.(event)
+      stream.record(framesSubject(), event)
+      // A step is the one event that can change the thinking level, and the model event is the
+      // mod's own report of a model change: neither is worth a read of the mod to notice.
+      if (event.kind === "step" || event.kind === "model") publishSettings()
+    }
+  })()
+  void reading.catch((error: unknown) => {
+    warn(`the live view stopped reading this session's events — ${messageFor(error)}`)
+  })
+
+  subscribe()
+
+  return {
+    refresh(): void {
+      refreshSettings()
+    },
+    pickedEffort(effort: ModEffort): void {
+      if (stopped) return
+      stream.pickedEffort(effort)
+      publishSettings()
+    },
+    stop(): void {
+      if (stopped) return
+      stopped = true
+      subscription?.unsubscribe()
+      subscription = undefined
+    },
+  }
+}

package/src/bounded-set.ts

@@ -0,0 +1,54 @@
+// The bounded, insertion-ordered records this plugin keeps (INFRA-1026): a session remembers
+// several things for its whole life — the rows it claimed, the deliveries it answered, the
+// attempts it handled, the Dispatch message each delivered row is — and each drops its oldest
+// entry at a bound of its own. Two shapes carry them, a `Set` for a record that is its values
+// alone and a `Map` for one that holds a value beside its key, and the rule is written once here
+// in each, so a fix to how the oldest is dropped is made once.
+//
+// What is not here is a queue: a list of work still in flight, where the oldest entry is dropped
+// as the cap that keeps a reply nobody sent from growing for ever, not as the record of
+// something seen. `user-turn-router`'s `awaited` is the one such list, and it drops its own with
+// `shift()` where it is kept.
+
+/**
+ * Remember `value`, dropping the oldest entries until the record is back inside `max`.
+ *
+ * A `Set` iterates in insertion order, so its first entry is the one added longest ago, and
+ * adding a value the set already holds leaves that order alone. The caller names `max`, which is
+ * what each record's own bound says; the loop also holds a record that is already past a bound
+ * to it.
+ */
+export function rememberBounded(remembered: Set<string>, value: string, max: number): void {
+  remembered.add(value)
+  while (remembered.size > max) {
+    const oldest = remembered.values().next().value
+    // A non-empty `Set` always yields one, and `max` is never below zero in this package; the
+    // check is what keeps a bound of a different shape from looping here forever.
+    if (oldest === undefined) break
+    remembered.delete(oldest)
+  }
+}
+
+/**
+ * Remember `key` as `value`, dropping the oldest entries until the record is back inside `max`.
+ *
+ * The `Map`-shaped record's rule, for one that holds a value beside its key: the Dispatch
+ * message each delivered row is (`./user-turn-state`). A `Map` iterates in insertion order as a
+ * `Set` does, and setting a key the map already holds leaves that order alone, so the oldest
+ * entry is the one its first key names.
+ */
+export function rememberBoundedEntry(
+  remembered: Map<string, string>,
+  key: string,
+  value: string,
+  max: number,
+): void {
+  remembered.set(key, value)
+  while (remembered.size > max) {
+    const oldest = remembered.keys().next().value
+    // As above: a non-empty `Map` always yields a key, and the check is what keeps a bound of a
+    // different shape from looping here forever.
+    if (oldest === undefined) break
+    remembered.delete(oldest)
+  }
+}

package/src/channel-forwarder.ts

@@ -148,7 +148,7 @@ function report(what: string, error: unknown): void {
  * One channel process receives both its direct Envoy route and every followed
  * topic. It deduplicates at the broker boundary, by event id and by dedupe key,
  * so an event covered by several patterns, and a re-send of one already
- * delivered, still becomes one Claude Code channel notification. With a replay
+ * delivered, still becomes one line in the session's conversation. With a replay
  * ledger, a frame the session was shown before this process started is dropped
  * too, and each frame handed on is recorded there before its claim settles.
  */

package/src/claude-rows.ts

@@ -0,0 +1,195 @@
+// The rows Claude Code writes of its own bookkeeping, parsed (INFRA-1026).
+//
+// One command a person runs writes three rows by the `command` door - the caveat, the echo of
+// what was typed, and the output - and two readers of this plugin parse them. The live view draws
+// the echo row as the plain command line a person typed and drops the other two, which would
+// otherwise show a reader raw tags and a `/context` table inside the agent's conversation
+// (`./agent-stream-claude`). The session reads the output row to answer the person who sent the
+// command, since most commands resolve `$.command.run` with no output in the result at all
+// (`./mod-session`, `runCommand`).
+//
+// A picture a person sent writes a row of the same kind: Claude Code's note of where it put the
+// bytes (`isPictureAttachmentRow`), which the live view drops as it drops the command's
+// bookkeeping.
+//
+// A line a person types while a turn is running arrives wrapped in framing of Claude Code's own
+// (`claudeMidTurnMessage`), and the live view draws the person's words out of it and none of the
+// wrapper.
+import type { ModContentBlock } from "../hooks/mod-protocol"
+
+/**
+ * The tags Claude Code wraps its own bookkeeping of a slash command in.
+ *
+ * Measured on 2.1.310: a command a person runs writes three rows by the `command` door - the
+ * caveat row, which says the command's output went to the person rather than to the model and
+ * carries `isMeta: true`; the echo row, which holds what was typed; and the output row. The
+ * output row's `message.type` is `user` in some runs and `system` (`name: "local_command"`) in
+ * others, so the tag its text starts with is the only safe discriminator
+ * (`/legion/scratch/tmp/infra-1026-spike/config/projects/-legion-scratch-tmp-infra-1026-proof-work/22a2c318-8433-4659-9568-a5ce1a873926.jsonl:42-44`,
+ * this plugin's own mod running `/usage`).
+ */
+const COMMAND_BOOKKEEPING_TAGS = [
+  "<local-command-caveat>",
+  "<local-command-stdout>",
+  "<local-command-stderr>",
+] as const
+
+/** The two tags an output row wraps what the command printed in, in the order a row carrying
+ *  both would be read: what went to the terminal's stdout, else what went to its stderr. */
+const COMMAND_OUTPUT_TAGS = ["local-command-stdout", "local-command-stderr"] as const
+
+/** The text a row's content holds, blocks flattened: a tool result is shown as text alone. A
+ *  block with no text of its own is named rather than dropped, as the publisher names one. */
+export function claudeRowText(value: unknown): string {
+  if (typeof value === "string") return value
+  if (!Array.isArray(value)) return ""
+  const pieces: string[] = []
+  for (const item of value as readonly unknown[]) {
+    if (typeof item === "string") {
+      pieces.push(item)
+      continue
+    }
+    if (typeof item !== "object" || item === null) continue
+    const block = item as Record<string, unknown>
+    const text = block["text"]
+    const type = block["type"]
+    if (typeof text === "string") pieces.push(text)
+    else if (typeof type === "string") pieces.push(`[${type}]`)
+  }
+  return pieces.join("\n")
+}
+
+/** The value one of a row's tags holds, trimmed: the recorded row indents every tag after the
+ *  first, so the whitespace around a value is the row's layout and not part of it. */
+function taggedValue(text: string, tag: string): string | undefined {
+  const open = `<${tag}>`
+  const from = text.indexOf(open)
+  if (from === -1) return undefined
+  const to = text.indexOf(`</${tag}>`, from + open.length)
+  if (to === -1) return undefined
+  return text.slice(from + open.length, to).trim()
+}
+
+/**
+ * The plain command line a row of the `command` door echoes, or `undefined` where the row is not
+ * the echo of a command a person ran.
+ *
+ * Measured on 2.1.310: the echo row holds one text block naming `<command-name>/usage</command-
+ * name>`, `<command-message>usage</command-message>` and `<command-args></command-args>`,
+ * newline-separated, each tag on its own line (same transcript as
+ * `COMMAND_BOOKKEEPING_TAGS`). The command line is the name, and the arguments after a space
+ * where there are any - `/clear`, `/effort low` - which is what the person typed and all of the
+ * command the live view shows.
+ */
+export function claudeEchoedCommandLine(content: readonly ModContentBlock[]): string | undefined {
+  const text = claudeRowText(content)
+  const name = taggedValue(text, "command-name")
+  if (name === undefined || name === "") return undefined
+  const args = taggedValue(text, "command-args") ?? ""
+  return args === "" ? name : `${name} ${args}`
+}
+
+/**
+ * What the output row of a slash command printed, or `undefined` where the row is not an output
+ * row. A row that is one and holds nothing answers `""`: the command printed nothing, which is
+ * itself the answer the person who sent it gets.
+ *
+ * Measured on 2.1.310: the row holds one text block wrapped in
+ * `<local-command-stdout>…</local-command-stdout>` (`<local-command-stderr>` where the command
+ * wrote to stderr), and most commands put their whole output there and nowhere else -
+ * `/effort low` resolves `$.command.run` with `{}` and writes
+ * `<local-command-stdout>Set effort level to low …</local-command-stdout>` 158 ms later
+ * (`/legion/scratch/tmp/infra-1026-spike/logs/mod3-q2-310.jsonl:98-102`).
+ */
+export function claudeCommandOutput(content: readonly ModContentBlock[]): string | undefined {
+  const text = claudeRowText(content)
+  for (const tag of COMMAND_OUTPUT_TAGS) {
+    const value = taggedValue(text, tag)
+    if (value !== undefined) return value
+  }
+  return undefined
+}
+
+/** Whether a row of the `command` door is Claude Code's bookkeeping of the command rather than
+ *  anything a person wrote: the caveat it records before the command runs, and the command's own
+ *  output, which published shows the person raw tags and a `/context` table in the agent's
+ *  conversation (INFRA-1026). */
+export function isCommandBookkeeping(content: readonly ModContentBlock[]): boolean {
+  const text = claudeRowText(content)
+  return COMMAND_BOOKKEEPING_TAGS.some((tag) => text.startsWith(tag))
+}
+
+/**
+ * The row Claude Code writes of where it put a picture's bytes: one text block holding
+ * `[Image: source: <absolute path>]` and nothing else.
+ *
+ * Measured on 2.1.310: a person's message carrying a picture reaches the session as its text and
+ * an image block, and Claude Code writes the bytes under the session's own images directory and
+ * records a companion row for them - `type: "user"`, `isMeta: true`, `turnCompanion: true`, its
+ * one text block
+ * `[Image: source: /legion/scratch/tmp/i3-k5-pane/tmp/claude-1000/-legion-scratch-tmp-i3-k5-pane-cwd/f376a3a9-6e75-461b-806b-22dea4e83ddf/images/1.png]`
+ * (`/legion/scratch/tmp/i3-k5-pane/config/projects/-legion-scratch-tmp-i3-k5-pane-cwd/f376a3a9-6e75-461b-806b-22dea4e83ddf.jsonl:123`,
+ * a Legion pane answering a picture sent from the Agents page). The path is Claude Code saying
+ * where the bytes went, not a message anybody wrote, so the row is no part of the conversation.
+ */
+const PICTURE_ATTACHMENT_ROW = /^\[Image: source: \/[^\]]+\]$/
+
+/** Whether a row is that note of Claude Code's rather than anything a person wrote
+ *  (`PICTURE_ATTACHMENT_ROW`), so the live view drops it as it drops a command's bookkeeping:
+ *  drawn, it is a second user row for the one message the person sent (INFRA-1026). */
+export function isPictureAttachmentRow(content: readonly ModContentBlock[]): boolean {
+  return PICTURE_ATTACHMENT_ROW.test(claudeRowText(content).trim())
+}
+
+/** The tags and the two fixed sentences the wrapper around a mid-turn message is made of
+ *  (`claudeMidTurnMessage`): the opening tag, the announcement, the person's words, Claude
+ *  Code's note to the model, the closing tag. */
+const MID_TURN_OPEN = "<system-reminder>"
+const MID_TURN_CLOSE = "</system-reminder>"
+const MID_TURN_ANNOUNCEMENT = "The user sent a new message while you were working:"
+const MID_TURN_NOTE = "This is how Claude Code surfaces messages the user sends mid-turn"
+
+/**
+ * The words a person typed while a turn was running, read out of the wrapper Claude Code hands
+ * them in, or `undefined` where the text is not that wrapper.
+ *
+ * Measured on 2.1.310: a line typed at the terminal mid-turn reaches the mod as one row by the
+ * `delivery` door (`origin.kind: "composer"`, `message.type: "attachment"`,
+ * `name: "queued_command"`, `/legion/scratch/tmp/infra-1026-spike/logs/mod2.jsonl:120`) whose
+ * single text block is
+ *
+ *     <system-reminder>
+ *     The user sent a new message while you were working:
+ *     TYPED-AT-TERMINAL-h1: say the word CEDAR when you can.
+ *
+ *     This is how Claude Code surfaces messages the user sends mid-turn - within the running
+ *     turn, often alongside the next tool result, rather than as a separate conversation turn.
+ *     Address the message above as you continue this turn.
+ *     </system-reminder>
+ *
+ * (`/legion/scratch/tmp/t-term-h1/config/projects/-legion-scratch-tmp-t-term-h1-cwd/b6411755-7568-4608-93a5-1db3c839e038.jsonl:70`).
+ * Drawn whole, that is tags and a note written to the model where the person wrote one sentence,
+ * which is the plumbing the view already drops for a command and for a picture's bytes.
+ *
+ * The words are found by the wrapper's shape and never by line number, since a person's message
+ * runs to as many lines, and as many blank ones, as they typed: everything between the
+ * announcement and the note is theirs. The note is looked for from the end, so a person who
+ * quotes its first words keeps their own. A wrapper holding no words answers `""`, which shows
+ * the reader nothing - right, because none of the framing is anybody's words.
+ *
+ * A `<system-reminder>` of any other kind answers `undefined` and the view draws it as it draws
+ * any other text row today, which this reader leaves alone: measured in the same spike, a peer
+ * session's message (`logs/mod3-q1q3q5.jsonl:223`) and the
+ * `[SYSTEM NOTIFICATION - NOT USER INPUT]` rows (`logs/mod3-q7-int.jsonl:13`) come by this same
+ * `delivery` door, and `<total_tokens>` by the `attachment` door the mod does not watch
+ * (`logs/mod2.jsonl:121`).
+ */
+export function claudeMidTurnMessage(text: string): string | undefined {
+  const body = text.trim()
+  if (!body.startsWith(MID_TURN_OPEN) || !body.endsWith(MID_TURN_CLOSE)) return undefined
+  const inner = body.slice(MID_TURN_OPEN.length, body.length - MID_TURN_CLOSE.length).trimStart()
+  if (!inner.startsWith(MID_TURN_ANNOUNCEMENT)) return undefined
+  const note = inner.lastIndexOf(MID_TURN_NOTE)
+  if (note < MID_TURN_ANNOUNCEMENT.length) return undefined
+  return inner.slice(MID_TURN_ANNOUNCEMENT.length, note).trim()
+}