@arcforge/cognet 2.0.114 → 2.0.116

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@arcforge/cognet",
-  "version": "2.0.114",
+  "version": "2.0.116",
   "description": "A cognitive engine",
   "type": "module",
   "private": false,
   "main": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./ecs": "./src/ecs/index.ts",
-    "./air": "./src/air/index.ts"
+    "./ecs": "./src/ecs/index.ts"
   },
   "files": [
     "src"
@@ -18,8 +17,8 @@
     "deploy": "echo \"This package is published ONLY by apps/tui/scripts/release.ts, which pins workspace:* deps to concrete versions first. Publishing it directly ships an unresolvable dependency.\" && exit 1"
   },
   "dependencies": {
-    "@arcforge/err": "2.0.114",
-    "@arcforge/types": "2.0.114",
+    "@arcforge/err": "2.0.116",
+    "@arcforge/types": "2.0.116",
     "hookable": "^5.5.3"
   },
   "devDependencies": {

package/src/host.ts

@@ -126,11 +126,11 @@ globals.definePlugin = (plugin: CognetPlugin): CognetPlugin => {
 
 // run() is overloaded on input shape (string vs string[]) — a plain arrow
 // can't carry two call signatures, so it's declared separately and spread in.
-function run(code: string, opts?: { signal?: AbortSignal }): Promise<AxonRunResult>
-function run(code: string[], opts?: { signal?: AbortSignal }): Promise<AxonRunResult[]>
-function run(code: string | string[], opts?: { signal?: AbortSignal }) {
-    if (Array.isArray(code)) return kernelOrThrow().run(code, opts)
-    return kernelOrThrow().run(code, opts)
+function run(code: string): Promise<AxonRunResult>
+function run(code: string[]): Promise<AxonRunResult[]>
+function run(code: string | string[]) {
+    if (Array.isArray(code)) return kernelOrThrow().run(code)
+    return kernelOrThrow().run(code)
 }
 
 // the syscall table, delegating — live from load() onward
@@ -141,6 +141,7 @@ const localKernel = {
     scope: () => kernelOrThrow().scope(),
     base: () => kernelOrThrow().base(),
     emit: (type: never, data: never) => kernelOrThrow().emit(type, data),
+    fault: (input: Parameters<KernelAbi["fault"]>[0]) => kernelOrThrow().fault(input),
     // store is a live sub-object on the bound ABI — delegate per call, same
     // discipline as every other syscall (never captured before load())
     store: {
@@ -185,10 +186,11 @@ globals.loop = (body: LoopBody): void => ambientOrThrow().loop(body)
 globals.kernel = {
     output: (type: keyof AxonOutputEvent, data: never) => ambientOrThrow().kernel.output(type, data),
     stream: (req: never) => ambientOrThrow().kernel.stream(req),
-    run: ((code: string | string[], opts?: { signal?: AbortSignal }) => ambientOrThrow().kernel.run(code as never, opts)) as KernelAbi["run"],
+    run: ((code: string | string[]) => ambientOrThrow().kernel.run(code as never)) as KernelAbi["run"],
     scope: () => ambientOrThrow().kernel.scope(),
     base: () => ambientOrThrow().kernel.base(),
     emit: (type: never, data: never) => ambientOrThrow().kernel.emit(type, data),
+    fault: (input: Parameters<KernelAbi["fault"]>[0]) => ambientOrThrow().kernel.fault(input),
     store: {
         session: { get: (opts?: { after?: number }) => ambientOrThrow().kernel.store.session.get(opts) },
         get: (key: never) => ambientOrThrow().kernel.store.get(key),

package/src/air/air.ts

@@ -1,32 +0,0 @@
-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

@@ -1,103 +0,0 @@
-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

@@ -1,25 +0,0 @@
-// 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"
-
-/**
- * The <scope> block renderer, exported because the CLI's typegen must render
- * the SAME scope the model is shown — if the .d.ts and the <scope> block ever
- * disagreed, the editor would describe capabilities the model does not have.
- * One renderer, two consumers, no second implementation to drift.
- */
-export { renderScope } from "./render/blocks"
-export type { AirOpts } from "./grammar"
-export type {
-    AirBlockEvent,
-    AirMessage,
-    AirMode,
-    AirModeType,
-    AirRenderInput,
-} from "./types"

package/src/air/parse/index.ts

@@ -1,210 +0,0 @@
-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

@@ -1,35 +0,0 @@
-/** 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

@@ -1,242 +0,0 @@
-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 } : {}),
-            }
-    }
-}

package/src/air/render/index.ts

@@ -1,51 +0,0 @@
-import type { GrammarT } from "../grammar"
-import type { AirMessage, AirRenderInput } from "../types"
-import {
-    renderContract,
-    renderMeta,
-    renderScope,
-    renderSystem,
-    renderTimeline,
-} from "./blocks"
-
-type RenderOpts = {
-    grammar: GrammarT
-}
-
-/**
- * Render — domain in, ordered messages out. Pure.
- *
- * The caller passes what it holds (base string, AxonTool[], AxonEntry[]);
- * the block renderers own every translation into protocol shape. System
- * sections (meta, scope, system, contract) become individual system messages;
- * the timeline becomes a single user message — proper conversation structure
- * rather than one monolithic system prompt.
- *
- * Section order: <meta> → <scope> → <system> → <contract> → timeline
- */
-export function Render(opts: RenderOpts) {
-    const { grammar } = opts
-
-    return {
-        render(input: AirRenderInput): AirMessage[] {
-            const messages: AirMessage[] = []
-
-            const sys = (content: string) => {
-                if (content) messages.push({ role: "system", content })
-            }
-
-            sys(renderMeta(grammar))
-            if (input.scope) sys(renderScope(input.scope))
-            sys(renderSystem(input.base))
-            sys(renderContract(grammar))
-
-            if (input.history && input.history.length > 0) {
-                messages.push({ role: "user", content: renderTimeline(input.history) })
-            }
-
-            return messages
-        },
-    }
-}
-
-export type RenderT = ReturnType<typeof Render>

package/src/air/render/output.ts

@@ -1,144 +0,0 @@
-import { formatBytes } from "./text"
-
-/**
- * Capsule output projection — how raw capsule REPL output looks to the model.
- *
- * The capsule REPL emits a JSONL op-record envelope for every module function
- * call, followed by the raw auto-logged return value. This detects that
- * envelope, extracts the meaningful content per op type, and discards the
- * noise.
- *
- * For content-returning ops (fs.read, fs.list, ...) — show the content.
- * For mutation ops (fs.write, fs.mkdir, ...) — show a compact tick line.
- * For anything else — pass through unchanged.
- *
- * The silent catch fall-throughs here are correct, not masked failures:
- * this is a best-effort display projection where "show the raw string"
- * is the honest fallback for anything that doesn't parse.
- */
-export function formatCapsuleOutput(content: string): string {
-    const raw = content.trim()
-
-    // Plain JSON array — e.g. fs.list() return value serialised directly
-    if (raw.startsWith("[")) {
-        try {
-            const arr = JSON.parse(raw)
-            if (Array.isArray(arr)) {
-                if (arr.length === 0) return "(empty)"
-                // DirEntry[] — render as a compact directory listing
-                if (
-                    arr.length > 0 &&
-                    typeof arr[0] === "object" &&
-                    arr[0] !== null &&
-                    "name" in arr[0]
-                ) {
-                    return arr
-                        .map((e: any) => `${e.type === "directory" ? "d" : "-"}  ${e.name}`)
-                        .join("\n")
-                }
-                // Generic array of primitives or unknown objects
-                return arr
-                    .map((e: any) => (typeof e === "object" ? JSON.stringify(e) : String(e)))
-                    .join("\n")
-            }
-        } catch {
-            /* not JSON — fall through to raw */
-        }
-        return raw
-    }
-
-    if (!raw.startsWith("{")) return raw
-
-    // Extract all leading JSON op-record objects.
-    // Everything after the last op record (the raw auto-logged return value)
-    // is discarded — the meaningful content comes from the op record's data field.
-    const opRecords: any[] = []
-    let i = 0
-    while (i < raw.length && raw[i] === "{") {
-        let depth = 0
-        let j = i
-        while (j < raw.length) {
-            const ch = raw[j]
-            if (ch === '"') {
-                // skip over string contents, respecting escape sequences
-                j++
-                while (j < raw.length) {
-                    if (raw[j] === "\\") {
-                        j += 2
-                        continue
-                    }
-                    if (raw[j] === '"') {
-                        j++
-                        break
-                    }
-                    j++
-                }
-                continue
-            }
-            if (ch === "{") depth++
-            else if (ch === "}") {
-                depth--
-                if (depth === 0) {
-                    j++
-                    break
-                }
-            }
-            j++
-        }
-        try {
-            const obj = JSON.parse(raw.slice(i, j))
-            if ("op" in obj) opRecords.push(obj)
-            else if ("procId" in obj && "command" in obj) {
-                const tail = obj.tail ? `\n${obj.tail}` : ""
-                return `spawned  ${obj.command}  procId=${obj.procId}  pid=${obj.pid ?? "?"}  status=${obj.status ?? "running"}${tail}`
-            } else break
-        } catch {
-            break
-        }
-        i = j
-        while (i < raw.length && (raw[i] === "\n" || raw[i] === "\r")) i++
-    }
-
-    if (opRecords.length === 0) return raw
-
-    return opRecords
-        .map(obj => {
-            const op: string = obj.op ?? ""
-            const d = obj.data ?? {}
-
-            if (!obj.ok) {
-                return `${op}  ${d.path ?? ""}  ✗ ${obj.error ?? d.message ?? "failed"}`
-            }
-
-            switch (op) {
-                case "fs.read":
-                case "fs.readLines":
-                    return `read  ${d.path}  ${formatBytes(d.bytes ?? 0)}\n${d.content ?? ""}`
-                case "fs.list": {
-                    const entries: any[] = d.entries ?? []
-                    const lines = entries
-                        .map((e: any) => {
-                            const prefix = e.type === "directory" ? "d" : "-"
-                            return `${prefix}  ${e.name}`
-                        })
-                        .join("\n")
-                    return `list  ${d.path}  ${entries.length} entries\n${lines}`
-                }
-                case "fs.write":
-                    return `write  ${d.path}  ${formatBytes(d.bytes ?? 0)}  ✓`
-                case "fs.mkdir":
-                    return `mkdir  ${d.path}  ✓`
-                case "fs.delete":
-                    return `rm     ${d.path}  ✓`
-                case "fs.move":
-                    return `mv     ${d.src} → ${d.dest}  ✓`
-                case "fs.copy":
-                    return `cp     ${d.src} → ${d.dest}  ✓`
-                case "fs.cd":
-                    return `cd     ${d.path}  ✓`
-                default:
-                    return `${op}  ${JSON.stringify(d)}  ✓`
-            }
-        })
-        .join("\n")
-}

package/src/air/render/text.ts

@@ -1,85 +0,0 @@
-/** Pure string utilities for AIR rendering. */
-
-/** Escape XML text content (prose, stdout, user messages). */
-export function esc(s: string): string {
-    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
-}
-
-/** Escape a trusted value for a double-quoted XML attribute. */
-export function escAttr(s: string): string {
-    return esc(s).replace(/"/g, "&quot;").replace(/'/g, "&apos;")
-}
-
-/** Escape XML inside code blocks — only & and <. Never > (breaks =>, generics). */
-export function escCode(s: string): string {
-    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;")
-}
-
-/** Indent every line of s by `spaces` spaces. */
-export function indent(s: string, spaces: number): string {
-    const pad = " ".repeat(spaces)
-    return s
-        .split("\n")
-        .map(line => pad + line)
-        .join("\n")
-}
-
-export function formatBytes(n: number): string {
-    return n >= 1024 ? `${(n / 1024).toFixed(1)}K` : `${n}B`
-}
-
-/**
- * Normalize code that may contain literal \n or \t escape sequences outside
- * of string literals (a common model mistake). Replaces them with real
- * whitespace so the timeline shows clean, executable code.
- *
- * Best-effort heuristic: only acts on \n/\t outside single-quoted,
- * double-quoted, or template-literal strings.
- */
-export function normalizeCode(code: string): string {
-    // Fast path: no escape sequences at all
-    if (!code.includes("\\n") && !code.includes("\\t")) return code
-
-    let result = ""
-    let i = 0
-    while (i < code.length) {
-        const c = code[i]
-        // Track string boundaries to avoid replacing inside strings
-        if (c === '"' || c === "'" || c === "`") {
-            const quote = c
-            result += c
-            i++
-            while (i < code.length) {
-                const sc = code[i]
-                if (sc === "\\") {
-                    // Keep escape sequences inside strings as-is
-                    result += code[i] + (code[i + 1] ?? "")
-                    i += 2
-                } else if (sc === quote) {
-                    result += sc
-                    i++
-                    break
-                } else {
-                    result += sc
-                    i++
-                }
-            }
-        } else if (c === "\\" && i + 1 < code.length) {
-            const next = code[i + 1]
-            if (next === "n") {
-                result += "\n"
-                i += 2
-            } else if (next === "t") {
-                result += "\t"
-                i += 2
-            } else {
-                result += c + next
-                i += 2
-            }
-        } else {
-            result += c
-            i++
-        }
-    }
-    return result
-}

package/src/air/repair/index.ts

@@ -1 +0,0 @@
-export { repair } from "./repair"

package/src/air/repair/repair.ts

@@ -1,33 +0,0 @@
-/**
- * Deterministic, pre-parse repair of raw model output.
- *
- * Scope is deliberately narrow: string-only fixes for mistakes that are
- * common and unambiguous to correct. No semantic guessing, no model calls.
- * If a fix isn't mechanically certain, leave the text alone — the parser's
- * own incomplete/error reporting is the honest fallback, and that goes back
- * to the model as an `agent:output:error` for it to correct itself.
- *
- * Applied to the full buffered response before it reaches the AIR parser.
- */
-
-const KNOWN_TAGS = ["text", "thinking", "typescript", "shell"] as const
-
-export function repair(raw: string): string {
-    return normalizeTagCase(raw)
-}
-
-/**
- * Lowercase tag names the model emitted in the wrong case
- * (`<Text>`, `<TYPESCRIPT>`) — case is not semantically meaningful here,
- * so normalizing it can never change intent, only make it parseable.
- */
-function normalizeTagCase(raw: string): string {
-    let out = raw
-    for (const tag of KNOWN_TAGS) {
-        const open = new RegExp(`<(${tag})(\\s[^>]*)?>`, "gi")
-        const close = new RegExp(`</(${tag})>`, "gi")
-        out = out.replace(open, (match, _name, attrs) => `<${tag}${attrs ?? ""}>`)
-        out = out.replace(close, `</${tag}>`)
-    }
-    return out
-}

package/src/air/types.ts

@@ -1,71 +0,0 @@
-/**
- * AIR — Agent Intermediate Representation.
- *
- * A general-purpose LLM protocol: hand the renderer Axon's domain (base
- * context, declared tools, an event history) and it produces the ordered
- * messages a model sees. AIR owns BOTH halves — render (what the model
- * sees) and parse (what it emits back) — from one grammar, so they cannot
- * drift.
- *
- * The render boundary is DOMAIN in, messages out: callers pass AxonTool[]
- * and AxonEntry[], never AIR's internal render vocabulary. The
- * timeline item shapes below are private to render/ — the exhaustive
- * AxonEntry → item translation lives there, next to the parser it
- * must agree with.
- */
-
-import type { AxonEntry, AxonScope } from "@arcforge/types"
-
-// ── Messages ─────────────────────────────────────────────────────────────────
-
-export type AirMessage = {
-    role: "system" | "user" | "assistant"
-    content: string
-}
-
-// ── Modes (output grammar) ───────────────────────────────────────────────────
-
-export type AirModeType = "text" | "typescript" | "shell"
-
-export type AirMode = {
-    /** The output type this mode produces. */
-    type: AirModeType
-    /** Optional description override. Falls back to the default for the type. */
-    description?: string
-}
-
-// ── Render input ───────────────────────────────────────────────────────────
-//
-// DOMAIN in — the caller passes what it already holds. AIR owns every
-// translation into protocol shape: tools → <scope> declarations, entries →
-// <timeline> items. A cognet curates (which entries, what order, elided how)
-// and hands the lists over; it never manufactures AIR-internal types.
-
-export type AirRenderInput = {
-    /** Base context — the agent's identity contract. Rendered as <system>. */
-    base?: string
-    /** Capsule-implemented globals. Rendered as <scope lang="ts">. */
-    scope?: AxonScope
-    /** The event history to render, already curated by the cognet. Rendered as <timeline>. */
-    history?: readonly AxonEntry[]
-}
-
-// ── Parser output ────────────────────────────────────────────────────────────
-
-/**
- * Events emitted by the streaming AIR parser.
- *
- * *:delta — tokens inside a streamable block (<text>, <thinking>), real time.
- * *:done  — a block closed; content is the full inner text.
- *           `incomplete: true` means the stream ended without the closing tag —
- *           callers must treat these as format errors, never as valid actions.
- * done    — a <done/> self-closing tag was encountered.
- */
-export type AirBlockEvent =
-    | { type: "text:delta"; content: string }
-    | { type: "text:done"; content: string; incomplete?: true }
-    | { type: "thinking:delta"; content: string }
-    | { type: "thinking:done"; content: string; incomplete?: true }
-    | { type: "typescript:done"; content: string; incomplete?: true }
-    | { type: "shell:done"; content: string; incomplete?: true }
-    | { type: "done" }