@dungle-scrubs/harness-cli-normalizer 0.1.1

package/dist/execution/stream-turn.js

@@ -0,0 +1,283 @@
+/**
+ * streamTurn: the spawn-per-turn headless runner. Spawn, drain both stdio
+ * streams concurrently, decode typed HarnessEvents, watchdog stalls (only
+ * for none-granularity invocations - a structured stream proves its own
+ * liveness), classify the exit, always end with `done` (spawn failures
+ * included). Runtime primitives are injected (D-005); structured boundary
+ * events (spawn/exit/stall, argv redacted by POSITION) are always-on
+ * evidence, not diagnostics. An abandoned turn (consumer breaks early)
+ * closes backpressure, disposes output, stops the child, and awaits both
+ * pumps before it returns.
+ */
+import { buildLaunchArgv, buildResumeArgv, streamingGranularityOf, } from "../interpretation/argv.js";
+import { stdinPolicyOf } from "../interpretation/dimensions.js";
+import { detectAuthFailureInLine, detectLimitInLine } from "../interpretation/limits.js";
+import { AsyncChannel } from "./channel.js";
+import { decodeLine, freshDecodeState } from "./decode.js";
+import { LineBuffer } from "./lines.js";
+/** Fallback correlation when the host does not mint turn ids: monotonic per
+ * process. Hosts that need cross-process uniqueness pass deps.turnId. */
+let turnCounter = 0;
+/** SIGTERM -> SIGKILL escalation budget for a child that ignores the first
+ * signal, and the grace allowed for pipes still held open (by a grandchild)
+ * after the process itself exited. */
+export const KILL_GRACE_MS = 5_000;
+export const PIPE_GRACE_MS = 2_000;
+const OUTPUT_STREAMS = ["stdout", "stderr"];
+const pumpFailureMessage = (stream, cause) => `${stream} pump failed: ${cause instanceof Error ? cause.message : String(cause)}`;
+/** Stray secret-shaped tokens are masked; identifiers (session UUIDs, model
+ * ids, paths) log verbatim - they are what the log exists to correlate. */
+const SECRETISH = /(sk-[A-Za-z0-9_-]{8,}|(?:token|key|secret|password)=\S+)/i;
+/** Redact by POSITION, not shape: the prompt is a known argv slot and is
+ * masked wholesale (content never reaches a log line - v1 D-005); every
+ * other token is kept unless it is secret-shaped. */
+export const redactArgv = (argv, prompt) => argv.map((token) => {
+    if (prompt !== undefined && token === prompt)
+        return `[prompt:${prompt.length}ch]`;
+    if (SECRETISH.test(token))
+        return "[redacted]";
+    return token;
+});
+/** Bounded tail of unmatched stderr - the crash context a nonzero exit is
+ * explained by (v1 kept the turn's output slice for exactly this). Shared
+ * with the session runner. */
+export class StderrTail {
+    lines = [];
+    bytes = 0;
+    push(line) {
+        this.lines.push(line);
+        this.bytes += line.length;
+        while (this.lines.length > 20 || (this.bytes > 4096 && this.lines.length > 1)) {
+            const dropped = this.lines.shift();
+            this.bytes -= dropped?.length ?? 0;
+        }
+    }
+    snapshot() {
+        return [...this.lines];
+    }
+}
+export async function* streamTurn(h, opts, deps) {
+    const turnId = deps.turnId ?? `turn-${++turnCounter}`;
+    const log = deps.log ?? (() => { });
+    const argv = opts.resume === undefined
+        ? buildLaunchArgv(h, opts)
+        : buildResumeArgv(h, { ...opts, sessionId: opts.resume });
+    const granularity = streamingGranularityOf(h, argv);
+    log({
+        event: "spawn",
+        turnId,
+        harness: h.name,
+        argv: redactArgv(argv, opts.prompt),
+        granularity,
+    });
+    let proc;
+    try {
+        proc = deps.spawn(argv, {
+            stdin: stdinPolicyOf(h) === "close-required" ? "close" : "inherit",
+            ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+        });
+    }
+    catch (cause) {
+        // A spawn that cannot start still honors the contract: error, done,
+        // and a closed exit log - never a throw out of the first next().
+        const message = cause instanceof Error ? cause.message : String(cause);
+        log({
+            event: "exit",
+            turnId,
+            harness: h.name,
+            exitCode: 127,
+            cause: "crash",
+            spawnError: message,
+        });
+        yield { kind: "error", message: `spawn failed: ${message}` };
+        yield { kind: "done", exitCode: 127, cause: "crash" };
+        return;
+    }
+    const queue = new AsyncChannel();
+    const state = freshDecodeState(opts.resume ?? null);
+    const stderrTail = new StderrTail();
+    let killedByWatchdog = false;
+    let exited = false;
+    let exitCode = null;
+    let pipesOpenAtExit = false;
+    let cancelled = false;
+    let terminalEventReached = false;
+    const safeSignal = (sig) => {
+        if (!exited)
+            deps.signal(proc, sig);
+    };
+    let escalationTimer = null;
+    const escalate = () => {
+        if (exited || escalationTimer !== null)
+            return;
+        safeSignal("SIGTERM");
+        escalationTimer = deps.clock.setTimeout(() => {
+            escalationTimer = null;
+            safeSignal("SIGKILL");
+        }, KILL_GRACE_MS);
+    };
+    let watchdog = null;
+    const disarm = () => {
+        if (watchdog !== null)
+            deps.clock.clearTimeout(watchdog);
+        watchdog = null;
+    };
+    const rearm = () => {
+        if (granularity !== "none" || deps.stallMs === undefined)
+            return;
+        disarm();
+        watchdog = deps.clock.setTimeout(() => {
+            killedByWatchdog = true;
+            log({ event: "stall", turnId, harness: h.name, stallMs: deps.stallMs });
+            escalate();
+        }, deps.stallMs);
+    };
+    rearm();
+    let pipeGrace = null;
+    void proc.exited.then((code) => {
+        exited = true;
+        exitCode = code;
+        if (escalationTimer !== null)
+            deps.clock.clearTimeout(escalationTimer);
+        escalationTimer = null;
+        // The process is gone: the watchdog has nothing left to kill, and a
+        // fire after this point would flip a completed turn to "stall".
+        disarm();
+        // Pipes held open past exit (a grandchild inherited the fd) must not
+        // hang the turn forever - close out with the exit code in hand.
+        if (cancelled)
+            return;
+        pipeGrace = deps.clock.setTimeout(() => {
+            pipesOpenAtExit = true;
+            proc.disposeOutput();
+        }, PIPE_GRACE_MS);
+    });
+    const pumpStdout = async () => {
+        const lines = new LineBuffer();
+        for await (const chunk of proc.stdout) {
+            if (cancelled)
+                break;
+            rearm();
+            for (const line of lines.push(chunk)) {
+                for (const event of decodeLine(h, line, state, opts.model ?? "")) {
+                    await queue.push(event);
+                }
+            }
+        }
+        const rest = lines.flush();
+        if (rest !== null && !cancelled) {
+            for (const event of decodeLine(h, rest, state, opts.model ?? ""))
+                await queue.push(event);
+        }
+    };
+    const pumpStderr = async () => {
+        const lines = new LineBuffer();
+        for await (const chunk of proc.stderr) {
+            if (cancelled)
+                break;
+            rearm();
+            for (const line of lines.push(chunk)) {
+                const limit = detectLimitInLine(h, line);
+                if (limit !== null) {
+                    state.limitSeen = true;
+                    await queue.push({
+                        kind: "limit",
+                        code: limit,
+                        message: `limit wall detected (${limit})`,
+                    });
+                    continue;
+                }
+                const auth = detectAuthFailureInLine(h, line);
+                if (auth !== null) {
+                    await queue.push({ kind: "error", message: `auth wall: ${auth}` });
+                    continue;
+                }
+                stderrTail.push(line);
+            }
+        }
+    };
+    const observePump = async (stream, pump) => {
+        try {
+            await pump;
+        }
+        catch (cause) {
+            log({
+                event: "output_pump_failed",
+                turnId,
+                harness: h.name,
+                stream,
+                issue: "read-failed",
+            });
+            await queue.push({ kind: "error", message: pumpFailureMessage(stream, cause) });
+            escalate();
+            await proc.exited;
+            proc.disposeOutput();
+        }
+    };
+    const pumpSettlements = Promise.all([
+        observePump("stdout", pumpStdout()),
+        observePump("stderr", pumpStderr()),
+    ]);
+    void Promise.all([proc.exited, pumpSettlements]).then(() => queue.close());
+    try {
+        for await (const event of queue)
+            yield event;
+        const cause = state.limitSeen
+            ? "limit"
+            : killedByWatchdog && exitCode !== 0
+                ? "stall"
+                : exitCode === 0
+                    ? "clean"
+                    : exitCode === null
+                        ? "killed"
+                        : "crash";
+        const tail = stderrTail.snapshot();
+        log({
+            event: "exit",
+            turnId,
+            harness: h.name,
+            exitCode,
+            cause,
+            ...(pipesOpenAtExit ? { pipesOpenAtExit } : {}),
+            ...(cause === "crash" || cause === "stall" || cause === "killed" ? { stderrTail: tail } : {}),
+        });
+        // A failure with captured stderr surfaces as a stream-level error, not
+        // only in the exit log - so a crash from the real adapter's async spawn
+        // failure carries the same error-event signal as the sync-throw path.
+        if ((cause === "crash" || cause === "killed") && tail.length > 0) {
+            yield { kind: "error", message: tail.join("\n").slice(0, 4096) };
+        }
+        terminalEventReached = true;
+        yield { kind: "done", exitCode, cause };
+    }
+    finally {
+        const abandoned = !terminalEventReached;
+        cancelled = true;
+        queue.close();
+        disarm();
+        if (abandoned) {
+            log({ event: "abandoned", turnId, harness: h.name });
+            if (!exited)
+                escalate();
+        }
+        proc.disposeOutput();
+        const [settledExit] = await Promise.all([proc.exited, pumpSettlements]);
+        exitCode = settledExit;
+        if (pipeGrace !== null)
+            deps.clock.clearTimeout(pipeGrace);
+        pipeGrace = null;
+        if (escalationTimer !== null)
+            deps.clock.clearTimeout(escalationTimer);
+        escalationTimer = null;
+        if (abandoned) {
+            log({
+                event: "abandonment_settled",
+                turnId,
+                harness: h.name,
+                exitCode,
+                outputDisposed: true,
+            });
+        }
+    }
+}
+//# sourceMappingURL=stream-turn.js.map

package/dist/execution/stream-turn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-turn.js","sourceRoot":"","sources":["../../src/execution/stream-turn.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Public package surface. The three architectural layers remain available as
+ * explicit subpath exports for consumers that want the narrowest dependency.
+ */
+export * from "./execution/index.js";
+export * from "./interpretation/index.js";
+export * from "./knowledge/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * Public package surface. The three architectural layers remain available as
+ * explicit subpath exports for consumers that want the narrowest dependency.
+ */
+export * from "./execution/index.js";
+export * from "./interpretation/index.js";
+export * from "./knowledge/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC"}

package/dist/interpretation/argv.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Argv construction: pure functions turning a descriptor + launch options
+ * into the exact argv a spawner would exec. Ordering rules (positional
+ * prompt before tool grants) and the spawn-boundary refusals live here so
+ * no caller re-derives them.
+ */
+import type { HarnessDescriptor, StreamingGranularity } from "../knowledge/descriptor.js";
+/** Raised when launch options would corrupt or subvert the spawned argv. */
+export declare class ArgvRefusalError extends Error {
+    readonly issue: string;
+    constructor(issue: string, message: string);
+}
+export interface TurnOptions {
+    readonly prompt: string;
+    readonly tools?: readonly string[];
+    readonly model?: string;
+    readonly autonomy?: boolean;
+}
+export interface ResumeOptions extends TurnOptions {
+    readonly sessionId: string;
+}
+export type LaunchOptions = TurnOptions;
+export declare const buildLaunchArgv: (h: HarnessDescriptor, opts: LaunchOptions) => string[];
+export declare const buildResumeArgv: (h: HarnessDescriptor, opts: ResumeOptions) => string[];
+export interface SessionOptions {
+    readonly sessionId: string;
+    readonly model?: string;
+}
+export declare const buildSessionArgv: (h: HarnessDescriptor, opts: SessionOptions) => string[];
+/** The granularity an invocation will actually emit: pins are checked in
+ * order, first fully-satisfied pin wins (every member present with its
+ * pinned value, last occurrence winning like the CLIs themselves); an argv
+ * satisfying no pin gets the floor. */
+export declare const streamingGranularityOf: (h: HarnessDescriptor, argv: readonly string[]) => StreamingGranularity;
+//# sourceMappingURL=argv.d.ts.map

package/dist/interpretation/argv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argv.d.ts","sourceRoot":"","sources":["../../src/interpretation/argv.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAI1F,4EAA4E;AAC5E,qBAAa,gBAAiB,SAAQ,KAAK;IAEvC,QAAQ,CAAC,KAAK,EAAE,MAAM;IADxB,YACW,KAAK,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EAIhB;CACF;AAcD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC;AA+BxC,eAAO,MAAM,eAAe,MAAO,iBAAiB,QAAQ,aAAa,KAAG,MAAM,EAIjF,CAAC;AAEF,eAAO,MAAM,eAAe,MAAO,iBAAiB,QAAQ,aAAa,KAAG,MAAM,EAejF,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,gBAAgB,MAAO,iBAAiB,QAAQ,cAAc,KAAG,MAAM,EAqBnF,CAAC;AAiDF;;;uCAGuC;AACvC,eAAO,MAAM,sBAAsB,MAC9B,iBAAiB,QACd,SAAS,MAAM,EAAE,KACtB,oBAOF,CAAC"}

package/dist/interpretation/argv.js

@@ -0,0 +1,147 @@
+import { assertUsableSessionId } from "./session-id.js";
+import { validateModel } from "./vocabulary.js";
+/** Raised when launch options would corrupt or subvert the spawned argv. */
+export class ArgvRefusalError extends Error {
+    issue;
+    constructor(issue, message) {
+        super(message);
+        this.issue = issue;
+        this.name = "ArgvRefusalError";
+    }
+}
+/** One guard for every builder that places a positional prompt. Selector
+ * hygiene (session ids) lives in session-id.ts; model selectors go through
+ * validateModel - both refuse, never sanitize. */
+const assertCleanPrompt = (h, prompt) => {
+    if (prompt.startsWith("-")) {
+        throw new ArgvRefusalError("prompt-flag-injection", `positional prompt may not start with '-'; it would be parsed as a flag by ${h.bin}`);
+    }
+};
+/** The shared tail of every headless-turn argv: prompt, stream flags, then
+ * validated selections, with the variadic tools flag LAST and fed exactly
+ * one joined token so nothing after it can be swallowed as a tool name. */
+const turnTail = (h, opts) => {
+    assertCleanPrompt(h, opts.prompt);
+    const tail = [opts.prompt, ...h.launch.streamFlags];
+    if (opts.model !== undefined) {
+        const validated = validateModel(h, opts.model);
+        if (!validated.ok)
+            throw new ArgvRefusalError("unknown-model", validated.reason);
+        tail.push(h.vocabulary.modelFlag, validated.id);
+    }
+    if (opts.autonomy === true) {
+        if (h.autonomy === null) {
+            throw new ArgvRefusalError("no-autonomy-mode", `${h.bin} has no unattended-run flag`);
+        }
+        tail.push(h.autonomy.flag);
+    }
+    if (opts.tools !== undefined && h.launch.toolsFlag !== null) {
+        if (opts.tools.length === 0 || opts.tools.some((t) => t.trim() === "" || t.includes(","))) {
+            throw new ArgvRefusalError("invalid-tool-grant", `tool grant for ${h.bin} contains an empty entry or a comma; a blank ${h.launch.toolsFlag} value grants nothing detectable, and a comma inside one name silently splits the grant`);
+        }
+        tail.push(h.launch.toolsFlag, opts.tools.join(","));
+    }
+    return tail;
+};
+export const buildLaunchArgv = (h, opts) => [
+    h.bin,
+    ...h.launch.baseFlags,
+    ...turnTail(h, opts),
+];
+export const buildResumeArgv = (h, opts) => {
+    assertUsableSessionId(opts.sessionId);
+    // Subcommands lead, then the resume token and id, then the flags the
+    // RESUME grammar accepts (never inherited launch flags - codex exec
+    // resume rejects --sandbox). One shape serves both styles:
+    // `claude --resume <id> -p <prompt>`, `codex exec resume <id> --json
+    // <prompt>`, `muse exec --session-id <id> <prompt>`.
+    return [
+        h.bin,
+        ...h.launch.subcommands,
+        h.resume.flag,
+        opts.sessionId,
+        ...h.resume.extraFlags,
+        ...turnTail(h, opts),
+    ];
+};
+export const buildSessionArgv = (h, opts) => {
+    if (!h.sessionMode) {
+        throw new ArgvRefusalError("no-session-mode", `${h.bin} declares no persistent headless session mode`);
+    }
+    assertUsableSessionId(opts.sessionId);
+    const argv = [
+        h.bin,
+        ...h.launch.baseFlags,
+        ...h.sessionMode.flags,
+        h.sessionMode.idFlag,
+        opts.sessionId,
+    ];
+    if (opts.model !== undefined) {
+        const validated = validateModel(h, opts.model);
+        if (!validated.ok)
+            throw new ArgvRefusalError("unknown-model", validated.reason);
+        argv.push(h.vocabulary.modelFlag, validated.id);
+    }
+    return argv;
+};
+/** Canonicalize an argv into a last-wins flag map: `--flag=value` splits,
+ * `--flag value` consumes the following non-flag token as its value, a flag
+ * followed by another flag is boolean. Positional tokens are skipped, so a
+ * value can never satisfy a boolean pin member. Aliases map onto canonical
+ * spellings. Known limitation: a crafted argv giving a pin member as the
+ * value of an unknown variadic flag can still false-positive - full CLI
+ * grammar is unknowable from outside. */
+const flagMapOf = (h, argv) => {
+    const map = new Map();
+    for (let i = 1; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === undefined || !token.startsWith("-"))
+            continue;
+        const eq = token.indexOf("=");
+        if (eq !== -1) {
+            const name = token.slice(0, eq);
+            map.set(h.output.flagAliases[name] ?? name, token.slice(eq + 1));
+            continue;
+        }
+        const name = h.output.flagAliases[token] ?? token;
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("-")) {
+            map.set(name, next);
+            i++;
+        }
+        else {
+            map.set(name, true);
+        }
+    }
+    return map;
+};
+const pinSatisfied = (pin, flags) => {
+    for (let i = 0; i < pin.length; i++) {
+        const member = pin[i];
+        if (member === undefined || !member.startsWith("-"))
+            continue;
+        const expected = pin[i + 1];
+        const actual = flags.get(member);
+        if (actual === undefined)
+            return false;
+        if (expected !== undefined && !expected.startsWith("-") && actual !== expected) {
+            return false;
+        }
+    }
+    return true;
+};
+/** The granularity an invocation will actually emit: pins are checked in
+ * order, first fully-satisfied pin wins (every member present with its
+ * pinned value, last occurrence winning like the CLIs themselves); an argv
+ * satisfying no pin gets the floor. */
+export const streamingGranularityOf = (h, argv) => {
+    if (h.output.pins.length === 0)
+        return h.output.floor;
+    const flags = flagMapOf(h, argv);
+    for (const pin of h.output.pins) {
+        if (pinSatisfied(pin.flags, flags))
+            return pin.granularity;
+    }
+    return h.output.floor;
+};
+//# sourceMappingURL=argv.js.map

package/dist/interpretation/argv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argv.js","sourceRoot":"","sources":["../../src/interpretation/argv.ts"],"names":[],"mappings":"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"}

package/dist/interpretation/capabilities.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Capability resolution: capabilitiesOf(h, model, mode) answers what this
+ * harness/model/mode combination can actually do, always with a source.
+ * This layer serves the CURATED baseline (or degrades to unknown for a
+ * model outside the vocabulary); runtime verification against a live
+ * harness/registry happens at attach time in the consumer, which upgrades
+ * source to runtime-verified. An LLM self-asserting capability is neither.
+ */
+import type { HarnessDescriptor, HarnessMode, StreamingGranularity } from "../knowledge/descriptor.js";
+export interface CapabilityResult {
+    readonly vision: boolean;
+    readonly images: boolean;
+    readonly streaming: StreamingGranularity;
+    readonly session: boolean;
+    readonly source: "runtime-verified" | "curated" | "unknown";
+    readonly confidence: "high" | "medium" | "none";
+}
+export declare const capabilitiesOf: (h: HarnessDescriptor, model: string, mode: HarnessMode) => CapabilityResult;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/interpretation/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/interpretation/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACX,oBAAoB,EACrB,MAAM,4BAA4B,CAAC;AAGpC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,oBAAoB,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,GAAG,SAAS,GAAG,SAAS,CAAC;IAC5D,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;CACjD;AAED,eAAO,MAAM,cAAc,MACtB,iBAAiB,SACb,MAAM,QACP,WAAW,KAChB,gBAsBF,CAAC"}

package/dist/interpretation/capabilities.js

@@ -0,0 +1,25 @@
+import { resolveModel } from "./vocabulary.js";
+export const capabilitiesOf = (h, model, mode) => {
+    if (!resolveModel(h, model).curated) {
+        // Curated claims cover curated models only - an extensible registry's
+        // unknown model still degrades here until runtime verification.
+        // Degrade: no raw-image claims, no streaming claims - transcribe/hold.
+        return {
+            vision: false,
+            images: false,
+            streaming: "none",
+            session: false,
+            source: "unknown",
+            confidence: "none",
+        };
+    }
+    return {
+        vision: h.capabilities.vision,
+        images: h.capabilities.images,
+        streaming: h.capabilities.streamingByMode[mode],
+        session: h.capabilities.session,
+        source: "curated",
+        confidence: "medium",
+    };
+};
+//# sourceMappingURL=capabilities.js.map

package/dist/interpretation/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/interpretation/capabilities.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAW/C,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,CAAoB,EACpB,KAAa,EACb,IAAiB,EACC,EAAE;IACpB,IAAI,CAAC,YAAY,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;QACpC,sEAAsE;QACtE,gEAAgE;QAChE,uEAAuE;QACvE,OAAO;YACL,MAAM,EAAE,KAAK;YACb,MAAM,EAAE,KAAK;YACb,SAAS,EAAE,MAAM;YACjB,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,SAAS;YACjB,UAAU,EAAE,MAAM;SACnB,CAAC;IACJ,CAAC;IACD,OAAO;QACL,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;QAC7B,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM;QAC7B,SAAS,EAAE,CAAC,CAAC,YAAY,CAAC,eAAe,CAAC,IAAI,CAAC;QAC/C,OAAO,EAAE,CAAC,CAAC,YAAY,CAAC,OAAO;QAC/B,MAAM,EAAE,SAAS;QACjB,UAAU,EAAE,QAAQ;KACrB,CAAC;AACJ,CAAC,CAAC"}

package/dist/interpretation/content.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Content decoding: extract assistant text, token deltas, tool calls, and
+ * progress from ONE parsed harness record. Each harness has an entirely
+ * different event vocabulary, so this dispatches by harness name to a pure
+ * per-harness reader. Identity and wall detection stay descriptor-driven
+ * elsewhere; this owns the message/token/tool/progress classes only.
+ *
+ * (Kept as functions rather than descriptor data because the shapes are
+ * structurally too varied - array-of-blocks text, nested delta events,
+ * payload-discriminated records - for the flat match/field spec that
+ * identity decoding uses.)
+ */
+import type { HarnessName } from "../knowledge/descriptor.js";
+export type ContentEvent = {
+    readonly kind: "token";
+    readonly text: string;
+} | {
+    readonly kind: "message";
+    readonly role: string;
+    readonly text: string;
+} | {
+    readonly kind: "tool";
+    readonly name: string;
+    readonly input?: unknown;
+} | {
+    readonly kind: "progress";
+    readonly label: string;
+} | {
+    readonly kind: "error";
+    readonly message: string;
+};
+export declare const contentEventsOf: (harness: HarnessName, raw: unknown) => ContentEvent[];
+//# sourceMappingURL=content.d.ts.map

package/dist/interpretation/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/interpretation/content.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAG9D,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAsKzD,eAAO,MAAM,eAAe,YAAa,WAAW,OAAO,OAAO,KAAG,YAAY,EAIhF,CAAC"}