@chernabog/sdk 0.4.0 → 0.7.0
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 +39 -29
- package/package.json +1 -1
- package/src/claims.ts +169 -0
- package/src/comment.ts +6 -6
- package/src/default-prompts.ts +52 -0
- package/src/errors.ts +209 -20
- package/src/flow.ts +227 -62
- package/src/hybrid.ts +308 -0
- package/src/implement.ts +477 -191
- package/src/index.ts +17 -14
- package/src/issue.ts +2 -2
- package/src/json.ts +7 -4
- package/src/markers.ts +73 -16
- package/src/paths.ts +18 -10
- package/src/plan.ts +762 -0
- package/src/prompt.ts +76 -24
- package/src/pull-request.ts +254 -55
- package/src/review.ts +406 -301
- package/src/roles.ts +15 -8
- package/src/services.ts +239 -51
- package/src/stage.ts +4 -4
package/src/hybrid.ts
ADDED
|
@@ -0,0 +1,308 @@
|
|
|
1
|
+
// The building blocks of the hybrid path, which chernabog's human-initiated
|
|
2
|
+
// recipe composes. A person hands
|
|
3
|
+
// chernabog an issue with `chernabog start`, and plans and implements it with
|
|
4
|
+
// the agent in an interactive session in front of them (workWithPerson).
|
|
5
|
+
// `chernabog open-pr`, run from that session, ends it; the flow then runs the
|
|
6
|
+
// local gate, pushes, opens the pull request (openPullRequest), waits for CI
|
|
7
|
+
// and asks a reviewer from the pool (handOff). review, address-review and
|
|
8
|
+
// re-review follow, with the person at the decisions: answering a review
|
|
9
|
+
// reopens their session, and only a person merges, since the pull request
|
|
10
|
+
// isn't on the automated path (auto:ship).
|
|
11
|
+
|
|
12
|
+
import * as DateTime from "effect/DateTime";
|
|
13
|
+
import * as Effect from "effect/Effect";
|
|
14
|
+
import * as Option from "effect/Option";
|
|
15
|
+
import * as Schema from "effect/Schema";
|
|
16
|
+
|
|
17
|
+
import * as Claims from "./claims.ts";
|
|
18
|
+
import { HUMAN_INITIATED } from "./default-prompts.ts";
|
|
19
|
+
import { Skip, StepFailed } from "./errors.ts";
|
|
20
|
+
import { activity, reportAs } from "./flow.ts";
|
|
21
|
+
import {
|
|
22
|
+
type AuthorSession,
|
|
23
|
+
branchFor,
|
|
24
|
+
issueItem,
|
|
25
|
+
latestClaim,
|
|
26
|
+
legacyClaim,
|
|
27
|
+
PullRequestRef,
|
|
28
|
+
sessionIdFor,
|
|
29
|
+
} from "./implement.ts";
|
|
30
|
+
import type { Json } from "./json.ts";
|
|
31
|
+
import { claimMarker, sessionMarker } from "./markers.ts";
|
|
32
|
+
import { renderPromptOr } from "./prompt.ts";
|
|
33
|
+
import { requestReview } from "./pull-request.ts";
|
|
34
|
+
import { Agent, GitHub, Repo, Run, type WorkItem } from "./services.ts";
|
|
35
|
+
|
|
36
|
+
// Finds nothing, on whatever schedule it is given.
|
|
37
|
+
/** @deprecated Leave `trigger` out instead: a flow with `item` and no trigger is manual, and runs only when a person names its work. */
|
|
38
|
+
export const trigger = Effect.succeed<ReadonlyArray<WorkItem>>([]);
|
|
39
|
+
|
|
40
|
+
const ISSUE_KEY = /^issue-(\d+)$/;
|
|
41
|
+
|
|
42
|
+
// The issue a person names, as `issue-<number>`, whatever its labels; none for one GitHub doesn't have.
|
|
43
|
+
export const itemFor = (key: string) =>
|
|
44
|
+
Option.match(Option.fromNullishOr(ISSUE_KEY.exec(key)), {
|
|
45
|
+
onNone: () => Effect.succeedNone,
|
|
46
|
+
onSome: (match) =>
|
|
47
|
+
GitHub.use((github) => github.issue(Number(match[1]))).pipe(
|
|
48
|
+
Effect.map((issue) => Option.some(issueItem(issue))),
|
|
49
|
+
Effect.catchTag("NotFound", () => Effect.succeedNone),
|
|
50
|
+
reportAs("item"),
|
|
51
|
+
),
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
// One session per issue, whichever run opens it, so starting an issue again picks up the conversation.
|
|
55
|
+
const sessionIdOf = (issue: number) =>
|
|
56
|
+
Repo.use((repo) => Effect.succeed(sessionIdFor(`${repo.slug}#${issue}`, "human-initiated")));
|
|
57
|
+
|
|
58
|
+
// The person's session, as the steps that send the agent back to it name it.
|
|
59
|
+
export const personSession = (issue: number) =>
|
|
60
|
+
Effect.gen(function* () {
|
|
61
|
+
const repo = yield* Repo;
|
|
62
|
+
|
|
63
|
+
return {
|
|
64
|
+
sessionId: Option.some(yield* sessionIdOf(issue)),
|
|
65
|
+
adapter: Option.some(repo.agent),
|
|
66
|
+
withPerson: true,
|
|
67
|
+
} satisfies AuthorSession;
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
const claimComment = (claimedAt: string, branch: string, runId: string) =>
|
|
71
|
+
[
|
|
72
|
+
`Started by a person with Chernabog at ${claimedAt}, on branch \`${branch}\`.`,
|
|
73
|
+
"",
|
|
74
|
+
`- Run: \`${runId}\``,
|
|
75
|
+
"",
|
|
76
|
+
claimMarker.write({ runId, claimedAt, branch, withPerson: true, ref: true }),
|
|
77
|
+
].join("\n");
|
|
78
|
+
|
|
79
|
+
// How to let go of the claim another run holds: cancelling it, which for a run
|
|
80
|
+
// that has ended deletes only the claim ref its flow left.
|
|
81
|
+
const cancelHint = (holder: Option.Option<Claims.Holder>) =>
|
|
82
|
+
Option.match(holder, {
|
|
83
|
+
onNone: () => "`chernabog cancel` the run that holds it",
|
|
84
|
+
onSome: (found) => `\`chernabog cancel ${found.runId}\``,
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
// Claims the issue with its claim ref, then creates the issue's branch, or
|
|
88
|
+
// takes up one an earlier start or an ended run left, and labels, assigns and
|
|
89
|
+
// comments as claim does. It takes the issue out of the unattended queues. An
|
|
90
|
+
// issue another run holds is left to it. Wrap the run in
|
|
91
|
+
// `Claims.releasing(Claims.issue(issue))` to let the claim go when it ends.
|
|
92
|
+
export const claim = (issue: number) =>
|
|
93
|
+
activity(
|
|
94
|
+
"claim",
|
|
95
|
+
Effect.gen(function* () {
|
|
96
|
+
const github = yield* GitHub;
|
|
97
|
+
const repo = yield* Repo;
|
|
98
|
+
const run = yield* Run;
|
|
99
|
+
const branch = branchFor(issue);
|
|
100
|
+
const item = Claims.issue(issue);
|
|
101
|
+
const baseSha = yield* github.branchSha(repo.baseBranch);
|
|
102
|
+
|
|
103
|
+
if (Option.isNone(baseSha)) {
|
|
104
|
+
return yield* new StepFailed({
|
|
105
|
+
step: "claim",
|
|
106
|
+
message: `base branch ${repo.baseBranch} not found`,
|
|
107
|
+
});
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
const claimed = yield* Claims.acquire(item, { withPerson: true });
|
|
111
|
+
|
|
112
|
+
if (!claimed.acquired) {
|
|
113
|
+
return yield* new Skip({
|
|
114
|
+
reason: `#${issue} is already claimed (${Claims.describeHolder(item, claimed.holder)}); ${cancelHint(claimed.holder)} to start it here`,
|
|
115
|
+
});
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
if ((yield* github.createBranch(branch, baseSha.value)) === "already-exists") {
|
|
119
|
+
const latest = yield* latestClaim(issue);
|
|
120
|
+
|
|
121
|
+
if (Option.exists(latest, (marker) => marker.runId === run.runId)) {
|
|
122
|
+
return { branch };
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
// An earlier start that held it by its branch alone is taken over, as before claim refs.
|
|
126
|
+
if (Option.exists(legacyClaim(latest, run.runId), (marker) => marker.withPerson !== true)) {
|
|
127
|
+
yield* Claims.release(item);
|
|
128
|
+
|
|
129
|
+
return yield* new Skip({
|
|
130
|
+
reason: `#${issue} is already claimed by an unattended run (${branch} exists)`,
|
|
131
|
+
});
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
yield* github.addLabel(issue, repo.labels.inProgress);
|
|
136
|
+
|
|
137
|
+
for (const queued of [repo.labels.eligible, repo.labels.ship]) {
|
|
138
|
+
yield* github.removeLabel(issue, queued);
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
if (Option.isSome(repo.board)) {
|
|
142
|
+
yield* github.moveToStatus(issue, repo.board.value.inProgressStatus);
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
yield* github.assignSelf(issue);
|
|
146
|
+
yield* github.comment(
|
|
147
|
+
issue,
|
|
148
|
+
claimComment(DateTime.formatIso(yield* DateTime.now), branch, run.runId),
|
|
149
|
+
);
|
|
150
|
+
|
|
151
|
+
return { branch };
|
|
152
|
+
}),
|
|
153
|
+
Schema.Struct({ branch: Schema.String }),
|
|
154
|
+
);
|
|
155
|
+
|
|
156
|
+
// What `chernabog open-pr` records when the person and the agent are done.
|
|
157
|
+
export const Finished = Schema.Struct({
|
|
158
|
+
title: Schema.String,
|
|
159
|
+
body: Schema.String,
|
|
160
|
+
summary: Schema.String,
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
export type Finished = typeof Finished.Type;
|
|
164
|
+
|
|
165
|
+
export const finishedJsonSchema = {
|
|
166
|
+
type: "object",
|
|
167
|
+
properties: {
|
|
168
|
+
title: {
|
|
169
|
+
type: "string",
|
|
170
|
+
description: "The pull request title, following the repo commit convention",
|
|
171
|
+
},
|
|
172
|
+
body: {
|
|
173
|
+
type: "string",
|
|
174
|
+
description: "The pull request body in Markdown, without the Closes line",
|
|
175
|
+
},
|
|
176
|
+
summary: {
|
|
177
|
+
type: "string",
|
|
178
|
+
description: "What changed and how it was tested, for the issue comment",
|
|
179
|
+
},
|
|
180
|
+
},
|
|
181
|
+
required: ["title", "body", "summary"],
|
|
182
|
+
additionalProperties: false,
|
|
183
|
+
} satisfies Json;
|
|
184
|
+
|
|
185
|
+
const RESUME_PROMPT =
|
|
186
|
+
"You are back in your session on this issue, with the person. Pick up where the two of you left off; when you are both done, draft the pull request with `chernabog open-pr --draft` and ask the person, as before.";
|
|
187
|
+
|
|
188
|
+
// The person and the agent work on the issue in a session in front of the
|
|
189
|
+
// person, until the person's Yes to the agent's draft (or their own
|
|
190
|
+
// `chernabog open-pr`) records the pull request's title, body and summary. Its prompt is .chernabog/prompts/human-initiated.md, or the SDK's own.
|
|
191
|
+
export const workWithPerson = (issue: number, worktree: string) =>
|
|
192
|
+
activity(
|
|
193
|
+
"work-with-person",
|
|
194
|
+
Effect.gen(function* () {
|
|
195
|
+
const github = yield* GitHub;
|
|
196
|
+
const repo = yield* Repo;
|
|
197
|
+
const details = yield* github.issue(issue);
|
|
198
|
+
const comments = yield* github.trustedComments(issue);
|
|
199
|
+
|
|
200
|
+
const prompt = yield* renderPromptOr("human-initiated", HUMAN_INITIATED, {
|
|
201
|
+
repo: repo.slug,
|
|
202
|
+
issue,
|
|
203
|
+
title: details.title,
|
|
204
|
+
body: details.body,
|
|
205
|
+
comments: comments.map((comment) => `${comment.author}: ${comment.body}`),
|
|
206
|
+
branch: branchFor(issue),
|
|
207
|
+
base: repo.baseBranch,
|
|
208
|
+
localGate: repo.localGate.map((command) => `\`${command}\``),
|
|
209
|
+
humanOnly: repo.humanOnly,
|
|
210
|
+
notes: repo.notes,
|
|
211
|
+
});
|
|
212
|
+
|
|
213
|
+
const result = yield* (yield* Agent).run({
|
|
214
|
+
cwd: worktree,
|
|
215
|
+
prompt,
|
|
216
|
+
sessionId: yield* sessionIdOf(issue),
|
|
217
|
+
resumePrompt: Option.some(RESUME_PROMPT),
|
|
218
|
+
outputSchema: Option.some(finishedJsonSchema),
|
|
219
|
+
adapter: Option.none(),
|
|
220
|
+
withPerson: true,
|
|
221
|
+
});
|
|
222
|
+
|
|
223
|
+
return yield* Schema.decodeUnknownEffect(Finished)(result.output).pipe(
|
|
224
|
+
Effect.mapError(
|
|
225
|
+
(invalid) =>
|
|
226
|
+
new StepFailed({
|
|
227
|
+
step: "work-with-person",
|
|
228
|
+
message: `open-pr answer: ${invalid.message}`,
|
|
229
|
+
}),
|
|
230
|
+
),
|
|
231
|
+
);
|
|
232
|
+
}),
|
|
233
|
+
Finished,
|
|
234
|
+
);
|
|
235
|
+
|
|
236
|
+
// Opens the pull request for the branch, or finds the one already open, and
|
|
237
|
+
// labels it hybrid for people reading GitHub. It never carries ship, so a
|
|
238
|
+
// person merges it.
|
|
239
|
+
export const openPullRequest = (issue: number, finished: Finished) =>
|
|
240
|
+
activity(
|
|
241
|
+
"open-pull-request",
|
|
242
|
+
Effect.gen(function* () {
|
|
243
|
+
const github = yield* GitHub;
|
|
244
|
+
const repo = yield* Repo;
|
|
245
|
+
const branch = branchFor(issue);
|
|
246
|
+
|
|
247
|
+
const existing = Option.filter(
|
|
248
|
+
yield* github.pullRequestForBranch(branch),
|
|
249
|
+
(pull) => pull.state === "open",
|
|
250
|
+
);
|
|
251
|
+
|
|
252
|
+
const footer = `Opened by Chernabog for a person who worked on it with ${repo.agent}, on the hybrid path. A person merges.`;
|
|
253
|
+
|
|
254
|
+
const opened = yield* Option.match(existing, {
|
|
255
|
+
onSome: Effect.succeed,
|
|
256
|
+
onNone: () =>
|
|
257
|
+
github.openPullRequest({
|
|
258
|
+
head: branch,
|
|
259
|
+
base: repo.baseBranch,
|
|
260
|
+
title: finished.title,
|
|
261
|
+
body: `Closes #${issue}\n\n${finished.body}\n\n---\n${footer}`,
|
|
262
|
+
}),
|
|
263
|
+
});
|
|
264
|
+
|
|
265
|
+
yield* github.addLabel(opened.number, repo.labels.hybrid);
|
|
266
|
+
|
|
267
|
+
return { number: opened.number, url: opened.url };
|
|
268
|
+
}),
|
|
269
|
+
PullRequestRef,
|
|
270
|
+
);
|
|
271
|
+
|
|
272
|
+
// Hands the green pull request to review, as Implement.handOff does: the
|
|
273
|
+
// session marker, so answering a review reopens the person's session, the
|
|
274
|
+
// review trigger if the repo has one, a comment on the issue, and a review
|
|
275
|
+
// asked of one reviewer from the pool.
|
|
276
|
+
export const handOff = (issue: number, pullRequest: PullRequestRef, finished: Finished) =>
|
|
277
|
+
activity(
|
|
278
|
+
"hand-off",
|
|
279
|
+
Effect.gen(function* () {
|
|
280
|
+
const github = yield* GitHub;
|
|
281
|
+
const repo = yield* Repo;
|
|
282
|
+
|
|
283
|
+
if (Option.isSome(repo.reviewTrigger)) {
|
|
284
|
+
yield* github.comment(pullRequest.number, repo.reviewTrigger.value);
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
const session = {
|
|
288
|
+
adapter: repo.agent,
|
|
289
|
+
sessionId: yield* sessionIdOf(issue),
|
|
290
|
+
issue,
|
|
291
|
+
branch: branchFor(issue),
|
|
292
|
+
withPerson: true,
|
|
293
|
+
};
|
|
294
|
+
|
|
295
|
+
yield* github.comment(
|
|
296
|
+
pullRequest.number,
|
|
297
|
+
`Worked on by a person with ${repo.agent} for #${issue}. ${sessionMarker.write(session)}`,
|
|
298
|
+
);
|
|
299
|
+
yield* github.removeLabel(issue, repo.labels.inProgress);
|
|
300
|
+
yield* github.comment(
|
|
301
|
+
issue,
|
|
302
|
+
`Pull request ready for review: ${pullRequest.url}\n\n${finished.summary}`,
|
|
303
|
+
);
|
|
304
|
+
|
|
305
|
+
return `#${issue}: ${pullRequest.url} is ready for review; a person merges`;
|
|
306
|
+
}),
|
|
307
|
+
Schema.String,
|
|
308
|
+
).pipe(Effect.tap(() => requestReview(pullRequest.number)));
|