@framers/agentos 0.15.71 → 0.15.73

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

@@ -0,0 +1,219 @@
+/**
+ * @fileoverview The allow-list logger: a typed logger over a product's event map that writes
+ * only declared events with fields of their declared kinds.
+ *
+ * A line the product writes through the kit is refused when its event is undeclared, or when a
+ * field or the context breaks its kind. A refusal is written as `log_refused` at `warn` with a
+ * fixed reason (`unknown_event`, `unknown_key`, `bad_value` or `bad_context`), plus the
+ * event's name only when the event is declared, and never the key or the value; under
+ * `NODE_ENV=test` it is thrown as a `LogValidationError` instead. A line that reaches the
+ * kit's pino-shaped form, `asLogger()`, with an undeclared event is written as
+ * `agentos.untyped` with only its component and its level, so a sentence from code that has
+ * not moved to events never reaches the log. Every line counts against the burst budgets the
+ * process shares.
+ *
+ * @module agentos/core/logging/kit/allowList
+ */
+import { AGENTOS_CONTEXT, AGENTOS_EVENTS, errorFields, safeWord, valid } from '../events.js';
+import { checkContext, checkFields, isValidationError, LogValidationError, sinkCall } from '../forward.js';
+import { admit, burstOwner, closeOwner } from './burst.js';
+const own = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+// Whether two field kinds are the same: the same word, or enums of the same values in any order.
+function sameKind(a, b) {
+    if (typeof a === 'string' || typeof b === 'string')
+        return a === b;
+    if (!a || !b || !Array.isArray(a.enum) || !Array.isArray(b.enum))
+        return false;
+    return a.enum.length === b.enum.length && a.enum.every(value => b.enum.includes(value));
+}
+// Whether two event declarations name the same fields with the same kinds.
+function sameFields(a, b) {
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every(key => own(b, key) && sameKind(a[key], b[key]));
+}
+/**
+ * Creates an allow-list logger over a product's event map. AgentOS's own events are always
+ * declared; the product's map adds its own and those of the packs it uses, and may name one of
+ * AgentOS's events again only with the same fields. No process listener is installed by
+ * importing or creating a kit.
+ *
+ * @param options - The kit's settings.
+ * @param options.logger - The pino logger, or pino child, the kit writes through.
+ * @param options.events - The product's event map.
+ * @param options.context - The context keys a child may bind beyond AgentOS's own, which stay in the schema because AgentOS's lines carry them.
+ * @param options.burst - Lines a minute for each event and each refusal reason, 30 unless set. Every kit in the process shares the budgets, at the smallest bound asked for.
+ * @returns The kit, typed over AgentOS's events and the product's map, so it also takes the
+ * `console_line` and `process.*` lines `captureConsole` and `installProcessHandlers` write.
+ * @throws {TypeError} When `burst` is not a positive integer, an event's name is not a word of at most 64 characters or is `log_refused` or `log_held`, an event declares a context key, `event`, `level` or `time` as a field, the product's map declares one of AgentOS's events with other fields than AgentOS gives it, or `context` gives one of AgentOS's context keys another kind.
+ *
+ * @example
+ * ```ts
+ * import pino from 'pino';
+ * const kit = createAllowListLogger({ logger: pino(), events: { 'job.done': { ms: 'int' } } });
+ * kit.info('job.done', { ms: 120 });
+ * setLogger(kit.asLogger());
+ * ```
+ */
+export function createAllowListLogger(options) {
+    const events = { ...AGENTOS_EVENTS, ...options.events };
+    // AgentOS's own lines carry its context keys, so a host's keys extend them and may name one again only with its kind.
+    for (const [key, kind] of Object.entries(options.context ?? {})) {
+        if (own(AGENTOS_CONTEXT, key) && !sameKind(kind, AGENTOS_CONTEXT[key]))
+            throw new TypeError('context key redeclared with another kind');
+    }
+    const schema = { ...AGENTOS_CONTEXT, ...options.context };
+    const limit = options.burst ?? 30;
+    if (!Number.isInteger(limit) || limit < 1)
+        throw new TypeError('burst must be a positive integer');
+    // The refusal and held-lines records are the kit's own, so a product map can neither declare nor overwrite them.
+    // An AgentOS event the product's map names again keeps AgentOS's fields, so AgentOS's own lines are never refused.
+    for (const [name, fields] of Object.entries(events)) {
+        if (own(AGENTOS_EVENTS, name) && !sameFields(fields, AGENTOS_EVENTS[name]))
+            throw new TypeError('event redeclared with other fields');
+        if (name === 'log_refused' || name === 'log_held' || !/^[A-Za-z0-9_.:-]{1,64}$/.test(name))
+            throw new TypeError('invalid event declaration');
+        for (const key of Object.keys(fields))
+            if (own(schema, key) || key === 'event' || key === 'level' || key === 'time')
+                throw new TypeError('reserved field declaration');
+    }
+    let closed = false;
+    const raw = (level, fields) => { if (!closed)
+        sinkCall(() => options.logger[level](fields)); };
+    const owner = burstOwner((name, n) => raw('info', { event: 'log_held', name, n }));
+    function refuse(reason, event) {
+        if (process.env.NODE_ENV === 'test')
+            throw new LogValidationError(reason);
+        if (admit(owner, `reason:${reason}`, reason, limit))
+            raw('warn', { event: 'log_refused', reason, ...(event && own(events, event) ? { name: event } : {}) });
+    }
+    // One logger over `bindings`. A child whose bindings fail the context schema writes one refusal and is then
+    // disabled, so it writes nothing.
+    function make(bindings, disabled = false) {
+        function write(level, event, fields = {}, adapter = false) {
+            if (closed || disabled)
+                return;
+            if (adapter && !own(events, event)) {
+                if (admit(owner, 'event:agentos.untyped', 'agentos.untyped', limit))
+                    raw(level, { event: 'agentos.untyped', ...(bindings.component ? { component: bindings.component } : {}), sourceLevel: level });
+                return;
+            }
+            try {
+                checkContext(schema, bindings);
+                checkFields(events, schema, event, fields);
+            }
+            catch (error) {
+                if (isValidationError(error)) {
+                    refuse(error.reason, event);
+                    return;
+                }
+                throw error;
+            }
+            if (admit(owner, `event:${event}`, event, limit))
+                raw(level, { ...bindings, ...fields, event });
+        }
+        function child(next) {
+            const merged = { ...bindings, ...next };
+            try {
+                checkContext(schema, merged);
+            }
+            catch (error) {
+                if (isValidationError(error)) {
+                    refuse('bad_context');
+                    return make({}, true);
+                }
+                throw error;
+            }
+            return make(merged, disabled);
+        }
+        const api = {
+            debug: (event, fields) => write('debug', event, fields),
+            info: (event, fields) => write('info', event, fields),
+            warn: (event, fields) => write('warn', event, fields),
+            error: (event, fields) => write('error', event, fields),
+            fatal: (event, fields) => write('fatal', event, fields),
+            child,
+            terminal(event, fields = {}) {
+                if (closed || disabled)
+                    return;
+                // Terminal never routes an unsafe value into a refusal or echoes it.
+                const safe = {};
+                const shape = events[event];
+                if (shape) {
+                    for (const [key, value] of Object.entries(fields)) {
+                        try {
+                            checkFields(events, schema, event, { [key]: value });
+                            safe[key] = value;
+                        }
+                        catch { /* Omit an invalid terminal field. */ }
+                    }
+                    raw('fatal', { ...bindings, ...safe, event });
+                }
+                else
+                    raw('fatal', { event: 'process.uncaught', ...errorFields(undefined) });
+            },
+            close() { if (!closed) {
+                closeOwner(owner);
+                closed = true;
+            } },
+            // The pino-shaped form. A host's line arrives as one object holding its event, its context and its fields;
+            // a message alone has no event, so it is written as agentos.untyped. A refusal another layer forwards is
+            // written again as this kit's own, from its reason and declared name alone.
+            asLogger() {
+                const method = (level) => ((obj) => {
+                    if (closed || disabled)
+                        return;
+                    if (typeof obj === 'string') {
+                        write(level, '', {}, true);
+                        return;
+                    }
+                    if (obj === null) {
+                        write(level, '', {}, true);
+                        return;
+                    }
+                    const input = obj;
+                    const event = typeof input.event === 'string' ? input.event : '';
+                    if (event === 'log_refused') {
+                        const reasons = ['unknown_event', 'unknown_key', 'bad_value', 'bad_context'];
+                        const reason = reasons.includes(input.reason) ? input.reason : 'bad_value';
+                        refuse(reason, typeof input.name === 'string' && own(events, input.name) ? input.name : undefined);
+                        return;
+                    }
+                    if (!own(events, event)) {
+                        const component = valid('word', input.component) ? input.component : bindings.component;
+                        if (admit(owner, 'event:agentos.untyped', 'agentos.untyped', limit)) {
+                            raw(level, { event: 'agentos.untyped', ...(component ? { component } : {}), sourceLevel: level });
+                        }
+                        return;
+                    }
+                    const context = { ...bindings };
+                    const fields = {};
+                    for (const [key, value] of Object.entries(input)) {
+                        if (key === 'event')
+                            continue;
+                        if (own(schema, key))
+                            context[key] = value;
+                        else
+                            fields[key] = value;
+                    }
+                    try {
+                        checkContext(schema, context);
+                    }
+                    catch (error) {
+                        if (isValidationError(error)) {
+                            refuse('bad_context', event);
+                            return;
+                        }
+                        throw error;
+                    }
+                    make(context)[level](event, fields);
+                });
+                return { debug: method('debug'), info: method('info'), warn: method('warn'), error: method('error'), fatal: method('fatal'), child: next => child(next).asLogger() };
+            },
+        };
+        return api;
+    }
+    // The map the kit checks against always holds AgentOS's own events, so its type does too.
+    return make({});
+}
+export { safeWord };
+//# sourceMappingURL=allowList.js.map

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

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

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

@@ -0,0 +1,38 @@
+/**
+ * @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
+ */
+/**
+ * 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 declare function burstOwner(emit: (name: string, n: number) => void): symbol;
+/**
+ * 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 declare function admit(owner: symbol, key: string, name: string, limit: number): boolean;
+/**
+ * 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 declare function closeOwner(owner: symbol): void;
+//# sourceMappingURL=burst.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"burst.d.ts","sourceRoot":"","sources":["../../../../src/core/logging/kit/burst.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA6BH;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAE1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAOtF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAI9C"}

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"}