@inflexa-ai/harness 0.4.2 → 0.4.4

package/dist/app/synthesize-run.d.ts

@@ -22,6 +22,7 @@ import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
 import type { RunFinding } from "../workflows/execute-analysis.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
+import type { SynthesisStatus } from "../state/index.js";
 import type { Logger } from "../lib/logger.js";
 export interface SynthesizeRunDeps {
     /** Operational logging seam; omitted falls back to no-op. */
@@ -40,7 +41,6 @@ export interface SynthesizeRunDeps {
 /** Optional fields for a progress update, mirroring the wire part. */
 export interface SynthesisProgressExtra {
     readonly delegationCount?: number;
-    readonly validationAttempts?: number;
     readonly reason?: string;
     readonly error?: string;
 }
@@ -56,5 +56,7 @@ export interface SynthesizeRunParams {
 }
 export interface SynthesizeRunResult {
     readonly findings: readonly RunFinding[];
+    readonly synthesisStatus: Exclude<SynthesisStatus, "failed">;
+    readonly synthesisReason: string | null;
 }
 export declare function synthesizeRun(deps: SynthesizeRunDeps, params: SynthesizeRunParams): Promise<SynthesizeRunResult>;

package/dist/app/synthesize-run.js

@@ -33,10 +33,12 @@ export async function synthesizeRun(deps, params) {
             completedSteps,
         });
         if (summaries.length === 0) {
+            const logger = (deps.logger ?? createNoopLogger()).named("synthesize-run");
+            logger.warn("synthesis skipped — no step summaries on disk", { runId, reason: "no-summaries" });
             await onProgress("skipped", "No step summaries available for synthesis", {
                 reason: "no-summaries",
             });
-            return { findings: [] };
+            return { findings: [], synthesisStatus: "skipped_no_summaries", synthesisReason: "no-summaries" };
         }
         const planNarrative = await loadPlanNarrative(pool, runId, analysisId);
         const synthesizerSession = forSubAgent(session, "run-synthesizer");
@@ -51,8 +53,15 @@ export async function synthesizeRun(deps, params) {
             emit,
         });
         if (result.kind === "skipped") {
-            await onProgress("skipped", "Synthesis skipped — run did not produce synthesizable content", { reason: result.reason });
-            return { findings: [] };
+            const logger = (deps.logger ?? createNoopLogger()).named("synthesize-run");
+            logger.warn("synthesis skipped — synthesizer reported a blocker", {
+                runId,
+                reason: result.reason,
+            });
+            await onProgress("skipped", "Synthesis skipped — run did not produce synthesizable content", {
+                reason: result.reason,
+            });
+            return { findings: [], synthesisStatus: "skipped_blocker", synthesisReason: result.reason };
         }
         const synthesis = result.synthesis;
         await onProgress("indexing", "Indexing synthesis for search");
@@ -84,6 +93,8 @@ export async function synthesizeRun(deps, params) {
                 title: f.title,
                 confidence: f.confidence,
             })),
+            synthesisStatus: "produced",
+            synthesisReason: null,
         };
     }
     catch (err) {

package/dist/contracts/chat-parts.d.ts

@@ -262,8 +262,6 @@ export interface SynthesisProgressPart {
     activity: string;
     /** Number of literature-reviewer delegations started so far. */
     delegationCount?: number;
-    /** Number of times the synthesizer's submit_synthesis call was rejected. */
-    validationAttempts?: number;
     /** Agent-provided reason — set when phase === "skipped". */
     reason?: string;
     /** Error message — set when phase === "failed". */

package/dist/contracts/schemas/chat-parts.d.ts

@@ -298,11 +298,11 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
         low: "low";
     }>;
     noveltyStatus: z.ZodEnum<{
+        expected: "expected";
         novel: "novel";
         confirmed: "confirmed";
         partially_confirmed: "partially_confirmed";
         contradicted: "contradicted";
-        expected: "expected";
     }>;
     literatureInterpretation: z.ZodString;
 }, z.core.$strip>;
@@ -330,11 +330,11 @@ export declare const RunSynthesisPartSchema: z.ZodObject<{
             low: "low";
         }>;
         noveltyStatus: z.ZodEnum<{
+            expected: "expected";
             novel: "novel";
             confirmed: "confirmed";
             partially_confirmed: "partially_confirmed";
             contradicted: "contradicted";
-            expected: "expected";
         }>;
         literatureInterpretation: z.ZodString;
     }, z.core.$strip>>;
@@ -383,7 +383,6 @@ export declare const SynthesisProgressPartSchema: z.ZodObject<{
     }>;
     activity: z.ZodString;
     delegationCount: z.ZodOptional<z.ZodNumber>;
-    validationAttempts: z.ZodOptional<z.ZodNumber>;
     reason: z.ZodOptional<z.ZodString>;
     error: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -589,11 +588,11 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
             low: "low";
         }>;
         noveltyStatus: z.ZodEnum<{
+            expected: "expected";
             novel: "novel";
             confirmed: "confirmed";
             partially_confirmed: "partially_confirmed";
             contradicted: "contradicted";
-            expected: "expected";
         }>;
         literatureInterpretation: z.ZodString;
     }, z.core.$strip>>;
@@ -629,7 +628,6 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     }>;
     activity: z.ZodString;
     delegationCount: z.ZodOptional<z.ZodNumber>;
-    validationAttempts: z.ZodOptional<z.ZodNumber>;
     reason: z.ZodOptional<z.ZodString>;
     error: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{

package/dist/contracts/schemas/chat-parts.js

@@ -243,7 +243,6 @@ export const SynthesisProgressPartSchema = z.object({
     phase: SynthesisPhaseSchema,
     activity: z.string(),
     delegationCount: z.number().int().nonnegative().optional(),
-    validationAttempts: z.number().int().nonnegative().optional(),
     reason: z.string().optional(),
     error: z.string().optional(),
 });

package/dist/execution/run-synthesis.d.ts

@@ -1,9 +1,14 @@
 /**
  * Run synthesizer — a single-shot agent loop driven through `runAgent`:
  *
+ *   - `validate_synthesis` — non-terminal: dry-run schema + semantic validation
+ *                            of a candidate in any shape. Never records.
  *   - `submit_synthesis`  — terminal: schema + semantic validation, captures
- *                            the outcome. Re-callable on rejection.
+ *                            the outcome. Re-callable; a later valid submission
+ *                            supersedes an earlier outcome (last-valid-wins).
  *   - `report_blocker`    — terminal: the run produced nothing synthesizable.
+ *                            Only records when no outcome exists yet, so a
+ *                            blocker can never clobber a real synthesis.
  *   - `literature_reviewer` — research sub-agent exposed as a tool. The tool
  *                            re-uses `createLiteratureReviewerTool`; the
  *                            sub-agent loop's brief is the only context handed
@@ -43,6 +48,7 @@ export declare function __buildInnerToolsForTest(args: {
     knownStepIds: ReadonlySet<string>;
     runId: string;
 }): {
+    validate: Tool;
     submit: Tool;
     blocker: Tool;
     holder: OutcomeHolder;

package/dist/execution/run-synthesis.js

@@ -1,9 +1,14 @@
 /**
  * Run synthesizer — a single-shot agent loop driven through `runAgent`:
  *
+ *   - `validate_synthesis` — non-terminal: dry-run schema + semantic validation
+ *                            of a candidate in any shape. Never records.
  *   - `submit_synthesis`  — terminal: schema + semantic validation, captures
- *                            the outcome. Re-callable on rejection.
+ *                            the outcome. Re-callable; a later valid submission
+ *                            supersedes an earlier outcome (last-valid-wins).
  *   - `report_blocker`    — terminal: the run produced nothing synthesizable.
+ *                            Only records when no outcome exists yet, so a
+ *                            blocker can never clobber a real synthesis.
  *   - `literature_reviewer` — research sub-agent exposed as a tool. The tool
  *                            re-uses `createLiteratureReviewerTool`; the
  *                            sub-agent loop's brief is the only context handed
@@ -23,7 +28,8 @@ import { join } from "node:path";
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { writeFileWithinRoot } from "../lib/fs-helpers.js";
-import { RunSynthesisSchema } from "../schemas/run-synthesis.js";
+import { hintForZodIssue } from "../lib/zod-issues.js";
+import { BiologicalThemeSchema, KeyReferenceSchema, RunSynthesisSchema, SynthesizedFindingSchema, } from "../schemas/run-synthesis.js";
 import { synthesisAgentPrompt } from "../prompts/synthesis-agent.js";
 import { composeSystemPrompt } from "../agents/system-prompt.js";
 import { runDir } from "../workspace/paths.js";
@@ -40,23 +46,37 @@ const AGENT_ID = "run-synthesizer";
  */
 const SYNTHESIZER_MAX_ITERATIONS = 25;
 // ── Validation ──────────────────────────────────────────────────────
-function zodIssuesToValidationIssues(error, rootPath = "synthesis") {
+function zodIssuesToValidationIssues(error, input, rootPath = "synthesis") {
     return error.issues.map((i) => ({
         path: [rootPath, ...i.path.map((p) => String(p))].join("."),
         code: "schema",
         message: i.message,
+        hint: hintForZodIssue(i, input),
     }));
 }
-function semanticCheck(synthesis, ctx) {
-    const issues = [];
-    if (synthesis.runId !== ctx.runId) {
-        issues.push({
+const PMID_PATTERN = /^\d+$/;
+// ── Semantic checks ─────────────────────────────────────────────────
+//
+// Each check takes only the fields it reads, never the whole synthesis. That is
+// what lets a candidate which failed whole-payload schema validation still be
+// checked: whichever fields parsed on their own get their checks run, and only
+// the checks whose inputs are genuinely missing are deferred. `semanticCheck`
+// composes them for the schema-valid path — it is the one definition of "all
+// semantic checks, in report order".
+function checkRunId(runId, ctx) {
+    if (runId === ctx.runId)
+        return [];
+    return [
+        {
             path: "synthesis.runId",
             code: "semantic",
             message: `runId must be "${ctx.runId}"`,
-        });
-    }
-    for (const [i, f] of synthesis.findings.entries()) {
+        },
+    ];
+}
+function checkFindingStepIds(findings, ctx) {
+    const issues = [];
+    for (const [i, f] of findings.entries()) {
         if (!ctx.knownStepIds.has(f.stepId)) {
             issues.push({
                 path: `synthesis.findings[${i}].stepId`,
@@ -66,8 +86,12 @@ function semanticCheck(synthesis, ctx) {
             });
         }
     }
-    const findingKeys = new Set(synthesis.findings.map((f) => `${f.stepId}::${f.title}`));
-    for (const [ti, t] of synthesis.themes.entries()) {
+    return issues;
+}
+function checkThemeReferences(themes, findings) {
+    const issues = [];
+    const findingKeys = new Set(findings.map((f) => `${f.stepId}::${f.title}`));
+    for (const [ti, t] of themes.entries()) {
         for (const [fi, ref] of t.findings.entries()) {
             if (!findingKeys.has(`${ref.stepId}::${ref.title}`)) {
                 issues.push({
@@ -78,8 +102,12 @@ function semanticCheck(synthesis, ctx) {
             }
         }
     }
-    const citedPmids = new Set(synthesis.findings.flatMap((f) => f.references.map((r) => r.pmid)));
-    for (const [i, r] of synthesis.keyReferences.entries()) {
+    return issues;
+}
+function checkKeyReferencesCited(keyReferences, findings) {
+    const issues = [];
+    const citedPmids = new Set(findings.flatMap((f) => f.references.map((r) => r.pmid)));
+    for (const [i, r] of keyReferences.entries()) {
         if (!citedPmids.has(r.pmid)) {
             issues.push({
                 path: `synthesis.keyReferences[${i}].pmid`,
@@ -89,10 +117,13 @@ function semanticCheck(synthesis, ctx) {
             });
         }
     }
-    const pmidRe = /^\d+$/;
-    for (const [fi, f] of synthesis.findings.entries()) {
+    return issues;
+}
+function checkFindingPmidFormat(findings) {
+    const issues = [];
+    for (const [fi, f] of findings.entries()) {
         for (const [ri, r] of f.references.entries()) {
-            if (!pmidRe.test(r.pmid)) {
+            if (!PMID_PATTERN.test(r.pmid)) {
                 issues.push({
                     path: `synthesis.findings[${fi}].references[${ri}].pmid`,
                     code: "semantic",
@@ -101,8 +132,12 @@ function semanticCheck(synthesis, ctx) {
             }
         }
     }
-    for (const [i, r] of synthesis.keyReferences.entries()) {
-        if (!pmidRe.test(r.pmid)) {
+    return issues;
+}
+function checkKeyReferencePmidFormat(keyReferences) {
+    const issues = [];
+    for (const [i, r] of keyReferences.entries()) {
+        if (!PMID_PATTERN.test(r.pmid)) {
             issues.push({
                 path: `synthesis.keyReferences[${i}].pmid`,
                 code: "semantic",
@@ -112,10 +147,91 @@ function semanticCheck(synthesis, ctx) {
     }
     return issues;
 }
+function semanticCheck(synthesis, ctx) {
+    return [
+        ...checkRunId(synthesis.runId, ctx),
+        ...checkFindingStepIds(synthesis.findings, ctx),
+        ...checkThemeReferences(synthesis.themes, synthesis.findings),
+        ...checkKeyReferencesCited(synthesis.keyReferences, synthesis.findings),
+        ...checkFindingPmidFormat(synthesis.findings),
+        ...checkKeyReferencePmidFormat(synthesis.keyReferences),
+    ];
+}
+function salvageInputs(candidate) {
+    const record = typeof candidate === "object" && candidate !== null ? candidate : {};
+    const runId = z.string().safeParse(record.runId);
+    const findings = z.array(SynthesizedFindingSchema).safeParse(record.findings);
+    const themes = z.array(BiologicalThemeSchema).safeParse(record.themes);
+    const keyReferences = z.array(KeyReferenceSchema).safeParse(record.keyReferences);
+    return {
+        runId: runId.success ? runId.data : undefined,
+        findings: findings.success ? findings.data : undefined,
+        themes: themes.success ? themes.data : undefined,
+        keyReferences: keyReferences.success ? keyReferences.data : undefined,
+    };
+}
+/**
+ * A short issue list must never read as "everything else is fine". When the
+ * payload failed schema validation and some checks could not run, the deferred
+ * ones are named back to the model as an issue of their own.
+ */
+function deferredChecksNotice(deferred) {
+    return {
+        path: "synthesis",
+        code: "semantic",
+        message: `This issue list is INCOMPLETE: ${deferred.length} semantic check(s) could not run because the fields ` +
+            `they read did not survive schema validation — ${deferred.join("; ")}.`,
+        hint: "Fix the schema issues above and call validate_synthesis again; the deferred checks will run then and may report further problems.",
+    };
+}
+/**
+ * Semantic checks over a candidate that failed `RunSynthesisSchema`. Every check
+ * whose own inputs parsed is run; the rest are reported as deferred.
+ */
+function salvagedSemanticCheck(candidate, ctx) {
+    const { runId, findings, themes, keyReferences } = salvageInputs(candidate);
+    const issues = [];
+    const deferred = [];
+    if (runId !== undefined)
+        issues.push(...checkRunId(runId, ctx));
+    else
+        deferred.push("runId matches the run");
+    if (findings !== undefined)
+        issues.push(...checkFindingStepIds(findings, ctx));
+    else
+        deferred.push("finding stepIds are present in the input summaries");
+    if (themes !== undefined && findings !== undefined)
+        issues.push(...checkThemeReferences(themes, findings));
+    else
+        deferred.push("theme references resolve to entries in findings[]");
+    if (keyReferences !== undefined && findings !== undefined)
+        issues.push(...checkKeyReferencesCited(keyReferences, findings));
+    else
+        deferred.push("keyReferences PMIDs are cited by some finding");
+    if (findings !== undefined)
+        issues.push(...checkFindingPmidFormat(findings));
+    else
+        deferred.push("finding reference PMIDs are numeric");
+    if (keyReferences !== undefined)
+        issues.push(...checkKeyReferencePmidFormat(keyReferences));
+    else
+        deferred.push("keyReferences PMIDs are numeric");
+    if (deferred.length > 0)
+        issues.push(deferredChecksNotice(deferred));
+    return issues;
+}
+/**
+ * Validate a candidate in one pass. A schema failure no longer hides the
+ * semantic problems behind it: structure issues come first, then every semantic
+ * check whose inputs survived, then an explicit note of what was deferred.
+ */
 function fullyValidate(candidate, ctx) {
     const parsed = RunSynthesisSchema.safeParse(candidate);
     if (!parsed.success) {
-        return { valid: false, issues: zodIssuesToValidationIssues(parsed.error) };
+        return {
+            valid: false,
+            issues: [...zodIssuesToValidationIssues(parsed.error, candidate), ...salvagedSemanticCheck(candidate, ctx)],
+        };
     }
     const semanticIssues = semanticCheck(parsed.data, ctx);
     if (semanticIssues.length > 0) {
@@ -124,6 +240,36 @@ function fullyValidate(candidate, ctx) {
     return { valid: true, synthesis: parsed.data };
 }
 // ── Inner tools ─────────────────────────────────────────────────────
+function buildValidateTool(ctx) {
+    return defineTool({
+        id: "validate_synthesis",
+        description: "Dry-run a candidate synthesis and get back everything that is wrong " +
+            "with it. Takes the synthesis in ANY shape: a malformed, partial, or " +
+            "wrong-typed candidate is REPORTED, not rejected. Returns " +
+            "{valid, issues[]} covering both schema problems (missing / " +
+            "wrong-typed fields) and the semantic checks a schema cannot express " +
+            "(unknown stepId refs, theme→finding refs, keyReferences PMIDs not " +
+            "cited by any finding, non-numeric PMIDs) in a SINGLE pass — a " +
+            "schema problem does not hide the semantic problems behind it. If a " +
+            "field is too malformed for a semantic check to read, that check is " +
+            "reported as deferred rather than silently skipped. The authoritative " +
+            "field-by-field synthesis schema is the arg schema of " +
+            "submit_synthesis — this tool deliberately does not restate it. " +
+            "Non-terminal: call as often as needed to iterate toward a clean " +
+            "synthesis, then submit_synthesis.",
+        // Deliberately permissive: a structurally-invalid candidate must reach
+        // `execute` so the model gets a structured {valid:false, issues} result —
+        // including semantic issues — instead of a bare Zod rejection at the loop's
+        // input boundary. `execute` re-parses against RunSynthesisSchema itself.
+        inputSchema: z.object({
+            synthesis: z.unknown().describe("The candidate synthesis, in any shape. Field-by-field schema: see submit_synthesis."),
+        }),
+        execute: async (input) => {
+            const result = fullyValidate(input.synthesis, ctx);
+            return ok(result.valid ? { valid: true, issues: [] } : { valid: false, issues: result.issues });
+        },
+    });
+}
 function buildSubmitTool(holder, ctx) {
     return defineTool({
         id: "submit_synthesis",
@@ -133,23 +279,16 @@ function buildSubmitTool(holder, ctx) {
             "success returns {accepted: true} — STOP after this. On rejection " +
             "returns {accepted: false, issues} — fix the specific fields at each " +
             "issue path and call again, or switch to report_blocker if the " +
-            "synthesis cannot be made valid.",
+            "synthesis cannot be made valid. A rejected submission leaves any " +
+            "already-accepted synthesis untouched; a later accepted submission " +
+            "supersedes an earlier one.",
         inputSchema: z.object({ synthesis: RunSynthesisSchema }),
         execute: async (input) => {
-            if (holder.outcome !== null) {
-                return ok({
-                    accepted: false,
-                    issues: [
-                        {
-                            path: "synthesis",
-                            code: "semantic",
-                            message: "A terminal outcome has already been recorded; submit_synthesis " + "can only be called once per invocation.",
-                        },
-                    ],
-                });
-            }
             const result = fullyValidate(input.synthesis, ctx);
             if (!result.valid) {
+                // A rejection is not terminal — submission is last-valid-wins, so this
+                // leaves any already-recorded outcome intact and the model may fix the
+                // cited paths and submit again.
                 return ok({ accepted: false, issues: result.issues });
             }
             holder.outcome = { kind: "submitted", synthesis: result.synthesis };
@@ -163,11 +302,12 @@ function buildBlockerTool(holder) {
             if (holder.outcome === null)
                 holder.outcome = outcome;
         },
-        blockedWhen: "Ends run synthesis with no synthesis written. Use it when the run " +
-            "produced no synthesizable content (all step summaries empty, " +
-            "contradictory to the point of incoherence, or no findings worth " +
-            "surfacing) — not as an escape from a synthesis you could fix and " +
-            "submit.",
+        blockedWhen: "Ends run synthesis with no synthesis written. Use it ONLY when the " +
+            "run produced no synthesizable content — every step summary is empty, " +
+            "or the summaries are contradictory to the point of incoherence. A run " +
+            "with non-empty summaries but no individually notable findings is NOT a " +
+            "blocker: submit a synthesis with an empty findings[] instead. Never " +
+            "use it as an escape from a synthesis you could fix and submit.",
     });
 }
 /**
@@ -181,6 +321,7 @@ export function __buildInnerToolsForTest(args) {
         runId: args.runId,
     };
     return {
+        validate: buildValidateTool(ctx),
         submit: buildSubmitTool(holder, ctx),
         blocker: buildBlockerTool(holder),
         holder,
@@ -203,9 +344,10 @@ export async function generateRunSynthesis(input) {
         model: input.model,
         bioKeys: input.bioKeys,
     });
+    const validateTool = buildValidateTool(innerCtx);
     const submitTool = buildSubmitTool(holder, innerCtx);
     const blockerTool = buildBlockerTool(holder);
-    const tools = [submitTool, blockerTool, reviewer];
+    const tools = [validateTool, submitTool, blockerTool, reviewer];
     const agent = {
         id: AGENT_ID,
         systemPrompt: composeSystemPrompt(synthesisAgentPrompt),

package/dist/lib/zod-issues.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Diagnosis and repair of model-authored arguments that failed Zod validation.
+ *
+ * A Zod issue message is accurate but inert: "Invalid input: expected object,
+ * received string" tells a model what the schema wanted, not what it did wrong
+ * or how to change the next call. Two failure modes put a whole, well-formed
+ * JSON value behind that message:
+ *
+ *  - **Double encoding** — the model serialized a nested object or array with
+ *    `JSON.stringify` and passed the resulting string as the argument value.
+ *  - **Wrapper artifacts** — the JSON value arrived intact but with function-call
+ *    markup or a markdown fence stuck to it (`{…}</parameter>\n</invoke>`,
+ *    ` ```json {…}``` `). The payload is complete; only the wrapper makes it a
+ *    string.
+ *
+ * This module owns both halves of the response for the four model-facing
+ * validation sites (`loop/run-agent.ts`'s tool-input boundary,
+ * `execution/run-synthesis.ts`, `tools/research/generate-plan.ts`,
+ * `tools/iterate-report.ts`):
+ *
+ *  - `hintForZodIssue` — a **diagnostic only**. It parses nothing into the
+ *    caller's data; it distinguishes the two modes so the message the model
+ *    reads matches the mistake it actually made. When neither mode explains the
+ *    string it stays silent, because speculative advice to a model that is
+ *    already misdiagnosing is worse than no advice at all.
+ *  - `repairToolInput` — an **issue-guided** repair: only a path where the
+ *    schema wanted an `object` or `array` and found a string is even considered,
+ *    so a tool that legitimately declares a `z.string()` field is never touched.
+ *    It makes validation *reachable*; it never substitutes for it. The caller
+ *    re-runs the full schema over the repaired value, and the tool's own
+ *    semantic checks still run unchanged.
+ *
+ * Neither is used by `tools/lib/api-utils.ts`'s `summarizeZodIssues`, whose
+ * audience is a developer reading a log about a third-party API response shape —
+ * "pass the object directly" is meaningless advice for a payload no one here
+ * constructed.
+ *
+ * Detection walks `issue.path` into the raw input rather than reading the
+ * received type off the issue. Zod 4's `invalid_type` issue exposes `expected`
+ * but carries no `received` field — the received type appears only inside the
+ * human-readable `message`, which is version- and locale-dependent and must
+ * not be pattern-matched.
+ */
+import type { z } from "zod";
+/**
+ * A hint for a single Zod issue, or `undefined` when nothing actionable can be
+ * said. `input` is the raw value that failed validation — the same value handed
+ * to `safeParse` — because the issue alone does not carry the offending value.
+ *
+ * Fires only for an `invalid_type` issue wanting an `object` or an `array` whose
+ * path resolves to a string, and only when that string demonstrably *is* the
+ * expected value:
+ *
+ *  1. it parses in full as JSON of the expected type → double encoding, and
+ *  2. it parses only once a wrapper artifact is stripped → the value is intact
+ *     but surrounded by content that does not belong.
+ *
+ * Anything else — a plain string, a truncated fragment, a stray
+ * `<parameter name=…>` opener — yields `undefined`.
+ *
+ * A path that does not resolve — a mismatched shape, a pruned branch — yields
+ * `undefined` rather than throwing.
+ */
+export declare function hintForZodIssue(issue: z.core.$ZodIssue, input: unknown): string | undefined;
+/**
+ * Repair model-authored tool input whose JSON values arrived as strings behind a
+ * wrapper artifact, or double-encoded. Returns a **new** input value with the
+ * repairs applied, or `undefined` when nothing was repaired.
+ *
+ * The repair is guided entirely by `error`: a path is considered only when the
+ * schema reported an `invalid_type` there wanting an `object` or `array` and the
+ * value sitting at that path is a string. The parsed result is accepted only if
+ * its own type matches what the schema expected, so a string field that happens
+ * to hold JSON-looking text is never rewritten.
+ *
+ * The input object graph is never mutated: the repaired copy shares every
+ * untouched branch and clones only along the paths it patches. Repaired content
+ * is not re-examined — one pass, no recursion — and no input causes a throw.
+ */
+export declare function repairToolInput(input: unknown, error: z.ZodError): unknown | undefined;