@withtruing/companion 0.0.0-stage → 0.13.0

package/dist/claude-cli-caller.js

@@ -0,0 +1,344 @@
+/**
+ * The 3a backend (see the local-companion plan's Section 3a) — shells out to an already-authenticated
+ * `claude` CLI for full agentic Read/Grep/Glob depth, rather than this package driving its own
+ * file-selection pass the way api-key-caller.ts does. One CLI call fulfills a whole task (find
+ * the files, read them, do the task) — the model does its own exploring, so every task kind
+ * shares the same invocation mechanics below; only the ModelTaskSpec (prompt/schema) differs
+ * per kind, extracted from that task's own payload shape by its own thin wrapper at the bottom.
+ *
+ * Every shape assumed below (the JSON result envelope, the stream-json tool-use event shape,
+ * --max-budget-usd's exceeded-budget behavior) was confirmed with real, budgeted `claude` calls
+ * during development, not guessed from --help text alone — see the Phase 2 PR description.
+ */
+import { rmSync } from 'node:fs';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { StringDecoder } from 'node:string_decoder';
+import { assertSingleLineArguments } from './cli-arguments.js';
+import { spawnClaude } from './claude-binary.js';
+import { gitErrorMessage } from './sandbox.js';
+import { appendDiffToVolatile, prepareShipmentAnalysis } from './shipment.js';
+import { ModelRefusalError } from './text-model.js';
+/** Independent of --max-budget-usd — a dollar cap doesn't prevent a network-stall hang. No
+ *  automatic retry on top of this (see cli.ts): auto-retry would risk double-spending the
+ *  customer's own subscription/API quota. */
+const WALL_CLOCK_TIMEOUT_MS = 10 * 60 * 1000;
+const INVESTIGATION_CALL_BUDGET_USD = 2;
+const STDOUT_SAMPLE_CHARS = 200;
+const UNPARSEABLE_LINE_SAMPLE_CHARS = 120;
+const EMPTY_MCP_CONFIG = '{"mcpServers":{}}';
+let emptyMcpConfigPathPromise = null;
+let emptyMcpConfigDir = null;
+async function createEmptyMcpConfig() {
+    const dir = await mkdtemp(join(tmpdir(), 'product-console-claude-mcp-'));
+    const path = join(dir, 'mcp.json');
+    try {
+        await writeFile(path, EMPTY_MCP_CONFIG, { encoding: 'utf8', mode: 0o600 });
+    }
+    catch (error) {
+        await rm(dir, { recursive: true, force: true });
+        throw error;
+    }
+    emptyMcpConfigDir = dir;
+    process.once('exit', () => {
+        if (emptyMcpConfigDir)
+            rmSync(emptyMcpConfigDir, { recursive: true, force: true });
+    });
+    return path;
+}
+async function getEmptyMcpConfigPath() {
+    emptyMcpConfigPathPromise ??= createEmptyMcpConfig();
+    try {
+        return await emptyMcpConfigPathPromise;
+    }
+    catch (error) {
+        emptyMcpConfigPathPromise = null;
+        throw error;
+    }
+}
+function sampleForError(value) {
+    return gitErrorMessage(JSON.stringify(value));
+}
+function promptWriteFailure(error) {
+    const code = error.code ? ` (${error.code})` : '';
+    const wrapped = new Error(`Failed to write the prompt to claude CLI stdin${code}: ${gitErrorMessage(error)}`, { cause: error });
+    wrapped.code = error.code;
+    wrapped.errno = error.errno;
+    wrapped.syscall = error.syscall;
+    return wrapped;
+}
+/** The model sometimes emits an absolute path matching the sandbox root, sometimes a
+ *  POSIX-flavoured path as if --add-dir were mounted at "/" — normalize both down to a
+ *  repo-relative path, matching api-key-caller.ts's own filesRead convention. */
+function normalizeToRepoRelative(filePath, root) {
+    const p = filePath.replace(/\\/g, '/');
+    const r = root.replace(/\\/g, '/');
+    return (p.startsWith(r) ? p.slice(r.length) : p).replace(/^\/+/, '');
+}
+/** The actual invocation — task-kind-agnostic. Repo-scoped calls receive the disposable snapshot
+ *  sandbox as `repoPath`; connection-less calls grant no tools and need no sandbox.
+ *  Returns whatever structured_output the model produced plus every file it actually read via
+ *  the Read tool. Every exported per-kind function below is a thin wrapper over this. */
+async function runViaCli(spec, maxBudgetUsd, repoPath, connectionless = false) {
+    if (spec.stableDocumentBase64) {
+        throw new Error("This task includes a PDF PRD, which the cli backend can't read yet. Pair with " +
+            '--backend api-key instead, or re-upload the PRD as .md/.txt/.docx.');
+    }
+    const sandboxPath = connectionless ? tmpdir() : repoPath;
+    let systemPromptDir = null;
+    try {
+        systemPromptDir = await mkdtemp(join(tmpdir(), 'product-console-claude-system-'));
+        const systemPromptPath = join(systemPromptDir, 'prompt.txt');
+        await writeFile(systemPromptPath, spec.system, { encoding: 'utf8', mode: 0o600 });
+        const emptyMcpConfigPath = await getEmptyMcpConfigPath();
+        const args = [
+            '-p',
+            '--system-prompt-file',
+            systemPromptPath,
+            '--strict-mcp-config',
+            '--mcp-config',
+            emptyMcpConfigPath,
+            '--output-format',
+            'stream-json',
+            '--verbose',
+            ...(spec.schema ? ['--json-schema', JSON.stringify(spec.schema)] : []),
+            '--restricted',
+            ...(connectionless ? ['--tools', ''] : ['--tools', 'Read,Grep,Glob', '--add-dir', sandboxPath]),
+            '--model',
+            spec.model,
+            '--effort',
+            spec.effort,
+            '--max-budget-usd',
+            String(maxBudgetUsd),
+            '--no-session-persistence',
+            // Neither prompt is an argv value: on Windows, `claude` resolves to a .cmd shim, and
+            // cmd.exe truncates a multi-line argument at its first newline before the program sees
+            // the remainder. The system prompt stays a system prompt via the CLI's file option;
+            // `claude -p` reads the user prompt from stdin when no positional prompt is given.
+        ];
+        assertSingleLineArguments('claude', args);
+        const filesRead = new Set();
+        let resultEnvelope = null;
+        let lastStopReason = null;
+        let stderrTail = '';
+        let timedOut = false;
+        let stdinError = null;
+        let stdoutBytes = 0;
+        let stdoutLines = 0;
+        let parsedLines = 0;
+        let unparseableLines = 0;
+        let stdoutFirst = '';
+        let stdoutLast = '';
+        let firstUnparseableLineLength = null;
+        let firstUnparseableLineFirst = '';
+        let firstUnparseableLineLast = '';
+        const typeCounts = new Map();
+        const child = spawnClaude(args, { cwd: sandboxPath });
+        // stdout/stderr are only null when stdio is explicitly configured away from 'pipe' — the
+        // default here, so both are always real streams in practice; the ! just satisfies the type.
+        const stdoutDecoder = new StringDecoder('utf8');
+        const recordStdout = (text) => {
+            if (!text)
+                return;
+            if (stdoutFirst.length < STDOUT_SAMPLE_CHARS) {
+                stdoutFirst += text.slice(0, STDOUT_SAMPLE_CHARS - stdoutFirst.length);
+            }
+            stdoutLast = (stdoutLast + text).slice(-STDOUT_SAMPLE_CHARS);
+        };
+        child.stdout.on('data', (chunk) => {
+            stdoutBytes += chunk.length;
+            recordStdout(stdoutDecoder.write(chunk));
+        });
+        child.stdout.on('end', () => recordStdout(stdoutDecoder.end()));
+        child.stdin.on('error', (error) => {
+            stdinError ??= error;
+            child.kill();
+        });
+        child.stderr.on('data', (chunk) => {
+            stderrTail = (stderrTail + chunk.toString()).slice(-2000);
+        });
+        const rl = createInterface({ input: child.stdout });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, WALL_CLOCK_TIMEOUT_MS);
+        rl.on('line', (line) => {
+            stdoutLines++;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                unparseableLines++;
+                if (firstUnparseableLineLength === null) {
+                    firstUnparseableLineLength = line.length;
+                    firstUnparseableLineFirst = line.slice(0, UNPARSEABLE_LINE_SAMPLE_CHARS);
+                    firstUnparseableLineLast = line.slice(-UNPARSEABLE_LINE_SAMPLE_CHARS);
+                }
+                return; // one bad stream line must not crash or stop parsing the rest of the run
+            }
+            parsedLines++;
+            const typed = event !== null && typeof event === 'object'
+                ? event
+                : {};
+            const eventType = typeof typed.type === 'string' ? typed.type : '(missing)';
+            typeCounts.set(eventType, (typeCounts.get(eventType) ?? 0) + 1);
+            if (eventType === 'result') {
+                resultEnvelope = event;
+            }
+            else if (eventType === 'assistant') {
+                const stopReason = event.message?.stop_reason;
+                if (typeof stopReason === 'string')
+                    lastStopReason = stopReason;
+                const blocks = event.message?.content ?? [];
+                for (const b of blocks) {
+                    if (b.type === 'tool_use' && b.name === 'Read' && b.input?.file_path) {
+                        filesRead.add(normalizeToRepoRelative(b.input.file_path, sandboxPath));
+                    }
+                }
+            }
+        });
+        const exitPromise = new Promise((resolvePromise, reject) => {
+            child.on('error', reject); // e.g. ENOENT — claude isn't installed / not on PATH
+            child.on('close', (code) => resolvePromise(code ?? 1));
+        });
+        try {
+            if (spec.stableText)
+                child.stdin.write(spec.stableText + '\n\n');
+            child.stdin.write(spec.volatileText);
+            child.stdin.end();
+        }
+        catch (error) {
+            stdinError ??= error;
+            child.kill();
+        }
+        const exitCode = await exitPromise;
+        clearTimeout(timer);
+        if (!resultEnvelope && timedOut) {
+            throw new Error(`claude CLI took longer than ${WALL_CLOCK_TIMEOUT_MS / 60_000} minutes and was killed.`);
+        }
+        const capturedStdinError = stdinError;
+        if (!resultEnvelope) {
+            if (capturedStdinError) {
+                throw promptWriteFailure(capturedStdinError);
+            }
+            const plainTextDiagnosis = parsedLines === 0 && unparseableLines > 0
+                ? 'The claude CLI produced plain text, which means it did not receive --output-format stream-json. '
+                : '';
+            const types = [...typeCounts.entries()]
+                .map(([type, count]) => `${gitErrorMessage(type) || '(empty)'}=${count}`)
+                .join(', ') || '(none)';
+            const stdoutSample = stdoutBytes === 0
+                ? '(none)'
+                : `first ${STDOUT_SAMPLE_CHARS} chars=${sampleForError(stdoutFirst)}, last ${STDOUT_SAMPLE_CHARS} chars=${sampleForError(stdoutLast)}`;
+            const capturedUnparseableLineLength = firstUnparseableLineLength;
+            const unparseableSample = capturedUnparseableLineLength === null
+                ? ''
+                : `; first unparseable line: ${capturedUnparseableLineLength} chars, first ${UNPARSEABLE_LINE_SAMPLE_CHARS} chars=${sampleForError(firstUnparseableLineFirst)}, last ${UNPARSEABLE_LINE_SAMPLE_CHARS} chars=${sampleForError(firstUnparseableLineLast)}`;
+            throw new Error(`claude CLI exited (code ${exitCode}) without ever producing a result line — ` +
+                plainTextDiagnosis +
+                `stderr: ${stderrTail ? gitErrorMessage(stderrTail) : '(none)'}; ` +
+                `stdout: ${stdoutLines} line${stdoutLines === 1 ? '' : 's'} (${parsedLines} JSON, ${unparseableLines} unparseable), ${stdoutBytes} bytes; ` +
+                `types: ${types}; raw stdout: ${stdoutSample}${unparseableSample}`);
+        }
+        const envelope = resultEnvelope;
+        if (envelope.terminal_reason === 'budget_exhausted' || envelope.subtype === 'error_max_budget_usd') {
+            throw new Error(`Exceeded the $${maxBudgetUsd.toFixed(2)} budget for this task (spent $${envelope.total_cost_usd.toFixed(4)} before stopping).`);
+        }
+        if (envelope.is_error) {
+            const message = envelope.errors?.length ? envelope.errors.join('; ') : envelope.result;
+            throw new Error(message || 'Unknown claude CLI error');
+        }
+        // A refused turn can still end in a non-error result envelope; its result is empty or partial
+        // text, so it must fail here rather than be returned (or JSON-parsed) as an answer.
+        if (envelope.stop_reason === 'refusal' || lastStopReason === 'refusal') {
+            throw new ModelRefusalError('The model declined this request.');
+        }
+        if (capturedStdinError) {
+            throw promptWriteFailure(capturedStdinError);
+        }
+        // Only a schema-constrained call has JSON to parse in the first place — design_prompt sends
+        // no --json-schema (see its own comment in cli.ts/api-key-caller.ts: it's the one task kind
+        // with a free-text markdown answer, never JSON), so envelope.result there is already the
+        // raw text answer; JSON.parse-ing it would throw on perfectly valid prose.
+        const result = spec.schema ? (envelope.structured_output ?? JSON.parse(envelope.result)) : envelope.result;
+        return { result, filesRead: [...filesRead] };
+    }
+    finally {
+        if (systemPromptDir)
+            await rm(systemPromptDir, { recursive: true, force: true });
+    }
+}
+/** The CLI is only a structured-output model transport for investigations. It gets no tools and
+ * no repository directory; all evidence reads happen in investigation-reader.ts first. */
+export async function runStructuredModelCallViaCli(request) {
+    const { result } = await runViaCli({
+        kind: 'investigation',
+        model: request.model,
+        effort: request.effort,
+        maxTokens: request.maxTokens,
+        system: request.system,
+        stableText: '',
+        volatileText: request.prompt,
+        schema: request.schema,
+    }, INVESTIGATION_CALL_BUDGET_USD, process.cwd(), true);
+    return result;
+}
+/** Forward-compatible fallback for server-created graph/spec reasoning tasks. The server sends
+ *  the complete self-describing spec, so these calls run connectionless with zero tools. */
+export async function runGenericTaskViaCli(task, repoPath) {
+    const spec = task.payload?.spec;
+    if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+        throw new Error(`Cannot run task kind "${task.kind}": payload.spec is missing or not an object.`);
+    }
+    return runViaCli(spec, task.maxBudgetUsd, repoPath, true);
+}
+export async function runVerifyModuleTaskViaCli(task, repoPath) {
+    const payload = task.payload;
+    return runViaCli(payload.spec, task.maxBudgetUsd, repoPath);
+}
+/** moduleIds isn't needed here the way api-key-caller.ts's batch path needs it (to structure its
+ *  own file-select pass) — spec.volatileText already names every module in the batch. */
+export async function runGenerateSpecBatchTaskViaCli(task, repoPath) {
+    const payload = task.payload;
+    return runViaCli(payload.spec, task.maxBudgetUsd, repoPath, payload.connectionless);
+}
+/** propose_skeleton and propose_new_capabilities are "shallow whole-repo" tasks (see
+ *  api-key-caller.ts's own comment on the pair). Repo-scoped calls let the model explore via
+ *  --add-dir plus Read/Grep/Glob; a connection-less skeleton call has no repo to explore. */
+export async function runProposeSkeletonTaskViaCli(task, repoPath) {
+    const payload = task.payload;
+    return runViaCli(payload.spec, task.maxBudgetUsd, repoPath, payload.connectionless);
+}
+export async function runProposeNewCapabilitiesTaskViaCli(task, repoPath) {
+    const payload = task.payload;
+    return runViaCli(payload.spec, task.maxBudgetUsd, repoPath);
+}
+/** design_prompt sends no schema (see runViaCli's own comment above on why that matters for
+ *  parsing) — otherwise exactly as thin as the other "let the CLI explore itself" wrappers. */
+export async function runDesignPromptTaskViaCli(task, repoPath) {
+    const payload = task.payload;
+    return runViaCli(payload.spec, task.maxBudgetUsd, repoPath);
+}
+/**
+ * NOT a thin runViaCli wrapper, unlike every kind above — this is the one task kind where even
+ * the CLI backend can't let the model explore for itself: `--restricted --tools "Read,Grep,Glob"`
+ * gives it no Bash/git tool to run `git show` with, so reading the commit has to happen in this
+ * package's own trusted code first (prepareShipmentAnalysis, shipment.ts — shared with
+ * api-key-caller.ts's own runAnalyseShipmentTask), with the diff embedded into the prompt before
+ * runViaCli is ever called. A trivial/sha_not_local outcome resolves without invoking the CLI at
+ * all — same as the api-key backend's own short-circuit, see that function's own comment. */
+export async function runAnalyseShipmentTaskViaCli(task, repoPath) {
+    const payload = task.payload;
+    const prep = await prepareShipmentAnalysis(repoPath, payload.sha);
+    if (prep.outcome === 'sha_not_local') {
+        throw new Error(`sha_not_local: commit ${payload.sha} was not found in the local checkout at ${repoPath}, even after a git fetch.`);
+    }
+    if (prep.outcome === 'trivial') {
+        return { result: { touched: [], possibleNewModules: [] }, filesRead: [] };
+    }
+    const spec = appendDiffToVolatile(payload.spec, prep.diffText, prep.changedPaths);
+    return runViaCli(spec, task.maxBudgetUsd, repoPath);
+}

package/dist/cli-arguments.js

@@ -0,0 +1,11 @@
+export function assertSingleLineArguments(command, args) {
+    for (const [index, argument] of args.entries()) {
+        if (!/[\r\n]/.test(argument))
+            continue;
+        const flag = index > 0 && args[index - 1].startsWith('-')
+            ? args[index - 1]
+            : `argument ${index + 1}`;
+        throw new Error(`${command} CLI argument for ${flag} contains a newline; refusing to spawn because ` +
+            'cmd.exe silently truncates .cmd arguments at the first newline.');
+    }
+}