groundswell 0.0.3 → 1.0.0
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 +26 -9
- package/dist/cache/cache-key.d.ts +20 -0
- package/dist/cache/cache-key.d.ts.map +1 -1
- package/dist/cache/cache-key.js +9 -0
- package/dist/cache/cache-key.js.map +1 -1
- package/dist/core/agent.d.ts +120 -29
- package/dist/core/agent.d.ts.map +1 -1
- package/dist/core/agent.js +584 -177
- package/dist/core/agent.js.map +1 -1
- package/dist/core/mcp-handler.d.ts +63 -5
- package/dist/core/mcp-handler.d.ts.map +1 -1
- package/dist/core/mcp-handler.js +184 -4
- package/dist/core/mcp-handler.js.map +1 -1
- package/dist/core/workflow-context.d.ts +6 -2
- package/dist/core/workflow-context.d.ts.map +1 -1
- package/dist/core/workflow-context.js +99 -4
- package/dist/core/workflow-context.js.map +1 -1
- package/dist/core/workflow.d.ts +315 -13
- package/dist/core/workflow.d.ts.map +1 -1
- package/dist/core/workflow.js +552 -30
- package/dist/core/workflow.js.map +1 -1
- package/dist/debugger/event-replayer.d.ts +422 -0
- package/dist/debugger/event-replayer.d.ts.map +1 -0
- package/dist/debugger/event-replayer.js +639 -0
- package/dist/debugger/event-replayer.js.map +1 -0
- package/dist/debugger/tree-debugger.d.ts +170 -1
- package/dist/debugger/tree-debugger.d.ts.map +1 -1
- package/dist/debugger/tree-debugger.js +423 -1
- package/dist/debugger/tree-debugger.js.map +1 -1
- package/dist/decorators/step.d.ts.map +1 -1
- package/dist/decorators/step.js +129 -47
- package/dist/decorators/step.js.map +1 -1
- package/dist/harnesses/claude-code-harness.d.ts +391 -0
- package/dist/harnesses/claude-code-harness.d.ts.map +1 -0
- package/dist/harnesses/claude-code-harness.js +1076 -0
- package/dist/harnesses/claude-code-harness.js.map +1 -0
- package/dist/harnesses/harness-registry.d.ts +440 -0
- package/dist/harnesses/harness-registry.d.ts.map +1 -0
- package/dist/harnesses/harness-registry.js +543 -0
- package/dist/harnesses/harness-registry.js.map +1 -0
- package/dist/harnesses/index.d.ts +12 -0
- package/dist/harnesses/index.d.ts.map +1 -0
- package/dist/harnesses/index.js +11 -0
- package/dist/harnesses/index.js.map +1 -0
- package/dist/harnesses/pi-harness.d.ts +219 -0
- package/dist/harnesses/pi-harness.d.ts.map +1 -0
- package/dist/harnesses/pi-harness.js +676 -0
- package/dist/harnesses/pi-harness.js.map +1 -0
- package/dist/harnesses/pi-schema-converter.d.ts +24 -0
- package/dist/harnesses/pi-schema-converter.d.ts.map +1 -0
- package/dist/harnesses/pi-schema-converter.js +81 -0
- package/dist/harnesses/pi-schema-converter.js.map +1 -0
- package/dist/harnesses/register-defaults.d.ts +24 -0
- package/dist/harnesses/register-defaults.d.ts.map +1 -0
- package/dist/harnesses/register-defaults.js +40 -0
- package/dist/harnesses/register-defaults.js.map +1 -0
- package/dist/harnesses/session-store.d.ts +201 -0
- package/dist/harnesses/session-store.d.ts.map +1 -0
- package/dist/harnesses/session-store.js +254 -0
- package/dist/harnesses/session-store.js.map +1 -0
- package/dist/index.d.ts +12 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +17 -0
- package/dist/index.js.map +1 -1
- package/dist/reflection/reflection.d.ts.map +1 -1
- package/dist/reflection/reflection.js +19 -4
- package/dist/reflection/reflection.js.map +1 -1
- package/dist/types/agent.d.ts +1253 -2
- package/dist/types/agent.d.ts.map +1 -1
- package/dist/types/agent.js +418 -1
- package/dist/types/agent.js.map +1 -1
- package/dist/types/decorators.d.ts +10 -1
- package/dist/types/decorators.d.ts.map +1 -1
- package/dist/types/events.d.ts +26 -0
- package/dist/types/events.d.ts.map +1 -1
- package/dist/types/harnesses.d.ts +474 -0
- package/dist/types/harnesses.d.ts.map +1 -0
- package/dist/types/harnesses.js +2 -0
- package/dist/types/harnesses.js.map +1 -0
- package/dist/types/index.d.ts +9 -1
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/index.js +6 -0
- package/dist/types/index.js.map +1 -1
- package/dist/types/providers.d.ts +691 -0
- package/dist/types/providers.d.ts.map +1 -0
- package/dist/types/providers.js +14 -0
- package/dist/types/providers.js.map +1 -0
- package/dist/types/restart.d.ts +132 -0
- package/dist/types/restart.d.ts.map +1 -0
- package/dist/types/restart.js +2 -0
- package/dist/types/restart.js.map +1 -0
- package/dist/types/streaming.d.ts +194 -0
- package/dist/types/streaming.d.ts.map +1 -0
- package/dist/types/streaming.js +67 -0
- package/dist/types/streaming.js.map +1 -0
- package/dist/types/workflow-context.d.ts +137 -1
- package/dist/types/workflow-context.d.ts.map +1 -1
- package/dist/utils/agent-validation.d.ts +88 -0
- package/dist/utils/agent-validation.d.ts.map +1 -0
- package/dist/utils/agent-validation.js +87 -0
- package/dist/utils/agent-validation.js.map +1 -0
- package/dist/utils/delay.d.ts +7 -0
- package/dist/utils/delay.d.ts.map +1 -0
- package/dist/utils/delay.js +9 -0
- package/dist/utils/delay.js.map +1 -0
- package/dist/utils/harness-config.d.ts +180 -0
- package/dist/utils/harness-config.d.ts.map +1 -0
- package/dist/utils/harness-config.js +311 -0
- package/dist/utils/harness-config.js.map +1 -0
- package/dist/utils/index.d.ts +9 -1
- package/dist/utils/index.d.ts.map +1 -1
- package/dist/utils/index.js +8 -1
- package/dist/utils/index.js.map +1 -1
- package/dist/utils/model-spec.d.ts +110 -0
- package/dist/utils/model-spec.d.ts.map +1 -0
- package/dist/utils/model-spec.js +149 -0
- package/dist/utils/model-spec.js.map +1 -0
- package/dist/utils/provider-config.d.ts +10 -0
- package/dist/utils/provider-config.d.ts.map +1 -0
- package/dist/utils/provider-config.js +10 -0
- package/dist/utils/provider-config.js.map +1 -0
- package/dist/utils/restart-analysis.d.ts +202 -0
- package/dist/utils/restart-analysis.d.ts.map +1 -0
- package/dist/utils/restart-analysis.js +426 -0
- package/dist/utils/restart-analysis.js.map +1 -0
- package/dist/utils/session-serialization.d.ts +118 -0
- package/dist/utils/session-serialization.d.ts.map +1 -0
- package/dist/utils/session-serialization.js +217 -0
- package/dist/utils/session-serialization.js.map +1 -0
- package/package.json +31 -5
- package/CHANGELOG.md +0 -188
- package/dist/__tests__/adversarial/attachChild-performance.test.d.ts +0 -16
- package/dist/__tests__/adversarial/attachChild-performance.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/attachChild-performance.test.js +0 -187
- package/dist/__tests__/adversarial/attachChild-performance.test.js.map +0 -1
- package/dist/__tests__/adversarial/circular-reference.test.d.ts +0 -13
- package/dist/__tests__/adversarial/circular-reference.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/circular-reference.test.js +0 -92
- package/dist/__tests__/adversarial/circular-reference.test.js.map +0 -1
- package/dist/__tests__/adversarial/complex-circular-reference.test.d.ts +0 -16
- package/dist/__tests__/adversarial/complex-circular-reference.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/complex-circular-reference.test.js +0 -127
- package/dist/__tests__/adversarial/complex-circular-reference.test.js.map +0 -1
- package/dist/__tests__/adversarial/concurrent-task-failures.test.d.ts +0 -21
- package/dist/__tests__/adversarial/concurrent-task-failures.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/concurrent-task-failures.test.js +0 -667
- package/dist/__tests__/adversarial/concurrent-task-failures.test.js.map +0 -1
- package/dist/__tests__/adversarial/deep-analysis.test.d.ts +0 -6
- package/dist/__tests__/adversarial/deep-analysis.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/deep-analysis.test.js +0 -877
- package/dist/__tests__/adversarial/deep-analysis.test.js.map +0 -1
- package/dist/__tests__/adversarial/deep-hierarchy-stress.test.d.ts +0 -13
- package/dist/__tests__/adversarial/deep-hierarchy-stress.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/deep-hierarchy-stress.test.js +0 -186
- package/dist/__tests__/adversarial/deep-hierarchy-stress.test.js.map +0 -1
- package/dist/__tests__/adversarial/e2e-prd-validation.test.d.ts +0 -6
- package/dist/__tests__/adversarial/e2e-prd-validation.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/e2e-prd-validation.test.js +0 -626
- package/dist/__tests__/adversarial/e2e-prd-validation.test.js.map +0 -1
- package/dist/__tests__/adversarial/edge-case.test.d.ts +0 -6
- package/dist/__tests__/adversarial/edge-case.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/edge-case.test.js +0 -857
- package/dist/__tests__/adversarial/edge-case.test.js.map +0 -1
- package/dist/__tests__/adversarial/error-merge-strategy.test.d.ts +0 -20
- package/dist/__tests__/adversarial/error-merge-strategy.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/error-merge-strategy.test.js +0 -907
- package/dist/__tests__/adversarial/error-merge-strategy.test.js.map +0 -1
- package/dist/__tests__/adversarial/incremental-performance.test.d.ts +0 -2
- package/dist/__tests__/adversarial/incremental-performance.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/incremental-performance.test.js +0 -113
- package/dist/__tests__/adversarial/incremental-performance.test.js.map +0 -1
- package/dist/__tests__/adversarial/node-map-update-benchmarks.test.d.ts +0 -22
- package/dist/__tests__/adversarial/node-map-update-benchmarks.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/node-map-update-benchmarks.test.js +0 -383
- package/dist/__tests__/adversarial/node-map-update-benchmarks.test.js.map +0 -1
- package/dist/__tests__/adversarial/observer-propagation.test.d.ts +0 -21
- package/dist/__tests__/adversarial/observer-propagation.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/observer-propagation.test.js +0 -404
- package/dist/__tests__/adversarial/observer-propagation.test.js.map +0 -1
- package/dist/__tests__/adversarial/parent-validation.test.d.ts +0 -13
- package/dist/__tests__/adversarial/parent-validation.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/parent-validation.test.js +0 -128
- package/dist/__tests__/adversarial/parent-validation.test.js.map +0 -1
- package/dist/__tests__/adversarial/prd-12-2-compliance.test.d.ts +0 -20
- package/dist/__tests__/adversarial/prd-12-2-compliance.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/prd-12-2-compliance.test.js +0 -482
- package/dist/__tests__/adversarial/prd-12-2-compliance.test.js.map +0 -1
- package/dist/__tests__/adversarial/prd-compliance.test.d.ts +0 -6
- package/dist/__tests__/adversarial/prd-compliance.test.d.ts.map +0 -1
- package/dist/__tests__/adversarial/prd-compliance.test.js +0 -886
- package/dist/__tests__/adversarial/prd-compliance.test.js.map +0 -1
- package/dist/__tests__/compatibility/backward-compatibility.test.d.ts +0 -22
- package/dist/__tests__/compatibility/backward-compatibility.test.d.ts.map +0 -1
- package/dist/__tests__/compatibility/backward-compatibility.test.js +0 -1843
- package/dist/__tests__/compatibility/backward-compatibility.test.js.map +0 -1
- package/dist/__tests__/helpers/index.d.ts +0 -10
- package/dist/__tests__/helpers/index.d.ts.map +0 -1
- package/dist/__tests__/helpers/index.js +0 -10
- package/dist/__tests__/helpers/index.js.map +0 -1
- package/dist/__tests__/helpers/tree-verification.d.ts +0 -90
- package/dist/__tests__/helpers/tree-verification.d.ts.map +0 -1
- package/dist/__tests__/helpers/tree-verification.js +0 -202
- package/dist/__tests__/helpers/tree-verification.js.map +0 -1
- package/dist/__tests__/integration/agent-workflow.test.d.ts +0 -2
- package/dist/__tests__/integration/agent-workflow.test.d.ts.map +0 -1
- package/dist/__tests__/integration/agent-workflow.test.js +0 -256
- package/dist/__tests__/integration/agent-workflow.test.js.map +0 -1
- package/dist/__tests__/integration/bidirectional-consistency.test.d.ts +0 -14
- package/dist/__tests__/integration/bidirectional-consistency.test.d.ts.map +0 -1
- package/dist/__tests__/integration/bidirectional-consistency.test.js +0 -668
- package/dist/__tests__/integration/bidirectional-consistency.test.js.map +0 -1
- package/dist/__tests__/integration/observer-logging.test.d.ts +0 -2
- package/dist/__tests__/integration/observer-logging.test.d.ts.map +0 -1
- package/dist/__tests__/integration/observer-logging.test.js +0 -517
- package/dist/__tests__/integration/observer-logging.test.js.map +0 -1
- package/dist/__tests__/integration/tree-mirroring.test.d.ts +0 -2
- package/dist/__tests__/integration/tree-mirroring.test.d.ts.map +0 -1
- package/dist/__tests__/integration/tree-mirroring.test.js +0 -117
- package/dist/__tests__/integration/tree-mirroring.test.js.map +0 -1
- package/dist/__tests__/integration/workflow-reparenting.test.d.ts +0 -12
- package/dist/__tests__/integration/workflow-reparenting.test.d.ts.map +0 -1
- package/dist/__tests__/integration/workflow-reparenting.test.js +0 -239
- package/dist/__tests__/integration/workflow-reparenting.test.js.map +0 -1
- package/dist/__tests__/unit/agent.test.d.ts +0 -2
- package/dist/__tests__/unit/agent.test.d.ts.map +0 -1
- package/dist/__tests__/unit/agent.test.js +0 -143
- package/dist/__tests__/unit/agent.test.js.map +0 -1
- package/dist/__tests__/unit/cache-key.test.d.ts +0 -5
- package/dist/__tests__/unit/cache-key.test.d.ts.map +0 -1
- package/dist/__tests__/unit/cache-key.test.js +0 -145
- package/dist/__tests__/unit/cache-key.test.js.map +0 -1
- package/dist/__tests__/unit/cache.test.d.ts +0 -5
- package/dist/__tests__/unit/cache.test.d.ts.map +0 -1
- package/dist/__tests__/unit/cache.test.js +0 -132
- package/dist/__tests__/unit/cache.test.js.map +0 -1
- package/dist/__tests__/unit/context.test.d.ts +0 -2
- package/dist/__tests__/unit/context.test.d.ts.map +0 -1
- package/dist/__tests__/unit/context.test.js +0 -220
- package/dist/__tests__/unit/context.test.js.map +0 -1
- package/dist/__tests__/unit/decorators.test.d.ts +0 -2
- package/dist/__tests__/unit/decorators.test.d.ts.map +0 -1
- package/dist/__tests__/unit/decorators.test.js +0 -162
- package/dist/__tests__/unit/decorators.test.js.map +0 -1
- package/dist/__tests__/unit/introspection-tools.test.d.ts +0 -5
- package/dist/__tests__/unit/introspection-tools.test.d.ts.map +0 -1
- package/dist/__tests__/unit/introspection-tools.test.js +0 -191
- package/dist/__tests__/unit/introspection-tools.test.js.map +0 -1
- package/dist/__tests__/unit/logger.test.d.ts +0 -2
- package/dist/__tests__/unit/logger.test.d.ts.map +0 -1
- package/dist/__tests__/unit/logger.test.js +0 -241
- package/dist/__tests__/unit/logger.test.js.map +0 -1
- package/dist/__tests__/unit/observable.test.d.ts +0 -2
- package/dist/__tests__/unit/observable.test.d.ts.map +0 -1
- package/dist/__tests__/unit/observable.test.js +0 -251
- package/dist/__tests__/unit/observable.test.js.map +0 -1
- package/dist/__tests__/unit/prompt.test.d.ts +0 -2
- package/dist/__tests__/unit/prompt.test.d.ts.map +0 -1
- package/dist/__tests__/unit/prompt.test.js +0 -113
- package/dist/__tests__/unit/prompt.test.js.map +0 -1
- package/dist/__tests__/unit/reflection.test.d.ts +0 -5
- package/dist/__tests__/unit/reflection.test.d.ts.map +0 -1
- package/dist/__tests__/unit/reflection.test.js +0 -160
- package/dist/__tests__/unit/reflection.test.js.map +0 -1
- package/dist/__tests__/unit/tree-debugger-incremental.test.d.ts +0 -2
- package/dist/__tests__/unit/tree-debugger-incremental.test.d.ts.map +0 -1
- package/dist/__tests__/unit/tree-debugger-incremental.test.js +0 -136
- package/dist/__tests__/unit/tree-debugger-incremental.test.js.map +0 -1
- package/dist/__tests__/unit/tree-debugger.test.d.ts +0 -2
- package/dist/__tests__/unit/tree-debugger.test.d.ts.map +0 -1
- package/dist/__tests__/unit/tree-debugger.test.js +0 -69
- package/dist/__tests__/unit/tree-debugger.test.js.map +0 -1
- package/dist/__tests__/unit/utils/workflow-error-utils.test.d.ts +0 -2
- package/dist/__tests__/unit/utils/workflow-error-utils.test.d.ts.map +0 -1
- package/dist/__tests__/unit/utils/workflow-error-utils.test.js +0 -154
- package/dist/__tests__/unit/utils/workflow-error-utils.test.js.map +0 -1
- package/dist/__tests__/unit/workflow-detachChild.test.d.ts +0 -2
- package/dist/__tests__/unit/workflow-detachChild.test.d.ts.map +0 -1
- package/dist/__tests__/unit/workflow-detachChild.test.js +0 -76
- package/dist/__tests__/unit/workflow-detachChild.test.js.map +0 -1
- package/dist/__tests__/unit/workflow-emitEvent-childDetached.test.d.ts +0 -2
- package/dist/__tests__/unit/workflow-emitEvent-childDetached.test.d.ts.map +0 -1
- package/dist/__tests__/unit/workflow-emitEvent-childDetached.test.js +0 -122
- package/dist/__tests__/unit/workflow-emitEvent-childDetached.test.js.map +0 -1
- package/dist/__tests__/unit/workflow-isDescendantOf.test.d.ts +0 -2
- package/dist/__tests__/unit/workflow-isDescendantOf.test.d.ts.map +0 -1
- package/dist/__tests__/unit/workflow-isDescendantOf.test.js +0 -140
- package/dist/__tests__/unit/workflow-isDescendantOf.test.js.map +0 -1
- package/dist/__tests__/unit/workflow.test.d.ts +0 -2
- package/dist/__tests__/unit/workflow.test.d.ts.map +0 -1
- package/dist/__tests__/unit/workflow.test.js +0 -330
- package/dist/__tests__/unit/workflow.test.js.map +0 -1
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Groundswell Contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ Hierarchical workflow orchestration engine with full observability.
|
|
|
8
8
|
npm install groundswell
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
**Requirements:** Node.js
|
|
11
|
+
**Requirements:** Node.js 20+, TypeScript 5.2+
|
|
12
12
|
|
|
13
13
|
## Quick Start
|
|
14
14
|
|
|
@@ -61,30 +61,41 @@ const result = await workflow.run();
|
|
|
61
61
|
|
|
62
62
|
### Agent with Prompt
|
|
63
63
|
|
|
64
|
+
> [!IMPORTANT]
|
|
65
|
+
> Groundswell v2.0: `agent.prompt()` now returns `AgentResponse<T>`.
|
|
66
|
+
> See the [Migration Guide](docs/migration-guide-agent-response.md) if upgrading.
|
|
67
|
+
|
|
64
68
|
```typescript
|
|
65
69
|
import { createAgent, createPrompt } from 'groundswell';
|
|
66
70
|
import { z } from 'zod';
|
|
67
71
|
|
|
68
|
-
const agent = createAgent({
|
|
69
|
-
name: 'AnalysisAgent',
|
|
70
|
-
enableCache: true,
|
|
71
|
-
});
|
|
72
|
+
const agent = createAgent({ name: 'AnalysisAgent' });
|
|
72
73
|
|
|
73
74
|
const prompt = createPrompt({
|
|
74
|
-
user: 'Analyze this code
|
|
75
|
-
data: { code: 'function foo() { return 42; }' },
|
|
75
|
+
user: 'Analyze this code',
|
|
76
76
|
responseFormat: z.object({
|
|
77
77
|
bugs: z.array(z.string()),
|
|
78
78
|
severity: z.enum(['low', 'medium', 'high']),
|
|
79
79
|
}),
|
|
80
80
|
});
|
|
81
81
|
|
|
82
|
-
const
|
|
83
|
-
|
|
82
|
+
const response = await agent.prompt(prompt);
|
|
83
|
+
if (response.status === 'error') {
|
|
84
|
+
throw new Error(response.error.message);
|
|
85
|
+
}
|
|
86
|
+
console.log(response.data.bugs);
|
|
84
87
|
```
|
|
85
88
|
|
|
89
|
+
**Why AgentResponse?**
|
|
90
|
+
- Type-safe validated responses with error handling
|
|
91
|
+
- Observable metadata (tokens, timing, cache hits)
|
|
92
|
+
- Consistent API across all agent operations
|
|
93
|
+
|
|
86
94
|
## Documentation
|
|
87
95
|
|
|
96
|
+
- [Migration Guide](docs/migration-guide-agent-response.md) - Upgrading from v1.x ⚠️
|
|
97
|
+
- [Harnesses](docs/harnesses.md) - Pluggable agent runtime (pi default, claude-code optional)
|
|
98
|
+
- [Provider → Harness Migration](docs/migration-provider-to-harness.md) - v1.2 vocabulary migration
|
|
88
99
|
- [Workflows](docs/workflow.md) - Hierarchical task orchestration
|
|
89
100
|
- [Agents](docs/agent.md) - LLM execution with caching and reflection
|
|
90
101
|
- [Prompts](docs/prompt.md) - Type-safe prompt definitions with Zod
|
|
@@ -301,6 +312,12 @@ See [examples/](examples/) for source code.
|
|
|
301
312
|
|
|
302
313
|
Contributions and issues are welcome.
|
|
303
314
|
|
|
315
|
+
### Releasing
|
|
316
|
+
|
|
317
|
+
Releases are automated with [release-please](https://github.com/googleapis/release-please). When `feat:` / `fix:` / `BREAKING CHANGE` commits land on `main`, release-please opens a release PR that bumps the version, updates `CHANGELOG.md`, and tags a release. Merging that PR publishes to npm.
|
|
318
|
+
|
|
319
|
+
One-time setup: add an **`NPM_TOKEN`** secret to the repository (an npm *automation* access token, or a granular access token with publish permission).
|
|
320
|
+
|
|
304
321
|
## Support
|
|
305
322
|
|
|
306
323
|
If Groundswell helps you build something great, consider fueling future development:
|
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
* identical inputs always produce identical cache keys.
|
|
6
6
|
*/
|
|
7
7
|
import type { Tool, MCPServer, Skill } from '../types/index.js';
|
|
8
|
+
import type { HarnessId, ModelProviderId } from '../types/harnesses.js';
|
|
8
9
|
import type { z } from 'zod';
|
|
9
10
|
/**
|
|
10
11
|
* Inputs used to generate a cache key
|
|
@@ -18,6 +19,25 @@ export interface CacheKeyInputs {
|
|
|
18
19
|
system?: string;
|
|
19
20
|
/** Model identifier */
|
|
20
21
|
model: string;
|
|
22
|
+
/**
|
|
23
|
+
* Agent runtime identifier (PRD §7.2 / §7.14.5 cache isolation).
|
|
24
|
+
*
|
|
25
|
+
* Optional during the harness migration window: the Agent cache build-site (P3.M1.T2.S3)
|
|
26
|
+
* does not yet pass it, so omitting it preserves the pre-task key. Once P3.M1.T2.S3 rewires
|
|
27
|
+
* `agent.ts` to always pass the resolved harness, this field may be tightened to required.
|
|
28
|
+
* When provided, it becomes a component of the SHA-256 cache key so `pi` and `claude-code`
|
|
29
|
+
* runs never share cache entries.
|
|
30
|
+
*/
|
|
31
|
+
harness?: HarnessId;
|
|
32
|
+
/**
|
|
33
|
+
* LLM host / model provider (PRD §7.8 / §7.14.5 cache isolation).
|
|
34
|
+
*
|
|
35
|
+
* The LLM-vendor axis (NOT the harness) — e.g. 'anthropic', 'openai', 'google', 'zai', or
|
|
36
|
+
* any open-set provider string. Optional; resolved from the ModelSpec. When provided, it
|
|
37
|
+
* becomes a component of the SHA-256 cache key so provider-qualified models with colliding
|
|
38
|
+
* bare ids get distinct entries.
|
|
39
|
+
*/
|
|
40
|
+
provider?: ModelProviderId;
|
|
21
41
|
/** Temperature setting */
|
|
22
42
|
temperature?: number;
|
|
23
43
|
/** Maximum tokens */
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cache-key.d.ts","sourceRoot":"","sources":["../../src/cache/cache-key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,oBAAoB;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,kBAAkB;IAClB,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC;IACnB,aAAa;IACb,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACjB,iCAAiC;IACjC,cAAc,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA2D7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,MAAM,CAqBnE;AAoDD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,
|
|
1
|
+
{"version":3,"file":"cache-key.d.ts","sourceRoot":"","sources":["../../src/cache/cache-key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,oBAAoB;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,0BAA0B;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,kBAAkB;IAClB,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC;IACnB,aAAa;IACb,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACjB,iCAAiC;IACjC,cAAc,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA2D7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,MAAM,CAqBnE;AAoDD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAqD/D"}
|
package/dist/cache/cache-key.js
CHANGED
|
@@ -163,6 +163,15 @@ export function generateCacheKey(inputs) {
|
|
|
163
163
|
user: inputs.user,
|
|
164
164
|
model: inputs.model,
|
|
165
165
|
};
|
|
166
|
+
// PRD §7.14.5: incorporate the harness + provider axes for cross-harness/provider isolation.
|
|
167
|
+
// Conditional append (matches the optional-field pattern below) — omitting them yields the
|
|
168
|
+
// exact pre-task key, so the Agent build-site stays green until P3.M1.T2.S3 rewires it.
|
|
169
|
+
if (inputs.harness !== undefined) {
|
|
170
|
+
normalized.harness = inputs.harness;
|
|
171
|
+
}
|
|
172
|
+
if (inputs.provider !== undefined) {
|
|
173
|
+
normalized.provider = inputs.provider;
|
|
174
|
+
}
|
|
166
175
|
// Include optional fields only if defined
|
|
167
176
|
if (inputs.data !== undefined) {
|
|
168
177
|
normalized.data = inputs.data;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"cache-key.js","sourceRoot":"","sources":["../../src/cache/cache-key.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"cache-key.js","sourceRoot":"","sources":["../../src/cache/cache-key.ts"],"names":[],"mappings":"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"}
|
package/dist/core/agent.d.ts
CHANGED
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Agent -
|
|
2
|
+
* Agent - Multi-provider agent for LLM prompt execution
|
|
3
3
|
*
|
|
4
|
-
* Agents execute prompts
|
|
5
|
-
*
|
|
4
|
+
* Agents execute prompts via provider abstraction layer, supporting
|
|
5
|
+
* multiple LLM providers (Anthropic, Claude Code, etc.) with unified
|
|
6
|
+
* configuration cascade and tool delegation.
|
|
6
7
|
*/
|
|
7
|
-
import type { AgentConfig, PromptOverrides, TokenUsage } from '../types/index.js';
|
|
8
|
+
import type { AgentConfig, PromptOverrides, TokenUsage, AgentResponse } from '../types/index.js';
|
|
8
9
|
import type { Prompt } from './prompt.js';
|
|
9
10
|
import { MCPHandler } from './mcp-handler.js';
|
|
11
|
+
import type { AsyncStream } from '../types/streaming.js';
|
|
10
12
|
/**
|
|
11
13
|
* Result from a prompt execution including metadata
|
|
12
14
|
*/
|
|
@@ -21,7 +23,7 @@ export interface PromptResult<T> {
|
|
|
21
23
|
toolCalls: number;
|
|
22
24
|
}
|
|
23
25
|
/**
|
|
24
|
-
* Agent class - executes prompts via Anthropic SDK
|
|
26
|
+
* Agent class - executes prompts via Anthropic Agent SDK
|
|
25
27
|
*/
|
|
26
28
|
export declare class Agent {
|
|
27
29
|
/** Unique identifier for this agent instance */
|
|
@@ -30,40 +32,126 @@ export declare class Agent {
|
|
|
30
32
|
readonly name: string;
|
|
31
33
|
/** Stored configuration */
|
|
32
34
|
private readonly config;
|
|
33
|
-
/** Anthropic client instance */
|
|
34
|
-
private readonly client;
|
|
35
35
|
/** MCP handler for tool management */
|
|
36
36
|
private readonly mcpHandler;
|
|
37
37
|
/** Direct MCPHandler instances for delegated execution */
|
|
38
38
|
private readonly mcpHandlers;
|
|
39
39
|
/** Default model to use */
|
|
40
40
|
private readonly model;
|
|
41
|
+
/** Harness to use for this agent (resolved at construction) */
|
|
42
|
+
private readonly harnessId?;
|
|
43
|
+
/** Harness-specific options for this agent */
|
|
44
|
+
private readonly harnessOptions?;
|
|
45
|
+
/** Harness instance from registry (resolved at construction) */
|
|
46
|
+
private readonly harness;
|
|
41
47
|
/**
|
|
42
48
|
* Create a new Agent instance
|
|
43
|
-
* @param config Agent configuration
|
|
49
|
+
* @param config Agent configuration (default: { name: 'Agent', model: 'claude-sonnet-4-20250514' })
|
|
44
50
|
*/
|
|
45
51
|
constructor(config?: AgentConfig);
|
|
52
|
+
/**
|
|
53
|
+
* Execute tool via MCPHandler delegation
|
|
54
|
+
*
|
|
55
|
+
* This method implements the ToolExecutor callback signature for provider
|
|
56
|
+
* integration. Providers delegate tool execution back to the Agent's
|
|
57
|
+
* MCPHandler, maintaining centralized tool management.
|
|
58
|
+
*
|
|
59
|
+
* Tool names use the serverName__toolName format (double underscore)
|
|
60
|
+
* created during MCP server registration. The full name is passed
|
|
61
|
+
* directly to MCPHandler without parsing.
|
|
62
|
+
*
|
|
63
|
+
* ## Tool Resolution Order
|
|
64
|
+
*
|
|
65
|
+
* 1. Delegated handlers (this.mcpHandlers[]) - Custom MCPHandler instances
|
|
66
|
+
* 2. Main handler (this.mcpHandler) - Primary tool registry
|
|
67
|
+
*
|
|
68
|
+
* ## Error Handling
|
|
69
|
+
*
|
|
70
|
+
* Tool errors are returned in ToolExecutionResult format with isError: true.
|
|
71
|
+
* The method never throws - errors are wrapped in result objects.
|
|
72
|
+
*
|
|
73
|
+
* @param req - Tool execution request with name (serverName__toolName) and input
|
|
74
|
+
* @returns Promise resolving to tool execution result with content and error flag
|
|
75
|
+
* @private
|
|
76
|
+
* @remarks
|
|
77
|
+
* Used internally by provider.execute() for tool delegation.
|
|
78
|
+
* Tool execution flow: Provider → Agent.toolExecutor → MCPHandler.executeTool()
|
|
79
|
+
*/
|
|
80
|
+
private toolExecutor;
|
|
81
|
+
/**
|
|
82
|
+
* Convert MCPHandler ToolResult to ToolExecutionResult
|
|
83
|
+
*
|
|
84
|
+
* Maps the MCPHandler's internal ToolResult format to the
|
|
85
|
+
* provider-facing ToolExecutionResult format.
|
|
86
|
+
*
|
|
87
|
+
* Tries to parse JSON strings back to objects for better usability.
|
|
88
|
+
*
|
|
89
|
+
* @param toolResult - Result from MCPHandler.executeTool()
|
|
90
|
+
* @returns ToolExecutionResult with content and isError flag
|
|
91
|
+
* @private
|
|
92
|
+
*/
|
|
93
|
+
private convertToToolExecutionResult;
|
|
46
94
|
/**
|
|
47
95
|
* Execute a prompt and return validated response
|
|
48
|
-
* @param prompt Prompt to execute
|
|
49
|
-
* @param overrides Optional overrides for this execution
|
|
50
|
-
* @returns
|
|
96
|
+
* @param prompt Prompt to execute (required)
|
|
97
|
+
* @param overrides Optional overrides for this execution (default: undefined)
|
|
98
|
+
* @returns AgentResponse containing validated response or error
|
|
51
99
|
*/
|
|
52
|
-
prompt<T>(prompt: Prompt<T>, overrides?: PromptOverrides): Promise<T
|
|
100
|
+
prompt<T>(prompt: Prompt<T>, overrides?: PromptOverrides): Promise<AgentResponse<T>>;
|
|
53
101
|
/**
|
|
54
102
|
* Execute a prompt with full result metadata
|
|
55
103
|
* @param prompt Prompt to execute
|
|
56
104
|
* @param overrides Optional overrides for this execution
|
|
57
105
|
* @returns Full result including metadata
|
|
106
|
+
* @deprecated Use prompt() which now returns AgentResponse with metadata
|
|
58
107
|
*/
|
|
59
108
|
promptWithMetadata<T>(prompt: Prompt<T>, overrides?: PromptOverrides): Promise<PromptResult<T>>;
|
|
60
109
|
/**
|
|
61
110
|
* Execute a prompt with reflection capabilities
|
|
111
|
+
* @param prompt Prompt to execute (required)
|
|
112
|
+
* @param overrides Optional overrides for this execution (default: undefined)
|
|
113
|
+
* @returns AgentResponse containing validated response or error
|
|
114
|
+
* @remarks Reflection follows opt-out pattern: enabled by default unless explicitly disabled.
|
|
115
|
+
* When reflection is enabled (prompt.enableReflection, overrides.enableReflection, or
|
|
116
|
+
* config.enableReflection), prefixes system prompt with reflection instructions.
|
|
117
|
+
*/
|
|
118
|
+
reflect<T>(prompt: Prompt<T>, overrides?: PromptOverrides): Promise<AgentResponse<T>>;
|
|
119
|
+
/**
|
|
120
|
+
* Execute a prompt with streaming response
|
|
121
|
+
*
|
|
122
|
+
* Returns an AsyncStream that yields StreamEvent objects during execution.
|
|
123
|
+
* Enables real-time response generation with text deltas, tool calls, and metadata.
|
|
124
|
+
*
|
|
62
125
|
* @param prompt Prompt to execute
|
|
63
126
|
* @param overrides Optional overrides for this execution
|
|
64
|
-
* @returns
|
|
127
|
+
* @returns AsyncStream with AsyncGenerator for for-await...of consumption
|
|
128
|
+
*
|
|
129
|
+
* @example
|
|
130
|
+
* ```ts
|
|
131
|
+
* const agent = new Agent({ provider: 'anthropic' });
|
|
132
|
+
* const prompt = new Prompt({ user: 'Tell me a story' });
|
|
133
|
+
*
|
|
134
|
+
* const streamResult = agent.stream(prompt);
|
|
135
|
+
*
|
|
136
|
+
* for await (const event of streamResult.stream) {
|
|
137
|
+
* switch (event.type) {
|
|
138
|
+
* case 'text_delta':
|
|
139
|
+
* process.stdout.write(event.delta);
|
|
140
|
+
* break;
|
|
141
|
+
* case 'tool_call_start':
|
|
142
|
+
* console.log(`Tool: ${event.name}`);
|
|
143
|
+
* break;
|
|
144
|
+
* case 'done':
|
|
145
|
+
* console.log('Complete!');
|
|
146
|
+
* break;
|
|
147
|
+
* case 'error':
|
|
148
|
+
* console.error('Error:', event.error.message);
|
|
149
|
+
* break;
|
|
150
|
+
* }
|
|
151
|
+
* }
|
|
152
|
+
* ```
|
|
65
153
|
*/
|
|
66
|
-
|
|
154
|
+
stream<T>(prompt: Prompt<T>, overrides?: PromptOverrides): AsyncStream<T>;
|
|
67
155
|
/**
|
|
68
156
|
* Get the MCP handler for custom tool registration
|
|
69
157
|
*/
|
|
@@ -73,17 +161,26 @@ export declare class Agent {
|
|
|
73
161
|
*/
|
|
74
162
|
private emitWorkflowEvent;
|
|
75
163
|
/**
|
|
76
|
-
* Internal prompt execution with full flow
|
|
164
|
+
* Internal prompt execution with full flow using provider abstraction
|
|
165
|
+
* @side effects May emit workflow events, may read from/write to cache if enabled,
|
|
166
|
+
* may modify environment variables temporarily, validates response against schema,
|
|
167
|
+
* and stores result in cache if enabled.
|
|
77
168
|
*/
|
|
78
169
|
private executePrompt;
|
|
79
170
|
/**
|
|
80
|
-
*
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
*
|
|
171
|
+
* Validates an AgentResponse against the schema before returning
|
|
172
|
+
*
|
|
173
|
+
* This provides defense-in-depth validation to ensure all returned responses
|
|
174
|
+
* conform to the AgentResponse schema, even if factory helpers have bugs.
|
|
175
|
+
*
|
|
176
|
+
* @template T - The type of response data
|
|
177
|
+
* @param response - The response to validate (required)
|
|
178
|
+
* @param dataSchema - The Zod schema for the response data (required from Prompt.responseFormat)
|
|
179
|
+
* @returns The validated response, or an INTERNAL_ERROR response if validation fails
|
|
180
|
+
*
|
|
181
|
+
* @private
|
|
85
182
|
*/
|
|
86
|
-
private
|
|
183
|
+
private validateResponse;
|
|
87
184
|
/**
|
|
88
185
|
* Merge tools from config and MCP servers
|
|
89
186
|
*/
|
|
@@ -92,21 +189,15 @@ export declare class Agent {
|
|
|
92
189
|
* Merge hooks from multiple sources
|
|
93
190
|
*/
|
|
94
191
|
private mergeHooks;
|
|
95
|
-
/**
|
|
96
|
-
* Call hooks of a specific type
|
|
97
|
-
*/
|
|
98
|
-
private callHooks;
|
|
99
192
|
/**
|
|
100
193
|
* Set up environment variables
|
|
194
|
+
* @side effects Modifies process.env with provided values and returns original values for restoration.
|
|
195
|
+
* Restores environment in finally block of executePrompt.
|
|
101
196
|
*/
|
|
102
197
|
private setupEnvironment;
|
|
103
198
|
/**
|
|
104
199
|
* Restore environment variables
|
|
105
200
|
*/
|
|
106
201
|
private restoreEnvironment;
|
|
107
|
-
/**
|
|
108
|
-
* Add token usage from response
|
|
109
|
-
*/
|
|
110
|
-
private addUsage;
|
|
111
202
|
}
|
|
112
203
|
//# sourceMappingURL=agent.d.ts.map
|
package/dist/core/agent.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/core/agent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EAGf,UAAU,EAMV,aAAa,EAEd,MAAM,mBAAmB,CAAC;AAK3B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAkB9C,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,uBAAuB,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,8BAA8B;IAC9B,IAAI,EAAE,CAAC,CAAC;IACR,+BAA+B;IAC/B,KAAK,EAAE,UAAU,CAAC;IAClB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,qBAAa,KAAK;IAChB,gDAAgD;IAChD,SAAgB,EAAE,EAAE,MAAM,CAAC;IAE3B,iBAAiB;IACjB,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,2BAA2B;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IAErC,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IAExC,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAEhD,2BAA2B;IAC3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B,+DAA+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAY;IAEvC,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAiB;IAEjD,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAElC;;;OAGG;gBACS,MAAM,GAAE,WAAgB;IA0DpC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;YACW,YAAY;IA+B1B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,4BAA4B;IA4BpC;;;;;OAKG;IACU,MAAM,CAAC,CAAC,EACnB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,SAAS,CAAC,EAAE,eAAe,GAC1B,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAI5B;;;;;;OAMG;IACU,kBAAkB,CAAC,CAAC,EAC/B,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,SAAS,CAAC,EAAE,eAAe,GAC1B,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAc3B;;;;;;;;OAQG;IACU,OAAO,CAAC,CAAC,EACpB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,SAAS,CAAC,EAAE,eAAe,GAC1B,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAqB5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACI,MAAM,CAAC,CAAC,EACb,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,SAAS,CAAC,EAAE,eAAe,GAC1B,WAAW,CAAC,CAAC,CAAC;IAyNjB;;OAEG;IACI,aAAa,IAAI,UAAU;IAIlC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAOzB;;;;;OAKG;YACW,aAAa;IAgV3B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,gBAAgB;IAyCxB;;OAEG;IACH,OAAO,CAAC,UAAU;IAQlB;;OAEG;IACH,OAAO,CAAC,UAAU;IA6BlB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAaxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAS3B"}
|