logquill 0.3.0 → 1.0.0

package/dist/logger-CRdmCDfC.d.cts

@@ -0,0 +1,299 @@
+/** Log levels, shared by name and numeric weight with the logquill-python contract. */
+declare enum Level {
+    /** Finest-grained diagnostic detail. */
+    TRACE = 5,
+    /** Diagnostic detail useful in development. */
+    DEBUG = 10,
+    /** Notable events during normal operation. */
+    INFO = 20,
+    /** Something unexpected, but not (yet) an error. */
+    WARN = 30,
+    /** An error that didn't necessarily stop the operation. */
+    ERROR = 40,
+    /** An error that precedes an unrecoverable failure. */
+    FATAL = 50
+}
+/** A level given as a `Level`, a level name (any case), or its numeric weight. */
+type LevelInput = Level | number | string;
+/** The level's name, e.g. `levelName(Level.INFO) === "INFO"`. */
+declare function levelName(level: Level): string;
+/** Normalize a level given as a `Level`, level name, or numeric weight. Throws if unknown. */
+declare function parseLevel(level: LevelInput): Level;
+
+/** The cross-language record shape shared with logquill-python. */
+interface LogRecord {
+    /** ISO8601 UTC timestamp with millisecond precision. */
+    timestamp: string;
+    /** Level name, e.g. `"INFO"`. */
+    level: string;
+    /** Name of the `Logger` that created this record. */
+    logger: string;
+    /** The log message. */
+    message: string;
+    /** Structured payload — always present, even if empty. */
+    meta: Record<string, unknown>;
+}
+/** ISO8601 UTC timestamp with millisecond precision, matching Python's `utc_timestamp()`. */
+declare function utcTimestamp(): string;
+/** Builds a `LogRecord` with the current UTC timestamp. Used internally by `Logger`; exported for transports/plugins that need to construct a record directly. */
+declare function createRecord(params: {
+    level: Level;
+    logger: string;
+    message: string;
+    meta: Record<string, unknown>;
+}): LogRecord;
+
+/** `format(record) -> string`, per the transport contract shared with logquill-python. */
+interface Formatter {
+    /** Turns a `LogRecord` into the string a `Transport` writes. */
+    format(record: LogRecord): string;
+}
+/** Serializes a record to the canonical JSON line shape. */
+declare class JSONFormatter implements Formatter {
+    /** Returns `JSON.stringify(record)`. */
+    format(record: LogRecord): string;
+}
+
+/**
+ * The plugin pipeline hooks, matching the Python hook names: `beforeLog`,
+ * `afterLog`, `onError`. All hooks are optional — implement only what you need.
+ * A hook that throws cannot crash logging: the pipeline catches it, routes it
+ * to `onError`, and moves on.
+ */
+interface Plugin {
+    /** Return a (possibly modified) record, or `null` to drop it. */
+    beforeLog?(record: LogRecord): LogRecord | null;
+    /** Called after the record has been dispatched to every transport. */
+    afterLog?(record: LogRecord): void;
+    /** Called when one of this plugin's own hooks throws. */
+    onError?(error: unknown, record: LogRecord): void;
+}
+/** A plain `beforeLog`-style function, as accepted by `Logger.use()` in place of a `Plugin`. */
+type MiddlewareFunc = (record: LogRecord) => LogRecord | null;
+/**
+ * Wraps a plain `beforeLog`-style function as a `Plugin`. `Logger.use()`
+ * builds one of these automatically when given a function instead of a
+ * `Plugin` — Express/Koa-style middleware ergonomics, without needing to
+ * read the `Plugin` interface first. There's no `next()` chaining: the
+ * pipeline already calls hooks in sequence, so this is sugar for a
+ * single-method `Plugin`, not a new execution model.
+ */
+declare class FunctionPlugin implements Plugin {
+    private readonly func;
+    constructor(func: MiddlewareFunc);
+    beforeLog(record: LogRecord): LogRecord | null;
+}
+
+/** How a full queue behaves when another task arrives. */
+type BackpressurePolicy = "dropOldest" | "dropNewest" | "block";
+/** Options for the {@link DispatchQueue} constructor. */
+interface DispatchQueueOptions {
+    /** Maximum number of pending tasks the queue holds at once. Default 10_000. */
+    maxSize?: number;
+    /**
+     * What happens when `enqueue()` is called while the queue is already at
+     * `maxSize`:
+     * - `"dropOldest"` (default) — evict the longest-waiting task (it never
+     *   runs) and enqueue the new one. Favors recent records.
+     * - `"dropNewest"` — discard the incoming task; everything already queued
+     *   is left alone. Favors records already in flight.
+     * - `"block"` — run the task synchronously, right now, on the caller's
+     *   stack instead of queueing it. Nothing is ever dropped, at the cost of
+     *   the caller (e.g. `logger.info()`) taking as long as the write itself —
+     *   real backpressure rather than a silent drop.
+     */
+    policy?: BackpressurePolicy;
+    /**
+     * Called at most once per `warnIntervalMs` (default 5000) when the queue
+     * drops tasks, with the number dropped since the last call — a
+     * rate-limited way to surface sustained overload without flooding the
+     * caller's own logs with one warning per drop. Defaults to `console.warn`.
+     */
+    onDrop?: (droppedSinceLastWarning: number, policy: BackpressurePolicy) => void;
+    /** Minimum gap between `onDrop` calls. Default 5000ms. */
+    warnIntervalMs?: number;
+}
+/** A unit of deferred work queued via `DispatchQueue.enqueue()`. */
+type Task = () => void | Promise<void>;
+/**
+ * A bounded, in-order queue of pending write tasks, drained outside the
+ * caller's own call stack (`setImmediate`/microtask) so `Logger` methods can
+ * return before the I/O they triggered actually runs. Backed by an explicit
+ * size cap and backpressure policy — see `DispatchQueueOptions` — so a
+ * sustained burst can never grow memory unboundedly.
+ */
+declare class DispatchQueue {
+    /** Maximum number of pending tasks held at once, as configured via `DispatchQueueOptions`. */
+    readonly maxSize: number;
+    /** Backpressure policy applied once `maxSize` is reached, as configured via `DispatchQueueOptions`. */
+    readonly policy: BackpressurePolicy;
+    private readonly onDrop;
+    private readonly warnIntervalMs;
+    private readonly tasks;
+    private draining;
+    private scheduled;
+    private idleWaiters;
+    private droppedSinceWarning;
+    private lastWarnAt;
+    constructor(options?: DispatchQueueOptions);
+    /** Number of tasks currently waiting to run. Bounded by `maxSize`. */
+    get size(): number;
+    /**
+     * Queue `task` to run outside the current call stack, applying the
+     * configured backpressure policy if the queue is already full. Under
+     * `"block"`, `task` may run synchronously before this call returns.
+     */
+    enqueue(task: Task): void;
+    /** Resolves once every task queued so far has run. Safe to call when idle. */
+    flush(): Promise<void>;
+    private recordDrop;
+    private runInline;
+    private schedule;
+    private drainAll;
+}
+
+/**
+ * Sink for log records, per the cross-language transport contract:
+ * `format(record) -> string`, `write(formatted, record)`, `close()` on shutdown.
+ */
+declare abstract class Transport {
+    /** Turns a `LogRecord` into the string this transport actually writes. Defaults to `JSONFormatter`. */
+    formatter: Formatter;
+    constructor(formatter?: Formatter);
+    /** Formats `record` via `this.formatter`. Called once per record before `write()`. */
+    format(record: LogRecord): string;
+    /** Sends the already-formatted record to this transport's sink. */
+    abstract write(formatted: string, record: LogRecord): void;
+    /** Flush/release resources on shutdown. No-op unless a transport overrides it. */
+    close(): void;
+}
+/** Duck-typed: a transport (typically a `BatchingTransport`) whose `flush()` sends its current buffer now, without closing. */
+interface FlushableTransport {
+    /** Sends the current buffer now, even if it hasn't reached its own flush threshold. */
+    flush(): void | Promise<void>;
+}
+/** Type guard for {@link FlushableTransport} — true for any transport (e.g. every `BatchingTransport`) that exposes a `flush()` method. */
+declare function hasFlush(transport: Transport): transport is Transport & FlushableTransport;
+/** In-memory transport for tests: collects every (formatted, record) pair written to it. */
+declare class CollectingTransport extends Transport {
+    /** Every formatted string passed to `write()`, in call order. */
+    readonly formatted: string[];
+    /** Every raw `LogRecord` passed to `write()`, in call order. */
+    readonly records: LogRecord[];
+    /** Set once `close()` has been called. */
+    closed: boolean;
+    write(formatted: string, record: LogRecord): void;
+    close(): void;
+}
+
+/** Options for `Logger.span()`. Any extra keys become the span's own `meta`. */
+interface SpanOptions extends Record<string, unknown> {
+    /** Adopt an id handed in from elsewhere (e.g. a framework's own run id) instead of generating one. */
+    spanId?: string;
+    /** Adopt a parent id explicitly, overriding auto-nesting from an enclosing `span()` block. */
+    parentSpanId?: string;
+}
+/** Options for the {@link Logger} constructor. */
+interface LoggerOptions {
+    /** Minimum level that reaches a transport; records below it are dropped before any plugin runs. Default `INFO`. */
+    level?: LevelInput;
+    /** Sinks every record that passes the level filter and plugin pipeline is written to. */
+    transports?: Transport[];
+    /** Registered via `.use()` in order — a plain function is wrapped as an anonymous `Plugin`. */
+    plugins?: (Plugin | MiddlewareFunc)[];
+    /** Merged into every record's `meta`, before a call-site `meta` value (which always wins on collision). */
+    meta?: Record<string, unknown>;
+    /** Bounds and backpressure policy for the internal async dispatch queue. See `DispatchQueueOptions`. */
+    queue?: DispatchQueueOptions;
+}
+/**
+ * The core logger: leveled, structured logging over a pluggable transport
+ * and plugin pipeline. Every log call returns the finished `LogRecord` (or
+ * `null` if it was filtered by level or dropped by a plugin) synchronously —
+ * the actual transport writes are dispatched onto an internal queue so the
+ * call returns before any I/O runs; see `flush()`/`close()`.
+ */
+declare class Logger {
+    /** This logger's name, as passed to the constructor (or derived via `.child()`). Appears on every record as `logger`. */
+    readonly name: string;
+    /** Every transport a written record is sent to. */
+    readonly transports: Transport[];
+    /** Every plugin registered via `.use()`, in registration order. */
+    readonly plugins: Plugin[];
+    private currentLevel;
+    private readonly baseMeta;
+    private dispatchQueue;
+    constructor(name: string, options?: LoggerOptions);
+    /** This logger's current minimum level — records below it are filtered before any plugin runs. */
+    get level(): Level;
+    /** Changes the minimum level records must meet to reach a transport. Accepts a `Level`, its numeric weight, or its name. */
+    setLevel(level: LevelInput): void;
+    /**
+     * Register a plugin, or a plain `beforeLog`-style function. A function is
+     * wrapped internally as an anonymous `Plugin` (`FunctionPlugin`) — the
+     * same middleware ergonomics as Express/Koa, without needing to read the
+     * `Plugin` interface first. Returns `this` so calls can be chained.
+     */
+    use(plugin: Plugin | MiddlewareFunc): this;
+    /** Number of dispatched records not yet written to their transports. Bounded by the `queue` option. */
+    get queueSize(): number;
+    /**
+     * Waits for every record dispatched so far to reach its transports'
+     * `write()` (and any plugin `afterLog` hooks). Note this does *not* force
+     * a batching transport (SQL, a queue, `HTTPTransport`, ...) to send a
+     * batch still under its own `maxRecords`/`maxBytes` threshold early — it
+     * only guarantees the record has been handed to that transport, the same
+     * contract `write()` always had. Before a process may pause or exit
+     * (a serverless freeze, a shutdown signal), prefer `withLambda`/
+     * `installShutdownHandlers`, which additionally force every batching
+     * transport to send its current buffer regardless of threshold.
+     */
+    flush(): Promise<void>;
+    /** Flush every pending record, then close every attached transport. Call once, on shutdown. */
+    close(): Promise<void>;
+    /** A logger scoped under this one, inheriting its level, transports, plugins, and dispatch queue. */
+    child(name: string, meta?: Record<string, unknown>): Logger;
+    private notifyError;
+    private dispatch;
+    private writeAndNotify;
+    /** Logs at `TRACE` — the lowest level, for fine-grained diagnostic detail. Returns the record, or `null` if filtered/dropped. */
+    trace(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `DEBUG`. Returns the record, or `null` if filtered/dropped. */
+    debug(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `INFO`. Returns the record, or `null` if filtered/dropped. */
+    info(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `WARN`. Returns the record, or `null` if filtered/dropped. */
+    warn(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `ERROR`. Returns the record, or `null` if filtered/dropped. */
+    error(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `FATAL` — the highest level, for errors that precede an unrecoverable failure. Returns the record, or `null` if filtered/dropped. */
+    fatal(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "thought"` — an agent's internal reasoning step, for harness/agentic tracing. */
+    thought(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "action"` — an agent taking an action (a tool call, an LLM request), for harness/agentic tracing. */
+    action(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "observation"` — the result an agent observed from an action, for harness/agentic tracing. */
+    observation(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "decision"` — an agent's concluding decision for a step or run, for harness/agentic tracing. */
+    decision(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /**
+     * `await logger.span("callLlm", async () => {...})` — runs `fn`, and on
+     * settling (success or throw) emits one record for the span itself
+     * carrying `meta.spanId` and `meta.durationMs`. Every record logged
+     * inside `fn` — through any method, and through any further `await` —
+     * is automatically stamped with `meta.parentSpanId` pointing at this
+     * span, so nested/sub-agent calls reconstruct their exact nesting when
+     * sorted by `spanId`/`parentSpanId`.
+     *
+     * Still emits its record — at `ERROR`, with `meta.error` set — if `fn`
+     * throws; the error itself propagates unchanged to the caller.
+     *
+     * `spanId`/`parentSpanId` normally auto-generate/auto-nest; pass them in
+     * `options` to adopt an id handed in from elsewhere (e.g. a framework
+     * adapter translating an id it already received).
+     */
+    span<T>(name: string, fn: () => T | Promise<T>, options?: SpanOptions): Promise<T>;
+    private finishSpan;
+}
+
+export { type BackpressurePolicy as B, CollectingTransport as C, DispatchQueue as D, type Formatter as F, JSONFormatter as J, type LogRecord as L, type MiddlewareFunc as M, type Plugin as P, type SpanOptions as S, Transport as T, Level as a, Logger as b, type LevelInput as c, type DispatchQueueOptions as d, type FlushableTransport as e, FunctionPlugin as f, type LoggerOptions as g, type Task as h, createRecord as i, hasFlush as j, levelName as l, parseLevel as p, utcTimestamp as u };

package/dist/logger-CRdmCDfC.d.ts

@@ -0,0 +1,299 @@
+/** Log levels, shared by name and numeric weight with the logquill-python contract. */
+declare enum Level {
+    /** Finest-grained diagnostic detail. */
+    TRACE = 5,
+    /** Diagnostic detail useful in development. */
+    DEBUG = 10,
+    /** Notable events during normal operation. */
+    INFO = 20,
+    /** Something unexpected, but not (yet) an error. */
+    WARN = 30,
+    /** An error that didn't necessarily stop the operation. */
+    ERROR = 40,
+    /** An error that precedes an unrecoverable failure. */
+    FATAL = 50
+}
+/** A level given as a `Level`, a level name (any case), or its numeric weight. */
+type LevelInput = Level | number | string;
+/** The level's name, e.g. `levelName(Level.INFO) === "INFO"`. */
+declare function levelName(level: Level): string;
+/** Normalize a level given as a `Level`, level name, or numeric weight. Throws if unknown. */
+declare function parseLevel(level: LevelInput): Level;
+
+/** The cross-language record shape shared with logquill-python. */
+interface LogRecord {
+    /** ISO8601 UTC timestamp with millisecond precision. */
+    timestamp: string;
+    /** Level name, e.g. `"INFO"`. */
+    level: string;
+    /** Name of the `Logger` that created this record. */
+    logger: string;
+    /** The log message. */
+    message: string;
+    /** Structured payload — always present, even if empty. */
+    meta: Record<string, unknown>;
+}
+/** ISO8601 UTC timestamp with millisecond precision, matching Python's `utc_timestamp()`. */
+declare function utcTimestamp(): string;
+/** Builds a `LogRecord` with the current UTC timestamp. Used internally by `Logger`; exported for transports/plugins that need to construct a record directly. */
+declare function createRecord(params: {
+    level: Level;
+    logger: string;
+    message: string;
+    meta: Record<string, unknown>;
+}): LogRecord;
+
+/** `format(record) -> string`, per the transport contract shared with logquill-python. */
+interface Formatter {
+    /** Turns a `LogRecord` into the string a `Transport` writes. */
+    format(record: LogRecord): string;
+}
+/** Serializes a record to the canonical JSON line shape. */
+declare class JSONFormatter implements Formatter {
+    /** Returns `JSON.stringify(record)`. */
+    format(record: LogRecord): string;
+}
+
+/**
+ * The plugin pipeline hooks, matching the Python hook names: `beforeLog`,
+ * `afterLog`, `onError`. All hooks are optional — implement only what you need.
+ * A hook that throws cannot crash logging: the pipeline catches it, routes it
+ * to `onError`, and moves on.
+ */
+interface Plugin {
+    /** Return a (possibly modified) record, or `null` to drop it. */
+    beforeLog?(record: LogRecord): LogRecord | null;
+    /** Called after the record has been dispatched to every transport. */
+    afterLog?(record: LogRecord): void;
+    /** Called when one of this plugin's own hooks throws. */
+    onError?(error: unknown, record: LogRecord): void;
+}
+/** A plain `beforeLog`-style function, as accepted by `Logger.use()` in place of a `Plugin`. */
+type MiddlewareFunc = (record: LogRecord) => LogRecord | null;
+/**
+ * Wraps a plain `beforeLog`-style function as a `Plugin`. `Logger.use()`
+ * builds one of these automatically when given a function instead of a
+ * `Plugin` — Express/Koa-style middleware ergonomics, without needing to
+ * read the `Plugin` interface first. There's no `next()` chaining: the
+ * pipeline already calls hooks in sequence, so this is sugar for a
+ * single-method `Plugin`, not a new execution model.
+ */
+declare class FunctionPlugin implements Plugin {
+    private readonly func;
+    constructor(func: MiddlewareFunc);
+    beforeLog(record: LogRecord): LogRecord | null;
+}
+
+/** How a full queue behaves when another task arrives. */
+type BackpressurePolicy = "dropOldest" | "dropNewest" | "block";
+/** Options for the {@link DispatchQueue} constructor. */
+interface DispatchQueueOptions {
+    /** Maximum number of pending tasks the queue holds at once. Default 10_000. */
+    maxSize?: number;
+    /**
+     * What happens when `enqueue()` is called while the queue is already at
+     * `maxSize`:
+     * - `"dropOldest"` (default) — evict the longest-waiting task (it never
+     *   runs) and enqueue the new one. Favors recent records.
+     * - `"dropNewest"` — discard the incoming task; everything already queued
+     *   is left alone. Favors records already in flight.
+     * - `"block"` — run the task synchronously, right now, on the caller's
+     *   stack instead of queueing it. Nothing is ever dropped, at the cost of
+     *   the caller (e.g. `logger.info()`) taking as long as the write itself —
+     *   real backpressure rather than a silent drop.
+     */
+    policy?: BackpressurePolicy;
+    /**
+     * Called at most once per `warnIntervalMs` (default 5000) when the queue
+     * drops tasks, with the number dropped since the last call — a
+     * rate-limited way to surface sustained overload without flooding the
+     * caller's own logs with one warning per drop. Defaults to `console.warn`.
+     */
+    onDrop?: (droppedSinceLastWarning: number, policy: BackpressurePolicy) => void;
+    /** Minimum gap between `onDrop` calls. Default 5000ms. */
+    warnIntervalMs?: number;
+}
+/** A unit of deferred work queued via `DispatchQueue.enqueue()`. */
+type Task = () => void | Promise<void>;
+/**
+ * A bounded, in-order queue of pending write tasks, drained outside the
+ * caller's own call stack (`setImmediate`/microtask) so `Logger` methods can
+ * return before the I/O they triggered actually runs. Backed by an explicit
+ * size cap and backpressure policy — see `DispatchQueueOptions` — so a
+ * sustained burst can never grow memory unboundedly.
+ */
+declare class DispatchQueue {
+    /** Maximum number of pending tasks held at once, as configured via `DispatchQueueOptions`. */
+    readonly maxSize: number;
+    /** Backpressure policy applied once `maxSize` is reached, as configured via `DispatchQueueOptions`. */
+    readonly policy: BackpressurePolicy;
+    private readonly onDrop;
+    private readonly warnIntervalMs;
+    private readonly tasks;
+    private draining;
+    private scheduled;
+    private idleWaiters;
+    private droppedSinceWarning;
+    private lastWarnAt;
+    constructor(options?: DispatchQueueOptions);
+    /** Number of tasks currently waiting to run. Bounded by `maxSize`. */
+    get size(): number;
+    /**
+     * Queue `task` to run outside the current call stack, applying the
+     * configured backpressure policy if the queue is already full. Under
+     * `"block"`, `task` may run synchronously before this call returns.
+     */
+    enqueue(task: Task): void;
+    /** Resolves once every task queued so far has run. Safe to call when idle. */
+    flush(): Promise<void>;
+    private recordDrop;
+    private runInline;
+    private schedule;
+    private drainAll;
+}
+
+/**
+ * Sink for log records, per the cross-language transport contract:
+ * `format(record) -> string`, `write(formatted, record)`, `close()` on shutdown.
+ */
+declare abstract class Transport {
+    /** Turns a `LogRecord` into the string this transport actually writes. Defaults to `JSONFormatter`. */
+    formatter: Formatter;
+    constructor(formatter?: Formatter);
+    /** Formats `record` via `this.formatter`. Called once per record before `write()`. */
+    format(record: LogRecord): string;
+    /** Sends the already-formatted record to this transport's sink. */
+    abstract write(formatted: string, record: LogRecord): void;
+    /** Flush/release resources on shutdown. No-op unless a transport overrides it. */
+    close(): void;
+}
+/** Duck-typed: a transport (typically a `BatchingTransport`) whose `flush()` sends its current buffer now, without closing. */
+interface FlushableTransport {
+    /** Sends the current buffer now, even if it hasn't reached its own flush threshold. */
+    flush(): void | Promise<void>;
+}
+/** Type guard for {@link FlushableTransport} — true for any transport (e.g. every `BatchingTransport`) that exposes a `flush()` method. */
+declare function hasFlush(transport: Transport): transport is Transport & FlushableTransport;
+/** In-memory transport for tests: collects every (formatted, record) pair written to it. */
+declare class CollectingTransport extends Transport {
+    /** Every formatted string passed to `write()`, in call order. */
+    readonly formatted: string[];
+    /** Every raw `LogRecord` passed to `write()`, in call order. */
+    readonly records: LogRecord[];
+    /** Set once `close()` has been called. */
+    closed: boolean;
+    write(formatted: string, record: LogRecord): void;
+    close(): void;
+}
+
+/** Options for `Logger.span()`. Any extra keys become the span's own `meta`. */
+interface SpanOptions extends Record<string, unknown> {
+    /** Adopt an id handed in from elsewhere (e.g. a framework's own run id) instead of generating one. */
+    spanId?: string;
+    /** Adopt a parent id explicitly, overriding auto-nesting from an enclosing `span()` block. */
+    parentSpanId?: string;
+}
+/** Options for the {@link Logger} constructor. */
+interface LoggerOptions {
+    /** Minimum level that reaches a transport; records below it are dropped before any plugin runs. Default `INFO`. */
+    level?: LevelInput;
+    /** Sinks every record that passes the level filter and plugin pipeline is written to. */
+    transports?: Transport[];
+    /** Registered via `.use()` in order — a plain function is wrapped as an anonymous `Plugin`. */
+    plugins?: (Plugin | MiddlewareFunc)[];
+    /** Merged into every record's `meta`, before a call-site `meta` value (which always wins on collision). */
+    meta?: Record<string, unknown>;
+    /** Bounds and backpressure policy for the internal async dispatch queue. See `DispatchQueueOptions`. */
+    queue?: DispatchQueueOptions;
+}
+/**
+ * The core logger: leveled, structured logging over a pluggable transport
+ * and plugin pipeline. Every log call returns the finished `LogRecord` (or
+ * `null` if it was filtered by level or dropped by a plugin) synchronously —
+ * the actual transport writes are dispatched onto an internal queue so the
+ * call returns before any I/O runs; see `flush()`/`close()`.
+ */
+declare class Logger {
+    /** This logger's name, as passed to the constructor (or derived via `.child()`). Appears on every record as `logger`. */
+    readonly name: string;
+    /** Every transport a written record is sent to. */
+    readonly transports: Transport[];
+    /** Every plugin registered via `.use()`, in registration order. */
+    readonly plugins: Plugin[];
+    private currentLevel;
+    private readonly baseMeta;
+    private dispatchQueue;
+    constructor(name: string, options?: LoggerOptions);
+    /** This logger's current minimum level — records below it are filtered before any plugin runs. */
+    get level(): Level;
+    /** Changes the minimum level records must meet to reach a transport. Accepts a `Level`, its numeric weight, or its name. */
+    setLevel(level: LevelInput): void;
+    /**
+     * Register a plugin, or a plain `beforeLog`-style function. A function is
+     * wrapped internally as an anonymous `Plugin` (`FunctionPlugin`) — the
+     * same middleware ergonomics as Express/Koa, without needing to read the
+     * `Plugin` interface first. Returns `this` so calls can be chained.
+     */
+    use(plugin: Plugin | MiddlewareFunc): this;
+    /** Number of dispatched records not yet written to their transports. Bounded by the `queue` option. */
+    get queueSize(): number;
+    /**
+     * Waits for every record dispatched so far to reach its transports'
+     * `write()` (and any plugin `afterLog` hooks). Note this does *not* force
+     * a batching transport (SQL, a queue, `HTTPTransport`, ...) to send a
+     * batch still under its own `maxRecords`/`maxBytes` threshold early — it
+     * only guarantees the record has been handed to that transport, the same
+     * contract `write()` always had. Before a process may pause or exit
+     * (a serverless freeze, a shutdown signal), prefer `withLambda`/
+     * `installShutdownHandlers`, which additionally force every batching
+     * transport to send its current buffer regardless of threshold.
+     */
+    flush(): Promise<void>;
+    /** Flush every pending record, then close every attached transport. Call once, on shutdown. */
+    close(): Promise<void>;
+    /** A logger scoped under this one, inheriting its level, transports, plugins, and dispatch queue. */
+    child(name: string, meta?: Record<string, unknown>): Logger;
+    private notifyError;
+    private dispatch;
+    private writeAndNotify;
+    /** Logs at `TRACE` — the lowest level, for fine-grained diagnostic detail. Returns the record, or `null` if filtered/dropped. */
+    trace(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `DEBUG`. Returns the record, or `null` if filtered/dropped. */
+    debug(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `INFO`. Returns the record, or `null` if filtered/dropped. */
+    info(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `WARN`. Returns the record, or `null` if filtered/dropped. */
+    warn(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `ERROR`. Returns the record, or `null` if filtered/dropped. */
+    error(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** Logs at `FATAL` — the highest level, for errors that precede an unrecoverable failure. Returns the record, or `null` if filtered/dropped. */
+    fatal(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "thought"` — an agent's internal reasoning step, for harness/agentic tracing. */
+    thought(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "action"` — an agent taking an action (a tool call, an LLM request), for harness/agentic tracing. */
+    action(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "observation"` — the result an agent observed from an action, for harness/agentic tracing. */
+    observation(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /** `.info()` tagged `meta.kind = "decision"` — an agent's concluding decision for a step or run, for harness/agentic tracing. */
+    decision(message: string, meta?: Record<string, unknown>): LogRecord | null;
+    /**
+     * `await logger.span("callLlm", async () => {...})` — runs `fn`, and on
+     * settling (success or throw) emits one record for the span itself
+     * carrying `meta.spanId` and `meta.durationMs`. Every record logged
+     * inside `fn` — through any method, and through any further `await` —
+     * is automatically stamped with `meta.parentSpanId` pointing at this
+     * span, so nested/sub-agent calls reconstruct their exact nesting when
+     * sorted by `spanId`/`parentSpanId`.
+     *
+     * Still emits its record — at `ERROR`, with `meta.error` set — if `fn`
+     * throws; the error itself propagates unchanged to the caller.
+     *
+     * `spanId`/`parentSpanId` normally auto-generate/auto-nest; pass them in
+     * `options` to adopt an id handed in from elsewhere (e.g. a framework
+     * adapter translating an id it already received).
+     */
+    span<T>(name: string, fn: () => T | Promise<T>, options?: SpanOptions): Promise<T>;
+    private finishSpan;
+}
+
+export { type BackpressurePolicy as B, CollectingTransport as C, DispatchQueue as D, type Formatter as F, JSONFormatter as J, type LogRecord as L, type MiddlewareFunc as M, type Plugin as P, type SpanOptions as S, Transport as T, Level as a, Logger as b, type LevelInput as c, type DispatchQueueOptions as d, type FlushableTransport as e, FunctionPlugin as f, type LoggerOptions as g, type Task as h, createRecord as i, hasFlush as j, levelName as l, parseLevel as p, utcTimestamp as u };