@buildanagent/harness 0.1.0-alpha.29 → 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.
package/README.md CHANGED
@@ -66,6 +66,47 @@ The `none` backend starts each command in its own process group. A timeout, an a
66
66
 
67
67
  Bad input is an error, not a result. A working directory that isn't an existing folder, a bad `timeoutMs` or a bad `maxOutputBytes` throws a `HarnessError`. An already aborted signal rejects before the command runs, and reading a missing file rejects with the code `sandbox_not_found`.
68
68
 
69
+ ## A denied command becomes a signed request, and an approved one reruns once
70
+
71
+ `escalation({ approvalPolicy, approvals })` from `./sandbox` decides what happens when the sandbox denies a command. The host owns that decision, and no tool or model can widen the sandbox. A wider policy is built on the host from two things only, the denial the backend reported and a verified answer, and it lasts for one rerun.
72
+
73
+ ```ts
74
+ import { escalation, spawnEnv } from "@buildanagent/harness/sandbox";
75
+
76
+ const machine = escalation({ approvalPolicy: "on-request", approvals: createApprovals(harness) });
77
+ const where = { client, manifest: { root: "/work/repo" }, env: spawnEnv([]), signal: controller.signal };
78
+ const outcome = await machine.run(session, { ...where, tool: "fetch", input: { url: "https://example.com" }, command: ["curl", "https://example.com"], policy });
79
+ ```
80
+
81
+ `machine.run(session, run)` runs the command once under `run.policy` and ends one of three ways. Each result carries `result`, a tool result a tool can return to the model. The model reads it only when nothing was written, as under `never`; once a request exists, the rebuilt context leaves it out and the host reads it.
82
+
83
+ - **`ran`.** The backend did not deny the command, and nothing is written.
84
+ - **`denied`.** The backend denied it, and nobody is asked, so nothing is written. That is every denial under `never`, every denial that no `granular` rule lets the host ask about, and every denial that can't be widened: a path that is `/`, relative or holds `..`, a host with a wildcard, a scheme or a path, and a host that an entry of the policy's own `network.deny` closes. An entry closes a host as `srt` matches a denied domain: `*` closes every host, `*.name` every name under `name` but not `name` itself, and any other entry that host alone, with case ignored. An entry's port is ignored, so a host closed on one port is never widened on any, and an IPv6 address is never widened while `deny` names any IPv6 address. An address must be in its canonical form: an IPv4 address as four decimal octets with no leading zero, and an IPv6 address that does not wrap an IPv4 one. A host whose last label is a number counts as an IPv4 address, so `127.1`, `2130706433` and `0x7f.1` can't be widened, and a deny entry closes an IPv4 address it names in any spelling, such as `10.1` for `10.0.0.1`. A host that reaches the machine itself or its link is never widened, whatever `deny` says: `localhost` and the names under it, and the unspecified, loopback and link-local addresses, which hold the cloud metadata address 169.254.169.254. A name that DNS resolves to a closed address can't be seen here, so the backend's own deny list still covers it.
85
+ - **`awaiting_approval`.** Under `on-request`, or `granular` where a rule allows it, `run()` writes an `approval_requested` entry before it returns. The harness's signer signs the request as `createPendingRequest()` does, and the request's tool is `ESCALATION_TOOL` (`sandbox.escalation`), a name no registered tool can have. Its input is the record the approver sees: the tool and its input, the command, the workspace root, the policy and the denial. `widened` is the policy the rerun would get.
86
+
87
+ `run()` writes only when it asks. A tool's `execute` may call it under `never`, and under the other two policies host code calls it between turns, as it calls `invokeTool()`, because a write inside a turn's tool step can race the turn's own writes.
88
+
89
+ `machine.resolve(session, resolution, options)` answers one request. The log holds no backend, workspace, environment or signal, so `options` passes them again:
90
+
91
+ ```ts
92
+ import { spawnEnv } from "@buildanagent/harness/sandbox";
93
+
94
+ const rerun = await machine.resolve(session, { requestId, decision: "allow", by: "grace" }, { client, manifest: { root: "/work/repo" }, env: spawnEnv([]), signal: controller.signal });
95
+ ```
96
+
97
+ - **The check comes first.** Before anything is written, the answer is checked against the request: the signature under a key in the ring, the bound host context, the call, and the record, which must hash to the signed hash. A forged, re-signed or edited request throws `approval_refused`, writes nothing and runs nothing.
98
+ - **Only a named person or hook approves a rerun.** An allow with no `by`, or whose `by` starts with `classifier:` in any case, throws `approval_refused`, writes nothing and leaves the request waiting. A person's or a hook's allow approves it. `by` is not covered by the request's signature, so set it only after you have authenticated the approver.
99
+ - **The quorum policy decides.** The answer is written, and the approvals' quorum policy decides the answer. A quorum that still waits returns `awaiting_approval`, and a deny, a rejection or an expiry ends `denied` with no rerun.
100
+ - **An abort before the answer is written writes no answer.** `options.signal` is checked when `resolve()` is called and again just before the answer is written, so an abort by then runs nothing and the request still waits. Once the answer is written the approval is spent, and an abort only reaches the rerun, as `Sandbox.exec()` takes a signal.
101
+ - **A deny rule added since the pause wins.** An allow goes through the permission pipeline again, as the tool call the command ran for.
102
+ - **The rerun runs once, no wider than the denial.** It runs in a fresh sandbox under the recorded policy plus exactly the path or host that was denied, and that sandbox is disposed after it. A second denial is the rerun's result: it ends `denied`, and nobody is asked again.
103
+
104
+ Every move follows `ESCALATION_TRANSITIONS`, a table of the states `sandboxed`, `denied`, `requested`, `approved`, `rerun` and `done` and the events between them. A result's `status` and the state `denied` are different things: `status` is how the call ended, and `states` is the path it took. `nextEscalationState()` throws `invalid_escalation` for an edge the table does not list. Only a verified allow leads from `requested` to `approved`, and `rerun` leads only to `done`. Each result's `states` lists the states its call passed through.
105
+
106
+ A rerun runs at most once, even across a crash. It *starts* once the log holds the pipeline's fresh decision after a final allow, the last entry before the rerun runs. To *settle* an escalation is to write the result it lacks. The next `resolve()`, or `run()` that asks, settles each escalation a crash left open: a rerun that started may have run, so it is settled as such and never run again, and an answer whose rerun never started is settled as never run. The result is a `tool_result` with the tool `sandbox.escalation`. The rerun's output, and any sentence that quotes a backend's denial, an error's message or an approver's reason, is marked `untrusted`; only the harness's own fixed sentences, such as a crash's settlement, are marked `trusted`. The model never reads the result, because the rebuilt context leaves out each result whose call id is an escalation's; a result the model's own call got stays, even for a call to a tool it named `sandbox.escalation`. The host gets the command's output from `resolve()`. The log keeps at most 4,096 characters of each of the rerun's output streams, and `resolve()` returns all of it.
107
+
108
+ `approvals.pending()` and `approvals.resolve()` don't see an escalation: `machine.pending(session)` lists the ones that wait. It asks the quorum policy about each with the answers written so far and leaves out one the policy says has expired. Listing writes nothing, so an expired escalation stays in the log until it is answered, and `resolve()` then writes the policy's denial and runs nothing. A `granular` policy takes `granular`, a list of rules of the form `{ kind?, tool?, escalate }`. The first rule that matches the denial's kind and the tool decides, and a denial no rule matches goes back with no request. `escalation()` throws `invalid_escalation` for rules given with another policy, for a `granular` policy with none, and for approvals that `createApprovals()` did not make. A policy that can ask also needs a harness with a signer and a permission pipeline: without the signer it throws `approval_unavailable`, and without the pipeline `invalid_escalation`.
109
+
69
110
  ## The srt backend confines each command with Anthropic's OS sandbox
70
111
 
71
112
  `srtSandbox()` from `./sandbox/srt` runs each command under `srt`, Anthropic's sandbox runtime. It pins `@anthropic-ai/sandbox-runtime` 0.0.83 under the Apache-2.0 license. The package calls itself a "Beta Research Preview", and says its APIs and configuration formats may evolve (as of November 2026). `provision()` writes the settings file, so `./sandbox/srt` is the one place that knows that format.
@@ -12,3 +12,14 @@
12
12
  export declare function isPublicAddress(address: string): boolean;
13
13
  /** Whether `text` is an IPv4 or IPv6 address, as a host name that must not be looked up. */
14
14
  export declare function isAddressLiteral(text: string): boolean;
15
+ /**
16
+ * The IPv4 address `address` names, as a number: a dotted quad in its canonical form, or an IPv6 address that wraps
17
+ * one (the mapped, compatible, translated, NAT64 and 6to4 forms). `undefined` for anything else.
18
+ */
19
+ export declare function ipv4Of(address: string): number | undefined;
20
+ /**
21
+ * Whether `address` reaches the host itself or its link: unspecified, loopback or link-local (which holds the cloud
22
+ * metadata address 169.254.169.254), for IPv4 and IPv6, and an IPv6 address that wraps one of those IPv4 ones. Text
23
+ * that isn't an address literal is not one.
24
+ */
25
+ export declare function isLocalAddress(address: string): boolean;
@@ -73,12 +73,14 @@ function parseIpv6(text) {
73
73
  const missing = 8 - head.length - tail.length;
74
74
  return missing >= 1 ? [...head, ...new Array(missing).fill(0), ...tail] : undefined;
75
75
  }
76
- function ipv4Refused(value) {
77
- return IPV4_REFUSED.some(([base, bits]) => {
76
+ /** Whether `value` falls in one of `ranges`, each an `[address, prefix length]` pair. */
77
+ function inIpv4Ranges(value, ranges) {
78
+ return ranges.some(([base, bits]) => {
78
79
  const size = 2 ** (32 - bits);
79
80
  return Math.floor(value / size) === Math.floor(base / size);
80
81
  });
81
82
  }
83
+ const ipv4Refused = (value) => inIpv4Ranges(value, IPV4_REFUSED);
82
84
  /** The IPv6 prefixes a proxy refuses, as the leading groups and the prefix length in bits. */
83
85
  const IPV6_REFUSED = [
84
86
  [[0, 0, 0, 0, 0, 0, 0, 0], 128], // ::, unspecified
@@ -141,4 +143,41 @@ export function isAddressLiteral(text) {
141
143
  const bare = text.startsWith("[") && text.endsWith("]") ? text.slice(1, -1) : text;
142
144
  return parseIpv4(bare) !== undefined || parseIpv6(bare) !== undefined;
143
145
  }
146
+ const bareOf = (text) => (text.startsWith("[") && text.endsWith("]") ? text.slice(1, -1) : text);
147
+ /**
148
+ * The IPv4 address `address` names, as a number: a dotted quad in its canonical form, or an IPv6 address that wraps
149
+ * one (the mapped, compatible, translated, NAT64 and 6to4 forms). `undefined` for anything else.
150
+ */
151
+ export function ipv4Of(address) {
152
+ const bare = bareOf(address);
153
+ const v4 = parseIpv4(bare);
154
+ if (v4 !== undefined)
155
+ return v4;
156
+ const v6 = parseIpv6(bare);
157
+ return v6 === undefined ? undefined : wrappedIpv4(v6);
158
+ }
159
+ /** The IPv4 ranges that reach the host itself or its link: this network, loopback and link-local. */
160
+ const IPV4_LOCAL = [
161
+ [0x00000000, 8],
162
+ [0x7f000000, 8],
163
+ [0xa9fe0000, 16],
164
+ ];
165
+ /** The IPv6 prefixes that reach the host itself or its link: unspecified, loopback and link-local. */
166
+ const IPV6_LOCAL = [
167
+ [[0, 0, 0, 0, 0, 0, 0, 0], 128],
168
+ [[0, 0, 0, 0, 0, 0, 0, 1], 128],
169
+ [[0xfe80], 10],
170
+ ];
171
+ /**
172
+ * Whether `address` reaches the host itself or its link: unspecified, loopback or link-local (which holds the cloud
173
+ * metadata address 169.254.169.254), for IPv4 and IPv6, and an IPv6 address that wraps one of those IPv4 ones. Text
174
+ * that isn't an address literal is not one.
175
+ */
176
+ export function isLocalAddress(address) {
177
+ const v4 = ipv4Of(address);
178
+ if (v4 !== undefined && inIpv4Ranges(v4, IPV4_LOCAL))
179
+ return true;
180
+ const v6 = parseIpv6(bareOf(address));
181
+ return v6 !== undefined && IPV6_LOCAL.some(([prefix, bits]) => inPrefix(v6, prefix, bits));
182
+ }
144
183
  //# sourceMappingURL=addresses.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"addresses.js","sourceRoot":"","sources":["../../src/credentials/addresses.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which network addresses an egress proxy may connect to. It refuses every address that isn't a public one: loopback,\n * link-local (which holds the cloud metadata address 169.254.169.254), private, carrier-grade NAT, unspecified,\n * multicast and reserved ranges, for both IPv4 and IPv6, and an IPv6 address that wraps one of the refused IPv4 ones.\n * Names resolve to addresses in the proxy, and each address is checked here, so a name that points at the host's own\n * network is refused even when its name is allowed. It parses addresses itself and imports no Node module.\n */\n\n/** The IPv4 ranges a proxy refuses, as `[address, prefix length]`. */\nconst IPV4_REFUSED: readonly (readonly [number, number])[] = [\n [0x00000000, 8], // this network\n [0x0a000000, 8], // private\n [0x64400000, 10], // carrier-grade NAT, 100.64.0.0/10\n [0x7f000000, 8], // loopback\n [0xa9fe0000, 16], // link-local, which holds the metadata address\n [0xac100000, 12], // private\n [0xc0000000, 24], // IETF protocol assignments\n [0xc0000200, 24], // documentation\n [0xc0a80000, 16], // private\n [0xc6120000, 15], // benchmarking, 198.18.0.0/15\n [0xc6336400, 24], // documentation\n [0xcb007100, 24], // documentation\n [0xe0000000, 4], // multicast\n [0xf0000000, 4], // reserved, and the broadcast address\n];\n\n/** The four parts of an IPv4 address as one number, or `undefined` when `text` is not a dotted quad. */\nfunction parseIpv4(text: string): number | undefined {\n const parts = text.split(\".\");\n if (parts.length !== 4) return undefined;\n let value = 0;\n for (const part of parts) {\n if (!/^(0|[1-9][0-9]{0,2})$/.test(part)) return undefined;\n const octet = Number(part);\n if (octet > 255) return undefined;\n value = value * 256 + octet;\n }\n return value;\n}\n\n/** The 16-bit groups in one side of an IPv6 address, where the last piece may be a dotted IPv4 address. */\nfunction readGroups(side: string): number[] | undefined {\n if (side === \"\") return [];\n const groups: number[] = [];\n const pieces = side.split(\":\");\n for (const [index, piece] of pieces.entries()) {\n const v4 = index === pieces.length - 1 && piece.includes(\".\") ? parseIpv4(piece) : undefined;\n if (v4 !== undefined) {\n groups.push(Math.floor(v4 / 65536), v4 % 65536);\n } else if (/^[0-9a-fA-F]{1,4}$/.test(piece)) {\n groups.push(Number.parseInt(piece, 16));\n } else {\n return undefined;\n }\n }\n return groups;\n}\n\n/** The eight 16-bit groups of an IPv6 address, or `undefined` when `text` is not one. */\nfunction parseIpv6(text: string): number[] | undefined {\n const whole = text.split(\"%\")[0] ?? text;\n const doubles = whole.split(\"::\");\n if (doubles.length > 2) return undefined;\n const head = readGroups(doubles[0] ?? \"\");\n const tail = doubles.length === 2 ? readGroups(doubles[1] ?? \"\") : [];\n if (head === undefined || tail === undefined) return undefined;\n if (doubles.length === 1) return head.length === 8 ? head : undefined;\n const missing = 8 - head.length - tail.length;\n return missing >= 1 ? [...head, ...new Array<number>(missing).fill(0), ...tail] : undefined;\n}\n\nfunction ipv4Refused(value: number): boolean {\n return IPV4_REFUSED.some(([base, bits]) => {\n const size = 2 ** (32 - bits);\n return Math.floor(value / size) === Math.floor(base / size);\n });\n}\n\n/** The IPv6 prefixes a proxy refuses, as the leading groups and the prefix length in bits. */\nconst IPV6_REFUSED: readonly (readonly [readonly number[], number])[] = [\n [[0, 0, 0, 0, 0, 0, 0, 0], 128], // ::, unspecified\n [[0, 0, 0, 0, 0, 0, 0, 1], 128], // ::1, loopback\n [[0x64, 0xff9b, 1], 48], // 64:ff9b:1::/48, local-use NAT64\n [[0x100], 64], // 100::/64, discard-only\n [[0x2001, 0], 23], // 2001::/23: Teredo, benchmarking, ORCHID and protocol assignments\n [[0x2001, 0x0db8], 32], // documentation\n [[0x3fff], 20], // 3fff::/20, documentation\n [[0x5f00], 16], // segment routing SIDs\n [[0xfc00], 7], // unique local\n [[0xfe80], 10], // link-local\n [[0xfec0], 10], // site-local, deprecated\n [[0xff00], 8], // multicast\n];\n\n/** Whether the first `bits` bits of `groups` equal those of `prefix`. */\nfunction inPrefix(groups: readonly number[], prefix: readonly number[], bits: number): boolean {\n for (let index = 0; index * 16 < bits; index += 1) {\n const take = Math.min(16, bits - index * 16);\n const mask = (0xffff << (16 - take)) & 0xffff;\n if (((groups[index] ?? 0) & mask) !== ((prefix[index] ?? 0) & mask)) return false;\n }\n return true;\n}\n\n/** The IPv4 address an IPv6 one carries, as a number: mapped, compatible, translated, NAT64 and 6to4 forms. */\nfunction wrappedIpv4(groups: readonly number[]): number | undefined {\n const [a = 0, b = 0, c = 0, d = 0, e = 0, f = 0, g = 0, h = 0] = groups;\n const zeroHigh = a === 0 && b === 0 && c === 0 && d === 0;\n const low = g * 65536 + h;\n if (zeroHigh && e === 0 && (f === 0xffff || f === 0)) return low; // ::ffff:a.b.c.d and ::a.b.c.d\n if (zeroHigh && e === 0xffff && f === 0) return low; // ::ffff:0:a.b.c.d, IPv4-translated\n if (a === 0x64 && b === 0xff9b && c === 0 && d === 0 && e === 0 && f === 0) return low; // 64:ff9b::/96\n return a === 0x2002 ? b * 65536 + c : undefined; // 6to4 wraps the address in its next two groups\n}\n\n/** Whether an IPv6 address, as eight groups, is one a proxy refuses. */\nfunction ipv6Refused(groups: readonly number[]): boolean {\n const wrapped = wrappedIpv4(groups);\n if (wrapped !== undefined && ipv4Refused(wrapped)) return true;\n return IPV6_REFUSED.some(([prefix, bits]) => inPrefix(groups, prefix, bits));\n}\n\n/**\n * Whether `address` is a public one a proxy may connect to. Text that isn't an IPv4 or IPv6 address is not public, so a\n * resolver's odd answer is refused instead of passed on.\n */\nexport function isPublicAddress(address: string): boolean {\n const bare = address.startsWith(\"[\") && address.endsWith(\"]\") ? address.slice(1, -1) : address;\n const v4 = parseIpv4(bare);\n if (v4 !== undefined) return !ipv4Refused(v4);\n const v6 = parseIpv6(bare);\n return v6 !== undefined && !ipv6Refused(v6);\n}\n\n/** Whether `text` is an IPv4 or IPv6 address, as a host name that must not be looked up. */\nexport function isAddressLiteral(text: string): boolean {\n const bare = text.startsWith(\"[\") && text.endsWith(\"]\") ? text.slice(1, -1) : text;\n return parseIpv4(bare) !== undefined || parseIpv6(bare) !== undefined;\n}\n"]}
1
+ {"version":3,"file":"addresses.js","sourceRoot":"","sources":["../../src/credentials/addresses.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Which network addresses an egress proxy may connect to. It refuses every address that isn't a public one: loopback,\n * link-local (which holds the cloud metadata address 169.254.169.254), private, carrier-grade NAT, unspecified,\n * multicast and reserved ranges, for both IPv4 and IPv6, and an IPv6 address that wraps one of the refused IPv4 ones.\n * Names resolve to addresses in the proxy, and each address is checked here, so a name that points at the host's own\n * network is refused even when its name is allowed. It parses addresses itself and imports no Node module.\n */\n\n/** The IPv4 ranges a proxy refuses, as `[address, prefix length]`. */\nconst IPV4_REFUSED: readonly (readonly [number, number])[] = [\n [0x00000000, 8], // this network\n [0x0a000000, 8], // private\n [0x64400000, 10], // carrier-grade NAT, 100.64.0.0/10\n [0x7f000000, 8], // loopback\n [0xa9fe0000, 16], // link-local, which holds the metadata address\n [0xac100000, 12], // private\n [0xc0000000, 24], // IETF protocol assignments\n [0xc0000200, 24], // documentation\n [0xc0a80000, 16], // private\n [0xc6120000, 15], // benchmarking, 198.18.0.0/15\n [0xc6336400, 24], // documentation\n [0xcb007100, 24], // documentation\n [0xe0000000, 4], // multicast\n [0xf0000000, 4], // reserved, and the broadcast address\n];\n\n/** The four parts of an IPv4 address as one number, or `undefined` when `text` is not a dotted quad. */\nfunction parseIpv4(text: string): number | undefined {\n const parts = text.split(\".\");\n if (parts.length !== 4) return undefined;\n let value = 0;\n for (const part of parts) {\n if (!/^(0|[1-9][0-9]{0,2})$/.test(part)) return undefined;\n const octet = Number(part);\n if (octet > 255) return undefined;\n value = value * 256 + octet;\n }\n return value;\n}\n\n/** The 16-bit groups in one side of an IPv6 address, where the last piece may be a dotted IPv4 address. */\nfunction readGroups(side: string): number[] | undefined {\n if (side === \"\") return [];\n const groups: number[] = [];\n const pieces = side.split(\":\");\n for (const [index, piece] of pieces.entries()) {\n const v4 = index === pieces.length - 1 && piece.includes(\".\") ? parseIpv4(piece) : undefined;\n if (v4 !== undefined) {\n groups.push(Math.floor(v4 / 65536), v4 % 65536);\n } else if (/^[0-9a-fA-F]{1,4}$/.test(piece)) {\n groups.push(Number.parseInt(piece, 16));\n } else {\n return undefined;\n }\n }\n return groups;\n}\n\n/** The eight 16-bit groups of an IPv6 address, or `undefined` when `text` is not one. */\nfunction parseIpv6(text: string): number[] | undefined {\n const whole = text.split(\"%\")[0] ?? text;\n const doubles = whole.split(\"::\");\n if (doubles.length > 2) return undefined;\n const head = readGroups(doubles[0] ?? \"\");\n const tail = doubles.length === 2 ? readGroups(doubles[1] ?? \"\") : [];\n if (head === undefined || tail === undefined) return undefined;\n if (doubles.length === 1) return head.length === 8 ? head : undefined;\n const missing = 8 - head.length - tail.length;\n return missing >= 1 ? [...head, ...new Array<number>(missing).fill(0), ...tail] : undefined;\n}\n\n/** Whether `value` falls in one of `ranges`, each an `[address, prefix length]` pair. */\nfunction inIpv4Ranges(value: number, ranges: readonly (readonly [number, number])[]): boolean {\n return ranges.some(([base, bits]) => {\n const size = 2 ** (32 - bits);\n return Math.floor(value / size) === Math.floor(base / size);\n });\n}\n\nconst ipv4Refused = (value: number): boolean => inIpv4Ranges(value, IPV4_REFUSED);\n\n/** The IPv6 prefixes a proxy refuses, as the leading groups and the prefix length in bits. */\nconst IPV6_REFUSED: readonly (readonly [readonly number[], number])[] = [\n [[0, 0, 0, 0, 0, 0, 0, 0], 128], // ::, unspecified\n [[0, 0, 0, 0, 0, 0, 0, 1], 128], // ::1, loopback\n [[0x64, 0xff9b, 1], 48], // 64:ff9b:1::/48, local-use NAT64\n [[0x100], 64], // 100::/64, discard-only\n [[0x2001, 0], 23], // 2001::/23: Teredo, benchmarking, ORCHID and protocol assignments\n [[0x2001, 0x0db8], 32], // documentation\n [[0x3fff], 20], // 3fff::/20, documentation\n [[0x5f00], 16], // segment routing SIDs\n [[0xfc00], 7], // unique local\n [[0xfe80], 10], // link-local\n [[0xfec0], 10], // site-local, deprecated\n [[0xff00], 8], // multicast\n];\n\n/** Whether the first `bits` bits of `groups` equal those of `prefix`. */\nfunction inPrefix(groups: readonly number[], prefix: readonly number[], bits: number): boolean {\n for (let index = 0; index * 16 < bits; index += 1) {\n const take = Math.min(16, bits - index * 16);\n const mask = (0xffff << (16 - take)) & 0xffff;\n if (((groups[index] ?? 0) & mask) !== ((prefix[index] ?? 0) & mask)) return false;\n }\n return true;\n}\n\n/** The IPv4 address an IPv6 one carries, as a number: mapped, compatible, translated, NAT64 and 6to4 forms. */\nfunction wrappedIpv4(groups: readonly number[]): number | undefined {\n const [a = 0, b = 0, c = 0, d = 0, e = 0, f = 0, g = 0, h = 0] = groups;\n const zeroHigh = a === 0 && b === 0 && c === 0 && d === 0;\n const low = g * 65536 + h;\n if (zeroHigh && e === 0 && (f === 0xffff || f === 0)) return low; // ::ffff:a.b.c.d and ::a.b.c.d\n if (zeroHigh && e === 0xffff && f === 0) return low; // ::ffff:0:a.b.c.d, IPv4-translated\n if (a === 0x64 && b === 0xff9b && c === 0 && d === 0 && e === 0 && f === 0) return low; // 64:ff9b::/96\n return a === 0x2002 ? b * 65536 + c : undefined; // 6to4 wraps the address in its next two groups\n}\n\n/** Whether an IPv6 address, as eight groups, is one a proxy refuses. */\nfunction ipv6Refused(groups: readonly number[]): boolean {\n const wrapped = wrappedIpv4(groups);\n if (wrapped !== undefined && ipv4Refused(wrapped)) return true;\n return IPV6_REFUSED.some(([prefix, bits]) => inPrefix(groups, prefix, bits));\n}\n\n/**\n * Whether `address` is a public one a proxy may connect to. Text that isn't an IPv4 or IPv6 address is not public, so a\n * resolver's odd answer is refused instead of passed on.\n */\nexport function isPublicAddress(address: string): boolean {\n const bare = address.startsWith(\"[\") && address.endsWith(\"]\") ? address.slice(1, -1) : address;\n const v4 = parseIpv4(bare);\n if (v4 !== undefined) return !ipv4Refused(v4);\n const v6 = parseIpv6(bare);\n return v6 !== undefined && !ipv6Refused(v6);\n}\n\n/** Whether `text` is an IPv4 or IPv6 address, as a host name that must not be looked up. */\nexport function isAddressLiteral(text: string): boolean {\n const bare = text.startsWith(\"[\") && text.endsWith(\"]\") ? text.slice(1, -1) : text;\n return parseIpv4(bare) !== undefined || parseIpv6(bare) !== undefined;\n}\n\nconst bareOf = (text: string): string => (text.startsWith(\"[\") && text.endsWith(\"]\") ? text.slice(1, -1) : text);\n\n/**\n * The IPv4 address `address` names, as a number: a dotted quad in its canonical form, or an IPv6 address that wraps\n * one (the mapped, compatible, translated, NAT64 and 6to4 forms). `undefined` for anything else.\n */\nexport function ipv4Of(address: string): number | undefined {\n const bare = bareOf(address);\n const v4 = parseIpv4(bare);\n if (v4 !== undefined) return v4;\n const v6 = parseIpv6(bare);\n return v6 === undefined ? undefined : wrappedIpv4(v6);\n}\n\n/** The IPv4 ranges that reach the host itself or its link: this network, loopback and link-local. */\nconst IPV4_LOCAL: readonly (readonly [number, number])[] = [\n [0x00000000, 8],\n [0x7f000000, 8],\n [0xa9fe0000, 16],\n];\n\n/** The IPv6 prefixes that reach the host itself or its link: unspecified, loopback and link-local. */\nconst IPV6_LOCAL: readonly (readonly [readonly number[], number])[] = [\n [[0, 0, 0, 0, 0, 0, 0, 0], 128],\n [[0, 0, 0, 0, 0, 0, 0, 1], 128],\n [[0xfe80], 10],\n];\n\n/**\n * Whether `address` reaches the host itself or its link: unspecified, loopback or link-local (which holds the cloud\n * metadata address 169.254.169.254), for IPv4 and IPv6, and an IPv6 address that wraps one of those IPv4 ones. Text\n * that isn't an address literal is not one.\n */\nexport function isLocalAddress(address: string): boolean {\n const v4 = ipv4Of(address);\n if (v4 !== undefined && inIpv4Ranges(v4, IPV4_LOCAL)) return true;\n const v6 = parseIpv6(bareOf(address));\n return v6 !== undefined && IPV6_LOCAL.some(([prefix, bits]) => inPrefix(v6, prefix, bits));\n}\n"]}
package/dist/errors.d.ts CHANGED
@@ -4,7 +4,7 @@
4
4
  * `SandboxDeniedError`, `SandboxPolicyMismatchError` and `SandboxUnsupportedError`, all in `./sandbox`.
5
5
  */
6
6
  /** Why a `HarnessError` was thrown. */
7
- export type HarnessErrorCode = "sandbox_unavailable" | "sandbox_denied" | "sandbox_disposed" | "sandbox_not_found" | "sandbox_io_failed" | "sandbox_policy_mismatch" | "sandbox_unsupported" | "egress_denied" | "invalid_egress_options" | "unsafe_sandbox_not_acknowledged" | "invalid_sandbox_options" | "invalid_spawn_env" | "duplicate_tool" | "invalid_tool_registration" | "invalid_tool_options" | "invalid_permission_config" | "invalid_lock_options" | "session_locked" | "session_read_only" | "entry_not_found" | "unsupported_format" | "invalid_turn_options" | "invalid_context_options" | "invalid_dispatcher_options" | "invalid_transport_options" | "spill_unavailable" | "invalid_extension" | "extension_hash_mismatch" | "approval_not_pending" | "approval_unavailable" | "sticky_refused" | "approval_reuse_refused" | "approver_is_requester" | "approval_refused" | "invalid_code_call" | "invalid_key_store" | "key_store_read_only" | "session_conflict" | "entry_too_large" | "invalid_session_entry" | "invalid_session_key" | "invalid_retention" | "session_corrupt" | "invalid_completion_config" | "invalid_mcp_config" | "mcp_connect_failed" | "mcp_tool_list_refused" | "mcp_call_failed";
7
+ export type HarnessErrorCode = "sandbox_unavailable" | "sandbox_denied" | "sandbox_disposed" | "sandbox_not_found" | "sandbox_io_failed" | "sandbox_policy_mismatch" | "sandbox_unsupported" | "egress_denied" | "invalid_egress_options" | "unsafe_sandbox_not_acknowledged" | "invalid_sandbox_options" | "invalid_spawn_env" | "duplicate_tool" | "invalid_tool_registration" | "invalid_tool_options" | "invalid_permission_config" | "invalid_lock_options" | "session_locked" | "session_read_only" | "entry_not_found" | "unsupported_format" | "invalid_turn_options" | "invalid_context_options" | "invalid_dispatcher_options" | "invalid_transport_options" | "spill_unavailable" | "invalid_extension" | "extension_hash_mismatch" | "approval_not_pending" | "approval_unavailable" | "sticky_refused" | "approval_reuse_refused" | "approver_is_requester" | "approval_refused" | "invalid_code_call" | "invalid_escalation" | "invalid_key_store" | "key_store_read_only" | "session_conflict" | "entry_too_large" | "invalid_session_entry" | "invalid_session_key" | "invalid_retention" | "session_corrupt" | "invalid_completion_config" | "invalid_mcp_config" | "mcp_connect_failed" | "mcp_tool_list_refused" | "mcp_call_failed";
8
8
  /**
9
9
  * Thrown for a mistake in how the harness is called, and for a sandbox that is unavailable or refuses a file operation.
10
10
  * `sandbox_unavailable`: a backend can't start (`SandboxUnavailableError`). `sandbox_denied`: the policy refused a file
@@ -34,9 +34,12 @@ export type HarnessErrorCode = "sandbox_unavailable" | "sandbox_denied" | "sandb
34
34
  * `approval_unavailable`: the harness has no signer, so no approval can be checked. `sticky_refused`: a sticky
35
35
  * allowance would cover an interpreter prefix or a secret. `approval_reuse_refused`: the tool's `approvalReuse` forbids
36
36
  * a sticky or grouped answer. `approver_is_requester`: the approver is the one who asked. `approval_refused`: a code
37
- * call's signed request failed its check when it was resolved, so nothing ran and nothing was written.
37
+ * call's or a sandbox escalation's signed request failed its check when it was resolved, or a classifier tried to
38
+ * approve an escalation, so nothing ran and nothing was written.
38
39
  * `invalid_code_call`: `Harness.invokeTool()` or a code call's resolution was given something it can't run, such as a
39
- * tool the registry lacks or a compensation that names no call that ran. `invalid_key_store`: a key
40
+ * tool the registry lacks or a compensation that names no call that ran. `invalid_escalation`: `escalation()` or one
41
+ * of its calls was given something it can't use, such as a granular policy with no rules, or an edge the escalation
42
+ * table does not list. `invalid_key_store`: a key
40
43
  * file or key secret is unreadable or malformed, or a key file is readable by others. `key_store_read_only`: a key store
41
44
  * with no `rotate()` or `prune()` was asked to rotate or prune. `session_conflict`: an append found the log in a state it did
42
45
  * not expect (`ConflictError`). `entry_too_large`: an entry is over the store's size bound (`EntryTooLargeError`).
package/dist/errors.js CHANGED
@@ -34,9 +34,12 @@ const HARNESS_ERROR = Symbol.for("buildanagent.harness.HarnessError");
34
34
  * `approval_unavailable`: the harness has no signer, so no approval can be checked. `sticky_refused`: a sticky
35
35
  * allowance would cover an interpreter prefix or a secret. `approval_reuse_refused`: the tool's `approvalReuse` forbids
36
36
  * a sticky or grouped answer. `approver_is_requester`: the approver is the one who asked. `approval_refused`: a code
37
- * call's signed request failed its check when it was resolved, so nothing ran and nothing was written.
37
+ * call's or a sandbox escalation's signed request failed its check when it was resolved, or a classifier tried to
38
+ * approve an escalation, so nothing ran and nothing was written.
38
39
  * `invalid_code_call`: `Harness.invokeTool()` or a code call's resolution was given something it can't run, such as a
39
- * tool the registry lacks or a compensation that names no call that ran. `invalid_key_store`: a key
40
+ * tool the registry lacks or a compensation that names no call that ran. `invalid_escalation`: `escalation()` or one
41
+ * of its calls was given something it can't use, such as a granular policy with no rules, or an edge the escalation
42
+ * table does not list. `invalid_key_store`: a key
40
43
  * file or key secret is unreadable or malformed, or a key file is readable by others. `key_store_read_only`: a key store
41
44
  * with no `rotate()` or `prune()` was asked to rotate or prune. `session_conflict`: an append found the log in a state it did
42
45
  * not expect (`ConflictError`). `entry_too_large`: an entry is over the store's size bound (`EntryTooLargeError`).
@@ -1 +1 @@
1
- {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqDH,4FAA4F;AAC5F,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACnB,IAAI,GAAW,cAAc,CAAC;IACvC,IAAI,CAAmB;IAEhC,YAAY,IAAsB,EAAE,OAAe,EAAE,OAAsB;QACzE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAAiC,CAAC,aAAa,CAAC,KAAK,IAAI,CAAC;AACnH,CAAC","sourcesContent":["/**\n * `HarnessError`: the harness's error for programmer errors and for a sandbox that can't do what it was asked. Four\n * subclasses keep their own names for the cases callers catch by class: `SandboxUnavailableError`,\n * `SandboxDeniedError`, `SandboxPolicyMismatchError` and `SandboxUnsupportedError`, all in `./sandbox`.\n */\n\n/** Why a `HarnessError` was thrown. */\nexport type HarnessErrorCode =\n | \"sandbox_unavailable\"\n | \"sandbox_denied\"\n | \"sandbox_disposed\"\n | \"sandbox_not_found\"\n | \"sandbox_io_failed\"\n | \"sandbox_policy_mismatch\"\n | \"sandbox_unsupported\"\n | \"egress_denied\"\n | \"invalid_egress_options\"\n | \"unsafe_sandbox_not_acknowledged\"\n | \"invalid_sandbox_options\"\n | \"invalid_spawn_env\"\n | \"duplicate_tool\"\n | \"invalid_tool_registration\"\n | \"invalid_tool_options\"\n | \"invalid_permission_config\"\n | \"invalid_lock_options\"\n | \"session_locked\"\n | \"session_read_only\"\n | \"entry_not_found\"\n | \"unsupported_format\"\n | \"invalid_turn_options\"\n | \"invalid_context_options\"\n | \"invalid_dispatcher_options\"\n | \"invalid_transport_options\"\n | \"spill_unavailable\"\n | \"invalid_extension\"\n | \"extension_hash_mismatch\"\n | \"approval_not_pending\"\n | \"approval_unavailable\"\n | \"sticky_refused\"\n | \"approval_reuse_refused\"\n | \"approver_is_requester\"\n | \"approval_refused\"\n | \"invalid_code_call\"\n | \"invalid_key_store\"\n | \"key_store_read_only\"\n | \"session_conflict\"\n | \"entry_too_large\"\n | \"invalid_session_entry\"\n | \"invalid_session_key\"\n | \"invalid_retention\"\n | \"session_corrupt\"\n | \"invalid_completion_config\"\n | \"invalid_mcp_config\"\n | \"mcp_connect_failed\"\n | \"mcp_tool_list_refused\"\n | \"mcp_call_failed\";\n\n// A registered symbol, so the guard still works when two copies of the package are bundled.\nconst HARNESS_ERROR = Symbol.for(\"buildanagent.harness.HarnessError\");\n\n/**\n * Thrown for a mistake in how the harness is called, and for a sandbox that is unavailable or refuses a file operation.\n * `sandbox_unavailable`: a backend can't start (`SandboxUnavailableError`). `sandbox_denied`: the policy refused a file\n * read or write (`SandboxDeniedError`). `sandbox_disposed`: the sandbox was disposed before the call.\n * `sandbox_not_found`: a file to read doesn't exist. `sandbox_io_failed`: a file call failed for a reason that is\n * neither a missing file nor a denial. `sandbox_policy_mismatch`: the policy a backend read back after it provisioned or\n * resumed a sandbox differs from the one requested (`SandboxPolicyMismatchError`). `sandbox_unsupported`: a sandbox was\n * asked to resume, snapshot or pause on a backend that lacks the capability (`SandboxUnsupportedError`).\n * `unsafe_sandbox_not_acknowledged`: `noneSandbox()` was called without `unsafe:\n * true`. `invalid_sandbox_options`: a sandbox option, manifest or command is unusable. `invalid_spawn_env`:\n * `spawnEnv()` was given a name or value that can't be part of a clean environment. `duplicate_tool`: a tool registry\n * already holds a tool or alias by that name (`DuplicateToolError`). `invalid_tool_registration`: a tool registration\n * or a registry option is unusable, such as a name that breaks the canonical rule or an unknown source.\n * `invalid_tool_options`: the built-in tools were given a workspace root or a policy root that is not an absolute path.\n * `invalid_permission_config`: an allow rule makes the host callback unreachable (`PermissionConfigError`).\n * `invalid_lock_options`: a file lock was given a lease, renewal interval or host name it can't use. `session_locked`:\n * another writer holds the session. `session_read_only`: a session opened without a lock was asked to write.\n * `entry_not_found`: an entry id is in no file of the session. `unsupported_format`: a session file's format can't be\n * read or migrated, its header names none, or the store can't read it as written. `invalid_turn_options`: a turn's\n * options can't be used, such as a tool allowlist that names a tool the registry lacks, or a hook that changed the\n * model inside a turn.\n * `invalid_context_options`: a context policy's setting can't be used, such as a write cap with no spill store or a mask\n * step of zero. `invalid_dispatcher_options`: a dispatcher's setting can't be used, such as a queue size of zero.\n * `invalid_transport_options`: a transport's setting can't be used, such as a write timeout of zero.\n * `spill_unavailable`: a spill store can't write, such as the file store on a runtime without Node's file\n * system. `invalid_extension`: an extension has no name or version, two share a name, or a project extension's module does not export one. `extension_hash_mismatch`: a project extension's files hash differently from the lock file, or the lock file does not list it. `approval_not_pending`: a resolution names a request that is not waiting.\n * `approval_unavailable`: the harness has no signer, so no approval can be checked. `sticky_refused`: a sticky\n * allowance would cover an interpreter prefix or a secret. `approval_reuse_refused`: the tool's `approvalReuse` forbids\n * a sticky or grouped answer. `approver_is_requester`: the approver is the one who asked. `approval_refused`: a code\n * call's signed request failed its check when it was resolved, so nothing ran and nothing was written.\n * `invalid_code_call`: `Harness.invokeTool()` or a code call's resolution was given something it can't run, such as a\n * tool the registry lacks or a compensation that names no call that ran. `invalid_key_store`: a key\n * file or key secret is unreadable or malformed, or a key file is readable by others. `key_store_read_only`: a key store\n * with no `rotate()` or `prune()` was asked to rotate or prune. `session_conflict`: an append found the log in a state it did\n * not expect (`ConflictError`). `entry_too_large`: an entry is over the store's size bound (`EntryTooLargeError`).\n * `invalid_session_entry`: an entry is not valid or is out of place, such as a first entry that is not a header.\n * `invalid_session_key`: a user or session id the store can't use. `invalid_retention`: a retention period that is not a\n * positive number, or an action other than `archive` and `purge`. `session_corrupt`: a log file has a bad line before\n * its last line. `invalid_completion_config`: `.agents/harness.json` is not JSON, or its `completionChecks` is not a list\n * of commands. `invalid_mcp_config`: an MCP server's configuration can't be used, such as a name outside the allowed\n * characters or two servers with one name. `mcp_connect_failed`: an MCP server did not start, did not finish the\n * handshake in time, or closed before it did (`McpError`). `mcp_tool_list_refused`: an MCP server listed tools the\n * harness refuses, such as two with one name, so none of its tools was registered (`McpError`). `mcp_call_failed`: an\n * MCP tool call ended without a result, because the server closed, timed out, asked for input or answered with an\n * error (`McpError`).\n */\nexport class HarnessError extends Error {\n override readonly name: string = \"HarnessError\";\n readonly code: HarnessErrorCode;\n\n constructor(code: HarnessErrorCode, message: string, options?: ErrorOptions) {\n super(message, options);\n this.code = code;\n Object.defineProperty(this, HARNESS_ERROR, { value: true });\n }\n}\n\n/** True for a `HarnessError`, including one from another copy of the package. */\nexport function isHarnessError(error: unknown): error is HarnessError {\n return typeof error === \"object\" && error !== null && (error as Record<symbol, unknown>)[HARNESS_ERROR] === true;\n}\n"]}
1
+ {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAsDH,4FAA4F;AAC5F,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACnB,IAAI,GAAW,cAAc,CAAC;IACvC,IAAI,CAAmB;IAEhC,YAAY,IAAsB,EAAE,OAAe,EAAE,OAAsB;QACzE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9D,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAAiC,CAAC,aAAa,CAAC,KAAK,IAAI,CAAC;AACnH,CAAC","sourcesContent":["/**\n * `HarnessError`: the harness's error for programmer errors and for a sandbox that can't do what it was asked. Four\n * subclasses keep their own names for the cases callers catch by class: `SandboxUnavailableError`,\n * `SandboxDeniedError`, `SandboxPolicyMismatchError` and `SandboxUnsupportedError`, all in `./sandbox`.\n */\n\n/** Why a `HarnessError` was thrown. */\nexport type HarnessErrorCode =\n | \"sandbox_unavailable\"\n | \"sandbox_denied\"\n | \"sandbox_disposed\"\n | \"sandbox_not_found\"\n | \"sandbox_io_failed\"\n | \"sandbox_policy_mismatch\"\n | \"sandbox_unsupported\"\n | \"egress_denied\"\n | \"invalid_egress_options\"\n | \"unsafe_sandbox_not_acknowledged\"\n | \"invalid_sandbox_options\"\n | \"invalid_spawn_env\"\n | \"duplicate_tool\"\n | \"invalid_tool_registration\"\n | \"invalid_tool_options\"\n | \"invalid_permission_config\"\n | \"invalid_lock_options\"\n | \"session_locked\"\n | \"session_read_only\"\n | \"entry_not_found\"\n | \"unsupported_format\"\n | \"invalid_turn_options\"\n | \"invalid_context_options\"\n | \"invalid_dispatcher_options\"\n | \"invalid_transport_options\"\n | \"spill_unavailable\"\n | \"invalid_extension\"\n | \"extension_hash_mismatch\"\n | \"approval_not_pending\"\n | \"approval_unavailable\"\n | \"sticky_refused\"\n | \"approval_reuse_refused\"\n | \"approver_is_requester\"\n | \"approval_refused\"\n | \"invalid_code_call\"\n | \"invalid_escalation\"\n | \"invalid_key_store\"\n | \"key_store_read_only\"\n | \"session_conflict\"\n | \"entry_too_large\"\n | \"invalid_session_entry\"\n | \"invalid_session_key\"\n | \"invalid_retention\"\n | \"session_corrupt\"\n | \"invalid_completion_config\"\n | \"invalid_mcp_config\"\n | \"mcp_connect_failed\"\n | \"mcp_tool_list_refused\"\n | \"mcp_call_failed\";\n\n// A registered symbol, so the guard still works when two copies of the package are bundled.\nconst HARNESS_ERROR = Symbol.for(\"buildanagent.harness.HarnessError\");\n\n/**\n * Thrown for a mistake in how the harness is called, and for a sandbox that is unavailable or refuses a file operation.\n * `sandbox_unavailable`: a backend can't start (`SandboxUnavailableError`). `sandbox_denied`: the policy refused a file\n * read or write (`SandboxDeniedError`). `sandbox_disposed`: the sandbox was disposed before the call.\n * `sandbox_not_found`: a file to read doesn't exist. `sandbox_io_failed`: a file call failed for a reason that is\n * neither a missing file nor a denial. `sandbox_policy_mismatch`: the policy a backend read back after it provisioned or\n * resumed a sandbox differs from the one requested (`SandboxPolicyMismatchError`). `sandbox_unsupported`: a sandbox was\n * asked to resume, snapshot or pause on a backend that lacks the capability (`SandboxUnsupportedError`).\n * `unsafe_sandbox_not_acknowledged`: `noneSandbox()` was called without `unsafe:\n * true`. `invalid_sandbox_options`: a sandbox option, manifest or command is unusable. `invalid_spawn_env`:\n * `spawnEnv()` was given a name or value that can't be part of a clean environment. `duplicate_tool`: a tool registry\n * already holds a tool or alias by that name (`DuplicateToolError`). `invalid_tool_registration`: a tool registration\n * or a registry option is unusable, such as a name that breaks the canonical rule or an unknown source.\n * `invalid_tool_options`: the built-in tools were given a workspace root or a policy root that is not an absolute path.\n * `invalid_permission_config`: an allow rule makes the host callback unreachable (`PermissionConfigError`).\n * `invalid_lock_options`: a file lock was given a lease, renewal interval or host name it can't use. `session_locked`:\n * another writer holds the session. `session_read_only`: a session opened without a lock was asked to write.\n * `entry_not_found`: an entry id is in no file of the session. `unsupported_format`: a session file's format can't be\n * read or migrated, its header names none, or the store can't read it as written. `invalid_turn_options`: a turn's\n * options can't be used, such as a tool allowlist that names a tool the registry lacks, or a hook that changed the\n * model inside a turn.\n * `invalid_context_options`: a context policy's setting can't be used, such as a write cap with no spill store or a mask\n * step of zero. `invalid_dispatcher_options`: a dispatcher's setting can't be used, such as a queue size of zero.\n * `invalid_transport_options`: a transport's setting can't be used, such as a write timeout of zero.\n * `spill_unavailable`: a spill store can't write, such as the file store on a runtime without Node's file\n * system. `invalid_extension`: an extension has no name or version, two share a name, or a project extension's module does not export one. `extension_hash_mismatch`: a project extension's files hash differently from the lock file, or the lock file does not list it. `approval_not_pending`: a resolution names a request that is not waiting.\n * `approval_unavailable`: the harness has no signer, so no approval can be checked. `sticky_refused`: a sticky\n * allowance would cover an interpreter prefix or a secret. `approval_reuse_refused`: the tool's `approvalReuse` forbids\n * a sticky or grouped answer. `approver_is_requester`: the approver is the one who asked. `approval_refused`: a code\n * call's or a sandbox escalation's signed request failed its check when it was resolved, or a classifier tried to\n * approve an escalation, so nothing ran and nothing was written.\n * `invalid_code_call`: `Harness.invokeTool()` or a code call's resolution was given something it can't run, such as a\n * tool the registry lacks or a compensation that names no call that ran. `invalid_escalation`: `escalation()` or one\n * of its calls was given something it can't use, such as a granular policy with no rules, or an edge the escalation\n * table does not list. `invalid_key_store`: a key\n * file or key secret is unreadable or malformed, or a key file is readable by others. `key_store_read_only`: a key store\n * with no `rotate()` or `prune()` was asked to rotate or prune. `session_conflict`: an append found the log in a state it did\n * not expect (`ConflictError`). `entry_too_large`: an entry is over the store's size bound (`EntryTooLargeError`).\n * `invalid_session_entry`: an entry is not valid or is out of place, such as a first entry that is not a header.\n * `invalid_session_key`: a user or session id the store can't use. `invalid_retention`: a retention period that is not a\n * positive number, or an action other than `archive` and `purge`. `session_corrupt`: a log file has a bad line before\n * its last line. `invalid_completion_config`: `.agents/harness.json` is not JSON, or its `completionChecks` is not a list\n * of commands. `invalid_mcp_config`: an MCP server's configuration can't be used, such as a name outside the allowed\n * characters or two servers with one name. `mcp_connect_failed`: an MCP server did not start, did not finish the\n * handshake in time, or closed before it did (`McpError`). `mcp_tool_list_refused`: an MCP server listed tools the\n * harness refuses, such as two with one name, so none of its tools was registered (`McpError`). `mcp_call_failed`: an\n * MCP tool call ended without a result, because the server closed, timed out, asked for input or answered with an\n * error (`McpError`).\n */\nexport class HarnessError extends Error {\n override readonly name: string = \"HarnessError\";\n readonly code: HarnessErrorCode;\n\n constructor(code: HarnessErrorCode, message: string, options?: ErrorOptions) {\n super(message, options);\n this.code = code;\n Object.defineProperty(this, HARNESS_ERROR, { value: true });\n }\n}\n\n/** True for a `HarnessError`, including one from another copy of the package. */\nexport function isHarnessError(error: unknown): error is HarnessError {\n return typeof error === \"object\" && error !== null && (error as Record<symbol, unknown>)[HARNESS_ERROR] === true;\n}\n"]}
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Where a sandboxed command stands. `sandboxed`: it runs under the host's policy. `denied`: the backend refused it.
3
+ * `requested`: a signed request for a person waits in the log. `approved`: a signed allow verified. `rerun`: the
4
+ * command runs once more under the policy widened by exactly the denial. `done`: the caller has its result.
5
+ */
6
+ export type EscalationState = "sandboxed" | "denied" | "requested" | "approved" | "rerun" | "done";
7
+ /**
8
+ * What moves a command between states. `ran`: the command finished without a denial, or the rerun finished.
9
+ * `denied`: the backend returned a `SandboxDenial`. `returned`: the denial goes back to the caller with no request.
10
+ * `asked`: a signed request was written. `waiting`: an answer the quorum policy still waits on. `allowed`: a signed
11
+ * allow verified and the quorum policy is met. `refused`: a deny, a quorum refusal or expiry, or the permission
12
+ * pipeline's deny. `started`: the pipeline's fresh decision is not a deny, so the rerun starts. `settled`: a crash
13
+ * left the command open, and its result is written without running it.
14
+ */
15
+ export type EscalationEvent = "ran" | "denied" | "returned" | "asked" | "waiting" | "allowed" | "refused" | "started" | "settled";
16
+ /** One legal edge: from a state, on an event, to a state, and when the machine takes it. */
17
+ export interface EscalationTransition {
18
+ /** The state the edge leaves. */
19
+ readonly from: EscalationState;
20
+ /** What moves the command along the edge. */
21
+ readonly event: EscalationEvent;
22
+ /** The state the edge enters. */
23
+ readonly to: EscalationState;
24
+ /** When the machine takes this edge, in a sentence. */
25
+ readonly when: string;
26
+ }
27
+ /** Every state, in the order a command that escalates passes through them. */
28
+ export declare const ESCALATION_STATES: readonly EscalationState[];
29
+ /** Every event. */
30
+ export declare const ESCALATION_EVENTS: readonly EscalationEvent[];
31
+ /**
32
+ * The legal edges. Any pair of a state and an event not listed is illegal. Only `allowed` enters `approved`, only from
33
+ * `requested`, and only `started` enters `rerun`, only from `approved`, so no path reaches a rerun without a verified
34
+ * allow. `rerun` leads only to `done`: a second denial is the rerun's result, never a new request.
35
+ */
36
+ export declare const ESCALATION_TRANSITIONS: readonly EscalationTransition[];
37
+ /** The state `event` moves `from` to. Throws `invalid_escalation` for an edge the table does not list. */
38
+ export declare function nextEscalationState(from: EscalationState, event: EscalationEvent): EscalationState;
@@ -0,0 +1,95 @@
1
+ /**
2
+ * The escalation state machine as data: the states a sandboxed command passes through after a denial, the events that
3
+ * move it, and the one table of legal edges. `escalation()` moves only through `nextEscalationState()`, so a test of
4
+ * the table is a test of every move the machine can make.
5
+ */
6
+ import { HarnessError } from "../errors.js";
7
+ /** Every state, in the order a command that escalates passes through them. */
8
+ export const ESCALATION_STATES = Object.freeze([
9
+ "sandboxed",
10
+ "denied",
11
+ "requested",
12
+ "approved",
13
+ "rerun",
14
+ "done",
15
+ ]);
16
+ /** Every event. */
17
+ export const ESCALATION_EVENTS = Object.freeze([
18
+ "ran",
19
+ "denied",
20
+ "returned",
21
+ "asked",
22
+ "waiting",
23
+ "allowed",
24
+ "refused",
25
+ "started",
26
+ "settled",
27
+ ]);
28
+ /**
29
+ * The legal edges. Any pair of a state and an event not listed is illegal. Only `allowed` enters `approved`, only from
30
+ * `requested`, and only `started` enters `rerun`, only from `approved`, so no path reaches a rerun without a verified
31
+ * allow. `rerun` leads only to `done`: a second denial is the rerun's result, never a new request.
32
+ */
33
+ export const ESCALATION_TRANSITIONS = Object.freeze([
34
+ { from: "sandboxed", event: "ran", to: "done", when: "the command finished under the host's policy" },
35
+ { from: "sandboxed", event: "denied", to: "denied", when: "the backend returned a denial" },
36
+ {
37
+ from: "denied",
38
+ event: "returned",
39
+ to: "done",
40
+ when: "the approval policy, its granular rule or the denial itself rules out a request",
41
+ },
42
+ {
43
+ from: "denied",
44
+ event: "asked",
45
+ to: "requested",
46
+ when: "the policy allows a request and the denial names one path or host to widen; the signed request is written",
47
+ },
48
+ { from: "requested", event: "waiting", to: "requested", when: "the quorum policy waits for more answers" },
49
+ {
50
+ from: "requested",
51
+ event: "allowed",
52
+ to: "approved",
53
+ when: "a signed allow from a person or a hook verified, and the quorum policy is met",
54
+ },
55
+ {
56
+ from: "requested",
57
+ event: "refused",
58
+ to: "done",
59
+ when: "a deny, or the quorum policy rejected the request or let it expire",
60
+ },
61
+ {
62
+ from: "requested",
63
+ event: "settled",
64
+ to: "done",
65
+ when: "a crash left an answered request before its rerun started, so it never ran",
66
+ },
67
+ { from: "approved", event: "refused", to: "done", when: "the permission pipeline now denies the call" },
68
+ {
69
+ from: "approved",
70
+ event: "started",
71
+ to: "rerun",
72
+ when: "the pipeline's fresh decision is not a deny; its entry is the last one before the rerun",
73
+ },
74
+ {
75
+ from: "rerun",
76
+ event: "ran",
77
+ to: "done",
78
+ when: "the rerun finished once under the widened policy, a second denial included",
79
+ },
80
+ {
81
+ from: "rerun",
82
+ event: "settled",
83
+ to: "done",
84
+ when: "a crash left a started rerun with no result, so it may have run and never runs again",
85
+ },
86
+ ].map((edge) => Object.freeze(edge)));
87
+ /** The state `event` moves `from` to. Throws `invalid_escalation` for an edge the table does not list. */
88
+ export function nextEscalationState(from, event) {
89
+ const edge = ESCALATION_TRANSITIONS.find((transition) => transition.from === from && transition.event === event);
90
+ if (edge === undefined) {
91
+ throw new HarnessError("invalid_escalation", `an escalation can't move from ${from} on ${event}`);
92
+ }
93
+ return edge.to;
94
+ }
95
+ //# sourceMappingURL=escalation-table.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"escalation-table.js","sourceRoot":"","sources":["../../src/sandbox/escalation-table.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The escalation state machine as data: the states a sandboxed command passes through after a denial, the events that\n * move it, and the one table of legal edges. `escalation()` moves only through `nextEscalationState()`, so a test of\n * the table is a test of every move the machine can make.\n */\nimport { HarnessError } from \"../errors.js\";\n\n/**\n * Where a sandboxed command stands. `sandboxed`: it runs under the host's policy. `denied`: the backend refused it.\n * `requested`: a signed request for a person waits in the log. `approved`: a signed allow verified. `rerun`: the\n * command runs once more under the policy widened by exactly the denial. `done`: the caller has its result.\n */\nexport type EscalationState = \"sandboxed\" | \"denied\" | \"requested\" | \"approved\" | \"rerun\" | \"done\";\n\n/**\n * What moves a command between states. `ran`: the command finished without a denial, or the rerun finished.\n * `denied`: the backend returned a `SandboxDenial`. `returned`: the denial goes back to the caller with no request.\n * `asked`: a signed request was written. `waiting`: an answer the quorum policy still waits on. `allowed`: a signed\n * allow verified and the quorum policy is met. `refused`: a deny, a quorum refusal or expiry, or the permission\n * pipeline's deny. `started`: the pipeline's fresh decision is not a deny, so the rerun starts. `settled`: a crash\n * left the command open, and its result is written without running it.\n */\nexport type EscalationEvent =\n | \"ran\"\n | \"denied\"\n | \"returned\"\n | \"asked\"\n | \"waiting\"\n | \"allowed\"\n | \"refused\"\n | \"started\"\n | \"settled\";\n\n/** One legal edge: from a state, on an event, to a state, and when the machine takes it. */\nexport interface EscalationTransition {\n /** The state the edge leaves. */\n readonly from: EscalationState;\n /** What moves the command along the edge. */\n readonly event: EscalationEvent;\n /** The state the edge enters. */\n readonly to: EscalationState;\n /** When the machine takes this edge, in a sentence. */\n readonly when: string;\n}\n\n/** Every state, in the order a command that escalates passes through them. */\nexport const ESCALATION_STATES: readonly EscalationState[] = Object.freeze([\n \"sandboxed\",\n \"denied\",\n \"requested\",\n \"approved\",\n \"rerun\",\n \"done\",\n]);\n\n/** Every event. */\nexport const ESCALATION_EVENTS: readonly EscalationEvent[] = Object.freeze([\n \"ran\",\n \"denied\",\n \"returned\",\n \"asked\",\n \"waiting\",\n \"allowed\",\n \"refused\",\n \"started\",\n \"settled\",\n]);\n\n/**\n * The legal edges. Any pair of a state and an event not listed is illegal. Only `allowed` enters `approved`, only from\n * `requested`, and only `started` enters `rerun`, only from `approved`, so no path reaches a rerun without a verified\n * allow. `rerun` leads only to `done`: a second denial is the rerun's result, never a new request.\n */\nexport const ESCALATION_TRANSITIONS: readonly EscalationTransition[] = Object.freeze(\n [\n { from: \"sandboxed\", event: \"ran\", to: \"done\", when: \"the command finished under the host's policy\" },\n { from: \"sandboxed\", event: \"denied\", to: \"denied\", when: \"the backend returned a denial\" },\n {\n from: \"denied\",\n event: \"returned\",\n to: \"done\",\n when: \"the approval policy, its granular rule or the denial itself rules out a request\",\n },\n {\n from: \"denied\",\n event: \"asked\",\n to: \"requested\",\n when: \"the policy allows a request and the denial names one path or host to widen; the signed request is written\",\n },\n { from: \"requested\", event: \"waiting\", to: \"requested\", when: \"the quorum policy waits for more answers\" },\n {\n from: \"requested\",\n event: \"allowed\",\n to: \"approved\",\n when: \"a signed allow from a person or a hook verified, and the quorum policy is met\",\n },\n {\n from: \"requested\",\n event: \"refused\",\n to: \"done\",\n when: \"a deny, or the quorum policy rejected the request or let it expire\",\n },\n {\n from: \"requested\",\n event: \"settled\",\n to: \"done\",\n when: \"a crash left an answered request before its rerun started, so it never ran\",\n },\n { from: \"approved\", event: \"refused\", to: \"done\", when: \"the permission pipeline now denies the call\" },\n {\n from: \"approved\",\n event: \"started\",\n to: \"rerun\",\n when: \"the pipeline's fresh decision is not a deny; its entry is the last one before the rerun\",\n },\n {\n from: \"rerun\",\n event: \"ran\",\n to: \"done\",\n when: \"the rerun finished once under the widened policy, a second denial included\",\n },\n {\n from: \"rerun\",\n event: \"settled\",\n to: \"done\",\n when: \"a crash left a started rerun with no result, so it may have run and never runs again\",\n },\n ].map((edge) => Object.freeze(edge)) as EscalationTransition[],\n);\n\n/** The state `event` moves `from` to. Throws `invalid_escalation` for an edge the table does not list. */\nexport function nextEscalationState(from: EscalationState, event: EscalationEvent): EscalationState {\n const edge = ESCALATION_TRANSITIONS.find((transition) => transition.from === from && transition.event === event);\n if (edge === undefined) {\n throw new HarnessError(\"invalid_escalation\", `an escalation can't move from ${from} on ${event}`);\n }\n return edge.to;\n}\n"]}