@moo.md/hum 0.1.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 (108) hide show
  1. package/package.json +2 -2
  2. package/scripts/eval.ts +88 -50
  3. package/src/adapter-api.ts +46 -14
  4. package/src/adapters/admit.ts +2 -2
  5. package/src/adapters/argument.ts +1 -1
  6. package/src/adapters/claim.ts +18 -15
  7. package/src/adapters/claude-bg.ts +50 -27
  8. package/src/adapters/claude-p.ts +18 -23
  9. package/src/adapters/contract.ts +22 -10
  10. package/src/adapters/each-call.ts +9 -0
  11. package/src/adapters/fake.ts +6 -6
  12. package/src/adapters/git.ts +10 -18
  13. package/src/adapters/github-client.ts +102 -0
  14. package/src/adapters/github.ts +34 -142
  15. package/src/adapters/guard.ts +20 -9
  16. package/src/adapters/history.ts +12 -15
  17. package/src/adapters/item-file.ts +1 -1
  18. package/src/adapters/markdown.ts +49 -42
  19. package/src/adapters/marked.ts +6 -12
  20. package/src/adapters/model-call.ts +4 -4
  21. package/src/adapters/once.ts +5 -5
  22. package/src/adapters/owner-commit.ts +13 -11
  23. package/src/adapters/pull-requests.ts +11 -13
  24. package/src/adapters/registry.ts +7 -7
  25. package/src/adapters/roundup.ts +27 -35
  26. package/src/adapters/serial.ts +4 -5
  27. package/src/adapters/transcript.ts +13 -8
  28. package/src/cli/main.ts +1 -0
  29. package/src/cli/ops.ts +32 -14
  30. package/src/cli/service.ts +14 -8
  31. package/src/cli/setup.ts +8 -3
  32. package/src/cli/shared-watch.ts +3 -3
  33. package/src/config/checks.ts +14 -18
  34. package/src/config/machine.ts +5 -7
  35. package/src/config/refusal.ts +7 -0
  36. package/src/config/schema.ts +7 -7
  37. package/src/config/settings.ts +17 -2
  38. package/src/config/state-map.ts +5 -3
  39. package/src/decide/alignment.ts +4 -4
  40. package/src/decide/answer.ts +24 -22
  41. package/src/decide/kind.ts +1 -6
  42. package/src/decide/labels.ts +9 -9
  43. package/src/decide/merge.ts +6 -7
  44. package/src/decide/prose.ts +4 -4
  45. package/src/decide/question.ts +23 -20
  46. package/src/decide/review.ts +4 -2
  47. package/src/decide/risk.ts +25 -19
  48. package/src/decide/taste.ts +3 -3
  49. package/src/exec.ts +4 -3
  50. package/src/index.ts +14 -13
  51. package/src/loop/check-item.ts +3 -3
  52. package/src/loop/ci.ts +1 -1
  53. package/src/loop/github.ts +2 -2
  54. package/src/loop/groups.ts +13 -6
  55. package/src/loop/memory.ts +40 -28
  56. package/src/loop/notes.ts +5 -5
  57. package/src/loop/pair.ts +1 -1
  58. package/src/loop/pass.ts +18 -12
  59. package/src/loop/proof.ts +9 -7
  60. package/src/loop/prove-item.ts +1 -1
  61. package/src/loop/records.ts +12 -13
  62. package/src/loop/signals.ts +6 -6
  63. package/src/measure/inputs.ts +1 -1
  64. package/src/measure/measure.ts +4 -4
  65. package/src/measure/rate.ts +2 -0
  66. package/src/service/ci-tick.ts +2 -2
  67. package/src/service/supervise.ts +3 -2
  68. package/src/service/token.ts +3 -3
  69. package/src/service/wake.ts +2 -2
  70. package/src/service/workflows.ts +2 -2
  71. package/src/setup/propose.ts +4 -4
  72. package/src/setup/prove.ts +18 -12
  73. package/src/setup/scan.ts +31 -24
  74. package/src/setup/shipped.ts +8 -2
  75. package/src/setup/tables.ts +4 -3
  76. package/src/setup/waits.ts +9 -11
  77. package/src/setup/write.ts +17 -10
  78. package/src/slots/pool.ts +32 -24
  79. package/src/state/events.ts +1 -1
  80. package/src/state/faults.ts +13 -5
  81. package/src/state/format.ts +2 -2
  82. package/src/state/items.ts +9 -10
  83. package/src/state/open.ts +2 -2
  84. package/src/state/ops.ts +16 -10
  85. package/src/state/records.ts +5 -5
  86. package/src/state/runs.ts +33 -26
  87. package/src/state/saved.ts +44 -32
  88. package/src/status/file.ts +20 -1
  89. package/src/status/format.ts +47 -57
  90. package/src/status/sections.ts +2 -2
  91. package/src/worker/alignment-report.ts +4 -5
  92. package/src/worker/answers.ts +26 -24
  93. package/src/worker/base-check.ts +2 -2
  94. package/src/worker/kind.ts +23 -19
  95. package/src/worker/land.ts +114 -126
  96. package/src/worker/merged.ts +9 -7
  97. package/src/worker/open.ts +14 -12
  98. package/src/worker/prose-run.ts +3 -3
  99. package/src/worker/questions.ts +15 -12
  100. package/src/worker/scheduler.ts +4 -4
  101. package/src/worker/signature.ts +3 -3
  102. package/src/worker/tally.ts +0 -2
  103. package/src/worker/taste.ts +6 -15
  104. package/src/worker/thin-path.ts +148 -121
  105. package/src/worker/thread.ts +25 -0
  106. package/src/worker/worker.ts +77 -47
  107. package/surface.json +632 -2197
  108. package/src/slots/scan.ts +0 -26
@@ -1,4 +1,4 @@
1
- import { mkdirSync, readFileSync, statSync } from "node:fs";
1
+ import { mkdirSync, readFileSync, rmSync, statSync } from "node:fs";
2
2
  import { homedir } from "node:os";
3
3
  import { join } from "node:path";
4
4
  import { stripVTControlCharacters } from "node:util";
@@ -9,7 +9,7 @@ import { listRecords, orMissing } from "../state/fs.ts";
9
9
  import type { State } from "../state/open.ts";
10
10
  import { CARD_EXCERPT, type Card } from "../status/format.ts";
11
11
  import { SECOND_MS } from "../time.ts";
12
- import { type Finished, type RunOutcome, type RunRequest, type Runner, type RunnerOptions, START_ANSWER, START_PROMPT, START_SCHEMA, startRunner, succeeded } from "./claude-p.ts";
12
+ import { type Finished, type RunOutcome, type RunRequest, type Runner, type RunnerOptions, START_ANSWER, START_PROMPT, START_SCHEMA, startRunner, hasSucceeded } from "./claude-p.ts";
13
13
  import { type LimitEnded, limitOf, savedLimitUntil, settleLimit } from "./limit.ts";
14
14
  import { parseLooseJson } from "./marked.ts";
15
15
  import { billedTokens, cacheReadTokens, modelsOf, outputTokens, type RunTranscript, readTranscript } from "./transcript.ts";
@@ -31,8 +31,15 @@ const SINGLE_QUOTE = /'/g;
31
31
 
32
32
  const shellQuote = (text: string): string => `'${text.replace(SINGLE_QUOTE, `'\\''`)}'`;
33
33
 
34
- /** A hook command that saves the hook's input, which names the session and its transcript, as a file of its own. */
35
- const dropInto = (folder: string): string => `cat > ${shellQuote(folder)}/$$.json`;
34
+ /**
35
+ * A hook command that saves the hook's input, which names the session and its transcript, as a file of its own. It
36
+ * writes a temp file the folder's reader skips and renames it in, so a reader never meets half a report.
37
+ */
38
+ const dropInto = (folder: string): string => {
39
+ const at = shellQuote(folder);
40
+
41
+ return `cat > ${at}/$$.part && mv ${at}/$$.part ${at}/$$.json`;
42
+ };
36
43
 
37
44
  /** The settings every background run starts with: hum's plugin off, the deny rules and auto mode's rules, and a hook that reports the run. */
38
45
  export const backgroundSettings = ({ deniedRunCommands, runAutoMode }: Pick<HumConfig, "deniedRunCommands" | "runAutoMode">, stopsFolder: string, env: Readonly<Record<string, string>> = {}) => ({
@@ -172,12 +179,12 @@ export type BackgroundOptions = Pick<RunnerOptions, "binary" | "env" | "now"> &
172
179
  * transcript, enforces the token cap by `claude stop`, and stops and removes the run once its outcome is taken.
173
180
  * A cheap model call, a run with no name, and a run the background service cannot take go to `fallback`.
174
181
  */
175
- export const backgroundRunner = ({ binary = "claude", env, state, config, fallback, now = Date.now }: BackgroundOptions): Runner => {
182
+ export const backgroundRunner = ({ binary = "claude", env, state, config, fallback, now }: BackgroundOptions): Runner => {
176
183
  const pollMs = config.backgroundPollSeconds * SECOND_MS;
177
- const jobsFolder = join({ ...process.env, ...env }.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude"), JOBS_FOLDER);
184
+ const jobsFolder = join(env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude"), JOBS_FOLDER);
178
185
 
179
186
  const claude = (args: readonly string[], options: { stdin?: string; cwd?: string } = {}) =>
180
- exec(binary, args, { stdin: options.stdin, nodePath: false, timeoutMs: commandTimeoutMs(config), nodeOptions: { cwd: options.cwd, env: { ...process.env, ...env } } });
187
+ exec(binary, args, { stdin: options.stdin, nodePath: false, timeoutMs: commandTimeoutMs(config), nodeOptions: { cwd: options.cwd, env } });
181
188
 
182
189
  /** The background runs Claude Code lists. A list hum cannot read throws, with one card: read as empty, it would start a run that is already going. */
183
190
  const agents = async (): Promise<Agent[]> => {
@@ -192,18 +199,23 @@ export const backgroundRunner = ({ binary = "claude", env, state, config, fallba
192
199
  throw new Error(cause);
193
200
  }
194
201
 
195
- state.faults.clear(AGENTS_UNREAD);
202
+ state.faults.clear({ code: AGENTS_UNREAD });
196
203
 
197
204
  return found.flatMap(({ kind, id, name, sessionId, state }) => (kind === AGENT_VIEW_KIND && id !== undefined ? [{ id, name, sessionId, state }] : []));
198
205
  };
199
206
 
200
- const reportsOf = (sessionId: string): { at: number; event: string; transcriptPath: string | undefined }[] =>
207
+ const reportsOf = (sessionId: string): { file: string; at: number; event: string; transcriptPath: string | undefined }[] =>
201
208
  listRecords(state.stops).flatMap((file) => {
202
209
  const reported = orMissing(() => Reported.safeParse(JSON.parse(readFileSync(file, "utf8"))), undefined);
203
210
 
204
- return reported?.success && reported.data.session_id === sessionId ? [{ at: statSync(file).mtimeMs, event: reported.data.hook_event_name, transcriptPath: reported.data.transcript_path }] : [];
211
+ return reported?.success && reported.data.session_id === sessionId ? [{ file, at: statSync(file).mtimeMs, event: reported.data.hook_event_name, transcriptPath: reported.data.transcript_path }] : [];
205
212
  });
206
213
 
214
+ /** Drops the session's hook reports, so the stops folder holds only runs still going. */
215
+ const forget = (sessionId: string): void => {
216
+ for (const { file } of reportsOf(sessionId)) rmSync(file, { force: true });
217
+ };
218
+
207
219
  const jobTokens = (id: string): number => orMissing(() => JobFile.parse(JSON.parse(readFileSync(join(jobsFolder, id, JOB_STATE_FILE), "utf8"))).tokens ?? 0, 0);
208
220
 
209
221
  const readRun = async (id: string, sessionId: string): Promise<Reading> => {
@@ -246,9 +258,9 @@ export const backgroundRunner = ({ binary = "claude", env, state, config, fallba
246
258
  };
247
259
 
248
260
  const listed = async (id: string, signal: AbortSignal | undefined): Promise<Agent | undefined> => {
249
- const until = Date.now() + config.backgroundLaunchSeconds * SECOND_MS;
261
+ const until = now() + config.backgroundLaunchSeconds * SECOND_MS;
250
262
 
251
- while (Date.now() < until && !signal?.aborted) {
263
+ while (now() < until && !signal?.aborted) {
252
264
  const found = (await agents()).find((agent) => agent.id === id);
253
265
 
254
266
  if (found) return found;
@@ -259,6 +271,22 @@ export const backgroundRunner = ({ binary = "claude", env, state, config, fallba
259
271
  return undefined;
260
272
  };
261
273
 
274
+ /** The outcome a reading ends the run with, or `waiting` while it goes on. */
275
+ const endOf = (progress: Progress, sessionId: string, reading: Reading): RunOutcome | "waiting" => {
276
+ switch (progress.kind) {
277
+ case "waiting":
278
+ return "waiting";
279
+ case "over-cap":
280
+ return progress;
281
+ case "limit":
282
+ return settleLimit(state, progress.ended);
283
+ case "done":
284
+ return finishedOf(sessionId, reading, succeededWith(progress.structured));
285
+ case "failed":
286
+ return finishedOf(sessionId, reading, failedWith(progress.why));
287
+ }
288
+ };
289
+
262
290
  const watch = async (request: RunRequest, id: string, sessionId: string): Promise<RunOutcome> => {
263
291
  let announced = false;
264
292
 
@@ -272,15 +300,9 @@ export const backgroundRunner = ({ binary = "claude", env, state, config, fallba
272
300
  request.onFirstToken?.();
273
301
  }
274
302
 
275
- const progress = progressOf(reading, request.tokenCap);
276
-
277
- if (progress.kind === "over-cap") return progress;
278
-
279
- if (progress.kind === "limit") return settleLimit(state, progress.ended);
280
-
281
- if (progress.kind === "done") return finishedOf(sessionId, reading, succeededWith(progress.structured));
303
+ const ended = endOf(progressOf(reading, request.tokenCap), sessionId, reading);
282
304
 
283
- if (progress.kind === "failed") return finishedOf(sessionId, reading, failedWith(progress.why));
305
+ if (ended !== "waiting") return ended;
284
306
 
285
307
  await Bun.sleep(pollMs);
286
308
  }
@@ -304,7 +326,7 @@ export const backgroundRunner = ({ binary = "claude", env, state, config, fallba
304
326
 
305
327
  if (session === undefined) return request.signal?.aborted ? { kind: "stopped" } : fellBack(request, "the run never appeared in claude agents");
306
328
 
307
- state.faults.clear(FALLBACK_CODE);
329
+ state.faults.clear({ code: FALLBACK_CODE });
308
330
 
309
331
  request.onSession?.(session.sessionId);
310
332
 
@@ -312,6 +334,7 @@ export const backgroundRunner = ({ binary = "claude", env, state, config, fallba
312
334
  return await watch(request, id, session.sessionId);
313
335
  } finally {
314
336
  await end(id);
337
+ forget(session.sessionId);
315
338
  }
316
339
  };
317
340
 
@@ -334,7 +357,7 @@ export type BackgroundStartOptions = Omit<RunnerOptions, "state"> &
334
357
  readonly repo: string;
335
358
  };
336
359
 
337
- const isOk = (outcome: RunOutcome): boolean => outcome.kind === "finished" && succeeded(outcome) && START_ANSWER.safeParse(outcome.structured).success;
360
+ const isOk = (outcome: RunOutcome): boolean => outcome.kind === "finished" && hasSucceeded(outcome) && START_ANSWER.safeParse(outcome.structured).success;
338
361
 
339
362
  const startCheckFault = (repo: string, why: string) => ({
340
363
  code: BACKGROUND_CHECK_CODE,
@@ -365,27 +388,27 @@ const whyNot = (outcome: RunOutcome, timeoutMs: number): string => {
365
388
  * missing from agent view.
366
389
  */
367
390
  export const startBackgroundRunner = async (options: BackgroundStartOptions): Promise<StartedBackground> => {
368
- const { config, repo, state, binary, env } = options;
391
+ const { config, repo, state, binary, env, now } = options;
369
392
  const started = await startRunner(options);
370
393
 
371
394
  if (started.check.kind !== "finished") return started;
372
395
 
373
396
  // The check's own fall-back holds with the card that says why the service refused.
374
397
  const refuse: Runner = { run: async () => ({ kind: "held", card: refusalCard(state) }), limitedUntil: started.runner.limitedUntil };
375
- const checker = backgroundRunner({ binary, env, state, config, fallback: refuse });
398
+ const checker = backgroundRunner({ binary, env, state, config, fallback: refuse, now });
376
399
  const timeoutMs = commandTimeoutMs(config);
377
400
  const check = await checker.run({ name: START_NAME, prompt: START_PROMPT, cwd: repo, model: options.model, effort: "low", schema: START_SCHEMA, signal: AbortSignal.timeout(timeoutMs) });
378
401
 
379
402
  if (isOk(check)) {
380
- state.faults.clear(BACKGROUND_CHECK_CODE);
403
+ state.faults.clear({ code: BACKGROUND_CHECK_CODE });
381
404
 
382
- return { check, runner: backgroundRunner({ binary, env, state, config, fallback: started.runner }) };
405
+ return { check, runner: backgroundRunner({ binary, env, state, config, fallback: started.runner, now }) };
383
406
  }
384
407
 
385
408
  // The start check's card says why for every run, so the card for the check's own fall-back would only repeat it.
386
409
  const why = whyNot(check, timeoutMs);
387
410
 
388
- state.faults.clear(FALLBACK_CODE);
411
+ state.faults.clear({ code: FALLBACK_CODE });
389
412
  state.faults.raise(startCheckFault(repo, why));
390
413
 
391
414
  return { check, runner: started.runner };
@@ -8,14 +8,14 @@ import semver from "semver";
8
8
  import { x } from "tinyexec";
9
9
  import { z } from "zod";
10
10
  import type { EFFORTS } from "../config/schema.ts";
11
- import { CommandTimedOut, exec, SHIPPED_COMMAND_TIMEOUT_MS } from "../exec.ts";
12
- import { rejectedToken, UNAUTHORIZED } from "../service/token.ts";
11
+ import { CommandTimedOut, type Env, exec, SHIPPED_COMMAND_TIMEOUT_MS } from "../exec.ts";
12
+ import { raiseRejectedToken, UNAUTHORIZED } from "../service/token.ts";
13
13
  import { atomicWrite, isMissing } from "../state/fs.ts";
14
14
  import type { State } from "../state/open.ts";
15
15
  import { SECOND_MS } from "../time.ts";
16
16
  import { CARD_EXCERPT, type Card } from "../status/format.ts";
17
17
  import { LIMIT_TEXT, LIMIT_UNPARSED, type LimitEnded, limitOf, savedLimitUntil, settleLimit } from "./limit.ts";
18
- import { billed } from "./transcript.ts";
18
+ import { billed, Counts } from "./transcript.ts";
19
19
 
20
20
  export type Effort = (typeof EFFORTS)[number];
21
21
 
@@ -33,7 +33,7 @@ export const RUN_SETTINGS = JSON.stringify({
33
33
  * no settings source (plugins, MCP servers, memory files) and no built-in tool: a question needs neither, and each
34
34
  * one bills on every call.
35
35
  */
36
- export const CALLS = {
36
+ const CALLS = {
37
37
  run: { settings: RUN_SETTINGS, flags: [] },
38
38
  judgment: {
39
39
  settings: JSON.stringify({ permissions: { defaultMode: "bypassPermissions" }, disableAllHooks: true, outputStyle: "default" }),
@@ -41,7 +41,7 @@ export const CALLS = {
41
41
  },
42
42
  } as const satisfies Record<string, { settings: string; flags: readonly string[] }>;
43
43
 
44
- export type Call = keyof typeof CALLS;
44
+ type Call = keyof typeof CALLS;
45
45
 
46
46
  const REQUIRED_PLUGIN = "hope";
47
47
 
@@ -88,11 +88,7 @@ export const runArgs = ({ model, effort, schema, sessionId, call = "run", name }
88
88
  ...(name === undefined ? [] : ["-n", name]),
89
89
  ];
90
90
 
91
- const Usage = z.looseObject({
92
- input_tokens: z.number().default(0),
93
- output_tokens: z.number().default(0),
94
- cache_creation_input_tokens: z.number().default(0),
95
- });
91
+ const Usage = z.looseObject(Counts);
96
92
 
97
93
  const ModelUsage = z.looseObject({
98
94
  inputTokens: z.number().default(0),
@@ -229,7 +225,7 @@ export type RunOutcome =
229
225
  /** What one process ended as, before the runner acts on a limit it could not read. */
230
226
  type Ended = RunOutcome | LimitEnded;
231
227
 
232
- export const succeeded = (outcome: Finished): boolean => outcome.subtype === "success" && !outcome.isError;
228
+ export const hasSucceeded = (outcome: Finished): boolean => outcome.subtype === "success" && !outcome.isError;
233
229
 
234
230
  const LOCK_TEXT = /refresh[^\n]*lock|lock[^\n]*refresh/i;
235
231
 
@@ -322,9 +318,9 @@ export type RunnerOptions = {
322
318
  readonly binary?: string;
323
319
  /** The limit of `claude --version`, which the version floor reads, and of the start check; the owner's `commandTimeoutSeconds` in milliseconds. */
324
320
  readonly timeoutMs?: number;
325
- /** Added to the process environment. An API key in the environment is passed on untouched. */
326
- readonly env?: Readonly<Record<string, string>>;
327
- readonly now?: () => number;
321
+ /** The environment `claude` runs with, the process's own from the root. An API key in it is passed on untouched. */
322
+ readonly env: Env;
323
+ readonly now: () => number;
328
324
  /** The first wait before a run that hit the refresh-lock error runs again; later waits grow from it. */
329
325
  readonly lockBackoffMs?: number;
330
326
  };
@@ -368,7 +364,7 @@ const recordCredential = (state: RunnerOptions["state"], credential: string): vo
368
364
  return;
369
365
  }
370
366
 
371
- if (recorded === credential) return state.faults.clear("credential-changed");
367
+ if (recorded === credential) return state.faults.clear({ code: "credential-changed" });
372
368
 
373
369
  state.faults.raise({
374
370
  code: "credential-changed",
@@ -402,8 +398,7 @@ type Started = { readonly check: RunOutcome; readonly runner: Runner };
402
398
  * No run starts until the version floor and the start check pass; until then every run is held with one card.
403
399
  */
404
400
  const startChecked = async (options: RunnerOptions): Promise<Started> => {
405
- const { state, binary = "claude", now = Date.now, lockBackoffMs = LOCK_BACKOFF_MS, timeoutMs = SHIPPED_COMMAND_TIMEOUT_MS } = options;
406
- const env = { ...process.env, ...options.env };
401
+ const { state, binary = "claude", env, now, lockBackoffMs = LOCK_BACKOFF_MS, timeoutMs = SHIPPED_COMMAND_TIMEOUT_MS } = options;
407
402
  const limitedUntil = () => savedLimitUntil(state);
408
403
 
409
404
  const hold = (code: string, cause: string, fix: string): Extract<RunOutcome, { kind: "held" }> => ({
@@ -507,9 +502,9 @@ const startChecked = async (options: RunnerOptions): Promise<Started> => {
507
502
 
508
503
  if (outcome.kind !== "finished") return outcome;
509
504
 
510
- if (isUnauthorized(outcome)) return { kind: "held", card: rejectedToken(state.faults, outcome.text) };
505
+ if (isUnauthorized(outcome)) return { kind: "held", card: raiseRejectedToken(state.faults, outcome.text) };
511
506
 
512
- state.faults.clear("token-rejected");
507
+ state.faults.clear({ code: "token-rejected" });
513
508
 
514
509
  return outcome;
515
510
  };
@@ -550,7 +545,7 @@ const startChecked = async (options: RunnerOptions): Promise<Started> => {
550
545
 
551
546
  const hasPlugin = check.plugins.includes(REQUIRED_PLUGIN);
552
547
 
553
- if (!succeeded(check) || !hasPlugin) {
548
+ if (!hasSucceeded(check) || !hasPlugin) {
554
549
  return held(
555
550
  hold(
556
551
  "start-check-failed",
@@ -562,8 +557,8 @@ const startChecked = async (options: RunnerOptions): Promise<Started> => {
562
557
 
563
558
  recordCredential(state, credentialOf(check.keySource, env));
564
559
 
565
- state.faults.clear(LIMIT_UNPARSED);
566
- state.faults.clear(START_TIMED_OUT);
560
+ state.faults.clear({ code: LIMIT_UNPARSED });
561
+ state.faults.clear({ code: START_TIMED_OUT });
567
562
 
568
563
  return { check, runner: { run, limitedUntil } };
569
564
  };
@@ -576,7 +571,7 @@ const isUnsettled = ({ check }: Started): boolean => check.kind === "limited" ||
576
571
  * limit that still stands defers the check, so no call is made before the limit ends and no restart is needed.
577
572
  */
578
573
  export const startRunner = async (options: RunnerOptions): Promise<Started> => {
579
- const { state, now = Date.now } = options;
574
+ const { state, now } = options;
580
575
  const started = pMemoize(() => startChecked(options));
581
576
 
582
577
  const settle = async (): Promise<Started> => {
@@ -1,6 +1,7 @@
1
1
  import assert from "node:assert/strict";
2
- import { type Adapter, type Answers, ClaimResult, Item, ItemRef, type Questions, type Release, Watch, type WorkSource } from "../adapter-api.ts";
2
+ import { type Adapter, type Answers, ClaimResult, Failed, type Fallible, Holder, Item, ItemId, ItemRef, type Questions, type Release, Watch, type WorkSource } from "../adapter-api.ts";
3
3
  import type { ClaimMode } from "./claim.ts";
4
+ import { eachCall } from "./each-call.ts";
4
5
 
5
6
  /**
6
7
  * What the contract suite needs from one provider. Reads hit the provider; writes go to a scratch
@@ -12,7 +13,7 @@ export type ContractTarget = {
12
13
  /** A second worker on the same scratch target, for races. Defaults to `adapter`. */
13
14
  readonly other?: () => Promise<Adapter>;
14
15
  /** Puts a ready item on the scratch target and returns its id. */
15
- readonly seed: (title: string) => Promise<string>;
16
+ readonly seed: (title: string) => Promise<ItemId>;
16
17
  /** Moves the provider's clock forward, so a claim expires. */
17
18
  readonly advance: (ms: number) => Promise<void>;
18
19
  /** Requests so far that spent rate limit. */
@@ -31,14 +32,25 @@ const need = <T>(value: T | undefined, what: string): T => {
31
32
  return value;
32
33
  };
33
34
 
35
+ /** `integration` with a `Failed` reply turned into a failed check, in the adapter's own words. */
36
+ const answering = <I extends object>(integration: Fallible<I>): I =>
37
+ eachCall<Fallible<I>, I>(integration, (call, name) => async (...args) => {
38
+ const reply = await call(...args);
39
+ const failed = Failed.safeParse(reply);
40
+
41
+ assert.ok(!failed.success, `${name} answered failed ${failed.data?.failed}: ${failed.data?.why}`);
42
+
43
+ return reply;
44
+ });
45
+
34
46
  const workSourceChecks = (target: ContractTarget, source: WorkSource): Check[] => {
35
47
  const second = async () => (target.other ? target.other() : target.adapter);
36
- const readItem = async (id: string) => Item.parse(await source.read(id));
48
+ const readItem = async (id: ItemId) => Item.parse(await source.read(id));
37
49
  const ready = async () => ItemRef.array().parse(await source.listReady());
38
- const isListed = async (id: string) => (await ready()).some((ref) => ref.id === id);
50
+ const isListed = async (id: ItemId) => (await ready()).some((ref) => ref.id === id);
39
51
 
40
- const claimOf = async (who: Adapter, id: string, holder: string, mode: ClaimMode = "claim") =>
41
- ClaimResult.parse(await need(who.workSource, "no work source")[mode](id, holder, TTL));
52
+ const claimOf = async (who: Adapter, id: ItemId, holder: string, mode: ClaimMode = "claim") =>
53
+ ClaimResult.parse(await answering<WorkSource>(need(who.workSource, "no work source"))[mode](id, Holder.parse(holder), TTL));
42
54
 
43
55
  return [
44
56
  {
@@ -199,13 +211,13 @@ const releaseChecks = (target: ContractTarget, release: Release): Check[] => [
199
211
  /** The checks every adapter runs for the integrations it provides. */
200
212
  export const contractChecks = (target: ContractTarget): Check[] => {
201
213
  const { questions, answers, release } = target.adapter;
202
- const source = need(target.adapter.workSource, `${target.name} provides no work source`);
214
+ const source = answering<WorkSource>(need(target.adapter.workSource, `${target.name} provides no work source`));
203
215
 
204
216
  return [
205
217
  ...workSourceChecks(target, source),
206
- ...(questions ? questionChecks(target, source, questions) : []),
207
- ...(answers ? answerChecks(target, source, answers) : []),
208
- ...(release ? releaseChecks(target, release) : []),
218
+ ...(questions ? questionChecks(target, source, answering<Questions>(questions)) : []),
219
+ ...(answers ? answerChecks(target, source, answering<Answers>(answers)) : []),
220
+ ...(release ? releaseChecks(target, answering<Release>(release)) : []),
209
221
  ];
210
222
  };
211
223
 
@@ -0,0 +1,9 @@
1
+ type Wrap = <A extends unknown[], R>(call: (...args: A) => Promise<R>, name: string) => (...args: A) => Promise<R>;
2
+
3
+ /**
4
+ * `role` with each of its calls passed through `wrap`, and its other members kept.
5
+ * SAFETY: every member of an integration role that is a function is an async method, and `wrap` keeps its
6
+ * parameters; the caller names the role type the wrapped calls answer as.
7
+ */
8
+ export const eachCall = <R extends object, W extends object>(role: R, wrap: Wrap): W =>
9
+ Object.fromEntries(Object.entries(role).map(([name, member]) => [name, member instanceof Function ? wrap(async (...args: unknown[]) => member.apply(role, args), name) : member])) as W;
@@ -1,8 +1,8 @@
1
- import { type Adapter, type Claim, type ItemRef, PermanentError, type ThreadEntry, type Watch } from "../adapter-api.ts";
1
+ import { ADAPTER_API_VERSION, type Claim, type Integrations, ItemId, type ItemRef, PermanentError, type ThreadEntry, type Watch } from "../adapter-api.ts";
2
2
  import { claimer, isLive } from "./claim.ts";
3
3
  import { questionText } from "./marked.ts";
4
4
 
5
- type Stored = { id: string; title: string; body: string; ready: boolean; thread: ThreadEntry[]; claim?: Claim; from?: string };
5
+ type Stored = { id: ItemId; title: string; body: string; ready: boolean; thread: ThreadEntry[]; claim?: Claim; from?: string };
6
6
 
7
7
  /** A provider failure a retry can outlast, like a GitHub 502. */
8
8
  export class ProviderError extends Error {
@@ -48,8 +48,8 @@ export class FakeProvider {
48
48
  this.#emptyList = value;
49
49
  }
50
50
 
51
- seed(title: string, { ready = true }: { ready?: boolean } = {}): string {
52
- const id = `item-${this.#items.size + 1}`;
51
+ seed(title: string, { ready = true }: { ready?: boolean } = {}): ItemId {
52
+ const id = ItemId.parse(`item-${this.#items.size + 1}`);
53
53
 
54
54
  this.#items.set(id, { id, title, body: `${title} body`, ready, thread: [] });
55
55
  this.#version++;
@@ -107,12 +107,12 @@ export class FakeProvider {
107
107
  this.now,
108
108
  );
109
109
 
110
- adapter(): Adapter {
110
+ adapter(): Integrations {
111
111
  const asRef = ({ id, title }: Stored): ItemRef => ({ id, title });
112
112
  const spend = <T>(body: () => T) => this.#call(true, body);
113
113
 
114
114
  return {
115
- apiVersion: 1,
115
+ apiVersion: ADAPTER_API_VERSION,
116
116
  workSource: {
117
117
  listReady: async () =>
118
118
  spend(() => this.listReplacement?.() ?? (this.#emptyList ? [] : [...this.#items.values()].flatMap((item) => (this.#isReady(item) ? [asRef(item)] : [])))),
@@ -1,4 +1,3 @@
1
- import { PermanentError } from "../adapter-api.ts";
2
1
  import { exec } from "../exec.ts";
3
2
 
4
3
  /** No hook runs: the hooks path points nowhere, whatever the clone's own config says. */
@@ -15,7 +14,7 @@ export const PATCH = ["--no-ext-diff", "--no-color"] as const;
15
14
  const ANCESTOR = 0;
16
15
  const NOT_ANCESTOR = 1;
17
16
 
18
- export type GitResult = { readonly code: number; readonly stdout: string; readonly stderr: string };
17
+ type GitResult = { readonly code: number; readonly stdout: string; readonly stderr: string };
19
18
 
20
19
  export type Git = {
21
20
  /** Runs git; a non-zero exit is a result, not a throw, but a run past its time limit throws `CommandTimedOut`. `input` is its stdin, which is closed either way. */
@@ -24,7 +23,7 @@ export type Git = {
24
23
  readonly raw: (args: readonly string[], input?: string) => Promise<string>;
25
24
  };
26
25
 
27
- export class GitFailed extends Error {
26
+ class GitFailed extends Error {
28
27
  override name = "GitFailed";
29
28
 
30
29
  constructor(
@@ -44,12 +43,8 @@ export const whenGitFailed =
44
43
  throw error;
45
44
  };
46
45
 
47
- /** The remote refused the push: a protected branch, a hook, a permission. Retrying cannot help. */
48
- export class PushRefused extends PermanentError {
49
- override name = "PushRefused";
50
- }
51
-
52
- export type PushOutcome = "pushed" | "conflict";
46
+ /** `conflict`: another writer moved the ref first, and a retry can win. `refused`: the remote said no, in `said`, and no retry helps. */
47
+ export type PushOutcome = { readonly kind: "pushed" } | { readonly kind: "conflict" } | { readonly kind: "refused"; readonly said: string };
53
48
 
54
49
  /** The author and committer of the commits hum makes. */
55
50
  export type GitIdentity = { readonly name: string; readonly email: string };
@@ -95,7 +90,7 @@ export const gitIn = (cwd: string, { identity, env = {}, timeoutMs }: GitOptions
95
90
  const run = async (args: readonly string[], input = ""): Promise<GitResult> => {
96
91
  const { exitCode, stdout, stderr } = await exec("git", ["-c", HOOKS_OFF, ...args], {
97
92
  timeoutMs,
98
- nodeOptions: { cwd, env: { ...process.env, ...(identity && identityEnv(identity)), ...env } },
93
+ nodeOptions: { cwd, env: { ...(identity && identityEnv(identity)), ...env } },
99
94
  stdin: input,
100
95
  });
101
96
 
@@ -116,26 +111,23 @@ export const gitIn = (cwd: string, { identity, env = {}, timeoutMs }: GitOptions
116
111
  /** The arguments for `git push` with hooks off, for a command line handed straight to git. */
117
112
  export const pushArgs = (rest: readonly string[]): string[] => ["-c", HOOKS_OFF, "push", "--no-verify", ...rest];
118
113
 
119
- /**
120
- * Pushes. `conflict` means another writer moved the ref first and a retry can win.
121
- * A refusal throws `PushRefused` with the remote's own words; any other failure throws `GitFailed`.
122
- */
114
+ /** Pushes. A refusal is an outcome that carries the remote's own words; any other failure throws `GitFailed`. */
123
115
  export const push = async (git: Git, rest: readonly string[]): Promise<PushOutcome> => {
124
116
  const args = ["push", "--no-verify", ...rest];
125
117
  const result = await git.run(args);
126
118
  const said = `${result.stderr}${result.stdout}`.trim();
127
119
 
128
- if (result.code === 0) return "pushed";
120
+ if (result.code === 0) return { kind: "pushed" };
129
121
 
130
- if (CONFLICT.test(said)) return "conflict";
122
+ if (CONFLICT.test(said)) return { kind: "conflict" };
131
123
 
132
- if (REFUSED.test(said)) throw new PushRefused(`git push refused: ${said}`);
124
+ if (REFUSED.test(said)) return { kind: "refused", said: `git push refused: ${said}` };
133
125
 
134
126
  throw new GitFailed(args, result);
135
127
  };
136
128
 
137
129
  /** Whether `ancestor` is reachable from `descendant`. git answers by exit code alone. */
138
- export const isAncestor = async (git: Git, ancestor: string, descendant: string): Promise<boolean> => {
130
+ export const isAncestor = async (git: Git, { ancestor, descendant }: { readonly ancestor: string; readonly descendant: string }): Promise<boolean> => {
139
131
  const args = ["merge-base", "--is-ancestor", ancestor, descendant];
140
132
  const result = await git.run(args);
141
133
 
@@ -0,0 +1,102 @@
1
+ import { Octokit } from "@octokit/core";
2
+ import { GraphqlResponseError } from "@octokit/graphql";
3
+ import { paginateGraphQL } from "@octokit/plugin-paginate-graphql";
4
+ import { type ThrottlingOptions, throttling } from "@octokit/plugin-throttling";
5
+ import { RequestError } from "@octokit/request-error";
6
+ import pMemoize from "p-memoize";
7
+ import { PermanentError } from "../adapter-api.ts";
8
+ import type { MERGE_METHODS } from "../config/schema.ts";
9
+ import { type Env, exec } from "../exec.ts";
10
+
11
+ const RATE_LIMIT_RETRIES = 1;
12
+ const NOT_MODIFIED = 304;
13
+
14
+ const HumOctokit = Octokit.plugin(throttling, paginateGraphQL);
15
+
16
+ export type GitHubClient = InstanceType<typeof HumOctokit>;
17
+
18
+ /** The GraphQL name of each merge method. */
19
+ export const MERGE_METHOD = { merge: "MERGE", squash: "SQUASH", rebase: "REBASE" } as const satisfies Record<(typeof MERGE_METHODS)[number], string>;
20
+
21
+ /** What a failed request means to hum. */
22
+ type Failure =
23
+ /** GitHub answered 304 to a conditional request: nothing changed, and no rate limit was spent. */
24
+ | { readonly kind: "not-modified" }
25
+ /** Another writer took the ref first: it already exists, or it moved since it was read. */
26
+ | { readonly kind: "lost-race" }
27
+ /** No retry fixes it: a 4xx other than a rate limit, or a GraphQL error about the request itself. */
28
+ | { readonly kind: "permanent"; readonly message: string }
29
+ | { readonly kind: "transient" };
30
+
31
+ /** GraphQL errors about the request itself; any other, such as a timeout GitHub reports, may pass on a retry. */
32
+ const PERMANENT_GRAPHQL_ERRORS: ReadonlySet<string> = new Set(["NOT_FOUND", "FORBIDDEN", "UNPROCESSABLE"]);
33
+
34
+ const isRateLimited = (error: RequestError): boolean => error.status === 429 || (error.status === 403 && error.response?.headers["x-ratelimit-remaining"] === "0");
35
+
36
+ export const failureOf = (cause: unknown): Failure => {
37
+ if (cause instanceof RequestError) {
38
+ if (cause.status === NOT_MODIFIED) return { kind: "not-modified" };
39
+
40
+ return cause.status >= 400 && cause.status < 500 && !isRateLimited(cause) ? { kind: "permanent", message: cause.message } : { kind: "transient" };
41
+ }
42
+
43
+ const found = cause instanceof GraphqlResponseError ? cause.errors?.[0] : undefined;
44
+
45
+ if (found?.type === "STALE_DATA" || (found?.type === "UNPROCESSABLE" && /already exists/i.test(found.message))) return { kind: "lost-race" };
46
+
47
+ return found && PERMANENT_GRAPHQL_ERRORS.has(found.type ?? "") ? { kind: "permanent", message: found.message } : { kind: "transient" };
48
+ };
49
+
50
+ /** Throws `cause`, marked permanent when no retry can fix it. */
51
+ export const raise = (cause: unknown): never => {
52
+ const failure = failureOf(cause);
53
+
54
+ throw failure.kind === "permanent" ? new PermanentError(failure.message, { cause }) : cause;
55
+ };
56
+
57
+ /** The owner's own login: `GH_TOKEN` or `GITHUB_TOKEN`, else the token `gh` holds. */
58
+ const ownerToken = async (timeoutMs: number, env: Env): Promise<string> => {
59
+ const fromEnv = env.GH_TOKEN || env.GITHUB_TOKEN;
60
+
61
+ if (fromEnv) return fromEnv;
62
+
63
+ const gh = await exec("gh", ["auth", "token"], { stdin: "", timeoutMs });
64
+ const token = gh.stdout.trim();
65
+
66
+ if (gh.exitCode !== 0 || token === "") throw new PermanentError("no GitHub login: run `gh auth login`, or set GH_TOKEN");
67
+
68
+ return token;
69
+ };
70
+
71
+ const retryOnce: NonNullable<ThrottlingOptions["onRateLimit"]> = (_retryAfter, _options, _octokit, retryCount) => retryCount < RATE_LIMIT_RETRIES;
72
+
73
+ type Send = (url: string, init?: RequestInit) => Promise<Response>;
74
+
75
+ export type GitHubClientOptions = {
76
+ readonly token: string;
77
+ readonly baseUrl?: string;
78
+ /** Replaces `fetch`, for a GitHub that is not github.com. */
79
+ readonly fetch?: Send;
80
+ /** Whether writes are spaced as GitHub asks; only a GitHub with no secondary rate limit may go without. */
81
+ readonly spaced?: boolean;
82
+ /** The owner's `commandTimeoutSeconds` in milliseconds: how long one request may wait for GitHub's answer. */
83
+ readonly timeoutMs: number;
84
+ };
85
+
86
+ const bounded =
87
+ (send: Send, timeoutMs: number): Send =>
88
+ (url, init) =>
89
+ send(url, { ...init, signal: AbortSignal.any([AbortSignal.timeout(timeoutMs), ...(init?.signal ? [init.signal] : [])]) });
90
+
91
+ /** A GitHub client that waits out rate limits, spaces its writes as GitHub asks, and gives up on a request GitHub has not answered within `timeoutMs`. */
92
+ export const gitHubClient = ({ token, baseUrl, fetch = globalThis.fetch, spaced = true, timeoutMs }: GitHubClientOptions): GitHubClient =>
93
+ new HumOctokit({
94
+ auth: token,
95
+ userAgent: "hum",
96
+ baseUrl,
97
+ request: { fetch: bounded(fetch, timeoutMs) },
98
+ throttle: { enabled: spaced, onRateLimit: retryOnce, onSecondaryRateLimit: retryOnce },
99
+ });
100
+
101
+ /** The client on the owner's own login, made once per process and `timeoutMs`, so every reader and writer shares its rate-limit spacing. */
102
+ export const ownerGitHub = pMemoize(async (timeoutMs: number, env: Env): Promise<GitHubClient> => gitHubClient({ token: await ownerToken(timeoutMs, env), timeoutMs }), { cacheKey: ([timeoutMs]) => timeoutMs });