@qvac/harness 0.0.0 → 0.1.1

package/dist-lib/lib/hardware/parsers.d.ts

@@ -0,0 +1,7 @@
+import type { MemoryBudget } from './memory-budget.ts';
+export declare const IGPU_LIE_THRESHOLD = 0.9;
+export declare function parseNvidiaSmiOutput(stdout: string): MemoryBudget | null;
+export declare function parseRocmSmiOutput(stdout: string): MemoryBudget | null;
+export declare function parseWindowsRegistryOutput(stdout: string, systemRamBytes: number): MemoryBudget | null;
+export declare function sharedRamBudget(ramBytes: number): MemoryBudget;
+export declare function mobileBudget(ramBytes: number, isPixel: boolean): MemoryBudget;

package/dist-lib/lib/hardware/parsers.js

@@ -0,0 +1,41 @@
+const GIB = 1024 * 1024 * 1024;
+const SHARED_RAM_RESERVE_BYTES = 3 * GIB;
+const SHARED_RAM_FRACTION = 0.8;
+const MOBILE_FRACTION = 0.6;
+const MOBILE_PIXEL_FRACTION = 0.4;
+export const IGPU_LIE_THRESHOLD = 0.9;
+export function parseNvidiaSmiOutput(stdout) {
+    const firstLine = stdout.split('\n')[0] ?? '';
+    const mib = Number.parseInt(firstLine, 10);
+    if (Number.isNaN(mib) || mib <= 0)
+        return null;
+    const bytes = mib * 1024 * 1024;
+    return { totalBytes: bytes, availableBytes: bytes, source: 'vram', gpuClass: 'discrete' };
+}
+export function parseRocmSmiOutput(stdout) {
+    const match = /Total.*?:\s*(\d+)/i.exec(stdout);
+    if (!match)
+        return null;
+    const bytes = Number.parseInt(match[1] ?? '', 10);
+    if (Number.isNaN(bytes) || bytes <= 0)
+        return null;
+    return { totalBytes: bytes, availableBytes: bytes, source: 'vram' };
+}
+export function parseWindowsRegistryOutput(stdout, systemRamBytes) {
+    const firstLine = stdout.split('\n')[0] ?? '';
+    const bytes = Number.parseInt(firstLine, 10);
+    if (Number.isNaN(bytes) || bytes <= 0)
+        return null;
+    if (bytes > systemRamBytes * IGPU_LIE_THRESHOLD) {
+        return { ...sharedRamBudget(systemRamBytes), source: 'integrated' };
+    }
+    return { totalBytes: bytes, availableBytes: bytes, source: 'vram' };
+}
+export function sharedRamBudget(ramBytes) {
+    const available = Math.min(ramBytes * SHARED_RAM_FRACTION, ramBytes - SHARED_RAM_RESERVE_BYTES);
+    return { totalBytes: ramBytes, availableBytes: Math.max(available, 0), source: 'shared' };
+}
+export function mobileBudget(ramBytes, isPixel) {
+    const fraction = isPixel ? MOBILE_PIXEL_FRACTION : MOBILE_FRACTION;
+    return { totalBytes: ramBytes, availableBytes: ramBytes * fraction, source: 'mobile' };
+}

package/dist-lib/lib/headers-bare.d.ts

@@ -0,0 +1 @@
+export { Headers } from 'bare-fetch';

package/dist-lib/lib/headers-bare.js

@@ -0,0 +1 @@
+export { Headers } from 'bare-fetch';

package/dist-lib/lib/headers-node.d.ts

@@ -0,0 +1,4 @@
+export declare const Headers: {
+    new (init?: HeadersInit): Headers;
+    prototype: Headers;
+};

package/dist-lib/lib/headers-node.js

@@ -0,0 +1 @@
+export const Headers = globalThis.Headers;

package/dist-lib/lib/helpers/buffer-burst.d.ts

@@ -0,0 +1 @@
+export declare function bufferBurst(tokens: AsyncIterable<string>, ms: number): AsyncGenerator<string>;

package/dist-lib/lib/helpers/buffer-burst.js

@@ -0,0 +1,20 @@
+export async function* bufferBurst(tokens, ms) {
+    const deadline = Date.now() + ms;
+    let burst = '';
+    for await (const token of tokens) {
+        if (burst === null) {
+            yield token;
+            continue;
+        }
+        if (Date.now() >= deadline) {
+            if (burst)
+                yield burst;
+            burst = null;
+            yield token;
+            continue;
+        }
+        burst += token;
+    }
+    if (burst)
+        yield burst;
+}

package/dist-lib/lib/helpers/control-tokens.d.ts

@@ -0,0 +1,7 @@
+export declare const STOP_MARKERS: readonly string[];
+export declare const RUNAWAY_STOP_SEQUENCES: readonly string[];
+export declare function endsTurn(token: string): boolean;
+export declare function controlTokenIndex(text: string): number;
+export declare function truncateAtControlToken(text: string): string;
+export declare function stripControlTokens(text: string): string;
+export declare function stopAtControlToken(tokens: AsyncIterable<string>, onStop?: (token: string) => void): AsyncGenerator<string>;

package/dist-lib/lib/helpers/control-tokens.js

@@ -0,0 +1,32 @@
+import { firstMarker, markers, strip, truncateAt } from 'asenion/guards';
+import { scanner } from 'asenion/scan';
+export const STOP_MARKERS = [...markers.controlTokens, ...markers.scaffold];
+const [SCAFFOLD_OPENING] = markers.scaffold;
+export const RUNAWAY_STOP_SEQUENCES = [SCAFFOLD_OPENING];
+export function endsTurn(token) {
+    return markers.turnEnd.includes(token);
+}
+export function controlTokenIndex(text) {
+    return firstMarker(text, STOP_MARKERS)?.index ?? -1;
+}
+export function truncateAtControlToken(text) {
+    return truncateAt(text, STOP_MARKERS);
+}
+export function stripControlTokens(text) {
+    return strip(truncateAt(text, markers.scaffold), markers.controlTokens);
+}
+export async function* stopAtControlToken(tokens, onStop) {
+    const safe = scanner({ stop: STOP_MARKERS });
+    for await (const token of tokens) {
+        const shown = safe.push(token);
+        if (shown)
+            yield shown;
+        if (safe.stopped !== null) {
+            onStop?.(safe.stopped);
+            return;
+        }
+    }
+    const rest = safe.flush();
+    if (rest)
+        yield rest;
+}

package/dist-lib/lib/helpers/join-guard.d.ts

@@ -0,0 +1,6 @@
+export type JoinGuard = {
+    readonly push: (text: string) => string;
+    readonly cut: () => void;
+    readonly flush: () => string;
+};
+export declare function createJoinGuard(markers: readonly string[]): JoinGuard;

package/dist-lib/lib/helpers/join-guard.js

@@ -0,0 +1,46 @@
+import { holdback } from 'asenion/scan';
+export function createJoinGuard(markers) {
+    let held = '';
+    let join = -1;
+    return {
+        push(text) {
+            let buffer = held + text;
+            if (join !== -1) {
+                const mended = mend(buffer, join, markers);
+                buffer = mended.text;
+                join = mended.at;
+            }
+            const keep = holdback(buffer, markers);
+            const shown = buffer.slice(0, buffer.length - keep);
+            held = buffer.slice(buffer.length - keep);
+            join = join === -1 || join < shown.length ? -1 : join - shown.length;
+            return shown;
+        },
+        cut() {
+            join = held.length;
+        },
+        flush() {
+            const rest = held;
+            held = '';
+            join = -1;
+            return rest;
+        }
+    };
+}
+function mend(text, at, markers) {
+    for (;;) {
+        const found = spanning(text, at, markers);
+        if (found === null)
+            return { text, at };
+        text = text.slice(0, found.index) + text.slice(found.index + found.marker.length);
+        at = found.index;
+    }
+}
+function spanning(text, at, markers) {
+    for (const marker of markers) {
+        const index = text.indexOf(marker, Math.max(0, at - marker.length + 1));
+        if (index !== -1 && index < at)
+            return { index, marker };
+    }
+    return null;
+}

package/dist-lib/lib/helpers/markup-stream-filter.d.ts

@@ -0,0 +1,5 @@
+export type MarkupStreamFilter = {
+    readonly push: (token: string) => string;
+    readonly flush: () => string;
+};
+export declare function createMarkupStreamFilter(): MarkupStreamFilter;

package/dist-lib/lib/helpers/markup-stream-filter.js

@@ -0,0 +1,75 @@
+import { firstMarker } from 'asenion/guards';
+import { holdback } from 'asenion/scan';
+import { createJoinGuard } from "./join-guard.js";
+const MARKUP_OPENERS = ['<tool_call>', '<function=', '<tool_response>'];
+const MARKUP_CLOSERS = {
+    '<tool_call>': '</tool_call>',
+    '<function=': '</function>',
+    '<tool_response>': '</tool_response>'
+};
+const MARKUP_MARKERS = [...MARKUP_OPENERS, ...Object.values(MARKUP_CLOSERS)];
+export function createMarkupStreamFilter() {
+    const state = {
+        buffer: '',
+        closer: null,
+        stripNewline: false,
+        guard: createJoinGuard(MARKUP_MARKERS)
+    };
+    return {
+        push(token) {
+            state.buffer += token;
+            let out = '';
+            for (;;) {
+                const step = state.closer ? consumeSuppressed(state) : emitUntilOpener(state);
+                out += step.out;
+                if (step.done)
+                    return out;
+            }
+        },
+        flush() {
+            dropResumeNewline(state);
+            const rest = state.guard.push(state.closer ? '' : state.buffer) + state.guard.flush();
+            state.buffer = '';
+            state.closer = null;
+            state.stripNewline = false;
+            return rest;
+        }
+    };
+}
+function consumeSuppressed(state) {
+    const closer = state.closer ?? '';
+    const end = state.buffer.indexOf(closer);
+    if (end === -1) {
+        state.buffer = state.buffer.slice(state.buffer.length - holdback(state.buffer, [closer]));
+        return { out: '', done: true };
+    }
+    state.buffer = state.buffer.slice(end + closer.length);
+    state.stripNewline = true;
+    state.closer = null;
+    return { out: '', done: false };
+}
+function dropResumeNewline(state) {
+    if (!state.stripNewline || state.buffer.length === 0)
+        return;
+    state.stripNewline = false;
+    if (state.buffer[0] === '\n')
+        state.buffer = state.buffer.slice(1);
+}
+function emitUntilOpener(state) {
+    dropResumeNewline(state);
+    const marker = firstMarker(state.buffer, MARKUP_MARKERS);
+    if (marker) {
+        const out = state.guard.push(state.buffer.slice(0, marker.index));
+        state.guard.cut();
+        state.buffer = state.buffer.slice(marker.index + marker.marker.length);
+        const closer = MARKUP_CLOSERS[marker.marker];
+        if (closer === undefined)
+            state.stripNewline = true;
+        state.closer = closer ?? null;
+        return { out, done: false };
+    }
+    const hold = holdback(state.buffer, MARKUP_MARKERS);
+    const out = state.guard.push(state.buffer.slice(0, state.buffer.length - hold));
+    state.buffer = state.buffer.slice(state.buffer.length - hold);
+    return { out, done: true };
+}

package/dist-lib/lib/helpers/race-abort.d.ts

@@ -0,0 +1,5 @@
+import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
+export declare class AbortedError extends Error {
+    constructor();
+}
+export declare function raceAbort<T>(promise: Promise<T>, signal?: BareAbortSignal): Promise<T>;

package/dist-lib/lib/helpers/race-abort.js

@@ -0,0 +1,18 @@
+export class AbortedError extends Error {
+    constructor() {
+        super('aborted');
+        this.name = 'AbortedError';
+        Error.captureStackTrace?.(this, AbortedError);
+    }
+}
+export function raceAbort(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(new AbortedError());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new AbortedError());
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}

package/dist-lib/lib/helpers/retry-memo.d.ts

@@ -0,0 +1,5 @@
+export interface RetryMemo<T> {
+    (): Promise<T>;
+    peek(): Promise<T> | null;
+}
+export declare function retryMemo<T>(load: () => Promise<T>): RetryMemo<T>;

package/dist-lib/lib/helpers/retry-memo.js

@@ -0,0 +1,12 @@
+export function retryMemo(load) {
+    let memo = null;
+    return Object.assign(() => {
+        memo ??= Promise.resolve()
+            .then(load)
+            .catch((err) => {
+            memo = null;
+            throw err;
+        });
+        return memo;
+    }, { peek: () => memo });
+}

package/dist-lib/lib/helpers/run-outcome.d.ts

@@ -0,0 +1,33 @@
+import type { ToolExecutionOutcome } from '../tool-call-display.ts';
+export type RunOutcome = 'answered' | 'mute' | 'exhausted' | 'search-capped' | 'time-capped';
+export declare const DEGENERATE_ANSWER_FALLBACK = "I couldn't complete that step and don't have a useful result to share.";
+export declare const ROUND_CAP_ANSWER = "I ran out of steps before I could finish that. Ask me to continue and I'll pick up where I left off.";
+export declare const SEARCH_CAPPED_ANSWER = "I searched the web but couldn't find the answer in the results I got.";
+export declare const WRITE_RESULT_LEAD = "Here's what came back:";
+export declare const TIME_CAPPED_ANSWER = "I hit this run's time budget before I could finish that. Ask me to continue and I'll pick up where I left off.";
+export interface RunOutcomeFacts {
+    readonly latestFailure: string | null;
+    readonly confirmedWrites: ReadonlyArray<string>;
+}
+export interface RunOutcomeTracker {
+    readonly confirmedWrites: string[];
+    beginRound(): void;
+    record(result: unknown, outcome: ToolExecutionOutcome): void;
+    finishRound(): void;
+    confirmWrite(result: unknown): void;
+    facts(): RunOutcomeFacts;
+}
+export declare function createRunOutcomeTracker(): RunOutcomeTracker;
+export declare function normalizeToolExecutionOutcome(result: unknown, outcome: ToolExecutionOutcome): ToolExecutionOutcome;
+export declare function failureFromToolExecution(result: unknown, outcome: ToolExecutionOutcome): string | null;
+export declare function degenerateAnswer(outcome: Exclude<RunOutcome, 'answered'>, history: ReadonlyArray<{
+    role: string;
+    content: string;
+}>, facts?: RunOutcomeFacts): string;
+export declare function lastFailedToolAnswer(history: ReadonlyArray<{
+    role: string;
+    content: string;
+}>): string | null;
+export declare function writeResult(output: unknown): string | null;
+export declare function unnamedWrites(answer: string, landed: ReadonlyArray<string>): ReadonlyArray<string>;
+export declare function writeReport(landed: ReadonlyArray<string>): string | null;

package/dist-lib/lib/helpers/run-outcome.js

@@ -0,0 +1,204 @@
+import { TOOL_CONTINUATION_NUDGE } from "../capabilities/tool-turns.js";
+export const DEGENERATE_ANSWER_FALLBACK = "I couldn't complete that step and don't have a useful result to share.";
+export const ROUND_CAP_ANSWER = "I ran out of steps before I could finish that. Ask me to continue and I'll pick up where I left off.";
+export const SEARCH_CAPPED_ANSWER = "I searched the web but couldn't find the answer in the results I got.";
+export const WRITE_RESULT_LEAD = "Here's what came back:";
+export const TIME_CAPPED_ANSWER = "I hit this run's time budget before I could finish that. Ask me to continue and I'll pick up where I left off.";
+const MAX_FAILURE_CHARS = 300;
+const MAX_SUCCESS_CHARS = 800;
+const MAX_WRITES_LISTED = 4;
+const MAX_CAPPED_SOURCES = 3;
+const TOOL_RESULT_HEADER_RE = /^\[Tool: [^(\]]+ \([^)]+\)\]\n/;
+const WEB_SEARCH_TURN_RE = /^\[Tool: web_search /;
+const RESULT_ENTRY_RE = /\[\d+\] ([^\n]+)\nSource: (\S+)/g;
+const WRITE_ID_RE = /[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}/gi;
+export function createRunOutcomeTracker() {
+    const confirmedWrites = [];
+    let roundFailure = null;
+    let latestFailure = null;
+    let hasRoundResult = false;
+    return {
+        confirmedWrites,
+        beginRound() {
+            roundFailure = null;
+            hasRoundResult = false;
+        },
+        record(result, outcome) {
+            hasRoundResult = true;
+            const failure = failureFromToolExecution(result, outcome);
+            if (failure)
+                roundFailure = failure;
+        },
+        finishRound() {
+            if (!hasRoundResult)
+                return;
+            latestFailure = roundFailure;
+        },
+        confirmWrite(result) {
+            const write = writeResult(result);
+            if (write)
+                confirmedWrites.push(write);
+        },
+        facts() {
+            return { latestFailure, confirmedWrites };
+        }
+    };
+}
+export function normalizeToolExecutionOutcome(result, outcome) {
+    if (outcome.kind !== 'success')
+        return outcome;
+    const failure = resultFailure(result);
+    return failure ? { kind: 'error', message: failure } : outcome;
+}
+export function failureFromToolExecution(result, outcome) {
+    if (outcome.kind === 'denied' || outcome.kind === 'blocked' || outcome.kind === 'guidance') {
+        return null;
+    }
+    if (outcome.kind === 'error') {
+        return bound(outcome.message ?? resultFailure(result) ?? 'The request failed.', MAX_FAILURE_CHARS);
+    }
+    return resultFailure(result);
+}
+export function degenerateAnswer(outcome, history, facts) {
+    const rest = (facts ? facts.latestFailure : lastFailedToolAnswer(history)) ?? cappedAnswer(outcome, history);
+    const written = writeReport(facts?.confirmedWrites ?? []);
+    if (written)
+        return rest ? `${written}\n\n${rest}` : written;
+    return rest ?? DEGENERATE_ANSWER_FALLBACK;
+}
+function cappedAnswer(outcome, history) {
+    if (outcome === 'search-capped')
+        return searchCappedAnswer(history);
+    if (outcome === 'time-capped')
+        return TIME_CAPPED_ANSWER;
+    return outcome === 'exhausted' ? ROUND_CAP_ANSWER : null;
+}
+function searchCappedAnswer(history) {
+    const seen = new Set();
+    const lines = [];
+    for (const turn of history) {
+        if (lines.length === MAX_CAPPED_SOURCES)
+            break;
+        if (turn.role !== 'tool' || !WEB_SEARCH_TURN_RE.test(turn.content))
+            continue;
+        const payload = parsed(turn.content.replace(TOOL_RESULT_HEADER_RE, ''));
+        const content = typeof payload?.content === 'string' ? payload.content : '';
+        for (const [, title, url] of content.matchAll(RESULT_ENTRY_RE)) {
+            if (title === undefined || url === undefined)
+                continue;
+            if (seen.has(url))
+                continue;
+            seen.add(url);
+            lines.push(`- ${title.trim()}: ${url}`);
+            if (lines.length === MAX_CAPPED_SOURCES)
+                break;
+        }
+    }
+    if (!lines.length)
+        return SEARCH_CAPPED_ANSWER;
+    return `${SEARCH_CAPPED_ANSWER} These pages looked most relevant:\n${lines.join('\n')}`;
+}
+export function lastFailedToolAnswer(history) {
+    for (let i = history.length - 1; i >= 0; i--) {
+        const turn = history[i];
+        if (turn?.role === 'user' && turn.content === TOOL_CONTINUATION_NUDGE)
+            continue;
+        if (turn?.role !== 'tool')
+            return null;
+        const failure = failureText(turn.content.replace(TOOL_RESULT_HEADER_RE, ''));
+        if (failure)
+            return failure;
+    }
+    return null;
+}
+export function writeResult(output) {
+    const result = asRecord(output);
+    if (!result || typeof result.status !== 'number')
+        return null;
+    if (result.status >= 400 || nonEmpty(result.error))
+        return null;
+    return nonEmpty(result.body);
+}
+export function unnamedWrites(answer, landed) {
+    const said = withoutDashes(answer);
+    return landed.filter((write) => {
+        const ids = writeIds(write);
+        return ids.length > 0 && !ids.some((id) => said.includes(id));
+    });
+}
+function writeIds(write) {
+    return [...write.matchAll(WRITE_ID_RE)].map(([id]) => withoutDashes(id));
+}
+function withoutDashes(text) {
+    return text.toLowerCase().replace(/-/g, '');
+}
+export function writeReport(landed) {
+    if (!landed.length)
+        return null;
+    const listed = landed.slice(0, MAX_WRITES_LISTED);
+    const share = Math.floor(MAX_SUCCESS_CHARS / listed.length);
+    const lines = listed.map((write) => bound(write, share));
+    const dropped = landed.length - listed.length;
+    if (dropped)
+        lines.push(`(+${dropped} more)`);
+    return `${WRITE_RESULT_LEAD}\n${lines.join('\n')}`;
+}
+function failureText(payload) {
+    const result = parsed(payload);
+    return resultFailure(result);
+}
+function resultFailure(value) {
+    const result = typeof value === 'string' ? parsed(value) : asRecord(value);
+    if (!result)
+        return null;
+    if (result.denied === true || result.guidance === true)
+        return null;
+    const status = typeof result.status === 'number' ? result.status : null;
+    const httpSuffix = status !== null && status >= 400 ? ` (HTTP ${status.toString()})` : '';
+    const error = nonEmpty(result.error);
+    if (error)
+        return `${bound(error, MAX_FAILURE_CHARS)}${httpSuffix}`;
+    if (status !== null && status >= 400)
+        return httpFailure(status, result.body);
+    if (typeof result.exitCode === 'number' && result.exitCode !== 0) {
+        const output = nonEmpty(result.stderr) ?? nonEmpty(result.stdout);
+        return output ? bound(output, MAX_FAILURE_CHARS) : null;
+    }
+    return null;
+}
+function httpFailure(status, body) {
+    const message = apiMessage(body);
+    return message
+        ? `${bound(message, MAX_FAILURE_CHARS)} (HTTP ${status})`
+        : `The request failed with HTTP ${status}.`;
+}
+function apiMessage(body) {
+    const value = typeof body === 'string' ? parsed(body) : asRecord(body);
+    if (!value)
+        return null;
+    const error = value.error;
+    const fromError = typeof error === 'string' ? nonEmpty(error) : nonEmpty(asRecord(error)?.['message']);
+    return fromError ?? nonEmpty(value.message);
+}
+function parsed(payload) {
+    try {
+        return asRecord(JSON.parse(payload));
+    }
+    catch {
+        return null;
+    }
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function nonEmpty(value) {
+    if (typeof value !== 'string')
+        return null;
+    const text = value.trim();
+    return text || null;
+}
+function bound(text, max) {
+    return text.length > max ? `${text.slice(0, max).trimEnd()}…` : text;
+}

package/dist-lib/lib/helpers/spawn-path.d.ts

@@ -0,0 +1,5 @@
+export declare const HOMEBREW_BIN_DIRS: readonly string[];
+export declare function withHomebrewPath(path: string | undefined, platformName: string): string | undefined;
+export declare const EXEC_ENV_ALLOWLIST: readonly ["PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LC_ALL", "LC_CTYPE", "TZ", "USER", "LOGNAME", "HTTP_PROXY", "http_proxy", "HTTPS_PROXY", "https_proxy", "ALL_PROXY", "all_proxy", "NO_PROXY", "no_proxy", "SSL_CERT_FILE", "SSL_CERT_DIR", "CURL_CA_BUNDLE", "REQUESTS_CA_BUNDLE", "NODE_EXTRA_CA_CERTS"];
+export declare function execEnv(env: Readonly<Record<string, string | undefined>>, platformName: string): Record<string, string>;
+export declare function spawnEnv(env: Readonly<Record<string, string | undefined>>, platformName: string, overrides?: Readonly<Record<string, string>>): Record<string, string>;

package/dist-lib/lib/helpers/spawn-path.js

@@ -0,0 +1,57 @@
+export const HOMEBREW_BIN_DIRS = ['/opt/homebrew/bin', '/usr/local/bin'];
+export function withHomebrewPath(path, platformName) {
+    if (platformName !== 'darwin')
+        return path;
+    const dirs = (path ?? '').split(':').filter(Boolean);
+    const seen = new Set(dirs);
+    const missing = HOMEBREW_BIN_DIRS.filter((dir) => !seen.has(dir));
+    if (missing.length === 0)
+        return path;
+    return [...dirs, ...missing].join(':');
+}
+export const EXEC_ENV_ALLOWLIST = [
+    'PATH',
+    'HOME',
+    'TMPDIR',
+    'TMP',
+    'TEMP',
+    'LANG',
+    'LC_ALL',
+    'LC_CTYPE',
+    'TZ',
+    'USER',
+    'LOGNAME',
+    'HTTP_PROXY',
+    'http_proxy',
+    'HTTPS_PROXY',
+    'https_proxy',
+    'ALL_PROXY',
+    'all_proxy',
+    'NO_PROXY',
+    'no_proxy',
+    'SSL_CERT_FILE',
+    'SSL_CERT_DIR',
+    'CURL_CA_BUNDLE',
+    'REQUESTS_CA_BUNDLE',
+    'NODE_EXTRA_CA_CERTS'
+];
+const PLATFORM_EXEC_ENV_ALLOWLIST = {
+    win32: ['SystemRoot', 'COMSPEC', 'PATHEXT', 'USERPROFILE'],
+    linux: ['DISPLAY', 'WAYLAND_DISPLAY', 'XDG_RUNTIME_DIR']
+};
+export function execEnv(env, platformName) {
+    const out = {};
+    const keys = [...EXEC_ENV_ALLOWLIST, ...(PLATFORM_EXEC_ENV_ALLOWLIST[platformName] ?? [])];
+    for (const key of keys) {
+        const value = env[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    const path = withHomebrewPath(out.PATH ?? env.Path, platformName);
+    if (path !== undefined)
+        out.PATH = path;
+    return out;
+}
+export function spawnEnv(env, platformName, overrides) {
+    return { ...execEnv(env, platformName), ...overrides };
+}

package/dist-lib/lib/helpers/text-coalescer.d.ts

@@ -0,0 +1,15 @@
+export type TextType = 'content' | 'thinking';
+export interface TextCoalescerOptions {
+    cap?: number;
+    holdMs?: number;
+}
+export declare class TextCoalescer {
+    private readonly _write;
+    private readonly _cap;
+    private readonly _holdMs;
+    private _buffered;
+    private _hold;
+    constructor(write: (type: TextType, text: string) => Promise<void>, { cap, holdMs }?: TextCoalescerOptions);
+    add(type: TextType, text: string): Promise<void>;
+    flush(): Promise<void>;
+}

package/dist-lib/lib/helpers/text-coalescer.js

@@ -0,0 +1,34 @@
+export class TextCoalescer {
+    _write;
+    _cap;
+    _holdMs;
+    _buffered = null;
+    _hold = null;
+    constructor(write, { cap = 8192, holdMs = 60 } = {}) {
+        this._write = write;
+        this._cap = cap;
+        this._holdMs = holdMs;
+    }
+    async add(type, text) {
+        if (this._buffered && this._buffered.type !== type)
+            await this.flush();
+        if (!this._buffered) {
+            this._buffered = { type, text: '' };
+            this._hold = setTimeout(() => void this.flush(), this._holdMs);
+        }
+        this._buffered.text += text;
+        if (this._buffered.text.length >= this._cap)
+            await this.flush();
+    }
+    flush() {
+        if (this._hold) {
+            clearTimeout(this._hold);
+            this._hold = null;
+        }
+        if (!this._buffered)
+            return Promise.resolve();
+        const { type, text } = this._buffered;
+        this._buffered = null;
+        return this._write(type, text);
+    }
+}