whale-code 6.4.0

package/dist/server/lib/code-worker-pool.js

@@ -0,0 +1,224 @@
+// server/lib/code-worker-pool.ts — Persistent pre-forked worker pool for code steps
+// Eliminates fork-per-execution overhead. Workers are recycled after MAX_USES executions.
+import { fork } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname_pool = dirname(fileURLToPath(import.meta.url));
+const WORKER_PATH = join(__dirname_pool, "code-worker.js");
+const POOL_SIZE = parseInt(process.env.CODE_WORKER_POOL_SIZE || "4", 10);
+const MAX_USES = 50; // Recycle worker after N executions (prevent memory leaks)
+const ACQUIRE_TIMEOUT_MS = 10_000; // Max wait to acquire a worker
+const pool = [];
+const waitQueue = [];
+let initialized = false;
+// Restricted env for worker processes — strip server secrets (API keys, DB URLs, etc.)
+const WORKER_ENV = {
+    NODE_ENV: process.env.NODE_ENV || "production",
+    PATH: process.env.PATH || "/usr/local/bin:/usr/bin:/bin",
+};
+function spawnWorker() {
+    const child = fork(WORKER_PATH, [], {
+        stdio: "pipe",
+        serialization: "json",
+        env: WORKER_ENV,
+    });
+    const worker = { child, busy: false, uses: 0, ready: false };
+    child.on("message", (msg) => {
+        if (msg.type === "ready") {
+            worker.ready = true;
+        }
+    });
+    child.on("exit", () => {
+        // Remove dead worker from pool and replace it
+        const idx = pool.indexOf(worker);
+        if (idx >= 0) {
+            pool.splice(idx, 1);
+            try {
+                pool.push(spawnWorker());
+            }
+            catch {
+                // Can't respawn — pool shrinks
+            }
+        }
+    });
+    child.on("error", () => {
+        // Will trigger exit event above
+    });
+    return worker;
+}
+/** Initialize the worker pool. Safe to call multiple times. */
+export function initWorkerPool() {
+    if (initialized)
+        return;
+    initialized = true;
+    for (let i = 0; i < POOL_SIZE; i++) {
+        try {
+            pool.push(spawnWorker());
+        }
+        catch {
+            console.error(`[worker-pool] Failed to spawn worker ${i + 1}/${POOL_SIZE}`);
+        }
+    }
+    console.log(`[worker-pool] Initialized with ${pool.length} workers`);
+}
+/** Acquire an available worker, or wait in queue. */
+function acquireWorker() {
+    // Try to find an idle worker
+    const idle = pool.find(w => !w.busy && w.ready);
+    if (idle) {
+        idle.busy = true;
+        return Promise.resolve(idle);
+    }
+    // No idle worker — wait in queue
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            const idx = waitQueue.findIndex(q => q.resolve === resolve);
+            if (idx >= 0)
+                waitQueue.splice(idx, 1);
+            reject(new Error("Timed out waiting for available code worker"));
+        }, ACQUIRE_TIMEOUT_MS);
+        waitQueue.push({ resolve, timer });
+    });
+}
+/** Release a worker back to the pool. Recycle if MAX_USES reached. */
+function releaseWorker(worker) {
+    worker.busy = false;
+    worker.uses++;
+    // Recycle if too many uses (prevent memory leaks in vm)
+    if (worker.uses >= MAX_USES) {
+        const idx = pool.indexOf(worker);
+        if (idx >= 0)
+            pool.splice(idx, 1);
+        try {
+            worker.child.kill("SIGTERM");
+        }
+        catch { /* process already dead */ }
+        try {
+            pool.push(spawnWorker());
+        }
+        catch { /* spawn failure handled by pool size checks */ }
+        return;
+    }
+    // Service waiting queue
+    if (waitQueue.length > 0) {
+        const next = waitQueue.shift();
+        clearTimeout(next.timer);
+        worker.busy = true;
+        next.resolve(worker);
+    }
+}
+/**
+ * Execute code using the worker pool. Falls back to direct fork if pool is unavailable.
+ */
+export async function executeWithPool(req) {
+    if (!initialized || pool.length === 0) {
+        // Pool not available — fall back to one-shot fork
+        return executeDirectFork(req);
+    }
+    let worker;
+    try {
+        worker = await acquireWorker();
+    }
+    catch {
+        return executeDirectFork(req);
+    }
+    return new Promise((resolve) => {
+        let resolved = false;
+        const finish = (result) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(killTimer);
+            releaseWorker(worker);
+            resolve(result);
+        };
+        const killTimer = setTimeout(() => {
+            finish({ success: false, error: `Code execution timed out after ${req.timeoutMs}ms` });
+            // Kill and replace the stuck worker
+            const idx = pool.indexOf(worker);
+            if (idx >= 0)
+                pool.splice(idx, 1);
+            try {
+                worker.child.kill("SIGKILL");
+            }
+            catch { /* process already dead */ }
+            try {
+                pool.push(spawnWorker());
+            }
+            catch { /* spawn failure handled by pool size checks */ }
+        }, req.timeoutMs + 3000);
+        // Listen for result (one-shot)
+        const onMessage = (msg) => {
+            if (msg.type === "result") {
+                worker.child.removeListener("message", onMessage);
+                finish(msg.success
+                    ? { success: true, output: msg.output, logs: msg.logs }
+                    : { success: false, error: msg.error, logs: msg.logs });
+            }
+        };
+        worker.child.on("message", onMessage);
+        // Send code
+        worker.child.send({
+            type: "execute",
+            code: req.code,
+            context: req.context,
+            timeoutMs: req.timeoutMs,
+        });
+    });
+}
+/** One-shot fork fallback (same as original) */
+function executeDirectFork(req) {
+    return new Promise((resolve) => {
+        let resolved = false;
+        let child;
+        const finish = (result) => {
+            if (resolved)
+                return;
+            resolved = true;
+            try {
+                child?.kill("SIGKILL");
+            }
+            catch { /* process already dead */ }
+            resolve(result);
+        };
+        try {
+            child = fork(WORKER_PATH, [], { timeout: req.timeoutMs + 2000, stdio: "pipe", serialization: "json", env: WORKER_ENV });
+        }
+        catch {
+            return resolve({ success: false, error: "Failed to fork code worker" });
+        }
+        const killTimer = setTimeout(() => {
+            finish({ success: false, error: `Code execution timed out after ${req.timeoutMs}ms` });
+        }, req.timeoutMs + 3000);
+        child.on("message", (msg) => {
+            if (msg.type === "result") {
+                clearTimeout(killTimer);
+                finish(msg.success ? { success: true, output: msg.output } : { success: false, error: msg.error });
+            }
+        });
+        child.on("error", (err) => { clearTimeout(killTimer); finish({ success: false, error: `Worker error: ${err.message}` }); });
+        child.on("exit", (code) => { clearTimeout(killTimer); if (!resolved)
+            finish({ success: false, error: `Worker crashed (exit ${code})` }); });
+        child.send({ type: "execute", code: req.code, context: req.context, timeoutMs: req.timeoutMs });
+    });
+}
+/** Gracefully shutdown all workers */
+export function shutdownPool() {
+    for (const w of pool) {
+        try {
+            w.child.kill("SIGTERM");
+        }
+        catch { /* process already dead */ }
+    }
+    pool.length = 0;
+    initialized = false;
+}
+/** Pool stats for monitoring */
+export function getPoolStats() {
+    return {
+        total: pool.length,
+        busy: pool.filter(w => w.busy).length,
+        idle: pool.filter(w => !w.busy && w.ready).length,
+        queue: waitQueue.length,
+    };
+}

package/dist/server/lib/code-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/lib/code-worker.js

@@ -0,0 +1,188 @@
+// server/lib/code-worker.ts — Isolated code execution worker
+// Runs as a child process via fork(). Receives code + context via IPC,
+// executes in a fresh vm context, returns result. Crash here cannot take down the server.
+import { runInNewContext } from "node:vm";
+import { randomUUID } from "node:crypto";
+/**
+ * Create a safe wrapper function that cannot be used to reach the host Function constructor.
+ * Wraps a host function in a proxy whose prototype chain is severed — .constructor returns
+ * undefined instead of the host Function constructor.
+ */
+function safeFunction(fn) {
+    // Create a wrapper function whose .constructor and .prototype are severed.
+    // We can't make a callable null-prototype object directly, so we override them on a regular function.
+    const safe = function (...args) {
+        return fn.apply(this, args);
+    };
+    Object.defineProperty(safe, "constructor", { value: undefined, writable: false, configurable: false });
+    Object.defineProperty(safe, "prototype", { value: undefined, writable: false, configurable: false });
+    // Freeze to prevent re-assignment of constructor
+    Object.freeze(safe);
+    return safe;
+}
+/**
+ * Create a safe namespace object (like Math, JSON, Buffer) whose properties
+ * cannot reach the host Function constructor through any prototype chain.
+ * All function-valued properties are wrapped via safeFunction().
+ */
+function safeNamespace(source, keys) {
+    const ns = Object.create(null);
+    for (const key of keys) {
+        const val = source[key];
+        if (typeof val === "function") {
+            ns[key] = safeFunction(val);
+        }
+        else {
+            ns[key] = val;
+        }
+    }
+    return Object.freeze(ns);
+}
+// Only run when forked as a child process
+if (process.send) {
+    process.on("message", (msg) => {
+        if (msg.type !== "execute")
+            return;
+        const logs = [];
+        // Validate code for dangerous patterns (defense-in-depth — sandbox isolation is primary defense)
+        const dangerousPatterns = [
+            /constructor\s*\[/i,
+            /constructor\s*\(/i,
+            /\.constructor/i,
+            /__proto__/i,
+            /prototype\s*\[/i,
+            /\bprocess\b/,
+            /\brequire\b/,
+            /\bimport\b/,
+            /\bglobalThis\b/,
+            /\bglobal\b/,
+            /\bFunction\b/,
+            /\beval\b/,
+            /\bReflect\b/,
+            /\bProxy\b/,
+            /\bSymbol\b/,
+            /\bWeakRef\b/,
+        ];
+        for (const pattern of dangerousPatterns) {
+            if (pattern.test(msg.code)) {
+                const result = {
+                    type: "result",
+                    success: false,
+                    error: `Code contains blocked pattern: ${pattern.source}`,
+                };
+                process.send(result);
+                return;
+            }
+        }
+        // Build hardened sandbox — NO host constructors or direct function references.
+        // vm.runInNewContext provides its own Array, Object, String, Number, Boolean in the
+        // sandbox context. We do NOT pass host realm constructors, which would allow
+        // escaping via .constructor.constructor('return process')().
+        const sandbox = Object.create(null);
+        sandbox.steps = JSON.parse(JSON.stringify(msg.context.steps));
+        sandbox.trigger = JSON.parse(JSON.stringify(msg.context.trigger));
+        sandbox.input = msg.context.input != null ? JSON.parse(JSON.stringify(msg.context.input)) : undefined;
+        sandbox.output = undefined;
+        // console — safe: null-prototype object with wrapped log function
+        const logFn = safeFunction((...args) => logs.push(args.map(String).join(" ")));
+        const consoleObj = Object.create(null);
+        consoleObj.log = logFn;
+        sandbox.console = Object.freeze(consoleObj);
+        // JSON — safe namespace with only parse/stringify
+        sandbox.JSON = safeNamespace(JSON, ["parse", "stringify"]);
+        // Math — safe namespace (all methods wrapped, numeric constants preserved)
+        const mathKeys = [
+            "abs", "ceil", "floor", "round", "max", "min", "pow", "sqrt", "log", "log2", "log10",
+            "random", "sign", "trunc", "cbrt", "hypot", "clz32", "imul", "fround",
+            "sin", "cos", "tan", "asin", "acos", "atan", "atan2", "sinh", "cosh", "tanh",
+            "PI", "E", "LN2", "LN10", "LOG2E", "LOG10E", "SQRT2", "SQRT1_2",
+        ];
+        sandbox.Math = safeNamespace(Math, mathKeys);
+        // Date — only expose Date.now() as a safe function, not the Date constructor itself.
+        // The Date constructor is a host function whose .constructor leads to Function.
+        const dateNs = Object.create(null);
+        dateNs.now = safeFunction(Date.now);
+        sandbox.Date = Object.freeze(dateNs);
+        // Utility functions — each wrapped to sever .constructor chain
+        sandbox.parseInt = safeFunction(parseInt);
+        sandbox.parseFloat = safeFunction(parseFloat);
+        sandbox.isNaN = safeFunction(isNaN);
+        sandbox.isFinite = safeFunction(isFinite);
+        sandbox.encodeURIComponent = safeFunction(encodeURIComponent);
+        sandbox.decodeURIComponent = safeFunction(decodeURIComponent);
+        // URL — safe namespace with only parse method (no constructor exposure)
+        const urlNs = Object.create(null);
+        urlNs.parse = safeFunction((input) => {
+            try {
+                const u = new URL(input);
+                return { href: u.href, protocol: u.protocol, host: u.host, hostname: u.hostname,
+                    port: u.port, pathname: u.pathname, search: u.search, hash: u.hash,
+                    origin: u.origin, searchParams: Object.fromEntries(u.searchParams) };
+            }
+            catch {
+                return null;
+            }
+        });
+        urlNs.format = safeFunction((parts) => {
+            try {
+                return new URL(`${parts.protocol || "https:"}//${parts.host || parts.hostname || ""}${parts.pathname || ""}${parts.search || ""}`).href;
+            }
+            catch {
+                return null;
+            }
+        });
+        sandbox.URL = Object.freeze(urlNs);
+        // Buffer — safe namespace with wrapped from/alloc
+        const bufferNs = Object.create(null);
+        bufferNs.from = safeFunction((...args) => Buffer.from(args[0], args[1]));
+        bufferNs.alloc = safeFunction((size) => Buffer.alloc(size));
+        sandbox.Buffer = Object.freeze(bufferNs);
+        // crypto — safe namespace with wrapped randomUUID
+        const cryptoNs = Object.create(null);
+        cryptoNs.randomUUID = safeFunction(randomUUID);
+        sandbox.crypto = Object.freeze(cryptoNs);
+        // DO NOT expose host constructors: Array, Object, String, Number, Boolean.
+        // vm.runInNewContext creates its own versions of these in the sandbox context.
+        // Passing host constructors would allow: [].constructor.constructor('return process')()
+        // Block dangerous globals explicitly
+        sandbox.process = undefined;
+        sandbox.require = undefined;
+        sandbox.global = undefined;
+        sandbox.globalThis = undefined;
+        sandbox.Function = undefined;
+        sandbox.eval = undefined;
+        sandbox.setTimeout = undefined;
+        sandbox.setInterval = undefined;
+        sandbox.Reflect = undefined;
+        sandbox.Proxy = undefined;
+        sandbox.Symbol = undefined;
+        sandbox.WeakRef = undefined;
+        try {
+            const result = runInNewContext(msg.code, sandbox, {
+                timeout: msg.timeoutMs,
+                filename: "workflow-code-step",
+                breakOnSigint: true,
+                microtaskMode: "afterEvaluate",
+            });
+            const workerResult = {
+                type: "result",
+                success: true,
+                output: { result: sandbox.output ?? result, logs },
+            };
+            process.send(workerResult);
+        }
+        catch (err) {
+            const workerResult = {
+                type: "result",
+                success: false,
+                error: err.code === "ERR_SCRIPT_EXECUTION_TIMEOUT"
+                    ? `Code execution timed out after ${msg.timeoutMs}ms`
+                    : `Code error: ${err.message}`,
+                logs,
+            };
+            process.send(workerResult);
+        }
+    });
+    // Signal ready
+    process.send({ type: "ready" });
+}

package/dist/server/lib/compaction-service.d.ts

@@ -0,0 +1,32 @@
+import Anthropic from "@anthropic-ai/sdk";
+export interface CompactionResult {
+    success: boolean;
+    content?: string;
+    error?: string;
+}
+export interface PreCompactResult {
+    messages: Array<Record<string, unknown>>;
+    bytesRemoved: number;
+}
+/**
+ * Pre-compaction pass: strip redundant data before calling LLM summarizer.
+ * Mechanically removes large tool results already processed by the agent
+ * and thinking blocks from older turns. Returns modified messages array
+ * with reduced content so the LLM summarizer (or API context_management)
+ * has less to work with.
+ */
+export declare function preCompact(messages: Array<Record<string, unknown>>): PreCompactResult;
+/**
+ * Generate a compaction summary using Haiku.
+ *
+ * Takes the full conversation history and produces a concise summary
+ * that preserves all state needed to continue the conversation.
+ * Falls back gracefully — returns null content on failure so the
+ * caller can keep the unsummarized history.
+ */
+export declare function generateCompaction(opts: {
+    anthropic: Anthropic;
+    messages: Array<Record<string, unknown>>;
+    systemPrompt: string;
+    instructions?: string;
+}): Promise<CompactionResult>;

package/dist/server/lib/compaction-service.js

@@ -0,0 +1,162 @@
+// server/lib/compaction-service.ts — Haiku-based conversation compaction
+//
+// Used for non-Anthropic providers (OpenAI, Gemini) that lack native
+// server-side compaction. Calls Haiku to produce a transparent summary
+// using the same instructions as compact_20260112.
+const COMPACTION_MODEL = "claude-haiku-4-5-20251001";
+const COMPACTION_MAX_TOKENS = 4096;
+const COMPACTION_TIMEOUT_MS = 30_000;
+const COMPACTION_INSTRUCTIONS = "Summarize the conversation preserving: (1) task goals and constraints, " +
+    "(2) files created/modified with paths, (3) decisions made and rationale, " +
+    "(4) errors encountered and resolutions, (5) exact next steps. " +
+    "Be concise but preserve all state needed to continue work without repeating mistakes.";
+/**
+ * Pre-compaction pass: strip redundant data before calling LLM summarizer.
+ * Mechanically removes large tool results already processed by the agent
+ * and thinking blocks from older turns. Returns modified messages array
+ * with reduced content so the LLM summarizer (or API context_management)
+ * has less to work with.
+ */
+export function preCompact(messages) {
+    let bytesRemoved = 0;
+    const compacted = messages.map((msg, idx) => {
+        if (msg.role !== "user")
+            return msg;
+        const content = msg.content;
+        if (!Array.isArray(content))
+            return msg;
+        const newContent = content.map((block) => {
+            // 1. Replace large tool results (>2KB) that the agent already acted on
+            if (block.type === "tool_result") {
+                const rc = typeof block.content === "string"
+                    ? block.content
+                    : JSON.stringify(block.content);
+                if (rc.length > 2048) {
+                    // Check if there's a subsequent assistant message (meaning agent processed this)
+                    const hasFollowup = messages
+                        .slice(idx + 1)
+                        .some((m) => m.role === "assistant");
+                    if (hasFollowup) {
+                        const originalSize = rc.length;
+                        bytesRemoved += originalSize - 100;
+                        return {
+                            ...block,
+                            content: `[Tool result: ${block.tool_use_id || "unknown"} returned ${Math.round(originalSize / 1024)}KB — agent processed and continued]`,
+                        };
+                    }
+                }
+            }
+            return block;
+        });
+        return { ...msg, content: newContent };
+    });
+    // 2. Remove thinking blocks older than 3 turns from the end
+    const thinkingCutoff = Math.max(0, compacted.length - 6); // 3 turns = ~6 messages
+    const result = compacted.map((msg, idx) => {
+        if (idx >= thinkingCutoff)
+            return msg;
+        if (msg.role !== "assistant")
+            return msg;
+        const content = msg.content;
+        if (!Array.isArray(content))
+            return msg;
+        const filtered = content.filter((block) => {
+            if (block.type === "thinking") {
+                bytesRemoved += String(block.thinking || "").length;
+                return false;
+            }
+            return true;
+        });
+        if (filtered.length === 0)
+            return msg; // Keep at least something
+        return { ...msg, content: filtered };
+    });
+    return { messages: result, bytesRemoved };
+}
+/**
+ * Generate a compaction summary using Haiku.
+ *
+ * Takes the full conversation history and produces a concise summary
+ * that preserves all state needed to continue the conversation.
+ * Falls back gracefully — returns null content on failure so the
+ * caller can keep the unsummarized history.
+ */
+export async function generateCompaction(opts) {
+    const { anthropic, messages, systemPrompt, instructions } = opts;
+    // Build a text representation of the conversation for summarization
+    const conversationText = messages
+        .map((msg) => {
+        const role = msg.role;
+        let content;
+        if (typeof msg.content === "string") {
+            content = msg.content;
+        }
+        else if (Array.isArray(msg.content)) {
+            content = msg.content
+                .map((block) => {
+                if (block.type === "text")
+                    return block.text;
+                if (block.type === "tool_use")
+                    return `[Tool: ${block.name}]`;
+                if (block.type === "tool_result") {
+                    const rc = block.content;
+                    if (typeof rc === "string")
+                        return rc.slice(0, 500);
+                    if (Array.isArray(rc)) {
+                        return rc
+                            .map((b) => (b.type === "text" ? b.text.slice(0, 500) : `[${b.type}]`))
+                            .join(" ");
+                    }
+                    return "[tool_result]";
+                }
+                if (block.type === "compaction")
+                    return `[Previous summary: ${block.content.slice(0, 200)}...]`;
+                return `[${block.type}]`;
+            })
+                .join("\n");
+        }
+        else {
+            content = String(msg.content);
+        }
+        return `${role.toUpperCase()}:\n${content}`;
+    })
+        .join("\n\n---\n\n");
+    // Truncate if conversation is very long (Haiku has 200K context)
+    const maxInputChars = 400_000; // ~100K tokens
+    const truncatedConversation = conversationText.length > maxInputChars
+        ? conversationText.slice(-maxInputChars) + "\n\n... (earlier messages truncated)"
+        : conversationText;
+    const summaryInstructions = instructions || COMPACTION_INSTRUCTIONS;
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), COMPACTION_TIMEOUT_MS);
+        try {
+            const response = await anthropic.messages.create({
+                model: COMPACTION_MODEL,
+                max_tokens: COMPACTION_MAX_TOKENS,
+                system: `You are summarizing an AI agent conversation for context compaction. ${summaryInstructions}`,
+                messages: [
+                    {
+                        role: "user",
+                        content: `Summarize this conversation. The agent's system prompt was:\n\n${systemPrompt.slice(0, 2000)}\n\n---\n\nConversation:\n\n${truncatedConversation}`,
+                    },
+                ],
+            }, { signal: controller.signal });
+            clearTimeout(timeout);
+            const textBlock = response.content.find((b) => b.type === "text");
+            if (!textBlock || textBlock.type !== "text") {
+                return { success: false, error: "No text in compaction response" };
+            }
+            return { success: true, content: textBlock.text };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: `Compaction failed: ${err.message}`,
+        };
+    }
+}

package/dist/server/lib/logger.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Structured logging with pino — Phase 6.1
+ *
+ * JSON output in production, optional pino-pretty in dev.
+ * Provides child loggers with context and correlation IDs.
+ */
+import pino from "pino";
+declare const logger: pino.Logger<never, boolean>;
+/**
+ * Create a child logger bound to a specific context (module name).
+ * Usage: const log = createLogger('agent-loop');
+ */
+export declare function createLogger(context: string): pino.Logger;
+/**
+ * Create a child logger with correlation IDs for request tracing.
+ * Usage: const log = withTrace(traceId, conversationId);
+ */
+export declare function withTrace(traceId: string, conversationId?: string): pino.Logger;
+export default logger;

package/dist/server/lib/logger.js

@@ -0,0 +1,46 @@
+/**
+ * Structured logging with pino — Phase 6.1
+ *
+ * JSON output in production, optional pino-pretty in dev.
+ * Provides child loggers with context and correlation IDs.
+ */
+import pino from "pino";
+const logger = pino({
+    level: process.env.LOG_LEVEL || "info",
+    formatters: {
+        level(label) {
+            return { level: label };
+        },
+    },
+    // Pretty print in dev if pino-pretty is installed, JSON in production
+    transport: process.env.NODE_ENV !== "production"
+        ? (() => {
+            try {
+                // pino-pretty is optional — if not installed, fall back to JSON
+                require.resolve("pino-pretty");
+                return { target: "pino-pretty", options: { colorize: true } };
+            }
+            catch {
+                return undefined;
+            }
+        })()
+        : undefined,
+});
+/**
+ * Create a child logger bound to a specific context (module name).
+ * Usage: const log = createLogger('agent-loop');
+ */
+export function createLogger(context) {
+    return logger.child({ context });
+}
+/**
+ * Create a child logger with correlation IDs for request tracing.
+ * Usage: const log = withTrace(traceId, conversationId);
+ */
+export function withTrace(traceId, conversationId) {
+    return logger.child({
+        traceId,
+        ...(conversationId ? { conversationId } : {}),
+    });
+}
+export default logger;