dsh-agy-cli 0.0.0-stage → 0.12.0

package/lib/agy/process.d.ts

@@ -0,0 +1,144 @@
+export type ProcessTermination = 'completed' | 'non-zero' | 'signaled' | 'aborted' | 'timeout' | 'idle-timeout' | 'output-limit';
+/**
+ * How `runProcess` retires the stdin pipe after writing the request frame.
+ *
+ * `'close'` ends stdin immediately (the historical behaviour). AGY's print mode
+ * reads that EOF as "there is no next turn", shuts its store manager down and
+ * cancels the turn still being generated — measured as
+ * `Print mode: stream input closed after 1 turn(s)` followed by
+ * `CORTEX_STEP_STATUS_CANCELED` on every step, which surfaces to the user as
+ * text that appears and is then rolled back.
+ *
+ * `'hold'` keeps the pipe open and closes it only when the run is over (a
+ * `result` line arrived, or the process exited). Nothing in AGY's stream-json
+ * contract requires a follow-up frame, so holding costs nothing but the
+ * lifetime of one pipe — and `idleTimeoutMs`/`timeoutMs` still kill a run that
+ * goes silent, so a turn can never hang forever on an unclosed pipe.
+ */
+export type AgyStdinMode = 'close' | 'hold';
+/** Maps a termination to the code the retry classifier sees, so a silence kill
+ * and a wall-clock kill are distinguishable in telemetry without changing the
+ * DSH-facing code (`TIMEOUT` either way). */
+export declare const AGY_REASONING_EFFORTS: readonly ["low", "medium", "high"];
+export type AgyReasoningEffort = typeof AGY_REASONING_EFFORTS[number];
+export declare const AGY_EXECUTION_MODES: readonly ["plan", "accept-edits"];
+export type AgyExecutionMode = typeof AGY_EXECUTION_MODES[number];
+export declare function isAgyReasoningEffort(value: unknown): value is AgyReasoningEffort;
+export declare function isAgyExecutionMode(value: unknown): value is AgyExecutionMode;
+export declare class AgyProcessError extends Error {
+    readonly code: 'ABORTED' | 'SPAWN_FAILED' | 'INPUT_FAILED' | 'INPUT_TOO_LARGE' | 'OUTPUT_HANDLER_FAILED' | 'OUTPUT_LIMIT';
+    readonly diagnostic?: AgyProcessDiagnostic | undefined;
+    constructor(message: string, code: 'ABORTED' | 'SPAWN_FAILED' | 'INPUT_FAILED' | 'INPUT_TOO_LARGE' | 'OUTPUT_HANDLER_FAILED' | 'OUTPUT_LIMIT', options?: ErrorOptions, diagnostic?: AgyProcessDiagnostic | undefined);
+}
+export type AgyProcessDiagnosticStage = 'prepare' | 'spawn' | 'stdin' | 'stdout-handler';
+/**
+ * Safe process-failure metadata; never contains the prompt, the response, or paths.
+ *
+ * `stderrSummary` is the one deliberate exception on the stderr side. When AGY
+ * dies before the first stdin write, the EOF is only a symptom: the cause is a
+ * line AGY already printed to stderr (an eligibility failure, a rejected model,
+ * a broken upstream connection). Without that line every such failure reads as
+ * the same uninformative `(Error:EOF stage=stdin)`. It is therefore carried as a
+ * single redacted, capped line, and only on the stdin stage.
+ */
+export interface AgyProcessDiagnostic {
+    readonly stage: AgyProcessDiagnosticStage;
+    readonly errorName?: string;
+    readonly errorCode?: string;
+    readonly lineNumber?: number;
+    readonly lineLength?: number;
+    readonly lineHash?: string;
+    readonly stdoutLineCount?: number;
+    readonly stdoutBytes?: number;
+    readonly stderrBytes?: number;
+    readonly stderrSummary?: string;
+}
+/**
+ * Pick the most informative stderr line for a failed launch: AGY writes its
+ * fatal reason last, after progress chatter, so the last non-empty line wins.
+ */
+export declare function stderrSummaryOf(stderr: string): string | undefined;
+/** Find process diagnostics through the LlmError -> cause chain. */
+export declare function agyProcessDiagnosticOf(error: unknown): AgyProcessDiagnostic | undefined;
+export interface ProcessRequest {
+    executable: string;
+    args: readonly string[];
+    /** Optional stdin payload written once before the stream is closed. */
+    stdin?: string;
+    /**
+     * Whether to end stdin right after writing the payload (default) or keep it
+     * open until the run finishes. See `AgyStdinMode`.
+     */
+    stdinMode?: AgyStdinMode;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Hard wall-clock ceiling for the whole run. Omitted means unbounded. */
+    timeoutMs?: number;
+    /**
+     * Inactivity budget: the run is killed when no stdout/stderr line arrives for
+     * this long. Re-armed on every delivered line, so a turn that keeps producing
+     * output can run past `timeoutMs` without being cut off. Omitted means only
+     * the wall-clock ceiling applies.
+     */
+    idleTimeoutMs?: number;
+    /** Maximum captured stdout bytes; omitted means unlimited. */
+    maxStdoutBytes?: number;
+    /** Maximum captured stderr bytes; omitted means unlimited. */
+    maxStderrBytes?: number;
+    signal?: AbortSignal;
+    /** Called synchronously for each complete stdout line as it arrives. */
+    onStdoutLine?: (line: string) => void;
+    /** Use the Windows no-console bridge for a console-subsystem executable. */
+    windowsNoConsole?: boolean;
+}
+export interface ProcessResult {
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    termination: ProcessTermination;
+    stdoutLines: readonly string[];
+    stderr: string;
+    durationMs: number;
+    /** Epoch ms of the last stdout/stderr chunk; used to report an idle kill. */
+    lastOutputAtMs?: number;
+}
+export interface AgyRequest extends Omit<ProcessRequest, 'executable' | 'args'> {
+    executable?: string;
+    prompt: string;
+    agent?: string;
+    model?: string;
+    conversation?: string;
+    reasoningEffort?: AgyReasoningEffort;
+    /** Explicit AGY directories made available to the selected Agent. */
+    addDirs?: readonly string[];
+    /** Bounded AGY execution mode selected by an Agent preset. */
+    mode?: AgyExecutionMode;
+    /** Disable slash commands for bundled non-interactive presets. */
+    disableSlashCommands?: boolean;
+    /** Absolute temporary JSON Schema path passed to AGY's final-result validator. */
+    jsonSchemaPath?: string;
+    /** Maximum UTF-8 bytes allowed for one encoded stream-json user frame. */
+    maxInputFrameBytes?: number;
+    /**
+     * How long to keep the request pipe open. AGY's print mode treats an
+     * immediate EOF as "no next turn" and cancels the turn it is still
+     * generating, so the adapter holds the pipe by default; see `AgyStdinMode`.
+     */
+    stdinMode?: AgyStdinMode;
+}
+export declare function defaultAgyCommand(): 'agy.exe' | 'agy';
+/**
+ * Resolve an explicit AGY path, AGY_PATH/AGY_EXECUTABLE, or an executable on
+ * PATH. Returning the bare command in the final fallback lets spawn produce
+ * the platform-native diagnostic if PATH changes between discovery and run.
+ */
+export declare function resolveAgyExecutable(explicit?: string): string;
+/** Build AGY's stdin stream-json argv without invoking a shell. */
+export declare function buildAgyArgs(request: Pick<AgyRequest, 'prompt' | 'agent' | 'model' | 'conversation' | 'reasoningEffort' | 'addDirs' | 'mode' | 'disableSlashCommands' | 'jsonSchemaPath'>): string[];
+/**
+ * Run a process with piped output and deterministic lifecycle handling.
+ * stdout is delivered line-by-line while the process is running; the result
+ * also retains the lines for tests and adapters that do not need live output.
+ */
+export declare function runProcess(request: ProcessRequest): Promise<ProcessResult>;
+export declare function runAgyProcess(request: AgyRequest): Promise<ProcessResult>;
+//# sourceMappingURL=process.d.ts.map

package/lib/agy/process.js

@@ -0,0 +1,452 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { delimiter, join, resolve } from 'node:path';
+import { redactText } from './redact.js';
+import { AgyStreamProtocolError, encodeAgyUserMessage } from './stream-protocol.js';
+import { buildWindowsNoConsoleLaunch } from './windows-launcher.js';
+/** Maps a termination to the code the retry classifier sees, so a silence kill
+ * and a wall-clock kill are distinguishable in telemetry without changing the
+ * DSH-facing code (`TIMEOUT` either way). */
+export const AGY_REASONING_EFFORTS = ['low', 'medium', 'high'];
+export const AGY_EXECUTION_MODES = ['plan', 'accept-edits'];
+export function isAgyReasoningEffort(value) {
+    return typeof value === 'string'
+        && AGY_REASONING_EFFORTS.includes(value);
+}
+export function isAgyExecutionMode(value) {
+    return typeof value === 'string'
+        && AGY_EXECUTION_MODES.includes(value);
+}
+export class AgyProcessError extends Error {
+    code;
+    diagnostic;
+    constructor(message, code, options, diagnostic) {
+        super(message, options);
+        this.code = code;
+        this.diagnostic = diagnostic;
+        this.name = 'AgyProcessError';
+    }
+}
+/** Longest stderr excerpt carried on a stdin failure. */
+const STDERR_SUMMARY_MAX_LENGTH = 200;
+/**
+ * Pick the most informative stderr line for a failed launch: AGY writes its
+ * fatal reason last, after progress chatter, so the last non-empty line wins.
+ */
+export function stderrSummaryOf(stderr) {
+    const lines = stderr.split(/\r?\n/).map(line => line.trim()).filter(line => line.length > 0);
+    const chosen = lines.at(-1);
+    if (chosen === undefined)
+        return undefined;
+    return redactText(chosen, STDERR_SUMMARY_MAX_LENGTH);
+}
+function errorNameOf(error) {
+    return error instanceof Error && error.name.length > 0 ? error.name.slice(0, 128) : undefined;
+}
+function errorCodeOf(error) {
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    const code = error.code;
+    return typeof code === 'string' && code.length > 0 ? code.slice(0, 128) : undefined;
+}
+function integerFieldOf(error, key) {
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    const value = error[key];
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 1 ? value : undefined;
+}
+function shortLineHash(line) {
+    return createHash('sha256').update(line, 'utf8').digest('hex').slice(0, 16);
+}
+function processDiagnosticFor(error, stage, details = {}) {
+    const line = details.line;
+    const errorName = errorNameOf(error);
+    const errorCode = errorCodeOf(error);
+    const lineNumber = integerFieldOf(error, 'lineNumber');
+    return {
+        stage,
+        ...(errorName === undefined ? {} : { errorName }),
+        ...(errorCode === undefined ? {} : { errorCode }),
+        ...(lineNumber === undefined ? {} : { lineNumber }),
+        ...(line === undefined ? {} : {
+            lineLength: line.length,
+            lineHash: shortLineHash(line),
+        }),
+        ...(details.stdoutLineCount === undefined ? {} : { stdoutLineCount: details.stdoutLineCount }),
+        ...(details.stdoutBytes === undefined ? {} : { stdoutBytes: details.stdoutBytes }),
+        ...(details.stderrBytes === undefined ? {} : { stderrBytes: details.stderrBytes }),
+        ...(details.stderrSummary === undefined ? {} : { stderrSummary: details.stderrSummary }),
+    };
+}
+function diagnosticLabel(diagnostic) {
+    if (diagnostic === undefined)
+        return '';
+    const cause = [diagnostic.errorName, diagnostic.errorCode].filter(Boolean).join(':');
+    const line = diagnostic.lineNumber === undefined ? '' : ` line=${diagnostic.lineNumber}`;
+    const length = diagnostic.lineLength === undefined ? '' : ` length=${diagnostic.lineLength}`;
+    const stage = `stage=${diagnostic.stage}`;
+    const stderr = diagnostic.stderrSummary === undefined ? '' : ` stderr=${JSON.stringify(diagnostic.stderrSummary)}`;
+    return ` (${[cause || undefined, stage, line.trim(), length.trim(), stderr.trim()].filter(Boolean).join(' ')})`;
+}
+/** Find process diagnostics through the LlmError -> cause chain. */
+export function agyProcessDiagnosticOf(error) {
+    let current = error;
+    for (let depth = 0; depth < 4 && current !== undefined; depth += 1) {
+        if (current instanceof AgyProcessError && current.diagnostic !== undefined)
+            return current.diagnostic;
+        if (!(current instanceof Error))
+            return undefined;
+        current = current.cause;
+    }
+    return undefined;
+}
+export function defaultAgyCommand() {
+    return process.platform === 'win32' ? 'agy.exe' : 'agy';
+}
+function terminateProcessTree(child) {
+    const pid = child.pid;
+    if (pid === undefined) {
+        child.kill();
+        return;
+    }
+    if (process.platform === 'win32') {
+        const killer = spawn('taskkill', ['/pid', String(pid), '/t', '/f'], {
+            shell: false,
+            windowsHide: true,
+            stdio: 'ignore',
+        });
+        killer.once('error', () => child.kill());
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch {
+        child.kill('SIGKILL');
+    }
+}
+/**
+ * Resolve an explicit AGY path, AGY_PATH/AGY_EXECUTABLE, or an executable on
+ * PATH. Returning the bare command in the final fallback lets spawn produce
+ * the platform-native diagnostic if PATH changes between discovery and run.
+ */
+export function resolveAgyExecutable(explicit) {
+    const configured = explicit?.trim()
+        || process.env.AGY_PATH?.trim()
+        || process.env.AGY_EXECUTABLE?.trim();
+    if (configured !== undefined && configured.length > 0)
+        return resolve(configured);
+    const command = defaultAgyCommand();
+    const pathEntries = (process.env.PATH ?? '').split(delimiter).filter(Boolean);
+    const suffixes = process.platform === 'win32'
+        ? (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+        : [''];
+    for (const directory of pathEntries) {
+        const direct = join(directory, command);
+        if (existsSync(direct))
+            return direct;
+        if (process.platform === 'win32' && !command.includes('.')) {
+            for (const suffix of suffixes) {
+                const candidate = join(directory, `${command}${suffix.toLowerCase()}`);
+                if (existsSync(candidate))
+                    return candidate;
+            }
+        }
+    }
+    return command;
+}
+/** Build AGY's stdin stream-json argv without invoking a shell. */
+export function buildAgyArgs(request) {
+    if (request.reasoningEffort !== undefined && !isAgyReasoningEffort(request.reasoningEffort)) {
+        throw new TypeError('AGY reasoning effort must be one of: low, medium, high');
+    }
+    if (request.mode !== undefined && !isAgyExecutionMode(request.mode)) {
+        throw new TypeError('AGY execution mode must be one of: plan, accept-edits');
+    }
+    if (request.addDirs?.some(directory => typeof directory !== 'string' || directory.trim().length === 0)) {
+        throw new TypeError('AGY add-dir entries must be non-empty paths');
+    }
+    if (request.jsonSchemaPath !== undefined && request.jsonSchemaPath.trim().length === 0) {
+        throw new TypeError('AGY json-schema path must be non-empty');
+    }
+    return [
+        '-p', '',
+        ...(request.agent === undefined ? [] : ['--agent', request.agent]),
+        ...(request.model === undefined ? [] : ['--model', request.model]),
+        ...(request.conversation === undefined ? [] : ['--conversation', request.conversation]),
+        ...(request.reasoningEffort === undefined ? [] : ['--effort', request.reasoningEffort]),
+        ...(request.addDirs?.flatMap(directory => ['--add-dir', directory]) ?? []),
+        ...(request.mode === undefined ? [] : ['--mode', request.mode]),
+        ...(request.disableSlashCommands === true ? ['--disable-slash-commands'] : []),
+        ...(request.jsonSchemaPath === undefined ? [] : ['--json-schema', request.jsonSchemaPath]),
+        '--input-format', 'stream-json',
+        '--output-format', 'stream-json',
+    ];
+}
+function splitLines(buffer, final) {
+    const parts = buffer.split(/\r?\n/);
+    const remainder = parts.pop() ?? '';
+    if (final && remainder.length > 0) {
+        parts.push(remainder.replace(/\r$/, ''));
+        return { lines: parts, remainder: '' };
+    }
+    return { lines: parts, remainder };
+}
+function byteLength(value) {
+    return Buffer.byteLength(value, 'utf8');
+}
+/**
+ * Run a process with piped output and deterministic lifecycle handling.
+ * stdout is delivered line-by-line while the process is running; the result
+ * also retains the lines for tests and adapters that do not need live output.
+ */
+export function runProcess(request) {
+    if (request.signal?.aborted) {
+        return Promise.reject(new AgyProcessError('AGY process aborted before start', 'ABORTED'));
+    }
+    const startedAt = Date.now();
+    let launch;
+    try {
+        launch = request.windowsNoConsole === true
+            ? buildWindowsNoConsoleLaunch(request.executable, request.args)
+            : { executable: request.executable, args: request.args };
+        if (process.platform === 'win32' && request.windowsNoConsole === true && !existsSync(launch.executable)) {
+            throw new Error('Bundled Windows AGY launcher is missing');
+        }
+    }
+    catch (error) {
+        const cause = error instanceof Error ? error : new Error(String(error));
+        const diagnostic = processDiagnosticFor(cause, 'prepare');
+        return Promise.reject(new AgyProcessError(`Unable to prepare AGY launcher: ${cause.message}${diagnosticLabel(diagnostic)}`, 'SPAWN_FAILED', { cause }, diagnostic));
+    }
+    let child;
+    try {
+        child = spawn(launch.executable, [...launch.args], {
+            cwd: request.cwd,
+            env: request.env === undefined ? process.env : { ...process.env, ...request.env },
+            shell: false,
+            detached: process.platform !== 'win32',
+            windowsHide: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch (error) {
+        const cause = error instanceof Error ? error : new Error(String(error));
+        const code = cause.code ?? 'unknown';
+        const diagnostic = processDiagnosticFor(cause, 'spawn');
+        return Promise.reject(new AgyProcessError(`Unable to start AGY executable (${code})${diagnosticLabel(diagnostic)}`, 'SPAWN_FAILED', { cause }, diagnostic));
+    }
+    return new Promise((resolveResult, rejectResult) => {
+        let stdoutBuffer = '';
+        let stderr = '';
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        const stdoutLines = [];
+        let termination;
+        let outputHandlerError;
+        let outputHandlerDiagnostic;
+        let inputError;
+        let settled = false;
+        let lastOutputAtMs = startedAt;
+        let turnClosed = false;
+        const deliver = (line) => {
+            stdoutLines.push(line);
+            if (!turnClosed && resultSeen(line)) {
+                turnClosed = true;
+                endStdin();
+            }
+            if (request.onStdoutLine === undefined || outputHandlerError !== undefined)
+                return;
+            try {
+                request.onStdoutLine(line);
+            }
+            catch (error) {
+                outputHandlerError = error;
+                outputHandlerDiagnostic = processDiagnosticFor(error, 'stdout-handler', {
+                    line,
+                    stdoutLineCount: stdoutLines.length,
+                    stdoutBytes,
+                    stderrBytes,
+                });
+                termination = 'aborted';
+                terminateProcessTree(child);
+            }
+        };
+        const flushStdout = (final) => {
+            const split = splitLines(stdoutBuffer, final);
+            stdoutBuffer = split.remainder;
+            for (const line of split.lines)
+                deliver(line);
+        };
+        const kill = (reason) => {
+            if (termination === undefined)
+                termination = reason;
+            if (!child.killed)
+                terminateProcessTree(child);
+        };
+        // `hold` keeps the request pipe open until the turn is over. Ending it
+        // early is read by AGY as "no next turn" and cancels the running one.
+        const stdinMode = request.stdinMode ?? 'close';
+        let stdinClosed = false;
+        const endStdin = () => {
+            if (stdinClosed || request.stdin === undefined)
+                return;
+            stdinClosed = true;
+            child.stdin.end();
+        };
+        const resultSeen = (line) => {
+            try {
+                const parsed = JSON.parse(line);
+                return typeof parsed === 'object'
+                    && parsed !== null
+                    && parsed.event === 'result';
+            }
+            catch {
+                return false;
+            }
+        };
+        const abortListener = () => kill('aborted');
+        request.signal?.addEventListener('abort', abortListener, { once: true });
+        const timeout = request.timeoutMs !== undefined && request.timeoutMs > 0
+            ? setTimeout(() => kill('timeout'), request.timeoutMs)
+            : undefined;
+        // Idle watchdog: re-armed on every stdout/stderr chunk, so long reasoning
+        // or a long tool step is not mistaken for a hung process. A turn that keeps
+        // producing output outlives `timeoutMs`; only real silence trips it.
+        const idleBudgetMs = request.idleTimeoutMs !== undefined && request.idleTimeoutMs > 0
+            ? request.idleTimeoutMs
+            : undefined;
+        let idle;
+        const armIdle = () => {
+            if (idleBudgetMs === undefined || settled)
+                return;
+            if (idle !== undefined)
+                clearTimeout(idle);
+            idle = setTimeout(() => kill('idle-timeout'), idleBudgetMs);
+        };
+        armIdle();
+        // AGY's own headless default is an unbounded turn, and its `--print-timeout`
+        // is passed separately; a fixed wall clock would cut off a healthy turn, so
+        // it is opt-in via `timeoutMs` and never implied by the idle budget.
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            armIdle();
+            lastOutputAtMs = Date.now();
+            stdoutBytes += byteLength(chunk);
+            if (request.maxStdoutBytes !== undefined && stdoutBytes > request.maxStdoutBytes) {
+                termination = 'output-limit';
+                terminateProcessTree(child);
+                return;
+            }
+            stdoutBuffer += chunk;
+            flushStdout(false);
+        });
+        child.stdout.on('end', () => {
+            if (termination !== 'output-limit')
+                flushStdout(true);
+            // A final `result` line is the contract's "turn is over" signal; the
+            // process is expected to exit on its own, but a held pipe gives it a
+            // clean shutdown cue rather than an EOF it may read as a new turn.
+            if (stdinMode === 'hold')
+                endStdin();
+        });
+        child.stderr.on('data', (chunk) => {
+            armIdle();
+            lastOutputAtMs = Date.now();
+            stderrBytes += byteLength(chunk);
+            if (request.maxStderrBytes !== undefined && stderrBytes > request.maxStderrBytes) {
+                termination = 'output-limit';
+                terminateProcessTree(child);
+                return;
+            }
+            stderr += chunk;
+        });
+        if (request.stdin !== undefined) {
+            child.stdin.once('error', error => {
+                if (settled || inputError !== undefined)
+                    return;
+                inputError = error;
+                kill('aborted');
+            });
+        }
+        child.once('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            if (idle !== undefined)
+                clearTimeout(idle);
+            request.signal?.removeEventListener('abort', abortListener);
+            rejectResult(new AgyProcessError(`Unable to start AGY executable (${error.code ?? 'unknown'})${diagnosticLabel(processDiagnosticFor(error, 'spawn'))}`, 'SPAWN_FAILED', { cause: error }, processDiagnosticFor(error, 'spawn')));
+        });
+        child.once('close', (exitCode, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            endStdin();
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            if (idle !== undefined)
+                clearTimeout(idle);
+            request.signal?.removeEventListener('abort', abortListener);
+            if (termination !== 'output-limit')
+                flushStdout(true);
+            if (outputHandlerError !== undefined) {
+                rejectResult(new AgyProcessError(`AGY stdout handler failed${diagnosticLabel(outputHandlerDiagnostic)}`, 'OUTPUT_HANDLER_FAILED', { cause: outputHandlerError }, outputHandlerDiagnostic));
+                return;
+            }
+            if (inputError !== undefined) {
+                const stderrSummary = stderrSummaryOf(stderr);
+                const diagnostic = processDiagnosticFor(inputError, 'stdin', {
+                    stdoutLineCount: stdoutLines.length,
+                    stdoutBytes,
+                    stderrBytes,
+                    ...(stderrSummary === undefined ? {} : { stderrSummary }),
+                });
+                rejectResult(new AgyProcessError(`Unable to write AGY stream-json input${diagnosticLabel(diagnostic)}`, 'INPUT_FAILED', { cause: inputError instanceof Error ? inputError : new Error(String(inputError)) }, diagnostic));
+                return;
+            }
+            const finalTermination = termination
+                ?? (exitCode === 0 ? 'completed' : signal === null ? 'non-zero' : 'signaled');
+            resolveResult({
+                exitCode,
+                signal,
+                termination: finalTermination,
+                stdoutLines,
+                stderr,
+                durationMs: Date.now() - startedAt,
+                lastOutputAtMs,
+            });
+        });
+        if (request.stdin !== undefined) {
+            child.stdin.write(request.stdin);
+            // `hold` leaves the pipe open until `deliver` sees AGY's closing `result`
+            // line (or the process exits, which closes it anyway). Ending it here is
+            // what made AGY cancel a turn it was still generating.
+            if (stdinMode === 'close')
+                endStdin();
+        }
+    });
+}
+export function runAgyProcess(request) {
+    const executable = resolveAgyExecutable(request.executable);
+    let stdin;
+    try {
+        stdin = encodeAgyUserMessage(request.prompt, request.maxInputFrameBytes);
+    }
+    catch (error) {
+        const tooLarge = error instanceof AgyStreamProtocolError && error.code === 'FRAME_TOO_LARGE';
+        return Promise.reject(new AgyProcessError(error instanceof Error ? error.message : 'Unable to encode AGY stream-json input', tooLarge ? 'INPUT_TOO_LARGE' : 'INPUT_FAILED', { cause: error instanceof Error ? error : new Error(String(error)) }));
+    }
+    return runProcess({
+        ...request,
+        executable,
+        args: buildAgyArgs(request),
+        stdin,
+        windowsNoConsole: true,
+    });
+}
+//# sourceMappingURL=process.js.map

package/lib/agy/redact.d.ts

@@ -0,0 +1,3 @@
+/** Redact common credentials, environment assignments, and user-home prefixes. */
+export declare function redactText(value: string, maxLength?: number): string;
+//# sourceMappingURL=redact.d.ts.map

package/lib/agy/redact.js

@@ -0,0 +1,24 @@
+// Key part allows the surrounding quotes JSON produces: `"token": "v"` must
+// match even though the separator sits one character after the sensitive word.
+const SENSITIVE_ASSIGNMENT = /["']?(authorization|bearer|access[_-]?token|refresh[_-]?token|token|api[_-]?key|password|secret)["']?\s*[:=]\s*(?:bearer\s+)?(?:"[^"]*"|'[^']*'|[^\s,;}]+)/gi;
+const SENSITIVE_QUERY = /([?&](?:access[_-]?token|refresh[_-]?token|api[_-]?key|token|password|secret)=)[^&#\s]+/gi;
+// Bare token shapes that carry no key at all: the sk- keys this workspace's
+// own commit discipline greps for, and credentials in a URL userinfo section.
+const BARE_SK_TOKEN = /\bsk-[A-Za-z0-9]{20,}\b/g;
+const URL_USERINFO = /[a-z][a-z0-9+.-]*:\/\/[^/?#\s]+:[^/?#\s]+@/gi;
+const WINDOWS_USER_PATH = /[A-Za-z]:\\Users\\[^\s"'`,;)]*/g;
+const UNIX_USER_PATH = /\/(?:Users|home)\/[^\s"'`,;)]*/g;
+const ENV_ASSIGNMENT = /\b[A-Z][A-Z0-9_]{2,}=(?:"[^"]*"|'[^']*'|[^\s,;]+)/g;
+/** Redact common credentials, environment assignments, and user-home prefixes. */
+export function redactText(value, maxLength = 1_000) {
+    return value
+        .replace(SENSITIVE_ASSIGNMENT, '$1=[REDACTED]')
+        .replace(SENSITIVE_QUERY, '$1[REDACTED]')
+        .replace(BARE_SK_TOKEN, '[REDACTED]')
+        .replace(URL_USERINFO, '[REDACTED]@')
+        .replace(ENV_ASSIGNMENT, '[ENV]=[REDACTED]')
+        .replace(WINDOWS_USER_PATH, '<user-path>')
+        .replace(UNIX_USER_PATH, '<user-path>')
+        .slice(0, maxLength);
+}
+//# sourceMappingURL=redact.js.map

package/lib/agy/stream-protocol.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Small, transport-neutral helpers for AGY's stdin stream-json mode.
+ *
+ * Real AGY 1.1.15 stream-json input is event-driven. Factual envelope sampled
+ * in V8-M1 (see findings.md 2026-08-20, .tmp/v8-m1/three-turn.log):
+ *   input:  {"event":"user","message":{"role":"user","content":[{"type":"text","text":"..."}]}} per NDJSON line
+ *   output: {"event":"init","conversation_id":"...","init":{...}} then
+ *           {"event":"step_update",...} then {"event":"result",...} per turn.
+ * The generic encodeAgyStreamInput is retained for forward compatibility, but
+ * callers should use the typed encodeAgyUserMessage helper.
+ */
+export type AgyProtocolValue = Record<string, unknown> | readonly unknown[] | string | number | boolean | null;
+export declare class AgyStreamProtocolError extends Error {
+    readonly code: 'INVALID_INPUT' | 'FRAME_TOO_LARGE' | 'INVALID_OUTPUT';
+    constructor(message: string, code: 'INVALID_INPUT' | 'FRAME_TOO_LARGE' | 'INVALID_OUTPUT', options?: ErrorOptions);
+}
+/** Typed input for AGY 1.1.15 stream-json: one user turn per NDJSON line. */
+export interface AgyStreamUserMessage {
+    readonly event: "user";
+    readonly message: {
+        readonly role: "user";
+        readonly content: readonly {
+            readonly type: "text";
+            readonly text: string;
+        }[];
+    };
+}
+/** Encode one stdin NDJSON message without invoking a shell. */
+export declare function encodeAgyStreamInput(message: unknown, maxFrameBytes?: number): string;
+/** Return the exact UTF-8 size of one encoded AGY user frame. */
+export declare function getAgyUserMessageByteLength(text: string): number;
+/** Encode one AGY stream-json user turn with the factual V8-M1 envelope. */
+export declare function encodeAgyUserMessage(text: string, maxFrameBytes?: number): string;
+/**
+ * Replace all free-form strings and identifiers while retaining enough
+ * structure to replay parser behavior. Stable protocol enum fields remain.
+ */
+export declare function sanitizeAgyProtocolValue(value: unknown, key?: string, depth?: number): unknown;
+export interface AgyProtocolRecordSummary {
+    readonly topLevelKeys: readonly string[];
+    readonly event: string | null;
+    readonly shapePaths: readonly string[];
+    readonly valueKinds: readonly string[];
+    readonly stringLengths: Readonly<Record<string, number>>;
+}
+/** Summarize one decoded output record without returning its payload. */
+export declare function summarizeAgyProtocolValue(value: unknown): AgyProtocolRecordSummary;
+/** Convert one decoded output record into a safe fixture value. */
+export declare function sanitizeAgyProtocolRecord(value: unknown): unknown;
+//# sourceMappingURL=stream-protocol.d.ts.map