@chernabog/sdk 0.4.0 → 0.6.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/src/flow.ts CHANGED
@@ -4,23 +4,44 @@
4
4
  // the last completed one. Side effects belong inside activities, never in the
5
5
  // workflow body, because the body runs again on every replay.
6
6
 
7
- import * as Context from 'effect/Context';
8
- import * as Duration from 'effect/Duration';
9
- import * as Effect from 'effect/Effect';
10
- import type * as FileSystem from 'effect/FileSystem';
11
- import * as Option from 'effect/Option';
12
- import * as Predicate from 'effect/Predicate';
13
- import type * as ChildProcessSpawner from 'effect/process/ChildProcessSpawner';
14
- import * as Schema from 'effect/Schema';
15
- import type * as Scope from 'effect/Scope';
16
- import * as Activity from 'effect/workflow/Activity';
17
- import * as DurableClock from 'effect/workflow/DurableClock';
18
- import * as DurableDeferred from 'effect/workflow/DurableDeferred';
19
- import type * as WorkflowEngine from 'effect/workflow/WorkflowEngine';
20
-
21
- import { NeedsHuman, Skip, StepFailed } from './errors.ts';
22
- import type { Json } from './json.ts';
23
- import { type Agent, type Git, type GitHub, type Repo, type Run, RunLog, type Usage, type WorkItem, type Worktree } from './services.ts';
7
+ import * as Context from "effect/Context";
8
+ import * as Duration from "effect/Duration";
9
+ import * as Effect from "effect/Effect";
10
+ import type * as FileSystem from "effect/FileSystem";
11
+ import * as Option from "effect/Option";
12
+ import * as Predicate from "effect/Predicate";
13
+ import type * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
14
+ import * as Schema from "effect/Schema";
15
+ import type * as Scope from "effect/Scope";
16
+ import * as Activity from "effect/workflow/Activity";
17
+ import * as DurableClock from "effect/workflow/DurableClock";
18
+ import * as DurableDeferred from "effect/workflow/DurableDeferred";
19
+ import type * as WorkflowEngine from "effect/workflow/WorkflowEngine";
20
+
21
+ import {
22
+ AgentError,
23
+ GitError,
24
+ GitHubError,
25
+ NeedsHuman,
26
+ type ReportedError,
27
+ Skip,
28
+ StepFailed,
29
+ UsageError,
30
+ WorkError,
31
+ } from "./errors.ts";
32
+ import type { Json } from "./json.ts";
33
+ import {
34
+ type Agent,
35
+ type Git,
36
+ type GitHub,
37
+ type Repo,
38
+ type ReviewerSeat,
39
+ type Run,
40
+ RunLog,
41
+ type Usage,
42
+ type WorkItem,
43
+ type Worktree,
44
+ } from "./services.ts";
24
45
 
25
46
  // Runs a step from .chernabog/stages/ in its own process. Provided by Chernabog.
26
47
  export class StepRunner extends Context.Service<
@@ -28,7 +49,7 @@ export class StepRunner extends Context.Service<
28
49
  {
29
50
  run(name: string, input: Json): Effect.Effect<Json, Skip | StepFailed>;
30
51
  }
31
- >()('@chernabog/sdk/StepRunner') {}
52
+ >()("@chernabog/sdk/StepRunner") {}
32
53
 
33
54
  // Records that a run waits on a signal, so the next tick's trigger can wake it. Provided by Chernabog.
34
55
  export class Signals extends Context.Service<
@@ -36,9 +57,19 @@ export class Signals extends Context.Service<
36
57
  {
37
58
  register(signal: string, deferred: string, token: string): Effect.Effect<void>;
38
59
  }
39
- >()('@chernabog/sdk/Signals') {}
60
+ >()("@chernabog/sdk/Signals") {}
40
61
 
41
- export type TriggerServices = Repo | GitHub | Git | Worktree | Usage | Agent | RunLog | FileSystem.FileSystem | ChildProcessSpawner.ChildProcessSpawner;
62
+ export type TriggerServices =
63
+ | Repo
64
+ | GitHub
65
+ | Git
66
+ | Worktree
67
+ | Usage
68
+ | Agent
69
+ | ReviewerSeat
70
+ | RunLog
71
+ | FileSystem.FileSystem
72
+ | ChildProcessSpawner.ChildProcessSpawner;
42
73
 
43
74
  export type WorkflowServices =
44
75
  | TriggerServices
@@ -49,92 +80,203 @@ export type WorkflowServices =
49
80
  | WorkflowEngine.WorkflowInstance
50
81
  | Scope.Scope;
51
82
 
83
+ // What a flow's trigger, gate and workflow may fail with: the flow's own
84
+ // outcomes. Any other error must be handled, or mapped to one of these, before
85
+ // the flow compiles: a work error such as PushRejected by deciding what it
86
+ // means for the work, and an error the flow can only report with `reportAs`.
52
87
  export type FlowError = Skip | NeedsHuman | StepFailed;
53
88
 
54
- // What a flow's trigger, gate and workflow may fail with: anything, which the engine reports by its message.
55
- export type FlowFailure = { readonly _tag: string } | Error;
56
-
57
89
  // A label a flow triggers on or sets beyond the repo's own, such as auto:ship. `chernabog labels` creates it.
58
- export type FlowLabel = { readonly name: string; readonly color?: string; readonly description?: string };
90
+ export type FlowLabel = {
91
+ readonly name: string;
92
+ readonly color?: string;
93
+ readonly description?: string;
94
+ };
59
95
 
60
- export type Flow = {
61
- // The work items in the state this flow acts on, such as issues labelled auto:eligible.
62
- readonly trigger: Effect.Effect<ReadonlyArray<WorkItem>, FlowFailure, TriggerServices>;
96
+ // The work item for a key a person names: the issue `chernabog start` hands
97
+ // over, say. None when there is no such item.
98
+ export type ItemLookup = (
99
+ key: string,
100
+ ) => Effect.Effect<Option.Option<WorkItem>, FlowError, TriggerServices>;
101
+
102
+ // What every flow has, whether a trigger finds its work or a person names it.
103
+ type FlowCommon = {
63
104
  // Checked before each run starts; fail with Skip to hold the run back, such as on usage.
64
- readonly gate?: Effect.Effect<void, FlowFailure, TriggerServices>;
105
+ readonly gate?: Effect.Effect<void, FlowError, TriggerServices>;
65
106
  // Runs of this flow in one repo at once. Defaults to 1; machine limits still apply.
66
107
  readonly concurrency?: number;
67
- // A cron schedule for the trigger, overriding the repo's default.
68
- readonly schedule?: string;
69
108
  // Labels of the flow's own, for `chernabog labels` to create.
70
109
  readonly labels?: ReadonlyArray<FlowLabel>;
110
+ // Whether the trigger finds only the work of the persona it runs as, as
111
+ // review's does by its review requests, so several personas can run the
112
+ // flow without assignee or reviewRequested to tell them apart.
113
+ readonly ownWork?: boolean;
71
114
  // The durable work for one item. Its result, if a string, is the run's summary.
72
- readonly workflow: (item: WorkItem) => Effect.Effect<string | void, FlowFailure, WorkflowServices>;
115
+ readonly workflow: (item: WorkItem) => Effect.Effect<string | void, FlowError, WorkflowServices>;
73
116
  };
74
117
 
118
+ // A flow whose trigger finds its work, on a schedule.
119
+ export type TriggeredFlow = FlowCommon & {
120
+ // The work items in the state this flow acts on, such as issues labelled auto:eligible.
121
+ readonly trigger: Effect.Effect<ReadonlyArray<WorkItem>, FlowError, TriggerServices>;
122
+ // A cron schedule for the trigger, overriding the repo's default.
123
+ readonly schedule?: string;
124
+ // The work item for a key a person names, when the trigger doesn't report it.
125
+ readonly item?: ItemLookup;
126
+ };
127
+
128
+ // A flow with no trigger: nothing finds its work, and it runs only when a
129
+ // person names an item, as `chernabog start <issue>` does. It has no schedule.
130
+ export type ManualFlow = FlowCommon & {
131
+ readonly trigger?: never;
132
+ readonly schedule?: never;
133
+ readonly item: ItemLookup;
134
+ };
135
+
136
+ export type Flow = TriggeredFlow | ManualFlow;
137
+
75
138
  export const defineFlow = (flow: Flow): Flow => flow;
76
139
 
140
+ // Whether a person starts each of the flow's runs, by naming its work.
141
+ export const isManual = (flow: Flow): flow is ManualFlow => !Effect.isEffect(flow.trigger);
142
+
143
+ // What the flow's trigger reports; nothing, for a manual flow.
144
+ export const triggerOf = (flow: Flow): TriggeredFlow["trigger"] => {
145
+ if (isManual(flow)) {
146
+ return Effect.succeed([]);
147
+ }
148
+
149
+ return flow.trigger;
150
+ };
151
+
77
152
  const FlowErrorSchema = Schema.Union([Skip, NeedsHuman, StepFailed]);
78
- const isFlowError = Schema.is(FlowErrorSchema);
153
+
154
+ // What an activity may fail with, as its journal stores it: the flow's outcomes and the work's errors.
155
+ const ActivityError = Schema.Union([...FlowErrorSchema.members, ...WorkError.members]);
156
+ const isActivityError = Schema.is(ActivityError);
79
157
 
80
158
  // An error's message, whatever shape it came in.
81
159
  export const describeError = <E>(error: E): string => {
82
- if (Predicate.hasProperty(error, 'step') && Predicate.hasProperty(error, 'message')) return `${String(error.step)}: ${String(error.message)}`;
160
+ if (Predicate.hasProperty(error, "step") && Predicate.hasProperty(error, "message")) {
161
+ return `${String(error.step)}: ${String(error.message)}`;
162
+ }
83
163
 
84
- if (Predicate.hasProperty(error, 'message') && Predicate.isString(error.message)) return error.message;
164
+ if (Predicate.hasProperty(error, "message") && Predicate.isString(error.message)) {
165
+ return error.message;
166
+ }
85
167
 
86
- if (Predicate.hasProperty(error, 'reason') && Predicate.isString(error.reason)) return error.reason;
168
+ if (Predicate.hasProperty(error, "reason") && Predicate.isString(error.reason)) {
169
+ return error.reason;
170
+ }
87
171
 
88
172
  return String(error);
89
173
  };
90
174
 
91
- // Keeps the SDK's own outcomes, and names the activity in any other failure.
92
- const toFlowError =
175
+ // Keeps the flow's outcomes and the work's errors, and names the activity in any other failure.
176
+ const toActivityError =
93
177
  (name: string) =>
94
- <E>(error: E): FlowError => {
95
- if (isFlowError(error)) return error;
178
+ <E>(error: E): FlowError | WorkError => {
179
+ if (isActivityError(error)) {
180
+ return error;
181
+ }
96
182
 
97
183
  return new StepFailed({ step: name, message: describeError(error) });
98
184
  };
99
185
 
100
- const withRunLog = (use: (log: RunLog['Service']) => Effect.Effect<void>) =>
101
- Effect.serviceOption(RunLog).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: use })));
186
+ const isReportedError = Schema.is(Schema.Union([GitHubError, GitError, AgentError, UsageError]));
187
+
188
+ const isReported = <E>(error: E): error is Extract<E, ReportedError> => isReportedError(error);
189
+
190
+ // Turns the errors a flow can only report (GitHubError, GitError, AgentError,
191
+ // UsageError) into StepFailed, named for `step`, and keeps every other error
192
+ // for the flow to handle. For a trigger, or work outside an activity, which
193
+ // does the same for its own.
194
+ export const reportAs =
195
+ (step: string) =>
196
+ <A, E, R>(effect: Effect.Effect<A, E, R>) =>
197
+ Effect.catchIf(
198
+ effect,
199
+ isReported,
200
+ (error) => Effect.fail(new StepFailed({ step, message: error.message })),
201
+ (other) => Effect.fail(other),
202
+ );
203
+
204
+ const withRunLog = (use: (log: RunLog["Service"]) => Effect.Effect<void>) =>
205
+ Effect.serviceOption(RunLog).pipe(
206
+ Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: use })),
207
+ );
208
+
209
+ // An activity's journal holds any of the flow's outcomes and work errors, but
210
+ // an activity only ever fails with the outcomes and the work errors its own
211
+ // execute raised: toActivityError keeps no others, and a replay reads back
212
+ // what it kept. So a failure that is an activity error is one of E's.
213
+ const raisedBy =
214
+ <E>() =>
215
+ (error: FlowError | WorkError): error is FlowError | Extract<E, WorkError> =>
216
+ isActivityError(error);
217
+
218
+ const narrowed =
219
+ <E>(name: string) =>
220
+ <A, R>(effect: Effect.Effect<A, FlowError | WorkError, R>) =>
221
+ Effect.catchIf(effect, raisedBy<E>(), Effect.fail, (other) =>
222
+ Effect.fail(new StepFailed({ step: name, message: describeError(other) })),
223
+ );
102
224
 
103
225
  // One durable step of a workflow. It runs once; its result is saved, and a
104
226
  // replay returns the saved result. Names must be unique within a run, so a
105
227
  // step inside a loop carries its round: `fix-ci-2`. `success` is the result's
106
228
  // schema, which the journal stores it with; leave it out for a step that
107
- // returns nothing.
108
- export const activity = <S extends Schema.Constraint = typeof Schema.Void, E = never, R = never>(name: string, execute: Effect.Effect<S['Type'], E, R>, success?: S) =>
109
- Activity.make({
110
- name,
111
- success,
112
- error: FlowErrorSchema,
113
- execute: withRunLog((log) => log.step(name)).pipe(
114
- Effect.andThen(execute),
115
- Effect.ensuring(withRunLog((log) => log.stepDone(name))),
116
- Effect.mapError(toFlowError(name)),
117
- ),
118
- });
229
+ // returns nothing. It fails with the flow's outcomes and the work's errors
230
+ // it raised, which the flow handles; any other failure is StepFailed.
231
+ export const activity = <S extends Schema.Constraint = typeof Schema.Void, E = never, R = never>(
232
+ name: string,
233
+ execute: Effect.Effect<S["Type"], E, R>,
234
+ success?: S,
235
+ ) =>
236
+ narrowed<E>(name)(
237
+ Activity.make({
238
+ name,
239
+ success,
240
+ error: ActivityError,
241
+ execute: withRunLog((log) => log.step(name)).pipe(
242
+ Effect.andThen(execute),
243
+ Effect.ensuring(withRunLog((log) => log.stepDone(name))),
244
+ Effect.mapError(toActivityError(name)),
245
+ ),
246
+ }),
247
+ );
119
248
 
120
249
  // Runs .chernabog/stages/<name>.ts (or an executable <name>) in a child
121
250
  // process, checks its output against `output`, and saves the result. `id`
122
251
  // tells apart two runs of one step in a run.
123
- export const step = <A>(name: string, input: Json, output: Schema.Codec<A, Json>, id: Option.Option<string> = Option.none()) =>
252
+ export const step = <A>(
253
+ name: string,
254
+ input: Json,
255
+ output: Schema.Codec<A, Json>,
256
+ id: Option.Option<string> = Option.none(),
257
+ ) =>
124
258
  activity(
125
259
  Option.match(id, { onNone: () => name, onSome: (suffix) => `${name}#${suffix}` }),
126
260
  StepRunner.use((runner) => runner.run(name, input)).pipe(
127
- Effect.flatMap((raw) => Schema.decodeEffect(output)(raw).pipe(Effect.mapError((issue) => new StepFailed({ step: name, message: `output: ${issue.message}` })))),
261
+ Effect.flatMap((raw) =>
262
+ Schema.decodeEffect(output)(raw).pipe(
263
+ Effect.mapError(
264
+ (issue) => new StepFailed({ step: name, message: `output: ${issue.message}` }),
265
+ ),
266
+ ),
267
+ ),
128
268
  ),
129
269
  output,
130
270
  );
131
271
 
132
272
  // A durable pause: it survives restarts, and a timer that came due while the
133
273
  // daemon was down fires as soon as it is back.
134
- export const sleep = (name: string, duration: Duration.Input) => DurableClock.sleep({ name, duration, inMemoryThreshold: Duration.zero });
274
+ export const sleep = (name: string, duration: Duration.Input) =>
275
+ DurableClock.sleep({ name, duration, inMemoryThreshold: Duration.zero });
135
276
 
136
277
  // The durable deferred behind one wait, by name. Chernabog completes it with `true` when the signal comes.
137
- export const signalDeferred = (name: string) => DurableDeferred.make(name, { success: Schema.Literal(true) });
278
+ export const signalDeferred = (name: string) =>
279
+ DurableDeferred.make(name, { success: Schema.Literal(true) });
138
280
 
139
281
  export type Wait = { readonly id: string; readonly timeout: Duration.Input };
140
282
 
@@ -144,17 +286,30 @@ export type Wait = { readonly id: string; readonly timeout: Duration.Input };
144
286
  // `awaitSignal(["pushed", "closed"], { id: "round-2", timeout: "6 hours" })`.
145
287
  export const awaitSignal = (signals: ReadonlyArray<string>, wait: Wait) =>
146
288
  Effect.gen(function* () {
147
- const waits = signals.map((signal) => ({ signal, deferred: signalDeferred(`${signal}:${wait.id}`) }));
289
+ const waits = signals.map((signal) => ({
290
+ signal,
291
+ deferred: signalDeferred(`${signal}:${wait.id}`),
292
+ }));
148
293
 
149
294
  for (const pending of waits) {
150
295
  const token = yield* DurableDeferred.token(pending.deferred);
151
- yield* activity(`await-${pending.deferred.name}`, Signals.use((registry) => registry.register(pending.signal, pending.deferred.name, token)));
296
+ yield* activity(
297
+ `await-${pending.deferred.name}`,
298
+ Signals.use((registry) => registry.register(pending.signal, pending.deferred.name, token)),
299
+ );
152
300
  }
153
301
 
154
302
  const [first, ...rest] = [
155
- ...waits.map((pending) => DurableDeferred.await(pending.deferred).pipe(Effect.as(pending.signal))),
156
- sleep(`timeout:${wait.id}`, wait.timeout).pipe(Effect.as('timeout')),
303
+ ...waits.map((pending) =>
304
+ DurableDeferred.await(pending.deferred).pipe(Effect.as(pending.signal)),
305
+ ),
306
+ sleep(`timeout:${wait.id}`, wait.timeout).pipe(Effect.as("timeout")),
157
307
  ];
158
308
 
159
- return yield* DurableDeferred.raceAll({ name: `race:${wait.id}`, success: Schema.String, error: Schema.Never, effects: [first, ...rest] });
309
+ return yield* DurableDeferred.raceAll({
310
+ name: `race:${wait.id}`,
311
+ success: Schema.String,
312
+ error: Schema.Never,
313
+ effects: [first, ...rest],
314
+ });
160
315
  });
package/src/hybrid.ts ADDED
@@ -0,0 +1,286 @@
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 { HUMAN_INITIATED } from "./default-prompts.ts";
18
+ import { Skip, StepFailed } from "./errors.ts";
19
+ import { activity, reportAs } from "./flow.ts";
20
+ import {
21
+ type AuthorSession,
22
+ branchFor,
23
+ issueItem,
24
+ PullRequestRef,
25
+ sessionIdFor,
26
+ } from "./implement.ts";
27
+ import type { Json } from "./json.ts";
28
+ import { claimMarker, latestMarker, sessionMarker } from "./markers.ts";
29
+ import { renderPromptOr } from "./prompt.ts";
30
+ import { requestReview } from "./pull-request.ts";
31
+ import { Agent, GitHub, Repo, Run, type WorkItem } from "./services.ts";
32
+
33
+ // Finds nothing, on whatever schedule it is given.
34
+ /** @deprecated Leave `trigger` out instead: a flow with `item` and no trigger is manual, and runs only when a person names its work. */
35
+ export const trigger = Effect.succeed<ReadonlyArray<WorkItem>>([]);
36
+
37
+ const ISSUE_KEY = /^issue-(\d+)$/;
38
+
39
+ // The issue a person names, as `issue-<number>`, whatever its labels; none for one GitHub doesn't have.
40
+ export const itemFor = (key: string) =>
41
+ Option.match(Option.fromNullishOr(ISSUE_KEY.exec(key)), {
42
+ onNone: () => Effect.succeedNone,
43
+ onSome: (match) =>
44
+ GitHub.use((github) => github.issue(Number(match[1]))).pipe(
45
+ Effect.map((issue) => Option.some(issueItem(issue))),
46
+ Effect.catchTag("NotFound", () => Effect.succeedNone),
47
+ reportAs("item"),
48
+ ),
49
+ });
50
+
51
+ // One session per issue, whichever run opens it, so starting an issue again picks up the conversation.
52
+ const sessionIdOf = (issue: number) =>
53
+ Repo.use((repo) => Effect.succeed(sessionIdFor(`${repo.slug}#${issue}`, "human-initiated")));
54
+
55
+ // The person's session, as the steps that send the agent back to it name it.
56
+ export const personSession = (issue: number) =>
57
+ Effect.gen(function* () {
58
+ const repo = yield* Repo;
59
+
60
+ return {
61
+ sessionId: Option.some(yield* sessionIdOf(issue)),
62
+ adapter: Option.some(repo.agent),
63
+ withPerson: true,
64
+ } satisfies AuthorSession;
65
+ });
66
+
67
+ const claimComment = (claimedAt: string, branch: string, runId: string) =>
68
+ [
69
+ `Started by a person with Chernabog at ${claimedAt}, on branch \`${branch}\`.`,
70
+ "",
71
+ `- Run: \`${runId}\``,
72
+ "",
73
+ claimMarker.write({ runId, claimedAt, branch, withPerson: true }),
74
+ ].join("\n");
75
+
76
+ // Creates the issue's branch, or takes over one an earlier start left, and
77
+ // labels, assigns and comments as claim does. It takes the issue out of the
78
+ // unattended queues. A branch an unattended run claimed is left to it.
79
+ export const claim = (issue: number) =>
80
+ activity(
81
+ "claim",
82
+ Effect.gen(function* () {
83
+ const github = yield* GitHub;
84
+ const repo = yield* Repo;
85
+ const run = yield* Run;
86
+ const branch = branchFor(issue);
87
+ const baseSha = yield* github.branchSha(repo.baseBranch);
88
+
89
+ if (Option.isNone(baseSha)) {
90
+ return yield* new StepFailed({
91
+ step: "claim",
92
+ message: `base branch ${repo.baseBranch} not found`,
93
+ });
94
+ }
95
+
96
+ if ((yield* github.createBranch(branch, baseSha.value)) === "already-exists") {
97
+ const latest = latestMarker(
98
+ claimMarker.read,
99
+ (yield* github.comments(issue)).map((comment) => comment.body),
100
+ );
101
+
102
+ if (Option.exists(latest, (marker) => marker.runId === run.runId)) {
103
+ return { branch };
104
+ }
105
+
106
+ if (Option.exists(latest, (marker) => marker.withPerson !== true)) {
107
+ return yield* new Skip({
108
+ reason: `#${issue} is already claimed by an unattended run (${branch} exists)`,
109
+ });
110
+ }
111
+ }
112
+
113
+ yield* github.addLabel(issue, repo.labels.inProgress);
114
+
115
+ for (const queued of [repo.labels.eligible, repo.labels.ship]) {
116
+ yield* github.removeLabel(issue, queued);
117
+ }
118
+
119
+ if (Option.isSome(repo.board)) {
120
+ yield* github.moveToStatus(issue, repo.board.value.inProgressStatus);
121
+ }
122
+
123
+ yield* github.assignSelf(issue);
124
+ yield* github.comment(
125
+ issue,
126
+ claimComment(DateTime.formatIso(yield* DateTime.now), branch, run.runId),
127
+ );
128
+
129
+ return { branch };
130
+ }),
131
+ Schema.Struct({ branch: Schema.String }),
132
+ );
133
+
134
+ // What `chernabog open-pr` records when the person and the agent are done.
135
+ export const Finished = Schema.Struct({
136
+ title: Schema.String,
137
+ body: Schema.String,
138
+ summary: Schema.String,
139
+ });
140
+
141
+ export type Finished = typeof Finished.Type;
142
+
143
+ export const finishedJsonSchema = {
144
+ type: "object",
145
+ properties: {
146
+ title: {
147
+ type: "string",
148
+ description: "The pull request title, following the repo commit convention",
149
+ },
150
+ body: {
151
+ type: "string",
152
+ description: "The pull request body in Markdown, without the Closes line",
153
+ },
154
+ summary: {
155
+ type: "string",
156
+ description: "What changed and how it was tested, for the issue comment",
157
+ },
158
+ },
159
+ required: ["title", "body", "summary"],
160
+ additionalProperties: false,
161
+ } satisfies Json;
162
+
163
+ const RESUME_PROMPT =
164
+ "You are back in your session on this issue, with the person. Pick up where the two of you left off; when you are done, finish with `chernabog open-pr`, as before.";
165
+
166
+ // The person and the agent work on the issue in a session in front of the
167
+ // person, until `chernabog open-pr` records the pull request's title, body and
168
+ // summary. Its prompt is .chernabog/prompts/human-initiated.md, or the SDK's own.
169
+ export const workWithPerson = (issue: number, worktree: string) =>
170
+ activity(
171
+ "work-with-person",
172
+ Effect.gen(function* () {
173
+ const github = yield* GitHub;
174
+ const repo = yield* Repo;
175
+ const details = yield* github.issue(issue);
176
+ const comments = yield* github.trustedComments(issue);
177
+
178
+ const prompt = yield* renderPromptOr("human-initiated", HUMAN_INITIATED, {
179
+ repo: repo.slug,
180
+ issue,
181
+ title: details.title,
182
+ body: details.body,
183
+ comments: comments.map((comment) => `${comment.author}: ${comment.body}`),
184
+ branch: branchFor(issue),
185
+ base: repo.baseBranch,
186
+ localGate: repo.localGate.map((command) => `\`${command}\``),
187
+ humanOnly: repo.humanOnly,
188
+ notes: repo.notes,
189
+ });
190
+
191
+ const result = yield* (yield* Agent).run({
192
+ cwd: worktree,
193
+ prompt,
194
+ sessionId: yield* sessionIdOf(issue),
195
+ resumePrompt: Option.some(RESUME_PROMPT),
196
+ outputSchema: Option.some(finishedJsonSchema),
197
+ adapter: Option.none(),
198
+ withPerson: true,
199
+ });
200
+
201
+ return yield* Schema.decodeUnknownEffect(Finished)(result.output).pipe(
202
+ Effect.mapError(
203
+ (invalid) =>
204
+ new StepFailed({
205
+ step: "work-with-person",
206
+ message: `open-pr answer: ${invalid.message}`,
207
+ }),
208
+ ),
209
+ );
210
+ }),
211
+ Finished,
212
+ );
213
+
214
+ // Opens the pull request for the branch, or finds the one already open, and
215
+ // labels it hybrid for people reading GitHub. It never carries ship, so a
216
+ // person merges it.
217
+ export const openPullRequest = (issue: number, finished: Finished) =>
218
+ activity(
219
+ "open-pull-request",
220
+ Effect.gen(function* () {
221
+ const github = yield* GitHub;
222
+ const repo = yield* Repo;
223
+ const branch = branchFor(issue);
224
+
225
+ const existing = Option.filter(
226
+ yield* github.pullRequestForBranch(branch),
227
+ (pull) => pull.state === "open",
228
+ );
229
+
230
+ const footer = `Opened by Chernabog for a person who worked on it with ${repo.agent}, on the hybrid path. A person merges.`;
231
+
232
+ const opened = yield* Option.match(existing, {
233
+ onSome: Effect.succeed,
234
+ onNone: () =>
235
+ github.openPullRequest({
236
+ head: branch,
237
+ base: repo.baseBranch,
238
+ title: finished.title,
239
+ body: `Closes #${issue}\n\n${finished.body}\n\n---\n${footer}`,
240
+ }),
241
+ });
242
+
243
+ yield* github.addLabel(opened.number, repo.labels.hybrid);
244
+
245
+ return { number: opened.number, url: opened.url };
246
+ }),
247
+ PullRequestRef,
248
+ );
249
+
250
+ // Hands the green pull request to review, as Implement.handOff does: the
251
+ // session marker, so answering a review reopens the person's session, the
252
+ // review trigger if the repo has one, a comment on the issue, and a review
253
+ // asked of one reviewer from the pool.
254
+ export const handOff = (issue: number, pullRequest: PullRequestRef, finished: Finished) =>
255
+ activity(
256
+ "hand-off",
257
+ Effect.gen(function* () {
258
+ const github = yield* GitHub;
259
+ const repo = yield* Repo;
260
+
261
+ if (Option.isSome(repo.reviewTrigger)) {
262
+ yield* github.comment(pullRequest.number, repo.reviewTrigger.value);
263
+ }
264
+
265
+ const session = {
266
+ adapter: repo.agent,
267
+ sessionId: yield* sessionIdOf(issue),
268
+ issue,
269
+ branch: branchFor(issue),
270
+ withPerson: true,
271
+ };
272
+
273
+ yield* github.comment(
274
+ pullRequest.number,
275
+ `Worked on by a person with ${repo.agent} for #${issue}. ${sessionMarker.write(session)}`,
276
+ );
277
+ yield* github.removeLabel(issue, repo.labels.inProgress);
278
+ yield* github.comment(
279
+ issue,
280
+ `Pull request ready for review: ${pullRequest.url}\n\n${finished.summary}`,
281
+ );
282
+
283
+ return `#${issue}: ${pullRequest.url} is ready for review; a person merges`;
284
+ }),
285
+ Schema.String,
286
+ ).pipe(Effect.tap(() => requestReview(pullRequest.number)));