@arcforge/cognet 2.0.97

package/src/air/render/index.ts

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

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

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

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

package/src/air/repair/repair.ts

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

@@ -0,0 +1,71 @@
+/**
+ * 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" }

package/src/clock.ts

@@ -0,0 +1,118 @@
+import { err } from "@axon/err"
+import type { KernelAbi } from "@arcforge/types"
+
+/** Telemetry sink — the cognet's own `kernel.emit`. Fire-and-forget, never awaited. */
+export type ClockEmit = KernelAbi["emit"]
+
+export type ClockOpts = {
+    emit: ClockEmit
+    /**
+     * The wake's own abort signal. Lets tick/phase/system tell an intentional
+     * interrupt (Escape/Ctrl+C, engine abort) apart from a genuine failure.
+     */
+    signal?: AbortSignal
+}
+
+/**
+ * Clock — the world clock and the execution wrappers that drive it.
+ *
+ * Every cognet has one, whether or not it holds a world: `phase()` and
+ * `system()` are ambient globals, and the host wraps each loop iteration in a
+ * tick. This is deliberately separate from the ECS so a cognet that never
+ * queries an entity — a control loop, a perception stack — doesn't carry an
+ * entity store it never touches.
+ *
+ * tick/phase/system are the ONLY writers of the clock. Each brackets its
+ * callback with telemetry so the shape of a thought is recorded as it happens
+ * rather than reconstructed afterward.
+ *
+ * Interrupt is a THIRD outcome, not a failure: when `signal` is aborted,
+ * whatever fn() threw is cancellation surfacing through the call stack, not a
+ * bug in the phase's own work. Emitting *:failed for that would conflate a
+ * cancelled thought with a broken one, and telemetry full of meaningless red
+ * is telemetry nobody reads. Real failures still emit *:failed and rethrow —
+ * telemetry never swallows.
+ */
+export function Clock(opts: ClockOpts) {
+    const { emit, signal } = opts
+
+    let tick = 0
+    let phase: string | null = null
+
+    /** tick/phase stamp merged into every event payload below tick level. */
+    function stamp() {
+        return { tick, phase }
+    }
+
+    return {
+        get tick() {
+            return tick
+        },
+        get phase() {
+            return phase
+        },
+        stamp,
+
+        /** One iteration of the cognitive loop. Advances the clock. */
+        async runTick<T>(fn: () => Promise<T>): Promise<T> {
+            tick += 1
+            const current = tick
+            void emit("cognet:tick:start", { tick: current })
+            try {
+                const result = await fn()
+                void emit("cognet:tick:complete", { tick: current })
+                return result
+            } catch (cause) {
+                if (signal?.aborted) {
+                    void emit("cognet:tick:interrupted", { tick: current })
+                    throw cause
+                }
+                const failure = err(cause)
+                void emit("cognet:tick:failed", { tick: current, error: failure })
+                throw failure
+            }
+        },
+
+        /** A named stage within a tick. Sets the current phase for its duration. */
+        async runPhase<T>(name: string, fn: () => Promise<T>): Promise<T> {
+            phase = name
+            void emit("cognet:phase:start", { tick, phase: name })
+            try {
+                const result = await fn()
+                void emit("cognet:phase:complete", { tick, phase: name })
+                return result
+            } catch (cause) {
+                if (signal?.aborted) {
+                    void emit("cognet:phase:interrupted", { tick, phase: name })
+                    throw cause
+                }
+                const failure = err(cause)
+                void emit("cognet:phase:failed", { tick, phase: name, error: failure })
+                throw failure
+            } finally {
+                phase = null
+            }
+        },
+
+        /** A unit of work within a phase. Timed for the flame graph. */
+        async runSystem<T>(name: string, fn: () => Promise<T>): Promise<T> {
+            const started = Date.now()
+            void emit("cognet:system:start", { ...stamp(), system: name })
+            try {
+                const result = await fn()
+                void emit("cognet:system:complete", { ...stamp(), system: name, durationMs: Date.now() - started })
+                return result
+            } catch (cause) {
+                if (signal?.aborted) {
+                    void emit("cognet:system:interrupted", { ...stamp(), system: name })
+                    throw cause
+                }
+                const failure = err(cause)
+                void emit("cognet:system:failed", { ...stamp(), system: name, error: failure })
+                throw failure
+            }
+        },
+    }
+}
+
+export type ClockT = ReturnType<typeof Clock>

package/src/define.ts

@@ -0,0 +1,11 @@
+import type { CognetDefinition } from "@arcforge/types"
+
+/**
+ * The cognet authoring surface. Cognet projects (cognets/*) call this in
+ * their main.ts; the CLI bundle gets it as an injected global — the
+ * desugared form and the global form compile to the same thing, so there
+ * is never a side channel around the ABI.
+ */
+export function defineCognet(definition: CognetDefinition): CognetDefinition {
+    return definition
+}

package/src/ecs/component.ts

@@ -0,0 +1,78 @@
+import type { StateT } from "./state"
+import type { ComponentRegistry, ComponentType, EntityId } from "./types"
+import type { EcsEmit } from "./ecs"
+
+type ComponentOpts = {
+    state: StateT
+    emit: EcsEmit
+}
+
+/**
+ * Component — the single write path for component data.
+ * Every write emits kernel telemetry and fires watchers; Entity() delegates
+ * here so there is exactly one place a component can change.
+ *
+ * Telemetry goes to the runtime bus (→ tracing pipeline), never the session
+ * log. Bus emit never rejects (handler errors are re-emitted as
+ * axon:bus:error), so firing without await keeps writes synchronous.
+ */
+export function Component(opts: ComponentOpts) {
+    const { state, emit } = opts
+
+    return {
+        add<K extends ComponentType>({
+            entity,
+            type,
+            data,
+        }: {
+            entity: EntityId
+            type: K
+            data: ComponentRegistry[K]
+        }) {
+            let store = state.components.get(type)
+            if (!store) {
+                store = new Map<EntityId, ComponentRegistry[K]>()
+                state.components.set(type, store)
+            }
+
+            const existed = store.has(entity)
+            store.set(entity, data)
+
+            void emit(existed ? "cognet:component:update" : "cognet:component:add", {
+                ...state.stamp(),
+                entity,
+                component: type,
+            })
+
+            state.notify(type, entity, data)
+        },
+
+        remove<K extends ComponentType>({ entity, type }: { entity: EntityId; type: K }) {
+            const store = state.components.get(type)
+            if (!store?.has(entity)) return
+            store.delete(entity)
+
+            void emit("cognet:component:remove", {
+                ...state.stamp(),
+                entity,
+                component: type,
+            })
+        },
+
+        get<K extends ComponentType>({
+            entity,
+            type,
+        }: {
+            entity: EntityId
+            type: K
+        }): ComponentRegistry[K] | undefined {
+            return state.components.get(type)?.get(entity)
+        },
+
+        has<K extends ComponentType>({ entity, type }: { entity: EntityId; type: K }): boolean {
+            return state.components.get(type)?.has(entity) ?? false
+        },
+    }
+}
+
+export type ComponentT = ReturnType<typeof Component>

package/src/ecs/ecs.ts

@@ -0,0 +1,51 @@
+import type { KernelAbi } from "@arcforge/types"
+import { Component } from "./component"
+import { Entity } from "./entity"
+import { State } from "./state"
+
+/** Telemetry sink — cognets pass abi.emit; fire-and-forget, never awaited. Typed against cognet:*. */
+export type EcsEmit = KernelAbi["emit"]
+
+export type EcsOpts = {
+    emit: EcsEmit
+    /**
+     * The clock's stamp. Every world mutation is attributed to the tick and
+     * phase it happened in, so the mutation history replays against the clock
+     * rather than being a flat list of writes.
+     */
+    stamp(): { tick: number; phase: string | null }
+}
+
+/**
+ * Ecs — the wake-scoped world: entities, components, and queries over both.
+ *
+ * A WORKING SET, not memory. Persistence lives in the session log and durable
+ * cognitive state in kernel.store; if an entity matters beyond this wake, it
+ * was derived from the log and the next wake derives it again.
+ *
+ * Deliberately opt-in. The world clock (tick/phase/system) is separate and
+ * always present — see ../clock.ts — so a control loop or perception stack
+ * that never queries an entity carries none of this.
+ *
+ * State() owns the store; Component() and Entity() are the write paths, and
+ * Entity delegates to Component so there is exactly one place a component can
+ * change — which is what makes telemetry and watchers reliable rather than
+ * best-effort.
+ */
+export function Ecs(opts: EcsOpts) {
+    const state = State({ stamp: opts.stamp })
+
+    const component = Component({ state, emit: opts.emit })
+    const entity = Entity({ state, component, emit: opts.emit })
+
+    return {
+        state: state,
+        entity: entity,
+        component: component,
+
+        query: state.query,
+        watch: state.watch,
+    }
+}
+
+export type EcsT = ReturnType<typeof Ecs>