@chernabog/sdk 0.0.0-stage → 0.1.0

package/src/review.ts

@@ -0,0 +1,398 @@
+// The building blocks of the default `review` and `fix` flows. A review run
+// stays inside one workflow: after each review it waits on whichever comes
+// first, the author's push or the staleness timeout. It ends when the pull
+// request closes, the timeout labels it stale, or the loop cap hands it to a
+// person. The fix flow is the author, for pull requests an agent wrote: it
+// resumes the session that implemented them, addresses the review and pushes.
+
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Record from 'effect/Record';
+import * as Schema from 'effect/Schema';
+
+import { NeedsHuman, StepFailed } from './errors.ts';
+import { activity, awaitSignal } from './flow.ts';
+import { fixWithAgent, push, sessionIdFor, waitForCi } from './implement.ts';
+import type { Json } from './json.ts';
+import { latestMarker, reviewMarker, SessionMarker, sessionMarker } from './markers.ts';
+import { renderPrompt } from './prompt.ts';
+import { Agent, Git, GitHub, type PullRequest, Repo, type ReviewNote, Run, type WorkItem, Worktree } from './services.ts';
+
+export { type ReviewMarker, reviewMarker, type SessionMarker, sessionMarker } from './markers.ts';
+
+// Agent-written pull requests come from claim branches.
+export const isAgentBranch = (branch: string) => branch.startsWith('auto/');
+
+export const ReviewItem = Schema.Struct({ pullRequest: Schema.Finite, headRef: Schema.String, agentWritten: Schema.Boolean });
+
+export type ReviewItem = typeof ReviewItem.Type;
+
+export const FixItem = Schema.Struct({ ...ReviewItem.fields, round: Schema.Finite, reviewedSha: Schema.String });
+
+export type FixItem = typeof FixItem.Type;
+
+const itemData =
+  <A>(schema: Schema.Codec<A, Json>) =>
+  (item: WorkItem) =>
+    Schema.decodeEffect(schema)(item.data).pipe(Effect.mapError((issue) => new StepFailed({ step: 'work item', message: `${item.key}: ${issue.message}` })));
+
+export const pullRequestOf = itemData(ReviewItem);
+const fixItemOf = itemData(FixItem);
+
+const reviewItem = (pull: PullRequest): WorkItem => ({
+  key: `pr-${pull.number}`,
+  title: pull.title,
+  url: pull.url,
+  data: { pullRequest: pull.number, headRef: pull.headRef, agentWritten: isAgentBranch(pull.headRef) },
+});
+
+// The head the latest review saw.
+const reviewedSha = (pull: PullRequest) =>
+  GitHub.use((github) => github.comments(pull.number)).pipe(
+    Effect.map((comments) =>
+      latestMarker(
+        reviewMarker.read,
+        comments.map((comment) => comment.body),
+      ).pipe(Option.map((marker) => marker.sha)),
+    ),
+  );
+
+const changedSinceReview = (pull: PullRequest) => reviewedSha(pull).pipe(Effect.map(Option.exists((sha) => sha !== pull.headSha)));
+
+// Pull requests to review, and the signals that wake reviews already waiting:
+// "pushed" when a pull request changed since its last review (for one an agent
+// wrote, once the fix flow handed it back), "closed" when it merged or closed.
+export const trigger = Effect.gen(function* () {
+  const github = yield* GitHub;
+  const repo = yield* Repo;
+  const items: Array<WorkItem> = [];
+
+  for (const pull of yield* github.pullRequestsLabelled(repo.labels.needsReview)) {
+    const item = reviewItem(pull);
+
+    if (yield* changedSinceReview(pull)) items.push({ ...item, signals: ['pushed'] });
+    else items.push(item);
+  }
+
+  for (const pull of yield* github.pullRequestsLabelled(repo.labels.changesRequested)) {
+    if (!isAgentBranch(pull.headRef) && (yield* changedSinceReview(pull))) items.push({ ...reviewItem(pull), signals: ['pushed'], wakeOnly: true });
+  }
+
+  for (const label of [repo.labels.changesRequested, repo.labels.approved, repo.labels.needsReview]) {
+    for (const pull of yield* github.closedPullRequestsLabelled(label)) items.push({ ...reviewItem(pull), signals: ['closed'], wakeOnly: true });
+  }
+
+  return items;
+});
+
+export const Verdict = Schema.Struct({
+  verdict: Schema.Literals(['approve', 'request-changes']),
+  summary: Schema.String,
+  comments: Schema.Array(Schema.Struct({ path: Schema.String, line: Schema.Finite, body: Schema.String })),
+});
+
+export type Verdict = typeof Verdict.Type;
+
+export const verdictJsonSchema = {
+  type: 'object',
+  properties: {
+    verdict: { type: 'string', enum: ['approve', 'request-changes'] },
+    summary: { type: 'string', description: 'The review: what is right, what must change and why, in Markdown' },
+    comments: {
+      type: 'array',
+      description: 'Comments on lines the pull request changed',
+      items: {
+        type: 'object',
+        properties: { path: { type: 'string' }, line: { type: 'number' }, body: { type: 'string' } },
+        required: ['path', 'line', 'body'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['verdict', 'summary', 'comments'],
+  additionalProperties: false,
+} satisfies Json;
+
+const ReviewResult = Schema.Struct({ verdict: Schema.Literals(['approve', 'request-changes']), sha: Schema.String });
+
+const withoutMarkers = (body: string) => body.replace(/<!--.*?-->/gs, '').trim();
+
+const describeNote = (note: ReviewNote) =>
+  Option.match(note.location, {
+    onNone: () => `${note.author}: ${withoutMarkers(note.body)}`,
+    onSome: (location) => `${note.author} on ${location.path}:${location.line}: ${withoutMarkers(note.body)}`,
+  });
+
+const headingFor = (verdict: Verdict['verdict'], reviewer: string) => {
+  if (verdict === 'approve') return `Approved by ${reviewer}`;
+
+  return `Changes requested by ${reviewer}`;
+};
+
+// One review of the pull request's current head, in a detached worktree, by the
+// flow's agent (flows.review.agent) in a fresh session that is given the earlier
+// reviews. Posts it and moves the labels.
+export const reviewRound = (pullRequest: number, round: number) =>
+  activity(
+    `review-${round}`,
+    Effect.gen(function* () {
+      const github = yield* GitHub;
+      const repo = yield* Repo;
+      const run = yield* Run;
+      const pull = yield* github.pullRequest(pullRequest);
+      const worktree = yield* (yield* Worktree).checkout(`review-pr-${pullRequest}`, `origin/${pull.headRef}`);
+      const earlier = (yield* github.reviewComments(pullRequest)).filter((note) => note.trusted);
+
+      const prompt = yield* renderPrompt('review', {
+        repo: repo.slug,
+        pullRequest,
+        title: pull.title,
+        body: pull.body,
+        base: pull.baseRef,
+        round,
+        earlier: earlier.map(describeNote),
+        humanOnly: repo.humanOnly,
+        notes: repo.notes,
+      });
+
+      const adapter = Record.get(repo.flowAgents, run.flow);
+
+      const result = yield* (yield* Agent).run({
+        cwd: worktree,
+        prompt,
+        sessionId: sessionIdFor(run.runId, `review-${round}`),
+        resumePrompt: Option.none(),
+        outputSchema: Option.some(verdictJsonSchema),
+        adapter,
+      });
+
+      const verdict = yield* Schema.decodeUnknownEffect(Verdict)(result.output).pipe(
+        Effect.mapError((issue) => new StepFailed({ step: `review-${round}`, message: `reviewer answer: ${issue.message}` })),
+      );
+
+      const heading = headingFor(verdict.verdict, Option.getOrElse(adapter, () => repo.agent));
+      const marker = reviewMarker.write({ sha: pull.headSha, round, verdict: verdict.verdict });
+      yield* github.review(pullRequest, { body: `**${heading}** (review ${round})\n\n${verdict.summary}\n\n${marker}`, commitSha: pull.headSha, comments: verdict.comments });
+      // The marker also goes in a plain comment, which the trigger reads back.
+      yield* github.comment(pullRequest, `${heading} at \`${pull.headSha.slice(0, 7)}\`. ${marker}`);
+      yield* github.removeLabel(pullRequest, repo.labels.needsReview);
+
+      if (verdict.verdict === 'approve') yield* github.addLabel(pullRequest, repo.labels.approved);
+      else yield* github.addLabel(pullRequest, repo.labels.changesRequested);
+
+      return { verdict: verdict.verdict, sha: pull.headSha };
+    }),
+    ReviewResult,
+  );
+
+// Moves a pull request from some labels to another, saying why when there is something to say.
+type Relabel = { readonly remove: ReadonlyArray<string>; readonly add: string; readonly comment: Option.Option<string> };
+
+const relabel = (name: string, pullRequest: number, change: Relabel) =>
+  activity(
+    name,
+    Effect.gen(function* () {
+      const github = yield* GitHub;
+
+      for (const label of change.remove) yield* github.removeLabel(pullRequest, label);
+
+      yield* github.addLabel(pullRequest, change.add);
+
+      if (Option.isSome(change.comment)) yield* github.comment(pullRequest, change.comment.value);
+    }),
+  );
+
+// Removes the worktrees of a pull request that merged or closed: the branch's own and the review's.
+export const cleanUp = (pullRequest: number, headRef: string) =>
+  activity(
+    'clean-up',
+    Effect.gen(function* () {
+      const worktree = yield* Worktree;
+      yield* worktree.remove(`review-pr-${pullRequest}`);
+      yield* worktree.remove(headRef);
+
+      return `#${pullRequest} closed; worktrees removed`;
+    }),
+    Schema.String,
+  );
+
+// How long an approved pull request's worktrees wait for it to merge before the run lets go.
+const APPROVED_WAIT = '14 days';
+
+const afterApproval = (pullRequest: number, headRef: string) =>
+  Effect.gen(function* () {
+    const closed = yield* awaitSignal(['closed'], { id: 'approved', timeout: APPROVED_WAIT });
+
+    if (closed === 'closed') return yield* cleanUp(pullRequest, headRef);
+
+    return `#${pullRequest} approved; a person merges`;
+  });
+
+export const workflow = (item: WorkItem) =>
+  Effect.gen(function* () {
+    const repo = yield* Repo;
+    const { headRef, pullRequest } = yield* pullRequestOf(item);
+
+    for (let round = 1; ; round++) {
+      const { verdict } = yield* reviewRound(pullRequest, round);
+
+      if (verdict === 'approve') return yield* afterApproval(pullRequest, headRef);
+
+      if (round >= repo.limits.reviewRounds) {
+        yield* relabel('needs-human', pullRequest, {
+          remove: [repo.labels.changesRequested],
+          add: repo.labels.needsHuman,
+          comment: Option.some(`Still changes requested after ${round} reviews, so a person takes it from here.`),
+        });
+
+        return yield* new NeedsHuman({ reason: `#${pullRequest}: still changes requested after ${round} reviews` });
+      }
+
+      const woke = yield* awaitSignal(['pushed', 'closed'], { id: `round-${round}`, timeout: repo.limits.staleAfter });
+
+      if (woke === 'closed') return yield* cleanUp(pullRequest, headRef);
+
+      if (woke === 'timeout') {
+        yield* relabel(`stale-${round}`, pullRequest, {
+          remove: [repo.labels.changesRequested],
+          add: repo.labels.stale,
+          comment: Option.some('No push since the last review, so this is marked stale.'),
+        });
+
+        return `#${pullRequest} went stale waiting for a push`;
+      }
+
+      yield* relabel(`re-review-${round}`, pullRequest, { remove: [repo.labels.changesRequested], add: repo.labels.needsReview, comment: Option.none() });
+    }
+  });
+
+// The fix flow's work items: agent-written pull requests with changes requested
+// and no push since, one per review that asked.
+export const fixTrigger = Effect.gen(function* () {
+  const github = yield* GitHub;
+  const repo = yield* Repo;
+  const items: Array<WorkItem> = [];
+
+  for (const pull of yield* github.pullRequestsLabelled(repo.labels.changesRequested)) {
+    const reviewed = latestMarker(
+      reviewMarker.read,
+      (yield* github.comments(pull.number)).map((comment) => comment.body),
+    );
+
+    if (isAgentBranch(pull.headRef) && Option.isSome(reviewed) && reviewed.value.sha === pull.headSha) {
+      items.push({
+        key: `pr-${pull.number}-review-${reviewed.value.round}`,
+        title: pull.title,
+        url: pull.url,
+        data: { pullRequest: pull.number, headRef: pull.headRef, agentWritten: true, round: reviewed.value.round, reviewedSha: reviewed.value.sha },
+      });
+    }
+  }
+
+  return items;
+});
+
+// The author's session, from the marker the implement run left; a fresh one if there is none.
+const authorSession = (pullRequest: number) =>
+  activity(
+    'find-author',
+    Effect.gen(function* () {
+      const github = yield* GitHub;
+      const run = yield* Run;
+      const repo = yield* Repo;
+
+      const found = latestMarker(
+        sessionMarker.read,
+        (yield* github.comments(pullRequest)).map((comment) => comment.body),
+      );
+
+      return Option.getOrElse(found, () => ({ adapter: repo.agent, sessionId: sessionIdFor(run.runId, 'fix'), issue: 0, branch: '' }));
+    }),
+    SessionMarker,
+  );
+
+const prepareFix = (headRef: string) =>
+  activity(
+    'prepare-worktree',
+    Effect.gen(function* () {
+      const path = yield* (yield* Worktree).ensure(headRef);
+      yield* (yield* Git).pull(path, headRef);
+
+      return path;
+    }),
+    Schema.String,
+  );
+
+const describeReviewLine = (note: ReviewNote) =>
+  Option.match(note.location, {
+    onNone: () => withoutMarkers(note.body),
+    onSome: (location) => `${location.path}:${location.line}: ${withoutMarkers(note.body)}`,
+  });
+
+const readReview = (fix: FixItem) =>
+  activity(
+    'read-review',
+    Effect.gen(function* () {
+      const notes = (yield* (yield* GitHub).reviewComments(fix.pullRequest)).filter((note) => note.trusted);
+
+      return yield* renderPrompt('fix', { pullRequest: fix.pullRequest, round: fix.round, review: notes.map(describeReviewLine) });
+    }),
+    Schema.String,
+  );
+
+const checkChanged = (fix: FixItem, worktree: string) =>
+  activity(
+    'check-changed',
+    Effect.gen(function* () {
+      if ((yield* (yield* Git).headSha(worktree)) === fix.reviewedSha) {
+        return yield* new NeedsHuman({ reason: `#${fix.pullRequest}: the author agent committed nothing in answer to review ${fix.round}` });
+      }
+    }),
+  );
+
+const fixPullRequest = (fix: FixItem) =>
+  Effect.gen(function* () {
+    const repo = yield* Repo;
+    const author = yield* authorSession(fix.pullRequest);
+    const session = { sessionId: Option.some(author.sessionId), adapter: Option.some(author.adapter) };
+    const worktree = yield* prepareFix(fix.headRef);
+    const prompt = yield* readReview(fix);
+    const outcome = yield* fixWithAgent(`address-review-${fix.round}`, worktree, prompt, session);
+
+    if (outcome.status === 'needs-clarification') {
+      return yield* new NeedsHuman({ reason: `the author agent needs a person to answer review ${fix.round}:\n\n${outcome.questions ?? outcome.summary}` });
+    }
+
+    yield* checkChanged(fix, worktree);
+    yield* push(`push-fix-${fix.round}`, worktree, fix.headRef);
+    yield* waitForCi(fix.pullRequest, worktree, { ...session, branch: fix.headRef });
+    yield* relabel('hand-back', fix.pullRequest, {
+      remove: [repo.labels.changesRequested],
+      add: repo.labels.needsReview,
+      comment: Option.some(`Addressed review ${fix.round}: ${outcome.summary}`),
+    });
+
+    return `#${fix.pullRequest}: addressed review ${fix.round}`;
+  });
+
+// Resumes the author's session with the review, pushes the fix once CI is
+// green, and hands the pull request back for another review.
+export const fixWorkflow = (item: WorkItem) =>
+  Effect.gen(function* () {
+    const fix = yield* fixItemOf(item);
+
+    return yield* fixPullRequest(fix).pipe(
+      Effect.catchTag('NeedsHuman', (needsHuman) =>
+        Effect.gen(function* () {
+          const repo = yield* Repo;
+          yield* relabel('needs-human', fix.pullRequest, {
+            remove: [repo.labels.changesRequested],
+            add: repo.labels.needsHuman,
+            comment: Option.some(`Chernabog stopped and needs a person: ${needsHuman.reason}`),
+          });
+
+          return yield* needsHuman;
+        }),
+      ),
+    );
+  });

package/src/services.ts

@@ -0,0 +1,273 @@
+// The services a flow, trigger or step can use. Chernabog provides each one;
+// a team can replace any of them with its own layer, and tests can use fakes.
+
+import * as Context from 'effect/Context';
+import type * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+
+import type { AgentError, GitError, GitHubError, UsageError } from './errors.ts';
+import type { Json } from './json.ts';
+
+export const Labels = Schema.Struct({
+  eligible: Schema.String,
+  inProgress: Schema.String,
+  needsReview: Schema.String,
+  changesRequested: Schema.String,
+  approved: Schema.String,
+  needsHuman: Schema.String,
+  needsClarification: Schema.String,
+  stale: Schema.String,
+});
+
+export type Labels = typeof Labels.Type;
+
+export const DEFAULT_LABELS: Labels = {
+  eligible: 'auto:eligible',
+  inProgress: 'auto:in-progress',
+  needsReview: 'auto:needs-review',
+  changesRequested: 'auto:changes-requested',
+  approved: 'auto:approved',
+  needsHuman: 'auto:needs-human',
+  needsClarification: 'auto:needs-clarification',
+  stale: 'auto:stale',
+};
+
+export const Board = Schema.Struct({ projectNumber: Schema.Finite, readyStatus: Schema.String, inProgressStatus: Schema.String });
+
+export type Board = typeof Board.Type;
+
+// configDir none is the agent's default home (~/.claude, ~/.codex).
+export const Account = Schema.Struct({ name: Schema.String, configDir: Schema.Option(Schema.String), expectedEmail: Schema.Option(Schema.String) });
+
+export type Account = typeof Account.Type;
+
+export const Limits = Schema.Struct({
+  // Agent attempts to get the local gate passing before a person takes over.
+  localGateRounds: Schema.Finite,
+  // Pushes to fix red CI before a person takes over.
+  ciRounds: Schema.Finite,
+  // Review rounds on one pull request before a person takes over.
+  reviewRounds: Schema.Finite,
+  // How long a pull request waits for its author's push before it is stale.
+  staleAfter: Schema.Duration,
+  // How long CI may stay pending before a person looks.
+  ciTimeout: Schema.Duration,
+});
+
+export type Limits = typeof Limits.Type;
+
+const Strings = Schema.Array(Schema.String);
+
+// A launcher of your own, from machine config: command templates with
+// {command}, {cwd}, {title} and {handle}.
+export const LauncherCommands = Schema.Struct({ start: Strings, close: Strings, alive: Schema.Option(Strings), attach: Schema.Option(Strings) });
+
+export type LauncherCommands = typeof LauncherCommands.Type;
+
+// Where interactive agent sessions run (orca, tmux, a custom one, or headless
+// for none), which config layer chose it, and a custom launcher's commands.
+export const ResolvedLauncher = Schema.Struct({ name: Schema.String, from: Schema.String, custom: Schema.Option(LauncherCommands) });
+
+export type ResolvedLauncher = typeof ResolvedLauncher.Type;
+
+export const HEADLESS: ResolvedLauncher = { name: 'headless', from: 'default', custom: Option.none() };
+
+// Everything a run knows about the repo it works on, merged from the repo's
+// committed config, the person's override and machine config.
+export const RepoSettings = Schema.Struct({
+  name: Schema.String,
+  slug: Schema.String,
+  path: Schema.String,
+  baseBranch: Schema.String,
+  account: Account,
+  // The adapter that implements, and the account each adapter runs under.
+  agent: Schema.String,
+  agentAccounts: Schema.Record(Schema.String, Account),
+  launcher: ResolvedLauncher,
+  // The adapter a flow asked for in config (flows.<name>.agent), such as a Codex reviewer.
+  flowAgents: Schema.Record(Schema.String, Schema.String),
+  labels: Labels,
+  install: Schema.Option(Schema.String),
+  localGate: Strings,
+  humanOnly: Strings,
+  humanOnlyPaths: Strings,
+  notes: Strings,
+  board: Schema.Option(Board),
+  reviewTrigger: Schema.Option(Schema.String),
+  limits: Limits,
+  // Extra environment for commands run in the repo, such as PATH with its pinned Node.
+  env: Schema.Record(Schema.String, Schema.String),
+  // The trusted copy of the repo's .chernabog/, read from the base branch.
+  configDir: Schema.String,
+});
+
+export type RepoSettings = typeof RepoSettings.Type;
+
+export class Repo extends Context.Service<Repo, RepoSettings>()('@chernabog/sdk/Repo') {}
+
+// One thing a flow works on: an issue, a pull request. `key` identifies it
+// across ticks, so it never has two runs at once. `signals` are events the
+// trigger saw for it this tick, such as "pushed", which wake a waiting run.
+export const WorkItem = Schema.Struct({
+  key: Schema.String,
+  title: Schema.optionalKey(Schema.String),
+  url: Schema.optionalKey(Schema.String),
+  data: Schema.Json,
+  signals: Schema.optionalKey(Schema.Array(Schema.String)),
+  // Only wakes a run already waiting on it; never starts one.
+  wakeOnly: Schema.optionalKey(Schema.Boolean),
+});
+
+export type WorkItem = typeof WorkItem.Type;
+
+export const RunInfo = Schema.Struct({ flow: Schema.String, runId: Schema.String, executionId: Schema.String, item: WorkItem });
+
+export type RunInfo = typeof RunInfo.Type;
+
+export class Run extends Context.Service<Run, RunInfo>()('@chernabog/sdk/Run') {}
+
+export type Issue = {
+  readonly number: number;
+  readonly title: string;
+  readonly body: string;
+  readonly url: string;
+  readonly createdAt: string;
+  readonly labels: ReadonlyArray<string>;
+};
+
+export type Comment = { readonly id: number; readonly author: string; readonly body: string; readonly createdAt: string; readonly trusted: boolean };
+
+// A review summary, or a comment on one line of the diff.
+export type ReviewNote = Comment & { readonly location: Option.Option<{ readonly path: string; readonly line: number }> };
+
+export type PullRequest = {
+  readonly number: number;
+  readonly title: string;
+  readonly body: string;
+  readonly url: string;
+  readonly state: 'open' | 'closed' | 'merged';
+  readonly headRef: string;
+  readonly headSha: string;
+  readonly baseRef: string;
+  readonly labels: ReadonlyArray<string>;
+  readonly author: string;
+};
+
+export type ReviewComment = { readonly path: string; readonly line: number; readonly body: string };
+
+export type NewPullRequest = { readonly head: string; readonly base: string; readonly title: string; readonly body: string };
+
+export type NewReview = { readonly body: string; readonly commitSha: string; readonly comments: ReadonlyArray<ReviewComment> };
+
+export type CiState = { state: 'pending'; waitingOn: Array<string> } | { state: 'green' } | { state: 'red'; failedChecks: Array<string> };
+
+export class GitHub extends Context.Service<
+  GitHub,
+  {
+    // Open issues labelled eligible (and ready on the board, when the repo has one), oldest first.
+    readonly queuedIssues: Effect.Effect<ReadonlyArray<Issue>, GitHubError>;
+    readonly oldestQueued: Effect.Effect<Option.Option<number>, GitHubError>;
+    issue(number: number): Effect.Effect<Issue, GitHubError>;
+    // Comments by the repo's owners, members and collaborators only; anyone can comment on a public repo.
+    trustedComments(number: number): Effect.Effect<ReadonlyArray<Comment>, GitHubError>;
+    comments(number: number): Effect.Effect<ReadonlyArray<Comment>, GitHubError>;
+    comment(number: number, body: string): Effect.Effect<void, GitHubError>;
+    addLabel(number: number, label: string): Effect.Effect<void, GitHubError>;
+    removeLabel(number: number, label: string): Effect.Effect<void, GitHubError>;
+    // Moves an issue to a Status on the repo's project board. Does nothing without a board.
+    moveToStatus(number: number, status: string): Effect.Effect<void, GitHubError>;
+    assignSelf(number: number): Effect.Effect<void, GitHubError>;
+    readonly login: Effect.Effect<string, GitHubError>;
+    branchSha(branch: string): Effect.Effect<Option.Option<string>, GitHubError>;
+    // Whoever creates a branch first owns it: the claim.
+    createBranch(branch: string, sha: string): Effect.Effect<'created' | 'already-exists', GitHubError>;
+    deleteBranch(branch: string): Effect.Effect<void, GitHubError>;
+    pullRequest(number: number): Effect.Effect<PullRequest, GitHubError>;
+    pullRequestForBranch(branch: string): Effect.Effect<Option.Option<PullRequest>, GitHubError>;
+    pullRequestsLabelled(label: string): Effect.Effect<ReadonlyArray<PullRequest>, GitHubError>;
+    openPullRequest(pullRequest: NewPullRequest): Effect.Effect<PullRequest, GitHubError>;
+    ciState(pullRequest: number): Effect.Effect<CiState, GitHubError>;
+    // Changed paths of a pull request, for path rules such as humanOnlyPaths.
+    pullRequestFiles(pullRequest: number): Effect.Effect<ReadonlyArray<string>, GitHubError>;
+    // Recently closed or merged pull requests carrying the label, newest first.
+    closedPullRequestsLabelled(label: string): Effect.Effect<ReadonlyArray<PullRequest>, GitHubError>;
+    // Posts a review as a comment (an account cannot approve its own pull request; labels carry the verdict).
+    review(pullRequest: number, review: NewReview): Effect.Effect<void, GitHubError>;
+    // Review summaries and line comments on a pull request.
+    reviewComments(pullRequest: number): Effect.Effect<ReadonlyArray<ReviewNote>, GitHubError>;
+    // Any other call, for what the service does not cover.
+    request(method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', path: string, body: Option.Option<Json>): Effect.Effect<Json, GitHubError>;
+  }
+>()('@chernabog/sdk/GitHub') {}
+
+export class Git extends Context.Service<
+  Git,
+  {
+    run(args: ReadonlyArray<string>, cwd: string): Effect.Effect<string, GitError>;
+    headSha(cwd: string): Effect.Effect<string, GitError>;
+    // Commits on HEAD that origin/<base> does not have.
+    commitsAhead(cwd: string, base: string): Effect.Effect<number, GitError>;
+    changedFiles(cwd: string, base: string): Effect.Effect<ReadonlyArray<string>, GitError>;
+    push(cwd: string, branch: string): Effect.Effect<void, GitError>;
+    // Brings the checked-out branch up to its remote, fast-forward only.
+    pull(cwd: string, branch: string): Effect.Effect<void, GitError>;
+  }
+>()('@chernabog/sdk/Git') {}
+
+export class Worktree extends Context.Service<
+  Worktree,
+  {
+    // The worktree for a branch, created from origin/<base> the first time and reused after.
+    ensure(branch: string): Effect.Effect<string, GitError>;
+    pathFor(branch: string): string;
+    remove(branch: string): Effect.Effect<void, GitError>;
+    // A detached worktree named `name`, reset to `ref` (fetched first) every call: for reading, such as a review.
+    checkout(name: string, ref: string): Effect.Effect<string, GitError>;
+  }
+>()('@chernabog/sdk/Worktree') {}
+
+export type LaunchDecision = { readonly launch: boolean; readonly reason: string };
+
+export class Usage extends Context.Service<
+  Usage,
+  {
+    // Whether the repo's account has room for one more task.
+    readonly gate: Effect.Effect<LaunchDecision, UsageError>;
+    // The account's logged-in identity; fails when it is not the expected one.
+    readonly checkAccount: Effect.Effect<string, UsageError>;
+  }
+>()('@chernabog/sdk/Usage') {}
+
+export type AgentResult = { readonly sessionId: string; readonly output: Json; readonly costUsd: Option.Option<number> };
+
+export type AgentRequest = {
+  readonly cwd: string;
+  readonly prompt: string;
+  // A stable id per piece of work, so a rerun after a crash resumes the same session.
+  readonly sessionId: string;
+  // Sent instead of `prompt` when the session already exists.
+  readonly resumePrompt: Option.Option<string>;
+  // JSON Schema the agent's final answer must match.
+  readonly outputSchema: Option.Option<Json>;
+  // Another adapter than the repo's own, such as a Codex reviewer.
+  readonly adapter: Option.Option<string>;
+};
+
+export class Agent extends Context.Service<
+  Agent,
+  {
+    run(request: AgentRequest): Effect.Effect<AgentResult, AgentError>;
+    readonly adapters: ReadonlyArray<string>;
+  }
+>()('@chernabog/sdk/Agent') {}
+
+// Writes to the run's log file, which `chernabog logs <run>` prints.
+export class RunLog extends Context.Service<
+  RunLog,
+  {
+    log(line: string): Effect.Effect<void>;
+    step(name: string): Effect.Effect<void>;
+    stepDone(name: string): Effect.Effect<void>;
+  }
+>()('@chernabog/sdk/RunLog') {}