@moo.md/hum 0.0.0-stage → 0.0.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 (150) hide show
  1. package/defaults/hum.json +321 -0
  2. package/defaults/kinds/check.json +183 -0
  3. package/defaults/kinds/docs.json +151 -0
  4. package/defaults/kinds/feature.json +202 -0
  5. package/defaults/kinds/fix.json +183 -0
  6. package/defaults/kinds/hotfix.json +164 -0
  7. package/defaults/roles/build.md +3 -0
  8. package/defaults/roles/fix.md +1 -0
  9. package/defaults/roles/plan.md +3 -0
  10. package/defaults/roles/review.md +3 -0
  11. package/evals/alignment/RESULTS.md +8 -0
  12. package/evals/alignment/cases.jsonl +128 -0
  13. package/evals/alignment/sample.jsonl +20 -0
  14. package/evals/kind/RESULTS.md +5 -0
  15. package/evals/kind/cases.jsonl +24 -0
  16. package/evals/plan-outcome/RESULTS.md +4 -0
  17. package/evals/plan-outcome/cases.jsonl +12 -0
  18. package/evals/repeat-pair/RESULTS.md +4 -0
  19. package/evals/repeat-pair/cases.jsonl +51 -0
  20. package/evals/reply-option/RESULTS.md +3 -0
  21. package/evals/reply-option/cases.jsonl +45 -0
  22. package/evals/review-verdict/RESULTS.md +4 -0
  23. package/evals/review-verdict/cases.jsonl +12 -0
  24. package/package.json +88 -4
  25. package/schema/hum.schema.json +1355 -0
  26. package/scripts/eval.ts +244 -0
  27. package/src/adapter-api.ts +134 -0
  28. package/src/adapters/admit.ts +111 -0
  29. package/src/adapters/argument.ts +11 -0
  30. package/src/adapters/claim.ts +93 -0
  31. package/src/adapters/claude-bg.ts +375 -0
  32. package/src/adapters/claude-p.ts +593 -0
  33. package/src/adapters/contract.ts +231 -0
  34. package/src/adapters/fake.ts +157 -0
  35. package/src/adapters/git.ts +155 -0
  36. package/src/adapters/github.ts +457 -0
  37. package/src/adapters/guard.ts +152 -0
  38. package/src/adapters/history.ts +215 -0
  39. package/src/adapters/item-file.ts +102 -0
  40. package/src/adapters/limit.ts +67 -0
  41. package/src/adapters/markdown.ts +365 -0
  42. package/src/adapters/marked.ts +119 -0
  43. package/src/adapters/model-call.ts +75 -0
  44. package/src/adapters/once.ts +45 -0
  45. package/src/adapters/owner-commit.ts +60 -0
  46. package/src/adapters/pull-requests.ts +253 -0
  47. package/src/adapters/registry.ts +156 -0
  48. package/src/adapters/roundup.ts +291 -0
  49. package/src/adapters/serial.ts +22 -0
  50. package/src/adapters/transcript.ts +99 -0
  51. package/src/cli/commands.ts +46 -0
  52. package/src/cli/main.ts +8 -0
  53. package/src/cli/ops.ts +224 -0
  54. package/src/cli/service.ts +156 -0
  55. package/src/cli/setup.ts +141 -0
  56. package/src/cli/shared-watch.ts +127 -0
  57. package/src/config/change.ts +54 -0
  58. package/src/config/checks.ts +217 -0
  59. package/src/config/git-ref-name.d.ts +3 -0
  60. package/src/config/hash.ts +6 -0
  61. package/src/config/json.ts +6 -0
  62. package/src/config/load.ts +88 -0
  63. package/src/config/machine.ts +20 -0
  64. package/src/config/migrate.ts +61 -0
  65. package/src/config/refusal.ts +58 -0
  66. package/src/config/schema.ts +465 -0
  67. package/src/config/settings.ts +6 -0
  68. package/src/config/state-map.ts +76 -0
  69. package/src/decide/alignment.ts +79 -0
  70. package/src/decide/answer.ts +131 -0
  71. package/src/decide/kind.ts +39 -0
  72. package/src/decide/labels.ts +137 -0
  73. package/src/decide/merge.ts +102 -0
  74. package/src/decide/prose.ts +109 -0
  75. package/src/decide/question.ts +159 -0
  76. package/src/decide/review.ts +10 -0
  77. package/src/decide/risk.ts +216 -0
  78. package/src/decide/taste.ts +37 -0
  79. package/src/exec.ts +80 -0
  80. package/src/index.ts +200 -0
  81. package/src/loop/breaks.ts +8 -0
  82. package/src/loop/check-item.ts +76 -0
  83. package/src/loop/ci.ts +8 -0
  84. package/src/loop/github.ts +81 -0
  85. package/src/loop/groups.ts +108 -0
  86. package/src/loop/memory.ts +70 -0
  87. package/src/loop/notes.ts +76 -0
  88. package/src/loop/pair.ts +39 -0
  89. package/src/loop/pass.ts +99 -0
  90. package/src/loop/proof.ts +85 -0
  91. package/src/loop/prove-item.ts +33 -0
  92. package/src/loop/records.ts +75 -0
  93. package/src/loop/signals.ts +130 -0
  94. package/src/measure/inputs.ts +28 -0
  95. package/src/measure/measure.ts +68 -0
  96. package/src/service/cards.ts +24 -0
  97. package/src/service/ci-tick.ts +28 -0
  98. package/src/service/launchd.ts +16 -0
  99. package/src/service/supervise.ts +145 -0
  100. package/src/service/systemd.ts +44 -0
  101. package/src/service/token.ts +21 -0
  102. package/src/service/unit.ts +29 -0
  103. package/src/service/wake.ts +30 -0
  104. package/src/service/workflows.ts +97 -0
  105. package/src/setup/propose.ts +120 -0
  106. package/src/setup/prove.ts +216 -0
  107. package/src/setup/scan.ts +186 -0
  108. package/src/setup/scratch.ts +81 -0
  109. package/src/setup/shipped.ts +15 -0
  110. package/src/setup/tables.ts +101 -0
  111. package/src/setup/waits.ts +58 -0
  112. package/src/setup/write.ts +161 -0
  113. package/src/slots/env.ts +42 -0
  114. package/src/slots/pool.ts +329 -0
  115. package/src/slots/scan.ts +26 -0
  116. package/src/slots/worktree.ts +17 -0
  117. package/src/state/events.ts +52 -0
  118. package/src/state/faults.ts +73 -0
  119. package/src/state/format.ts +50 -0
  120. package/src/state/fs.ts +100 -0
  121. package/src/state/items.ts +189 -0
  122. package/src/state/open.ts +80 -0
  123. package/src/state/ops.ts +76 -0
  124. package/src/state/records.ts +35 -0
  125. package/src/state/runs.ts +99 -0
  126. package/src/state/saved.ts +119 -0
  127. package/src/status/file.ts +49 -0
  128. package/src/status/format.ts +132 -0
  129. package/src/status/sections.ts +14 -0
  130. package/src/status/version.ts +2 -0
  131. package/src/time.ts +7 -0
  132. package/src/worker/alignment-report.ts +18 -0
  133. package/src/worker/answers.ts +153 -0
  134. package/src/worker/base-check.ts +46 -0
  135. package/src/worker/checks.ts +26 -0
  136. package/src/worker/kind.ts +68 -0
  137. package/src/worker/land.ts +508 -0
  138. package/src/worker/lifecycle.ts +97 -0
  139. package/src/worker/merged.ts +29 -0
  140. package/src/worker/open.ts +100 -0
  141. package/src/worker/prose-run.ts +56 -0
  142. package/src/worker/questions.ts +89 -0
  143. package/src/worker/scheduler.ts +135 -0
  144. package/src/worker/signature.ts +41 -0
  145. package/src/worker/tally.ts +25 -0
  146. package/src/worker/taste.ts +38 -0
  147. package/src/worker/thin-path.ts +886 -0
  148. package/src/worker/worker.ts +728 -0
  149. package/surface.json +8787 -0
  150. package/README.md +0 -3
@@ -0,0 +1,97 @@
1
+ import { createActor, createAsyncLogic, setup, toPromise } from "xstate";
2
+ import { z } from "zod";
3
+
4
+ export type TickResult =
5
+ | { readonly kind: "ran"; readonly started: readonly string[] }
6
+ /** An update was seen; no new run starts, and the worker exits once its runs end. */
7
+ | { readonly kind: "draining"; readonly reason: string }
8
+ | { readonly kind: "exit"; readonly reason: string };
9
+
10
+ export type Exit = { readonly reason: string };
11
+
12
+ export type LifecycleOptions = {
13
+ readonly tick: () => Promise<TickResult>;
14
+ /** Stops every run in flight and resolves once they have ended. */
15
+ readonly stopRuns: () => Promise<void>;
16
+ readonly tickIntervalMs: number;
17
+ readonly drainTimeoutMs: number;
18
+ };
19
+
20
+ type Phase = "serving" | "draining" | "exited";
21
+
22
+ /** Where a tick's result leads, whichever phase the worker was in. */
23
+ const PHASE_AFTER = { ran: "serving", draining: "draining", exit: "exited" } as const satisfies Record<TickResult["kind"], Phase>;
24
+
25
+ const Context = z.object({ woken: z.boolean(), reason: z.string() });
26
+
27
+ type Context = z.infer<typeof Context>;
28
+
29
+ const STOPPED: Exit = { reason: "stopped" };
30
+
31
+ /** The transition after a tick: to the phase its result names, else straight into the next tick when woken, else to rest. */
32
+ const afterTick = (phase: Exclude<Phase, "exited">, context: Context, result: TickResult) => {
33
+ const next = PHASE_AFTER[result.kind];
34
+ const reason = result.kind === "ran" ? context.reason : result.reason;
35
+
36
+ if (next === "exited") return { target: "#worker.exited", context: { ...context, reason } };
37
+
38
+ if (next !== phase) return { target: `#worker.${next}.resting`, context: { ...context, reason } };
39
+
40
+ return context.woken ? { target: "ticking", reenter: true } : { target: "resting" };
41
+ };
42
+
43
+ /**
44
+ * The worker's life as a machine. It ticks, rests for the tick interval, and ticks again at once when woken; a
45
+ * wake that arrives during a tick makes one more tick, however many arrive. A tick that sees an update moves it to
46
+ * draining, where it still ticks, so claims are renewed and the heartbeat stays fresh, and the runs still going
47
+ * are stopped once the drain timeout passes. It ends when a tick finds nothing left to wait for, or on `stop`.
48
+ */
49
+ const lifecycleMachine = ({ tick, stopRuns, tickIntervalMs, drainTimeoutMs }: LifecycleOptions) => {
50
+ const worker = setup({
51
+ schemas: { context: Context, events: { wake: z.object({}), stop: z.object({}) } },
52
+ delays: { tickInterval: tickIntervalMs, drainTimeout: drainTimeoutMs },
53
+ actors: { tick: createAsyncLogic({ run: tick }), stopRuns: createAsyncLogic({ run: stopRuns }) },
54
+ });
55
+
56
+ const cycle = (phase: Exclude<Phase, "exited">) =>
57
+ ({
58
+ ticking: {
59
+ entry: ({ context }: { context: Context }) => ({ context: { ...context, woken: false } }),
60
+ invoke: { src: "tick", onDone: ({ context, event }: { context: Context; event: { output: TickResult } }) => afterTick(phase, context, event.output) },
61
+ on: { wake: ({ context }: { context: Context }) => ({ context: { ...context, woken: true } }) },
62
+ },
63
+ resting: {
64
+ after: { tickInterval: { target: "ticking" } },
65
+ on: { wake: { target: "ticking" } },
66
+ },
67
+ }) as const;
68
+
69
+ return worker.createMachine({
70
+ id: "worker",
71
+ context: { woken: false, reason: "" },
72
+ initial: "serving",
73
+ on: { stop: { target: "#worker.stopping" } },
74
+ states: {
75
+ serving: { initial: "ticking", states: cycle("serving") },
76
+ draining: { initial: "ticking", states: cycle("draining"), after: { drainTimeout: (_, enq) => void enq(() => void stopRuns()) } },
77
+ stopping: { on: { stop: undefined }, invoke: { src: "stopRuns", onDone: { target: "stopped" } } },
78
+ exited: { type: "final", output: ({ context }): Exit => ({ reason: context.reason }) },
79
+ stopped: { type: "final", output: STOPPED },
80
+ },
81
+ });
82
+ };
83
+
84
+ export type Lifecycle = { readonly wake: () => void; readonly ended: Promise<Exit> };
85
+
86
+ /** Starts the machine. `stop` ends it after the runs have stopped; `wake` asks for a tick now. */
87
+ export const runLifecycle = (options: LifecycleOptions, stop?: AbortSignal): Lifecycle => {
88
+ const actor = createActor(lifecycleMachine(options)).start();
89
+ const halt = () => actor.send({ type: "stop" });
90
+
91
+ if (stop?.aborted) halt();
92
+ else stop?.addEventListener("abort", halt, { once: true });
93
+
94
+ const ended: Promise<Exit> = toPromise(actor).finally(() => stop?.removeEventListener("abort", halt));
95
+
96
+ return { wake: () => actor.send({ type: "wake" }), ended };
97
+ };
@@ -0,0 +1,29 @@
1
+ import type { PullRequests } from "../adapters/pull-requests.ts";
2
+ import type { State } from "../state/open.ts";
3
+
4
+ /**
5
+ * An item's change reached the base: the merge is kept for the measure, the saved landing, plan and verdict go,
6
+ * and the merge is logged once per commit.
7
+ */
8
+ export const recordMerged = (state: State, item: string, sha: string, at: number): void => {
9
+ const landing = state.landings.get(item);
10
+
11
+ state.merges.put(item, { item, sha, at, paths: landing?.change.paths ?? [] });
12
+ state.landings.remove(item);
13
+ state.plans.remove(item);
14
+ state.verdicts.remove(item);
15
+ state.events.add({ source: "work-source", sourceId: `merged:${sha}`, itemId: item, type: "merged", payload: {} });
16
+ };
17
+
18
+ /**
19
+ * A change that landed through a pull request is merged by GitHub after the worker has moved on, and the item is never
20
+ * listed again. Each saved landing whose pull request has merged is recorded as merged, so the measure counts it.
21
+ */
22
+ export const settleMergedPulls = async (state: State, pulls: Pick<PullRequests, "find">, at: number): Promise<void> => {
23
+ for (const { item, branch, head } of state.landings.list()) {
24
+ if ((await pulls.find(branch))?.state !== "MERGED") continue;
25
+
26
+ recordMerged(state, item, head, at);
27
+ state.items.remove(item);
28
+ }
29
+ };
@@ -0,0 +1,100 @@
1
+ import { join } from "node:path";
2
+ import { z } from "zod";
3
+ import type { Adapter } from "../adapter-api.ts";
4
+ import { resolveAdapters } from "../adapters/registry.ts";
5
+ import { startBackgroundRunner } from "../adapters/claude-bg.ts";
6
+ import { startRunner } from "../adapters/claude-p.ts";
7
+ import { gitIn } from "../adapters/git.ts";
8
+ import { gitHubClient, ownerToken, repoFromRemote } from "../adapters/github.ts";
9
+ import { githubLoopReads } from "../loop/github.ts";
10
+ import { gitHubPullRequests } from "../adapters/pull-requests.ts";
11
+ import { serialized } from "../adapters/serial.ts";
12
+ import { SlotPool } from "../slots/pool.ts";
13
+ import { loadConfig, readConfigDir } from "../config/load.ts";
14
+ import type { HumConfig } from "../config/schema.ts";
15
+ import { commandTimeoutMs } from "../exec.ts";
16
+ import { defaultStateDir, openState } from "../state/open.ts";
17
+ import { DEFAULT_BASE } from "./thin-path.ts";
18
+ import { Worker, type WorkerOptions } from "./worker.ts";
19
+
20
+ export type OpenWorkerOptions = Omit<WorkerOptions, "repo" | "state" | "config" | "adapters" | "runner" | "remote" | "pulls" | "loop" | "checks"> & {
21
+ /** Where saved state lives; default `<git common dir>/hum`. */
22
+ readonly stateDir?: string;
23
+ /** The skill names of hope's installed copy; a role that names another is refused. */
24
+ readonly hopeSkills: ReadonlySet<string>;
25
+ readonly remote?: string;
26
+ readonly binary?: string;
27
+ readonly env?: Readonly<Record<string, string>>;
28
+ };
29
+
30
+ const Latest = z.looseObject({ version: z.string().min(1) });
31
+
32
+ const NPM_LATEST = "https://registry.npmjs.org/@moo.md/hum/latest";
33
+
34
+ const NPM_TIMEOUT_MS = 5000;
35
+
36
+ /** The newest `@moo.md/hum` on npm. */
37
+ export const npmLatest = async (): Promise<string | undefined> => {
38
+ const reply = await fetch(NPM_LATEST, { signal: AbortSignal.timeout(NPM_TIMEOUT_MS) });
39
+
40
+ return reply.ok ? Latest.safeParse(await reply.json()).data?.version : undefined;
41
+ };
42
+
43
+ /** Runs are background agents where an owner can see agent view: on the Mac, and only when `hum.json` allows it. */
44
+ const isInBackground = ({ backgroundRuns }: Pick<HumConfig, "backgroundRuns">, where: WorkerOptions["where"]): boolean => backgroundRuns && where !== "ci";
45
+
46
+ /**
47
+ * Wires a worker for the owner's repo: state in the git common dir, the config in `.hum/`, the adapters
48
+ * `hum.json` names (guarded, with the last ready list saved, and one call at a time), a started runner, and for a
49
+ * remote on GitHub its pull requests and branch rules, so landing follows what the target branch requires.
50
+ * Throws when the config is refused or the repo has no `origin`; the service unit shows that as a card.
51
+ */
52
+ export const openWorker = async (repo: string, options: OpenWorkerOptions): Promise<Worker> => {
53
+ const { stateDir, hopeSkills, binary, env, ...rest } = options;
54
+ const now = rest.now ?? Date.now;
55
+ const state = openState(stateDir ?? (await defaultStateDir(repo)), { now });
56
+ const loaded = loadConfig(readConfigDir(join(repo, ".hum")), { env: { hopeSkills } });
57
+
58
+ if (!loaded.ok) throw new Error(loaded.refusal.message);
59
+
60
+ const timeoutMs = commandTimeoutMs(loaded.value.hum);
61
+ const remote = options.remote ?? (await gitIn(repo, { timeoutMs }).raw(["remote", "get-url", "origin"])).trim();
62
+
63
+ if (!remote) throw new Error(`${repo} has no origin remote, and none was given`);
64
+
65
+ const config = loaded.value;
66
+
67
+ if (config.hum.checks.length === 0) throw new Error("hum.json names no checks: set \"checks\" to the commands a change must pass, or run /hum");
68
+
69
+ const adapters = await resolveAdapters(repo, {
70
+ faults: state.faults,
71
+ guard: { lastReady: { load: () => state.ready.get("work-source")?.ids ?? [], save: (ids) => state.ready.put("work-source", { ids }) } },
72
+ context: { report: (fault) => void state.faults.raise(fault), now },
73
+ });
74
+
75
+ // One adapter serves several slots; its calls go one at a time whichever slot they come through.
76
+ const ordered = new Map<Adapter, Adapter>();
77
+
78
+ const inOrder = (adapter: Adapter | undefined): Adapter | undefined => {
79
+ if (adapter && !ordered.has(adapter)) ordered.set(adapter, serialized(adapter));
80
+
81
+ return adapter && ordered.get(adapter);
82
+ };
83
+
84
+ const workSource = inOrder(adapters["work-source"])?.workSource;
85
+ const questions = inOrder(adapters.questions)?.questions;
86
+ const answers = inOrder(adapters.answers)?.answers;
87
+
88
+ if (!workSource || !questions) throw new Error("hum.json names no work source or no questions integration");
89
+
90
+ const runnerOptions = { state, model: config.hum.models.light, binary, env, now };
91
+ const { runner } = isInBackground(config.hum, rest.where) ? await startBackgroundRunner({ ...runnerOptions, config: config.hum, repo }) : await startRunner(runnerOptions);
92
+
93
+ // A slot is a worktree a background run starts in, so the pool stands only where runs are background agents.
94
+ const slots = config.hum.runSlots.enabled && isInBackground(config.hum, rest.where) ? new SlotPool({ repo, state, config: config.hum, base: rest.base ?? DEFAULT_BASE, liveRuns: runner.liveRuns, now }) : undefined;
95
+ const github = repoFromRemote(remote);
96
+ const pulls = github === undefined ? undefined : gitHubPullRequests(github, { timeoutMs });
97
+ const loop = github === undefined ? undefined : githubLoopReads(github, rest.base ?? DEFAULT_BASE, config.hum.measureWindow, async () => gitHubClient({ token: await ownerToken(timeoutMs) }));
98
+
99
+ return new Worker({ ...rest, checks: config.hum.checks, checkout: rest.checkout ?? slots?.checkout, slots, repo, state, config, adapters: { workSource, questions, answers }, runner, remote, pulls, loop });
100
+ };
@@ -0,0 +1,56 @@
1
+ import { type AgentDecisionExecutor, createDecisionRequest, getMessageText, renderDecisionAttempts, resolveDecision } from "@statelyai/agent";
2
+ import { type Finished, succeeded } from "../adapters/claude-p.ts";
3
+ import { type EventPick, type JsonSchema, PROSE_STATES, type ProsePurpose, pickSchema, readPick } from "../decide/prose.ts";
4
+
5
+ const RESULT_EXCERPT = 300;
6
+
7
+ /** One agent run answering in `schema`. It settles only with a finished run; a limit, a hold or a stop never settles it. */
8
+ export type AnswerRun = (prompt: string, schema: JsonSchema) => Promise<Finished>;
9
+
10
+ export type ProseDecision = { readonly pick: EventPick; readonly models: readonly string[] };
11
+
12
+ export type ProseOptions = {
13
+ readonly purpose: ProsePurpose;
14
+ readonly prompt: string;
15
+ /** The diff a pick's citations must point into; empty for a plan. */
16
+ readonly diff: string;
17
+ readonly model: string;
18
+ readonly run: AnswerRun;
19
+ /** Whether the machine takes this event now; every offered event by default. */
20
+ readonly canTake?: (event: string) => boolean;
21
+ };
22
+
23
+ const offer = (events: readonly string[]): string =>
24
+ `Answer with one event: ${events.join(", ")}. Set sure to false when you are not sure; the safer event is then taken. Give your reason in a sentence.`;
25
+
26
+ /**
27
+ * A plan or review run's pick of the next event, through the agent library's decide executor: the run is offered
28
+ * only the events the state takes, and code checks the artifact behind its pick. A pick that fails its check is
29
+ * refused and the run is made again with the reason; once the library's retries are spent the decision throws.
30
+ */
31
+ export const decideProse = async ({ purpose, prompt, diff, model, run, canTake = () => true }: ProseOptions): Promise<ProseDecision> => {
32
+ let taken: ProseDecision | undefined;
33
+
34
+ const decide: AgentDecisionExecutor = async (request) => {
35
+ const offered = request.events.map(({ type }) => type);
36
+ const feedback = renderDecisionAttempts(request).map(getMessageText);
37
+ const outcome = await run([prompt, offer(offered), ...feedback].join("\n\n"), pickSchema(offered));
38
+
39
+ if (!succeeded(outcome)) return { rejected: { failure: "invalid-payload", reason: `the run ended as ${outcome.subtype}: ${outcome.text.slice(0, RESULT_EXCERPT)}` } };
40
+
41
+ const read = readPick(purpose, outcome, diff);
42
+
43
+ if (!read.ok) return { rejected: { failure: "invalid-payload", reason: read.why } };
44
+
45
+ taken = { pick: read.pick, models: outcome.models };
46
+
47
+ return { event: { type: read.pick.event } };
48
+ };
49
+
50
+ const request = createDecisionRequest({ name: purpose, model, events: [...PROSE_STATES[purpose].events] });
51
+ const event = await resolveDecision(request, { decide }, { canTake: ({ type }) => canTake(type) });
52
+
53
+ if (taken?.pick.event !== event.type) throw new Error(`the ${purpose} decision took ${event.type}, which no run picked`);
54
+
55
+ return taken;
56
+ };
@@ -0,0 +1,89 @@
1
+ import { ADAPTER_API_VERSION, type Item, type Question, type Questions, type ThreadEntry, type WorkSource } from "../adapter-api.ts";
2
+ import { visibleText } from "../adapters/marked.ts";
3
+ import { onceCalls } from "../adapters/once.ts";
4
+ import type { Config } from "../config/load.ts";
5
+ import { composeQuestion, type PlainQuestion, priorityOf, questionOrder, roomToAsk, type Waiting } from "../decide/question.ts";
6
+ import type { State } from "../state/open.ts";
7
+ import type { QueuedQuestion } from "../state/saved.ts";
8
+ import { DAY_MS, HOUR_MS } from "../time.ts";
9
+ import { footprintOf, overlaps } from "./scheduler.ts";
10
+
11
+ export type QuestionContext = {
12
+ readonly state: State;
13
+ readonly config: Config;
14
+ readonly workSource: WorkSource;
15
+ readonly questions: Questions;
16
+ readonly now: () => number;
17
+ };
18
+
19
+ const isOpenQuestion = (thread: readonly ThreadEntry[], text: string): boolean => {
20
+ const last = thread.findLastIndex((entry) => entry.kind === "question" && entry.author !== "person");
21
+ const reply = thread.findIndex((entry, index) => index > last && (entry.kind === "answer" || (entry.kind === "comment" && entry.author === "person")));
22
+
23
+ return last >= 0 && reply < 0 && visibleText(thread[last]?.text ?? "") === text;
24
+ };
25
+
26
+ const keyOf = ({ item, queuedAt }: Pick<QueuedQuestion, "item" | "queuedAt">): string => `${item}@${queuedAt}`;
27
+
28
+ /** How long an asked question is kept: long enough to count the day, and to read late answers to it. */
29
+ const keptFor = ({ hum }: Config): number => Math.max(DAY_MS, hum.questionTimeoutHours * HOUR_MS);
30
+
31
+ const isWaiting = ({ askedAt }: QueuedQuestion): boolean => askedAt === undefined;
32
+
33
+ /** A question to the owner, checked against the question rules and queued for room under the daily cap. One already open, or already queued, is not asked twice. */
34
+ export const queueQuestion = (ctx: QuestionContext, item: Item, draft: Question, plain: PlainQuestion): void => {
35
+ const { state, config, now } = ctx;
36
+ const question = composeQuestion(draft, plain, item.id, config.hum.questionLimits);
37
+ const known = state.questions.list().some((queued) => queued.item === item.id && isWaiting(queued) && queued.text === question.text);
38
+
39
+ if (known || isOpenQuestion(item.thread, question.text)) return;
40
+
41
+ const queued: QueuedQuestion = {
42
+ item: item.id,
43
+ text: question.text,
44
+ options: question.options && [...question.options],
45
+ detail: question.detail,
46
+ priority: priorityOf(item.labels ?? [], config.hum.priorityLabels),
47
+ footprint: footprintOf(item) && [...(footprintOf(item) ?? [])],
48
+ queuedAt: now(),
49
+ };
50
+
51
+ state.questions.put(keyOf(queued), queued);
52
+ };
53
+
54
+ const waitingOrder = (queue: readonly QueuedQuestion[]): QueuedQuestion[] => {
55
+ const ranked = queue.map((queued): Waiting & { queued: QueuedQuestion } => ({
56
+ item: queued.item,
57
+ priority: queued.priority,
58
+ behind: queue.filter((other) => other !== queued && overlaps(queued.footprint, other.footprint)).length,
59
+ since: queued.queuedAt,
60
+ queued,
61
+ }));
62
+
63
+ return ranked.sort(questionOrder).map(({ queued }) => queued);
64
+ };
65
+
66
+ /** Asks the queued questions the daily cap has room for, first by the owner's priority label, then by how many items wait on it, then by age. */
67
+ export const releaseQuestions = async (ctx: QuestionContext): Promise<string[]> => {
68
+ const { state, config, workSource, questions, now } = ctx;
69
+ const all = state.questions.list();
70
+
71
+ for (const old of all) if (old.askedAt !== undefined && now() - old.askedAt > keptFor(config)) state.questions.remove(keyOf(old));
72
+
73
+ const room = roomToAsk(all.flatMap(({ askedAt }) => (askedAt === undefined ? [] : [askedAt])), config.hum.dailyQuestionCap, now());
74
+ const released: string[] = [];
75
+
76
+ for (const queued of waitingOrder(all.filter(isWaiting)).slice(0, room)) {
77
+ const calls = onceCalls({ apiVersion: ADAPTER_API_VERSION, workSource, questions }, state.ops, { run: "ask", attempt: queued.queuedAt });
78
+
79
+ await calls.questions?.ask(queued.item, { text: queued.text, options: queued.options, detail: queued.detail });
80
+ state.questions.put(keyOf(queued), { ...queued, askedAt: now() });
81
+ released.push(queued.item);
82
+ }
83
+
84
+ return released;
85
+ };
86
+
87
+ /** Items whose question was asked recently enough that an answer may still come for it. */
88
+ export const recentlyAsked = ({ state, config, now }: Pick<QuestionContext, "state" | "config" | "now">): string[] =>
89
+ state.questions.list().flatMap(({ item, askedAt }) => (askedAt !== undefined && now() - askedAt <= keptFor(config) ? [item] : []));
@@ -0,0 +1,135 @@
1
+ import type { Item } from "../adapter-api.ts";
2
+
3
+ /** The paths an item will touch, as files or folders (a glob counts as its folder). `undefined` when the item does not say. */
4
+ export type Footprint = readonly string[] | undefined;
5
+
6
+ const TOUCHES = /^touches:[ \t]*(.+)$/im;
7
+
8
+ /** The item's declared footprint: a body line `touches: docs/a.md, src/`. An item that declares none is unknown, so it runs alone. */
9
+ export const footprintOf = (item: Pick<Item, "body">): Footprint => {
10
+ const line = TOUCHES.exec(item.body)?.[1];
11
+ const paths = line?.split(/[,\s]+/).filter(Boolean);
12
+
13
+ return paths && paths.length > 0 ? paths : undefined;
14
+ };
15
+
16
+ /** The folder a path or glob stands for: cut at the first glob character, then back to a whole segment. "" is the repo root. */
17
+ const folderOf = (entry: string): string => {
18
+ const path = entry.replace(/^\.\//, "").replace(/\/+$/, "");
19
+ const glob = path.search(/[*?[{]/);
20
+
21
+ return glob < 0 ? path : path.slice(0, Math.max(0, path.lastIndexOf("/", glob)));
22
+ };
23
+
24
+ const isRoot = (folder: string): boolean => folder === "";
25
+
26
+ const isWithin = (inner: string, outer: string): boolean => inner === outer || inner.startsWith(`${outer}/`);
27
+
28
+ /** Two folders are related when either holds the other; the repo root holds every folder. */
29
+ const related = (a: string, b: string): boolean => isRoot(a) || isRoot(b) || isWithin(a, b) || isWithin(b, a);
30
+
31
+ /** Safe by default: two items clash when either footprint is unknown or any path of one lies in the other's. */
32
+ export const overlaps = (a: Footprint, b: Footprint): boolean => a === undefined || b === undefined || a.some((x) => b.some((y) => related(folderOf(x), folderOf(y))));
33
+
34
+ export type Candidate = {
35
+ readonly id: string;
36
+ readonly footprint: Footprint;
37
+ /** The owner answered it: it goes ahead of fresh items. */
38
+ readonly answered: boolean;
39
+ };
40
+
41
+ export type PickInput = {
42
+ readonly now: number;
43
+ /** Until then no run starts. */
44
+ readonly limitedUntil: number;
45
+ /** The most runs that go at once. */
46
+ readonly runners: number;
47
+ readonly running: readonly { readonly id: string; readonly footprint: Footprint }[];
48
+ /** Waiting items, oldest first. */
49
+ readonly queue: readonly Candidate[];
50
+ };
51
+
52
+ export type Picked = { readonly start: readonly Candidate[]; readonly deferred: readonly Candidate[] };
53
+
54
+ /**
55
+ * Which waiting items start now. Items on different files run side by side; an item that clashes with a
56
+ * running item, or with an item ahead of it in the queue, waits, so items on one file go in order.
57
+ * Answered items go first. Never more than `runners` runs at once, and none while limited.
58
+ */
59
+ export const pick = ({ now, limitedUntil, runners, running, queue }: PickInput): Picked => {
60
+ if (now < limitedUntil) return { start: [], deferred: queue };
61
+
62
+ const ordered = [...queue.filter((c) => c.answered), ...queue.filter((c) => !c.answered)];
63
+
64
+ return ordered.reduce<Picked>(
65
+ (picked, candidate, index) => {
66
+ const ahead = [...running, ...ordered.slice(0, index)];
67
+ const clashes = ahead.some((other) => overlaps(other.footprint, candidate.footprint));
68
+ const isFull = running.length + picked.start.length >= runners;
69
+
70
+ return clashes || isFull ? { ...picked, deferred: [...picked.deferred, candidate] } : { ...picked, start: [...picked.start, candidate] };
71
+ },
72
+ { start: [], deferred: [] },
73
+ );
74
+ };
75
+
76
+ /** The prompt cache keeps a written prefix this long: the API's default cache lifetime. */
77
+ const CACHE_TTL_MS = 5 * 60_000;
78
+
79
+ /** What the run that entered a prefix must do: `opened` at its first token, `release` when it ends. Both do nothing for a run that did not open the prefix. */
80
+ export type Lease = { readonly opened: () => void; readonly release: () => void };
81
+
82
+ const NO_LEASE: Lease = { opened: () => {}, release: () => {} };
83
+
84
+ /**
85
+ * Runs that share a prompt prefix start one at a time. The first goes at once; the others wait until its
86
+ * first token has arrived, so the cache is written once and every later run reads it. A prefix written
87
+ * within the cache TTL is warm, and its runs start freely.
88
+ */
89
+ export class PrefixGate {
90
+ readonly #now: () => number;
91
+ readonly #ttl: number;
92
+ readonly #open = new Map<string, { readonly promise: Promise<void>; readonly resolve: () => void }>();
93
+ readonly #warm = new Map<string, number>();
94
+
95
+ constructor({ now = Date.now, ttlMs = CACHE_TTL_MS }: { now?: () => number; ttlMs?: number } = {}) {
96
+ this.#now = now;
97
+ this.#ttl = ttlMs;
98
+ }
99
+
100
+ /** Returns when this run may start its model call. */
101
+ async enter(prefix: string, abort?: AbortSignal): Promise<Lease> {
102
+ for (;;) {
103
+ const waiting = this.#open.get(prefix);
104
+
105
+ if (waiting) {
106
+ await new Promise<void>((resolve, reject) => {
107
+ abort?.addEventListener("abort", () => reject(new Error("stopped while waiting for the prefix's first token")), { once: true });
108
+ void waiting.promise.then(resolve);
109
+ });
110
+
111
+ continue;
112
+ }
113
+
114
+ if ((this.#warm.get(prefix) ?? 0) > this.#now()) return NO_LEASE;
115
+
116
+ const mine = Promise.withResolvers<void>();
117
+
118
+ const free = () => {
119
+ mine.resolve();
120
+
121
+ if (this.#open.get(prefix) === mine) this.#open.delete(prefix);
122
+ };
123
+
124
+ this.#open.set(prefix, mine);
125
+
126
+ return {
127
+ opened: () => {
128
+ this.#warm.set(prefix, this.#now() + this.#ttl);
129
+ free();
130
+ },
131
+ release: free,
132
+ };
133
+ }
134
+ }
135
+ }
@@ -0,0 +1,41 @@
1
+ import { createHash } from "node:crypto";
2
+ import { existsSync, readFileSync } from "node:fs";
3
+ import { join, relative } from "node:path";
4
+ import { z } from "zod";
5
+ import { isMissing } from "../state/fs.ts";
6
+
7
+ const Package = z.looseObject({ version: z.string().min(1) });
8
+
9
+ /** What the worker compares each tick with the one at its start. A change in either makes it drain and exit. */
10
+ export type Signature = { readonly engineVersion: string; readonly hash: string };
11
+
12
+ const LOCKFILES = ["bun.lock", "bun.lockb", "package-lock.json", "pnpm-lock.yaml", "yarn.lock"];
13
+
14
+ const isInside = (path: string, folder: string): boolean => path === folder || path.startsWith(`${folder}/`);
15
+
16
+ /** Every file under `folder` of `root`, hidden ones too, as paths from `root` in a stable order, without the items folder: every claim, answer and merge changes it, and it is no config. */
17
+ const filesUnder = (root: string, folder: string, itemsDir: string): string[] =>
18
+ existsSync(join(root, folder))
19
+ ? [...new Bun.Glob("**").scanSync({ cwd: join(root, folder), dot: true, onlyFiles: true })].flatMap((path) => (isInside(join(folder, path), itemsDir) ? [] : [join(folder, path)])).sort()
20
+ : [];
21
+
22
+ /** The engine version installed in the owner's repo, else `fallback` (the running one). */
23
+ export const installedVersion = (repo: string, fallback: string): string => {
24
+ try {
25
+ return Package.safeParse(JSON.parse(readFileSync(join(repo, "node_modules", "@moo.md", "hum", "package.json"), "utf8"))).data?.version ?? fallback;
26
+ } catch (error) {
27
+ if (error instanceof Error && isMissing(error)) return fallback;
28
+
29
+ throw error;
30
+ }
31
+ };
32
+
33
+ /** The installed engine version and one hash of the lockfile, `.hum/` (without its items) and `adapters/`. */
34
+ export const signatureOf = (repo: string, fallbackVersion: string, itemsDir: string): Signature => {
35
+ const hash = createHash("sha256");
36
+ const files = [...LOCKFILES.filter((name) => existsSync(join(repo, name))), ...filesUnder(repo, ".hum", itemsDir), ...filesUnder(repo, "adapters", itemsDir)];
37
+
38
+ for (const file of files) hash.update(relative(repo, join(repo, file))).update("\0").update(readFileSync(join(repo, file))).update("\0");
39
+
40
+ return { engineVersion: installedVersion(repo, fallbackVersion), hash: hash.digest("hex") };
41
+ };
@@ -0,0 +1,25 @@
1
+ import type { State } from "../state/open.ts";
2
+ import type { Spent } from "../state/saved.ts";
3
+
4
+ /** An item's token count, read and written through the saved record on every call, so every run of the item adds to the one total. */
5
+ export const tallyOf = (state: State, item: string) => {
6
+ const read = (): Spent => state.spent.get(item) ?? { item, total: 0, base: 0 };
7
+
8
+ return {
9
+ /** Tokens spent since the owner last answered, which is what the kind's cap counts. */
10
+ sinceAnswer: (): number => read().total - read().base,
11
+ spend: (tokens: number): void => {
12
+ const now = read();
13
+
14
+ state.spent.put(item, { ...now, total: now.total + tokens });
15
+ },
16
+ /** The owner answered: the cap counts from here. */
17
+ startAfresh: (): void => {
18
+ const now = read();
19
+
20
+ state.spent.put(item, { ...now, base: now.total });
21
+ },
22
+ };
23
+ };
24
+
25
+ export type Tally = ReturnType<typeof tallyOf>;
@@ -0,0 +1,38 @@
1
+ import { PATCH } from "../adapters/git.ts";
2
+ import type { Pull, PullRequests } from "../adapters/pull-requests.ts";
3
+ import { isTrusted } from "../decide/prose.ts";
4
+ import { type TasteResult, tasteComment, tasteQuestion } from "../decide/taste.ts";
5
+ import type { LandContext } from "./land.ts";
6
+
7
+ /**
8
+ * Comments on the pull request whether its diff keeps each of the owner's taste rules, once per head. The comment
9
+ * reports only: no result reaches the placement, the route or the merge.
10
+ */
11
+ export const reportTaste = async (ctx: LandContext, pulls: PullRequests, pull: Pull, head: string): Promise<void> => {
12
+ const { rules, ...bar } = { rules: ctx.config.hum.tasteRules, measuredModels: ctx.config.hum.measuredModels, minJudgeRate: ctx.config.hum.minJudgeRate };
13
+
14
+ if (rules.length === 0) return;
15
+
16
+ await ctx.state.ops.once(
17
+ { itemId: ctx.id, run: "merge", attempt: 0, op: `taste:${head}` },
18
+ {
19
+ holds: async () => false,
20
+ run: async () => {
21
+ const diff = await ctx.git.raw(["diff", ...PATCH, `origin/${ctx.base}...${head}`]);
22
+ const models = new Set<string>();
23
+
24
+ const results: TasteResult[] = [];
25
+
26
+ for (const rule of rules) {
27
+ const judged = await ctx.judge({ ...tasteQuestion(rule, diff, ctx.config.hum), item: ctx.id });
28
+
29
+ if (judged.kind === "picked") judged.models.forEach((model) => models.add(model));
30
+
31
+ results.push({ rule, answer: judged.kind === "picked" ? judged.value : { abstained: judged.why } });
32
+ }
33
+
34
+ await pulls.comment(pull, tasteComment(results, isTrusted([...models], "taste", bar)));
35
+ },
36
+ },
37
+ );
38
+ };