@inflexa-ai/harness 0.1.1

package/dist/execution/run-authorizer.d.ts

@@ -0,0 +1,43 @@
+/**
+ * RunAuthorizer — the async-edge run-authorization seam.
+ *
+ * Every async edge that starts durable work (`execute_plan`, `run_ephemeral`,
+ * data-profile) must turn the caller's opaque auth into a durable `RunSession`
+ * before dispatching a workflow. That turning is the ONE place the credential
+ * kind matters (a live caller credential → mint a fresh run credential Cortex
+ * owns; an existing run credential → reuse it, caller-owned) — so it lives
+ * behind this seam, not in the harness tools. The managed impl owns the
+ * mint/reuse + revoke against the host authority; an OSS impl issues a local
+ * `RunSession` with no host call, no jti, no revoke. The harness's tools depend only on
+ * this interface and never read a credential.
+ *
+ * Mirrors the `PreviewPublisher` seam: a narrow interface in the harness, the managed
+ * realization injected at the composition root.
+ */
+import type { AuthContext, Provenance, RunFrame, RunSession, Scope } from "../auth/types.js";
+/** What an async edge knows when it authorizes a run: the opaque caller auth,
+ * the scope + provenance to stamp on the run, and the run frame to mint for. */
+export interface AuthorizeRunInput {
+    readonly auth: AuthContext;
+    readonly scope: Scope;
+    readonly provenance: Provenance;
+    readonly frame: RunFrame;
+}
+export interface RunAuthorization {
+    readonly runSession: RunSession;
+    /**
+     * True when this authorizer minted the run credential and therefore owns its
+     * lifecycle — the run's terminal path must `revoke`. False when an existing
+     * run credential was reused (the caller owns it; `revoke` is a no-op).
+     */
+    readonly ownsMandate: boolean;
+}
+/**
+ * Authorize durable work at the async edge. `authorize` produces the durable
+ * `RunSession`; `revoke` releases a self-minted run credential on the terminal
+ * path (a no-op for reused or local authorizations).
+ */
+export interface RunAuthorizer {
+    authorize(input: AuthorizeRunInput): Promise<RunAuthorization>;
+    revoke(authorization: RunAuthorization, reason: string): Promise<void>;
+}

package/dist/execution/run-authorizer.js

@@ -0,0 +1,17 @@
+/**
+ * RunAuthorizer — the async-edge run-authorization seam.
+ *
+ * Every async edge that starts durable work (`execute_plan`, `run_ephemeral`,
+ * data-profile) must turn the caller's opaque auth into a durable `RunSession`
+ * before dispatching a workflow. That turning is the ONE place the credential
+ * kind matters (a live caller credential → mint a fresh run credential Cortex
+ * owns; an existing run credential → reuse it, caller-owned) — so it lives
+ * behind this seam, not in the harness tools. The managed impl owns the
+ * mint/reuse + revoke against the host authority; an OSS impl issues a local
+ * `RunSession` with no host call, no jti, no revoke. The harness's tools depend only on
+ * this interface and never read a credential.
+ *
+ * Mirrors the `PreviewPublisher` seam: a narrow interface in the harness, the managed
+ * realization injected at the composition root.
+ */
+export {};

package/dist/execution/run-launcher.d.ts

@@ -0,0 +1,36 @@
+/**
+ * RunLauncher — the durability-engine launch seam.
+ *
+ * The async-edge tools (`execute_plan`, `run_ephemeral`) start durable runs but
+ * must not reach the durability engine directly — that engine is quarantined
+ * out of tools and the loop. This seam is the one capability they need: start a
+ * registered workflow under a caller-chosen id, either fire-and-forget or
+ * awaiting its result inline. `launchAndAwait` hides the engine's cancellation
+ * behind a discriminated outcome, so no engine error type leaks to callers.
+ *
+ * The workflow itself stays injected — it is the registered-workflow function
+ * reference, typed `(input) => Promise<result>`; the launcher only owns the
+ * start/await/cancel mechanics around it.
+ */
+export interface LaunchOptions {
+    /** Caller-chosen durable workflow id (e.g. the runId). */
+    readonly workflowId: string;
+}
+export interface LaunchRunOptions {
+    /** Aborting cancels the in-flight run; wired internally by the launcher. */
+    readonly signal: AbortSignal;
+}
+/** Result of an awaited launch: the value on completion, or a cancelled
+ * sentinel that replaces the engine's cancellation error. */
+export type LaunchOutcome<R> = {
+    readonly status: "completed";
+    readonly result: R;
+} | {
+    readonly status: "cancelled";
+};
+export interface RunLauncher {
+    /** Fire-and-forget: resolves once the run is durably started. */
+    launch<I>(workflow: (input: I) => Promise<unknown>, opts: LaunchOptions, input: I): Promise<void>;
+    /** Start the run and await its result inline, wiring cancel-on-abort. */
+    launchAndAwait<I, R>(workflow: (input: I) => Promise<R>, opts: LaunchOptions, input: I, runOpts: LaunchRunOptions): Promise<LaunchOutcome<R>>;
+}

package/dist/execution/run-launcher.js

@@ -0,0 +1,15 @@
+/**
+ * RunLauncher — the durability-engine launch seam.
+ *
+ * The async-edge tools (`execute_plan`, `run_ephemeral`) start durable runs but
+ * must not reach the durability engine directly — that engine is quarantined
+ * out of tools and the loop. This seam is the one capability they need: start a
+ * registered workflow under a caller-chosen id, either fire-and-forget or
+ * awaiting its result inline. `launchAndAwait` hides the engine's cancellation
+ * behind a discriminated outcome, so no engine error type leaks to callers.
+ *
+ * The workflow itself stays injected — it is the registered-workflow function
+ * reference, typed `(input) => Promise<result>`; the launcher only owns the
+ * start/await/cancel mechanics around it.
+ */
+export {};

package/dist/execution/run-synthesis.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Run synthesizer — a single-shot agent loop driven through `runAgent`:
+ *
+ *   - `submit_synthesis`  — terminal: schema + semantic validation, captures
+ *                            the outcome. Re-callable on rejection.
+ *   - `report_blocker`    — terminal: the run produced nothing synthesizable.
+ *   - `literature_reviewer` — research sub-agent exposed as a tool. The tool
+ *                            re-uses `createLiteratureReviewerTool`; the
+ *                            sub-agent loop's brief is the only context handed
+ *                            across the boundary (forSubAgent semantics).
+ *
+ * Two deliverables on a happy path: `synthesis.json` written to the run dir
+ * and a `data-run-synthesis` chat data part emitted via the `emit` callback
+ * the dep wrapper provides (the wrapper forwards events to the parent
+ * workflow's `"events"` stream).
+ *
+ * The dep wrapper handles failure semantics — if this function throws or
+ * resolves with `{ kind: "failed" }`, the wrapper emits a synthesis-progress
+ * `failed` part. We do not throw here for routine submitter rejections.
+ */
+import { type RunSynthesis } from "../schemas/run-synthesis.js";
+import type { StepSummary } from "../schemas/step-summary.js";
+import type { ChatDataPart, EmitFn } from "../loop/types.js";
+import type { ChatProvider } from "../providers/types.js";
+import type { RunSession } from "../auth/types.js";
+import { type Tool } from "../tools/define-tool.js";
+import type { BioToolKeys } from "../tools/bio/keys.js";
+type SynthesizerOutcome = {
+    kind: "submitted";
+    synthesis: RunSynthesis;
+} | {
+    kind: "blocker";
+    reason: string;
+};
+interface OutcomeHolder {
+    outcome: SynthesizerOutcome | null;
+}
+/**
+ * Test-only — expose the inner-tool factory so unit tests can assert on
+ * validation + outcome capture without driving the whole agent loop.
+ */
+export declare function __buildInnerToolsForTest(args: {
+    knownStepIds: ReadonlySet<string>;
+    runId: string;
+}): {
+    submit: Tool;
+    blocker: Tool;
+    holder: OutcomeHolder;
+};
+export interface GenerateRunSynthesisInput {
+    readonly provider: ChatProvider;
+    readonly session: RunSession;
+    readonly model: string;
+    /** API keys for the bio/chem tools the embedded literature reviewer uses. */
+    readonly bioKeys: BioToolKeys;
+    /** Step summaries from the completed run. Non-empty. */
+    readonly summaries: readonly StepSummary[];
+    /** Plan analytical narrative for context. */
+    readonly planNarrative: string;
+    /** Run id — submitted synthesis must match. */
+    readonly runId: string;
+    /** Optional cancellation. */
+    readonly signal?: AbortSignal;
+    /** Optional UI event sink (chat data parts forwarded to the parent stream). */
+    readonly emit?: EmitFn;
+}
+export type GenerateRunSynthesisResult = {
+    kind: "synthesis";
+    synthesis: RunSynthesis;
+} | {
+    kind: "skipped";
+    reason: string;
+};
+/**
+ * Drive the synthesizer agent loop to a terminal outcome — either a
+ * validated synthesis (`submit_synthesis`) or a blocker (`report_blocker`).
+ * Throws when neither terminal is reached (loop cap or external abort).
+ */
+export declare function generateRunSynthesis(input: GenerateRunSynthesisInput): Promise<GenerateRunSynthesisResult>;
+export interface LoadStepSummariesInput {
+    /** Absolute host root of the analysis's workspace tree. */
+    readonly workspaceRoot: string;
+    readonly runId: string;
+    readonly completedSteps: readonly string[];
+    readonly agentByStepId?: Readonly<Record<string, string>>;
+}
+/**
+ * Read each completed step's `output/summary.md`. Steps with missing or empty
+ * summaries are silently dropped — the caller decides what to do when the
+ * resulting array is empty.
+ */
+export declare function loadStepSummariesFromDisk(args: LoadStepSummariesInput): Promise<StepSummary[]>;
+export interface PersistSynthesisInput {
+    /** Absolute host root of the analysis's workspace tree. */
+    readonly workspaceRoot: string;
+    readonly runId: string;
+    readonly synthesis: RunSynthesis;
+}
+export declare function persistSynthesis(args: PersistSynthesisInput): Promise<string>;
+export declare function formatSynthesisEmbeddingText(synthesis: RunSynthesis): string;
+/**
+ * Build the `data-run-synthesis` chat part the parent stream emits when the
+ * synthesizer completes successfully. The schema mirrors the harness's contracts
+ * `RunSynthesisPart` interface — keep them in lockstep.
+ */
+export declare function buildRunSynthesisPart(runId: string, synthesis: RunSynthesis): ChatDataPart;
+export {};

package/dist/execution/run-synthesis.js

@@ -0,0 +1,329 @@
+/**
+ * Run synthesizer — a single-shot agent loop driven through `runAgent`:
+ *
+ *   - `submit_synthesis`  — terminal: schema + semantic validation, captures
+ *                            the outcome. Re-callable on rejection.
+ *   - `report_blocker`    — terminal: the run produced nothing synthesizable.
+ *   - `literature_reviewer` — research sub-agent exposed as a tool. The tool
+ *                            re-uses `createLiteratureReviewerTool`; the
+ *                            sub-agent loop's brief is the only context handed
+ *                            across the boundary (forSubAgent semantics).
+ *
+ * Two deliverables on a happy path: `synthesis.json` written to the run dir
+ * and a `data-run-synthesis` chat data part emitted via the `emit` callback
+ * the dep wrapper provides (the wrapper forwards events to the parent
+ * workflow's `"events"` stream).
+ *
+ * The dep wrapper handles failure semantics — if this function throws or
+ * resolves with `{ kind: "failed" }`, the wrapper emits a synthesis-progress
+ * `failed` part. We do not throw here for routine submitter rejections.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { writeFileWithinRoot } from "../lib/fs-helpers.js";
+import { RunSynthesisSchema } from "../schemas/run-synthesis.js";
+import { synthesisAgentPrompt } from "../prompts/synthesis-agent.js";
+import { runDir } from "../workspace/paths.js";
+import { runToTerminal } from "../loop/run-to-terminal.js";
+import { passthroughStep } from "../loop/run-step.js";
+import { defineTool } from "../tools/define-tool.js";
+import { createLiteratureReviewerTool } from "../tools/research/literature-reviewer.js";
+// ── Agent identity / budgets ────────────────────────────────────────
+const AGENT_ID = "run-synthesizer";
+/**
+ * Budget for the synthesizer loop: read summaries + 1–3 reviewer delegations
+ * + draft + 1–2 submit/fix cycles + headroom.
+ */
+const SYNTHESIZER_MAX_ITERATIONS = 25;
+// ── Validation ──────────────────────────────────────────────────────
+function zodIssuesToValidationIssues(error, rootPath = "synthesis") {
+    return error.issues.map((i) => ({
+        path: [rootPath, ...i.path.map((p) => String(p))].join("."),
+        code: "schema",
+        message: i.message,
+    }));
+}
+function semanticCheck(synthesis, ctx) {
+    const issues = [];
+    if (synthesis.runId !== ctx.runId) {
+        issues.push({
+            path: "synthesis.runId",
+            code: "semantic",
+            message: `runId must be "${ctx.runId}"`,
+        });
+    }
+    for (const [i, f] of synthesis.findings.entries()) {
+        if (!ctx.knownStepIds.has(f.stepId)) {
+            issues.push({
+                path: `synthesis.findings[${i}].stepId`,
+                code: "semantic",
+                message: `stepId "${f.stepId}" is not in the input summaries`,
+                hint: `Known stepIds: ${Array.from(ctx.knownStepIds).join(", ")}`,
+            });
+        }
+    }
+    const findingKeys = new Set(synthesis.findings.map((f) => `${f.stepId}::${f.title}`));
+    for (const [ti, t] of synthesis.themes.entries()) {
+        for (const [fi, ref] of t.findings.entries()) {
+            if (!findingKeys.has(`${ref.stepId}::${ref.title}`)) {
+                issues.push({
+                    path: `synthesis.themes[${ti}].findings[${fi}]`,
+                    code: "semantic",
+                    message: `theme reference (stepId="${ref.stepId}", title="${ref.title}") ` + `does not match any entry in findings[]`,
+                });
+            }
+        }
+    }
+    const citedPmids = new Set(synthesis.findings.flatMap((f) => f.references.map((r) => r.pmid)));
+    for (const [i, r] of synthesis.keyReferences.entries()) {
+        if (!citedPmids.has(r.pmid)) {
+            issues.push({
+                path: `synthesis.keyReferences[${i}].pmid`,
+                code: "semantic",
+                message: `keyReferences pmid "${r.pmid}" does not appear in any finding.references[]`,
+                hint: "Every keyReferences entry must already be cited by at least one finding.",
+            });
+        }
+    }
+    const pmidRe = /^\d+$/;
+    for (const [fi, f] of synthesis.findings.entries()) {
+        for (const [ri, r] of f.references.entries()) {
+            if (!pmidRe.test(r.pmid)) {
+                issues.push({
+                    path: `synthesis.findings[${fi}].references[${ri}].pmid`,
+                    code: "semantic",
+                    message: `pmid "${r.pmid}" is not a valid numeric PMID`,
+                });
+            }
+        }
+    }
+    for (const [i, r] of synthesis.keyReferences.entries()) {
+        if (!pmidRe.test(r.pmid)) {
+            issues.push({
+                path: `synthesis.keyReferences[${i}].pmid`,
+                code: "semantic",
+                message: `pmid "${r.pmid}" is not a valid numeric PMID`,
+            });
+        }
+    }
+    return issues;
+}
+function fullyValidate(candidate, ctx) {
+    const parsed = RunSynthesisSchema.safeParse(candidate);
+    if (!parsed.success) {
+        return { valid: false, issues: zodIssuesToValidationIssues(parsed.error) };
+    }
+    const semanticIssues = semanticCheck(parsed.data, ctx);
+    if (semanticIssues.length > 0) {
+        return { valid: false, issues: semanticIssues };
+    }
+    return { valid: true, synthesis: parsed.data };
+}
+// ── Inner tools ─────────────────────────────────────────────────────
+function buildSubmitTool(holder, ctx) {
+    return defineTool({
+        id: "submit_synthesis",
+        description: "Submit the final synthesis. Re-validates payload against the schema " +
+            "and semantic checks (stepId refs, theme→finding refs, keyReferences " +
+            "PMIDs cited, numeric PMIDs). On success returns {accepted: true} — " +
+            "STOP after this. On rejection returns {accepted: false, issues} — " +
+            "fix the specific fields at each issue path and call again, or switch " +
+            "to report_blocker if the synthesis cannot be made valid.",
+        inputSchema: z.object({ synthesis: z.unknown() }),
+        execute: async (input) => {
+            if (holder.outcome !== null) {
+                return ok({
+                    accepted: false,
+                    issues: [
+                        {
+                            path: "synthesis",
+                            code: "semantic",
+                            message: "A terminal outcome has already been recorded; submit_synthesis " + "can only be called once per invocation.",
+                        },
+                    ],
+                });
+            }
+            const result = fullyValidate(input.synthesis, ctx);
+            if (!result.valid) {
+                return ok({ accepted: false, issues: result.issues });
+            }
+            holder.outcome = { kind: "submitted", synthesis: result.synthesis };
+            return ok({ accepted: true });
+        },
+    });
+}
+function buildBlockerTool(holder) {
+    return defineTool({
+        id: "report_blocker",
+        description: "Terminal. Use when the run produced no synthesizable content (all " +
+            "summaries empty, contradictory to the point of incoherence, or no " +
+            "findings worth surfacing). Pass a short reason. Stop after calling.",
+        inputSchema: z.object({ reason: z.string().min(1) }),
+        execute: async (input) => {
+            if (holder.outcome === null) {
+                holder.outcome = { kind: "blocker", reason: input.reason };
+            }
+            return ok({ recorded: true });
+        },
+    });
+}
+/**
+ * Test-only — expose the inner-tool factory so unit tests can assert on
+ * validation + outcome capture without driving the whole agent loop.
+ */
+export function __buildInnerToolsForTest(args) {
+    const holder = { outcome: null };
+    const ctx = {
+        knownStepIds: args.knownStepIds,
+        runId: args.runId,
+    };
+    return {
+        submit: buildSubmitTool(holder, ctx),
+        blocker: buildBlockerTool(holder),
+        holder,
+    };
+}
+/**
+ * Drive the synthesizer agent loop to a terminal outcome — either a
+ * validated synthesis (`submit_synthesis`) or a blocker (`report_blocker`).
+ * Throws when neither terminal is reached (loop cap or external abort).
+ */
+export async function generateRunSynthesis(input) {
+    if (input.summaries.length === 0) {
+        throw new Error("Run synthesis: no step summaries to synthesize");
+    }
+    const knownStepIds = new Set(input.summaries.map((s) => s.stepId));
+    const holder = { outcome: null };
+    const innerCtx = { knownStepIds, runId: input.runId };
+    const reviewer = createLiteratureReviewerTool({
+        provider: input.provider,
+        model: input.model,
+        bioKeys: input.bioKeys,
+    });
+    const submitTool = buildSubmitTool(holder, innerCtx);
+    const blockerTool = buildBlockerTool(holder);
+    const tools = [submitTool, blockerTool, reviewer];
+    const agent = {
+        id: AGENT_ID,
+        systemPrompt: synthesisAgentPrompt,
+        model: input.model,
+        tools,
+        maxIterations: SYNTHESIZER_MAX_ITERATIONS,
+    };
+    const prompt = buildSynthesizerPrompt(input.planNarrative, input.summaries, input.runId);
+    const signal = input.signal ?? new AbortController().signal;
+    const emit = input.emit ?? (() => { });
+    const loopDeps = {
+        provider: input.provider,
+        signal,
+        emit,
+        runStep: passthroughStep,
+    };
+    await runToTerminal(agent, [{ role: "user", content: prompt }], input.session, loopDeps, {
+        resolved: () => holder.outcome !== null,
+        tools: [submitTool, blockerTool],
+        nudge: "You ended without calling a terminal tool. You MUST call " +
+            "submit_synthesis with the final synthesis now, or report_blocker " +
+            "if the run produced nothing synthesizable. Do not reply with prose.",
+    });
+    const outcome = holder.outcome;
+    if (outcome?.kind === "submitted") {
+        return { kind: "synthesis", synthesis: outcome.synthesis };
+    }
+    if (outcome?.kind === "blocker") {
+        return { kind: "skipped", reason: outcome.reason };
+    }
+    if (signal.aborted) {
+        throw new Error("Run synthesis was cancelled.");
+    }
+    throw new Error("Run synthesis completed without a terminal tool call — the synthesizer " + "did not call submit_synthesis or report_blocker.");
+}
+/**
+ * Read each completed step's `output/summary.md`. Steps with missing or empty
+ * summaries are silently dropped — the caller decides what to do when the
+ * resulting array is empty.
+ */
+export async function loadStepSummariesFromDisk(args) {
+    const out = [];
+    for (const stepId of args.completedSteps) {
+        const path = join(args.workspaceRoot, "runs", args.runId, stepId, "output", "summary.md");
+        try {
+            const markdown = await readFile(path, "utf8");
+            if (markdown.trim().length === 0)
+                continue;
+            out.push({
+                stepId,
+                agentId: args.agentByStepId?.[stepId] ?? "scientific-executor",
+                markdown,
+            });
+        }
+        catch {
+            // Missing summary — skip silently. Steps that produced no summary do
+            // not contribute to synthesis.
+        }
+    }
+    return out;
+}
+export async function persistSynthesis(args) {
+    // Confine to the run directory, not the whole workspace: synthesis.json sits
+    // at runs/{runId}/, above any step's RW mount and never in the hard-linked
+    // `data/` inputs.
+    const runRoot = join(args.workspaceRoot, runDir(args.runId));
+    const path = join(runRoot, "synthesis.json");
+    await writeFileWithinRoot(runRoot, path, JSON.stringify(args.synthesis, null, 2));
+    return path;
+}
+// ── Embedding text ──────────────────────────────────────────────────
+export function formatSynthesisEmbeddingText(synthesis) {
+    return [
+        "# Overview",
+        synthesis.overview,
+        "",
+        "# Conclusions",
+        synthesis.conclusions,
+        "",
+        "# Key Findings",
+        ...synthesis.findings.flatMap((f) => [
+            `## ${f.title} [${f.noveltyStatus}]`,
+            f.description,
+            f.literatureInterpretation,
+            ...(f.references.length > 0 ? f.references.map((r) => `- [PMID:${r.pmid}] ${r.citation} (${r.concordance})`) : []),
+            "",
+        ]),
+        "# Themes",
+        ...synthesis.themes.flatMap((t) => [`## ${t.name}`, t.narrative, ""]),
+        "# Limitations",
+        ...synthesis.limitations.map((l) => `- ${l}`),
+        "",
+        "# Key References",
+        ...synthesis.keyReferences.map((r) => `- [PMID:${r.pmid}] ${r.citation} — ${r.description}`),
+    ].join("\n");
+}
+// ── Prompt builder ──────────────────────────────────────────────────
+function buildSynthesizerPrompt(planNarrative, summaries, runId) {
+    const summaryBlock = summaries.map((s) => `### ${s.stepId} (${s.agentId})\n\n${s.markdown}`).join("\n\n---\n\n");
+    return [`runId: "${runId}"`, "", "## Analytical Narrative", planNarrative, "", "## Step Summaries", summaryBlock].join("\n");
+}
+// ── Chat data part builders ─────────────────────────────────────────
+/**
+ * Build the `data-run-synthesis` chat part the parent stream emits when the
+ * synthesizer completes successfully. The schema mirrors the harness's contracts
+ * `RunSynthesisPart` interface — keep them in lockstep.
+ */
+export function buildRunSynthesisPart(runId, synthesis) {
+    return {
+        type: "data-run-synthesis",
+        data: {
+            id: `synthesis-${runId}`,
+            runId,
+            overview: synthesis.overview,
+            conclusions: synthesis.conclusions,
+            findings: synthesis.findings,
+            themes: synthesis.themes,
+            limitations: synthesis.limitations,
+            keyReferences: synthesis.keyReferences,
+        },
+    };
+}

package/dist/execution/staged-input.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Staged-input manifest contract.
+ *
+ * The harness's durable workflows assume an analysis's input tree is already populated
+ * under `data/inputs/` (see the data-profile-init spec) — they never download or copy input data, and
+ * never call a staging step. The embedder stages the tree at the async edge,
+ * once, BEFORE invoking the harness: the managed service downloads from object storage;
+ * the CLI copies/links the user's local files. The embedder hands the resulting
+ * manifest to the data-profile trigger, which rides it in the workflow input.
+ *
+ * This file declares only the manifest element — the data shape the harness consumes.
+ * The act of producing it (download / copy) lives entirely caller-side; the harness
+ * holds no staging seam.
+ */
+/**
+ * One input file present under the analysis data dir, with its content hash.
+ * `fileId`/`mountName`/`key`/`fileName` are source identifiers the managed
+ * service derives from its object-store index and the CLI synthesizes from the
+ * local path — the harness treats them as opaque labels.
+ */
+export interface StagedInput {
+    readonly fileId: string;
+    readonly mountName: string;
+    readonly key: string;
+    readonly fileName: string;
+    readonly hash: string;
+    readonly size: number;
+    /**
+     * Last-modification time in epoch milliseconds. With `size` and `fileId` it forms
+     * the file's drift signature — the value a consumer compares against a completed
+     * profile's `inputFiles` to decide whether the same bytes were profiled, since a
+     * `fileId` is a path identity and survives an in-place content edit unchanged.
+     *
+     * Embedder-supplied and opaque: the CLI reads it from the same `stat` that yields
+     * `size`; a managed service supplies its object store's last-modified epoch. The
+     * harness persists it verbatim and never stats a source file.
+     */
+    readonly mtimeMs: number;
+    /** Path relative to the data dir, e.g. "inputs/{mountName}/{key}". */
+    readonly relativePath: string;
+}

package/dist/execution/staged-input.js

@@ -0,0 +1,15 @@
+/**
+ * Staged-input manifest contract.
+ *
+ * The harness's durable workflows assume an analysis's input tree is already populated
+ * under `data/inputs/` (see the data-profile-init spec) — they never download or copy input data, and
+ * never call a staging step. The embedder stages the tree at the async edge,
+ * once, BEFORE invoking the harness: the managed service downloads from object storage;
+ * the CLI copies/links the user's local files. The embedder hands the resulting
+ * manifest to the data-profile trigger, which rides it in the workflow input.
+ *
+ * This file declares only the manifest element — the data shape the harness consumes.
+ * The act of producing it (download / copy) lives entirely caller-side; the harness
+ * holds no staging seam.
+ */
+export {};

package/dist/execution/step-summary-metrics.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Step-summary OTel metrics — Middleware.io routing follows the global
+ * meter provider (see `harness/lib/otel.ts`).
+ *
+ * cortex.summary.null_count — counter, incremented when a step-summary
+ *   turn returns empty markdown or its provider call throws. Tagged with
+ *   `agent_id` and a `reason` discriminator (`"empty" | "throw"`) so
+ *   weekly review can split mode of failure.
+ */
+export declare function incrementSummaryNullCount(agentId: string, reason: "empty" | "throw"): void;

package/dist/execution/step-summary-metrics.js

@@ -0,0 +1,22 @@
+/**
+ * Step-summary OTel metrics — Middleware.io routing follows the global
+ * meter provider (see `harness/lib/otel.ts`).
+ *
+ * cortex.summary.null_count — counter, incremented when a step-summary
+ *   turn returns empty markdown or its provider call throws. Tagged with
+ *   `agent_id` and a `reason` discriminator (`"empty" | "throw"`) so
+ *   weekly review can split mode of failure.
+ */
+import { metrics } from "@opentelemetry/api";
+let counter;
+function getCounter() {
+    if (counter === undefined) {
+        counter = metrics.getMeter("cortex.harness.execution").createCounter("cortex.summary.null_count", {
+            description: "Step-summary turns that returned empty markdown or threw.",
+        });
+    }
+    return counter;
+}
+export function incrementSummaryNullCount(agentId, reason) {
+    getCounter().add(1, { agent_id: agentId, reason });
+}