@framers/agentos 0.15.71 → 0.15.73

package/dist/core/logging/events.js

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview AgentOS's events and context keys, declared once as data, and the checks a
+ * value passes before it reaches a line.
+ *
+ * Each event maps its fields to one of four kinds: `int` (an integer), `word` (letters,
+ * digits and `_ . : -`, at most 64 characters), `path` (a word that may also hold `/`, at
+ * most 128 characters) or an `enum` (one of a declared list). A word or a path with the shape
+ * of a credential is refused. Nothing a person wrote, a model answered or a tool was given is
+ * ever a field; a length or a count may be.
+ *
+ * @module agentos/core/logging/events
+ */
+/** The provider names a line may carry. Any other provider is written as `unknown`. */
+export const PROVIDERS = ['openai', 'openrouter', 'anthropic', 'gemini', 'ollama', 'requesty', 'groq', 'mistral', 'together', 'xai', 'litellm', 'minimax', 'claude-code-cli', 'gemini-cli', 'unknown'];
+const provider = { enum: PROVIDERS };
+const api = { enum: ['generateText', 'streamText'] };
+// The fields every fallback event of generateText and streamText shares.
+const fallback = { api, primaryProvider: provider, fallbackProvider: provider, attempt: 'int' };
+/**
+ * The context keys a child may bind: `component` and `extension` as words, and `requestId`,
+ * which takes only letters, digits and dashes, at most 64 characters.
+ */
+export const AGENTOS_CONTEXT = { component: 'word', extension: 'word', requestId: 'word' };
+/**
+ * Every event AgentOS writes, with its fields. A field that names a provider, a state or a
+ * reason is an `enum`, never a free word, and an error is written as its `type` and `code`.
+ */
+export const AGENTOS_EVENTS = {
+    'logging.level_unknown': {},
+    'agentos.untyped': { sourceLevel: { enum: ['debug', 'info', 'warn', 'error', 'fatal'] } },
+    'console_line': { method: { enum: ['debug', 'info', 'log', 'warn', 'error', 'trace', 'dir', 'table', 'assert', 'count', 'countReset', 'time', 'timeEnd', 'timeLog', 'group', 'groupCollapsed', 'groupEnd', 'clear', 'dirxml', 'profile', 'profileEnd', 'timeStamp'] }, type: 'word', code: 'word' },
+    'process.uncaught': { type: 'word', code: 'word' },
+    'process.shutdown': { signal: { enum: ['SIGTERM', 'SIGINT'] } },
+    'http.request': { method: { enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', 'CONNECT', 'TRACE', 'OTHER'] }, route: 'path', status: 'int', ms: 'int', outcome: { enum: ['ok', 'aborted', 'error'] } },
+    'http.handler_failed': { type: 'word', code: 'word' },
+    'llm.provider_ready': { provider, count: 'int' },
+    'llm.provider_stopped': { provider },
+    'llm.provider_start_failed': { provider, type: 'word', code: 'word' },
+    'llm.default_changed': { provider },
+    'llm.manager_state': { state: { enum: ['reinitializing', 'empty', 'ready', 'stopping', 'stopped'] }, count: 'int' },
+    'llm.retry': { provider, status: 'int', attempt: 'int', waitMs: 'int' },
+    'llm.stream_invalid': { provider, bytes: 'int', reason: { enum: ['json', 'shape', 'framing', 'mapping'] } },
+    'llm.stream_failed': { provider, type: 'word', code: 'word' },
+    'llm.stream_cancel_failed': { provider, type: 'word', code: 'word' },
+    'llm.models_refresh': { provider },
+    'llm.models_failed': { provider, type: 'word', code: 'word' },
+    'llm.models_empty': { provider },
+    // Every key of a pool of several is out of rotation at start: the provider starts without its model listing.
+    'llm.key_pool_out': { provider, count: 'int' },
+    'llm.option_ignored': { provider, reason: { enum: ['provider_sort', 'cache_retention', 'embedding_capability'] } },
+    'llm.output_mismatch': { provider, reason: { enum: ['tool_arguments', 'text'] } },
+    'llm.output_empty': { provider, count: 'int' },
+    'llm.format_fallback': { provider, reason: { enum: ['json_schema'] } },
+    'llm.response_format_failed': { provider, type: 'word', code: 'word' },
+    'llm.fallback_skipped': { ...fallback, reason: { enum: ['duplicate', 'excluded', 'capability', 'refusal', 'refill', 'unknown'] } },
+    'llm.fallback_circuit_open': fallback,
+    'llm.fallback_fired': { ...fallback, type: 'word', code: 'word' },
+    'llm.fallback_succeeded': fallback,
+    'llm.fallback_failed_after_output': fallback,
+    'llm.fallback_exhausted': { api, primaryProvider: provider, attempts: 'int', type: 'word', code: 'word' },
+};
+/**
+ * Whether a string has the shape of a credential. Segments are split at the start and end,
+ * `.`, `/`, `:`, `-` and whitespace, and the shapes are:
+ *
+ * - a key prefix (`sk-`, `sk_`, `pk_` or `rk_`) opening a segment;
+ * - the word `bearer`, in any case;
+ * - three base64url parts joined by dots (a JWT);
+ * - a whole segment of 20 or more letters, digits and underscores.
+ *
+ * @param value - The string to test.
+ * @returns `true` when the string must not reach a line.
+ */
+export function credential(value) {
+    return keyShape(value) || /(?:^|[./:\s-])[A-Za-z0-9_]{20,}(?:$|[./:\s-])/.test(value);
+}
+// The credential shapes other than a long segment: a key prefix, the word bearer, or a JWT.
+function keyShape(value) {
+    return /(?:^|[./:\s-])(?:sk[-_]|pk_|rk_)/i.test(value) || /bearer/i.test(value)
+        || /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(value);
+}
+// A class name ending in Error or Exception, and an upper-case constant code of two or more parts joined by
+// underscores, each part at most 16 characters. Either may be 20 characters or more, which the long-segment
+// credential rule alone would refuse; the other credential shapes still refuse them.
+const CLASS_NAME = /^[A-Z][A-Za-z0-9]{0,54}(?:Error|Exception)$/;
+const CONSTANT_CODE = /^[A-Z][A-Z0-9]{0,15}(?:_[A-Z0-9]{1,16})+$/;
+/**
+ * Whether a value fits a field kind. A word or a path also fails when it has the shape of a
+ * credential, and the `requestId` context key takes only letters, digits and dashes. A word
+ * field named `type` also takes a class name ending in `Error` or `Exception`, and one named
+ * `code` an upper-case constant code such as `STREAM_PARSING_ERROR`, up to 64 characters and
+ * free of the other credential shapes, so that what {@link errorFields} writes passes.
+ *
+ * @param kind - The field's kind.
+ * @param value - The value, of any type, since JavaScript callers are checked too.
+ * @param key - The field's or the context key's name, which selects the `requestId`, `type` and `code` forms.
+ * @returns `true` when the value may be written.
+ */
+export function valid(kind, value, key = '') {
+    if (kind === 'int')
+        return typeof value === 'number' && Number.isInteger(value);
+    if (typeof value !== 'string')
+        return false;
+    if (typeof kind === 'object')
+        return kind.enum.includes(value);
+    if (kind === 'word' && value.length <= 64 && ((key === 'type' && CLASS_NAME.test(value)) || (key === 'code' && CONSTANT_CODE.test(value))))
+        return !keyShape(value);
+    if (credential(value))
+        return false;
+    if (key === 'requestId')
+        return /^[A-Za-z0-9-]{1,64}$/.test(value);
+    return kind === 'path' ? /^[A-Za-z0-9_.:/-]{1,128}$/.test(value) : /^[A-Za-z0-9_.:-]{1,64}$/.test(value);
+}
+/**
+ * A value as a word, or `unknown` when it is not a valid word.
+ *
+ * @param value - The value to write.
+ * @returns The value when it is a valid word, otherwise `'unknown'`.
+ */
+export function safeWord(value) { return valid('word', value) ? value : 'unknown'; }
+// A value read from a caught error, or undefined when reading it throws.
+function read(get) {
+    try {
+        return get();
+    }
+    catch {
+        return undefined;
+    }
+}
+// A value as the word field named `key`, or `unknown` when it does not fit.
+function fieldWord(value, key) {
+    return valid('word', value, key) ? value : 'unknown';
+}
+/**
+ * The fields an error is written as: its type and its code, never its message or its stack.
+ * Either is `unknown` when it is not a valid word. A class name ending in `Error` or
+ * `Exception` and an upper-case constant code such as `STREAM_PARSING_ERROR` are kept at any
+ * length up to 64 characters, while a value with the shape of a credential is still `unknown`.
+ * Reading the error never throws: a property whose getter throws is written as `unknown`.
+ *
+ * @param error - The caught value.
+ * @returns `type`, the error's name (or the value's `typeof` when it is not an `Error`), and `code`, its `code` property.
+ *
+ * @example
+ * ```ts
+ * errorFields(Object.assign(new Error('text that is never written'), { code: 'ECONNRESET' }));
+ * // { type: 'Error', code: 'ECONNRESET' }
+ * ```
+ */
+export function errorFields(error) {
+    const type = read(() => (error instanceof Error ? error.name : typeof error));
+    const code = read(() => (typeof error === 'object' && error !== null ? error.code : undefined));
+    return { type: fieldWord(type, 'type'), code: fieldWord(code, 'code') };
+}
+/**
+ * A provider's name as one of {@link PROVIDERS}, or `unknown`.
+ *
+ * @param value - The provider name to write.
+ * @returns The name when it is listed, otherwise `'unknown'`.
+ */
+export function providerName(value) {
+    return PROVIDERS.includes(value) ? value : 'unknown';
+}
+//# sourceMappingURL=events.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/core/logging/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuBH,uFAAuF;AACvF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,iBAAiB,EAAE,YAAY,EAAE,SAAS,CAAU,CAAC;AAChN,MAAM,QAAQ,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AACrC,MAAM,GAAG,GAAG,EAAE,IAAI,EAAE,CAAC,cAAc,EAAE,YAAY,CAAU,EAAE,CAAC;AAC9D,yEAAyE;AACzE,MAAM,QAAQ,GAAG,EAAE,GAAG,EAAE,eAAe,EAAE,QAAQ,EAAE,gBAAgB,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAW,CAAC;AAEzG;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAW,CAAC;AAEpG;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,uBAAuB,EAAE,EAAE;IAC3B,iBAAiB,EAAE,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE;IACzF,cAAc,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;IACnS,kBAAkB,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;IAClD,kBAAkB,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,EAAE;IAC/D,cAAc,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE;IACvN,qBAAqB,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;IACrD,oBAAoB,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE;IAChD,sBAAsB,EAAE,EAAE,QAAQ,EAAE;IACpC,2BAA2B,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;IACrE,qBAAqB,EAAE,EAAE,QAAQ,EAAE;IACnC,mBAAmB,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,gBAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;IACnH,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE;IACvE,oBAAoB,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,EAAE,EAAE;IAC3G,mBAAmB,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;IAC7D,0BAA0B,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;IACpE,oBAAoB,EAAE,EAAE,QAAQ,EAAE;IAClC,mBAAmB,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;IAC7D,kBAAkB,EAAE,EAAE,QAAQ,EAAE;IAChC,6GAA6G;IAC7G,kBAAkB,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE;IAC9C,oBAAoB,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,eAAe,EAAE,iBAAiB,EAAE,sBAAsB,CAAC,EAAE,EAAE;IAClH,qBAAqB,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,gBAAgB,EAAE,MAAM,CAAC,EAAE,EAAE;IACjF,kBAAkB,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE;IAC9C,qBAAqB,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,aAAa,CAAC,EAAE,EAAE;IACtE,4BAA4B,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;IACtE,sBAAsB,EAAE,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,EAAE;IAClI,2BAA2B,EAAE,QAAQ;IACrC,oBAAoB,EAAE,EAAE,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;IACjE,wBAAwB,EAAE,QAAQ;IAClC,kCAAkC,EAAE,QAAQ;IAC5C,wBAAwB,EAAE,EAAE,GAAG,EAAE,eAAe,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE;CAC9E,CAAC;AAQ9B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,QAAQ,CAAC,KAAK,CAAC,IAAI,+CAA+C,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACxF,CAAC;AAED,4FAA4F;AAC5F,SAAS,QAAQ,CAAC,KAAa;IAC7B,OAAO,mCAAmC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC;WAC1E,kDAAkD,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC;AAED,4GAA4G;AAC5G,4GAA4G;AAC5G,qFAAqF;AACrF,MAAM,UAAU,GAAG,6CAA6C,CAAC;AACjE,MAAM,aAAa,GAAG,2CAA2C,CAAC;AAElE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,KAAK,CAAC,IAAe,EAAE,KAAc,EAAE,GAAG,GAAG,EAAE;IAC7D,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAChF,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC/D,IAAI,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,MAAM,IAAI,EAAE,IAAI,CAAC,CAAC,GAAG,KAAK,MAAM,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,KAAK,MAAM,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACpK,IAAI,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,GAAG,KAAK,WAAW;QAAE,OAAO,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnE,OAAO,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,2BAA2B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,yBAAyB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3G,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc,IAAY,OAAO,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAe,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AAE/G,yEAAyE;AACzE,SAAS,IAAI,CAAC,GAAkB;IAC9B,IAAI,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,OAAO,SAAS,CAAC;IAAC,CAAC;AACnD,CAAC;AAED,4EAA4E;AAC5E,SAAS,SAAS,CAAC,KAAc,EAAE,GAAoB;IACrD,OAAO,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,KAAe,CAAC,CAAC,CAAC,SAAS,CAAC;AACjE,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC;IAC9E,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAE,KAAiC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAC7H,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;AAC1E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,SAAS,CAAC,QAAQ,CAAC,KAAmC,CAAC,CAAC,CAAC,CAAC,KAAmC,CAAC,CAAC,CAAC,SAAS,CAAC;AACnH,CAAC"}

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

@@ -0,0 +1,93 @@
+/**
+ * @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
+ */
+import type { Level } from './Logger.js';
+import type { Target } from './state.js';
+import { type ContextSchema, type EventMap } from './events.js';
+import { PinoLogger } from './PinoLogger.js';
+import { type ContentSafeLogComponent } from './contentSafeTelemetry.js';
+/** Why a line was refused. A refusal line carries the reason, never the key or the value. */
+export type RefusalReason = 'unknown_event' | 'unknown_key' | 'bad_value' | 'bad_context';
+declare const ERROR: unique symbol;
+/** A line that failed its event, field or context check. */
+export declare class LogValidationError extends Error {
+    readonly reason: RefusalReason;
+    readonly [ERROR] = true;
+    /** @param reason - Why the line was refused. */
+    constructor(reason: RefusalReason);
+}
+/**
+ * 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 declare function isValidationError(error: unknown): error is LogValidationError;
+/**
+ * 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 declare function sinkCall(write: () => void): void;
+/**
+ * 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 declare function checkContext(schema: ContextSchema, bindings: Record<string, unknown>): void;
+/**
+ * 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 declare function checkFields(events: EventMap, context: ContextSchema, event: string, fields: Record<string, unknown>): void;
+/**
+ * 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 declare function defaultRoot(): PinoLogger;
+/**
+ * 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 declare function forward(target: Target, level: Level, event: string, fields: Record<string, unknown>, context: Record<string, any>, strict?: boolean, origin?: ContentSafeLogComponent): void;
+export {};
+//# sourceMappingURL=forward.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"forward.d.ts","sourceRoot":"","sources":["../../../src/core/logging/forward.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,EAA0C,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AACxG,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAsB,KAAK,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAE7F,6FAA6F;AAC7F,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,aAAa,GAAG,WAAW,GAAG,aAAa,CAAC;AAE1F,QAAA,MAAM,KAAK,eAA8C,CAAC;AAE1D,4DAA4D;AAC5D,qBAAa,kBAAmB,SAAQ,KAAK;IAG/B,QAAQ,CAAC,MAAM,EAAE,aAAa;IAF1C,QAAQ,CAAC,CAAC,KAAK,CAAC,QAAQ;IACxB,gDAAgD;gBAC3B,MAAM,EAAE,aAAa;CAC3C;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAE7E;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,GAAG,IAAI,CAEhD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAI3F;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAM1H;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,IAAI,UAAU,CAWxC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,UAAO,EAAE,MAAM,GAAE,uBAAmC,GAAG,IAAI,CAyBpM"}

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