muonroi-cli 1.3.4 → 1.4.1

package/dist/src/self-qa/agentic-loop.js

@@ -0,0 +1,516 @@
+/**
+ * agentic-loop.ts — Tier 2 of Self-QA.
+ *
+ * Outer LLM (configured provider, e.g. DeepSeek) drives the inner muonroi-cli
+ * interactively:
+ *
+ *   1. Spawn child + wait idle
+ *   2. Build context block (current frame + delta vs last + event tail)
+ *   3. brain.decide(ctx) → AgenticDecision ({type/press/wait_for/done})
+ *   4. Execute decision via Driver
+ *   5. Observe new frame + events → loop
+ *
+ * Terminates when the brain returns `{action: "done"}` OR max turns hit OR
+ * the child crashes / disconnects.
+ *
+ * The brain is pluggable: `createMockBrain` for tests, `createLLMBrain` for
+ * production. Brain only needs access to the prompt block + a free-form goal
+ * — it knows nothing about Driver internals.
+ */
+import { resolve } from "node:path";
+import { createDriver } from "@muonroi/agent-harness-core/driver";
+import { createLineSplitter } from "@muonroi/agent-harness-core/transports/sidechannel";
+import { generateObject, generateText } from "ai";
+import { z } from "zod";
+import { spawnAgentTui } from "../agent-harness/test-spawn.js";
+import { loadKeyForProvider } from "../providers/keychain.js";
+import { createProviderFactory, detectProviderForModel, resolveModelRuntime } from "../providers/runtime.js";
+import { buildAgenticContext } from "./agentic-context.js";
+// ── Zod schema for the decision union — used with generateObject to force
+// structured output instead of free-text JSON (which reasoning models
+// frequently corrupt with thinking prose). ────────────────────────────────
+const DecisionSchema = z.discriminatedUnion("action", [
+    z.object({ action: z.literal("type"), text: z.string(), reason: z.string() }),
+    z.object({ action: z.literal("press"), key: z.string(), reason: z.string() }),
+    z.object({
+        action: z.literal("wait_for"),
+        selector: z.string().optional(),
+        event: z.string().optional(),
+        idle: z.boolean().optional(),
+        timeoutMs: z.number().optional(),
+        reason: z.string(),
+    }),
+    z.object({
+        action: z.literal("done"),
+        verdict: z.enum(["pass", "fail", "inconclusive"]),
+        reason: z.string(),
+    }),
+]);
+// ---------------------------------------------------------------------------
+// Mock brain — for tests / deterministic playback
+// ---------------------------------------------------------------------------
+export function createMockBrain(script) {
+    let i = 0;
+    return {
+        async decide() {
+            if (i >= script.length) {
+                return { action: "done", verdict: "inconclusive", reason: "mock script exhausted" };
+            }
+            const next = script[i++];
+            return next;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// LLM brain — uses the configured provider stack
+// ---------------------------------------------------------------------------
+const DEFAULT_SYSTEM_PROMPT = `You are a QA agent driving a TUI via an agent-harness.
+Your job: given a free-form goal and the current TUI state (semantic tree + recent events),
+decide the SINGLE next action.
+
+Reply with a strict JSON object — no prose, no markdown fences:
+
+  {"action":"type","text":"...","reason":"short"}
+  {"action":"press","key":"Enter|Escape|Down|Up|Tab","reason":"short"}
+  {"action":"wait_for","idle":true,"timeoutMs":5000,"reason":"..."}
+  {"action":"wait_for","selector":"id=askcard","timeoutMs":5000,"reason":"..."}
+  {"action":"wait_for","event":"askcard-open","timeoutMs":5000,"reason":"..."}
+  {"action":"done","verdict":"pass","reason":"goal achieved"}
+  {"action":"done","verdict":"fail","reason":"goal cannot be achieved"}
+
+Rules:
+- One action per turn. Do not batch.
+- Prefer wait_for after type/press to let the TUI settle.
+- If the goal looks satisfied, return done(pass).
+- If an error toast appears or the TUI is stuck, return done(fail).
+- Stay within ${"${maxTurns}"} turns. Be concise.`;
+/**
+ * Pull a usable text body out of an AI SDK generateText result.
+ *
+ * Reasoning models (DeepSeek-V4-Flash, SiliconFlow R1, etc.) sometimes
+ * route the visible output to `result.reasoning` instead of `result.text`,
+ * or embed thinking inside `<think>…</think>` blocks. This walker tries:
+ *
+ *   1. `result.text` (canonical)
+ *   2. `result.reasoning` (some providers expose only this)
+ *   3. Concatenation of `parts[].text` (AI SDK v5+ shape)
+ *
+ * Then strips `<think>…</think>` so the JSON object emerges cleanly.
+ */
+function extractBrainText(res) {
+    // biome-ignore lint/suspicious/noExplicitAny: heterogeneous SDK result
+    const r = res;
+    const candidates = [];
+    if (typeof r?.text === "string")
+        candidates.push(r.text);
+    if (typeof r?.reasoning === "string")
+        candidates.push(r.reasoning);
+    if (Array.isArray(r?.content)) {
+        for (const p of r.content)
+            if (typeof p?.text === "string")
+                candidates.push(p.text);
+    }
+    for (const c of candidates) {
+        const stripped = c.replace(/<think>[\s\S]*?<\/think>/gi, "").trim();
+        if (stripped.length > 0)
+            return stripped;
+    }
+    // Last resort: return whatever was longest, even if it's just thinking text.
+    return (candidates.sort((a, b) => b.length - a.length)[0] ?? "").trim();
+}
+export async function createLLMBrain(opts) {
+    // 1) Silence the cosmetic "responseFormat schema only supported with
+    //    structuredOutputs" warning — we know DeepSeek only supports
+    //    response_format={type:"json_object"} and the strategy sets
+    //    supportsStructuredOutputs=false; the warning is informational.
+    // 2) Default-on thinking disable for DeepSeek so JSON-only output
+    //    flows without reasoning prose leaking through.
+    // biome-ignore lint/suspicious/noExplicitAny: global flag is AI SDK's docs convention
+    globalThis.AI_SDK_LOG_WARNINGS = false;
+    if (process.env["MUONROI_DEEPSEEK_DISABLE_THINKING"] === undefined) {
+        process.env["MUONROI_DEEPSEEK_DISABLE_THINKING"] = "1";
+    }
+    const provider = detectProviderForModel(opts.modelId);
+    if (!provider)
+        throw new Error(`No provider detected for model '${opts.modelId}'`);
+    const apiKey = await loadKeyForProvider(provider);
+    if (!apiKey)
+        throw new Error(`No API key found for provider '${provider}'`);
+    const { factory } = createProviderFactory(provider, { apiKey });
+    const runtime = resolveModelRuntime(factory, opts.modelId);
+    const systemPrompt = opts.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+    const maxTokens = opts.maxTokens ?? 1024;
+    const retryOnEmpty = opts.retryOnEmpty !== false;
+    // @ai-sdk/openai-compatible's chat schema exposes `strictJsonSchema: false`
+    // for providers that don't honour OpenAI's strict JSON schema mode.
+    // DeepSeek (and DeepSeek-compatible providers like SiliconFlow) only
+    // support `response_format: {type: "json_object"}` — they reject the full
+    // schema response_format. Setting strictJsonSchema=false makes AI SDK fall
+    // back to lenient json_object mode silently (no "responseFormat not
+    // supported" warning) while still steering the model toward JSON output.
+    //
+    // Disabling DeepSeek thinking mode would require `extra_body.thinking
+    // .type=disabled` per https://api-docs.deepseek.com/guides/thinking_mode
+    // — but openai-compatible v2.0.42 does not expose a generic extraBody
+    // knob, so that's left to a future provider patch.
+    const mergedProviderOptions = {
+        ...(runtime.providerOptions ?? {}),
+    };
+    if (provider === "deepseek" || provider === "siliconflow") {
+        mergedProviderOptions[provider] = {
+            ...(mergedProviderOptions[provider] ?? {}),
+            strictJsonSchema: false,
+        };
+    }
+    async function callStructured(userPrompt) {
+        try {
+            const res = await generateObject({
+                model: runtime.model,
+                schema: DecisionSchema,
+                system: systemPrompt,
+                prompt: userPrompt,
+                maxOutputTokens: maxTokens,
+                // biome-ignore lint/suspicious/noExplicitAny: AI SDK ProviderOptions type is too narrow for dynamic builds
+                providerOptions: mergedProviderOptions,
+            });
+            return res.object;
+        }
+        catch {
+            return null;
+        }
+    }
+    async function callFreeText(userPrompt) {
+        const res = await generateText({
+            model: runtime.model,
+            system: `${systemPrompt}\n\nReply with ONE LINE of JSON only. No prose, no markdown fences, no <think> blocks.`,
+            prompt: userPrompt,
+            maxOutputTokens: maxTokens,
+            // biome-ignore lint/suspicious/noExplicitAny: AI SDK ProviderOptions type is too narrow for dynamic builds
+            providerOptions: mergedProviderOptions,
+        });
+        const text = extractBrainText(res);
+        return { text, decision: parseDecision(text) };
+    }
+    return {
+        async decide({ goal, context, historyExcerpt, turn, maxTurns }) {
+            const userPrompt = [
+                `## Goal`,
+                goal,
+                ``,
+                `## Turn ${turn}/${maxTurns}`,
+                ``,
+                `## History (most recent decisions)`,
+                historyExcerpt || "(no prior turns)",
+                ``,
+                `## TUI state`,
+                context.prompt,
+                ``,
+                `## Your reply — emit a single structured decision now.`,
+            ].join("\n");
+            // Primary path: structured output (forces schema-conformant JSON).
+            const structured = await callStructured(userPrompt);
+            if (structured)
+                return structured;
+            // Fallback: free-text generateText + parseDecision, with one retry.
+            const first = await callFreeText(userPrompt);
+            if (first.decision)
+                return first.decision;
+            let lastText = first.text;
+            if (retryOnEmpty) {
+                const stricter = `${userPrompt}\n\nReminder: emit exactly one JSON object such as {"action":"press","key":"Enter","reason":"..."}. Nothing else.`;
+                const second = await callFreeText(stricter);
+                if (second.decision)
+                    return second.decision;
+                lastText = second.text || lastText;
+            }
+            return {
+                action: "done",
+                verdict: "inconclusive",
+                reason: `Brain emitted unparseable output: ${lastText.slice(0, 200) || "(empty)"}`,
+            };
+        },
+    };
+}
+export function parseDecision(raw) {
+    // Strip ```json fences if any LLM ignores instructions.
+    const trimmed = raw
+        .replace(/```(?:json)?\s*/gi, "")
+        .replace(/```/g, "")
+        .trim();
+    // Scan for every {...} candidate (brace-balanced) and try each, biggest first.
+    const candidates = extractJsonCandidates(trimmed);
+    for (const slice of candidates) {
+        const parsed = tryParseDecisionSlice(slice);
+        if (parsed)
+            return parsed;
+    }
+    // Last-resort: span from first { to last } as a single attempt.
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start < 0 || end <= start)
+        return null;
+    return tryParseDecisionSlice(trimmed.slice(start, end + 1));
+}
+function extractJsonCandidates(text) {
+    const out = [];
+    let depth = 0;
+    let start = -1;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === "{") {
+            if (depth === 0)
+                start = i;
+            depth++;
+        }
+        else if (ch === "}") {
+            depth--;
+            if (depth === 0 && start >= 0) {
+                out.push(text.slice(start, i + 1));
+                start = -1;
+            }
+        }
+    }
+    // Try longest first — usually the most complete object.
+    return out.sort((a, b) => b.length - a.length);
+}
+function tryParseDecisionSlice(slice) {
+    try {
+        const obj = JSON.parse(slice);
+        if (typeof obj["action"] !== "string")
+            return null;
+        const action = obj["action"];
+        const reason = typeof obj["reason"] === "string" ? obj["reason"] : "";
+        switch (action) {
+            case "type":
+                if (typeof obj["text"] === "string")
+                    return { action, text: obj["text"], reason };
+                return null;
+            case "press":
+                if (typeof obj["key"] === "string")
+                    return { action, key: obj["key"], reason };
+                return null;
+            case "wait_for": {
+                const w = {
+                    action,
+                    reason,
+                    timeoutMs: typeof obj["timeoutMs"] === "number" ? obj["timeoutMs"] : 5_000,
+                };
+                if (obj["idle"] === true)
+                    w.idle = true;
+                if (typeof obj["selector"] === "string")
+                    w.selector = obj["selector"];
+                if (typeof obj["event"] === "string")
+                    w.event = obj["event"];
+                return w;
+            }
+            case "done": {
+                const v = obj["verdict"];
+                if (v === "pass" || v === "fail" || v === "inconclusive") {
+                    return { action, verdict: v, reason };
+                }
+                return null;
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+export async function runAgenticLoop(opts) {
+    const log = opts.log ?? (() => { });
+    const maxTurns = opts.maxTurns ?? 20;
+    const budget = opts.budgetMs ?? 5 * 60_000;
+    const startedAt = Date.now();
+    const events = [];
+    let lastFrame = null;
+    const entry = opts.entry ?? resolve("src/index.ts");
+    const mockDir = opts.mockLlmDir ?? resolve("tests/harness/fixtures/llm");
+    const args = [entry, "--agent-mode", "--mock-llm", mockDir, ...(opts.extraArgs ?? [])];
+    const env = {
+        ...process.env,
+        MUONROI_TEST_NO_PERSIST: "1",
+        MUONROI_INTERNAL_SHIM_OK: "1",
+        ...(opts.env ?? {}),
+    };
+    log(`[agentic] Spawning child: ${entry}`);
+    const spawn = await spawnAgentTui(args, { spawnOpts: { env } });
+    const driver = wireDriver(spawn.inWrite, spawn.outRead);
+    // Collect every event into the bus.
+    void (async () => {
+        try {
+            for await (const e of driver.events())
+                events.push(e);
+        }
+        catch { }
+    })();
+    let crashed = false;
+    let crashReason = "";
+    spawn.proc.on("exit", (code, signal) => {
+        if (code !== null && code !== 0) {
+            crashed = true;
+            crashReason = `child exited code=${code} signal=${signal ?? "none"}`;
+        }
+        driver._closeAllSubscribers();
+    });
+    const turns = [];
+    let verdict = "inconclusive";
+    let reason = "loop terminated without explicit verdict";
+    try {
+        // Initial idle.
+        try {
+            await driver.wait_for({ idle: true, timeoutMs: 15_000 });
+        }
+        catch { }
+        lastFrame = driver.snapshot();
+        for (let turn = 1; turn <= maxTurns; turn++) {
+            if (Date.now() - startedAt > budget) {
+                verdict = "inconclusive";
+                reason = `wall-clock budget ${budget}ms exhausted at turn ${turn}`;
+                break;
+            }
+            if (crashed) {
+                verdict = "inconclusive";
+                reason = crashReason;
+                break;
+            }
+            const before = driver.snapshot();
+            const eventsBefore = events.length;
+            const context = buildAgenticContext(lastFrame, before, events.slice(-20), {
+                pinIds: opts.pinIds ?? ["askcard"],
+            });
+            const historyExcerpt = turns
+                .slice(-5)
+                .map((t) => {
+                const d = t.decision;
+                let detail = "";
+                if (d.action === "type")
+                    detail = ` text=${JSON.stringify(d.text)}`;
+                else if (d.action === "press")
+                    detail = ` key=${d.key}`;
+                else if (d.action === "wait_for")
+                    detail = ` ${d.idle ? "idle" : (d.selector ?? d.event ?? "")}`;
+                return `T${t.turn}: ${d.action}${detail} — ${truncate(d.reason, 60)}`;
+            })
+                .join("\n");
+            log(`[agentic] T${turn}/${maxTurns} — context ~${context.estimatedTokens} tokens`);
+            const t0 = Date.now();
+            let decision;
+            try {
+                decision = await opts.brain.decide({
+                    goal: opts.goal,
+                    context,
+                    historyExcerpt,
+                    turn,
+                    maxTurns,
+                });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                verdict = "inconclusive";
+                reason = `brain.decide threw: ${msg}`;
+                turns.push({
+                    turn,
+                    decision: { action: "done", verdict: "inconclusive", reason: msg },
+                    observedSeq: before?.seq ?? null,
+                    newEvents: 0,
+                    durationMs: Date.now() - t0,
+                });
+                break;
+            }
+            log(`[agentic]   → ${decision.action}${"reason" in decision ? `: ${truncate(decision.reason, 60)}` : ""}`);
+            if (decision.action === "done") {
+                verdict = decision.verdict;
+                reason = decision.reason;
+                turns.push({
+                    turn,
+                    decision,
+                    observedSeq: before?.seq ?? null,
+                    newEvents: events.length - eventsBefore,
+                    durationMs: Date.now() - t0,
+                });
+                break;
+            }
+            try {
+                await executeDecision(driver, decision);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                // wait_for timeouts are common — brain gets to see and adapt.
+                log(`[agentic]     (action threw: ${truncate(msg, 80)})`);
+            }
+            lastFrame = before;
+            turns.push({
+                turn,
+                decision,
+                observedSeq: driver.snapshot()?.seq ?? null,
+                newEvents: events.length - eventsBefore,
+                durationMs: Date.now() - t0,
+            });
+        }
+    }
+    finally {
+        try {
+            spawn.proc.kill();
+        }
+        catch { }
+        spawn.cleanup();
+    }
+    return {
+        goal: opts.goal,
+        verdict,
+        reason,
+        turns,
+        totalDurationMs: Date.now() - startedAt,
+        events,
+        finalFrame: lastFrame,
+    };
+}
+async function executeDecision(driver, d) {
+    switch (d.action) {
+        case "type":
+            driver.type(d.text);
+            return;
+        case "press":
+            driver.press(d.key);
+            return;
+        case "wait_for": {
+            const timeout = d.timeoutMs ?? 5_000;
+            if (d.idle)
+                return driver.wait_for({ idle: true, timeoutMs: timeout });
+            if (d.selector)
+                return driver.wait_for({ selector: d.selector, timeoutMs: timeout });
+            if (d.event)
+                return driver.wait_for({ event: d.event, timeoutMs: timeout });
+            return;
+        }
+        case "done":
+            return;
+    }
+}
+function wireDriver(inWrite, outRead) {
+    const driver = createDriver({
+        sendKey: (k) => inWrite.write(`${JSON.stringify({ op: "press", key: k })}\n`),
+        sendType: (t) => inWrite.write(`${JSON.stringify({ op: "type", text: t })}\n`),
+    });
+    const splitter = createLineSplitter((line) => {
+        try {
+            const msg = JSON.parse(line);
+            if (msg["mode"] === "live")
+                driver._ingest({ kind: "frame", frame: msg });
+            else if (msg["t"] === "idle")
+                driver._ingest({ kind: "idle" });
+            else if (msg["t"] === "event")
+                driver._ingest({ kind: "event", event: msg });
+        }
+        catch { }
+    });
+    outRead.on("data", (chunk) => {
+        splitter(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    });
+    return driver;
+}
+function truncate(s, max) {
+    return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
+}
+//# sourceMappingURL=agentic-loop.js.map

package/dist/src/self-qa/delta-encoder.d.ts

@@ -0,0 +1,35 @@
+/**
+ * delta-encoder.ts — M3 of Self-QA.
+ *
+ * Diffs two LiveFrames and emits only the changed UINodes. Keeps the
+ * outer-agent token cost flat regardless of UI tree size — the agent
+ * sees what *changed*, not the entire frame on every tick.
+ *
+ * Algorithm:
+ *   1. Build flat id→UINode maps for both frames.
+ *   2. added   = ids in `next` not in `prev`
+ *   3. removed = ids in `prev` not in `next`
+ *   4. changed = ids in both whose user-visible fields differ
+ *   5. focusChanged / modalsChanged tracked separately.
+ *
+ * Children traversal is depth-first and treats nodes as identity-keyed by `id`.
+ */
+import type { LiveFrame } from "@muonroi/agent-harness-core/protocol";
+import type { FrameDelta } from "./types.js";
+/**
+ * Compute a FrameDelta from `prev` to `next`. Pass `prev === null` for the
+ * first frame — the result will have all nodes as `added` and `baseSeq=null`.
+ */
+export declare function encodeDelta(prev: LiveFrame | null, next: LiveFrame): FrameDelta;
+/**
+ * Re-apply a delta on top of a previous frame to reconstruct the next.
+ * Useful for tests and for any consumer that wants to materialise state
+ * without storing every frame.
+ */
+export declare function applyDelta(prev: LiveFrame | null, delta: FrameDelta): LiveFrame;
+/**
+ * Estimate the wire-size savings of a delta vs. the full next frame.
+ * Returns the compression ratio as a number in [0, 1], where smaller is better.
+ * Useful for budget tuning.
+ */
+export declare function compressionRatio(next: LiveFrame, delta: FrameDelta): number;

package/dist/src/self-qa/delta-encoder.js

@@ -0,0 +1,138 @@
+/**
+ * delta-encoder.ts — M3 of Self-QA.
+ *
+ * Diffs two LiveFrames and emits only the changed UINodes. Keeps the
+ * outer-agent token cost flat regardless of UI tree size — the agent
+ * sees what *changed*, not the entire frame on every tick.
+ *
+ * Algorithm:
+ *   1. Build flat id→UINode maps for both frames.
+ *   2. added   = ids in `next` not in `prev`
+ *   3. removed = ids in `prev` not in `next`
+ *   4. changed = ids in both whose user-visible fields differ
+ *   5. focusChanged / modalsChanged tracked separately.
+ *
+ * Children traversal is depth-first and treats nodes as identity-keyed by `id`.
+ */
+const TRACKED_FIELDS = ["name", "value", "state", "focus", "selected", "disabled", "hidden"];
+/**
+ * Compute a FrameDelta from `prev` to `next`. Pass `prev === null` for the
+ * first frame — the result will have all nodes as `added` and `baseSeq=null`.
+ */
+export function encodeDelta(prev, next) {
+    const prevMap = prev ? indexNodes(prev.nodes) : new Map();
+    const nextMap = indexNodes(next.nodes);
+    const added = [];
+    const removed = [];
+    const changed = [];
+    for (const [id, node] of nextMap) {
+        if (!prevMap.has(id)) {
+            added.push(stripChildren(node));
+        }
+        else {
+            const diff = diffFields(prevMap.get(id), node);
+            if (diff)
+                changed.push({ id, fields: diff });
+        }
+    }
+    for (const id of prevMap.keys()) {
+        if (!nextMap.has(id))
+            removed.push(id);
+    }
+    const delta = {
+        seq: next.seq,
+        baseSeq: prev?.seq ?? null,
+        added,
+        removed,
+        changed,
+    };
+    if (prev?.focus !== next.focus) {
+        delta.focusChanged = { from: prev?.focus, to: next.focus };
+    }
+    const prevModals = prev?.modals ?? [];
+    const nextModals = next.modals ?? [];
+    if (!arraysEqual(prevModals, nextModals)) {
+        delta.modalsChanged = { from: prevModals, to: nextModals };
+    }
+    return delta;
+}
+/**
+ * Re-apply a delta on top of a previous frame to reconstruct the next.
+ * Useful for tests and for any consumer that wants to materialise state
+ * without storing every frame.
+ */
+export function applyDelta(prev, delta) {
+    const map = prev ? indexNodes(prev.nodes) : new Map();
+    for (const id of delta.removed)
+        map.delete(id);
+    for (const node of delta.added)
+        map.set(node.id, node);
+    for (const c of delta.changed) {
+        const existing = map.get(c.id);
+        if (!existing)
+            continue;
+        map.set(c.id, { ...existing, ...c.fields });
+    }
+    const nodes = [...map.values()];
+    return {
+        mode: "live",
+        version: prev?.version ?? "0.4.0",
+        seq: delta.seq,
+        ts: Date.now(),
+        focus: delta.focusChanged ? delta.focusChanged.to : prev?.focus,
+        modals: delta.modalsChanged ? delta.modalsChanged.to : prev?.modals,
+        nodes,
+    };
+}
+/**
+ * Estimate the wire-size savings of a delta vs. the full next frame.
+ * Returns the compression ratio as a number in [0, 1], where smaller is better.
+ * Useful for budget tuning.
+ */
+export function compressionRatio(next, delta) {
+    const fullSize = JSON.stringify(next).length;
+    const deltaSize = JSON.stringify(delta).length;
+    if (fullSize === 0)
+        return 1;
+    return deltaSize / fullSize;
+}
+function indexNodes(nodes) {
+    const out = new Map();
+    walk(nodes, (n) => out.set(n.id, n));
+    return out;
+}
+function walk(nodes, cb) {
+    for (const n of nodes) {
+        cb(n);
+        if (n.children)
+            walk(n.children, cb);
+    }
+}
+function stripChildren(node) {
+    // Keep children for `added` because the outer agent needs context, but
+    // recurse via the index so each subtree node was already emitted.
+    // We return shallow copy without `children` to avoid double-emission.
+    const { children: _children, ...rest } = node;
+    return rest;
+}
+function diffFields(prev, next) {
+    const out = {};
+    let dirty = false;
+    for (const f of TRACKED_FIELDS) {
+        if (prev[f] !== next[f]) {
+            // biome-ignore lint/suspicious/noExplicitAny: heterogeneous union write
+            out[f] = next[f];
+            dirty = true;
+        }
+    }
+    return dirty ? out : null;
+}
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+//# sourceMappingURL=delta-encoder.js.map