@framers/agentos 0.15.70 → 0.15.72

package/dist/core/logging/kit/burst.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview The burst budgets every allow-list kit in the process shares.
+ *
+ * Each declared event, and each refusal reason, writes the first `limit` lines of a minute;
+ * the rest are held, and once the minute has turned one `log_held` line gives the name and
+ * the count held. The budgets live in the process-wide logging state, so every kit instance,
+ * child, adapter and lazy handle that writes through a kit counts against the same minute.
+ * The timer that reports held lines is unreferenced, so it never holds the process open, and
+ * closing the last kit clears it with the counters.
+ *
+ * @module agentos/core/logging/kit/burst
+ */
+import { getLoggingState } from '../state.js';
+// Ends every minute that has turned and reports what it held through the writer of the kit that opened it, or,
+// when that kit has closed, through any kit still open.
+function flush() {
+    const state = getLoggingState();
+    const now = Date.now();
+    for (const [key, minute] of state.minutes) {
+        if (now - minute.start < 60000)
+            continue;
+        state.minutes.delete(key);
+        const emit = state.owners.get(minute.owner) ?? state.owners.values().next().value;
+        if (minute.held)
+            emit?.(minute.name, minute.held);
+    }
+}
+// Keeps one unreferenced timer for the earliest minute that holds lines, and none when no minute holds any or no
+// kit is open to report it.
+function schedule() {
+    const state = getLoggingState();
+    if (state.timer)
+        clearTimeout(state.timer);
+    state.timer = undefined;
+    const ends = [...state.minutes.values()].filter(m => m.held > 0).map(m => m.start + 60000);
+    if (!ends.length || !state.owners.size)
+        return;
+    const delay = Math.min(60000, Math.max(0, Math.min(...ends) - Date.now()));
+    state.timer = setTimeout(() => { state.timer = undefined; flush(); schedule(); }, delay);
+    state.timer.unref();
+}
+/**
+ * Registers a kit as an owner of burst budgets.
+ *
+ * @param emit - Writes the kit's `log_held` line: the event or refusal reason held, and how many lines were held.
+ * @returns The owner's key, which {@link admit} and {@link closeOwner} take.
+ */
+export function burstOwner(emit) {
+    const owner = Symbol();
+    getLoggingState().owners.set(owner, emit);
+    return owner;
+}
+/**
+ * Counts one line against its minute's budget. A budget's bound is the smallest any kit asked
+ * for in that minute.
+ *
+ * @param owner - The kit writing the line; a minute it opens reports its held lines through it.
+ * @param key - The budget's key, built from a declared event's name or a fixed refusal reason, so the keys are finite.
+ * @param name - The event's name or the refusal reason, as the `log_held` line gives it.
+ * @param limit - The kit's bound on lines a minute.
+ * @returns `true` when the line may be written, `false` when it is held.
+ */
+export function admit(owner, key, name, limit) {
+    const state = getLoggingState();
+    flush();
+    const minute = state.minutes.get(key) ?? { start: Date.now(), written: 0, held: 0, limit, owner, name };
+    minute.limit = Math.min(minute.limit, limit);
+    state.minutes.set(key, minute);
+    if (minute.written < minute.limit) {
+        minute.written++;
+        schedule();
+        return true;
+    }
+    minute.held++;
+    schedule();
+    return false;
+}
+/**
+ * Removes a kit from the owners. A minute it opened still reports through a kit that remains
+ * open; when no kit remains, the counters and the timer are cleared.
+ *
+ * @param owner - The key {@link burstOwner} returned.
+ */
+export function closeOwner(owner) {
+    const state = getLoggingState();
+    state.owners.delete(owner);
+    if (!state.owners.size)
+        state.minutes.clear();
+    schedule();
+}
+//# sourceMappingURL=burst.js.map

package/dist/core/logging/kit/burst.js.map

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

package/dist/core/logging/kit/consoleCapture.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Console capture: each console call becomes one content-free `console_line`
+ * event.
+ *
+ * The event carries the console method and, when one of the values is an error, its type and
+ * code. The text is never written. For an error, the frames of its stack after the exact
+ * opening (its name, `: ` and its message) go to standard error through the terminal writer,
+ * so an operator sees where it was thrown; a stack that opens any other way gives no frames,
+ * since a value inside a message could be shaped like a frame. Only lines with a frame's form
+ * (`at ` after the indent) are written, at most 50, and a line over 512 characters or holding
+ * a control or direction character is left out, so a stack set by hand cannot put text or
+ * terminal sequences on standard error. An error whose properties throw when read gives the
+ * event with `unknown` fields and no frames, and the console call does not throw.
+ *
+ * @module agentos/core/logging/kit/consoleCapture
+ */
+/**
+ * What console capture writes through: the `warn` method of an allow-list kit whose map
+ * declares AgentOS's `console_line` event.
+ */
+export interface ConsoleKit {
+    warn(event: 'console_line', fields: {
+        method: (typeof METHODS)[number];
+        type?: string;
+        code?: string;
+    }): void;
+}
+declare const METHODS: readonly ["debug", "info", "log", "warn", "error", "trace", "dir", "table", "assert", "count", "countReset", "time", "timeEnd", "timeLog", "group", "groupCollapsed", "groupEnd", "clear", "dirxml", "profile", "profileEnd", "timeStamp"];
+/**
+ * Replaces each console method with one that writes a `console_line` event through the kit.
+ * Capturing is idempotent across every copy of AgentOS in the process: a second call returns
+ * the first call's restore function and changes nothing. A console call made while a captured
+ * call is being written is dropped.
+ *
+ * @param kit - The kit the events are written through.
+ * @returns A function that puts the original console methods back.
+ *
+ * @example
+ * ```ts
+ * const restore = captureConsole(kit);
+ * console.error(new Error('text that is never written')); // one console_line line: method, type, code
+ * restore();
+ * ```
+ */
+export declare function captureConsole(kit: ConsoleKit): () => void;
+export {};
+//# sourceMappingURL=consoleCapture.d.ts.map

package/dist/core/logging/kit/consoleCapture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consoleCapture.d.ts","sourceRoot":"","sources":["../../../../src/core/logging/kit/consoleCapture.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH;;;GAGG;AACH,MAAM,WAAW,UAAU;IAAG,IAAI,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE;QAAE,MAAM,EAAE,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CAAE;AAC7I,QAAA,MAAM,OAAO,4OAA6O,CAAC;AA6C3P;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,IAAI,CAyB1D"}

package/dist/core/logging/kit/consoleCapture.js

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview Console capture: each console call becomes one content-free `console_line`
+ * event.
+ *
+ * The event carries the console method and, when one of the values is an error, its type and
+ * code. The text is never written. For an error, the frames of its stack after the exact
+ * opening (its name, `: ` and its message) go to standard error through the terminal writer,
+ * so an operator sees where it was thrown; a stack that opens any other way gives no frames,
+ * since a value inside a message could be shaped like a frame. Only lines with a frame's form
+ * (`at ` after the indent) are written, at most 50, and a line over 512 characters or holding
+ * a control or direction character is left out, so a stack set by hand cannot put text or
+ * terminal sequences on standard error. An error whose properties throw when read gives the
+ * event with `unknown` fields and no frames, and the console call does not throw.
+ *
+ * @module agentos/core/logging/kit/consoleCapture
+ */
+import { errorFields } from '../events.js';
+import { terminal } from '../../utils/terminal.js';
+const METHODS = ['debug', 'info', 'log', 'warn', 'error', 'trace', 'dir', 'table', 'assert', 'count', 'countReset', 'time', 'timeEnd', 'timeLog', 'group', 'groupCollapsed', 'groupEnd', 'clear', 'dirxml', 'profile', 'profileEnd', 'timeStamp'];
+// The restore function of the capture in place, shared by every copy of AgentOS in the process.
+const KEY = Symbol.for('agentos.logging.console.v1');
+// A frame line, and the bounds on the frames written.
+const FRAME = /^ +at \S/;
+const MAX_FRAMES = 50;
+const MAX_FRAME_LENGTH = 512;
+// Whether a line holds a C0 or C1 control, DEL, or a direction mark or override. A loop, not a regular
+// expression, since eslint's no-control-regex refuses control characters in one.
+function unsafe(line) {
+    for (let index = 0; index < line.length; index += 1) {
+        const code = line.charCodeAt(index);
+        if (code < 0x20 || (code >= 0x7f && code <= 0x9f) || code === 0x200e || code === 0x200f
+            || (code >= 0x202a && code <= 0x202e) || (code >= 0x2066 && code <= 0x2069))
+            return true;
+    }
+    return false;
+}
+// The first value that is an error; a value whose prototype throws when read is passed over.
+function firstError(values) {
+    for (const value of values) {
+        try {
+            if (value instanceof Error)
+                return value;
+        }
+        catch { /* Not an error that can be read. */ }
+    }
+    return undefined;
+}
+// The frame lines of an error's stack after its exact opening, bounded, or '' when there are none or reading fails.
+function framesOf(error) {
+    try {
+        const stack = error.stack;
+        if (typeof stack !== 'string')
+            return '';
+        const message = error.message;
+        for (const name of [error.name, 'Error']) {
+            const opening = `${name}: ${message}\n`;
+            if (!stack.startsWith(opening))
+                continue;
+            const lines = stack.slice(opening.length).split('\n')
+                .filter(line => line.length <= MAX_FRAME_LENGTH && FRAME.test(line) && !unsafe(line))
+                .slice(0, MAX_FRAMES);
+            return lines.length ? `${lines.join('\n')}\n` : '';
+        }
+        return '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Replaces each console method with one that writes a `console_line` event through the kit.
+ * Capturing is idempotent across every copy of AgentOS in the process: a second call returns
+ * the first call's restore function and changes nothing. A console call made while a captured
+ * call is being written is dropped.
+ *
+ * @param kit - The kit the events are written through.
+ * @returns A function that puts the original console methods back.
+ *
+ * @example
+ * ```ts
+ * const restore = captureConsole(kit);
+ * console.error(new Error('text that is never written')); // one console_line line: method, type, code
+ * restore();
+ * ```
+ */
+export function captureConsole(kit) {
+    const holder = globalThis;
+    if (holder[KEY])
+        return holder[KEY];
+    const target = console;
+    const originals = new Map();
+    let writing = false;
+    for (const method of METHODS) {
+        if (typeof target[method] !== 'function')
+            continue;
+        originals.set(method, target[method]);
+        target[method] = (...values) => {
+            if (writing)
+                return;
+            writing = true;
+            try {
+                const error = firstError(values);
+                kit.warn('console_line', { method, ...(error ? errorFields(error) : {}) });
+                const frames = error ? framesOf(error) : '';
+                if (frames)
+                    terminal(frames, 'stderr');
+            }
+            finally {
+                writing = false;
+            }
+        };
+    }
+    const restore = () => {
+        for (const [method, original] of originals)
+            target[method] = original;
+        delete holder[KEY];
+    };
+    holder[KEY] = restore;
+    return restore;
+}
+//# sourceMappingURL=consoleCapture.js.map

package/dist/core/logging/kit/consoleCapture.js.map

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

package/dist/core/logging/kit/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview The allow-list kit: a typed logger over a product's event map with fixed
+ * refusal reasons and burst budgets shared across the process, console capture, and opt-in
+ * process handlers.
+ *
+ * @module agentos/core/logging/kit
+ */
+export { createAllowListLogger, type AllowListLogger } from './allowList.js';
+export { captureConsole } from './consoleCapture.js';
+export { installProcessHandlers } from './processHandlers.js';
+export { LogValidationError } from '../forward.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/logging/kit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/logging/kit/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/core/logging/kit/index.js

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview The allow-list kit: a typed logger over a product's event map with fixed
+ * refusal reasons and burst budgets shared across the process, console capture, and opt-in
+ * process handlers.
+ *
+ * @module agentos/core/logging/kit
+ */
+export { createAllowListLogger } from './allowList.js';
+export { captureConsole } from './consoleCapture.js';
+export { installProcessHandlers } from './processHandlers.js';
+export { LogValidationError } from '../forward.js';
+//# sourceMappingURL=index.js.map

package/dist/core/logging/kit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/logging/kit/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,qBAAqB,EAAwB,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}

package/dist/core/logging/kit/processHandlers.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Opt-in process handlers: the shutdown line and the process's last line.
+ *
+ * AgentOS never installs these. A host with handlers of its own calls the kit's `terminal()`
+ * from them instead.
+ *
+ * @module agentos/core/logging/kit/processHandlers
+ */
+/** What the process handlers write through: an allow-list kit whose map declares AgentOS's process events. */
+export interface ProcessKit {
+    info(event: 'process.shutdown', fields: {
+        signal: 'SIGTERM' | 'SIGINT';
+    }): void;
+    terminal(event: 'process.uncaught', fields: {
+        type: string;
+        code: string;
+    }): void;
+}
+/**
+ * Installs handlers for SIGTERM, SIGINT, uncaught exceptions and unhandled rejections.
+ *
+ * - On SIGTERM or SIGINT, the first signal writes `process.shutdown` with the signal, then
+ *   calls `onShutdown`, which owns closing the host's servers and pools and ending the
+ *   process. A later signal is ignored.
+ * - On an uncaught exception or an unhandled rejection, or when `onShutdown` fails, it writes
+ *   `process.uncaught` with the error's type and code through `terminal()`, which bypasses the
+ *   burst budget at `fatal`, then calls `onFatal`, which exits with status 1 unless the host
+ *   gives its own.
+ *
+ * Installing is idempotent across every copy of AgentOS in the process: while the handlers are
+ * installed, a second call returns the first call's remover and installs nothing.
+ *
+ * @param kit - The kit the lines are written through.
+ * @param options - The host's callbacks.
+ * @param options.onShutdown - Called once, after the shutdown line, with the signal.
+ * @param options.onFatal - Called after the last line with the error; `process.exit(1)` unless given.
+ * @returns A function that removes every handler it installed.
+ *
+ * @example
+ * ```ts
+ * installProcessHandlers(kit, { onShutdown: async () => { await server.close(); process.exit(0); } });
+ * ```
+ */
+export declare function installProcessHandlers(kit: ProcessKit, options: {
+    onShutdown: (signal: 'SIGTERM' | 'SIGINT') => void | Promise<void>;
+    onFatal?: (error: unknown) => void;
+}): () => void;
+//# sourceMappingURL=processHandlers.d.ts.map

package/dist/core/logging/kit/processHandlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processHandlers.d.ts","sourceRoot":"","sources":["../../../../src/core/logging/kit/processHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,8GAA8G;AAC9G,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,KAAK,EAAE,kBAAkB,EAAE,MAAM,EAAE;QAAE,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAA;KAAE,GAAG,IAAI,CAAC;IAChF,QAAQ,CAAC,KAAK,EAAE,kBAAkB,EAAE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACnF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE;IAC/D,UAAU,EAAE,CAAC,MAAM,EAAE,SAAS,GAAG,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACpC,GAAG,MAAM,IAAI,CAuBb"}

package/dist/core/logging/kit/processHandlers.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Opt-in process handlers: the shutdown line and the process's last line.
+ *
+ * AgentOS never installs these. A host with handlers of its own calls the kit's `terminal()`
+ * from them instead.
+ *
+ * @module agentos/core/logging/kit/processHandlers
+ */
+import { errorFields } from '../events.js';
+import { getLoggingState } from '../state.js';
+/**
+ * Installs handlers for SIGTERM, SIGINT, uncaught exceptions and unhandled rejections.
+ *
+ * - On SIGTERM or SIGINT, the first signal writes `process.shutdown` with the signal, then
+ *   calls `onShutdown`, which owns closing the host's servers and pools and ending the
+ *   process. A later signal is ignored.
+ * - On an uncaught exception or an unhandled rejection, or when `onShutdown` fails, it writes
+ *   `process.uncaught` with the error's type and code through `terminal()`, which bypasses the
+ *   burst budget at `fatal`, then calls `onFatal`, which exits with status 1 unless the host
+ *   gives its own.
+ *
+ * Installing is idempotent across every copy of AgentOS in the process: while the handlers are
+ * installed, a second call returns the first call's remover and installs nothing.
+ *
+ * @param kit - The kit the lines are written through.
+ * @param options - The host's callbacks.
+ * @param options.onShutdown - Called once, after the shutdown line, with the signal.
+ * @param options.onFatal - Called after the last line with the error; `process.exit(1)` unless given.
+ * @returns A function that removes every handler it installed.
+ *
+ * @example
+ * ```ts
+ * installProcessHandlers(kit, { onShutdown: async () => { await server.close(); process.exit(0); } });
+ * ```
+ */
+export function installProcessHandlers(kit, options) {
+    const state = getLoggingState();
+    if (state.removeProcessHandlers)
+        return state.removeProcessHandlers;
+    let ending = false;
+    const fatal = (error) => {
+        try {
+            kit.terminal('process.uncaught', errorFields(error));
+        }
+        finally {
+            (options.onFatal ?? (() => process.exit(1)))(error);
+        }
+    };
+    const shutdown = (signal) => {
+        if (ending)
+            return;
+        ending = true;
+        try {
+            kit.info('process.shutdown', { signal });
+        }
+        finally {
+            Promise.resolve().then(() => options.onShutdown(signal)).catch(fatal);
+        }
+    };
+    const term = () => shutdown('SIGTERM');
+    const interrupt = () => shutdown('SIGINT');
+    process.on('SIGTERM', term);
+    process.on('SIGINT', interrupt);
+    process.on('uncaughtException', fatal);
+    process.on('unhandledRejection', fatal);
+    const remove = () => {
+        process.off('SIGTERM', term);
+        process.off('SIGINT', interrupt);
+        process.off('uncaughtException', fatal);
+        process.off('unhandledRejection', fatal);
+        if (state.removeProcessHandlers === remove)
+            state.removeProcessHandlers = undefined;
+    };
+    state.removeProcessHandlers = remove;
+    return remove;
+}
+//# sourceMappingURL=processHandlers.js.map

package/dist/core/logging/kit/processHandlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processHandlers.js","sourceRoot":"","sources":["../../../../src/core/logging/kit/processHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAQ9C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAe,EAAE,OAGvD;IACC,MAAM,KAAK,GAAG,eAAe,EAAE,CAAC;IAChC,IAAI,KAAK,CAAC,qBAAqB;QAAE,OAAO,KAAK,CAAC,qBAAqB,CAAC;IACpE,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,KAAK,GAAG,CAAC,KAAc,EAAE,EAAE;QAC/B,IAAI,CAAC;YAAC,GAAG,CAAC,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;QAAC,CAAC;gBACrD,CAAC;YAAC,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QAAC,CAAC;IAClE,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,CAAC,MAA4B,EAAE,EAAE;QAChD,IAAI,MAAM;YAAE,OAAO;QACnB,MAAM,GAAG,IAAI,CAAC;QACd,IAAI,CAAC;YAAC,GAAG,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;QAAC,CAAC;gBACzC,CAAC;YAAC,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAAC,CAAC;IACpF,CAAC,CAAC;IACF,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAAC,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnF,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC7D,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,KAAK,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,KAAK,CAAC,CAAC;IAChF,MAAM,MAAM,GAAG,GAAG,EAAE;QAClB,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC/D,OAAO,CAAC,GAAG,CAAC,mBAAmB,EAAE,KAAK,CAAC,CAAC;QAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,KAAK,CAAC,CAAC;QAClF,IAAI,KAAK,CAAC,qBAAqB,KAAK,MAAM;YAAE,KAAK,CAAC,qBAAqB,GAAG,SAAS,CAAC;IACtF,CAAC,CAAC;IACF,KAAK,CAAC,qBAAqB,GAAG,MAAM,CAAC;IAAC,OAAO,MAAM,CAAC;AACtD,CAAC"}

package/dist/core/logging/level.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview The level of AgentOS's default logger, read from the environment.
+ *
+ * @module agentos/core/logging/level
+ */
+/** The level names pino takes, from the most verbose to the least, then `silent`. */
+declare const LEVELS: readonly ["trace", "debug", "info", "warn", "error", "fatal", "silent"];
+/**
+ * Reads the default logger's level from the environment.
+ *
+ * `AGENTOS_LOG_LEVEL` names the level, in any case. A value that is not a level name gives
+ * `info` with `unknown` set, and the caller writes one `logging.level_unknown` line, which
+ * never repeats the value. When `AGENTOS_LOG_LEVEL` is unset or names a level,
+ * `AGENTOS_DEBUG=1` or `AGENTOS_DEBUG=true` gives `debug`, as the providers' start-up checks
+ * read them. With neither set the level is `info`.
+ *
+ * @param env - The environment to read, usually `process.env`.
+ * @returns The level, and whether `AGENTOS_LOG_LEVEL` held a value that is not a level name.
+ *
+ * @example
+ * ```ts
+ * parseLogLevel({ AGENTOS_LOG_LEVEL: 'warn' }); // { level: 'warn', unknown: false }
+ * parseLogLevel({ AGENTOS_LOG_LEVEL: 'DEBUG' }); // { level: 'debug', unknown: false }
+ * parseLogLevel({ AGENTOS_LOG_LEVEL: 'loud' }); // { level: 'info', unknown: true }
+ * parseLogLevel({ AGENTOS_DEBUG: 'true' }); // { level: 'debug', unknown: false }
+ * ```
+ */
+export declare function parseLogLevel(env: Record<string, string | undefined>): {
+    level: (typeof LEVELS)[number];
+    unknown: boolean;
+};
+export {};
+//# sourceMappingURL=level.d.ts.map

package/dist/core/logging/level.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"level.d.ts","sourceRoot":"","sources":["../../../src/core/logging/level.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qFAAqF;AACrF,QAAA,MAAM,MAAM,yEAA0E,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG;IACtE,KAAK,EAAE,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;CAClD,CAKA"}

package/dist/core/logging/level.js

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview The level of AgentOS's default logger, read from the environment.
+ *
+ * @module agentos/core/logging/level
+ */
+/** The level names pino takes, from the most verbose to the least, then `silent`. */
+const LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'fatal', 'silent'];
+/**
+ * Reads the default logger's level from the environment.
+ *
+ * `AGENTOS_LOG_LEVEL` names the level, in any case. A value that is not a level name gives
+ * `info` with `unknown` set, and the caller writes one `logging.level_unknown` line, which
+ * never repeats the value. When `AGENTOS_LOG_LEVEL` is unset or names a level,
+ * `AGENTOS_DEBUG=1` or `AGENTOS_DEBUG=true` gives `debug`, as the providers' start-up checks
+ * read them. With neither set the level is `info`.
+ *
+ * @param env - The environment to read, usually `process.env`.
+ * @returns The level, and whether `AGENTOS_LOG_LEVEL` held a value that is not a level name.
+ *
+ * @example
+ * ```ts
+ * parseLogLevel({ AGENTOS_LOG_LEVEL: 'warn' }); // { level: 'warn', unknown: false }
+ * parseLogLevel({ AGENTOS_LOG_LEVEL: 'DEBUG' }); // { level: 'debug', unknown: false }
+ * parseLogLevel({ AGENTOS_LOG_LEVEL: 'loud' }); // { level: 'info', unknown: true }
+ * parseLogLevel({ AGENTOS_DEBUG: 'true' }); // { level: 'debug', unknown: false }
+ * ```
+ */
+export function parseLogLevel(env) {
+    const value = env.AGENTOS_LOG_LEVEL?.toLowerCase();
+    if (value && !LEVELS.includes(value))
+        return { level: 'info', unknown: true };
+    if (env.AGENTOS_DEBUG === '1' || env.AGENTOS_DEBUG === 'true')
+        return { level: 'debug', unknown: false };
+    return { level: (value || 'info'), unknown: false };
+}
+//# sourceMappingURL=level.js.map

package/dist/core/logging/level.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"level.js","sourceRoot":"","sources":["../../../src/core/logging/level.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qFAAqF;AACrF,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,aAAa,CAAC,GAAuC;IAGnE,MAAM,KAAK,GAAG,GAAG,CAAC,iBAAiB,EAAE,WAAW,EAAE,CAAC;IACnD,IAAI,KAAK,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAgC,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACzG,IAAI,GAAG,CAAC,aAAa,KAAK,GAAG,IAAI,GAAG,CAAC,aAAa,KAAK,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IACzG,OAAO,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,MAAM,CAA4B,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AACjF,CAAC"}

package/dist/core/logging/loggerFactory.d.ts

@@ -1,31 +1,90 @@
 /**
- * @fileoverview The process-wide logger factory behind `createLogger`, and the guard that keeps every logger it
- * hands out, including one made before content-safe telemetry was enabled, inside that mode.
- * @module agentos/logging/loggerFactory
+ * @fileoverview How a host hands AgentOS its logger, the handles AgentOS writes through, and the
+ * guard that keeps every logger `createLogger` hands out inside content-safe telemetry.
+ *
+ * `setLogger` takes a pino-shaped logger, `setLoggerFactory` takes a factory of `ILogger`s,
+ * `setLogger(null)` silences AgentOS, and `resetLoggerFactory` returns to the default pino
+ * root, which is built on its first use. The last setter wins. `createLogger` calls the
+ * current factory at once and returns a guard over that factory's object: its calls reach the
+ * object until content-safe telemetry is enabled, and from then on each becomes one fixed
+ * event, even on a logger made earlier. `lazyLogger` returns a typed handle that reads the
+ * current target at each write, and so do its children; while content-safe telemetry is on,
+ * each of their lines is one fixed event as well.
+ *
+ * @module agentos/core/logging/loggerFactory
  */
 import type { ILogger } from './ILogger.js';
+import type { Logger, EventLogger } from './Logger.js';
+import type { AgentOSEvents, AgentOSContext } from './events.js';
+import { type LoggerFactory } from './state.js';
+import { type ContentSafeLogComponent } from './contentSafeTelemetry.js';
+export type { LoggerFactory } from './state.js';
 /**
- * Makes the logger `createLogger` delegates to, from a component name and optional bindings.
+ * Hands AgentOS a pino-shaped logger, or silences it with `null`. Lazy handles, whenever they
+ * were made, write to it from their next line; an object `createLogger` returned earlier keeps
+ * its target.
+ *
+ * @param logger - A logger with `debug`, `info`, `warn`, `error`, `fatal` and `child`, such as a pino logger or a pino child, or `null` to write nothing.
+ * @throws {TypeError} When one of those methods is missing, naming it.
+ *
+ * @example
+ * ```ts
+ * import pino from 'pino';
+ * setLogger(pino());
+ * ```
  */
-export type LoggerFactory = (name: string, bindings?: Record<string, any>) => ILogger;
+export declare function setLogger(logger: Logger | null): void;
 /**
- * Sets the factory that later `createLogger` calls delegate to.
+ * Hands AgentOS a factory of `ILogger`s. `createLogger` calls it at once. A lazy handle calls
+ * it at each write with its component and context, and writes `(event, fields)` to the logger
+ * it returns.
  *
- * @param factory - Makes the logger for a component name and optional bindings.
+ * @param factory - The factory.
  */
 export declare function setLoggerFactory(factory: LoggerFactory): void;
-/**
- * Restores the default factory: children of a new root `PinoLogger` named `agentos`.
- */
+/** Returns AgentOS to its default pino root, which is built again on its next use. */
 export declare function resetLoggerFactory(): void;
 /**
- * A logger for one component. Its calls go to the logger the current factory makes, with the caller's arguments,
- * until content-safe telemetry is enabled; from then on each call becomes one fixed event for the host's sink, even
- * on a logger created earlier. While the mode is on, the factory is not called and `child` returns the same logger.
+ * Returns a component's logger: a guard over the logger the current target gives. With a factory
+ * set, it calls the factory at once; otherwise it takes a child of the default root, or an
+ * adapter over the logger or the silence set now, and that logger keeps its target after a later
+ * setter. The guard's calls reach that logger, with the caller's arguments, until content-safe
+ * telemetry is enabled; from then on each call becomes one fixed event for the host's sink, even
+ * on a logger made earlier, and `child` returns the same logger. While the mode is on, the
+ * factory is not called and nothing is made.
  *
- * @param name - The component name.
- * @param bindings - Fields every record of the logger carries.
+ * @param name - The component's name.
+ * @param bindings - Bindings for every line the logger writes.
  * @returns The component's logger.
  */
 export declare function createLogger(name: string, bindings?: Record<string, any>): ILogger;
+/**
+ * Returns a typed handle that reads the current target at each write, so a handle made at
+ * import follows a later `setLogger` or `setLoggerFactory`; its children do the same. Its
+ * methods take only an event `AGENTOS_EVENTS` declares, with that event's fields.
+ *
+ * @param component - The component the lines come from.
+ * @param context - More context keys to bind, such as `extension`.
+ * @returns The handle.
+ * @throws {LogValidationError} Under `NODE_ENV=test`, when the component or the context breaks AgentOS's context schema; otherwise such a handle writes one `log_refused` line and then nothing.
+ *
+ * @example
+ * ```ts
+ * const log = lazyLogger('OpenAIProvider');
+ * log.warn('llm.retry', { provider: 'openai', status: 429, attempt: 1, waitMs: 2000 });
+ * ```
+ */
+export declare function lazyLogger(component: string, context?: AgentOSContext): EventLogger<AgentOSEvents>;
+/**
+ * The handle an AgentOS module writes through: a {@link lazyLogger} handle whose lines, while
+ * content-safe telemetry is on, each reach the sink as one fixed event naming the module, as
+ * the module's console lines do. An origin outside `CONTENT_SAFE_COMPONENTS` reads as
+ * `library`.
+ *
+ * @param component - The component the lines come from.
+ * @param origin - The module's fixed word in `CONTENT_SAFE_COMPONENTS`.
+ * @returns The handle.
+ * @internal
+ */
+export declare function moduleLogger(component: string, origin: ContentSafeLogComponent): EventLogger<AgentOSEvents>;
 //# sourceMappingURL=loggerFactory.d.ts.map