@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.
- package/LICENSE +21 -0
- package/README.md +401 -0
- package/dist/.tsbuildinfo.build +1 -0
- package/dist/channel-helpers.d.ts +32 -0
- package/dist/channel-helpers.d.ts.map +1 -0
- package/dist/channel-helpers.js +62 -0
- package/dist/channel-helpers.js.map +1 -0
- package/dist/channel.d.ts +164 -0
- package/dist/channel.d.ts.map +1 -0
- package/dist/channel.js +199 -0
- package/dist/channel.js.map +1 -0
- package/dist/context.d.ts +412 -0
- package/dist/context.d.ts.map +1 -0
- package/dist/context.js +289 -0
- package/dist/context.js.map +1 -0
- package/dist/event-buffer.d.ts +208 -0
- package/dist/event-buffer.d.ts.map +1 -0
- package/dist/event-buffer.js +335 -0
- package/dist/event-buffer.js.map +1 -0
- package/dist/execution-helpers.d.ts +179 -0
- package/dist/execution-helpers.d.ts.map +1 -0
- package/dist/execution-helpers.js +212 -0
- package/dist/execution-helpers.js.map +1 -0
- package/dist/execution-tracker.d.ts +61 -0
- package/dist/execution-tracker.d.ts.map +1 -0
- package/dist/execution-tracker.js +319 -0
- package/dist/execution-tracker.js.map +1 -0
- package/dist/guard.d.ts +65 -0
- package/dist/guard.d.ts.map +1 -0
- package/dist/guard.js +15 -0
- package/dist/guard.js.map +1 -0
- package/dist/index.d.ts +61 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +62 -0
- package/dist/index.js.map +1 -0
- package/dist/logger.d.ts +341 -0
- package/dist/logger.d.ts.map +1 -0
- package/dist/logger.js +346 -0
- package/dist/logger.js.map +1 -0
- package/dist/metrics-helpers.d.ts +40 -0
- package/dist/metrics-helpers.d.ts.map +1 -0
- package/dist/metrics-helpers.js +72 -0
- package/dist/metrics-helpers.js.map +1 -0
- package/dist/otel-provider.d.ts +54 -0
- package/dist/otel-provider.d.ts.map +1 -0
- package/dist/otel-provider.js +107 -0
- package/dist/otel-provider.js.map +1 -0
- package/dist/procedure-graph.d.ts +136 -0
- package/dist/procedure-graph.d.ts.map +1 -0
- package/dist/procedure-graph.js +272 -0
- package/dist/procedure-graph.js.map +1 -0
- package/dist/procedure.d.ts +757 -0
- package/dist/procedure.d.ts.map +1 -0
- package/dist/procedure.js +895 -0
- package/dist/procedure.js.map +1 -0
- package/dist/schema.d.ts +153 -0
- package/dist/schema.d.ts.map +1 -0
- package/dist/schema.js +385 -0
- package/dist/schema.js.map +1 -0
- package/dist/stream.d.ts +106 -0
- package/dist/stream.d.ts.map +1 -0
- package/dist/stream.js +186 -0
- package/dist/stream.js.map +1 -0
- package/dist/telemetry.d.ts +182 -0
- package/dist/telemetry.d.ts.map +1 -0
- package/dist/telemetry.js +124 -0
- package/dist/telemetry.js.map +1 -0
- package/dist/testing.d.ts +55 -0
- package/dist/testing.d.ts.map +1 -0
- package/dist/testing.js +96 -0
- package/dist/testing.js.map +1 -0
- package/package.json +48 -0
package/dist/guard.d.ts
ADDED
|
@@ -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"}
|
package/dist/index.d.ts
ADDED
|
@@ -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"}
|
package/dist/logger.d.ts
ADDED
|
@@ -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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"}
|