@moo.md/hum 0.3.0 → 0.4.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.
Files changed (67) hide show
  1. package/defaults/hum.json +5 -0
  2. package/defaults/roles/build.md +1 -1
  3. package/defaults/roles/fix.md +1 -1
  4. package/npm-shrinkwrap.json +3297 -0
  5. package/package.json +6 -2
  6. package/release.json +3 -0
  7. package/schema/hum.schema.json +47 -7
  8. package/scripts/eval.ts +21 -5
  9. package/src/adapter-api.ts +3 -1
  10. package/src/adapters/claude-bg.ts +2 -2
  11. package/src/adapters/claude-p.ts +44 -18
  12. package/src/adapters/contract.ts +12 -0
  13. package/src/adapters/fake.ts +5 -0
  14. package/src/adapters/git.ts +61 -9
  15. package/src/adapters/github-client.ts +15 -0
  16. package/src/adapters/github-commits.ts +84 -0
  17. package/src/adapters/github.ts +9 -0
  18. package/src/adapters/guard.ts +1 -0
  19. package/src/adapters/item-file.ts +1 -1
  20. package/src/adapters/markdown.ts +10 -1
  21. package/src/adapters/pull-requests.ts +8 -8
  22. package/src/adapters/registry.ts +3 -6
  23. package/src/adapters/roundup.ts +3 -0
  24. package/src/bytes.ts +1 -0
  25. package/src/cli/service.ts +176 -29
  26. package/src/cli/setup.ts +4 -5
  27. package/src/config/checks.ts +21 -50
  28. package/src/config/load.ts +2 -3
  29. package/src/config/machine.ts +29 -0
  30. package/src/config/refusal.ts +5 -6
  31. package/src/config/schema.ts +23 -7
  32. package/src/config/wake-job.ts +6 -2
  33. package/src/decide/risk.ts +2 -2
  34. package/src/exec.ts +10 -0
  35. package/src/index.ts +1 -1
  36. package/src/loop/records.ts +8 -1
  37. package/src/measure/rate.ts +14 -0
  38. package/src/publish/bundle.ts +128 -0
  39. package/src/publish/handoff.ts +107 -0
  40. package/src/publish/handover.ts +182 -0
  41. package/src/publish/intents.ts +61 -0
  42. package/src/publish/publisher.ts +259 -0
  43. package/src/publish/wake.ts +78 -0
  44. package/src/service/ci-state.ts +99 -0
  45. package/src/service/plugins.ts +137 -0
  46. package/src/service/wake.ts +3 -1
  47. package/src/service/workflows.ts +122 -28
  48. package/src/setup/propose.ts +17 -4
  49. package/src/setup/prove.ts +3 -3
  50. package/src/setup/write.ts +2 -2
  51. package/src/state/items.ts +17 -8
  52. package/src/state/open.ts +20 -6
  53. package/src/state/records.ts +7 -0
  54. package/src/state/runs.ts +5 -0
  55. package/src/state/saved.ts +17 -2
  56. package/src/worker/base-check.ts +41 -13
  57. package/src/worker/checks.ts +3 -2
  58. package/src/worker/evidence.ts +72 -0
  59. package/src/worker/kind.ts +4 -7
  60. package/src/worker/land.ts +173 -81
  61. package/src/worker/merged.ts +20 -8
  62. package/src/worker/open.ts +33 -17
  63. package/src/worker/questions.ts +16 -8
  64. package/src/worker/signed-push.ts +167 -0
  65. package/src/worker/thin-path.ts +245 -133
  66. package/src/worker/worker.ts +50 -9
  67. package/surface.json +185 -56
@@ -6,10 +6,8 @@ import { type AnyActor, createActor, createAsyncLogic } from "xstate";
6
6
  import type { Holder, Item, ItemId, Question, Questions, ThreadEntry, WorkSource } from "../adapter-api.ts";
7
7
  import { type Finished, type Runner, type RunOutcome, hasSucceeded } from "../adapters/claude-p.ts";
8
8
  import { configuredModelCall, type ModelCall } from "../adapters/model-call.ts";
9
- import { ADAPTER_API_VERSION } from "../adapter-api.ts";
10
- import { onceCalls } from "../adapters/once.ts";
11
9
  import { visibleText } from "../adapters/marked.ts";
12
- import { type Git, gitIn, identityEnv, PATCH, push } from "../adapters/git.ts";
10
+ import { type Git, gitIn, PATCH, withConfigPinned } from "../adapters/git.ts";
13
11
  import type { PullRequests } from "../adapters/pull-requests.ts";
14
12
  import { pickTier } from "../config/checks.ts";
15
13
  import type { Config } from "../config/load.ts";
@@ -22,20 +20,26 @@ import { persistedSnapshot } from "../state/items.ts";
22
20
  import type { State } from "../state/open.ts";
23
21
  import { HOUR_MS, SECOND_MS } from "../time.ts";
24
22
  import { checksTimeoutMs, runChecks } from "./checks.ts";
25
- import { BASE_CONTENDED, changeOn, type LandContext, land, placementOf, prepareLanding, type ReviewOutcome, unpushed } from "./land.ts";
23
+ import { BASE_CONTENDED, changeOn, declaredChange, placementOf, rebaseOnto, type ReviewOutcome, tierOf } from "./land.ts";
26
24
  import { OWNER_APPROVAL } from "../decide/merge.ts";
27
25
  import { askDecision, askedQuestion, isWaitQuestion, PLAIN_QUESTIONS, type PlainQuestion, RunReason } from "../decide/question.ts";
28
26
  import type { Stage } from "../decide/answer.ts";
29
27
  import { type ItemText, reviewInput } from "../decide/review.ts";
30
28
  import { forgetProgress, keepKind, kindAnswered, pickKind } from "./kind.ts";
31
29
  import { settleAnswers } from "./answers.ts";
32
- import { queueQuestion, releaseQuestions } from "./questions.ts";
30
+ import { queueQuestion } from "./questions.ts";
33
31
  import { answerToLatest, latestQuestionAt, openQuestion } from "./thread.ts";
34
32
  import { memorySection, readMemory, rulesUsed } from "../loop/memory.ts";
35
33
  import { proveCheckItem } from "../loop/prove-item.ts";
36
34
  import { tallyOf } from "./tally.ts";
37
35
  import { decideProse } from "./prose-run.ts";
38
- import { footprintOf, type PrefixGate } from "./scheduler.ts";
36
+ import { type PrefixGate } from "./scheduler.ts";
37
+ import { evidenceRef, keepEvidence } from "./evidence.ts";
38
+ import { Outbox } from "../publish/intents.ts";
39
+ import { type GatherTrust, type PassOutbox, type Publisher, publishPass } from "../publish/publisher.ts";
40
+ import { PUBLISH_DIR as PUBLISH_REPO } from "../state/open.ts";
41
+ import type { GitHubCommits } from "../adapters/github-commits.ts";
42
+ import { repoFromRemote } from "../adapters/github.ts";
39
43
 
40
44
  /** How long a claim lasts unless its holder renews it. */
41
45
  export const claimTtlMs = (config: Config): number => config.hum.claimExpirySeconds * SECOND_MS;
@@ -49,8 +53,13 @@ export const DEFAULT_BASE = "main";
49
53
 
50
54
  export const runBranch = ({ runBranchPrefix }: Naming, id: string): string => `${runBranchPrefix}${id}`;
51
55
 
52
- /** What the agent run hands back besides its commit. */
53
- export const RUN_SCHEMA = jsonSchemaOf(z.object({ status: z.enum(["done", "needs-owner"]), question: z.string().optional(), plan: z.string().optional(), reason: RunReason.optional(), memoryUsed: z.array(z.int().positive()).optional() }));
56
+ /** The pull request a build or fix run writes for the branch's whole change, and the one file of evidence it saved, by name. */
57
+ const PullRequestWritten = z.object({ title: z.string().min(1), body: z.string().min(1), evidence: z.string().min(1).optional() });
58
+
59
+ type PullRequestWritten = z.infer<typeof PullRequestWritten>;
60
+
61
+ /** What the agent run hands back besides the change it leaves in the working tree. */
62
+ export const RUN_SCHEMA = jsonSchemaOf(z.object({ status: z.enum(["done", "needs-owner"]), question: z.string().optional(), plan: z.string().optional(), reason: RunReason.optional(), memoryUsed: z.array(z.int().positive()).optional(), pullRequest: PullRequestWritten.optional() }));
54
63
 
55
64
  /** The comment that carries a run's plan on the item's thread, so the next run reads it. */
56
65
  export const PLAN_MARK = "hum plan:";
@@ -83,10 +92,14 @@ export type ThinPathOptions = {
83
92
  readonly gate?: PrefixGate;
84
93
  /** The remote's pull requests and branch rules, for a remote on GitHub. */
85
94
  readonly pulls?: PullRequests;
95
+ /** The remote's branches through GitHub's API, which signs the commits it makes, for a remote on GitHub. */
96
+ readonly commits?: GitHubCommits;
86
97
  /** The names, never the values, of the variables the runs have; a missing secret is checked against them. */
87
98
  readonly runnerVariables: ReadonlySet<string>;
88
99
  /** A fresh id for each run's session. */
89
100
  readonly newSessionId: () => string;
101
+ /** Applies a pass's outbox, given what the pass's own work came to; by default publish runs in this process once the pass's runs ended. */
102
+ readonly publish?: (pass: PassOutbox, worked: ThinResult) => Promise<ThinResult | undefined>;
90
103
  /** False while the worker drains for an update: a finished change is saved and pushed, and the next worker lands it under the config it starts with. */
91
104
  readonly mayLand?: () => boolean;
92
105
  };
@@ -131,7 +144,7 @@ const isApprovalWait = (kind: Kind, state: string | undefined): boolean => state
131
144
  /** Where an item saved in an owner wait stands for an answer: waiting on approval where the state takes the owner's approval, else waiting. */
132
145
  export const ownerWaitStage = (kind: Kind, state: string | undefined): Stage => (isApprovalWait(kind, state) ? "approval" : "waiting");
133
146
 
134
- const Wants = z.looseObject({ status: z.string().optional(), question: z.string().optional(), plan: z.string().optional(), reason: RunReason.optional() });
147
+ const Wants = z.looseObject({ status: z.string().optional(), question: z.string().optional(), plan: z.string().optional(), reason: RunReason.optional(), pullRequest: PullRequestWritten.optional() });
135
148
 
136
149
  /** The kind as it stood at an earlier machine version, kept by `rememberKinds`, so a saved item restores across a change. */
137
150
  const earlierKinds = (state: State, kind: Kind) => (machineVersion: string) => state.kinds.get(`${kind.machine.id}@${machineVersion}`);
@@ -181,12 +194,23 @@ export const runThinPath = async (o: ThinPathOptions): Promise<ThinResult> => {
181
194
  return result;
182
195
  };
183
196
 
184
- const pass = async (o: ThinPathOptions): Promise<ThinResult> => {
185
- const base = o.base ?? DEFAULT_BASE;
186
- const id = o.itemId ?? (await o.workSource.listReady())[0]?.id;
187
-
188
- if (id === undefined) return { outcome: "idle" };
197
+ /**
198
+ * What a pass settles before any clone or run, all from the work source and saved state: the claim, the owner's
199
+ * answers and the item's kind. Gather runs it apart from the work in CI; a pass that runs it again on what gather
200
+ * settled writes nothing.
201
+ */
202
+ export type Gathered = {
203
+ readonly item: Item;
204
+ readonly kindName: string;
205
+ readonly kind: Kind;
206
+ readonly judge: ModelCall;
207
+ /** The item has a saved machine state to go on from. */
208
+ readonly onSnapshot: boolean;
209
+ readonly asking: boolean;
210
+ readonly answered: ReturnType<typeof answerTo>;
211
+ };
189
212
 
213
+ export const gatherItem = async (o: ThinPathOptions, id: ItemId): Promise<Gathered | ThinResult> => {
190
214
  // A parked item stays parked until the owner acts: its file still says ready, and a rerun would spend the same tokens again.
191
215
  const parked = o.state.parked.get(id);
192
216
 
@@ -230,13 +254,32 @@ const pass = async (o: ThinPathOptions): Promise<ThinResult> => {
230
254
 
231
255
  const settled = named ?? known;
232
256
  const kindContext = { ...o, judge, now };
233
- const kindName = settled ? settled.kind : await keepKind(kindContext, item, await pickKind(kindContext, item));
257
+ const kindName = settled ? settled.kind : keepKind(kindContext, item, await pickKind(kindContext, item));
234
258
  const kind = kindNamed(o.config, kindName);
235
259
  const asking = isWaitingOnOwner(kind, at);
236
260
  const answered = asking || !onSnapshot ? answerTo(item) : undefined;
237
261
 
238
262
  if (asking && answered === undefined) return { outcome: "waiting", item: id };
239
263
 
264
+ /* The owner's rejection at the approval wait ends the landing saved for it, so only a new change lands. */
265
+ if (isApprovalWait(kind, at) && answered !== undefined && answered.option !== OWNER_APPROVAL) o.state.landings.remove(id);
266
+
267
+ return { item, kindName, kind, judge, onSnapshot, asking, answered };
268
+ };
269
+
270
+ export const isGathered = (gathered: Gathered | ThinResult): gathered is Gathered => "kindName" in gathered;
271
+
272
+ const pass = async (o: ThinPathOptions): Promise<ThinResult> => {
273
+ const base = o.base ?? DEFAULT_BASE;
274
+ const id = o.itemId ?? (await o.workSource.listReady())[0]?.id;
275
+
276
+ if (id === undefined) return { outcome: "idle" };
277
+
278
+ const gathered = await gatherItem(o, id);
279
+
280
+ if (!isGathered(gathered)) return gathered;
281
+
282
+ const { item, kindName, kind, judge, onSnapshot, asking, answered } = gathered;
240
283
  const landing = o.state.landings.get(id);
241
284
  /** Nothing saved is left to go on from: a new item, one that moved to another kind, or one the owner ran again. */
242
285
  const isFresh = !onSnapshot && landing === undefined;
@@ -246,24 +289,38 @@ const pass = async (o: ThinPathOptions): Promise<ThinResult> => {
246
289
 
247
290
  if (taken === undefined) return { outcome: "lost", item: id };
248
291
 
249
- const { folder: clone } = taken;
250
- const { commitIdentity } = o.config.hum;
251
- /** The agent's own commits take the owner's identity too: a fresh clone holds none of the repo's local git config. */
252
- const env = { ...identityEnv(commitIdentity), ...taken.env };
253
- const git = gitIn(clone, { identity: commitIdentity, timeoutMs });
254
- const g = (args: readonly string[]): Promise<string> => git.raw(args);
292
+ const { folder: clone, env } = taken;
255
293
 
256
294
  try {
257
- await onRunBranch(git, { branch, restartAt: isFresh ? `origin/${base}` : undefined });
295
+ const checkedOut = gitIn(clone, { identity: o.config.hum.commitIdentity, timeoutMs });
296
+ const gathered = await gatheredIn(checkedOut, { base, branch });
258
297
 
259
- const driven: Driven = { ...o, base, dir: o.dir ?? o.config.hum.itemsDir, kindName, kind, judge, id, item, branch, clone, env, g, git, answered, resume: asking, restarted: isFresh };
298
+ await onRunBranch(checkedOut, { branch, restartAt: isFresh ? gathered.baseSha : undefined });
260
299
 
261
- // A change already finished lands again from its pushed branch; no run is spent on it.
262
- const result = park(o, landing ? await landAgain(driven) : await drive(driven));
300
+ /** From here a run may have written in the folder, so hum's git runs only while the config it read stands. */
301
+ const git = await withConfigPinned(checkedOut);
302
+ const g = (args: readonly string[]): Promise<string> => git.raw(args);
263
303
 
264
- if (result.outcome === "moved") forgetProgress(o.state, id);
304
+ /** Where a run saves its one picture or video of the change, outside the clone so nothing commits it. */
305
+ const evidence = mkdtempSync(join(o.workDir ?? tmpdir(), "hum-evidence-"));
265
306
 
266
- return result;
307
+ try {
308
+ const outbox = new Outbox(id);
309
+ const driven: Driven = { ...o, base, baseSha: gathered.baseSha, dir: o.dir ?? o.config.hum.itemsDir, kindName, kind, judge, id, item, branch, clone, evidence, env, g, git, answered, resume: asking, restarted: isFresh, outbox };
310
+
311
+ /* A change already finished lands again from its pushed branch; no run is spent on it. One saved at the owner's approval wait goes on from the wait. */
312
+ const worked = landing && !asking ? await handToPublish(driven) : await drive(driven);
313
+ const published = await (o.publish ?? publishInProcess(o, judge, gathered))({ item: id, intents: outbox.drain(), bundle: await bundleOf(git, { branch, item: id, gathered, folder: evidence }) }, worked);
314
+ const result = park(o, published ?? worked);
315
+
316
+ if (result.outcome === "moved") forgetProgress(o.state, id);
317
+
318
+ if (result.outcome === "merged") o.state.items.remove(id);
319
+
320
+ return result;
321
+ } finally {
322
+ rmSync(evidence, { recursive: true, force: true });
323
+ }
267
324
  } finally {
268
325
  await taken.giveBack();
269
326
  }
@@ -332,10 +389,16 @@ type Driven = ThinPathOptions & {
332
389
  readonly item: Item;
333
390
  readonly branch: string;
334
391
  readonly clone: string;
392
+ /** The folder a run saves its evidence in. */
393
+ readonly evidence: string;
335
394
  readonly env: Readonly<Record<string, string>>;
336
395
  readonly g: (args: readonly string[]) => Promise<string>;
337
396
  readonly git: Git;
338
397
  readonly answered: Answered | undefined;
398
+ /** The base commit the pass started from, which a landing is checked on. */
399
+ readonly baseSha: string;
400
+ /** What the pass asks publish to do. */
401
+ readonly outbox: Outbox;
339
402
  /** Restore the saved owner-wait snapshot instead of starting the machine. */
340
403
  readonly resume: boolean;
341
404
  /** The run branch starts again at the base: earlier work on the item, and the plan written for it, are gone. */
@@ -359,7 +422,6 @@ const drive = async (d: Driven): Promise<ThinResult> => {
359
422
  let cause = "";
360
423
  let handled = "";
361
424
  let pending: Pending | undefined;
362
- let approvedByOwner = false;
363
425
  let actor: AnyActor;
364
426
 
365
427
  const stuckCause = (): string | undefined => cause || lastFailure.slice(0, CARD_EXCERPT) || undefined;
@@ -371,17 +433,7 @@ const drive = async (d: Driven): Promise<ThinResult> => {
371
433
  };
372
434
 
373
435
  /** A plan or build is placed by the files its item declares; a fix or review by the branch's diff so far. */
374
- const tierFor = async (purpose: Purpose) => {
375
- const declared = { paths: footprintOf(item) ?? [], size: 0, loosened: false, pinChanged: false };
376
- const change = PLACED_BY_DIFF[purpose] ? await changeOn(landContext(d)) : declared;
377
- const { placement } = await placementOf(landContext(d), change);
378
- const row = pickTier(kind, { purpose, level: placement.level.name, size: "small" });
379
-
380
- if (!row) throw new Error(`the ${d.kindName} table has no ${purpose} row`);
381
-
382
- return { model: config.hum.models[row.tier], effort: row.effort };
383
- };
384
-
436
+ const tierFor = async (purpose: Purpose) => tierOf(placing(d), kind, purpose, PLACED_BY_DIFF[purpose] ? await changeOn(placing(d)) : declaredChange(item));
385
437
 
386
438
  const branchDiff = (): Promise<string> => g(["diff", ...PATCH, `origin/${base}...HEAD`]);
387
439
 
@@ -391,7 +443,8 @@ const drive = async (d: Driven): Promise<ThinResult> => {
391
443
  const parts = [
392
444
  roleOf(config, purpose),
393
445
  `# Item ${id}: ${item.title}\n\n${item.body}`,
394
- `Work on the branch ${branch}. Commit the change when it is whole. End with the JSON {"status":"done"}, or {"status":"needs-owner","question":…,"plan":…} when only the owner can answer.`,
446
+ `Work on the branch ${branch}. Leave the change in the working tree and make no commit: hum commits every file there once you are done. End with the JSON {"status":"done"}, or {"status":"needs-owner","question":…,"plan":…} when only the owner can answer.`,
447
+ `With "done", give "pullRequest": the title and body of the pull request that lands the branch's whole change, written as this repo's own rules ask a pull request to be; hum commits your change under its title. Where one screenshot or short video shows the change at work, save that one file in ${d.evidence}, never in the repo, and give its file name as "pullRequest.evidence".`,
395
448
  ];
396
449
 
397
450
  if (plan) parts.push(`## The approved plan (${plan.hash})\n${JSON.stringify(plan.plan, null, 2)}`);
@@ -404,7 +457,7 @@ const drive = async (d: Driven): Promise<ThinResult> => {
404
457
  parts.push(`## The owner answered\nQuestion: ${d.answered.question}\nAnswer: ${d.answered.answer}\n\n${soFar}`);
405
458
  }
406
459
 
407
- if (purpose === "fix") parts.push(`## What to fix\n${lastFailure.slice(-config.hum.failureTail)}\nFix the cause and commit.`);
460
+ if (purpose === "fix") parts.push(`## What to fix\n${lastFailure.slice(-config.hum.failureTail)}\nFix the cause.`);
408
461
 
409
462
  return parts.join("\n\n");
410
463
  };
@@ -475,8 +528,8 @@ const drive = async (d: Driven): Promise<ThinResult> => {
475
528
  /** The owner is asked, or the run's choice stands and is listed under the choices made without them. */
476
529
  const settleNeed = async (wants: z.infer<typeof Wants>): Promise<{ asked: Pending } | { chose: string }> => {
477
530
  const reason = wants.reason ?? { kind: "unsure" as const };
478
- const change = await changeOn(landContext(d));
479
- const { placement } = await placementOf(landContext(d), change);
531
+ const change = await changeOn(placing(d));
532
+ const { placement } = await placementOf(placing(d), change);
480
533
 
481
534
  const decision = askDecision(reason, {
482
535
  runnerVariables: d.runnerVariables,
@@ -488,9 +541,7 @@ const drive = async (d: Driven): Promise<ThinResult> => {
488
541
  if (decision.action === "ask") return { asked: { ...askedQuestion({ reason, confirmed: decision.confirmed, runsWords: wants.question }), plan: wants.plan ?? "" } };
489
542
 
490
543
  const text = `Chose "${decision.choice}" over ${decision.over.filter((word) => word !== decision.choice).join(", ")} without you.`;
491
- const calls = onceCalls({ apiVersion: ADAPTER_API_VERSION, workSource: d.workSource, questions: d.questions }, state.ops, { run: "decide", attempt: state.runs.list(id).length });
492
-
493
- await calls.questions?.decide(id, text);
544
+ await d.outbox.calls({ run: "decide", attempt: state.runs.list(id).length }).decide(id, text);
494
545
  state.choices.put(`${id}@${text}`, { item: id, text, at: d.now() });
495
546
 
496
547
  return { chose: text };
@@ -511,7 +562,17 @@ const drive = async (d: Driven): Promise<ThinResult> => {
511
562
 
512
563
  const wants = Wants.safeParse(outcome.structured).data;
513
564
 
514
- if (wants?.status !== "needs-owner") break;
565
+ if (wants?.status !== "needs-owner") {
566
+ if (!wants?.pullRequest) throw failed(`the ${purpose} run ended without the pull request title hum commits its change under`);
567
+
568
+ await keepPullRequest(d, wants.pullRequest);
569
+
570
+ if (!(await commitRun(d.git, { since: before, subject: wants.pullRequest.title }))) throw failed(`the ${purpose} run succeeded and changed nothing`);
571
+
572
+ return;
573
+ }
574
+
575
+ await commitRun(d.git, { since: before, subject: `hum: ${id} so far` });
515
576
 
516
577
  const settled = await settleNeed(wants);
517
578
 
@@ -519,9 +580,6 @@ const drive = async (d: Driven): Promise<ThinResult> => {
519
580
 
520
581
  chosen.push(settled.chose);
521
582
  }
522
-
523
- // Done is a new commit on the branch, not the run's word.
524
- if ((await g(["rev-parse", "HEAD"])).trim() === before) throw failed(`the ${purpose} run succeeded and committed nothing`);
525
583
  },
526
584
  });
527
585
 
@@ -575,7 +633,7 @@ const drive = async (d: Driven): Promise<ThinResult> => {
575
633
 
576
634
  PICKED.get(pick.event)?.(pick, models);
577
635
 
578
- if (pick.event === SPLIT) return result.resolve(await split(d, pick.parts, () => actor.send({ type: SPLIT })));
636
+ if (pick.event === SPLIT) return result.resolve(await split(d, pick.parts));
579
637
 
580
638
  actor.send({ type: pick.event });
581
639
  },
@@ -607,14 +665,13 @@ const drive = async (d: Driven): Promise<ThinResult> => {
607
665
  if (isWaitingOnOwner(kind, value)) {
608
666
  const note = pending ?? { question: { text: "The run stopped for the owner." }, plain: "unsure" as const, plan: "" };
609
667
 
610
- if (!(await isStillMine(d))) return result.resolve({ outcome: "lost", item: id });
611
-
612
- const stopped = await handOff(d, isApprovalWait(kind, value) ? approvalQuestion(note) : note);
668
+ const approval = isApprovalWait(kind, value);
669
+ const stopped = await handOff(d, approval ? approvalQuestion(note) : note, { approval });
613
670
 
614
671
  return result.resolve(stopped ?? { outcome: "asked", item: id, detail: note.question.text });
615
672
  }
616
673
 
617
- if (value === "merging") return result.resolve(await merge(d, { onMerged: () => actor.send({ type: "merged" }), ownerApproved: approvedByOwner }));
674
+ if (value === "merging") return result.resolve(await merge(d));
618
675
  };
619
676
 
620
677
  actor.subscribe((snapshot) => {
@@ -636,8 +693,6 @@ const drive = async (d: Driven): Promise<ThinResult> => {
636
693
  if (d.answered && d.resume) {
637
694
  const resume = resumeEvent(actor.getSnapshot(), d.answered);
638
695
 
639
- approvedByOwner = resume === OWNER_APPROVED;
640
-
641
696
  if (resume === OWNER_REJECTED) lastFailure = d.answered.answer;
642
697
 
643
698
  actor.send({ type: resume });
@@ -646,6 +701,31 @@ const drive = async (d: Driven): Promise<ThinResult> => {
646
701
  return result.promise.finally(() => actor.stop());
647
702
  };
648
703
 
704
+ /** Saves the pull request a run wrote, with its evidence kept where GitHub shows it; evidence an earlier run kept stays when this run names none. */
705
+ /**
706
+ * Commits what a build or fix run left in the working tree as one commit on `since`, under `subject`, by the owner's
707
+ * commitIdentity, and says whether there was a change to commit. A commit the run made anyway, and the work so far
708
+ * hum committed when the run asked, are folded into it, so the run's whole change is one commit of hum's.
709
+ */
710
+ const commitRun = async (git: Git, { since, subject }: { readonly since: string; readonly subject: string }): Promise<boolean> => {
711
+ await git.raw(["reset", "-q", "--soft", since]);
712
+ await git.raw(["add", "-A"]);
713
+
714
+ if ((await git.run(["diff", "--cached", "--quiet"])).code === 0) return false;
715
+
716
+ await git.raw(["commit", "-q", "--no-verify", "-m", subject]);
717
+
718
+ return true;
719
+ };
720
+
721
+ const keepPullRequest = async (d: Driven, { title, body, evidence }: PullRequestWritten): Promise<void> => {
722
+ const kept = evidence === undefined ? d.state.pullRequests.get(d.id)?.evidence : await keepEvidence({ git: d.git, folder: d.evidence, file: evidence, item: d.id, repo: repoFromRemote(d.remote) });
723
+
724
+ if (evidence !== undefined && kept !== undefined && "url" in kept) d.outbox.add({ kind: "keep-evidence" });
725
+
726
+ d.state.pullRequests.put(d.id, { item: d.id, title, body, evidence: kept });
727
+ };
728
+
649
729
  /** What a run left for the owner: the question, the plain one it falls back to, and the plan so far. */
650
730
  type Pending = { readonly question: Question; readonly plain: PlainQuestion; readonly plan: string };
651
731
 
@@ -675,10 +755,13 @@ const SPLIT = "needs-split";
675
755
  /** What a run reads from its config: the settings and the role files. */
676
756
  export type RunConfig = Pick<Config, "hum" | "roles">;
677
757
 
758
+ /** The role file of a run's purpose, then the skills its role names, so the run reaches for them. */
678
759
  const roleOf = (config: RunConfig, purpose: Purpose): string => {
679
760
  const role = config.hum.roles[purpose];
761
+ const text = ((role && config.roles[role.file]) ?? "").trim();
762
+ const skills = role?.skills ?? [];
680
763
 
681
- return ((role && config.roles[role.file]) ?? "").trim();
764
+ return skills.length === 0 ? text : [text, `Use these skills with the Skill tool where they apply: ${skills.join(", ")}.`].filter(Boolean).join("\n\n");
682
765
  };
683
766
 
684
767
 
@@ -714,15 +797,19 @@ const pauseOf = (id: string, outcome: Paused): ThinResult => {
714
797
  }
715
798
  };
716
799
 
717
- /** A fresh review run at landing, for a level that asks for one: it reads only the item and the diff, and its verdict is saved. */
718
- const reviewAtLanding =
719
- (d: Driven) =>
800
+ /**
801
+ * A fresh review at landing, for a level that asks for one: a model call with no tool, which reads only the item and
802
+ * the diff, and whose verdict is saved. Publish makes it, so no verdict comes from the side that wrote the change.
803
+ */
804
+ export const reviewRunOf =
805
+ (o: Pick<ThinPathOptions, "runner" | "state" | "config">, item: Item, kindName: string) =>
720
806
  async ({ head, diff, level }: { head: string; diff: string; level: string }): Promise<ReviewOutcome> => {
721
- const row = pickTier(d.kind, { purpose: "review", level, size: "small" });
807
+ const kind = kindNamed(o.config, kindName);
808
+ const row = pickTier(kind, { purpose: "review", level, size: "small" });
722
809
 
723
- if (!row) throw new Error(`the ${d.kindName} table has no review row`);
810
+ if (!row) throw new Error(`the ${kindName} table has no review row`);
724
811
 
725
- const tally = tallyOf(d.state, d.id);
812
+ const tally = tallyOf(o.state, item.id);
726
813
 
727
814
  let halt: (result: ThinResult) => void = () => {};
728
815
 
@@ -732,7 +819,7 @@ const reviewAtLanding =
732
819
 
733
820
  /** A run with no answer never settles, as AnswerRun requires; the review comes to `halted` instead. */
734
821
  const run = async (prompt: string, schema: JsonSchema): Promise<Finished> => {
735
- const outcome = await d.runner.run({ prompt, cwd: tmpdir(), model: d.config.hum.models[row.tier], effort: row.effort, schema, signal: d.signal, tokenCap: d.kind.tokenCap.tokens - tally.sinceAnswer() });
822
+ const outcome = await o.runner.run({ prompt, cwd: tmpdir(), call: "judgment", model: o.config.hum.models[row.tier], effort: row.effort, schema, tokenCap: kind.tokenCap.tokens - tally.sinceAnswer() });
736
823
 
737
824
  if (outcome.kind === "finished") {
738
825
  tally.spend(outcome.tokens);
@@ -742,15 +829,15 @@ const reviewAtLanding =
742
829
 
743
830
  if (outcome.kind === "over-cap") tally.spend(outcome.tokens);
744
831
 
745
- halt(isPaused(outcome) ? pauseOf(d.id, outcome) : { outcome: "review", item: d.id, detail: `the review run passed the item's token cap (${d.kind.tokenCap.tokens}) at ${tally.sinceAnswer()} tokens` });
832
+ halt(isPaused(outcome) ? pauseOf(item.id, outcome) : { outcome: "review", item: item.id, detail: `the review run passed the item's token cap (${kind.tokenCap.tokens}) at ${tally.sinceAnswer()} tokens` });
746
833
 
747
834
  return new Promise<never>(() => {});
748
835
  };
749
836
 
750
- const decided = decideProse({ purpose: "review", prompt: PROSE_PROMPTS.review(d.config, d.item, diff), diff, model: d.config.hum.models[row.tier], run }).then(({ pick, models }): ReviewOutcome => {
751
- const verdict = verdictOf({ id: d.id, head, pick, models });
837
+ const decided = decideProse({ purpose: "review", prompt: PROSE_PROMPTS.review(o.config, item, diff), diff, model: o.config.hum.models[row.tier], run }).then(({ pick, models }): ReviewOutcome => {
838
+ const verdict = verdictOf({ id: item.id, head, pick, models });
752
839
 
753
- d.state.verdicts.put(d.id, verdict);
840
+ o.state.verdicts.put(item.id, verdict);
754
841
 
755
842
  return { verdict };
756
843
  });
@@ -758,13 +845,64 @@ const reviewAtLanding =
758
845
  return Promise.race([decided, halted]);
759
846
  };
760
847
 
848
+ /** Publish's root for the passes of `o`: the worker's own adapters, its claim, and a repo of publish's own beside the state. */
849
+ export const publisherOf = (
850
+ o: Pick<ThinPathOptions, "state" | "config" | "workSource" | "questions" | "pulls" | "commits" | "runner" | "holder" | "now" | "remote" | "base" | "dir">,
851
+ judge: ModelCall,
852
+ mergesBefore?: number,
853
+ ): Publisher => ({
854
+ state: o.state,
855
+ config: o.config,
856
+ workSource: o.workSource,
857
+ questions: o.questions,
858
+ pulls: o.pulls,
859
+ commits: o.commits,
860
+ judge,
861
+ reviewRun: (item, kindName) => reviewRunOf(o, item, kindName),
862
+ kindOf: (item) => o.state.itemKinds.get(item.id)?.kind ?? o.config.hum.fallbackKind,
863
+ holder: o.holder,
864
+ now: o.now,
865
+ remote: o.remote,
866
+ base: o.base ?? DEFAULT_BASE,
867
+ dir: o.dir ?? o.config.hum.itemsDir,
868
+ repo: join(o.state.dir, PUBLISH_REPO),
869
+ mergesBefore,
870
+ });
871
+
872
+ /** Publishes a pass in the worker's own process, against what the pass's checkout saw before any run. */
873
+ const publishInProcess =
874
+ (o: ThinPathOptions, judge: ModelCall, gathered: GatherTrust) =>
875
+ (pass: PassOutbox): Promise<ThinResult | undefined> =>
876
+ publishPass(publisherOf(o, judge), gathered, pass);
877
+
878
+ /** What the checkout saw before any run: the base commit and the run branch's head on the remote. */
879
+ const gatheredIn = async (git: Git, { base, branch }: { readonly base: string; readonly branch: string }): Promise<GatherTrust> => ({
880
+ baseSha: (await git.raw(["rev-parse", `origin/${base}`])).trim(),
881
+ heads: Object.fromEntries((await git.raw(["ls-remote", "--heads", "origin", branch])).split("\n").flatMap((line) => line.split("\t", 1).filter(Boolean).map((sha) => [branch, sha] as const))),
882
+ });
883
+
884
+ /** The bundle of the refs a pass made, the run branch and its evidence, with only what gather did not see; undefined when the pass made nothing new. */
885
+ const bundleOf = async (git: Git, { branch, item, gathered, folder }: { readonly branch: string; readonly item: string; readonly gathered: GatherTrust; readonly folder: string }): Promise<string | undefined> => {
886
+ const known = [gathered.baseSha, ...Object.values(gathered.heads)];
887
+ const refs = (await Promise.all([`refs/heads/${branch}`, evidenceRef(item)].map(async (ref) => ((await git.run(["rev-parse", "--verify", "--quiet", ref])).code === 0 ? [ref] : [])))).flat();
888
+ const fresh = refs.length === 0 ? 0 : Number((await git.raw(["rev-list", "--count", ...refs, "--not", ...known])).trim());
889
+
890
+ if (fresh === 0) return undefined;
891
+
892
+ const file = join(folder, "pass.bundle");
893
+
894
+ await git.raw(["bundle", "create", "-q", file, ...refs, "--not", ...known]);
895
+
896
+ return file;
897
+ };
898
+
761
899
  /** Files each part of a split item as its own item, then lands the item as done with no change of its own. */
762
- const split = async (d: Driven, parts: readonly string[], onMerged: () => void): Promise<ThinResult> => {
763
- const calls = onceCalls({ apiVersion: ADAPTER_API_VERSION, workSource: d.workSource, questions: d.questions }, d.state.ops, { run: SPLIT, attempt: 0 });
900
+ const split = async (d: Driven, parts: readonly string[]): Promise<ThinResult> => {
901
+ const writes = d.outbox.calls({ run: SPLIT, attempt: 0 });
764
902
 
765
- for (const title of parts) await calls.workSource?.fileFollowUp(d.id, { title, body: `Split from ${d.id}: ${d.item.title}` });
903
+ for (const title of parts) await writes.fileFollowUp(d.id, { title, body: `Split from ${d.id}: ${d.item.title}` });
766
904
 
767
- return merge(d, { onMerged });
905
+ return merge(d);
768
906
  };
769
907
 
770
908
  /** The owner-review wait asks for the change's approval, whatever the review run wrote. */
@@ -774,63 +912,39 @@ const approvalQuestion = ({ question, plan }: Pending): Pending => ({
774
912
  plan,
775
913
  });
776
914
 
777
- /** Push the work branch, put the plan on the item, queue the question for room under the daily cap, and end. Each write runs once per key. A push that did not land ends the pass with its result instead. */
778
- const handOff = async (d: Driven, { question, plain, plan }: Pending): Promise<ThinResult | undefined> => {
779
- const { state, id, g, branch, workSource, questions, git } = d;
915
+ /**
916
+ * Hands the work branch and the plan to publish, queues the question for room under the daily cap, and ends. At the
917
+ * owner's approval wait publish saves the change as the item's landing before it asks, so the approval the owner
918
+ * gives counts for this change alone.
919
+ */
920
+ const handOff = async (d: Driven, { question, plain, plan }: Pending, { approval }: { readonly approval: boolean }): Promise<undefined> => {
921
+ const { state, id } = d;
780
922
  const attempt = state.runs.list(id).length;
781
- const key = (op: string) => ({ itemId: id, run: "ask", attempt, op });
782
- const calls = onceCalls({ apiVersion: ADAPTER_API_VERSION, workSource, questions }, state.ops, { run: "ask", attempt });
783
-
784
- const pushed = await state.ops.once(key("push-branch"), {
785
- holds: async () => (await g(["ls-remote", "--heads", "origin", branch])).startsWith((await g(["rev-parse", "HEAD"])).trim()),
786
- run: () => push(git, ["--force", "origin", `HEAD:refs/heads/${branch}`]),
787
- isDone: ({ kind }) => kind === "pushed",
788
- });
923
+ const head = (await d.g(["rev-parse", "HEAD"])).trim();
789
924
 
790
- if (pushed.kind === "ran" && pushed.value.kind !== "pushed") return unpushed(id, branch, pushed.value);
925
+ d.outbox.add(approval ? { kind: "save-landing", head } : { kind: "push-branch", head });
791
926
 
792
- if (plan.trim()) await calls.workSource?.comment(id, `${PLAN_MARK}\n${plan.trim()}`);
927
+ if (plan.trim()) await d.outbox.calls({ run: "ask", attempt }).comment(id, `${PLAN_MARK}\n${plan.trim()}`);
793
928
 
794
929
  queueQuestion(d, d.item, question, plain);
795
- await releaseQuestions(d);
796
930
 
797
931
  return undefined;
798
932
  };
799
933
 
800
- /** Every act that changes the world checks the claim first. */
801
- const isStillMine = async (d: Pick<Driven, "workSource" | "id" | "holder" | "config">): Promise<boolean> => (await d.workSource.renew(d.id, d.holder, claimTtlMs(d.config))).won;
802
-
803
- const landContext = (d: Driven): LandContext => ({
804
- state: d.state,
805
- config: d.config,
806
- kind: d.kindName,
807
- id: d.id,
808
- item: d.item,
809
- branch: d.branch,
810
- base: d.base,
811
- remote: d.remote,
812
- clone: d.clone,
813
- env: d.env,
814
- dir: d.dir,
815
- git: d.git,
816
- checks: d.checks,
817
- workSource: d.workSource,
818
- questions: d.questions,
819
- pulls: d.pulls,
820
- now: d.now,
821
- judge: d.judge,
822
- reviewRun: reviewAtLanding(d),
823
- });
934
+ /** What the work side reads to place a change: the policy, the base's history and the change's own diff. */
935
+ const placing = (d: Driven) => ({ state: d.state, config: d.config, git: d.git, base: d.base, now: d.now, kind: d.kindName, dir: d.dir, id: d.id });
824
936
 
825
937
  const DRAINING = "the worker restarts for an update; the next worker lands the change under its config";
826
938
 
939
+ /** Publish decides the landing; the pass's own word on it is that publish has it. */
940
+ const LANDING_HANDED: string = "publish lands the change";
941
+
827
942
  /**
828
- * At `merging`: the change is saved and its branch pushed, then landed by its level unless the worker drains. A
829
- * docs-only item whose change reaches past its globs moves to its real kind first.
943
+ * Hands the change at `merging` to publish, once it grows from the base the pass started on and the checks pass
944
+ * there, unless the worker drains. A check item proves its check first. A docs-only item whose change reaches past
945
+ * its globs moves to its real kind first.
830
946
  */
831
- const merge = async (d: Driven, { onMerged, ownerApproved = false }: { readonly onMerged: () => void; readonly ownerApproved?: boolean }): Promise<ThinResult> => {
832
- if (!(await isStillMine(d))) return { outcome: "lost", item: d.id };
833
-
947
+ const merge = async (d: Driven): Promise<ThinResult> => {
834
948
  if (d.kindName === d.config.hum.checkKind) {
835
949
  const proof = await proveCheckItem({ state: d.state, config: d.config, git: d.git, item: d.id, base: d.base, checks: d.checks, now: d.now });
836
950
 
@@ -839,34 +953,32 @@ const merge = async (d: Driven, { onMerged, ownerApproved = false }: { readonly
839
953
 
840
954
  const isDocsOnly = d.kindName === d.config.hum.docsOnly.kind;
841
955
 
842
- if (isDocsOnly && doesLeaveDocs((await changeOn(landContext(d))).paths, d.config.hum)) {
843
- const real = await keepKind(d, d.item, await pickKind(d, d.item, d.kindName), d.kindName);
956
+ if (isDocsOnly && doesLeaveDocs((await changeOn(placing(d))).paths, d.config.hum)) {
957
+ const real = keepKind(d, d.item, await pickKind(d, d.item, d.kindName), d.kindName);
844
958
 
845
959
  return { outcome: "moved", item: d.id, kind: real };
846
960
  }
847
961
 
848
- const pushed = await prepareLanding(landContext(d), { ownerApproved });
849
-
850
- if (pushed.kind !== "pushed") return unpushed(d.id, d.branch, pushed);
851
-
852
- if (d.mayLand?.() === false) return { outcome: "held", item: d.id, why: DRAINING };
962
+ return handToPublish(d);
963
+ };
853
964
 
854
- const result = await land(landContext(d));
965
+ /** A finished change whose landing did not end: its branch is checked on the base again, and publish lands it. */
966
+ const handToPublish = async (d: Driven): Promise<ThinResult> => {
967
+ const head = async () => (await d.g(["rev-parse", "HEAD"])).trim();
855
968
 
856
- if (result.outcome === "merged") onMerged();
969
+ if (d.mayLand?.() === false) {
970
+ d.outbox.add({ kind: "save-landing", head: await head() });
857
971
 
858
- return result;
859
- };
972
+ return { outcome: "held", item: d.id, why: DRAINING };
973
+ }
860
974
 
861
- /** A finished change whose landing did not end: its pushed branch lands again, and once merged its saved state goes. */
862
- const landAgain = async (d: Driven): Promise<ThinResult> => {
863
- if (d.mayLand?.() === false) return { outcome: "held", item: d.id, why: DRAINING };
975
+ const stale = await rebaseOnto(d, d.baseSha);
864
976
 
865
- const result = await land(landContext(d));
977
+ if (stale) return { outcome: "review", item: d.id, detail: stale };
866
978
 
867
- if (result.outcome === "merged") d.state.items.remove(d.id);
979
+ d.outbox.add({ kind: "land", head: await head() });
868
980
 
869
- return result;
981
+ return { outcome: "held", item: d.id, why: LANDING_HANDED };
870
982
  };
871
983
 
872
984
  /** The answer option that runs a parked item again from the start. */