@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/tools/lib/pubmed-client.d.ts

@@ -9,29 +9,29 @@
  * `.optional()`, not `.nullable()`.
  */
 import { type ArticleDetail, type ArticleSection, type FullTextResult, type PubmedSearchOptions, type PubMedSummary } from "../../literature/sources/pubmed.js";
-export type { PubMedSummary, ArticleDetail, ArticleSection, FullTextResult };
+export type { PubMedSummary, ArticleDetail, ArticleSection, FullTextResult } from "../../literature/sources/pubmed.js";
 export type SearchOptions = PubmedSearchOptions;
 /** PubMed search via esearch + esummary. */
 export declare function searchPubmed(ncbiApiKey: string | undefined, query: string, options?: SearchOptions, signal?: AbortSignal): Promise<{
     totalFound: number;
     results: PubMedSummary[];
 }>;
-export interface DetailOptions {
+export type DetailOptions = {
     /** Authors kept per article before collapsing the rest into `authorCount`. */
     maxAuthors?: number;
     /** MeSH terms kept per article; 0 drops the list entirely. */
     maxMeshTerms?: number;
-}
+};
 /**
  * One article as the tool returns it: `ArticleDetail` with the two unbounded
  * list fields trimmed. A consortium paper can carry hundreds of authors and
  * dozens of MeSH headings — neither is worth the context, so the counts travel
  * instead of the tails.
  */
-export interface BoundedArticleDetail extends ArticleDetail {
+export type BoundedArticleDetail = ArticleDetail & {
     authorCount: number;
     meshTermCount: number;
-}
+};
 /** Fetch full PubMed article details (efetch + ID Converter for PMC). */
 export declare function getArticleDetails(ncbiApiKey: string | undefined, pmids: string[], signal?: AbortSignal): Promise<{
     articles: ArticleDetail[];
@@ -39,19 +39,19 @@ export declare function getArticleDetails(ncbiApiKey: string | undefined, pmids:
 }>;
 /** Trim the two unbounded list fields on each article, recording their true sizes. */
 export declare function boundArticleDetails(articles: ArticleDetail[], options?: DetailOptions): BoundedArticleDetail[];
-export interface FullTextOptions {
+export type FullTextOptions = {
     /** Case-insensitive substring match against section headings. */
     sections?: string[];
     /** Character budget across the returned section bodies. */
     maxChars?: number;
-}
+};
 /**
  * A full text trimmed to a character budget. `outline` always lists EVERY
  * section in the article with its size and whether the body came back, so one
  * call is enough to decide which sections a follow-up should request — the
  * alternative is the agent guessing headings it has not seen.
  */
-export interface BoundedFullText {
+export type BoundedFullText = {
     fullText: string;
     sections: ArticleSection[];
     outline: {
@@ -62,7 +62,7 @@ export interface BoundedFullText {
     totalChars: number;
     returnedChars: number;
     truncated: boolean;
-}
+};
 /**
  * Fetch open-access full text from PMC, trimmed to a section filter and a
  * character budget. Returns null when the article is not open-access.

package/dist/tools/lib/pubmed-client.js

@@ -11,7 +11,7 @@
 import { createPubmedSource, } from "../../literature/sources/pubmed.js";
 function pubmedSource(ncbiApiKey) {
     return createPubmedSource({
-        ...(ncbiApiKey === undefined ? {} : { apiKey: ncbiApiKey }),
+        apiKey: ncbiApiKey,
         maxRetries: 3,
         retryDelayMs: 1_000,
         timeoutMs: 90_000,

package/dist/tools/lib/string-client.d.ts

@@ -8,15 +8,15 @@
  * `.nullable()`.
  */
 import { z } from "zod";
-export interface StringInteraction {
+export type StringInteraction = {
     proteinA: string;
     proteinB: string;
     score: number;
     experimentalScore?: number;
     databaseScore?: number;
     textminingScore?: number;
-}
-export interface StringEnrichment {
+};
+export type StringEnrichment = {
     category: string;
     term: string;
     description: string;
@@ -24,12 +24,12 @@ export interface StringEnrichment {
     fdr: number;
     geneCount: number;
     genes: string[];
-}
-export interface InteractionOptions {
+};
+export type InteractionOptions = {
     species?: number;
     minScore?: number;
     limit?: number;
-}
+};
 export declare const StringInteractionSchema: z.ZodPipe<z.ZodObject<{
     preferredName_A: z.ZodOptional<z.ZodString>;
     preferredName_B: z.ZodOptional<z.ZodString>;

package/dist/tools/lib/uniprot-client.d.ts

@@ -7,14 +7,14 @@
  * carries `.optional()`, not `.nullable()`.
  */
 import { z } from "zod";
-export interface UniProtRecord {
+export type UniProtRecord = {
     primaryAccession: string;
     uniProtkbId: string | null;
     geneNames: string[];
     chemblIds: string[];
     reactomePathwayIds: string[];
     proteinFamilyText: string | null;
-}
+};
 /**
  * Fetch a single UniProtKB entry by accession. Returns null on 404; throws
  * on other HTTP errors so callers can surface upstream outages.
@@ -25,7 +25,7 @@ export declare function getChemblIdsByUniProt(accession: string): Promise<string
 /** All Reactome pathway ids cross-referenced from a UniProt accession. */
 export declare function getReactomePathwaysByUniProt(accession: string): Promise<string[]>;
 /** One protein of a UniProtKB search. */
-export interface UniProtProtein {
+export type UniProtProtein = {
     accession: string;
     /** The UniProtKB ID, for example `BRCA1_HUMAN`. */
     uniProtkbId: string | null;
@@ -38,7 +38,7 @@ export interface UniProtProtein {
     subcellularLocations: string[];
     /** True for a Swiss-Prot entry, false for a TrEMBL entry. */
     reviewed: boolean;
-}
+};
 /**
  * One result row of `uniprotkb/search`, with the same all-optional discipline as
  * `UniProtRecordSchema`: UniProt omits the key of an absent value, thus every
@@ -131,19 +131,19 @@ export declare const UniProtSearchResponseSchema: z.ZodObject<{
  * never reach one, because the 400 fails the whole request.
  */
 export declare function isUniProtAccession(query: string): boolean;
-export interface SearchProteinsOptions {
+export type SearchProteinsOptions = {
     /** NCBI taxonomy id; omit to search every organism. */
     organismId?: number;
     /** Swiss-Prot only when true (the default), Swiss-Prot and TrEMBL when false. */
     reviewedOnly?: boolean;
     /** Max rows returned. */
     limit?: number;
-}
-export interface SearchProteinsResult {
+};
+export type SearchProteinsResult = {
     proteins: UniProtProtein[];
     /** True when UniProt held at least one row beyond `limit`. */
     hasMore: boolean;
-}
+};
 /**
  * Search UniProtKB for a protein by gene symbol or by accession.
  *

package/dist/tools/lib/uniprot-client.js

@@ -206,7 +206,10 @@ function toProtein(raw) {
         accession: raw.primaryAccession ?? "",
         uniProtkbId: raw.uniProtkbId ?? null,
         proteinName: extractProteinName(raw),
-        geneNames: (raw.genes ?? []).map((gene) => gene.geneName?.value).filter((name) => Boolean(name)),
+        geneNames: (raw.genes ?? []).flatMap((gene) => {
+            const name = gene.geneName?.value;
+            return name ? [name] : [];
+        }),
         sequenceLength: raw.sequence?.length ?? null,
         function: extractFunctionText(raw),
         subcellularLocations: extractSubcellularLocations(raw),
@@ -222,6 +225,7 @@ function toProtein(raw) {
  * that match this form. Thus the match decides only whether the `accession:`
  * clause is SAFE to send, never which space the query names.
  */
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the full UniProt accession grammar, both entry-class arms with the optional isoform suffix; the shape overlap with gene symbols is why the match decides safety only.
 const ACCESSION_RE = /^(?:[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9](?:[A-Z][A-Z0-9]{2}[0-9]){1,2})(?:-\d+)?$/i;
 /**
  * Can the query ride in an `accession:` clause?

package/dist/tools/memory/update-working-memory.d.ts

@@ -23,41 +23,44 @@
  * exists AND belongs to this analysis (`cortex_runs.analysis_id`) before it is
  * stored: an unknown runId is an `err(ToolError)` the model can correct from,
  * not a silent reference to a run that never existed.
+ *
+ * Inside a durable step, the store records the key of the step in the
+ * transaction of the edit. A rerun of the step after the edit, before its
+ * checkpoint, then changes nothing and gives ok.
  */
 import type { Pool } from "pg";
 import { z } from "zod";
 import type { WorkingMemoryStore } from "../../memory/working-memory.js";
+import { type Tool } from "../define-tool.js";
 declare const inputSchema: z.ZodObject<{
     section: z.ZodEnum<{
         constraint: "constraint";
+        finding: "finding";
         goal: "goal";
         hypothesis: "hypothesis";
-        finding: "finding";
     }>;
     operation: z.ZodOptional<z.ZodEnum<{
         add: "add";
-        revise: "revise";
         retire: "retire";
+        revise: "revise";
     }>>;
     text: z.ZodOptional<z.ZodString>;
     id: z.ZodOptional<z.ZodString>;
     origin: z.ZodOptional<z.ZodEnum<{
-        user: "user";
         agent: "agent";
+        user: "user";
     }>>;
     runId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 type Input = z.infer<typeof inputSchema>;
-interface UpdateOutput {
+type UpdateOutput = {
     readonly ok: true;
     readonly section: Input["section"];
-}
-export declare function createUpdateWorkingMemoryTool(workingMemory: WorkingMemoryStore, pool: Pool): import("../define-tool.js").Tool<{
-    section: "constraint" | "goal" | "hypothesis" | "finding";
-    operation?: "add" | "revise" | "retire" | undefined;
-    text?: string | undefined;
-    id?: string | undefined;
-    origin?: "user" | "agent" | undefined;
-    runId?: string | undefined;
-}, UpdateOutput>;
+};
+export type UpdateWorkingMemoryOpts = {
+    /** The key of the durable step that runs the call, `undefined` outside one. */
+    readonly stepKey: () => string | undefined;
+};
+export declare const DEFAULT_UPDATE_WORKING_MEMORY_OPTS: UpdateWorkingMemoryOpts;
+export declare function createUpdateWorkingMemoryTool(workingMemory: WorkingMemoryStore, pool: Pool, opts?: UpdateWorkingMemoryOpts): Tool<z.infer<typeof inputSchema>, UpdateOutput>;
 export {};

package/dist/tools/memory/update-working-memory.js

@@ -23,6 +23,10 @@
  * exists AND belongs to this analysis (`cortex_runs.analysis_id`) before it is
  * stored: an unknown runId is an `err(ToolError)` the model can correct from,
  * not a silent reference to a run that never existed.
+ *
+ * Inside a durable step, the store records the key of the step in the
+ * transaction of the edit. A rerun of the step after the edit, before its
+ * checkpoint, then changes nothing and gives ok.
  */
 import { err, ok } from "neverthrow";
 import { z } from "zod";
@@ -31,6 +35,7 @@ import { toThrowable, unwrapOrThrow } from "../../lib/result.js";
 import { isWorkingMemoryRejection, WORKING_MEMORY_LIMITS } from "../../memory/working-memory.js";
 import { queryRun } from "../../state/index.js";
 import { defineTool } from "../define-tool.js";
+import { durableStepKey } from "../workspace/edit-file.js";
 const { goalChars, entryChars, constraints, hypotheses, findings } = WORKING_MEMORY_LIMITS;
 const inputSchema = z
     .object({
@@ -91,10 +96,16 @@ const inputSchema = z
 function toListOp(input) {
     switch (input.operation ?? "add") {
         case "add":
+            if (input.text === undefined)
+                throw new Error("add requires text");
             return { op: "add", text: input.text };
         case "revise":
+            if (input.id === undefined || input.text === undefined)
+                throw new Error("revise requires id and text");
             return { op: "revise", id: input.id, text: input.text };
         case "retire":
+            if (input.id === undefined)
+                throw new Error("retire requires id");
             return { op: "retire", id: input.id };
     }
 }
@@ -105,12 +116,17 @@ function toConstraintOp(input) {
 /** As `toListOp`, but an added finding also carries the run it is attributed to. */
 function toFindingOp(input) {
     const base = toListOp(input);
-    return base.op === "add" ? { ...base, runId: input.runId } : base;
+    if (base.op !== "add")
+        return base;
+    if (input.runId === undefined)
+        throw new Error("a finding add requires runId");
+    return { ...base, runId: input.runId };
 }
-export function createUpdateWorkingMemoryTool(workingMemory, pool) {
+export const DEFAULT_UPDATE_WORKING_MEMORY_OPTS = { stepKey: durableStepKey };
+export function createUpdateWorkingMemoryTool(workingMemory, pool, opts = DEFAULT_UPDATE_WORKING_MEMORY_OPTS) {
     /** Write one amendment, mapping a refused write to a model-visible error. */
     async function apply(analysisId, section, value) {
-        const written = await workingMemory.updateSection(analysisId, section, value);
+        const written = await workingMemory.updateSection(analysisId, section, value, opts.stepKey());
         if (written.isErr()) {
             // A refused write (cap hit, unknown id) is an expected outcome the model
             // can act on — its message carries the remedy. A DbError is not: it throws,
@@ -161,6 +177,8 @@ export function createUpdateWorkingMemoryTool(workingMemory, pool) {
             const analysisId = scopeResource(ctx.session.scope).resourceId;
             switch (input.section) {
                 case "goal":
+                    if (input.text === undefined)
+                        throw new Error("goal requires text");
                     return apply(analysisId, "goal", { text: input.text });
                 case "constraint":
                     return apply(analysisId, "constraint", toConstraintOp(input));

package/dist/tools/read-tool-output.js

@@ -2,6 +2,8 @@
  * `read_tool_output` — reads the kept text of a tool result that the loop cut, by a window or by a pattern.
  * Each result stays under the cap of the loop, thus the loop never cuts a result of this tool.
  */
+import { errorMessageOf } from "../lib/thrown.js";
+import { textOf } from "../lib/unknown-text.js";
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { unwrapOrThrow } from "../lib/result.js";
@@ -61,10 +63,11 @@ function page(ref, text, start, limit) {
 function search(ref, text, start, limit, pattern) {
     let regex;
     try {
+        // oxlint-disable-next-line eslint-js/no-restricted-syntax -- the caller-supplied search pattern is the tool's input; the dynamic form is the feature, and an invalid pattern is the handled error below.
         regex = new RegExp(pattern, "g");
     }
     catch (err) {
-        return { status: "invalid_pattern", pattern, error: err instanceof Error ? err.message : String(err) };
+        return { status: "invalid_pattern", pattern, error: errorMessageOf(err) ?? textOf(err) };
     }
     const stop = limit === undefined ? text.length : windowEnd(text, start, limit);
     const window = text.slice(start, stop);
@@ -97,7 +100,10 @@ function search(ref, text, start, limit, pattern) {
     });
     let result = at(end);
     while (!fits(result) && matches.length > 1) {
-        end = matches.pop().offset;
+        const dropped = matches.pop();
+        if (dropped === undefined)
+            break;
+        end = dropped.offset;
         result = at(end);
     }
     return result;

package/dist/tools/registry.d.ts

@@ -6,10 +6,10 @@
  */
 import { type ToolSet } from "ai";
 import type { Tool } from "./define-tool.js";
-export interface Registry {
+export type Registry = {
     /** The AI SDK tool definitions to send with a chat request. */
     definitions(): ToolSet;
     /** Resolve a tool by name for dispatch; `undefined` if unknown. */
     get(name: string): Tool | undefined;
-}
+};
 export declare function createRegistry(tools: readonly Tool[]): Registry;

package/dist/tools/report-authoring/authoring-tools.d.ts

@@ -15,12 +15,17 @@
  *
  * The primitive admits a flat object input only. Thus a destination is four optional fields, and not a
  * nested union. A conflict between the flat fields refuses before the core runs.
+ *
+ * Inside a durable step, a mutation stores its result for the thread and the step, in the transaction of
+ * the document and under the lock of the row. A rerun of the step after the landing, before its
+ * checkpoint, gives the stored result. Thus a rerun of `add_block` does not refuse its own block id, and a
+ * rerun of `remove_block` does not refuse its own removed target.
  */
 import { type Result } from "neverthrow";
 import { z } from "zod";
 import type { Scope } from "../../auth/types.js";
 import type { Logger } from "../../lib/logger.js";
-import { type ProvenanceSeam } from "../../provenance/seam.js";
+import { type ProvenanceSeam, type SessionProvenanceEvent } from "../../provenance/seam.js";
 import { type DraftRefusal } from "../../report-model/draft-operations.js";
 import { type OutlineEntry, type ReadableBlock } from "../../report-model/draft-read.js";
 import type { ReportWarning } from "../../report-model/block-walk.js";
@@ -81,11 +86,11 @@ export type ReadBlockInput = z.infer<typeof readBlockInput>;
 export type SetTitleInput = z.infer<typeof setTitleInput>;
 export type FinishDraftInput = z.infer<typeof finishDraftInput>;
 /** One container that an operation changed, and the child order inside it after the operation. */
-export interface ChangedContainer {
+export type ChangedContainer = {
     /** The section that holds the children. It is absent when the container is the root. */
     parentId?: string;
     children: OutlineEntry[];
-}
+};
 /**
  * The closed set of tool-layer refusal reasons.
  *
@@ -105,10 +110,10 @@ export type SessionRefusalReason = "no-thread-scope" | "absent-state" | "wrong-t
  * state, or a gateway that cannot give the state. It sits beside the core `DraftRefusal`, and it never
  * widens the closed reason set of the core.
  */
-export interface SessionRefusal {
+export type SessionRefusal = {
     reason: SessionRefusalReason;
     detail: string;
-}
+};
 /**
  * The result of a mutation tool. A refusal carries the typed reason, from the core or from the tool layer.
  *
@@ -120,13 +125,15 @@ export interface SessionRefusal {
  *
  * A move across two containers reports both. An operation that changes no child order reports none.
  */
-export type MutationResult = {
-    applied: true;
-    changed: ChangedContainer[];
-} | {
+export type MutationResult = LandedResult | {
     applied: false;
     refusal: DraftRefusal | SessionRefusal;
 };
+/** The result of a mutation that landed its document. A durable step stores it, and a rerun of the step gives it again. */
+export type LandedResult = {
+    applied: true;
+    changed: ChangedContainer[];
+};
 /** The result of `read_outline`. A load that gives no state refuses instead of an outline. */
 export type OutlineResult = {
     outline: OutlineEntry[];
@@ -160,10 +167,10 @@ export type FinishToolResult = {
     refused: SessionRefusal;
 };
 /** The state of one report thread: the document under composition, and the frozen snapshot. */
-export interface ReportSessionState {
+export type ReportSessionState = {
     readonly document: DraftDocument;
     readonly snapshot: ReportSnapshot;
-}
+};
 /**
  * The concurrency token that a load hands out and a persist compares against. It is the prior document
  * that the load read, or `null` before the first document lands. The persist lands only when the row still
@@ -191,6 +198,8 @@ export type SessionStateLoad = {
     token: SessionStateToken;
     seenDocumentHash: string | null;
     derivations: readonly DerivationRecord[];
+    /** The stored result of the call that the load names, when an earlier run of that call landed. */
+    landed?: unknown;
 } | {
     outcome: "absent";
 } | {
@@ -200,15 +209,31 @@ export type SessionStateLoad = {
     outcome: "failed";
     detail: string;
 };
-/** The outcome of a gateway persist. `conflict` means that a concurrent turn landed first. */
+/**
+ * The outcome of a gateway persist. `conflict` means that a concurrent turn landed first. `replayed` means
+ * that an earlier run of the call landed, and it carries the stored result of that run.
+ */
 export type SessionStatePersist = {
     outcome: "persisted";
 } | {
     outcome: "conflict";
+} | {
+    outcome: "replayed";
+    landed: unknown;
 } | {
     outcome: "failed";
     detail: string;
 };
+/**
+ * The authoring call of a persist: the key of its durable step, and the result that it gives when the document lands.
+ * The result carries the events of the act, thus a rerun that finds the result can emit them again.
+ */
+export type LandingCall = {
+    readonly key: string;
+    readonly result: LandedResult & {
+        readonly events: readonly SessionProvenanceEvent[];
+    };
+};
 /**
  * The outcome of a gateway stamp. `stamped` wrote the marker. `absent` means that no row holds the thread.
  * `failed` is a transient store fault that names its cause. Each arm is plain data, thus a stamp never
@@ -246,9 +271,11 @@ export type SeenStampResult = {
  * the gateway over the durable store. A load gives the state, a typed absence, or a typed failure. A
  * persist gives success, or a typed failure.
  */
-export interface ReportSessionStateGateway {
-    load(threadId: string): Promise<SessionStateLoad>;
-    persist(threadId: string, document: DraftDocument, expected: SessionStateToken): Promise<SessionStatePersist>;
+export type ReportSessionStateGateway = {
+    /** `callKey` names the durable step of a mutation, and the found load then carries the stored result of an earlier run. */
+    load(threadId: string, callKey?: string): Promise<SessionStateLoad>;
+    /** A persist with a `call` stores the result of the call in the transaction of the document. */
+    persist(threadId: string, document: DraftDocument, expected: SessionStateToken, call?: LandingCall): Promise<SessionStatePersist>;
     /**
      * Stamp the hash of the rendered draft on the session state. The preview calls it when the page lands,
      * thus the runtime knows which draft the page shows.
@@ -260,12 +287,12 @@ export interface ReportSessionStateGateway {
      * rendered hash existed to copy, thus the eyes tell a real stamp from a missed one.
      */
     stampSeen(threadId: string): Promise<SeenStampResult>;
-}
+};
 /**
  * The thread of a call, its analysis, the loaded state, the concurrency token that the persist compares
  * against, the seen-document hash of the look-before-record rule, and the derivations of the session.
  */
-export interface OpenedThread {
+export type OpenedThread = {
     readonly threadId: string;
     readonly analysisId: string;
     readonly state: ReportSessionState;
@@ -274,7 +301,9 @@ export interface OpenedThread {
     readonly seenDocumentHash: string | null;
     /** The derivations of the session, in the order that the records landed. */
     readonly derivations: readonly DerivationRecord[];
-}
+    /** The stored result of an earlier run of the call that the open names. */
+    readonly landed?: unknown;
+};
 /**
  * Resolve the report thread of a call, and load its state through the gateway.
  *
@@ -290,9 +319,9 @@ export interface OpenedThread {
  * The authoring tools and the preview tool share this one resolution, thus the two surfaces accept the
  * same thread id and map a load outcome onto a refusal the same way.
  */
-export declare function openReportThread(gateway: ReportSessionStateGateway, scope: Scope): Promise<Result<OpenedThread, SessionRefusal>>;
+export declare function openReportThread(gateway: ReportSessionStateGateway, scope: Scope, callKey?: string): Promise<Result<OpenedThread, SessionRefusal>>;
 /** The eight authoring tools. */
-export interface ReportAuthoringTools {
+export type ReportAuthoringTools = {
     readonly add_block: Tool<AddBlockInput, MutationResult>;
     readonly change_block: Tool<ChangeBlockInput, MutationResult>;
     readonly remove_block: Tool<RemoveBlockInput, MutationResult>;
@@ -301,17 +330,19 @@ export interface ReportAuthoringTools {
     readonly read_outline: Tool<ReadOutlineInput, OutlineResult>;
     readonly read_block: Tool<ReadBlockInput, ReadBlockResult>;
     readonly finish_draft: Tool<FinishDraftInput, FinishToolResult>;
-}
+};
 /**
  * The optional deps of the authoring surface. The gateway is the one mandatory part, thus it stays a
  * parameter of its own and this bag holds what a composition can leave out.
  */
-export interface ReportAuthoringToolDeps {
+export type ReportAuthoringToolDeps = {
     /** The provenance seam; an unbound session emit emits nothing and each tool acts the same. */
     readonly provenance?: ProvenanceSeam;
     /** Operational logging seam; omitted falls back to no-op. */
     readonly logger?: Logger;
-}
+    /** The key of the durable step that runs the call, `undefined` outside one. Defaults to {@link durableStepKey}. */
+    readonly stepKey?: () => string | undefined;
+};
 /**
  * Make the eight authoring tools over a session-state gateway.
  *