@ygrishajev/jig 0.0.0-stage → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +135 -2
- package/dist/adapters/find-symlink.js +23 -0
- package/dist/adapters/git/git-workspace.js +297 -0
- package/dist/adapters/local-store/credentials-file.js +51 -0
- package/dist/adapters/local-store/local-run-store.js +45 -0
- package/dist/adapters/local-store/local-state.js +12 -0
- package/dist/adapters/local-store/metrics-log.js +119 -0
- package/dist/adapters/local-store/run-artefacts.js +76 -0
- package/dist/adapters/local-store/run-lock.js +51 -0
- package/dist/adapters/local-store/run-paths.js +49 -0
- package/dist/adapters/logging/create-logger.js +29 -0
- package/dist/adapters/run-store/composite-run-store.js +57 -0
- package/dist/adapters/run-store/git-remote-run-store.js +239 -0
- package/dist/adapters/sandbox-image/docker-images.js +93 -0
- package/dist/adapters/sandbox-image/image-recipe.js +96 -0
- package/dist/adapters/sandbox-image/latest-agent-versions.js +9 -0
- package/dist/adapters/sandcastle/agents.js +100 -0
- package/dist/adapters/sandcastle/codex-auth.js +191 -0
- package/dist/adapters/sandcastle/git-hooks.js +20 -0
- package/dist/adapters/sandcastle/open-session.js +67 -0
- package/dist/adapters/sandcastle/private-clone-docker.js +232 -0
- package/dist/adapters/sandcastle/sandcastle-env.js +17 -0
- package/dist/adapters/sandcastle/sandcastle-session.js +338 -0
- package/dist/adapters/sandcastle/structured-output.js +35 -0
- package/dist/adapters/sandcastle/usage.js +65 -0
- package/dist/adapters/telemetry/open-telemetry.js +29 -0
- package/dist/adapters/terminal/ask-for-agents.js +61 -0
- package/dist/adapters/terminal/ask-for-credential.js +32 -0
- package/dist/adapters/terminal/ask-for-preset.js +15 -0
- package/dist/adapters/terminal/standard-input.js +7 -0
- package/dist/adapters/terminal/terminal.js +45 -0
- package/dist/app/container.js +131 -0
- package/dist/app/init-sandbox.js +185 -0
- package/dist/app/observed-events.js +10 -0
- package/dist/app/report-cleanup.js +10 -0
- package/dist/app/run-jig.js +101 -0
- package/dist/app/run-status.js +20 -0
- package/dist/app/run-stores.js +107 -0
- package/dist/app/sandbox-image.js +151 -0
- package/dist/app/throwaway-sandbox.js +49 -0
- package/dist/cli/app-action.js +18 -0
- package/dist/cli/commands/presets.js +32 -0
- package/dist/cli/commands/run.js +82 -0
- package/dist/cli/commands/sandbox.js +54 -0
- package/dist/cli/commands/status.js +41 -0
- package/dist/cli/config-option.js +18 -0
- package/dist/cli/exit-when-done.js +11 -0
- package/dist/cli/log-format-option.js +14 -0
- package/dist/cli/main.js +33 -0
- package/dist/cli/read-request.js +36 -0
- package/dist/cli/with-app.js +73 -0
- package/dist/cli/with-error-handling.js +31 -0
- package/dist/cli/with-input.js +27 -0
- package/dist/config/describe-issues.js +6 -0
- package/dist/config/environment.js +53 -0
- package/dist/config/load-config.js +122 -0
- package/dist/config/presets.js +150 -0
- package/dist/config/write-config.js +39 -0
- package/dist/domain/agent-role.js +12 -0
- package/dist/domain/apply-outcome.js +132 -0
- package/dist/domain/completion-reuse.js +176 -0
- package/dist/domain/design-docs.js +3 -0
- package/dist/domain/design-review-report.js +86 -0
- package/dist/domain/design-review.js +193 -0
- package/dist/domain/errors.js +139 -0
- package/dist/domain/events.js +8 -0
- package/dist/domain/final-check.js +133 -0
- package/dist/domain/outcome.js +26 -0
- package/dist/domain/plan-coverage.js +129 -0
- package/dist/domain/protected-paths.js +35 -0
- package/dist/domain/retry.js +21 -0
- package/dist/domain/run-id.js +42 -0
- package/dist/domain/run-state.js +147 -0
- package/dist/domain/settings.js +49 -0
- package/dist/domain/slice.js +63 -0
- package/dist/domain/usage.js +1 -0
- package/dist/domain/work-facts.js +22 -0
- package/dist/flow/define-flow.js +11 -0
- package/dist/flow/engine.js +255 -0
- package/dist/flow/run-flow.js +129 -0
- package/dist/git/branch.js +26 -0
- package/dist/git/merge.js +92 -0
- package/dist/git/repository.js +48 -0
- package/dist/git/throwaway-branch.js +64 -0
- package/dist/observers/logging-observer.js +51 -0
- package/dist/observers/metrics.js +109 -0
- package/dist/observers/run-events.js +25 -0
- package/dist/observers/tracing-observer.js +86 -0
- package/dist/ports/agent-session.js +1 -0
- package/dist/ports/observability.js +1 -0
- package/dist/ports/run-store.js +1 -0
- package/dist/ports/sandbox-git.js +1 -0
- package/dist/ports/sandbox-images.js +1 -0
- package/dist/ports/workspace.js +1 -0
- package/dist/prompts/design-review.js +172 -0
- package/dist/prompts/final-check.js +58 -0
- package/dist/prompts/planning.js +111 -0
- package/dist/prompts/pull-request.js +78 -0
- package/dist/prompts/slice.js +254 -0
- package/dist/prompts/toolchain.js +37 -0
- package/dist/steps/completion-reuse.js +32 -0
- package/dist/steps/design-review.js +38 -0
- package/dist/steps/final-check.js +39 -0
- package/dist/steps/finishing.js +72 -0
- package/dist/steps/planning.js +77 -0
- package/dist/steps/pull-request-description.js +142 -0
- package/dist/steps/slice.js +149 -0
- package/package.json +95 -4
- package/presets/cheap-volume.json +7 -0
- package/presets/claude-only.json +7 -0
- package/presets/codex-only.json +7 -0
- package/presets/codex-reviewed-opencode.json +7 -0
- package/presets/full-power-codex.json +7 -0
- package/presets/full-power.json +7 -0
- package/presets/long-claude.json +7 -0
- package/presets/open-weight.json +7 -0
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
import { createHash } from 'node:crypto';
|
|
2
|
+
import stringify from 'safe-stable-stringify';
|
|
3
|
+
import { z } from 'zod';
|
|
4
|
+
import { fulfillmentVerdictSchema } from './final-check.js';
|
|
5
|
+
import { verificationRecordSchema } from './slice.js';
|
|
6
|
+
import { checkedWorkSchema, workObservationsSchema, } from './work-facts.js';
|
|
7
|
+
/**
|
|
8
|
+
* A sha256 digest, as hex: how recorded evidence binds itself to the exact sources and settings
|
|
9
|
+
* it saw without repeating them.
|
|
10
|
+
*/
|
|
11
|
+
const digestSchema = z.string().regex(/^[0-9a-f]{64}$/);
|
|
12
|
+
/**
|
|
13
|
+
* What a combined slice review recorded about the whole request, bound to the exact work, sources
|
|
14
|
+
* and settings it saw — the run's evidence for reusing that review as its completion check.
|
|
15
|
+
*/
|
|
16
|
+
export const completionEvidenceSchema = z.object({
|
|
17
|
+
/** The reviewer's judgement of the whole request: whether the run fulfils it, and every gap. */
|
|
18
|
+
verdict: fulfillmentVerdictSchema,
|
|
19
|
+
/** The complete verification the reviewed work passed under; undefined when none is recorded. */
|
|
20
|
+
verification: verificationRecordSchema.optional(),
|
|
21
|
+
/** Digest of the settings the review ran under; a different digest means the evidence no longer applies. */
|
|
22
|
+
settingsIdentity: digestSchema,
|
|
23
|
+
/** The exact resulting work the review vouches for: the run branch's commit and its tree. */
|
|
24
|
+
checked: checkedWorkSchema,
|
|
25
|
+
/** Where the work stood before and after the review; a difference is mutation during it. */
|
|
26
|
+
observed: workObservationsSchema,
|
|
27
|
+
/** The sources the review judged, by digest, and the full run range it read them against. */
|
|
28
|
+
scope: z.object({
|
|
29
|
+
request: digestSchema,
|
|
30
|
+
plan: digestSchema,
|
|
31
|
+
range: z.object({ start: z.string().min(1), end: z.string().min(1) }),
|
|
32
|
+
}),
|
|
33
|
+
});
|
|
34
|
+
/**
|
|
35
|
+
* The evidence a combined review leaves, bound to what it actually saw: the resulting work, the
|
|
36
|
+
* verification that passed under it, the digests of the request and plan it judged, and the
|
|
37
|
+
* settings it ran under.
|
|
38
|
+
*/
|
|
39
|
+
export function completionEvidenceOf(input) {
|
|
40
|
+
const { reviewed, settings, verification, verdict, observed, range } = input;
|
|
41
|
+
return {
|
|
42
|
+
verdict,
|
|
43
|
+
verification,
|
|
44
|
+
settingsIdentity: settingsIdentityOf(settings),
|
|
45
|
+
checked: {
|
|
46
|
+
commit: observed.after.host.commit,
|
|
47
|
+
tree: observed.after.host.tree,
|
|
48
|
+
},
|
|
49
|
+
observed,
|
|
50
|
+
scope: {
|
|
51
|
+
request: digestOf(reviewed.request),
|
|
52
|
+
plan: digestOf(reviewed.plan),
|
|
53
|
+
range,
|
|
54
|
+
},
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
/** How the settings a review ran under are identified, so a later check can see they did not change. */
|
|
58
|
+
export function settingsIdentityOf(settings) {
|
|
59
|
+
return digestOf(stringify(settings));
|
|
60
|
+
}
|
|
61
|
+
function digestOf(value) {
|
|
62
|
+
return createHash('sha256').update(value).digest('hex');
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Whether the recorded whole-request review still stands for the work the run now holds: the run
|
|
66
|
+
* is still the eligible single approved slice the review judged, the verification the work passed
|
|
67
|
+
* still matches the configured command and the checked work, the review ran on both repositories
|
|
68
|
+
* clean and unmoving at exactly that work, and the work the run holds is still that work. Anything
|
|
69
|
+
* else asks for a fresh final check.
|
|
70
|
+
*/
|
|
71
|
+
export function completionStillReusable(state, observed, settings, forkPoint) {
|
|
72
|
+
const evidence = state.completionReuse;
|
|
73
|
+
if (evidence === undefined || !completionReuseInPlay(state, settings))
|
|
74
|
+
return false;
|
|
75
|
+
return (scopeStillHolds(evidence, forkPoint) &&
|
|
76
|
+
factsVouchFor(observed, evidence.checked) &&
|
|
77
|
+
observationsVouchFor(evidence.observed, evidence.checked));
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* Whether the run's own record still offers its evidence for reuse, before the work is observed:
|
|
81
|
+
* an eligible approved run, a standing verdict, unchanged sources and settings, and a verification
|
|
82
|
+
* that passed at the checked work. A run that offers none needs no observation to be declined.
|
|
83
|
+
*/
|
|
84
|
+
export function completionReuseInPlay(state, settings) {
|
|
85
|
+
const evidence = state.completionReuse;
|
|
86
|
+
return (evidence !== undefined &&
|
|
87
|
+
reviewStillEligible(state) &&
|
|
88
|
+
verdictStands(evidence.verdict) &&
|
|
89
|
+
settingsStillHold(evidence, state, settings) &&
|
|
90
|
+
verificationStillHolds(evidence, settings));
|
|
91
|
+
}
|
|
92
|
+
/** The run is still what a combined review can vouch for: one slice, no final check yet, that slice approved. */
|
|
93
|
+
function reviewStillEligible(state) {
|
|
94
|
+
return wholeRequestOf(state) !== undefined && state.slices[0].status === 'approved';
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* The whole request this run's slice review can also judge, when its single slice is the run's
|
|
98
|
+
* whole work. Undefined for any other run: one whose final check already ran, whose review would
|
|
99
|
+
* cover a repair, or whose plan never reached it.
|
|
100
|
+
*/
|
|
101
|
+
export function wholeRequestOf(state) {
|
|
102
|
+
if (state.slices.length !== 1)
|
|
103
|
+
return undefined;
|
|
104
|
+
if (state.finalCheck !== undefined)
|
|
105
|
+
return undefined;
|
|
106
|
+
const docs = state.docs;
|
|
107
|
+
if (docs === undefined)
|
|
108
|
+
return undefined;
|
|
109
|
+
return { request: state.request, plan: docs.plan };
|
|
110
|
+
}
|
|
111
|
+
/** The recorded verdict must have found the request fulfilled, with no gap left open. */
|
|
112
|
+
function verdictStands(verdict) {
|
|
113
|
+
return verdict.fulfilled && verdict.gaps.length === 0;
|
|
114
|
+
}
|
|
115
|
+
/** The settings and the sources the review judged are still the ones the run holds. */
|
|
116
|
+
function settingsStillHold(evidence, state, settings) {
|
|
117
|
+
return (evidence.settingsIdentity === settingsIdentityOf(settings) && sourcesStillHold(evidence, state));
|
|
118
|
+
}
|
|
119
|
+
/** The sources the review judged are still the ones the run holds. */
|
|
120
|
+
function sourcesStillHold(evidence, state) {
|
|
121
|
+
return (evidence.scope.request === digestOf(state.request) &&
|
|
122
|
+
state.docs !== undefined &&
|
|
123
|
+
evidence.scope.plan === digestOf(state.docs.plan));
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* The verification the review relied on: the now-configured command is the one that passed, and
|
|
127
|
+
* the work it ran on is exactly the work the review checked, clean and unmoving on both sides.
|
|
128
|
+
*/
|
|
129
|
+
function verificationStillHolds(evidence, settings) {
|
|
130
|
+
const verification = evidence.verification;
|
|
131
|
+
return (verification !== undefined &&
|
|
132
|
+
verification.command === settings.verifyCommand &&
|
|
133
|
+
verification.observed !== undefined &&
|
|
134
|
+
observationsVouchFor(verification.observed, evidence.checked));
|
|
135
|
+
}
|
|
136
|
+
/** Both sides of the recorded work stood exactly at the checked work, clean, before an operation as after it. */
|
|
137
|
+
function observationsVouchFor(observed, checked) {
|
|
138
|
+
return (factsIdentity(observed.before) === factsIdentity(observed.after) &&
|
|
139
|
+
factsVouchFor(observed.before, checked));
|
|
140
|
+
}
|
|
141
|
+
/** Where the work stood, as one comparable value: key order cannot make two facts look different. */
|
|
142
|
+
function factsIdentity(facts) {
|
|
143
|
+
return stringify(facts);
|
|
144
|
+
}
|
|
145
|
+
/** A repository pair vouches for the checked work when both hold exactly that commit and tree, clean. */
|
|
146
|
+
function factsVouchFor(facts, checked) {
|
|
147
|
+
return (facts.host.commit === checked.commit &&
|
|
148
|
+
facts.host.tree === checked.tree &&
|
|
149
|
+
facts.sandbox.commit === checked.commit &&
|
|
150
|
+
facts.sandbox.tree === checked.tree &&
|
|
151
|
+
facts.host.clean &&
|
|
152
|
+
facts.sandbox.clean);
|
|
153
|
+
}
|
|
154
|
+
/** The recorded range is still the run's whole range: it starts where the run was cut and ends at the checked work. */
|
|
155
|
+
function scopeStillHolds(evidence, forkPoint) {
|
|
156
|
+
return (evidence.scope.range.start === forkPoint && evidence.scope.range.end === evidence.checked.commit);
|
|
157
|
+
}
|
|
158
|
+
/** The evidence the run was authorized to finish on in place of a final check; undefined when it finishes otherwise. */
|
|
159
|
+
export function reusedCompletion(state) {
|
|
160
|
+
return state.completionReuseAuthorized ? state.completionReuse : undefined;
|
|
161
|
+
}
|
|
162
|
+
export function completionReuseWasAuthorized(state) {
|
|
163
|
+
return state.completionReuseAuthorized === true;
|
|
164
|
+
}
|
|
165
|
+
/** How jig states a reused completion: what the combined review decided, and the verification it relied on. */
|
|
166
|
+
export function reusedCompletionReport(evidence) {
|
|
167
|
+
const verification = evidence.verification;
|
|
168
|
+
return [
|
|
169
|
+
"jig ran no separate final check: the review of the run's single slice judged the whole request against its plan and reported it fulfilled.",
|
|
170
|
+
...(verification === undefined
|
|
171
|
+
? []
|
|
172
|
+
: [
|
|
173
|
+
`The verify command \`${verification.command}\` passed in the sandbox on exactly the reviewed work.`,
|
|
174
|
+
]),
|
|
175
|
+
];
|
|
176
|
+
}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import { designReviewStage, MAX_DESIGN_REVIEWS, outstandingFindings, } from './design-review.js';
|
|
2
|
+
/** Built from the saved run alone, so a run resumed on another machine explains itself without local reports. */
|
|
3
|
+
export function designReviewReport(state) {
|
|
4
|
+
const stage = designReviewStage(state);
|
|
5
|
+
if (stage === undefined)
|
|
6
|
+
return undefined;
|
|
7
|
+
const progress = state.designReview;
|
|
8
|
+
return [
|
|
9
|
+
'# Design review',
|
|
10
|
+
`**Status:** ${STAGE_DESCRIPTIONS[stage]}`,
|
|
11
|
+
`**Reviews:** ${progress?.reviews.length ?? 0} of ${MAX_DESIGN_REVIEWS}`,
|
|
12
|
+
...(progress ? progressSections(progress) : []),
|
|
13
|
+
]
|
|
14
|
+
.join('\n\n')
|
|
15
|
+
.concat('\n');
|
|
16
|
+
}
|
|
17
|
+
const STAGE_DESCRIPTIONS = {
|
|
18
|
+
awaitingReview: 'pending — the design has not been reviewed yet.',
|
|
19
|
+
awaitingRevision: "pending — the review found problems; the planner's revision is next.",
|
|
20
|
+
awaitingReReview: 'pending — the planner revised the design; the re-review is next.',
|
|
21
|
+
approved: 'approved — the latest review left no findings standing.',
|
|
22
|
+
unresolved: "blocked — findings still stand after the planner's one revision; the run needs a person.",
|
|
23
|
+
};
|
|
24
|
+
function progressSections(progress) {
|
|
25
|
+
const [firstReview, reReview] = progress.reviews;
|
|
26
|
+
return [
|
|
27
|
+
...operatorDecisionSection(outstandingFindings(progress)),
|
|
28
|
+
...reviewSection('Review 1', firstReview),
|
|
29
|
+
...(progress.revision ? revisionSection(progress.revision) : []),
|
|
30
|
+
...(reReview ? reviewSection('Review 2', reReview) : []),
|
|
31
|
+
];
|
|
32
|
+
}
|
|
33
|
+
function operatorDecisionSection(outstanding) {
|
|
34
|
+
const decisions = outstanding.filter((finding) => finding.resolution === 'operatorDecision');
|
|
35
|
+
if (decisions.length === 0)
|
|
36
|
+
return [];
|
|
37
|
+
return [
|
|
38
|
+
'## Decisions for the operator',
|
|
39
|
+
decisions
|
|
40
|
+
.map((finding) => `- **${finding.id}**: ${finding.concern} Recommended: ${finding.recommendation}`)
|
|
41
|
+
.join('\n'),
|
|
42
|
+
];
|
|
43
|
+
}
|
|
44
|
+
function reviewSection(heading, review) {
|
|
45
|
+
if (review.findings.length === 0)
|
|
46
|
+
return [`## ${heading}`, 'No consequential findings.'];
|
|
47
|
+
return [`## ${heading}`, ...review.findings.map(findingSection)];
|
|
48
|
+
}
|
|
49
|
+
function findingSection(finding) {
|
|
50
|
+
return [
|
|
51
|
+
`### ${finding.id}: ${finding.concern}`,
|
|
52
|
+
`- **Needs:** ${RESOLUTION_DESCRIPTIONS[finding.resolution]}`,
|
|
53
|
+
`- **Failure scenario:** ${finding.failureScenario}`,
|
|
54
|
+
`- **Evidence:**\n${indentedList(finding.evidence)}`,
|
|
55
|
+
`- **Recommendation:** ${finding.recommendation}`,
|
|
56
|
+
...(finding.uncertainty ? [`- **Uncertainty:** ${finding.uncertainty}`] : []),
|
|
57
|
+
].join('\n');
|
|
58
|
+
}
|
|
59
|
+
const RESOLUTION_DESCRIPTIONS = {
|
|
60
|
+
correction: 'a technical correction',
|
|
61
|
+
operatorDecision: 'an operator decision',
|
|
62
|
+
};
|
|
63
|
+
function indentedList(items) {
|
|
64
|
+
return items.map((item) => ` - ${item}`).join('\n');
|
|
65
|
+
}
|
|
66
|
+
function revisionSection(revision) {
|
|
67
|
+
return [
|
|
68
|
+
'## Revision',
|
|
69
|
+
revision.dispositions.map(dispositionLine).join('\n'),
|
|
70
|
+
originalDocument('Design as first reviewed', revision.reviewedDocs.design),
|
|
71
|
+
originalDocument('Plan as first reviewed', revision.reviewedDocs.plan),
|
|
72
|
+
];
|
|
73
|
+
}
|
|
74
|
+
function dispositionLine(disposition) {
|
|
75
|
+
if (disposition.status === 'addressed') {
|
|
76
|
+
return `- **${disposition.findingId}** addressed: ${disposition.change}`;
|
|
77
|
+
}
|
|
78
|
+
return [
|
|
79
|
+
`- **${disposition.findingId}** disputed: ${disposition.reasoning}`,
|
|
80
|
+
indentedList(disposition.evidence),
|
|
81
|
+
].join('\n');
|
|
82
|
+
}
|
|
83
|
+
/** The pre-revision document, folded away: `design.md` and `plan.md` hold the current ones. */
|
|
84
|
+
function originalDocument(summary, markdown) {
|
|
85
|
+
return `<details>\n<summary>${summary}</summary>\n\n${markdown}\n\n</details>`;
|
|
86
|
+
}
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
import { panic, Result } from 'better-result';
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
import { designDocsSchema } from './design-docs.js';
|
|
4
|
+
import { DesignUnresolved } from './errors.js';
|
|
5
|
+
/** The planner's revision of a design under `findings`: one disposition per finding, no more. */
|
|
6
|
+
export function designRevisionSchemaFor(findings) {
|
|
7
|
+
return designRevisionSchema.superRefine(({ dispositions }, context) => {
|
|
8
|
+
for (const problem of dispositionProblems(findings, dispositions)) {
|
|
9
|
+
context.addIssue({ code: z.ZodIssueCode.custom, path: ['dispositions'], message: problem });
|
|
10
|
+
}
|
|
11
|
+
});
|
|
12
|
+
}
|
|
13
|
+
/** How the planner answered one finding: changed the design, or disputed it with evidence. */
|
|
14
|
+
export const findingDispositionSchema = z.discriminatedUnion('status', [
|
|
15
|
+
z.object({
|
|
16
|
+
findingId: z.string().trim().min(1),
|
|
17
|
+
status: z.literal('addressed'),
|
|
18
|
+
change: z.string().min(1),
|
|
19
|
+
}),
|
|
20
|
+
z.object({
|
|
21
|
+
findingId: z.string().trim().min(1),
|
|
22
|
+
status: z.literal('disputed'),
|
|
23
|
+
reasoning: z.string().min(1),
|
|
24
|
+
evidence: z.array(z.string().min(1)).min(1),
|
|
25
|
+
}),
|
|
26
|
+
]);
|
|
27
|
+
const designRevisionSchema = designDocsSchema.extend({
|
|
28
|
+
dispositions: z.array(findingDispositionSchema),
|
|
29
|
+
});
|
|
30
|
+
function dispositionProblems(findings, dispositions) {
|
|
31
|
+
const findingIds = findings.map((finding) => finding.id);
|
|
32
|
+
const answered = dispositions.map((disposition) => disposition.findingId);
|
|
33
|
+
const unanswered = findingIds.filter((id) => !answered.includes(id));
|
|
34
|
+
const unknown = answered.filter((id) => !findingIds.includes(id));
|
|
35
|
+
const repeated = repeatedIds(answered);
|
|
36
|
+
return [
|
|
37
|
+
...(unanswered.length > 0 ? [`No disposition for findings: ${unanswered.join(', ')}`] : []),
|
|
38
|
+
...(unknown.length > 0 ? [`Dispositions for unknown findings: ${unknown.join(', ')}`] : []),
|
|
39
|
+
...(repeated.length > 0 ? [`More than one disposition for: ${repeated.join(', ')}`] : []),
|
|
40
|
+
];
|
|
41
|
+
}
|
|
42
|
+
function repeatedIds(ids) {
|
|
43
|
+
return [...new Set(ids.filter((id, index) => ids.indexOf(id) !== index))];
|
|
44
|
+
}
|
|
45
|
+
/** Who can settle a finding: the planner, with a technical correction, or only the operator. */
|
|
46
|
+
export const findingResolutionSchema = z.enum(['correction', 'operatorDecision']);
|
|
47
|
+
/**
|
|
48
|
+
* One consequential problem the reviewer found in the design or plan. `uncertainty` states what
|
|
49
|
+
* the reviewer could not confirm, so a guess is never passed off as evidence; empty when nothing.
|
|
50
|
+
*/
|
|
51
|
+
export const designFindingSchema = z.object({
|
|
52
|
+
id: z.string().trim().min(1),
|
|
53
|
+
concern: z.string().min(1),
|
|
54
|
+
failureScenario: z.string().min(1),
|
|
55
|
+
evidence: z.array(z.string().min(1)).min(1),
|
|
56
|
+
recommendation: z.string().min(1),
|
|
57
|
+
resolution: findingResolutionSchema,
|
|
58
|
+
uncertainty: z.string(),
|
|
59
|
+
});
|
|
60
|
+
/** The reviewer's verdict is its findings alone: an empty list approves, so the two cannot disagree. */
|
|
61
|
+
export const designReviewSchema = z
|
|
62
|
+
.object({ findings: z.array(designFindingSchema) })
|
|
63
|
+
.superRefine(({ findings }, context) => {
|
|
64
|
+
const repeated = repeatedIds(findings.map((finding) => finding.id));
|
|
65
|
+
if (repeated.length === 0)
|
|
66
|
+
return;
|
|
67
|
+
context.addIssue({
|
|
68
|
+
code: z.ZodIssueCode.custom,
|
|
69
|
+
path: ['findings'],
|
|
70
|
+
message: `Finding ids must be unique; repeated: ${repeated.join(', ')}`,
|
|
71
|
+
});
|
|
72
|
+
});
|
|
73
|
+
/**
|
|
74
|
+
* A design is reviewed at most twice: once as written, and once more after the planner's one
|
|
75
|
+
* revision. The cap is the design review's own, independent of the slice review cap.
|
|
76
|
+
*/
|
|
77
|
+
export const MAX_DESIGN_REVIEWS = 2;
|
|
78
|
+
/** The planner's one revision, kept with the documents it revised so the re-review can compare. */
|
|
79
|
+
const designRevisionRecordSchema = z.object({
|
|
80
|
+
reviewedDocs: designDocsSchema,
|
|
81
|
+
dispositions: z.array(findingDispositionSchema),
|
|
82
|
+
});
|
|
83
|
+
/**
|
|
84
|
+
* How far a run's design review has come. A second review only ever follows the revision, so a
|
|
85
|
+
* saved run can neither skip the revision nor be granted another one.
|
|
86
|
+
*/
|
|
87
|
+
export const designReviewProgressSchema = z
|
|
88
|
+
.object({
|
|
89
|
+
reviews: z.array(designReviewSchema).min(1).max(MAX_DESIGN_REVIEWS),
|
|
90
|
+
revision: designRevisionRecordSchema.optional(),
|
|
91
|
+
})
|
|
92
|
+
.refine(({ reviews, revision }) => reviews.length === 1 || revision !== undefined, {
|
|
93
|
+
message: 'A second design review must follow the revision it reviewed',
|
|
94
|
+
});
|
|
95
|
+
/**
|
|
96
|
+
* What each stage of the design review requires of the saved progress, so a stale or hand-edited
|
|
97
|
+
* run fails when it is loaded rather than panicking in the step it resumes. A run saved past the
|
|
98
|
+
* review may have none — it predates design reviews — but any it has must have approved the design.
|
|
99
|
+
*/
|
|
100
|
+
export const designReviewProgressAt = {
|
|
101
|
+
reReview: designReviewProgressSchema.refine(({ reviews, revision }) => reviews.length === 1 && revision !== undefined, { message: 'A design re-review must follow exactly one review and its revision' }),
|
|
102
|
+
revision: designReviewProgressSchema.refine(designRevisionOwed, {
|
|
103
|
+
message: 'A design revision must follow one review that found problems',
|
|
104
|
+
}),
|
|
105
|
+
resolution: designReviewProgressSchema.refine((progress) => progress.reviews.length === MAX_DESIGN_REVIEWS && outstandingFindings(progress).length > 0, { message: 'Resolving a design must follow a re-review that left findings standing' }),
|
|
106
|
+
settled: designReviewProgressSchema.refine((progress) => outstandingFindings(progress).length === 0, { message: 'A run past the design review must carry an approved design' }),
|
|
107
|
+
};
|
|
108
|
+
function designRevisionOwed(progress) {
|
|
109
|
+
return (progress.reviews.length === 1 &&
|
|
110
|
+
progress.revision === undefined &&
|
|
111
|
+
outstandingFindings(progress).length > 0);
|
|
112
|
+
}
|
|
113
|
+
export function outstandingFindings(progress) {
|
|
114
|
+
return progress.reviews.at(-1)?.findings ?? [];
|
|
115
|
+
}
|
|
116
|
+
/** Folds a completed review into the run; a review past the cap or out of turn is a bug. */
|
|
117
|
+
export function recordDesignReview(state, review) {
|
|
118
|
+
const reviews = [...(state.designReview?.reviews ?? []), review];
|
|
119
|
+
if (reviews.length > MAX_DESIGN_REVIEWS) {
|
|
120
|
+
panic(`Run ${state.runId} has already had its ${MAX_DESIGN_REVIEWS} design reviews`);
|
|
121
|
+
}
|
|
122
|
+
if (reviews.length > 1 && state.designReview?.revision === undefined) {
|
|
123
|
+
panic(`Run ${state.runId} cannot re-review a design that was never revised`);
|
|
124
|
+
}
|
|
125
|
+
return { ...state, designReview: { ...state.designReview, reviews } };
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Folds the planner's one revision into the run atomically: the revised documents replace the
|
|
129
|
+
* reviewed ones, which are kept beside the dispositions for the re-review.
|
|
130
|
+
*/
|
|
131
|
+
export function recordDesignRevision(state, revision) {
|
|
132
|
+
const progress = state.designReview;
|
|
133
|
+
if (!state.docs || !progress || !designRevisionOwed(progress)) {
|
|
134
|
+
panic(`Run ${state.runId} owes no design revision`);
|
|
135
|
+
}
|
|
136
|
+
const { design, plan, dispositions } = revision;
|
|
137
|
+
return {
|
|
138
|
+
...state,
|
|
139
|
+
docs: { design, plan },
|
|
140
|
+
designReview: { ...progress, revision: { reviewedDocs: state.docs, dispositions } },
|
|
141
|
+
};
|
|
142
|
+
}
|
|
143
|
+
/** The latest review of the run's design found nothing, so its plan may be sliced. */
|
|
144
|
+
export function designApproved(state) {
|
|
145
|
+
const progress = state.designReview;
|
|
146
|
+
return progress !== undefined && outstandingFindings(progress).length === 0;
|
|
147
|
+
}
|
|
148
|
+
/** Undefined for a run saved before design reviews existed, which must still load and report. */
|
|
149
|
+
export function designReviewStage(state) {
|
|
150
|
+
const progress = state.designReview;
|
|
151
|
+
if (!progress)
|
|
152
|
+
return state.phase === 'reviewingDesign' ? 'awaitingReview' : undefined;
|
|
153
|
+
if (outstandingFindings(progress).length === 0)
|
|
154
|
+
return 'approved';
|
|
155
|
+
if (designRevisionOwed(progress))
|
|
156
|
+
return 'awaitingRevision';
|
|
157
|
+
return progress.reviews.length < MAX_DESIGN_REVIEWS ? 'awaitingReReview' : 'unresolved';
|
|
158
|
+
}
|
|
159
|
+
/** The first review found problems and the planner has not yet had its one revision. */
|
|
160
|
+
export function designNeedsRevision(state) {
|
|
161
|
+
return state.designReview !== undefined && designRevisionOwed(state.designReview);
|
|
162
|
+
}
|
|
163
|
+
/** The re-review's inputs once the planner has revised the design; undefined before that. */
|
|
164
|
+
export function designReReview(state) {
|
|
165
|
+
const progress = state.designReview;
|
|
166
|
+
if (progress?.revision === undefined)
|
|
167
|
+
return undefined;
|
|
168
|
+
return { ...progress.revision, findings: findingsToRevise(progress) };
|
|
169
|
+
}
|
|
170
|
+
/** The findings the planner's revision must answer. */
|
|
171
|
+
export function findingsToRevise(progress) {
|
|
172
|
+
return progress.reviews[0].findings;
|
|
173
|
+
}
|
|
174
|
+
/**
|
|
175
|
+
* Lets an approved design on to slicing; a design still carrying findings after its one revision
|
|
176
|
+
* stops the run for the operator, in either gate mode, naming what is unresolved.
|
|
177
|
+
*/
|
|
178
|
+
export function resolveDesignReview(progress) {
|
|
179
|
+
const outstanding = outstandingFindings(progress);
|
|
180
|
+
if (outstanding.length === 0)
|
|
181
|
+
return Result.ok();
|
|
182
|
+
return Result.err(new DesignUnresolved({
|
|
183
|
+
message: [
|
|
184
|
+
`The design review left ${outstanding.length} finding${outstanding.length > 1 ? 's' : ''} unresolved after the planner's one revision:`,
|
|
185
|
+
...outstanding.map(unresolvedFindingLine),
|
|
186
|
+
].join('\n'),
|
|
187
|
+
findingIds: outstanding.map((finding) => finding.id),
|
|
188
|
+
}));
|
|
189
|
+
}
|
|
190
|
+
function unresolvedFindingLine(finding) {
|
|
191
|
+
const needs = finding.resolution === 'operatorDecision' ? ' (needs an operator decision)' : '';
|
|
192
|
+
return `- ${finding.id}${needs}: ${finding.concern} — recommended: ${finding.recommendation}`;
|
|
193
|
+
}
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
import { Panic, TaggedError } from 'better-result';
|
|
2
|
+
/** JavaScript can throw anything, not only an `Error`. */
|
|
3
|
+
export function messageOf(error) {
|
|
4
|
+
return error instanceof Error ? error.message : String(error);
|
|
5
|
+
}
|
|
6
|
+
/** What was first thrown under a chain of panics, such as the one `Result.gen` wraps around a throw. */
|
|
7
|
+
export function rootCause(error) {
|
|
8
|
+
let cause = error;
|
|
9
|
+
while (Panic.is(cause) && cause.cause !== undefined)
|
|
10
|
+
cause = cause.cause;
|
|
11
|
+
return cause;
|
|
12
|
+
}
|
|
13
|
+
/** A failure worth another attempt: a step, or a sandbox that did not start, gets bounded retries. */
|
|
14
|
+
export function isTransient(error) {
|
|
15
|
+
return error.kind === 'retry';
|
|
16
|
+
}
|
|
17
|
+
export function isJigError(value) {
|
|
18
|
+
return jigErrorClasses.some((errorClass) => value instanceof errorClass);
|
|
19
|
+
}
|
|
20
|
+
export class AgentRunFailed extends TaggedError('AgentRunFailed') {
|
|
21
|
+
kind = 'retry';
|
|
22
|
+
}
|
|
23
|
+
/** The agent's own reply was malformed; a fresh attempt at the same step may well get it right. */
|
|
24
|
+
export class AgentOutputInvalid extends TaggedError('AgentOutputInvalid') {
|
|
25
|
+
kind = 'retry';
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* The planner's slices do not cover its plan. Distinct from AgentOutputInvalid so the slicing
|
|
29
|
+
* step can retry exactly this failure once, with the check's diagnostics as correction feedback.
|
|
30
|
+
*/
|
|
31
|
+
export class PlanNotCovered extends TaggedError('PlanNotCovered') {
|
|
32
|
+
kind = 'retry';
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* The design still carries consequential findings after the planner's one revision and its
|
|
36
|
+
* re-review. Only the operator can settle them, so the run stops before any slice is written.
|
|
37
|
+
*/
|
|
38
|
+
export class DesignUnresolved extends TaggedError('DesignUnresolved') {
|
|
39
|
+
kind = 'block';
|
|
40
|
+
}
|
|
41
|
+
/** A fetch or push to the remote failed; the network may well be back on the next attempt. */
|
|
42
|
+
export class RemoteUnavailable extends TaggedError('RemoteUnavailable') {
|
|
43
|
+
kind = 'retry';
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* The sandbox did not start: the Docker daemon, a container start, or creating the worktree
|
|
47
|
+
* failed in a way sandcastle does not tell apart from a passing hiccup, so it is worth another go.
|
|
48
|
+
*/
|
|
49
|
+
export class SandboxUnavailable extends TaggedError('SandboxUnavailable') {
|
|
50
|
+
kind = 'retry';
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* The setup command exited non-zero or outlived its timeout. It is the project's toolchain, so
|
|
54
|
+
* `init` hands it back to the planner; in a run it is retried, since `npm ci` fails on a network
|
|
55
|
+
* blip as readily as on a broken lockfile.
|
|
56
|
+
*/
|
|
57
|
+
export class SetupCommandFailed extends TaggedError('SetupCommandFailed') {
|
|
58
|
+
kind = 'retry';
|
|
59
|
+
}
|
|
60
|
+
/** The remote copy of a run moved in a way this process cannot follow without losing someone's work. */
|
|
61
|
+
export class RunStateConflict extends TaggedError('RunStateConflict') {
|
|
62
|
+
kind = 'block';
|
|
63
|
+
}
|
|
64
|
+
export class MergeFailed extends TaggedError('MergeFailed') {
|
|
65
|
+
kind = 'block';
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* A git command failed for a reason the operator has to look at: a missing ref, a broken
|
|
69
|
+
* repository. `command` is what was run; `output` is what it printed, or why it could not run.
|
|
70
|
+
*/
|
|
71
|
+
export class GitCommandFailed extends TaggedError('GitCommandFailed') {
|
|
72
|
+
kind = 'block';
|
|
73
|
+
}
|
|
74
|
+
/** The sandbox's commits were not taken: its answers did not add up, or it rewrote approved work. */
|
|
75
|
+
export class CommitImportRefused extends TaggedError('CommitImportRefused') {
|
|
76
|
+
kind = 'block';
|
|
77
|
+
}
|
|
78
|
+
/** The target repository's commit hooks refused the commit; `output` is what they printed. */
|
|
79
|
+
export class CommitRejected extends TaggedError('CommitRejected') {
|
|
80
|
+
kind = 'block';
|
|
81
|
+
}
|
|
82
|
+
export class ConfigInvalid extends TaggedError('ConfigInvalid') {
|
|
83
|
+
kind = 'fatal';
|
|
84
|
+
}
|
|
85
|
+
export class RunRequestInvalid extends TaggedError('RunRequestInvalid') {
|
|
86
|
+
kind = 'fatal';
|
|
87
|
+
}
|
|
88
|
+
/** Another jig process is already running this run; two writers would overwrite each other. */
|
|
89
|
+
export class RunInProgress extends TaggedError('RunInProgress') {
|
|
90
|
+
kind = 'fatal';
|
|
91
|
+
}
|
|
92
|
+
/** A complete line of a run's metrics log is not a metric record: the file was edited or damaged. */
|
|
93
|
+
export class MetricsLogCorrupt extends TaggedError('MetricsLogCorrupt') {
|
|
94
|
+
kind = 'fatal';
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Reading or writing jig's own files on this machine failed, under `.jig/` or in a temporary
|
|
98
|
+
* directory: a full disk, a permission, a file that is not there.
|
|
99
|
+
*/
|
|
100
|
+
export class LocalStateUnwritable extends TaggedError('LocalStateUnwritable') {
|
|
101
|
+
kind = 'fatal';
|
|
102
|
+
}
|
|
103
|
+
/**
|
|
104
|
+
* The Codex login a run refreshed could not be handed back to the operator's own login, or its
|
|
105
|
+
* lock could not be let go; the run's work is unaffected.
|
|
106
|
+
*/
|
|
107
|
+
export class CodexLoginNotSaved extends TaggedError('CodexLoginNotSaved') {
|
|
108
|
+
kind = 'fatal';
|
|
109
|
+
}
|
|
110
|
+
/** A sandbox image could not be built, or docker could not be asked about one; `output` is what docker said. */
|
|
111
|
+
export class ImageBuildFailed extends TaggedError('ImageBuildFailed') {
|
|
112
|
+
kind = 'fatal';
|
|
113
|
+
}
|
|
114
|
+
/** What the operator typed does not fit the command. */
|
|
115
|
+
export class CommandInputInvalid extends TaggedError('CommandInputInvalid') {
|
|
116
|
+
kind = 'fatal';
|
|
117
|
+
}
|
|
118
|
+
const jigErrorClasses = [
|
|
119
|
+
AgentRunFailed,
|
|
120
|
+
AgentOutputInvalid,
|
|
121
|
+
PlanNotCovered,
|
|
122
|
+
DesignUnresolved,
|
|
123
|
+
RemoteUnavailable,
|
|
124
|
+
SandboxUnavailable,
|
|
125
|
+
SetupCommandFailed,
|
|
126
|
+
RunStateConflict,
|
|
127
|
+
MergeFailed,
|
|
128
|
+
GitCommandFailed,
|
|
129
|
+
CommitImportRefused,
|
|
130
|
+
CommitRejected,
|
|
131
|
+
ConfigInvalid,
|
|
132
|
+
RunRequestInvalid,
|
|
133
|
+
RunInProgress,
|
|
134
|
+
MetricsLogCorrupt,
|
|
135
|
+
LocalStateUnwritable,
|
|
136
|
+
CodexLoginNotSaved,
|
|
137
|
+
ImageBuildFailed,
|
|
138
|
+
CommandInputInvalid,
|
|
139
|
+
];
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import { runPhaseSchema } from './run-state.js';
|
|
3
|
+
import { sliceStatusSchema } from './slice.js';
|
|
4
|
+
/** Where a step ran: a run phase, or one slice's step inside it. The slice form comes first so it is not read as the bare phase. */
|
|
5
|
+
export const stepLocationSchema = z.union([
|
|
6
|
+
z.object({ phase: runPhaseSchema, sliceId: z.string(), sliceStatus: sliceStatusSchema }),
|
|
7
|
+
z.object({ phase: runPhaseSchema, sliceId: z.undefined(), sliceStatus: z.undefined() }),
|
|
8
|
+
]);
|