@framers/agentos 0.15.70 → 0.15.72

package/dist/core/logging/forward.js

@@ -0,0 +1,167 @@
+/**
+ * @fileoverview Turns an event, its context and the current request's id into the call the
+ * current target takes, and keeps a failing sink away from the caller.
+ *
+ * A sink that throws never reaches the caller. A failed check is a `LogValidationError`:
+ * under `NODE_ENV=test` it is thrown, so a test that writes a bad field fails, and otherwise
+ * it becomes one `log_refused` line with a fixed reason and no key or value.
+ *
+ * @module agentos/core/logging/forward
+ */
+var _a;
+import { getLoggingState } from './state.js';
+import { AGENTOS_CONTEXT, AGENTOS_EVENTS, valid } from './events.js';
+import { PinoLogger } from './PinoLogger.js';
+import { parseLogLevel } from './level.js';
+import { emitContentSafeLog } from './contentSafeTelemetry.js';
+// Marks a validation error so that another copy of the package recognises it, where instanceof fails.
+const ERROR = Symbol.for('agentos.logging.validation.v1');
+/** A line that failed its event, field or context check. */
+export class LogValidationError extends Error {
+    /** @param reason - Why the line was refused. */
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+        this[_a] = true;
+        this.name = 'LogValidationError';
+    }
+}
+_a = ERROR;
+/**
+ * Whether a value is a {@link LogValidationError}, including one thrown by another copy of
+ * AgentOS in the process.
+ *
+ * @param error - The caught value.
+ * @returns `true` for a validation error from any copy of the package.
+ */
+export function isValidationError(error) {
+    return typeof error === 'object' && error !== null && error[ERROR] === true;
+}
+/**
+ * Runs one write to a sink and swallows what it throws, except a validation error under
+ * `NODE_ENV=test`, which reaches the test.
+ *
+ * @param write - The write to run.
+ */
+export function sinkCall(write) {
+    try {
+        write();
+    }
+    catch (error) {
+        if (process.env.NODE_ENV === 'test' && isValidationError(error))
+            throw error;
+    }
+}
+/**
+ * Checks bindings against a context schema.
+ *
+ * @param schema - The keys a child may bind, and their kinds.
+ * @param bindings - The bindings to check.
+ * @throws {LogValidationError} With `bad_context` when a key is not in the schema or its value breaks its kind.
+ */
+export function checkContext(schema, bindings) {
+    for (const [key, value] of Object.entries(bindings)) {
+        if (!Object.prototype.hasOwnProperty.call(schema, key) || !valid(schema[key], value, key))
+            throw new LogValidationError('bad_context');
+    }
+}
+/**
+ * Checks an event and its fields against an event map.
+ *
+ * @param events - The declared events.
+ * @param context - The context schema, whose keys a field cannot set.
+ * @param event - The event's name.
+ * @param fields - The event's fields.
+ * @throws {LogValidationError} With `unknown_event` for an undeclared event, `unknown_key` for an undeclared field or a context key, and `bad_value` for a value that breaks its kind.
+ */
+export function checkFields(events, context, event, fields) {
+    if (!Object.prototype.hasOwnProperty.call(events, event))
+        throw new LogValidationError('unknown_event');
+    for (const [key, value] of Object.entries(fields)) {
+        if (Object.prototype.hasOwnProperty.call(context, key) || !Object.prototype.hasOwnProperty.call(events[event], key))
+            throw new LogValidationError('unknown_key');
+        if (!valid(events[event][key], value, key))
+            throw new LogValidationError('bad_value');
+    }
+}
+/**
+ * The default pino root, built on its first use at the level the environment names. When
+ * `AGENTOS_LOG_LEVEL` holds a value that is not a level name, the first build in the process
+ * writes one `logging.level_unknown` line, which never repeats the value.
+ *
+ * @returns The shared root.
+ */
+export function defaultRoot() {
+    const state = getLoggingState();
+    if (!state.root) {
+        const parsed = parseLogLevel(process.env);
+        state.root = new PinoLogger({ name: 'agentos', level: parsed.level });
+        if (parsed.unknown && !state.levelWarned) {
+            state.levelWarned = true;
+            sinkCall(() => state.root.writeEvent('warn', 'logging.level_unknown', {}));
+        }
+    }
+    return state.root;
+}
+/**
+ * Writes one line to a target.
+ *
+ * The line's context is the handle's bindings plus the current request's id. With `strict`
+ * the context, the event and its fields are checked against `AGENTOS_CONTEXT` and
+ * `AGENTOS_EVENTS`, the map a strict handle is typed over, so an event it does not declare,
+ * which only a JavaScript caller or a cast can write, is refused as `unknown_event`. A failed
+ * check is thrown under `NODE_ENV=test` and otherwise written as `log_refused`.
+ *
+ * A logger gets `logger[level]({ ...context, ...fields, event })`, with no message, and the
+ * default root writes the same object. A factory's logger gets `(event, fields)`: at `error`
+ * when it has no `fatal`, and not at all at `debug` when it has no `debug`. A silent target
+ * gets nothing. While content-safe telemetry is on, any other target gets nothing either: the
+ * line becomes one fixed event for the host's sink (a `fatal` line at `error`) naming `origin`,
+ * before any check, and nothing of it is read.
+ *
+ * @param target - Where the line goes.
+ * @param level - The line's level.
+ * @param event - The event's name.
+ * @param fields - The event's fields.
+ * @param context - The handle's bindings.
+ * @param strict - Whether to check the context and the fields; `createLogger`'s adapters pass `false`.
+ * @param origin - The fixed module word the content-safe event names; `library` for a handle no AgentOS module owns.
+ */
+export function forward(target, level, event, fields, context, strict = true, origin = 'library') {
+    if (target.mode === 'silent')
+        return;
+    if (emitContentSafeLog(level === 'fatal' ? 'error' : level, origin))
+        return;
+    const requestId = getLoggingState().requests.getStore()?.requestId;
+    // Annotated: a spread keeps an index signature only when every part has one, so the inferred type would lose
+    // the context's keys (component among them).
+    const merged = { ...context, ...(requestId ? { requestId } : {}) };
+    if (strict) {
+        try {
+            checkContext(AGENTOS_CONTEXT, merged);
+            checkFields(AGENTOS_EVENTS, AGENTOS_CONTEXT, event, fields);
+        }
+        catch (error) {
+            if (!isValidationError(error))
+                return;
+            if (process.env.NODE_ENV === 'test')
+                throw error;
+            forward(target, 'warn', 'log_refused', { reason: error.reason, ...(Object.prototype.hasOwnProperty.call(AGENTOS_EVENTS, event) ? { name: event } : {}) }, {}, false, origin);
+            return;
+        }
+    }
+    sinkCall(() => {
+        if (target.mode === 'logger') {
+            target.logger[level]({ ...merged, ...fields, event });
+            return;
+        }
+        if (target.mode === 'default') {
+            defaultRoot().writeEvent(level, event, { ...merged, ...fields });
+            return;
+        }
+        const log = target.factory(String(merged.component ?? 'agentos'), merged);
+        const method = level === 'fatal' ? log.fatal ?? log.error : log[level];
+        method?.call(log, event, fields);
+    });
+}
+//# sourceMappingURL=forward.js.map

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

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

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

@@ -1,10 +1,15 @@
 /**
- * Logging infrastructure: the `ILogger` contract, `createLogger` and its factory, `PinoLogger`, and content-safe
- * server telemetry.
+ * Logging infrastructure: the `ILogger` contract, `createLogger` and its factory, the hand-over of a host's pino
+ * logger (`setLogger`) with the typed event handles AgentOS writes through (`lazyLogger`), AgentOS's events and
+ * context keys as data, `PinoLogger`, and content-safe server telemetry. The allow-list kit is its own entry,
+ * `@framers/agentos/logging/kit`.
  * @module agentos/logging
  */
 export * from './ILogger.js';
-export * from './loggerFactory.js';
+export { setLogger, setLoggerFactory, resetLoggerFactory, createLogger, lazyLogger, type LoggerFactory, } from './loggerFactory.js';
+export type { Logger, LogMethod, Level, EventLogger, EventMethod } from './Logger.js';
+export { AGENTOS_EVENTS, AGENTOS_CONTEXT, PROVIDERS, type AgentOSEvents, type AgentOSContext, type EventMap, type ContextSchema, type FieldKind, type Fields, type ContextValues, } from './events.js';
+export { LogValidationError, type RefusalReason } from './forward.js';
 export { PinoLogger } from './PinoLogger.js';
 export { enableContentSafeTelemetry, isContentSafeTelemetryEnabled, CONTENT_SAFE_COMPONENTS, type ContentSafeLogLevel, type ContentSafeLogEvent, type ContentSafeLogSink, type ContentSafeLogComponent, type ContentSafeTelemetryOptions, } from './contentSafeTelemetry.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/logging/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,0BAA0B,EAAE,6BAA6B,EAAE,uBAAuB,EAClF,KAAK,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAC3E,KAAK,uBAAuB,EAAE,KAAK,2BAA2B,GAC/D,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/logging/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,cAAc,CAAC;AAC7B,OAAO,EACL,SAAS,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,aAAa,GAC9F,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,EACL,cAAc,EAAE,eAAe,EAAE,SAAS,EAC1C,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAE,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,KAAK,MAAM,EAAE,KAAK,aAAa,GAC5H,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,0BAA0B,EAAE,6BAA6B,EAAE,uBAAuB,EAClF,KAAK,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAC3E,KAAK,uBAAuB,EAAE,KAAK,2BAA2B,GAC/D,MAAM,2BAA2B,CAAC"}

package/dist/core/logging/index.js

@@ -1,10 +1,14 @@
 /**
- * Logging infrastructure: the `ILogger` contract, `createLogger` and its factory, `PinoLogger`, and content-safe
- * server telemetry.
+ * Logging infrastructure: the `ILogger` contract, `createLogger` and its factory, the hand-over of a host's pino
+ * logger (`setLogger`) with the typed event handles AgentOS writes through (`lazyLogger`), AgentOS's events and
+ * context keys as data, `PinoLogger`, and content-safe server telemetry. The allow-list kit is its own entry,
+ * `@framers/agentos/logging/kit`.
  * @module agentos/logging
  */
 export * from './ILogger.js';
-export * from './loggerFactory.js';
+export { setLogger, setLoggerFactory, resetLoggerFactory, createLogger, lazyLogger, } from './loggerFactory.js';
+export { AGENTOS_EVENTS, AGENTOS_CONTEXT, PROVIDERS, } from './events.js';
+export { LogValidationError } from './forward.js';
 export { PinoLogger } from './PinoLogger.js';
 export { enableContentSafeTelemetry, isContentSafeTelemetryEnabled, CONTENT_SAFE_COMPONENTS, } from './contentSafeTelemetry.js';
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/logging/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,0BAA0B,EAAE,6BAA6B,EAAE,uBAAuB,GAGnF,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/logging/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,cAAc,cAAc,CAAC;AAC7B,OAAO,EACL,SAAS,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,YAAY,EAAE,UAAU,GAC1E,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,cAAc,EAAE,eAAe,EAAE,SAAS,GAE3C,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAsB,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,0BAA0B,EAAE,6BAA6B,EAAE,uBAAuB,GAGnF,MAAM,2BAA2B,CAAC"}

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

@@ -0,0 +1,68 @@
+/**
+ * @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 type { EventLogger, Logger } from '../Logger.js';
+import { AGENTOS_CONTEXT, safeWord, type AgentOSEvents, type ContextSchema, type EventMap, type Fields } from '../events.js';
+/**
+ * The logger {@link createAllowListLogger} returns: an `EventLogger` over the product's event
+ * map, plus three methods.
+ *
+ * - `asLogger()` returns the pino-shaped form that `setLogger` takes.
+ * - `terminal(event, fields)` writes the process's last line at `fatal`. It bypasses the burst
+ *   budget and never refuses: a field that breaks its kind is left out, and an undeclared
+ *   event is written as `process.uncaught`.
+ * - `close()` stops the kit writing. Closing a child closes the kit it came from; closing the
+ *   last open kit in the process clears the shared counters and their timer.
+ *
+ * @typeParam E - The product's event map.
+ * @typeParam C - The context schema.
+ */
+export type AllowListLogger<E extends EventMap, C extends ContextSchema> = EventLogger<E, C> & {
+    asLogger(): Logger;
+    terminal<K extends keyof E & string>(event: K, fields?: Fields<E[K]>): void;
+    close(): void;
+};
+/**
+ * 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 declare function createAllowListLogger<E extends EventMap, C extends ContextSchema = typeof AGENTOS_CONTEXT>(options: {
+    logger: Logger;
+    events: E;
+    context?: C;
+    burst?: number;
+}): AllowListLogger<E & AgentOSEvents, C & typeof AGENTOS_CONTEXT>;
+export { safeWord };
+//# sourceMappingURL=allowList.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"allowList.d.ts","sourceRoot":"","sources":["../../../../src/core/logging/kit/allowList.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAS,MAAM,EAAa,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,eAAe,EAA+B,QAAQ,EAAS,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAkB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAIjL;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,aAAa,IAAI,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG;IAC7F,QAAQ,IAAI,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC5E,KAAK,IAAI,IAAI,CAAC;CACf,CAAC;AAgBF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,aAAa,GAAG,OAAO,eAAe,EAAE,OAAO,EAAE;IACnH,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACxD,GAAG,eAAe,CAAC,CAAC,GAAG,aAAa,EAAE,CAAC,GAAG,OAAO,eAAe,CAAC,CAqGjE;AACD,OAAO,EAAE,QAAQ,EAAE,CAAC"}

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