@inflexa-ai/harness 0.1.1 → 0.3.0

package/dist/agents/sandbox/shared.js

@@ -8,8 +8,8 @@
  * the workspace mutate trio (`execute_command`, `write_file`, `edit_file`)
  * bound to the shared `SandboxClient` and the step's `allowedWritePrefix`,
  * the workspace read tools (`read_file`, `grep`) over the shared
- * `WorkspaceFilesystem`, and the bio/literature/context7/run-inspection
- * tools its `meta.tools` allowlist names.
+ * `WorkspaceFilesystem`, `inspect_data_profile` over the shared `Pool`, and the
+ * bio/literature/context7/run-inspection tools its `meta.tools` allowlist names.
  *
  * Tool resolution is a single registry lookup — every name in `meta.tools`
  * must map to a concrete `Tool`; unknown names throw at composition time
@@ -18,13 +18,15 @@
 import { sandboxOrientCorePrompt, sandboxAnalysisStepStandardsPrompt } from "../../prompts/sandbox-standards.js";
 import { composeSystemPrompt } from "../system-prompt.js";
 // Sandbox-environment introspection.
-import { listAvailablePackagesTool, listAvailableRefsTool } from "../../tools/sandbox/index.js";
+import { createListAvailableRefsTool, listAvailablePackagesTool } from "../../tools/sandbox/index.js";
 // Context7 docs (pure leaves).
 import { queryDocsTool, resolveLibraryIdTool } from "../../tools/research/context7-docs.js";
 // Run-inspection (dependency-bearing).
 import { createInspectRunTool } from "../../tools/research/inspect-run.js";
+// Data-profile retrieval (dependency-bearing) — always-on, see `createSandboxAgent`.
+import { createInspectDataProfileTool } from "../../tools/research/inspect-data-profile.js";
 // Bio leaf tools.
-import { checkSafetyPanelTool, getBioactivityTool, getDrugInfoTool, getImpcKoProfileTool, getMechanismTool, getPubchemAssaysTool, getPubchemCrossRefsTool, getTargetSafetyTool, lookupGoTermTool, searchBgeeExpressionTool, searchClinicalTrialsTool, searchCompoundsTool, searchDgidbTool, searchFaersTool, searchGeneTool, searchGeoDatasetsTool, searchGwasCatalogTool, searchInteractionsTool, searchOpenTargetsTool, searchPathwayTool, searchPharmgkbTool, searchPubchemCompoundTool, searchTargetsTool, } from "../../tools/bio/index.js";
+import { checkSafetyPanelTool, chemblTool, getImpcKoProfileTool, lookupGoTermTool, openTargetsTool, pubchemTool, searchBgeeExpressionTool, searchClinicalTrialsTool, createSearchDgidbTool, searchFaersTool, searchGeneTool, searchGeoDatasetsTool, searchGwasCatalogTool, searchInteractionsTool, searchPathwayTool, searchPharmgkbTool, } from "../../tools/bio/index.js";
 import { createNcbiTools, createChemDbTools } from "../../tools/bio/keys.js";
 // Workspace read surface.
 import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createWorkspaceSearchTool } from "../../tools/workspace/index.js";
@@ -44,52 +46,48 @@ import { SANDBOX_AGENT_DEFAULT_MAX_ITERATIONS } from "./types.js";
  */
 export const BASE_SANDBOX_TOOLS = ["listAvailablePackages", "listAvailableRefs", "resolveLibraryId", "queryDocs", "inspectRun"];
 /**
- * Resolve `meta.tools` into the bio/research tools record. Workspace
- * read/mutate tools are added by `createSandboxAgent` regardless of meta
- * — they are the always-on substrate, not in the allowlist.
+ * Resolve `meta.tools` into the bio/research tools record. The workspace
+ * read/mutate tools and `inspect_data_profile` are added by `createSandboxAgent`
+ * regardless of meta — they are the always-on substrate, not in the allowlist.
  */
 function resolveSandboxTools(deps, tools) {
     const ncbi = createNcbiTools(deps.bioKeys);
     const chemDb = createChemDbTools(deps.bioKeys);
     const registry = {
         listAvailablePackages: listAvailablePackagesTool,
-        listAvailableRefs: listAvailableRefsTool,
+        listAvailableRefs: createListAvailableRefsTool({
+            sandboxClient: deps.sandboxClient,
+            sandbox: deps.step.sandbox,
+            workflowId: deps.step.workflowId,
+            stepId: deps.step.stepId,
+            nextFunctionId: deps.step.nextFunctionId,
+            deadlineMs: deps.step.deadlineMs,
+            markExecActive: createMarkExecActive(deps),
+        }),
         resolveLibraryId: resolveLibraryIdTool,
         queryDocs: queryDocsTool,
         inspectRun: createInspectRunTool(deps.pool),
-        searchPubMed: ncbi.searchPubMed,
-        getArticleDetails: ncbi.getArticleDetails,
-        getArticleFullText: ncbi.getArticleFullText,
+        pubmed: ncbi.pubmed,
         searchGene: searchGeneTool,
         searchPathway: searchPathwayTool,
         lookupGoTerm: lookupGoTermTool,
         searchInteractions: searchInteractionsTool,
-        searchCompounds: searchCompoundsTool,
-        getBioactivity: getBioactivityTool,
-        searchTargets: searchTargetsTool,
-        getMechanism: getMechanismTool,
-        getDrugInfo: getDrugInfoTool,
-        searchPubchemCompound: searchPubchemCompoundTool,
-        getPubchemCrossRefs: getPubchemCrossRefsTool,
-        getPubchemAssays: getPubchemAssaysTool,
-        searchOpenTargets: searchOpenTargetsTool,
-        getTargetSafety: getTargetSafetyTool,
+        chembl: chemblTool,
+        pubchem: pubchemTool,
+        opentargets: openTargetsTool,
         searchPharmgkb: searchPharmgkbTool,
         searchFaers: searchFaersTool,
         searchClinicalTrials: searchClinicalTrialsTool,
         searchGeoDatasets: searchGeoDatasetsTool,
         searchClinvar: ncbi.searchClinvar,
-        searchDgidb: searchDgidbTool,
+        searchDgidb: createSearchDgidbTool({ ...(deps.logger ? { logger: deps.logger } : {}) }),
         searchGwasCatalog: searchGwasCatalogTool,
         searchDisgenet: chemDb.searchDisgenet,
         searchDrugbank: chemDb.searchDrugbank,
         searchBgeeExpression: searchBgeeExpressionTool,
         getImpcKoProfile: getImpcKoProfileTool,
         checkSafetyPanel: checkSafetyPanelTool,
-        searchToxcast: chemDb.searchToxcast,
-        searchCtxHazard: chemDb.searchCtxHazard,
-        searchCtxChemical: chemDb.searchCtxChemical,
-        searchCtxExposure: chemDb.searchCtxExposure,
+        comptox: chemDb.comptox,
     };
     const seen = new Set();
     const resolved = [];
@@ -105,6 +103,9 @@ function resolveSandboxTools(deps, tools) {
     }
     return resolved;
 }
+function createMarkExecActive(deps) {
+    return (execId) => setActiveExecId(deps.pool, deps.step.runId, deps.step.stepId, execId).match(() => { }, () => { });
+}
 /** Build the workspace mutate + read tools every sandbox agent receives. In
  *  `readOnly` mode the write_file/edit_file pair is omitted; execute_command
  *  and the read tools stay. */
@@ -113,7 +114,7 @@ function buildWorkspaceTools(deps, readOnly) {
     // Registry tagging is a best-effort watchdog backstop (`run-exec.ts` already
     // swallows a throw here); fold a `DbError` into a no-op so a registry write
     // failure neither fails the exec nor surfaces as an unhandled rejection.
-    const markExecActive = (execId) => setActiveExecId(pool, step.runId, step.stepId, execId).match(() => { }, () => { });
+    const markExecActive = createMarkExecActive(deps);
     // The agent's writable working directory: relative paths resolve here, and
     // writes are confined here. `allowedWritePrefix` is its host path; the
     // in-sandbox path (the `execute_command` default cwd, see the harness-workspace-tools spec) is the same
@@ -161,26 +162,36 @@ function buildWorkspaceTools(deps, readOnly) {
 }
 /**
  * Build one sandbox `AgentDefinition`. The system prompt is composed once
- * (SOUL kernel + agent body + sandbox standards) — no processors, no
- * conversational layer (sandbox agents are not user-facing). Tools are
- * resolved against the closed allowlist; the workspace surface is always
- * wired regardless of meta.
+ * (SOUL execution core + agent body + sandbox standards) — no processors, and
+ * neither human-facing SOUL layer: a sandbox agent is headless, so the identity
+ * and conversational layers are dead weight in its context while every hard
+ * guardrail it does need rides in the execution core. Tools are resolved
+ * against the closed allowlist; the workspace surface is always wired
+ * regardless of meta.
+ *
+ * The composed `systemPrompt` is a **pure function of the agent type** — nothing
+ * from `deps.step` reaches it, so two steps of one run, and two runs of one
+ * analysis, send a byte-identical ~20k-char prefix that the provider's prompt
+ * cache can actually reuse. Keep it that way: a single interpolated id or path
+ * makes every step's prefix unique again, and each step pays a full cache write
+ * and reads nothing back. Per-step values belong in the step's briefing (its
+ * first user message — see `prompts/briefing.ts`), which names the working
+ * directory, the analysis root, the dataset, and what each dependency produced.
  */
 export function createSandboxAgent(deps, meta, body, opts = {}) {
     const appendStandards = opts.appendAnalysisStepStandards ?? true;
     const sandboxLayer = appendStandards ? [sandboxOrientCorePrompt, sandboxAnalysisStepStandardsPrompt] : [sandboxOrientCorePrompt];
     const agentBody = [body, ...sandboxLayer].map((s) => s.trim()).join("\n\n");
-    // Substitute the concrete in-sandbox paths the agent sees so the orient-core
-    // path model is accurate per step (see the harness-workspace-tools spec), not boilerplate prose.
-    const analysisRoot = `/${deps.step.analysisId}`;
-    const workingDir = toSandboxPath(deps.step.workspaceRoot, deps.step.analysisId, deps.step.allowedWritePrefix);
-    const resolvedBody = agentBody.split("{{WORKING_DIR}}").join(workingDir).split("{{ANALYSIS_ROOT}}").join(analysisRoot);
-    const systemPrompt = composeSystemPrompt(resolvedBody, {
-        includeConversationalStyle: false,
-    });
+    const systemPrompt = composeSystemPrompt(agentBody);
     const skillTools = deps.skillsDir ? Object.values(createSkillTools({ skillsDir: deps.skillsDir, skills: meta.skills })) : [];
     const tools = [
         ...buildWorkspaceTools(deps, opts.readOnly ?? false),
+        // Always-on, not in the `meta.tools` allowlist: the data profile is the only
+        // record of what the analysis's input dataset IS, and no file carries it (the
+        // profiler's scratch tree is deleted on completion). An agent that cannot pull
+        // it has no fallback but to re-derive organism, dimensions, and format from the
+        // raw bytes — so every sandbox agent gets it, whatever its meta declares.
+        createInspectDataProfileTool(deps.pool),
         ...skillTools,
         ...resolveSandboxTools(deps, meta.tools),
         ...(deps.blockerHolder ? [createReportBlockerTool(deps.blockerHolder)] : []),

package/dist/agents/sandbox/single-cell-agent.js

@@ -18,7 +18,7 @@ export const meta = {
     ],
     suitableFor: ["scrna-seq", "snrna-seq", "cytof", "mass-cytometry"],
     skills: ["single-cell", "shared/omics-general"],
-    tools: [...BASE_SANDBOX_TOOLS, "searchPubMed", "getArticleDetails", "getArticleFullText", "searchGeoDatasets"],
+    tools: [...BASE_SANDBOX_TOOLS, "pubmed", "searchGeoDatasets"],
 };
 export function createSingleCellAgent(deps) {
     return createSandboxAgent(deps, meta, singleCellAgentPrompt);

package/dist/agents/sandbox/spatial-omics-agent.js

@@ -8,7 +8,7 @@ export const meta = {
     capabilities: ["spatial statistics", "spatial domain detection", "deconvolution", "niche analysis", "spatial autocorrelation", "ligand-receptor spatial"],
     suitableFor: ["visium", "merfish", "slide-seq", "codex", "xenium", "mibi", "imc"],
     skills: ["spatial-omics", "shared/omics-general"],
-    tools: [...BASE_SANDBOX_TOOLS, "searchPubMed", "getArticleDetails", "getArticleFullText", "searchGeoDatasets"],
+    tools: [...BASE_SANDBOX_TOOLS, "pubmed", "searchGeoDatasets"],
 };
 export function createSpatialOmicsAgent(deps) {
     return createSandboxAgent(deps, meta, spatialOmicsAgentPrompt);

package/dist/agents/sandbox/statistical-modeling-agent.js

@@ -30,7 +30,7 @@ export const meta = {
         "patient-stratification",
     ],
     skills: ["statistical-modeling", "shared/omics-general"],
-    tools: [...BASE_SANDBOX_TOOLS, "searchPubMed", "getArticleDetails", "getArticleFullText"],
+    tools: [...BASE_SANDBOX_TOOLS, "pubmed"],
 };
 export function createStatisticalModelingAgent(deps) {
     return createSandboxAgent(deps, meta, statisticalModelingAgentPrompt);

package/dist/agents/sandbox/translational-safety-agent.js

@@ -34,22 +34,16 @@ export const meta = {
     tools: [
         ...BASE_SANDBOX_TOOLS,
         "checkSafetyPanel",
-        "searchPubMed",
-        "getArticleDetails",
-        "getArticleFullText",
+        "pubmed",
         "searchGene",
         "searchPathway",
         "lookupGoTerm",
         "searchInteractions",
-        "searchOpenTargets",
-        "getTargetSafety",
+        "opentargets",
         "searchFaers",
         "searchPharmgkb",
         "searchDgidb",
-        "searchToxcast",
-        "searchCtxHazard",
-        "searchCtxChemical",
-        "searchCtxExposure",
+        "comptox",
         "searchBgeeExpression",
         "getImpcKoProfile",
     ],

package/dist/agents/sandbox/types.d.ts

@@ -12,7 +12,7 @@
  * envelope. `searchGwasCatalog` is fully public.
  */
 /** Closed allowlist of tools any sandbox agent may declare. */
-export type SandboxToolName = "listAvailablePackages" | "listAvailableRefs" | "resolveLibraryId" | "queryDocs" | "inspectRun" | "searchPubMed" | "getArticleDetails" | "getArticleFullText" | "searchGene" | "searchPathway" | "lookupGoTerm" | "searchInteractions" | "searchCompounds" | "getBioactivity" | "searchTargets" | "getMechanism" | "getDrugInfo" | "searchPubchemCompound" | "getPubchemCrossRefs" | "getPubchemAssays" | "searchOpenTargets" | "getTargetSafety" | "searchPharmgkb" | "searchFaers" | "searchClinicalTrials" | "searchGeoDatasets" | "searchClinvar" | "searchDgidb" | "searchGwasCatalog" | "searchDisgenet" | "searchDrugbank" | "searchBgeeExpression" | "getImpcKoProfile" | "checkSafetyPanel" | "searchToxcast" | "searchCtxHazard" | "searchCtxChemical" | "searchCtxExposure";
+export type SandboxToolName = "listAvailablePackages" | "listAvailableRefs" | "resolveLibraryId" | "queryDocs" | "inspectRun" | "pubmed" | "searchGene" | "searchPathway" | "lookupGoTerm" | "searchInteractions" | "chembl" | "pubchem" | "opentargets" | "searchPharmgkb" | "searchFaers" | "searchClinicalTrials" | "searchGeoDatasets" | "searchClinvar" | "searchDgidb" | "searchGwasCatalog" | "searchDisgenet" | "searchDrugbank" | "searchBgeeExpression" | "getImpcKoProfile" | "checkSafetyPanel" | "comptox";
 /** Planner-facing metadata + tool allowlist for one sandbox agent. */
 export interface AgentMeta {
     /** Stable agent id — also the key in the catalog and the `AgentDefinition.id`. */

package/dist/agents/system-prompt.d.ts

@@ -2,24 +2,50 @@
  * Harness system-prompt composition.
  *
  * SOUL is static text — there is no processor pipeline. `composeSystemPrompt`
- * concatenates the SOUL kernel, the optional SOUL conversational layer, and an
- * agent's own prompt into the single `AgentDefinition.systemPrompt` string the
- * loop sends as the cacheable prefix.
+ * concatenates the SOUL layers an agent declares with the agent's own prompt
+ * into the single `AgentDefinition.systemPrompt` string the loop sends as the
+ * cacheable prefix. It is the only place SOUL is applied, and every agent is
+ * built through it — an unguarded agent is not constructible.
  *
- * `includeConversationalStyle` toggles the conversational block: the
- * user-facing conversation agent keeps it; internal tool-only specialists
- * (planner, run-synthesizer) and sandbox agents omit it — their tight tool
- * loops compete with conversational discipline.
+ * The layer policy:
+ *
+ * - `SOULExecutionCore` is **always** included; there is no opt-out. The
+ *   scientific stance and the hard guardrails (never fabricate, never oversell,
+ *   never hide uncertainty, confidentiality, prompt-injection defense) bind a
+ *   headless agent exactly as they bind the user-facing one. The run
+ *   synthesizer and the report builder author user-facing scientific claims
+ *   without a human in their loop — they are the last agents that should be
+ *   free to fabricate.
+ *
+ * - `identity` (default `false`) adds `SOULIdentity` — the Inflexa name, the
+ *   scope, and the human-facing refusal / impersonation / external-action
+ *   guardrails. Only the conversation agent faces a human, so only it opts in.
+ *
+ * - `conversational` (default `false`) adds `SOULConversationalPrompt` —
+ *   personality, response policy, and the 7-step reasoning cadence. Conversation
+ *   agent only: a tool-only specialist's tight loop competes with conversational
+ *   discipline.
+ *
+ * Both flags default off, so the zero-argument call yields a fully guarded
+ * headless agent — the safe default is also the shortest one to write.
  */
 export interface ComposeSystemPromptOptions {
+    /**
+     * Include the SOUL identity layer (name, scope, refusal of harmful
+     * requests, impersonation and external-action guardrails). Default `false`
+     * — opt in only for an agent a human talks to.
+     */
+    readonly identity?: boolean;
     /**
      * Include the SOUL conversational layer (personality, response policy,
-     * 7-step reasoning). Default `true` — opt out for internal specialists.
+     * 7-step reasoning). Default `false` — opt in only for the conversation
+     * agent.
      */
-    readonly includeConversationalStyle?: boolean;
+    readonly conversational?: boolean;
 }
 /**
- * Compose an agent's full system prompt: SOUL kernel, the optional SOUL
- * conversational layer, then the agent's own prompt — joined by blank lines.
+ * Compose an agent's full system prompt: the always-on SOUL execution core, the
+ * layers the agent opted into, then the agent's own prompt — joined by blank
+ * lines.
  */
 export declare function composeSystemPrompt(agentPrompt: string, options?: ComposeSystemPromptOptions): string;

package/dist/agents/system-prompt.js

@@ -2,22 +2,45 @@
  * Harness system-prompt composition.
  *
  * SOUL is static text — there is no processor pipeline. `composeSystemPrompt`
- * concatenates the SOUL kernel, the optional SOUL conversational layer, and an
- * agent's own prompt into the single `AgentDefinition.systemPrompt` string the
- * loop sends as the cacheable prefix.
+ * concatenates the SOUL layers an agent declares with the agent's own prompt
+ * into the single `AgentDefinition.systemPrompt` string the loop sends as the
+ * cacheable prefix. It is the only place SOUL is applied, and every agent is
+ * built through it — an unguarded agent is not constructible.
  *
- * `includeConversationalStyle` toggles the conversational block: the
- * user-facing conversation agent keeps it; internal tool-only specialists
- * (planner, run-synthesizer) and sandbox agents omit it — their tight tool
- * loops compete with conversational discipline.
+ * The layer policy:
+ *
+ * - `SOULExecutionCore` is **always** included; there is no opt-out. The
+ *   scientific stance and the hard guardrails (never fabricate, never oversell,
+ *   never hide uncertainty, confidentiality, prompt-injection defense) bind a
+ *   headless agent exactly as they bind the user-facing one. The run
+ *   synthesizer and the report builder author user-facing scientific claims
+ *   without a human in their loop — they are the last agents that should be
+ *   free to fabricate.
+ *
+ * - `identity` (default `false`) adds `SOULIdentity` — the Inflexa name, the
+ *   scope, and the human-facing refusal / impersonation / external-action
+ *   guardrails. Only the conversation agent faces a human, so only it opts in.
+ *
+ * - `conversational` (default `false`) adds `SOULConversationalPrompt` —
+ *   personality, response policy, and the 7-step reasoning cadence. Conversation
+ *   agent only: a tool-only specialist's tight loop competes with conversational
+ *   discipline.
+ *
+ * Both flags default off, so the zero-argument call yields a fully guarded
+ * headless agent — the safe default is also the shortest one to write.
  */
-import { SOULKernelPrompt, SOULConversationalPrompt } from "../prompts/SOUL.js";
+import { SOULExecutionCore, SOULIdentity, SOULConversationalPrompt } from "../prompts/SOUL.js";
 /**
- * Compose an agent's full system prompt: SOUL kernel, the optional SOUL
- * conversational layer, then the agent's own prompt — joined by blank lines.
+ * Compose an agent's full system prompt: the always-on SOUL execution core, the
+ * layers the agent opted into, then the agent's own prompt — joined by blank
+ * lines.
  */
 export function composeSystemPrompt(agentPrompt, options = {}) {
-    const includeConversational = options.includeConversationalStyle ?? true;
-    const sections = includeConversational ? [SOULKernelPrompt, SOULConversationalPrompt, agentPrompt] : [SOULKernelPrompt, agentPrompt];
+    const sections = [SOULExecutionCore];
+    if (options.identity ?? false)
+        sections.push(SOULIdentity);
+    if (options.conversational ?? false)
+        sections.push(SOULConversationalPrompt);
+    sections.push(agentPrompt);
     return sections.map((s) => s.trim()).join("\n\n");
 }

package/dist/app/chat-turn.d.ts

@@ -14,7 +14,10 @@
  */
 import type { Pool } from "pg";
 import { type AssembledMessages } from "./message-assembly.js";
+import type { Logger } from "../lib/logger.js";
 export interface PrepareChatTurnDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly pool: Pool;
 }
 export interface PrepareChatTurnParams {

package/dist/app/chat-turn.js

@@ -19,6 +19,7 @@ import { createThreadStore } from "../memory/thread-store.js";
 import { createWorkingMemory } from "../memory/working-memory.js";
 import { loadAnalysisStatus } from "../state/index.js";
 import { assembleMessages } from "./message-assembly.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 /**
  * Prepare one chat turn: resolve thread ownership, seed the title, load
  * analysis status, and assemble the message array. Input sanitization stays
@@ -48,7 +49,8 @@ export async function prepareChatTurn(deps, params) {
         }
     }
     catch (err) {
-        console.warn("[harness.chat] title-seed failed (non-fatal):", err instanceof Error ? err.message : err);
+        const logger = (deps.logger ?? createNoopLogger()).named("harness.chat");
+        logger.warn("title-seed failed (non-fatal)", logger.errorFields(err));
     }
     const analysisState = await loadAnalysisStatus(pool, analysisId).unwrapOr(null);
     const history = createThreadHistory(pool);

package/dist/app/data-profile-orientation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Data-profile orientation — the bounded projection of a persisted
+ * `DataProfileResult` into the few hundred characters an agent needs to know
+ * WHAT DATASET IT IS HOLDING before it does anything else.
+ *
+ * The persisted profile is deliberately rich (per-file metrics, warnings, tags,
+ * the full narrative summary) because the DB row is its only durable home — the
+ * profiler's scratch tree is deleted on completion. That richness is right for a
+ * pull-on-demand tool (`inspect_data_profile`) and wrong for anything injected
+ * unconditionally into a context window, which is what a step seed does. This is
+ * the lossy half of that pair: a hard character budget, a fixed field order, and
+ * visible truncation counts, so an agent that needs more knows to go pull it.
+ *
+ * A pure function over the record — no I/O, no LLM, no pipeline. It is the whole
+ * mechanism.
+ */
+import type { DataProfileResult } from "../state/data-profile.js";
+/** The character budget the projection guarantees it will not exceed. */
+export declare const DATA_PROFILE_ORIENTATION_MAX_CHARS = 1200;
+/**
+ * Project a persisted profile into an orientation blurb of at most `maxChars`
+ * characters. The bound is a guarantee, not a target: the assembled text is
+ * hard-clamped, so no profile — however verbose — can blow a caller's budget.
+ *
+ * Field order is fixed and reflects what an agent must know first: what the
+ * dataset IS, how it was designed, what is wrong with it, then what files carry
+ * it. Both list sections state their true total, so an elided tail is visible
+ * rather than silent.
+ *
+ * A snapshot written before the record was widened carries none of the structured
+ * fields. Rather than emit a bare file list, that case falls back to the narrative
+ * summary — the one orientation a legacy row does have.
+ */
+export declare function buildDataProfileOrientation(result: DataProfileResult, maxChars?: number): string;

package/dist/app/data-profile-orientation.js

@@ -0,0 +1,117 @@
+/**
+ * Data-profile orientation — the bounded projection of a persisted
+ * `DataProfileResult` into the few hundred characters an agent needs to know
+ * WHAT DATASET IT IS HOLDING before it does anything else.
+ *
+ * The persisted profile is deliberately rich (per-file metrics, warnings, tags,
+ * the full narrative summary) because the DB row is its only durable home — the
+ * profiler's scratch tree is deleted on completion. That richness is right for a
+ * pull-on-demand tool (`inspect_data_profile`) and wrong for anything injected
+ * unconditionally into a context window, which is what a step seed does. This is
+ * the lossy half of that pair: a hard character budget, a fixed field order, and
+ * visible truncation counts, so an agent that needs more knows to go pull it.
+ *
+ * A pure function over the record — no I/O, no LLM, no pipeline. It is the whole
+ * mechanism.
+ */
+/** The character budget the projection guarantees it will not exceed. */
+export const DATA_PROFILE_ORIENTATION_MAX_CHARS = 1200;
+/** Files listed before the tail is elided (the count still reports the total). */
+const MAX_FILES = 8;
+/** Quality concerns listed — the profiler orders them, so these are the top ones. */
+const MAX_CONCERNS = 3;
+const MAX_DESIGN_CHARS = 200;
+const MAX_CONCERN_CHARS = 120;
+const MAX_FILE_DESCRIPTION_CHARS = 100;
+const MAX_SUMMARY_FALLBACK_CHARS = 300;
+/**
+ * Clamp to `max` chars, marking any elision with an ellipsis. Whitespace is left
+ * alone, so the assembled line structure survives the final bound.
+ */
+function clamp(text, max) {
+    if (text.length <= max)
+        return text;
+    if (max <= 1)
+        return "";
+    return text.slice(0, max - 1).trimEnd() + "…";
+}
+/**
+ * Collapse a free-text field to one line and clamp it. Profiler prose (a summary, a
+ * design note, a file description) may contain newlines; folding them out is what
+ * keeps one record on one line.
+ */
+function clip(text, max) {
+    return clamp(text.replace(/\s+/g, " ").trim(), max);
+}
+/** Non-empty, whitespace-collapsed value, or `undefined` — nulls and blanks read the same. */
+function present(value) {
+    const flat = value?.replace(/\s+/g, " ").trim();
+    return flat ? flat : undefined;
+}
+/** `Homo sapiens (taxon 9606)`, plus a confidence marker when the profiler was unsure. */
+function formatOrganism(organism) {
+    if (!organism)
+        return undefined;
+    const name = present(organism.scientificName);
+    if (!name)
+        return undefined;
+    const taxon = present(organism.taxonId);
+    const qualifier = organism.confidence === "high" ? "" : ` [${organism.confidence} confidence]`;
+    return taxon ? `${name} (taxon ${taxon})${qualifier}` : `${name}${qualifier}`;
+}
+/** `(20000 x 24, CSV)` — whichever of dimensions / format the profiler recorded. */
+function formatFileFacts(file) {
+    const dims = typeof file.rows === "number" && typeof file.cols === "number" ? `${file.rows} x ${file.cols}` : undefined;
+    const facts = [dims, present(file.format)].filter((f) => f !== undefined);
+    return facts.length > 0 ? ` (${facts.join(", ")})` : "";
+}
+/**
+ * Project a persisted profile into an orientation blurb of at most `maxChars`
+ * characters. The bound is a guarantee, not a target: the assembled text is
+ * hard-clamped, so no profile — however verbose — can blow a caller's budget.
+ *
+ * Field order is fixed and reflects what an agent must know first: what the
+ * dataset IS, how it was designed, what is wrong with it, then what files carry
+ * it. Both list sections state their true total, so an elided tail is visible
+ * rather than silent.
+ *
+ * A snapshot written before the record was widened carries none of the structured
+ * fields. Rather than emit a bare file list, that case falls back to the narrative
+ * summary — the one orientation a legacy row does have.
+ */
+export function buildDataProfileOrientation(result, maxChars = DATA_PROFILE_ORIENTATION_MAX_CHARS) {
+    const lines = [];
+    const identity = [
+        [present(result.domain), present(result.subtype)].filter((f) => f !== undefined).join(" / ") || undefined,
+        formatOrganism(result.organism),
+        present(result.tissue) ? `tissue: ${present(result.tissue)}` : undefined,
+        present(result.cellType) ? `cells: ${present(result.cellType)}` : undefined,
+        present(result.condition) ? `condition: ${present(result.condition)}` : undefined,
+    ].filter((f) => f !== undefined);
+    if (identity.length > 0) {
+        lines.push(`Dataset: ${identity.join(" — ")}`);
+    }
+    else {
+        // A legacy snapshot has no structured identity at all; the summary is the
+        // only orientation it carries, so it stands in for the whole header.
+        lines.push(`Dataset: ${clip(result.summary, MAX_SUMMARY_FALLBACK_CHARS)}`);
+    }
+    const design = present(result.experimentalDesign);
+    if (design)
+        lines.push(`Design: ${clip(design, MAX_DESIGN_CHARS)}`);
+    const concerns = (result.qualityAssessment?.concerns ?? []).map((c) => present(c)).filter((c) => c !== undefined);
+    if (concerns.length > 0) {
+        const shown = concerns.slice(0, MAX_CONCERNS).map((c) => clip(c, MAX_CONCERN_CHARS));
+        const more = concerns.length > shown.length ? ` (+${concerns.length - shown.length} more)` : "";
+        lines.push(`Concerns: ${shown.join("; ")}${more}`);
+    }
+    if (result.files.length > 0) {
+        const shown = result.files.slice(0, MAX_FILES);
+        const header = shown.length < result.files.length ? `Files (${shown.length} of ${result.files.length}):` : `Files (${result.files.length}):`;
+        lines.push(header);
+        for (const file of shown) {
+            lines.push(`- ${file.path} — ${clip(file.description, MAX_FILE_DESCRIPTION_CHARS)}${formatFileFacts(file)}`);
+        }
+    }
+    return clamp(lines.join("\n"), maxChars);
+}

package/dist/app/synthesize-run.d.ts

@@ -22,7 +22,10 @@ import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
 import type { RunFinding } from "../workflows/execute-analysis.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
+import type { Logger } from "../lib/logger.js";
 export interface SynthesizeRunDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly pool: Pool;
     readonly provider: ChatProvider;
     /** Write-side embedder — its `dimensions` sizes the per-analysis index. */

package/dist/app/synthesize-run.js

@@ -20,6 +20,7 @@ import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.j
 import { createVectorStore } from "../state/vector-store.js";
 import { loadPlan, queryRun } from "../state/index.js";
 import { unwrapOrThrow } from "../lib/result.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 export async function synthesizeRun(deps, params) {
     const { pool, provider, embedding, resolveWorkspaceRoot, synthesisModel, bioKeys } = deps;
     const { analysisId, runId, completedSteps, session, emit, onProgress } = params;
@@ -71,7 +72,8 @@ export async function synthesizeRun(deps, params) {
             }));
         }
         catch (indexErr) {
-            console.warn(`[synthesize-run] vector indexing failed for run ${runId}:`, indexErr instanceof Error ? indexErr.message : indexErr);
+            const logger = (deps.logger ?? createNoopLogger()).named("synthesize-run");
+            logger.warn("vector indexing failed", { runId, ...logger.errorFields(indexErr) });
         }
         await onProgress("persisting", "Persisting synthesis");
         await persistSynthesis({ workspaceRoot, runId, synthesis });