@amaranthic/hernex 0.2.0 → 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/README.md +2 -2
- package/dist/checkpoints/FileCheckpointStore.d.ts.map +1 -1
- package/dist/checkpoints/FileCheckpointStore.js +105 -15
- package/dist/checkpoints/FileCheckpointStore.js.map +1 -1
- package/dist/checkpoints/types.d.ts +4 -4
- package/dist/checkpoints/types.d.ts.map +1 -1
- package/dist/engine/AgentEngine.d.ts +4 -4
- package/dist/engine/AgentEngine.d.ts.map +1 -1
- package/dist/engine/AgentEngine.js +9 -7
- package/dist/engine/AgentEngine.js.map +1 -1
- package/dist/engine/engineConfig.d.ts +2 -2
- package/dist/engine/engineConfig.d.ts.map +1 -1
- package/dist/engine/index.d.ts +1 -1
- package/dist/engine/index.d.ts.map +1 -1
- package/dist/engine/index.js.map +1 -1
- package/dist/engine/runTurn.d.ts.map +1 -1
- package/dist/engine/runTurn.js +85 -51
- package/dist/engine/runTurn.js.map +1 -1
- package/dist/errors.d.ts +52 -0
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +45 -0
- package/dist/errors.js.map +1 -1
- package/dist/events/checkpointEvents.d.ts +1 -1
- package/dist/events/index.d.ts +4 -4
- package/dist/events/index.d.ts.map +1 -1
- package/dist/events/stepEvents.d.ts +1 -1
- package/dist/events/stepEvents.d.ts.map +1 -1
- package/dist/events/streamEvents.d.ts +2 -2
- package/dist/events/toolEvents.d.ts +4 -2
- package/dist/events/toolEvents.d.ts.map +1 -1
- package/dist/events/types.d.ts +7 -0
- package/dist/events/types.d.ts.map +1 -1
- package/dist/events/types.js +20 -1
- package/dist/events/types.js.map +1 -1
- package/dist/hooks/composeAgentHooks.d.ts.map +1 -1
- package/dist/hooks/composeAgentHooks.js +19 -7
- package/dist/hooks/composeAgentHooks.js.map +1 -1
- package/dist/hooks/types.d.ts +1 -1
- package/dist/hooks/types.d.ts.map +1 -1
- package/dist/index.d.ts +8 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -6
- package/dist/index.js.map +1 -1
- package/dist/model/resolveModel.d.ts.map +1 -1
- package/dist/model/resolveModel.js +1 -1
- package/dist/model/resolveModel.js.map +1 -1
- package/dist/model/types.d.ts.map +1 -1
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +1 -1
- package/dist/runtime.js.map +1 -1
- package/dist/storage/atomicFile.d.ts +1 -1
- package/dist/storage/atomicFile.d.ts.map +1 -1
- package/dist/storage/atomicFile.js +28 -2
- package/dist/storage/atomicFile.js.map +1 -1
- package/dist/storage/homeDirectory.d.ts +1 -1
- package/dist/storage/homeDirectory.d.ts.map +1 -1
- package/dist/storage/index.d.ts +1 -0
- package/dist/storage/index.d.ts.map +1 -1
- package/dist/storage/index.js +1 -0
- package/dist/storage/index.js.map +1 -1
- package/dist/storage/jsonl.d.ts +9 -0
- package/dist/storage/jsonl.d.ts.map +1 -1
- package/dist/storage/jsonl.js +22 -1
- package/dist/storage/jsonl.js.map +1 -1
- package/dist/storage/lock.d.ts +23 -0
- package/dist/storage/lock.d.ts.map +1 -1
- package/dist/storage/lock.js +149 -1
- package/dist/storage/lock.js.map +1 -1
- package/dist/storage/valueCodec.d.ts +10 -4
- package/dist/storage/valueCodec.d.ts.map +1 -1
- package/dist/storage/valueCodec.js +65 -40
- package/dist/storage/valueCodec.js.map +1 -1
- 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 +1 -1
- package/dist/tasks/TaskManager.d.ts.map +1 -1
- package/dist/tasks/TaskManager.js +52 -16
- package/dist/tasks/TaskManager.js.map +1 -1
- package/dist/tasks/types.d.ts +8 -2
- package/dist/tasks/types.d.ts.map +1 -1
- package/dist/threads/FileThreadStore.d.ts +3 -3
- package/dist/threads/FileThreadStore.d.ts.map +1 -1
- package/dist/threads/FileThreadStore.js +18 -14
- package/dist/threads/FileThreadStore.js.map +1 -1
- package/dist/threads/index.d.ts +2 -0
- package/dist/threads/index.d.ts.map +1 -1
- package/dist/threads/index.js +2 -0
- package/dist/threads/index.js.map +1 -1
- 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 +29 -9
- package/dist/threads/types.d.ts.map +1 -1
- package/dist/threads/types.js +1 -1
- package/dist/tools/BashTool.d.ts.map +1 -1
- package/dist/tools/BashTool.js +37 -21
- package/dist/tools/BashTool.js.map +1 -1
- package/dist/tools/EditFileTool.d.ts.map +1 -1
- package/dist/tools/EditFileTool.js +62 -57
- package/dist/tools/EditFileTool.js.map +1 -1
- package/dist/tools/GlobTool.d.ts +4 -4
- package/dist/tools/GlobTool.d.ts.map +1 -1
- package/dist/tools/GlobTool.js +6 -6
- package/dist/tools/GlobTool.js.map +1 -1
- package/dist/tools/GrepTool.d.ts +8 -5
- package/dist/tools/GrepTool.d.ts.map +1 -1
- package/dist/tools/GrepTool.js +45 -19
- package/dist/tools/GrepTool.js.map +1 -1
- package/dist/tools/ReadFileTool.d.ts.map +1 -1
- package/dist/tools/ReadFileTool.js.map +1 -1
- package/dist/tools/TaskManagerTool.d.ts +1 -1
- package/dist/tools/TaskManagerTool.d.ts.map +1 -1
- package/dist/tools/TaskManagerTool.js +5 -3
- package/dist/tools/TaskManagerTool.js.map +1 -1
- package/dist/tools/ToolExecutionContext.d.ts +3 -3
- package/dist/tools/WriteFileTool.d.ts +1 -1
- package/dist/tools/WriteFileTool.d.ts.map +1 -1
- package/dist/tools/WriteFileTool.js +49 -44
- package/dist/tools/WriteFileTool.js.map +1 -1
- package/dist/tools/internal/pathGuard.d.ts +2 -2
- package/dist/tools/internal/pathGuard.d.ts.map +1 -1
- package/dist/tools/internal/pathGuard.js +3 -3
- package/dist/tools/internal/pathGuard.js.map +1 -1
- package/dist/tools/prompts.d.ts.map +1 -1
- package/dist/tools/prompts.js +7 -7
- package/dist/tools/prompts.js.map +1 -1
- package/package.json +6 -5
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"jsonl.js","sources":["../../src/storage/jsonl.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,WAAW,EAAqB,MAAM,iBAAiB,CAAC;AAY9E;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAiC,CAAC,OAAO,KAAK,CAAC;QAChD,OAAO,IAAI,KAAK;QAChB,OAAQ,KAAiC,CAAC,KAAK,KAAK,QAAQ;QAC3D,KAAiC,CAAC,KAAK,KAAK,IAAI;QACjD,MAAM,
|
|
1
|
+
{"version":3,"file":"jsonl.js","sources":["../../src/storage/jsonl.ts"],"names":[],"mappings":"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"}
|
package/dist/storage/lock.d.ts
CHANGED
|
@@ -27,12 +27,35 @@ export interface FileLockOptions {
|
|
|
27
27
|
* Defaults to 25ms.
|
|
28
28
|
*/
|
|
29
29
|
readonly retryIntervalMs?: number;
|
|
30
|
+
/**
|
|
31
|
+
* Maximum age of a lock in milliseconds before it is considered stale, even if process
|
|
32
|
+
* liveness cannot be disproven.
|
|
33
|
+
*
|
|
34
|
+
* Note on distributed/network filesystems:
|
|
35
|
+
* Process liveness checks (`process.kill(pid, 0)`) are strictly local to the current host kernel.
|
|
36
|
+
* Clustered or shared network file systems (NFS, SMB, CIFS) span multiple hosts that do not share
|
|
37
|
+
* process identifiers; in multi-host topologies, configure `staleMs` to recover abandoned locks.
|
|
38
|
+
*/
|
|
39
|
+
readonly staleMs?: number;
|
|
30
40
|
}
|
|
41
|
+
/**
|
|
42
|
+
* Checks whether a process with the given PID is running on the local host.
|
|
43
|
+
*
|
|
44
|
+
* Uses `process.kill(pid, 0)` which performs permission and existence checks without
|
|
45
|
+
* sending an actual signal.
|
|
46
|
+
*
|
|
47
|
+
* @param pid - Local operating system process identifier to probe.
|
|
48
|
+
* @returns `true` if the process exists and is active; `false` if `ESRCH` (process not found).
|
|
49
|
+
*/
|
|
50
|
+
export declare function isProcessAlive(pid: number): boolean;
|
|
31
51
|
/**
|
|
32
52
|
* Executes an operation while holding an exclusive file lock.
|
|
33
53
|
*
|
|
34
54
|
* Contention (`EEXIST`) is retried until `timeoutMs` expires. All non-contention
|
|
35
55
|
* errors (such as `EACCES`, `ENOSPC`, or `EIO`) fail immediately without retry.
|
|
56
|
+
* If an existing lock is held by a terminated local process or its age exceeds `staleMs`,
|
|
57
|
+
* it is safely reclaimed via an atomic staging and compare-and-swap sequence without
|
|
58
|
+
* displacing live owners.
|
|
36
59
|
* Ownership is verified on release using a cryptographic token. If both the inner
|
|
37
60
|
* operation and lock release encounter errors, they are preserved via `AggregateError`.
|
|
38
61
|
*
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"lock.d.ts","sources":["../../src/storage/lock.ts"],"names":[],"mappings":"AAAA;;;GAGG;
|
|
1
|
+
{"version":3,"file":"lock.d.ts","sources":["../../src/storage/lock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAgBH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAenD;AA8ED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,gBAAgB,CAAC,EAAE,MAAM,GAAG,eAAe,GAC1C,OAAO,CAAC,CAAC,CAAC,CAoLZ"}
|
package/dist/storage/lock.js
CHANGED
|
@@ -4,14 +4,102 @@
|
|
|
4
4
|
*/
|
|
5
5
|
import { randomUUID } from "node:crypto";
|
|
6
6
|
import { existsSync } from "node:fs";
|
|
7
|
-
import { mkdir, open, readFile, unlink } from "node:fs/promises";
|
|
7
|
+
import { mkdir, open, readFile, rename, stat, unlink, writeFile, } from "node:fs/promises";
|
|
8
8
|
import path from "node:path";
|
|
9
9
|
import { HernexLockError } from "../errors.js";
|
|
10
|
+
/**
|
|
11
|
+
* Checks whether a process with the given PID is running on the local host.
|
|
12
|
+
*
|
|
13
|
+
* Uses `process.kill(pid, 0)` which performs permission and existence checks without
|
|
14
|
+
* sending an actual signal.
|
|
15
|
+
*
|
|
16
|
+
* @param pid - Local operating system process identifier to probe.
|
|
17
|
+
* @returns `true` if the process exists and is active; `false` if `ESRCH` (process not found).
|
|
18
|
+
*/
|
|
19
|
+
export function isProcessAlive(pid) {
|
|
20
|
+
if (typeof pid !== "number" || pid <= 0 || !Number.isInteger(pid)) {
|
|
21
|
+
return false;
|
|
22
|
+
}
|
|
23
|
+
try {
|
|
24
|
+
process.kill(pid, 0);
|
|
25
|
+
return true;
|
|
26
|
+
}
|
|
27
|
+
catch (error) {
|
|
28
|
+
const code = error?.code;
|
|
29
|
+
if (code === "ESRCH") {
|
|
30
|
+
return false;
|
|
31
|
+
}
|
|
32
|
+
// EPERM indicates the process exists on this host but is owned by another user
|
|
33
|
+
return true;
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Inspects an existing lock file to determine if it is stale or abandoned.
|
|
38
|
+
*
|
|
39
|
+
* @param lockPath - Absolute path to the lock file.
|
|
40
|
+
* @param staleMs - Optional stale threshold in milliseconds.
|
|
41
|
+
* @returns Lock inspection result.
|
|
42
|
+
*/
|
|
43
|
+
async function inspectLock(lockPath, staleMs) {
|
|
44
|
+
let content;
|
|
45
|
+
try {
|
|
46
|
+
content = await readFile(lockPath, "utf-8");
|
|
47
|
+
}
|
|
48
|
+
catch (error) {
|
|
49
|
+
if (error?.code === "ENOENT") {
|
|
50
|
+
return { isStale: false };
|
|
51
|
+
}
|
|
52
|
+
throw error;
|
|
53
|
+
}
|
|
54
|
+
if (!content || content.trim() === "") {
|
|
55
|
+
try {
|
|
56
|
+
const stats = await stat(lockPath);
|
|
57
|
+
if (Date.now() - stats.mtimeMs > (staleMs ?? 1000)) {
|
|
58
|
+
return { isStale: true, reason: "empty_or_abandoned" };
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
catch {
|
|
62
|
+
return { isStale: false };
|
|
63
|
+
}
|
|
64
|
+
return { isStale: false };
|
|
65
|
+
}
|
|
66
|
+
let parsed;
|
|
67
|
+
try {
|
|
68
|
+
parsed = JSON.parse(content);
|
|
69
|
+
}
|
|
70
|
+
catch {
|
|
71
|
+
try {
|
|
72
|
+
const stats = await stat(lockPath);
|
|
73
|
+
if (Date.now() - stats.mtimeMs > (staleMs ?? 1000)) {
|
|
74
|
+
return { isStale: true, reason: "corrupted_payload" };
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
catch {
|
|
78
|
+
return { isStale: false };
|
|
79
|
+
}
|
|
80
|
+
return { isStale: false };
|
|
81
|
+
}
|
|
82
|
+
if (typeof parsed?.pid !== "number" ||
|
|
83
|
+
typeof parsed?.token !== "string" ||
|
|
84
|
+
typeof parsed?.createdAt !== "number") {
|
|
85
|
+
return { isStale: true, reason: "malformed_fields" };
|
|
86
|
+
}
|
|
87
|
+
if (staleMs !== undefined && Date.now() - parsed.createdAt > staleMs) {
|
|
88
|
+
return { isStale: true, payload: parsed, reason: "stale_ms_exceeded" };
|
|
89
|
+
}
|
|
90
|
+
if (!isProcessAlive(parsed.pid)) {
|
|
91
|
+
return { isStale: true, payload: parsed, reason: "process_terminated" };
|
|
92
|
+
}
|
|
93
|
+
return { isStale: false, payload: parsed };
|
|
94
|
+
}
|
|
10
95
|
/**
|
|
11
96
|
* Executes an operation while holding an exclusive file lock.
|
|
12
97
|
*
|
|
13
98
|
* Contention (`EEXIST`) is retried until `timeoutMs` expires. All non-contention
|
|
14
99
|
* errors (such as `EACCES`, `ENOSPC`, or `EIO`) fail immediately without retry.
|
|
100
|
+
* If an existing lock is held by a terminated local process or its age exceeds `staleMs`,
|
|
101
|
+
* it is safely reclaimed via an atomic staging and compare-and-swap sequence without
|
|
102
|
+
* displacing live owners.
|
|
15
103
|
* Ownership is verified on release using a cryptographic token. If both the inner
|
|
16
104
|
* operation and lock release encounter errors, they are preserved via `AggregateError`.
|
|
17
105
|
*
|
|
@@ -29,6 +117,9 @@ export async function withFileLock(lockPath, operation, optionsOrTimeout) {
|
|
|
29
117
|
const retryIntervalMs = typeof optionsOrTimeout === "object" && optionsOrTimeout !== null
|
|
30
118
|
? (optionsOrTimeout.retryIntervalMs ?? 25)
|
|
31
119
|
: 25;
|
|
120
|
+
const staleMs = typeof optionsOrTimeout === "object" && optionsOrTimeout !== null
|
|
121
|
+
? optionsOrTimeout.staleMs
|
|
122
|
+
: undefined;
|
|
32
123
|
const absoluteLock = path.resolve(lockPath);
|
|
33
124
|
const parentDir = path.dirname(absoluteLock);
|
|
34
125
|
if (!existsSync(parentDir)) {
|
|
@@ -65,6 +156,63 @@ export async function withFileLock(lockPath, operation, optionsOrTimeout) {
|
|
|
65
156
|
}
|
|
66
157
|
throw error;
|
|
67
158
|
}
|
|
159
|
+
// Check if existing lock is stale and can be safely reclaimed
|
|
160
|
+
const inspection = await inspectLock(absoluteLock, staleMs);
|
|
161
|
+
if (inspection.isStale) {
|
|
162
|
+
const reclaimLockPath = `${absoluteLock}.reclaim`;
|
|
163
|
+
let reclaimHandle = null;
|
|
164
|
+
try {
|
|
165
|
+
reclaimHandle = await open(reclaimLockPath, "wx");
|
|
166
|
+
}
|
|
167
|
+
catch (reclaimErr) {
|
|
168
|
+
if (reclaimErr?.code === "EEXIST") {
|
|
169
|
+
try {
|
|
170
|
+
const reclaimStats = await stat(reclaimLockPath);
|
|
171
|
+
if (Date.now() - reclaimStats.mtimeMs > 5000) {
|
|
172
|
+
await unlink(reclaimLockPath);
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
catch {
|
|
176
|
+
// Ignore stats/unlink errors on secondary contention
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
if (reclaimHandle !== null) {
|
|
181
|
+
try {
|
|
182
|
+
await reclaimHandle.close();
|
|
183
|
+
// Re-verify under arbitration lock to avoid displacing newly active owners
|
|
184
|
+
const recheck = await inspectLock(absoluteLock, staleMs);
|
|
185
|
+
if (recheck.isStale) {
|
|
186
|
+
const stagingPath = `${absoluteLock}.staging.${process.pid}.${token}.${Date.now()}`;
|
|
187
|
+
await writeFile(stagingPath, JSON.stringify(payload), "utf-8");
|
|
188
|
+
try {
|
|
189
|
+
await rename(stagingPath, absoluteLock);
|
|
190
|
+
acquired = true;
|
|
191
|
+
}
|
|
192
|
+
catch (renameErr) {
|
|
193
|
+
try {
|
|
194
|
+
await unlink(stagingPath);
|
|
195
|
+
}
|
|
196
|
+
catch {
|
|
197
|
+
// Ignore staging cleanup error
|
|
198
|
+
}
|
|
199
|
+
throw renameErr;
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
finally {
|
|
204
|
+
try {
|
|
205
|
+
await unlink(reclaimLockPath);
|
|
206
|
+
}
|
|
207
|
+
catch {
|
|
208
|
+
// Ignore reclaim lock unlink error
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
if (acquired) {
|
|
214
|
+
break;
|
|
215
|
+
}
|
|
68
216
|
if (Date.now() - startTime >= timeoutMs) {
|
|
69
217
|
throw new HernexLockError(`Failed to acquire lock at "${absoluteLock}" within ${timeoutMs}ms.`, absoluteLock);
|
|
70
218
|
}
|
package/dist/storage/lock.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"lock.js","sources":["../../src/storage/lock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,
|
|
1
|
+
{"version":3,"file":"lock.js","sources":["../../src/storage/lock.ts"],"names":[],"mappings":"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"}
|
|
@@ -41,6 +41,7 @@ export type EncodedValue = {
|
|
|
41
41
|
} | {
|
|
42
42
|
readonly type: "object";
|
|
43
43
|
readonly entries: Record<string, EncodedValue>;
|
|
44
|
+
readonly isNullPrototype?: boolean;
|
|
44
45
|
} | {
|
|
45
46
|
readonly type: "binary";
|
|
46
47
|
readonly base64: string;
|
|
@@ -49,18 +50,23 @@ export type EncodedValue = {
|
|
|
49
50
|
* Encodes an arbitrary JavaScript value into a lossless tagged JSON-safe representation.
|
|
50
51
|
*
|
|
51
52
|
* Supports primitives, special numbers (NaN, Infinity, -Infinity, -0), Buffer, Uint8Array,
|
|
52
|
-
* URL, arrays, and plain objects
|
|
53
|
-
*
|
|
53
|
+
* URL, arrays, and plain objects (including null-prototype dictionaries). Allows shared
|
|
54
|
+
* acyclic references (diamond structures) while rejecting true circular references fail-closed.
|
|
55
|
+
* Rejects functions, symbols, bigint, and unsupported prototypes fail-closed with a TypeError.
|
|
56
|
+
* Safely preserves special object keys (such as `__proto__`) without altering object prototypes.
|
|
54
57
|
*
|
|
55
58
|
* @param value - Any JavaScript value.
|
|
56
|
-
* @param
|
|
59
|
+
* @param ancestors - Internal Set of active call-stack ancestor objects to detect circular reference cycles.
|
|
57
60
|
* @returns Lossless tagged EncodedValue.
|
|
58
61
|
* @throws {TypeError} When value contains functions, symbols, bigint, circular references, or unsupported prototypes.
|
|
59
62
|
*/
|
|
60
|
-
export declare function encodeValue(value: unknown,
|
|
63
|
+
export declare function encodeValue(value: unknown, ancestors?: Set<object>): EncodedValue;
|
|
61
64
|
/**
|
|
62
65
|
* Decodes a tagged EncodedValue back to its original JavaScript form.
|
|
63
66
|
*
|
|
67
|
+
* Preserves null prototypes when indicated by `isNullPrototype`, and defines properties
|
|
68
|
+
* using safe own-property definition semantics to prevent prototype tampering.
|
|
69
|
+
*
|
|
64
70
|
* @param encoded - The EncodedValue.
|
|
65
71
|
* @returns Restored original JavaScript value.
|
|
66
72
|
*/
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"valueCodec.d.ts","sources":["../../src/storage/valueCodec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE,GACrC;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,GACnE;
|
|
1
|
+
{"version":3,"file":"valueCodec.d.ts","sources":["../../src/storage/valueCodec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;CAAE,GACrC;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;CAAE,GACnE;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC/C,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EACd,SAAS,GAAE,GAAG,CAAC,MAAM,CAAa,GACjC,YAAY,CA8Gd;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CA8C1D"}
|
|
@@ -6,15 +6,17 @@
|
|
|
6
6
|
* Encodes an arbitrary JavaScript value into a lossless tagged JSON-safe representation.
|
|
7
7
|
*
|
|
8
8
|
* Supports primitives, special numbers (NaN, Infinity, -Infinity, -0), Buffer, Uint8Array,
|
|
9
|
-
* URL, arrays, and plain objects
|
|
10
|
-
*
|
|
9
|
+
* URL, arrays, and plain objects (including null-prototype dictionaries). Allows shared
|
|
10
|
+
* acyclic references (diamond structures) while rejecting true circular references fail-closed.
|
|
11
|
+
* Rejects functions, symbols, bigint, and unsupported prototypes fail-closed with a TypeError.
|
|
12
|
+
* Safely preserves special object keys (such as `__proto__`) without altering object prototypes.
|
|
11
13
|
*
|
|
12
14
|
* @param value - Any JavaScript value.
|
|
13
|
-
* @param
|
|
15
|
+
* @param ancestors - Internal Set of active call-stack ancestor objects to detect circular reference cycles.
|
|
14
16
|
* @returns Lossless tagged EncodedValue.
|
|
15
17
|
* @throws {TypeError} When value contains functions, symbols, bigint, circular references, or unsupported prototypes.
|
|
16
18
|
*/
|
|
17
|
-
export function encodeValue(value,
|
|
19
|
+
export function encodeValue(value, ancestors = new Set()) {
|
|
18
20
|
if (value === null) {
|
|
19
21
|
return { type: "null" };
|
|
20
22
|
}
|
|
@@ -52,50 +54,66 @@ export function encodeValue(value, seen = new WeakSet()) {
|
|
|
52
54
|
throw new TypeError("Cannot encode value: functions are not serializable.");
|
|
53
55
|
}
|
|
54
56
|
if (typeof value === "object") {
|
|
55
|
-
if (
|
|
57
|
+
if (ancestors.has(value)) {
|
|
56
58
|
throw new TypeError("Cannot encode value: circular reference detected.");
|
|
57
59
|
}
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
60
|
+
ancestors.add(value);
|
|
61
|
+
try {
|
|
62
|
+
if (Buffer.isBuffer(value)) {
|
|
63
|
+
return {
|
|
64
|
+
type: "buffer",
|
|
65
|
+
base64: value.toString("base64"),
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
if (value instanceof Uint8Array) {
|
|
69
|
+
const buffer = Buffer.from(value.buffer, value.byteOffset, value.byteLength);
|
|
70
|
+
return {
|
|
71
|
+
type: "uint8array",
|
|
72
|
+
base64: buffer.toString("base64"),
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
if (value instanceof URL) {
|
|
76
|
+
return {
|
|
77
|
+
type: "url",
|
|
78
|
+
href: value.href,
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
if (Array.isArray(value)) {
|
|
82
|
+
return {
|
|
83
|
+
type: "array",
|
|
84
|
+
items: value.map((item) => encodeValue(item, ancestors)),
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
const proto = Object.getPrototypeOf(value);
|
|
88
|
+
if (proto !== Object.prototype && proto !== null) {
|
|
89
|
+
throw new TypeError(`Cannot encode value: unsupported prototype "${proto?.constructor?.name ?? "unknown"}".`);
|
|
90
|
+
}
|
|
91
|
+
const isNullPrototype = proto === null;
|
|
92
|
+
const entries = Object.create(null);
|
|
93
|
+
for (const [k, v] of Object.entries(value)) {
|
|
94
|
+
Object.defineProperty(entries, k, {
|
|
95
|
+
value: encodeValue(v, ancestors),
|
|
96
|
+
enumerable: true,
|
|
97
|
+
writable: true,
|
|
98
|
+
configurable: true,
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
return isNullPrototype
|
|
102
|
+
? { type: "object", entries, isNullPrototype: true }
|
|
103
|
+
: { type: "object", entries };
|
|
87
104
|
}
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
entries[k] = encodeValue(v, seen);
|
|
105
|
+
finally {
|
|
106
|
+
ancestors.delete(value);
|
|
91
107
|
}
|
|
92
|
-
return { type: "object", entries };
|
|
93
108
|
}
|
|
94
109
|
throw new TypeError(`Cannot encode value: unsupported type "${typeof value}".`);
|
|
95
110
|
}
|
|
96
111
|
/**
|
|
97
112
|
* Decodes a tagged EncodedValue back to its original JavaScript form.
|
|
98
113
|
*
|
|
114
|
+
* Preserves null prototypes when indicated by `isNullPrototype`, and defines properties
|
|
115
|
+
* using safe own-property definition semantics to prevent prototype tampering.
|
|
116
|
+
*
|
|
99
117
|
* @param encoded - The EncodedValue.
|
|
100
118
|
* @returns Restored original JavaScript value.
|
|
101
119
|
*/
|
|
@@ -129,9 +147,16 @@ export function decodeValue(encoded) {
|
|
|
129
147
|
case "array":
|
|
130
148
|
return encoded.items.map(decodeValue);
|
|
131
149
|
case "object": {
|
|
132
|
-
const result =
|
|
150
|
+
const result = encoded.isNullPrototype
|
|
151
|
+
? Object.create(null)
|
|
152
|
+
: {};
|
|
133
153
|
for (const [k, v] of Object.entries(encoded.entries)) {
|
|
134
|
-
result
|
|
154
|
+
Object.defineProperty(result, k, {
|
|
155
|
+
value: decodeValue(v),
|
|
156
|
+
enumerable: true,
|
|
157
|
+
writable: true,
|
|
158
|
+
configurable: true,
|
|
159
|
+
});
|
|
135
160
|
}
|
|
136
161
|
return result;
|
|
137
162
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"valueCodec.js","sources":["../../src/storage/valueCodec.ts"],"names":[],"mappings":"AAAA;;;GAGG;
|
|
1
|
+
{"version":3,"file":"valueCodec.js","sources":["../../src/storage/valueCodec.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Deterministic multi-file workspace mutation locking.
|
|
3
|
+
* @packageDocumentation
|
|
4
|
+
*/
|
|
5
|
+
import { type ResolveHomeDirectoryOptions } from "./homeDirectory.js";
|
|
6
|
+
import { type FileLockOptions } from "./lock.js";
|
|
7
|
+
/**
|
|
8
|
+
* Derives the exclusive lock file path for a specific target file within a workspace.
|
|
9
|
+
*
|
|
10
|
+
* Placed in `<homeDirectory>/locks/workspaces/<workspaceHash>/<targetHash>.lock` outside
|
|
11
|
+
* the workspace tree so locking never interferes with workspace file content or git status.
|
|
12
|
+
*
|
|
13
|
+
* @param workingDirectory - Absolute workspace root path.
|
|
14
|
+
* @param relativeFilePath - Normalized relative path within the workspace.
|
|
15
|
+
* @param homeDirectory - Optional explicit storage home directory override.
|
|
16
|
+
* @returns Absolute path to the lock file.
|
|
17
|
+
*/
|
|
18
|
+
export declare function getWorkspaceLockPath(workingDirectory: string, relativeFilePath: string, homeDirectory?: string): string;
|
|
19
|
+
/**
|
|
20
|
+
* Executes an operation under exclusive file locks for one or more workspace target files.
|
|
21
|
+
*
|
|
22
|
+
* Invariants enforced:
|
|
23
|
+
* - Target paths are normalized, made relative to `workingDirectory`, and deduplicated.
|
|
24
|
+
* - Multi-file locks are acquired in strictly deterministic lexicographical order.
|
|
25
|
+
* This mathematically prevents lock inversion and deadlocks across concurrent mutations.
|
|
26
|
+
* - Holds locks across the entire transaction boundary (before pre-state capture/reading,
|
|
27
|
+
* through mutation, and through post-state checkpoint finalization).
|
|
28
|
+
* - All acquired locks are safely released in reverse order upon completion or failure.
|
|
29
|
+
*
|
|
30
|
+
* @typeParam T - The return type of the executed operation.
|
|
31
|
+
* @param workingDirectory - Absolute workspace root path.
|
|
32
|
+
* @param targetPaths - One or more target file paths relative to or within the workspace.
|
|
33
|
+
* @param operation - The asynchronous transaction callback to execute.
|
|
34
|
+
* @param options - Optional file lock and home directory configuration.
|
|
35
|
+
* @returns The resolved result of the executed operation.
|
|
36
|
+
*/
|
|
37
|
+
export declare function withWorkspaceFileLock<T>(workingDirectory: string, targetPaths: string | readonly string[], operation: () => Promise<T>, options?: FileLockOptions & ResolveHomeDirectoryOptions): Promise<T>;
|
|
38
|
+
//# sourceMappingURL=workspaceLock.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"workspaceLock.d.ts","sources":["../../src/storage/workspaceLock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,WAAW,CAAC;AAY/D;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,gBAAgB,EAAE,MAAM,EACxB,gBAAgB,EAAE,MAAM,EACxB,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CAcR;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EACvC,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,CAAC,EAAE,eAAe,GAAG,2BAA2B,GACtD,OAAO,CAAC,CAAC,CAAC,CAoCZ"}
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @fileoverview Deterministic multi-file workspace mutation locking.
|
|
3
|
+
* @packageDocumentation
|
|
4
|
+
*/
|
|
5
|
+
import { createHash } from "node:crypto";
|
|
6
|
+
import path from "node:path";
|
|
7
|
+
import { resolveHomeDirectory, } from "./homeDirectory.js";
|
|
8
|
+
import { withFileLock } from "./lock.js";
|
|
9
|
+
/**
|
|
10
|
+
* Computes a deterministic hexadecimal hash digest of a path string.
|
|
11
|
+
*
|
|
12
|
+
* @param input - The raw path string to hash.
|
|
13
|
+
* @returns A 24-character hexadecimal hash digest.
|
|
14
|
+
*/
|
|
15
|
+
function hashPathSegment(input) {
|
|
16
|
+
return createHash("sha256").update(input).digest("hex").slice(0, 24);
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* Derives the exclusive lock file path for a specific target file within a workspace.
|
|
20
|
+
*
|
|
21
|
+
* Placed in `<homeDirectory>/locks/workspaces/<workspaceHash>/<targetHash>.lock` outside
|
|
22
|
+
* the workspace tree so locking never interferes with workspace file content or git status.
|
|
23
|
+
*
|
|
24
|
+
* @param workingDirectory - Absolute workspace root path.
|
|
25
|
+
* @param relativeFilePath - Normalized relative path within the workspace.
|
|
26
|
+
* @param homeDirectory - Optional explicit storage home directory override.
|
|
27
|
+
* @returns Absolute path to the lock file.
|
|
28
|
+
*/
|
|
29
|
+
export function getWorkspaceLockPath(workingDirectory, relativeFilePath, homeDirectory) {
|
|
30
|
+
const canonicalWorkspace = path.resolve(workingDirectory);
|
|
31
|
+
const normalizedRelative = path.normalize(relativeFilePath);
|
|
32
|
+
const workspaceHash = hashPathSegment(canonicalWorkspace);
|
|
33
|
+
const fileHash = hashPathSegment(normalizedRelative);
|
|
34
|
+
const storageHome = resolveHomeDirectory({ homeDirectory });
|
|
35
|
+
return path.join(storageHome, "locks", "workspaces", workspaceHash, `${fileHash}.lock`);
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Executes an operation under exclusive file locks for one or more workspace target files.
|
|
39
|
+
*
|
|
40
|
+
* Invariants enforced:
|
|
41
|
+
* - Target paths are normalized, made relative to `workingDirectory`, and deduplicated.
|
|
42
|
+
* - Multi-file locks are acquired in strictly deterministic lexicographical order.
|
|
43
|
+
* This mathematically prevents lock inversion and deadlocks across concurrent mutations.
|
|
44
|
+
* - Holds locks across the entire transaction boundary (before pre-state capture/reading,
|
|
45
|
+
* through mutation, and through post-state checkpoint finalization).
|
|
46
|
+
* - All acquired locks are safely released in reverse order upon completion or failure.
|
|
47
|
+
*
|
|
48
|
+
* @typeParam T - The return type of the executed operation.
|
|
49
|
+
* @param workingDirectory - Absolute workspace root path.
|
|
50
|
+
* @param targetPaths - One or more target file paths relative to or within the workspace.
|
|
51
|
+
* @param operation - The asynchronous transaction callback to execute.
|
|
52
|
+
* @param options - Optional file lock and home directory configuration.
|
|
53
|
+
* @returns The resolved result of the executed operation.
|
|
54
|
+
*/
|
|
55
|
+
export async function withWorkspaceFileLock(workingDirectory, targetPaths, operation, options) {
|
|
56
|
+
const rawList = Array.isArray(targetPaths) ? targetPaths : [targetPaths];
|
|
57
|
+
if (rawList.length === 0) {
|
|
58
|
+
return await operation();
|
|
59
|
+
}
|
|
60
|
+
const canonicalWorkspace = path.resolve(workingDirectory);
|
|
61
|
+
const normalizedPaths = Array.from(new Set(rawList.map((p) => {
|
|
62
|
+
const resolved = path.isAbsolute(p)
|
|
63
|
+
? path.resolve(p)
|
|
64
|
+
: path.resolve(canonicalWorkspace, p);
|
|
65
|
+
return path.relative(canonicalWorkspace, resolved);
|
|
66
|
+
}))).sort();
|
|
67
|
+
const acquireRecursive = async (index) => {
|
|
68
|
+
if (index >= normalizedPaths.length) {
|
|
69
|
+
return await operation();
|
|
70
|
+
}
|
|
71
|
+
const relPath = normalizedPaths[index];
|
|
72
|
+
const lockPath = getWorkspaceLockPath(canonicalWorkspace, relPath, options?.homeDirectory);
|
|
73
|
+
return await withFileLock(lockPath, () => acquireRecursive(index + 1), options);
|
|
74
|
+
};
|
|
75
|
+
return await acquireRecursive(0);
|
|
76
|
+
}
|
|
77
|
+
//# sourceMappingURL=workspaceLock.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"workspaceLock.js","sources":["../../src/storage/workspaceLock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EACL,oBAAoB,GAErB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAwB,MAAM,WAAW,CAAC;AAE/D;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,gBAAwB,EACxB,gBAAwB,EACxB,aAAsB;IAEtB,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1D,MAAM,kBAAkB,GAAG,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IAC5D,MAAM,aAAa,GAAG,eAAe,CAAC,kBAAkB,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,eAAe,CAAC,kBAAkB,CAAC,CAAC;IAErD,MAAM,WAAW,GAAG,oBAAoB,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC,IAAI,CACd,WAAW,EACX,OAAO,EACP,YAAY,EACZ,aAAa,EACb,GAAG,QAAQ,OAAO,CACnB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,gBAAwB,EACxB,WAAuC,EACvC,SAA2B,EAC3B,OAAuD;IAEvD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACzE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,MAAM,SAAS,EAAE,CAAC;IAC3B,CAAC;IAED,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC1D,MAAM,eAAe,GAAG,KAAK,CAAC,IAAI,CAChC,IAAI,GAAG,CACL,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAChB,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;YACjC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;YACjB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC,QAAQ,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;IACrD,CAAC,CAAC,CACH,CACF,CAAC,IAAI,EAAE,CAAC;IAET,MAAM,gBAAgB,GAAG,KAAK,EAAE,KAAa,EAAc,EAAE;QAC3D,IAAI,KAAK,IAAI,eAAe,CAAC,MAAM,EAAE,CAAC;YACpC,OAAO,MAAM,SAAS,EAAE,CAAC;QAC3B,CAAC;QACD,MAAM,OAAO,GAAG,eAAe,CAAC,KAAK,CAAE,CAAC;QACxC,MAAM,QAAQ,GAAG,oBAAoB,CACnC,kBAAkB,EAClB,OAAO,EACP,OAAO,EAAE,aAAa,CACvB,CAAC;QACF,OAAO,MAAM,YAAY,CACvB,QAAQ,EACR,GAAG,EAAE,CAAC,gBAAgB,CAAC,KAAK,GAAG,CAAC,CAAC,EACjC,OAAO,CACR,CAAC;IACJ,CAAC,CAAC;IAEF,OAAO,MAAM,gBAAgB,CAAC,CAAC,CAAC,CAAC;AACnC,CAAC"}
|
|
@@ -58,7 +58,7 @@ export declare class TaskManager {
|
|
|
58
58
|
private getTaskDirectory;
|
|
59
59
|
/**
|
|
60
60
|
* Spawns and registers a new shell process as a managed task.
|
|
61
|
-
* This is the sole execution owner for subprocess spawning across
|
|
61
|
+
* This is the sole execution owner for subprocess spawning across Hernex.
|
|
62
62
|
*
|
|
63
63
|
* @param input - Process parameters including command string, cwd, timeout, and environment allowlist.
|
|
64
64
|
* @param options - Optional observers such as streaming onOutput callback.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"TaskManager.d.ts","sources":["../../src/tasks/TaskManager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoBH,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EAEjB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,gEAAgE;AAChE,eAAO,MAAM,qBAAqB,QAAiB,CAAC;AAEpD,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,UAAY,CAAC;AAE/C,2FAA2F;AAC3F,eAAO,MAAM,yBAAyB,OAAO,CAAC;
|
|
1
|
+
{"version":3,"file":"TaskManager.d.ts","sources":["../../src/tasks/TaskManager.ts"],"names":[],"mappings":"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"}
|