@arcforge/cognet 2.0.115 → 2.0.116

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@arcforge/cognet",
-  "version": "2.0.115",
+  "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.115",
-    "@arcforge/types": "2.0.115",
+    "@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
@@ -186,7 +186,7 @@ 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),

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,58 +0,0 @@
-import type { AirMode, AirProtocolName } from "./types"
-import { MODE_DEFAULTS, resolveProtocol } from "./protocol"
-
-/**
- * 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.
- *
- * The variability point is `protocol` — a named grammar resolved as a unit
- * (see protocol/). Modes are not chosen independently of the prose that
- * describes them, so a caller picks a protocol and gets all three parts
- * consistent, or overrides modes explicitly and takes responsibility for
- * the pairing.
- */
-
-export type AirOpts = {
-    /** The output grammar. Default: classic (the two-block <typescript>/<text> contract). */
-    protocol?: AirProtocolName
-    /** Override the protocol's mode list. Rarely needed — prefer choosing a protocol. */
-    modes?: AirMode[]
-    /** Extra contract rules appended after the protocol's rules. */
-    extraRules?: string[]
-}
-
-export function Grammar(opts: AirOpts = {}) {
-    const protocol = resolveProtocol(opts.protocol ?? "classic")
-    const modes = opts.modes ?? protocol.modes
-
-    return {
-        protocol: protocol.name,
-        modes,
-        meta: protocol.meta,
-        rules: [...protocol.rules, ...(opts.extraRules ?? [])],
-        examples: protocol.examples,
-
-        /** 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 but is never a contract mode: models
-         * do not choose to emit it, providers inline it. The parser must
-         * recognise the tag in order to strip it, which is a parse concern,
-         * not a promise made to the model.
-         */
-        tags(): string[] {
-            return [...new Set(["thinking", ...modes.map(m => m.type)])]
-        },
-    }
-}
-
-export type GrammarT = ReturnType<typeof Grammar>

package/src/air/index.ts

@@ -1,37 +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"
-
-/**
- * The template renderer, exported because the SFC protocol's suspension
- * point lives in the consumer: the parser emits script/template blocks, the
- * consumer runs the script and resolves a scope, and this turns the template
- * into what the user reads.
- */
-export { Interpolate, InterpolationError } from "./interpolate"
-export type { InterpolateT, InterpolateOpts, Scope } from "./interpolate"
-
-export type {
-    AirBlockEvent,
-    AirMessage,
-    AirMode,
-    AirModeType,
-    AirProtocolName,
-    AirRenderInput,
-    AirTemplateLang,
-} from "./types"

package/src/air/interpolate/index.ts

@@ -1 +0,0 @@
-export { Interpolate, InterpolationError, type InterpolateT, type InterpolateOpts, type Scope } from "./interpolate"

package/src/air/interpolate/interpolate.ts

@@ -1,178 +0,0 @@
-import type { AirTemplateLang } from "../types"
-
-/**
- * Interpolate — the streaming template renderer.
- *
- * Feeds template source in and emits rendered output, replacing
- * {{ expression }} with values from a resolved scope. Streaming is the whole
- * point: literal text passes through the moment it arrives, so a template
- * with no interpolations streams exactly as fast as raw text did.
- *
- * The scope arrives asynchronously — the script that produces it runs while
- * the model is still generating the template. That race is resolved by
- * blocking at the first brace and nowhere else: text before any {{ is
- * released immediately, and only the segment that actually needs a value
- * waits for one. When the script wins the race (the common case, since token
- * generation is slower than a few file reads) nothing ever blocks.
- *
- * Rendered output is never patched after emission. A value the user has
- * already read is never revised — if an expression cannot be resolved, that
- * is an error the model must correct, not a glitch shown to the user.
- */
-
-export type Scope = Record<string, unknown>
-
-export type InterpolateOpts = {
-    lang: AirTemplateLang
-    /**
-     * Resolves the script's bindings. Awaited at the first interpolation
-     * only — a template with no braces never calls it.
-     */
-    scope: () => Promise<Scope>
-}
-
-/** Thrown when an expression cannot be evaluated against the resolved scope. */
-export class InterpolationError extends Error {
-    readonly expression: string
-    constructor(expression: string, cause: unknown) {
-        super(`could not evaluate {{ ${expression} }}: ${cause instanceof Error ? cause.message : String(cause)}`)
-        this.name = "InterpolationError"
-        this.expression = expression
-    }
-}
-
-const OPEN = "{{"
-const CLOSE = "}}"
-
-/**
- * How much of a brace-free tail is safe to emit now.
- *
- * A trailing "{" may be the first half of a split "{{", and a trailing "\"
- * may be the first character of a split "\{{" escape. Emitting either would
- * commit to a rendering the next chunk contradicts.
- */
-function safeEnd(buffer: string): number {
-    if (buffer.endsWith("{") || buffer.endsWith("\\")) return buffer.length - 1
-    return buffer.length
-}
-
-export function Interpolate(opts: InterpolateOpts) {
-    let buffer = ""
-    let resolved: Scope | null = null
-    /** Held so a template with several interpolations awaits the script once. */
-    let pending: Promise<Scope> | null = null
-
-    async function scope(): Promise<Scope> {
-        if (resolved) return resolved
-        pending ??= opts.scope()
-        resolved = await pending
-        return resolved
-    }
-
-    /**
-     * In JSON mode the template is exactly one interpolation, so the rendered
-     * output IS the serialised value — never a string spliced into
-     * hand-written syntax. Markdown renders values for reading.
-     */
-    function render(value: unknown): string {
-        if (opts.lang === "json") return JSON.stringify(value, null, 2) ?? "null"
-        if (typeof value === "string") return value
-        if (value === null || value === undefined) return String(value)
-        if (typeof value === "object") return JSON.stringify(value)
-        return String(value)
-    }
-
-    async function evaluate(expression: string): Promise<string> {
-        const s = await scope()
-        const names = Object.keys(s)
-        try {
-            // Bindings become named parameters, so an expression sees exactly
-            // the script's top-level scope and nothing from this closure.
-            const fn = new Function(...names, `"use strict"; return (${expression});`)
-            return render(fn(...names.map(n => s[n])))
-        } catch (cause) {
-            throw new InterpolationError(expression, cause)
-        }
-    }
-
-    /**
-     * Drain everything currently resolvable. Literal text is emitted up to
-     * the next `{{`; a complete `{{ ... }}` is evaluated and emitted in place.
-     * A trailing partial brace or unterminated expression stays buffered for
-     * the next chunk — `flushing` marks the stream over, so a partial open
-     * brace is genuine trailing text and an unterminated expression is an
-     * error rather than something still arriving.
-     */
-    async function drain(flushing: boolean): Promise<string> {
-        let out = ""
-
-        while (buffer.length > 0) {
-            const open = buffer.indexOf(OPEN)
-
-            if (open === -1) {
-                // Hold back a lone trailing "{" or an escape prefix that may
-                // still be completed by the next chunk.
-                const safe = flushing ? buffer.length : safeEnd(buffer)
-                out += buffer.slice(0, safe)
-                buffer = buffer.slice(safe)
-                break
-            }
-
-            // `\{{ ... }}` is a literal, not a value — the escape an agent
-            // needs to write ABOUT interpolation without performing it.
-            // Without this, explaining the output format is impossible: the
-            // example is evaluated, fails on a binding that was never meant
-            // to exist, and takes the message with it.
-            if (open > 0 && buffer[open - 1] === "\\") {
-                out += buffer.slice(0, open - 1) + OPEN
-                buffer = buffer.slice(open + OPEN.length)
-                continue
-            }
-
-            out += buffer.slice(0, open)
-
-            const close = buffer.indexOf(CLOSE, open + OPEN.length)
-            if (close === -1) {
-                buffer = buffer.slice(open)
-                if (flushing) {
-                    throw new InterpolationError(buffer.slice(OPEN.length).trim(), "unterminated interpolation")
-                }
-                break
-            }
-
-            const raw = buffer.slice(open + OPEN.length, close)
-            const expression = raw.trim()
-            buffer = buffer.slice(close + CLOSE.length)
-
-            // `{{ }}` with nothing in it is not an interpolation — it is an
-            // agent writing ABOUT interpolation, which it does whenever it
-            // explains its own output format. Evaluating an empty expression
-            // throws a syntax error and destroys the rest of the message, so
-            // the braces pass through verbatim: there is no value being asked
-            // for, and reproducing what was written is the only honest render.
-            if (expression.length === 0) {
-                out += OPEN + raw + CLOSE
-                continue
-            }
-
-            out += await evaluate(expression)
-        }
-
-        return out
-    }
-
-    return {
-        /** Feed template source. Returns rendered output ready to stream. */
-        feed(chunk: string): Promise<string> {
-            buffer += chunk
-            return drain(false)
-        },
-
-        /** End of template. Emits any held-back tail; throws on an unterminated expression. */
-        flush(): Promise<string> {
-            return drain(true)
-        },
-    }
-}
-
-export type InterpolateT = ReturnType<typeof Interpolate>

package/src/air/parse/index.ts

@@ -1,274 +0,0 @@
-import type { GrammarT } from "../grammar"
-import type { AirBlockEvent, AirTemplateLang } 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
- *   template    → inside <template>, streaming deltas token-by-token
- *   thinking    → inside <thinking>, streaming deltas token-by-token
- *   typescript  → inside <typescript>, buffering silently
- *   script      → inside <script>, buffering silently
- *
- * Tags are fixed and non-nesting. Attributes are tolerated on any tag, and
- * `lang` is captured on <template> because it selects the interpolation
- * serializer downstream — the only attribute that carries meaning.
- *
- * The parser stays synchronous and knows nothing about interpolation. Under
- * the SFC protocol it emits script:done, then template:open, then template
- * deltas — the consumer is what suspends between them to run the script.
- * Keeping the suspension out here is what leaves the parser pure and
- * testable against a fed string.
- */
-
-type BlockTag = "text" | "thinking" | "typescript" | "script" | "template"
-
-/** Blocks whose content streams as deltas. Code blocks buffer silently. */
-const STREAMABLE = new Set<BlockTag>(["text", "thinking", "template"])
-
-/**
- * How much of the buffer to hold back in idle mode so an opening tag split
- * across chunks can still be completed by the next one.
- *
- * This must cover the longest OPENING tag including its attributes, not just
- * the longest tag name: `<template lang="json">` is 22 chars, and holding
- * back fewer would discard its prefix as stray text before the rest arrived,
- * silently losing the lang and rendering JSON as markdown. Derived from the
- * grammar rather than hand-counted so a new tag cannot outgrow it.
- */
-const ATTR_ALLOWANCE = 16
-
-function maxTagLen(tags: string[]): number {
-    const longest = tags.reduce((n, t) => Math.max(n, t.length), 0)
-    return longest + "</>".length + ATTR_ALLOWANCE
-}
-
-/** Templates default to markdown; only an explicit lang="json" changes the serializer. */
-function templateLang(attrs: string | undefined): AirTemplateLang {
-    return /lang\s*=\s*["']?json["']?/i.test(attrs ?? "") ? "json" : "md"
-}
-
-/**
- * The delta event for a streamable tag. An explicit map rather than a
- * template-literal cast: the compiler checks every STREAMABLE tag has one,
- * so adding a streamable block cannot silently produce an unhandled event.
- */
-const DELTA = {
-    text: "text:delta",
-    thinking: "thinking:delta",
-    template: "template:delta",
-} as const satisfies Record<"text" | "thinking" | "template", AirBlockEvent["type"]>
-
-function delta(tag: BlockTag, content: string): AirBlockEvent {
-    return { type: DELTA[tag as keyof typeof DELTA], content }
-}
-
-type ParserOpts = {
-    grammar: GrammarT
-}
-
-export function Parser(opts: ParserOpts) {
-    const tags = opts.grammar.tags()
-    const openTag = new RegExp(`<(${tags.join("|")})(\\s[^>]*)?>`)
-    const MAX_TAG_LEN = maxTagLen(tags)
-
-    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 "script": return { type: "script:done", content }
-            case "template": return { type: "template: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; attrs?: string } | 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, attrs: openMatch[2] }
-            }
-        }
-
-        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 = ""
-                // Announced at open, not at close: the consumer must know
-                // which serializer applies before the first delta arrives,
-                // since deltas are released as they stream.
-                if (state === "template") {
-                    events.push({ type: "template:open", lang: templateLang(earliest.attrs) })
-                }
-            }
-            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 streamable = STREAMABLE.has(tag)
-
-        /**
-         * Code blocks scan from the START of the block, not from the
-         * unconsumed tail. String-literal state is only meaningful over the
-         * whole block: scanning a mid-code fragment starts outside a string
-         * by assumption, so a chunk boundary falling inside one (`fs.list("`
-         * / `src")`) would leave the scanner permanently mis-synced and it
-         * would never find the real closing tag. Streamable blocks have no
-         * such state, so they scan the tail directly.
-         */
-        const scanned = streamable ? buffer : blockContent + buffer
-        const offset = streamable ? 0 : blockContent.length
-
-        const found = streamable
-            ? scanned.indexOf(closeTag)
-            : findCloseTagOutsideStrings(scanned, closeTag)
-        const closeIdx = found === -1 ? -1 : found - offset
-
-        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(delta(tag, 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(delta(tag, 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>