onto-mcp 0.4.6 → 0.4.7

package/dist/core-runtime/cli/submit-salvage.js

@@ -0,0 +1,115 @@
+/**
+ * Submit salvage recovery — pure decision/merge logic (no I/O, no LLM calls).
+ *
+ * After a structured-submit unit exhausts its regular retries with
+ * `output_contract`, the executor can be re-invoked in salvage mode to
+ * recover the already-produced semantics without re-engaging the violating
+ * model. This module owns the parts that must be deterministic and
+ * unit-testable: failure-mode classification, prompt construction, the
+ * invention guard sentinel, and the missing-rows merge. The LLM calls and
+ * file I/O stay in the executor; validation/serialization stay in
+ * worker-structured-output (same validator as self-submitted payloads).
+ *
+ * Design: development-records/design/submit-salvage-recovery-design.md.
+ */
+/** Invention guard: the transcription model must answer this when the frozen
+ * text lacks required content instead of inventing it. */
+export const SALVAGE_INCOMPLETE_SENTINEL = "SALVAGE_INCOMPLETE";
+/** Frozen-input sidecar path for a unit seat (runtime-owned scratch, not the seat). */
+export function salvageInputPathFor(outputPath) {
+    return `${outputPath}.salvage-input.json`;
+}
+const MISSING_STANCE_ROWS_PATTERN = /submit_issue_stance_response is missing issue_id\(s\): (.+)$/m;
+/**
+ * Classify the recovery path from the frozen failure.
+ *
+ * - S2 (partial submit, measured case): the payload exists and the validator
+ *   named the missing stance rows -> bounded delta completion by a fresh
+ *   same-tier instance (`delta_rows`). v1 covers issue-stance-response only —
+ *   the other formats are single-object submissions without a row dimension.
+ * - S1-prose / S3 (no payload, or field-level violations) -> transcription by
+ *   the cheap model (`transcription`), guarded by the incompleteness sentinel.
+ * - No payload AND no usable text -> unsalvageable (the regular failure
+ *   stands; salvage never invents content).
+ */
+export function classifySalvageMode(args) {
+    if (args.payload !== null) {
+        const missing = MISSING_STANCE_ROWS_PATTERN.exec(args.error);
+        if (missing?.[1] && args.outputFormat === "issue-stance-response") {
+            const missingIssueIds = missing[1]
+                .split(",")
+                .map((id) => id.trim())
+                .filter((id) => id.length > 0);
+            if (missingIssueIds.length > 0)
+                return { mode: "delta_rows", missingIssueIds };
+        }
+        return { mode: "transcription" };
+    }
+    if (args.resultText !== null && args.resultText.trim().length > 0) {
+        return { mode: "transcription" };
+    }
+    return {
+        mode: "unsalvageable",
+        reason: "frozen attempt has neither a structured payload nor result text",
+    };
+}
+/**
+ * Merge delta stance rows into the partial payload. The partial payload's
+ * rows win on duplicate issue_id (first-wins — the original model's accepted
+ * semantics stay authoritative; the delta only fills the named gaps).
+ */
+export function mergeMissingStanceRows(partial, delta) {
+    const partialRows = Array.isArray(partial.stances) ? partial.stances : [];
+    const deltaRows = Array.isArray(delta.stances) ? delta.stances : [];
+    const seen = new Set(partialRows
+        .map((row) => typeof row?.issue_id === "string"
+        ? row.issue_id
+        : null)
+        .filter((id) => id !== null));
+    const merged = [
+        ...partialRows,
+        ...deltaRows.filter((row) => {
+            const issueId = row?.issue_id;
+            return typeof issueId === "string" && !seen.has(issueId);
+        }),
+    ];
+    return { ...partial, stances: merged };
+}
+/**
+ * Path A prompt — transcription only. The salvage model gets the frozen text
+ * (and the validator error when one exists) and must transcribe, never
+ * author: missing required content aborts via the sentinel.
+ */
+export function buildTranscriptionSalvagePrompt(args) {
+    return [
+        "You are a transcription-only recovery worker. A previous worker produced",
+        "the review content below but failed the structured submission contract.",
+        "Transcribe that content into the required submission EXACTLY as written —",
+        "do NOT add, infer, or repair any semantic content that is not present in",
+        "the text. If any REQUIRED field's content is absent from the text, reply",
+        `with exactly ${SALVAGE_INCOMPLETE_SENTINEL} and nothing else.`,
+        "",
+        `Original submission error: ${args.error}`,
+        "",
+        "--- FROZEN WORKER OUTPUT (transcribe from this only) ---",
+        args.resultText,
+        "--- END FROZEN WORKER OUTPUT ---",
+    ].join("\n");
+}
+/**
+ * Path B prompt — bounded delta completion. A fresh same-tier instance gets
+ * the original unit packet (full semantic grounding) and must produce ONLY
+ * the named missing rows; the runtime merges and re-validates.
+ */
+export function buildDeltaRowsSalvagePrompt(args) {
+    return [
+        args.boundedPrompt,
+        "",
+        "--- SALVAGE ADDENDUM (bounded delta completion) ---",
+        "A previous submission for this unit was accepted except that it is",
+        `missing the row(s) for: ${args.missingIssueIds.join(", ")}.`,
+        "Submit a payload whose `stances` contains ONLY the missing row(s) listed",
+        "above — do not restate rows for any other issue. Every other contract in",
+        "the packet (schema, evidence boundaries, lens identity) applies unchanged.",
+    ].join("\n");
+}

package/dist/core-runtime/cli/worker-structured-output.js

@@ -0,0 +1,266 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createLensSidecarSubmissionTools, } from "./lens-sidecar-tools.js";
+import { createRuntimeSubmitTools, isRuntimeSubmitOutputFormat, } from "./structured-output-tools.js";
+import { parseRuntimeSubmitContextForOutputFormat } from "./runtime-submit-context.js";
+import { writeYamlDocument } from "../review/review-artifact-utils.js";
+import { writeValidatedLensSidecarArtifact } from "../review/lens-sidecar-artifact.js";
+export function requireString(value, optionName) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Missing required option --${optionName}`);
+    }
+    return value;
+}
+export function parseOutputFormat(raw) {
+    if (raw === undefined || raw === "" || raw === "markdown")
+        return "markdown";
+    if (typeof raw === "string" && isRuntimeSubmitOutputFormat(raw))
+        return raw;
+    if (raw === "lens-sidecar")
+        return raw;
+    throw new Error(`Invalid --output-format value for review worker: ${String(raw)} (expected markdown | lens-sidecar | issue-artifact | issue-stance-response | issue-deliberation-response | deliberation-resolution | issue-synthesis-response)`);
+}
+export function submitToolNameForOutputFormat(outputFormat) {
+    if (outputFormat === "lens-sidecar")
+        return "submit_lens_findings";
+    switch (outputFormat) {
+        case "issue-artifact":
+            return "submit_issue_artifact";
+        case "issue-stance-response":
+            return "submit_issue_stance_response";
+        case "issue-deliberation-response":
+            return "submit_issue_deliberation_response";
+        case "deliberation-resolution":
+            return "submit_deliberation_resolution";
+        case "issue-synthesis-response":
+            return "submit_issue_synthesis_response";
+    }
+}
+export function buildStructuredOutputPrompt(args) {
+    const submitToolName = submitToolNameForOutputFormat(args.outputFormat);
+    return `You are executing one bounded review structured-output unit as a ContextIsolatedReasoningUnit.
+
+Unit id: ${args.unitId}
+Unit kind: ${args.unitKind}
+Output format: ${args.outputFormat}
+Authoritative prompt packet path: ${args.packetPath}
+Canonical YAML output path: ${args.outputPath}
+
+Rules:
+- Treat the prompt packet below as the authoritative contract.
+- Treat the Boundary Policy and Effective Boundary State in the packet as hard constraints.
+- Read the files referenced by the prompt packet when needed.
+- Stay within the smallest sufficient file set implied by the packet.
+- Do not recursively follow reference chains beyond the files explicitly listed in the packet unless the packet requires it.
+- Do not use web research when the packet says web research is denied.
+- Do not read outside the allowed filesystem scope described in the packet.
+- Do not modify repository files yourself.
+- Produce only one JSON object matching the provided output schema.
+- The JSON object is the argument payload for ${submitToolName}.
+- Do not wrap the JSON object in markdown or code fences.
+- Do not include runtime-owned envelope fields such as schema_version, session_id, lens_id, issue_id, or validation unless the output schema explicitly requires them.
+- The runtime will validate the JSON object through the submit contract and write the canonical YAML artifact.
+- If the packet asks you to preserve disagreement or uncertainty, preserve it explicitly in the structured fields.
+- If you cannot complete the task within the declared boundary, encode the limitation as insufficient access or insufficient evidence within boundary instead of broadening the search.
+
+Authoritative prompt packet follows:
+
+${args.packetText}
+`;
+}
+export function buildBoundedPrompt(packetPath, packetText, outputPath, unitId, unitKind, outputFormat) {
+    if (outputFormat !== "markdown") {
+        return buildStructuredOutputPrompt({
+            packetPath,
+            packetText,
+            outputPath,
+            unitId,
+            unitKind,
+            outputFormat,
+        });
+    }
+    return `You are executing a single bounded review unit as a ContextIsolatedReasoningUnit.
+
+Unit id: ${unitId}
+Unit kind: ${unitKind}
+Authoritative prompt packet path: ${packetPath}
+Canonical output path: ${outputPath}
+
+Rules:
+- Treat the prompt packet below as the authoritative contract.
+- Treat the Boundary Policy and Effective Boundary State in the packet as hard constraints.
+- Read the files referenced by the prompt packet when needed.
+- Stay within the smallest sufficient file set implied by the packet.
+- Do not recursively follow reference chains beyond the files explicitly listed in the packet unless the packet requires it.
+- Do not use web research when the packet says web research is denied.
+- Do not read outside the allowed filesystem scope described in the packet.
+- Produce only the final markdown content for the canonical output path.
+- Do not wrap the answer in code fences.
+- Do not add commentary before or after the markdown.
+- Do not modify repository files yourself.
+- Do not change the required output structure from the packet.
+- If the packet asks you to preserve disagreement or uncertainty, preserve it explicitly.
+- If you cannot complete the task within the declared boundary, preserve that limitation explicitly as insufficient access or insufficient evidence within boundary instead of broadening the search.
+
+Authoritative prompt packet follows:
+
+${packetText}
+`;
+}
+function requireRecord(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object.`);
+    }
+    return value;
+}
+/**
+ * Normalize a JSON Schema into the strict shape external workers require: every
+ * object's properties become `required`. Mirrors what the Codex `--output-schema`
+ * and Claude `--json-schema` flags expect for structured output.
+ */
+export function toWorkerStructuredOutputSchema(schema) {
+    if (Array.isArray(schema)) {
+        return schema.map((item) => toWorkerStructuredOutputSchema(item));
+    }
+    if (!schema || typeof schema !== "object") {
+        return schema;
+    }
+    const normalized = {};
+    for (const [key, value] of Object.entries(schema)) {
+        normalized[key] = toWorkerStructuredOutputSchema(value);
+    }
+    const properties = normalized.properties;
+    if (properties && typeof properties === "object" && !Array.isArray(properties)) {
+        normalized.required = Object.keys(properties);
+    }
+    return normalized;
+}
+/**
+ * Build the submit-tool JSON Schema and the submission state for an output
+ * format, without writing any file. Codex writes this to disk for its
+ * `--output-schema` flag; Claude Code embeds it in the prompt instead.
+ */
+export function buildWorkerSubmitSchema(args) {
+    return args.outputFormat === "lens-sidecar"
+        ? (() => {
+            const lensSidecarState = {
+                sessionId: args.sessionId,
+                lensId: args.unitId,
+                humanOutputRef: args.humanOutputRef ?? null,
+            };
+            const [submitTool] = createLensSidecarSubmissionTools(lensSidecarState);
+            if (!submitTool) {
+                throw new Error("No lens sidecar submit tool for worker structured output.");
+            }
+            return {
+                state: {
+                    outputFormat: "lens-sidecar",
+                    submitToolName: "submit_lens_findings",
+                    lensSidecarState,
+                },
+                schema: toWorkerStructuredOutputSchema(submitTool.input_schema),
+            };
+        })()
+        : (() => {
+            const runtimeSubmitState = {
+                sessionId: args.sessionId,
+                unitId: args.unitId,
+                outputFormat: args.outputFormat,
+                ...parseRuntimeSubmitContextForOutputFormat({
+                    rawPacketText: args.rawPacketText,
+                    unitId: args.unitId,
+                    outputFormat: args.outputFormat,
+                }),
+            };
+            const [submitTool] = createRuntimeSubmitTools(runtimeSubmitState);
+            if (!submitTool) {
+                throw new Error(`No runtime submit tool for output format ${args.outputFormat}.`);
+            }
+            return {
+                state: {
+                    outputFormat: args.outputFormat,
+                    submitToolName: submitTool.name,
+                    runtimeSubmitState,
+                },
+                schema: toWorkerStructuredOutputSchema(submitTool.input_schema),
+            };
+        })();
+}
+/**
+ * Build the submit schema and write it to `<rawOutputPath>.schema.json` for
+ * workers that consume a schema file on disk (Codex `--output-schema`).
+ */
+export async function writeOutputSchemaFile(args) {
+    const { schema, state } = buildWorkerSubmitSchema({
+        outputFormat: args.outputFormat,
+        unitId: args.unitId,
+        sessionId: args.sessionId,
+        rawPacketText: args.rawPacketText,
+        humanOutputRef: args.humanOutputRef ?? null,
+    });
+    const schemaPath = `${args.rawOutputPath}.schema.json`;
+    await fs.mkdir(path.dirname(args.rawOutputPath), { recursive: true });
+    await fs.writeFile(schemaPath, `${JSON.stringify(schema, null, 2)}\n`, "utf8");
+    return { schemaPath, state };
+}
+export function stripWrappingCodeFence(text) {
+    const trimmed = text.trim();
+    const match = trimmed.match(/^```(?:json)?\s*\n([\s\S]*?)\n```$/);
+    return match ? match[1].trim() : trimmed;
+}
+/**
+ * Parse and validate a worker's raw structured output text into a submit-tool
+ * payload object. Rejects the legacy `payload_json` wrapper. The raw text may be
+ * fenced; it is unwrapped first.
+ */
+export function coerceStructuredPayload(rawText, label) {
+    const raw = stripWrappingCodeFence(rawText);
+    try {
+        const payload = requireRecord(JSON.parse(raw), label);
+        if (Object.prototype.hasOwnProperty.call(payload, "payload_json")) {
+            throw new Error("payload_json wrapper is no longer accepted; structured output must be the submit payload object.");
+        }
+        return payload;
+    }
+    catch (error) {
+        throw new Error(`Failed to parse worker structured output JSON: ${label}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export async function writeRuntimeSubmitArtifactFromPayload(args) {
+    const [submitTool] = createRuntimeSubmitTools(args.state);
+    if (!submitTool) {
+        throw new Error(`No runtime submit tool for output format ${args.state.outputFormat}.`);
+    }
+    await submitTool.execute(args.payload, {
+        projectRoot: "",
+        ontoHome: "",
+    });
+    if (args.state.artifact === undefined) {
+        throw new Error(`${args.state.outputFormat} mode completed without ${submitTool.name} for unit ${args.state.unitId}.`);
+    }
+    await writeYamlDocument(args.outputPath, args.state.artifact);
+    return Object.keys(args.payload).length;
+}
+export async function writeLensSidecarArtifactFromPayload(args) {
+    const [submitTool] = createLensSidecarSubmissionTools(args.state);
+    if (!submitTool) {
+        throw new Error("No lens sidecar submit tool for worker structured output.");
+    }
+    await submitTool.execute(args.payload, {
+        projectRoot: "",
+        ontoHome: "",
+    });
+    if (args.state.artifact === undefined) {
+        throw new Error(`lens-sidecar mode completed without ${submitTool.name} for unit ${args.state.lensId}.`);
+    }
+    await writeValidatedLensSidecarArtifact({
+        sidecarPath: args.outputPath,
+        artifact: args.state.artifact,
+        sessionId: args.state.sessionId,
+        lensId: args.state.lensId,
+        ...(args.state.humanOutputRef !== undefined
+            ? { expectedHumanOutputRef: args.state.humanOutputRef }
+            : {}),
+    });
+    return Object.keys(args.payload).length;
+}

package/dist/core-runtime/discovery/host-detection.js

@@ -31,3 +31,40 @@ export function detectCodexBinaryAvailable() {
         return false;
     return fsSync.existsSync(path.join(os.homedir(), ".codex", "auth.json"));
 }
+/** OAuth credential filenames Claude Code may write under its config dir. */
+const CLAUDE_OAUTH_CREDENTIAL_FILENAMES = [
+    ".credentials.json",
+    ".oauth-token",
+];
+function claudeConfigDir() {
+    const configured = process.env.CLAUDE_CONFIG_DIR;
+    if (typeof configured === "string" && configured.trim().length > 0) {
+        return configured.trim();
+    }
+    return path.join(os.homedir(), ".claude");
+}
+/**
+ * True when the Claude Code worker path can be used from this process.
+ *
+ * Mirrors {@link detectCodexBinaryAvailable}: both the executable and an OAuth
+ * credential are required so the external OAuth worker (`claude_code` adapter)
+ * route stays fail-loud when the host-bound worker is unavailable. The config
+ * dir honors CLAUDE_CONFIG_DIR; the credential filename is tolerant of the
+ * known Claude Code variants.
+ */
+export function detectClaudeBinaryAvailable() {
+    const pathEnv = process.env.PATH ?? "";
+    let claudeOnPath = false;
+    for (const dir of pathEnv.split(path.delimiter)) {
+        if (!dir)
+            continue;
+        if (fsSync.existsSync(path.join(dir, "claude"))) {
+            claudeOnPath = true;
+            break;
+        }
+    }
+    if (!claudeOnPath)
+        return false;
+    const configDir = claudeConfigDir();
+    return CLAUDE_OAUTH_CREDENTIAL_FILENAMES.some((name) => fsSync.existsSync(path.join(configDir, name)));
+}