@skanl/brambo-adapter-cli 0.1.1

package/dist/traits.d.ts

@@ -0,0 +1,179 @@
+import type { ExecutorAdapter, UsageReport } from '@skanl/brambo-contracts';
+import type { ChildProcessSpawner } from './spawn-seam.ts';
+/**
+ * How the prompt reaches the executor.
+ * - `stdin`: written to the child's stdin, which is then closed. Long prompts
+ *   can never hit a command-line length limit this way.
+ * - `argument`: appended as the FINAL argv entry; stdin is closed immediately
+ *   so an executor that also reads stdin never blocks waiting for input.
+ */
+export type PromptDelivery = 'stdin' | 'argument';
+/**
+ * Shape of what the executor prints on stdout.
+ * - `single-object`: the whole stream is one JSON object.
+ * - `jsonl`: newline-delimited event objects; the result is somewhere inside.
+ */
+export type PayloadShape = 'single-object' | 'jsonl';
+/** Equality test over a property path, used to discriminate payload records. */
+export interface PathMatch {
+    readonly path: readonly string[];
+    readonly equals: string;
+}
+/**
+ * Where a vendor publishes its OWN per-window quota utilisation, and under which
+ * spellings (Story M15.A).
+ *
+ * Trait DATA rather than field names in the engine, for the reason the whole
+ * file exists: a fourth executor with a usage surface of its own must arrive as
+ * a record, never as an edit here. `path` resolves to the vendor's MAP of named
+ * windows — the keys of that map are the window names brambo reports, so the
+ * vocabulary is the vendor's and brambo names nothing.
+ */
+export interface UsageWindowTraits {
+    /** Which record carries the surface, e.g. `type == "rate_limit_event"`. */
+    readonly when: PathMatch;
+    /** Path to the map of NAMED windows inside that record. */
+    readonly path: readonly string[];
+    /** The vendor's key for the utilisation figure inside one window. */
+    readonly utilizationKey: string;
+    /** The vendor's key for the reset instant inside one window. */
+    readonly resetsAtKey: string;
+}
+export interface ExecutorOutputTraits {
+    readonly payload: PayloadShape;
+    /** Property path to the result text inside a payload record. */
+    readonly resultPath: readonly string[];
+    /**
+     * Extra condition a record must satisfy to count as THE result. Without it
+     * any record carrying `resultPath` qualifies — which for Codex would accept
+     * a reasoning item and answer with chain-of-thought.
+     */
+    readonly resultWhen?: PathMatch;
+    /**
+     * Extra condition a record must satisfy before `errorFlagPath` and
+     * `errorStatusPrefix` are read off it. Without it EVERY record in a stream is
+     * examined, which is the widening a single-object payload never had.
+     *
+     * Claude's `--output-format json` printed exactly one object, so "the record
+     * that could report failure" and "the result" were the same record by
+     * construction. Its stream prints `system`, `assistant` and `hook_*` events
+     * beside the result, all of them carrying a `subtype` of their own — so
+     * without this the `error` prefix would be tested against a vocabulary that is
+     * not the result's, and the envelope would no longer be the one the old mode
+     * produced. That equivalence is the story's own acceptance criterion.
+     */
+    readonly failureWhen?: PathMatch;
+    /** Path to a boolean flag that marks an executor-reported failure. */
+    readonly errorFlagPath?: readonly string[];
+    /** Path to a status string reported in failure messages. */
+    readonly statusPath?: readonly string[];
+    /** A status starting with this prefix is a failure even on exit code 0. */
+    readonly errorStatusPrefix?: string;
+    /** Path to the failure detail. Defaults to `resultPath`. */
+    readonly errorMessagePath?: readonly string[];
+    /** Extra payload paths copied into `envelope.data` under the given keys. */
+    readonly metadata?: Readonly<Record<string, readonly string[]>>;
+    /**
+     * Which records report usage. Required whenever `usagePaths` is declared.
+     *
+     * `usagePaths` is summed across EVERY matching record (see below), so the
+     * discriminator is what bounds the sum: without it, any record whose shape
+     * happens to carry the same paths joins the bill and the run is double-charged.
+     * It is `resultWhen` for the accounting half, and it exists for the same reason.
+     */
+    readonly usageWhen?: PathMatch;
+    /**
+     * Paths to the vendor's OWN numeric usage fields, summed into `data.usage`.
+     *
+     * A separate channel from `metadata` rather than a loosening of it: `metadata`
+     * keeps strings, several suites assert exactly that, and a usage figure is a
+     * NUMBER an accounting seam adds up. Widening the shared channel to carry both
+     * would have made every existing metadata key silently numeric-capable too.
+     *
+     * A list, because no vendor reports one total for a run: claude-code reports
+     * disjoint components (uncached input, cache creation, cache read, output) that
+     * only mean something added together. Summing figures a vendor printed is not
+     * brambo counting tokens — nothing here estimates, tokenizes or infers; every
+     * term is a number the tool itself emitted.
+     *
+     * Summed ACROSS records as well as within one, because a vendor that works in
+     * steps bills every step. Measured on opencode 1.18.23 with a three-step task:
+     * `step_finish` carried 42770, 42875 and 43025, each equal to its OWN
+     * components rather than to a running total. Taking the last one billed 43025
+     * of 128670 — and a task whose last step is trivial bills almost nothing.
+     *
+     * The record carrying usage is usually NOT the record carrying the result —
+     * codex reports it on `turn.completed` and opencode on `step_finish` — so it is
+     * resolved by its own scan, keyed on `usageWhen`.
+     *
+     * Fails CLOSED as a whole: if any matching record fails to resolve every path
+     * to a finite non-negative number, the run reports NO figure at all rather than
+     * a sum missing a term. A partial bill is a wrong bill; an absent one is a case
+     * the pipeline already handles by keeping the estimate.
+     */
+    readonly usagePaths?: readonly (readonly string[])[];
+    /**
+     * The vendor's own QUOTA surface, if it publishes one. Absent means it does
+     * not, and absence is reported as absence with that reason — never as a zero.
+     *
+     * Read from the LAST matching record and reported through
+     * `CliExecutorAdapterOptions.onUsageObservation`, never through the envelope:
+     * the envelope this story switched Claude's stream mode under has to stay
+     * byte-for-byte the one the single-object mode produced.
+     */
+    readonly usageWindows?: UsageWindowTraits;
+}
+export interface ExecutorTraits {
+    /** Stable identity of the executor, independent of which binary path runs it. */
+    readonly executorId: string;
+    /** Default binary; `CliExecutorAdapterOptions.command` overrides it. */
+    readonly command: string;
+    /** Fixed argv, placed before the prompt when `promptDelivery` is `argument`. */
+    readonly args: readonly string[];
+    readonly promptDelivery: PromptDelivery;
+    /**
+     * Emitted between `args` and the prompt so a prompt starting with `-` is not
+     * parsed as a flag. Omit only for a CLI that has no such separator.
+     */
+    readonly promptArgSeparator?: string;
+    readonly output: ExecutorOutputTraits;
+}
+export interface CliExecutorAdapterOptions {
+    /**
+     * Child-process seam. Defaults to the real Node spawner; tests inject fakes
+     * here so suites never touch the actual binary.
+     */
+    readonly spawner?: ChildProcessSpawner;
+    /** Overrides the trait's command, e.g. an absolute path to the binary. */
+    readonly command?: string;
+    /** Receives per-run timing, including NFR-9 spawn-overhead instrumentation. */
+    readonly onTiming?: (timing: AdapterTiming) => void;
+    /**
+     * Receives the vendor's own quota reading for THIS run, when the trait record
+     * declares a surface to read it from (Story M15.A).
+     *
+     * A callback and not an envelope field, because the envelope had to stay
+     * identical across the mode switch that made the reading possible. Called at
+     * most once per run, and only on a run whose child actually printed something
+     * — a spawn that never happened has nothing to observe, which is different
+     * from an executor that ran and said nothing.
+     */
+    readonly onUsageObservation?: (report: UsageReport) => void;
+}
+export interface AdapterTiming {
+    /** Milliseconds spent inside run() before the child was handed to the OS. */
+    readonly spawnSetupMs: number;
+    /** Total wall time of the run() call. */
+    readonly runMs: number;
+}
+/**
+ * An adapter that also answers WHICH executor it drives. `command` can be
+ * overridden per instance (an absolute path, a shim), so it is not an identity;
+ * `executorId` is.
+ */
+export interface CliExecutorAdapter extends ExecutorAdapter {
+    readonly executorId: string;
+}
+/** The engine-owned `data` key a settled cost is read back from. */
+export declare const USAGE_DATA_KEY = "usage";
+export declare function createCliExecutorAdapter(traits: ExecutorTraits, options?: CliExecutorAdapterOptions): CliExecutorAdapter;