@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.
- package/README.md +152 -5
- package/dist/context/file-spill.d.ts +11 -1
- package/dist/context/file-spill.js +23 -8
- package/dist/context/file-spill.js.map +1 -1
- package/dist/context/spill.d.ts +5 -1
- package/dist/context/spill.js +6 -2
- package/dist/context/spill.js.map +1 -1
- package/dist/credentials/addresses.d.ts +11 -0
- package/dist/credentials/addresses.js +41 -2
- package/dist/credentials/addresses.js.map +1 -1
- package/dist/credentials/allowlist.d.ts +22 -2
- package/dist/credentials/allowlist.js +74 -17
- package/dist/credentials/allowlist.js.map +1 -1
- package/dist/credentials/egress-policy.d.ts +69 -0
- package/dist/credentials/egress-policy.js +170 -0
- package/dist/credentials/egress-policy.js.map +1 -0
- package/dist/credentials/egress-proxy.d.ts +13 -1
- package/dist/credentials/egress-proxy.js +179 -11
- package/dist/credentials/egress-proxy.js.map +1 -1
- package/dist/credentials/git-route.d.ts +68 -0
- package/dist/credentials/git-route.js +288 -0
- package/dist/credentials/git-route.js.map +1 -0
- package/dist/credentials/index.d.ts +5 -1
- package/dist/credentials/index.js +5 -1
- package/dist/credentials/index.js.map +1 -1
- package/dist/credentials/scrub.d.ts +7 -0
- package/dist/credentials/scrub.js +22 -0
- package/dist/credentials/scrub.js.map +1 -1
- package/dist/errors.d.ts +14 -7
- package/dist/errors.js +13 -6
- package/dist/errors.js.map +1 -1
- package/dist/sandbox/base.d.ts +11 -1
- package/dist/sandbox/base.js +14 -0
- package/dist/sandbox/base.js.map +1 -1
- package/dist/sandbox/docker/index.d.ts +8 -2
- package/dist/sandbox/docker/index.js +63 -14
- package/dist/sandbox/docker/index.js.map +1 -1
- package/dist/sandbox/errors.d.ts +30 -2
- package/dist/sandbox/errors.js +36 -1
- package/dist/sandbox/errors.js.map +1 -1
- package/dist/sandbox/escalation-table.d.ts +38 -0
- package/dist/sandbox/escalation-table.js +95 -0
- package/dist/sandbox/escalation-table.js.map +1 -0
- package/dist/sandbox/escalation.d.ts +191 -0
- package/dist/sandbox/escalation.js +370 -0
- package/dist/sandbox/escalation.js.map +1 -0
- package/dist/sandbox/host-files.d.ts +2 -0
- package/dist/sandbox/host-files.js +10 -0
- package/dist/sandbox/host-files.js.map +1 -1
- package/dist/sandbox/index.d.ts +9 -4
- package/dist/sandbox/index.js +8 -3
- package/dist/sandbox/index.js.map +1 -1
- package/dist/sandbox/policy.d.ts +49 -0
- package/dist/sandbox/policy.js +149 -0
- package/dist/sandbox/policy.js.map +1 -0
- package/dist/sandbox/process.js +1 -1
- package/dist/sandbox/process.js.map +1 -1
- package/dist/sandbox/srt/index.d.ts +5 -2
- package/dist/sandbox/srt/index.js +27 -8
- package/dist/sandbox/srt/index.js.map +1 -1
- package/dist/sandbox/srt/settings.d.ts +17 -5
- package/dist/sandbox/srt/settings.js +53 -0
- package/dist/sandbox/srt/settings.js.map +1 -1
- package/dist/sandbox/types.d.ts +41 -4
- package/dist/sandbox/types.js.map +1 -1
- package/dist/sandbox/widen.d.ts +10 -0
- package/dist/sandbox/widen.js +150 -0
- package/dist/sandbox/widen.js.map +1 -0
- package/dist/session/approvals.d.ts +30 -1
- package/dist/session/approvals.js +12 -4
- package/dist/session/approvals.js.map +1 -1
- package/dist/session/code-call.d.ts +15 -1
- package/dist/session/code-call.js +2 -1
- package/dist/session/code-call.js.map +1 -1
- package/dist/session/escalation-log.d.ts +65 -0
- package/dist/session/escalation-log.js +84 -0
- package/dist/session/escalation-log.js.map +1 -0
- package/dist/session/rebuild.js +12 -3
- package/dist/session/rebuild.js.map +1 -1
- package/dist/testing/fake-sandbox.d.ts +21 -3
- package/dist/testing/fake-sandbox.js +157 -8
- package/dist/testing/fake-sandbox.js.map +1 -1
- package/dist/testing/sandbox-conformance.js +108 -1
- package/dist/testing/sandbox-conformance.js.map +1 -1
- package/dist/tools/builtins/bash.d.ts +9 -0
- package/dist/tools/builtins/bash.js +75 -0
- package/dist/tools/builtins/bash.js.map +1 -0
- package/dist/tools/builtins/builtins.d.ts +38 -0
- package/dist/tools/builtins/builtins.js +48 -0
- package/dist/tools/builtins/builtins.js.map +1 -0
- package/dist/tools/builtins/descriptions.d.ts +69 -0
- package/dist/tools/builtins/descriptions.js +94 -0
- package/dist/tools/builtins/descriptions.js.map +1 -0
- package/dist/tools/builtins/fetch.d.ts +12 -0
- package/dist/tools/builtins/fetch.js +157 -0
- package/dist/tools/builtins/fetch.js.map +1 -0
- package/dist/tools/builtins/files.d.ts +27 -0
- package/dist/tools/builtins/files.js +274 -0
- package/dist/tools/builtins/files.js.map +1 -0
- package/dist/tools/builtins/paths.d.ts +30 -0
- package/dist/tools/builtins/paths.js +62 -0
- package/dist/tools/builtins/paths.js.map +1 -0
- package/dist/tools/builtins/results.d.ts +15 -0
- package/dist/tools/builtins/results.js +31 -0
- package/dist/tools/builtins/results.js.map +1 -0
- package/dist/tools/builtins/search.d.ts +18 -0
- package/dist/tools/builtins/search.js +217 -0
- package/dist/tools/builtins/search.js.map +1 -0
- package/dist/tools/index.d.ts +6 -2
- package/dist/tools/index.js +5 -2
- package/dist/tools/index.js.map +1 -1
- package/llms.txt +52 -0
- package/package.json +5 -5
package/dist/sandbox/errors.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
/** The sandbox's
|
|
1
|
+
/** The sandbox's four named errors, each a `HarnessError` with its own code and its own fields. */
|
|
2
2
|
import { HarnessError } from "../errors.js";
|
|
3
3
|
/** Thrown by `provision()` when a backend can't start, such as a missing binary. The host must not run unconfined. */
|
|
4
4
|
export class SandboxUnavailableError extends HarnessError {
|
|
@@ -19,4 +19,39 @@ export class SandboxDeniedError extends HarnessError {
|
|
|
19
19
|
this.denial = denial;
|
|
20
20
|
}
|
|
21
21
|
}
|
|
22
|
+
/**
|
|
23
|
+
* Thrown when the policy a backend read back from what it applied differs from the policy it was asked for, after
|
|
24
|
+
* `provision()` or a resume. After `provision()` the sandbox is disposed before the error is thrown, so nothing runs
|
|
25
|
+
* under the wrong policy; after `resumeSandbox()` it is left to the caller, who decides whether to dispose it. `field`
|
|
26
|
+
* names the first field that differs, such as `network.allow`. The message names only the field and, for `stops`, the
|
|
27
|
+
* cause, never a path or host from either policy.
|
|
28
|
+
*/
|
|
29
|
+
export class SandboxPolicyMismatchError extends HarnessError {
|
|
30
|
+
name = "SandboxPolicyMismatchError";
|
|
31
|
+
/**
|
|
32
|
+
* What differs: `readRoots`, `writeRoots`, `network.allow` or `network.deny` for the first field that differs;
|
|
33
|
+
* `stops` when the applied policy can't deliver a stop the backend claims; `readBack` when a backend that claims a
|
|
34
|
+
* stop has no read-back or its read-back fails; and `settings` when a settings file isn't in the shape its backend
|
|
35
|
+
* writes.
|
|
36
|
+
*/
|
|
37
|
+
field;
|
|
38
|
+
/** `options.reason` says why a claimed stop isn't delivered, and must not hold a path or host of either policy. */
|
|
39
|
+
constructor(field, options) {
|
|
40
|
+
const { reason, ...rest } = options ?? {};
|
|
41
|
+
super("sandbox_policy_mismatch", reason === undefined
|
|
42
|
+
? `the sandbox applied a policy that differs from the one requested, in ${field}`
|
|
43
|
+
: `the sandbox can't deliver the ${field} its backend claims: ${reason}`, rest);
|
|
44
|
+
this.field = field;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
/** Thrown by `resumeSandbox()`, `snapshotSandbox()` and `pauseSandbox()` for a capability the backend doesn't list. */
|
|
48
|
+
export class SandboxUnsupportedError extends HarnessError {
|
|
49
|
+
name = "SandboxUnsupportedError";
|
|
50
|
+
/** The capability that was asked for. */
|
|
51
|
+
capability;
|
|
52
|
+
constructor(capability, tier) {
|
|
53
|
+
super("sandbox_unsupported", `this ${tier}-tier sandbox backend can't ${capability}`);
|
|
54
|
+
this.capability = capability;
|
|
55
|
+
}
|
|
56
|
+
}
|
|
22
57
|
//# sourceMappingURL=errors.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/sandbox/errors.ts"],"names":[],"mappings":"AAAA,
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/sandbox/errors.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAG5C,sHAAsH;AACtH,MAAM,OAAO,uBAAwB,SAAQ,YAAY;IACrC,IAAI,GAAG,yBAAyB,CAAC;IACnD,sDAAsD;IAC7C,OAAO,CAAS;IAEzB,YAAY,OAAe,EAAE,MAAc,EAAE,OAAsB;QACjE,KAAK,CAAC,qBAAqB,EAAE,OAAO,OAAO,4BAA4B,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;QAC1F,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,gHAAgH;AAChH,MAAM,OAAO,kBAAmB,SAAQ,YAAY;IAChC,IAAI,GAAG,oBAAoB,CAAC;IACrC,MAAM,CAAgB;IAE/B,YAAY,MAAqB;QAC/B,KAAK,CACH,gBAAgB,EAChB,wBAAwB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,OAAO,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAC9F,CAAC;QACF,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,0BAA2B,SAAQ,YAAY;IACxC,IAAI,GAAG,4BAA4B,CAAC;IACtD;;;;;OAKG;IACM,KAAK,CAAS;IAEvB,mHAAmH;IACnH,YAAY,KAAa,EAAE,OAAqD;QAC9E,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QAC1C,KAAK,CACH,yBAAyB,EACzB,MAAM,KAAK,SAAS;YAClB,CAAC,CAAC,wEAAwE,KAAK,EAAE;YACjF,CAAC,CAAC,iCAAiC,KAAK,wBAAwB,MAAM,EAAE,EAC1E,IAAI,CACL,CAAC;QACF,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED,uHAAuH;AACvH,MAAM,OAAO,uBAAwB,SAAQ,YAAY;IACrC,IAAI,GAAG,yBAAyB,CAAC;IACnD,yCAAyC;IAChC,UAAU,CAAoB;IAEvC,YAAY,UAA6B,EAAE,IAAY;QACrD,KAAK,CAAC,qBAAqB,EAAE,QAAQ,IAAI,+BAA+B,UAAU,EAAE,CAAC,CAAC;QACtF,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF","sourcesContent":["/** The sandbox's four named errors, each a `HarnessError` with its own code and its own fields. */\nimport { HarnessError } from \"../errors.js\";\nimport type { SandboxCapability, SandboxDenial } from \"./types.js\";\n\n/** Thrown by `provision()` when a backend can't start, such as a missing binary. The host must not run unconfined. */\nexport class SandboxUnavailableError extends HarnessError {\n override readonly name = \"SandboxUnavailableError\";\n /** The backend that is unavailable, such as `srt`. */\n readonly backend: string;\n\n constructor(backend: string, reason: string, options?: ErrorOptions) {\n super(\"sandbox_unavailable\", `the ${backend} sandbox is unavailable: ${reason}`, options);\n this.backend = backend;\n }\n}\n\n/** Thrown when the policy refuses a file read or write. A command's denial is an `ExecResult`, not an error. */\nexport class SandboxDeniedError extends HarnessError {\n override readonly name = \"SandboxDeniedError\";\n readonly denial: SandboxDenial;\n\n constructor(denial: SandboxDenial) {\n super(\n \"sandbox_denied\",\n `the sandbox denied a ${denial.kind.replace(\"_\", \" \")} of ${denial.target}: ${denial.reason}`,\n );\n this.denial = denial;\n }\n}\n\n/**\n * Thrown when the policy a backend read back from what it applied differs from the policy it was asked for, after\n * `provision()` or a resume. After `provision()` the sandbox is disposed before the error is thrown, so nothing runs\n * under the wrong policy; after `resumeSandbox()` it is left to the caller, who decides whether to dispose it. `field`\n * names the first field that differs, such as `network.allow`. The message names only the field and, for `stops`, the\n * cause, never a path or host from either policy.\n */\nexport class SandboxPolicyMismatchError extends HarnessError {\n override readonly name = \"SandboxPolicyMismatchError\";\n /**\n * What differs: `readRoots`, `writeRoots`, `network.allow` or `network.deny` for the first field that differs;\n * `stops` when the applied policy can't deliver a stop the backend claims; `readBack` when a backend that claims a\n * stop has no read-back or its read-back fails; and `settings` when a settings file isn't in the shape its backend\n * writes.\n */\n readonly field: string;\n\n /** `options.reason` says why a claimed stop isn't delivered, and must not hold a path or host of either policy. */\n constructor(field: string, options?: ErrorOptions & { readonly reason?: string }) {\n const { reason, ...rest } = options ?? {};\n super(\n \"sandbox_policy_mismatch\",\n reason === undefined\n ? `the sandbox applied a policy that differs from the one requested, in ${field}`\n : `the sandbox can't deliver the ${field} its backend claims: ${reason}`,\n rest,\n );\n this.field = field;\n }\n}\n\n/** Thrown by `resumeSandbox()`, `snapshotSandbox()` and `pauseSandbox()` for a capability the backend doesn't list. */\nexport class SandboxUnsupportedError extends HarnessError {\n override readonly name = \"SandboxUnsupportedError\";\n /** The capability that was asked for. */\n readonly capability: SandboxCapability;\n\n constructor(capability: SandboxCapability, tier: string) {\n super(\"sandbox_unsupported\", `this ${tier}-tier sandbox backend can't ${capability}`);\n this.capability = capability;\n }\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"]}
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `escalation()`: what the host does when a sandbox denies a command. Under `never` the denial goes back to the caller
|
|
3
|
+
* and nothing is written. Under `on-request`, and under `granular` where a rule allows it, the denial becomes a signed
|
|
4
|
+
* `approval_requested` entry, and once a person or a hook allows it, the command runs once more under the policy
|
|
5
|
+
* widened by exactly what the denial named. The widened policy is built here, on the host, from the signed record and
|
|
6
|
+
* the verified answer; no tool input or model output reaches it, and it lasts for that one rerun.
|
|
7
|
+
*/
|
|
8
|
+
import { type Resolution, type SignedPendingRequest, type ToolResult } from "@buildanagent/sdk";
|
|
9
|
+
import type { Clock } from "@buildanagent/sdk/testing";
|
|
10
|
+
import { type Approvals } from "../session/approvals.js";
|
|
11
|
+
import { type EscalationRecord } from "../session/escalation-log.js";
|
|
12
|
+
import type { Session } from "../session/session.js";
|
|
13
|
+
import { type EscalationState, type EscalationTransition } from "./escalation-table.js";
|
|
14
|
+
import type { ApprovalPolicy, ExecResult, Sandbox, SandboxClient, SandboxDenial, SandboxPolicy, WorkspaceManifest } from "./types.js";
|
|
15
|
+
/**
|
|
16
|
+
* One rule of a `granular` policy: a denial of `kind` for `tool` may be asked about (`on-request`) or goes back to the
|
|
17
|
+
* caller (`never`). A rule with no `kind` or no `tool` matches every kind or every tool. The first rule that matches
|
|
18
|
+
* decides, and a denial no rule matches goes back to the caller.
|
|
19
|
+
*/
|
|
20
|
+
export interface EscalationRule {
|
|
21
|
+
/** The kind of denial the rule covers. Left out, every kind. */
|
|
22
|
+
readonly kind?: SandboxDenial["kind"];
|
|
23
|
+
/** A tool's canonical name or alias, as the registry knows it. */
|
|
24
|
+
readonly tool?: string;
|
|
25
|
+
/** Whether a matching denial may become a request. */
|
|
26
|
+
readonly escalate: "on-request" | "never";
|
|
27
|
+
}
|
|
28
|
+
/** The options of `escalation()`. */
|
|
29
|
+
export interface EscalationOptions<H = unknown> {
|
|
30
|
+
/** When a denial may become a request: `on-request`, `granular` (by `granular`'s rules) or `never`. */
|
|
31
|
+
readonly approvalPolicy: ApprovalPolicy;
|
|
32
|
+
/**
|
|
33
|
+
* The approvals from `createApprovals()`. The escalation signs with their harness's signer, decides the rerun with
|
|
34
|
+
* their harness's permission pipeline, and lets their quorum policy decide each answer.
|
|
35
|
+
*/
|
|
36
|
+
readonly approvals: Approvals<H>;
|
|
37
|
+
/** The rules a `granular` policy needs, and that any other policy refuses. */
|
|
38
|
+
readonly granular?: readonly EscalationRule[];
|
|
39
|
+
}
|
|
40
|
+
/** One command to run in a sandbox, for one tool call, and what the host provisions the sandbox with. */
|
|
41
|
+
export interface EscalationRun<H = unknown> {
|
|
42
|
+
/** The tool the command runs for, which the permission pipeline decides again before a rerun. */
|
|
43
|
+
readonly tool: string;
|
|
44
|
+
/** That tool call's input, as the pipeline sees it. It is recorded, so it needs a canonical JSON form. */
|
|
45
|
+
readonly input: unknown;
|
|
46
|
+
/** Who chose the call. Default `model`. */
|
|
47
|
+
readonly initiator?: "model" | "code";
|
|
48
|
+
/** The tool call's own id, recorded for the approver to see. */
|
|
49
|
+
readonly toolCallId?: string;
|
|
50
|
+
/** The executable and its arguments, with no shell. */
|
|
51
|
+
readonly command: readonly string[];
|
|
52
|
+
/** The working directory, relative to the workspace root. */
|
|
53
|
+
readonly cwd?: string;
|
|
54
|
+
/** Stops the command, and its rerun, after this long, as `Sandbox.exec()` does. */
|
|
55
|
+
readonly timeoutMs?: number;
|
|
56
|
+
/** The most bytes of each output stream to keep, as `Sandbox.exec()` does. */
|
|
57
|
+
readonly maxOutputBytes?: number;
|
|
58
|
+
/** The command's whole environment, from `spawnEnv()`. It is never recorded. */
|
|
59
|
+
readonly env: Readonly<Record<string, string>>;
|
|
60
|
+
/** Aborts the command. */
|
|
61
|
+
readonly signal: AbortSignal;
|
|
62
|
+
/** The backend `run()` provisions from when it is given no `sandbox`. */
|
|
63
|
+
readonly client: SandboxClient;
|
|
64
|
+
/** The workspace. Its root is recorded, and a rerun needs the same root. */
|
|
65
|
+
readonly manifest: WorkspaceManifest;
|
|
66
|
+
/** The policy the command runs under. It is recorded, and a rerun widens this record of it. */
|
|
67
|
+
readonly policy: SandboxPolicy;
|
|
68
|
+
/** A sandbox already provisioned with `policy`. Left out, `run()` provisions one and disposes it. */
|
|
69
|
+
readonly sandbox?: Sandbox;
|
|
70
|
+
/** The caller's identity. A request binds a MAC of it, so only the same value can resolve it. */
|
|
71
|
+
readonly hostContext?: H;
|
|
72
|
+
/** The clock of the entries and the signed request. Default the system clock. */
|
|
73
|
+
readonly clock?: Clock;
|
|
74
|
+
/** Makes the escalation's id and the ids of its entries and request. Default `crypto.randomUUID()`. */
|
|
75
|
+
readonly newId?: () => string;
|
|
76
|
+
}
|
|
77
|
+
/** The options of `EscalationMachine.resolve()`: where the rerun runs, which the log does not hold. */
|
|
78
|
+
export interface EscalationResolveOptions<H = unknown> {
|
|
79
|
+
/** The backend the rerun provisions a fresh sandbox from. */
|
|
80
|
+
readonly client: SandboxClient;
|
|
81
|
+
/** The workspace, whose root must be the recorded one. */
|
|
82
|
+
readonly manifest: WorkspaceManifest;
|
|
83
|
+
/** The rerun's whole environment, from `spawnEnv()`. */
|
|
84
|
+
readonly env: Readonly<Record<string, string>>;
|
|
85
|
+
/**
|
|
86
|
+
* Aborts the call and its rerun. A signal aborted when `resolve()` is called writes nothing. One aborted later, but
|
|
87
|
+
* before the answer is written, writes no answer and runs nothing, so the request still waits. One aborted after the
|
|
88
|
+
* answer is written only reaches the rerun, as `Sandbox.exec()` takes a signal, and the approval is spent.
|
|
89
|
+
*/
|
|
90
|
+
readonly signal: AbortSignal;
|
|
91
|
+
/** The same host context the request was made with, when it bound one. */
|
|
92
|
+
readonly hostContext?: H;
|
|
93
|
+
/** Who asked. An approver equal to it is refused. */
|
|
94
|
+
readonly requesterId?: string;
|
|
95
|
+
/** The clock of the entries. Default the system clock. */
|
|
96
|
+
readonly clock?: Clock;
|
|
97
|
+
/** Makes the ids of the entries. Default `crypto.randomUUID()`. */
|
|
98
|
+
readonly newId?: () => string;
|
|
99
|
+
}
|
|
100
|
+
/**
|
|
101
|
+
* How an escalation call ended. `states` is the path it took through the transition table in this call. `result` is a
|
|
102
|
+
* tool result a tool can return to the model: the command's output, or why it did not run. The model reads it only
|
|
103
|
+
* when nothing was written, as under `never`; once a request exists, the rebuilt context leaves it out and the host
|
|
104
|
+
* reads it.
|
|
105
|
+
*
|
|
106
|
+
* - `ran`: the command finished without a denial. `rerun` is true when it was the approved rerun.
|
|
107
|
+
* - `denied`: the command did not run to an end the caller can use: a denial that went back with no request, a refused
|
|
108
|
+
* answer, the pipeline's deny, or a second denial on the rerun.
|
|
109
|
+
* - `awaiting_approval`: `pending` waits for an answer through `resolve()`. `widened` is the policy the rerun would get.
|
|
110
|
+
*
|
|
111
|
+
* `escalationId` names the escalation once it has a request; a denial that went back with no request has none.
|
|
112
|
+
* `denial` is what the backend refused, and `reason` is the sentence `result` carries.
|
|
113
|
+
*/
|
|
114
|
+
export type EscalationResult = {
|
|
115
|
+
readonly status: "ran";
|
|
116
|
+
readonly exec: Extract<ExecResult, {
|
|
117
|
+
exitCode: number;
|
|
118
|
+
}>;
|
|
119
|
+
readonly rerun: boolean;
|
|
120
|
+
readonly escalationId?: string;
|
|
121
|
+
readonly states: readonly EscalationState[];
|
|
122
|
+
readonly result: ToolResult<unknown>;
|
|
123
|
+
} | {
|
|
124
|
+
readonly status: "denied";
|
|
125
|
+
readonly reason: string;
|
|
126
|
+
readonly denial?: SandboxDenial;
|
|
127
|
+
readonly rerun: boolean;
|
|
128
|
+
readonly escalationId?: string;
|
|
129
|
+
readonly states: readonly EscalationState[];
|
|
130
|
+
readonly result: ToolResult<unknown>;
|
|
131
|
+
} | {
|
|
132
|
+
readonly status: "awaiting_approval";
|
|
133
|
+
readonly escalationId: string;
|
|
134
|
+
readonly pending: SignedPendingRequest;
|
|
135
|
+
readonly denial: SandboxDenial;
|
|
136
|
+
readonly widened: SandboxPolicy;
|
|
137
|
+
readonly states: readonly EscalationState[];
|
|
138
|
+
readonly result: ToolResult<unknown>;
|
|
139
|
+
};
|
|
140
|
+
/** An escalation that waits for an answer: its id, its signed request and the record the request signs. */
|
|
141
|
+
export interface PendingEscalation {
|
|
142
|
+
/** The escalation's id, which its request names as its call id. */
|
|
143
|
+
readonly escalationId: string;
|
|
144
|
+
/** The signed request, to show the approver with the record. */
|
|
145
|
+
readonly request: SignedPendingRequest;
|
|
146
|
+
/** What the request signs: the tool and its input, the command, the workspace root, the policy and the denial. */
|
|
147
|
+
readonly record: EscalationRecord;
|
|
148
|
+
}
|
|
149
|
+
/** The machine `escalation()` returns. */
|
|
150
|
+
export interface EscalationMachine<H = unknown> {
|
|
151
|
+
/** The approval policy the machine was made with. */
|
|
152
|
+
readonly approvalPolicy: ApprovalPolicy;
|
|
153
|
+
/** The table every move follows. */
|
|
154
|
+
readonly transitions: readonly EscalationTransition[];
|
|
155
|
+
/**
|
|
156
|
+
* Runs a command in the sandbox. A command the backend does not deny ends `ran`, and nothing is written. A denial
|
|
157
|
+
* ends `denied`, with nothing written, unless the policy allows a request and the denial names one path or host that
|
|
158
|
+
* can be widened; then a signed `approval_requested` entry is written and the call ends `awaiting_approval`.
|
|
159
|
+
*
|
|
160
|
+
* Writing a request appends to the session, so under `on-request` and `granular` call it from host code outside a
|
|
161
|
+
* turn's tool step, as `invokeTool()` runs. Throws `invalid_escalation` for an input or host context with no
|
|
162
|
+
* canonical JSON form, before anything is written.
|
|
163
|
+
*/
|
|
164
|
+
run(session: Session, run: EscalationRun<H>): Promise<EscalationResult>;
|
|
165
|
+
/**
|
|
166
|
+
* The escalations of the session that wait for an answer. The quorum policy is asked about each one with the answers
|
|
167
|
+
* written so far, and one it says has expired is left out. Listing writes nothing, so such an escalation stays in the
|
|
168
|
+
* log until it is answered: `resolve()` then writes the policy's denial, and it never reruns.
|
|
169
|
+
*/
|
|
170
|
+
pending(session: Session): Promise<PendingEscalation[]>;
|
|
171
|
+
/**
|
|
172
|
+
* Answers one waiting escalation. The answer is checked before anything is written: the signature under a key in the
|
|
173
|
+
* ring, the bound host context, the call and the record. An allow must name its approver in `by`, and a classifier's
|
|
174
|
+
* allow (`by: "classifier:…"`) never approves a rerun; both are refused with nothing written. `by` is not covered by
|
|
175
|
+
* the request's signature, so the host sets it only after it has authenticated the approver. The answer is written,
|
|
176
|
+
* the quorum policy decides the answer, and an allow then goes through the permission pipeline again, so a deny rule
|
|
177
|
+
* added since the pause wins. The rerun runs once in a fresh sandbox under the recorded policy widened by exactly the
|
|
178
|
+
* recorded denial, and that sandbox is disposed after it. A second denial is the rerun's result.
|
|
179
|
+
*
|
|
180
|
+
* It first settles every escalation a crash left open: a rerun that started and has no result is never run again.
|
|
181
|
+
* Throws `approval_not_pending` for a request that does not wait, `approval_refused` for one that fails its check, an
|
|
182
|
+
* allow with no `by` or a classifier's allow, `approver_is_requester`, and `invalid_escalation` for a workspace with
|
|
183
|
+
* another root.
|
|
184
|
+
*/
|
|
185
|
+
resolve(session: Session, resolution: Resolution, options: EscalationResolveOptions<H>): Promise<EscalationResult>;
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* Creates the escalation machine for a harness's approvals. Throws `invalid_escalation` for unusable options, and
|
|
189
|
+
* `approval_unavailable` when a policy that can ask has a harness with no signer.
|
|
190
|
+
*/
|
|
191
|
+
export declare function escalation<H = unknown>(options: EscalationOptions<H>): EscalationMachine<H>;
|