@juzser/blacksmith 0.1.0 → 0.2.0

package/factory/orchestrator/dist/providers/api-transport.js

@@ -7,6 +7,12 @@ import { extractAndValidate } from './schema-validate.js';
 import { ProviderError } from './types.js';
 const NUDGE = '\n\nReturn only valid JSON per schema.';
 const RESPONSE_BODY_ERROR_SNIPPET_LIMIT = 500;
+// Raw answer kept on a rejected verdict: enough head to see what the model
+// started writing, enough tail to see where it stopped. A truncated JSON
+// answer and a prose answer look alike in a bare `no-json-found`.
+const CONTENT_SNIPPET_HEAD = 300;
+const CONTENT_SNIPPET_TAIL = 200;
+const CONTENT_SNIPPET_JOINER = ' … ';
 function resolveApiKey(config, provider) {
     const key = process.env[config.apiKeyEnv];
     if (!key) {
@@ -14,9 +20,31 @@ function resolveApiKey(config, provider) {
     }
     return key;
 }
+/**
+ * The raw answer as it may appear in an error: the API key scrubbed the same
+ * way a non-OK body is, and bounded to head + tail so a 64K truncation shows
+ * its last bytes instead of nothing.
+ */
+function contentSnippet(content, apiKey) {
+    const scrubbed = content.split(apiKey).join('[REDACTED]');
+    if (scrubbed.length <= CONTENT_SNIPPET_HEAD + CONTENT_SNIPPET_TAIL)
+        return scrubbed;
+    return `${scrubbed.slice(0, CONTENT_SNIPPET_HEAD)}${CONTENT_SNIPPET_JOINER}${scrubbed.slice(-CONTENT_SNIPPET_TAIL)}`;
+}
+/**
+ * Whether a second call with the nudge appended can change anything. It can
+ * when the model finished on its own (`stop`) — the prompt is the suspect. It
+ * cannot when the model was cut off at `max_tokens`: the same prompt runs to
+ * the same cap and bills the same tokens. An absent finish_reason is read as
+ * `stop` so a provider that omits the field keeps the retry it always had.
+ */
+function nudgeCanHelp(finishReason) {
+    return finishReason === undefined || finishReason === 'stop';
+}
 async function callOnce(provider, config, apiKey, prompt, budget, fetchImpl) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), budget.timeout_ms);
+    const maxTokens = budget.max_output_tokens ?? config.maxTokens;
     let response;
     try {
         response = await fetchImpl(`${config.baseUrl.replace(/\/$/, '')}/chat/completions`, {
@@ -27,6 +55,7 @@ async function callOnce(provider, config, apiKey, prompt, budget, fetchImpl) {
                 messages: [{ role: 'user', content: prompt }],
                 stream: false,
                 ...(config.responseFormatJsonObject ? { response_format: { type: 'json_object' } } : {}),
+                ...(maxTokens === undefined ? {} : { max_tokens: maxTokens }),
             }),
             signal: controller.signal,
         });
@@ -65,13 +94,39 @@ async function callOnce(provider, config, apiKey, prompt, budget, fetchImpl) {
     catch {
         throw new ProviderError('provider.malformed-response', `Provider "${provider}" API judge response was not valid JSON.`, { provider });
     }
-    const content = parsed.choices?.[0]?.message?.content ?? '';
+    const choice = parsed.choices?.[0];
+    const content = choice?.message?.content ?? '';
     return {
         content,
         usage: parsed.usage
             ? { input_tokens: parsed.usage.prompt_tokens, output_tokens: parsed.usage.completion_tokens }
             : undefined,
+        finishReason: typeof choice?.finish_reason === 'string' ? choice.finish_reason : undefined,
+    };
+}
+/**
+ * The error for an answer that never validated. Two codes, because the two
+ * situations are fixed in different places: `output-truncated` (the model
+ * stopped at the cap mid-answer) is fixed by a cap or a shorter prompt;
+ * `invalid-output` (the model finished and still did not answer the schema)
+ * is fixed at the prompt. Both carry the raw answer, scrubbed and bounded, so
+ * the operator can tell the two apart in the log instead of guessing from a
+ * reason string.
+ */
+function rejectedAnswerError(provider, apiKey, call, result, retried) {
+    const details = {
+        provider,
+        reason: result.reason,
+        errors: result.errors,
+        finish_reason: call.finishReason,
+        content_length: call.content.length,
+        content_snippet: contentSnippet(call.content, apiKey),
+        retried,
     };
+    if (call.finishReason === 'length') {
+        return new ProviderError('provider.output-truncated', `Provider "${provider}" API judge stopped at its output cap (finish_reason "length") after ${call.content.length} characters, before the answer closed; not retried. Raise max_tokens for the provider (crosscheck.yml) or --max-output-tokens, or shorten the prompt.`, details);
+    }
+    return new ProviderError('provider.invalid-output', `Provider "${provider}" API judge returned invalid output${retried ? ' after one retry' : ''}: ${result.reason}.`, details);
 }
 /**
  * Both attempts, added together — the provider billed both, and this is the
@@ -99,13 +154,15 @@ export async function runApiJudge(provider, config, request, fetchImpl = fetch)
     let call = await callOnce(provider, config, apiKey, request.prompt, request.budget, fetchImpl);
     let usage = call.usage;
     let result = extractAndValidate(call.content, request.schemaName);
-    if (!result.valid) {
+    let retried = false;
+    if (!result.valid && nudgeCanHelp(call.finishReason)) {
         call = await callOnce(provider, config, apiKey, `${request.prompt}${NUDGE}`, request.budget, fetchImpl);
         usage = addUsage(usage, call.usage);
         result = extractAndValidate(call.content, request.schemaName);
-        if (!result.valid) {
-            throw new ProviderError('provider.invalid-output', `Provider "${provider}" API judge returned invalid output after one retry: ${result.reason}.`, { provider, reason: result.reason, errors: 'errors' in result ? result.errors : undefined });
-        }
+        retried = true;
+    }
+    if (!result.valid) {
+        throw rejectedAnswerError(provider, apiKey, call, { reason: result.reason, errors: 'errors' in result ? result.errors : undefined }, retried);
     }
     return {
         provider,

package/factory/orchestrator/dist/providers/cli-transport.js

@@ -3,7 +3,7 @@
 // providers.md). Prompt delivery: STDIN, not a temp file — no filesystem
 // cleanup/race to manage, and a CLI judge that reads a prompt off stdin
 // (same as an interactive paste) needs no extra flag wiring per provider.
-import { spawn } from 'node:child_process';
+import { spawnCapped } from '../spawn.js';
 import { extractAndValidate } from './schema-validate.js';
 import { ProviderError } from './types.js';
 const NUDGE = '\n\nReturn only valid JSON per schema.';
@@ -40,80 +40,14 @@ function diagnosticFor(outcome) {
     return combined === '' ? errOnly : `${errOnly} | ${combined}`;
 }
 /**
- * One CLI judge invocation: detached process group (POSIX `setsid` via
- * `detached: true`) + group-kill on timeout or size-cap breach — mirrors
- * testgate.ts's runOne() exactly (a judge CLI can spawn its own child
- * processes; a plain per-child kill would orphan them the same way
- * testgate's own regression note describes).
+ * One CLI judge invocation via the shared capped spawn (src/spawn.ts). No
+ * `cwd` in the call: a CLI judge transport is handed a prompt and nothing
+ * else — architecture §18 rule 5, "judges never gain write access" — and a
+ * process started with no working directory of its own has no worktree to
+ * write into even if its command line wanted one.
  */
 function spawnOnce(config, prompt, budget) {
-    return new Promise((resolve) => {
-        const child = spawn(config.command, config.args, {
-            detached: true,
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
-        let combined = '';
-        let stderr = '';
-        let totalBytes = 0;
-        let timedOut = false;
-        let sizeExceeded = false;
-        let settled = false;
-        let spawnError;
-        const killGroup = () => {
-            if (child.pid !== undefined) {
-                try {
-                    process.kill(-child.pid, 'SIGKILL');
-                }
-                catch {
-                    // Group already gone — fine.
-                }
-            }
-        };
-        const timer = setTimeout(() => {
-            timedOut = true;
-            killGroup();
-        }, budget.timeout_ms);
-        const onChunk = (chunk) => {
-            totalBytes += chunk.length;
-            if (totalBytes > budget.max_output_bytes) {
-                if (!sizeExceeded) {
-                    sizeExceeded = true;
-                    killGroup();
-                }
-                return;
-            }
-            combined += chunk.toString('utf8');
-        };
-        child.stdout?.on('data', onChunk);
-        child.stderr?.on('data', (chunk) => {
-            // Still folded into `combined` for extraction — a judge that writes its
-            // verdict to stderr has always worked and must keep working. The second
-            // copy exists only so a refusal reason can be reported on its own.
-            stderr += chunk.toString('utf8');
-            onChunk(chunk);
-        });
-        child.stdin?.on('error', () => {
-            // Judge exited before consuming stdin (e.g. a fixture that errors
-            // immediately) — writing to a closed pipe would otherwise raise an
-            // unhandled EPIPE; the close handler below still resolves correctly.
-        });
-        child.stdin?.write(prompt);
-        child.stdin?.end();
-        const finish = (exitCode, signal) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            resolve({ combined, stderr, exitCode, signal, spawnError, timedOut, sizeExceeded });
-        };
-        child.on('error', (err) => {
-            // The child never ran (ENOENT, EACCES, …). Distinct from a child that
-            // ran and failed: 'close' carries no code in this case.
-            spawnError = err;
-            finish(null, null);
-        });
-        child.on('close', finish);
-    });
+    return spawnCapped({ command: config.command, args: config.args }, prompt, budget);
 }
 /**
  * The buffer minus the prompt this process just sent, for the extractor to

package/factory/orchestrator/dist/providers/index.js

@@ -48,6 +48,7 @@ export async function runJudge(providerName, request, opts = {}) {
         model: config.model,
         apiKeyEnv: config.apiKeyEnv,
         responseFormatJsonObject: config.responseFormatJsonObject,
+        ...(config.maxTokens === undefined ? {} : { maxTokens: config.maxTokens }),
     }, request, opts.fetchImpl);
 }
 export { ProviderError } from './types.js';

package/factory/orchestrator/dist/providers/schema-validate.js

@@ -100,20 +100,71 @@ export function extractBalancedJson(text) {
  * array of evidence as a single malformed object.
  */
 const ARRAY_VALUED_SCHEMAS = new Set(['finding', 'finding-evidence']);
+/**
+ * The list a judge answered with for an array-valued schema, or undefined when
+ * it answered with some other shape. A bare array is the list. An object with
+ * exactly one key whose value is an array is the list wrapped — the shape an
+ * API judge under `response_format: json_object` has to produce, because that
+ * mode refuses a top-level array (FD-41; deepseek-chat answered
+ * `{"findings":[...]}` and lost the whole review to `schema-invalid`).
+ * Anything else — a bare record, a wrapper with a second key, a scalar — is
+ * refused: `balancedJsonCandidates` never descends into a value it has
+ * yielded, so this is the only place a wrapped list can be recognised, and it
+ * recognises exactly that one shape rather than searching for an array
+ * somewhere inside the answer.
+ */
+function unwrapArray(parsed) {
+    if (Array.isArray(parsed))
+        return parsed;
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const keys = Object.keys(parsed);
+    if (keys.length !== 1)
+        return undefined;
+    const inner = parsed[keys[0]];
+    return Array.isArray(inner) ? inner : undefined;
+}
+function describeShape(parsed) {
+    if (Array.isArray(parsed))
+        return 'an array';
+    if (parsed === null)
+        return 'null';
+    if (typeof parsed === 'object')
+        return `an object with ${Object.keys(parsed).length} key(s)`;
+    return `a ${typeof parsed}`;
+}
 /**
  * Extract + schema-validate a judge's raw text response. `finding.schema.json`
  * describes ONE finding, but a `kind: review` judge's contract
- * (.claude/agents/reviewer.md) returns an ARRAY of findings — so an array
- * top-level value against an ARRAY_VALUED_SCHEMAS name validates element-wise;
- * every other schema (e.g. "judge-verdict") validates the parsed value
- * directly against its own object shape.
+ * (.claude/agents/reviewer.md) returns an ARRAY of findings — so against an
+ * ARRAY_VALUED_SCHEMAS name the top-level value must be that array, bare or
+ * wrapped in one single-key object (see `unwrapArray`), and validates
+ * element-wise; the value returned is the array itself, unwrapped. A bare
+ * record is refused there even when it would validate on its own: one finding
+ * where a list was asked for is a judge that misread its contract, and
+ * accepting it would file the answer as a review of exactly one issue. Every
+ * other schema (e.g. "judge-verdict") validates the parsed value directly
+ * against its own object shape.
  */
 export function extractAndValidate(rawText, schemaName, opts = {}) {
     const { taxonomy, schemas } = resolve(opts);
     const validateOne = (parsed) => {
-        if (ARRAY_VALUED_SCHEMAS.has(schemaName) && Array.isArray(parsed)) {
+        if (ARRAY_VALUED_SCHEMAS.has(schemaName)) {
+            const items = unwrapArray(parsed);
+            if (items === undefined) {
+                return {
+                    valid: false,
+                    reason: 'schema-invalid',
+                    errors: [
+                        {
+                            path: '',
+                            message: `expected an array of ${schemaName} records (or one object whose single key holds that array); got ${describeShape(parsed)}`,
+                        },
+                    ],
+                };
+            }
             const errors = [];
-            parsed.forEach((item, index) => {
+            items.forEach((item, index) => {
                 const result = validateRecord(schemas, taxonomy, schemaName, item);
                 if (!result.valid) {
                     errors.push(...result.errors.map((e) => ({ path: `/${index}${e.path}`, message: e.message })));
@@ -121,7 +172,7 @@ export function extractAndValidate(rawText, schemaName, opts = {}) {
             });
             if (errors.length > 0)
                 return { valid: false, reason: 'schema-invalid', errors };
-            return { valid: true, value: parsed };
+            return { valid: true, value: items };
         }
         const result = validateRecord(schemas, taxonomy, schemaName, parsed);
         if (!result.valid)

package/factory/orchestrator/dist/providers/types.js

@@ -15,6 +15,11 @@ export const JUDGE_SCHEMA_FAILURE_CODES = new Set([
     'provider.invalid-output',
     'provider.malformed-response',
     'provider.output-too-large',
+    // The provider stopped writing at its output cap (finish_reason `length`)
+    // before the answer closed. The answer is unusable for the same reason a
+    // malformed one is, and the fix is the same side of the wire: a cap that
+    // fits the answer, or a prompt that asks for a shorter one.
+    'provider.output-truncated',
 ]);
 /** Codes raised when no usable answer arrived -- including when no request was sent. */
 export const JUDGE_TRANSPORT_FAILURE_CODES = new Set([

package/factory/orchestrator/dist/roadmap.js

@@ -11,7 +11,7 @@
 // entry (documented as a deviation in ui/docs/DESIGN.md).
 import { readFileSync } from 'node:fs';
 import { SmithError } from './errors.js';
-import { ROADMAP_PATH } from './paths.js';
+import { roadmapReadPath } from './paths.js';
 export class RoadmapError extends SmithError {
 }
 /**
@@ -347,7 +347,7 @@ export function parseRoadmap(markdown) {
  * guard is around the read rather than an existsSync in front of it so a
  * directory, a permission error and a missing file all answer the same way.
  */
-export function readRoadmapText(roadmapPath = ROADMAP_PATH) {
+export function readRoadmapText(roadmapPath = roadmapReadPath()) {
     try {
         return readFileSync(roadmapPath, 'utf8');
     }
@@ -392,7 +392,7 @@ export function roadmapDeclaresId(markdown, id) {
     return false;
 }
 /** Read and parse roadmap.md from disk (defaults to the real repo path). */
-export function loadRoadmap(roadmapPath = ROADMAP_PATH) {
+export function loadRoadmap(roadmapPath = roadmapReadPath()) {
     return parseRoadmap(readRoadmapText(roadmapPath));
 }
 /**

package/factory/orchestrator/dist/run-cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+// smith-run: a separate executable, not a `smith` verb. `smith harness plan`
+// renders a WorkerInvocation and stops there — architecture §18 rule 3,
+// "nothing that observes may dispatch". This program is the only thing in
+// this repo that actually starts one, and it does nothing else: no event
+// log, no state/, no DB (see runner.ts's own header and its source-level
+// test in test/runner.test.ts).
+import { readFileSync, writeFileSync } from 'node:fs';
+import { parseArgs } from './args.js';
+import { runInvocation } from './runner.js';
+const HELP = `Usage: smith-run <invocation.json | -> [--prompt-file <path>] [--timeout-ms <n>] [--out <file>]
+
+Spawns ONE already-rendered worker invocation (the JSON \`smith harness plan\`
+prints) and reports what happened as JSON. This is not \`smith harness run\`:
+\`smith\` only ever renders an invocation and never starts it (§18 rule 3,
+"nothing that observes may dispatch"), so starting the process an invocation
+describes lives in its own binary instead.
+
+Arguments:
+  <invocation.json>     Path to a rendered WorkerInvocation, or "-" for stdin.
+
+Options:
+  --prompt-file <path>  Read the prompt from this file instead of invocation.promptFile.
+  --timeout-ms <n>       Override invocation.budget.timeout_ms for this run.
+  --out <file>           Write the JSON result here instead of stdout.
+  --help                 Show this message.
+
+Exit codes:
+  0  completed (exit 0), answer validated against its schema (or no schema set)
+  1  the harness process failed to start, or exited non-zero, or the harness
+     reported an error in its output
+  2  completed (exit 0), but schema validation failed
+  3  timed out, or exceeded the output size cap
+`;
+const FLAG_SPEC = new Map([
+    ['prompt-file', true],
+    ['timeout-ms', true],
+    ['out', true],
+    ['help', false],
+]);
+function readInvocation(source) {
+    const text = source === '-' ? readFileSync(0, 'utf8') : readFileSync(source, 'utf8');
+    return JSON.parse(text);
+}
+/** See HELP's own exit-code table — kept in one place so the two cannot drift. */
+function exitCodeFor(outcome) {
+    if (outcome.spawnError !== null)
+        return 1;
+    if (outcome.timedOut || outcome.sizeExceeded)
+        return 3;
+    if (outcome.exitCode !== 0)
+        return 1;
+    // The process exited 0, but its own output reported a failure (a codex
+    // top-level `error` event, or claude's `is_error: true`) — only reachable
+    // for a clean exit, since a nonzero exitCode above already returned 1.
+    if (outcome.harness_error !== null)
+        return 1;
+    if (outcome.validation !== null && !outcome.validation.ok)
+        return 2;
+    return 0;
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const parsed = parseArgs(argv, FLAG_SPEC);
+    if (parsed.flags.help === 'true') {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    const source = parsed.positional[0];
+    if (source === undefined) {
+        process.stderr.write('smith-run: missing <invocation.json | -> argument.\n\n');
+        process.stderr.write(HELP);
+        return 1;
+    }
+    let invocation;
+    try {
+        invocation = readInvocation(source);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`smith-run: could not read/parse invocation: ${message}\n`);
+        return 1;
+    }
+    const timeoutOverride = parsed.flags['timeout-ms'];
+    if (timeoutOverride !== undefined && invocation.kind === 'cli') {
+        const timeout_ms = Number.parseInt(timeoutOverride, 10);
+        if (Number.isNaN(timeout_ms)) {
+            process.stderr.write(`smith-run: --timeout-ms must be a number, got "${timeoutOverride}".\n`);
+            return 1;
+        }
+        invocation = { ...invocation, budget: { ...invocation.budget, timeout_ms } };
+    }
+    const opts = {};
+    const promptFile = parsed.flags['prompt-file'];
+    if (promptFile !== undefined) {
+        try {
+            opts.promptText = readFileSync(promptFile, 'utf8');
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`smith-run: could not read --prompt-file: ${message}\n`);
+            return 1;
+        }
+    }
+    let outcome;
+    try {
+        outcome = await runInvocation(invocation, opts);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`smith-run: ${message}\n`);
+        return 1;
+    }
+    const json = `${JSON.stringify(outcome, null, 2)}\n`;
+    const outFile = parsed.flags.out;
+    if (outFile !== undefined) {
+        writeFileSync(outFile, json);
+    }
+    else {
+        process.stdout.write(json);
+    }
+    return exitCodeFor(outcome);
+}
+main().then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    const message = err instanceof Error ? (err.stack ?? err.message) : String(err);
+    process.stderr.write(`smith-run: unexpected error: ${message}\n`);
+    process.exitCode = 1;
+});