@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,128 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Settles what a crash left open, before a turn goes on. A message whose blocks were written without its end is ended
|
|
3
|
+
* as `tool_calls` if it made calls and as `aborted` if not. A tool call whose result never reached the log must not get an ordinary error: for a write, or a tool
|
|
4
|
+
* this harness doesn't know, the call may have taken effect, so its result says the outcome is unknown and tells the
|
|
5
|
+
* model to check before any retry. A read-only call has changed nothing, so it gets an error the model may retry. A
|
|
6
|
+
* turn with no end gets a `turn_end` that says it was aborted. Calls a turn left waiting for an approval or an answer
|
|
7
|
+
* are not a crash: they stay open for the approval that resolves them.
|
|
8
|
+
*/
|
|
9
|
+
import { renderOutcome, writeOutcome } from "@buildanagent/agent-safety";
|
|
10
|
+
import { crashedResumes } from "./rebuild.js";
|
|
11
|
+
const READ_ONLY_TEXT = "The tool call was interrupted before a result was recorded.";
|
|
12
|
+
/** The result of a call that may have taken effect: `unknown`, to be checked before any retry. */
|
|
13
|
+
function interruptedWrite(tool) {
|
|
14
|
+
const rendered = renderOutcome(writeOutcome({
|
|
15
|
+
kind: "unknown",
|
|
16
|
+
operation: tool,
|
|
17
|
+
retry: "reconcile_first",
|
|
18
|
+
reason: "WRITE_INTERRUPTED",
|
|
19
|
+
currentState: "The call stopped before it recorded a result, so it may have taken effect.",
|
|
20
|
+
next: "Check whether it took effect before you do anything else, and tell the user if you cannot.",
|
|
21
|
+
}));
|
|
22
|
+
return {
|
|
23
|
+
content: [
|
|
24
|
+
{ type: "text", text: rendered.text },
|
|
25
|
+
{ type: "text", text: JSON.stringify({ outcome: rendered.payload }) },
|
|
26
|
+
],
|
|
27
|
+
isError: rendered.isError,
|
|
28
|
+
details: { outcome: rendered.payload },
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* The result of a call whose own result never reached the log. A call to a write, or to a tool the registry no longer
|
|
33
|
+
* has, may have taken effect, so its outcome is `unknown`; a read-only call changed nothing, so it gets a plain error.
|
|
34
|
+
*/
|
|
35
|
+
export function interruptedResult(harness, name) {
|
|
36
|
+
const tool = harness.registry.get(name);
|
|
37
|
+
// A tool the registry no longer has may have been a write, so its call is as uncertain as a write's.
|
|
38
|
+
const mayHaveWritten = tool === undefined || tool.definition.effect?.kind === "write";
|
|
39
|
+
return {
|
|
40
|
+
...(mayHaveWritten ? interruptedWrite(name) : { content: [{ type: "text", text: READ_ONLY_TEXT }], isError: true }),
|
|
41
|
+
trust: tool?.outputTrust ?? "untrusted",
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
/** Ends each assistant message that has blocks and no end, so its calls are part of the context. */
|
|
45
|
+
async function endDanglingMessages(path, harness, write) {
|
|
46
|
+
const ended = new Set(path.flatMap((entry) => (entry.type === "message_end" ? [entry.messageId] : [])));
|
|
47
|
+
const dangling = new Map();
|
|
48
|
+
for (const entry of path) {
|
|
49
|
+
if (entry.type === "message_block" && entry.role === "assistant" && !ended.has(entry.messageId)) {
|
|
50
|
+
dangling.set(entry.messageId, entry.block.type === "tool_call" || dangling.get(entry.messageId) === true);
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
const model = path.findLast((entry) => entry.type === "loadout" && entry.model !== undefined);
|
|
54
|
+
const ref = model?.type === "loadout" && model.model !== undefined ? model.model : harness.model.ref;
|
|
55
|
+
for (const [messageId, hasCalls] of dangling) {
|
|
56
|
+
// The gateway drops an aborted message with the results that answer its calls, so a message that made calls ends as
|
|
57
|
+
// `tool_calls`, and the model reads the unknown outcome of each call.
|
|
58
|
+
await write("model", {
|
|
59
|
+
type: "message_end",
|
|
60
|
+
messageId,
|
|
61
|
+
model: ref,
|
|
62
|
+
stopReason: hasCalls ? "tool_calls" : "aborted",
|
|
63
|
+
});
|
|
64
|
+
}
|
|
65
|
+
return dangling.size;
|
|
66
|
+
}
|
|
67
|
+
const PAUSES = new Set(["awaiting_approval", "clarification_requested"]);
|
|
68
|
+
/**
|
|
69
|
+
* The calls the path's assistant blocks make that no `tool_result` answers, in the order the model made them. A turn
|
|
70
|
+
* that ended waiting for an approval or an answer leaves its calls open on purpose, so they are left out unless
|
|
71
|
+
* `includePaused` is set.
|
|
72
|
+
*/
|
|
73
|
+
export function unansweredCalls(path, includePaused = false) {
|
|
74
|
+
const answered = new Set(path.flatMap((entry) => (entry.type === "tool_result" ? [entry.callId] : [])));
|
|
75
|
+
// A paused call whose resume started and died counts as a crash: the approved call may have run.
|
|
76
|
+
const crashed = crashedResumes(path);
|
|
77
|
+
const requestOf = new Map(path.flatMap((entry) => entry.type === "approval_requested" ? [[entry.request.callId, entry.request.id]] : []));
|
|
78
|
+
const calls = [];
|
|
79
|
+
const paused = new Set();
|
|
80
|
+
let turn = -1;
|
|
81
|
+
for (const entry of path) {
|
|
82
|
+
if (entry.type === "turn_start")
|
|
83
|
+
turn += 1;
|
|
84
|
+
else if (entry.type === "turn_end" && PAUSES.has(entry.stopReason))
|
|
85
|
+
paused.add(turn);
|
|
86
|
+
else if (entry.type === "message_block" && entry.role === "assistant" && entry.block.type === "tool_call") {
|
|
87
|
+
if (!answered.has(entry.block.callId))
|
|
88
|
+
calls.push({ callId: entry.block.callId, name: entry.block.name, turn });
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
return calls.filter((call) => includePaused || !paused.has(call.turn) || crashed.has(requestOf.get(call.callId) ?? ""));
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Settles what a crash left open and returns whether it wrote anything. `closeTurns` is false when HEAD was moved by
|
|
95
|
+
* a checkout, because a turn that has no end on the branch left behind was not interrupted.
|
|
96
|
+
*/
|
|
97
|
+
export async function settleOpenCalls(path, harness, write, closeTurns) {
|
|
98
|
+
if (path.length === 0)
|
|
99
|
+
return false;
|
|
100
|
+
const calls = unansweredCalls(path);
|
|
101
|
+
const dangling = await endDanglingMessages(path, harness, write);
|
|
102
|
+
for (const call of calls) {
|
|
103
|
+
await write("tool", {
|
|
104
|
+
type: "tool_result",
|
|
105
|
+
callId: call.callId,
|
|
106
|
+
tool: call.name,
|
|
107
|
+
...interruptedResult(harness, call.name),
|
|
108
|
+
});
|
|
109
|
+
}
|
|
110
|
+
const closed = closeTurns ? await closeTurn(path, write, dangling) : false;
|
|
111
|
+
return dangling > 0 || calls.length > 0 || closed;
|
|
112
|
+
}
|
|
113
|
+
async function closeTurn(path, write, justEnded) {
|
|
114
|
+
const start = path.findLast((entry) => entry.type === "turn_start");
|
|
115
|
+
if (start?.type !== "turn_start")
|
|
116
|
+
return false;
|
|
117
|
+
const after = path.slice(path.indexOf(start));
|
|
118
|
+
if (after.some((entry) => entry.type === "turn_end"))
|
|
119
|
+
return false;
|
|
120
|
+
await write("harness", {
|
|
121
|
+
type: "turn_end",
|
|
122
|
+
runId: start.runId,
|
|
123
|
+
stopReason: "aborted",
|
|
124
|
+
steps: after.filter((entry) => entry.type === "message_end").length + justEnded,
|
|
125
|
+
});
|
|
126
|
+
return true;
|
|
127
|
+
}
|
|
128
|
+
//# sourceMappingURL=resume.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"resume.js","sourceRoot":"","sources":["../../src/session/resume.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Settles what a crash left open, before a turn goes on. A message whose blocks were written without its end is ended\n * as `tool_calls` if it made calls and as `aborted` if not. A tool call whose result never reached the log must not get an ordinary error: for a write, or a tool\n * this harness doesn't know, the call may have taken effect, so its result says the outcome is unknown and tells the\n * model to check before any retry. A read-only call has changed nothing, so it gets an error the model may retry. A\n * turn with no end gets a `turn_end` that says it was aborted. Calls a turn left waiting for an approval or an answer\n * are not a crash: they stay open for the approval that resolves them.\n */\nimport { renderOutcome, writeOutcome } from \"@buildanagent/agent-safety\";\nimport type { SessionEntry, ToolResultEntry } from \"@buildanagent/protocol\";\nimport type { Harness } from \"../harness.js\";\nimport { crashedResumes } from \"./rebuild.js\";\n\ntype DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;\ntype Body = DistributiveOmit<SessionEntry, \"id\" | \"parentId\" | \"timestamp\" | \"origin\" | \"seq\">;\n\n/** Writes one entry with the origin it names, after the entries before it. */\nexport type WriteEntry = (origin: \"harness\" | \"model\" | \"tool\", body: Body) => Promise<unknown>;\n\nconst READ_ONLY_TEXT = \"The tool call was interrupted before a result was recorded.\";\n\n/** The result of a call that may have taken effect: `unknown`, to be checked before any retry. */\nfunction interruptedWrite(tool: string): Pick<ToolResultEntry, \"content\" | \"isError\" | \"details\"> {\n const rendered = renderOutcome(\n writeOutcome({\n kind: \"unknown\",\n operation: tool,\n retry: \"reconcile_first\",\n reason: \"WRITE_INTERRUPTED\",\n currentState: \"The call stopped before it recorded a result, so it may have taken effect.\",\n next: \"Check whether it took effect before you do anything else, and tell the user if you cannot.\",\n }),\n );\n return {\n content: [\n { type: \"text\", text: rendered.text },\n { type: \"text\", text: JSON.stringify({ outcome: rendered.payload }) },\n ],\n isError: rendered.isError,\n details: { outcome: rendered.payload },\n };\n}\n\n/**\n * The result of a call whose own result never reached the log. A call to a write, or to a tool the registry no longer\n * has, may have taken effect, so its outcome is `unknown`; a read-only call changed nothing, so it gets a plain error.\n */\nexport function interruptedResult<H>(\n harness: Harness<H>,\n name: string,\n): Pick<ToolResultEntry, \"content\" | \"isError\" | \"details\" | \"trust\"> {\n const tool = harness.registry.get(name);\n // A tool the registry no longer has may have been a write, so its call is as uncertain as a write's.\n const mayHaveWritten = tool === undefined || tool.definition.effect?.kind === \"write\";\n return {\n ...(mayHaveWritten ? interruptedWrite(name) : { content: [{ type: \"text\", text: READ_ONLY_TEXT }], isError: true }),\n trust: tool?.outputTrust ?? \"untrusted\",\n };\n}\n\n/** Ends each assistant message that has blocks and no end, so its calls are part of the context. */\nasync function endDanglingMessages<H>(\n path: readonly SessionEntry[],\n harness: Harness<H>,\n write: WriteEntry,\n): Promise<number> {\n const ended = new Set(path.flatMap((entry) => (entry.type === \"message_end\" ? [entry.messageId] : [])));\n const dangling = new Map<string, boolean>();\n for (const entry of path) {\n if (entry.type === \"message_block\" && entry.role === \"assistant\" && !ended.has(entry.messageId)) {\n dangling.set(entry.messageId, entry.block.type === \"tool_call\" || dangling.get(entry.messageId) === true);\n }\n }\n const model = path.findLast((entry) => entry.type === \"loadout\" && entry.model !== undefined);\n const ref = model?.type === \"loadout\" && model.model !== undefined ? model.model : harness.model.ref;\n for (const [messageId, hasCalls] of dangling) {\n // The gateway drops an aborted message with the results that answer its calls, so a message that made calls ends as\n // `tool_calls`, and the model reads the unknown outcome of each call.\n await write(\"model\", {\n type: \"message_end\",\n messageId,\n model: ref,\n stopReason: hasCalls ? \"tool_calls\" : \"aborted\",\n });\n }\n return dangling.size;\n}\n\nconst PAUSES = new Set([\"awaiting_approval\", \"clarification_requested\"]);\n\n/**\n * The calls the path's assistant blocks make that no `tool_result` answers, in the order the model made them. A turn\n * that ended waiting for an approval or an answer leaves its calls open on purpose, so they are left out unless\n * `includePaused` is set.\n */\nexport function unansweredCalls(\n path: readonly SessionEntry[],\n includePaused = false,\n): { callId: string; name: string }[] {\n const answered = new Set(path.flatMap((entry) => (entry.type === \"tool_result\" ? [entry.callId] : [])));\n // A paused call whose resume started and died counts as a crash: the approved call may have run.\n const crashed = crashedResumes(path);\n const requestOf = new Map(\n path.flatMap((entry) =>\n entry.type === \"approval_requested\" ? [[entry.request.callId, entry.request.id] as const] : [],\n ),\n );\n const calls: { callId: string; name: string; turn: number }[] = [];\n const paused = new Set<number>();\n let turn = -1;\n for (const entry of path) {\n if (entry.type === \"turn_start\") turn += 1;\n else if (entry.type === \"turn_end\" && PAUSES.has(entry.stopReason)) paused.add(turn);\n else if (entry.type === \"message_block\" && entry.role === \"assistant\" && entry.block.type === \"tool_call\") {\n if (!answered.has(entry.block.callId)) calls.push({ callId: entry.block.callId, name: entry.block.name, turn });\n }\n }\n return calls.filter(\n (call) => includePaused || !paused.has(call.turn) || crashed.has(requestOf.get(call.callId) ?? \"\"),\n );\n}\n\n/**\n * Settles what a crash left open and returns whether it wrote anything. `closeTurns` is false when HEAD was moved by\n * a checkout, because a turn that has no end on the branch left behind was not interrupted.\n */\nexport async function settleOpenCalls<H>(\n path: readonly SessionEntry[],\n harness: Harness<H>,\n write: WriteEntry,\n closeTurns: boolean,\n): Promise<boolean> {\n if (path.length === 0) return false;\n const calls = unansweredCalls(path);\n const dangling = await endDanglingMessages(path, harness, write);\n for (const call of calls) {\n await write(\"tool\", {\n type: \"tool_result\",\n callId: call.callId,\n tool: call.name,\n ...interruptedResult(harness, call.name),\n } as Body);\n }\n const closed = closeTurns ? await closeTurn(path, write, dangling) : false;\n return dangling > 0 || calls.length > 0 || closed;\n}\n\nasync function closeTurn(path: readonly SessionEntry[], write: WriteEntry, justEnded: number): Promise<boolean> {\n const start = path.findLast((entry) => entry.type === \"turn_start\");\n if (start?.type !== \"turn_start\") return false;\n const after = path.slice(path.indexOf(start));\n if (after.some((entry) => entry.type === \"turn_end\")) return false;\n await write(\"harness\", {\n type: \"turn_end\",\n runId: start.runId,\n stopReason: \"aborted\",\n steps: after.filter((entry) => entry.type === \"message_end\").length + justEnded,\n });\n return true;\n}\n"]}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Retention for a `jsonlStore()` folder. Nothing is ever deleted unless the caller sets a retention period: an expired
|
|
3
|
+
* session is then gzipped into `.archive/`, where the store still lists and loads it, or deleted with its pointer. The
|
|
4
|
+
* code only runs when a caller asks, either through `pruneSessions()` or when the store first touches a user, and never
|
|
5
|
+
* on a timer. Every doubt resolves to keeping a file: a file the run cannot read, a session it cannot date and a session
|
|
6
|
+
* that a surviving one continues are all left where they are.
|
|
7
|
+
*/
|
|
8
|
+
import { Buffer } from "node:buffer";
|
|
9
|
+
import type { SessionLock } from "./lock.js";
|
|
10
|
+
/**
|
|
11
|
+
* The folder under the store's folder that holds archived sessions, one folder per user. `encodeName()` encodes every
|
|
12
|
+
* `.`, so no user's folder can have this name.
|
|
13
|
+
*/
|
|
14
|
+
export declare const ARCHIVE_DIR = ".archive";
|
|
15
|
+
/** The extension of an archived file: the session file's `.jsonl`, gzipped. */
|
|
16
|
+
export declare const ARCHIVE_EXTENSION = ".jsonl.gz";
|
|
17
|
+
/** How long to keep a session after its last entry, and what to do with it then. */
|
|
18
|
+
export interface Retention {
|
|
19
|
+
/** Days since the session's last entry. A positive number. */
|
|
20
|
+
readonly days: number;
|
|
21
|
+
/** `archive` gzips the session's files into `.archive/`, where the store still reads them. `purge` deletes them. */
|
|
22
|
+
readonly action: "archive" | "purge";
|
|
23
|
+
}
|
|
24
|
+
/** The options of `pruneSessions()`. */
|
|
25
|
+
export interface PruneOptions {
|
|
26
|
+
/** The store's folder. */
|
|
27
|
+
readonly dir: string;
|
|
28
|
+
readonly userId: string;
|
|
29
|
+
/** Without it nothing is touched, so a caller that has no retention period can pass its setting through unchecked. */
|
|
30
|
+
readonly retention?: Retention;
|
|
31
|
+
/** The clock. Default `new Date()`. */
|
|
32
|
+
readonly now?: () => Date;
|
|
33
|
+
/**
|
|
34
|
+
* The writer lock. A session whose lock is held is kept, and the run holds each lock it takes until that session is
|
|
35
|
+
* archived, purged or kept.
|
|
36
|
+
*/
|
|
37
|
+
readonly lock?: SessionLock;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Why an expired session was left alone. `locked`: a writer holds its lock. `continued`: a surviving session continues
|
|
41
|
+
* its log. `unreadable`: a file of it, its pointer or, for a purge, any file in the user's folder could not be read, so
|
|
42
|
+
* the run can't tell whether it is expired or continued. `error`: expiring it failed, and the error is in `errors`.
|
|
43
|
+
*/
|
|
44
|
+
export type KeptReason = "locked" | "continued" | "unreadable" | "error";
|
|
45
|
+
/** What `pruneSessions()` did, by session id. */
|
|
46
|
+
export interface PruneResult {
|
|
47
|
+
readonly archived: string[];
|
|
48
|
+
readonly purged: string[];
|
|
49
|
+
/** Expired sessions left alone, and why. */
|
|
50
|
+
readonly kept: Array<{
|
|
51
|
+
readonly sessionId: string;
|
|
52
|
+
readonly reason: KeptReason;
|
|
53
|
+
}>;
|
|
54
|
+
/**
|
|
55
|
+
* Files the run left untouched because it could not read them or tell which session they belong to, by name under the
|
|
56
|
+
* user's folder or the user's archive folder. A file with no complete line holds nothing and is not listed.
|
|
57
|
+
*/
|
|
58
|
+
readonly skipped: string[];
|
|
59
|
+
/** What stopped each session in `kept` with reason `error`. The run went on with the other sessions. */
|
|
60
|
+
readonly errors: Array<{
|
|
61
|
+
readonly sessionId: string;
|
|
62
|
+
readonly error: unknown;
|
|
63
|
+
}>;
|
|
64
|
+
}
|
|
65
|
+
/** Throws a `HarnessError` with code `invalid_retention` unless `days` is a positive finite number and `action` is known. */
|
|
66
|
+
export declare function checkRetention(retention: Retention): void;
|
|
67
|
+
/** Where a session file's archive is. */
|
|
68
|
+
export declare const archivePath: (dir: string, userId: string, file: string) => string;
|
|
69
|
+
/** The bytes of an archived file, or `undefined` when there is none. */
|
|
70
|
+
export declare function readArchive(path: string): Promise<Buffer | undefined>;
|
|
71
|
+
/** Moves a file's archive back to its place, for a session that is written again. Returns whether there was one. */
|
|
72
|
+
export declare function restoreArchive(dir: string, userId: string, file: string, live: string): Promise<boolean>;
|
|
73
|
+
/**
|
|
74
|
+
* Expires the user's sessions: each one whose last entry is more than `retention.days` old is archived or purged, and
|
|
75
|
+
* with no `retention` nothing happens. A session is a first file, the derived files that continue it and its pointer,
|
|
76
|
+
* and its files count wherever they are, live or archived, so an archived session expires again under a purge.
|
|
77
|
+
*
|
|
78
|
+
* Before anything is removed, the run takes the lock of every session it means to expire, reads the folder again, and
|
|
79
|
+
* decides from that second read which sessions survive: the fresh ones, the locked ones, and the ones it can't read or
|
|
80
|
+
* date. A writer that appended between the first read and the lock is so judged on what it wrote. A purge then keeps
|
|
81
|
+
* every expired session that a survivor continues, directly or through another kept session, and it keeps every
|
|
82
|
+
* session when any file in the user's folder can't be read, because that file could continue any of them. A purge
|
|
83
|
+
* removes a fork before the session it continues, and keeps that session when the fork's removal fails. Each lock is
|
|
84
|
+
* given up as soon as its session is archived, purged or kept. Without `lock`, nothing stops a writer elsewhere from
|
|
85
|
+
* appending to a session while the run moves it, so pass the lock that writers hold.
|
|
86
|
+
*
|
|
87
|
+
* Each archived file is written and read back before its original goes, and a file deleted while the run goes on is
|
|
88
|
+
* not brought back. A session's files go one at a time, newest first, then its first file and then its pointer, so a
|
|
89
|
+
* run that stops part-way leaves a session the next run still finds and finishes. A failure stops only its own session:
|
|
90
|
+
* it is recorded in `errors` and the run goes on.
|
|
91
|
+
*/
|
|
92
|
+
export declare function pruneSessions(options: PruneOptions): Promise<PruneResult>;
|
|
93
|
+
/**
|
|
94
|
+
* `pruneSessions()` for the store, which passes `busy`: a session with a file that one of the store's own calls is
|
|
95
|
+
* reading or writing is kept as `locked`, so a pass never moves a file under a call that is already past expiry.
|
|
96
|
+
*/
|
|
97
|
+
export declare function expireSessions(options: PruneOptions, busy: (fileId: string) => boolean): Promise<PruneResult>;
|