@agnt5/sdk 0.2.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 (126) hide show
  1. package/README.md +183 -0
  2. package/dist/__tests__/integration/helpers.d.ts +41 -0
  3. package/dist/__tests__/integration/helpers.d.ts.map +1 -0
  4. package/dist/__tests__/integration/helpers.js +78 -0
  5. package/dist/__tests__/integration/helpers.js.map +1 -0
  6. package/dist/agent.d.ts +260 -0
  7. package/dist/agent.d.ts.map +1 -0
  8. package/dist/agent.js +493 -0
  9. package/dist/agent.js.map +1 -0
  10. package/dist/async-context.d.ts +57 -0
  11. package/dist/async-context.d.ts.map +1 -0
  12. package/dist/async-context.js +52 -0
  13. package/dist/async-context.js.map +1 -0
  14. package/dist/batch.d.ts +116 -0
  15. package/dist/batch.d.ts.map +1 -0
  16. package/dist/batch.js +98 -0
  17. package/dist/batch.js.map +1 -0
  18. package/dist/chat.d.ts +137 -0
  19. package/dist/chat.d.ts.map +1 -0
  20. package/dist/chat.js +278 -0
  21. package/dist/chat.js.map +1 -0
  22. package/dist/client.d.ts +394 -0
  23. package/dist/client.d.ts.map +1 -0
  24. package/dist/client.js +757 -0
  25. package/dist/client.js.map +1 -0
  26. package/dist/context.d.ts +47 -0
  27. package/dist/context.d.ts.map +1 -0
  28. package/dist/context.js +244 -0
  29. package/dist/context.js.map +1 -0
  30. package/dist/errors.d.ts +148 -0
  31. package/dist/errors.d.ts.map +1 -0
  32. package/dist/errors.js +201 -0
  33. package/dist/errors.js.map +1 -0
  34. package/dist/eval.d.ts +242 -0
  35. package/dist/eval.d.ts.map +1 -0
  36. package/dist/eval.js +452 -0
  37. package/dist/eval.js.map +1 -0
  38. package/dist/event-emitter.d.ts +28 -0
  39. package/dist/event-emitter.d.ts.map +1 -0
  40. package/dist/event-emitter.js +79 -0
  41. package/dist/event-emitter.js.map +1 -0
  42. package/dist/events.d.ts +285 -0
  43. package/dist/events.d.ts.map +1 -0
  44. package/dist/events.js +256 -0
  45. package/dist/events.js.map +1 -0
  46. package/dist/function.d.ts +61 -0
  47. package/dist/function.d.ts.map +1 -0
  48. package/dist/function.js +78 -0
  49. package/dist/function.js.map +1 -0
  50. package/dist/index.d.ts +67 -0
  51. package/dist/index.d.ts.map +1 -0
  52. package/dist/index.js +80 -0
  53. package/dist/index.js.map +1 -0
  54. package/dist/lm.d.ts +301 -0
  55. package/dist/lm.d.ts.map +1 -0
  56. package/dist/lm.js +283 -0
  57. package/dist/lm.js.map +1 -0
  58. package/dist/logging.d.ts +68 -0
  59. package/dist/logging.d.ts.map +1 -0
  60. package/dist/logging.js +165 -0
  61. package/dist/logging.js.map +1 -0
  62. package/dist/mcp-server.d.ts +98 -0
  63. package/dist/mcp-server.d.ts.map +1 -0
  64. package/dist/mcp-server.js +307 -0
  65. package/dist/mcp-server.js.map +1 -0
  66. package/dist/mcp.d.ts +73 -0
  67. package/dist/mcp.d.ts.map +1 -0
  68. package/dist/mcp.js +224 -0
  69. package/dist/mcp.js.map +1 -0
  70. package/dist/memory.d.ts +234 -0
  71. package/dist/memory.d.ts.map +1 -0
  72. package/dist/memory.js +609 -0
  73. package/dist/memory.js.map +1 -0
  74. package/dist/platform-adapters.d.ts +121 -0
  75. package/dist/platform-adapters.d.ts.map +1 -0
  76. package/dist/platform-adapters.js +174 -0
  77. package/dist/platform-adapters.js.map +1 -0
  78. package/dist/platform-context.d.ts +55 -0
  79. package/dist/platform-context.d.ts.map +1 -0
  80. package/dist/platform-context.js +196 -0
  81. package/dist/platform-context.js.map +1 -0
  82. package/dist/retry-utils.d.ts +169 -0
  83. package/dist/retry-utils.d.ts.map +1 -0
  84. package/dist/retry-utils.js +304 -0
  85. package/dist/retry-utils.js.map +1 -0
  86. package/dist/sandbox.d.ts +103 -0
  87. package/dist/sandbox.d.ts.map +1 -0
  88. package/dist/sandbox.js +168 -0
  89. package/dist/sandbox.js.map +1 -0
  90. package/dist/schema-utils.d.ts +250 -0
  91. package/dist/schema-utils.d.ts.map +1 -0
  92. package/dist/schema-utils.js +444 -0
  93. package/dist/schema-utils.js.map +1 -0
  94. package/dist/scorer.d.ts +130 -0
  95. package/dist/scorer.d.ts.map +1 -0
  96. package/dist/scorer.js +211 -0
  97. package/dist/scorer.js.map +1 -0
  98. package/dist/state.d.ts +92 -0
  99. package/dist/state.d.ts.map +1 -0
  100. package/dist/state.js +151 -0
  101. package/dist/state.js.map +1 -0
  102. package/dist/tool.d.ts +120 -0
  103. package/dist/tool.d.ts.map +1 -0
  104. package/dist/tool.js +215 -0
  105. package/dist/tool.js.map +1 -0
  106. package/dist/tracing.d.ts +82 -0
  107. package/dist/tracing.d.ts.map +1 -0
  108. package/dist/tracing.js +206 -0
  109. package/dist/tracing.js.map +1 -0
  110. package/dist/types.d.ts +139 -0
  111. package/dist/types.d.ts.map +1 -0
  112. package/dist/types.js +2 -0
  113. package/dist/types.js.map +1 -0
  114. package/dist/worker.d.ts +111 -0
  115. package/dist/worker.d.ts.map +1 -0
  116. package/dist/worker.js +944 -0
  117. package/dist/worker.js.map +1 -0
  118. package/dist/workflow-utils.d.ts +257 -0
  119. package/dist/workflow-utils.d.ts.map +1 -0
  120. package/dist/workflow-utils.js +370 -0
  121. package/dist/workflow-utils.js.map +1 -0
  122. package/dist/workflow.d.ts +78 -0
  123. package/dist/workflow.d.ts.map +1 -0
  124. package/dist/workflow.js +138 -0
  125. package/dist/workflow.js.map +1 -0
  126. package/package.json +86 -0
package/dist/tool.js ADDED
@@ -0,0 +1,215 @@
1
+ /**
2
+ * Tool component for Agent capabilities.
3
+ *
4
+ * Tools wrap functions with structured interfaces for agent invocation.
5
+ * Phase 1: In-memory execution with basic schema support
6
+ * Phase 2: Platform integration with durable execution
7
+ */
8
+ import { ConfigurationError } from './errors.js';
9
+ /**
10
+ * Tool class representing a callable tool for agents
11
+ */
12
+ export class Tool {
13
+ constructor(name, description, handler, options = {}) {
14
+ this.name = name;
15
+ this.description = description;
16
+ this.handler = handler;
17
+ this.confirmation = options.confirmation || false;
18
+ // Use provided schema or create default
19
+ this.inputSchema = options.inputSchema || {
20
+ type: 'object',
21
+ properties: {},
22
+ required: []
23
+ };
24
+ }
25
+ /**
26
+ * Invoke the tool with given arguments
27
+ */
28
+ async invoke(ctx, args) {
29
+ if (this.confirmation) {
30
+ ctx.logger.warn(`Tool '${this.name}' requires confirmation but confirmation is not implemented in Phase 1`);
31
+ }
32
+ ctx.logger.debug(`Invoking tool '${this.name}' with args: ${Object.keys(args).join(', ')}`);
33
+ // Execute handler
34
+ const result = await this.handler(ctx, args);
35
+ ctx.logger.debug(`Tool '${this.name}' completed successfully`);
36
+ return result;
37
+ }
38
+ /**
39
+ * Get complete tool schema for agent consumption
40
+ */
41
+ getSchema() {
42
+ return {
43
+ name: this.name,
44
+ description: this.description,
45
+ input_schema: this.inputSchema,
46
+ requires_confirmation: this.confirmation
47
+ };
48
+ }
49
+ }
50
+ /**
51
+ * Global registry for tools
52
+ */
53
+ export class ToolRegistry {
54
+ /**
55
+ * Register a tool
56
+ */
57
+ static register(tool) {
58
+ if (this.tools.has(tool.name)) {
59
+ console.warn(`Overwriting existing tool '${tool.name}'`);
60
+ }
61
+ this.tools.set(tool.name, tool);
62
+ }
63
+ /**
64
+ * Get a tool by name
65
+ */
66
+ static get(name) {
67
+ return this.tools.get(name);
68
+ }
69
+ /**
70
+ * Get all registered tools
71
+ */
72
+ static all() {
73
+ return new Map(this.tools);
74
+ }
75
+ /**
76
+ * List all tool names
77
+ */
78
+ static listNames() {
79
+ return Array.from(this.tools.keys());
80
+ }
81
+ /**
82
+ * Clear all registered tools (for testing)
83
+ */
84
+ static clear() {
85
+ this.tools.clear();
86
+ }
87
+ }
88
+ ToolRegistry.tools = new Map();
89
+ /**
90
+ * Decorator to mark a function as a tool
91
+ *
92
+ * @example
93
+ * ```typescript
94
+ * const searchWeb = tool('search_web', {
95
+ * description: 'Search the web for information',
96
+ * inputSchema: {
97
+ * type: 'object',
98
+ * properties: {
99
+ * query: { type: 'string', description: 'Search query' },
100
+ * maxResults: { type: 'integer', description: 'Max results' }
101
+ * },
102
+ * required: ['query']
103
+ * }
104
+ * }, async (ctx, args) => {
105
+ * const { query, maxResults = 10 } = args;
106
+ * // Implementation
107
+ * return results;
108
+ * });
109
+ * ```
110
+ */
111
+ export function tool(name, options, handler) {
112
+ // Extract description
113
+ const description = options.description || name;
114
+ // Create Tool instance
115
+ const toolInstance = new Tool(name, description, handler, options);
116
+ // Register tool
117
+ ToolRegistry.register(toolInstance);
118
+ // Return wrapper that can invoke tool
119
+ const toolWrapper = async (ctx, ...args) => {
120
+ // If called with object args, use tool.invoke
121
+ if (args.length === 1 && typeof args[0] === 'object' && args[0] !== null) {
122
+ return toolInstance.invoke(ctx, args[0]);
123
+ }
124
+ // Otherwise, direct call
125
+ return toolInstance.handler(ctx, ...args);
126
+ };
127
+ // Attach tool instance for inspection
128
+ toolWrapper._tool = toolInstance;
129
+ return toolWrapper;
130
+ }
131
+ // ─── Built-in Human-in-the-Loop Tools ────────────────────────────────
132
+ /**
133
+ * Built-in tool that agents can use to request text input from users.
134
+ *
135
+ * Pauses workflow execution and waits for the user to provide a text response.
136
+ *
137
+ * @example
138
+ * ```typescript
139
+ * const agent = new Agent({
140
+ * name: 'research_agent',
141
+ * model: LM.openai(),
142
+ * instructions: 'You are a research assistant.',
143
+ * tools: [new AskUserTool(wfCtx)],
144
+ * });
145
+ * ```
146
+ */
147
+ export class AskUserTool extends Tool {
148
+ constructor(context) {
149
+ if (!context || typeof context.waitForUser !== 'function') {
150
+ throw new ConfigurationError('AskUserTool requires a ContextImpl with waitForUser. ' +
151
+ 'This tool can only be used within workflows.');
152
+ }
153
+ const wfContext = context;
154
+ super('ask_user', 'Ask the user a question and wait for their text response', async (_ctx, args) => {
155
+ const question = typeof args === 'string' ? args : args.question;
156
+ return wfContext.waitForUser(question, { inputType: 'text' });
157
+ }, {
158
+ inputSchema: {
159
+ type: 'object',
160
+ properties: {
161
+ question: { type: 'string', description: 'Question to ask the user' },
162
+ },
163
+ required: ['question'],
164
+ },
165
+ });
166
+ }
167
+ }
168
+ /**
169
+ * Built-in tool that agents can use to request approval from users.
170
+ *
171
+ * Pauses workflow execution and presents approve/reject options to the user.
172
+ *
173
+ * @example
174
+ * ```typescript
175
+ * const agent = new Agent({
176
+ * name: 'deploy_agent',
177
+ * model: LM.openai(),
178
+ * instructions: 'You help deploy code changes safely.',
179
+ * tools: [new RequestApprovalTool(wfCtx)],
180
+ * });
181
+ * ```
182
+ */
183
+ export class RequestApprovalTool extends Tool {
184
+ constructor(context) {
185
+ if (!context || typeof context.waitForUser !== 'function') {
186
+ throw new ConfigurationError('RequestApprovalTool requires a ContextImpl with waitForUser. ' +
187
+ 'This tool can only be used within workflows.');
188
+ }
189
+ const wfContext = context;
190
+ super('request_approval', 'Request user approval for an action before proceeding', async (_ctx, args) => {
191
+ let question = `Action: ${args.action}`;
192
+ if (args.details) {
193
+ question += `\n\nDetails:\n${args.details}`;
194
+ }
195
+ question += '\n\nDo you approve?';
196
+ return wfContext.waitForUser(question, {
197
+ inputType: 'approval',
198
+ options: [
199
+ { id: 'approve', label: 'Approve' },
200
+ { id: 'reject', label: 'Reject' },
201
+ ],
202
+ });
203
+ }, {
204
+ inputSchema: {
205
+ type: 'object',
206
+ properties: {
207
+ action: { type: 'string', description: 'The action requiring approval' },
208
+ details: { type: 'string', description: 'Additional details about the action' },
209
+ },
210
+ required: ['action'],
211
+ },
212
+ });
213
+ }
214
+ }
215
+ //# sourceMappingURL=tool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Tracing utilities for AGNT5 components.
3
+ *
4
+ * Provides span creation and context propagation using AsyncLocalStorage.
5
+ * When NAPI bindings are available, creates real OpenTelemetry spans via
6
+ * sdk-core. Falls back to log-only when NAPI is unavailable.
7
+ */
8
+ export interface SpanInfo {
9
+ traceId: string;
10
+ spanId: string;
11
+ }
12
+ /** Get the current span info (if inside a span scope) */
13
+ export declare function getCurrentSpanInfo(): SpanInfo | undefined;
14
+ /**
15
+ * Represents an active tracing span.
16
+ *
17
+ * When NAPI bindings are available, this wraps a real OpenTelemetry span
18
+ * exported via OTLP. Otherwise, operates as a lightweight in-process span
19
+ * with attribute tracking and duration measurement.
20
+ */
21
+ export declare class Span {
22
+ readonly traceId: string;
23
+ readonly spanId: string;
24
+ readonly name: string;
25
+ readonly componentType: string;
26
+ readonly parentSpanId: string | null;
27
+ private _nativeSpan;
28
+ private _attributes;
29
+ private _startTime;
30
+ private _endTime;
31
+ constructor(name: string, componentType: string, parentInfo?: SpanInfo, attributes?: Record<string, string>);
32
+ /** Set an attribute on this span */
33
+ setAttribute(key: string, value: string): void;
34
+ /** Record an exception on this span */
35
+ recordException(error: Error): void;
36
+ /** End the span (records duration, exports via OTLP if available) */
37
+ end(): void;
38
+ /** Duration in milliseconds (undefined if span not ended) */
39
+ get durationMs(): number | undefined;
40
+ get attributes(): Record<string, string>;
41
+ }
42
+ /**
43
+ * Execute a function within a new tracing span.
44
+ *
45
+ * Automatically sets the span as current context for nested spans,
46
+ * records exceptions, and ends the span when the function completes.
47
+ *
48
+ * @example
49
+ * ```typescript
50
+ * const result = await withSpan('db-query', async (span) => {
51
+ * span.setAttribute('table', 'users');
52
+ * return await db.query('SELECT * FROM users');
53
+ * });
54
+ * ```
55
+ */
56
+ export declare function withSpan<T>(name: string, fn: (span: Span) => T | Promise<T>, options?: {
57
+ componentType?: string;
58
+ attributes?: Record<string, string>;
59
+ }): Promise<T>;
60
+ /**
61
+ * Create a span and return it for manual control.
62
+ * The span is set as the current context for nested operations.
63
+ */
64
+ export declare function spanContext(name: string, options?: {
65
+ componentType?: string;
66
+ attributes?: Record<string, string>;
67
+ }): Span;
68
+ /**
69
+ * Decorator factory that wraps an async function in a tracing span.
70
+ *
71
+ * @example
72
+ * ```typescript
73
+ * const processOrder = span('process-order')(async (orderId: string) => {
74
+ * // ... function body automatically traced ...
75
+ * });
76
+ * ```
77
+ */
78
+ export declare function span(name?: string, options?: {
79
+ componentType?: string;
80
+ attributes?: Record<string, string>;
81
+ }): <T extends (...args: any[]) => Promise<any>>(fn: T) => T;
82
+ //# sourceMappingURL=tracing.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tracing.d.ts","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA8CH,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,yDAAyD;AACzD,wBAAgB,kBAAkB,IAAI,QAAQ,GAAG,SAAS,CAEzD;AAID;;;;;;GAMG;AACH,qBAAa,IAAI;IACf,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,OAAO,CAAC,WAAW,CAAa;IAChC,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAuB;gBAGrC,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,UAAU,CAAC,EAAE,QAAQ,EACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAmDrC,oCAAoC;IACpC,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAO9C,uCAAuC;IACvC,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAQnC,qEAAqE;IACrE,GAAG,IAAI,IAAI;IAQX,6DAA6D;IAC7D,IAAI,UAAU,IAAI,MAAM,GAAG,SAAS,CAGnC;IAED,IAAI,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEvC;CACF;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAClC,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACxE,OAAO,CAAC,CAAC,CAAC,CAoBZ;AAID;;;GAGG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACxE,IAAI,CAQN;AAID;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAClB,IAAI,CAAC,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACxE,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,KAAK,CAAC,CAY1D"}
@@ -0,0 +1,206 @@
1
+ /**
2
+ * Tracing utilities for AGNT5 components.
3
+ *
4
+ * Provides span creation and context propagation using AsyncLocalStorage.
5
+ * When NAPI bindings are available, creates real OpenTelemetry spans via
6
+ * sdk-core. Falls back to log-only when NAPI is unavailable.
7
+ */
8
+ import { AsyncLocalStorage } from 'async_hooks';
9
+ import { randomUUID } from 'crypto';
10
+ import { createRequire } from 'module';
11
+ import { fileURLToPath } from 'url';
12
+ import { dirname, join } from 'path';
13
+ // ─── NAPI binding loader ─────────────────────────────────────────────
14
+ let nativeBindings = null;
15
+ let napiAvailable = false;
16
+ function tryLoadNapi() {
17
+ if (nativeBindings !== null)
18
+ return nativeBindings;
19
+ try {
20
+ const __filename = fileURLToPath(import.meta.url);
21
+ const __dirname = dirname(__filename);
22
+ const require = createRequire(import.meta.url);
23
+ const possiblePaths = [
24
+ join(__dirname, '../../native/agnt5-sdk-native.darwin-arm64.node'),
25
+ join(__dirname, '../native/agnt5-sdk-native.darwin-arm64.node'),
26
+ join(__dirname, '../../native/agnt5-sdk-native.linux-x64-gnu.node'),
27
+ join(__dirname, '../native/agnt5-sdk-native.linux-x64-gnu.node'),
28
+ ];
29
+ for (const nativePath of possiblePaths) {
30
+ try {
31
+ nativeBindings = require(nativePath);
32
+ napiAvailable = true;
33
+ return nativeBindings;
34
+ }
35
+ catch {
36
+ continue;
37
+ }
38
+ }
39
+ }
40
+ catch {
41
+ // NAPI not available — fall back to log-only
42
+ }
43
+ nativeBindings = false; // Mark as attempted
44
+ return null;
45
+ }
46
+ const spanStorage = new AsyncLocalStorage();
47
+ /** Get the current span info (if inside a span scope) */
48
+ export function getCurrentSpanInfo() {
49
+ return spanStorage.getStore();
50
+ }
51
+ // ─── Span class ──────────────────────────────────────────────────────
52
+ /**
53
+ * Represents an active tracing span.
54
+ *
55
+ * When NAPI bindings are available, this wraps a real OpenTelemetry span
56
+ * exported via OTLP. Otherwise, operates as a lightweight in-process span
57
+ * with attribute tracking and duration measurement.
58
+ */
59
+ export class Span {
60
+ constructor(name, componentType, parentInfo, attributes) {
61
+ this._nativeSpan = null;
62
+ this._attributes = {};
63
+ this._endTime = null;
64
+ this.name = name;
65
+ this.componentType = componentType;
66
+ this.parentSpanId = parentInfo?.spanId || null;
67
+ this._startTime = Date.now();
68
+ if (attributes) {
69
+ this._attributes = { ...attributes };
70
+ }
71
+ // Try to create a real OTel span via NAPI
72
+ const bindings = tryLoadNapi();
73
+ if (bindings && bindings.Span) {
74
+ try {
75
+ // Only pass parent IDs to NAPI if they look like valid hex (OTel format)
76
+ const parentTraceId = parentInfo?.traceId && /^[0-9a-f]{16,32}$/i.test(parentInfo.traceId)
77
+ ? parentInfo.traceId : null;
78
+ const parentSpanId = parentInfo?.spanId && /^[0-9a-f]{16}$/i.test(parentInfo.spanId)
79
+ ? parentInfo.spanId : null;
80
+ this._nativeSpan = bindings.Span.create(name, componentType, parentTraceId, parentSpanId, attributes || null);
81
+ const napiTraceId = this._nativeSpan.traceId;
82
+ const napiSpanId = this._nativeSpan.spanId;
83
+ if (napiTraceId && napiSpanId) {
84
+ // Real OTel IDs from initialized telemetry
85
+ this.traceId = napiTraceId;
86
+ this.spanId = napiSpanId;
87
+ }
88
+ else {
89
+ // NAPI span created but telemetry not initialized — use JS-level IDs
90
+ this.traceId = parentInfo?.traceId || randomUUID();
91
+ this.spanId = randomUUID();
92
+ }
93
+ return;
94
+ }
95
+ catch {
96
+ // Fall through to log-only
97
+ }
98
+ }
99
+ // Fallback: generate local IDs
100
+ this.traceId = parentInfo?.traceId || randomUUID();
101
+ this.spanId = randomUUID();
102
+ }
103
+ /** Set an attribute on this span */
104
+ setAttribute(key, value) {
105
+ this._attributes[key] = value;
106
+ if (this._nativeSpan) {
107
+ try {
108
+ this._nativeSpan.setAttribute(key, value);
109
+ }
110
+ catch { /* ignore */ }
111
+ }
112
+ }
113
+ /** Record an exception on this span */
114
+ recordException(error) {
115
+ this._attributes['error.type'] = error.name;
116
+ this._attributes['error.message'] = error.message;
117
+ if (this._nativeSpan) {
118
+ try {
119
+ this._nativeSpan.recordError(error.message);
120
+ }
121
+ catch { /* ignore */ }
122
+ }
123
+ }
124
+ /** End the span (records duration, exports via OTLP if available) */
125
+ end() {
126
+ this._endTime = Date.now();
127
+ if (this._nativeSpan) {
128
+ try {
129
+ this._nativeSpan.end();
130
+ }
131
+ catch { /* ignore */ }
132
+ this._nativeSpan = null;
133
+ }
134
+ }
135
+ /** Duration in milliseconds (undefined if span not ended) */
136
+ get durationMs() {
137
+ if (this._endTime === null)
138
+ return undefined;
139
+ return this._endTime - this._startTime;
140
+ }
141
+ get attributes() {
142
+ return { ...this._attributes };
143
+ }
144
+ }
145
+ // ─── withSpan ────────────────────────────────────────────────────────
146
+ /**
147
+ * Execute a function within a new tracing span.
148
+ *
149
+ * Automatically sets the span as current context for nested spans,
150
+ * records exceptions, and ends the span when the function completes.
151
+ *
152
+ * @example
153
+ * ```typescript
154
+ * const result = await withSpan('db-query', async (span) => {
155
+ * span.setAttribute('table', 'users');
156
+ * return await db.query('SELECT * FROM users');
157
+ * });
158
+ * ```
159
+ */
160
+ export async function withSpan(name, fn, options) {
161
+ const parentInfo = getCurrentSpanInfo();
162
+ const span = new Span(name, options?.componentType || 'operation', parentInfo, options?.attributes);
163
+ const spanInfo = { traceId: span.traceId, spanId: span.spanId };
164
+ try {
165
+ const result = await spanStorage.run(spanInfo, () => fn(span));
166
+ span.end();
167
+ return result;
168
+ }
169
+ catch (error) {
170
+ span.recordException(error);
171
+ span.end();
172
+ throw error;
173
+ }
174
+ }
175
+ // ─── spanContext ─────────────────────────────────────────────────────
176
+ /**
177
+ * Create a span and return it for manual control.
178
+ * The span is set as the current context for nested operations.
179
+ */
180
+ export function spanContext(name, options) {
181
+ const parentInfo = getCurrentSpanInfo();
182
+ return new Span(name, options?.componentType || 'operation', parentInfo, options?.attributes);
183
+ }
184
+ // ─── span decorator ─────────────────────────────────────────────────
185
+ /**
186
+ * Decorator factory that wraps an async function in a tracing span.
187
+ *
188
+ * @example
189
+ * ```typescript
190
+ * const processOrder = span('process-order')(async (orderId: string) => {
191
+ * // ... function body automatically traced ...
192
+ * });
193
+ * ```
194
+ */
195
+ export function span(name, options) {
196
+ return (fn) => {
197
+ const spanName = name || fn.name || 'anonymous';
198
+ const wrapped = async function (...args) {
199
+ return withSpan(spanName, () => fn.apply(this, args), options);
200
+ };
201
+ // Preserve the original function name
202
+ Object.defineProperty(wrapped, 'name', { value: fn.name });
203
+ return wrapped;
204
+ };
205
+ }
206
+ //# sourceMappingURL=tracing.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tracing.js","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,139 @@
1
+ /**
2
+ * Retry policy configuration for functions
3
+ */
4
+ export interface RetryPolicy {
5
+ /** Maximum number of retry attempts */
6
+ maxAttempts?: number;
7
+ /** Initial delay before first retry in milliseconds */
8
+ initialIntervalMs?: number;
9
+ /** Maximum delay between retries in milliseconds */
10
+ maxIntervalMs?: number;
11
+ }
12
+ /**
13
+ * Backoff strategy for retries
14
+ */
15
+ export interface BackoffPolicy {
16
+ /** Type of backoff strategy */
17
+ type: 'constant' | 'linear' | 'exponential';
18
+ /** Multiplier for exponential/linear backoff */
19
+ multiplier?: number;
20
+ }
21
+ /**
22
+ * Configuration options for function definitions
23
+ */
24
+ export interface FunctionOptions {
25
+ /** Optional custom name for the function */
26
+ name?: string;
27
+ /** Retry policy configuration */
28
+ retries?: RetryPolicy;
29
+ /** Backoff strategy for retries */
30
+ backoff?: BackoffPolicy;
31
+ /** Timeout in milliseconds for function execution */
32
+ timeout_ms?: number;
33
+ }
34
+ /**
35
+ * Function handler type
36
+ * @template TInput - Input parameter types
37
+ * @template TOutput - Return type
38
+ */
39
+ export type FunctionHandler<TInput = any, TOutput = any> = (ctx: Context, ...args: TInput[]) => Promise<TOutput> | TOutput;
40
+ /**
41
+ * Execution context provided to all AGNT5 components
42
+ *
43
+ * BREAKING CHANGE: State methods are now async to support durable storage
44
+ */
45
+ export interface Context {
46
+ /** Unique invocation identifier */
47
+ readonly invocationId: string;
48
+ /** Workflow/run identifier */
49
+ readonly runId: string;
50
+ /** Current retry attempt number (0-indexed) */
51
+ readonly attempt: number;
52
+ /** Service name */
53
+ readonly serviceName: string;
54
+ /** Get value from state (async) */
55
+ get<T>(key: string, defaultValue?: T): Promise<T | undefined>;
56
+ /** Set value in state (async) */
57
+ set<T>(key: string, value: T): Promise<void>;
58
+ /** Delete key from state (async) */
59
+ delete(key: string): Promise<boolean>;
60
+ /** Execute and checkpoint a step */
61
+ step<T>(stepName: string, fn: () => T | Promise<T>): Promise<T>;
62
+ /** Structured logger */
63
+ readonly logger: Logger;
64
+ /** Emit an event to the platform (no-op when running locally without a worker) */
65
+ emit(event: any): Promise<void>;
66
+ }
67
+ /**
68
+ * Structured logger interface
69
+ */
70
+ export interface Logger {
71
+ /** Log informational message */
72
+ info(message: string, meta?: Record<string, any>): void;
73
+ /** Log error message */
74
+ error(message: string, meta?: Record<string, any>): void;
75
+ /** Log warning message */
76
+ warn(message: string, meta?: Record<string, any>): void;
77
+ /** Log debug message */
78
+ debug(message: string, meta?: Record<string, any>): void;
79
+ }
80
+ /**
81
+ * Worker configuration options
82
+ */
83
+ export interface WorkerOptions {
84
+ /** Runtime mode */
85
+ runtime?: 'standalone' | 'managed';
86
+ }
87
+ /**
88
+ * JSON Schema type definitions
89
+ */
90
+ export interface JSONSchema {
91
+ type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
92
+ description?: string;
93
+ properties?: Record<string, JSONSchema>;
94
+ required?: string[];
95
+ items?: JSONSchema;
96
+ enum?: any[];
97
+ const?: any;
98
+ anyOf?: JSONSchema[];
99
+ allOf?: JSONSchema[];
100
+ oneOf?: JSONSchema[];
101
+ [key: string]: any;
102
+ }
103
+ /**
104
+ * Tool handler function type
105
+ */
106
+ export type ToolHandler<TInput = any, TOutput = any> = (ctx: Context, ...args: any[]) => Promise<TOutput> | TOutput;
107
+ /**
108
+ * Tool definition schema for agents
109
+ */
110
+ export interface ToolSchema {
111
+ name: string;
112
+ description: string;
113
+ input_schema: JSONSchema;
114
+ requires_confirmation?: boolean;
115
+ }
116
+ /**
117
+ * Tool configuration options
118
+ */
119
+ export interface ToolOptions {
120
+ /** Custom tool name (defaults to function name) */
121
+ name?: string;
122
+ /** Tool description for agents */
123
+ description?: string;
124
+ /** Manually specified input schema */
125
+ inputSchema?: JSONSchema;
126
+ /** Automatically extract schema from function signature */
127
+ autoSchema?: boolean;
128
+ /** Require confirmation before execution */
129
+ confirmation?: boolean;
130
+ }
131
+ /**
132
+ * Entity method handler type
133
+ */
134
+ export type EntityMethod<TInput = any, TOutput = any> = (ctx: Context, ...args: any[]) => Promise<TOutput> | TOutput;
135
+ /**
136
+ * Workflow handler type
137
+ */
138
+ export type WorkflowHandler<TInput = any, TOutput = any> = (ctx: Context, input: TInput) => Promise<TOutput> | TOutput;
139
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
package/dist/types.js ADDED
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=types.js.map