@inflexa-ai/harness 0.47.0 → 0.48.0

package/dist/tools/script/run-script.js

@@ -33,6 +33,8 @@ const SCRIPT_TIMEOUT_MS = 180_000;
 const SCRIPT_MEMORY_BYTES = 256 * 1024 * 1024;
 /** The text of a result that reaches the model. A longer output keeps its head and its tail. */
 const MAX_RESULT_CHARS = 24_000;
+/** The least time between two live copies of the nested calls of a script. */
+const LIVE_ACTIVITY_INTERVAL_MS = 500;
 const inputSchema = z.object({
     description: z.string().max(200).optional().describe("One short line that tells the user what the script does, for example 'Top 20 genes by padj'."),
     code: z
@@ -57,11 +59,59 @@ function plainJson(value) {
     return value === undefined ? null : parseJsonAs(JSON.stringify(value), z.json());
 }
 function describeTool(tool) {
-    return renderToolSample({ name: tool.id, description: tool.description, inputSchema: tool.jsonSchema, outputSchema: tool.outputJsonSchema });
+    return renderToolSample({ name: tool.id, description: tool.description, inputSchema: inputSchemaOf(tool), outputSchema: tool.outputJsonSchema });
 }
 function issuesOf(error) {
     return error.issues.map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`).join("; ");
 }
+/**
+ * The live copies of the activity part of one script, so a reader sees each nested call while the script runs. A copy
+ * is transient, and the part that the call emits at its end is the one that a stored display keeps. Each copy holds
+ * each entry so far, thus at most one copy goes in each interval. A copy that the interval holds back goes at the end
+ * of the interval, thus a long nested call shows before it ends.
+ */
+function createLiveActivity(emit, log, intervalMs) {
+    let latest = null;
+    let lastSentMs = Number.NEGATIVE_INFINITY;
+    let timer;
+    let closed = false;
+    const inFlight = new Set();
+    const send = () => {
+        timer = undefined;
+        if (closed || latest === null)
+            return;
+        lastSentMs = Date.now();
+        const part = latest;
+        const sent = (async () => {
+            try {
+                await emit({ type: part.type, data: part, transient: true });
+            }
+            catch (err) {
+                log.warn("a live copy of the nested calls did not reach the stream", log.errorFields(err));
+            }
+        })();
+        inFlight.add(sent);
+        void sent.finally(() => inFlight.delete(sent));
+    };
+    return {
+        update(part) {
+            latest = part;
+            if (closed || timer !== undefined)
+                return;
+            const wait = lastSentMs + intervalMs - Date.now();
+            if (wait <= 0)
+                send();
+            // oxlint-disable-next-line eslint-js/no-restricted-syntax -- `close` clears it, and the call runs `close` in its `finally`, thus it ends with the call.
+            else
+                timer = setTimeout(send, wait);
+        },
+        async close() {
+            closed = true;
+            clearTimeout(timer);
+            await Promise.all(inFlight);
+        },
+    };
+}
 /** Keep the files of the call record of one nested call. A record of another shape carries no file. */
 function collectEffect(state, value) {
     const effect = ScriptFileEffectSchema.safeParse(readToolCallRecord(value));
@@ -82,7 +132,7 @@ function scriptToolOf(tool, ctx, state, log, inCallContext) {
     return {
         name: tool.id,
         description: tool.description,
-        inputSchema: tool.jsonSchema,
+        inputSchema: inputSchemaOf(tool),
         outputSchema: tool.outputJsonSchema,
         execute: (args, options) => inCallContext(() => runNestedCall(tool, ctx, state, log, args, options.signal)),
     };
@@ -148,6 +198,36 @@ function withoutProse(schema) {
         .filter(([key]) => key !== "description" && key !== "examples")
         .map(([key, value]) => [key, withoutProse(value)]));
 }
+/**
+ * A JSON schema as a script reads it. A tool can union its real shape with the empty schema to keep its runtime parse
+ * permissive (`add_block` does, thus a malformed block reaches its typed refusal). The type of such a union is
+ * `unknown`, which hides the real shape, thus the empty member goes. The VM only renders the schema and validates
+ * nothing, and the tool still parses each input with its own schema.
+ */
+function printableSchema(schema) {
+    const array = UnknownArraySchema.safeParse(schema);
+    if (array.success)
+        return array.data.map(printableSchema);
+    const record = parseUnknownRecord(schema);
+    if (record === undefined)
+        return schema;
+    let out = Object.fromEntries(Object.entries(record).map(([key, value]) => [key, printableSchema(value)]));
+    for (const key of ["anyOf", "oneOf"]) {
+        const members = UnknownArraySchema.safeParse(out[key]);
+        if (!members.success)
+            continue;
+        const shaped = members.data.filter((member) => Object.keys(parseUnknownRecord(member) ?? {}).length > 0);
+        if (shaped.length === 0 || shaped.length === members.data.length)
+            continue;
+        const rest = Object.fromEntries(Object.entries(out).filter(([name]) => name !== key));
+        out = shaped.length > 1 ? { ...rest, [key]: shaped } : { ...rest, ...parseUnknownRecord(shaped[0]) };
+    }
+    return out;
+}
+/** The input schema of a tool as a script reads it. See {@link printableSchema}. */
+function inputSchemaOf(tool) {
+    return parseUnknownRecord(printableSchema(tool.jsonSchema)) ?? tool.jsonSchema;
+}
 /** The longest result type that the catalog shows. A longer type shows as `unknown`, and `describe()` gives it whole. */
 const MAX_CATALOG_RESULT_TYPE_CHARS = 800;
 /** One catalog entry: the first sentence of the description, then the signature with no prose. */
@@ -155,7 +235,7 @@ function catalogEntry(tool) {
     const output = tool.outputJsonSchema === undefined ? undefined : parseUnknownRecord(withoutProse(tool.outputJsonSchema));
     const resultType = output === undefined ? "unknown" : schemaToType(output, { maxChars: MAX_CATALOG_RESULT_TYPE_CHARS });
     // pi renders a signature with no result schema as `...: Promise<unknown>;`, thus the catalog puts its capped type there.
-    const untyped = renderToolSignature({ name: tool.id, inputSchema: parseUnknownRecord(withoutProse(tool.jsonSchema)) ?? {} });
+    const untyped = renderToolSignature({ name: tool.id, inputSchema: parseUnknownRecord(withoutProse(inputSchemaOf(tool))) ?? {} });
     const signature = `${untyped.slice(0, -"unknown>;".length)}${resultType}>;`;
     return `/** ${firstSentence(tool.description)} */\n${signature}`;
 }
@@ -234,6 +314,7 @@ export function createRunScriptTool(scriptTools, runtime = {}, options = {}) {
                 source: { agentId: caller.agentId, callPath: [...caller.callPath] },
             }, Date.now());
             const tracked = { part: null };
+            const live = createLiveActivity(ctx.emit, log, LIVE_ACTIVITY_INTERVAL_MS);
             let started = 0;
             const state = {
                 code,
@@ -244,7 +325,11 @@ export function createRunScriptTool(scriptTools, runtime = {}, options = {}) {
                 nextInvocationId: () => `${ctx.invocationId}:${++started}`,
                 source: { agentId: RUN_SCRIPT_TOOL_ID, callPath: [...caller.callPath, RUN_SCRIPT_TOOL_ID], invocationId: ctx.invocationId },
                 observe: (frame) => {
-                    tracked.part = tracker.track(frame, Date.now()) ?? tracked.part;
+                    const part = tracker.track(frame, Date.now());
+                    if (part === null)
+                        return;
+                    tracked.part = part;
+                    live.update(part);
                 },
             };
             // The VM calls a tool from a message event of its worker, and such an event runs outside the async context
@@ -286,6 +371,7 @@ export function createRunScriptTool(scriptTools, runtime = {}, options = {}) {
                     reads: state.reads.length,
                     writes: state.writes.length,
                 });
+                await live.close();
                 if (tracked.part !== null)
                     await ctx.emit({ type: tracked.part.type, data: tracked.part });
                 if (state.writes.length > 0) {
@@ -319,6 +405,7 @@ export function createRunScriptTool(scriptTools, runtime = {}, options = {}) {
                 return ok(record.run === undefined && record.nested.length === 0 ? outcome : withToolCallRecord(outcome, record));
             }
             finally {
+                await live.close();
                 await sandbox.close();
             }
         },

package/dist/tools/script/scratch.d.ts

@@ -13,6 +13,7 @@ import type { AgentSession } from "../../auth/types.js";
 import type { Logger } from "../../lib/logger.js";
 import { type ProvenanceSeam } from "../../provenance/seam.js";
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
+import { type SyncSessionFile } from "../../workspace/session-files.js";
 /** The cap of one derived file. It matches the cap of a table read, thus a script can read back what it wrote. */
 export declare const DERIVED_FILE_CAP_BYTES: number;
 /** The cap of the derived files of one session together. */
@@ -76,6 +77,8 @@ export type ScriptScratchDeps = {
     readonly sessionDir: (threadId: string) => string;
     /** The provenance seam. An unbound session emit records nothing, and the scripts run the same. */
     readonly provenance?: ProvenanceSeam;
+    /** The host copy of each file that lands, owned by the thread of the session. */
+    readonly syncSessionFile?: SyncSessionFile;
     readonly logger?: Logger;
 };
 export declare function createScriptScratch(deps: ScriptScratchDeps): ScriptScratch;

package/dist/tools/script/scratch.js

@@ -17,6 +17,7 @@ import { tryFs } from "../../lib/fs-result.js";
 import { unwrapOrThrow } from "../../lib/result.js";
 import { bindSessionEmit } from "../../provenance/seam.js";
 import { isSafeId } from "../../workspace/paths.js";
+import { syncWrittenFile } from "../../workspace/session-files.js";
 import { confinedWrite } from "../workspace/mutator.js";
 /** The cap of one derived file. It matches the cap of a table read, thus a script can read back what it wrote. */
 export const DERIVED_FILE_CAP_BYTES = 16 * 1024 * 1024;
@@ -55,7 +56,7 @@ async function directoryBytes(absolute) {
 export function createScriptScratch(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("script-scratch");
     const observe = bindSessionEmit(deps.provenance, logger);
-    async function land(session, dir, name, content, invocationId) {
+    async function land(session, threadId, dir, name, content, invocationId) {
         const { analysisId } = session.scope;
         const workspaceRoot = await deps.resolveWorkspaceRoot(analysisId);
         const landed = await confinedWrite({
@@ -70,14 +71,16 @@ export function createScriptScratch(deps) {
         });
         if (landed.status !== "ok")
             return { refused: `the write of ${dir}/${name} was refused (${landed.status})` };
-        return { path: landed.relative, hash: computeSha256(landed.bytes), size: landed.bytes.length };
+        const file = { path: landed.relative, hash: computeSha256(landed.bytes), size: landed.bytes.length };
+        await syncWrittenFile(deps.syncSessionFile, logger, { session, owner: { kind: "thread", threadId }, ...file, content: landed.bytes });
+        return file;
     }
     return {
         async saveScript({ session, invocationId, code }) {
             const { threadId } = session.scope;
             if (threadId === undefined)
                 return undefined;
-            const saved = await land(session, `${deps.sessionDir(threadId)}/scripts`, scriptFileName(invocationId), code, invocationId);
+            const saved = await land(session, threadId, `${deps.sessionDir(threadId)}/scripts`, scriptFileName(invocationId), code, invocationId);
             if ("refused" in saved)
                 throw new Error(saved.refused);
             return saved;
@@ -115,7 +118,7 @@ export function createScriptScratch(deps) {
             if (used + bytes > DERIVED_SESSION_CAP_BYTES) {
                 return { status: "refused", reason: `the derived files of this session would pass the cap of ${String(DERIVED_SESSION_CAP_BYTES)} bytes` };
             }
-            const landed = await land(session, dir, name, content, invocationId);
+            const landed = await land(session, threadId, dir, name, content, invocationId);
             if ("refused" in landed)
                 return { status: "refused", reason: landed.refused };
             return { status: "written", file: landed };

package/dist/tools/workspace/mutator.d.ts

@@ -38,6 +38,7 @@ import type { AgentSession } from "../../auth/types.js";
 import type { Logger } from "../../lib/logger.js";
 import type { ProvenanceCollector } from "../../provenance/collector.js";
 import { type ProvenanceSeam } from "../../provenance/seam.js";
+import { type SyncSessionFile } from "../../workspace/session-files.js";
 import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
 /** Outcome of a confined write. Expected outcomes are data variants — never throws on them. */
 export type WriteFileResult = {
@@ -191,6 +192,8 @@ export type SessionWorkspaceMutatorDeps = {
      * proceeds unchanged.
      */
     readonly provenance?: ProvenanceSeam;
+    /** The host copy of each file that lands, owned by the analysis: the path is anywhere in its tree. */
+    readonly syncSessionFile?: SyncSessionFile;
     readonly logger?: Logger;
 };
 /**

package/dist/tools/workspace/mutator.js

@@ -43,6 +43,7 @@ import { computeSha256 } from "../../lib/fs-helpers.js";
 import { tryFs, tryFsWrite } from "../../lib/fs-result.js";
 import { unwrapOrThrow } from "../../lib/result.js";
 import { bindSessionEmit } from "../../provenance/seam.js";
+import { syncWrittenFile } from "../../workspace/session-files.js";
 import { resolveForWrite, STAGED_INPUT_ROOT } from "../../workspace/paths.js";
 /**
  * Agent-visible name of the tool driving a confined write. Rides the write args
@@ -305,7 +306,16 @@ export function createSessionWorkspaceMutator(deps) {
             });
             if (landed.status !== "ok")
                 return { ...landed, path };
-            return landedWrite(landed);
+            const write = landedWrite(landed);
+            await syncWrittenFile(deps.syncSessionFile, logger, {
+                session,
+                owner: { kind: "analysis" },
+                path: write.record.path,
+                hash: write.record.hash,
+                size: write.record.size,
+                content: landed.bytes,
+            });
+            return write;
         },
         recordWrite(record) {
             const event = {

package/dist/workspace/session-files.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The files that a session writes outside a run, and the host hook that keeps a copy of each.
+ *
+ * A run registers its step files through `ArtifactRegistry`. A chat thread and a report session write files too:
+ * the scripts and the derived files of `run_script`, and the files of `write_file` and `edit_file`. A host that
+ * keeps the files of an analysis elsewhere binds `syncSessionFile`, and each write reaches it with its bytes. The
+ * call runs inside the tool step of the write, thus a step that runs again after a crash calls the hook again with
+ * the same file.
+ */
+import type { ResultAsync } from "neverthrow";
+import type { AgentSession } from "../auth/types.js";
+import { type NoticeFailure } from "../lib/hooks.js";
+import type { Logger } from "../lib/logger.js";
+/** Who owns a session file. A file in the scratch directory of a thread belongs to that thread. */
+export type SessionFileOwner = {
+    readonly kind: "thread";
+    readonly threadId: string;
+} | {
+    readonly kind: "analysis";
+};
+export type SessionFileWrite = {
+    /** The session of the tool call that wrote the file. */
+    readonly session: AgentSession;
+    readonly owner: SessionFileOwner;
+    /** The analysis-relative path, and the hash and the size of the bytes. */
+    readonly path: string;
+    readonly hash: string;
+    readonly size: number;
+    /** The exact bytes that landed. */
+    readonly content: Uint8Array;
+};
+/** A notice: a failure is logged, and the write stays done. */
+export type SyncSessionFile = (write: SessionFileWrite) => ResultAsync<void, NoticeFailure>;
+/** Give one landed write to the hook of the host. An unbound hook does nothing. */
+export declare function syncWrittenFile(sync: SyncSessionFile | undefined, logger: Logger, write: SessionFileWrite): Promise<void>;

package/dist/workspace/session-files.js

@@ -0,0 +1,16 @@
+/**
+ * The files that a session writes outside a run, and the host hook that keeps a copy of each.
+ *
+ * A run registers its step files through `ArtifactRegistry`. A chat thread and a report session write files too:
+ * the scripts and the derived files of `run_script`, and the files of `write_file` and `edit_file`. A host that
+ * keeps the files of an analysis elsewhere binds `syncSessionFile`, and each write reaches it with its bytes. The
+ * call runs inside the tool step of the write, thus a step that runs again after a crash calls the hook again with
+ * the same file.
+ */
+import { deliverNotice } from "../lib/hooks.js";
+/** Give one landed write to the hook of the host. An unbound hook does nothing. */
+export async function syncWrittenFile(sync, logger, write) {
+    if (sync === undefined)
+        return;
+    await deliverNotice(logger.with({ analysisId: write.session.scope.analysisId, path: write.path }), "syncSessionFile", sync(write));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.47.0",
+    "version": "0.48.0",
     "description": "Host-agnostic bioinformatics agent harness — an agent loop on the AI SDK, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",
@@ -83,6 +83,7 @@
         "dockerode": "^4.0.12",
         "echarts": "6.1.0",
         "fast-xml-parser": "^5.10.1",
+        "fflate": "^0.8.3",
         "hono": "^4.12.34",
         "hyparquet": "^1.28.1",
         "js-tiktoken": "^1.0.21",