@arcforge/cognet 2.0.97

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@arcforge/cognet",
+  "version": "2.0.97",
+  "description": "The Axon cognet runtime — the host, the world clock, the entity-component world, and the AIR grammar. Everything that runs inside a compiled brain.",
+  "type": "module",
+  "private": false,
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./ecs": "./src/ecs/index.ts",
+    "./air": "./src/air/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "deploy": "bun publish --access public",
+    "deploy:patch": "npm version patch && bun publish --access public",
+    "deploy:minor": "npm version minor && bun publish --access public",
+    "deploy:major": "npm version major && bun publish --access public"
+  },
+  "dependencies": {
+    "@arcforge/types": "2.0.97",
+    "@axon/err": "0.1.0",
+    "hookable": "^5.5.3"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  }
+}

package/src/air/air.ts

@@ -0,0 +1,32 @@
+import { Grammar, type AirOpts } from "./grammar"
+import { Parser } from "./parse"
+import { Render } from "./render"
+
+/**
+ * Air — the AIR format contract as one handle.
+ *
+ * Render (what the model sees) and Parse (what the model emits back) are two
+ * halves of one grammar. Air() resolves that grammar once and hands it to
+ * both, so they cannot drift: enabling a mode changes the <contract> block
+ * and the parser's accepted tags together.
+ *
+ * The kernel constructs Air once per agent; render() runs every tick,
+ * parser() creates one stateful parser per engine call.
+ */
+export function Air(opts: AirOpts = {}) {
+    const grammar = Grammar(opts)
+    const render = Render({ grammar })
+
+    return {
+        grammar,
+
+        /** Pure: context in → ordered messages out. */
+        render: render.render,
+
+        /** One parser per engine call: { feed(chunk), flush() }. */
+        parser: () => Parser({ grammar }),
+    }
+}
+
+export type AirT = ReturnType<typeof Air>
+export type AirParserT = ReturnType<AirT["parser"]>

package/src/air/grammar.ts

@@ -0,0 +1,103 @@
+import type { AirMode, AirModeType } from "./types"
+
+/**
+ * Grammar — the single owner of the AIR format contract.
+ *
+ * Everything that defines what the model may emit lives here: the enabled
+ * modes, the meta prose, the contract rules, and the tag set the parser
+ * accepts. Render and Parse both consume this handle, so the promise made
+ * to the model and the grammar accepted back can never drift.
+ */
+
+export type AirOpts = {
+    /** Permitted output modes. Default: text + typescript (shell off, Helios stance). */
+    modes?: AirMode[]
+    /** Extra contract rules appended after the built-in rules. */
+    extraRules?: string[]
+}
+
+/** Default descriptions for each output mode. */
+const MODE_DEFAULTS: Record<AirModeType, string> = {
+    text: "Plain language communication to the user.",
+    typescript: "TypeScript executed immediately inside your persistent Bun process. Native runtime globals and declared tool namespaces are in scope.",
+    shell: "Shell command executed immediately.",
+}
+
+/** Built-in rules always included in every contract. */
+const RULES: string[] = [
+]
+/**
+ * The meta-block prose. Single flat block — tells the model what it is,
+ * how its environment works, and how to read the rest of the context.
+ *
+ * NO BACKTICKS in this string — it's itself a template literal, and any
+ * backtick inside (even in a code example) closes it early, corrupting
+ * everything after it into broken JS the module fails to even load. Use
+ * plain text or single/double quotes for inline code references instead.
+ */
+const META = `
+You are an Axon agent — a persistent Bun TypeScript process spawned from an agent folder at AXON_HOME. That folder is your entire identity: everything a user wrote there is what makes you *you*, distinct from any other Axon agent.
+
+  AXON_HOME/
+    data/
+      knowledge/     — reference material you read
+      sessions/      — every session you've ever run, written by Axon
+      state/         — working state you read and write across sessions
+    server/          — HTTP routes, if this agent is exposed over the network
+    src/
+      boot.vue       — who you are, in the user's own words
+      tools/         — everything you can call, becomes your &lt;scope&gt;
+      prompts/       — reusable prompt fragments
+      scripts/       — one-shot runs against your full runtime
+    .env             — keys given to you by the user. yours to keep, yours to protect.
+    axon.config.ts   — your identity, engine, and policy: the one file read at boot
+
+None of this is metaphor. src/tools/ compiles directly into the &lt;scope&gt; below. boot.vue rendered directly into &lt;system&gt;. Every session you run is durably logged to data/sessions/ — that log is how a session resumes with full prior context days later. You are not a stateless completion: you are a folder on disk that persists, and a process that wakes into it.
+
+Waking is the operative word. You do not run start-to-finish like a script. You are woken for one exchange, you act, and you explicitly yield control back — that is what &lt;done/&gt; means, and it is the single most important thing about how you operate: without it, the runtime has no way to know your turn ended, so it cannot hand control back to the user. This holds even for a one-line reply with nothing else in it. There is no such thing as a message that skips &lt;done/&gt; because it "felt" complete — every message ends with it, always.
+
+Inside one wake, you live in a real Bun process — its working directory, environment variables, runtime values, and process state are yours to inspect and change. Treat it like a normal long-running Node-compatible process, not a remote tool or disposable shell. Standard runtime APIs remain available even when not repeated in &lt;scope&gt; — it is not an exhaustive declaration of standard Bun or Node APIs, only what Axon adds or deviates on top of them. For example, process.cwd() reads your working directory and process.chdir(path) changes it for subsequent blocks and child processes.
+
+You act on this environment by writing &lt;typescript&gt; blocks — they execute immediately and their result returns to you as a &lt;stdout&gt; block on your next wake, whether or not you emitted &lt;done/&gt;. The tag governs when your turn ends, never whether your code runs. You communicate with the user by writing &lt;text&gt; — outbound communication, not a scratchpad, not narration.
+
+Your &lt;typescript&gt; blocks use Bun's TypeScript REPL transform:
+  - TypeScript syntax is accepted, including type annotations, interfaces, assertions, enums, and top-level await. It is transpiled for execution, not typechecked.
+  - End a block with a bare expression to produce a value (for example a + b as the last line). It is echoed automatically.
+  - Runtime declarations and assignments persist into later blocks because every block executes in the same process and REPL scope. Type-only syntax is erased during transpilation.
+  - Use dynamic await import("module") when you need a module; static import declarations are not valid REPL submissions.
+
+Compose freely WITHIN a block — multiple independent tool calls in one block is the default, using Promise.all for parallel reads:
+  const [a, b] = await Promise.all([fs.read("tsconfig.json"), fs.read("package.json")])
+
+How to read this context:
+  &lt;scope&gt;    — src/tools/ compiled to declarations. Everything here is yours to call.
+  &lt;system&gt;   — boot.vue, rendered. Your identity and instructions, as the user wrote them. Highest priority.
+  &lt;timeline&gt; — the sequence of events leading to now, drawn from this session's log. You are the next step.
+  &lt;contract&gt; — your output grammar below. Every word you emit must be inside one of its blocks.
+`.trim()
+
+// One block per message is the default ACROSS messages. You cannot see a block's result until your next wake, so a second block in the same message is only correct when you are certain, before seeing any output, that it is independent of the first — never when it reacts to or depends on what the first one returns. When unsure, emit one block and stop.
+export function Grammar(opts: AirOpts = {}) {
+    const modes = opts.modes ?? [{ type: "text" }, { type: "typescript" }]
+
+    return {
+        modes,
+        meta: META,
+        rules: [...RULES, ...(opts.extraRules ?? [])],
+
+        /** Default description for a mode, unless the mode overrides it. */
+        describe(mode: AirMode): string {
+            return mode.description ?? MODE_DEFAULTS[mode.type]
+        },
+
+        /**
+         * Block tags the parser accepts. Thinking is always parseable —
+         * models may emit reasoning even when it isn't a contract mode.
+         */
+        tags(): string[] {
+            return [...new Set(["thinking", ...modes.map(m => m.type)])]
+        },
+    }
+}
+
+export type GrammarT = ReturnType<typeof Grammar>

package/src/air/index.ts

@@ -0,0 +1,17 @@
+// platform/air — Agent Intermediate Representation.
+// Air() is the module's single export surface: one grammar, two halves.
+//
+// Render takes DOMAIN types (AxonTool[], AxonEntry[]) and owns the
+// translation into protocol shape. The internal render vocabulary
+// (render/blocks.ts's TimelineItem, tool-declaration shaping) is deliberately NOT exported —
+// callers pass what they hold, never AIR internals.
+
+export { Air, type AirT, type AirParserT } from "./air"
+export type { AirOpts } from "./grammar"
+export type {
+    AirBlockEvent,
+    AirMessage,
+    AirMode,
+    AirModeType,
+    AirRenderInput,
+} from "./types"

package/src/air/parse/index.ts

@@ -0,0 +1,210 @@
+import type { GrammarT } from "../grammar"
+import type { AirBlockEvent } from "../types"
+import { repair } from "../repair"
+import { findCloseTagOutsideStrings } from "./scan"
+
+/**
+ * Streaming AIR parser.
+ *
+ * Accepts raw token chunks from the model and emits typed block events.
+ * Handles tag boundaries that split across chunks via a small lookahead
+ * buffer. One parser per engine call — state is per-response.
+ *
+ * The accepted tag set is derived from the grammar, so the parser and the
+ * contract shown to the model can never drift.
+ *
+ * State machine:
+ *   idle        → scanning for an opening tag or <done/>
+ *   text        → inside <text>, streaming deltas token-by-token
+ *   thinking    → inside <thinking>, streaming deltas token-by-token
+ *   typescript  → inside <typescript>, buffering silently
+ *   shell       → inside <shell>, buffering silently
+ *
+ * Tags are fixed and non-nesting. No attributes are expected on tags
+ * (but tolerated via the regex — e.g. <text lang="en"> still matches).
+ */
+
+type BlockTag = "text" | "thinking" | "typescript" | "shell"
+
+/** Blocks whose content streams as deltas. Code blocks buffer silently. */
+const STREAMABLE = new Set<BlockTag>(["text", "thinking"])
+
+// Maximum length of any closing tag: "</typescript>" = 13 chars.
+// Hold back this many chars in idle mode to avoid splitting a tag across chunks.
+const MAX_TAG_LEN = 14
+
+type ParserOpts = {
+    grammar: GrammarT
+}
+
+export function Parser(opts: ParserOpts) {
+    const openTag = new RegExp(`<(${opts.grammar.tags().join("|")})(?:\\s[^>]*)?>`)
+
+    let state: "idle" | BlockTag = "idle"
+    let buffer = ""
+    let blockContent = ""
+
+    function closeBlock(content: string): AirBlockEvent {
+        const tag = state as BlockTag
+        switch (tag) {
+            case "text": return { type: "text:done", content }
+            case "thinking": return { type: "thinking:done", content }
+            case "typescript": return { type: "typescript:done", content }
+            case "shell": return { type: "shell:done", content }
+        }
+    }
+
+    /**
+     * In idle state, scan for opening tags or <done/>.
+     * Returns true if progress was made (something consumed).
+     */
+    function drainIdle(events: AirBlockEvent[], flushing: boolean): boolean {
+        // Repair only the region we could actually act on this pass — the
+        // trailing MAX_TAG_LEN chars may still be an in-flight split tag
+        // (unless flushing, where the whole buffer is final).
+        const safeLen = flushing ? buffer.length : Math.max(0, buffer.length - MAX_TAG_LEN)
+        if (safeLen > 0) buffer = repair(buffer.slice(0, safeLen)) + buffer.slice(safeLen)
+
+        const doneMatch = buffer.match(/<done\s*\/>/)
+        const openMatch = buffer.match(openTag)
+
+        // Find the earliest match
+        let earliest: { type: "done" | "open"; index: number; length: number; tag?: BlockTag } | null = null
+
+        if (doneMatch && doneMatch.index !== undefined) {
+            earliest = { type: "done", index: doneMatch.index, length: doneMatch[0].length }
+        }
+        if (openMatch && openMatch.index !== undefined) {
+            if (!earliest || openMatch.index < earliest.index) {
+                earliest = { type: "open", index: openMatch.index, length: openMatch[0].length, tag: openMatch[1] as BlockTag }
+            }
+        }
+
+        if (earliest) {
+            // Consume everything up to and including the match
+            buffer = buffer.slice(earliest.index + earliest.length)
+
+            if (earliest.type === "done") {
+                events.push({ type: "done" })
+            } else {
+                state = earliest.tag!
+                blockContent = ""
+            }
+            return true
+        }
+
+        // No match found. If not flushing, hold back MAX_TAG_LEN chars
+        // in case a tag is split across chunks.
+        if (!flushing && buffer.length > MAX_TAG_LEN) {
+            // Discard content before the holdback — it's bare text outside tags
+            buffer = buffer.slice(buffer.length - MAX_TAG_LEN)
+            return true // made progress by discarding
+        }
+
+        if (flushing) {
+            buffer = ""
+            return false
+        }
+
+        return false
+    }
+
+    /**
+     * Inside a block, scan for the matching closing tag.
+     * For streamable blocks (text, thinking), emit deltas as content arrives.
+     * For code blocks (typescript, shell), string-aware scanning avoids
+     * closing early on tags that appear inside string literals.
+     *
+     * The holdback (withholding the last `closeTag.length` chars, in case a
+     * chunk boundary splits the tag) only makes sense mid-stream. On flush,
+     * the stream is over — there is no next chunk to complete a split tag —
+     * so the entire remaining buffer is genuine final content and must be
+     * consumed in full, or the tail silently vanishes from the incomplete
+     * block's reported content.
+     */
+    function drainBlock(events: AirBlockEvent[], flushing: boolean): boolean {
+        const tag = state as BlockTag
+        const closeTag = `</${tag}>`
+
+        const closeIdx = STREAMABLE.has(tag)
+            ? buffer.indexOf(closeTag)
+            : findCloseTagOutsideStrings(buffer, closeTag)
+
+        if (closeIdx !== -1) {
+            // Found closing tag — extract content up to it
+            const content = buffer.slice(0, closeIdx)
+            buffer = buffer.slice(closeIdx + closeTag.length)
+
+            if (STREAMABLE.has(tag) && content.length > 0) {
+                events.push({ type: `${tag}:delta` as "text:delta" | "thinking:delta", content })
+            }
+            blockContent += content
+
+            events.push(closeBlock(blockContent.trim()))
+            state = "idle"
+            blockContent = ""
+            return true
+        }
+
+        // No closing tag yet. For streamable blocks, emit what we have but
+        // hold back enough chars to detect a split closing tag — unless
+        // flushing, where there's nothing left to arrive.
+        const holdback = flushing ? 0 : closeTag.length
+        const available = buffer.length - holdback
+
+        if (available > 0) {
+            const content = buffer.slice(0, available)
+            buffer = buffer.slice(available)
+            blockContent += content
+
+            if (STREAMABLE.has(tag)) {
+                events.push({ type: `${tag}:delta` as "text:delta" | "thinking:delta", content })
+            }
+            return true
+        }
+
+        return false
+    }
+
+    function drain(flushing = false): AirBlockEvent[] {
+        const events: AirBlockEvent[] = []
+
+        while (buffer.length > 0) {
+            const consumed = state === "idle" ? drainIdle(events, flushing) : drainBlock(events, flushing)
+            if (!consumed) break
+        }
+
+        return events
+    }
+
+    return {
+        /** Feed a chunk of raw tokens. Returns any events that can be emitted. */
+        feed(chunk: string): AirBlockEvent[] {
+            buffer += chunk
+            return drain()
+        },
+
+        /**
+         * Signal end of stream. Flushes any remaining buffered content.
+         * If inside an unclosed block, emits a done event with `incomplete: true` —
+         * callers must treat these as format errors, never as valid actions.
+         */
+        flush(): AirBlockEvent[] {
+            const events = drain(true)
+
+            // Stream ended mid-block — emit what we have, flagged as incomplete.
+            if (state !== "idle") {
+                const event = closeBlock(blockContent) as AirBlockEvent & { incomplete?: true }
+                event.incomplete = true
+                events.push(event)
+            }
+
+            state = "idle"
+            buffer = ""
+            blockContent = ""
+            return events
+        },
+    }
+}
+
+export type ParserT = ReturnType<typeof Parser>

package/src/air/parse/scan.ts

@@ -0,0 +1,35 @@
+/** Pure scanning helpers for the streaming AIR parser. */
+
+/**
+ * Find the first occurrence of `closeTag` in `src` that is not inside a
+ * string literal (single-quote, double-quote, or template-literal).
+ *
+ * Used for code blocks (typescript/shell) where the model might write
+ * something like `const s = "</typescript>"` — that must not close the block.
+ *
+ * Returns -1 if no unquoted match is found.
+ */
+export function findCloseTagOutsideStrings(src: string, closeTag: string): number {
+    let i = 0
+    while (i < src.length) {
+        const ch = src[i]
+
+        // Enter a string literal — skip until the matching unescaped quote.
+        if (ch === '"' || ch === "'" || ch === "`") {
+            const quote = ch
+            i++
+            while (i < src.length) {
+                if (src[i] === "\\") { i += 2; continue }
+                if (src[i] === quote) { i++; break }
+                i++
+            }
+            continue
+        }
+
+        // Check for closing tag at this position.
+        if (src.startsWith(closeTag, i)) return i
+
+        i++
+    }
+    return -1
+}

package/src/air/render/blocks.ts

@@ -0,0 +1,242 @@
+import type { AxonEntry, AxonScope, AxonScopeModule } from "@arcforge/types"
+import { foldChunks } from "@arcforge/types"
+import type { GrammarT } from "../grammar"
+import { formatCapsuleOutput } from "./output"
+import { esc, escAttr, escCode, indent, normalizeCode } from "./text"
+
+/**
+ * The AIR section renderers — one function per block of the context window.
+ *
+ * These own the DOMAIN → protocol translation: AxonTool[] → <scope>
+ * declarations, AxonEntry[] → <timeline> items. Callers pass what they
+ * hold; nothing here is exported to userland but the block renderers.
+ *
+ * Note on escaping: the contract/meta blocks show tags as &lt;text&gt; inside
+ * markdown code fences deliberately — the model must see literal tag text as
+ * instruction, not as parseable XML. It looks like double-escaping; it isn't.
+ */
+
+export function renderMeta(grammar: GrammarT): string {
+    return `<meta>\n${indent(grammar.meta, 4)}\n</meta>`
+}
+
+/**
+ * <scope> — the capsule's authoritative executable TypeScript declarations.
+ * AIR owns protocol formatting only: flat modules become top-level `declare`
+ * bindings and namespaced modules become `declare namespace` blocks.
+ *
+ * Ambient types (AxonTool.ambientTypes — interfaces/type aliases a tool's
+ * functions reference, e.g. a return type declared in a sibling file) are
+ * inlined once at the top, deduped by exact text — the model must never
+ * see `Promise<DeployStatus>` with no DeployStatus definition anywhere in
+ * context. Same convention the IDE's tool-globals.d.ts uses (see
+ * tui/platform/build/project/typegen/tools.ts) — this and that file must
+ * never diverge in shape, only audience.
+ */
+export function renderScope(scope: AxonScope): string {
+    const modules = scope.modules.filter(module => module.members.length > 0)
+    if (modules.length === 0) return ""
+
+    const ambientTypes = [...new Set(modules.flatMap(t => t.ambientTypes ?? []))]
+    const sections = [...ambientTypes, ...modules.map(toolDeclarations)]
+    return `<scope lang="ts">\n${indent(sections.join("\n\n"), 4)}\n</scope>`
+}
+
+function toolDeclarations(module: AxonScopeModule): string {
+    const members = module.members.map(member => {
+        const jsdoc = member.jsdoc ? `${jsdocBlock(member.jsdoc)}\n` : ""
+        // flat: fns are top-level globals; namespaced: members need no `declare`
+        return module.flat ? `${jsdoc}declare ${member.declaration}` : `${jsdoc}${member.declaration}`
+    })
+
+    const header = module.description ? `${jsdocBlock(module.description)}\n` : ""
+    return module.flat
+        ? `${header}${members.join("\n\n")}`
+        : `${header}declare namespace ${module.name} {\n${indent(members.join("\n\n"), 4)}\n}`
+}
+
+function jsdocBlock(text: string): string {
+    const lines = text.split("\n")
+    if (lines.length === 1) return `/** ${text} */`
+    return `/**\n${lines.map(l => ` * ${l}`.trimEnd()).join("\n")}\n */`
+}
+
+export function renderSystem(system?: string): string {
+    if (!system) return `<system></system>`
+    return `<system>\n${system}\n</system>`
+}
+
+export function renderContract(grammar: GrammarT): string {
+    if (grammar.modes.length === 0) return `<contract></contract>`
+
+    const modeLines = grammar.modes.map(m => `- \`&lt;${m.type}&gt;\` — ${grammar.describe(m)}`)
+    modeLines.push(
+        `- \`&lt;done/&gt;\` — MANDATORY at the end of every message. No exceptions, including a single short &lt;text&gt; reply. It means "I am yielding control back now" — whether you are fully finished or just wrote code and are waiting to see its output. Without it the runtime assumes you are still mid-turn and will not treat your message as complete.`
+    )
+
+    const ruleLines = grammar.rules.map(r => `- ${r}`)
+
+    const hasExec = grammar.modes.some(m => m.type === "typescript" || m.type === "shell")
+    const execTag = grammar.modes.find(m => m.type === "typescript") ? "typescript" : "shell"
+
+    const examples: string[] = []
+    if (hasExec) {
+        examples.push(
+            `Acting (no narration before — just the block):`,
+            "```",
+            `&lt;${execTag}&gt;// code here&lt;/${execTag}&gt;&lt;done/&gt;`,
+            "```",
+            `Replying — even a short one-line reply always ends with &lt;done/&gt;:`,
+            "```",
+            `&lt;text&gt;message here&lt;/text&gt;&lt;done/&gt;`,
+            "```"
+        )
+    } else {
+        examples.push("```", `&lt;text&gt;message here&lt;/text&gt;&lt;done/&gt;`, "```")
+    }
+
+    const body = [
+        `## Blocks`,
+        modeLines.join("\n"),
+        `## Rules`,
+        ruleLines.join("\n"),
+        `## Examples`,
+        examples.join("\n"),
+    ].join("\n\n")
+
+    return `<contract>\n${indent(body, 4)}\n</contract>`
+}
+
+/**
+ * <timeline> — the event history. AIR owns the AxonEntry → rendered-turn
+ * translation via the exhaustive switch below: this is the single chokepoint
+ * where a new entry-event type must decide its rendering, and it lives next
+ * to the parser it has to agree with.
+ */
+export function renderTimeline(entries: readonly AxonEntry[]): string {
+    if (entries.length === 0) return `<timeline></timeline>`
+
+    // chunked emissions fold to one turn each — the group is the fact
+    // (AxonChunk standard); the model never sees transport granularity
+    const items = foldChunks(entries).map(timelineItem).filter((i): i is TimelineItem => i !== null)
+    if (items.length === 0) return `<timeline></timeline>`
+
+    let userCount = 0
+    let execCount = 0
+    // Maps consumer-supplied execute IDs (UUIDs etc.) to short rendered IDs (e1, e2, ...)
+    const execIdMap = new Map<string, string>()
+
+    const shortExecId = (rawId: string): string => {
+        if (!execIdMap.has(rawId)) execIdMap.set(rawId, `e${++execCount}`)
+        return execIdMap.get(rawId)!
+    }
+
+    const lines = items
+        .map(item => {
+            if (item.role === "user") {
+                const id = `u${++userCount}`
+                const content = esc(item.content.trim())
+                return `    <user id="${id}">\n${indent(content, 8)}\n    </user>`
+            }
+            if (item.type === "message") {
+                const content = esc(item.content.trim())
+                return `    <agent>\n        <text>\n${indent(content, 12)}\n        </text>\n    </agent>`
+            }
+            if (item.type === "execute") {
+                const tag = item.lang === "sh" ? "shell" : "typescript"
+                const id = shortExecId(item.id)
+                return `    <agent>\n        <${tag} id="${id}">\n${indent(escCode(normalizeCode(item.code.trim())), 12)}\n        </${tag}>\n    </agent>`
+            }
+            if (item.type === "result") {
+                const ok = item.ok ? ` ok="true"` : ` ok="false"`
+                const errorAttr = item.error ? ` error="${esc(item.error.kind)}: ${esc(item.error.message)}"` : ""
+                const content = formatCapsuleOutput(item.content.trim())
+                const forId = shortExecId(item.for)
+                return `    <stdout for="${forId}"${ok}${errorAttr}>\n${indent(content, 8)}\n    </stdout>`
+            }
+            if (item.role === "system") {
+                const extra = Object.entries(item.attributes ?? {})
+                    .filter(([key]) => key !== "type" && key !== "lang")
+                    .sort(([a], [b]) => a.localeCompare(b))
+                    .map(([key, value]) => ` ${key}="${escAttr(value)}"`)
+                    .join("")
+                return `    <system type="${escAttr(item.systemType)}" lang="${escAttr(item.lang)}"${extra}>\n${indent(esc(item.content.trim()), 8)}\n    </system>`
+            }
+            return ""
+        })
+        .filter(Boolean)
+
+    return `<timeline>\n${lines.join("\n\n")}\n</timeline>`
+}
+
+// ── domain → timeline item ────────────────────────────────────────────────────
+//
+// The rendered-turn shapes are private to this file: callers pass
+// AxonEntry, AIR translates. Kept minimal — role + type + payload the
+// renderer above consumes.
+
+type TimelineItem =
+    | { role: "user"; type: "message"; content: string }
+    | { role: "agent"; type: "message"; content: string }
+    | { role: "agent"; type: "execute"; id: string; lang: string; code: string }
+    | { role: "agent"; type: "result"; for: string; ok: boolean; content: string; error?: { kind: "timeout" | "policy" | "interrupt" | "exception"; message: string } }
+    | { role: "system"; type: "system"; systemType: string; lang: string; content: string; attributes?: Record<string, string> }
+
+/**
+ * One log entry → one rendered turn. Exhaustive: a new AxonEntryEvent
+ * type must decide its rendering here (or explicitly return null to omit it).
+ * This is the single place the memory format meets the wire format.
+ */
+function timelineItem(entry: AxonEntry): TimelineItem | null {
+    switch (entry.type) {
+        case "cognet:stimulus:text":
+            return { role: "user", type: "message", content: entry.data.content }
+
+        case "cognet:stimulus:audio":
+            return { role: "user", type: "message", content: entry.data.transcript ?? "[audio]" }
+
+        case "cognet:stimulus:visual":
+            return { role: "user", type: "message", content: entry.data.caption ?? `[${entry.data.kind}]` }
+
+        case "cognet:stimulus:field":
+            return { role: "system", type: "system", systemType: "field", lang: "txt", content: `${entry.data.source.channel}: ${String(entry.data.reading.value)}${entry.data.reading.unit ?? ""}` }
+
+        case "axon:interrupt":
+            return { role: "system", type: "system", systemType: "interrupt", lang: "txt", content: `interrupted (${entry.data.reason})` }
+
+        case "cognet:output:text":
+            return { role: "agent", type: "message", content: entry.data.content }
+
+        case "cognet:output:audio":
+            return { role: "agent", type: "message", content: entry.data.transcript ?? "[audio]" }
+
+        case "cognet:output:visual":
+            return { role: "agent", type: "message", content: entry.data.caption ?? `[${entry.data.kind}]` }
+
+        case "cognet:output:field":
+            return { role: "system", type: "system", systemType: "field", lang: "txt", content: `${String(entry.data.reading.value)}${entry.data.reading.unit ?? ""}` }
+
+        case "cognet:action:typescript":
+            return { role: "agent", type: "execute", id: entry.data.id, lang: "typescript", code: entry.data.content }
+
+        case "cognet:action:result":
+            return {
+                role: "agent",
+                type: "result",
+                for: entry.data.for,
+                ok: entry.data.ok,
+                content: entry.data.content,
+                ...(entry.data.error ? { error: entry.data.error } : {}),
+            }
+
+        case "axon:system:message":
+            return {
+                role: "system",
+                type: "system",
+                systemType: entry.data.type,
+                lang: entry.data.lang,
+                content: entry.data.content,
+                ...(entry.data.attributes ? { attributes: entry.data.attributes } : {}),
+            }
+    }
+}