@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/README.md ADDED
@@ -0,0 +1,183 @@
1
+ # AGNT5 TypeScript SDK
2
+
3
+ Durable AI workflows and agents for TypeScript.
4
+
5
+ ## Features
6
+
7
+ - ✅ **Durable Functions** - Automatic retry with configurable policies
8
+ - ✅ **Checkpointing** - Resume from last successful step on failure
9
+ - ✅ **Multi-Runtime** - Works on Node.js, Bun, Deno, and Edge runtimes
10
+ - ✅ **Type-Safe** - Full TypeScript support with type inference
11
+ - 🔄 **Phase 1** - Local execution (current)
12
+ - 📋 **Phase 2** - Platform integration (coming soon)
13
+
14
+ ## Installation
15
+
16
+ ```bash
17
+ npm install @agnt5/sdk
18
+ # or
19
+ yarn add @agnt5/sdk
20
+ # or
21
+ pnpm add @agnt5/sdk
22
+ ```
23
+
24
+ ## Quick Start
25
+
26
+ ### Define a Function
27
+
28
+ ```typescript
29
+ import { fn } from '@agnt5/sdk';
30
+
31
+ export const greet = fn('greet').run(async (ctx, name: string) => {
32
+ ctx.logger.info(`Greeting ${name}`);
33
+ return `Hello, ${name}!`;
34
+ });
35
+ ```
36
+
37
+ ### With Retry and Backoff
38
+
39
+ ```typescript
40
+ import { fn } from '@agnt5/sdk';
41
+
42
+ export const processData = fn('process-data')
43
+ .retry({ maxAttempts: 3, initialIntervalMs: 1000 })
44
+ .backoff({ type: 'exponential', multiplier: 2.0 })
45
+ .run(async (ctx, data: DataInput) => {
46
+ // Your processing logic here
47
+ return { processed: true };
48
+ });
49
+ ```
50
+
51
+ ### With Checkpointing
52
+
53
+ ```typescript
54
+ import { fn } from '@agnt5/sdk';
55
+
56
+ export const dataPipeline = fn('data-pipeline').run(async (ctx, datasetId: string) => {
57
+ // Step 1: Load data (checkpointed)
58
+ const data = await ctx.step('load', () => loadData(datasetId));
59
+
60
+ // Step 2: Transform (checkpointed)
61
+ const transformed = await ctx.step('transform', () => transform(data));
62
+
63
+ // Step 3: Validate (checkpointed)
64
+ const validated = await ctx.step('validate', () => validate(transformed));
65
+
66
+ return { success: true, records: validated.length };
67
+ });
68
+ ```
69
+
70
+ ### Create a Worker
71
+
72
+ ```typescript
73
+ import { Worker } from '@agnt5/sdk';
74
+ import './functions'; // Import your function definitions
75
+
76
+ const worker = new Worker('my-service');
77
+ await worker.run();
78
+ ```
79
+
80
+ ## Runtime Support
81
+
82
+ The SDK automatically detects and adapts to your runtime:
83
+
84
+ | Runtime | Binding | Performance | Status |
85
+ |---------|---------|-------------|---------|
86
+ | Node.js | NAPI (native) | ⚡ Fastest | ✅ Supported |
87
+ | Bun | NAPI (native) | ⚡ Fastest | ✅ Supported |
88
+ | Deno | NAPI (compat) | ⚡ Fastest | ✅ Supported |
89
+ | Cloudflare Workers | WASM | 🔥 Fast | 📋 Phase 2 |
90
+ | Vercel Edge | WASM | 🔥 Fast | 📋 Phase 2 |
91
+ | Next.js Edge | WASM | 🔥 Fast | 📋 Phase 2 |
92
+
93
+ No configuration needed - the right binding is automatically selected!
94
+
95
+ ## Documentation
96
+
97
+ - [Overview](./docs/overview.md) - SDK architecture and concepts
98
+ - [Function Component](./docs/function.md) - Durable functions API
99
+ - [Context API](./docs/context.md) - Execution context capabilities
100
+ - [Runtime Support](./docs/runtime-support.md) - Multi-runtime architecture
101
+ - [Tool Component](./docs/tool.md) - Agent capabilities (Phase 2)
102
+ - [Agent Component](./docs/agent.md) - LLM-driven agents (Phase 2)
103
+ - [Entity Component](./docs/entity.md) - Stateful components (Phase 2)
104
+ - [Workflow Component](./docs/workflow.md) - Multi-step orchestration (Phase 2)
105
+
106
+ ## Development
107
+
108
+ ### Setup
109
+
110
+ ```bash
111
+ # Install dependencies
112
+ npm install
113
+
114
+ # Build TypeScript
115
+ npm run build:ts
116
+
117
+ # Run tests
118
+ npm test
119
+
120
+ # Watch mode
121
+ npm run dev
122
+ ```
123
+
124
+ ### Project Structure
125
+
126
+ ```
127
+ sdk-typescript/
128
+ ├── src/ # TypeScript source code
129
+ │ ├── function.ts # Function builder
130
+ │ ├── context.ts # Execution context
131
+ │ ├── worker.ts # Worker implementation
132
+ │ ├── types.ts # TypeScript types
133
+ │ └── __tests__/ # Test files
134
+ ├── native/ # NAPI-RS bindings (Phase 2)
135
+ ├── wasm/ # WASM bindings (Phase 2)
136
+ ├── docs/ # Documentation
137
+ └── dist/ # Compiled output
138
+ ```
139
+
140
+ ## Examples
141
+
142
+ See the [`examples/`](./examples/) directory for complete working examples:
143
+
144
+ - `basic-function.ts` - Simple function definition
145
+ - `retry-backoff.ts` - Retry and backoff configuration
146
+ - `checkpointing.ts` - Multi-step checkpointing
147
+ - `worker.ts` - Worker setup
148
+
149
+ ## Phase 1 vs Phase 2
150
+
151
+ ### Phase 1 (Current) - Local Execution
152
+
153
+ - ✅ Function builder API
154
+ - ✅ Context with state and checkpointing
155
+ - ✅ Retry policies and backoff strategies
156
+ - ✅ Worker infrastructure
157
+ - ✅ TypeScript types and inference
158
+ - ⚠️ In-memory state (not persistent)
159
+ - ⚠️ In-memory checkpoints (not durable)
160
+
161
+ ### Phase 2 (Coming Soon) - Platform Integration
162
+
163
+ - 📋 NAPI and WASM bindings to Rust core
164
+ - 📋 Durable state (survives process restarts)
165
+ - 📋 Distributed execution across workers
166
+ - 📋 Platform orchestration APIs
167
+ - 📋 LLM integration
168
+ - 📋 Tool and Agent components
169
+ - 📋 Entity and Workflow components
170
+
171
+ ## Contributing
172
+
173
+ See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
174
+
175
+ ## License
176
+
177
+ MIT - See [LICENSE](../../LICENSE) for details.
178
+
179
+ ## Resources
180
+
181
+ - [AGNT5 Documentation](../../docs/)
182
+ - [GitHub Repository](https://github.com/agnt5/agnt5)
183
+ - [SDK Architecture](../../sdk/CLAUDE.md)
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Integration test helpers for the AGNT5 TypeScript SDK.
3
+ *
4
+ * These helpers set up the test environment for running integration tests
5
+ * against a local or remote AGNT5 platform instance.
6
+ *
7
+ * Prerequisites:
8
+ * - Running AGNT5 platform (dev server or managed)
9
+ * - Set AGNT5_GATEWAY_URL (default: http://localhost:34181)
10
+ * - Set AGNT5_COORDINATOR_ENDPOINT (default: http://localhost:34186)
11
+ * - Optionally set AGNT5_API_KEY for authenticated tests
12
+ */
13
+ import { Client } from '../../client.js';
14
+ import type { ClientOptions } from '../../client.js';
15
+ export declare const GATEWAY_URL: string;
16
+ export declare const COORDINATOR_ENDPOINT: string;
17
+ export declare const API_KEY: string | undefined;
18
+ export declare const TENANT_ID: string | undefined;
19
+ /**
20
+ * Check if the platform is reachable.
21
+ * Integration tests should skip if this returns false.
22
+ */
23
+ export declare function isPlatformAvailable(): Promise<boolean>;
24
+ /**
25
+ * Create a Client configured for integration tests.
26
+ */
27
+ export declare function createTestClient(overrides?: Partial<ClientOptions>): Client;
28
+ /**
29
+ * Generate a unique test name to avoid collisions.
30
+ */
31
+ export declare function uniqueName(prefix: string): string;
32
+ /**
33
+ * Wait for a condition with timeout.
34
+ */
35
+ export declare function waitFor(condition: () => Promise<boolean>, timeoutMs?: number, pollMs?: number): Promise<void>;
36
+ /**
37
+ * Skip test suite if platform is not available.
38
+ * Use as: `beforeAll(skipIfNoPlatform)` in describe blocks.
39
+ */
40
+ export declare function skipIfNoPlatform(): Promise<void>;
41
+ //# sourceMappingURL=helpers.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/__tests__/integration/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAIrD,eAAO,MAAM,WAAW,QAA4D,CAAC;AACrF,eAAO,MAAM,oBAAoB,QAAqE,CAAC;AACvG,eAAO,MAAM,OAAO,oBAA4B,CAAC;AACjD,eAAO,MAAM,SAAS,oBAA8B,CAAC;AAErD;;;GAGG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,OAAO,CAAC,CAS5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,MAAM,CAQ3E;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAIjD;AAED;;GAEG;AACH,wBAAsB,OAAO,CAC3B,SAAS,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,EACjC,SAAS,GAAE,MAAc,EACzB,MAAM,GAAE,MAAY,GACnB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC,CAOtD"}
@@ -0,0 +1,78 @@
1
+ /**
2
+ * Integration test helpers for the AGNT5 TypeScript SDK.
3
+ *
4
+ * These helpers set up the test environment for running integration tests
5
+ * against a local or remote AGNT5 platform instance.
6
+ *
7
+ * Prerequisites:
8
+ * - Running AGNT5 platform (dev server or managed)
9
+ * - Set AGNT5_GATEWAY_URL (default: http://localhost:34181)
10
+ * - Set AGNT5_COORDINATOR_ENDPOINT (default: http://localhost:34186)
11
+ * - Optionally set AGNT5_API_KEY for authenticated tests
12
+ */
13
+ import { Client } from '../../client.js';
14
+ // ─── Environment ─────────────────────────────────────────────────────
15
+ export const GATEWAY_URL = process.env.AGNT5_GATEWAY_URL || 'http://localhost:34181';
16
+ export const COORDINATOR_ENDPOINT = process.env.AGNT5_COORDINATOR_ENDPOINT || 'http://localhost:34186';
17
+ export const API_KEY = process.env.AGNT5_API_KEY;
18
+ export const TENANT_ID = process.env.AGNT5_TENANT_ID;
19
+ /**
20
+ * Check if the platform is reachable.
21
+ * Integration tests should skip if this returns false.
22
+ */
23
+ export async function isPlatformAvailable() {
24
+ try {
25
+ const response = await fetch(`${GATEWAY_URL}/health`, {
26
+ signal: AbortSignal.timeout(3000),
27
+ });
28
+ return response.ok;
29
+ }
30
+ catch {
31
+ return false;
32
+ }
33
+ }
34
+ /**
35
+ * Create a Client configured for integration tests.
36
+ */
37
+ export function createTestClient(overrides) {
38
+ return new Client({
39
+ gatewayUrl: GATEWAY_URL,
40
+ apiKey: API_KEY,
41
+ timeout: 30000,
42
+ maxRetries: 1,
43
+ ...overrides,
44
+ });
45
+ }
46
+ /**
47
+ * Generate a unique test name to avoid collisions.
48
+ */
49
+ export function uniqueName(prefix) {
50
+ const ts = Date.now().toString(36);
51
+ const rand = Math.random().toString(36).slice(2, 6);
52
+ return `${prefix}-${ts}-${rand}`;
53
+ }
54
+ /**
55
+ * Wait for a condition with timeout.
56
+ */
57
+ export async function waitFor(condition, timeoutMs = 10000, pollMs = 500) {
58
+ const start = Date.now();
59
+ while (Date.now() - start < timeoutMs) {
60
+ if (await condition())
61
+ return;
62
+ await new Promise(resolve => setTimeout(resolve, pollMs));
63
+ }
64
+ throw new Error(`waitFor timed out after ${timeoutMs}ms`);
65
+ }
66
+ /**
67
+ * Skip test suite if platform is not available.
68
+ * Use as: `beforeAll(skipIfNoPlatform)` in describe blocks.
69
+ */
70
+ export async function skipIfNoPlatform() {
71
+ const available = await isPlatformAvailable();
72
+ if (!available) {
73
+ console.log(`⚠ Skipping integration tests: platform not reachable at ${GATEWAY_URL}`);
74
+ // This will cause vitest to skip via the returned value
75
+ throw new Error('Platform not available - skipping integration tests');
76
+ }
77
+ }
78
+ //# sourceMappingURL=helpers.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/__tests__/integration/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAIzC,wEAAwE;AAExE,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,wBAAwB,CAAC;AACrF,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,wBAAwB,CAAC;AACvG,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;AACjD,MAAM,CAAC,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;AAErD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,WAAW,SAAS,EAAE;YACpD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC;SAClC,CAAC,CAAC;QACH,OAAO,QAAQ,CAAC,EAAE,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAkC;IACjE,OAAO,IAAI,MAAM,CAAC;QAChB,UAAU,EAAE,WAAW;QACvB,MAAM,EAAE,OAAO;QACf,OAAO,EAAE,KAAK;QACd,UAAU,EAAE,CAAC;QACb,GAAG,SAAS;KACb,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACpD,OAAO,GAAG,MAAM,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,SAAiC,EACjC,YAAoB,KAAK,EACzB,SAAiB,GAAG;IAEpB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,SAAS,EAAE,CAAC;QACtC,IAAI,MAAM,SAAS,EAAE;YAAE,OAAO;QAC9B,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5D,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,2BAA2B,SAAS,IAAI,CAAC,CAAC;AAC5D,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,MAAM,SAAS,GAAG,MAAM,mBAAmB,EAAE,CAAC;IAC9C,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,CAAC,GAAG,CAAC,2DAA2D,WAAW,EAAE,CAAC,CAAC;QACtF,wDAAwD;QACxD,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;AACH,CAAC"}
@@ -0,0 +1,260 @@
1
+ /**
2
+ * Agent component for LLM-driven autonomous execution.
3
+ *
4
+ * Production ready with support for the new LM class and durable execution
5
+ */
6
+ import type { Context, ToolSchema } from './types.js';
7
+ import { Tool } from './tool.js';
8
+ import type { LM } from './lm.js';
9
+ import type { Message as LMMessage, ToolCall as LMToolCall } from './lm.js';
10
+ import type { AgentEvent } from './events.js';
11
+ /**
12
+ * Message role in conversation (for backwards compatibility)
13
+ * @deprecated Use MessageRole from lm.js instead
14
+ */
15
+ export declare enum MessageRole {
16
+ System = "system",
17
+ User = "user",
18
+ Assistant = "assistant"
19
+ }
20
+ /**
21
+ * Conversation message (uses LM types internally)
22
+ */
23
+ export type Message = LMMessage;
24
+ /**
25
+ * Message factory functions
26
+ */
27
+ export declare const Message: {
28
+ system: (content: string) => Message;
29
+ user: (content: string) => Message;
30
+ assistant: (content: string) => Message;
31
+ };
32
+ /**
33
+ * Tool call from LLM (uses LM types internally)
34
+ */
35
+ export type ToolCall = LMToolCall;
36
+ /**
37
+ * Token usage statistics
38
+ */
39
+ export interface TokenUsage {
40
+ promptTokens: number;
41
+ completionTokens: number;
42
+ totalTokens: number;
43
+ }
44
+ /**
45
+ * Generation configuration (for backwards compatibility)
46
+ * @deprecated Use GenerationConfig from lm.js instead
47
+ */
48
+ export interface GenerationConfig {
49
+ temperature?: number;
50
+ maxTokens?: number;
51
+ topP?: number;
52
+ }
53
+ /**
54
+ * LLM generation request (for backwards compatibility)
55
+ * @deprecated Use GenerateRequest from lm.js instead
56
+ */
57
+ export interface GenerateRequest {
58
+ model: string;
59
+ messages: Message[];
60
+ systemPrompt?: string;
61
+ tools?: ToolSchema[];
62
+ config?: GenerationConfig;
63
+ }
64
+ /**
65
+ * LLM generation response (for backwards compatibility)
66
+ * @deprecated Use GenerateResponse from lm.js instead
67
+ */
68
+ export interface GenerateResponse {
69
+ text: string;
70
+ usage?: TokenUsage;
71
+ finishReason?: string;
72
+ toolCalls?: ToolCall[];
73
+ }
74
+ /**
75
+ * Language model interface (for backwards compatibility)
76
+ * @deprecated Use LM class from lm.js instead
77
+ */
78
+ export interface LanguageModel {
79
+ /**
80
+ * Generate completion from LLM
81
+ */
82
+ generate(request: GenerateRequest): Promise<GenerateResponse>;
83
+ /**
84
+ * Stream completion from LLM (Phase 2)
85
+ */
86
+ stream?(request: GenerateRequest): AsyncIterableIterator<string>;
87
+ }
88
+ /**
89
+ * Agent execution result
90
+ */
91
+ export interface AgentResult {
92
+ output: string;
93
+ toolCalls: Array<{
94
+ name: string;
95
+ arguments: string;
96
+ iteration: number;
97
+ }>;
98
+ context: Context;
99
+ /** Name of agent control was handed off to (null if no handoff) */
100
+ handoffTo: string | null;
101
+ /** Metadata from the handoff (empty if no handoff) */
102
+ handoffMetadata: Record<string, any>;
103
+ }
104
+ /**
105
+ * Handoff configuration for agent-to-agent delegation
106
+ */
107
+ export declare class Handoff {
108
+ readonly agent: Agent;
109
+ readonly description: string;
110
+ readonly toolName: string;
111
+ readonly passFullHistory: boolean;
112
+ constructor(agent: Agent, description?: string, toolName?: string, passFullHistory?: boolean);
113
+ }
114
+ /**
115
+ * Create a handoff configuration for agent delegation
116
+ */
117
+ export declare function handoff(agent: Agent, description?: string, toolName?: string, passFullHistory?: boolean): Handoff;
118
+ /**
119
+ * Global registry for looking up agents by name.
120
+ *
121
+ * Provides discovery for multi-agent systems where agents need to find each
122
+ * other, and for the worker to enumerate registered agents.
123
+ *
124
+ * @example
125
+ * ```typescript
126
+ * const researcher = new Agent({ name: 'researcher', ... });
127
+ * // Agent is auto-registered in constructor
128
+ *
129
+ * // Look up later
130
+ * const found = AgentRegistry.get('researcher');
131
+ * ```
132
+ */
133
+ export declare class AgentRegistry {
134
+ private static agents;
135
+ static register(agent: Agent): void;
136
+ static get(name: string): Agent | undefined;
137
+ static all(): Map<string, Agent>;
138
+ static listNames(): string[];
139
+ static clear(): void;
140
+ }
141
+ /**
142
+ * Agent configuration options
143
+ */
144
+ export interface AgentOptions {
145
+ /** Agent name/identifier */
146
+ name: string;
147
+ /** Language model instance (LM class or legacy LanguageModel) */
148
+ model: LM | LanguageModel;
149
+ /** System instructions for the agent */
150
+ instructions: string;
151
+ /** List of tools available to the agent */
152
+ tools?: (Tool | any)[];
153
+ /** Handoff targets for agent-to-agent delegation */
154
+ handoffs?: (Agent | Handoff)[];
155
+ /** Model name to use (e.g., "gpt-4o-mini") */
156
+ modelName?: string;
157
+ /** LLM temperature (0.0 to 1.0) */
158
+ temperature?: number;
159
+ /** Maximum reasoning iterations */
160
+ maxIterations?: number;
161
+ }
162
+ /**
163
+ * Autonomous LLM-driven agent with tool orchestration
164
+ *
165
+ * @example
166
+ * ```typescript
167
+ * import { Agent, tool } from '@agnt5/sdk';
168
+ *
169
+ * const searchTool = tool('search_web', {
170
+ * description: 'Search the web for information',
171
+ * inputSchema: {
172
+ * type: 'object',
173
+ * properties: {
174
+ * query: { type: 'string', description: 'Search query' }
175
+ * },
176
+ * required: ['query']
177
+ * }
178
+ * }, async (ctx, args) => {
179
+ * const { query } = args;
180
+ * // Search implementation
181
+ * return [{ title: 'Result', url: '...' }];
182
+ * });
183
+ *
184
+ * const agent = new Agent({
185
+ * name: 'researcher',
186
+ * model: myLanguageModel,
187
+ * instructions: 'You are a research assistant.',
188
+ * tools: [searchTool]
189
+ * });
190
+ *
191
+ * const result = await agent.run('What are the latest AI trends?');
192
+ * console.log(result.output);
193
+ * ```
194
+ */
195
+ export declare class Agent {
196
+ readonly name: string;
197
+ readonly model: LM | LanguageModel;
198
+ readonly instructions: string;
199
+ readonly modelName: string;
200
+ readonly temperature: number;
201
+ readonly maxIterations: number;
202
+ private tools;
203
+ private handoffs;
204
+ private isNewLM;
205
+ constructor(options: AgentOptions);
206
+ /**
207
+ * Add a tool to this agent's tool set
208
+ */
209
+ private addTool;
210
+ /**
211
+ * Create an auto-generated transfer tool for a handoff target
212
+ */
213
+ private createHandoffTool;
214
+ /**
215
+ * Convert ToolSchema to LM ToolDefinition
216
+ */
217
+ private convertToolSchema;
218
+ /**
219
+ * Generate using the model (handles both old and new LM types)
220
+ */
221
+ private generateWithModel;
222
+ /**
223
+ * Stream agent execution, yielding events at each stage.
224
+ *
225
+ * @example
226
+ * ```typescript
227
+ * for await (const event of agent.stream('Analyze tech news')) {
228
+ * if (event.eventType === 'agent.completed') {
229
+ * console.log('Done:', event.outputLength);
230
+ * }
231
+ * }
232
+ * ```
233
+ */
234
+ stream(userMessage: string, context?: Context, history?: Message[]): AsyncGenerator<AgentEvent | AgentResult, void, undefined>;
235
+ /**
236
+ * Run agent to completion (non-streaming).
237
+ * Consumes stream() internally and returns the final AgentResult.
238
+ *
239
+ * @example
240
+ * ```typescript
241
+ * const result = await agent.run('Analyze recent tech news');
242
+ * console.log(result.output);
243
+ * ```
244
+ */
245
+ run(userMessage: string, context?: Context, history?: Message[]): Promise<AgentResult>;
246
+ /**
247
+ * Continue multi-turn conversation
248
+ *
249
+ * @example
250
+ * ```typescript
251
+ * let messages: Message[] = [];
252
+ * let response: string;
253
+ *
254
+ * [response, messages] = await agent.chat('Hello', messages);
255
+ * [response, messages] = await agent.chat('Tell me more', messages);
256
+ * ```
257
+ */
258
+ chat(userMessage: string, messages: Message[], context?: Context): Promise<[string, Message[]]>;
259
+ }
260
+ //# sourceMappingURL=agent.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}