@amaranthic/hernex 0.0.0-stage → 0.3.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/CHANGELOG.md +261 -0
- package/LICENSE +21 -0
- package/README.md +66 -2
- package/dist/ai.d.ts +11 -0
- package/dist/ai.d.ts.map +1 -0
- package/dist/ai.js +11 -0
- package/dist/ai.js.map +1 -0
- package/dist/checkpoints/FileCheckpointStore.d.ts +95 -0
- package/dist/checkpoints/FileCheckpointStore.d.ts.map +1 -0
- package/dist/checkpoints/FileCheckpointStore.js +502 -0
- package/dist/checkpoints/FileCheckpointStore.js.map +1 -0
- package/dist/checkpoints/index.d.ts +7 -0
- package/dist/checkpoints/index.d.ts.map +1 -0
- package/dist/checkpoints/index.js +7 -0
- package/dist/checkpoints/index.js.map +1 -0
- package/dist/checkpoints/types.d.ts +157 -0
- package/dist/checkpoints/types.d.ts.map +1 -0
- package/dist/checkpoints/types.js +6 -0
- package/dist/checkpoints/types.js.map +1 -0
- package/dist/engine/AgentEngine.d.ts +156 -0
- package/dist/engine/AgentEngine.d.ts.map +1 -0
- package/dist/engine/AgentEngine.js +290 -0
- package/dist/engine/AgentEngine.js.map +1 -0
- package/dist/engine/engineConfig.d.ts +138 -0
- package/dist/engine/engineConfig.d.ts.map +1 -0
- package/dist/engine/engineConfig.js +6 -0
- package/dist/engine/engineConfig.js.map +1 -0
- package/dist/engine/eventQueue.d.ts +42 -0
- package/dist/engine/eventQueue.d.ts.map +1 -0
- package/dist/engine/eventQueue.js +93 -0
- package/dist/engine/eventQueue.js.map +1 -0
- package/dist/engine/index.d.ts +7 -0
- package/dist/engine/index.d.ts.map +1 -0
- package/dist/engine/index.js +6 -0
- package/dist/engine/index.js.map +1 -0
- package/dist/engine/runTurn.d.ts +17 -0
- package/dist/engine/runTurn.d.ts.map +1 -0
- package/dist/engine/runTurn.js +718 -0
- package/dist/engine/runTurn.js.map +1 -0
- package/dist/errors.d.ts +194 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +219 -0
- package/dist/errors.js.map +1 -0
- package/dist/events/checkpointEvents.d.ts +20 -0
- package/dist/events/checkpointEvents.d.ts.map +1 -0
- package/dist/events/checkpointEvents.js +6 -0
- package/dist/events/checkpointEvents.js.map +1 -0
- package/dist/events/errorEvents.d.ts +23 -0
- package/dist/events/errorEvents.d.ts.map +1 -0
- package/dist/events/errorEvents.js +6 -0
- package/dist/events/errorEvents.js.map +1 -0
- package/dist/events/index.d.ts +11 -0
- package/dist/events/index.d.ts.map +1 -0
- package/dist/events/index.js +6 -0
- package/dist/events/index.js.map +1 -0
- package/dist/events/stepEvents.d.ts +68 -0
- package/dist/events/stepEvents.d.ts.map +1 -0
- package/dist/events/stepEvents.js +6 -0
- package/dist/events/stepEvents.js.map +1 -0
- package/dist/events/streamEvents.d.ts +41 -0
- package/dist/events/streamEvents.d.ts.map +1 -0
- package/dist/events/streamEvents.js +6 -0
- package/dist/events/streamEvents.js.map +1 -0
- package/dist/events/toolEvents.d.ts +64 -0
- package/dist/events/toolEvents.d.ts.map +1 -0
- package/dist/events/toolEvents.js +6 -0
- package/dist/events/toolEvents.js.map +1 -0
- package/dist/events/types.d.ts +44 -0
- package/dist/events/types.d.ts.map +1 -0
- package/dist/events/types.js +25 -0
- package/dist/events/types.js.map +1 -0
- package/dist/hooks/composeAgentHooks.d.ts +14 -0
- package/dist/hooks/composeAgentHooks.d.ts.map +1 -0
- package/dist/hooks/composeAgentHooks.js +154 -0
- package/dist/hooks/composeAgentHooks.js.map +1 -0
- package/dist/hooks/index.d.ts +7 -0
- package/dist/hooks/index.d.ts.map +1 -0
- package/dist/hooks/index.js +6 -0
- package/dist/hooks/index.js.map +1 -0
- package/dist/hooks/types.d.ts +133 -0
- package/dist/hooks/types.d.ts.map +1 -0
- package/dist/hooks/types.js +6 -0
- package/dist/hooks/types.js.map +1 -0
- package/dist/index.d.ts +28 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +26 -0
- package/dist/index.js.map +1 -0
- package/dist/model/ProviderRegistry.d.ts +62 -0
- package/dist/model/ProviderRegistry.d.ts.map +1 -0
- package/dist/model/ProviderRegistry.js +114 -0
- package/dist/model/ProviderRegistry.js.map +1 -0
- package/dist/model/providers/alibaba.d.ts +11 -0
- package/dist/model/providers/alibaba.d.ts.map +1 -0
- package/dist/model/providers/alibaba.js +16 -0
- package/dist/model/providers/alibaba.js.map +1 -0
- package/dist/model/providers/anthropic.d.ts +11 -0
- package/dist/model/providers/anthropic.d.ts.map +1 -0
- package/dist/model/providers/anthropic.js +16 -0
- package/dist/model/providers/anthropic.js.map +1 -0
- package/dist/model/providers/cohere.d.ts +11 -0
- package/dist/model/providers/cohere.d.ts.map +1 -0
- package/dist/model/providers/cohere.js +16 -0
- package/dist/model/providers/cohere.js.map +1 -0
- package/dist/model/providers/compatible.d.ts +11 -0
- package/dist/model/providers/compatible.d.ts.map +1 -0
- package/dist/model/providers/compatible.js +17 -0
- package/dist/model/providers/compatible.js.map +1 -0
- package/dist/model/providers/deepseek.d.ts +11 -0
- package/dist/model/providers/deepseek.d.ts.map +1 -0
- package/dist/model/providers/deepseek.js +16 -0
- package/dist/model/providers/deepseek.js.map +1 -0
- package/dist/model/providers/google.d.ts +11 -0
- package/dist/model/providers/google.d.ts.map +1 -0
- package/dist/model/providers/google.js +16 -0
- package/dist/model/providers/google.js.map +1 -0
- package/dist/model/providers/groq.d.ts +11 -0
- package/dist/model/providers/groq.d.ts.map +1 -0
- package/dist/model/providers/groq.js +16 -0
- package/dist/model/providers/groq.js.map +1 -0
- package/dist/model/providers/mistral.d.ts +11 -0
- package/dist/model/providers/mistral.d.ts.map +1 -0
- package/dist/model/providers/mistral.js +16 -0
- package/dist/model/providers/mistral.js.map +1 -0
- package/dist/model/providers/openai.d.ts +11 -0
- package/dist/model/providers/openai.d.ts.map +1 -0
- package/dist/model/providers/openai.js +16 -0
- package/dist/model/providers/openai.js.map +1 -0
- package/dist/model/providers/openrouter.d.ts +14 -0
- package/dist/model/providers/openrouter.d.ts.map +1 -0
- package/dist/model/providers/openrouter.js +20 -0
- package/dist/model/providers/openrouter.js.map +1 -0
- package/dist/model/providers/togetherai.d.ts +11 -0
- package/dist/model/providers/togetherai.d.ts.map +1 -0
- package/dist/model/providers/togetherai.js +16 -0
- package/dist/model/providers/togetherai.js.map +1 -0
- package/dist/model/providers/vercelGateway.d.ts +14 -0
- package/dist/model/providers/vercelGateway.d.ts.map +1 -0
- package/dist/model/providers/vercelGateway.js +19 -0
- package/dist/model/providers/vercelGateway.js.map +1 -0
- package/dist/model/providers/xai.d.ts +11 -0
- package/dist/model/providers/xai.d.ts.map +1 -0
- package/dist/model/providers/xai.js +16 -0
- package/dist/model/providers/xai.js.map +1 -0
- package/dist/model/resolveModel.d.ts +45 -0
- package/dist/model/resolveModel.d.ts.map +1 -0
- package/dist/model/resolveModel.js +109 -0
- package/dist/model/resolveModel.js.map +1 -0
- package/dist/model/types.d.ts +98 -0
- package/dist/model/types.d.ts.map +1 -0
- package/dist/model/types.js +6 -0
- package/dist/model/types.js.map +1 -0
- package/dist/runtime.d.ts +74 -0
- package/dist/runtime.d.ts.map +1 -0
- package/dist/runtime.js +41 -0
- package/dist/runtime.js.map +1 -0
- package/dist/storage/atomicFile.d.ts +28 -0
- package/dist/storage/atomicFile.d.ts.map +1 -0
- package/dist/storage/atomicFile.js +82 -0
- package/dist/storage/atomicFile.js.map +1 -0
- package/dist/storage/homeDirectory.d.ts +21 -0
- package/dist/storage/homeDirectory.d.ts.map +1 -0
- package/dist/storage/homeDirectory.js +36 -0
- package/dist/storage/homeDirectory.js.map +1 -0
- package/dist/storage/index.d.ts +11 -0
- package/dist/storage/index.d.ts.map +1 -0
- package/dist/storage/index.js +11 -0
- package/dist/storage/index.js.map +1 -0
- package/dist/storage/jsonl.d.ts +55 -0
- package/dist/storage/jsonl.d.ts.map +1 -0
- package/dist/storage/jsonl.js +142 -0
- package/dist/storage/jsonl.js.map +1 -0
- package/dist/storage/lock.d.ts +70 -0
- package/dist/storage/lock.d.ts.map +1 -0
- package/dist/storage/lock.js +274 -0
- package/dist/storage/lock.js.map +1 -0
- package/dist/storage/valueCodec.d.ts +74 -0
- package/dist/storage/valueCodec.d.ts.map +1 -0
- package/dist/storage/valueCodec.js +165 -0
- package/dist/storage/valueCodec.js.map +1 -0
- package/dist/storage/workspaceLock.d.ts +38 -0
- package/dist/storage/workspaceLock.d.ts.map +1 -0
- package/dist/storage/workspaceLock.js +77 -0
- package/dist/storage/workspaceLock.js.map +1 -0
- package/dist/tasks/TaskManager.d.ts +155 -0
- package/dist/tasks/TaskManager.d.ts.map +1 -0
- package/dist/tasks/TaskManager.js +810 -0
- package/dist/tasks/TaskManager.js.map +1 -0
- package/dist/tasks/index.d.ts +7 -0
- package/dist/tasks/index.d.ts.map +1 -0
- package/dist/tasks/index.js +6 -0
- package/dist/tasks/index.js.map +1 -0
- package/dist/tasks/types.d.ts +166 -0
- package/dist/tasks/types.d.ts.map +1 -0
- package/dist/tasks/types.js +8 -0
- package/dist/tasks/types.js.map +1 -0
- package/dist/threads/FileThreadStore.d.ts +118 -0
- package/dist/threads/FileThreadStore.d.ts.map +1 -0
- package/dist/threads/FileThreadStore.js +324 -0
- package/dist/threads/FileThreadStore.js.map +1 -0
- package/dist/threads/index.d.ts +9 -0
- package/dist/threads/index.d.ts.map +1 -0
- package/dist/threads/index.js +9 -0
- package/dist/threads/index.js.map +1 -0
- package/dist/threads/transcriptMigration.d.ts +52 -0
- package/dist/threads/transcriptMigration.d.ts.map +1 -0
- package/dist/threads/transcriptMigration.js +100 -0
- package/dist/threads/transcriptMigration.js.map +1 -0
- package/dist/threads/transcriptProjection.d.ts +21 -0
- package/dist/threads/transcriptProjection.d.ts.map +1 -0
- package/dist/threads/transcriptProjection.js +123 -0
- package/dist/threads/transcriptProjection.js.map +1 -0
- package/dist/threads/types.d.ts +250 -0
- package/dist/threads/types.d.ts.map +1 -0
- package/dist/threads/types.js +6 -0
- package/dist/threads/types.js.map +1 -0
- package/dist/tools/AgentTool.d.ts +38 -0
- package/dist/tools/AgentTool.d.ts.map +1 -0
- package/dist/tools/AgentTool.js +6 -0
- package/dist/tools/AgentTool.js.map +1 -0
- package/dist/tools/BashTool.d.ts +61 -0
- package/dist/tools/BashTool.d.ts.map +1 -0
- package/dist/tools/BashTool.js +158 -0
- package/dist/tools/BashTool.js.map +1 -0
- package/dist/tools/EditFileTool.d.ts +49 -0
- package/dist/tools/EditFileTool.d.ts.map +1 -0
- package/dist/tools/EditFileTool.js +119 -0
- package/dist/tools/EditFileTool.js.map +1 -0
- package/dist/tools/GlobTool.d.ts +48 -0
- package/dist/tools/GlobTool.d.ts.map +1 -0
- package/dist/tools/GlobTool.js +117 -0
- package/dist/tools/GlobTool.js.map +1 -0
- package/dist/tools/GrepTool.d.ts +76 -0
- package/dist/tools/GrepTool.d.ts.map +1 -0
- package/dist/tools/GrepTool.js +276 -0
- package/dist/tools/GrepTool.js.map +1 -0
- package/dist/tools/ReadFileTool.d.ts +51 -0
- package/dist/tools/ReadFileTool.d.ts.map +1 -0
- package/dist/tools/ReadFileTool.js +153 -0
- package/dist/tools/ReadFileTool.js.map +1 -0
- package/dist/tools/TaskManagerTool.d.ts +102 -0
- package/dist/tools/TaskManagerTool.d.ts.map +1 -0
- package/dist/tools/TaskManagerTool.js +132 -0
- package/dist/tools/TaskManagerTool.js.map +1 -0
- package/dist/tools/ToolExecutionContext.d.ts +61 -0
- package/dist/tools/ToolExecutionContext.d.ts.map +1 -0
- package/dist/tools/ToolExecutionContext.js +8 -0
- package/dist/tools/ToolExecutionContext.js.map +1 -0
- package/dist/tools/ToolRegistry.d.ts +82 -0
- package/dist/tools/ToolRegistry.d.ts.map +1 -0
- package/dist/tools/ToolRegistry.js +116 -0
- package/dist/tools/ToolRegistry.js.map +1 -0
- package/dist/tools/WriteFileTool.d.ts +46 -0
- package/dist/tools/WriteFileTool.d.ts.map +1 -0
- package/dist/tools/WriteFileTool.js +92 -0
- package/dist/tools/WriteFileTool.js.map +1 -0
- package/dist/tools/index.d.ts +17 -0
- package/dist/tools/index.d.ts.map +1 -0
- package/dist/tools/index.js +17 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/internal/bashEnvironment.d.ts +20 -0
- package/dist/tools/internal/bashEnvironment.d.ts.map +1 -0
- package/dist/tools/internal/bashEnvironment.js +65 -0
- package/dist/tools/internal/bashEnvironment.js.map +1 -0
- package/dist/tools/internal/pathGuard.d.ts +27 -0
- package/dist/tools/internal/pathGuard.d.ts.map +1 -0
- package/dist/tools/internal/pathGuard.js +99 -0
- package/dist/tools/internal/pathGuard.js.map +1 -0
- package/dist/tools/prompts.d.ts +33 -0
- package/dist/tools/prompts.d.ts.map +1 -0
- package/dist/tools/prompts.js +48 -0
- package/dist/tools/prompts.js.map +1 -0
- package/package.json +65 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `@amaranthic/hernex` are documented in this file.
|
|
4
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
5
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## [0.3.0] - 2026-11-12
|
|
10
|
+
|
|
11
|
+
### Summary
|
|
12
|
+
|
|
13
|
+
Version `0.3.0` represents a comprehensive architectural overhaul, hardening the microkernel agent engine, standardizing conversational persistence terminology, enforcing strict tool schema validation, introducing workspace-wide transactional file locking, upgrading transcript replay to full AI SDK v7 compatibility, and eliminating prototype pollution and serialization bugs.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
### Migration Guide: Upgrading from `0.1.x`
|
|
18
|
+
|
|
19
|
+
This section details every breaking change between `0.1.x` and `0.3.0` and provides clear code examples on how to update older code.
|
|
20
|
+
|
|
21
|
+
#### 1. Package Rebrand: `@amaranthic/harnex` → `@amaranthic/hernex`
|
|
22
|
+
|
|
23
|
+
The package and repository have been renamed to `@amaranthic/hernex`.
|
|
24
|
+
|
|
25
|
+
**Before (`0.1.x`):**
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
import { AgentEngine, FileThreadStore } from "@amaranthic/harnex";
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
**After (`0.3.0`):**
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
import { AgentEngine, FileThreadStore } from "@amaranthic/hernex";
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Update your `package.json`:
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"dependencies": {
|
|
42
|
+
"@amaranthic/hernex": "^0.3.0"
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
#### 2. Terminology Standardization: `Session` → `Thread`
|
|
50
|
+
|
|
51
|
+
All persisted conversation state, identifiers, and storage methods now consistently use `thread` and `threadId` instead of `session` or `sessionId`.
|
|
52
|
+
|
|
53
|
+
**Before (`0.1.x`):**
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
const engine = new AgentEngine({
|
|
57
|
+
sessionId: "session-123",
|
|
58
|
+
sessionStore: new FileSessionStore({ storageDirectory: "./data" }),
|
|
59
|
+
// ...
|
|
60
|
+
});
|
|
61
|
+
|
|
62
|
+
const session = await engine.sessionStore.getSession("session-123");
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**After (`0.3.0`):**
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
const engine = new AgentEngine({
|
|
69
|
+
threadId: "thread-123",
|
|
70
|
+
threadStore: new FileThreadStore({ storageDirectory: "./data" }),
|
|
71
|
+
// ...
|
|
72
|
+
});
|
|
73
|
+
|
|
74
|
+
const thread = await engine.threadStore.getThread("thread-123");
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
**Key API Renames:**
|
|
78
|
+
|
|
79
|
+
| Older API (`0.1.x`) | New API (`0.3.0`) |
|
|
80
|
+
| :------------------------------------------ | :---------------------------------------- |
|
|
81
|
+
| `config.sessionId` | `config.threadId` |
|
|
82
|
+
| `config.sessionStore` | `config.threadStore` |
|
|
83
|
+
| `engine.sessionId` | `engine.threadId` |
|
|
84
|
+
| `engine.sessionStore` | `engine.threadStore` |
|
|
85
|
+
| `FileSessionStore` | `FileThreadStore` |
|
|
86
|
+
| `SessionStore` (interface) | `ThreadStore` (interface) |
|
|
87
|
+
| `SessionRecord` / `SessionMetadata` | `ThreadRecord` / `ThreadMetadata` |
|
|
88
|
+
| `CreateSessionInput` / `UpdateSessionInput` | `CreateThreadInput` / `UpdateThreadInput` |
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
#### 3. Tool Input Schemas: `GlobTool` and `GrepTool`
|
|
93
|
+
|
|
94
|
+
Tool parameter schemas have been aligned with standard filesystem semantics and made strictly unambiguous.
|
|
95
|
+
|
|
96
|
+
##### A. `GlobTool`
|
|
97
|
+
|
|
98
|
+
- Renamed the ambiguous `path` parameter to `directoryPath`.
|
|
99
|
+
|
|
100
|
+
**Before (`0.1.x`):**
|
|
101
|
+
|
|
102
|
+
```ts
|
|
103
|
+
await globTool.execute({
|
|
104
|
+
pattern: "**/*.ts",
|
|
105
|
+
path: "./src", // Ambiguous
|
|
106
|
+
});
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
**After (`0.3.0`):**
|
|
110
|
+
|
|
111
|
+
```ts
|
|
112
|
+
await globTool.execute({
|
|
113
|
+
pattern: "**/*.ts",
|
|
114
|
+
directoryPath: "./src", // Required, unambiguous directory target
|
|
115
|
+
});
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
##### B. `GrepTool`
|
|
119
|
+
|
|
120
|
+
- Replaced ambiguous `path` with mutually exclusive `filePath` and `directoryPath`.
|
|
121
|
+
|
|
122
|
+
**Before (`0.1.x`):**
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
await grepTool.execute({
|
|
126
|
+
pattern: "export function",
|
|
127
|
+
path: "./src/index.ts", // or path: "./src"
|
|
128
|
+
});
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
**After (`0.3.0`):**
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
// For targeted single-file search:
|
|
135
|
+
await grepTool.execute({
|
|
136
|
+
pattern: "export function",
|
|
137
|
+
filePath: "./src/index.ts",
|
|
138
|
+
});
|
|
139
|
+
|
|
140
|
+
// For recursive directory search:
|
|
141
|
+
await grepTool.execute({
|
|
142
|
+
pattern: "export function",
|
|
143
|
+
directoryPath: "./src",
|
|
144
|
+
});
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
> [!NOTE]
|
|
148
|
+
> Passing both `filePath` and `directoryPath` or neither will fail validation with a descriptive Zod error.
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
#### 4. Turn Indexing: 1-Based Numbering Contract
|
|
153
|
+
|
|
154
|
+
Turn indexing across `ToolExecutionContext`, checkpoints, and engine hooks now strictly enforces a 1-based convention (`1, 2, 3, ...`). Turn index `0` is invalid.
|
|
155
|
+
|
|
156
|
+
**Before (`0.1.x`):**
|
|
157
|
+
|
|
158
|
+
```ts
|
|
159
|
+
// Turn counter started at 0 or serialized undefined as 0
|
|
160
|
+
context.turnIndex; // Could be 0
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
**After (`0.3.0`):**
|
|
164
|
+
|
|
165
|
+
```ts
|
|
166
|
+
// Turn counter starts at 1
|
|
167
|
+
context.turnIndex; // Always >= 1
|
|
168
|
+
// Optional turnIndex on checkpoints serializes as undefined when omitted, never 0
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
---
|
|
172
|
+
|
|
173
|
+
#### 5. Checkpoint Restore Error Handling: `HernexCheckpointRestoreError`
|
|
174
|
+
|
|
175
|
+
When restoring checkpoints containing multiple files, if a failure occurs halfway through, Hernex now automatically applies reverse-order rollback compensation to restore already-committed files to their prior state, and throws a typed `HernexCheckpointRestoreError`.
|
|
176
|
+
|
|
177
|
+
**Before (`0.1.x`):**
|
|
178
|
+
|
|
179
|
+
```ts
|
|
180
|
+
try {
|
|
181
|
+
await checkpointStore.restoreCheckpoint("cp-1");
|
|
182
|
+
} catch (error) {
|
|
183
|
+
// Generic error; unknown which files were mutated on disk
|
|
184
|
+
}
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
**After (`0.3.0`):**
|
|
188
|
+
|
|
189
|
+
```ts
|
|
190
|
+
import { HernexCheckpointRestoreError } from "@amaranthic/hernex";
|
|
191
|
+
|
|
192
|
+
try {
|
|
193
|
+
await checkpointStore.restoreCheckpoint("cp-1");
|
|
194
|
+
} catch (error) {
|
|
195
|
+
if (error instanceof HernexCheckpointRestoreError) {
|
|
196
|
+
console.error("Checkpoint restore failed:", error.checkpointId);
|
|
197
|
+
console.error("Compensated files:", error.compensatedPaths);
|
|
198
|
+
console.error(
|
|
199
|
+
"Unrecovered files requiring manual check:",
|
|
200
|
+
error.unrecoveredPaths,
|
|
201
|
+
);
|
|
202
|
+
console.error("Rollback succeeded cleanly:", error.isCompensated);
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
---
|
|
208
|
+
|
|
209
|
+
#### 6. AI SDK v7 Tool Replay & Transcript Projection
|
|
210
|
+
|
|
211
|
+
`FileThreadStore.getMessages(threadId)` now fully projects persisted transcripts into valid AI SDK v7 model messages.
|
|
212
|
+
|
|
213
|
+
- **Assistant Tool Calls & Tool Results**: In AI SDK v7, model tool calls in `role: "assistant"` messages require corresponding `role: "tool"` messages containing tool results. Hernex reconstructs these messages losslessly from persisted `toolResult` entries.
|
|
214
|
+
- **Residue Filtering**: Incompleted turns from crashes, hook vetoes, or failed model calls are automatically filtered out during replay, ensuring clean message histories without prompt corruption.
|
|
215
|
+
- **Transcript Versioning**: Transcripts written with version `1` (or unversioned) are automatically and lazily upgraded to `CURRENT_TRANSCRIPT_VERSION` (version `2`) upon read.
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
### New Features
|
|
220
|
+
|
|
221
|
+
- **Workspace Transactional File Locking (`withWorkspaceFileLock`)**:
|
|
222
|
+
- Exclusive multi-file mutation locking for concurrent tools and threads (`src/storage/workspaceLock.ts`).
|
|
223
|
+
- Locks are keyed outside the workspace in `<homeDirectory>/locks/workspaces/<workspaceHash>/<targetHash>.lock`.
|
|
224
|
+
- Multi-file operations acquire locks in deterministic lexicographical order to prevent deadlocks and lock inversion.
|
|
225
|
+
- Automatically integrated into `WriteFileTool`, `EditFileTool`, and `FileCheckpointStore.restoreCheckpoint`.
|
|
226
|
+
|
|
227
|
+
- **POSIX Permission Preservation (`atomicWriteFile`)**:
|
|
228
|
+
- `atomicWriteFile` inspects regular file permissions (`stats.mode & 0o7777`) via `lstat` prior to replacement and restores them on the newly written file.
|
|
229
|
+
- Supports explicit `{ mode: 0o755 }` overrides.
|
|
230
|
+
|
|
231
|
+
- **Stale Lock Recovery & CAS Arbitration (`withFileLock`)**:
|
|
232
|
+
- Detects abandoned locks from terminated or crashed processes using local OS process liveness probes (`process.kill(pid, 0)` checking for `ESRCH`).
|
|
233
|
+
- Supports configurable `staleMs` expiration for long-hanging processes or network-mounted filesystems.
|
|
234
|
+
- Employs atomic staging and rename arbitration to guarantee live lock holders are never displaced during concurrent recovery.
|
|
235
|
+
|
|
236
|
+
- **Lossless Acyclic Graph Serialization (`valueCodec`)**:
|
|
237
|
+
- Replaced global traversal sets with an active recursion ancestry stack.
|
|
238
|
+
- Supports valid directed acyclic graphs (DAGs), diamond structures, and shared sibling object references without false circular reference errors.
|
|
239
|
+
- Maintains strict cycle detection rejecting true circular references fail-closed.
|
|
240
|
+
|
|
241
|
+
- **Process Tree Abort Management (`BashTool`)**:
|
|
242
|
+
- When a foreground bash execution is interrupted via `abortSignal`, `BashTool` issues `taskManager.stopTask(taskId)` and awaits terminal state escalation (`SIGTERM` followed by `SIGKILL`), ensuring background process trees are never orphaned.
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
### Bug Fixes & Resilience Hardening
|
|
247
|
+
|
|
248
|
+
- **Task Log Persistence Containment**: Protected child stream `data` handlers against disk write failures (e.g. disk full, read-only filesystem). Prevents host process crashes, drains stdout/stderr pipes to prevent buffer stalls, and surfaces `persistenceError` on task metadata.
|
|
249
|
+
- **Prototype Pollution Prevention (`valueCodec`)**: Properties are decoded using `Object.defineProperty` instead of direct assignment, safely preserving own `__proto__` properties without altering prototype chains.
|
|
250
|
+
- **Null-Prototype Dictionaries**: Added `isNullPrototype: true` support in `EncodedValue`, ensuring `Object.create(null)` objects round-trip without acquiring standard `Object.prototype`.
|
|
251
|
+
- **EditFileTool Regex Special Replacements**: Replaced regex string substitution with literal replacer functions, preventing `$1`, `$&`, and `$\`` from corrupting edited source code.
|
|
252
|
+
- **Strict Symlink Traversal Protection**: Hardened `pathGuard` to disallow symbolic links pointing outside the workspace across all filesystem and shell tools.
|
|
253
|
+
- **Idempotent Turn Finalization**: Protected `runTurn` to guarantee exactly one `turnFinished` event is persisted and emitted even if errors occur in `onError` hooks or transcript serialization.
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
### Publication Details
|
|
258
|
+
|
|
259
|
+
- Package: `@amaranthic/hernex`
|
|
260
|
+
- License: MIT
|
|
261
|
+
- Node.js Requirement: `>= 22.0.0`
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Amaranthic
|
|
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
|
@@ -1,3 +1,67 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @amaranthic/hernex
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@amaranthic/hernex)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](https://nodejs.org)
|
|
6
|
+
[](https://bun.sh)
|
|
7
|
+
[](https://ai-sdk.dev)
|
|
8
|
+
[](https://www.typescriptlang.org)
|
|
9
|
+
|
|
10
|
+
Hernex is a focused agent execution harness and runtime bridge between application code and the Vercel AI SDK. It provides deterministic multi-step turn loops, fail-closed tool authorization, single-owner process execution, and content-addressed snapshot rollbacks while leaving agent personas, user experience, and high-level goal planning to product code.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## Quick Start
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
bun add @amaranthic/hernex
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
```typescript
|
|
21
|
+
import { AgentEngine, ToolRegistry } from "@amaranthic/hernex";
|
|
22
|
+
|
|
23
|
+
const tools = new ToolRegistry({ includeDefaults: true });
|
|
24
|
+
|
|
25
|
+
const engine = new AgentEngine({
|
|
26
|
+
threadId: "thread-001",
|
|
27
|
+
workingDirectory: process.cwd(),
|
|
28
|
+
model: "anthropic/claude-3-7-sonnet",
|
|
29
|
+
apiKey: process.env.ANTHROPIC_API_KEY!,
|
|
30
|
+
baseUrl: "https://api.anthropic.com/v1",
|
|
31
|
+
tools,
|
|
32
|
+
hooks: {
|
|
33
|
+
onAuthorizeTool: async () => ({ decision: "allow" }),
|
|
34
|
+
},
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
for await (const event of engine.runTurn("Check working directory status")) {
|
|
38
|
+
if (event.type === "tokenDelta") {
|
|
39
|
+
process.stdout.write(event.text);
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Key Invariants
|
|
47
|
+
|
|
48
|
+
1. **Explicit Credentials**: All runtime calls require explicit, non-empty `apiKey` and `baseUrl`. There are no hidden ambient environment variable fallbacks.
|
|
49
|
+
2. **First-Slash Model Parsing**: Models format as `provider/model_id` (e.g. `openrouter/openrouter/free`). Splitting occurs strictly on the first slash only.
|
|
50
|
+
3. **Fail-Closed Authorization**: All tools require explicit authorization via `hooks.onAuthorizeTool`; omission denies execution.
|
|
51
|
+
4. **Host Shell Capability**: `BashTool` runs with the host user's permissions with environment sanitization. It is an authorized host shell capability, not a filesystem sandbox.
|
|
52
|
+
5. **Raw SDK Subpath**: Direct Vercel AI SDK functions and schemas remain accessible via `@amaranthic/hernex/ai`.
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Documentation
|
|
57
|
+
|
|
58
|
+
- [Agent Engine & Turn Lifecycle](docs/agent.md)
|
|
59
|
+
- [Outward Streaming Events](docs/events.md)
|
|
60
|
+
- [Inward Interception Hooks](docs/hooks.md)
|
|
61
|
+
- [Tool Registry & Process Tools](docs/tools.md)
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## License
|
|
66
|
+
|
|
67
|
+
MIT © Amaranthic
|
package/dist/ai.d.ts
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Explicit raw Vercel AI SDK escape hatch for `@amaranthic/hernex/ai`.
|
|
3
|
+
*
|
|
4
|
+
* @remarks
|
|
5
|
+
* Invocations made through this subpath bypass Hernex's mandatory credential pairing
|
|
6
|
+
* and model string routing, executing with native AI SDK semantics.
|
|
7
|
+
*
|
|
8
|
+
* @packageDocumentation
|
|
9
|
+
*/
|
|
10
|
+
export * from "ai";
|
|
11
|
+
//# sourceMappingURL=ai.d.ts.map
|
package/dist/ai.d.ts.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ai.d.ts","sources":["../src/ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,IAAI,CAAC"}
|
package/dist/ai.js
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Explicit raw Vercel AI SDK escape hatch for `@amaranthic/hernex/ai`.
|
|
3
|
+
*
|
|
4
|
+
* @remarks
|
|
5
|
+
* Invocations made through this subpath bypass Hernex's mandatory credential pairing
|
|
6
|
+
* and model string routing, executing with native AI SDK semantics.
|
|
7
|
+
*
|
|
8
|
+
* @packageDocumentation
|
|
9
|
+
*/
|
|
10
|
+
export * from "ai";
|
|
11
|
+
//# sourceMappingURL=ai.js.map
|
package/dist/ai.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"ai.js","sources":["../src/ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,IAAI,CAAC"}
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Filesystem-backed content-addressed CheckpointStore with delta snapshots and safe conflict detection.
|
|
3
|
+
* @packageDocumentation
|
|
4
|
+
*/
|
|
5
|
+
import { type ResolveHomeDirectoryOptions } from "../storage/homeDirectory.js";
|
|
6
|
+
import type { CheckpointRecord, CheckpointStore, CreateCheckpointInput, RestorePlan, RestoreResult } from "./types.js";
|
|
7
|
+
/**
|
|
8
|
+
* FileCheckpointStore provides persistent content-addressed checkpointing
|
|
9
|
+
* and rollback verification across thread-scoped workspace files.
|
|
10
|
+
*/
|
|
11
|
+
export declare class FileCheckpointStore implements CheckpointStore {
|
|
12
|
+
private readonly rootDir;
|
|
13
|
+
/**
|
|
14
|
+
* Initializes a new FileCheckpointStore instance.
|
|
15
|
+
*
|
|
16
|
+
* @param options - Storage options including custom home directory.
|
|
17
|
+
*/
|
|
18
|
+
constructor(options?: ResolveHomeDirectoryOptions);
|
|
19
|
+
/**
|
|
20
|
+
* Validates safe identifier grammar for threads and checkpoints.
|
|
21
|
+
*
|
|
22
|
+
* @param id - Identifier string.
|
|
23
|
+
* @param label - Human-readable label for error reporting.
|
|
24
|
+
*/
|
|
25
|
+
private validateId;
|
|
26
|
+
/**
|
|
27
|
+
* Validates SHA-256 hexadecimal hash strings.
|
|
28
|
+
*
|
|
29
|
+
* @param hash - Hash string to validate.
|
|
30
|
+
*/
|
|
31
|
+
private validateSha256;
|
|
32
|
+
/**
|
|
33
|
+
* Resolves the manifest file path for a thread.
|
|
34
|
+
*/
|
|
35
|
+
private getManifestPath;
|
|
36
|
+
/**
|
|
37
|
+
* Resolves the content-addressed blob storage path for a given SHA-256 digest.
|
|
38
|
+
*/
|
|
39
|
+
private getBlobPath;
|
|
40
|
+
/**
|
|
41
|
+
* Resolves the external lock path for thread checkpoint operations.
|
|
42
|
+
*/
|
|
43
|
+
private getLockPath;
|
|
44
|
+
/**
|
|
45
|
+
* Stores raw data in the content-addressed blob store with SHA-256 digest validation.
|
|
46
|
+
*/
|
|
47
|
+
private storeBlob;
|
|
48
|
+
/**
|
|
49
|
+
* Reads a raw blob from the content-addressed store and verifies its integrity.
|
|
50
|
+
*/
|
|
51
|
+
private readBlob;
|
|
52
|
+
/**
|
|
53
|
+
* Internal unlocked helper to read and validate the thread checkpoint manifest.
|
|
54
|
+
*/
|
|
55
|
+
private readManifestUnlocked;
|
|
56
|
+
/**
|
|
57
|
+
* Internal unlocked helper to save checkpoint manifest under the version 2 envelope.
|
|
58
|
+
*/
|
|
59
|
+
private writeManifestUnlocked;
|
|
60
|
+
/**
|
|
61
|
+
* Lists all recorded checkpoints for a thread ordered chronologically under lock.
|
|
62
|
+
*/
|
|
63
|
+
listCheckpoints(threadId: string): Promise<readonly CheckpointRecord[]>;
|
|
64
|
+
/**
|
|
65
|
+
* Retrieves a checkpoint record by thread and checkpoint identifier under lock.
|
|
66
|
+
*/
|
|
67
|
+
getCheckpoint(threadId: string, checkpointId: string): Promise<CheckpointRecord | undefined>;
|
|
68
|
+
/**
|
|
69
|
+
* Records a pre-mutation snapshot of the specified workspace files under lock.
|
|
70
|
+
*/
|
|
71
|
+
createCheckpoint(threadId: string, input: CreateCheckpointInput): Promise<CheckpointRecord>;
|
|
72
|
+
/**
|
|
73
|
+
* Updates an existing checkpoint after mutation with the post-state file hashes.
|
|
74
|
+
*/
|
|
75
|
+
updateCheckpoint(threadId: string, checkpointId: string, workingDirectory: string): Promise<CheckpointRecord>;
|
|
76
|
+
/**
|
|
77
|
+
* Deletes a checkpoint record from the thread manifest under lock.
|
|
78
|
+
*/
|
|
79
|
+
deleteCheckpoint(threadId: string, checkpointId: string): Promise<boolean>;
|
|
80
|
+
/**
|
|
81
|
+
* Internal unlocked helper to compute the restore plan for a checkpoint.
|
|
82
|
+
*/
|
|
83
|
+
private planRestoreUnlocked;
|
|
84
|
+
/**
|
|
85
|
+
* Preflights and plans the restoration of a checkpoint under lock.
|
|
86
|
+
*/
|
|
87
|
+
planRestore(threadId: string, checkpointId: string, workingDirectory: string): Promise<RestorePlan>;
|
|
88
|
+
/**
|
|
89
|
+
* Restores workspace files to their recorded pre-mutation state under lock.
|
|
90
|
+
*/
|
|
91
|
+
restoreCheckpoint(threadId: string, checkpointId: string, workingDirectory: string, options?: {
|
|
92
|
+
readonly force?: boolean;
|
|
93
|
+
} | undefined): Promise<RestoreResult>;
|
|
94
|
+
}
|
|
95
|
+
//# sourceMappingURL=FileCheckpointStore.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"FileCheckpointStore.d.ts","sources":["../../src/checkpoints/FileCheckpointStore.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,6BAA6B,CAAC;AAIrC,OAAO,KAAK,EAEV,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EAErB,WAAW,EACX,aAAa,EACd,MAAM,YAAY,CAAC;AAgBpB;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;;OAIG;IACH,YAAmB,OAAO,CAAC,EAAE,2BAA2B,EAEvD;IAED;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAMlB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAMtB;;OAEG;IACH,OAAO,CAAC,eAAe;IAWvB;;OAEG;IACH,OAAO,CAAC,WAAW;IAKnB;;OAEG;IACH,OAAO,CAAC,WAAW;IAKnB;;OAEG;YACW,SAAS;IAWvB;;OAEG;YACW,QAAQ;IAkBtB;;OAEG;YACW,oBAAoB;IAuClC;;OAEG;YACW,qBAAqB;IAYnC;;OAEG;IACU,eAAe,CAC1B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAOtC;IAED;;OAEG;IACU,aAAa,CACxB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CASvC;IAED;;OAEG;IACU,gBAAgB,CAC3B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CA8D3B;IAED;;OAEG;IACU,gBAAgB,CAC3B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,gBAAgB,CAAC,CAiD3B;IAED;;OAEG;IACU,gBAAgB,CAC3B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,OAAO,CAAC,CAclB;IAED;;OAEG;YACW,mBAAmB;IAmDjC;;OAEG;IACU,WAAW,CACtB,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,WAAW,CAAC,CAatB;IAED;;OAEG;IACU,iBAAiB,CAC5B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,GACjD,OAAO,CAAC,aAAa,CAAC,CA0MxB;CACF"}
|