@buildanagent/harness 0.0.0-stage → 0.1.0-alpha.28
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 +54 -0
- package/LICENSE-APACHE +202 -0
- package/LICENSE-MIT +21 -0
- package/README.md +716 -2
- package/dist/ablation.d.ts +2 -0
- package/dist/ablation.js +3 -0
- package/dist/ablation.js.map +1 -0
- package/dist/completion/check.d.ts +64 -0
- package/dist/completion/check.js +152 -0
- package/dist/completion/check.js.map +1 -0
- package/dist/completion/checks.d.ts +45 -0
- package/dist/completion/checks.js +173 -0
- package/dist/completion/checks.js.map +1 -0
- package/dist/completion/flags.d.ts +25 -0
- package/dist/completion/flags.js +87 -0
- package/dist/completion/flags.js.map +1 -0
- package/dist/completion/index.d.ts +8 -0
- package/dist/completion/index.js +9 -0
- package/dist/completion/index.js.map +1 -0
- package/dist/completion/snapshot.d.ts +33 -0
- package/dist/completion/snapshot.js +83 -0
- package/dist/completion/snapshot.js.map +1 -0
- package/dist/context/cap.d.ts +32 -0
- package/dist/context/cap.js +50 -0
- package/dist/context/cap.js.map +1 -0
- package/dist/context/estimate.d.ts +18 -0
- package/dist/context/estimate.js +20 -0
- package/dist/context/estimate.js.map +1 -0
- package/dist/context/file-spill.d.ts +5 -0
- package/dist/context/file-spill.js +25 -0
- package/dist/context/file-spill.js.map +1 -0
- package/dist/context/index.d.ts +10 -0
- package/dist/context/index.js +10 -0
- package/dist/context/index.js.map +1 -0
- package/dist/context/mask.d.ts +27 -0
- package/dist/context/mask.js +71 -0
- package/dist/context/mask.js.map +1 -0
- package/dist/context/mid-turn.d.ts +40 -0
- package/dist/context/mid-turn.js +82 -0
- package/dist/context/mid-turn.js.map +1 -0
- package/dist/context/policy.d.ts +9 -0
- package/dist/context/policy.js +140 -0
- package/dist/context/policy.js.map +1 -0
- package/dist/context/spill-ledger.d.ts +25 -0
- package/dist/context/spill-ledger.js +54 -0
- package/dist/context/spill-ledger.js.map +1 -0
- package/dist/context/spill.d.ts +6 -0
- package/dist/context/spill.js +14 -0
- package/dist/context/spill.js.map +1 -0
- package/dist/context/summarize.d.ts +53 -0
- package/dist/context/summarize.js +204 -0
- package/dist/context/summarize.js.map +1 -0
- package/dist/context/summary-template.d.ts +29 -0
- package/dist/context/summary-template.js +69 -0
- package/dist/context/summary-template.js.map +1 -0
- package/dist/context/types.d.ts +150 -0
- package/dist/context/types.js +2 -0
- package/dist/context/types.js.map +1 -0
- package/dist/context/write-cap.d.ts +19 -0
- package/dist/context/write-cap.js +41 -0
- package/dist/context/write-cap.js.map +1 -0
- package/dist/create-harness.d.ts +7 -0
- package/dist/create-harness.js +21 -0
- package/dist/create-harness.js.map +1 -0
- package/dist/credentials/addresses.d.ts +14 -0
- package/dist/credentials/addresses.js +144 -0
- package/dist/credentials/addresses.js.map +1 -0
- package/dist/credentials/allowlist.d.ts +34 -0
- package/dist/credentials/allowlist.js +77 -0
- package/dist/credentials/allowlist.js.map +1 -0
- package/dist/credentials/egress-proxy.d.ts +70 -0
- package/dist/credentials/egress-proxy.js +482 -0
- package/dist/credentials/egress-proxy.js.map +1 -0
- package/dist/credentials/index.d.ts +9 -0
- package/dist/credentials/index.js +10 -0
- package/dist/credentials/index.js.map +1 -0
- package/dist/credentials/scrub.d.ts +16 -0
- package/dist/credentials/scrub.js +93 -0
- package/dist/credentials/scrub.js.map +1 -0
- package/dist/errors.d.ts +56 -0
- package/dist/errors.js +63 -0
- package/dist/errors.js.map +1 -0
- package/dist/extensions/compose.d.ts +27 -0
- package/dist/extensions/compose.js +83 -0
- package/dist/extensions/compose.js.map +1 -0
- package/dist/extensions/context-files-node.d.ts +28 -0
- package/dist/extensions/context-files-node.js +74 -0
- package/dist/extensions/context-files-node.js.map +1 -0
- package/dist/extensions/context-files.d.ts +68 -0
- package/dist/extensions/context-files.js +214 -0
- package/dist/extensions/context-files.js.map +1 -0
- package/dist/extensions/digest.d.ts +6 -0
- package/dist/extensions/digest.js +68 -0
- package/dist/extensions/digest.js.map +1 -0
- package/dist/extensions/index.d.ts +10 -0
- package/dist/extensions/index.js +10 -0
- package/dist/extensions/index.js.map +1 -0
- package/dist/extensions/load.d.ts +42 -0
- package/dist/extensions/load.js +211 -0
- package/dist/extensions/load.js.map +1 -0
- package/dist/extensions/lock.d.ts +8 -0
- package/dist/extensions/lock.js +95 -0
- package/dist/extensions/lock.js.map +1 -0
- package/dist/extensions/node.d.ts +10 -0
- package/dist/extensions/node.js +11 -0
- package/dist/extensions/node.js.map +1 -0
- package/dist/extensions/project-dirs.d.ts +24 -0
- package/dist/extensions/project-dirs.js +97 -0
- package/dist/extensions/project-dirs.js.map +1 -0
- package/dist/extensions/skills-node.d.ts +34 -0
- package/dist/extensions/skills-node.js +123 -0
- package/dist/extensions/skills-node.js.map +1 -0
- package/dist/extensions/skills.d.ts +51 -0
- package/dist/extensions/skills.js +175 -0
- package/dist/extensions/skills.js.map +1 -0
- package/dist/extensions/trust-file.d.ts +3 -0
- package/dist/extensions/trust-file.js +62 -0
- package/dist/extensions/trust-file.js.map +1 -0
- package/dist/extensions/trust-store-node.d.ts +10 -0
- package/dist/extensions/trust-store-node.js +33 -0
- package/dist/extensions/trust-store-node.js.map +1 -0
- package/dist/extensions/types.d.ts +42 -0
- package/dist/extensions/types.js +2 -0
- package/dist/extensions/types.js.map +1 -0
- package/dist/harness.d.ts +156 -0
- package/dist/harness.js +2 -0
- package/dist/harness.js.map +1 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -0
- package/dist/mcp/connection.d.ts +22 -0
- package/dist/mcp/connection.js +267 -0
- package/dist/mcp/connection.js.map +1 -0
- package/dist/mcp/content.d.ts +27 -0
- package/dist/mcp/content.js +177 -0
- package/dist/mcp/content.js.map +1 -0
- package/dist/mcp/errors.d.ts +19 -0
- package/dist/mcp/errors.js +21 -0
- package/dist/mcp/errors.js.map +1 -0
- package/dist/mcp/index.d.ts +10 -0
- package/dist/mcp/index.js +10 -0
- package/dist/mcp/index.js.map +1 -0
- package/dist/mcp/manager.d.ts +7 -0
- package/dist/mcp/manager.js +173 -0
- package/dist/mcp/manager.js.map +1 -0
- package/dist/mcp/record.d.ts +7 -0
- package/dist/mcp/record.js +20 -0
- package/dist/mcp/record.js.map +1 -0
- package/dist/mcp/stdio.d.ts +39 -0
- package/dist/mcp/stdio.js +382 -0
- package/dist/mcp/stdio.js.map +1 -0
- package/dist/mcp/types.d.ts +172 -0
- package/dist/mcp/types.js +2 -0
- package/dist/mcp/types.js.map +1 -0
- package/dist/memory/index.d.ts +2 -0
- package/dist/memory/index.js +3 -0
- package/dist/memory/index.js.map +1 -0
- package/dist/permissions/default-rules.d.ts +7 -0
- package/dist/permissions/default-rules.js +42 -0
- package/dist/permissions/default-rules.js.map +1 -0
- package/dist/permissions/errors.d.ts +11 -0
- package/dist/permissions/errors.js +14 -0
- package/dist/permissions/errors.js.map +1 -0
- package/dist/permissions/index.d.ts +9 -0
- package/dist/permissions/index.js +9 -0
- package/dist/permissions/index.js.map +1 -0
- package/dist/permissions/match.d.ts +33 -0
- package/dist/permissions/match.js +287 -0
- package/dist/permissions/match.js.map +1 -0
- package/dist/permissions/pipeline.d.ts +9 -0
- package/dist/permissions/pipeline.js +235 -0
- package/dist/permissions/pipeline.js.map +1 -0
- package/dist/permissions/rules.d.ts +22 -0
- package/dist/permissions/rules.js +74 -0
- package/dist/permissions/rules.js.map +1 -0
- package/dist/permissions/shadow.d.ts +5 -0
- package/dist/permissions/shadow.js +22 -0
- package/dist/permissions/shadow.js.map +1 -0
- package/dist/permissions/types.d.ts +104 -0
- package/dist/permissions/types.js +2 -0
- package/dist/permissions/types.js.map +1 -0
- package/dist/sandbox/base.d.ts +35 -0
- package/dist/sandbox/base.js +60 -0
- package/dist/sandbox/base.js.map +1 -0
- package/dist/sandbox/docker/index.d.ts +35 -0
- package/dist/sandbox/docker/index.js +448 -0
- package/dist/sandbox/docker/index.js.map +1 -0
- package/dist/sandbox/errors.d.ts +16 -0
- package/dist/sandbox/errors.js +22 -0
- package/dist/sandbox/errors.js.map +1 -0
- package/dist/sandbox/host-files.d.ts +63 -0
- package/dist/sandbox/host-files.js +248 -0
- package/dist/sandbox/host-files.js.map +1 -0
- package/dist/sandbox/index.d.ts +8 -0
- package/dist/sandbox/index.js +8 -0
- package/dist/sandbox/index.js.map +1 -0
- package/dist/sandbox/none.d.ts +17 -0
- package/dist/sandbox/none.js +108 -0
- package/dist/sandbox/none.js.map +1 -0
- package/dist/sandbox/process.d.ts +61 -0
- package/dist/sandbox/process.js +253 -0
- package/dist/sandbox/process.js.map +1 -0
- package/dist/sandbox/spawn-env.d.ts +20 -0
- package/dist/sandbox/spawn-env.js +128 -0
- package/dist/sandbox/spawn-env.js.map +1 -0
- package/dist/sandbox/srt/index.d.ts +35 -0
- package/dist/sandbox/srt/index.js +264 -0
- package/dist/sandbox/srt/index.js.map +1 -0
- package/dist/sandbox/srt/settings.d.ts +48 -0
- package/dist/sandbox/srt/settings.js +31 -0
- package/dist/sandbox/srt/settings.js.map +1 -0
- package/dist/sandbox/types.d.ts +88 -0
- package/dist/sandbox/types.js +6 -0
- package/dist/sandbox/types.js.map +1 -0
- package/dist/server/answers.d.ts +16 -0
- package/dist/server/answers.js +43 -0
- package/dist/server/answers.js.map +1 -0
- package/dist/server/connection.d.ts +99 -0
- package/dist/server/connection.js +309 -0
- package/dist/server/connection.js.map +1 -0
- package/dist/server/dispatcher.d.ts +86 -0
- package/dist/server/dispatcher.js +800 -0
- package/dist/server/dispatcher.js.map +1 -0
- package/dist/server/index.d.ts +13 -0
- package/dist/server/index.js +12 -0
- package/dist/server/index.js.map +1 -0
- package/dist/server/local-transport.d.ts +44 -0
- package/dist/server/local-transport.js +103 -0
- package/dist/server/local-transport.js.map +1 -0
- package/dist/server/outbox.d.ts +31 -0
- package/dist/server/outbox.js +130 -0
- package/dist/server/outbox.js.map +1 -0
- package/dist/server/params.d.ts +25 -0
- package/dist/server/params.js +112 -0
- package/dist/server/params.js.map +1 -0
- package/dist/server/protocol.schema.json +2448 -0
- package/dist/server/rpc-session.d.ts +43 -0
- package/dist/server/rpc-session.js +167 -0
- package/dist/server/rpc-session.js.map +1 -0
- package/dist/server/stdio-streams.d.ts +67 -0
- package/dist/server/stdio-streams.js +218 -0
- package/dist/server/stdio-streams.js.map +1 -0
- package/dist/server/stdio.d.ts +59 -0
- package/dist/server/stdio.js +189 -0
- package/dist/server/stdio.js.map +1 -0
- package/dist/server/websocket.d.ts +106 -0
- package/dist/server/websocket.js +327 -0
- package/dist/server/websocket.js.map +1 -0
- package/dist/session/approvals.d.ts +81 -0
- package/dist/session/approvals.js +217 -0
- package/dist/session/approvals.js.map +1 -0
- package/dist/session/code-call-log.d.ts +42 -0
- package/dist/session/code-call-log.js +63 -0
- package/dist/session/code-call-log.js.map +1 -0
- package/dist/session/code-call-result.d.ts +19 -0
- package/dist/session/code-call-result.js +95 -0
- package/dist/session/code-call-result.js.map +1 -0
- package/dist/session/code-call.d.ts +49 -0
- package/dist/session/code-call.js +345 -0
- package/dist/session/code-call.js.map +1 -0
- package/dist/session/effect-scope.d.ts +11 -0
- package/dist/session/effect-scope.js +10 -0
- package/dist/session/effect-scope.js.map +1 -0
- package/dist/session/errors.d.ts +19 -0
- package/dist/session/errors.js +27 -0
- package/dist/session/errors.js.map +1 -0
- package/dist/session/file-index.d.ts +8 -0
- package/dist/session/file-index.js +70 -0
- package/dist/session/file-index.js.map +1 -0
- package/dist/session/file-key-store.d.ts +16 -0
- package/dist/session/file-key-store.js +169 -0
- package/dist/session/file-key-store.js.map +1 -0
- package/dist/session/file-lock.d.ts +52 -0
- package/dist/session/file-lock.js +324 -0
- package/dist/session/file-lock.js.map +1 -0
- package/dist/session/index.d.ts +22 -0
- package/dist/session/index.js +20 -0
- package/dist/session/index.js.map +1 -0
- package/dist/session/jsonl-store.d.ts +37 -0
- package/dist/session/jsonl-store.js +386 -0
- package/dist/session/jsonl-store.js.map +1 -0
- package/dist/session/jsonl.d.ts +9 -0
- package/dist/session/jsonl.js +10 -0
- package/dist/session/jsonl.js.map +1 -0
- package/dist/session/lock.d.ts +19 -0
- package/dist/session/lock.js +2 -0
- package/dist/session/lock.js.map +1 -0
- package/dist/session/memory-store.d.ts +12 -0
- package/dist/session/memory-store.js +60 -0
- package/dist/session/memory-store.js.map +1 -0
- package/dist/session/migrate.d.ts +41 -0
- package/dist/session/migrate.js +86 -0
- package/dist/session/migrate.js.map +1 -0
- package/dist/session/pointer.d.ts +15 -0
- package/dist/session/pointer.js +22 -0
- package/dist/session/pointer.js.map +1 -0
- package/dist/session/rebuild.d.ts +53 -0
- package/dist/session/rebuild.js +230 -0
- package/dist/session/rebuild.js.map +1 -0
- package/dist/session/resume.d.ts +26 -0
- package/dist/session/resume.js +128 -0
- package/dist/session/resume.js.map +1 -0
- package/dist/session/retention.d.ts +97 -0
- package/dist/session/retention.js +702 -0
- package/dist/session/retention.js.map +1 -0
- package/dist/session/runner.d.ts +156 -0
- package/dist/session/runner.js +656 -0
- package/dist/session/runner.js.map +1 -0
- package/dist/session/scheduler.d.ts +47 -0
- package/dist/session/scheduler.js +85 -0
- package/dist/session/scheduler.js.map +1 -0
- package/dist/session/secret-key-store.d.ts +47 -0
- package/dist/session/secret-key-store.js +79 -0
- package/dist/session/secret-key-store.js.map +1 -0
- package/dist/session/session.d.ts +106 -0
- package/dist/session/session.js +353 -0
- package/dist/session/session.js.map +1 -0
- package/dist/session/sticky.d.ts +48 -0
- package/dist/session/sticky.js +232 -0
- package/dist/session/sticky.js.map +1 -0
- package/dist/session/store.d.ts +108 -0
- package/dist/session/store.js +163 -0
- package/dist/session/store.js.map +1 -0
- package/dist/telemetry/index.d.ts +2 -0
- package/dist/telemetry/index.js +3 -0
- package/dist/telemetry/index.js.map +1 -0
- package/dist/testing/fake-sandbox.d.ts +34 -0
- package/dist/testing/fake-sandbox.js +221 -0
- package/dist/testing/fake-sandbox.js.map +1 -0
- package/dist/testing/index.d.ts +10 -0
- package/dist/testing/index.js +11 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/testing/key-store-conformance.d.ts +22 -0
- package/dist/testing/key-store-conformance.js +97 -0
- package/dist/testing/key-store-conformance.js.map +1 -0
- package/dist/testing/run-cases.d.ts +21 -0
- package/dist/testing/run-cases.js +20 -0
- package/dist/testing/run-cases.js.map +1 -0
- package/dist/testing/sandbox-conformance.d.ts +64 -0
- package/dist/testing/sandbox-conformance.js +361 -0
- package/dist/testing/sandbox-conformance.js.map +1 -0
- package/dist/testing/scheduler-conformance.d.ts +32 -0
- package/dist/testing/scheduler-conformance.js +72 -0
- package/dist/testing/scheduler-conformance.js.map +1 -0
- package/dist/testing/store-conformance.d.ts +21 -0
- package/dist/testing/store-conformance.js +320 -0
- package/dist/testing/store-conformance.js.map +1 -0
- package/dist/tools/errors.d.ts +13 -0
- package/dist/tools/errors.js +17 -0
- package/dist/tools/errors.js.map +1 -0
- package/dist/tools/index.d.ts +8 -0
- package/dist/tools/index.js +8 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/registry.d.ts +3 -0
- package/dist/tools/registry.js +234 -0
- package/dist/tools/registry.js.map +1 -0
- package/dist/tools/tool-search.d.ts +30 -0
- package/dist/tools/tool-search.js +118 -0
- package/dist/tools/tool-search.js.map +1 -0
- package/dist/tools/types.d.ts +106 -0
- package/dist/tools/types.js +2 -0
- package/dist/tools/types.js.map +1 -0
- package/llms.txt +435 -0
- package/package.json +118 -3
|
@@ -0,0 +1,324 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `fileLock()`: a `SessionLock` that keeps each lock in a file beside the sessions, created with the exclusive-create
|
|
3
|
+
* flag and renewed on a lease. It needs Node's file system and a local disk: an exclusive create is not reliable on a
|
|
4
|
+
* network file system, so those are unsupported.
|
|
5
|
+
*/
|
|
6
|
+
import { randomUUID } from "node:crypto";
|
|
7
|
+
import { link, mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
|
|
8
|
+
import { hostname } from "node:os";
|
|
9
|
+
import { join } from "node:path";
|
|
10
|
+
import process from "node:process";
|
|
11
|
+
import { HarnessError } from "../errors.js";
|
|
12
|
+
import { processScheduler } from "./scheduler.js";
|
|
13
|
+
import { checkKey, encodeName } from "./store.js";
|
|
14
|
+
const EXTENSION = ".lock";
|
|
15
|
+
const DEFAULT_LEASE_MS = 30_000;
|
|
16
|
+
const DEFAULT_RENEW_MS = 10_000;
|
|
17
|
+
// A takeover guard older than this was left by a process that died during a takeover, so it is cleared.
|
|
18
|
+
const GUARD_STALE_MS = 10_000;
|
|
19
|
+
function processExists(pid) {
|
|
20
|
+
try {
|
|
21
|
+
process.kill(pid, 0);
|
|
22
|
+
return true;
|
|
23
|
+
}
|
|
24
|
+
catch (error) {
|
|
25
|
+
// EPERM means the process exists and belongs to someone else.
|
|
26
|
+
return error.code === "EPERM";
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
function parseRecord(text) {
|
|
30
|
+
try {
|
|
31
|
+
const value = JSON.parse(text.trim());
|
|
32
|
+
const ok = typeof value.pid === "number" &&
|
|
33
|
+
typeof value.host === "string" &&
|
|
34
|
+
typeof value.token === "string" &&
|
|
35
|
+
typeof value.leaseUntil === "number";
|
|
36
|
+
return ok ? value : undefined;
|
|
37
|
+
}
|
|
38
|
+
catch {
|
|
39
|
+
return undefined;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
// Every lock record is padded to this many bytes, so a renewal overwrites the record in place with one write.
|
|
43
|
+
const RECORD_BYTES = 1024;
|
|
44
|
+
const MAX_TIMER_MS = 2 ** 31 - 1;
|
|
45
|
+
function encode(record) {
|
|
46
|
+
const text = JSON.stringify(record);
|
|
47
|
+
const bytes = new TextEncoder().encode(text).length;
|
|
48
|
+
if (bytes > RECORD_BYTES) {
|
|
49
|
+
throw new HarnessError("invalid_lock_options", "a lock record is over 1 KiB, so the host name is too long");
|
|
50
|
+
}
|
|
51
|
+
return text + " ".repeat(RECORD_BYTES - bytes);
|
|
52
|
+
}
|
|
53
|
+
function parseGuard(text) {
|
|
54
|
+
try {
|
|
55
|
+
const value = JSON.parse(text);
|
|
56
|
+
return typeof value.token === "string" && typeof value.createdAt === "number" ? value : undefined;
|
|
57
|
+
}
|
|
58
|
+
catch {
|
|
59
|
+
return undefined;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
async function createExclusive(path, text) {
|
|
63
|
+
const file = await open(path, "wx").catch((error) => {
|
|
64
|
+
if (error.code === "EEXIST")
|
|
65
|
+
return undefined;
|
|
66
|
+
throw error;
|
|
67
|
+
});
|
|
68
|
+
if (file === undefined)
|
|
69
|
+
return false;
|
|
70
|
+
try {
|
|
71
|
+
await file.writeFile(text);
|
|
72
|
+
await file.sync();
|
|
73
|
+
}
|
|
74
|
+
finally {
|
|
75
|
+
await file.close();
|
|
76
|
+
}
|
|
77
|
+
return true;
|
|
78
|
+
}
|
|
79
|
+
const readText = (path) => readFile(path, "utf8").catch(() => undefined);
|
|
80
|
+
class FileLock {
|
|
81
|
+
#dir;
|
|
82
|
+
#leaseMs;
|
|
83
|
+
#renewMs;
|
|
84
|
+
#now;
|
|
85
|
+
#isAlive;
|
|
86
|
+
#host;
|
|
87
|
+
#pid;
|
|
88
|
+
#scheduler;
|
|
89
|
+
constructor(options) {
|
|
90
|
+
this.#dir = options.dir;
|
|
91
|
+
this.#leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS;
|
|
92
|
+
this.#renewMs = options.renewMs ?? Math.min(DEFAULT_RENEW_MS, this.#leaseMs / 3);
|
|
93
|
+
this.#now = options.now ?? Date.now;
|
|
94
|
+
this.#isAlive = options.isAlive ?? processExists;
|
|
95
|
+
this.#host = options.host ?? hostname();
|
|
96
|
+
this.#pid = options.pid ?? process.pid;
|
|
97
|
+
this.#scheduler = options.scheduler ?? processScheduler();
|
|
98
|
+
const ok = Number.isFinite(this.#leaseMs) && this.#leaseMs > 0 && this.#renewMs > 0 && this.#renewMs < this.#leaseMs;
|
|
99
|
+
if (!ok || this.#renewMs > MAX_TIMER_MS) {
|
|
100
|
+
throw new HarnessError("invalid_lock_options", `fileLock() needs a finite leaseMs above 0 and a renewMs above 0, below the lease and at most ${MAX_TIMER_MS}`);
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
#record(token) {
|
|
104
|
+
return { pid: this.#pid, host: this.#host, token, leaseUntil: this.#now() + this.#leaseMs };
|
|
105
|
+
}
|
|
106
|
+
/** Whether a lock's holder is gone: its lease has lapsed and, on this host, its process no longer exists. */
|
|
107
|
+
#isStale(record) {
|
|
108
|
+
if (record.leaseUntil >= this.#now())
|
|
109
|
+
return false;
|
|
110
|
+
return record.host === this.#host && !this.#isAlive(record.pid);
|
|
111
|
+
}
|
|
112
|
+
/** A lock file with no readable record is one whose creator died, or is still writing it, so only its age says which. */
|
|
113
|
+
async #unreadableIsStale(path) {
|
|
114
|
+
const info = await stat(path).catch(() => undefined);
|
|
115
|
+
// A file's age is measured on the wall clock, because that is what its modification time is.
|
|
116
|
+
return info !== undefined && Date.now() - info.mtimeMs > this.#leaseMs;
|
|
117
|
+
}
|
|
118
|
+
/** Clears a takeover guard that its maker left behind, and says whether this call did. */
|
|
119
|
+
async #clearStaleGuard(guard) {
|
|
120
|
+
const text = await readText(guard);
|
|
121
|
+
if (text === undefined)
|
|
122
|
+
return true;
|
|
123
|
+
const record = parseGuard(text);
|
|
124
|
+
const info = await stat(guard).catch(() => undefined);
|
|
125
|
+
const age = record === undefined ? Date.now() - (info?.mtimeMs ?? Date.now()) : Date.now() - record.createdAt;
|
|
126
|
+
if (age <= GUARD_STALE_MS)
|
|
127
|
+
return false;
|
|
128
|
+
// Moved aside under a name no one else uses, so only one cleaner gets it, and checked before it is deleted.
|
|
129
|
+
const aside = `${guard}.${randomUUID()}.stale`;
|
|
130
|
+
if (!(await rename(guard, aside).then(() => true, () => false)))
|
|
131
|
+
return false;
|
|
132
|
+
const moved = parseGuard((await readText(aside)) ?? "");
|
|
133
|
+
if (moved?.token === record?.token) {
|
|
134
|
+
await rm(aside, { force: true });
|
|
135
|
+
return true;
|
|
136
|
+
}
|
|
137
|
+
// A fresh guard was grabbed by mistake, so it goes back, unless another has been made since, and this call gives up.
|
|
138
|
+
await link(aside, guard).catch(() => undefined);
|
|
139
|
+
await rm(aside, { force: true });
|
|
140
|
+
return false;
|
|
141
|
+
}
|
|
142
|
+
async #takeGuard(guard, mine) {
|
|
143
|
+
const text = JSON.stringify(mine);
|
|
144
|
+
if (await createExclusive(guard, text))
|
|
145
|
+
return true;
|
|
146
|
+
return (await this.#clearStaleGuard(guard)) && (await createExclusive(guard, text));
|
|
147
|
+
}
|
|
148
|
+
/** Takes over a stale lock under a short-lived guard, so two reclaimers can't each delete the other's new lock. */
|
|
149
|
+
async #reclaim(path, staleToken, record) {
|
|
150
|
+
const guard = `${path}.reclaim`;
|
|
151
|
+
const mine = { token: record.token, createdAt: Date.now() };
|
|
152
|
+
if (!(await this.#takeGuard(guard, mine)))
|
|
153
|
+
return false;
|
|
154
|
+
try {
|
|
155
|
+
const current = parseRecord((await readText(path)) ?? "");
|
|
156
|
+
// Someone renewed or replaced the lock since it was read as stale.
|
|
157
|
+
if (current?.token !== staleToken)
|
|
158
|
+
return false;
|
|
159
|
+
// A lock with no record may be one that another writer has just created and not finished writing, so it must
|
|
160
|
+
// still be old now that the guard is held.
|
|
161
|
+
if (staleToken === undefined && !(await this.#unreadableIsStale(path)))
|
|
162
|
+
return false;
|
|
163
|
+
await rm(path, { force: true });
|
|
164
|
+
if (!(await createExclusive(path, encode(record))))
|
|
165
|
+
return false;
|
|
166
|
+
// A guard that was cleared while this ran could have let a second reclaimer in, so the lock is read back.
|
|
167
|
+
return parseRecord((await readText(path)) ?? "")?.token === record.token;
|
|
168
|
+
}
|
|
169
|
+
finally {
|
|
170
|
+
const left = parseGuard((await readText(guard)) ?? "");
|
|
171
|
+
if (left?.token === record.token)
|
|
172
|
+
await rm(guard, { force: true });
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
async acquire(key) {
|
|
176
|
+
checkKey(key);
|
|
177
|
+
const path = lockPath(this.#dir, key);
|
|
178
|
+
await mkdir(join(path, ".."), { recursive: true });
|
|
179
|
+
const token = randomUUID();
|
|
180
|
+
const record = this.#record(token);
|
|
181
|
+
const text = encode(record);
|
|
182
|
+
if (!(await createExclusive(path, text)) && !(await this.#takeOver(path, record)))
|
|
183
|
+
return "would_block";
|
|
184
|
+
return new Hold(path, token, {
|
|
185
|
+
leaseMs: this.#leaseMs,
|
|
186
|
+
renewMs: this.#renewMs,
|
|
187
|
+
now: this.#now,
|
|
188
|
+
host: this.#host,
|
|
189
|
+
pid: this.#pid,
|
|
190
|
+
scheduler: this.#scheduler,
|
|
191
|
+
leaseId: leaseId(key),
|
|
192
|
+
});
|
|
193
|
+
}
|
|
194
|
+
async #takeOver(path, record) {
|
|
195
|
+
const text = await readText(path);
|
|
196
|
+
// The lock was released between the failed create and this read, so try the plain create again.
|
|
197
|
+
if (text === undefined)
|
|
198
|
+
return createExclusive(path, encode(record));
|
|
199
|
+
const existing = parseRecord(text);
|
|
200
|
+
if (existing === undefined) {
|
|
201
|
+
return (await this.#unreadableIsStale(path)) && this.#reclaim(path, undefined, record);
|
|
202
|
+
}
|
|
203
|
+
return this.#isStale(existing) && this.#reclaim(path, existing.token, record);
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
/** The scheduler id of a session's lease renewals, prefixed so it never meets a wake the host asks for the session. */
|
|
207
|
+
function leaseId(key) {
|
|
208
|
+
return `lease:${encodeName(key.userId)}/${encodeName(key.sessionId)}`;
|
|
209
|
+
}
|
|
210
|
+
class Hold {
|
|
211
|
+
token;
|
|
212
|
+
#held = true;
|
|
213
|
+
#renewing;
|
|
214
|
+
#path;
|
|
215
|
+
#options;
|
|
216
|
+
// Each hold's own id, so a hold that loses its lock never cancels the wake of a newer hold on the same session.
|
|
217
|
+
#wakeId;
|
|
218
|
+
#stopListening;
|
|
219
|
+
// The time of the renewal wake this hold is waiting for. A duplicate of a delivered wake carries an older time.
|
|
220
|
+
#armedAt = 0;
|
|
221
|
+
constructor(path, token, options) {
|
|
222
|
+
this.token = token;
|
|
223
|
+
this.#path = path;
|
|
224
|
+
this.#options = options;
|
|
225
|
+
this.#wakeId = `${options.leaseId}/${token}`;
|
|
226
|
+
this.#stopListening = options.scheduler.onWake((id, at) => {
|
|
227
|
+
if (id !== this.#wakeId || at.getTime() !== this.#armedAt || !this.#held)
|
|
228
|
+
return;
|
|
229
|
+
this.#arm();
|
|
230
|
+
void this.#tick();
|
|
231
|
+
});
|
|
232
|
+
this.#arm();
|
|
233
|
+
}
|
|
234
|
+
/** Asks the scheduler for the next renewal. The scheduler may wake twice, so a wake only counts at the time asked for. */
|
|
235
|
+
#arm() {
|
|
236
|
+
// Each ask has its own time, even when the clock has not moved, so a wake delivered twice is told from the next.
|
|
237
|
+
const { scheduler, renewMs } = this.#options;
|
|
238
|
+
const at = new Date(Math.max(scheduler.now() + renewMs, this.#armedAt + 1));
|
|
239
|
+
this.#armedAt = at.getTime();
|
|
240
|
+
// A scheduler that refuses the wake leaves no renewal coming, so the hold reports itself lost and the writer stops.
|
|
241
|
+
scheduler.wake(at, this.#wakeId).catch(() => this.#lose());
|
|
242
|
+
}
|
|
243
|
+
held() {
|
|
244
|
+
return this.#held;
|
|
245
|
+
}
|
|
246
|
+
#tick() {
|
|
247
|
+
if (!this.#held || this.#renewing !== undefined)
|
|
248
|
+
return Promise.resolve();
|
|
249
|
+
const renewal = this.#renew().finally(() => {
|
|
250
|
+
this.#renewing = undefined;
|
|
251
|
+
});
|
|
252
|
+
this.#renewing = renewal;
|
|
253
|
+
return renewal;
|
|
254
|
+
}
|
|
255
|
+
/**
|
|
256
|
+
* Renews the lease by overwriting the lock's record in place through an open handle, never by replacing the file. A
|
|
257
|
+
* lock that was removed can't come back, because the open fails, and a successor's lock is a different file, so a
|
|
258
|
+
* stale renewal can't overwrite it. Only a missing lock or another holder's token ends the hold; any other error is
|
|
259
|
+
* retried on the next tick.
|
|
260
|
+
*/
|
|
261
|
+
async #renew() {
|
|
262
|
+
const file = await open(this.#path, "r+").catch((error) => {
|
|
263
|
+
if (error.code === "ENOENT")
|
|
264
|
+
this.#lose();
|
|
265
|
+
return undefined;
|
|
266
|
+
});
|
|
267
|
+
if (file === undefined)
|
|
268
|
+
return;
|
|
269
|
+
try {
|
|
270
|
+
const current = parseRecord(await file.readFile({ encoding: "utf8" }));
|
|
271
|
+
if (current?.token !== this.token)
|
|
272
|
+
return this.#lose();
|
|
273
|
+
const { host, pid, now, leaseMs } = this.#options;
|
|
274
|
+
await file.write(encode({ pid, host, token: this.token, leaseUntil: now() + leaseMs }), 0);
|
|
275
|
+
}
|
|
276
|
+
catch {
|
|
277
|
+
// Retried on the next tick. A lease that lapses meanwhile can be taken over, which the next renewal then sees.
|
|
278
|
+
}
|
|
279
|
+
finally {
|
|
280
|
+
await file.close().catch(() => undefined);
|
|
281
|
+
}
|
|
282
|
+
}
|
|
283
|
+
#lose() {
|
|
284
|
+
this.#held = false;
|
|
285
|
+
this.#stopListening();
|
|
286
|
+
this.#options.scheduler.cancel(this.#wakeId).catch(() => undefined);
|
|
287
|
+
}
|
|
288
|
+
async release() {
|
|
289
|
+
this.#lose();
|
|
290
|
+
// A renewal in progress finishes first, so it can't touch the lock after it is gone.
|
|
291
|
+
await this.#renewing;
|
|
292
|
+
const current = parseRecord((await readText(this.#path)) ?? "");
|
|
293
|
+
if (current?.token === this.token)
|
|
294
|
+
await rm(this.#path, { force: true });
|
|
295
|
+
}
|
|
296
|
+
}
|
|
297
|
+
function lockPath(dir, key) {
|
|
298
|
+
return join(dir, encodeName(key.userId), `${encodeName(key.sessionId)}${EXTENSION}`);
|
|
299
|
+
}
|
|
300
|
+
/**
|
|
301
|
+
* Removes a session's lock whatever its state: the library behind `buildanagent session unlock --force`. A lock from
|
|
302
|
+
* another host is never reclaimed by `acquire()`, because this host can't tell whether its process lives, so this is the
|
|
303
|
+
* way to clear one. It returns what it removed, or `undefined` when there was no lock. The caller decides it is safe.
|
|
304
|
+
*/
|
|
305
|
+
export async function unlockSession(options, key) {
|
|
306
|
+
checkKey(key);
|
|
307
|
+
const path = lockPath(options.dir, key);
|
|
308
|
+
const text = await readFile(path, "utf8").catch(() => undefined);
|
|
309
|
+
if (text === undefined)
|
|
310
|
+
return undefined;
|
|
311
|
+
await rm(path, { force: true });
|
|
312
|
+
return parseRecord(text) ?? "unreadable";
|
|
313
|
+
}
|
|
314
|
+
/**
|
|
315
|
+
* A `SessionLock` over lock files in `options.dir`. `acquire()` creates `<user>/<session>.lock` with the exclusive-create
|
|
316
|
+
* flag and writes `{ pid, host, token, leaseUntil }`, and the holder renews the lease every `renewMs`. A second
|
|
317
|
+
* `acquire()` returns `"would_block"` at once. A lock is stale only when its lease has lapsed and, on the same host, its
|
|
318
|
+
* process no longer exists, so `acquire()` never takes a lock whose holder is alive or one from another host; only
|
|
319
|
+
* `unlockSession()` removes those. Readers never lock.
|
|
320
|
+
*/
|
|
321
|
+
export function fileLock(options) {
|
|
322
|
+
return new FileLock(options);
|
|
323
|
+
}
|
|
324
|
+
//# sourceMappingURL=file-lock.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"file-lock.js","sourceRoot":"","sources":["../../src/session/file-lock.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `fileLock()`: a `SessionLock` that keeps each lock in a file beside the sessions, created with the exclusive-create\n * flag and renewed on a lease. It needs Node's file system and a local disk: an exclusive create is not reliable on a\n * network file system, so those are unsupported.\n */\nimport { randomUUID } from \"node:crypto\";\nimport { link, mkdir, open, readFile, rename, rm, stat } from \"node:fs/promises\";\nimport { hostname } from \"node:os\";\nimport { join } from \"node:path\";\nimport process from \"node:process\";\nimport { HarnessError } from \"../errors.js\";\nimport type { LockHandle, SessionLock } from \"./lock.js\";\nimport { type ProcessScheduler, processScheduler } from \"./scheduler.js\";\nimport { checkKey, encodeName, type SessionKey } from \"./store.js\";\n\nconst EXTENSION = \".lock\";\nconst DEFAULT_LEASE_MS = 30_000;\nconst DEFAULT_RENEW_MS = 10_000;\n// A takeover guard older than this was left by a process that died during a takeover, so it is cleared.\nconst GUARD_STALE_MS = 10_000;\n\n/** What a lock file holds. */\nexport interface LockRecord {\n readonly pid: number;\n readonly host: string;\n readonly token: string;\n /** When the lease ends, in milliseconds since the epoch. */\n readonly leaseUntil: number;\n}\n\n/** The options of `fileLock()` and `unlockSession()`. */\nexport interface FileLockOptions {\n /** The folder that holds the lock files, one folder per user. Use the session store's folder or a sibling of it. */\n readonly dir: string;\n /** How long a lock lasts without a renewal. Default 30 seconds. */\n readonly leaseMs?: number;\n /**\n * How often the holder renews. Default 10 seconds or a third of the lease, whichever is less. It must be shorter\n * than the lease.\n */\n readonly renewMs?: number;\n /** The clock, in milliseconds. A test sets it. */\n readonly now?: () => number;\n /** Whether a process exists on this host. The default signals it with `process.kill(pid, 0)`. */\n readonly isAlive?: (pid: number) => boolean;\n /** This host's name, which a lock from another host is compared with. Default `os.hostname()`. */\n readonly host?: string;\n /** This process's id. Default `process.pid`. */\n readonly pid?: number;\n /**\n * What wakes a hold to renew its lease. Default: a scheduler of this lock's own, which uses timers. A host that shares\n * a scheduler across locks passes it here; each renewal's id starts with `lease:`, so the host's own wakes don't clash.\n */\n readonly scheduler?: ProcessScheduler;\n}\n\nfunction processExists(pid: number): boolean {\n try {\n process.kill(pid, 0);\n return true;\n } catch (error) {\n // EPERM means the process exists and belongs to someone else.\n return (error as NodeJS.ErrnoException).code === \"EPERM\";\n }\n}\n\nfunction parseRecord(text: string): LockRecord | undefined {\n try {\n const value = JSON.parse(text.trim()) as Partial<LockRecord>;\n const ok =\n typeof value.pid === \"number\" &&\n typeof value.host === \"string\" &&\n typeof value.token === \"string\" &&\n typeof value.leaseUntil === \"number\";\n return ok ? (value as LockRecord) : undefined;\n } catch {\n return undefined;\n }\n}\n\n// Every lock record is padded to this many bytes, so a renewal overwrites the record in place with one write.\nconst RECORD_BYTES = 1024;\nconst MAX_TIMER_MS = 2 ** 31 - 1;\n\nfunction encode(record: LockRecord): string {\n const text = JSON.stringify(record);\n const bytes = new TextEncoder().encode(text).length;\n if (bytes > RECORD_BYTES) {\n throw new HarnessError(\"invalid_lock_options\", \"a lock record is over 1 KiB, so the host name is too long\");\n }\n return text + \" \".repeat(RECORD_BYTES - bytes);\n}\n\n/** What a takeover guard holds: who made it, and when by the wall clock, which file ages are measured against. */\ninterface GuardRecord {\n readonly token: string;\n readonly createdAt: number;\n}\n\nfunction parseGuard(text: string): GuardRecord | undefined {\n try {\n const value = JSON.parse(text) as Partial<GuardRecord>;\n return typeof value.token === \"string\" && typeof value.createdAt === \"number\" ? (value as GuardRecord) : undefined;\n } catch {\n return undefined;\n }\n}\n\nasync function createExclusive(path: string, text: string): Promise<boolean> {\n const file = await open(path, \"wx\").catch((error: NodeJS.ErrnoException) => {\n if (error.code === \"EEXIST\") return undefined;\n throw error;\n });\n if (file === undefined) return false;\n try {\n await file.writeFile(text);\n await file.sync();\n } finally {\n await file.close();\n }\n return true;\n}\n\nconst readText = (path: string): Promise<string | undefined> => readFile(path, \"utf8\").catch(() => undefined);\n\nclass FileLock implements SessionLock {\n readonly #dir: string;\n readonly #leaseMs: number;\n readonly #renewMs: number;\n readonly #now: () => number;\n readonly #isAlive: (pid: number) => boolean;\n readonly #host: string;\n readonly #pid: number;\n readonly #scheduler: ProcessScheduler;\n\n constructor(options: FileLockOptions) {\n this.#dir = options.dir;\n this.#leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS;\n this.#renewMs = options.renewMs ?? Math.min(DEFAULT_RENEW_MS, this.#leaseMs / 3);\n this.#now = options.now ?? Date.now;\n this.#isAlive = options.isAlive ?? processExists;\n this.#host = options.host ?? hostname();\n this.#pid = options.pid ?? process.pid;\n this.#scheduler = options.scheduler ?? processScheduler();\n const ok =\n Number.isFinite(this.#leaseMs) && this.#leaseMs > 0 && this.#renewMs > 0 && this.#renewMs < this.#leaseMs;\n if (!ok || this.#renewMs > MAX_TIMER_MS) {\n throw new HarnessError(\n \"invalid_lock_options\",\n `fileLock() needs a finite leaseMs above 0 and a renewMs above 0, below the lease and at most ${MAX_TIMER_MS}`,\n );\n }\n }\n\n #record(token: string): LockRecord {\n return { pid: this.#pid, host: this.#host, token, leaseUntil: this.#now() + this.#leaseMs };\n }\n\n /** Whether a lock's holder is gone: its lease has lapsed and, on this host, its process no longer exists. */\n #isStale(record: LockRecord): boolean {\n if (record.leaseUntil >= this.#now()) return false;\n return record.host === this.#host && !this.#isAlive(record.pid);\n }\n\n /** A lock file with no readable record is one whose creator died, or is still writing it, so only its age says which. */\n async #unreadableIsStale(path: string): Promise<boolean> {\n const info = await stat(path).catch(() => undefined);\n // A file's age is measured on the wall clock, because that is what its modification time is.\n return info !== undefined && Date.now() - info.mtimeMs > this.#leaseMs;\n }\n\n /** Clears a takeover guard that its maker left behind, and says whether this call did. */\n async #clearStaleGuard(guard: string): Promise<boolean> {\n const text = await readText(guard);\n if (text === undefined) return true;\n const record = parseGuard(text);\n const info = await stat(guard).catch(() => undefined);\n const age = record === undefined ? Date.now() - (info?.mtimeMs ?? Date.now()) : Date.now() - record.createdAt;\n if (age <= GUARD_STALE_MS) return false;\n // Moved aside under a name no one else uses, so only one cleaner gets it, and checked before it is deleted.\n const aside = `${guard}.${randomUUID()}.stale`;\n if (\n !(await rename(guard, aside).then(\n () => true,\n () => false,\n ))\n )\n return false;\n const moved = parseGuard((await readText(aside)) ?? \"\");\n if (moved?.token === record?.token) {\n await rm(aside, { force: true });\n return true;\n }\n // A fresh guard was grabbed by mistake, so it goes back, unless another has been made since, and this call gives up.\n await link(aside, guard).catch(() => undefined);\n await rm(aside, { force: true });\n return false;\n }\n\n async #takeGuard(guard: string, mine: GuardRecord): Promise<boolean> {\n const text = JSON.stringify(mine);\n if (await createExclusive(guard, text)) return true;\n return (await this.#clearStaleGuard(guard)) && (await createExclusive(guard, text));\n }\n\n /** Takes over a stale lock under a short-lived guard, so two reclaimers can't each delete the other's new lock. */\n async #reclaim(path: string, staleToken: string | undefined, record: LockRecord): Promise<boolean> {\n const guard = `${path}.reclaim`;\n const mine: GuardRecord = { token: record.token, createdAt: Date.now() };\n if (!(await this.#takeGuard(guard, mine))) return false;\n try {\n const current = parseRecord((await readText(path)) ?? \"\");\n // Someone renewed or replaced the lock since it was read as stale.\n if (current?.token !== staleToken) return false;\n // A lock with no record may be one that another writer has just created and not finished writing, so it must\n // still be old now that the guard is held.\n if (staleToken === undefined && !(await this.#unreadableIsStale(path))) return false;\n await rm(path, { force: true });\n if (!(await createExclusive(path, encode(record)))) return false;\n // A guard that was cleared while this ran could have let a second reclaimer in, so the lock is read back.\n return parseRecord((await readText(path)) ?? \"\")?.token === record.token;\n } finally {\n const left = parseGuard((await readText(guard)) ?? \"\");\n if (left?.token === record.token) await rm(guard, { force: true });\n }\n }\n\n async acquire(key: SessionKey): Promise<LockHandle | \"would_block\"> {\n checkKey(key);\n const path = lockPath(this.#dir, key);\n await mkdir(join(path, \"..\"), { recursive: true });\n const token = randomUUID();\n const record = this.#record(token);\n const text = encode(record);\n if (!(await createExclusive(path, text)) && !(await this.#takeOver(path, record))) return \"would_block\";\n return new Hold(path, token, {\n leaseMs: this.#leaseMs,\n renewMs: this.#renewMs,\n now: this.#now,\n host: this.#host,\n pid: this.#pid,\n scheduler: this.#scheduler,\n leaseId: leaseId(key),\n });\n }\n\n async #takeOver(path: string, record: LockRecord): Promise<boolean> {\n const text = await readText(path);\n // The lock was released between the failed create and this read, so try the plain create again.\n if (text === undefined) return createExclusive(path, encode(record));\n const existing = parseRecord(text);\n if (existing === undefined) {\n return (await this.#unreadableIsStale(path)) && this.#reclaim(path, undefined, record);\n }\n return this.#isStale(existing) && this.#reclaim(path, existing.token, record);\n }\n}\n\ninterface HoldOptions {\n readonly leaseMs: number;\n readonly renewMs: number;\n readonly now: () => number;\n readonly host: string;\n readonly pid: number;\n readonly scheduler: ProcessScheduler;\n readonly leaseId: string;\n}\n\n/** The scheduler id of a session's lease renewals, prefixed so it never meets a wake the host asks for the session. */\nfunction leaseId(key: SessionKey): string {\n return `lease:${encodeName(key.userId)}/${encodeName(key.sessionId)}`;\n}\n\nclass Hold implements LockHandle {\n readonly token: string;\n #held = true;\n #renewing: Promise<void> | undefined;\n readonly #path: string;\n readonly #options: HoldOptions;\n // Each hold's own id, so a hold that loses its lock never cancels the wake of a newer hold on the same session.\n readonly #wakeId: string;\n readonly #stopListening: () => void;\n // The time of the renewal wake this hold is waiting for. A duplicate of a delivered wake carries an older time.\n #armedAt = 0;\n\n constructor(path: string, token: string, options: HoldOptions) {\n this.token = token;\n this.#path = path;\n this.#options = options;\n this.#wakeId = `${options.leaseId}/${token}`;\n this.#stopListening = options.scheduler.onWake((id, at) => {\n if (id !== this.#wakeId || at.getTime() !== this.#armedAt || !this.#held) return;\n this.#arm();\n void this.#tick();\n });\n this.#arm();\n }\n\n /** Asks the scheduler for the next renewal. The scheduler may wake twice, so a wake only counts at the time asked for. */\n #arm(): void {\n // Each ask has its own time, even when the clock has not moved, so a wake delivered twice is told from the next.\n const { scheduler, renewMs } = this.#options;\n const at = new Date(Math.max(scheduler.now() + renewMs, this.#armedAt + 1));\n this.#armedAt = at.getTime();\n // A scheduler that refuses the wake leaves no renewal coming, so the hold reports itself lost and the writer stops.\n scheduler.wake(at, this.#wakeId).catch(() => this.#lose());\n }\n\n held(): boolean {\n return this.#held;\n }\n\n #tick(): Promise<void> {\n if (!this.#held || this.#renewing !== undefined) return Promise.resolve();\n const renewal = this.#renew().finally(() => {\n this.#renewing = undefined;\n });\n this.#renewing = renewal;\n return renewal;\n }\n\n /**\n * Renews the lease by overwriting the lock's record in place through an open handle, never by replacing the file. A\n * lock that was removed can't come back, because the open fails, and a successor's lock is a different file, so a\n * stale renewal can't overwrite it. Only a missing lock or another holder's token ends the hold; any other error is\n * retried on the next tick.\n */\n async #renew(): Promise<void> {\n const file = await open(this.#path, \"r+\").catch((error: NodeJS.ErrnoException) => {\n if (error.code === \"ENOENT\") this.#lose();\n return undefined;\n });\n if (file === undefined) return;\n try {\n const current = parseRecord(await file.readFile({ encoding: \"utf8\" }));\n if (current?.token !== this.token) return this.#lose();\n const { host, pid, now, leaseMs } = this.#options;\n await file.write(encode({ pid, host, token: this.token, leaseUntil: now() + leaseMs }), 0);\n } catch {\n // Retried on the next tick. A lease that lapses meanwhile can be taken over, which the next renewal then sees.\n } finally {\n await file.close().catch(() => undefined);\n }\n }\n\n #lose(): void {\n this.#held = false;\n this.#stopListening();\n this.#options.scheduler.cancel(this.#wakeId).catch(() => undefined);\n }\n\n async release(): Promise<void> {\n this.#lose();\n // A renewal in progress finishes first, so it can't touch the lock after it is gone.\n await this.#renewing;\n const current = parseRecord((await readText(this.#path)) ?? \"\");\n if (current?.token === this.token) await rm(this.#path, { force: true });\n }\n}\n\nfunction lockPath(dir: string, key: SessionKey): string {\n return join(dir, encodeName(key.userId), `${encodeName(key.sessionId)}${EXTENSION}`);\n}\n\n/** What `unlockSession()` removed: the lock's record, or `\"unreadable\"` when the file held no valid record. */\nexport type RemovedLock = LockRecord | \"unreadable\";\n\n/**\n * Removes a session's lock whatever its state: the library behind `buildanagent session unlock --force`. A lock from\n * another host is never reclaimed by `acquire()`, because this host can't tell whether its process lives, so this is the\n * way to clear one. It returns what it removed, or `undefined` when there was no lock. The caller decides it is safe.\n */\nexport async function unlockSession(\n options: Pick<FileLockOptions, \"dir\">,\n key: SessionKey,\n): Promise<RemovedLock | undefined> {\n checkKey(key);\n const path = lockPath(options.dir, key);\n const text = await readFile(path, \"utf8\").catch(() => undefined);\n if (text === undefined) return undefined;\n await rm(path, { force: true });\n return parseRecord(text) ?? \"unreadable\";\n}\n\n/**\n * A `SessionLock` over lock files in `options.dir`. `acquire()` creates `<user>/<session>.lock` with the exclusive-create\n * flag and writes `{ pid, host, token, leaseUntil }`, and the holder renews the lease every `renewMs`. A second\n * `acquire()` returns `\"would_block\"` at once. A lock is stale only when its lease has lapsed and, on the same host, its\n * process no longer exists, so `acquire()` never takes a lock whose holder is alive or one from another host; only\n * `unlockSession()` removes those. Readers never lock.\n */\nexport function fileLock(options: FileLockOptions): SessionLock {\n return new FileLock(options);\n}\n"]}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@buildanagent/harness/session`: the session log. The entry union lives in `@buildanagent/protocol`, so the protocol
|
|
3
|
+
* never imports the harness, and this entry re-exports it for code that already imports the harness. It holds the
|
|
4
|
+
* store interface, `memoryStore()` and the read-only `secretKeyStore()`, and nothing that needs Node. `jsonlStore()` is in
|
|
5
|
+
* `@buildanagent/harness/session/jsonl`.
|
|
6
|
+
*/
|
|
7
|
+
export type { ApprovalPolicy, CheckoutEntry, CodeCallEntry, CompactionEntry, CompletionCheckEntry, EntryBase, EnvStampEntry, ExtensionLoadedEntry, LoadoutEntry, MessageBlockEntry, MessageEndEntry, Origin, PermissionDecisionEntry, PermissionMode, ProductRecordEntry, ProtocolErrorCode, SandboxTier, SessionEntry, SessionHeaderEntry, ShadowCallEntry, SkillLoadedEntry, SubagentLinkEntry, ToolResultEntry, TurnEndEntry, TurnStartEntry, UsageEntry, } from "@buildanagent/protocol";
|
|
8
|
+
export { FORMAT_VERSION, isProtocolError, ProtocolError, parseEntry, SESSION_ENTRY_TYPES, } from "@buildanagent/protocol";
|
|
9
|
+
export { ABORTED_EXIT_CODE, type CheckConfig, type CompletionOutcome, type CompletionSettings, type CompletionStart, DEFAULT_CHECK_TIMEOUT_MS, DENIED_EXIT_CODE, DISCOVERED_SCRIPTS, flagChanges, gitSnapshotter, HARNESS_CONFIG_PATH, isTestFile, MAX_FLAGS, MAX_SNAPSHOT_FILE_BYTES, MAX_SNAPSHOT_FILES, type ResolvedChecks, resolveChecks, runCompletionCheck, SNAPSHOT_TIMEOUT_MS, type SnapshotOptions, type Snapshotter, snapshotStart, type WorkspaceSnapshot, } from "../completion/index.js";
|
|
10
|
+
export { type Approvals, type ApprovalsOptions, createApprovals, oneResolution, type QuorumPolicy, type QuorumVerdict, quorumOf, type ResolveOptions, } from "./approvals.js";
|
|
11
|
+
export { effectScope } from "./effect-scope.js";
|
|
12
|
+
export { ConflictError, EntryTooLargeError } from "./errors.js";
|
|
13
|
+
export type { LockHandle, SessionLock } from "./lock.js";
|
|
14
|
+
export { type MemoryStoreOptions, memoryStore } from "./memory-store.js";
|
|
15
|
+
export { type MigrateOptions, type Migration, type MigrationResult, migrateSession } from "./migrate.js";
|
|
16
|
+
export { memoryIndex, type SessionIndex } from "./pointer.js";
|
|
17
|
+
export type { PendingApproval } from "./rebuild.js";
|
|
18
|
+
export { type ClientToolCall, type ClientToolRunner, rerunFrom, runTurn, type TurnOptions, type TurnResult, } from "./runner.js";
|
|
19
|
+
export { type ProcessScheduler, type ProcessSchedulerOptions, processScheduler, type Scheduler, type WakeHandler, } from "./scheduler.js";
|
|
20
|
+
export { DEFAULT_PLATFORM_HINT, type KeyChangeOptions, pruneKeys, rotateKeys, type SecretKeyStoreOptions, secretKeyStore, } from "./secret-key-store.js";
|
|
21
|
+
export { type ChildLink, DERIVED, isDerivedFile, listSessions, type OpenSessionOptions, openSession, Session, } from "./session.js";
|
|
22
|
+
export { type AppendOptions, DEFAULT_MAX_ENTRY_BYTES, type EntryInput, type LoadOptions, type SessionKey, type SessionStore, type SessionSummary, } from "./store.js";
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@buildanagent/harness/session`: the session log. The entry union lives in `@buildanagent/protocol`, so the protocol
|
|
3
|
+
* never imports the harness, and this entry re-exports it for code that already imports the harness. It holds the
|
|
4
|
+
* store interface, `memoryStore()` and the read-only `secretKeyStore()`, and nothing that needs Node. `jsonlStore()` is in
|
|
5
|
+
* `@buildanagent/harness/session/jsonl`.
|
|
6
|
+
*/
|
|
7
|
+
export { FORMAT_VERSION, isProtocolError, ProtocolError, parseEntry, SESSION_ENTRY_TYPES, } from "@buildanagent/protocol";
|
|
8
|
+
export { ABORTED_EXIT_CODE, DEFAULT_CHECK_TIMEOUT_MS, DENIED_EXIT_CODE, DISCOVERED_SCRIPTS, flagChanges, gitSnapshotter, HARNESS_CONFIG_PATH, isTestFile, MAX_FLAGS, MAX_SNAPSHOT_FILE_BYTES, MAX_SNAPSHOT_FILES, resolveChecks, runCompletionCheck, SNAPSHOT_TIMEOUT_MS, snapshotStart, } from "../completion/index.js";
|
|
9
|
+
export { createApprovals, oneResolution, quorumOf, } from "./approvals.js";
|
|
10
|
+
export { effectScope } from "./effect-scope.js";
|
|
11
|
+
export { ConflictError, EntryTooLargeError } from "./errors.js";
|
|
12
|
+
export { memoryStore } from "./memory-store.js";
|
|
13
|
+
export { migrateSession } from "./migrate.js";
|
|
14
|
+
export { memoryIndex } from "./pointer.js";
|
|
15
|
+
export { rerunFrom, runTurn, } from "./runner.js";
|
|
16
|
+
export { processScheduler, } from "./scheduler.js";
|
|
17
|
+
export { DEFAULT_PLATFORM_HINT, pruneKeys, rotateKeys, secretKeyStore, } from "./secret-key-store.js";
|
|
18
|
+
export { DERIVED, isDerivedFile, listSessions, openSession, Session, } from "./session.js";
|
|
19
|
+
export { DEFAULT_MAX_ENTRY_BYTES, } from "./store.js";
|
|
20
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA8BH,OAAO,EACL,cAAc,EACd,eAAe,EACf,aAAa,EACb,UAAU,EACV,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,iBAAiB,EAKjB,wBAAwB,EACxB,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,uBAAuB,EACvB,kBAAkB,EAElB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EAGnB,aAAa,GAEd,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAGL,eAAe,EACf,aAAa,EAGb,QAAQ,GAET,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAA2B,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAA6D,cAAc,EAAE,MAAM,cAAc,CAAC;AACzG,OAAO,EAAE,WAAW,EAAqB,MAAM,cAAc,CAAC;AAE9D,OAAO,EAGL,SAAS,EACT,OAAO,GAGR,MAAM,aAAa,CAAC;AACrB,OAAO,EAGL,gBAAgB,GAGjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,qBAAqB,EAErB,SAAS,EACT,UAAU,EAEV,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,OAAO,EACP,aAAa,EACb,YAAY,EAEZ,WAAW,EACX,OAAO,GACR,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,uBAAuB,GAMxB,MAAM,YAAY,CAAC","sourcesContent":["/**\n * `@buildanagent/harness/session`: the session log. The entry union lives in `@buildanagent/protocol`, so the protocol\n * never imports the harness, and this entry re-exports it for code that already imports the harness. It holds the\n * store interface, `memoryStore()` and the read-only `secretKeyStore()`, and nothing that needs Node. `jsonlStore()` is in\n * `@buildanagent/harness/session/jsonl`.\n */\n\nexport type {\n ApprovalPolicy,\n CheckoutEntry,\n CodeCallEntry,\n CompactionEntry,\n CompletionCheckEntry,\n EntryBase,\n EnvStampEntry,\n ExtensionLoadedEntry,\n LoadoutEntry,\n MessageBlockEntry,\n MessageEndEntry,\n Origin,\n PermissionDecisionEntry,\n PermissionMode,\n ProductRecordEntry,\n ProtocolErrorCode,\n SandboxTier,\n SessionEntry,\n SessionHeaderEntry,\n ShadowCallEntry,\n SkillLoadedEntry,\n SubagentLinkEntry,\n ToolResultEntry,\n TurnEndEntry,\n TurnStartEntry,\n UsageEntry,\n} from \"@buildanagent/protocol\";\nexport {\n FORMAT_VERSION,\n isProtocolError,\n ProtocolError,\n parseEntry,\n SESSION_ENTRY_TYPES,\n} from \"@buildanagent/protocol\";\nexport {\n ABORTED_EXIT_CODE,\n type CheckConfig,\n type CompletionOutcome,\n type CompletionSettings,\n type CompletionStart,\n DEFAULT_CHECK_TIMEOUT_MS,\n DENIED_EXIT_CODE,\n DISCOVERED_SCRIPTS,\n flagChanges,\n gitSnapshotter,\n HARNESS_CONFIG_PATH,\n isTestFile,\n MAX_FLAGS,\n MAX_SNAPSHOT_FILE_BYTES,\n MAX_SNAPSHOT_FILES,\n type ResolvedChecks,\n resolveChecks,\n runCompletionCheck,\n SNAPSHOT_TIMEOUT_MS,\n type SnapshotOptions,\n type Snapshotter,\n snapshotStart,\n type WorkspaceSnapshot,\n} from \"../completion/index.js\";\nexport {\n type Approvals,\n type ApprovalsOptions,\n createApprovals,\n oneResolution,\n type QuorumPolicy,\n type QuorumVerdict,\n quorumOf,\n type ResolveOptions,\n} from \"./approvals.js\";\nexport { effectScope } from \"./effect-scope.js\";\nexport { ConflictError, EntryTooLargeError } from \"./errors.js\";\nexport type { LockHandle, SessionLock } from \"./lock.js\";\nexport { type MemoryStoreOptions, memoryStore } from \"./memory-store.js\";\nexport { type MigrateOptions, type Migration, type MigrationResult, migrateSession } from \"./migrate.js\";\nexport { memoryIndex, type SessionIndex } from \"./pointer.js\";\nexport type { PendingApproval } from \"./rebuild.js\";\nexport {\n type ClientToolCall,\n type ClientToolRunner,\n rerunFrom,\n runTurn,\n type TurnOptions,\n type TurnResult,\n} from \"./runner.js\";\nexport {\n type ProcessScheduler,\n type ProcessSchedulerOptions,\n processScheduler,\n type Scheduler,\n type WakeHandler,\n} from \"./scheduler.js\";\nexport {\n DEFAULT_PLATFORM_HINT,\n type KeyChangeOptions,\n pruneKeys,\n rotateKeys,\n type SecretKeyStoreOptions,\n secretKeyStore,\n} from \"./secret-key-store.js\";\nexport {\n type ChildLink,\n DERIVED,\n isDerivedFile,\n listSessions,\n type OpenSessionOptions,\n openSession,\n Session,\n} from \"./session.js\";\nexport {\n type AppendOptions,\n DEFAULT_MAX_ENTRY_BYTES,\n type EntryInput,\n type LoadOptions,\n type SessionKey,\n type SessionStore,\n type SessionSummary,\n} from \"./store.js\";\n"]}
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
import type { SessionLock } from "./lock.js";
|
|
2
|
+
import { type Retention } from "./retention.js";
|
|
3
|
+
import { type SessionStore } from "./store.js";
|
|
4
|
+
/** The options of `jsonlStore()`. */
|
|
5
|
+
export interface JsonlStoreOptions {
|
|
6
|
+
/** The folder that holds the sessions. It is created on the first write. */
|
|
7
|
+
readonly dir: string;
|
|
8
|
+
/** The bound on one entry's JSON, in bytes. Default 64 KiB. */
|
|
9
|
+
readonly maxEntryBytes?: number;
|
|
10
|
+
/**
|
|
11
|
+
* How long to keep a session. Without it the store never deletes or moves a file. With it, the first time the store
|
|
12
|
+
* touches a user's sessions, it archives or purges that user's expired ones (see `pruneSessions()`), and it never does
|
|
13
|
+
* so in the background. That happens once per user for the life of the store: a long-running server calls
|
|
14
|
+
* `pruneSessions()` on a schedule of its own. A pass that had an error runs again on the first touch at least a minute
|
|
15
|
+
* after it ended. An archived session is still listed and loaded, and a write restores the file it writes to.
|
|
16
|
+
*/
|
|
17
|
+
readonly retention?: Retention;
|
|
18
|
+
/** The writer lock, so that expiry leaves a session whose writer is running. Only used with `retention`. */
|
|
19
|
+
readonly lock?: SessionLock;
|
|
20
|
+
/**
|
|
21
|
+
* Called with each error of an expiry pass: one for each session that failed to expire, or the one that stopped the
|
|
22
|
+
* pass. Expiry never stops the call that triggered it, and an error this callback throws is ignored.
|
|
23
|
+
*/
|
|
24
|
+
readonly onRetentionError?: (error: unknown) => void;
|
|
25
|
+
/** The clock expiry reads, for its cutoff and for when a failed pass may run again. Default `new Date()`. */
|
|
26
|
+
readonly now?: () => Date;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* A store that keeps each session in `<dir>/<user>/<session>.jsonl`, one JSON entry per line. Each append is one write
|
|
30
|
+
* of whole lines followed by an `fsync`, so a crash leaves at most one unterminated last line, which `load()` skips and
|
|
31
|
+
* the next append cuts off before it writes. Names are percent-encoded, so no id can reach another user's folder. A
|
|
32
|
+
* log's state is cached by file size, so one process appends without rereading the file, and another process's write
|
|
33
|
+
* is seen on the next append. Appends to one session from one process run one at a time, and a second process needs the
|
|
34
|
+
* writer lock. With `retention`, expired sessions are gzipped into `<dir>/.archive/<user>/` or deleted, and without it
|
|
35
|
+
* no file is ever deleted or moved.
|
|
36
|
+
*/
|
|
37
|
+
export declare function jsonlStore(options: JsonlStoreOptions): SessionStore;
|