@inflexa-ai/harness 0.45.0 → 0.46.0

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

@@ -1,18 +1,16 @@
 /**
- * Run synthesizer — a single-shot agent loop driven through `runAgent`:
+ * Run synthesizer — a single-shot agent loop driven through `runWithSalvage`:
  *
- *   - `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; 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
- *                            across the boundary (forSubAgent semantics).
+ *   - `submit_synthesis`  — checks one synthesis against the schema and the
+ *                            semantic checks, and gives back the issues. It
+ *                            does not end the run. The last accepted
+ *                            submission is the synthesis.
+ *   - `report_blocker`    — the run produced nothing synthesizable. An
+ *                            accepted synthesis wins over a blocker.
+ *   - `literature_reviewer` — research sub-agent exposed as a tool. The
+ *                            runtime registers it one time and gives it here;
+ *                            the sub-agent loop's brief is the only context
+ *                            handed across the boundary (forSubAgent semantics).
  *
  * Two deliverables on a happy path: `synthesis.json` written to the run dir
  * and a `data-run-synthesis` chat data part emitted via the `emit` callback
@@ -23,17 +21,16 @@
  * resolves with `{ kind: "failed" }`, the wrapper emits a synthesis-progress
  * `failed` part. We do not throw here for routine submitter rejections.
  */
-import { type RunSynthesis } from "../schemas/run-synthesis.js";
+import { type RunSynthesis, type SynthesisDraft } from "../schemas/run-synthesis.js";
 import type { RunSynthesisPart } from "../contracts/chat-parts.js";
 import type { StepSummary } from "../schemas/step-summary.js";
+import { type LoopOptions, type LoopStep } from "../loop/run-loop.js";
 import type { ToolOutputStore } from "../loop/tool-output.js";
 import type { ChatDataPart, EmitFn } from "../loop/types.js";
 import type { ChatProvider } from "../providers/types.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { RunSession } from "../auth/types.js";
 import { type Tool } from "../tools/define-tool.js";
-import type { BioToolKeys } from "../tools/bio/keys.js";
-import type { CitationResolver } from "../citations/types.js";
 /**
  * The synthesizer's agent identity — the `source.agentId` on its loop events
  * and the `agent_id` of the run-phase `synthesis` row `executeAnalysis` writes
@@ -41,38 +38,41 @@ import type { CitationResolver } from "../citations/types.js";
  * events can never disagree about who did the work.
  */
 export declare const SYNTHESIS_AGENT_ID = "run-synthesizer";
-type SynthesizerOutcome = {
-    kind: "submitted";
-    synthesis: RunSynthesis;
+export type ValidationIssue = {
+    readonly path: string;
+    readonly code: "schema" | "semantic";
+    readonly message: string;
+    readonly hint?: string;
+};
+export type SubmitSynthesisOutput = {
+    accepted: true;
 } | {
-    kind: "blocker";
-    reason: string;
+    accepted: false;
+    issues: ValidationIssue[];
 };
-interface OutcomeHolder {
-    outcome: SynthesizerOutcome | null;
-}
+/** The last accepted synthesis of a run, from the inputs of the calls of `submit_synthesis` that it accepted. */
+export declare function acceptedSynthesisOf(steps: readonly LoopStep[]): SynthesisDraft | undefined;
 /**
  * Test-only — expose the inner-tool factory so unit tests can assert on
- * validation + outcome capture without driving the whole agent loop.
+ * the checks without driving the whole agent loop.
  */
 export declare function __buildInnerToolsForTest(args: {
     knownStepIds: ReadonlySet<string>;
-    runId: string;
 }): {
-    validate: Tool;
-    submit: Tool;
-    blocker: Tool;
-    holder: OutcomeHolder;
+    submit: Tool<{
+        synthesis: SynthesisDraft;
+    }, SubmitSynthesisOutput>;
+    blocker: Tool<{
+        reason: string;
+    }>;
 };
-export interface GenerateRunSynthesisInput {
+export type GenerateRunSynthesisInput = {
     readonly provider: ChatProvider;
     readonly session: RunSession;
     readonly model: string;
-    /** API keys for the bio/chem tools the embedded literature reviewer uses. */
-    readonly bioKeys: BioToolKeys;
-    /** Shared resolver used by the embedded literature reviewer. */
-    readonly citationResolver: CitationResolver;
-    /** LLM usage-accounting seam for the synthesizer + reviewer loops; omitted falls back to the no-op recorder. */
+    /** The `literature_reviewer` tool of the synthesizer (`createLiteratureReviewerTool`). */
+    readonly literatureReviewer: Tool;
+    /** LLM usage-accounting seam for the synthesizer loop; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
     /** The store of the synthesizer and reviewer loops and of their read tools. */
     readonly toolOutputStore?: ToolOutputStore;
@@ -80,13 +80,15 @@ export interface GenerateRunSynthesisInput {
     readonly summaries: readonly StepSummary[];
     /** Plan analytical narrative for context. */
     readonly planNarrative: string;
-    /** Run id — submitted synthesis must match. */
+    /** Run id — the host stamps it on the accepted synthesis. */
     readonly runId: string;
     /** Optional cancellation. */
     readonly signal?: AbortSignal;
     /** Optional UI event sink (chat data parts forwarded to the parent stream). */
     readonly emit?: EmitFn;
-}
+    /** The pause of the run. The body of the run gives it, thus a failed request waits in place. */
+    readonly pause?: LoopOptions["pause"];
+};
 export type GenerateRunSynthesisResult = {
     kind: "synthesis";
     synthesis: RunSynthesis;
@@ -95,36 +97,36 @@ export type GenerateRunSynthesisResult = {
     reason: string;
 };
 /**
- * Drive the synthesizer agent loop to a terminal outcome — either a
- * validated synthesis (`submit_synthesis`) or a blocker (`report_blocker`).
- * Throws when neither terminal is reached (loop cap or external abort).
+ * Drive the synthesizer agent loop to an outcome — the last accepted
+ * synthesis (`submit_synthesis`), else a blocker (`report_blocker`).
+ * Throws when the run and its salvage end with neither (loop cap or external abort).
  */
 export declare function generateRunSynthesis(input: GenerateRunSynthesisInput): Promise<GenerateRunSynthesisResult>;
-export interface LoadStepSummariesInput {
+export type LoadStepSummariesInput = {
     /** Absolute host root of the analysis's workspace tree. */
     readonly workspaceRoot: string;
     readonly runId: string;
     readonly completedSteps: readonly string[];
     readonly agentByStepId?: Readonly<Record<string, string>>;
-}
+};
 /**
  * Read each completed step's `output/summary.md`. Steps with missing or empty
  * summaries are silently dropped — the caller decides what to do when the
  * resulting array is empty.
  */
 export declare function loadStepSummariesFromDisk(args: LoadStepSummariesInput): Promise<StepSummary[]>;
-export interface PersistSynthesisInput {
+export type PersistSynthesisInput = {
     /** Absolute host root of the analysis's workspace tree. */
     readonly workspaceRoot: string;
     readonly runId: string;
     readonly synthesis: RunSynthesis;
-}
+};
 export declare function persistSynthesis(args: PersistSynthesisInput): Promise<string>;
-export interface ReadSynthesisInput {
+export type ReadSynthesisInput = {
     /** Absolute host root of the analysis's workspace tree. */
     readonly workspaceRoot: string;
     readonly runId: string;
-}
+};
 /**
  * Read the text of a synthesis record under the cap, or give `undefined` when the bytes do not come back.
  *
@@ -147,4 +149,3 @@ export declare function formatSynthesisEmbeddingText(synthesis: RunSynthesis): s
  * `RunSynthesisPart` interface — keep them in lockstep.
  */
 export declare function buildRunSynthesisPart(runId: string, synthesis: RunSynthesis): ChatDataPart;
-export {};