The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
/**
* One whole session as turns, for a reader that is not the search index: the agent handoff.
*
* The same pipeline the indexer runs (`indexer.ts` `pass` / `historyPass`) — the engine's own line
* normalizer into a `TurnCollector` — but from the first line to the last, with no store and no resume
* offsets. So it gets the same cleaning for free: only the person's words as asks, secrets blanked, the
* agent's text, and one line per tool call; no tool output, no reasoning. Each message's text is bounded
* before the collector sees it: long whitespace-free runs cut (`omitLongRuns`), then at most its first and
* last 16 000 characters.
*
* The daemon's thread is shared with every terminal it streams, so the read yields to the event loop
* every few milliseconds, as the indexer does, and stops at a caller's deadline.
*/
import type { FileHandle } from 'node:fs/promises'
import { performance } from 'node:perf_hooks'
import type { LiveEvent } from '../normalize.js'
import { forEachLine, lineNormalizer, lineTime, skipPredicate } from '../transcriptReader.js'
import { TurnCollector, type IndexedTurn } from './turns.js'
export interface TurnSource {
engine: string
sessionId: string
/** The transcript file, for an engine that writes one. */
transcriptPath: string | null
/** The whole history, for an engine that keeps it in a database (OpenCode, Kilo, Hermes, Devin). */
readHistory?: () => Promise<readonly LiveEvent[]>
}
export class SessionTurnsError extends Error {
constructor(readonly code: 'NO_HISTORY' | 'NO_NORMALIZER' | 'DEADLINE') {
super(`session turns: ${code}`)
this.name = 'SessionTurnsError'
}
}
export interface ReadOptions {
/** A caller-owned verified descriptor and finite snapshot boundary; never reopened or closed here. */
handle?: FileHandle
end?: number
/** A bounded tail starts inside a record: discard that first fragment before interpreting any text. */
start?: number
/** How long to hold the thread between yields (ms). */
sliceMs?: number
/** Epoch ms after which the read gives up with `DEADLINE`. */
deadline?: number
/** Asked between lines and batches: true gives up with `DEADLINE` (a caller with its own clock). */
shouldStop?: () => boolean
}
const HISTORY_BATCH = 200
/** The longest whitespace-free run a handoff keeps: anything longer is a blob, never a word or a path. */
export const RUN_CAP = 512
const LONG_RUN = new RegExp(String.raw`(?<!\S)\S{${RUN_CAP + 1},}`, 'g')
/**
* How a run that ends in a secret's label ends: `password: `, `"api_key":`, `&token=`, `Bearer`. The value comes
* after a space, in the next run, so dropping the label with its run would free the value from the shared
* redaction. Bounded: at most 64 characters are looked at, so the match is linear.
*
* Its label words must cover those of the shared redaction's patterns (`logBundle.ts:111-113`) and be kept in
* step with them: a label word added there and missing here is cut off with its run, and its value then leaks.
*/
const LABEL_END = /(?:token|secret|password|passphrase|credential|api[_-]?key|access[_-]?key|auth)\w{0,40}["']?\s*[:=]\s*["']?$|Bearer$/i
const LABEL_WINDOW = 64
/**
* A whitespace-free run longer than `RUN_CAP` replaced by a count, keeping a short suffix that is a label (above)
* so the redaction after this still sees label and value. Linear. The shared redaction (`logBundle.ts`) is cubic
* on a long run of `?key?key…`, so no text reaches it before this has bounded its runs.
*/
export function omitLongRuns(text: string): string {
if (text.length <= RUN_CAP) return text
return text.replace(LONG_RUN, (run) => {
const label = LABEL_END.exec(run.slice(-LABEL_WINDOW))
return `<${run.length} characters omitted>${label ? label[0] : ''}`
})
}
/** Most of one event's text a handoff reads: the start and the end (a turn's budgets downstream keep no more). */
const EVENT_HEAD = 16_000
const EVENT_TAIL = 16_000
/** `text` run-capped, then, when still over the event budget, its start and its end around a cut mark with spaces in it. */
function boundedText(text: string): string {
const capped = omitLongRuns(text)
if (capped.length <= EVENT_HEAD + EVENT_TAIL) return capped
let head = EVENT_HEAD
const last = capped.charCodeAt(head - 1)
if (last >= 0xd800 && last <= 0xdbff) head -= 1
let tail = capped.length - EVENT_TAIL
const first = capped.charCodeAt(tail)
if (first >= 0xdc00 && first <= 0xdfff) tail += 1
return `${capped.slice(0, head)}\n… <${tail - head} characters omitted> …\n${capped.slice(tail)}`
}
/** An event with its message text bounded (the text the collector redacts); other events as they are. */
function boundedEvent(event: LiveEvent): LiveEvent {
switch (event.type) {
case 'turn_started': return { ...event, payload: { ...event.payload, userMessage: boundedText(event.payload.userMessage) } }
case 'user_message': return { ...event, payload: { ...event.payload, content: boundedText(event.payload.content) } }
case 'text_delta': return { ...event, payload: { ...event.payload, content: boundedText(event.payload.content) } }
default: return event
}
}
/**
* Every turn of the session, oldest first: from the transcript file when the engine writes one, else from
* `readHistory`. Throws `SessionTurnsError` — `DEADLINE` past `deadline` / `shouldStop`, `NO_NORMALIZER` for a
* file no normalizer reads, `NO_HISTORY` with neither source. Filesystem errors from the transcript propagate.
*/
export async function readSessionTurns(source: TurnSource, options: ReadOptions = {}): Promise<IndexedTurn[]> {
const { deadline } = options
const sliceMs = options.sliceMs ?? 12
let sliceStart = performance.now()
const pace = async (): Promise<void> => {
if (performance.now() - sliceStart < sliceMs) return
await new Promise<void>((resolve) => setImmediate(resolve))
sliceStart = performance.now()
}
let expired = false
const pastDeadline = (): boolean => {
if ((deadline !== undefined && Date.now() > deadline) || options.shouldStop?.()) expired = true
return expired
}
const collector = new TurnCollector(0)
const normalize = source.transcriptPath ? lineNormalizer(source.engine, source.sessionId) : null
if (source.transcriptPath && normalize) {
let lastAt: number | null = null
const start = options.start ?? 0
await forEachLine(source.transcriptPath, start, async ({ text, offset }) => {
if (start > 0 && offset === start) return
const at = lineTime(text) ?? lastAt
if (at !== null && (lastAt === null || at > lastAt)) lastAt = at
collector.feed(normalize(text).map(boundedEvent), offset, at)
await pace()
}, { skip: skipPredicate(source.engine), shouldStop: pastDeadline, handle: options.handle, end: options.end })
if (expired) throw new SessionTurnsError('DEADLINE')
} else if (source.transcriptPath) {
throw new SessionTurnsError('NO_NORMALIZER')
} else if (source.readHistory) {
const events = await source.readHistory()
for (let at = 0; at < events.length; at += HISTORY_BATCH) {
if (pastDeadline()) throw new SessionTurnsError('DEADLINE')
collector.feed(events.slice(at, at + HISTORY_BATCH).map(boundedEvent), 0, null)
await pace()
}
if (pastDeadline()) throw new SessionTurnsError('DEADLINE')
} else {
throw new SessionTurnsError('NO_HISTORY')
}
const { closed, open } = collector.finish()
return open ? [...closed, open] : closed
}