@inflexa-ai/harness 0.1.1

package/dist/sandbox/watchdog.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Per-sandbox-machine liveness watchdog (CONTEXT.md "Sandbox exec").
+ *
+ * A `@DBOS.scheduled` parent fires every minute, lists the active-sandbox
+ * registry, shards by `hash(sandboxId) % SHARD_COUNT`, and `startWorkflow`s
+ * one child check workflow per non-empty shard. The fan-out invariant —
+ * "no single invocation polls every sandbox" — is the user's explicit
+ * constraint.
+ *
+ * Each child workflow walks its shard, calls `isAlive`, and on `false`
+ * gates on `DBOS.getWorkflowStatus`: if the owning workflow is still
+ * `PENDING` or `ENQUEUED`, the child sends a `synthetic-failure`
+ * done-marker on `exec-event:${execId}` to unblock `awaitExec`. The
+ * marker carries `signature: null` and `kind: "synthetic-failure"` so the
+ * recv loop accepts it from the trusted in-process sender (see the harness-sandbox-exec spec).
+ *
+ * The pure sharding and check logic is hoisted so it can be unit-tested
+ * without spinning a DBOS runtime; `registerWatchdog` is the thin
+ * production wiring.
+ */
+import type pino from "pino";
+import type { ResultAsync } from "neverthrow";
+import type { DbError } from "../lib/db-result.js";
+import type { ActiveSandboxRow } from "../state/index.js";
+import type { SandboxClient } from "./client.js";
+import type { ExecEventMessage, ExecResult, SandboxLiveness, SandboxRef } from "./types.js";
+export declare const SHARD_COUNT = 8;
+/** Stable hash → shard mapping, exported for tests. */
+export declare function shardIndex(sandboxId: string, shardCount?: number): number;
+/** Partition the active-sandbox set into `shardCount` lists. */
+export declare function shardActiveSandboxes(rows: ActiveSandboxRow[], shardCount?: number): ActiveSandboxRow[][];
+export interface CheckShardDeps {
+    isAlive: (ref: SandboxRef) => Promise<SandboxLiveness>;
+    getStatus: (workflowId: string) => Promise<{
+        status: string;
+    } | null>;
+    /**
+     * Send a synthetic-failure marker on the per-exec topic. In production
+     * this is `DBOS.send`; injected here for testability.
+     */
+    sendSynthetic: (workflowId: string, execId: string, failure: ExecResult, reason: string) => Promise<void>;
+    logger?: Pick<pino.Logger, "info" | "warn" | "error">;
+}
+export interface CheckShardSummary {
+    activeCount: number;
+    deadCount: number;
+    syntheticSends: number;
+    liveWorkflowsSkipped: number;
+}
+/**
+ * Pure check logic over a shard: enumerate, call `isAlive`, and on
+ * dead-and-still-in-flight send a synthetic-failure. The in-flight guard
+ * is critical — without it a real `complete` arriving microseconds before
+ * the watchdog would race with the synthetic and produce a duplicate
+ * notification.
+ */
+export declare function checkShard(rows: ActiveSandboxRow[], deps: CheckShardDeps): Promise<CheckShardSummary>;
+/** Encodes the synthetic-failure marker on the per-exec topic envelope. */
+export declare function syntheticFailureMessage(execId: string, failure: ExecResult, reason: string, nowSec: number): ExecEventMessage;
+export interface WatchdogDeps {
+    queryActiveSandboxes: () => ResultAsync<ActiveSandboxRow[], DbError>;
+    sandboxClient: SandboxClient;
+    shardCount?: number;
+    logger?: Pick<pino.Logger, "info" | "warn" | "error">;
+}
+/**
+ * Production registration. Builds the parent + child registered workflows
+ * and the scheduled trigger. The parent fans out via `startWorkflow` so
+ * each child is durable in its own right (and recovers independently).
+ */
+export declare function registerWatchdog(deps: WatchdogDeps): void;

package/dist/sandbox/watchdog.js

@@ -0,0 +1,150 @@
+/**
+ * Per-sandbox-machine liveness watchdog (CONTEXT.md "Sandbox exec").
+ *
+ * A `@DBOS.scheduled` parent fires every minute, lists the active-sandbox
+ * registry, shards by `hash(sandboxId) % SHARD_COUNT`, and `startWorkflow`s
+ * one child check workflow per non-empty shard. The fan-out invariant —
+ * "no single invocation polls every sandbox" — is the user's explicit
+ * constraint.
+ *
+ * Each child workflow walks its shard, calls `isAlive`, and on `false`
+ * gates on `DBOS.getWorkflowStatus`: if the owning workflow is still
+ * `PENDING` or `ENQUEUED`, the child sends a `synthetic-failure`
+ * done-marker on `exec-event:${execId}` to unblock `awaitExec`. The
+ * marker carries `signature: null` and `kind: "synthetic-failure"` so the
+ * recv loop accepts it from the trusted in-process sender (see the harness-sandbox-exec spec).
+ *
+ * The pure sharding and check logic is hoisted so it can be unit-tested
+ * without spinning a DBOS runtime; `registerWatchdog` is the thin
+ * production wiring.
+ */
+import { createHash } from "node:crypto";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { unwrapOrThrow } from "../lib/result.js";
+import { workflowIdFromExec } from "./exec-id.js";
+import { syntheticFailureReason, syntheticFailureResult } from "./liveness.js";
+export const SHARD_COUNT = 8;
+const WATCHDOG_CRON = "*/60 * * * * *";
+/** Stable hash → shard mapping, exported for tests. */
+export function shardIndex(sandboxId, shardCount = SHARD_COUNT) {
+    const digest = createHash("sha1").update(sandboxId).digest();
+    const slice = digest.readUInt32BE(0);
+    return slice % shardCount;
+}
+/** Partition the active-sandbox set into `shardCount` lists. */
+export function shardActiveSandboxes(rows, shardCount = SHARD_COUNT) {
+    const shards = Array.from({ length: shardCount }, () => []);
+    for (const row of rows) {
+        shards[shardIndex(row.sandboxRef.sandboxId, shardCount)].push(row);
+    }
+    return shards;
+}
+const ACTIVE_WORKFLOW_STATUSES = new Set(["PENDING", "ENQUEUED"]);
+/**
+ * Pure check logic over a shard: enumerate, call `isAlive`, and on
+ * dead-and-still-in-flight send a synthetic-failure. The in-flight guard
+ * is critical — without it a real `complete` arriving microseconds before
+ * the watchdog would race with the synthetic and produce a duplicate
+ * notification.
+ */
+export async function checkShard(rows, deps) {
+    let deadCount = 0;
+    let syntheticSends = 0;
+    let liveWorkflowsSkipped = 0;
+    for (const row of rows) {
+        // We don't know the secret from here; reconstruct a minimal in-memory
+        // SandboxRef from the persisted shape. `isAlive` does not consult
+        // the secret, so this is safe.
+        const ref = {
+            ...row.sandboxRef,
+            callbackSecret: "",
+        };
+        let liveness;
+        try {
+            liveness = await deps.isAlive(ref);
+        }
+        catch (err) {
+            deps.logger?.warn({ sandboxId: row.sandboxRef.sandboxId, err: err instanceof Error ? err.message : String(err) }, "[sandbox-watchdog] isAlive threw — skipping this round");
+            continue;
+        }
+        if (liveness.alive)
+            continue;
+        deadCount++;
+        const workflowId = row.execId ? workflowIdFromExec(row.execId) : null;
+        if (!workflowId || !row.execId) {
+            // No exec was in flight when this row was tagged; nothing to
+            // unblock. Future change: clear the registry row separately.
+            continue;
+        }
+        const status = await deps.getStatus(workflowId);
+        if (!status || !ACTIVE_WORKFLOW_STATUSES.has(status.status)) {
+            liveWorkflowsSkipped++;
+            continue;
+        }
+        const reason = syntheticFailureReason(liveness);
+        const failure = syntheticFailureResult(row.execId, reason);
+        await deps.sendSynthetic(workflowId, row.execId, failure, reason);
+        syntheticSends++;
+    }
+    const summary = {
+        activeCount: rows.length,
+        deadCount,
+        syntheticSends,
+        liveWorkflowsSkipped,
+    };
+    deps.logger?.info(summary, "[sandbox-watchdog] shard check completed");
+    return summary;
+}
+/** Encodes the synthetic-failure marker on the per-exec topic envelope. */
+export function syntheticFailureMessage(execId, failure, reason, nowSec) {
+    return {
+        payload: {
+            done: true,
+            result: failure,
+            kind: "synthetic-failure",
+            reason,
+        },
+        signature: null,
+        timestamp: nowSec,
+    };
+}
+/**
+ * Production registration. Builds the parent + child registered workflows
+ * and the scheduled trigger. The parent fans out via `startWorkflow` so
+ * each child is durable in its own right (and recovers independently).
+ */
+export function registerWatchdog(deps) {
+    const shardCount = deps.shardCount ?? SHARD_COUNT;
+    const childCheckShard = DBOS.registerWorkflow(async (rows) => {
+        return checkShard(rows, {
+            isAlive: (ref) => deps.sandboxClient.isAlive(ref),
+            getStatus: async (workflowId) => (await DBOS.getWorkflowStatus(workflowId)),
+            sendSynthetic: async (workflowId, execId, failure, reason) => {
+                const msg = syntheticFailureMessage(execId, failure, reason, Math.floor((await DBOS.now()) / 1000));
+                await DBOS.send(workflowId, msg, `exec-event:${execId}`);
+            },
+            logger: deps.logger,
+        });
+    }, { name: "sandbox-watchdog-shard" });
+    // The scheduled target must itself be a registered workflow — DBOS's
+    // scheduler loop skips (and errors on) any `@scheduled` function that lacks
+    // a workflow registration. Register, then schedule the same callable.
+    const watchdogParent = DBOS.registerWorkflow(async () => {
+        // Checkpoint the live registry read: the row set gates how many
+        // `startWorkflow` calls fire below, so a differing set on replay would
+        // drift the recorded function-ID sequence (see the harness-durable-runtime spec).
+        const rows = await DBOS.runStep(async () => unwrapOrThrow(await deps.queryActiveSandboxes()), { name: "query-active-sandboxes" });
+        if (rows.length === 0)
+            return;
+        const shards = shardActiveSandboxes(rows, shardCount);
+        for (const shard of shards) {
+            if (shard.length === 0)
+                continue;
+            await DBOS.startWorkflow(childCheckShard)(shard);
+        }
+    }, { name: "sandbox-watchdog-parent" });
+    DBOS.registerScheduled(watchdogParent, {
+        name: "sandbox-watchdog-parent",
+        crontab: WATCHDOG_CRON,
+    });
+}

package/dist/schemas/artifact-manifest.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Artifact manifest schema — defines entries tracked in working memory.
+ *
+ * The manifest is updated deterministically by the workflow runner
+ * after each step completes, not by the LLM.
+ */
+import { z } from "zod";
+/** Artifact type inferred from the step subdirectory. */
+export declare const ArtifactTypeSchema: z.ZodEnum<{
+    output: "output";
+    script: "script";
+    figure: "figure";
+    log: "log";
+    notebook: "notebook";
+}>;
+export type ArtifactType = z.infer<typeof ArtifactTypeSchema>;
+/** A single artifact manifest entry. */
+export declare const ArtifactManifestEntrySchema: z.ZodObject<{
+    stepId: z.ZodString;
+    runId: z.ZodString;
+    path: z.ZodString;
+    size: z.ZodNumber;
+    type: z.ZodEnum<{
+        output: "output";
+        script: "script";
+        figure: "figure";
+        log: "log";
+        notebook: "notebook";
+    }>;
+    hash: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ArtifactManifestEntry = z.infer<typeof ArtifactManifestEntrySchema>;
+/** Infer artifact type from a file path based on its parent subdirectory. */
+export declare function inferArtifactType(filePath: string): ArtifactType;

package/dist/schemas/artifact-manifest.js

@@ -0,0 +1,36 @@
+/**
+ * Artifact manifest schema — defines entries tracked in working memory.
+ *
+ * The manifest is updated deterministically by the workflow runner
+ * after each step completes, not by the LLM.
+ */
+import { z } from "zod";
+/** Artifact type inferred from the step subdirectory. */
+export const ArtifactTypeSchema = z.enum(["output", "figure", "script", "log", "notebook"]);
+/** A single artifact manifest entry. */
+export const ArtifactManifestEntrySchema = z.object({
+    /** Step that produced this artifact. */
+    stepId: z.string(),
+    /** Workflow run ID. */
+    runId: z.string(),
+    /** Relative path within the workspace (e.g., runs/run-001/steps/de-analysis/output/results.csv). */
+    path: z.string(),
+    /** File size in bytes. */
+    size: z.number(),
+    /** Artifact type inferred from subdirectory. */
+    type: ArtifactTypeSchema,
+    /** SHA-256 content hash for integrity verification (e.g., sha256:abcdef...). */
+    hash: z.string().optional(),
+});
+/** Infer artifact type from a file path based on its parent subdirectory. */
+export function inferArtifactType(filePath) {
+    if (filePath.includes("/figures/"))
+        return "figure";
+    if (filePath.includes("/scripts/"))
+        return "script";
+    if (filePath.includes("/logs/"))
+        return "log";
+    if (filePath.includes("/notebooks/"))
+        return "notebook";
+    return "output";
+}

package/dist/schemas/data-profile-schemas.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Schemas for data profiling.
+ *
+ * Defines the profiler structured output schema used by the data-profile
+ * task and sandbox agent.
+ */
+import { z } from "zod";
+/** Per-file metadata — includes path so the agent can discover files itself. */
+export declare const ProfilerFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    description: z.ZodString;
+    dataType: z.ZodString;
+    format: z.ZodString;
+    rows: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cols: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    metrics: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+}, z.core.$strip>;
+/**
+ * Where an extracted subject fact came from. Used so downstream agents can
+ * judge how much to trust a field and so this profiler can flag conflicts.
+ */
+export declare const SubjectSourceEnum: z.ZodEnum<{
+    metadata: "metadata";
+    document: "document";
+    filename: "filename";
+    "user-context": "user-context";
+    inferred: "inferred";
+}>;
+export type SubjectSource = z.infer<typeof SubjectSourceEnum>;
+export declare const OrganismSchema: z.ZodObject<{
+    scientificName: z.ZodString;
+    taxonId: z.ZodString;
+    source: z.ZodEnum<{
+        metadata: "metadata";
+        document: "document";
+        filename: "filename";
+        "user-context": "user-context";
+        inferred: "inferred";
+    }>;
+    confidence: z.ZodEnum<{
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>;
+    notes: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Organism = z.infer<typeof OrganismSchema>;
+export declare const ProfilerOutputSchema: z.ZodObject<{
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        description: z.ZodString;
+        dataType: z.ZodString;
+        format: z.ZodString;
+        rows: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        cols: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        metrics: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    }, z.core.$strip>>;
+    analysisSummary: z.ZodString;
+    domain: z.ZodString;
+    subtype: z.ZodOptional<z.ZodString>;
+    organism: z.ZodNullable<z.ZodObject<{
+        scientificName: z.ZodString;
+        taxonId: z.ZodString;
+        source: z.ZodEnum<{
+            metadata: "metadata";
+            document: "document";
+            filename: "filename";
+            "user-context": "user-context";
+            inferred: "inferred";
+        }>;
+        confidence: z.ZodEnum<{
+            high: "high";
+            medium: "medium";
+            low: "low";
+        }>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    tissue: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    cellType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    condition: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    accessions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    experimentalDesign: z.ZodOptional<z.ZodString>;
+    qualityAssessment: z.ZodOptional<z.ZodObject<{
+        concerns: z.ZodArray<z.ZodString>;
+        strengths: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ProfilerOutput = z.infer<typeof ProfilerOutputSchema>;

package/dist/schemas/data-profile-schemas.js

@@ -0,0 +1,89 @@
+/**
+ * Schemas for data profiling.
+ *
+ * Defines the profiler structured output schema used by the data-profile
+ * task and sandbox agent.
+ */
+import { z } from "zod";
+// ── Profiler structured output (sandbox agent) ─────────────────────
+/** Per-file metadata — includes path so the agent can discover files itself. */
+export const ProfilerFileSchema = z.object({
+    path: z.string().describe("File path relative to analysis root (e.g. data/inputs/{fileId}/counts.txt)"),
+    description: z.string().describe("What this file contains and its role in the analysis"),
+    dataType: z
+        .string()
+        .describe("Semantic data type: count-matrix, normalized-expression, variants, alignments, " +
+        "clinical-metadata, clinical-sdtm, clinical-adam, clinical-response, " +
+        "pharmacokinetic-data, adverse-events, safety-labs, " +
+        "molecular-structures, annotations"),
+    format: z.string().describe("File format (e.g. CSV, TSV, h5ad, MTX, VCF, BAM, SDF, FASTQ)"),
+    rows: z.number().nullish(),
+    cols: z.number().nullish(),
+    tags: z.array(z.string()).optional().describe("Searchable labels for downstream discovery"),
+    warnings: z.array(z.string()).optional().describe("Quality issues or concerns specific to this file"),
+    metrics: z
+        .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+        .optional()
+        .describe("Format-specific profiling metrics as flat key-value pairs (e.g. sparsity, medianLibrarySize, tiTvRatio, gcContent, missingRate)"),
+});
+/**
+ * Where an extracted subject fact came from. Used so downstream agents can
+ * judge how much to trust a field and so this profiler can flag conflicts.
+ */
+export const SubjectSourceEnum = z.enum([
+    "metadata", // sample-sheet/header column, internal manifest
+    "document", // paper PDF, README, methods doc
+    "filename", // file or folder naming convention (GSExxx, "human_", etc.)
+    "user-context", // user-supplied analysis context
+    "inferred", // inferred from data content (e.g. gene symbol patterns)
+]);
+export const OrganismSchema = z.object({
+    scientificName: z.string().describe("Latin binomial, e.g. 'Homo sapiens', 'Macaca fascicularis', 'Mus musculus'."),
+    taxonId: z.string().describe("NCBI Taxonomy ID as a string, e.g. '9606' (human), '9541' (cynomolgus macaque), '10090' (mouse)."),
+    source: SubjectSourceEnum,
+    confidence: z
+        .enum(["high", "medium", "low"])
+        .describe("high: explicit organism column or paper/README statement. " +
+        "medium: filename convention or accession lookup. " +
+        "low: inferred from gene IDs or other indirect signals, OR sources disagree (in which case also record the conflict in qualityAssessment.concerns)."),
+    notes: z.string().optional().describe("Brief note when source is 'inferred' or confidence is 'low' (one sentence)."),
+});
+export const ProfilerOutputSchema = z.object({
+    files: z.array(ProfilerFileSchema),
+    analysisSummary: z.string().describe("Narrative overview of the dataset — structure, content, analytical potential, and limitations"),
+    domain: z.string().describe("Scientific domain (e.g. transcriptomics, proteomics, genomics, chemistry, clinical, imaging, metabolomics, multi-omics)"),
+    subtype: z.string().optional().describe("Specific subtype within domain (e.g. bulk-rna-seq, single-cell, LC-MS/MS, whole-genome-sequencing)"),
+    organism: OrganismSchema.nullable().describe("Subject organism, identified from any input (metadata files, paper PDFs, READMEs, filenames, accession patterns). " +
+        "Set to null ONLY when no input identifies the organism — never guess. " +
+        "A null organism is acceptable; a wrong taxon ID is not. " +
+        "If inputs disagree on organism, pick the most-trusted source, set confidence accordingly, and add the conflict to qualityAssessment.concerns."),
+    tissue: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Subject tissue or anatomical site when applicable (e.g. 'rectal mucosal biopsy', 'liver', 'PBMC', 'whole blood'). null if not applicable or unknown."),
+    cellType: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Subject cell type when applicable (e.g. 'CD4+ T cells', 'iPSC-derived hepatocytes', 'primary hepatocytes'). null if not applicable or unknown."),
+    condition: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Disease, treatment, or perturbation under study (e.g. 'Ulcerative Colitis vs healthy controls', 'cisplatin dose-response', 'CRISPR knockout of TP53'). null if not applicable or unknown."),
+    accessions: z
+        .array(z.string())
+        .optional()
+        .describe("Public dataset accessions found in any input (filenames, metadata, paper). " +
+        "GEO (GSE/GSM), SRA (SRP/SRR/SRX), BioProject (PRJNA/PRJEB/PRJDB), ArrayExpress (E-MTAB-xxxx), dbGaP (phs), EGA (EGAS/EGAD)."),
+    experimentalDesign: z.string().optional().describe("Description of experimental design — conditions, groups, comparisons, replicates, pairing"),
+    qualityAssessment: z
+        .object({
+        concerns: z
+            .array(z.string())
+            .describe("Dataset-wide quality issues (e.g. batch effects, sample imbalance, high missing rate, conflicting organism declarations across inputs)"),
+        strengths: z.array(z.string()).describe("Dataset strengths (e.g. deep coverage, balanced groups, low duplication)"),
+    })
+        .optional(),
+});

package/dist/schemas/file-metadata.d.ts

@@ -0,0 +1,51 @@
+import { z } from "zod";
+export declare const FileMetadataSchema: z.ZodObject<{
+    role: z.ZodEnum<{
+        input: "input";
+        step_output: "step_output";
+    }>;
+    dataType: z.ZodString;
+    format: z.ZodString;
+    rows: z.ZodOptional<z.ZodNumber>;
+    cols: z.ZodOptional<z.ZodNumber>;
+    producerStep: z.ZodOptional<z.ZodString>;
+    producerRun: z.ZodOptional<z.ZodString>;
+    producerAgent: z.ZodOptional<z.ZodString>;
+    omicsType: z.ZodOptional<z.ZodString>;
+    organism: z.ZodOptional<z.ZodString>;
+    featureType: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export type FileMetadata = z.infer<typeof FileMetadataSchema>;
+/**
+ * One file's metadata as submitted by the describer agent through the
+ * `submit_file_metadata` tool. Keyed by `path` — the tool validates each
+ * path against the known artifact set, so descriptions are matched to files
+ * by path, never by array position.
+ */
+export declare const SubmittedFileDescriptionSchema: z.ZodObject<{
+    path: z.ZodString;
+    description: z.ZodString;
+    dataType: z.ZodString;
+    format: z.ZodString;
+    rows: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    cols: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type SubmittedFileDescription = z.infer<typeof SubmittedFileDescriptionSchema>;
+/** Input contract for the `submit_file_metadata` tool. */
+export declare const SubmitFileMetadataInputSchema: z.ZodObject<{
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        description: z.ZodString;
+        dataType: z.ZodString;
+        format: z.ZodString;
+        rows: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        cols: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SubmitFileMetadataInput = z.infer<typeof SubmitFileMetadataInputSchema>;

package/dist/schemas/file-metadata.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+export const FileMetadataSchema = z
+    .object({
+    role: z.enum(["input", "step_output"]),
+    dataType: z.string(),
+    format: z.string(),
+    rows: z.number().optional(),
+    cols: z.number().optional(),
+    producerStep: z.string().optional(),
+    producerRun: z.string().optional(),
+    producerAgent: z.string().optional(),
+    omicsType: z.string().optional(),
+    organism: z.string().optional(),
+    featureType: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    warnings: z.array(z.string()).optional(),
+})
+    .passthrough();
+/**
+ * One file's metadata as submitted by the describer agent through the
+ * `submit_file_metadata` tool. Keyed by `path` — the tool validates each
+ * path against the known artifact set, so descriptions are matched to files
+ * by path, never by array position.
+ */
+export const SubmittedFileDescriptionSchema = z.object({
+    /** Exact path of the file being described, copied from the prompt's list. */
+    path: z.string(),
+    description: z.string(),
+    dataType: z.string(),
+    format: z.string(),
+    rows: z.number().nullish(),
+    cols: z.number().nullish(),
+    tags: z.array(z.string()).optional(),
+    warnings: z.array(z.string()).optional(),
+});
+/** Input contract for the `submit_file_metadata` tool. */
+export const SubmitFileMetadataInputSchema = z.object({
+    files: z.array(SubmittedFileDescriptionSchema),
+});