@inflexa-ai/harness 0.45.1 → 0.46.2

package/dist/execution/run-event-parts.js

@@ -7,8 +7,23 @@
  * They live apart from the reader, thus a test drives them directly instead of
  * through a subscription.
  */
+import { setTimeout as sleep } from "node:timers/promises";
 import { reconcileKey } from "../contracts/chat-frame.js";
 import { PART_REGISTRY } from "../contracts/part-registry.js";
+import { parseUnknownRecord } from "../lib/unknown-containers.js";
+/**
+ * The registry is keyed by the discriminant alone, so this validates `type` and
+ * trusts the producer for the payload. The part schemas in `contracts/schemas/`
+ * are for a consumer at the edge of the package, which parses what it receives.
+ * Both ends of this stream are typed against the same union inside this package,
+ * so the discriminant is the boundary that can drift (a producer that emits
+ * something else entirely), and a part that fails its schema still reaches the
+ * consumer for its own check.
+ */
+function isChatPartRecord(record) {
+    const { type } = record;
+    return typeof type === "string" && Object.hasOwn(PART_REGISTRY, type);
+}
 /**
  * Narrow one raw stream value to a chat data part, or `null` when it is not one.
  *
@@ -18,24 +33,12 @@ import { PART_REGISTRY } from "../contracts/part-registry.js";
  * contract is the `ChatPart` union, so anything the registry does not
  * classify is not deliverable — which also covers a part written by a producer
  * newer than the reader.
- *
- * The registry is keyed by the discriminant alone, so this validates `type` and
- * trusts the producer for the payload. The part schemas in `contracts/schemas/`
- * are for a consumer at the edge of the package, which parses what it receives.
- * Both ends of this stream are typed against the same union inside this package,
- * so the discriminant is the boundary that can drift (a producer that emits
- * something else entirely), and a part that fails its schema still reaches the
- * consumer for its own check.
  */
 export function parseRunEventPart(value) {
-    if (typeof value !== "object" || value === null)
-        return null;
-    const type = value.type;
-    if (typeof type !== "string")
+    const record = parseUnknownRecord(value);
+    if (record === undefined || !isChatPartRecord(record))
         return null;
-    if (!Object.hasOwn(PART_REGISTRY, type))
-        return null;
-    return value;
+    return record;
 }
 /**
  * Collapse a batch of parts so each reconciling id appears once, carrying its
@@ -78,10 +81,12 @@ export function foldRunEventParts(parts) {
 export async function pipeFoldedRunEvents(entries, emit, flushMs) {
     const latestByKey = new Map();
     const pendingKeys = new Set();
-    let flushTimer = null;
+    // The gate of the one armed flush wait: present while a window is open, so a
+    // second entry in the window reuses it instead of arming a second flush.
+    let flushGate;
     let flushChain = Promise.resolve();
     const flushPending = async () => {
-        flushTimer = null;
+        flushGate = undefined;
         const keys = [...pendingKeys];
         pendingKeys.clear();
         for (const key of keys) {
@@ -91,14 +96,15 @@ export async function pipeFoldedRunEvents(entries, emit, flushMs) {
         }
     };
     const scheduleFlush = () => {
-        if (flushTimer !== null)
+        if (flushGate !== undefined)
             return;
-        flushTimer = setTimeout(() => {
+        flushGate = new AbortController();
+        sleep(flushMs, undefined, { signal: flushGate.signal }).then(() => {
             // A timed flush has no caller to report to. A lasting emit failure
             // still reaches the caller, through the next direct emit or the
             // final flush.
             flushChain = flushChain.then(flushPending).catch(() => undefined);
-        }, flushMs);
+        }, () => undefined);
     };
     try {
         for await (const entry of entries) {
@@ -114,10 +120,9 @@ export async function pipeFoldedRunEvents(entries, emit, flushMs) {
         }
     }
     finally {
-        if (flushTimer !== null) {
-            clearTimeout(flushTimer);
-            flushTimer = null;
-        }
+        // The abort ends the armed wait, whose rejection the second arm swallows,
+        // so the teardown does not wait out the window.
+        flushGate?.abort();
         await flushChain;
         if (pendingKeys.size > 0)
             await flushPending();

package/dist/execution/run-event-stream.d.ts

@@ -37,17 +37,17 @@ import { type DbError } from "../lib/db-result.js";
 import type { Logger } from "../lib/logger.js";
 import type { RunStatus } from "../state/schema.js";
 /** The part of a run row that the terminal part is made from. */
-export interface RunEventRunRead {
+export type RunEventRunRead = {
     readonly status: RunStatus;
     readonly error: string | null;
-}
+};
 /**
  * Construction-time dependencies. The pool is the application pool the run
  * ledger lives in; the logger is where every contained failure is reported, and
  * defaults to silence so an embedder that wired none sees nothing rather than
  * having console forced on it.
  */
-export interface RunEventStreamDeps {
+export type RunEventStreamDeps = {
     readonly pool: Pool;
     readonly logger?: Logger;
     /** Reads the status and the error of the run row, `null` when no row exists. Defaults to `queryRun` on `pool`. */
@@ -59,7 +59,7 @@ export interface RunEventStreamDeps {
     readonly readWorkflowStatus?: (runId: string) => Promise<string | null>;
     /** The wait between two reads of the run row. Defaults to a timer. */
     readonly sleep?: (ms: number) => Promise<void>;
-}
+};
 /**
  * Receives one part. May be async — the subscription awaits it, so a handler is
  * never invoked concurrently with itself and back-pressure is the caller's to
@@ -67,20 +67,20 @@ export interface RunEventStreamDeps {
  */
 export type RunEventPartHandler = (part: ChatPart) => void | Promise<void>;
 /** Call-time parameters of one subscription. */
-export interface RunEventSubscribeOptions {
+export type RunEventSubscribeOptions = {
     /** The run to observe. Also the parent workflow's id. */
     readonly runId: string;
     /** Where each delivered part goes. */
     readonly onPart: RunEventPartHandler;
     /** Aborting stops delivery and settles the returned promise. */
     readonly signal: AbortSignal;
-}
+};
 /**
  * The run-event read seam. One method, because a run-scoped subscription is the
  * whole capability: a general-purpose stream reader would leak the engine's model
  * back into the surface this exists to quarantine.
  */
-export interface RunEventStream {
+export type RunEventStream = {
     /**
      * Deliver every part the run produces — parent and children alike — to
      * `onPart`, resolving when the run is terminal, every stream opened has
@@ -103,7 +103,7 @@ export interface RunEventStream {
      * `runId`/`stepId` and the reconciling fold is per id.
      */
     subscribe(options: RunEventSubscribeOptions): Promise<void>;
-}
+};
 /**
  * Build the DBOS-backed realization of {@link RunEventStream}.
  *

package/dist/execution/run-event-stream.js

@@ -43,10 +43,6 @@ function partOfRow(runId, row) {
     switch (row.status) {
         case "canceled":
             return canceledPart(runId);
-        case "suspended_insufficient_funds":
-            return row.error === null
-                ? { type: "data-run-failed", runId, error: "Run suspended" }
-                : { type: "data-run-failed", runId, error: row.error, reason: row.error };
         case "failed":
             return { type: "data-run-failed", runId, error: row.error ?? "Run failed" };
         case "completed":
@@ -138,6 +134,7 @@ export function createRunEventStream(deps) {
                     while (pending.length > 0 && !signal.aborted) {
                         const batch = pending.splice(0, pending.length);
                         for (const part of foldRunEventParts(batch)) {
+                            // oxlint-disable-next-line no-unnecessary-condition -- tsgolint cannot see the event wiring that aborts the signal; the re-check after each part is live (cancel stops delivery).
                             if (signal.aborted)
                                 return;
                             try {
@@ -228,6 +225,7 @@ export function createRunEventStream(deps) {
                     if (signal.aborted)
                         return;
                     await discoverChildren();
+                    // oxlint-disable-next-line no-unnecessary-condition -- tsgolint cannot see the event-wired abort or the parentRead .finally that sets parentDrained; both checks are live (discovery stops on cancel or a drained parent).
                     if (signal.aborted || parentDrained)
                         return;
                     await Promise.race([sleep(CHILD_DISCOVERY_INTERVAL_MS), aborted, parentRead]);
@@ -289,6 +287,7 @@ export function createRunEventStream(deps) {
                 await discovery;
                 await parentRead;
                 await Promise.all(childReads);
+                // oxlint-disable-next-line no-unnecessary-condition -- tsgolint cannot see the readWorkflowStream closure that sets sawTerminal or the event-wired abort; the fallback that mints the missing terminal part is live.
                 if (!sawTerminal && !signal.aborted) {
                     const terminal = await missingTerminalPart();
                     if (terminal !== null)

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

@@ -10,11 +10,11 @@
  * reference, typed `(input) => Promise<result>`; the launcher only owns the
  * start/await/cancel mechanics around it.
  */
-export interface LaunchOptions {
+export type LaunchOptions = {
     /** Caller-chosen durable workflow id (e.g. the runId). */
     readonly workflowId: string;
-}
-export interface RunLauncher {
+};
+export type RunLauncher = {
     /** Fire-and-forget: resolves once the run is durably started. */
     launch<I>(workflow: (input: I) => Promise<unknown>, opts: LaunchOptions, input: I): Promise<void>;
-}
+};

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 {};