@inflexa-ai/harness 0.35.5 → 0.35.7

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

@@ -105,3 +105,193 @@ export async function getReactomePathwaysByUniProt(accession) {
     const rec = await getUniProtRecord(accession);
     return rec?.reactomePathwayIds ?? [];
 }
+/**
+ * The field list of the search. It is separate from `FIELDS` on purpose:
+ * `FIELDS` feeds `getUniProtRecord` and the target-assessment dossier, thus a
+ * widening of it would change what that workflow reads.
+ */
+const SEARCH_FIELDS = ["accession", "id", "protein_name", "gene_names", "length", "cc_function", "cc_subcellular_location"].join(",");
+/** A FUNCTION comment runs to several hundred words; this is what one answer carries. */
+const MAX_FUNCTION_CHARS = 1200;
+/**
+ * `entryType` reads `UniProtKB reviewed (Swiss-Prot)` or
+ * `UniProtKB unreviewed (TrEMBL)`. The unreviewed value HOLDS the reviewed one
+ * as a substring, thus the negative test must run first. A test for `reviewed`
+ * alone answers true for every entry of either kind.
+ */
+const REVIEWED_ENTRY_TYPE = "reviewed";
+const UNREVIEWED_ENTRY_TYPE = "unreviewed";
+/** Is the entry a curated Swiss-Prot record, as opposed to a machine-annotated TrEMBL one? */
+function isReviewedEntry(entryType) {
+    const value = (entryType ?? "").toLowerCase();
+    if (value.includes(UNREVIEWED_ENTRY_TYPE))
+        return false;
+    return value.includes(REVIEWED_ENTRY_TYPE);
+}
+const SearchCommentSchema = z.object({
+    commentType: z.string().optional(),
+    texts: z.array(z.object({ value: z.string().optional() })).optional(),
+    subcellularLocations: z.array(z.object({ location: z.object({ value: z.string().optional() }).optional() })).optional(),
+});
+const ProteinNameSchema = z.object({ fullName: z.object({ value: z.string().optional() }).optional() });
+/**
+ * One result row of `uniprotkb/search`, with the same all-optional discipline as
+ * `UniProtRecordSchema`: UniProt omits the key of an absent value, thus every
+ * field carries `.optional()` and none carries `.nullable()`.
+ *
+ * A TrEMBL row can carry `submissionNames` in place of `recommendedName`
+ * (`X5D778` is one), thus the name reader falls back rather than reporting the
+ * protein as unnamed.
+ */
+export const UniProtSearchResultSchema = z.object({
+    primaryAccession: z.string().optional(),
+    uniProtkbId: z.string().optional(),
+    entryType: z.string().optional(),
+    proteinDescription: z
+        .object({
+        recommendedName: ProteinNameSchema.optional(),
+        submissionNames: z.array(ProteinNameSchema).optional(),
+    })
+        .optional(),
+    genes: z.array(z.object({ geneName: z.object({ value: z.string().optional() }).optional() })).optional(),
+    sequence: z.object({ length: z.number().optional() }).optional(),
+    comments: z.array(SearchCommentSchema).optional(),
+});
+/** The search envelope. It is exported so that the golden-fixture table drives it. */
+export const UniProtSearchResponseSchema = z.object({
+    results: z.array(UniProtSearchResultSchema).optional(),
+});
+/** Read the protein name, preferring the recommended name over a submitted one. */
+function extractProteinName(raw) {
+    const description = raw.proteinDescription;
+    const recommended = description?.recommendedName?.fullName?.value?.trim();
+    if (recommended)
+        return recommended;
+    for (const submitted of description?.submissionNames ?? []) {
+        const value = submitted.fullName?.value?.trim();
+        if (value)
+            return value;
+    }
+    return null;
+}
+/** Read the first FUNCTION comment, capped at {@link MAX_FUNCTION_CHARS}. */
+function extractFunctionText(raw) {
+    for (const comment of raw.comments ?? []) {
+        if (comment.commentType !== "FUNCTION")
+            continue;
+        for (const text of comment.texts ?? []) {
+            const value = text.value?.trim();
+            if (value)
+                return value.length > MAX_FUNCTION_CHARS ? `${value.slice(0, MAX_FUNCTION_CHARS)}…` : value;
+        }
+    }
+    return null;
+}
+/**
+ * Read the distinct subcellular locations. UniProt splits them over more than
+ * one SUBCELLULAR LOCATION comment, and it repeats a location across them, thus
+ * the reader collects across every comment and keeps the first occurrence only.
+ */
+function extractSubcellularLocations(raw) {
+    const locations = [];
+    const seen = new Set();
+    for (const comment of raw.comments ?? []) {
+        if (comment.commentType !== "SUBCELLULAR LOCATION")
+            continue;
+        for (const entry of comment.subcellularLocations ?? []) {
+            const value = entry.location?.value?.trim();
+            if (!value || seen.has(value))
+                continue;
+            seen.add(value);
+            locations.push(value);
+        }
+    }
+    return locations;
+}
+function toProtein(raw) {
+    return {
+        accession: raw.primaryAccession ?? "",
+        uniProtkbId: raw.uniProtkbId ?? null,
+        proteinName: extractProteinName(raw),
+        geneNames: (raw.genes ?? []).map((gene) => gene.geneName?.value).filter((name) => Boolean(name)),
+        sequenceLength: raw.sequence?.length ?? null,
+        function: extractFunctionText(raw),
+        subcellularLocations: extractSubcellularLocations(raw),
+        reviewed: isReviewedEntry(raw.entryType),
+    };
+}
+/**
+ * The accession forms that UniProt itself documents: the six-character form and
+ * the ten-character form, with an optional isoform suffix.
+ *
+ * The shape does NOT tell an accession from a gene symbol, because the two
+ * spaces overlap: `P2RY12`, `B3GAT1`, and their siblings are real gene symbols
+ * that match this form. Thus the match decides only whether the `accession:`
+ * clause is SAFE to send, never which space the query names.
+ */
+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?
+ *
+ * UniProt validates the value of that clause, and it answers HTTP 400 for a
+ * value that is not accession-shaped. Thus a plain symbol such as `BRCA1` must
+ * never reach one, because the 400 fails the whole request.
+ */
+export function isUniProtAccession(query) {
+    return ACCESSION_RE.test(query.trim());
+}
+/**
+ * Build the UniProtKB query.
+ *
+ * The organism filter and the reviewed filter narrow an ambiguous SYMBOL
+ * search. An accession is a unique key, thus the filters must not reach it: a
+ * lookup of `P02769` under the human default would otherwise answer nothing,
+ * although the accession names bovine serum albumin.
+ *
+ * An accession-shaped input is ambiguous, because the two identifier spaces
+ * overlap. Such an input searches both, and the unfiltered accession clause is
+ * OR-ed with the filtered symbol clause. An input that is not
+ * accession-shaped searches the symbol space alone.
+ *
+ * The accession side carries `active:true`, and that is the one filter it
+ * takes. A deleted accession still answers an `accession:` query, as an
+ * `Inactive` row with no name and no function, and `UniProtProtein` has no
+ * field for the deletion reason. `B3GAT1` is such a case: the gene symbol also
+ * names a deleted TrEMBL accession, thus without the filter the answer holds
+ * the human protein and a hollow second row.
+ */
+function buildSearchQuery(query, organismId, reviewedOnly) {
+    const symbolClauses = [`gene_exact:${query}`];
+    if (organismId !== undefined)
+        symbolClauses.push(`organism_id:${organismId}`);
+    if (reviewedOnly)
+        symbolClauses.push("reviewed:true");
+    const symbolQuery = symbolClauses.join(" AND ");
+    if (!isUniProtAccession(query))
+        return symbolQuery;
+    return `((accession:${query} AND active:true) OR (${symbolQuery}))`;
+}
+/**
+ * Search UniProtKB for a protein by gene symbol or by accession.
+ *
+ * An unknown query is HTTP 200 with `{"results":[]}`, never a 404, thus the
+ * empty result is an ordinary answer and never an error. The request asks for
+ * one row beyond `limit`, because UniProt reports its match count in the
+ * `x-total-results` header and `apiFetch` exposes no header. The extra row is
+ * what separates a trimmed answer from a complete one.
+ */
+export async function searchProteins(query, opts = {}) {
+    const { organismId, reviewedOnly = true, limit = 10 } = opts;
+    const trimmed = query.trim();
+    const params = new URLSearchParams({
+        query: buildSearchQuery(trimmed, organismId, reviewedOnly),
+        fields: SEARCH_FIELDS,
+        format: "json",
+        size: String(limit + 1),
+    });
+    const res = await apiFetchValidated(`${UNIPROT_BASE}/uniprotkb/search?${params.toString()}`, UniProtSearchResponseSchema, { headers: UNIPROT_HEADERS });
+    if (res.isErr())
+        throw new Error(describeApiError(res.error));
+    const rows = res.value.results ?? [];
+    return { proteins: rows.slice(0, limit).map(toProtein), hasMore: rows.length > limit };
+}

package/dist/tools/research/literature-reviewer.js

@@ -26,6 +26,7 @@ import { createChemDbTools, createNcbiTools } from "../bio/keys.js";
 import { genePreclinicalProfileTool } from "../bio/gene-preclinical-profile.js";
 import { lookupAnnotationTool } from "../bio/lookup-annotation.js";
 import { searchGeneTool } from "../bio/search-gene.js";
+import { searchProteinTool } from "../bio/search-protein.js";
 import { searchInteractionsTool } from "../bio/search-interactions.js";
 import { createResolveCitationTool } from "./resolve-citation.js";
 /** Sub-agent identity — appended to `callPath`, set as `agentId`. */
@@ -38,6 +39,7 @@ export function createLiteratureReviewerTool(deps) {
     const chemDb = createChemDbTools(deps.bioKeys, { ...(deps.logger ? { logger: deps.logger } : {}) });
     const reviewerTools = [
         searchGeneTool,
+        searchProteinTool,
         lookupAnnotationTool,
         searchInteractionsTool,
         ncbi.pubmed,

package/dist/tools/sandbox/list-available-packages.d.ts

@@ -116,6 +116,31 @@ export type ListAvailablePackagesDeps = Pick<EnvironmentStorePaths, "farmLockFil
      */
     readonly linkToolPresent?: boolean;
 };
+/**
+ * What one inventory read produced: the sections of the bound source, or the
+ * fact that the source cannot answer, with the reason where the source gives
+ * one. There is no empty-on-error shape — an unreadable inventory must stay
+ * distinguishable from an inventory that holds nothing, and a caller that
+ * cannot tell them apart reports a present package as absent.
+ */
+export type InventoryRead = {
+    readonly kind: "sections";
+    readonly sections: readonly Section[];
+} | {
+    readonly kind: "unavailable";
+    readonly reason?: string;
+};
+/**
+ * Read the inventory of the bound source: the pool-scope reader when the
+ * embedder binds one (a conversation or planning surface), the first readable
+ * farm `inflexa.lock` otherwise (a sandbox agent). The image record merges
+ * into either report.
+ *
+ * Every caller that resolves a name against the environment reads through
+ * here, thus the census a model sees and the check a launch runs never
+ * disagree about what the source holds.
+ */
+export declare function readInventorySections(deps: ListAvailablePackagesDeps): Promise<InventoryRead>;
 /**
  * Create the package inventory over the bound source: the pool-scope reader
  * when the embedder binds one (a conversation or planning surface), the

package/dist/tools/sandbox/list-available-packages.js

@@ -390,6 +390,50 @@ export function queryPackages(rawSections, { names, query, language, limit }) {
     const { content, returned } = renderListing(filtered, limit ?? DEFAULT_LIMIT, bothTrackNames(sections));
     return { available: true, total, returned, hasMore: returned < total, content };
 }
+/**
+ * Read the inventory of the bound source: the pool-scope reader when the
+ * embedder binds one (a conversation or planning surface), the first readable
+ * farm `inflexa.lock` otherwise (a sandbox agent). The image record merges
+ * into either report.
+ *
+ * Every caller that resolves a name against the environment reads through
+ * here, thus the census a model sees and the check a launch runs never
+ * disagree about what the source holds.
+ */
+export async function readInventorySections(deps) {
+    // The image record merges in when the host can read a valid one. An absent
+    // record and an invalid record both merge nothing, and neither is an
+    // error: the record is an enrichment, and the farm or pool inventory stays
+    // whole without it. A store packed before the record existed carries none.
+    // There is no logger here, thus an invalid record cannot be reported — the
+    // schema of the harness refuses it, and the report degrades to the tracks
+    // that it could read.
+    const recordSections = readImagePackagesFile(deps.imagePackagesFile ?? DEFAULT_IMAGE_PACKAGES_FILE)
+        .map(imageSections)
+        .unwrapOr([]);
+    if (deps.readPoolInventory) {
+        const pool = await deps.readPoolInventory().catch((cause) => ({
+            kind: "unavailable",
+            reason: cause instanceof Error ? cause.message : String(cause),
+        }));
+        if (pool.kind === "unavailable")
+            return { kind: "unavailable", reason: pool.reason };
+        return { kind: "sections", sections: [...pool.sections, ...recordSections] };
+    }
+    // Both farm container paths are tried when the host injects none, because
+    // the path keys on the declared toolchain and this read carries none.
+    let lock = null;
+    for (const candidate of deps.farmLockFile ? [deps.farmLockFile] : DEFAULT_FARM_LOCK_FILES) {
+        lock = readFarmLockFile(candidate).unwrapOr(null);
+        if (lock !== null)
+            break;
+    }
+    // A lock that no candidate path holds is an absence with no reason to
+    // report: the read never got far enough to learn one.
+    if (lock === null)
+        return { kind: "unavailable" };
+    return { kind: "sections", sections: [...lockSections(lock), ...recordSections] };
+}
 /**
  * Create the package inventory over the bound source: the pool-scope reader
  * when the embedder binds one (a conversation or planning surface), the
@@ -397,8 +441,6 @@ export function queryPackages(rawSections, { names, query, language, limit }) {
  * record merges into either report.
  */
 export function createListAvailablePackagesTool(deps = {}) {
-    const lockCandidates = deps.farmLockFile ? [deps.farmLockFile] : DEFAULT_FARM_LOCK_FILES;
-    const imagePackagesFile = deps.imagePackagesFile ?? DEFAULT_IMAGE_PACKAGES_FILE;
     const readPoolInventory = deps.readPoolInventory;
     // The scope decides the framing sentence: a sandbox agent reads what it can
     // import NOW, and a conversation surface reads what the store HOLDS — a
@@ -461,38 +503,18 @@ export function createListAvailablePackagesTool(deps = {}) {
             return "full package list";
         },
         execute: async (input) => {
-            // The image record merges in when the host can read a valid one.
-            // An absent record and an invalid record both merge nothing, and
-            // neither is an error: the record is an enrichment, and the farm
-            // or pool inventory stays whole without it. A store packed before
-            // the record existed carries none. The tool holds no logger, thus
-            // an invalid record cannot be reported here — the schema of the
-            // harness refuses it, and the report degrades to the tracks it
-            // could read.
-            const recordSections = readImagePackagesFile(imagePackagesFile).map(imageSections).unwrapOr([]);
+            const read = await readInventorySections(deps);
             // An unreadable inventory is an expected environment state — model it as an
             // `available: false` data variant telling the caller the set is UNKNOWN,
             // WITH the reason: without it, a structural fault (a damaged dependency
             // graph) reads as a transient flake, and the caller retries for ever.
-            if (readPoolInventory) {
-                const pool = await readPoolInventory().catch((cause) => ({
-                    kind: "unavailable",
-                    reason: cause instanceof Error ? cause.message : String(cause),
-                }));
-                if (pool.kind === "unavailable")
-                    return ok({ available: false, content: `${POOL_UNAVAILABLE_NOTE} The reason: ${pool.reason}.` });
-                return ok(queryPackages([...pool.sections, ...recordSections], input));
-            }
-            let lock = null;
-            for (const candidate of lockCandidates) {
-                lock = readFarmLockFile(candidate).unwrapOr(null);
-                if (lock !== null)
-                    break;
-            }
-            if (lock === null) {
-                return ok({ available: false, content: UNAVAILABLE_NOTE });
+            // The note follows the vantage of the bound source, because a
+            // conversation surface has no runtime to probe.
+            if (read.kind === "unavailable") {
+                const note = readPoolInventory ? POOL_UNAVAILABLE_NOTE : UNAVAILABLE_NOTE;
+                return ok({ available: false, content: read.reason === undefined ? note : `${note} The reason: ${read.reason}.` });
             }
-            return ok(queryPackages([...lockSections(lock), ...recordSections], input));
+            return ok(queryPackages(read.sections, input));
         },
     });
 }

package/dist/workflows/sandbox-step.js

@@ -34,6 +34,7 @@ import { unwrapOrThrow } from "../lib/result.js";
 import { isBudgetExceeded } from "../loop/budget-exceeded.js";
 import { runAgent } from "../loop/run-agent.js";
 import { durableStep } from "../loop/run-step.js";
+import { lastExecOutcome } from "../sandbox/exec-outcome.js";
 import { activityForTool, applyTreeDelta, isChatDataPart, sandboxTreeDelta, stepPartId } from "../sandbox/sandbox-step-translate.js";
 import { createDetailResolver } from "../tools/detail-resolver.js";
 import { forSubAgent } from "../auth/types.js";
@@ -274,8 +275,15 @@ export async function runSandboxStepBody(input, deps) {
         // The scrub below is deliberate and load-bearing, which makes this record
         // the ONLY account of why the step died — the thrown error carries just the
         // generic phrase, so nothing downstream can reconstruct the cause.
+        // `durationMs`, the iteration cap, and the last exec of the sandbox are
+        // what separate a step that died in the model from one that died in the
+        // machine. `lastExec` holds no stream text (see `exec-outcome.ts`).
+        const lastExec = lastExecOutcome(sandbox.sandboxId);
         logger.error("step failure", {
             errorClass,
+            durationMs,
+            hitMaxSteps,
+            ...(lastExec ? { lastExec } : {}),
             ...logger.errorFields(err),
         });
         const safe = userFacingStepFailure(errorClass);
@@ -341,7 +349,8 @@ export async function runSandboxStepBody(input, deps) {
     const neverAbort = new AbortController().signal;
     let transcript;
     let finishReason;
-    let hitMaxSteps;
+    // `false` until the loop reports otherwise: a loop that throws never reached its cap.
+    let hitMaxSteps = false;
     let stepUsage;
     try {
         const agentResult = await runAgent(agent, initial, session, {

package/dist/workflows/target-assessment/progress-stream.d.ts

@@ -0,0 +1,75 @@
+/**
+ * TargetAssessmentProgressStream — the read side of a target assessment's
+ * durable progress stream.
+ *
+ * `emitProgress` (the sibling `progress.ts`) writes one part per phase
+ * transition and nothing reads it back, so an embedder that wants to show a
+ * user how far an assessment has got had to reach for the durability engine
+ * itself. This seam is that read, and it quarantines the engine the way
+ * `RunLauncher` does for starting workflows: the delivered value is the
+ * harness's own `TargetAssessmentProgressEvent` contract type, and no engine
+ * type appears in the exported signature.
+ *
+ * It is far simpler than `execution/run-event-stream.ts`, and deliberately so.
+ * A run fans out over a parent workflow and every sandbox-step child, each
+ * writing its own stream, so that seam polls a ledger to discover children and
+ * folds reconciling parts before delivery. A target assessment writes progress
+ * from the parent body alone, under `workflowID === assessmentId`. One stream,
+ * no discovery, no pool.
+ *
+ * It is a push subscription rather than a returned iterator because handing the
+ * engine's async generator back to a caller would put the engine's model on the
+ * very surface this seam exists to remove, and would leave nowhere to contain a
+ * failure. A handler gives both, and matches the `EmitFn` idiom the writer side
+ * already speaks.
+ */
+import { type TargetAssessmentProgressEvent } from "@inflexa-ai/harness/contracts/target-dossier.js";
+import type { Logger } from "../../lib/logger.js";
+/**
+ * Construction-time dependencies. 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 TargetAssessmentProgressStreamDeps {
+    readonly logger?: Logger;
+}
+/**
+ * Receives one progress event. May be async — the subscription awaits it, so a
+ * handler is never invoked concurrently with itself. A throw is logged and
+ * swallowed.
+ */
+export type TargetAssessmentProgressHandler = (event: TargetAssessmentProgressEvent) => void | Promise<void>;
+/** Call-time parameters of one subscription. */
+export interface TargetAssessmentProgressSubscribeOptions {
+    /** The assessment to observe. Also the workflow's id — TA sets the two equal. */
+    readonly assessmentId: string;
+    /** Where each delivered event goes. */
+    readonly onEvent: TargetAssessmentProgressHandler;
+    /** Aborting stops delivery and settles the returned promise. */
+    readonly signal: AbortSignal;
+}
+/**
+ * The progress read seam. One method, because an assessment-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 TargetAssessmentProgressStream {
+    /**
+     * Deliver every progress event the assessment produces to `onEvent`,
+     * resolving when the assessment's stream drains or when the signal aborts.
+     *
+     * The stream drains when the workflow stops being active. A workflow that
+     * self-cancels on a 402 is no longer active, so the stream drains at the
+     * `suspended` phase and this settles there — it does NOT wait for a later
+     * `DBOS.resumeWorkflow`. Re-opening across a resume would mean polling the
+     * row's status, which is the caller's business, not this seam's.
+     *
+     * Events arrive in the order the workflow wrote them, each exactly once.
+     * There is no fold: the body emits each phase once and the engine caches a
+     * step's stream-write offset, so a recovered workflow does not re-write one.
+     * A fold would collapse nothing and cost a buffer.
+     */
+    subscribe(options: TargetAssessmentProgressSubscribeOptions): Promise<void>;
+}
+/** Build the DBOS-backed realization of {@link TargetAssessmentProgressStream}. */
+export declare function createTargetAssessmentProgressStream(deps?: TargetAssessmentProgressStreamDeps): TargetAssessmentProgressStream;

package/dist/workflows/target-assessment/progress-stream.js

@@ -0,0 +1,110 @@
+/**
+ * TargetAssessmentProgressStream — the read side of a target assessment's
+ * durable progress stream.
+ *
+ * `emitProgress` (the sibling `progress.ts`) writes one part per phase
+ * transition and nothing reads it back, so an embedder that wants to show a
+ * user how far an assessment has got had to reach for the durability engine
+ * itself. This seam is that read, and it quarantines the engine the way
+ * `RunLauncher` does for starting workflows: the delivered value is the
+ * harness's own `TargetAssessmentProgressEvent` contract type, and no engine
+ * type appears in the exported signature.
+ *
+ * It is far simpler than `execution/run-event-stream.ts`, and deliberately so.
+ * A run fans out over a parent workflow and every sandbox-step child, each
+ * writing its own stream, so that seam polls a ledger to discover children and
+ * folds reconciling parts before delivery. A target assessment writes progress
+ * from the parent body alone, under `workflowID === assessmentId`. One stream,
+ * no discovery, no pool.
+ *
+ * It is a push subscription rather than a returned iterator because handing the
+ * engine's async generator back to a caller would put the engine's model on the
+ * very surface this seam exists to remove, and would leave nowhere to contain a
+ * failure. A handler gives both, and matches the `EmitFn` idiom the writer side
+ * already speaks.
+ */
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { TargetAssessmentProgressEventSchema } from "@inflexa-ai/harness/contracts/target-dossier.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { TA_PROGRESS_STREAM_KEY } from "./progress.js";
+/**
+ * Shape `emitProgress` writes. The `data-target-assessment-progress` key is not
+ * in the chat-part registry — it is the writer's private envelope — so the
+ * payload, not the envelope, is what a caller gets.
+ */
+function readEvent(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const parsed = TargetAssessmentProgressEventSchema.safeParse(value.payload);
+    return parsed.success ? parsed.data : null;
+}
+/** Build the DBOS-backed realization of {@link TargetAssessmentProgressStream}. */
+export function createTargetAssessmentProgressStream(deps = {}) {
+    const baseLogger = (deps.logger ?? createNoopLogger()).named("ta-progress-stream");
+    return {
+        async subscribe({ assessmentId, onEvent, signal }) {
+            const logger = baseLogger.with({ assessmentId });
+            let resolveAbort;
+            const aborted = new Promise((resolve) => {
+                resolveAbort = resolve;
+            });
+            const generator = DBOS.readStream(assessmentId, TA_PROGRESS_STREAM_KEY);
+            // The engine's reader exposes no cancellation: while it waits on a
+            // quiet-but-active workflow it is suspended inside an await, where a
+            // queued `return()` is only honoured once it next reaches a yield.
+            // Teardown is therefore best-effort by construction, and the read's
+            // own promise is raced against the signal rather than waiting on it.
+            const onAbort = () => {
+                resolveAbort();
+                void generator.return(undefined).catch(() => {
+                    /* the read is already being abandoned */
+                });
+            };
+            if (signal.aborted)
+                onAbort();
+            else
+                signal.addEventListener("abort", onAbort, { once: true });
+            const read = (async () => {
+                try {
+                    for (;;) {
+                        const next = await generator.next();
+                        // Checked after the read, not before: `next()` is what
+                        // notices the workflow going inactive, and an aborted
+                        // subscription must deliver nothing further.
+                        if (next.done === true || signal.aborted)
+                            return;
+                        const event = readEvent(next.value);
+                        if (event === null) {
+                            logger.debug("dropped a stream value outside the progress contract");
+                            continue;
+                        }
+                        try {
+                            await onEvent(event);
+                        }
+                        catch (err) {
+                            logger.warn("progress handler threw", { phase: event.phase, ...logger.errorFields(err) });
+                        }
+                    }
+                }
+                catch (err) {
+                    // Observation is a diagnostic channel: `emitProgress` already
+                    // treats a failed write as best-effort so a lost frame cannot
+                    // fail the workflow. A read that propagated here would be
+                    // strictly less robust than the writer it observes.
+                    logger.error("progress stream read failed", logger.errorFields(err));
+                }
+                finally {
+                    void generator.return(undefined).catch(() => {
+                        /* already finished, or abandoned under abort */
+                    });
+                }
+            })();
+            try {
+                await Promise.race([read, aborted]);
+            }
+            finally {
+                signal.removeEventListener("abort", onAbort);
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.35.5",
+    "version": "0.35.7",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",