@inflexa-ai/harness 0.1.1 → 0.3.0

package/dist/execution/run-synthesis.js

@@ -25,10 +25,12 @@ 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 { composeSystemPrompt } from "../agents/system-prompt.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 { createReportBlockerToolFor } from "../tools/sandbox/report-blocker.js";
 import { createLiteratureReviewerTool } from "../tools/research/literature-reviewer.js";
 // ── Agent identity / budgets ────────────────────────────────────────
 const AGENT_ID = "run-synthesizer";
@@ -125,13 +127,14 @@ function fullyValidate(candidate, ctx) {
 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() }),
+        description: "Submit the final synthesis. Re-validates the payload against the " +
+            "semantic checks the arg schema cannot express (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: RunSynthesisSchema }),
         execute: async (input) => {
             if (holder.outcome !== null) {
                 return ok({
@@ -155,18 +158,16 @@ function buildSubmitTool(holder, ctx) {
     });
 }
 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 });
+    return createReportBlockerToolFor({
+        record: (outcome) => {
+            if (holder.outcome === null)
+                holder.outcome = outcome;
         },
+        blockedWhen: "Ends run synthesis with no synthesis written. Use it when the run " +
+            "produced no synthesizable content (all step summaries empty, " +
+            "contradictory to the point of incoherence, or no findings worth " +
+            "surfacing) — not as an escape from a synthesis you could fix and " +
+            "submit.",
     });
 }
 /**
@@ -207,7 +208,7 @@ export async function generateRunSynthesis(input) {
     const tools = [submitTool, blockerTool, reviewer];
     const agent = {
         id: AGENT_ID,
-        systemPrompt: synthesisAgentPrompt,
+        systemPrompt: composeSystemPrompt(synthesisAgentPrompt),
         model: input.model,
         tools,
         maxIterations: SYNTHESIZER_MAX_ITERATIONS,

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

@@ -29,7 +29,10 @@ import type { LoopMessage } from "../loop/types.js";
 import type { AgentChat } from "../providers/types.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import { type StepSummary } from "../schemas/step-summary.js";
+import type { Logger } from "../lib/logger.js";
 export interface GenerateStepSummaryOptions {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly provider: AgentChat;
     readonly session: AgentSession;
     readonly modelId: string;

package/dist/execution/step-summary.js

@@ -28,9 +28,11 @@ import { forSubAgent } from "../auth/types.js";
 import { finalText, runAgent } from "../loop/run-agent.js";
 import { passthroughStep } from "../loop/run-step.js";
 import { stepSummaryPrompt } from "../prompts/execute-analysis/step-summary.js";
+import { composeSystemPrompt } from "../agents/system-prompt.js";
 import { createReadFileTool } from "../tools/workspace/read-file.js";
 import { StepSummarySchema } from "../schemas/step-summary.js";
 import { incrementSummaryNullCount } from "./step-summary-metrics.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 const SYSTEM_PROMPT = `You are a sandbox agent writing a post-step interpretive summary of work you just completed.
 
 Your prior conversation — tool calls, code output, intermediate results — is in the message history above. Use it for narrative and intent.
@@ -68,11 +70,12 @@ function sanitizeTranscript(messages) {
  * without `summary.md` in that case.
  */
 export async function generateStepSummary(opts) {
+    const logger = (opts.logger ?? createNoopLogger()).named("step-summary").with({ runId: opts.runId, stepId: opts.stepId, agentId: opts.agentId });
     const transcript = sanitizeTranscript(opts.messages);
     const userPrompt = stepSummaryPrompt(opts.artifactPaths.join("\n"));
     const writer = {
         id: SUMMARY_AGENT_ID,
-        systemPrompt: SYSTEM_PROMPT,
+        systemPrompt: composeSystemPrompt(SYSTEM_PROMPT),
         model: opts.modelId,
         tools: [createReadFileTool(opts.workspaceFs, opts.workingDir)],
         maxIterations: opts.maxIterations ?? DEFAULT_MAX_ITERATIONS,
@@ -88,13 +91,13 @@ export async function generateStepSummary(opts) {
         });
     }
     catch (err) {
-        console.warn(`[step-summary] Summary loop failed runId=${opts.runId} stepId=${opts.stepId} agentId=${opts.agentId}: ${err instanceof Error ? err.message : err}`);
+        logger.warn("summary loop failed", logger.errorFields(err));
         incrementSummaryNullCount(opts.agentId, "throw");
         return undefined;
     }
     const markdown = finalText(result.messages);
     if (!markdown || markdown.trim().length === 0) {
-        console.warn(`[step-summary] Empty markdown runId=${opts.runId} stepId=${opts.stepId} agentId=${opts.agentId}`);
+        logger.warn("empty markdown");
         incrementSummaryNullCount(opts.agentId, "empty");
         return undefined;
     }

package/dist/index.d.ts

@@ -39,7 +39,8 @@ export { createConfiguredAiSdkProvider } from "./providers/ai-sdk.js";
 export type { AiSdkProviderConfig, ConfiguredAiSdkProviderDeps } from "./providers/ai-sdk.js";
 export { createEmbeddingProvider } from "./providers/embedding.js";
 export type { EmbeddingProviderDeps } from "./providers/embedding.js";
-export type { AgentChat, ChatProvider, EmbeddingProvider, ChatRequest, ChatResponse, ChatStreamEvent, ModelMessage } from "./providers/types.js";
+export type { AgentChat, ChatProvider, EmbeddingProvider, ChatRequest, ChatResponse, ChatStreamEvent, ChatUsage, ModelMessage, PromptCachePolicy, } from "./providers/types.js";
+export { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions } from "./providers/prompt-cache.js";
 export { toProviderError, isProviderError } from "./providers/errors.js";
 export type { ProviderError } from "./providers/errors.js";
 export { createStreamingChat } from "./providers/streaming-chat.js";
@@ -94,7 +95,6 @@ export type { PlanStep } from "./workflows/execute-analysis-scheduler.js";
 export { validatePlan } from "./schemas/validate-plan.js";
 export type { ValidatePlanOptions } from "./schemas/validate-plan.js";
 export type { ValidationResult } from "./schemas/validate-plan.js";
-export { renderStepPrompt } from "./schemas/render-step-prompt.js";
 export { upsertPlan, loadPlan } from "./state/plans.js";
 export type { UpsertPlanInput } from "./state/plans.js";
 export { insertRun, queryActiveRun, updateRunStatus, queryRun, queryRunsByAnalysis, RunDedupCollisionError } from "./state/runs.js";
@@ -102,8 +102,15 @@ export type { InsertRunInput } from "./state/runs.js";
 export { queryStepsByRun } from "./state/step-executions.js";
 export type { CortexRunRow, StepExecutionRow, RunStatus } from "./state/schema.js";
 export type { DbError } from "./lib/db-result.js";
+export { REFERENCE_DATA_CATALOG, REFERENCE_DATA_CATALOG_VERSION, ReferenceArtifactPathSchema, ReferenceArtifactSchema, ReferenceDataCatalogSchema, ReferenceDatasetSchema, ReferenceSha256Schema, UnknownReferenceDatasetError, referenceArtifactKey, resolveReferenceInstallPlan, } from "./reference-data/catalog.js";
+export type { ReferenceArtifact, ReferenceDataCatalog, ReferenceDataset, ReferenceInstallPlan, ReferenceInstallPlanDataset, ReferenceIntegrity, } from "./reference-data/catalog.js";
+export { REFERENCE_INSTALL_RECEIPT_VERSION, ReferenceInstallReceiptSchema, parseReferenceInstallReceipt } from "./reference-data/receipt.js";
+export type { ReferenceInstallReceipt, ReferenceReceiptArtifact } from "./reference-data/receipt.js";
 export { queryActiveSandboxes } from "./state/active-sandboxes.js";
 export { runStepDir } from "./workspace/paths.js";
+export type { LogFields, LogLevel, Logger } from "./lib/logger.js";
+export { defaultErrorFields } from "./lib/logger.js";
+export { createConsoleLogger, createNoopLogger } from "./lib/console-logger.js";
 export { registerSandboxReaper } from "./sandbox/reaper.js";
 export type { RegisterReaperDeps } from "./sandbox/reaper.js";
 export { registerWatchdog } from "./sandbox/watchdog.js";

package/dist/index.js

@@ -43,6 +43,14 @@ export { createAnthropicProvider } from "./providers/anthropic.js";
 // above is a convenience over this union's `anthropic` arm.
 export { createConfiguredAiSdkProvider } from "./providers/ai-sdk.js";
 export { createEmbeddingProvider } from "./providers/embedding.js";
+// Prompt caching. `PromptCachePolicy` is the harness's vendor-neutral cache
+// directive; a composition root sets it per run via `RunAgentOptions.promptCache`
+// (defaulting to `DEFAULT_PROMPT_CACHE` — 5m — when omitted, since an agent loop
+// re-sends its prefix every iteration and breaks even immediately). Hosts whose
+// endpoint ignores cache directives — notably the Claude Max OAuth path — pass
+// `"off"`; the `cortex.harness.agent.cache_*_tokens` metrics show which case a
+// deployment is actually in.
+export { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions } from "./providers/prompt-cache.js";
 // Provider error channel. `ProviderError` is the value `chat`/`embed` fail
 // with; `toProviderError` is its sole constructor. Exposed so an embedder
 // realizing its own `ChatProvider`/`EmbeddingProvider` fails with the exact
@@ -129,25 +137,36 @@ export { registerSandboxStep } from "./workflows/sandbox-step.js";
 // `SandboxAgentDeps`, then selects the per-step agent by id from this record;
 // `SANDBOX_AGENT_META` is the planner-facing meta the same ids key.
 export { createSandboxAgents, SANDBOX_AGENT_META } from "./agents/sandbox/index.js";
-// Plan schema, structural validation, and per-step prompt rendering — the gates
-// a plan passes before it can trigger a run, plus the prompt each step's agent
-// receives. `PlanStep` is the minimal `{ id, depends_on }` element type that
+// Plan schema and structural validation — the gates a plan passes before it can
+// trigger a run. `PlanStep` is the minimal `{ id, depends_on }` element type that
 // `ExecuteAnalysisInput.steps` is typed against; a parsed `AnalysisPlan`'s
-// richer `AnalysisStep[]` is assignable to it.
+// richer `AnalysisStep[]` is assignable to it, and is also what
+// `ExecuteAnalysisInput.planStepById` carries. There is no prompt renderer here:
+// an embedder supplies the plan's step DATA and the harness composes each step's
+// seed at dispatch, when the step's dependencies have actually produced something.
 export { AnalysisPlanSchema } from "./schemas/workflow-state.js";
 export { validatePlan } from "./schemas/validate-plan.js";
-export { renderStepPrompt } from "./schemas/render-step-prompt.js";
 // Plan + run + step ledgers around a trigger. `upsertPlan` takes a
 // caller-derived id and inserts-if-absent (the deterministic-id intake path);
 // the run-state calls mirror the chat trigger's reserve → dedup → status flow.
 export { upsertPlan, loadPlan } from "./state/plans.js";
 export { insertRun, queryActiveRun, updateRunStatus, queryRun, queryRunsByAnalysis, RunDedupCollisionError } from "./state/runs.js";
 export { queryStepsByRun } from "./state/step-executions.js";
+// Host-neutral reference-data catalog and shared installation receipts. Each
+// artifact names the third-party upstream it is fetched from; embedders own all
+// transfer/storage behavior but never choose a different source.
+export { REFERENCE_DATA_CATALOG, REFERENCE_DATA_CATALOG_VERSION, ReferenceArtifactPathSchema, ReferenceArtifactSchema, ReferenceDataCatalogSchema, ReferenceDatasetSchema, ReferenceSha256Schema, UnknownReferenceDatasetError, referenceArtifactKey, resolveReferenceInstallPlan, } from "./reference-data/catalog.js";
+export { REFERENCE_INSTALL_RECEIPT_VERSION, ReferenceInstallReceiptSchema, parseReferenceInstallReceipt } from "./reference-data/receipt.js";
 // Backs `WatchdogDeps.queryActiveSandboxes` when the embedder wires the watchdog.
 export { queryActiveSandboxes } from "./state/active-sandboxes.js";
 // Workspace-tree path convention — the root-relative step directory each
 // sandbox step confines its artifact writes to (join onto the resolved root).
 export { runStepDir } from "./workspace/paths.js";
+// `Logger.errorFields` is on the interface so a realization can defer to its
+// sink's native error handling (pino's `err` serializer, OTel's `exception.*`);
+// `defaultErrorFields` is the shipped mapping for one with no opinion.
+export { defaultErrorFields } from "./lib/logger.js";
+export { createConsoleLogger, createNoopLogger } from "./lib/console-logger.js";
 // Sandbox-hygiene scheduled workflows. Reaper reclaims a dead host's orphaned
 // containers; watchdog converts a dead sandbox into a prompt step failure
 // instead of a deadline-long `DBOS.recv` hang; the sweep prunes stale

package/dist/lib/chrome.d.ts

@@ -7,9 +7,12 @@
  * semaphore so the sidecar isn't overwhelmed by concurrent reports.
  */
 import type { Browser, BrowserContext, Page } from "puppeteer-core";
+import type { Logger } from "./logger.js";
 export interface ChromeConfig {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly browserUrl?: string;
     readonly maxPages?: number;
 }
-export declare function getBrowser(browserUrl?: string): Promise<Browser>;
+export declare function getBrowser(browserUrl?: string, injected?: Logger): Promise<Browser>;
 export declare function withPage<T>(cfg: ChromeConfig, fn: (page: Page, context: BrowserContext) => Promise<T>): Promise<T>;

package/dist/lib/chrome.js

@@ -7,6 +7,7 @@
  * semaphore so the sidecar isn't overwhelmed by concurrent reports.
  */
 import puppeteer from "puppeteer-core";
+import { createNoopLogger } from "./console-logger.js";
 let browser;
 let connecting;
 let semaphore;
@@ -41,7 +42,8 @@ function getSemaphore(maxPages) {
     }
     return semaphore;
 }
-export async function getBrowser(browserUrl) {
+export async function getBrowser(browserUrl, injected) {
+    const logger = (injected ?? createNoopLogger()).named("chrome");
     if (browser && browser.connected)
         return browser;
     if (connecting)
@@ -50,21 +52,21 @@ export async function getBrowser(browserUrl) {
     if (!browserURL) {
         throw new Error("CHROME_BROWSER_URL is not set — Cortex requires the chrome sidecar to be reachable");
     }
-    console.log(`[chrome] connecting to browser at ${browserURL}`);
+    logger.info("connecting to browser", { browserURL });
     connecting = puppeteer
         .connect({ browserURL })
         .then((b) => {
         browser = b;
         b.on("disconnected", () => {
-            console.log("[chrome] browser disconnected; will reconnect on next request");
+            logger.info("browser disconnected; will reconnect on next request");
             if (browser === b)
                 browser = undefined;
         });
-        console.log(`[chrome] connected (wsEndpoint=${b.wsEndpoint()})`);
+        logger.info("connected", { wsEndpoint: b.wsEndpoint() });
         return b;
     })
         .catch((err) => {
-        console.error("[chrome] failed to connect to browser:", err);
+        logger.error("failed to connect to browser", logger.errorFields(err));
         throw err;
     })
         .finally(() => {
@@ -76,7 +78,7 @@ export async function withPage(cfg, fn) {
     const release = await getSemaphore(cfg.maxPages).acquire();
     let context;
     try {
-        const b = await getBrowser(cfg.browserUrl);
+        const b = await getBrowser(cfg.browserUrl, cfg.logger);
         context = await b.createBrowserContext();
         const page = await context.newPage();
         return await fn(page, context);
@@ -87,7 +89,8 @@ export async function withPage(cfg, fn) {
                 await context.close();
             }
             catch (err) {
-                console.error("[chrome] error closing browser context:", err);
+                const logger = (cfg.logger ?? createNoopLogger()).named("chrome");
+                logger.error("error closing browser context", logger.errorFields(err));
             }
         }
         release();

package/dist/lib/console-logger.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The trivial `Logger` realizations: one that writes to `console`, and the
+ * silent fallback the harness substitutes when an embedder wires nothing.
+ *
+ * `createConsoleLogger` is offered, never defaulted. A host whose UI owns
+ * stdout (an alternate-screen TUI, for instance) discards console output, so
+ * defaulting to it would quietly reintroduce the invisible-diagnostics failure
+ * the seam exists to prevent — the default is `createNoopLogger`, which is at
+ * least honest about saying nothing.
+ */
+import { type Logger } from "./logger.js";
+/** Build a `Logger` that writes each record to the matching `console` method. */
+export declare function createConsoleLogger(): Logger;
+/**
+ * Build a `Logger` that discards every record. This is what the harness falls
+ * back to when an embedder injects no logger, so internal call sites can log
+ * unconditionally instead of threading `?.` through every diagnostic.
+ */
+export declare function createNoopLogger(): Logger;

package/dist/lib/console-logger.js

@@ -0,0 +1,62 @@
+/**
+ * The trivial `Logger` realizations: one that writes to `console`, and the
+ * silent fallback the harness substitutes when an embedder wires nothing.
+ *
+ * `createConsoleLogger` is offered, never defaulted. A host whose UI owns
+ * stdout (an alternate-screen TUI, for instance) discards console output, so
+ * defaulting to it would quietly reintroduce the invisible-diagnostics failure
+ * the seam exists to prevent — the default is `createNoopLogger`, which is at
+ * least honest about saying nothing.
+ */
+import { defaultErrorFields } from "./logger.js";
+/** Renders accumulated namespace segments as the message's `[a.b]` prefix. */
+function prefixed(names, msg) {
+    return names.length > 0 ? `[${names.join(".")}] ${msg}` : msg;
+}
+/**
+ * `with()` accumulates into `bindings` and `named()` into `names`; each record
+ * merges call-site fields over the bindings, so a narrower call-site key
+ * deliberately wins over inherited context.
+ */
+function makeConsoleLogger(names, bindings) {
+    const emit = (level) => (msg, fields) => {
+        // The one sanctioned console site in the harness — writing to console is
+        // this function's entire contract. `no-console` exempts this file by path
+        // in eslint.config.js rather than by an inline disable here.
+        console[level](prefixed(names, msg), { ...bindings, ...fields });
+    };
+    return {
+        debug: emit("debug"),
+        info: emit("info"),
+        warn: emit("warn"),
+        error: emit("error"),
+        with: (extra) => makeConsoleLogger(names, { ...bindings, ...extra }),
+        named: (name) => makeConsoleLogger([...names, name], bindings),
+        // console renders whatever it is handed; there is no native error
+        // serializer here to defer to, so the shipped default is the right shape.
+        errorFields: defaultErrorFields,
+    };
+}
+/** Build a `Logger` that writes each record to the matching `console` method. */
+export function createConsoleLogger() {
+    return makeConsoleLogger([], {});
+}
+/**
+ * Build a `Logger` that discards every record. This is what the harness falls
+ * back to when an embedder injects no logger, so internal call sites can log
+ * unconditionally instead of threading `?.` through every diagnostic.
+ */
+export function createNoopLogger() {
+    const noop = {
+        debug: () => { },
+        info: () => { },
+        warn: () => { },
+        error: () => { },
+        with: () => noop,
+        named: () => noop,
+        // Still the real mapping, not `{}`: callers spread the result into fields
+        // they may pass elsewhere, so it must stay honest even when nothing is emitted.
+        errorFields: defaultErrorFields,
+    };
+    return noop;
+}

package/dist/lib/logger.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The harness's operational logging seam.
+ *
+ * The harness ships as a published package embedded by hosts it does not
+ * control, so it declares the shape it logs through and lets the embedder bind
+ * a realization at its composition root — the same inversion the capability
+ * seams use. Naming a concrete logger here would push that library onto every
+ * consumer.
+ *
+ * The alternative that reads as obvious — take the embedder's logger type
+ * directly — was rejected for exactly that reason. `@opentelemetry/api-logs`
+ * was the other candidate, being the nearest thing to a neutral standard, but
+ * it is still pre-1.0 and would force consumers into an OTel SDK to read a log
+ * line. JS has no `log/slog` equivalent to conform to, so the harness defines
+ * its own minimum and adapts at the edges.
+ *
+ * Diagnostics MUST go through here, never `console`: an embedder whose UI owns
+ * stdout discards console output entirely, which is silent data loss precisely
+ * when something has gone wrong. `createConsoleLogger` (`./console-logger.ts`)
+ * is the one sanctioned console site.
+ */
+/** Severity of a log record, ascending. */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Structured key/value context attached to a record. Identifiers ride here
+ * rather than interpolated into the message so records stay queryable and any
+ * field-name redaction the host configures can actually match them.
+ */
+export type LogFields = Record<string, unknown>;
+/**
+ * Operational logger. Message-first (`error(msg, fields?)`) — the convention
+ * `slog`, winston, and `console` share. Object-first loggers exist (pino,
+ * bunyan) and an embedder using one adapts at its composition root; shaping
+ * this contract to match one of them would model the published surface on a
+ * single consumer's choice.
+ */
+export interface Logger {
+    debug(msg: string, fields?: LogFields): void;
+    info(msg: string, fields?: LogFields): void;
+    warn(msg: string, fields?: LogFields): void;
+    error(msg: string, fields?: LogFields): void;
+    /**
+     * Bind `fields` onto every record the returned logger emits — `slog`'s
+     * `With`. Lets a workflow body fix `{ runId, stepId }` once instead of
+     * repeating it at each call site.
+     */
+    with(fields: LogFields): Logger;
+    /**
+     * Bind a namespace onto every record the returned logger emits, rendered as
+     * a bracketed prefix on the message: `named("boot")` turns
+     * `info("harness booted")` into `[boot] harness booted`.
+     *
+     * The namespace is a first-class part of a record, so it is declared once at
+     * the seam rather than hand-typed into every message string — hand-typing is
+     * what lets one module drift to `[Boot]` or drop the tag entirely. Nesting
+     * composes with a dot (`named("post-step").named("reconcile")` →
+     * `[post-step.reconcile]`), matching the tag convention already in use.
+     */
+    named(name: string): Logger;
+    /**
+     * Normalize a thrown value into fields to spread onto a record:
+     * `logger.error("step failure", { ...logger.errorFields(err), stepId })`.
+     *
+     * Every catch block would otherwise hand-roll
+     * `err instanceof Error ? err.message : String(err)` — repetition that
+     * reliably drifts, and that silently drops the stack from whichever site
+     * forgot it.
+     *
+     * It lives on the interface rather than as a free function because how an
+     * error is best represented is a property of the SINK, not of the harness: a
+     * pino-backed realization may defer to pino's `err` serializer, an
+     * OTel-backed one to the `exception.*` semantic conventions. Owning the
+     * mapping here would foreclose both. `defaultErrorFields` is the shipped
+     * implementation — a realization with no opinion just references it.
+     */
+    errorFields(err: unknown): LogFields;
+}
+/**
+ * The default `Logger.errorFields`: `err` carries the message, `stack` rides as
+ * its own field when there is one.
+ *
+ * A raw `Error` is deliberately not passed through as a field value: it is
+ * assignable to `unknown` and so type-checks, but `JSON.stringify(new Error())`
+ * is `{}` — a sink that serializes to JSON would drop the message entirely,
+ * which is the silent-loss failure this seam exists to prevent. Normalizing to
+ * strings means any sink gets something printable regardless of its serializer.
+ */
+export declare function defaultErrorFields(err: unknown): LogFields;

package/dist/lib/logger.js

@@ -0,0 +1,37 @@
+/**
+ * The harness's operational logging seam.
+ *
+ * The harness ships as a published package embedded by hosts it does not
+ * control, so it declares the shape it logs through and lets the embedder bind
+ * a realization at its composition root — the same inversion the capability
+ * seams use. Naming a concrete logger here would push that library onto every
+ * consumer.
+ *
+ * The alternative that reads as obvious — take the embedder's logger type
+ * directly — was rejected for exactly that reason. `@opentelemetry/api-logs`
+ * was the other candidate, being the nearest thing to a neutral standard, but
+ * it is still pre-1.0 and would force consumers into an OTel SDK to read a log
+ * line. JS has no `log/slog` equivalent to conform to, so the harness defines
+ * its own minimum and adapts at the edges.
+ *
+ * Diagnostics MUST go through here, never `console`: an embedder whose UI owns
+ * stdout discards console output entirely, which is silent data loss precisely
+ * when something has gone wrong. `createConsoleLogger` (`./console-logger.ts`)
+ * is the one sanctioned console site.
+ */
+/**
+ * The default `Logger.errorFields`: `err` carries the message, `stack` rides as
+ * its own field when there is one.
+ *
+ * A raw `Error` is deliberately not passed through as a field value: it is
+ * assignable to `unknown` and so type-checks, but `JSON.stringify(new Error())`
+ * is `{}` — a sink that serializes to JSON would drop the message entirely,
+ * which is the silent-loss failure this seam exists to prevent. Normalizing to
+ * strings means any sink gets something printable regardless of its serializer.
+ */
+export function defaultErrorFields(err) {
+    if (err instanceof Error) {
+        return err.stack ? { err: err.message, stack: err.stack } : { err: err.message };
+    }
+    return { err: String(err) };
+}

package/dist/lib/otel.d.ts

@@ -15,13 +15,14 @@
  *        so inbound/outbound trace-context propagation across those paths is
  *        not currently wired.
  */
+import type { Logger } from "./logger.js";
 /**
  * Initialize the OpenTelemetry SDK. Must be called before any code that
  * calls trace.getTracer() or metrics.getMeter().
  *
  * Safe to call multiple times — only the first call has effect.
  */
-export declare function initOtel(): void;
+export declare function initOtel(injected?: Logger): void;
 /**
  * Flush and shut down the OTel exporters. Called by the graceful-shutdown
  * sequence so in-flight batch spans/metrics make it to the collector

package/dist/lib/otel.js

@@ -16,6 +16,7 @@
  *        not currently wired.
  */
 import { propagation, metrics, trace } from "@opentelemetry/api";
+import { createNoopLogger } from "./console-logger.js";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
@@ -33,10 +34,11 @@ let registeredMeterProvider;
  *
  * Safe to call multiple times — only the first call has effect.
  */
-export function initOtel() {
+export function initOtel(injected) {
     if (initialized)
         return;
     initialized = true;
+    const logger = (injected ?? createNoopLogger()).named("otel");
     // ── W3C Trace Context propagation ──────────────────────────────────
     propagation.setGlobalPropagator(new W3CTraceContextPropagator());
     const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
@@ -65,8 +67,11 @@ export function initOtel() {
         const testSpan = testTracer.startSpan("init-check");
         const ctx = testSpan.spanContext();
         const isNoop = ctx.spanId === "0000000000000000";
-        console.log(`[otel] TracerProvider registered: spanId=${ctx.spanId}, noop=${isNoop}, ` +
-            `endpoint=${endpoint ?? "(none)"}, processors=${spanProcessors.length}`);
+        // A `console.log` here is what forced the CLI embedder to pass
+        // `initTelemetry: () => {}` — its TUI owns stdout, so the banner corrupted
+        // the screen and the whole of the harness's traces + metrics were switched
+        // off to avoid it. At debug through the injected seam it costs nothing.
+        logger.debug("TracerProvider registered", { spanId: ctx.spanId, noop: isNoop, endpoint: endpoint ?? null, processors: spanProcessors.length });
         testSpan.end();
     }
     // ── Metrics ────────────────────────────────────────────────────────

package/dist/loop/__fixtures__/scripted-provider.d.ts

@@ -1,4 +1,4 @@
-import type { ChatResponse, ChatProvider, ChatRequest } from "../../providers/types.js";
+import type { ChatResponse, ChatProvider, ChatRequest, ChatUsage } from "../../providers/types.js";
 import type { AgentSession as Session } from "../../auth/types.js";
 export type TextBlock = {
     type: "text";
@@ -20,7 +20,7 @@ export type ToolUseBlock = {
     input: unknown;
 };
 export type ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock;
-export declare function makeMessage(content: ContentBlock[], finishReason: ChatResponse["finishReason"] | "tool_use" | "end_turn" | "max_tokens" | "refusal"): ChatResponse;
+export declare function makeMessage(content: ContentBlock[], finishReason: ChatResponse["finishReason"] | "tool_use" | "end_turn" | "max_tokens" | "refusal", usage?: ChatUsage): ChatResponse;
 export declare function textBlock(text: string): TextBlock;
 export declare function thinkingBlock(thinking: string, signature: string): ThinkingBlock;
 export declare function toolUseBlock(id: string, name: string, input: unknown): ToolUseBlock;

package/dist/loop/__fixtures__/scripted-provider.js

@@ -13,10 +13,11 @@ function mapFinishReason(finishReason) {
             return finishReason;
     }
 }
-export function makeMessage(content, finishReason) {
+export function makeMessage(content, finishReason, usage) {
     return {
         message: { role: "assistant", content },
         finishReason: mapFinishReason(finishReason),
+        usage,
     };
 }
 export function textBlock(text) {