@skanl/brambo-adapter-cli 0.1.1

package/dist/traits.js

@@ -0,0 +1,589 @@
+import { BramboError, BRAMBO_ERROR_CODES, USAGE_ABSENCE_REASONS } from '@skanl/brambo-contracts';
+import { isRecord, usageAbsence, usageObservation, validateRunRequest } from '@skanl/brambo-contracts';
+import { createNodeChildSpawner, routesThroughCmdShim } from './node-child-spawner.js';
+const SUMMARY_MAX_LENGTH = 200;
+const BYTE_ORDER_MARK = '\uFEFF';
+// Conservative argv bounds: win32 caps a whole command line at 32767 chars,
+// Linux caps a SINGLE argument at 128 KiB. Refusing just under the smaller of
+// the two turns an unattributable OS spawn error into a coded envelope that
+// names the limit.
+const ARGUMENT_PROMPT_MAX_LENGTH = process.platform === 'win32' ? 30_000 : 100_000;
+// Keys the engine itself writes into `envelope.data`; a metadata key colliding
+// with one of them would silently overwrite the real result, hide truncation, or
+// — since M3.C — forge the figure a cost cap is enforced on.
+const RESERVED_DATA_KEYS = ['result', 'stdoutTruncated', 'stderrTruncated', 'usage', 'malformedStreamLines'];
+/** The engine-owned `data` key a settled cost is read back from. */
+export const USAGE_DATA_KEY = 'usage';
+/**
+ * The engine-owned `data` key counting stream lines that were not JSON (E6).
+ *
+ * Written ONLY when the count is non-zero, exactly like `stdoutTruncated`. A bad
+ * line must never discard a run that completed — but a run whose stream brambo
+ * could only partly read is not the same run as one it read whole, and silence
+ * there is the difference nobody can see afterwards.
+ */
+// Not exported, unlike `USAGE_DATA_KEY` beside it: that one has a real consumer
+// in `plugin.ts`, and this one has none. A constant on the package surface that
+// nothing outside reads is surface nobody asked for.
+const MALFORMED_LINES_DATA_KEY = 'malformedStreamLines';
+export function createCliExecutorAdapter(traits, options = {}) {
+    validateExecutorTraits(traits);
+    return new TraitDrivenAdapter(traits, options);
+}
+// "Adding an executor is adding a record" makes the record the API surface, so
+// it gets the same factory-time validation Story 2.3 gives projection traits.
+// Each rejected shape below is one that fails SILENTLY at runtime rather than
+// loudly: an empty resultPath resolves to the record itself, and an empty
+// errorStatusPrefix marks every single run failed.
+function validateExecutorTraits(traits) {
+    const reject = (detail) => {
+        throw new BramboError(BRAMBO_ERROR_CODES.contractEnvelopeInvalid, `executor traits for '${traits.executorId}' are invalid: ${detail}`);
+    };
+    if (traits.executorId.trim().length === 0)
+        reject("'executorId' must be a non-empty string");
+    if (traits.command.trim().length === 0)
+        reject("'command' must be a non-empty string");
+    const output = traits.output;
+    if (output.resultPath.length === 0)
+        reject("'output.resultPath' must name at least one property");
+    if (output.errorStatusPrefix !== undefined && output.errorStatusPrefix.length === 0) {
+        reject("'output.errorStatusPrefix' must be non-empty — an empty prefix marks every run failed");
+    }
+    if (output.errorFlagPath !== undefined && output.errorFlagPath.length === 0) {
+        reject("'output.errorFlagPath' must name at least one property");
+    }
+    for (const key of Object.keys(output.metadata ?? {})) {
+        if (RESERVED_DATA_KEYS.includes(key))
+            reject(`'output.metadata' key '${key}' collides with an engine-owned data key`);
+    }
+    if (output.usagePaths !== undefined) {
+        // An empty list declares "this vendor reports usage" and then never produces
+        // a figure — the inert shape this story exists to refuse. An empty PATH
+        // resolves to the record itself, which is never a number, so it would make
+        // every run silently unsettleable.
+        if (output.usagePaths.length === 0)
+            reject("'output.usagePaths' must name at least one path, or be omitted");
+        for (const path of output.usagePaths) {
+            if (path.length === 0)
+                reject("'output.usagePaths' entries must each name at least one property");
+        }
+        // Required, because the figure is SUMMED across matching records: an
+        // undiscriminated sum bills every record that happens to fit the shape.
+        if (output.usageWhen === undefined) {
+            reject("'output.usageWhen' is required beside 'output.usagePaths' — a summed figure needs a bounded set of records");
+        }
+    }
+    if (output.usageWhen !== undefined && output.usageWhen.path.length === 0) {
+        reject("'output.usageWhen.path' must name at least one property");
+    }
+    if (output.failureWhen !== undefined && output.failureWhen.path.length === 0) {
+        reject("'output.failureWhen.path' must name at least one property");
+    }
+    const windows = output.usageWindows;
+    if (windows !== undefined) {
+        // Each rejected shape is one that would fail SILENTLY: an empty `when.path`
+        // resolves to the record itself and matches nothing, an empty `path`
+        // resolves to the whole event, and an empty key never names a field. All
+        // three produce "this executor reported no quota" forever, which is exactly
+        // the inert surface AD-5 forbids dressing up as an absence.
+        if (windows.when.path.length === 0)
+            reject("'output.usageWindows.when.path' must name at least one property");
+        if (windows.path.length === 0)
+            reject("'output.usageWindows.path' must name at least one property");
+        if (windows.utilizationKey.length === 0)
+            reject("'output.usageWindows.utilizationKey' must be a non-empty string");
+        if (windows.resetsAtKey.length === 0)
+            reject("'output.usageWindows.resetsAtKey' must be a non-empty string");
+    }
+}
+class TraitDrivenAdapter {
+    #traits;
+    #spawner;
+    #command;
+    #onTiming;
+    #onUsageObservation;
+    constructor(traits, options) {
+        this.#traits = traits;
+        this.#spawner = options.spawner ?? createNodeChildSpawner();
+        this.#command = options.command ?? traits.command;
+        this.#onTiming = options.onTiming;
+        this.#onUsageObservation = options.onUsageObservation;
+    }
+    get executorId() {
+        return this.#traits.executorId;
+    }
+    async run(request) {
+        validateRunRequest(request);
+        const startedAt = performance.now();
+        // Measured before any child exists; overwritten after spawn on the real path.
+        let spawnSetupMs = performance.now() - startedAt;
+        if (request.signal?.aborted)
+            return this.#cancelled(startedAt, spawnSetupMs);
+        const refusal = this.#refuseArgumentPrompt(request.prompt);
+        if (refusal !== undefined)
+            return this.#finish(startedAt, spawnSetupMs, refusal);
+        // Everything between startedAt and here is adapter-added overhead (NFR-9);
+        // the OS-level process start itself is shared with a raw CLI invocation.
+        let child;
+        try {
+            child = this.#spawner.spawn(this.#command, this.#argv(request.prompt), { cwd: request.workspace.rootPath });
+            spawnSetupMs = performance.now() - startedAt;
+        }
+        catch (error) {
+            return this.#finish(startedAt, spawnSetupMs, this.#failed(`executor '${this.#command}' could not be spawned: ${describe(error)}`, BRAMBO_ERROR_CODES.executorUnavailable));
+        }
+        // Completion must be observed before an abort can claim cancellation: an
+        // abort landing AFTER the child already exited successfully yields the real
+        // ok/failed result, not a cancelled envelope. `child.settled` closes the
+        // window between `done` resolving and the `.then` microtask below running.
+        let completionSettled = false;
+        const completion = child.done.then((outcome) => {
+            completionSettled = true;
+            return outcome;
+        });
+        let cancelledInFlight = false;
+        const abort = () => {
+            if (completionSettled || child.settled)
+                return;
+            cancelledInFlight = true;
+            child.killTree();
+        };
+        request.signal?.addEventListener('abort', abort, { once: true });
+        try {
+            try {
+                if (this.#traits.promptDelivery === 'stdin')
+                    child.writeStdin(request.prompt);
+                child.endStdin();
+            }
+            catch (error) {
+                // The child is alive and unreachable: without this it keeps running
+                // against the workspace after the envelope is returned.
+                child.killTree();
+                return this.#finish(startedAt, spawnSetupMs, this.#failed(`pipe to executor '${this.#command}' failed: ${describe(error)}`, BRAMBO_ERROR_CODES.executorRunFailed));
+            }
+            const outcome = await completion;
+            if (cancelledInFlight) {
+                // A killed child settles through `close` carrying everything it printed,
+                // so the tokens it already spent are right here. Charging a cancelled run
+                // its estimate while its own stdout says otherwise is a hole a caller can
+                // drive through by aborting late.
+                return this.#cancelled(startedAt, spawnSetupMs, this.#unstructuredData(outcome, this.#scan(outcome.stdout)));
+            }
+            return this.#fromOutcome(outcome, startedAt, spawnSetupMs);
+        }
+        finally {
+            request.signal?.removeEventListener('abort', abort);
+        }
+    }
+    #argv(prompt) {
+        if (this.#traits.promptDelivery !== 'argument')
+            return this.#traits.args;
+        const separator = this.#traits.promptArgSeparator;
+        return separator === undefined ? [...this.#traits.args, prompt] : [...this.#traits.args, separator, prompt];
+    }
+    /**
+     * Guards the argument-delivery path, which puts caller-supplied text in argv.
+     *
+     * The cmd.exe refusal is the important one: on win32 a `.cmd`/`.bat` command
+     * can only start by rerouting through a SHELL, and no amount of quoting stops
+     * cmd.exe from interpreting `&`, `|`, `>`, `^` or `%VAR%` in the prompt.
+     * Escaping for cmd.exe is not winnable, so the run fails closed instead.
+     */
+    #refuseArgumentPrompt(prompt) {
+        if (this.#traits.promptDelivery !== 'argument')
+            return undefined;
+        if (routesThroughCmdShim(this.#command)) {
+            return this.#failed(`executor '${this.#command}' can only start through cmd.exe, which would interpret shell metacharacters in the prompt argument; point 'command' at the real executable instead of the .cmd shim`, BRAMBO_ERROR_CODES.executorUnavailable);
+        }
+        if (prompt.length > ARGUMENT_PROMPT_MAX_LENGTH) {
+            return this.#failed(`prompt of ${prompt.length} characters exceeds the ${ARGUMENT_PROMPT_MAX_LENGTH}-character argument limit of executor '${this.#command}'`, BRAMBO_ERROR_CODES.executorRunFailed);
+        }
+        return undefined;
+    }
+    #fromOutcome(outcome, startedAt, spawnSetupMs) {
+        const finish = (envelope) => this.#finish(startedAt, spawnSetupMs, envelope);
+        // Scanned FIRST, and on every path below. A child that failed, was killed or
+        // was cut off still printed whatever it had already spent, and those bytes are
+        // in hand here — discarding them made failing and cancelling free, which is
+        // exactly the evasion a budget must not have. Measured before this moved: a
+        // cancelled run carrying 500,000 reported tokens in captured stdout was
+        // charged its estimate of 1.
+        const scan = this.#scan(outcome.stdout);
+        const truncation = this.#unstructuredData(outcome, scan);
+        if (outcome.spawnErrorMessage !== undefined) {
+            // The one path with genuinely nothing to read: no child ever started.
+            return finish(this.#failed(`executor '${this.#command}' is not available: ${outcome.spawnErrorMessage}`, BRAMBO_ERROR_CODES.executorUnavailable));
+        }
+        if (outcome.streamErrorMessage !== undefined) {
+            return finish(this.#failed(`pipe to or from executor '${this.#command}' failed: ${outcome.streamErrorMessage}`, BRAMBO_ERROR_CODES.executorRunFailed, truncation));
+        }
+        if (outcome.exitCode === null) {
+            return finish(this.#failed(`executor '${this.#command}' was terminated by an external signal before completing`, BRAMBO_ERROR_CODES.executorRunFailed, truncation));
+        }
+        // An executor that reports its own failure is believed regardless of exit
+        // code and regardless of WHERE in the stream it said so: OpenCode emits
+        // recoverable error events and keeps going, so a positional rule would drop
+        // the reason whenever any output followed it.
+        if (scan.failure !== undefined)
+            return finish(this.#failedFromRecord(scan.failure, outcome, scan));
+        if (outcome.exitCode !== 0) {
+            // codex and opencode exit non-zero exactly when they have printed their
+            // structured error, so the payload — not stderr noise — is the reason.
+            if (scan.result !== undefined)
+                return finish(this.#failedFromRecord(scan.result, outcome, scan));
+            const detail = outcome.stderr.trim().length > 0
+                ? outcome.stderr.trim()
+                : `executor '${this.#command}' exited with code ${outcome.exitCode}`;
+            return finish(this.#failed(detail, BRAMBO_ERROR_CODES.executorRunFailed, truncation));
+        }
+        // A cut stream can leave an earlier event as the last PARSEABLE one, so a
+        // truncated capture must never be reported as a complete answer.
+        if (outcome.stdoutTruncated === true) {
+            return finish(this.#failed(`executor '${this.#command}' produced more output than could be captured, so its result is incomplete`, BRAMBO_ERROR_CODES.executorRunFailed, truncation));
+        }
+        if (scan.result !== undefined)
+            return finish(this.#okFromRecord(scan.result, outcome, scan));
+        return finish(this.#failed(this.#noResultDetail(scan), BRAMBO_ERROR_CODES.executorRunFailed, truncation));
+    }
+    #noResultDetail(scan) {
+        if (!scan.sawRecord) {
+            return this.#traits.output.payload === 'single-object'
+                ? `executor '${this.#command}' printed unparseable output instead of JSON`
+                : `executor '${this.#command}' printed no JSON event carrying a '${this.#traits.output.resultPath.join('.')}' result`;
+        }
+        return `executor '${this.#command}' returned JSON without a usable '${this.#traits.output.resultPath.join('.')}' result`;
+    }
+    /**
+     * Reads stdout once and reports the two records that matter: the FIRST record
+     * reporting a failure, and the LAST record carrying a usable result.
+     *
+     * Event-type names (`item.completed`, `text`, …) are the executors' own
+     * evolving vocabularies; the engine never matches on them. It matches on the
+     * paths the trait record names, which is why trailing noise (blank lines,
+     * non-object lines, bookkeeping events) costs nothing.
+     */
+    #scan(stdout) {
+        const scan = {
+            failure: undefined,
+            result: undefined,
+            usage: undefined,
+            windows: undefined,
+            malformedLines: 0,
+            sawRecord: false,
+        };
+        const text = stdout.startsWith(BYTE_ORDER_MARK) ? stdout.slice(BYTE_ORDER_MARK.length) : stdout;
+        // Accumulated across every record `usageWhen` selects, and voided outright by
+        // any one of them that cannot be read — see `usagePaths`.
+        let usageTotal;
+        let usageVoid = false;
+        const consider = (record) => {
+            scan.sawRecord = true;
+            if (scan.failure === undefined && this.#reportsFailure(record))
+                scan.failure = record;
+            if (this.#resultText(record) !== undefined)
+                scan.result = record;
+            // LAST wins, like the result: a vendor that re-reports its quota mid-run
+            // has said something newer, and the newest reading is the true one.
+            const windows = this.#usageWindowsOf(record);
+            if (windows !== undefined)
+                scan.windows = windows;
+            if (usageVoid || !this.#reportsUsage(record))
+                return;
+            const usage = this.#usageOf(record);
+            if (usage === undefined) {
+                usageVoid = true;
+                return;
+            }
+            usageTotal = (usageTotal ?? 0) + usage;
+        };
+        if (this.#traits.output.payload === 'single-object') {
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                this.#reportUsage(scan);
+                return scan;
+            }
+            if (isRecord(parsed))
+                consider(parsed);
+            scan.usage = usageVoid ? undefined : usageTotal;
+            this.#reportUsage(scan);
+            return scan;
+        }
+        for (const rawLine of text.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            if (line.length === 0)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                // Skipped, and COUNTED (E6). One bad line in the middle of a stream must
+                // not throw away a run that reached its result — and it must not vanish
+                // either, or a partly-readable stream is indistinguishable from a whole one.
+                scan.malformedLines += 1;
+                continue;
+            }
+            if (isRecord(parsed))
+                consider(parsed);
+        }
+        scan.usage = usageVoid ? undefined : usageTotal;
+        this.#reportUsage(scan);
+        return scan;
+    }
+    /**
+     * Hands the caller what the vendor said about its own quota, once per run.
+     *
+     * Called from `#scan`, which is the one function every settled path goes
+     * through exactly once — reporting from the callers instead would be two
+     * places to forget it in.
+     *
+     * An executor whose traits declare no surface reports NOTHING here rather than
+     * a `noUsageSurface` absence: that answer is a property of the executor, not
+     * of any run, and `brambo status` states it from the catalogue without needing
+     * a run to have happened at all.
+     */
+    #reportUsage(scan) {
+        const report = this.#onUsageObservation;
+        const traits = this.#traits.output.usageWindows;
+        if (report === undefined || traits === undefined)
+            return;
+        if (scan.windows === undefined || scan.windows.length === 0) {
+            report(usageAbsence(this.#traits.executorId, USAGE_ABSENCE_REASONS.notReported, `executor '${this.#traits.executorId}' produced no readable '${traits.path.join('.')}' in this run`));
+            return;
+        }
+        report(usageObservation(this.#traits.executorId, scan.windows, new Date().toISOString()));
+    }
+    /**
+     * The vendor's named windows carried by one record, or undefined when it
+     * carries none.
+     *
+     * Per WINDOW rather than fail-closed as a whole, and that asymmetry with
+     * `#usageOf` is deliberate: a usage figure is a BILL, where a missing term
+     * silently under-charges, so a term it cannot read voids the sum. These are a
+     * REPORT of what the vendor said, where each window stands on its own — a
+     * vendor that adds a third window in a shape brambo does not know must not
+     * erase the two it does.
+     */
+    #usageWindowsOf(record) {
+        const traits = this.#traits.output.usageWindows;
+        if (traits === undefined || resolvePath(record, traits.when.path) !== traits.when.equals)
+            return undefined;
+        const map = resolvePath(record, traits.path);
+        if (!isRecord(map))
+            return undefined;
+        const windows = [];
+        for (const [name, value] of Object.entries(map)) {
+            if (!isRecord(value))
+                continue;
+            const utilization = value[traits.utilizationKey];
+            const resetsAt = value[traits.resetsAtKey];
+            // Copied across unchanged (D5): the vendor's own name, the vendor's own
+            // number, the vendor's own instant. Nothing here scales, averages, picks
+            // one window over another, or turns a reset into a countdown.
+            if (typeof utilization !== 'number' || !Number.isFinite(utilization))
+                continue;
+            if (typeof resetsAt !== 'number' || !Number.isFinite(resetsAt))
+                continue;
+            windows.push({ name, utilization, resetsAt });
+        }
+        return windows.length > 0 ? windows : undefined;
+    }
+    /** Whether this record is one of the ones this vendor reports usage on. */
+    #reportsUsage(record) {
+        const when = this.#traits.output.usageWhen;
+        return (this.#traits.output.usagePaths !== undefined &&
+            when !== undefined &&
+            resolvePath(record, when.path) === when.equals);
+    }
+    /**
+     * What one usage record reports, summed over its declared components, or
+     * undefined when it cannot be read.
+     *
+     * Undefined here VOIDS the whole run's figure rather than skipping the record
+     * (see `#scan`): a term the engine could not read is spend it cannot account
+     * for, and dropping it silently under-bills.
+     */
+    #usageOf(record) {
+        let total = 0;
+        for (const path of this.#traits.output.usagePaths ?? []) {
+            const value = resolvePath(record, path);
+            if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+                return undefined;
+            total += value;
+        }
+        return total;
+    }
+    /** The result text a record carries, or undefined when it carries none. */
+    #resultText(record) {
+        const match = this.#traits.output.resultWhen;
+        if (match !== undefined && resolvePath(record, match.path) !== match.equals)
+            return undefined;
+        const value = resolvePath(record, this.#traits.output.resultPath);
+        // A blank result must not shadow the real answer: a trailing empty-string
+        // event would otherwise win the scan and produce an empty summary.
+        return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+    }
+    // An executor can report failure while exiting 0 (Claude's `is_error` and
+    // `error_*` subtypes, Codex's and OpenCode's `error` events), so the payload —
+    // not the exit code alone — decides the envelope status.
+    #reportsFailure(record) {
+        const output = this.#traits.output;
+        const when = output.failureWhen;
+        if (when !== undefined && resolvePath(record, when.path) !== when.equals)
+            return false;
+        if (output.errorFlagPath !== undefined && resolvePath(record, output.errorFlagPath) === true)
+            return true;
+        const status = this.#status(record);
+        return output.errorStatusPrefix !== undefined && status !== undefined && status.startsWith(output.errorStatusPrefix);
+    }
+    #status(record) {
+        if (this.#traits.output.statusPath === undefined)
+            return undefined;
+        const status = resolvePath(record, this.#traits.output.statusPath);
+        return typeof status === 'string' ? status : undefined;
+    }
+    /**
+     * `envelope.data` for one payload record.
+     *
+     * `usage` arrives as a separate argument rather than being read off `record`
+     * because the vendor rarely reports it there: codex prints it on
+     * `turn.completed` and opencode on `step_finish`, both AFTER the record that
+     * carried the answer. It is written as a NUMBER — the one non-string value in
+     * this object, and the only one an accounting seam can add up.
+     */
+    /**
+     * `envelope.data` for a failure that has no payload record to report from —
+     * truncation flags and whatever usage the child printed before it died.
+     * `null` when there is nothing at all, which is what those paths used to return
+     * unconditionally.
+     */
+    #unstructuredData(outcome, scan) {
+        const truncation = truncationData(outcome);
+        const skipped = malformedData(scan);
+        if (truncation === null && skipped === null && scan.usage === undefined)
+            return null;
+        return {
+            ...(truncation ?? {}),
+            ...(skipped ?? {}),
+            ...(scan.usage === undefined ? {} : { [USAGE_DATA_KEY]: scan.usage }),
+        };
+    }
+    #data(record, outcome, scan) {
+        const result = resolvePath(record, this.#traits.output.resultPath);
+        const data = typeof result === 'string' ? { result } : {};
+        for (const [key, path] of Object.entries(this.#traits.output.metadata ?? {})) {
+            const value = resolvePath(record, path);
+            if (typeof value === 'string')
+                data[key] = value;
+        }
+        if (scan.usage !== undefined)
+            data[USAGE_DATA_KEY] = scan.usage;
+        return { ...data, ...(truncationData(outcome) ?? {}), ...(malformedData(scan) ?? {}) };
+    }
+    #failedFromRecord(record, outcome, scan) {
+        const output = this.#traits.output;
+        const status = this.#status(record);
+        const reported = stringifyDetail(resolvePath(record, output.errorMessagePath ?? output.resultPath));
+        const detail = [reported.trim(), outcome.stderr.trim()].find((part) => part.length > 0) ?? '';
+        const reason = `executor '${this.#command}' reported failure${status !== undefined ? ` (${status})` : ''}`;
+        return this.#failed(detail.length > 0 ? `${reason}: ${detail}` : reason, BRAMBO_ERROR_CODES.executorRunFailed, this.#data(record, outcome, scan));
+    }
+    #okFromRecord(record, outcome, scan) {
+        return {
+            status: 'ok',
+            data: this.#data(record, outcome, scan),
+            summary: this.#summarize(this.#resultText(record) ?? ''),
+            errors: [],
+        };
+    }
+    #summarize(result) {
+        const firstLine = result
+            .split('\n')
+            .map((line) => line.trim())
+            .find((line) => line.length > 0);
+        // executorId, not command: an overridden command is an absolute filesystem
+        // path, which has no business leaking into a user-facing summary.
+        return truncate(firstLine ?? `${this.#traits.executorId} completed the task`);
+    }
+    #cancelled(startedAt, spawnSetupMs, data = null) {
+        return this.#finish(startedAt, spawnSetupMs, {
+            status: 'cancelled',
+            data,
+            summary: 'execution cancelled before completion',
+            errors: [
+                {
+                    message: 'the run was cancelled and its process tree terminated',
+                    code: BRAMBO_ERROR_CODES.executorCancelled,
+                },
+            ],
+        });
+    }
+    #failed(message, code, data = null) {
+        return {
+            status: 'failed',
+            data,
+            summary: truncate(message),
+            errors: [{ message, code }],
+        };
+    }
+    #finish(startedAt, spawnSetupMs, envelope) {
+        this.#onTiming?.({ spawnSetupMs, runMs: performance.now() - startedAt });
+        return envelope;
+    }
+}
+function resolvePath(record, path) {
+    let current = record;
+    for (const segment of path) {
+        // Own properties only, so a segment named like an Object.prototype member
+        // ('constructor', 'toString', …) can never resolve an inherited value and
+        // make EVERY record qualify. Today `isRecord` already stops each of those
+        // one hop earlier — every Object.prototype member is a function — so this
+        // is the second lock rather than the first, and it is the one that keeps
+        // holding if the record shape or `isRecord` ever loosens.
+        if (!isRecord(current) || !Object.hasOwn(current, segment))
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * The skipped-line count, or null when nothing was skipped.
+ *
+ * Absent on a clean stream ON PURPOSE: the envelope this story's acceptance
+ * compares against the old single-object mode must be key-for-key the same one,
+ * and a counter that is structurally zero is a counter nobody can read anyway.
+ */
+function malformedData(scan) {
+    return scan.malformedLines > 0 ? { [MALFORMED_LINES_DATA_KEY]: scan.malformedLines } : null;
+}
+function truncationData(outcome) {
+    return outcome.stdoutTruncated === true || outcome.stderrTruncated === true
+        ? { stdoutTruncated: outcome.stdoutTruncated === true, stderrTruncated: outcome.stderrTruncated === true }
+        : null;
+}
+// Failure details are not always strings: OpenCode reports `error` as an object.
+// Stringifying keeps the reason inside the envelope instead of dropping it.
+function stringifyDetail(value) {
+    if (value === undefined || value === null)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value) ?? '';
+    }
+    catch {
+        return String(value);
+    }
+}
+// Cuts on code points, not UTF-16 units: slicing mid-surrogate would persist a
+// lone surrogate into the envelope summary.
+function truncate(text) {
+    const points = Array.from(text);
+    return points.length > SUMMARY_MAX_LENGTH ? `${points.slice(0, SUMMARY_MAX_LENGTH).join('')}…` : text;
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@skanl/brambo-adapter-cli",
+  "version": "0.1.1",
+  "description": "Every shipped ExecutorAdapter that drives an out-of-process coding CLI.",
+  "keywords": [
+    "ai-agent",
+    "brambo",
+    "adapter",
+    "claude-code",
+    "codex",
+    "opencode"
+  ],
+  "homepage": "https://github.com/SKANL/brambo#readme",
+  "bugs": {
+    "url": "https://github.com/SKANL/brambo/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SKANL/brambo.git",
+    "directory": "packages/adapter-cli"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "brambo-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@skanl/brambo-contracts": "0.1.1",
+    "@skanl/brambo-kernel": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "~7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json"
+  }
+}