@inflexa-ai/harness 0.2.0 → 0.3.0

package/dist/execution/step-summary.js

@@ -32,6 +32,7 @@ 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.
@@ -69,6 +70,7 @@ 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 = {
@@ -89,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

@@ -108,6 +108,9 @@ export { REFERENCE_INSTALL_RECEIPT_VERSION, ReferenceInstallReceiptSchema, parse
 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

@@ -162,6 +162,11 @@ 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/runtime/boot.d.ts

@@ -31,7 +31,7 @@
  * once shutdown starts, exiting takes precedence (see `runShutdownSequence`).
  */
 import type { Pool } from "pg";
-import type pino from "pino";
+import type { Logger } from "../lib/logger.js";
 import { type CoreRuntime, type CoreRuntimeDeps } from "./assemble.js";
 import { type ConnectionBudgetConfig } from "./connection-budget.js";
 import { type DbosConfig } from "./dbos.js";
@@ -46,7 +46,7 @@ export interface BootHarnessDeps {
     readonly dbos: DbosConfig;
     /** Connection-budget guard config. */
     readonly connectionBudget: ConnectionBudgetConfig;
-    readonly logger: pino.Logger;
+    readonly logger: Logger;
     /**
      * Host-specific work that must run AFTER workflow registration and BEFORE
      * DBOS launch (scheduled sweeps, ephemeral reap, agent-switch install). The

package/dist/runtime/boot.js

@@ -49,7 +49,7 @@ export async function bootHarness(deps) {
     const runtime = assembleCoreRuntime(core);
     await deps.beforeLaunch?.();
     await launchDbos({ config: deps.dbos, logger });
-    logger.info({ executorId: deps.dbos.executorId }, "[boot] harness booted");
+    logger.named("boot").info("harness booted", { executorId: deps.dbos.executorId });
     const shutdown = (signal) => runShutdownSequence({
         signal,
         logger,

package/dist/runtime/connection-budget.d.ts

@@ -21,7 +21,7 @@
  * misconfigured pod fails boot loudly instead of degrading under load.
  */
 import type { Pool } from "pg";
-import type pino from "pino";
+import type { Logger } from "../lib/logger.js";
 /**
  * Narrow config slice the budget guard reads — only the optional app-pool
  * size override. Composition roots map `Env.DB_POOL_MAX` onto this.
@@ -31,7 +31,7 @@ export interface ConnectionBudgetConfig {
 }
 export interface AssertConnectionBudgetOptions {
     pool: Pool;
-    logger: pino.Logger;
+    logger: Logger;
     config: ConnectionBudgetConfig;
 }
 /**

package/dist/runtime/connection-budget.js

@@ -38,15 +38,17 @@ export async function assertConnectionBudget({ pool, logger, config }) {
             `Lower DB_POOL_MAX or raise max_connections.`);
     }
     const supportedReplicas = Math.floor((maxConnections - SAFETY_MARGIN) / podFootprint);
-    logger.info({
+    logger
+        .named("boot")
+        .info(`postgres connection budget OK — this cluster's max_connections ` +
+        `supports ~${supportedReplicas} cortex replicas; size replicas/pooler accordingly`, {
         maxConnections,
         appPoolSize,
         dbosPoolSize,
         podFootprint,
         safetyMargin: SAFETY_MARGIN,
         supportedReplicas,
-    }, `[boot] postgres connection budget OK — this cluster's max_connections ` +
-        `supports ~${supportedReplicas} cortex replicas; size replicas/pooler accordingly`);
+    });
     return {
         maxConnections,
         appPoolSize,

package/dist/runtime/dbos.d.ts

@@ -12,8 +12,8 @@
  *
  * See `openspec/changes/harness-dbos-runtime`.
  */
-import type pino from "pino";
 import type { Pool } from "pg";
+import type { Logger } from "../lib/logger.js";
 /**
  * Narrow config slice the DBOS bootstrap reads. Composition roots map their
  * validated `Env` onto this and pass the executor id in (the harness reads no env).
@@ -50,9 +50,9 @@ interface State {
  * must resolve before the HTTP listener accepts traffic (otherwise the
  * readiness probe could 200 against a runtime that can't own workflows).
  */
-export declare function launchDbos({ config, logger }: {
+export declare function launchDbos({ config, logger: injected }: {
     config: DbosConfig;
-    logger: pino.Logger;
+    logger: Logger;
 }): Promise<void>;
 /**
  * Shut DBOS down. In-flight workflows are marked recoverable so another
@@ -63,8 +63,8 @@ export declare function launchDbos({ config, logger }: {
  * Must run after HTTP has drained (so no inbound request is orphaned) and
  * before the application pool closes (DBOS needs the system DB).
  */
-export declare function shutdownDbos({ logger }: {
-    logger: pino.Logger;
+export declare function shutdownDbos({ logger: injected }: {
+    logger: Logger;
 }): Promise<void>;
 /**
  * Cancel any `ephemeral:`-prefixed PENDING workflow this executor owns —
@@ -79,9 +79,9 @@ export declare function shutdownDbos({ logger }: {
  * pre-launch timing, and this is the sole module that owns DBOS. The system
  * DB is the same database as the app pool, so the pool reaches it directly.
  */
-export declare function sweepEphemeralWorkflows({ pool, logger, executorId, }: {
+export declare function sweepEphemeralWorkflows({ pool, logger: injectedLogger, executorId, }: {
     pool: Pool;
-    logger: pino.Logger;
+    logger: Logger;
     /** Stable per-pod executor id — must match `launchDbos`'s `executorId`. */
     executorId: string;
 }): Promise<void>;

package/dist/runtime/dbos.js

@@ -53,9 +53,10 @@ function systemDatabaseUrl(config) {
  * must resolve before the HTTP listener accepts traffic (otherwise the
  * readiness probe could 200 against a runtime that can't own workflows).
  */
-export async function launchDbos({ config, logger }) {
+export async function launchDbos({ config, logger: injected }) {
     if (state.launched)
         return;
+    const logger = injected.named("dbos");
     const executorID = config.executorId;
     const adminPort = parseInt(config.adminPort, 10);
     DBOS.setConfig({
@@ -71,12 +72,12 @@ export async function launchDbos({ config, logger }) {
     await DBOS.launch();
     state.launched = true;
     state.recoveryStarted = true;
-    logger.info({
+    logger.info("launched", {
         executorID,
         applicationVersion: config.applicationVersion,
         adminPort,
         durationMs: Math.round(performance.now() - start),
-    }, "[dbos] launched");
+    });
 }
 /**
  * Shut DBOS down. In-flight workflows are marked recoverable so another
@@ -87,19 +88,20 @@ export async function launchDbos({ config, logger }) {
  * Must run after HTTP has drained (so no inbound request is orphaned) and
  * before the application pool closes (DBOS needs the system DB).
  */
-export async function shutdownDbos({ logger }) {
+export async function shutdownDbos({ logger: injected }) {
     if (!state.launched)
         return;
+    const logger = injected.named("dbos");
     const start = performance.now();
     try {
         await DBOS.shutdown();
-        logger.info({ durationMs: Math.round(performance.now() - start) }, "[dbos] shutdown");
+        logger.info("shutdown", { durationMs: Math.round(performance.now() - start) });
     }
     catch (err) {
-        logger.error({
-            err: err instanceof Error ? err.message : String(err),
+        logger.error("shutdown failed", {
+            ...logger.errorFields(err),
             durationMs: Math.round(performance.now() - start),
-        }, "[dbos] shutdown failed");
+        });
     }
     finally {
         state.launched = false;
@@ -119,7 +121,8 @@ export async function shutdownDbos({ logger }) {
  * pre-launch timing, and this is the sole module that owns DBOS. The system
  * DB is the same database as the app pool, so the pool reaches it directly.
  */
-export async function sweepEphemeralWorkflows({ pool, logger, executorId, }) {
+export async function sweepEphemeralWorkflows({ pool, logger: injectedLogger, executorId, }) {
+    const logger = injectedLogger.named("dbos");
     const executorID = executorId;
     try {
         const { rowCount } = await pool.query({
@@ -131,7 +134,7 @@ export async function sweepEphemeralWorkflows({ pool, logger, executorId, }) {
             values: [Date.now(), executorID],
         });
         if (rowCount && rowCount > 0) {
-            logger.info({ executorID, swept: rowCount }, "[dbos] swept orphaned ephemeral workflows");
+            logger.info("swept orphaned ephemeral workflows", { executorID, swept: rowCount });
         }
     }
     catch (err) {
@@ -139,7 +142,7 @@ export async function sweepEphemeralWorkflows({ pool, logger, executorId, }) {
         if (err && typeof err === "object" && "code" in err && err.code === "42P01") {
             return;
         }
-        logger.error({ executorID, err: err instanceof Error ? err.message : String(err) }, "[dbos] ephemeral sweep failed");
+        logger.error("ephemeral sweep failed", { executorID, ...logger.errorFields(err) });
     }
 }
 /** Snapshot of DBOS lifecycle state — read by the readiness probe. */

package/dist/runtime/shutdown.d.ts

@@ -18,10 +18,10 @@
  * swallowed — once shutdown has started, exiting takes precedence over
  * any single step's failure.
  */
-import type pino from "pino";
+import type { Logger } from "../lib/logger.js";
 export interface ShutdownDeps {
     signal: string;
-    logger: pino.Logger;
+    logger: Logger;
     markDraining: () => void;
     closeHttpServer: () => Promise<void>;
     shutdownDbos: () => Promise<void>;

package/dist/runtime/shutdown.js

@@ -23,12 +23,13 @@ async function safely(logger, step, fn) {
         await fn();
     }
     catch (err) {
-        logger.error({ err: err instanceof Error ? err.message : String(err), step }, `[shutdown] ${step} failed`);
+        logger.error(`${step} failed`, { ...logger.errorFields(err), step });
     }
 }
 export async function runShutdownSequence(deps) {
-    const { logger, signal } = deps;
-    logger.info({ signal }, "[shutdown] requested");
+    const { signal } = deps;
+    const logger = deps.logger.named("shutdown");
+    logger.info("requested", { signal });
     deps.markDraining();
     await safely(logger, "http-drain", deps.closeHttpServer);
     await safely(logger, "dbos-shutdown", deps.shutdownDbos);

package/dist/sandbox/create-sandbox.d.ts

@@ -13,7 +13,7 @@
  */
 import type { V1Toleration } from "@kubernetes/client-node";
 import type { Pool } from "pg";
-import type pino from "pino";
+import type { Logger } from "../lib/logger.js";
 import { type ResourceLimits } from "../config/resource-limits.js";
 import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
 import { clearSandboxRef } from "../state/index.js";
@@ -87,7 +87,7 @@ export interface CreateSandboxClientConfig {
      * (a configured store whose `current` vanished/went incomplete mid-session) is
      * observable rather than a silent mount drop. No-op when unset.
      */
-    logger?: Pick<pino.Logger, "info" | "warn" | "error">;
+    logger?: Logger;
     /** Dependency seams (fetch, durable step/sleep, clock, recv, warn sink) forwarded to submit/await. */
     submitDeps?: SubmitExecDeps;
     awaitOptions?: AwaitExecOptions;