@a2a-wrapper/core 1.2.0

package/dist/utils/deep-merge.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Deep Merge and Environment Token Substitution Utilities
+ *
+ * This module provides two core utility functions used throughout the
+ * configuration loading pipeline:
+ *
+ * 1. `deepMerge` — Recursively merges a source object into a target object,
+ *    producing a new object without mutating either input. Used by the config
+ *    loader to layer defaults ← file ← env ← CLI overrides.
+ *
+ * 2. `substituteEnvTokens` — Replaces `$VAR_NAME` tokens in string arrays
+ *    with matching environment variable values. Used to resolve environment
+ *    references in MCP server arguments and other configuration arrays.
+ *
+ * Both functions are pure (no side effects beyond reading `process.env`) and
+ * return new data structures rather than mutating inputs.
+ *
+ * @module utils/deep-merge
+ */
+/**
+ * Recursively merge `source` into `target`, producing a new object.
+ *
+ * This function implements a deterministic, recursive merge strategy designed
+ * for layered configuration loading. The merge follows these rules:
+ *
+ * **Merge Rules:**
+ * - **Arrays are replaced** — If the source value for a key is an array, it
+ *   completely replaces the target's array (no concatenation).
+ * - **Neither input is mutated** — A new object is always returned. Both
+ *   `target` and `source` remain unchanged after the call.
+ * - **`undefined` values in source are skipped** — If a source key has the
+ *   value `undefined`, the corresponding target value is preserved.
+ * - **`null` values in source replace the target value** — An explicit `null`
+ *   in the source overwrites whatever the target had for that key.
+ * - **Nested objects are recursively merged** — When both the target and
+ *   source values for a key are plain objects (non-null, non-array), the
+ *   merge recurses into them.
+ *
+ * @typeParam T - The shape of the target object. The return type preserves
+ *   this shape so that downstream consumers retain full type information.
+ *
+ * @param target - The base object providing default values. Not mutated.
+ * @param source - The override object whose defined, non-undefined values
+ *   take precedence over `target`. Not mutated.
+ * @returns A new object containing the merged result of `target` and `source`.
+ *
+ * @example
+ * ```typescript
+ * const base = { server: { port: 3000, host: "localhost" }, tags: ["a"] };
+ * const overrides = { server: { port: 8080 }, tags: ["b", "c"] };
+ * const result = deepMerge(base, overrides);
+ * // result = { server: { port: 8080, host: "localhost" }, tags: ["b", "c"] }
+ * // base and overrides are unchanged
+ * ```
+ */
+export declare function deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T;
+/**
+ * Replace `$VAR_NAME` tokens in a string array with matching environment
+ * variable values from `process.env`.
+ *
+ * Each string in the input array is scanned for tokens matching the pattern
+ * `$WORD_CHARS` (i.e. `$` followed by one or more `[A-Za-z0-9_]` characters).
+ * When a matching environment variable exists, the token is replaced with its
+ * value. Unmatched tokens (no corresponding env var) are left unchanged.
+ *
+ * The function returns a **new array** — the input array is not mutated.
+ *
+ * @param args - Array of strings potentially containing `$VAR_NAME` tokens.
+ *   Each element is independently processed for token substitution.
+ * @returns A new array with environment variable tokens substituted where
+ *   matching values exist. Unmatched tokens remain as-is.
+ *
+ * @example
+ * ```typescript
+ * // Given: process.env.HOME = "/home/user"
+ * // Given: process.env.WORKSPACE_DIR is not set
+ *
+ * substituteEnvTokens(["--dir", "$HOME/projects", "$WORKSPACE_DIR"])
+ * // Returns: ["--dir", "/home/user/projects", "$WORKSPACE_DIR"]
+ * ```
+ */
+export declare function substituteEnvTokens(args: string[]): string[];
+//# sourceMappingURL=deep-merge.d.ts.map

package/dist/utils/deep-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-merge.d.ts","sourceRoot":"","sources":["../../src/utils/deep-merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzD,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GACjB,CAAC,CA+BH;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAI5D"}

package/dist/utils/deep-merge.js

@@ -0,0 +1,108 @@
+/**
+ * Deep Merge and Environment Token Substitution Utilities
+ *
+ * This module provides two core utility functions used throughout the
+ * configuration loading pipeline:
+ *
+ * 1. `deepMerge` — Recursively merges a source object into a target object,
+ *    producing a new object without mutating either input. Used by the config
+ *    loader to layer defaults ← file ← env ← CLI overrides.
+ *
+ * 2. `substituteEnvTokens` — Replaces `$VAR_NAME` tokens in string arrays
+ *    with matching environment variable values. Used to resolve environment
+ *    references in MCP server arguments and other configuration arrays.
+ *
+ * Both functions are pure (no side effects beyond reading `process.env`) and
+ * return new data structures rather than mutating inputs.
+ *
+ * @module utils/deep-merge
+ */
+/**
+ * Recursively merge `source` into `target`, producing a new object.
+ *
+ * This function implements a deterministic, recursive merge strategy designed
+ * for layered configuration loading. The merge follows these rules:
+ *
+ * **Merge Rules:**
+ * - **Arrays are replaced** — If the source value for a key is an array, it
+ *   completely replaces the target's array (no concatenation).
+ * - **Neither input is mutated** — A new object is always returned. Both
+ *   `target` and `source` remain unchanged after the call.
+ * - **`undefined` values in source are skipped** — If a source key has the
+ *   value `undefined`, the corresponding target value is preserved.
+ * - **`null` values in source replace the target value** — An explicit `null`
+ *   in the source overwrites whatever the target had for that key.
+ * - **Nested objects are recursively merged** — When both the target and
+ *   source values for a key are plain objects (non-null, non-array), the
+ *   merge recurses into them.
+ *
+ * @typeParam T - The shape of the target object. The return type preserves
+ *   this shape so that downstream consumers retain full type information.
+ *
+ * @param target - The base object providing default values. Not mutated.
+ * @param source - The override object whose defined, non-undefined values
+ *   take precedence over `target`. Not mutated.
+ * @returns A new object containing the merged result of `target` and `source`.
+ *
+ * @example
+ * ```typescript
+ * const base = { server: { port: 3000, host: "localhost" }, tags: ["a"] };
+ * const overrides = { server: { port: 8080 }, tags: ["b", "c"] };
+ * const result = deepMerge(base, overrides);
+ * // result = { server: { port: 8080, host: "localhost" }, tags: ["b", "c"] }
+ * // base and overrides are unchanged
+ * ```
+ */
+export function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        const srcVal = source[key];
+        // Skip undefined values — preserve the target's value
+        if (srcVal === undefined)
+            continue;
+        const tgtVal = result[key];
+        // Recursively merge when both sides are plain objects (non-null, non-array)
+        if (tgtVal !== null &&
+            srcVal !== null &&
+            typeof tgtVal === "object" &&
+            typeof srcVal === "object" &&
+            !Array.isArray(tgtVal) &&
+            !Array.isArray(srcVal)) {
+            result[key] = deepMerge(tgtVal, srcVal);
+        }
+        else {
+            // Arrays, primitives, and null — direct replacement
+            result[key] = srcVal;
+        }
+    }
+    return result;
+}
+/**
+ * Replace `$VAR_NAME` tokens in a string array with matching environment
+ * variable values from `process.env`.
+ *
+ * Each string in the input array is scanned for tokens matching the pattern
+ * `$WORD_CHARS` (i.e. `$` followed by one or more `[A-Za-z0-9_]` characters).
+ * When a matching environment variable exists, the token is replaced with its
+ * value. Unmatched tokens (no corresponding env var) are left unchanged.
+ *
+ * The function returns a **new array** — the input array is not mutated.
+ *
+ * @param args - Array of strings potentially containing `$VAR_NAME` tokens.
+ *   Each element is independently processed for token substitution.
+ * @returns A new array with environment variable tokens substituted where
+ *   matching values exist. Unmatched tokens remain as-is.
+ *
+ * @example
+ * ```typescript
+ * // Given: process.env.HOME = "/home/user"
+ * // Given: process.env.WORKSPACE_DIR is not set
+ *
+ * substituteEnvTokens(["--dir", "$HOME/projects", "$WORKSPACE_DIR"])
+ * // Returns: ["--dir", "/home/user/projects", "$WORKSPACE_DIR"]
+ * ```
+ */
+export function substituteEnvTokens(args) {
+    return args.map((arg) => arg.replace(/\$(\w+)/g, (_match, name) => process.env[name] ?? _match));
+}
+//# sourceMappingURL=deep-merge.js.map

package/dist/utils/deep-merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-merge.js","sourceRoot":"","sources":["../../src/utils/deep-merge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,SAAS,CACvB,MAAS,EACT,MAAkB;IAElB,MAAM,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;IAE7B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,MAAM,GAAI,MAAkC,CAAC,GAAG,CAAC,CAAC;QAExD,sDAAsD;QACtD,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS;QAEnC,MAAM,MAAM,GAAI,MAAkC,CAAC,GAAG,CAAC,CAAC;QAExD,4EAA4E;QAC5E,IACE,MAAM,KAAK,IAAI;YACf,MAAM,KAAK,IAAI;YACf,OAAO,MAAM,KAAK,QAAQ;YAC1B,OAAO,MAAM,KAAK,QAAQ;YAC1B,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YACtB,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EACtB,CAAC;YACA,MAAkC,CAAC,GAAG,CAAC,GAAG,SAAS,CAClD,MAAiC,EACjC,MAAiC,CAClC,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,oDAAoD;YACnD,MAAkC,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;QACpD,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAc;IAChD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CACtB,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,IAAY,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,CAC/E,CAAC;AACJ,CAAC"}

package/dist/utils/deferred.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @module utils/deferred
+ *
+ * Promise utilities for externally-controlled resolution and timed delays.
+ *
+ * This module provides two primitives used extensively across A2A wrapper
+ * projects:
+ *
+ * - {@link Deferred} / {@link createDeferred} — a promise whose `resolve` and
+ *   `reject` callbacks are exposed as properties, enabling completion from a
+ *   different code path than the one that created the promise. This pattern is
+ *   common in streaming event handlers where the completion signal arrives
+ *   asynchronously.
+ *
+ * - {@link sleep} — a simple timer-based delay that returns a promise,
+ *   useful for polling loops and retry back-off.
+ *
+ * @example
+ * ```ts
+ * import { createDeferred, sleep } from '@a2a-wrapper/core';
+ *
+ * // Deferred usage — resolve from an event handler
+ * const deferred = createDeferred<string>();
+ * eventBus.on('done', (result) => deferred.resolve(result));
+ * const value = await deferred.promise;
+ *
+ * // Sleep usage — wait 500 ms between retries
+ * await sleep(500);
+ * ```
+ */
+/**
+ * A deferred promise whose `resolve` and `reject` callbacks are accessible
+ * as properties, allowing external code to settle the promise.
+ *
+ * Created via {@link createDeferred}. The `promise` property is a standard
+ * `Promise<T>` that settles when either `resolve` or `reject` is called.
+ *
+ * @typeParam T - The type of the value the promise resolves with.
+ *
+ * @example
+ * ```ts
+ * const d: Deferred<number> = createDeferred<number>();
+ * d.resolve(42);
+ * const result = await d.promise; // 42
+ * ```
+ */
+export interface Deferred<T> {
+    /** The underlying promise that settles when {@link resolve} or {@link reject} is called. */
+    promise: Promise<T>;
+    /** Resolves the deferred promise with the given value. */
+    resolve: (value: T) => void;
+    /** Rejects the deferred promise with an optional reason. */
+    reject: (reason?: unknown) => void;
+}
+/**
+ * Creates a new {@link Deferred} instance.
+ *
+ * The returned object exposes `resolve` and `reject` callbacks alongside the
+ * `promise` they control. This is equivalent to extracting the executor
+ * arguments from `new Promise()` and storing them externally.
+ *
+ * @typeParam T - The type of the value the promise resolves with.
+ * @returns A new {@link Deferred} with an unsettled promise.
+ *
+ * @example
+ * ```ts
+ * const deferred = createDeferred<string>();
+ *
+ * // Later, in a callback or event handler:
+ * deferred.resolve('done');
+ *
+ * // The consumer awaits the promise:
+ * const result = await deferred.promise; // 'done'
+ * ```
+ */
+export declare function createDeferred<T>(): Deferred<T>;
+/**
+ * Returns a promise that resolves after the specified number of milliseconds.
+ *
+ * Useful for introducing delays in polling loops, retry back-off strategies,
+ * and test utilities. The returned promise always resolves (never rejects).
+ *
+ * @param ms - The delay duration in milliseconds. A value of `0` defers to
+ *             the next event-loop tick via `setTimeout(..., 0)`.
+ * @returns A promise that resolves with `void` after `ms` milliseconds.
+ *
+ * @example
+ * ```ts
+ * // Wait 1 second between retries
+ * for (let attempt = 0; attempt < 3; attempt++) {
+ *   try { return await fetchData(); }
+ *   catch { await sleep(1000); }
+ * }
+ * ```
+ */
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=deferred.d.ts.map

package/dist/utils/deferred.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred.d.ts","sourceRoot":"","sources":["../../src/utils/deferred.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,4FAA4F;IAC5F,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAEpB,0DAA0D;IAC1D,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAE5B,4DAA4D;IAC5D,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,cAAc,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAQ/C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/utils/deferred.js

@@ -0,0 +1,83 @@
+/**
+ * @module utils/deferred
+ *
+ * Promise utilities for externally-controlled resolution and timed delays.
+ *
+ * This module provides two primitives used extensively across A2A wrapper
+ * projects:
+ *
+ * - {@link Deferred} / {@link createDeferred} — a promise whose `resolve` and
+ *   `reject` callbacks are exposed as properties, enabling completion from a
+ *   different code path than the one that created the promise. This pattern is
+ *   common in streaming event handlers where the completion signal arrives
+ *   asynchronously.
+ *
+ * - {@link sleep} — a simple timer-based delay that returns a promise,
+ *   useful for polling loops and retry back-off.
+ *
+ * @example
+ * ```ts
+ * import { createDeferred, sleep } from '@a2a-wrapper/core';
+ *
+ * // Deferred usage — resolve from an event handler
+ * const deferred = createDeferred<string>();
+ * eventBus.on('done', (result) => deferred.resolve(result));
+ * const value = await deferred.promise;
+ *
+ * // Sleep usage — wait 500 ms between retries
+ * await sleep(500);
+ * ```
+ */
+/**
+ * Creates a new {@link Deferred} instance.
+ *
+ * The returned object exposes `resolve` and `reject` callbacks alongside the
+ * `promise` they control. This is equivalent to extracting the executor
+ * arguments from `new Promise()` and storing them externally.
+ *
+ * @typeParam T - The type of the value the promise resolves with.
+ * @returns A new {@link Deferred} with an unsettled promise.
+ *
+ * @example
+ * ```ts
+ * const deferred = createDeferred<string>();
+ *
+ * // Later, in a callback or event handler:
+ * deferred.resolve('done');
+ *
+ * // The consumer awaits the promise:
+ * const result = await deferred.promise; // 'done'
+ * ```
+ */
+export function createDeferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    return { promise, resolve, reject };
+}
+/**
+ * Returns a promise that resolves after the specified number of milliseconds.
+ *
+ * Useful for introducing delays in polling loops, retry back-off strategies,
+ * and test utilities. The returned promise always resolves (never rejects).
+ *
+ * @param ms - The delay duration in milliseconds. A value of `0` defers to
+ *             the next event-loop tick via `setTimeout(..., 0)`.
+ * @returns A promise that resolves with `void` after `ms` milliseconds.
+ *
+ * @example
+ * ```ts
+ * // Wait 1 second between retries
+ * for (let attempt = 0; attempt < 3; attempt++) {
+ *   try { return await fetchData(); }
+ *   catch { await sleep(1000); }
+ * }
+ * ```
+ */
+export function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=deferred.js.map

package/dist/utils/deferred.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred.js","sourceRoot":"","sources":["../../src/utils/deferred.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AA6BH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,cAAc;IAC5B,IAAI,OAA4B,CAAC;IACjC,IAAI,MAAmC,CAAC;IACxC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAC1C,OAAO,GAAG,GAAG,CAAC;QACd,MAAM,GAAG,GAAG,CAAC;IACf,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAC/C,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,186 @@
+/**
+ * @module utils/logger
+ *
+ * Structured, leveled logging with child-logger support and configurable root names.
+ *
+ * This module provides the logging infrastructure for all A2A wrapper projects.
+ * Each wrapper creates its own root logger via {@link createLogger}, avoiding
+ * hardcoded singletons and enabling independent log hierarchies per project.
+ *
+ * Output format: `[ISO_timestamp] [LEVEL] [name] message {data}`
+ *
+ * - ERROR messages route to `console.error`
+ * - WARN messages route to `console.warn`
+ * - DEBUG and INFO messages route to `console.log`
+ *
+ * @example
+ * ```ts
+ * import { createLogger, LogLevel } from '@a2a-wrapper/core';
+ *
+ * const logger = createLogger('a2a-copilot');
+ * logger.setLevel(LogLevel.DEBUG);
+ *
+ * const child = logger.child('session');
+ * child.info('session started', { contextId: 'abc-123' });
+ * // => [2024-01-15T10:30:00.000Z] [INFO] [a2a-copilot:session] session started {"contextId":"abc-123"}
+ * ```
+ */
+/**
+ * Numeric log levels controlling message suppression.
+ *
+ * Messages are emitted only when their level is greater than or equal to the
+ * logger's configured minimum level. Lower numeric values represent more
+ * verbose output.
+ */
+export declare enum LogLevel {
+    /** Verbose diagnostic output, typically disabled in production. */
+    DEBUG = 0,
+    /** General operational messages indicating normal behavior. */
+    INFO = 1,
+    /** Potentially harmful situations that deserve attention. */
+    WARN = 2,
+    /** Failures requiring immediate investigation. */
+    ERROR = 3
+}
+/**
+ * Structured logger with hierarchical naming and runtime level control.
+ *
+ * Each Logger instance has a `name` (used as a prefix in output) and a minimum
+ * {@link LogLevel}. Child loggers inherit the parent's level at creation time
+ * and format their name as `{parent}:{child}`.
+ *
+ * @example
+ * ```ts
+ * const root = new Logger('myApp', LogLevel.DEBUG);
+ * const child = root.child('http');
+ * child.info('request received', { method: 'GET', path: '/' });
+ * ```
+ */
+export declare class Logger {
+    /**
+     * Dot-colon-separated name identifying this logger in output.
+     *
+     * @readonly
+     */
+    private readonly name;
+    /**
+     * Current minimum log level. Messages below this level are suppressed.
+     */
+    private level;
+    /**
+     * Creates a new Logger instance.
+     *
+     * @param name  - Identifier included in every log line (e.g. `"a2a-copilot"` or `"a2a-copilot:session"`).
+     * @param level - Minimum log level; defaults to {@link LogLevel.INFO}.
+     */
+    constructor(name: string, level?: LogLevel);
+    /**
+     * Changes the minimum log level at runtime.
+     *
+     * All subsequent calls to {@link debug}, {@link info}, {@link warn}, and
+     * {@link error} will be filtered against the new level.
+     *
+     * @param level - The new minimum {@link LogLevel}.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Parses a string into a {@link LogLevel}.
+     *
+     * Matching is case-insensitive. The string `"warning"` is accepted as an
+     * alias for {@link LogLevel.WARN}. Unrecognized strings default to
+     * {@link LogLevel.INFO}.
+     *
+     * @param str - The string to parse (e.g. `"debug"`, `"WARN"`, `"error"`).
+     * @returns The corresponding {@link LogLevel} value.
+     */
+    static parseLevel(str: string): LogLevel;
+    /**
+     * Creates a child logger that inherits this logger's current level.
+     *
+     * The child's name is formatted as `{parentName}:{childName}`, producing
+     * a colon-separated hierarchy visible in log output.
+     *
+     * @param childName - Short identifier appended to the parent name.
+     * @returns A new {@link Logger} instance with the composite name.
+     *
+     * @example
+     * ```ts
+     * const root = createLogger('app');
+     * const child = root.child('db');
+     * const grandchild = child.child('query');
+     * // grandchild.name === 'app:db:query'
+     * ```
+     */
+    child(childName: string): Logger;
+    /**
+     * Logs a message at {@link LogLevel.DEBUG}.
+     *
+     * @param msg  - Human-readable log message.
+     * @param data - Optional structured data appended as JSON.
+     */
+    debug(msg: string, data?: Record<string, unknown>): void;
+    /**
+     * Logs a message at {@link LogLevel.INFO}.
+     *
+     * @param msg  - Human-readable log message.
+     * @param data - Optional structured data appended as JSON.
+     */
+    info(msg: string, data?: Record<string, unknown>): void;
+    /**
+     * Logs a message at {@link LogLevel.WARN}.
+     *
+     * @param msg  - Human-readable log message.
+     * @param data - Optional structured data appended as JSON.
+     */
+    warn(msg: string, data?: Record<string, unknown>): void;
+    /**
+     * Logs a message at {@link LogLevel.ERROR}.
+     *
+     * @param msg  - Human-readable log message.
+     * @param data - Optional structured data appended as JSON.
+     */
+    error(msg: string, data?: Record<string, unknown>): void;
+    /**
+     * Internal method that formats and emits a log line if the message level
+     * meets or exceeds the configured minimum.
+     *
+     * Output format: `[ISO_timestamp] [LEVEL] [name] message {data}`
+     *
+     * Routing:
+     * - {@link LogLevel.ERROR} → `console.error`
+     * - {@link LogLevel.WARN} → `console.warn`
+     * - All others → `console.log`
+     *
+     * @param level - The severity level of this message.
+     * @param msg   - Human-readable log message.
+     * @param data  - Optional structured data serialized as JSON.
+     *
+     * @internal
+     */
+    private write;
+}
+/**
+ * Creates a new root {@link Logger} instance with the given name.
+ *
+ * This is the recommended entry point for obtaining a logger. Each wrapper
+ * project should call this once with its own root name, then use
+ * {@link Logger.child} to create scoped loggers for subsystems.
+ *
+ * Unlike a singleton, this factory allows multiple independent logger
+ * hierarchies to coexist — one per wrapper project or test suite.
+ *
+ * @param rootName - The root identifier for the logger hierarchy
+ *                   (e.g. `"a2a-copilot"`, `"a2a-opencode"`).
+ * @returns A new {@link Logger} instance with the default level {@link LogLevel.INFO}.
+ *
+ * @example
+ * ```ts
+ * import { createLogger } from '@a2a-wrapper/core';
+ *
+ * const logger = createLogger('a2a-copilot');
+ * const sessionLog = logger.child('session');
+ * sessionLog.info('ready');
+ * ```
+ */
+export declare function createLogger(rootName: string): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH;;;;;;GAMG;AACH,oBAAY,QAAQ;IAClB,mEAAmE;IACnE,KAAK,IAAI;IACT,+DAA+D;IAC/D,IAAI,IAAI;IACR,6DAA6D;IAC7D,IAAI,IAAI;IACR,kDAAkD;IAClD,KAAK,IAAI;CACV;AAcD;;;;;;;;;;;;;GAaG;AACH,qBAAa,MAAM;IACjB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAE9B;;OAEG;IACH,OAAO,CAAC,KAAK,CAAW;IAExB;;;;;OAKG;gBACS,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,QAAwB;IAKzD;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B;;;;;;;;;OASG;IACH,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ;IAcxC;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAIhC;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIxD;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIvD;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIvD;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIxD;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,KAAK;CAqBd;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErD"}