@buildanagent/harness 0.1.0-alpha.28 → 0.1.0-alpha.30

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.
Files changed (113) hide show
  1. package/README.md +152 -5
  2. package/dist/context/file-spill.d.ts +11 -1
  3. package/dist/context/file-spill.js +23 -8
  4. package/dist/context/file-spill.js.map +1 -1
  5. package/dist/context/spill.d.ts +5 -1
  6. package/dist/context/spill.js +6 -2
  7. package/dist/context/spill.js.map +1 -1
  8. package/dist/credentials/addresses.d.ts +11 -0
  9. package/dist/credentials/addresses.js +41 -2
  10. package/dist/credentials/addresses.js.map +1 -1
  11. package/dist/credentials/allowlist.d.ts +22 -2
  12. package/dist/credentials/allowlist.js +74 -17
  13. package/dist/credentials/allowlist.js.map +1 -1
  14. package/dist/credentials/egress-policy.d.ts +69 -0
  15. package/dist/credentials/egress-policy.js +170 -0
  16. package/dist/credentials/egress-policy.js.map +1 -0
  17. package/dist/credentials/egress-proxy.d.ts +13 -1
  18. package/dist/credentials/egress-proxy.js +179 -11
  19. package/dist/credentials/egress-proxy.js.map +1 -1
  20. package/dist/credentials/git-route.d.ts +68 -0
  21. package/dist/credentials/git-route.js +288 -0
  22. package/dist/credentials/git-route.js.map +1 -0
  23. package/dist/credentials/index.d.ts +5 -1
  24. package/dist/credentials/index.js +5 -1
  25. package/dist/credentials/index.js.map +1 -1
  26. package/dist/credentials/scrub.d.ts +7 -0
  27. package/dist/credentials/scrub.js +22 -0
  28. package/dist/credentials/scrub.js.map +1 -1
  29. package/dist/errors.d.ts +14 -7
  30. package/dist/errors.js +13 -6
  31. package/dist/errors.js.map +1 -1
  32. package/dist/sandbox/base.d.ts +11 -1
  33. package/dist/sandbox/base.js +14 -0
  34. package/dist/sandbox/base.js.map +1 -1
  35. package/dist/sandbox/docker/index.d.ts +8 -2
  36. package/dist/sandbox/docker/index.js +63 -14
  37. package/dist/sandbox/docker/index.js.map +1 -1
  38. package/dist/sandbox/errors.d.ts +30 -2
  39. package/dist/sandbox/errors.js +36 -1
  40. package/dist/sandbox/errors.js.map +1 -1
  41. package/dist/sandbox/escalation-table.d.ts +38 -0
  42. package/dist/sandbox/escalation-table.js +95 -0
  43. package/dist/sandbox/escalation-table.js.map +1 -0
  44. package/dist/sandbox/escalation.d.ts +191 -0
  45. package/dist/sandbox/escalation.js +370 -0
  46. package/dist/sandbox/escalation.js.map +1 -0
  47. package/dist/sandbox/host-files.d.ts +2 -0
  48. package/dist/sandbox/host-files.js +10 -0
  49. package/dist/sandbox/host-files.js.map +1 -1
  50. package/dist/sandbox/index.d.ts +9 -4
  51. package/dist/sandbox/index.js +8 -3
  52. package/dist/sandbox/index.js.map +1 -1
  53. package/dist/sandbox/policy.d.ts +49 -0
  54. package/dist/sandbox/policy.js +149 -0
  55. package/dist/sandbox/policy.js.map +1 -0
  56. package/dist/sandbox/process.js +1 -1
  57. package/dist/sandbox/process.js.map +1 -1
  58. package/dist/sandbox/srt/index.d.ts +5 -2
  59. package/dist/sandbox/srt/index.js +27 -8
  60. package/dist/sandbox/srt/index.js.map +1 -1
  61. package/dist/sandbox/srt/settings.d.ts +17 -5
  62. package/dist/sandbox/srt/settings.js +53 -0
  63. package/dist/sandbox/srt/settings.js.map +1 -1
  64. package/dist/sandbox/types.d.ts +41 -4
  65. package/dist/sandbox/types.js.map +1 -1
  66. package/dist/sandbox/widen.d.ts +10 -0
  67. package/dist/sandbox/widen.js +150 -0
  68. package/dist/sandbox/widen.js.map +1 -0
  69. package/dist/session/approvals.d.ts +30 -1
  70. package/dist/session/approvals.js +12 -4
  71. package/dist/session/approvals.js.map +1 -1
  72. package/dist/session/code-call.d.ts +15 -1
  73. package/dist/session/code-call.js +2 -1
  74. package/dist/session/code-call.js.map +1 -1
  75. package/dist/session/escalation-log.d.ts +65 -0
  76. package/dist/session/escalation-log.js +84 -0
  77. package/dist/session/escalation-log.js.map +1 -0
  78. package/dist/session/rebuild.js +12 -3
  79. package/dist/session/rebuild.js.map +1 -1
  80. package/dist/testing/fake-sandbox.d.ts +21 -3
  81. package/dist/testing/fake-sandbox.js +157 -8
  82. package/dist/testing/fake-sandbox.js.map +1 -1
  83. package/dist/testing/sandbox-conformance.js +108 -1
  84. package/dist/testing/sandbox-conformance.js.map +1 -1
  85. package/dist/tools/builtins/bash.d.ts +9 -0
  86. package/dist/tools/builtins/bash.js +75 -0
  87. package/dist/tools/builtins/bash.js.map +1 -0
  88. package/dist/tools/builtins/builtins.d.ts +38 -0
  89. package/dist/tools/builtins/builtins.js +48 -0
  90. package/dist/tools/builtins/builtins.js.map +1 -0
  91. package/dist/tools/builtins/descriptions.d.ts +69 -0
  92. package/dist/tools/builtins/descriptions.js +94 -0
  93. package/dist/tools/builtins/descriptions.js.map +1 -0
  94. package/dist/tools/builtins/fetch.d.ts +12 -0
  95. package/dist/tools/builtins/fetch.js +157 -0
  96. package/dist/tools/builtins/fetch.js.map +1 -0
  97. package/dist/tools/builtins/files.d.ts +27 -0
  98. package/dist/tools/builtins/files.js +274 -0
  99. package/dist/tools/builtins/files.js.map +1 -0
  100. package/dist/tools/builtins/paths.d.ts +30 -0
  101. package/dist/tools/builtins/paths.js +62 -0
  102. package/dist/tools/builtins/paths.js.map +1 -0
  103. package/dist/tools/builtins/results.d.ts +15 -0
  104. package/dist/tools/builtins/results.js +31 -0
  105. package/dist/tools/builtins/results.js.map +1 -0
  106. package/dist/tools/builtins/search.d.ts +18 -0
  107. package/dist/tools/builtins/search.js +217 -0
  108. package/dist/tools/builtins/search.js.map +1 -0
  109. package/dist/tools/index.d.ts +6 -2
  110. package/dist/tools/index.js +5 -2
  111. package/dist/tools/index.js.map +1 -1
  112. package/llms.txt +52 -0
  113. package/package.json +5 -5
package/llms.txt CHANGED
@@ -9,12 +9,17 @@ The sections of README.md and every public export, generated from this package's
9
9
  - [Install the alpha with `pnpm add @buildanagent/harness@alpha`](README.md#install-the-alpha-with-pnpm-add-buildanagentharnessalpha)
10
10
  - [The session log holds twenty-one entry types](README.md#the-session-log-holds-twenty-one-entry-types)
11
11
  - [A sandbox says what it stops, and the host decides what it may touch](README.md#a-sandbox-says-what-it-stops-and-the-host-decides-what-it-may-touch)
12
+ - [A denied command becomes a signed request, and an approved one reruns once](README.md#a-denied-command-becomes-a-signed-request-and-an-approved-one-reruns-once)
12
13
  - [The srt backend confines each command with Anthropic's OS sandbox](README.md#the-srt-backend-confines-each-command-with-anthropics-os-sandbox)
13
14
  - [The Docker backend runs each command in a locked-down container](README.md#the-docker-backend-runs-each-command-in-a-locked-down-container)
15
+ - [A backend that claims a stop reads its policy back, and one that can't resume says so](README.md#a-backend-that-claims-a-stop-reads-its-policy-back-and-one-that-cant-resume-says-so)
14
16
  - [The egress proxy keeps every credential outside the sandbox](README.md#the-egress-proxy-keeps-every-credential-outside-the-sandbox)
17
+ - [An egress policy names a credential and never holds one](README.md#an-egress-policy-names-a-credential-and-never-holds-one)
18
+ - [A git route lets a push reach listed branches and nothing else](README.md#a-git-route-lets-a-push-reach-listed-branches-and-nothing-else)
15
19
  - [Every spawned process gets a cleared environment](README.md#every-spawned-process-gets-a-cleared-environment)
16
20
  - [Test a sandbox with the fake and the conformance suite](README.md#test-a-sandbox-with-the-fake-and-the-conformance-suite)
17
21
  - [One registry names, defers and wraps every tool](README.md#one-registry-names-defers-and-wraps-every-tool)
22
+ - [The built-in tools reach files, commands and the web only through the sandbox and the egress proxy](README.md#the-built-in-tools-reach-files-commands-and-the-web-only-through-the-sandbox-and-the-egress-proxy)
18
23
  - [One pipeline decides every tool call, and a call no rule settles is denied when nobody can answer](README.md#one-pipeline-decides-every-tool-call-and-a-call-no-rule-settles-is-denied-when-nobody-can-answer)
19
24
  - [A session belongs to a user, and every store call names both](README.md#a-session-belongs-to-a-user-and-every-store-call-names-both)
20
25
  - [One writer holds a session's lock, and a lock outlives a crash only by its lease](README.md#one-writer-holds-a-sessions-lock-and-a-lock-outlives-a-crash-only-by-its-lease)
@@ -205,12 +210,18 @@ The sections of README.md and every public export, generated from this package's
205
210
  ## Exports from `@buildanagent/harness/context/file`
206
211
 
207
212
  - `fileSpillStore()`: A spill store that writes `<dir>/<user>/<session>/<callId>.txt` and returns that path.
213
+ - `interface FileSpillStore`: A spill store in files, which can also read back the spills of one session.
208
214
 
209
215
  ## Exports from `@buildanagent/harness/tools`
210
216
 
211
217
  - `type ApprovalReuse`: Which approvals may cover later calls: a sticky one, a grouped one, both, or none, so each call asks.
218
+ - `BUILTIN_TOOL_DEFAULTS`: The built-in tools' descriptions, limits and defaults, frozen.
219
+ - `BUILTIN_TOOLS_HASH`: The SHA-256 of the canonical JSON of `BUILTIN_TOOL_DEFAULTS`.
220
+ - `builtinTools()`: The built-in tools for one sandbox: `read`, `write`, `edit`, `bash`, `grep`, `glob` and, when `proxy` is given, `fetch`.
221
+ - `interface BuiltinToolsOptions`: The options of `builtinTools()`.
212
222
  - `createToolRegistry()`: Creates an empty registry.
213
223
  - `class DuplicateToolError`: Thrown by `register()` when a registry already holds a tool, or an alias, by that name.
224
+ - `type FetchProxy`: What the `fetch` tool needs of an egress proxy.
214
225
  - `type HostPattern`: How a tool's code is reached: in this process, or by asking the client through a `tool/call` server request.
215
226
  - `type OutputTrust`: Whether a tool's output may carry instructions an attacker wrote.
216
227
  - `interface PreambleOptions`: The options of `preambleTokens()`.
@@ -264,20 +275,47 @@ The sections of README.md and every public export, generated from this package's
264
275
  ## Exports from `@buildanagent/harness/sandbox`
265
276
 
266
277
  - `type ApprovalPolicy`: When a denied action may be asked for again, which is the host's decision and never the sandbox's.
278
+ - `confirmPolicy()`: Reads back the policy `sandbox` applied and compares it with `requested`.
279
+ - `escalation()`: Creates the escalation machine for a harness's approvals.
280
+ - `ESCALATION_EVENTS`: Every event.
281
+ - `ESCALATION_STATES`: Every state, in the order a command that escalates passes through them.
282
+ - `ESCALATION_TOOL`: The tool name an escalation's signed request carries.
283
+ - `ESCALATION_TRANSITIONS`: The legal edges.
284
+ - `type EscalationEvent`: What moves a command between states.
285
+ - `interface EscalationMachine`: The machine `escalation()` returns.
286
+ - `interface EscalationOptions`: The options of `escalation()`.
287
+ - `interface EscalationRecord`: What an escalation's request signs, as the input of its `approval_requested` entry: the call the command ran for, the command, the workspace root, the policy it ran under and the denial.
288
+ - `interface EscalationResolveOptions`: The options of `EscalationMachine.resolve()`: where the rerun runs, which the log does not hold.
289
+ - `type EscalationResult`: How an escalation call ended.
290
+ - `interface EscalationRule`: One rule of a `granular` policy: a denial of `kind` for `tool` may be asked about (`on-request`) or goes back to the caller (`never`).
291
+ - `interface EscalationRun`: One command to run in a sandbox, for one tool call, and what the host provisions the sandbox with.
292
+ - `type EscalationState`: Where a sandboxed command stands.
293
+ - `interface EscalationTransition`: One legal edge: from a state, on an event, to a state, and when the machine takes it.
267
294
  - `interface ExecOptions`: The options of `Sandbox.exec()`.
268
295
  - `type ExecResult`: What a command did: its exit status and output, or the denial that stopped it.
296
+ - `hasCapability()`: Whether `client` lists `capability`.
297
+ - `nextEscalationState()`: The state `event` moves `from` to.
269
298
  - `NONE_SANDBOX_WARNING`: The warning written when a sandbox starts.
270
299
  - `noneSandbox()`: Builds the `none` backend.
271
300
  - `interface NoneSandboxOptions`: The options of `noneSandbox()`.
301
+ - `pauseSandbox()`: Pauses `sandbox` until `resumeSandbox()` with its `id`, or throws `SandboxUnsupportedError`.
302
+ - `interface PendingEscalation`: An escalation that waits for an answer: its id, its signed request and the record the request signs.
303
+ - `policyDifference()`: The first field in which `applied` differs from `requested`, or `undefined` when they hold the same entries.
304
+ - `resumeSandbox()`: Reattaches to a sandbox by its id, or starts one from a snapshot's id, then confirms its policy as `provision()` does and sets the sandbox's `stops` to what the confirmed policy delivers.
272
305
  - `interface Sandbox`: A provisioned sandbox.
306
+ - `type SandboxCapability`: What a backend can do besides provisioning.
273
307
  - `interface SandboxClient`: A sandbox backend.
274
308
  - `interface SandboxDenial`: What the policy refused.
275
309
  - `class SandboxDeniedError`: Thrown when the policy refuses a file read or write.
276
310
  - `interface SandboxPolicy`: What a sandbox may touch.
311
+ - `class SandboxPolicyMismatchError`: Thrown when the policy a backend read back from what it applied differs from the policy it was asked for, after `provision()` or a resume.
277
312
  - `type SandboxStop`: What a backend claims to stop.
278
313
  - `type SandboxTier`: How strongly a backend confines a process.
279
314
  - `class SandboxUnavailableError`: Thrown by `provision()` when a backend can't start, such as a missing binary.
315
+ - `class SandboxUnsupportedError`: Thrown by `resumeSandbox()`, `snapshotSandbox()` and `pauseSandbox()` for a capability the backend doesn't list.
316
+ - `snapshotSandbox()`: Snapshots `sandbox` and resolves with the id `resumeSandbox()` takes, or throws `SandboxUnsupportedError`.
280
317
  - `spawnEnv()`: The environment for a spawned process: `PATH`, a fresh temp `HOME`, `TMPDIR` and `LANG`, plus the parent variables named in `allow` that are set, plus every `extra`.
318
+ - `stopsFor()`: The stops a backend of `tier` delivers under `policy`.
281
319
  - `interface WorkspaceManifest`: The workspace a sandbox is provisioned for: its root directory and the files to put there first.
282
320
 
283
321
  ## Exports from `@buildanagent/harness/sandbox/srt`
@@ -285,6 +323,8 @@ The sections of README.md and every public export, generated from this package's
285
323
  - `SRT_ADDED_ENVIRONMENT`: The variables `srt` 0.0.83 adds to a command's environment, which are its proxy settings and the few that go with them.
286
324
  - `SRT_SYSTEM_READ_ROOTS`: The system folders a program needs to start.
287
325
  - `interface SrtPathEntry`: A path that `srt` must read as written.
326
+ - `srtPolicyFromSettings()`: The policy a settings file applies, in the spelling of the request.
327
+ - `interface SrtPolicyNames`: How a settings file's real paths map back to the spelling of the request, for `srtPolicyFromSettings()`.
288
328
  - `srtSandbox()`: Builds the `srt` backend.
289
329
  - `interface SrtSandboxOptions`: The options of `srtSandbox()`.
290
330
  - `srtSettings()`: Denies every read and then allows the policy's read and write roots, the system folders and the helper folders back.
@@ -299,12 +339,24 @@ The sections of README.md and every public export, generated from this package's
299
339
 
300
340
  ## Exports from `@buildanagent/harness/credentials`
301
341
 
342
+ - `interface CompiledEgressPolicy`: A compiled policy: the `allow` and `routes` options of `startEgressProxy()`.
343
+ - `interface CompileEgressOptions`: The options of `compileEgressPolicy()`.
344
+ - `compileEgressPolicy()`: Checks `policy` and compiles it for `startEgressProxy()`: pass the result's `allow` and `routes` with a `log`.
302
345
  - `interface CredentialRoute`: One credential route: where a request for `/<route>/…` goes, and how the proxy adds the credential.
346
+ - `interface EgressPolicy`: What a sandbox may reach: the hosts it may tunnel to, and the routes that add a credential on its behalf.
303
347
  - `interface EgressProxy`: A running egress proxy.
304
348
  - `interface EgressProxyOptions`: The options of `startEgressProxy()`.
305
349
  - `interface EgressRecord`: One line of the egress log.
350
+ - `type EgressRoute`: One credential route of an `EgressPolicy`.
351
+ - `GIT_MAX_COMMAND_BYTES`: The most bytes of a push's command list, before its flush, that the route reads.
352
+ - `GIT_MAX_COMMANDS`: The most ref updates in one push.
353
+ - `interface GitEgressRoute`: A route for git over HTTPS: git's smart HTTP requests for the listed repositories only, and a push only to the listed branches.
354
+ - `interface GitRouteFilter`: What a git route lets through.
355
+ - `interface HeaderEgressRoute`: A route that swaps the sentinel in one request header for a credential, as `startEgressProxy()`'s routes do.
306
356
  - `isAddressLiteral()`: Whether `text` is an IPv4 or IPv6 address, as a host name that must not be looked up.
307
357
  - `isPublicAddress()`: Whether `address` is a public one a proxy may connect to.
358
+ - `isValidRefName()`: Whether `name` is a ref name git itself would accept, by `git check-ref-format`'s rules, under `refs/`.
359
+ - `pushVerdict()`: The route's verdict on the start of a push body: `incomplete` while the command list hasn't reached its flush, `allowed` once every command creates or updates a ref the patterns allow, or the reason it is refused.
308
360
  - `REDACTED`: What replaces a secret.
309
361
  - `scrubSecrets()`: Returns a copy of `entry` with every secret replaced by `[REDACTED]`, in every string value and every key, at any depth.
310
362
  - `startEgressProxy()`: Starts the egress proxy on `127.0.0.1` with a port the system picks, or on `socketPath`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@buildanagent/harness",
3
- "version": "0.1.0-alpha.28",
3
+ "version": "0.1.0-alpha.30",
4
4
  "description": "The buildanagent harness: the session log, context policy, tools, permissions, sandbox and credentials around the SDK's loop.",
5
5
  "license": "Apache-2.0 OR MIT",
6
6
  "repository": {
@@ -103,10 +103,10 @@
103
103
  "@anthropic-ai/sandbox-runtime": "0.0.83",
104
104
  "@earendil-works/pi-schema": "1.5.2",
105
105
  "@modelcontextprotocol/client": "2.4.0",
106
- "@buildanagent/agent-safety": "0.1.0-alpha.28",
107
- "@buildanagent/gateway": "0.1.0-alpha.28",
108
- "@buildanagent/sdk": "0.1.0-alpha.28",
109
- "@buildanagent/protocol": "0.1.0-alpha.28"
106
+ "@buildanagent/agent-safety": "0.1.0-alpha.30",
107
+ "@buildanagent/protocol": "0.1.0-alpha.30",
108
+ "@buildanagent/sdk": "0.1.0-alpha.30",
109
+ "@buildanagent/gateway": "0.1.0-alpha.30"
110
110
  },
111
111
  "devDependencies": {
112
112
  "@modelcontextprotocol/server": "2.4.0",