@inflexa-ai/harness 0.19.0 → 0.19.1

package/dist/tasks/extract-values-script.js

@@ -0,0 +1,180 @@
+/**
+ * The fixed extraction script and its wire protocol.
+ *
+ * The extraction arm runs this one Python script in the sandbox. The script reads one JSON input: a list
+ * of path, format, and hash triples. For each triple the script hashes the file bytes with a streamed
+ * sha256 before any read. If the on-disk hash does not match the pinned hash, the script refuses the file
+ * as a typed error. If the hash matches, the script reads the file from the read-only analysis mount, and
+ * it parses the file by the carried format. A parquet file uses pyarrow. The script emits one JSON map:
+ * each path to its rows, or to a typed error. The script decides nothing else. It applies no filter and no
+ * projection.
+ *
+ * The host decides the format one time, and the request carries it. Thus the script derives no reader from
+ * an extension, and it refuses a request that names no format. The JSON arm obeys the strict host shape, an
+ * array of flat objects, thus a shape that the host refuses is a refusal here too and it never comes back
+ * as a table that pandas inferred.
+ *
+ * The harness holds the script as a string constant, thus the package ships no separate asset file. The
+ * script reaches the container as the argument of `python3 -c`. The input reaches the container as one
+ * environment variable.
+ */
+import { z } from "zod";
+/**
+ * The environment variable that carries the script input. The workflow body sets it to the JSON list of
+ * path, format, and hash triples. The script reads it back one time.
+ */
+export const EXTRACTION_INPUT_ENV = "CORTEX_EXTRACTION_REQUESTS";
+/**
+ * One artifact row, as plain cells. A text-backed format holds a numeric column as a string, thus a cell
+ * is a string or a number.
+ */
+const ExtractionRowSchema = z.record(z.string(), z.union([z.string(), z.number()]));
+/**
+ * The outcome for one path. A clean read gives the rows. A per-file read fault gives a typed error, and
+ * the script still emits the map. The arm keeps the rows and drops the error, thus a failed path reads as
+ * an unread artifact downstream.
+ */
+const ExtractOutcomeSchema = z.union([
+    z.object({ rows: z.array(ExtractionRowSchema) }),
+    z.object({ error: z.object({ type: z.string(), message: z.string() }) }),
+]);
+/** The script output: each requested path to its outcome. */
+export const ExtractValuesResultSchema = z.record(z.string(), ExtractOutcomeSchema);
+/**
+ * The one extraction script. The workflow body runs it as the argument of `python3 -c`. The script reads
+ * the request list from `CORTEX_EXTRACTION_REQUESTS`, and it emits the value map to stdout.
+ *
+ * The Python comments obey the same Simplified Technical English rule as the harness comments.
+ */
+export const EXTRACTION_SCRIPT = `import hashlib
+import json
+import math
+import os
+import sys
+
+import pandas as pd
+
+
+def sha256_of(path):
+    # The host pins the exact bytes with a streamed sha256, in the "sha256:<hex>" form. Mirror that form
+    # here, and stream the file in blocks, thus a large file never loads fully into memory.
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        for block in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(block)
+    return "sha256:" + digest.hexdigest()
+
+
+def coerce_cell(value):
+    # A null cell becomes None, thus the record drops the key.
+    if value is None:
+        return None
+    # A numpy scalar becomes a plain Python scalar.
+    if hasattr(value, "item"):
+        try:
+            value = value.item()
+        except (ValueError, TypeError):
+            return str(value)
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, float):
+        if math.isnan(value) or math.isinf(value):
+            return None
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        return value
+    return str(value)
+
+
+def read_frame(path, fmt):
+    # pyarrow reads the parquet columnar format.
+    if fmt == "parquet":
+        return pd.read_parquet(path, engine="pyarrow")
+    if fmt == "tsv":
+        # keep_default_na=False keeps a literal cell such as "NA" or an empty string as its text, and the
+        # host parser keeps it too. A default read turns each into NaN, and the row builder drops the key.
+        return pd.read_csv(path, sep="\\t", dtype=str, keep_default_na=False)
+    if fmt == "csv":
+        # keep_default_na=False keeps a literal cell such as "NA" or an empty string as its text, thus a
+        # text cell survives and the row keeps the key.
+        return pd.read_csv(path, dtype=str, keep_default_na=False)
+    # The host decides the format for both arms. A request with no decided format is a protocol fault, thus
+    # the file refuses here and no reader guesses at it.
+    raise ValueError("the request names no supported format: " + str(fmt))
+
+
+def json_rows(path):
+    # The host reads a JSON table as an array of flat objects, and it refuses any other shape. Obey the
+    # same shape here. An inference pass would turn a shape that the host refuses into a different table.
+    with open(path, "rb") as handle:
+        value = json.load(handle)
+    if not isinstance(value, list):
+        raise ValueError("the JSON top-level value is not an array")
+    rows = []
+    for item in value:
+        if not isinstance(item, dict):
+            raise ValueError("a JSON array item is not an object")
+        row = {}
+        for key, cell in item.items():
+            if isinstance(cell, (dict, list)):
+                raise ValueError("a JSON cell holds a nested value")
+            coerced = coerce_cell(cell)
+            if coerced is not None:
+                row[str(key)] = coerced
+        rows.append(row)
+    return rows
+
+
+def rows_of(frame):
+    # A null cell becomes None before the record build, thus a missing cell drops.
+    clean = frame.astype(object).where(pd.notnull(frame), None)
+    records = clean.to_dict(orient="records")
+    rows = []
+    for record in records:
+        row = {}
+        for key, value in record.items():
+            cell = coerce_cell(value)
+            if cell is not None:
+                row[str(key)] = cell
+        rows.append(row)
+    return rows
+
+
+def rows_for(path, fmt):
+    # The JSON arm reads the strict host shape itself. Each other format reads through pandas.
+    if fmt == "json":
+        return json_rows(path)
+    return rows_of(read_frame(path, fmt))
+
+
+def main():
+    raw = os.environ.get("${EXTRACTION_INPUT_ENV}", "[]")
+    requests = json.loads(raw)
+    out = {}
+    for request in requests:
+        path = request["path"]
+        fmt = request.get("format")
+        expected = request["hash"]
+        try:
+            # Hash the file before any read. A file that drifted from the pin never reaches the reader, thus
+            # the extraction never gives back drifted bytes for the gate to match against.
+            actual = sha256_of(path)
+            if actual != expected:
+                out[path] = {
+                    "error": {
+                        "type": "hash-mismatch",
+                        "message": f"the pinned hash {expected} does not match the on-disk hash {actual}",
+                    }
+                }
+                continue
+            out[path] = {"rows": rows_for(path, fmt)}
+        except Exception as exc:
+            # A per-file read fault lands as a typed error, and the map still holds each other path.
+            out[path] = {"error": {"type": "read-fault", "message": str(exc)}}
+    json.dump(out, sys.stdout)
+
+
+main()
+`;

package/dist/tasks/extract-values.d.ts

@@ -0,0 +1,124 @@
+/**
+ * The extraction workflow on the profile rails, and the `ExtractionArm` realization over it.
+ *
+ * The report resolver falls through to this arm for an over-cap file or a host parse fault. The arm runs one
+ * fixed extraction script in an ephemeral sandbox, and it gives back the rows that the script read. No agent
+ * loop runs anywhere in this path. A file whose extension names no tabular format never arrives here,
+ * because the host decides the format and it refuses the file before the fall-through.
+ *
+ * The shape matches the data profile (`src/tasks/data-profile.ts`). The authorization mints at the async
+ * edge (`triggerExtractValues`) and rides in the workflow input. The body never mints, and it revokes the
+ * authorization on every terminal path. The container is ephemeral, and it goes away with the work, thus no
+ * standing machine exists.
+ */
+import type { AuthContext, RunSession } from "../auth/types.js";
+import type { RunAuthorizer } from "../execution/run-authorizer.js";
+import type { Logger } from "../lib/logger.js";
+import type { ExtractionArm, ExtractionArtifact, ExtractionRequest } from "../report-model/production-resolver.js";
+import type { SandboxClient } from "../sandbox/client.js";
+import type { ExecResult, SubmitExecBody } from "../sandbox/types.js";
+import { type ExtractValuesResult } from "./extract-values-script.js";
+export type { ExtractValuesResult } from "./extract-values-script.js";
+/**
+ * The body's construction-time deps, closed over at registration. The extraction pass shares the profile's
+ * sandbox and authorization rails, thus it draws the same three seams and nothing else.
+ */
+export interface ExtractValuesDeps {
+    /** Operational logging seam. An absent logger falls back to a no-op. */
+    readonly logger?: Logger;
+    readonly sandboxClient: SandboxClient;
+    readonly runAuthorizer: RunAuthorizer;
+}
+/**
+ * The workflow input. It is JSON-serializable, thus DBOS persists it as the workflow's input row. The
+ * `RunSession` carries the run authorization. The body reads it and never mints.
+ */
+export interface ExtractValuesWorkflowInput {
+    readonly analysisId: string;
+    readonly runSession: RunSession;
+    /** The fall-through artifacts of one document pass. One submission covers every request. */
+    readonly requests: readonly ExtractionRequest[];
+    /**
+     * True when this workflow owns the run-authorization lifecycle, thus the body revokes on every terminal
+     * path. An input persisted before this field existed reads as absent, and the body defaults it to true,
+     * which matches the prior owned behavior.
+     */
+    readonly ownsMandate?: boolean;
+}
+/**
+ * Build the sandbox exec for one extraction pass. The command runs the fixed script through `python3 -c`.
+ * The working directory is the analysis mount, thus a relative request path reads the correct file. The
+ * request list rides in one environment variable.
+ *
+ * Each request carries its pinned hash. Thus the script can hash the file first and refuse a file that
+ * drifted from the pin, before the read gives back drifted bytes.
+ *
+ * Each request also carries the format that the host decided. The script obeys that format, thus this arm
+ * derives no reader from an extension and the two arms can never read one file two ways.
+ *
+ * The function is pure, thus a test asserts the command shape without a sandbox.
+ */
+export declare function buildExtractionExec(analysisId: string, requests: readonly ExtractionRequest[], execId: string): SubmitExecBody;
+/**
+ * Parse the script output from the exec result. A synthetic failure, a timeout, and a non-zero exit each
+ * throw, because each means the script did not emit its map. A stdout that is not the map shape throws too.
+ *
+ * The function is pure, thus a test asserts the parse without a sandbox. The throw crosses the workflow
+ * boundary, and the arm turns it into a rejected promise.
+ */
+export declare function parseExtractionOutput(result: ExecResult): ExtractValuesResult;
+/**
+ * The body, extracted so a test drives it without a registered workflow. It creates the ephemeral
+ * container, submits one exec, awaits the result durably, and gives the value map back. It revokes the run
+ * authorization on every terminal path, and it tears the container down on both paths.
+ */
+export declare function runExtractValuesBody(input: ExtractValuesWorkflowInput, deps: ExtractValuesDeps): Promise<ExtractValuesResult>;
+/**
+ * Register the extraction workflow with DBOS. It gives back the registered callable, thus a trigger
+ * dispatches with `DBOS.startWorkflow`.
+ */
+export declare function registerExtractValuesWorkflow(deps: ExtractValuesDeps): (input: ExtractValuesWorkflowInput) => Promise<ExtractValuesResult>;
+/** The per-attempt workflow id. A fresh nonce keeps each pass under a distinct id. */
+export declare function extractValuesWorkflowId(analysisId: string, nonce: string): string;
+/**
+ * The route-side deps for the trigger: the run authorizer, and the registered workflow callable. The body's
+ * construction-time deps are closed over at registration, thus the trigger never holds them.
+ */
+export interface ExtractValuesTriggerDeps {
+    readonly runAuthorizer: RunAuthorizer;
+    readonly workflow: (input: ExtractValuesWorkflowInput) => Promise<ExtractValuesResult>;
+}
+/** The identity and the requests for one extraction pass. */
+export interface ExtractValuesTriggerParams {
+    readonly auth: AuthContext;
+    readonly analysisId: string;
+    readonly requests: readonly ExtractionRequest[];
+}
+/**
+ * The async edge. It authorizes through the `RunAuthorizer`, starts the workflow, and awaits the outcome.
+ * The body owns the revoke, thus the trigger holds no lifecycle. A workflow fault rejects the returned
+ * promise.
+ */
+export declare function triggerExtractValues(deps: ExtractValuesTriggerDeps, params: ExtractValuesTriggerParams): Promise<ExtractValuesResult>;
+/** Runs one extraction pass for the bound analysis, and gives the raw value map back. */
+export type ExtractionRunner = (requests: readonly ExtractionRequest[]) => Promise<ExtractValuesResult>;
+/**
+ * Bind the trigger to one analysis and one auth context. The result runs one pass with every request in it.
+ */
+export declare function bindExtractionTrigger(deps: ExtractValuesTriggerDeps, binding: {
+    readonly auth: AuthContext;
+    readonly analysisId: string;
+}): ExtractionRunner;
+/**
+ * Turn the raw script output into the arm result. A path with rows enters the map. A path with an error
+ * drops out, thus the reference at that path reads as an unread artifact, which the seam contract expects.
+ *
+ * The function is pure, thus a test asserts the mapping without a sandbox.
+ */
+export declare function extractionArtifactsFromResult(result: ExtractValuesResult): Map<string, ExtractionArtifact>;
+/**
+ * Make the extraction arm over a runner. One `extract` call makes one run with every request in it, and it
+ * gives the value map. A run fault rejects the promise, and the resolver turns the rejection into a failed
+ * reference.
+ */
+export declare function createExtractionArm(run: ExtractionRunner): ExtractionArm;

package/dist/tasks/extract-values.js

@@ -0,0 +1,193 @@
+/**
+ * The extraction workflow on the profile rails, and the `ExtractionArm` realization over it.
+ *
+ * The report resolver falls through to this arm for an over-cap file or a host parse fault. The arm runs one
+ * fixed extraction script in an ephemeral sandbox, and it gives back the rows that the script read. No agent
+ * loop runs anywhere in this path. A file whose extension names no tabular format never arrives here,
+ * because the host decides the format and it refuses the file before the fall-through.
+ *
+ * The shape matches the data profile (`src/tasks/data-profile.ts`). The authorization mints at the async
+ * edge (`triggerExtractValues`) and rides in the workflow input. The body never mints, and it revokes the
+ * authorization on every terminal path. The container is ephemeral, and it goes away with the work, thus no
+ * standing machine exists.
+ */
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { randomUUID } from "node:crypto";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { generateExecutionId } from "../sandbox/execution-id.js";
+import { mintSandboxIdentity } from "../sandbox/identity.js";
+import { EXTRACTION_INPUT_ENV, EXTRACTION_SCRIPT, ExtractValuesResultSchema } from "./extract-values-script.js";
+/** The synthetic run id and step id of the extraction pass. Both are constants shared by every analysis. */
+const EXTRACT_VALUES_RUN_LITERAL = "extract-values";
+const EXTRACT_VALUES_STEP_LITERAL = "extract";
+/** The provenance agent id. No agent loop runs, thus this names the extraction pass, not a model agent. */
+const EXTRACT_VALUES_AGENT_ID = "value-extractor";
+/** The exec budget for one extraction pass. It matches the profile budget. */
+const EXTRACTION_DEADLINE_MS = 300_000;
+/**
+ * The container size for one extraction pass. The fall-through reads a file that is over the host cap, thus
+ * the container needs headroom to load the file into pandas. The size is fixed, because the seam request
+ * carries no file size. A later change can size it from the batch.
+ */
+const EXTRACTION_RESOURCES = { cpu: 2, memoryGb: 8 };
+/** The awaitExec callback. The extraction pass reports no live activity, thus the callback drops each event. */
+const noopEmit = () => { };
+/**
+ * Build the sandbox exec for one extraction pass. The command runs the fixed script through `python3 -c`.
+ * The working directory is the analysis mount, thus a relative request path reads the correct file. The
+ * request list rides in one environment variable.
+ *
+ * Each request carries its pinned hash. Thus the script can hash the file first and refuse a file that
+ * drifted from the pin, before the read gives back drifted bytes.
+ *
+ * Each request also carries the format that the host decided. The script obeys that format, thus this arm
+ * derives no reader from an extension and the two arms can never read one file two ways.
+ *
+ * The function is pure, thus a test asserts the command shape without a sandbox.
+ */
+export function buildExtractionExec(analysisId, requests, execId) {
+    const scriptRequests = requests.map((request) => ({ path: request.path, format: request.format, hash: request.hash }));
+    return {
+        command: ["python3", "-c", EXTRACTION_SCRIPT],
+        execId,
+        cwd: `/${analysisId}`,
+        env: { [EXTRACTION_INPUT_ENV]: JSON.stringify(scriptRequests) },
+        timeoutSeconds: Math.floor(EXTRACTION_DEADLINE_MS / 1000),
+    };
+}
+/**
+ * Parse the script output from the exec result. A synthetic failure, a timeout, and a non-zero exit each
+ * throw, because each means the script did not emit its map. A stdout that is not the map shape throws too.
+ *
+ * The function is pure, thus a test asserts the parse without a sandbox. The throw crosses the workflow
+ * boundary, and the arm turns it into a rejected promise.
+ */
+export function parseExtractionOutput(result) {
+    if (result.syntheticFailure !== undefined) {
+        throw new Error(`the extraction sandbox failed: ${result.syntheticFailure.reason}`);
+    }
+    if (result.timedOut) {
+        throw new Error("the extraction sandbox reached the deadline");
+    }
+    if (result.exitCode !== 0) {
+        throw new Error(`the extraction script exited with code ${String(result.exitCode)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        throw new Error("the extraction script did not emit valid JSON");
+    }
+    return ExtractValuesResultSchema.parse(parsed);
+}
+/**
+ * The body, extracted so a test drives it without a registered workflow. It creates the ephemeral
+ * container, submits one exec, awaits the result durably, and gives the value map back. It revokes the run
+ * authorization on every terminal path, and it tears the container down on both paths.
+ */
+export async function runExtractValuesBody(input, deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("extract-values").with({ analysisId: input.analysisId });
+    const { analysisId, runSession, requests, ownsMandate = true } = input; // oss-core-managed-ok
+    const authorization = { runSession, ownsMandate }; // oss-core-managed-ok
+    try {
+        const executionId = generateExecutionId(EXTRACT_VALUES_AGENT_ID);
+        const workflowId = DBOS.workflowID ?? `${EXTRACT_VALUES_RUN_LITERAL}:${executionId}`;
+        // The container mounts the analysis tree read-only. The extraction pass only reads, thus it needs
+        // no writable step mount.
+        const sandbox = await deps.sandboxClient.createSandbox({
+            runId: EXTRACT_VALUES_RUN_LITERAL,
+            stepId: EXTRACT_VALUES_STEP_LITERAL,
+            analysisId,
+            childWorkflowId: workflowId,
+            resources: EXTRACTION_RESOURCES,
+            readOnly: true,
+        }, mintSandboxIdentity(EXTRACT_VALUES_RUN_LITERAL));
+        try {
+            // A checkpointed clock, not `Date.now()`: the await gates on this absolute deadline, and a
+            // wall-clock deadline that grew on replay would shift which loop iteration crosses it.
+            const deadlineAbs = (await DBOS.now()) + EXTRACTION_DEADLINE_MS;
+            await deps.sandboxClient.submitExec(sandbox, buildExtractionExec(analysisId, requests, executionId));
+            const result = await deps.sandboxClient.awaitExec(sandbox, executionId, noopEmit, deadlineAbs);
+            const map = parseExtractionOutput(result);
+            await deps.runAuthorizer.revoke(authorization, "extract-values-completed");
+            return map;
+        }
+        finally {
+            try {
+                await deps.sandboxClient.teardown(sandbox);
+            }
+            catch (teardownErr) {
+                logger.warn("teardown failed (non-fatal)", { executionId, ...logger.errorFields(teardownErr) });
+            }
+        }
+    }
+    catch (err) {
+        logger.error("extraction failed", logger.errorFields(err));
+        await deps.runAuthorizer.revoke(authorization, "extract-values-failed");
+        throw err;
+    }
+}
+/**
+ * Register the extraction workflow with DBOS. It gives back the registered callable, thus a trigger
+ * dispatches with `DBOS.startWorkflow`.
+ */
+export function registerExtractValuesWorkflow(deps) {
+    return DBOS.registerWorkflow((input) => runExtractValuesBody(input, deps), { name: "extract-values" });
+}
+/** The per-attempt workflow id. A fresh nonce keeps each pass under a distinct id. */
+export function extractValuesWorkflowId(analysisId, nonce) {
+    return `extract-values:${analysisId}:${nonce}`;
+}
+/**
+ * The async edge. It authorizes through the `RunAuthorizer`, starts the workflow, and awaits the outcome.
+ * The body owns the revoke, thus the trigger holds no lifecycle. A workflow fault rejects the returned
+ * promise.
+ */
+export async function triggerExtractValues(deps, params) {
+    const { auth, analysisId, requests } = params;
+    const { runSession, ownsMandate } = await deps.runAuthorizer.authorize({
+        // oss-core-managed-ok
+        auth,
+        scope: { kind: "analysis", analysisId },
+        provenance: { agentId: EXTRACT_VALUES_AGENT_ID, callPath: [EXTRACT_VALUES_AGENT_ID] },
+        frame: { runId: EXTRACT_VALUES_RUN_LITERAL, stepId: EXTRACT_VALUES_STEP_LITERAL },
+    });
+    const handle = (await DBOS.startWorkflow(deps.workflow, {
+        workflowID: extractValuesWorkflowId(analysisId, randomUUID()),
+    })({ analysisId, runSession, requests: [...requests], ownsMandate })); // oss-core-managed-ok
+    return handle.getResult();
+}
+/**
+ * Bind the trigger to one analysis and one auth context. The result runs one pass with every request in it.
+ */
+export function bindExtractionTrigger(deps, binding) {
+    return (requests) => triggerExtractValues(deps, { auth: binding.auth, analysisId: binding.analysisId, requests });
+}
+/**
+ * Turn the raw script output into the arm result. A path with rows enters the map. A path with an error
+ * drops out, thus the reference at that path reads as an unread artifact, which the seam contract expects.
+ *
+ * The function is pure, thus a test asserts the mapping without a sandbox.
+ */
+export function extractionArtifactsFromResult(result) {
+    const out = new Map();
+    for (const [path, outcome] of Object.entries(result)) {
+        if ("rows" in outcome) {
+            out.set(path, { rows: outcome.rows });
+        }
+    }
+    return out;
+}
+/**
+ * Make the extraction arm over a runner. One `extract` call makes one run with every request in it, and it
+ * gives the value map. A run fault rejects the promise, and the resolver turns the rejection into a failed
+ * reference.
+ */
+export function createExtractionArm(run) {
+    return {
+        async extract(requests) {
+            return extractionArtifactsFromResult(await run(requests));
+        },
+    };
+}

package/dist/tools/define-tool.d.ts

@@ -38,6 +38,35 @@ export interface ToolError {
 export type ToolExecutionMode = "step" | "workflow" | "inline";
 /** Runtime guard — does a `Result`'s error value carry the `ToolError` shape? */
 export declare function isToolError(value: unknown): value is ToolError;
+/**
+ * The picture that a tool ok value carries beside its JSON data. `base64` holds
+ * the bytes, and `mediaType` names the IANA type, for example "image/png". The
+ * loop splits the picture out of the JSON text, and it rides the tool result as
+ * an image content block. Thus the model sees the picture, and the JSON text
+ * holds no bytes.
+ */
+export interface ToolResultImage {
+    readonly base64: string;
+    readonly mediaType: string;
+}
+/**
+ * The reserved key that carries a picture on a tool ok value. It is a symbol,
+ * thus it never collides with a data field. `JSON.stringify` also omits a symbol
+ * key, thus the bytes never reach the JSON text by accident.
+ */
+export declare const toolResultImageKey: unique symbol;
+/** A tool ok value that can carry a picture under the reserved key. */
+export type WithToolResultImage<T> = T & {
+    readonly [toolResultImageKey]?: ToolResultImage;
+};
+/**
+ * Attach a picture to a tool ok value. The value keeps its own fields, and the
+ * picture rides under the reserved key. The loop reads the key, and it moves the
+ * bytes into an image content block on the tool result.
+ */
+export declare function withToolResultImage<T extends object>(value: T, image: ToolResultImage): WithToolResultImage<T>;
+/** Read the picture that a tool ok value carries, or undefined when it carries none. */
+export declare function readToolResultImage(value: unknown): ToolResultImage | undefined;
 /**
  * The request-scoped values passed to every tool's `execute`. No injected
  * dependencies (see the harness-durable-runtime spec) — invocation identity,

package/dist/tools/define-tool.js

@@ -20,6 +20,32 @@ import { z } from "zod";
 export function isToolError(value) {
     return typeof value === "object" && value !== null && typeof value.error === "string" && typeof value.retryable === "boolean";
 }
+/**
+ * The reserved key that carries a picture on a tool ok value. It is a symbol,
+ * thus it never collides with a data field. `JSON.stringify` also omits a symbol
+ * key, thus the bytes never reach the JSON text by accident.
+ */
+export const toolResultImageKey = Symbol("toolResultImage");
+/**
+ * Attach a picture to a tool ok value. The value keeps its own fields, and the
+ * picture rides under the reserved key. The loop reads the key, and it moves the
+ * bytes into an image content block on the tool result.
+ */
+export function withToolResultImage(value, image) {
+    return { ...value, [toolResultImageKey]: image };
+}
+/** Read the picture that a tool ok value carries, or undefined when it carries none. */
+export function readToolResultImage(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const image = value[toolResultImageKey];
+    if (typeof image !== "object" || image === null)
+        return undefined;
+    const { base64, mediaType } = image;
+    if (typeof base64 !== "string" || typeof mediaType !== "string")
+        return undefined;
+    return { base64, mediaType };
+}
 /**
  * Package a `Tool`. The emitted JSON Schema must have a top-level
  * `"type": "object"` — model tool calling rejects anything else. A `z.discriminatedUnion`

package/dist/tools/report/preview-snapshot.d.ts

@@ -17,7 +17,7 @@
  * has to be able to see without reading the model transcript.
  */
 import { type Tool } from "../define-tool.js";
-import { type ChromeConfig } from "../../lib/chrome.js";
+import type { ChromeConfig } from "../../lib/chrome.js";
 import type { Logger } from "../../lib/logger.js";
 import { type PreviewPublisher } from "./preview-publisher.js";
 import type { PreviewUrlCell } from "./mint-preview-url.js";

package/dist/tools/report/preview-snapshot.js

@@ -19,11 +19,9 @@
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
-import { withPage } from "../../lib/chrome.js";
+import { capturePage } from "../../lib/page-capture.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
 import { describeMintFailure } from "./preview-publisher.js";
-const NAV_TIMEOUT_MS = 20_000;
-const READY_TIMEOUT_MS = 8_000;
 const WAIT_MS_CAP = 30_000;
 export function createPreviewSnapshotTool(state) {
     const logger = (state.logger ?? createNoopLogger()).named("preview-snapshot").with({ previewId: state.previewId });
@@ -75,53 +73,16 @@ export function createPreviewSnapshotTool(state) {
                 state.urlCell.expiresAt = result.data.expiresAt;
             }
             try {
-                return ok(await withPage(state.chrome, async (page) => {
-                    const consoleErrors = [];
-                    const failedRequests = [];
-                    page.on("console", (msg) => {
-                        if (msg.type() === "error")
-                            consoleErrors.push(msg.text());
-                    });
-                    page.on("pageerror", (err) => consoleErrors.push(`pageerror: ${err.message}`));
-                    page.on("requestfailed", (req) => {
-                        failedRequests.push({
-                            url: req.url(),
-                            reason: req.failure()?.errorText ?? "unknown",
-                        });
-                    });
-                    await page.goto(url, {
-                        waitUntil: "networkidle2",
-                        timeout: NAV_TIMEOUT_MS,
-                    });
-                    // Wait for the inflexa-theme-ready event (fired after echarts theme
-                    // registers). Check the `__inflexaThemeReady` sentinel first because
-                    // the page already deferred its dispatch — by the time we get here
-                    // via networkidle2, the event has likely already fired and a plain
-                    // addEventListener would block forever. The callback runs in the
-                    // browser context.
-                    await page
-                        .evaluate(new Function("timeout", "return new Promise(function(resolve){if(window.__inflexaThemeReady){resolve();return;}var t=setTimeout(resolve,timeout);document.addEventListener('inflexa-theme-ready',function(){clearTimeout(t);resolve();},{once:true});});"), READY_TIMEOUT_MS)
-                        .catch(() => {
-                        /* fall through — capture state as-is */
-                    });
-                    if (input.waitForSelector) {
-                        await page.waitForSelector(input.waitForSelector, { timeout: 5_000 }).catch(() => {
-                            /* not fatal */
-                        });
-                    }
-                    if (input.waitMs)
-                        await new Promise((r) => setTimeout(r, input.waitMs));
-                    const screenshot = await page.screenshot({
-                        encoding: "base64",
-                        fullPage: false,
-                    });
-                    return {
-                        ok: true,
-                        screenshotBase64: typeof screenshot === "string" ? screenshot : Buffer.from(screenshot).toString("base64"),
-                        consoleErrors,
-                        failedRequests,
-                    };
-                }));
+                const captured = await capturePage(state.chrome, url, {
+                    ...(input.waitForSelector !== undefined ? { waitForSelector: input.waitForSelector } : {}),
+                    ...(input.waitMs !== undefined ? { waitMs: input.waitMs } : {}),
+                });
+                return ok({
+                    ok: true,
+                    screenshotBase64: captured.screenshotBase64,
+                    consoleErrors: captured.consoleErrors,
+                    failedRequests: captured.failedRequests,
+                });
             }
             catch (err) {
                 return ok({