@agentick/kernel 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +401 -0
  3. package/dist/.tsbuildinfo.build +1 -0
  4. package/dist/channel-helpers.d.ts +32 -0
  5. package/dist/channel-helpers.d.ts.map +1 -0
  6. package/dist/channel-helpers.js +62 -0
  7. package/dist/channel-helpers.js.map +1 -0
  8. package/dist/channel.d.ts +164 -0
  9. package/dist/channel.d.ts.map +1 -0
  10. package/dist/channel.js +199 -0
  11. package/dist/channel.js.map +1 -0
  12. package/dist/context.d.ts +412 -0
  13. package/dist/context.d.ts.map +1 -0
  14. package/dist/context.js +289 -0
  15. package/dist/context.js.map +1 -0
  16. package/dist/event-buffer.d.ts +208 -0
  17. package/dist/event-buffer.d.ts.map +1 -0
  18. package/dist/event-buffer.js +335 -0
  19. package/dist/event-buffer.js.map +1 -0
  20. package/dist/execution-helpers.d.ts +179 -0
  21. package/dist/execution-helpers.d.ts.map +1 -0
  22. package/dist/execution-helpers.js +212 -0
  23. package/dist/execution-helpers.js.map +1 -0
  24. package/dist/execution-tracker.d.ts +61 -0
  25. package/dist/execution-tracker.d.ts.map +1 -0
  26. package/dist/execution-tracker.js +319 -0
  27. package/dist/execution-tracker.js.map +1 -0
  28. package/dist/guard.d.ts +65 -0
  29. package/dist/guard.d.ts.map +1 -0
  30. package/dist/guard.js +15 -0
  31. package/dist/guard.js.map +1 -0
  32. package/dist/index.d.ts +61 -0
  33. package/dist/index.d.ts.map +1 -0
  34. package/dist/index.js +62 -0
  35. package/dist/index.js.map +1 -0
  36. package/dist/logger.d.ts +341 -0
  37. package/dist/logger.d.ts.map +1 -0
  38. package/dist/logger.js +346 -0
  39. package/dist/logger.js.map +1 -0
  40. package/dist/metrics-helpers.d.ts +40 -0
  41. package/dist/metrics-helpers.d.ts.map +1 -0
  42. package/dist/metrics-helpers.js +72 -0
  43. package/dist/metrics-helpers.js.map +1 -0
  44. package/dist/otel-provider.d.ts +54 -0
  45. package/dist/otel-provider.d.ts.map +1 -0
  46. package/dist/otel-provider.js +107 -0
  47. package/dist/otel-provider.js.map +1 -0
  48. package/dist/procedure-graph.d.ts +136 -0
  49. package/dist/procedure-graph.d.ts.map +1 -0
  50. package/dist/procedure-graph.js +272 -0
  51. package/dist/procedure-graph.js.map +1 -0
  52. package/dist/procedure.d.ts +757 -0
  53. package/dist/procedure.d.ts.map +1 -0
  54. package/dist/procedure.js +895 -0
  55. package/dist/procedure.js.map +1 -0
  56. package/dist/schema.d.ts +153 -0
  57. package/dist/schema.d.ts.map +1 -0
  58. package/dist/schema.js +385 -0
  59. package/dist/schema.js.map +1 -0
  60. package/dist/stream.d.ts +106 -0
  61. package/dist/stream.d.ts.map +1 -0
  62. package/dist/stream.js +186 -0
  63. package/dist/stream.js.map +1 -0
  64. package/dist/telemetry.d.ts +182 -0
  65. package/dist/telemetry.d.ts.map +1 -0
  66. package/dist/telemetry.js +124 -0
  67. package/dist/telemetry.js.map +1 -0
  68. package/dist/testing.d.ts +55 -0
  69. package/dist/testing.d.ts.map +1 -0
  70. package/dist/testing.js +96 -0
  71. package/dist/testing.js.map +1 -0
  72. package/package.json +48 -0
@@ -0,0 +1,65 @@
1
+ import type { Middleware, ProcedureEnvelope } from "./procedure";
2
+ /**
3
+ * Guard function that inspects the procedure envelope to decide allow/deny.
4
+ *
5
+ * - Return `true` to allow execution.
6
+ * - Return `false` to deny (createGuard constructs a GuardError from config).
7
+ * - Throw a `GuardError` directly for full control over the error.
8
+ */
9
+ export type GuardFn = (envelope: ProcedureEnvelope<any[]>) => boolean | Promise<boolean>;
10
+ /**
11
+ * Configuration for createGuard.
12
+ */
13
+ export interface GuardConfig {
14
+ /** Guard name (for debugging, telemetry, error details) */
15
+ name?: string;
16
+ /**
17
+ * Denial reason when the guard fn returns `false`.
18
+ * String or function that receives the envelope for dynamic messages.
19
+ * Ignored when the guard fn throws its own error.
20
+ */
21
+ reason?: string | ((envelope: ProcedureEnvelope<any[]>) => string);
22
+ /** Guard type discriminator (e.g., "role", "guardrail", "rate-limit") */
23
+ guardType?: string;
24
+ }
25
+ /**
26
+ * Create a guard middleware from a predicate function.
27
+ *
28
+ * The guard runs before the procedure handler:
29
+ * - If the fn returns `true`, execution continues.
30
+ * - If the fn returns `false`, a `GuardError` is thrown (using config for the message).
31
+ * - If the fn throws a `GuardError`, it propagates directly (full control).
32
+ *
33
+ * @example Simple boolean guard
34
+ * ```typescript
35
+ * const adminOnly = createGuard(
36
+ * (envelope) => envelope.context.user?.roles?.includes("admin") ?? false,
37
+ * );
38
+ * ```
39
+ *
40
+ * @example Config with dynamic reason
41
+ * ```typescript
42
+ * const roleGuard = createGuard({
43
+ * name: "role-guard",
44
+ * guardType: "role",
45
+ * reason: (envelope) => `User ${envelope.context.user?.id} lacks required role`,
46
+ * }, (envelope) => {
47
+ * return envelope.context.user?.roles?.includes("admin") ?? false;
48
+ * });
49
+ * ```
50
+ *
51
+ * @example Throwing custom GuardError for full control
52
+ * ```typescript
53
+ * const roleGuard = createGuard({ name: "role-guard" }, (envelope) => {
54
+ * const userRoles = envelope.context.user?.roles ?? [];
55
+ * const required = ["admin", "moderator"];
56
+ * if (!required.some(r => userRoles.includes(r))) {
57
+ * throw GuardError.role(required);
58
+ * }
59
+ * return true;
60
+ * });
61
+ * ```
62
+ */
63
+ export declare function createGuard(fn: GuardFn): Middleware;
64
+ export declare function createGuard(config: GuardConfig, fn: GuardFn): Middleware;
65
+ //# sourceMappingURL=guard.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGjE;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG,CAAC,QAAQ,EAAE,iBAAiB,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEzF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,iBAAiB,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,CAAC,CAAC;IAEnE,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,CAAC;AACrD,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,OAAO,GAAG,UAAU,CAAC"}
package/dist/guard.js ADDED
@@ -0,0 +1,15 @@
1
+ import { GuardError } from "@agentick/shared";
2
+ export function createGuard(configOrFn, maybeFn) {
3
+ const config = typeof configOrFn === "function" ? {} : configOrFn;
4
+ const fn = typeof configOrFn === "function" ? configOrFn : maybeFn;
5
+ return async (args, envelope, next) => {
6
+ if (!(await fn(envelope))) {
7
+ const reason = typeof config.reason === "function"
8
+ ? config.reason(envelope)
9
+ : (config.reason ?? "Guard check failed");
10
+ throw new GuardError(reason, config.guardType ?? "custom", config.name ? { guard: config.name } : {});
11
+ }
12
+ return next();
13
+ };
14
+ }
15
+ //# sourceMappingURL=guard.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"guard.js","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAqE9C,MAAM,UAAU,WAAW,CAAC,UAAiC,EAAE,OAAiB;IAC9E,MAAM,MAAM,GAAgB,OAAO,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;IAC/E,MAAM,EAAE,GAAY,OAAO,UAAU,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAQ,CAAC;IAE7E,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE;QACpC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;YAC1B,MAAM,MAAM,GACV,OAAO,MAAM,CAAC,MAAM,KAAK,UAAU;gBACjC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC;gBACzB,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,oBAAoB,CAAC,CAAC;YAC9C,MAAM,IAAI,UAAU,CAClB,MAAM,EACN,MAAM,CAAC,SAAS,IAAI,QAAQ,EAC5B,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAC1C,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,EAAE,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}
@@ -0,0 +1,61 @@
1
+ /**
2
+ * # Agentick Kernel
3
+ *
4
+ * Low-level execution primitives for the Agentick framework. The kernel provides
5
+ * the foundational infrastructure that all other Agentick packages build upon.
6
+ *
7
+ * ## Core Primitives
8
+ *
9
+ * - **Procedures** - Async function wrappers with middleware, context, and telemetry
10
+ * - **Context** - Request-scoped state with automatic propagation
11
+ * - **Channels** - Async generators for streaming with backpressure
12
+ * - **Telemetry** - Execution tracking, spans, and metrics
13
+ * - **Logger** - Structured logging with configurable levels
14
+ *
15
+ * ## When to Use Kernel Directly
16
+ *
17
+ * Most applications should use the higher-level `agentick` package. Use kernel directly when:
18
+ *
19
+ * - Building custom execution infrastructure
20
+ * - Creating new Agentick adapters or integrations
21
+ * - Need fine-grained control over procedure execution
22
+ *
23
+ * ## Example
24
+ *
25
+ * ```typescript
26
+ * import { createProcedure, Context } from './core';
27
+ *
28
+ * const myProcedure = createProcedure(
29
+ * { name: 'my-operation' },
30
+ * async (input: string) => {
31
+ * return { result: input.toUpperCase() };
32
+ * }
33
+ * );
34
+ *
35
+ * const result = await myProcedure.exec('hello');
36
+ * ```
37
+ *
38
+ * @see {@link Procedure} - The core procedure abstraction
39
+ * @see {@link KernelContext} - Request-scoped context
40
+ * @see {@link Channel} - Streaming primitive
41
+ * @see {@link Telemetry} - Execution tracking
42
+ *
43
+ * @module @agentick/kernel
44
+ */
45
+ export * from "./context";
46
+ export * from "./telemetry";
47
+ export * from "./otel-provider";
48
+ export * from "./procedure-graph";
49
+ export * from "./execution-tracker";
50
+ export * from "./execution-helpers";
51
+ export * from "./metrics-helpers";
52
+ export * from "./stream";
53
+ export * from "./channel";
54
+ export * from "./channel-helpers";
55
+ export * from "./procedure";
56
+ export * from "./logger";
57
+ export * from "./event-buffer";
58
+ export * from "./schema";
59
+ export * from "./guard";
60
+ export { GuardError, isGuardError } from "@agentick/shared";
61
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,62 @@
1
+ /**
2
+ * # Agentick Kernel
3
+ *
4
+ * Low-level execution primitives for the Agentick framework. The kernel provides
5
+ * the foundational infrastructure that all other Agentick packages build upon.
6
+ *
7
+ * ## Core Primitives
8
+ *
9
+ * - **Procedures** - Async function wrappers with middleware, context, and telemetry
10
+ * - **Context** - Request-scoped state with automatic propagation
11
+ * - **Channels** - Async generators for streaming with backpressure
12
+ * - **Telemetry** - Execution tracking, spans, and metrics
13
+ * - **Logger** - Structured logging with configurable levels
14
+ *
15
+ * ## When to Use Kernel Directly
16
+ *
17
+ * Most applications should use the higher-level `agentick` package. Use kernel directly when:
18
+ *
19
+ * - Building custom execution infrastructure
20
+ * - Creating new Agentick adapters or integrations
21
+ * - Need fine-grained control over procedure execution
22
+ *
23
+ * ## Example
24
+ *
25
+ * ```typescript
26
+ * import { createProcedure, Context } from './core';
27
+ *
28
+ * const myProcedure = createProcedure(
29
+ * { name: 'my-operation' },
30
+ * async (input: string) => {
31
+ * return { result: input.toUpperCase() };
32
+ * }
33
+ * );
34
+ *
35
+ * const result = await myProcedure.exec('hello');
36
+ * ```
37
+ *
38
+ * @see {@link Procedure} - The core procedure abstraction
39
+ * @see {@link KernelContext} - Request-scoped context
40
+ * @see {@link Channel} - Streaming primitive
41
+ * @see {@link Telemetry} - Execution tracking
42
+ *
43
+ * @module @agentick/kernel
44
+ */
45
+ export * from "./context";
46
+ export * from "./telemetry";
47
+ export * from "./otel-provider";
48
+ export * from "./procedure-graph";
49
+ export * from "./execution-tracker";
50
+ export * from "./execution-helpers";
51
+ export * from "./metrics-helpers";
52
+ export * from "./stream";
53
+ export * from "./channel";
54
+ export * from "./channel-helpers";
55
+ export * from "./procedure";
56
+ export * from "./logger";
57
+ export * from "./event-buffer";
58
+ export * from "./schema";
59
+ export * from "./guard";
60
+ // Re-export guard errors from shared (guards are a procedure concept)
61
+ export { GuardError, isGuardError } from "@agentick/shared";
62
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AAExB,sEAAsE;AACtE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}
@@ -0,0 +1,341 @@
1
+ /**
2
+ * Logger - Structured logging with automatic context injection
3
+ *
4
+ * Built on pino for performance, with automatic injection of:
5
+ * - Execution context (executionId, threadId, userId, tick)
6
+ * - OpenTelemetry trace/span IDs for log-trace correlation
7
+ * - Custom metadata
8
+ *
9
+ * @example
10
+ * ```typescript
11
+ * import { Logger } from './core';
12
+ *
13
+ * // Configure once at app start
14
+ * Logger.configure({
15
+ * level: 'info',
16
+ * transport: {
17
+ * targets: [
18
+ * { target: 'pino-pretty', options: { colorize: true } },
19
+ * { target: 'pino/file', options: { destination: './app.log' } },
20
+ * ],
21
+ * },
22
+ * });
23
+ *
24
+ * // Use anywhere - context is auto-injected
25
+ * const log = Logger.get();
26
+ * log.info('Processing request');
27
+ *
28
+ * // Create scoped child logger
29
+ * const toolLog = Logger.for('CalculatorTool');
30
+ * toolLog.debug('Executing', { expression: '2+2' });
31
+ * ```
32
+ */
33
+ import { type Logger as PinoLogger, type TransportSingleOptions, type TransportMultiOptions } from "pino";
34
+ import { type KernelContext } from "./context";
35
+ /**
36
+ * Log levels supported by the kernel logger.
37
+ *
38
+ * Levels in order of severity (least to most):
39
+ * - `trace` - Very detailed debugging information
40
+ * - `debug` - Debugging information
41
+ * - `info` - Normal operational messages
42
+ * - `warn` - Warning conditions
43
+ * - `error` - Error conditions
44
+ * - `fatal` - Severe errors causing shutdown
45
+ * - `silent` - Disable all logging
46
+ *
47
+ * @example
48
+ * ```typescript
49
+ * Logger.configure({ level: 'debug' });
50
+ * Logger.setLevel('warn'); // Runtime change
51
+ * if (Logger.isLevelEnabled('trace')) {
52
+ * // Expensive debug operation
53
+ * }
54
+ * ```
55
+ */
56
+ export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal" | "silent";
57
+ /**
58
+ * Function to extract fields from KernelContext for logging.
59
+ * Return an object with fields to include in every log entry.
60
+ *
61
+ * @typeParam TContext - The context type (extends KernelContext)
62
+ *
63
+ * @example
64
+ * ```typescript
65
+ * const myExtractor: ContextFieldsExtractor = (ctx) => ({
66
+ * userId: ctx.user?.id,
67
+ * tenantId: ctx.user?.tenantId,
68
+ * requestId: ctx.requestId,
69
+ * });
70
+ * ```
71
+ *
72
+ * @see {@link composeContextFields} - Combine multiple extractors
73
+ */
74
+ export type ContextFieldsExtractor<TContext extends KernelContext = KernelContext> = (ctx: TContext) => Record<string, unknown>;
75
+ export interface LoggerConfig<TContext extends KernelContext = KernelContext> {
76
+ /** Log level (default: 'info') */
77
+ level?: LogLevel;
78
+ /** Pino transport configuration */
79
+ transport?: TransportSingleOptions | TransportMultiOptions;
80
+ /** Auto-inject execution context into every log (default: true) */
81
+ includeContext?: boolean;
82
+ /**
83
+ * Custom function to extract fields from context.
84
+ * If not provided, only core KernelContext fields are extracted.
85
+ * Use this to add application-specific fields from user/metadata.
86
+ *
87
+ * @example
88
+ * ```typescript
89
+ * Logger.configure({
90
+ * contextFields: (ctx) => ({
91
+ * // Core fields (you control what's included)
92
+ * request_id: ctx.requestId,
93
+ * trace_id: ctx.traceId,
94
+ * // Your custom fields
95
+ * tenantId: ctx.user?.tenantId,
96
+ * threadId: ctx.metadata?.threadId,
97
+ * }),
98
+ * });
99
+ * ```
100
+ */
101
+ contextFields?: ContextFieldsExtractor<TContext>;
102
+ /** Base properties to include in every log */
103
+ base?: Record<string, unknown>;
104
+ /** Custom mixin function for additional properties */
105
+ mixin?: () => Record<string, unknown>;
106
+ /** Pretty print in development (default: true if NODE_ENV !== 'production') */
107
+ prettyPrint?: boolean;
108
+ /**
109
+ * Replace existing config instead of merging (default: false).
110
+ * When true, completely replaces the existing configuration.
111
+ * When false (default), merges with existing configuration.
112
+ */
113
+ replace?: boolean;
114
+ }
115
+ /**
116
+ * Log method signature supporting both message-first and object-first forms.
117
+ *
118
+ * @example Message-first (simple logging)
119
+ * ```typescript
120
+ * log.info('User logged in');
121
+ * log.info('Processed %d items', count);
122
+ * ```
123
+ *
124
+ * @example Object-first (structured logging)
125
+ * ```typescript
126
+ * log.info({ userId, action: 'login' }, 'User logged in');
127
+ * log.error({ err, requestId }, 'Request failed');
128
+ * ```
129
+ */
130
+ export interface LogMethod {
131
+ /** Log a message with optional printf-style args */
132
+ (msg: string, ...args: unknown[]): void;
133
+ /** Log structured data with optional message */
134
+ (obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
135
+ }
136
+ /**
137
+ * Kernel logger interface with structured logging and context injection.
138
+ *
139
+ * Loggers automatically inject execution context (requestId, traceId, etc.)
140
+ * from the current `KernelContext` via AsyncLocalStorage.
141
+ *
142
+ * @example
143
+ * ```typescript
144
+ * const log = Logger.get();
145
+ *
146
+ * // Simple message
147
+ * log.info('Request received');
148
+ *
149
+ * // With structured data
150
+ * log.debug({ userId, action }, 'Processing action');
151
+ *
152
+ * // Create child logger with bindings
153
+ * const reqLog = log.child({ requestId: 'abc-123' });
154
+ *
155
+ * // Check level before expensive operation
156
+ * if (log.isLevelEnabled('trace')) {
157
+ * log.trace({ fullState: getState() }, 'State dump');
158
+ * }
159
+ * ```
160
+ *
161
+ * @see {@link Logger} - Static methods to get/configure loggers
162
+ * @see {@link LogLevel} - Available log levels
163
+ */
164
+ export interface KernelLogger {
165
+ /** Log at trace level (very detailed debugging) */
166
+ trace: LogMethod;
167
+ /** Log at debug level (debugging information) */
168
+ debug: LogMethod;
169
+ /** Log at info level (normal operations) */
170
+ info: LogMethod;
171
+ /** Log at warn level (warning conditions) */
172
+ warn: LogMethod;
173
+ /** Log at error level (error conditions) */
174
+ error: LogMethod;
175
+ /** Log at fatal level (severe errors) */
176
+ fatal: LogMethod;
177
+ /** Create a child logger with additional bindings */
178
+ child(bindings: Record<string, unknown>): KernelLogger;
179
+ /** Get the current log level */
180
+ level: LogLevel;
181
+ /** Check if a level is enabled */
182
+ isLevelEnabled(level: LogLevel): boolean;
183
+ }
184
+ /**
185
+ * Logger singleton for Agentick applications.
186
+ *
187
+ * Provides structured logging with automatic context injection from the
188
+ * current execution context (via AsyncLocalStorage).
189
+ *
190
+ * @example
191
+ * ```typescript
192
+ * // Configure at app startup
193
+ * Logger.configure({ level: 'debug' });
194
+ *
195
+ * // Get logger (context auto-injected)
196
+ * const log = Logger.get();
197
+ * log.info('Request received');
198
+ *
199
+ * // Create child logger for a component
200
+ * const componentLog = Logger.for('MyComponent');
201
+ * componentLog.debug('Initializing');
202
+ *
203
+ * // Or from an object (uses constructor name)
204
+ * class MyTool {
205
+ * private log = Logger.for(this);
206
+ * }
207
+ * ```
208
+ */
209
+ export declare const Logger: {
210
+ /**
211
+ * Configure the global logger.
212
+ * Should be called once at application startup.
213
+ *
214
+ * @param config Logger configuration
215
+ *
216
+ * @example
217
+ * ```typescript
218
+ * Logger.configure({
219
+ * level: process.env.LOG_LEVEL ?? 'info',
220
+ * transport: {
221
+ * targets: [
222
+ * { target: 'pino-pretty', options: { colorize: true } },
223
+ * { target: 'pino/file', options: { destination: './logs/app.log' } },
224
+ * ],
225
+ * },
226
+ * });
227
+ * ```
228
+ */
229
+ configure(config: LoggerConfig): void;
230
+ /**
231
+ * Get the global logger instance.
232
+ * Context is automatically injected into every log.
233
+ *
234
+ * @returns KernelLogger instance
235
+ *
236
+ * @example
237
+ * ```typescript
238
+ * const log = Logger.get();
239
+ * log.info('Processing', { items: 5 });
240
+ * // Output includes executionId, userId, trace_id, etc.
241
+ * ```
242
+ */
243
+ get(): KernelLogger;
244
+ /**
245
+ * Create a child logger scoped to a component or name.
246
+ *
247
+ * @param nameOrComponent Component name or object (uses constructor.name)
248
+ * @returns Child logger with component binding
249
+ *
250
+ * @example
251
+ * ```typescript
252
+ * // With string name
253
+ * const log = Logger.for('CalculatorTool');
254
+ *
255
+ * // With object (uses class name)
256
+ * class MyAgent {
257
+ * private log = Logger.for(this);
258
+ * }
259
+ * ```
260
+ */
261
+ for(nameOrComponent: string | object): KernelLogger;
262
+ /**
263
+ * Create a child logger with custom bindings.
264
+ *
265
+ * @param bindings Key-value pairs to include in every log
266
+ * @returns Child logger with bindings
267
+ *
268
+ * @example
269
+ * ```typescript
270
+ * const requestLog = Logger.child({ request_id: req.id });
271
+ * requestLog.info('Handling request');
272
+ * ```
273
+ */
274
+ child(bindings: Record<string, unknown>): KernelLogger;
275
+ /**
276
+ * Create a standalone logger instance with custom config.
277
+ * Does not affect the global logger.
278
+ *
279
+ * @param config Logger configuration
280
+ * @returns New logger instance
281
+ *
282
+ * @example
283
+ * ```typescript
284
+ * const auditLog = Logger.create({
285
+ * level: 'info',
286
+ * transport: { target: 'pino/file', options: { destination: './audit.log' } },
287
+ * });
288
+ * ```
289
+ */
290
+ create(config?: LoggerConfig): KernelLogger;
291
+ /**
292
+ * Get the current log level.
293
+ */
294
+ readonly level: LogLevel;
295
+ /**
296
+ * Set the log level at runtime.
297
+ *
298
+ * @param level New log level
299
+ */
300
+ setLevel(level: LogLevel): void;
301
+ /**
302
+ * Check if a level is enabled.
303
+ *
304
+ * @param level Log level to check
305
+ * @returns true if the level is enabled
306
+ */
307
+ isLevelEnabled(level: LogLevel): boolean;
308
+ /**
309
+ * Reset the global logger (mainly for testing).
310
+ */
311
+ reset(): void;
312
+ };
313
+ /**
314
+ * Compose multiple context field extractors into one.
315
+ * Later extractors override earlier ones for the same keys.
316
+ *
317
+ * @example
318
+ * ```typescript
319
+ * import { composeContextFields, defaultContextFields } from './core';
320
+ *
321
+ * Logger.configure({
322
+ * contextFields: composeContextFields(
323
+ * defaultContextFields, // Core kernel fields
324
+ * (ctx) => ({ // Your custom fields
325
+ * tenantId: ctx.user?.tenantId,
326
+ * threadId: ctx.metadata?.threadId,
327
+ * executionId: ctx.metadata?.executionId,
328
+ * }),
329
+ * ),
330
+ * });
331
+ * ```
332
+ */
333
+ export declare function composeContextFields(...extractors: ContextFieldsExtractor[]): ContextFieldsExtractor;
334
+ /**
335
+ * The default context fields extractor.
336
+ * Exports core KernelContext fields only.
337
+ * Use with composeContextFields to extend.
338
+ */
339
+ export declare const defaultContextFields: ContextFieldsExtractor<KernelContext>;
340
+ export type { PinoLogger, TransportSingleOptions, TransportMultiOptions };
341
+ //# sourceMappingURL=logger.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}