@chernabog/sdk 0.3.1 → 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/roles.ts ADDED
@@ -0,0 +1,30 @@
1
+ // Which adapter a step runs its agent with. A persona can give a role its own
2
+ // account in machine config (roles: { reviewer: codex-work }), and a flow can
3
+ // name roles in config (flows.<flow>.agents, such as { reviewer: codex }). A
4
+ // step given { role } runs with the persona's pick for it, then the flow's,
5
+ // then the flow's agent, then the repo's.
6
+
7
+ import * as Effect from "effect/Effect";
8
+ import * as Option from "effect/Option";
9
+ import * as Record from "effect/Record";
10
+
11
+ import { Repo, Run } from "./services.ts";
12
+
13
+ // What a step that runs an agent can be told: the role it plays in the flow.
14
+ export type RoleOptions = { readonly role?: string };
15
+
16
+ // The adapter for a role in this run's flow; none means the repo's own agent.
17
+ export const adapterFor = (role: Option.Option<string>) =>
18
+ Effect.gen(function* () {
19
+ const repo = yield* Repo;
20
+ const run = yield* Run;
21
+ const roles = Record.get(repo.flowRoleAgents ?? {}, run.flow);
22
+
23
+ const forRole = Option.flatMap(role, (name) =>
24
+ Option.orElse(Record.get(repo.roleAgents ?? {}, name), () =>
25
+ Option.flatMap(roles, Record.get(name)),
26
+ ),
27
+ );
28
+
29
+ return Option.orElse(forRole, () => Record.get(repo.flowAgents, run.flow));
30
+ });
package/src/services.ts CHANGED
@@ -1,13 +1,22 @@
1
1
  // The services a flow, trigger or step can use. Chernabog provides each one;
2
2
  // a team can replace any of them with its own layer, and tests can use fakes.
3
3
 
4
- import * as Context from 'effect/Context';
5
- import type * as Effect from 'effect/Effect';
6
- import * as Option from 'effect/Option';
7
- import * as Schema from 'effect/Schema';
8
-
9
- import type { AgentError, GitError, GitHubError, UsageError } from './errors.ts';
10
- import type { Json } from './json.ts';
4
+ import * as Context from "effect/Context";
5
+ import type * as Effect from "effect/Effect";
6
+ import * as Option from "effect/Option";
7
+ import * as Schema from "effect/Schema";
8
+
9
+ import type {
10
+ AgentError,
11
+ GitError,
12
+ GitHubError,
13
+ MergeRefused,
14
+ NotFound,
15
+ PullRequestClosed,
16
+ PushRejected,
17
+ UsageError,
18
+ } from "./errors.ts";
19
+ import type { Json } from "./json.ts";
11
20
 
12
21
  export const Labels = Schema.Struct({
13
22
  eligible: Schema.String,
@@ -18,22 +27,32 @@ export const Labels = Schema.Struct({
18
27
  needsHuman: Schema.String,
19
28
  needsClarification: Schema.String,
20
29
  stale: Schema.String,
30
+ // The automated path: chernabog merges a pull request only when it carries this.
31
+ ship: Schema.String,
32
+ // The hybrid path, for people reading GitHub: a person started the work. No flow decides anything from it.
33
+ hybrid: Schema.String,
21
34
  });
22
35
 
23
36
  export type Labels = typeof Labels.Type;
24
37
 
25
38
  export const DEFAULT_LABELS: Labels = {
26
- eligible: 'auto:eligible',
27
- inProgress: 'auto:in-progress',
28
- needsReview: 'auto:needs-review',
29
- changesRequested: 'auto:changes-requested',
30
- approved: 'auto:approved',
31
- needsHuman: 'auto:needs-human',
32
- needsClarification: 'auto:needs-clarification',
33
- stale: 'auto:stale',
39
+ eligible: "auto:eligible",
40
+ inProgress: "auto:in-progress",
41
+ needsReview: "auto:needs-review",
42
+ changesRequested: "auto:changes-requested",
43
+ approved: "auto:approved",
44
+ needsHuman: "auto:needs-human",
45
+ needsClarification: "auto:needs-clarification",
46
+ stale: "auto:stale",
47
+ ship: "auto:ship",
48
+ hybrid: "hybrid",
34
49
  };
35
50
 
36
- export const Board = Schema.Struct({ projectNumber: Schema.Finite, readyStatus: Schema.String, inProgressStatus: Schema.String });
51
+ export const Board = Schema.Struct({
52
+ projectNumber: Schema.Finite,
53
+ readyStatus: Schema.String,
54
+ inProgressStatus: Schema.String,
55
+ });
37
56
 
38
57
  export type Board = typeof Board.Type;
39
58
 
@@ -41,7 +60,7 @@ export type Board = typeof Board.Type;
41
60
  // oauthTokenEnv names the environment variable holding a Claude login token
42
61
  // (from `claude setup-token`), for a host with no login of its own, such as CI.
43
62
  // usageGate none launches without reading usage, which such a token cannot.
44
- export const UsageGateMode = Schema.Literals(['usage', 'none']);
63
+ export const UsageGateMode = Schema.Literals(["usage", "none"]);
45
64
 
46
65
  export type UsageGateMode = typeof UsageGateMode.Type;
47
66
 
@@ -74,25 +93,44 @@ const Strings = Schema.Array(Schema.String);
74
93
 
75
94
  // A launcher of your own, from machine config: command templates with
76
95
  // {command}, {cwd}, {title} and {handle}.
77
- export const LauncherCommands = Schema.Struct({ start: Strings, close: Strings, alive: Schema.Option(Strings), attach: Schema.Option(Strings) });
96
+ export const LauncherCommands = Schema.Struct({
97
+ start: Strings,
98
+ close: Strings,
99
+ alive: Schema.Option(Strings),
100
+ attach: Schema.Option(Strings),
101
+ });
78
102
 
79
103
  export type LauncherCommands = typeof LauncherCommands.Type;
80
104
 
81
105
  // Where interactive agent sessions run (orca, tmux, a custom one, or headless
82
106
  // for none), which config layer chose it, and a custom launcher's commands.
83
- export const ResolvedLauncher = Schema.Struct({ name: Schema.String, from: Schema.String, custom: Schema.Option(LauncherCommands) });
107
+ export const ResolvedLauncher = Schema.Struct({
108
+ name: Schema.String,
109
+ from: Schema.String,
110
+ custom: Schema.Option(LauncherCommands),
111
+ });
84
112
 
85
113
  export type ResolvedLauncher = typeof ResolvedLauncher.Type;
86
114
 
87
- export const HEADLESS: ResolvedLauncher = { name: 'headless', from: 'default', custom: Option.none() };
115
+ export const HEADLESS: ResolvedLauncher = {
116
+ name: "headless",
117
+ from: "default",
118
+ custom: Option.none(),
119
+ };
88
120
 
89
121
  // Everything a run knows about the repo it works on, merged from the repo's
90
- // committed config, the person's override and machine config.
122
+ // committed config and the persona's settings in machine config.
91
123
  export const RepoSettings = Schema.Struct({
92
124
  name: Schema.String,
93
125
  slug: Schema.String,
94
126
  path: Schema.String,
95
127
  baseBranch: Schema.String,
128
+ // The team's reviewer pool, by GitHub login: a pull request with green CI
129
+ // gets one of them, never its author. None, when the team names no pool.
130
+ reviewers: Schema.optionalKey(Strings),
131
+ // The GitHub login this run acts as, when machine config names personas;
132
+ // absent, it acts as whoever the daemon is.
133
+ persona: Schema.optionalKey(Schema.String),
96
134
  account: Account,
97
135
  // The adapter that implements, and the account each adapter runs under.
98
136
  agent: Schema.String,
@@ -100,6 +138,13 @@ export const RepoSettings = Schema.Struct({
100
138
  launcher: ResolvedLauncher,
101
139
  // The adapter a flow asked for in config (flows.<name>.agent), such as a Codex reviewer.
102
140
  flowAgents: Schema.Record(Schema.String, Schema.String),
141
+ // The adapters a flow gave its roles in config (flows.<name>.agents), such as { reviewer: codex }.
142
+ flowRoleAgents: Schema.optionalKey(
143
+ Schema.Record(Schema.String, Schema.Record(Schema.String, Schema.String)),
144
+ ),
145
+ // The adapters a persona's own role picks run with, in every flow: the
146
+ // agent of the account it chose for the role (roles: { reviewer: codex-work }).
147
+ roleAgents: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
103
148
  labels: Labels,
104
149
  install: Schema.Option(Schema.String),
105
150
  localGate: Strings,
@@ -117,7 +162,7 @@ export const RepoSettings = Schema.Struct({
117
162
 
118
163
  export type RepoSettings = typeof RepoSettings.Type;
119
164
 
120
- export class Repo extends Context.Service<Repo, RepoSettings>()('@chernabog/sdk/Repo') {}
165
+ export class Repo extends Context.Service<Repo, RepoSettings>()("@chernabog/sdk/Repo") {}
121
166
 
122
167
  // One thing a flow works on: an issue, a pull request. `key` identifies it
123
168
  // across ticks, so it never has two runs at once. `signals` are events the
@@ -138,11 +183,16 @@ export const WorkItem = Schema.Struct({
138
183
 
139
184
  export type WorkItem = typeof WorkItem.Type;
140
185
 
141
- export const RunInfo = Schema.Struct({ flow: Schema.String, runId: Schema.String, executionId: Schema.String, item: WorkItem });
186
+ export const RunInfo = Schema.Struct({
187
+ flow: Schema.String,
188
+ runId: Schema.String,
189
+ executionId: Schema.String,
190
+ item: WorkItem,
191
+ });
142
192
 
143
193
  export type RunInfo = typeof RunInfo.Type;
144
194
 
145
- export class Run extends Context.Service<Run, RunInfo>()('@chernabog/sdk/Run') {}
195
+ export class Run extends Context.Service<Run, RunInfo>()("@chernabog/sdk/Run") {}
146
196
 
147
197
  export type Issue = {
148
198
  readonly number: number;
@@ -154,17 +204,25 @@ export type Issue = {
154
204
  readonly assignees: ReadonlyArray<string>;
155
205
  };
156
206
 
157
- export type Comment = { readonly id: number; readonly author: string; readonly body: string; readonly createdAt: string; readonly trusted: boolean };
207
+ export type Comment = {
208
+ readonly id: number;
209
+ readonly author: string;
210
+ readonly body: string;
211
+ readonly createdAt: string;
212
+ readonly trusted: boolean;
213
+ };
158
214
 
159
215
  // A review summary, or a comment on one line of the diff.
160
- export type ReviewNote = Comment & { readonly location: Option.Option<{ readonly path: string; readonly line: number }> };
216
+ export type ReviewNote = Comment & {
217
+ readonly location: Option.Option<{ readonly path: string; readonly line: number }>;
218
+ };
161
219
 
162
220
  export type PullRequest = {
163
221
  readonly number: number;
164
222
  readonly title: string;
165
223
  readonly body: string;
166
224
  readonly url: string;
167
- readonly state: 'open' | 'closed' | 'merged';
225
+ readonly state: "open" | "closed" | "merged";
168
226
  readonly headRef: string;
169
227
  readonly headSha: string;
170
228
  readonly baseRef: string;
@@ -177,19 +235,53 @@ export type PullRequest = {
177
235
 
178
236
  export type ReviewComment = { readonly path: string; readonly line: number; readonly body: string };
179
237
 
180
- export type NewPullRequest = { readonly head: string; readonly base: string; readonly title: string; readonly body: string };
238
+ export type NewPullRequest = {
239
+ readonly head: string;
240
+ readonly base: string;
241
+ readonly title: string;
242
+ readonly body: string;
243
+ };
181
244
 
182
- export type NewReview = { readonly body: string; readonly commitSha: string; readonly comments: ReadonlyArray<ReviewComment> };
245
+ // A review approves, requests changes, or only comments, which is the default.
246
+ export type ReviewEvent = "APPROVE" | "REQUEST_CHANGES" | "COMMENT";
183
247
 
184
- export type CiState = { state: 'pending'; waitingOn: Array<string> } | { state: 'green' } | { state: 'red'; failedChecks: Array<string> };
248
+ export type NewReview = {
249
+ readonly body: string;
250
+ readonly commitSha: string;
251
+ readonly comments: ReadonlyArray<ReviewComment>;
252
+ readonly event?: ReviewEvent;
253
+ };
254
+
255
+ // A review someone submitted: who, its state as GitHub gives it (APPROVED,
256
+ // CHANGES_REQUESTED, COMMENTED, DISMISSED), and the head it saw.
257
+ export type SubmittedReview = {
258
+ readonly author: string;
259
+ readonly state: string;
260
+ readonly commitSha: string;
261
+ };
262
+
263
+ export type MergeMethod = "merge" | "squash" | "rebase";
264
+
265
+ // The merge of exactly `sha`: GitHub refuses one whose head has moved since.
266
+ export type MergeRequest = { readonly method: MergeMethod; readonly sha: string };
267
+
268
+ // The merge commit.
269
+ export type Merged = { readonly sha: string };
270
+
271
+ export type CiState =
272
+ | { state: "pending"; waitingOn: Array<string> }
273
+ | { state: "green" }
274
+ | { state: "red"; failedChecks: Array<string> };
185
275
 
186
276
  export class GitHub extends Context.Service<
187
277
  GitHub,
188
278
  {
189
279
  // Open issues labelled eligible (and ready on the board, when the repo has one), oldest first.
190
280
  readonly queuedIssues: Effect.Effect<ReadonlyArray<Issue>, GitHubError>;
281
+ // Open issues with this label (and ready on the board, when the repo has one), oldest first.
282
+ queuedIssuesLabelled(label: string): Effect.Effect<ReadonlyArray<Issue>, GitHubError>;
191
283
  readonly oldestQueued: Effect.Effect<Option.Option<number>, GitHubError>;
192
- issue(number: number): Effect.Effect<Issue, GitHubError>;
284
+ issue(number: number): Effect.Effect<Issue, NotFound | GitHubError>;
193
285
  // Comments by the repo's owners, members and collaborators only; anyone can comment on a public repo.
194
286
  trustedComments(number: number): Effect.Effect<ReadonlyArray<Comment>, GitHubError>;
195
287
  comments(number: number): Effect.Effect<ReadonlyArray<Comment>, GitHubError>;
@@ -202,25 +294,51 @@ export class GitHub extends Context.Service<
202
294
  readonly login: Effect.Effect<string, GitHubError>;
203
295
  branchSha(branch: string): Effect.Effect<Option.Option<string>, GitHubError>;
204
296
  // Whoever creates a branch first owns it: the claim.
205
- createBranch(branch: string, sha: string): Effect.Effect<'created' | 'already-exists', GitHubError>;
297
+ createBranch(
298
+ branch: string,
299
+ sha: string,
300
+ ): Effect.Effect<"created" | "already-exists", GitHubError>;
206
301
  deleteBranch(branch: string): Effect.Effect<void, GitHubError>;
207
- pullRequest(number: number): Effect.Effect<PullRequest, GitHubError>;
302
+ pullRequest(number: number): Effect.Effect<PullRequest, NotFound | GitHubError>;
208
303
  pullRequestForBranch(branch: string): Effect.Effect<Option.Option<PullRequest>, GitHubError>;
209
304
  pullRequestsLabelled(label: string): Effect.Effect<ReadonlyArray<PullRequest>, GitHubError>;
305
+ readonly openPullRequests: Effect.Effect<ReadonlyArray<PullRequest>, GitHubError>;
306
+ // Asks these logins to review the pull request, or to review it again.
307
+ requestReviewers(
308
+ pullRequest: number,
309
+ logins: ReadonlyArray<string>,
310
+ ): Effect.Effect<void, PullRequestClosed | GitHubError>;
311
+ // The reviews submitted on a pull request, oldest first.
312
+ reviews(pullRequest: number): Effect.Effect<ReadonlyArray<SubmittedReview>, GitHubError>;
210
313
  openPullRequest(pullRequest: NewPullRequest): Effect.Effect<PullRequest, GitHubError>;
211
314
  ciState(pullRequest: number): Effect.Effect<CiState, GitHubError>;
212
315
  // Changed paths of a pull request, for path rules such as humanOnlyPaths.
213
316
  pullRequestFiles(pullRequest: number): Effect.Effect<ReadonlyArray<string>, GitHubError>;
214
317
  // Recently closed or merged pull requests carrying the label, newest first.
215
- closedPullRequestsLabelled(label: string): Effect.Effect<ReadonlyArray<PullRequest>, GitHubError>;
216
- // Posts a review as a comment (an account cannot approve its own pull request; labels carry the verdict).
217
- review(pullRequest: number, review: NewReview): Effect.Effect<void, GitHubError>;
318
+ closedPullRequestsLabelled(
319
+ label: string,
320
+ ): Effect.Effect<ReadonlyArray<PullRequest>, GitHubError>;
321
+ // Posts a review. GitHub won't let an account approve or request changes on
322
+ // its own pull request; such a review is posted as a comment instead.
323
+ review(
324
+ pullRequest: number,
325
+ review: NewReview,
326
+ ): Effect.Effect<void, PullRequestClosed | GitHubError>;
218
327
  // Review summaries and line comments on a pull request.
219
328
  reviewComments(pullRequest: number): Effect.Effect<ReadonlyArray<ReviewNote>, GitHubError>;
329
+ // Refused by GitHub (branch protection, a conflict, a moved head) with its reason.
330
+ merge(
331
+ pullRequest: number,
332
+ merge: MergeRequest,
333
+ ): Effect.Effect<Merged, MergeRefused | PullRequestClosed | GitHubError>;
220
334
  // Any other call, for what the service does not cover.
221
- request(method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', path: string, body: Option.Option<Json>): Effect.Effect<Json, GitHubError>;
335
+ request(
336
+ method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE",
337
+ path: string,
338
+ body: Option.Option<Json>,
339
+ ): Effect.Effect<Json, GitHubError>;
222
340
  }
223
- >()('@chernabog/sdk/GitHub') {}
341
+ >()("@chernabog/sdk/GitHub") {}
224
342
 
225
343
  export class Git extends Context.Service<
226
344
  Git,
@@ -230,11 +348,11 @@ export class Git extends Context.Service<
230
348
  // Commits on HEAD that origin/<base> does not have.
231
349
  commitsAhead(cwd: string, base: string): Effect.Effect<number, GitError>;
232
350
  changedFiles(cwd: string, base: string): Effect.Effect<ReadonlyArray<string>, GitError>;
233
- push(cwd: string, branch: string): Effect.Effect<void, GitError>;
351
+ push(cwd: string, branch: string): Effect.Effect<void, PushRejected | GitError>;
234
352
  // Brings the checked-out branch up to its remote, fast-forward only.
235
353
  pull(cwd: string, branch: string): Effect.Effect<void, GitError>;
236
354
  }
237
- >()('@chernabog/sdk/Git') {}
355
+ >()("@chernabog/sdk/Git") {}
238
356
 
239
357
  export class Worktree extends Context.Service<
240
358
  Worktree,
@@ -246,7 +364,7 @@ export class Worktree extends Context.Service<
246
364
  // A detached worktree named `name`, reset to `ref` (fetched first) every call: for reading, such as a review.
247
365
  checkout(name: string, ref: string): Effect.Effect<string, GitError>;
248
366
  }
249
- >()('@chernabog/sdk/Worktree') {}
367
+ >()("@chernabog/sdk/Worktree") {}
250
368
 
251
369
  export type LaunchDecision = { readonly launch: boolean; readonly reason: string };
252
370
 
@@ -258,9 +376,13 @@ export class Usage extends Context.Service<
258
376
  // The account's logged-in identity; fails when it is not the expected one.
259
377
  readonly checkAccount: Effect.Effect<string, UsageError>;
260
378
  }
261
- >()('@chernabog/sdk/Usage') {}
379
+ >()("@chernabog/sdk/Usage") {}
262
380
 
263
- export type AgentResult = { readonly sessionId: string; readonly output: Json; readonly costUsd: Option.Option<number> };
381
+ export type AgentResult = {
382
+ readonly sessionId: string;
383
+ readonly output: Json;
384
+ readonly costUsd: Option.Option<number>;
385
+ };
264
386
 
265
387
  export type AgentRequest = {
266
388
  readonly cwd: string;
@@ -273,6 +395,11 @@ export type AgentRequest = {
273
395
  readonly outputSchema: Option.Option<Json>;
274
396
  // Another adapter than the repo's own, such as a Codex reviewer.
275
397
  readonly adapter: Option.Option<string>;
398
+ // A person works in the session with the agent, on the hybrid path: it
399
+ // opens in front of them under the launcher, the agent is never sent back
400
+ // to answer, and it is done once its answer is written. Only Claude under
401
+ // a launcher can.
402
+ readonly withPerson?: boolean;
276
403
  };
277
404
 
278
405
  export class Agent extends Context.Service<
@@ -281,7 +408,31 @@ export class Agent extends Context.Service<
281
408
  run(request: AgentRequest): Effect.Effect<AgentResult, AgentError>;
282
409
  readonly adapters: ReadonlyArray<string>;
283
410
  }
284
- >()('@chernabog/sdk/Agent') {}
411
+ >()("@chernabog/sdk/Agent") {}
412
+
413
+ // The persona's seat in the team's reviewer pool: a login under github:, not
414
+ // the implicit account, that the repo's reviewers list. Every block that
415
+ // reviews requires it, so a flow that reviews does too. Chernabog checks it
416
+ // when it builds the persona's services; a flow that asks for a seat the
417
+ // persona doesn't hold stops there, before its work, and the engine reports
418
+ // why (NotInReviewerPool, PersonaUnavailable). No flow handles that.
419
+ export class ReviewerSeat extends Context.Service<
420
+ ReviewerSeat,
421
+ {
422
+ // The reviewer's login.
423
+ readonly login: Effect.Effect<string>;
424
+ }
425
+ >()("@chernabog/sdk/ReviewerSeat") {}
426
+
427
+ // What this machine knows of a run, by id: whether it is still going, or none
428
+ // for a run it never had, such as one on another machine. Provided by Chernabog
429
+ // to triggers; a trigger reads it with Effect.serviceOption.
430
+ export class Runs extends Context.Service<
431
+ Runs,
432
+ {
433
+ isActive(runId: string): Effect.Effect<Option.Option<boolean>>;
434
+ }
435
+ >()("@chernabog/sdk/Runs") {}
285
436
 
286
437
  // Writes to the run's log file, which `chernabog logs <run>` prints.
287
438
  export class RunLog extends Context.Service<
@@ -291,4 +442,4 @@ export class RunLog extends Context.Service<
291
442
  step(name: string): Effect.Effect<void>;
292
443
  stepDone(name: string): Effect.Effect<void>;
293
444
  }
294
- >()('@chernabog/sdk/RunLog') {}
445
+ >()("@chernabog/sdk/RunLog") {}
package/src/stage.ts CHANGED
@@ -3,11 +3,11 @@
3
3
  // against `output`. A step that crashes partway runs again, so it must be safe
4
4
  // to repeat: "claim unless this run already holds it".
5
5
 
6
- import type * as Effect from 'effect/Effect';
7
- import type * as Schema from 'effect/Schema';
6
+ import type * as Effect from "effect/Effect";
7
+ import type * as Schema from "effect/Schema";
8
8
 
9
- import type { Json } from './json.ts';
10
- import type { Agent, Git, GitHub, Repo, Run, RunLog, Usage, Worktree } from './services.ts';
9
+ import type { Json } from "./json.ts";
10
+ import type { Agent, Git, GitHub, Repo, Run, RunLog, Usage, Worktree } from "./services.ts";
11
11
 
12
12
  export type StageServices = Repo | Run | GitHub | Git | Worktree | Usage | Agent | RunLog;
13
13