@moo.md/hum 0.0.0 → 0.2.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 (110) hide show
  1. package/package.json +2 -2
  2. package/schema/hum.schema.json +2 -2
  3. package/scripts/eval.ts +88 -50
  4. package/src/adapter-api.ts +46 -14
  5. package/src/adapters/admit.ts +2 -2
  6. package/src/adapters/argument.ts +1 -1
  7. package/src/adapters/claim.ts +18 -15
  8. package/src/adapters/claude-bg.ts +72 -32
  9. package/src/adapters/claude-p.ts +26 -25
  10. package/src/adapters/contract.ts +22 -10
  11. package/src/adapters/each-call.ts +9 -0
  12. package/src/adapters/fake.ts +6 -6
  13. package/src/adapters/git.ts +12 -19
  14. package/src/adapters/github-client.ts +102 -0
  15. package/src/adapters/github.ts +50 -136
  16. package/src/adapters/guard.ts +20 -9
  17. package/src/adapters/history.ts +12 -15
  18. package/src/adapters/item-file.ts +1 -1
  19. package/src/adapters/markdown.ts +49 -42
  20. package/src/adapters/marked.ts +15 -13
  21. package/src/adapters/model-call.ts +4 -4
  22. package/src/adapters/once.ts +5 -5
  23. package/src/adapters/owner-commit.ts +13 -11
  24. package/src/adapters/pull-requests.ts +11 -13
  25. package/src/adapters/registry.ts +7 -7
  26. package/src/adapters/roundup.ts +31 -37
  27. package/src/adapters/serial.ts +4 -5
  28. package/src/adapters/transcript.ts +13 -8
  29. package/src/cli/main.ts +1 -0
  30. package/src/cli/ops.ts +32 -14
  31. package/src/cli/service.ts +14 -8
  32. package/src/cli/setup.ts +8 -3
  33. package/src/cli/shared-watch.ts +3 -3
  34. package/src/config/checks.ts +14 -18
  35. package/src/config/machine.ts +5 -7
  36. package/src/config/refusal.ts +7 -0
  37. package/src/config/schema.ts +9 -9
  38. package/src/config/settings.ts +17 -2
  39. package/src/config/state-map.ts +5 -3
  40. package/src/decide/alignment.ts +4 -4
  41. package/src/decide/answer.ts +24 -22
  42. package/src/decide/kind.ts +1 -6
  43. package/src/decide/labels.ts +9 -9
  44. package/src/decide/merge.ts +6 -7
  45. package/src/decide/prose.ts +4 -4
  46. package/src/decide/question.ts +23 -20
  47. package/src/decide/review.ts +4 -2
  48. package/src/decide/risk.ts +25 -19
  49. package/src/decide/taste.ts +3 -3
  50. package/src/exec.ts +10 -4
  51. package/src/index.ts +14 -13
  52. package/src/loop/check-item.ts +3 -3
  53. package/src/loop/ci.ts +1 -1
  54. package/src/loop/github.ts +2 -2
  55. package/src/loop/groups.ts +13 -6
  56. package/src/loop/memory.ts +40 -28
  57. package/src/loop/notes.ts +5 -5
  58. package/src/loop/pair.ts +1 -1
  59. package/src/loop/pass.ts +18 -12
  60. package/src/loop/proof.ts +9 -7
  61. package/src/loop/prove-item.ts +3 -3
  62. package/src/loop/records.ts +12 -13
  63. package/src/loop/signals.ts +6 -6
  64. package/src/measure/inputs.ts +1 -1
  65. package/src/measure/measure.ts +4 -4
  66. package/src/measure/rate.ts +2 -0
  67. package/src/service/ci-tick.ts +2 -2
  68. package/src/service/supervise.ts +3 -2
  69. package/src/service/token.ts +3 -3
  70. package/src/service/wake.ts +2 -2
  71. package/src/service/workflows.ts +2 -2
  72. package/src/setup/propose.ts +4 -4
  73. package/src/setup/prove.ts +20 -14
  74. package/src/setup/scan.ts +31 -24
  75. package/src/setup/shipped.ts +8 -2
  76. package/src/setup/tables.ts +4 -3
  77. package/src/setup/waits.ts +9 -11
  78. package/src/setup/write.ts +17 -10
  79. package/src/slots/pool.ts +32 -24
  80. package/src/state/events.ts +1 -1
  81. package/src/state/faults.ts +13 -5
  82. package/src/state/format.ts +2 -2
  83. package/src/state/items.ts +20 -15
  84. package/src/state/open.ts +2 -2
  85. package/src/state/ops.ts +16 -10
  86. package/src/state/records.ts +5 -5
  87. package/src/state/runs.ts +33 -26
  88. package/src/state/saved.ts +44 -32
  89. package/src/status/file.ts +20 -1
  90. package/src/status/format.ts +47 -57
  91. package/src/status/sections.ts +2 -2
  92. package/src/worker/alignment-report.ts +4 -5
  93. package/src/worker/answers.ts +26 -24
  94. package/src/worker/base-check.ts +4 -5
  95. package/src/worker/checks.ts +25 -11
  96. package/src/worker/kind.ts +23 -19
  97. package/src/worker/land.ts +115 -126
  98. package/src/worker/merged.ts +9 -7
  99. package/src/worker/open.ts +15 -13
  100. package/src/worker/prose-run.ts +3 -3
  101. package/src/worker/questions.ts +15 -12
  102. package/src/worker/scheduler.ts +4 -4
  103. package/src/worker/signature.ts +3 -3
  104. package/src/worker/tally.ts +0 -2
  105. package/src/worker/taste.ts +6 -15
  106. package/src/worker/thin-path.ts +150 -123
  107. package/src/worker/thread.ts +25 -0
  108. package/src/worker/worker.ts +125 -73
  109. package/surface.json +633 -2198
  110. package/src/slots/scan.ts +0 -26
@@ -3,8 +3,8 @@ import { tmpdir } from "node:os";
3
3
  import { join } from "node:path";
4
4
  import { z } from "zod";
5
5
  import { type AnyActor, createActor, createAsyncLogic } from "xstate";
6
- import type { Item, Question, Questions, ThreadEntry, WorkSource } from "../adapter-api.ts";
7
- import { type Finished, type Runner, succeeded } from "../adapters/claude-p.ts";
6
+ import type { Holder, Item, ItemId, Question, Questions, ThreadEntry, WorkSource } from "../adapter-api.ts";
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
9
  import { ADAPTER_API_VERSION } from "../adapter-api.ts";
10
10
  import { onceCalls } from "../adapters/once.ts";
@@ -13,23 +13,24 @@ import { type Git, gitIn, identityEnv, PATCH, push } from "../adapters/git.ts";
13
13
  import type { PullRequests } from "../adapters/pull-requests.ts";
14
14
  import { pickTier } from "../config/checks.ts";
15
15
  import type { Config } from "../config/load.ts";
16
- import { kindMachine } from "../config/machine.ts";
16
+ import { invokedSources, kindMachine } from "../config/machine.ts";
17
17
  import { type Kind, type Naming, OWNER_WAIT_TAG, type PURPOSES, STUCK_TAG } from "../config/schema.ts";
18
18
  import { commandTimeoutMs } from "../exec.ts";
19
- import { leavesDocs } from "../decide/kind.ts";
19
+ import { doesLeaveDocs } from "../decide/kind.ts";
20
20
  import { type EventPick, type JsonSchema, jsonSchemaOf, type ProsePurpose, planHash, requestedChanges } from "../decide/prose.ts";
21
21
  import { persistedSnapshot } from "../state/items.ts";
22
22
  import type { State } from "../state/open.ts";
23
23
  import { HOUR_MS, SECOND_MS } from "../time.ts";
24
- import { runChecks } from "./checks.ts";
25
- import { changeOn, type LandContext, land, placementOf, prepareLanding, type ReviewOutcome } from "./land.ts";
24
+ import { checksTimeoutMs, runChecks } from "./checks.ts";
25
+ import { BASE_CONTENDED, changeOn, type LandContext, land, placementOf, prepareLanding, type ReviewOutcome, unpushed } from "./land.ts";
26
26
  import { OWNER_APPROVAL } from "../decide/merge.ts";
27
27
  import { askDecision, askedQuestion, isWaitQuestion, PLAIN_QUESTIONS, type PlainQuestion, RunReason } from "../decide/question.ts";
28
28
  import type { Stage } from "../decide/answer.ts";
29
- import { reviewInput } from "../decide/review.ts";
30
- import { decideKind, forgetProgress, kindAnswered } from "./kind.ts";
29
+ import { type ItemText, reviewInput } from "../decide/review.ts";
30
+ import { forgetProgress, keepKind, kindAnswered, pickKind } from "./kind.ts";
31
31
  import { settleAnswers } from "./answers.ts";
32
32
  import { queueQuestion, releaseQuestions } from "./questions.ts";
33
+ import { answerToLatest, latestQuestionAt, openQuestion } from "./thread.ts";
33
34
  import { memorySection, readMemory, rulesUsed } from "../loop/memory.ts";
34
35
  import { proveCheckItem } from "../loop/prove-item.ts";
35
36
  import { tallyOf } from "./tally.ts";
@@ -67,23 +68,25 @@ export type ThinPathOptions = {
67
68
  readonly base?: string;
68
69
  /** The repo's checks as shell commands, run in the clone. All must exit 0. */
69
70
  readonly checks: readonly string[];
70
- readonly holder: string;
71
+ readonly holder: Holder;
71
72
  /** Where runs clone to; a temp folder by default. */
72
73
  readonly workDir?: string;
73
74
  /** Gives the run its working copy on the remote's base branch, and takes it back when the item's pass ends. By default a `git clone` in a temp folder. */
74
75
  readonly checkout?: Checkout;
75
76
  readonly dir?: string;
76
77
  /** Take this item; default the first ready one. */
77
- readonly itemId?: string;
78
- readonly now?: () => number;
78
+ readonly itemId?: ItemId;
79
+ readonly now: () => number;
79
80
  /** Aborted when the worker loses the claim or exits for an update; the run stops and the result is `lost`. */
80
81
  readonly signal?: AbortSignal;
81
82
  /** Lets the first run of a shared prompt prefix reach its first token before the rest start. */
82
83
  readonly gate?: PrefixGate;
83
84
  /** The remote's pull requests and branch rules, for a remote on GitHub. */
84
85
  readonly pulls?: PullRequests;
85
- /** The names, never the values, of the variables the runs have; a missing secret is checked against them. Default: this process's. */
86
- readonly runnerVariables?: ReadonlySet<string>;
86
+ /** The names, never the values, of the variables the runs have; a missing secret is checked against them. */
87
+ readonly runnerVariables: ReadonlySet<string>;
88
+ /** A fresh id for each run's session. */
89
+ readonly newSessionId: () => string;
87
90
  /** 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. */
88
91
  readonly mayLand?: () => boolean;
89
92
  };
@@ -91,7 +94,7 @@ export type ThinPathOptions = {
91
94
  export type ThinResult =
92
95
  | { readonly outcome: "idle" }
93
96
  | { readonly outcome: "lost" | "waiting"; readonly item: string }
94
- /** The item's change showed it is another kind: it runs again from the start as that kind, on the same branch. */
97
+ /** The item's change showed it is another kind: it runs again from the start as that kind, on the same branch restarted at the base. */
95
98
  | { readonly outcome: "moved"; readonly item: string; readonly kind: string }
96
99
  | { readonly outcome: "merged" | "asked" | "stuck" | "review" | "landing"; readonly item: string; readonly detail?: string }
97
100
  | { readonly outcome: "limited"; readonly item: string; readonly until: number }
@@ -101,15 +104,14 @@ type Answered = { readonly question: string; readonly answer: string; readonly o
101
104
 
102
105
  /** The question, the answer to it and the plan, once the owner has answered the latest question. */
103
106
  export const answerTo = (item: Item): Answered | undefined => {
104
- const lastQuestion = item.thread.findLastIndex((e) => e.kind === "question");
105
- const answer = item.thread.slice(lastQuestion + 1).find((e) => e.kind === "answer");
107
+ const answer = answerToLatest(item.thread);
106
108
 
107
- if (lastQuestion < 0 || !answer) return undefined;
109
+ if (!answer) return undefined;
108
110
 
109
111
  const plan = item.thread.findLast((e) => e.kind === "comment" && e.text.startsWith(PLAN_MARK));
110
112
 
111
113
  return {
112
- question: item.thread[lastQuestion]?.text ?? "",
114
+ question: item.thread[latestQuestionAt(item.thread)]?.text ?? "",
113
115
  answer: answer.option ? `${answer.option}: ${answer.text}` : answer.text,
114
116
  option: answer.option,
115
117
  plan: plan?.text.slice(PLAN_MARK.length).trim() ?? "",
@@ -117,16 +119,18 @@ export const answerTo = (item: Item): Answered | undefined => {
117
119
  };
118
120
 
119
121
  /** The question the item's latest hum question puts, when it is one the item waits on and no applied answer follows it. */
120
- export const unansweredQuestion = (item: Item): ThreadEntry | undefined => {
121
- const last = item.thread.findLastIndex((e) => e.kind === "question" && e.author !== "person");
122
- const question = item.thread[last];
122
+ const unansweredQuestion = (item: Item): ThreadEntry | undefined => {
123
+ const question = openQuestion(item.thread);
123
124
 
124
- return question && isWaitQuestion(visibleText(question.text)) && !item.thread.slice(last + 1).some((e) => e.kind === "answer") ? question : undefined;
125
+ return question && isWaitQuestion(visibleText(question.text)) ? question : undefined;
125
126
  };
126
127
 
127
128
  /** Whether the kind's machine takes the owner's approval of a change in this state. */
128
129
  const isApprovalWait = (kind: Kind, state: string | undefined): boolean => state !== undefined && kind.machine.states[state]?.on?.[OWNER_APPROVED] !== undefined;
129
130
 
131
+ /** 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
+ export const ownerWaitStage = (kind: Kind, state: string | undefined): Stage => (isApprovalWait(kind, state) ? "approval" : "waiting");
133
+
130
134
  const Wants = z.looseObject({ status: z.string().optional(), question: z.string().optional(), plan: z.string().optional(), reason: RunReason.optional() });
131
135
 
132
136
  /** The kind as it stood at an earlier machine version, kept by `rememberKinds`, so a saved item restores across a change. */
@@ -140,16 +144,12 @@ export const rememberKinds = (state: State, config: Config): void => {
140
144
  /** Whether the kind's machine tags this state with `tag`. */
141
145
  const hasTag = (kind: Kind, state: string | undefined, tag: string): boolean => (state !== undefined && kind.machine.states[state]?.tags?.includes(tag)) ?? false;
142
146
 
143
- export const waitsOnOwner = (kind: Kind, state: string | undefined): boolean => hasTag(kind, state, OWNER_WAIT_TAG);
147
+ export const isWaitingOnOwner = (kind: Kind, state: string | undefined): boolean => hasTag(kind, state, OWNER_WAIT_TAG);
144
148
 
145
- export const endedStuck = (kind: Kind, state: string | undefined): boolean => hasTag(kind, state, STUCK_TAG);
149
+ export const hasEndedStuck = (kind: Kind, state: string | undefined): boolean => hasTag(kind, state, STUCK_TAG);
146
150
 
147
151
  /** Placeholder sources: enough to restore a snapshot and read its state before the real sources exist. */
148
- const stubSources = (kind: Kind) => {
149
- const idle = createAsyncLogic({ run: async () => {} });
150
-
151
- return Object.fromEntries(Object.values(kind.machine.states).flatMap((node) => (node.invoke ? [[node.invoke.src, idle]] : [])));
152
- };
152
+ const stubSources = (kind: Kind) => invokedSources(kind, createAsyncLogic({ run: async () => {} }));
153
153
 
154
154
  /**
155
155
  * The thin path: a ready markdown item is claimed, built by a `claude -p` run on its run branch,
@@ -165,8 +165,23 @@ const kindNamed = (config: Config, name: string): Kind => {
165
165
  return kind;
166
166
  };
167
167
 
168
- export const runThinPath = async (options: ThinPathOptions): Promise<ThinResult> => {
169
- const o: WithNow = { ...options, now: options.now ?? Date.now };
168
+ /** The outcomes that decide nothing about the item: it stays where its pass found it. */
169
+ type Undecided = Extract<ThinResult, { outcome: "idle" | "lost" | "waiting" | "limited" | "held" }>;
170
+
171
+ const UNDECIDED_OUTCOMES: readonly string[] = ["idle", "lost", "waiting", "limited", "held"] satisfies readonly Undecided["outcome"][];
172
+
173
+ const isUndecided = (result: ThinResult): result is Undecided => UNDECIDED_OUTCOMES.includes(result.outcome);
174
+
175
+ /** One pass of an item. A pass that decides the item, by any path, ends its hold on the base. */
176
+ export const runThinPath = async (o: ThinPathOptions): Promise<ThinResult> => {
177
+ const result = await pass(o);
178
+
179
+ if (!isUndecided(result)) o.state.faults.clear({ code: BASE_CONTENDED, item: result.item });
180
+
181
+ return result;
182
+ };
183
+
184
+ const pass = async (o: ThinPathOptions): Promise<ThinResult> => {
170
185
  const base = o.base ?? DEFAULT_BASE;
171
186
  const id = o.itemId ?? (await o.workSource.listReady())[0]?.id;
172
187
 
@@ -186,7 +201,7 @@ export const runThinPath = async (options: ThinPathOptions): Promise<ThinResult>
186
201
 
187
202
  const at = saved.value === undefined ? undefined : String(saved.value.getSnapshot().value);
188
203
 
189
- if (knownKind && endedStuck(knownKind, at)) return park(o, { outcome: "stuck", item: id, detail: "the saved state ended stuck" });
204
+ if (knownKind && hasEndedStuck(knownKind, at)) return park(o, { outcome: "stuck", item: id, detail: "the saved state ended stuck" });
190
205
 
191
206
  const claim = await o.workSource.claim(id, o.holder, claimTtlMs(o.config));
192
207
 
@@ -195,8 +210,8 @@ export const runThinPath = async (options: ThinPathOptions): Promise<ThinResult>
195
210
  const judge = o.judge ?? configuredModelCall(o.runner, o.config.hum, (item, tokens) => tallyOf(o.state, item).spend(tokens));
196
211
  const { now } = o;
197
212
  const onSnapshot = saved.value !== undefined;
198
- const waitingState = knownKind && waitsOnOwner(knownKind, at);
199
- const stage: Stage = o.state.landings.get(id) ? "approval" : waitingState ? (knownKind && isApprovalWait(knownKind, at) ? "approval" : "waiting") : onSnapshot ? "running" : "waiting";
213
+ const ownerWait = knownKind && isWaitingOnOwner(knownKind, at) ? ownerWaitStage(knownKind, at) : undefined;
214
+ const stage: Stage = o.state.landings.get(id) ? "approval" : (ownerWait ?? (onSnapshot ? "running" : "waiting"));
200
215
  const item = await settleAnswers({ state: o.state, workSource: o.workSource, judge, now }, await o.workSource.read(id), { stage });
201
216
  const named = known && kindAnswered(known, item, o.config.hum.kinds);
202
217
 
@@ -213,14 +228,18 @@ export const runThinPath = async (options: ThinPathOptions): Promise<ThinResult>
213
228
 
214
229
  if (unanswered) return unanswered.at + o.config.hum.questionTimeoutHours * HOUR_MS < now() ? park(o, { outcome: "stuck", item: id, detail: `no answer came within ${o.config.hum.questionTimeoutHours} hours` }) : { outcome: "waiting", item: id };
215
230
 
216
- const kindName = (named ?? known ?? (await decideKind({ ...o, judge, now }, item))).kind;
231
+ const settled = named ?? known;
232
+ const kindContext = { ...o, judge, now };
233
+ const kindName = settled ? settled.kind : await keepKind(kindContext, item, await pickKind(kindContext, item));
217
234
  const kind = kindNamed(o.config, kindName);
218
- const asking = waitsOnOwner(kind, at);
235
+ const asking = isWaitingOnOwner(kind, at);
219
236
  const answered = asking || !onSnapshot ? answerTo(item) : undefined;
220
237
 
221
238
  if (asking && answered === undefined) return { outcome: "waiting", item: id };
222
239
 
223
240
  const landing = o.state.landings.get(id);
241
+ /** Nothing saved is left to go on from: a new item, one that moved to another kind, or one the owner ran again. */
242
+ const isFresh = !onSnapshot && landing === undefined;
224
243
  const branch = runBranch(o.config.hum, id);
225
244
  const timeoutMs = commandTimeoutMs(o.config.hum);
226
245
  const taken = await (o.checkout ?? clonesIn(o.workDir, timeoutMs))({ remote: o.remote, base, item: id, signal: o.signal }).catch((error: Error) => (o.signal?.aborted ? undefined : Promise.reject(error)));
@@ -235,9 +254,9 @@ export const runThinPath = async (options: ThinPathOptions): Promise<ThinResult>
235
254
  const g = (args: readonly string[]): Promise<string> => git.raw(args);
236
255
 
237
256
  try {
238
- await onRunBranch(git, branch);
257
+ await onRunBranch(git, { branch, restartAt: isFresh ? `origin/${base}` : undefined });
239
258
 
240
- 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 };
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 };
241
260
 
242
261
  // A change already finished lands again from its pushed branch; no run is spent on it.
243
262
  const result = park(o, landing ? await landAgain(driven) : await drive(driven));
@@ -254,7 +273,7 @@ export const runThinPath = async (options: ThinPathOptions): Promise<ThinResult>
254
273
  export type Source = { readonly remote: string; readonly base: string };
255
274
 
256
275
  /** What a checkout is asked for: a working copy of `source` for the item's pass, and the signal that ends the wait for one. */
257
- export type CheckoutRequest = Source & { readonly item: string; readonly signal: AbortSignal | undefined };
276
+ type CheckoutRequest = Source & { readonly item: string; readonly signal: AbortSignal | undefined };
258
277
 
259
278
  /** A run's working copy: its folder, the environment its runs and checks add, and the call that takes it back. */
260
279
  export type Checkedout = {
@@ -264,8 +283,9 @@ export type Checkedout = {
264
283
  };
265
284
 
266
285
  /**
267
- * Gives an item's pass its working copy, with the base branch's files. A background run starts only in a repo the
268
- * owner trusts, which a fresh clone is not; a slot is a worktree of the owner's checkout.
286
+ * Gives an item's pass its working copy, with the base branch's files and `origin/<base>`, where a restarted run
287
+ * branch starts. A background run starts only in a repo the owner trusts, which a fresh clone is not; a slot is a
288
+ * worktree of the owner's checkout.
269
289
  */
270
290
  export type Checkout = (request: CheckoutRequest) => Promise<Checkedout>;
271
291
 
@@ -281,11 +301,14 @@ const clonesIn =
281
301
  };
282
302
 
283
303
  /**
284
- * Checks out the run branch: from the remote when it has it, from the folder when only the folder does (a pass that
285
- * ended before it pushed), and new from the current commit when neither does. A folder and the remote that disagree
286
- * throw: neither is dropped.
304
+ * Checks out the run branch. Given `restartAt`, it starts there, whatever an earlier run left on the remote or in the
305
+ * folder; its next push replaces the remote's. Otherwise it comes from the remote when the remote has it, from the
306
+ * folder when only the folder does (a pass that ended before it pushed), and new from the current commit when neither
307
+ * does. A folder and the remote that disagree throw: neither is dropped.
287
308
  */
288
- const onRunBranch = async (git: Git, branch: string): Promise<void> => {
309
+ const onRunBranch = async (git: Git, { branch, restartAt }: { readonly branch: string; readonly restartAt: string | undefined }): Promise<void> => {
310
+ if (restartAt !== undefined) return void (await git.raw(["checkout", "-q", "-B", branch, restartAt]));
311
+
289
312
  const onRemote = (await git.raw(["ls-remote", "--heads", "origin", branch])).trim() !== "";
290
313
  const onFolder = (await git.run(["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`])).code === 0;
291
314
 
@@ -299,15 +322,13 @@ const onRunBranch = async (git: Git, branch: string): Promise<void> => {
299
322
  };
300
323
 
301
324
  /** The options with the clock every later step reads. */
302
- type WithNow = ThinPathOptions & { readonly now: () => number };
303
-
304
- type Driven = WithNow & {
325
+ type Driven = ThinPathOptions & {
305
326
  readonly kindName: string;
306
327
  readonly judge: ModelCall;
307
328
  readonly base: string;
308
329
  readonly dir: string;
309
330
  readonly kind: Kind;
310
- readonly id: string;
331
+ readonly id: ItemId;
311
332
  readonly item: Item;
312
333
  readonly branch: string;
313
334
  readonly clone: string;
@@ -317,6 +338,8 @@ type Driven = WithNow & {
317
338
  readonly answered: Answered | undefined;
318
339
  /** Restore the saved owner-wait snapshot instead of starting the machine. */
319
340
  readonly resume: boolean;
341
+ /** The run branch starts again at the base: earlier work on the item, and the plan written for it, are gone. */
342
+ readonly restarted: boolean;
320
343
  };
321
344
 
322
345
  const drive = async (d: Driven): Promise<ThinResult> => {
@@ -374,11 +397,11 @@ const drive = async (d: Driven): Promise<ThinResult> => {
374
397
  if (plan) parts.push(`## The approved plan (${plan.hash})\n${JSON.stringify(plan.plan, null, 2)}`);
375
398
 
376
399
  if (d.answered) {
377
- const diff = await branchDiff();
400
+ const soFar = d.restarted
401
+ ? `## The branch so far\nIt starts again at origin/${base}: the earlier work on this item was discarded, and no file it made is here.`
402
+ : `## The plan so far\n${d.answered.plan || "(none saved)"}\n\n## The branch so far\n${(await branchDiff()).slice(0, config.hum.diffLimit)}`;
378
403
 
379
- parts.push(
380
- `## The owner answered\nQuestion: ${d.answered.question}\nAnswer: ${d.answered.answer}\n\n## The plan so far\n${d.answered.plan || "(none saved)"}\n\n## The branch so far\n${diff.slice(0, config.hum.diffLimit)}`,
381
- );
404
+ parts.push(`## The owner answered\nQuestion: ${d.answered.question}\nAnswer: ${d.answered.answer}\n\n${soFar}`);
382
405
  }
383
406
 
384
407
  if (purpose === "fix") parts.push(`## What to fix\n${lastFailure.slice(-config.hum.failureTail)}\nFix the cause and commit.`);
@@ -405,8 +428,8 @@ const drive = async (d: Driven): Promise<ThinResult> => {
405
428
  const runAgent = async (purpose: Purpose, text: string, schema: JsonSchema, signal: AbortSignal): Promise<Finished> => {
406
429
  const attempt = state.runs.unended(id, purpose)?.attempt ?? state.runs.list(id).length;
407
430
  const key = { itemId: id, run: purpose, attempt };
408
- const begun = state.runs.begin(key, `hum ${id} ${purpose} #${attempt}`, crypto.randomUUID());
409
- const held = purpose === "build" || purpose === "fix" ? readMemory(join(clone, ".hum", "memory.md")) : [];
431
+ const begun = state.runs.begin(key, { name: `hum ${id} ${purpose} #${attempt}`, sessionId: d.newSessionId() });
432
+ const held = purpose === "build" || purpose === "fix" ? readMemory(join(clone, ".hum", "memory.md"), config.hum.memoryMaxBytes).entries : [];
410
433
  const prefix = config.hum.roles[purpose]?.file ?? purpose;
411
434
 
412
435
  const lease = await d.gate?.enter(prefix, signal);
@@ -423,18 +446,14 @@ const drive = async (d: Driven): Promise<ThinResult> => {
423
446
  // A saved id already has a transcript under it; a fresh run mints its own.
424
447
  sessionId: begun.adopted ? undefined : begun.record.sessionId,
425
448
  signal,
426
- onSession: (sessionId) => state.runs.saveSession(key, sessionId),
449
+ onSession: (sessionId) => begun.saveSession(sessionId),
427
450
  onFirstToken: () => lease?.opened(),
428
451
  })
429
452
  .finally(() => lease?.release());
430
453
 
431
- state.runs.end(key, held.length === 0 ? undefined : outcome.kind === "finished" ? rulesUsed(outcome, held) : []);
454
+ begun.end(held.length === 0 ? undefined : outcome.kind === "finished" ? rulesUsed(outcome, held) : []);
432
455
 
433
- if (outcome.kind === "limited") return pause({ outcome: "limited", item: id, until: outcome.until });
434
-
435
- if (outcome.kind === "held") return pause({ outcome: "held", item: id, why: outcome.card.cause });
436
-
437
- if (outcome.kind === "stopped") return pause({ outcome: "lost", item: id });
456
+ if (isPaused(outcome)) return pause(pauseOf(id, outcome));
438
457
 
439
458
  if (outcome.kind === "over-cap") {
440
459
  tally.spend(outcome.tokens);
@@ -460,19 +479,19 @@ const drive = async (d: Driven): Promise<ThinResult> => {
460
479
  const { placement } = await placementOf(landContext(d), change);
461
480
 
462
481
  const decision = askDecision(reason, {
463
- runnerVariables: d.runnerVariables ?? new Set(Object.keys(process.env)),
482
+ runnerVariables: d.runnerVariables,
464
483
  changedPaths: change.paths,
465
484
  level: placement.level.name,
466
485
  undoableLevels: config.hum.undoableLevels,
467
486
  });
468
487
 
469
- if (decision.action === "ask") return { asked: { ...askedQuestion(reason, decision.confirmed, wants.question), plan: wants.plan ?? "" } };
488
+ if (decision.action === "ask") return { asked: { ...askedQuestion({ reason, confirmed: decision.confirmed, runsWords: wants.question }), plan: wants.plan ?? "" } };
470
489
 
471
490
  const text = `Chose "${decision.choice}" over ${decision.over.filter((word) => word !== decision.choice).join(", ")} without you.`;
472
491
  const calls = onceCalls({ apiVersion: ADAPTER_API_VERSION, workSource: d.workSource, questions: d.questions }, state.ops, { run: "decide", attempt: state.runs.list(id).length });
473
492
 
474
493
  await calls.questions?.decide(id, text);
475
- state.choices.put(`${id}@${text}`, { item: id, text, at: (d.now ?? Date.now)() });
494
+ state.choices.put(`${id}@${text}`, { item: id, text, at: d.now() });
476
495
 
477
496
  return { chose: text };
478
497
  };
@@ -488,7 +507,7 @@ const drive = async (d: Driven): Promise<ThinResult> => {
488
507
  for (;;) {
489
508
  const outcome = await runAgent(purpose, `${await prompt(purpose)}${chosenSection(chosen)}`, RUN_SCHEMA, signal);
490
509
 
491
- if (!succeeded(outcome)) throw failed(`the ${purpose} run ended as ${outcome.subtype}: ${outcome.text.slice(0, CARD_EXCERPT)}`);
510
+ if (!hasSucceeded(outcome)) throw failed(`the ${purpose} run ended as ${outcome.subtype}: ${outcome.text.slice(0, CARD_EXCERPT)}`);
492
511
 
493
512
  const wants = Wants.safeParse(outcome.structured).data;
494
513
 
@@ -508,7 +527,7 @@ const drive = async (d: Driven): Promise<ThinResult> => {
508
527
 
509
528
  const checksSource = createAsyncLogic({
510
529
  run: async () => {
511
- const failure = await runChecks(d.checks, clone, { env: d.env });
530
+ const failure = await runChecks(d.checks, clone, { env: d.env, timeoutMs: checksTimeoutMs(d.config.hum) });
512
531
 
513
532
  if (failure) {
514
533
  lastFailure = failure;
@@ -534,8 +553,7 @@ const drive = async (d: Driven): Promise<ThinResult> => {
534
553
  ],
535
554
  ]);
536
555
 
537
- const saveVerdict = (pick: EventPick, models: readonly string[], head: string) =>
538
- state.verdicts.put(id, { item: id, head, event: pick.event, reason: pick.reason, cites: pick.cites, models: [...models] });
556
+ const saveVerdict = (pick: EventPick, models: readonly string[], head: string) => state.verdicts.put(id, verdictOf({ id, head, pick, models }));
539
557
 
540
558
  /** A plan or review state: its run picks the next event, and a split files the parts and lands the item as done. */
541
559
  const decision = (purpose: ProsePurpose) =>
@@ -584,19 +602,19 @@ const drive = async (d: Driven): Promise<ThinResult> => {
584
602
 
585
603
  handled = value;
586
604
 
587
- if (endedStuck(kind, value)) return result.resolve({ outcome: "stuck", item: id, detail: stuckCause() });
605
+ if (hasEndedStuck(kind, value)) return result.resolve({ outcome: "stuck", item: id, detail: stuckCause() });
588
606
 
589
- if (waitsOnOwner(kind, value)) {
607
+ if (isWaitingOnOwner(kind, value)) {
590
608
  const note = pending ?? { question: { text: "The run stopped for the owner." }, plain: "unsure" as const, plan: "" };
591
609
 
592
- if (!(await stillMine(d))) return result.resolve({ outcome: "lost", item: id });
610
+ if (!(await isStillMine(d))) return result.resolve({ outcome: "lost", item: id });
593
611
 
594
- await handOff(d, isApprovalWait(kind, value) ? approvalQuestion(note) : note);
612
+ const stopped = await handOff(d, isApprovalWait(kind, value) ? approvalQuestion(note) : note);
595
613
 
596
- return result.resolve({ outcome: "asked", item: id, detail: note.question.text });
614
+ return result.resolve(stopped ?? { outcome: "asked", item: id, detail: note.question.text });
597
615
  }
598
616
 
599
- if (value === "merging") return result.resolve(await merge(d, () => actor.send({ type: "merged" }), approvedByOwner));
617
+ if (value === "merging") return result.resolve(await merge(d, { onMerged: () => actor.send({ type: "merged" }), ownerApproved: approvedByOwner }));
600
618
  };
601
619
 
602
620
  actor.subscribe((snapshot) => {
@@ -663,7 +681,6 @@ const roleOf = (config: RunConfig, purpose: Purpose): string => {
663
681
  return ((role && config.roles[role.file]) ?? "").trim();
664
682
  };
665
683
 
666
- type ItemText = Pick<Item, "id" | "title" | "body">;
667
684
 
668
685
  /** What a plan or review run reads. A plan run reads the repo too; a review run reads only the item and the diff, so no author's reasoning reaches it. */
669
686
  export const PROSE_PROMPTS = {
@@ -676,22 +693,26 @@ export const PROSE_PROMPTS = {
676
693
  review: (config: RunConfig, item: ItemText, diff: string): string => [roleOf(config, "review"), reviewInput(item, diff, config.hum)].join("\n\n"),
677
694
  } as const satisfies Record<ProsePurpose, (config: RunConfig, item: ItemText, diff: string) => string>;
678
695
 
679
- const verdictOf = (id: string, head: string, pick: EventPick, models: readonly string[]) => ({ item: id, head, event: pick.event, reason: pick.reason, cites: pick.cites, models: [...models] });
696
+ const verdictOf = ({ id, head, pick, models }: { readonly id: string; readonly head: string; readonly pick: EventPick; readonly models: readonly string[] }) => ({ item: id, head, event: pick.event, reason: pick.reason, cites: pick.cites, models: [...models] });
680
697
 
681
- /** A run that ended with no answer to read, carried out of the decision as the result it comes to. */
682
- class Halted extends Error {
683
- override name = "Halted";
698
+ /** A run that ended with no answer and no token to count: a usage limit, a hold, or a stop. */
699
+ type Paused = Extract<RunOutcome, { kind: "limited" | "held" | "stopped" }>;
684
700
 
685
- constructor(readonly result: ThinResult) {
686
- super(`the run halted: ${result.outcome}`);
687
- }
688
- }
701
+ const PAUSED_KINDS: readonly string[] = ["limited", "held", "stopped"] satisfies readonly Paused["kind"][];
702
+
703
+ const isPaused = (outcome: RunOutcome): outcome is Paused => PAUSED_KINDS.includes(outcome.kind);
689
704
 
690
- const HALTS = {
691
- limited: (id: string, outcome: { until: number }): ThinResult => ({ outcome: "limited", item: id, until: outcome.until }),
692
- held: (id: string, outcome: { card: { cause: string } }): ThinResult => ({ outcome: "held", item: id, why: outcome.card.cause }),
693
- "over-cap": (id: string, cap: number, spent: number): ThinResult => ({ outcome: "review", item: id, detail: `the review run passed the item's token cap (${cap}) at ${spent} tokens` }),
694
- } as const;
705
+ /** What a paused run comes to for its item. */
706
+ const pauseOf = (id: string, outcome: Paused): ThinResult => {
707
+ switch (outcome.kind) {
708
+ case "limited":
709
+ return { outcome: "limited", item: id, until: outcome.until };
710
+ case "held":
711
+ return { outcome: "held", item: id, why: outcome.card.cause };
712
+ case "stopped":
713
+ return { outcome: "lost", item: id };
714
+ }
715
+ };
695
716
 
696
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. */
697
718
  const reviewAtLanding =
@@ -701,39 +722,40 @@ const reviewAtLanding =
701
722
 
702
723
  if (!row) throw new Error(`the ${d.kindName} table has no review row`);
703
724
 
704
- const run = async (prompt: string, schema: JsonSchema): Promise<Finished> => {
705
- const tally = tallyOf(d.state, d.id);
706
- 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() });
725
+ const tally = tallyOf(d.state, d.id);
707
726
 
708
- if (outcome.kind === "limited") throw new Halted(HALTS.limited(d.id, outcome));
727
+ let halt: (result: ThinResult) => void = () => {};
709
728
 
710
- if (outcome.kind === "held") throw new Halted(HALTS.held(d.id, outcome));
729
+ const halted = new Promise<ReviewOutcome>((resolve) => {
730
+ halt = (result) => resolve({ halted: result });
731
+ });
711
732
 
712
- if (outcome.kind === "over-cap") {
733
+ /** A run with no answer never settles, as AnswerRun requires; the review comes to `halted` instead. */
734
+ 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() });
736
+
737
+ if (outcome.kind === "finished") {
713
738
  tally.spend(outcome.tokens);
714
739
 
715
- throw new Halted(HALTS["over-cap"](d.id, d.kind.tokenCap.tokens, tally.sinceAnswer()));
740
+ return outcome;
716
741
  }
717
742
 
718
- if (outcome.kind !== "finished") throw new Halted({ outcome: "lost", item: d.id });
743
+ if (outcome.kind === "over-cap") tally.spend(outcome.tokens);
719
744
 
720
- tally.spend(outcome.tokens);
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` });
721
746
 
722
- return outcome;
747
+ return new Promise<never>(() => {});
723
748
  };
724
749
 
725
- try {
726
- const { pick, models } = await decideProse({ purpose: "review", prompt: PROSE_PROMPTS.review(d.config, d.item, diff), diff, model: d.config.hum.models[row.tier], run });
727
- const verdict = verdictOf(d.id, head, pick, models);
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 });
728
752
 
729
753
  d.state.verdicts.put(d.id, verdict);
730
754
 
731
755
  return { verdict };
732
- } catch (error) {
733
- if (error instanceof Halted) return { halted: error.result };
756
+ });
734
757
 
735
- throw error;
736
- }
758
+ return Promise.race([decided, halted]);
737
759
  };
738
760
 
739
761
  /** Files each part of a split item as its own item, then lands the item as done with no change of its own. */
@@ -742,7 +764,7 @@ const split = async (d: Driven, parts: readonly string[], onMerged: () => void):
742
764
 
743
765
  for (const title of parts) await calls.workSource?.fileFollowUp(d.id, { title, body: `Split from ${d.id}: ${d.item.title}` });
744
766
 
745
- return merge(d, onMerged);
767
+ return merge(d, { onMerged });
746
768
  };
747
769
 
748
770
  /** The owner-review wait asks for the change's approval, whatever the review run wrote. */
@@ -752,28 +774,31 @@ const approvalQuestion = ({ question, plan }: Pending): Pending => ({
752
774
  plan,
753
775
  });
754
776
 
755
- /** 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. */
756
- const handOff = async (d: Driven, { question, plain, plan }: Pending) => {
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> => {
757
779
  const { state, id, g, branch, workSource, questions, git } = d;
758
780
  const attempt = state.runs.list(id).length;
759
781
  const key = (op: string) => ({ itemId: id, run: "ask", attempt, op });
760
782
  const calls = onceCalls({ apiVersion: ADAPTER_API_VERSION, workSource, questions }, state.ops, { run: "ask", attempt });
761
783
 
762
- await state.ops.once(key("push-branch"), {
784
+ const pushed = await state.ops.once(key("push-branch"), {
763
785
  holds: async () => (await g(["ls-remote", "--heads", "origin", branch])).startsWith((await g(["rev-parse", "HEAD"])).trim()),
764
- run: async () => {
765
- if ((await push(git, ["--force", "origin", `HEAD:refs/heads/${branch}`])) !== "pushed") throw new Error(`could not push ${branch}`);
766
- },
786
+ run: () => push(git, ["--force", "origin", `HEAD:refs/heads/${branch}`]),
787
+ isDone: ({ kind }) => kind === "pushed",
767
788
  });
768
789
 
790
+ if (pushed.kind === "ran" && pushed.value.kind !== "pushed") return unpushed(id, branch, pushed.value);
791
+
769
792
  if (plan.trim()) await calls.workSource?.comment(id, `${PLAN_MARK}\n${plan.trim()}`);
770
793
 
771
794
  queueQuestion(d, d.item, question, plain);
772
795
  await releaseQuestions(d);
796
+
797
+ return undefined;
773
798
  };
774
799
 
775
800
  /** Every act that changes the world checks the claim first. */
776
- const stillMine = async (d: Pick<Driven, "workSource" | "id" | "holder" | "config">): Promise<boolean> => (await d.workSource.renew(d.id, d.holder, claimTtlMs(d.config))).won;
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;
777
802
 
778
803
  const landContext = (d: Driven): LandContext => ({
779
804
  state: d.state,
@@ -792,7 +817,7 @@ const landContext = (d: Driven): LandContext => ({
792
817
  workSource: d.workSource,
793
818
  questions: d.questions,
794
819
  pulls: d.pulls,
795
- now: d.now ?? Date.now,
820
+ now: d.now,
796
821
  judge: d.judge,
797
822
  reviewRun: reviewAtLanding(d),
798
823
  });
@@ -803,24 +828,26 @@ const DRAINING = "the worker restarts for an update; the next worker lands the c
803
828
  * At `merging`: the change is saved and its branch pushed, then landed by its level unless the worker drains. A
804
829
  * docs-only item whose change reaches past its globs moves to its real kind first.
805
830
  */
806
- const merge = async (d: Driven, onMerged: () => void, ownerApproved = false): Promise<ThinResult> => {
807
- if (!(await stillMine(d))) return { outcome: "lost", item: d.id };
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 };
808
833
 
809
834
  if (d.kindName === d.config.hum.checkKind) {
810
- 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 ?? Date.now });
835
+ 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 });
811
836
 
812
837
  if (proof && !proof.passed) return { outcome: "stuck", item: d.id, detail: proof.reason };
813
838
  }
814
839
 
815
840
  const isDocsOnly = d.kindName === d.config.hum.docsOnly.kind;
816
841
 
817
- if (isDocsOnly && leavesDocs((await changeOn(landContext(d))).paths, d.config.hum)) {
818
- const real = await decideKind(d, d.item, d.kindName);
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);
819
844
 
820
- return { outcome: "moved", item: d.id, kind: real.kind };
845
+ return { outcome: "moved", item: d.id, kind: real };
821
846
  }
822
847
 
823
- await prepareLanding(landContext(d), ownerApproved);
848
+ const pushed = await prepareLanding(landContext(d), { ownerApproved });
849
+
850
+ if (pushed.kind !== "pushed") return unpushed(d.id, d.branch, pushed);
824
851
 
825
852
  if (d.mayLand?.() === false) return { outcome: "held", item: d.id, why: DRAINING };
826
853
 
@@ -873,7 +900,7 @@ export const park = (o: Pick<ThinPathOptions, "state" | "now">, result: ThinResu
873
900
  const rule = PARKING[result.outcome];
874
901
  const cause = result.detail ?? rule.fallback;
875
902
 
876
- o.state.parked.put(result.item, { item: result.item, why: result.outcome, cause, since: (o.now ?? Date.now)() });
903
+ o.state.parked.put(result.item, { item: result.item, why: result.outcome, cause, since: o.now() });
877
904
  o.state.faults.raise({
878
905
  code: rule.code,
879
906
  item: result.item,
@@ -0,0 +1,25 @@
1
+ import type { ThreadEntry } from "../adapter-api.ts";
2
+
3
+ type Thread = readonly ThreadEntry[];
4
+
5
+ /** Whether hum wrote the entry. A source that marks no authors holds only entries hum wrote or applied. */
6
+ export const isFromHum = (entry: ThreadEntry): boolean => entry.author !== "person";
7
+
8
+ const isHumQuestion = (entry: ThreadEntry): boolean => entry.kind === "question" && isFromHum(entry);
9
+
10
+ /** Where hum's latest question sits on the thread; -1 when it asked none. */
11
+ export const latestQuestionAt = (thread: Thread): number => thread.findLastIndex(isHumQuestion);
12
+
13
+ /** The applied answer to hum's latest question: the first answer after it. */
14
+ export const answerToLatest = (thread: Thread): ThreadEntry | undefined => {
15
+ const asked = latestQuestionAt(thread);
16
+
17
+ return asked < 0 ? undefined : thread.slice(asked + 1).find((entry) => entry.kind === "answer");
18
+ };
19
+
20
+ /** Hum's latest question, while no applied answer follows it. */
21
+ export const openQuestion = (thread: Thread): ThreadEntry | undefined => (answerToLatest(thread) === undefined ? thread[latestQuestionAt(thread)] : undefined);
22
+
23
+ /** The latest applied answer that picks one of `options`, from `since` on. */
24
+ export const pickedAnswer = (thread: Thread, options: readonly string[], since = 0): ThreadEntry | undefined =>
25
+ thread.findLast((entry) => entry.kind === "answer" && entry.at >= since && entry.option !== undefined && options.includes(entry.option));