@inflexa-ai/harness 0.46.0 → 0.47.0

package/dist/execution/run-synthesis.js

@@ -7,10 +7,12 @@
  *                            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).
+ *   - the lookups         — the gene, protein, annotation, interaction,
+ *                            PubMed, citation, drug-gene, and preclinical
+ *                            tools (`createSynthesisLookupTools`). Each lookup
+ *                            records the PMIDs of its result, and
+ *                            `submit_synthesis` refuses a PMID that no lookup
+ *                            of the run returned.
  *
  * 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
@@ -27,6 +29,7 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { writeFileWithinRoot } from "../lib/fs-helpers.js";
 import { isAllDigits } from "../lib/text.js";
+import { parseUnknownRecord } from "../lib/unknown-containers.js";
 import { tryFs } from "../lib/fs-result.js";
 import { safeParseJsonAs } from "../lib/parse-json.js";
 import { RunSynthesisSchema, SynthesisDraftSchema, } from "../schemas/run-synthesis.js";
@@ -35,8 +38,10 @@ import { composeSystemPrompt } from "../agents/system-prompt.js";
 import { isSafeId, runDir } from "../workspace/paths.js";
 import { runWithSalvage } from "../loop/run-loop.js";
 import { recordedInputOf } from "../loop/tool-adapter.js";
-import { defineTool } from "../tools/define-tool.js";
+import { defineTool, readToolResultImages, withToolCallRecord, withToolResultImages } from "../tools/define-tool.js";
 import { createReadToolOutputTool } from "../tools/read-tool-output.js";
+import { createReadScriptTools } from "../tools/script/file-tools.js";
+import { createReadSurfaceTools } from "../tools/workspace/read-surface.js";
 import { blockerOf, createReportBlockerToolFor, REPORT_BLOCKER_TOOL_ID } from "../tools/sandbox/report-blocker.js";
 // ── Agent identity / budgets ────────────────────────────────────────
 /**
@@ -47,17 +52,75 @@ import { blockerOf, createReportBlockerToolFor, REPORT_BLOCKER_TOOL_ID } from ".
  */
 export const SYNTHESIS_AGENT_ID = "run-synthesizer";
 /**
- * Budget for the synthesizer loop: read summaries + 1–3 reviewer delegations
- * + draft + 1–2 submit/fix cycles + headroom.
+ * Budget for the synthesizer loop: the rounds of lookups, each one a batch of
+ * parallel calls, then the draft, 1–2 submit/fix cycles, and headroom.
  */
-const SYNTHESIZER_MAX_ITERATIONS = 25;
-/**
- * Cap on `literature_reviewer` calls per run. Not named in the prompt: a
- * model treats a stated call-count limit as a target to hit, not a maximum.
- */
-const LITERATURE_REVIEWER_BUDGET = 3;
+const SYNTHESIZER_MAX_ITERATIONS = 40;
 const SubmitSynthesisOutputSchema = z.object({ accepted: z.boolean() });
 const SUBMIT_SYNTHESIS_TOOL_ID = "submit_synthesis";
+// ── The PMIDs of the lookups ────────────────────────────────────────
+/**
+ * The keys under which a lookup gives back its request: `resolve_citation`
+ * returns the citation that it was given, normalized. A PMID there came from
+ * the model, not from a source.
+ */
+const ECHO_KEYS = new Set(["input", "normalized", "supplied", "query"]);
+/** Each PMID that a lookup result holds under a `pmid` or `pmids` key, outside the echo of the request. */
+export function pmidsIn(value, found = new Set()) {
+    if (Array.isArray(value)) {
+        for (const item of value)
+            pmidsIn(item, found);
+        return found;
+    }
+    const record = parseUnknownRecord(value);
+    if (record === undefined)
+        return found;
+    for (const [key, child] of Object.entries(record)) {
+        if (ECHO_KEYS.has(key))
+            continue;
+        if (key === "pmid" && (typeof child === "string" || typeof child === "number")) {
+            if (isAllDigits(String(child)))
+                found.add(String(child));
+        }
+        else if (key === "pmids" && Array.isArray(child)) {
+            for (const pmid of child)
+                if (typeof pmid === "string" && isAllDigits(pmid))
+                    found.add(pmid);
+        }
+        else {
+            pmidsIn(child, found);
+        }
+    }
+    return found;
+}
+const PmidRecordSchema = z.object({ pmids: z.array(z.string()) });
+/**
+ * A lookup whose ok result records the PMIDs that it holds. The loop folds the
+ * record into `seen` after each round, on the first run and on each replay, thus
+ * the check of `submit_synthesis` reads the same set in both.
+ */
+export function recordingPmids(tool, seen) {
+    if (tool.foldCallRecord !== undefined)
+        throw new Error(`the lookup ${tool.id} keeps its own call record, which the PMID record would replace`);
+    return {
+        ...tool,
+        execute: async (input, ctx) => (await tool.execute(input, ctx)).map((value) => {
+            const record = parseUnknownRecord(value);
+            if (record === undefined)
+                return value;
+            // The parsed record is a copy without the symbol keys of the value, thus the pictures move over by hand.
+            const images = readToolResultImages(value);
+            const carried = images.length === 0 ? record : withToolResultImages(record, images);
+            return withToolCallRecord(carried, { pmids: [...pmidsIn(record)] });
+        }),
+        foldCallRecord: (record) => {
+            const parsed = PmidRecordSchema.safeParse(record);
+            if (parsed.success)
+                for (const pmid of parsed.data.pmids)
+                    seen.add(pmid);
+        },
+    };
+}
 // ── Validation ──────────────────────────────────────────────────────
 // ── Semantic checks ─────────────────────────────────────────────────
 //
@@ -138,6 +201,20 @@ function checkKeyReferencePmidFormat(keyReferences) {
     }
     return issues;
 }
+function checkPmidsLookedUp(synthesis, lookedUp) {
+    const cited = [
+        ...synthesis.findings.flatMap((f, fi) => f.references.map((r, ri) => ({ pmid: r.pmid, path: `synthesis.findings[${fi}].references[${ri}].pmid` }))),
+        ...synthesis.keyReferences.map((r, i) => ({ pmid: r.pmid, path: `synthesis.keyReferences[${i}].pmid` })),
+    ];
+    return cited
+        .filter(({ pmid }) => pmid.length > 0 && isAllDigits(pmid) && !lookedUp.has(pmid))
+        .map(({ pmid, path }) => ({
+        path,
+        code: "semantic",
+        message: `pmid "${pmid}" is in no lookup result of this run`,
+        hint: "Cite only a PMID that a lookup of this run returned. Look it up, or remove the reference.",
+    }));
+}
 function semanticCheck(synthesis, ctx) {
     return [
         ...checkFindingStepIds(synthesis.findings, ctx),
@@ -145,6 +222,7 @@ function semanticCheck(synthesis, ctx) {
         ...checkKeyReferencesCited(synthesis.keyReferences, synthesis.findings),
         ...checkFindingPmidFormat(synthesis.findings),
         ...checkKeyReferencePmidFormat(synthesis.keyReferences),
+        ...checkPmidsLookedUp(synthesis, ctx.lookedUpPmids),
     ];
 }
 // ── Inner tools ─────────────────────────────────────────────────────
@@ -153,7 +231,7 @@ function buildSubmitTool(ctx) {
         id: SUBMIT_SYNTHESIS_TOOL_ID,
         description: "Submit the synthesis. Checks the payload against the semantic checks " +
             "the arg schema cannot express (stepId refs, theme→finding refs, " +
-            "keyReferences PMIDs cited, numeric PMIDs). On success returns " +
+            "keyReferences PMIDs cited, numeric PMIDs, each PMID returned by a lookup of this run). On 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 " +
@@ -196,9 +274,26 @@ function buildBlockerTool() {
  * the checks without driving the whole agent loop.
  */
 export function __buildInnerToolsForTest(args) {
-    const ctx = { knownStepIds: args.knownStepIds };
+    const ctx = { knownStepIds: args.knownStepIds, lookedUpPmids: args.lookedUpPmids ?? new Set() };
     return { submit: buildSubmitTool(ctx), blocker: buildBlockerTool() };
 }
+/** The synthesizer agent of one run. Its submit tool checks the step ids of the summaries and the PMIDs of its lookups. */
+export function synthesizerAgentOf(input) {
+    const knownStepIds = new Set(input.summaries.map((s) => s.stepId));
+    const lookedUpPmids = new Set();
+    const innerCtx = { knownStepIds, lookedUpPmids };
+    const readTools = input.toolOutputStore ? [createReadToolOutputTool(input.toolOutputStore)] : [];
+    // The lookups run in `run_script`, which gives the PMID record of each nested call to its lookup.
+    return {
+        id: SYNTHESIS_AGENT_ID,
+        systemPrompt: composeSystemPrompt(synthesisAgentPrompt),
+        model: input.model,
+        tools: [...createReadSurfaceTools(input.workspace), buildSubmitTool(innerCtx), buildBlockerTool(), ...readTools],
+        scriptTools: [...input.synthesisLookups.map((tool) => recordingPmids(tool, lookedUpPmids)), ...createReadScriptTools(input.workspace)],
+        scriptRuntime: input.scriptRuntime,
+        maxIterations: SYNTHESIZER_MAX_ITERATIONS,
+    };
+}
 /**
  * Drive the synthesizer agent loop to an outcome — the last accepted
  * synthesis (`submit_synthesis`), else a blocker (`report_blocker`).
@@ -208,21 +303,8 @@ export async function generateRunSynthesis(input) {
     if (input.summaries.length === 0) {
         throw new Error("Run synthesis: no step summaries to synthesize");
     }
-    const knownStepIds = new Set(input.summaries.map((s) => s.stepId));
-    const innerCtx = { knownStepIds };
-    const reviewer = input.literatureReviewer;
-    const submitTool = buildSubmitTool(innerCtx);
-    const blockerTool = buildBlockerTool();
-    const readTools = input.toolOutputStore ? [createReadToolOutputTool(input.toolOutputStore)] : [];
-    const tools = [submitTool, blockerTool, reviewer, ...readTools];
-    const agent = {
-        id: SYNTHESIS_AGENT_ID,
-        systemPrompt: composeSystemPrompt(synthesisAgentPrompt),
-        model: input.model,
-        tools,
-        maxIterations: SYNTHESIZER_MAX_ITERATIONS,
-    };
-    const prompt = buildSynthesizerPrompt(input.planNarrative, input.summaries);
+    const agent = synthesizerAgentOf(input);
+    const prompt = synthesizerSeedOf(input.planNarrative, input.summaries);
     const signal = input.signal ?? new AbortController().signal;
     const emit = input.emit ?? (() => { });
     const run = await runWithSalvage(agent, [{ role: "user", content: prompt }], input.session, {
@@ -231,7 +313,6 @@ export async function generateRunSynthesis(input) {
         emit,
         usageRecorder: input.usageRecorder,
         toolOutputStore: input.toolOutputStore,
-        policy: { budget: { [reviewer.id]: LITERATURE_REVIEWER_BUDGET } },
         pause: input.pause,
     }, {
         tools: [SUBMIT_SYNTHESIS_TOOL_ID, REPORT_BLOCKER_TOOL_ID],
@@ -385,7 +466,8 @@ export function formatSynthesisEmbeddingText(synthesis) {
     ].join("\n");
 }
 // ── Prompt builder ──────────────────────────────────────────────────
-function buildSynthesizerPrompt(planNarrative, summaries) {
+/** The first message of the synthesizer: the narrative of the plan and the summary of each step. */
+export function synthesizerSeedOf(planNarrative, summaries) {
     const summaryBlock = summaries.map((s) => `### ${s.stepId} (${s.agentId})\n\n${s.markdown}`).join("\n\n---\n\n");
     return ["## Analytical Narrative", planNarrative, "", "## Step Summaries", summaryBlock].join("\n");
 }

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  * the agent with its own seam realizations.
  */
 export { assembleCoreRuntime } from "./runtime/assemble.js";
-export type { CoreRuntime, CoreRuntimeDeps, CoreWorkflowDeps, RegisteredWorkflows, ConversationAssemblyDeps, SandboxStepCallable, MakeReportReferenceResolver, ReportResolverScope, } from "./runtime/assemble.js";
+export type { CoreRuntime, CoreRuntimeDeps, CoreSandboxDeps, CoreWorkflowDeps, RegisteredWorkflows, ConversationAssemblyDeps, SandboxStepCallable, MakeReportReferenceResolver, ReportResolverScope, } from "./runtime/assemble.js";
 export type { ReferenceResolver, ReportSnapshot, ResolvedValue } from "./report-model/reference-resolver.js";
 export type { ResolvePageAsset } from "./tools/report-session/index.js";
 export { PAGE_ASSETS } from "./report-render/assets.js";
@@ -43,7 +43,6 @@ export type { MakeSessionPagePublisher, SessionPageGrant, SessionPageMintFailure
 export type { ResolvePageUrl, SessionPageAccess } from "./tools/report-session/index.js";
 export { bindReadExport, bindSessionEmit } from "./provenance/seam.js";
 export type { ProvenanceExport, ProvenanceSeam, RunProvenanceEvent, SessionProvenanceEvent } from "./provenance/seam.js";
-export type { DerivationSource } from "./state/report-session-state.js";
 export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
 export type { RunLauncher, LaunchOptions } from "./execution/run-launcher.js";
 export { createDbosWorkflowPurger } from "./execution/dbos-workflow-purger.js";
@@ -158,6 +157,7 @@ export type { ResolveWorkspaceRoot } from "./workspace/paths.js";
 export { createSandboxClient } from "./sandbox/create-sandbox.js";
 export type { CreateSandboxClientConfig, SandboxBackendConfig } from "./sandbox/create-sandbox.js";
 export type { SandboxClient } from "./sandbox/client.js";
+export type { AcquireOutcome, BoundLease, LeaseBinding, NoLease, SandboxLeases } from "./sandbox/leases.js";
 export type { ResolveSandboxLabels, SandboxLabels, SandboxSpec } from "./sandbox/types.js";
 export type { SpawnSession } from "./auth/types.js";
 export { describeSandboxError, keepSuspendingRefusal, SandboxFailure } from "./sandbox/sandbox-error.js";
@@ -188,7 +188,6 @@ export type { PlanStep } from "./workflows/execute-analysis-scheduler.js";
 export { planGraphOf } from "./workflows/plan/graph.js";
 export { planPartOf } from "./memory/card-builders.js";
 export { validatePlan } from "./schemas/validate-plan.js";
-export type { ValidatePlanOptions } from "./schemas/validate-plan.js";
 export type { ValidationResult } from "./schemas/validate-plan.js";
 export { upsertPlan, loadPlan, loadPlanRecord } from "./state/plans.js";
 export type { UpsertPlanInput, PlanRecord } from "./state/plans.js";
@@ -206,7 +205,5 @@ export { reportSessionDir } from "./workspace/paths.js";
 export type { LogFields, LogLevel, Logger } from "./lib/logger.js";
 export { defaultErrorFields } from "./lib/logger.js";
 export { createConsoleLogger, createNoopLogger } from "./lib/console-logger.js";
-export { registerSandboxReaper } from "./sandbox/reaper.js";
-export type { RegisterReaperDeps } from "./sandbox/reaper.js";
 export { registerNotificationSweep } from "./sandbox/notification-sweep.js";
 export type { RegisterNotificationSweepDeps } from "./sandbox/notification-sweep.js";

package/dist/index.js

@@ -55,8 +55,7 @@ export { UnavailableSessionPagePublisher } from "./tools/report-session/session-
 // back for the report page. Thus the seam and its vocabulary belong on the front door: an embedder
 // cannot type its realization without them. The two binders ride beside the types, because an
 // embedder that calls `prepareChatTurn` or one tool factory directly binds the same total forms
-// that the assembly binds. `DerivationSource` rides beside the event union, because the derivation
-// event carries the chain of the derived table.
+// that the assembly binds.
 export { bindReadExport, bindSessionEmit } from "./provenance/seam.js";
 // Run launching.
 export { createDbosRunLauncher } from "./execution/dbos-run-launcher.js";
@@ -314,8 +313,6 @@ export { reportSessionDir } from "./workspace/paths.js";
 // `defaultErrorFields` is the shipped mapping for one with no opinion.
 export { defaultErrorFields } from "./lib/logger.js";
 export { createConsoleLogger, createNoopLogger } from "./lib/console-logger.js";
-// Sandbox-hygiene scheduled workflows. Reaper reclaims a dead host's orphaned
-// containers; the sweep prunes stale notifications. Each is a
-// `@DBOS.scheduled` no-op on an idle system.
-export { registerSandboxReaper } from "./sandbox/reaper.js";
+// The scheduled sweep that prunes stale notifications. It is a `@DBOS.scheduled`
+// no-op on an idle system. The sandbox reconciler registers with the runtime.
 export { registerNotificationSweep } from "./sandbox/notification-sweep.js";

package/dist/input-scan/enrich.d.ts

@@ -17,8 +17,7 @@
  */
 import type { AgentSession } from "../auth/types.js";
 import type { EmitFn } from "../tools/define-tool.js";
-import type { SandboxClient } from "../sandbox/client.js";
-import type { SandboxRef } from "../sandbox/types.js";
+import type { BoundLease } from "../sandbox/leases.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import type { FileShape, HeaderReadout } from "./types.js";
 /** Members decoded per shape. One is enough to characterise a set whose names already match. */
@@ -45,24 +44,20 @@ export type ReadHeadersArgs = {
     readonly targets: readonly ReadoutTargetSpec[];
     readonly session: AgentSession;
     readonly fs: WorkspaceFilesystem;
-    /** Omit the sandbox to skip container readouts; every other format still reads. */
-    readonly sandboxClient?: SandboxClient;
-    readonly sandbox?: SandboxRef;
+    /** Omit the lease to skip container readouts; every other format still reads. */
+    readonly lease?: BoundLease;
     /** Absolute in-sandbox path of the analysis root (`/{analysisId}`). */
     readonly mountRoot: string;
-    readonly deadlineMs: number;
     readonly emit: EmitFn;
 };
 export type EnrichShapesArgs = {
     readonly shapes: readonly FileShape[];
     readonly session: AgentSession;
     readonly fs: WorkspaceFilesystem;
-    /** Omit the sandbox to skip container readouts; every other format still reads. */
-    readonly sandboxClient?: SandboxClient;
-    readonly sandbox?: SandboxRef;
+    /** Omit the lease to skip container readouts; every other format still reads. */
+    readonly lease?: BoundLease;
     /** Absolute in-sandbox path of the analysis root (`/{analysisId}`). */
     readonly mountRoot: string;
-    readonly deadlineMs: number;
     readonly emit: EmitFn;
 };
 /**

package/dist/input-scan/enrich.js

@@ -65,9 +65,9 @@ export async function readHeaders(args) {
             readouts.set(target.path, await readFromPrefix(args, target));
         }
     }));
-    const { sandboxClient, sandbox } = args;
-    if (containers.length > 0 && sandboxClient && sandbox) {
-        for (const [path, readout] of await decodeContainers(args, { sandboxClient, sandbox }, containers))
+    const { lease } = args;
+    if (containers.length > 0 && lease) {
+        for (const [path, readout] of await decodeContainers(args, lease, containers))
             readouts.set(path, readout);
     }
     return readouts;
@@ -118,7 +118,7 @@ const ReadoutLineSchema = z.object({
     fields: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
     unavailable: z.string().optional(),
 });
-async function decodeContainers(args, machine, containers) {
+async function decodeContainers(args, lease, containers) {
     const readouts = new Map();
     const source = await readFile(CONTAINER_DECODER, "utf8").catch(() => undefined);
     if (source === undefined) {
@@ -129,14 +129,18 @@ async function decodeContainers(args, machine, containers) {
     const byAbsolute = new Map();
     for (const target of containers)
         byAbsolute.set(`${args.mountRoot}/${target.path}`, target);
-    const result = await runSandboxExec({
-        sandboxClient: machine.sandboxClient,
-        sandbox: machine.sandbox,
+    const ran = await runSandboxExec({
+        lease,
         command: ["python3", "-c", source, ...byAbsolute.keys()],
         timeoutSeconds: ENRICH_TIMEOUT_SECONDS,
-        deadlineMs: args.deadlineMs,
         emit: args.emit,
     });
+    if (ran.isErr()) {
+        for (const { path } of containers)
+            readouts.set(path, { path, fields: {}, unavailable: ran.error.error });
+        return readouts;
+    }
+    const result = ran.value;
     for (const line of result.stdout.split("\n")) {
         const trimmed = line.trim();
         if (!trimmed.startsWith("{"))

package/dist/lib/hooks.d.ts

@@ -24,6 +24,11 @@ export type GateFailure = {
     readonly reason: string;
     /** True when the host asks the harness to suspend the work in place of a failure. */
     readonly suspend: boolean;
+    /**
+     * True when the host refuses the credential of the caller: it is expired, revoked, or absent. A person repairs
+     * it, thus a work that can pause waits for a resume. The suspend flag wins over it.
+     */
+    readonly credential?: boolean;
 };
 /**
  * The settlement a gate's `ResultAsync` resolves to, read structurally. An embedder whose neverthrow is
@@ -54,6 +59,10 @@ export type GateRefusal = {
     readonly kind: "suspended";
     readonly gate: GateName;
     readonly reason: string;
+} | {
+    readonly kind: "credential";
+    readonly gate: GateName;
+    readonly reason: string;
 };
 /**
  * The host can build its `Result` with its own copy of neverthrow. The helper

package/dist/lib/hooks.js

@@ -30,6 +30,11 @@ async function settlementOf(result) {
     }
     return await result;
 }
+function refusalKindOf(failure) {
+    if (failure.suspend)
+        return "suspended";
+    return failure.credential === true ? "credential" : "failed";
+}
 /**
  * The host can build its `Result` with its own copy of neverthrow. The helper
  * gives the outcome again as a `Result` of the copy of the harness. Thus the
@@ -41,7 +46,7 @@ export function passGate(gate, result) {
         const settled = await settlementOf(result);
         if (settlementOk(settled))
             return ok(settled.value);
-        return err({ kind: settled.error.suspend ? "suspended" : "failed", gate, reason: settled.error.reason });
+        return err({ kind: refusalKindOf(settled.error), gate, reason: settled.error.reason });
     })());
 }
 export async function deliverNotice(log, notice, result) {

package/dist/lib/markdown-pdf.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A PDF from markdown, on `marked` and `pdfmake`, with no browser.
+ *
+ * `marked` gives the token tree, and each token maps to a `pdfmake` node: a heading, a paragraph, a list, a GFM table,
+ * a code block, a quote, a rule, and an image. An SVG image, for example a chart of `render_chart`, lands as vector
+ * graphics. The text font is the Roboto that `pdfmake` ships, which holds the Greek letters and the common math signs.
+ *
+ * `pdfmake` resolves a font by a file path, also inside an SVG, thus the fonts land one time in a private temporary
+ * directory. Each URL is refused, and a local path is refused unless it is one of those font files, thus a document
+ * reads nothing that the caller did not give it.
+ */
+/** An image that a document embeds. The caller reads the bytes, thus the document reaches no file and no URL. */
+export type PdfImage = {
+    readonly kind: "svg";
+    readonly svg: string;
+} | {
+    readonly kind: "png" | "jpeg";
+    readonly bytes: Uint8Array;
+};
+/** The source of each image of a markdown text, in the order of the text. */
+export declare function markdownImageSources(markdown: string): string[];
+/** The PDF of a markdown text. `images` holds each image that the text names, by its source. */
+export declare function markdownToPdf(args: {
+    readonly markdown: string;
+    readonly title?: string;
+    readonly images: ReadonlyMap<string, PdfImage>;
+}): Promise<Uint8Array>;