@thinkwell/conductor 0.2.0

package/dist/index.js

@@ -0,0 +1,76 @@
+/**
+ * @thinkwell/conductor - TypeScript conductor for ACP proxy chains
+ *
+ * The conductor orchestrates message routing between clients, proxies, and agents.
+ * It sits between every component, managing process lifecycle and message flow.
+ *
+ * ## Quick Start
+ *
+ * ```typescript
+ * import { Conductor, fromCommands, createChannelPair } from '@thinkwell/conductor';
+ *
+ * // Create a conductor that spawns an agent subprocess
+ * const conductor = new Conductor({
+ *   instantiator: fromCommands(['my-agent']),
+ * });
+ *
+ * // Connect via a channel (for testing) or stdio (for production)
+ * const [clientEnd, conductorEnd] = createChannelPair();
+ * await conductor.connect(conductorEnd);
+ * ```
+ *
+ * ## Logging
+ *
+ * Enable logging to see what the conductor is doing:
+ *
+ * ```typescript
+ * const conductor = new Conductor({
+ *   instantiator: fromCommands(['my-agent']),
+ *   logging: {
+ *     level: 'debug', // 'error' | 'warn' | 'info' | 'debug' | 'trace'
+ *     name: 'my-app',
+ *   },
+ * });
+ * ```
+ *
+ * ## JSONL Tracing
+ *
+ * Write all messages to a JSONL file for debugging:
+ *
+ * ```typescript
+ * const conductor = new Conductor({
+ *   instantiator: fromCommands(['my-agent']),
+ *   trace: {
+ *     path: '/tmp/conductor-trace.jsonl',
+ *   },
+ * });
+ * ```
+ *
+ * ## Architecture
+ *
+ * The conductor uses a central message queue to preserve ordering:
+ *
+ * ```
+ * Client ←→ Conductor ←→ [Proxy 0] ←→ [Proxy 1] ←→ ... ←→ Agent
+ * ```
+ *
+ * All messages flow through the conductor's event loop, ensuring that
+ * responses never overtake notifications.
+ *
+ * @module
+ */
+// Conductor
+export { Conductor } from "./conductor.js";
+// Logging
+export { createLogger, createNoopLogger, getLogger, setLogger, } from "./logger.js";
+// Instantiators
+export { fromCommands, fromConnectors, dynamic, staticInstantiator, } from "./instantiators.js";
+export { ROLE_COUNTERPART } from "./types.js";
+// Message queue
+export { MessageQueue } from "./message-queue.js";
+// Connectors
+export { StdioConnector, stdio, ChannelConnector, createChannelPair, inProcess, echoComponent, } from "./connectors/index.js";
+// MCP Bridge
+export { McpBridge, createHttpListener, } from "./mcp-bridge/index.js";
+export { isJsonRpcRequest, isJsonRpcNotification, isJsonRpcResponse, createRequest, createNotification, createSuccessResponse, createErrorResponse, createResponder, } from "@thinkwell/protocol";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,YAAY;AACZ,OAAO,EAAE,SAAS,EAAwB,MAAM,gBAAgB,CAAC;AAEjE,UAAU;AACV,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,SAAS,GAOV,MAAM,aAAa,CAAC;AAErB,gBAAgB;AAChB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,OAAO,EACP,kBAAkB,GAKnB,MAAM,oBAAoB,CAAC;AAc5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,gBAAgB;AAChB,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,aAAa;AACb,OAAO,EACL,cAAc,EACd,KAAK,EACL,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,aAAa,GAId,MAAM,uBAAuB,CAAC;AAE/B,aAAa;AACb,OAAO,EACL,SAAS,EACT,kBAAkB,GASnB,MAAM,uBAAuB,CAAC;AAiB/B,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,GAChB,MAAM,qBAAqB,CAAC"}

package/dist/instantiators.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Component instantiator helpers
+ *
+ * These functions create ComponentInstantiator objects that determine how
+ * components are created when the conductor receives an initialize request.
+ *
+ * ## Instantiation Modes
+ *
+ * - **Static**: Components are determined at construction time (e.g., from a list of commands)
+ * - **Dynamic**: Components are determined at runtime based on the initialize request
+ *
+ * ## Lazy Instantiation
+ *
+ * All instantiators are lazy - components are only spawned when the first
+ * `initialize` request arrives. This allows the conductor to be constructed
+ * before the component processes need to exist.
+ */
+import type { ComponentConnector, ComponentInstantiator, InitializeRequest, InstantiatedComponents } from "./types.js";
+import type { StdioConnectorOptions } from "./connectors/stdio.js";
+/**
+ * Options for a component command
+ */
+export interface CommandOptions extends StdioConnectorOptions {
+}
+/**
+ * A command specification - either a string or full options
+ */
+export type CommandSpec = string | CommandOptions;
+/**
+ * Static configuration for component instantiation
+ */
+export interface StaticInstantiatorConfig {
+    /** Proxy commands to spawn (in order) */
+    proxies?: CommandSpec[];
+    /** Agent command to spawn (required) */
+    agent: CommandSpec;
+}
+/**
+ * Create a component instantiator from static command specifications.
+ *
+ * This is the most common way to create an instantiator - provide the
+ * commands for each component and they will be spawned when needed.
+ *
+ * @example
+ * ```ts
+ * // Simple string commands
+ * const instantiator = staticInstantiator({
+ *   proxies: ['sparkle-acp'],
+ *   agent: 'claude-agent',
+ * });
+ *
+ * // With options
+ * const instantiator = staticInstantiator({
+ *   agent: {
+ *     command: 'my-agent',
+ *     args: ['--mode', 'production'],
+ *     env: { DEBUG: 'true' },
+ *   },
+ * });
+ * ```
+ */
+export declare function staticInstantiator(config: StaticInstantiatorConfig): ComponentInstantiator;
+/**
+ * Create a component instantiator from a simple list of commands.
+ *
+ * The last command is treated as the agent, all others as proxies.
+ * This is a convenience wrapper around `staticInstantiator`.
+ *
+ * @example
+ * ```ts
+ * // Single agent (no proxies)
+ * const instantiator = fromCommands(['claude-agent']);
+ *
+ * // Agent with proxies
+ * const instantiator = fromCommands(['sparkle-acp', 'claude-agent']);
+ * ```
+ */
+export declare function fromCommands(commands: CommandSpec[]): ComponentInstantiator;
+/**
+ * Create a component instantiator from explicit connectors.
+ *
+ * This is useful when you have pre-configured connectors or want to use
+ * in-memory connections for testing.
+ *
+ * @example
+ * ```ts
+ * const instantiator = fromConnectors(agentConnector, [proxyConnector]);
+ * ```
+ */
+export declare function fromConnectors(agent: ComponentConnector, proxies?: ComponentConnector[]): ComponentInstantiator;
+/**
+ * Factory function type for dynamic instantiation.
+ *
+ * The factory receives the initialize request and returns the components
+ * to instantiate. This allows for runtime decisions about what to spawn.
+ */
+export type DynamicInstantiatorFactory = (initRequest: InitializeRequest) => Promise<InstantiatedComponents>;
+/**
+ * Create a component instantiator with a dynamic factory function.
+ *
+ * The factory function is called when the first `initialize` request arrives,
+ * allowing you to make decisions about what components to spawn based on
+ * the request content.
+ *
+ * @example
+ * ```ts
+ * const instantiator = dynamic(async (initRequest) => {
+ *   // Choose agent based on client capabilities
+ *   const capabilities = initRequest.params?.capabilities ?? {};
+ *   const agentCommand = capabilities.advanced ? 'advanced-agent' : 'basic-agent';
+ *
+ *   const { StdioConnector } = await import('./connectors/stdio.js');
+ *   return {
+ *     proxies: [],
+ *     agent: new StdioConnector(agentCommand),
+ *   };
+ * });
+ *
+ * // Or use it to inspect MCP servers
+ * const instantiator = dynamic(async (initRequest) => {
+ *   const mcpServers = initRequest.params?.mcpServers ?? [];
+ *   console.log('Client provided MCP servers:', mcpServers);
+ *
+ *   // ... create appropriate components
+ * });
+ * ```
+ */
+export declare function dynamic(factory: DynamicInstantiatorFactory): ComponentInstantiator;
+//# sourceMappingURL=instantiators.d.ts.map

package/dist/instantiators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instantiators.d.ts","sourceRoot":"","sources":["../src/instantiators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACvH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,qBAAqB;CAE5D;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,cAAc,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,yCAAyC;IACzC,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;IACxB,wCAAwC;IACxC,KAAK,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,wBAAwB,GAAG,qBAAqB,CAkB1F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,qBAAqB,CAS3E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,kBAAkB,EAAO,GACjC,qBAAqB,CAMvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,GAAG,CACvC,WAAW,EAAE,iBAAiB,KAC3B,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,0BAA0B,GAAG,qBAAqB,CAIlF"}

package/dist/instantiators.js

@@ -0,0 +1,183 @@
+/**
+ * Component instantiator helpers
+ *
+ * These functions create ComponentInstantiator objects that determine how
+ * components are created when the conductor receives an initialize request.
+ *
+ * ## Instantiation Modes
+ *
+ * - **Static**: Components are determined at construction time (e.g., from a list of commands)
+ * - **Dynamic**: Components are determined at runtime based on the initialize request
+ *
+ * ## Lazy Instantiation
+ *
+ * All instantiators are lazy - components are only spawned when the first
+ * `initialize` request arrives. This allows the conductor to be constructed
+ * before the component processes need to exist.
+ */
+/**
+ * Create a component instantiator from static command specifications.
+ *
+ * This is the most common way to create an instantiator - provide the
+ * commands for each component and they will be spawned when needed.
+ *
+ * @example
+ * ```ts
+ * // Simple string commands
+ * const instantiator = staticInstantiator({
+ *   proxies: ['sparkle-acp'],
+ *   agent: 'claude-agent',
+ * });
+ *
+ * // With options
+ * const instantiator = staticInstantiator({
+ *   agent: {
+ *     command: 'my-agent',
+ *     args: ['--mode', 'production'],
+ *     env: { DEBUG: 'true' },
+ *   },
+ * });
+ * ```
+ */
+export function staticInstantiator(config) {
+    return {
+        async instantiate() {
+            // Dynamic import to avoid circular dependency
+            const { StdioConnector } = await import("./connectors/stdio.js");
+            const proxyConnectors = (config.proxies ?? []).map((spec) => new StdioConnector(normalizeCommandSpec(spec)));
+            const agentConnector = new StdioConnector(normalizeCommandSpec(config.agent));
+            return {
+                proxies: proxyConnectors,
+                agent: agentConnector,
+            };
+        },
+    };
+}
+/**
+ * Create a component instantiator from a simple list of commands.
+ *
+ * The last command is treated as the agent, all others as proxies.
+ * This is a convenience wrapper around `staticInstantiator`.
+ *
+ * @example
+ * ```ts
+ * // Single agent (no proxies)
+ * const instantiator = fromCommands(['claude-agent']);
+ *
+ * // Agent with proxies
+ * const instantiator = fromCommands(['sparkle-acp', 'claude-agent']);
+ * ```
+ */
+export function fromCommands(commands) {
+    if (commands.length === 0) {
+        throw new Error("At least one command (the agent) is required");
+    }
+    return staticInstantiator({
+        proxies: commands.slice(0, -1),
+        agent: commands[commands.length - 1],
+    });
+}
+/**
+ * Create a component instantiator from explicit connectors.
+ *
+ * This is useful when you have pre-configured connectors or want to use
+ * in-memory connections for testing.
+ *
+ * @example
+ * ```ts
+ * const instantiator = fromConnectors(agentConnector, [proxyConnector]);
+ * ```
+ */
+export function fromConnectors(agent, proxies = []) {
+    return {
+        async instantiate() {
+            return { proxies, agent };
+        },
+    };
+}
+/**
+ * Create a component instantiator with a dynamic factory function.
+ *
+ * The factory function is called when the first `initialize` request arrives,
+ * allowing you to make decisions about what components to spawn based on
+ * the request content.
+ *
+ * @example
+ * ```ts
+ * const instantiator = dynamic(async (initRequest) => {
+ *   // Choose agent based on client capabilities
+ *   const capabilities = initRequest.params?.capabilities ?? {};
+ *   const agentCommand = capabilities.advanced ? 'advanced-agent' : 'basic-agent';
+ *
+ *   const { StdioConnector } = await import('./connectors/stdio.js');
+ *   return {
+ *     proxies: [],
+ *     agent: new StdioConnector(agentCommand),
+ *   };
+ * });
+ *
+ * // Or use it to inspect MCP servers
+ * const instantiator = dynamic(async (initRequest) => {
+ *   const mcpServers = initRequest.params?.mcpServers ?? [];
+ *   console.log('Client provided MCP servers:', mcpServers);
+ *
+ *   // ... create appropriate components
+ * });
+ * ```
+ */
+export function dynamic(factory) {
+    return {
+        instantiate: factory,
+    };
+}
+/**
+ * Normalize a command specification to full options
+ */
+function normalizeCommandSpec(spec) {
+    if (typeof spec === "string") {
+        // Parse command string into command and args
+        const parts = parseCommand(spec);
+        return {
+            command: parts[0],
+            args: parts.slice(1),
+        };
+    }
+    return spec;
+}
+/**
+ * Parse a command string into command and arguments.
+ * Handles quoted strings.
+ */
+function parseCommand(command) {
+    const parts = [];
+    let current = "";
+    let inQuote = null;
+    for (let i = 0; i < command.length; i++) {
+        const char = command[i];
+        if (inQuote) {
+            if (char === inQuote) {
+                inQuote = null;
+            }
+            else {
+                current += char;
+            }
+        }
+        else if (char === '"' || char === "'") {
+            inQuote = char;
+        }
+        else if (char === " " || char === "\t") {
+            if (current) {
+                parts.push(current);
+                current = "";
+            }
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current) {
+        parts.push(current);
+    }
+    return parts;
+}
+//# sourceMappingURL=instantiators.js.map

package/dist/instantiators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instantiators.js","sourceRoot":"","sources":["../src/instantiators.ts"],"names":[],"mappings":"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"}

package/dist/logger.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Logging module for the conductor
+ *
+ * Provides structured logging with configurable levels and optional JSONL tracing.
+ * All conductor logging goes through this module to enable consistent output
+ * formatting and filtering.
+ *
+ * ## Log Levels
+ *
+ * - `error`: Errors that affect operation (component crashes, protocol violations)
+ * - `warn`: Warnings about potential issues (missing responses, malformed messages)
+ * - `info`: Key operational events (component start/stop, connections)
+ * - `debug`: Detailed debugging information (message routing, state changes)
+ * - `trace`: Very detailed tracing (every message, internal state)
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const logger = createLogger({ level: 'debug', name: 'my-conductor' });
+ * logger.info('Component started', { component: 'agent', pid: 1234 });
+ * logger.error('Failed to connect', { error: err.message });
+ * ```
+ *
+ * ## JSONL Tracing
+ *
+ * When enabled, all messages routed through the conductor are written to a
+ * JSONL file for debugging and analysis:
+ *
+ * ```typescript
+ * const logger = createLogger({
+ *   level: 'info',
+ *   trace: { path: '/tmp/conductor.jsonl' }
+ * });
+ * ```
+ */
+import type { ConductorMessage } from "./types.js";
+import type { JsonRpcMessage } from "@thinkwell/protocol";
+/**
+ * Log level enumeration (lower = more severe)
+ */
+export type LogLevel = "error" | "warn" | "info" | "debug" | "trace";
+/**
+ * Log entry structure for structured logging
+ */
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    name?: string;
+    message: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Trace entry for JSONL message tracing
+ */
+export interface TraceEntry {
+    timestamp: string;
+    direction: "left-to-right" | "right-to-left" | "internal";
+    source?: string;
+    target?: string;
+    message: ConductorMessage | JsonRpcMessage;
+}
+/**
+ * Options for JSONL tracing output
+ */
+export interface TraceOptions {
+    /** Path to the JSONL trace file */
+    path: string;
+}
+/**
+ * Logger configuration
+ */
+export interface LoggerOptions {
+    /** Minimum log level to output (default: 'info') */
+    level?: LogLevel;
+    /** Optional name prefix for log messages */
+    name?: string;
+    /** Optional JSONL trace output */
+    trace?: TraceOptions;
+    /** Use JSON output format instead of human-readable (default: false) */
+    json?: boolean;
+}
+/**
+ * Logger interface
+ */
+export interface Logger {
+    /** Log an error message */
+    error(message: string, data?: Record<string, unknown>): void;
+    /** Log a warning message */
+    warn(message: string, data?: Record<string, unknown>): void;
+    /** Log an info message */
+    info(message: string, data?: Record<string, unknown>): void;
+    /** Log a debug message */
+    debug(message: string, data?: Record<string, unknown>): void;
+    /** Log a trace message */
+    trace(message: string, data?: Record<string, unknown>): void;
+    /** Write a trace entry for message inspection */
+    traceMessage(entry: Omit<TraceEntry, "timestamp">): void;
+    /** Check if a log level is enabled */
+    isEnabled(level: LogLevel): boolean;
+    /** Create a child logger with additional context */
+    child(name: string): Logger;
+    /** Close any open resources (trace file, etc.) */
+    close(): Promise<void>;
+}
+/**
+ * Create a no-op logger that discards all output
+ */
+export declare function createNoopLogger(): Logger;
+/**
+ * Create a logger with the specified options
+ */
+export declare function createLogger(options?: LoggerOptions): Logger;
+/**
+ * Get the default logger
+ */
+export declare function getLogger(): Logger;
+/**
+ * Set the default logger
+ */
+export declare function setLogger(logger: Logger): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAUrE;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,QAAQ,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,eAAe,GAAG,eAAe,GAAG,UAAU,CAAC;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,gBAAgB,GAAG,cAAc,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,wEAAwE;IACxE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,2BAA2B;IAC3B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,4BAA4B;IAC5B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,0BAA0B;IAC1B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5D,0BAA0B;IAC1B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7D,0BAA0B;IAC1B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAE7D,iDAAiD;IACjD,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,GAAG,IAAI,CAAC;IAEzD,sCAAsC;IACtC,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC;IAEpC,oDAAoD;IACpD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAE5B,kDAAkD;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAazC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAyFhE;AAOD;;GAEG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAE9C"}

package/dist/logger.js

@@ -0,0 +1,162 @@
+/**
+ * Logging module for the conductor
+ *
+ * Provides structured logging with configurable levels and optional JSONL tracing.
+ * All conductor logging goes through this module to enable consistent output
+ * formatting and filtering.
+ *
+ * ## Log Levels
+ *
+ * - `error`: Errors that affect operation (component crashes, protocol violations)
+ * - `warn`: Warnings about potential issues (missing responses, malformed messages)
+ * - `info`: Key operational events (component start/stop, connections)
+ * - `debug`: Detailed debugging information (message routing, state changes)
+ * - `trace`: Very detailed tracing (every message, internal state)
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * const logger = createLogger({ level: 'debug', name: 'my-conductor' });
+ * logger.info('Component started', { component: 'agent', pid: 1234 });
+ * logger.error('Failed to connect', { error: err.message });
+ * ```
+ *
+ * ## JSONL Tracing
+ *
+ * When enabled, all messages routed through the conductor are written to a
+ * JSONL file for debugging and analysis:
+ *
+ * ```typescript
+ * const logger = createLogger({
+ *   level: 'info',
+ *   trace: { path: '/tmp/conductor.jsonl' }
+ * });
+ * ```
+ */
+import { createWriteStream } from "node:fs";
+const LOG_LEVELS = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    debug: 3,
+    trace: 4,
+};
+/**
+ * Create a no-op logger that discards all output
+ */
+export function createNoopLogger() {
+    const noop = () => { };
+    return {
+        error: noop,
+        warn: noop,
+        info: noop,
+        debug: noop,
+        trace: noop,
+        traceMessage: noop,
+        isEnabled: () => false,
+        child: () => createNoopLogger(),
+        close: async () => { },
+    };
+}
+/**
+ * Create a logger with the specified options
+ */
+export function createLogger(options = {}) {
+    const level = options.level ?? "info";
+    const levelNum = LOG_LEVELS[level];
+    const name = options.name;
+    const useJson = options.json ?? false;
+    // Set up trace file if configured
+    let traceStream = null;
+    if (options.trace) {
+        traceStream = createWriteStream(options.trace.path, { flags: "a" });
+    }
+    function isEnabled(checkLevel) {
+        return LOG_LEVELS[checkLevel] <= levelNum;
+    }
+    function log(logLevel, message, data) {
+        if (!isEnabled(logLevel)) {
+            return;
+        }
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level: logLevel,
+            name,
+            message,
+            data,
+        };
+        if (useJson) {
+            // Output as JSON for machine parsing
+            const output = logLevel === "error" || logLevel === "warn" ? console.error : console.log;
+            output(JSON.stringify(entry));
+        }
+        else {
+            // Human-readable format
+            const prefix = name ? `[${name}]` : "";
+            const levelStr = logLevel.toUpperCase().padEnd(5);
+            const dataStr = data ? ` ${JSON.stringify(data)}` : "";
+            const output = logLevel === "error" || logLevel === "warn" ? console.error : console.log;
+            output(`${entry.timestamp} ${levelStr} ${prefix}${prefix ? " " : ""}${message}${dataStr}`);
+        }
+    }
+    function traceMessage(entry) {
+        if (!traceStream) {
+            return;
+        }
+        const fullEntry = {
+            timestamp: new Date().toISOString(),
+            ...entry,
+        };
+        traceStream.write(JSON.stringify(fullEntry) + "\n");
+    }
+    function child(childName) {
+        const fullName = name ? `${name}:${childName}` : childName;
+        return createLogger({
+            ...options,
+            name: fullName,
+            // Share trace stream with parent
+            trace: undefined, // Don't create new stream
+        });
+    }
+    async function close() {
+        if (traceStream) {
+            await new Promise((resolve, reject) => {
+                traceStream.end((err) => {
+                    if (err)
+                        reject(err);
+                    else
+                        resolve();
+                });
+            });
+            traceStream = null;
+        }
+    }
+    return {
+        error: (message, data) => log("error", message, data),
+        warn: (message, data) => log("warn", message, data),
+        info: (message, data) => log("info", message, data),
+        debug: (message, data) => log("debug", message, data),
+        trace: (message, data) => log("trace", message, data),
+        traceMessage,
+        isEnabled,
+        child,
+        close,
+    };
+}
+/**
+ * Default logger instance (silent by default, can be replaced)
+ */
+let defaultLogger = createNoopLogger();
+/**
+ * Get the default logger
+ */
+export function getLogger() {
+    return defaultLogger;
+}
+/**
+ * Set the default logger
+ */
+export function setLogger(logger) {
+    defaultLogger = logger;
+}
+//# sourceMappingURL=logger.js.map