@moo.md/hum 0.0.0-stage → 0.1.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.
- package/defaults/hum.json +321 -0
- package/defaults/kinds/check.json +183 -0
- package/defaults/kinds/docs.json +151 -0
- package/defaults/kinds/feature.json +202 -0
- package/defaults/kinds/fix.json +183 -0
- package/defaults/kinds/hotfix.json +164 -0
- package/defaults/roles/build.md +3 -0
- package/defaults/roles/fix.md +1 -0
- package/defaults/roles/plan.md +3 -0
- package/defaults/roles/review.md +3 -0
- package/evals/alignment/RESULTS.md +8 -0
- package/evals/alignment/cases.jsonl +128 -0
- package/evals/alignment/sample.jsonl +20 -0
- package/evals/kind/RESULTS.md +5 -0
- package/evals/kind/cases.jsonl +24 -0
- package/evals/plan-outcome/RESULTS.md +4 -0
- package/evals/plan-outcome/cases.jsonl +12 -0
- package/evals/repeat-pair/RESULTS.md +4 -0
- package/evals/repeat-pair/cases.jsonl +51 -0
- package/evals/reply-option/RESULTS.md +3 -0
- package/evals/reply-option/cases.jsonl +45 -0
- package/evals/review-verdict/RESULTS.md +4 -0
- package/evals/review-verdict/cases.jsonl +12 -0
- package/package.json +88 -4
- package/schema/hum.schema.json +1355 -0
- package/scripts/eval.ts +244 -0
- package/src/adapter-api.ts +134 -0
- package/src/adapters/admit.ts +111 -0
- package/src/adapters/argument.ts +11 -0
- package/src/adapters/claim.ts +93 -0
- package/src/adapters/claude-bg.ts +392 -0
- package/src/adapters/claude-p.ts +599 -0
- package/src/adapters/contract.ts +231 -0
- package/src/adapters/fake.ts +157 -0
- package/src/adapters/git.ts +156 -0
- package/src/adapters/github.ts +479 -0
- package/src/adapters/guard.ts +152 -0
- package/src/adapters/history.ts +215 -0
- package/src/adapters/item-file.ts +102 -0
- package/src/adapters/limit.ts +67 -0
- package/src/adapters/markdown.ts +365 -0
- package/src/adapters/marked.ts +127 -0
- package/src/adapters/model-call.ts +75 -0
- package/src/adapters/once.ts +45 -0
- package/src/adapters/owner-commit.ts +60 -0
- package/src/adapters/pull-requests.ts +253 -0
- package/src/adapters/registry.ts +156 -0
- package/src/adapters/roundup.ts +293 -0
- package/src/adapters/serial.ts +22 -0
- package/src/adapters/transcript.ts +99 -0
- package/src/cli/commands.ts +46 -0
- package/src/cli/main.ts +8 -0
- package/src/cli/ops.ts +224 -0
- package/src/cli/service.ts +156 -0
- package/src/cli/setup.ts +141 -0
- package/src/cli/shared-watch.ts +127 -0
- package/src/config/change.ts +54 -0
- package/src/config/checks.ts +217 -0
- package/src/config/git-ref-name.d.ts +3 -0
- package/src/config/hash.ts +6 -0
- package/src/config/json.ts +6 -0
- package/src/config/load.ts +88 -0
- package/src/config/machine.ts +20 -0
- package/src/config/migrate.ts +61 -0
- package/src/config/refusal.ts +58 -0
- package/src/config/schema.ts +465 -0
- package/src/config/settings.ts +6 -0
- package/src/config/state-map.ts +76 -0
- package/src/decide/alignment.ts +79 -0
- package/src/decide/answer.ts +131 -0
- package/src/decide/kind.ts +39 -0
- package/src/decide/labels.ts +137 -0
- package/src/decide/merge.ts +102 -0
- package/src/decide/prose.ts +109 -0
- package/src/decide/question.ts +159 -0
- package/src/decide/review.ts +10 -0
- package/src/decide/risk.ts +216 -0
- package/src/decide/taste.ts +37 -0
- package/src/exec.ts +85 -0
- package/src/index.ts +200 -0
- package/src/loop/breaks.ts +8 -0
- package/src/loop/check-item.ts +76 -0
- package/src/loop/ci.ts +8 -0
- package/src/loop/github.ts +81 -0
- package/src/loop/groups.ts +108 -0
- package/src/loop/memory.ts +70 -0
- package/src/loop/notes.ts +76 -0
- package/src/loop/pair.ts +39 -0
- package/src/loop/pass.ts +99 -0
- package/src/loop/proof.ts +85 -0
- package/src/loop/prove-item.ts +33 -0
- package/src/loop/records.ts +75 -0
- package/src/loop/signals.ts +130 -0
- package/src/measure/inputs.ts +28 -0
- package/src/measure/measure.ts +68 -0
- package/src/service/cards.ts +24 -0
- package/src/service/ci-tick.ts +28 -0
- package/src/service/launchd.ts +16 -0
- package/src/service/supervise.ts +145 -0
- package/src/service/systemd.ts +44 -0
- package/src/service/token.ts +21 -0
- package/src/service/unit.ts +29 -0
- package/src/service/wake.ts +30 -0
- package/src/service/workflows.ts +97 -0
- package/src/setup/propose.ts +120 -0
- package/src/setup/prove.ts +216 -0
- package/src/setup/scan.ts +186 -0
- package/src/setup/scratch.ts +81 -0
- package/src/setup/shipped.ts +15 -0
- package/src/setup/tables.ts +101 -0
- package/src/setup/waits.ts +58 -0
- package/src/setup/write.ts +161 -0
- package/src/slots/env.ts +42 -0
- package/src/slots/pool.ts +329 -0
- package/src/slots/scan.ts +26 -0
- package/src/slots/worktree.ts +17 -0
- package/src/state/events.ts +52 -0
- package/src/state/faults.ts +73 -0
- package/src/state/format.ts +50 -0
- package/src/state/fs.ts +100 -0
- package/src/state/items.ts +195 -0
- package/src/state/open.ts +80 -0
- package/src/state/ops.ts +76 -0
- package/src/state/records.ts +35 -0
- package/src/state/runs.ts +99 -0
- package/src/state/saved.ts +119 -0
- package/src/status/file.ts +49 -0
- package/src/status/format.ts +132 -0
- package/src/status/sections.ts +14 -0
- package/src/status/version.ts +2 -0
- package/src/time.ts +7 -0
- package/src/worker/alignment-report.ts +18 -0
- package/src/worker/answers.ts +153 -0
- package/src/worker/base-check.ts +45 -0
- package/src/worker/checks.ts +40 -0
- package/src/worker/kind.ts +68 -0
- package/src/worker/land.ts +509 -0
- package/src/worker/lifecycle.ts +97 -0
- package/src/worker/merged.ts +29 -0
- package/src/worker/open.ts +100 -0
- package/src/worker/prose-run.ts +56 -0
- package/src/worker/questions.ts +89 -0
- package/src/worker/scheduler.ts +135 -0
- package/src/worker/signature.ts +41 -0
- package/src/worker/tally.ts +25 -0
- package/src/worker/taste.ts +38 -0
- package/src/worker/thin-path.ts +886 -0
- package/src/worker/worker.ts +750 -0
- package/surface.json +8787 -0
- package/README.md +0 -3
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
2
|
+
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
import { type Adapter, type AdapterContext, type Answers, type Item, ItemId, PermanentError, type Questions, type Watch, type WorkSource } from "../adapter-api.ts";
|
|
5
|
+
import { hashJson } from "../config/hash.ts";
|
|
6
|
+
import { Json } from "../config/json.ts";
|
|
7
|
+
import { parseArgument } from "./argument.ts";
|
|
8
|
+
import { claimer, isLive } from "./claim.ts";
|
|
9
|
+
import {
|
|
10
|
+
answerMarker,
|
|
11
|
+
commentText,
|
|
12
|
+
filedFollowUp,
|
|
13
|
+
followUpBody,
|
|
14
|
+
followUpNote,
|
|
15
|
+
isFollowUpOf,
|
|
16
|
+
type Marker,
|
|
17
|
+
cutLine,
|
|
18
|
+
markedLine,
|
|
19
|
+
markerLine,
|
|
20
|
+
parseComment,
|
|
21
|
+
parseLooseJson,
|
|
22
|
+
questionMarker,
|
|
23
|
+
questionText,
|
|
24
|
+
splitMarker,
|
|
25
|
+
} from "./marked.ts";
|
|
26
|
+
|
|
27
|
+
const CLAIM_OPEN = "<!-- hum-claim ";
|
|
28
|
+
|
|
29
|
+
/** An Agent's comment on a Todo is one line of at most this many characters. */
|
|
30
|
+
const COMMENT_LIMIT = 280;
|
|
31
|
+
|
|
32
|
+
/** The digest in a Pad's name, so the same text posts to the same Pad name. */
|
|
33
|
+
const PAD_DIGEST_LENGTH = 8;
|
|
34
|
+
|
|
35
|
+
const TodoId = ItemId.pipe(z.string().regex(/^(0|[1-9]\d*)$/, "a roundup Todo id is a whole number")).transform(Number);
|
|
36
|
+
|
|
37
|
+
const Actor = z.looseObject({ kind: z.string(), id: z.string() });
|
|
38
|
+
|
|
39
|
+
const Todo = z.looseObject({
|
|
40
|
+
id: z.int().nonnegative(),
|
|
41
|
+
title: z.string(),
|
|
42
|
+
body: z.string(),
|
|
43
|
+
done: z.boolean(),
|
|
44
|
+
blocked: z.boolean(),
|
|
45
|
+
updated_at: z.number().optional(),
|
|
46
|
+
owner: Actor.nullable().optional(),
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
type Todo = z.infer<typeof Todo>;
|
|
50
|
+
|
|
51
|
+
const Todos = z.union([z.array(Todo), z.looseObject({ todos: z.array(Todo) }).transform((found) => found.todos)]);
|
|
52
|
+
|
|
53
|
+
const Comment = z.looseObject({ id: z.int().nonnegative(), body: z.string(), created_at: z.number() });
|
|
54
|
+
|
|
55
|
+
type Comment = z.infer<typeof Comment>;
|
|
56
|
+
|
|
57
|
+
const Reply = z.looseObject({
|
|
58
|
+
content: z.array(z.looseObject({ type: z.string(), text: z.string().optional() })).optional(),
|
|
59
|
+
isError: z.boolean().optional(),
|
|
60
|
+
structuredContent: Json.optional(),
|
|
61
|
+
});
|
|
62
|
+
|
|
63
|
+
/** One take or renewal of an item's claim, written as a comment. */
|
|
64
|
+
const ClaimEntry = z.strictObject({ holder: z.string().min(1), at: z.int().nonnegative(), expiresAt: z.int().nonnegative() });
|
|
65
|
+
|
|
66
|
+
type ClaimEntry = z.infer<typeof ClaimEntry>;
|
|
67
|
+
|
|
68
|
+
/** Calls one tool of roundup's MCP server and returns its parsed JSON. A tool that reports an error throws a `PermanentError`. */
|
|
69
|
+
export type ToolCall = (tool: string, args: Record<string, Json>) => Promise<Json>;
|
|
70
|
+
|
|
71
|
+
export type RoundupOptions = {
|
|
72
|
+
/** Replaces the stdio client, for a stub. */
|
|
73
|
+
readonly call?: ToolCall;
|
|
74
|
+
/** The Agent id `rup mcp` acts as. Defaults to `ROUNDUP_AGENT_ID`. */
|
|
75
|
+
readonly agent?: string;
|
|
76
|
+
/** The Project's daemon socket. Defaults to `RUPD_SOCKET`. */
|
|
77
|
+
readonly socket?: string;
|
|
78
|
+
};
|
|
79
|
+
|
|
80
|
+
const environment = (): Record<string, string> => Object.fromEntries(Object.entries(process.env).flatMap(([key, value]) => (value === undefined ? [] : [[key, value]])));
|
|
81
|
+
|
|
82
|
+
/** A tool's reply: its structured content, else its text as JSON, else the text itself. */
|
|
83
|
+
const replyValue = (tool: string, result: Awaited<ReturnType<Client["callTool"]>>): Json => {
|
|
84
|
+
const reply = Reply.parse(result);
|
|
85
|
+
const text = reply.content?.find((part) => part.type === "text")?.text ?? "";
|
|
86
|
+
|
|
87
|
+
if (reply.isError) throw new PermanentError(`${tool}: ${text.slice(0, 300)}`);
|
|
88
|
+
|
|
89
|
+
if (reply.structuredContent !== undefined) return reply.structuredContent;
|
|
90
|
+
|
|
91
|
+
const json = parseLooseJson(Json, text);
|
|
92
|
+
|
|
93
|
+
return json === undefined ? text : json;
|
|
94
|
+
};
|
|
95
|
+
|
|
96
|
+
/** The stdio client: `rup mcp <agent>` on the Project's socket. Only a run roundup started has both. */
|
|
97
|
+
export const stdioCall = ({ agent, socket }: RoundupOptions) => {
|
|
98
|
+
const who = agent ?? process.env.ROUNDUP_AGENT_ID;
|
|
99
|
+
const path = socket ?? process.env.RUPD_SOCKET;
|
|
100
|
+
let client: Promise<Client> | undefined;
|
|
101
|
+
|
|
102
|
+
if (!who || !path) throw new PermanentError("the roundup adapter runs only in a run roundup started: ROUNDUP_AGENT_ID and RUPD_SOCKET are not both set");
|
|
103
|
+
|
|
104
|
+
const connect = async () => {
|
|
105
|
+
const made = new Client({ name: "hum", version: "0" });
|
|
106
|
+
|
|
107
|
+
await made.connect(new StdioClientTransport({ command: "rup", args: ["mcp", who], env: { ...environment(), RUPD_SOCKET: path } }));
|
|
108
|
+
|
|
109
|
+
return made;
|
|
110
|
+
};
|
|
111
|
+
|
|
112
|
+
const call: ToolCall = async (tool, args) => {
|
|
113
|
+
const result = await (client ??= connect())
|
|
114
|
+
.then((live) => live.callTool({ name: tool, arguments: args }))
|
|
115
|
+
.catch((cause: unknown) => {
|
|
116
|
+
client = undefined;
|
|
117
|
+
|
|
118
|
+
throw cause;
|
|
119
|
+
});
|
|
120
|
+
|
|
121
|
+
return replyValue(tool, result);
|
|
122
|
+
};
|
|
123
|
+
|
|
124
|
+
return {
|
|
125
|
+
call,
|
|
126
|
+
close: async () => {
|
|
127
|
+
const used = client;
|
|
128
|
+
|
|
129
|
+
client = undefined;
|
|
130
|
+
await (await used)?.close();
|
|
131
|
+
},
|
|
132
|
+
};
|
|
133
|
+
};
|
|
134
|
+
|
|
135
|
+
const claimEntryOf = (body: string): ClaimEntry | undefined => {
|
|
136
|
+
const split = splitMarker(body, CLAIM_OPEN);
|
|
137
|
+
|
|
138
|
+
return split && parseLooseJson(ClaimEntry, split.json);
|
|
139
|
+
};
|
|
140
|
+
|
|
141
|
+
/** A later entry takes over when no claim stands, the standing one ended before it was made, or its holder renews. */
|
|
142
|
+
const takesOver = (current: ClaimEntry | undefined, entry: ClaimEntry): boolean => !current || current.expiresAt <= entry.at || current.holder === entry.holder;
|
|
143
|
+
|
|
144
|
+
/** The claim that stands after the comments' order. The daemon orders comments, so every worker folds the same list to the same winner. */
|
|
145
|
+
const standingEntry = (comments: readonly Comment[]): ClaimEntry | undefined =>
|
|
146
|
+
comments.reduce<ClaimEntry | undefined>((current, comment) => {
|
|
147
|
+
const entry = claimEntryOf(comment.body);
|
|
148
|
+
|
|
149
|
+
return entry && takesOver(current, entry) ? entry : current;
|
|
150
|
+
}, undefined);
|
|
151
|
+
|
|
152
|
+
/** Open, unblocked and unassigned: a Todo nobody else has taken. */
|
|
153
|
+
const isOpenToTake = (todo: Todo): boolean => !todo.done && !todo.blocked && !todo.owner;
|
|
154
|
+
|
|
155
|
+
const fitsOneComment = (text: string): boolean => !text.includes("\n") && text.length <= COMMENT_LIMIT;
|
|
156
|
+
|
|
157
|
+
type Whole = Adapter & {
|
|
158
|
+
readonly workSource: WorkSource;
|
|
159
|
+
readonly questions: Questions;
|
|
160
|
+
readonly answers: Answers;
|
|
161
|
+
/** Always 0: roundup's socket is local and has no rate limit. */
|
|
162
|
+
readonly spent: () => number;
|
|
163
|
+
readonly close: () => Promise<void>;
|
|
164
|
+
};
|
|
165
|
+
|
|
166
|
+
/**
|
|
167
|
+
* roundup as a work source, through its MCP server over stdio: Todos are items and their comments are the thread.
|
|
168
|
+
* A Todo is ready while it is open, unblocked, unassigned and holds no live claim. A claim is a comment, so the
|
|
169
|
+
* daemon's comment order picks the winner. roundup has no release step.
|
|
170
|
+
*/
|
|
171
|
+
export const roundupAdapter = (options: RoundupOptions, { now }: AdapterContext): Whole => {
|
|
172
|
+
const client = options.call ? { call: options.call, close: async () => {} } : stdioCall(options);
|
|
173
|
+
const { call } = client;
|
|
174
|
+
|
|
175
|
+
const comments = async (id: string) => Comment.array().parse(await call("todo_comments", { id: parseArgument(TodoId, id) }));
|
|
176
|
+
|
|
177
|
+
const todo = async (id: string) => Todo.parse(await call("todo_get", { id: parseArgument(TodoId, id) }));
|
|
178
|
+
|
|
179
|
+
const todos = async () => Todos.parse(await call("todo_list", {}));
|
|
180
|
+
|
|
181
|
+
const post = async (id: string, text: string): Promise<void> => {
|
|
182
|
+
if (!fitsOneComment(text)) throw new PermanentError(`a roundup comment is one line of at most ${COMMENT_LIMIT} characters`);
|
|
183
|
+
|
|
184
|
+
await call("todo_comment", { id: parseArgument(TodoId, id), body: text });
|
|
185
|
+
};
|
|
186
|
+
|
|
187
|
+
/** A text too long for one comment goes whole into a Pad; the comment holds its first words and the Pad's name. */
|
|
188
|
+
const postInPad = async (id: string, marker: Marker | undefined, text: string): Promise<void> => {
|
|
189
|
+
const name = `hum ${id} ${hashJson(text).slice(0, PAD_DIGEST_LENGTH)}`;
|
|
190
|
+
|
|
191
|
+
await call("pad_create", { name, text });
|
|
192
|
+
await post(id, cutLine(marker, text, ` … full text in Pad "${name}"`, COMMENT_LIMIT));
|
|
193
|
+
};
|
|
194
|
+
|
|
195
|
+
const fitsMarked = (marker: Marker, text: string): boolean => {
|
|
196
|
+
try {
|
|
197
|
+
markedLine(marker, text, COMMENT_LIMIT);
|
|
198
|
+
|
|
199
|
+
return true;
|
|
200
|
+
} catch (cause) {
|
|
201
|
+
if (cause instanceof PermanentError) return false;
|
|
202
|
+
|
|
203
|
+
throw cause;
|
|
204
|
+
}
|
|
205
|
+
};
|
|
206
|
+
|
|
207
|
+
const postMarked = async (id: string, marker: Marker, text: string): Promise<void> =>
|
|
208
|
+
fitsMarked(marker, text) ? post(id, markedLine(marker, text, COMMENT_LIMIT)) : postInPad(id, marker, text);
|
|
209
|
+
|
|
210
|
+
const postPlain = async (id: string, text: string): Promise<void> => (fitsOneComment(text) ? post(id, text) : postInPad(id, undefined, text));
|
|
211
|
+
|
|
212
|
+
const standingClaim = (id: string, list: readonly Comment[]) => {
|
|
213
|
+
const entry = standingEntry(list);
|
|
214
|
+
|
|
215
|
+
return entry && { claim: { item: id, holder: entry.holder, expiresAt: entry.expiresAt } };
|
|
216
|
+
};
|
|
217
|
+
|
|
218
|
+
const isFree = (id: string, list: readonly Comment[]): boolean => !isLive(standingClaim(id, list)?.claim, now());
|
|
219
|
+
|
|
220
|
+
const take = claimer(
|
|
221
|
+
{
|
|
222
|
+
standing: async (id) => standingClaim(id, await comments(id)),
|
|
223
|
+
isReady: async (id) => isOpenToTake(await todo(id)),
|
|
224
|
+
write: async (claim) => {
|
|
225
|
+
const entry: ClaimEntry = { holder: claim.holder, at: now(), expiresAt: claim.expiresAt };
|
|
226
|
+
|
|
227
|
+
await post(claim.item, `${markerLine(ClaimEntry, entry, CLAIM_OPEN)} claimed by ${claim.holder}`);
|
|
228
|
+
|
|
229
|
+
return standingEntry(await comments(claim.item))?.holder === claim.holder;
|
|
230
|
+
},
|
|
231
|
+
},
|
|
232
|
+
now,
|
|
233
|
+
);
|
|
234
|
+
|
|
235
|
+
const threadOf = (list: readonly Comment[]) => list.flatMap((comment) => (claimEntryOf(comment.body) === undefined ? [parseComment(comment.body, comment.created_at)] : []));
|
|
236
|
+
|
|
237
|
+
/** What `watch` hashes for one Todo. Comments are no Todo change, so each open Todo's comment ids count too. */
|
|
238
|
+
const watchedParts = async (found: Todo): Promise<Json> => ({
|
|
239
|
+
id: found.id,
|
|
240
|
+
updatedAt: found.updated_at ?? null,
|
|
241
|
+
done: found.done,
|
|
242
|
+
owner: found.owner?.id ?? null,
|
|
243
|
+
comments: found.done ? [] : (await comments(String(found.id))).map((comment) => comment.id),
|
|
244
|
+
});
|
|
245
|
+
|
|
246
|
+
return {
|
|
247
|
+
apiVersion: 1,
|
|
248
|
+
spent: () => 0,
|
|
249
|
+
close: client.close,
|
|
250
|
+
workSource: {
|
|
251
|
+
listReady: async () => {
|
|
252
|
+
const open = (await todos()).filter(isOpenToTake);
|
|
253
|
+
const free = await Promise.all(open.map(async (found) => isFree(String(found.id), await comments(String(found.id)))));
|
|
254
|
+
|
|
255
|
+
return open.flatMap((found, index) => (free[index] ? [{ id: String(found.id), title: found.title }] : []));
|
|
256
|
+
},
|
|
257
|
+
read: async (id): Promise<Item> => {
|
|
258
|
+
const [found, list] = await Promise.all([todo(id), comments(id)]);
|
|
259
|
+
|
|
260
|
+
return { id, title: found.title, body: found.body, ready: isOpenToTake(found) && isFree(id, list), thread: threadOf(list) };
|
|
261
|
+
},
|
|
262
|
+
claim: (id, holder, ttlMs) => take("claim", parseArgument(ItemId, id), holder, ttlMs),
|
|
263
|
+
renew: (id, holder, ttlMs) => take("renew", parseArgument(ItemId, id), holder, ttlMs),
|
|
264
|
+
comment: (id, text) => postPlain(id, commentText(text)),
|
|
265
|
+
fileFollowUp: async (from, { title, body }) => {
|
|
266
|
+
const filed = filedFollowUp((await comments(from)).map((comment) => comment.body), title);
|
|
267
|
+
|
|
268
|
+
if (filed !== undefined) return { id: filed, title };
|
|
269
|
+
|
|
270
|
+
const created = async () => Todo.parse(await call("todo_create", { title, body: followUpBody(body, `#${from}`) })).id;
|
|
271
|
+
const id = String((await todos()).find(isFollowUpOf(`#${from}`, title))?.id ?? (await created()));
|
|
272
|
+
const note = followUpNote(title, id);
|
|
273
|
+
|
|
274
|
+
await postMarked(from, note.marker, note.text);
|
|
275
|
+
|
|
276
|
+
return { id, title };
|
|
277
|
+
},
|
|
278
|
+
},
|
|
279
|
+
questions: {
|
|
280
|
+
ask: (id, question) => postMarked(id, questionMarker(question.options), questionText(question)),
|
|
281
|
+
decide: (id, text) => postMarked(id, { kind: "decision" }, text),
|
|
282
|
+
},
|
|
283
|
+
answers: {
|
|
284
|
+
answer: (id, { text, option }) => postMarked(id, answerMarker(option), text),
|
|
285
|
+
/** The socket is local: none of this spends rate limit. */
|
|
286
|
+
watch: async (since?: string): Promise<Watch> => {
|
|
287
|
+
const token = hashJson(await Promise.all((await todos()).map(watchedParts)));
|
|
288
|
+
|
|
289
|
+
return { token, changed: token !== since };
|
|
290
|
+
},
|
|
291
|
+
},
|
|
292
|
+
};
|
|
293
|
+
};
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import PQueue from "p-queue";
|
|
2
|
+
import type { Adapter } from "../adapter-api.ts";
|
|
3
|
+
|
|
4
|
+
// SAFETY: every member of an integration role is an async method; each is replaced by one with the same signature.
|
|
5
|
+
const inOrder = <R extends object>(role: R | undefined, queue: PQueue): R | undefined =>
|
|
6
|
+
role && (Object.fromEntries(Object.entries(role).map(([name, member]) => [name, member instanceof Function ? (...args: unknown[]) => queue.add(async () => member.apply(role, args)) : member])) as R);
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Runs an adapter's calls one at a time. Runs that go side by side share one adapter, and an adapter
|
|
10
|
+
* that keeps a clone, as the markdown source does, must not take two writes into it at once.
|
|
11
|
+
*/
|
|
12
|
+
export const serialized = (adapter: Adapter): Adapter => {
|
|
13
|
+
const queue = new PQueue({ concurrency: 1 });
|
|
14
|
+
|
|
15
|
+
return {
|
|
16
|
+
apiVersion: adapter.apiVersion,
|
|
17
|
+
workSource: inOrder(adapter.workSource, queue),
|
|
18
|
+
questions: inOrder(adapter.questions, queue),
|
|
19
|
+
answers: inOrder(adapter.answers, queue),
|
|
20
|
+
release: inOrder(adapter.release, queue),
|
|
21
|
+
};
|
|
22
|
+
};
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { epochMs } from "./limit.ts";
|
|
3
|
+
|
|
4
|
+
/** Tokens a run adds to the item's bill: input, output and cache writes. Cache reads are not counted. */
|
|
5
|
+
export const billed = (input: number, output: number, cacheWrite: number): number => input + output + cacheWrite;
|
|
6
|
+
|
|
7
|
+
const Counts = {
|
|
8
|
+
input_tokens: z.number().default(0),
|
|
9
|
+
output_tokens: z.number().default(0),
|
|
10
|
+
cache_creation_input_tokens: z.number().default(0),
|
|
11
|
+
};
|
|
12
|
+
|
|
13
|
+
/** The advisor model's own calls ride in the message's `iterations`; the message's top-level counts leave them out. */
|
|
14
|
+
const ADVISOR_ITERATION = "advisor_message";
|
|
15
|
+
|
|
16
|
+
const Usage = z.looseObject({
|
|
17
|
+
...Counts,
|
|
18
|
+
cache_read_input_tokens: z.number().default(0),
|
|
19
|
+
iterations: z.array(z.looseObject({ type: z.string(), ...Counts })).default([]),
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
type Usage = z.infer<typeof Usage>;
|
|
23
|
+
|
|
24
|
+
const advisorTokens = ({ iterations }: Usage): number =>
|
|
25
|
+
iterations.filter(({ type }) => type === ADVISOR_ITERATION).reduce((sum, call) => sum + billed(call.input_tokens, call.output_tokens, call.cache_creation_input_tokens), 0);
|
|
26
|
+
|
|
27
|
+
/** The rows of a transcript that matter, each named by what it is. Any other row says nothing. */
|
|
28
|
+
const Row = z.union([
|
|
29
|
+
z
|
|
30
|
+
.looseObject({
|
|
31
|
+
type: z.literal("assistant"),
|
|
32
|
+
isApiErrorMessage: z.literal(true),
|
|
33
|
+
error: z.literal("rate_limit"),
|
|
34
|
+
quotaLimits: z.looseObject({ resetsAt: z.number().optional() }).optional(),
|
|
35
|
+
message: z.looseObject({ content: z.array(z.looseObject({ text: z.string().optional() })).default([]) }).optional(),
|
|
36
|
+
})
|
|
37
|
+
.transform(({ quotaLimits, message }) => ({ kind: "limit", text: message?.content.map(({ text }) => text ?? "").join(" ").trim() ?? "", resetsAt: quotaLimits?.resetsAt === undefined ? undefined : epochMs(quotaLimits.resetsAt) }) as const),
|
|
38
|
+
z
|
|
39
|
+
.looseObject({ type: z.literal("assistant"), isApiErrorMessage: z.literal(true), error: z.string().default("api error") })
|
|
40
|
+
.transform(({ error }) => ({ kind: "api-error", error }) as const),
|
|
41
|
+
z
|
|
42
|
+
.looseObject({ type: z.literal("assistant"), message: z.looseObject({ id: z.string(), model: z.string().optional(), usage: Usage }) })
|
|
43
|
+
.transform(({ message: { id, model, usage } }) => ({ kind: "message", id, spent: { billed: billed(usage.input_tokens, usage.output_tokens, usage.cache_creation_input_tokens) + advisorTokens(usage), output: usage.output_tokens, cacheRead: usage.cache_read_input_tokens, model } }) as const),
|
|
44
|
+
z
|
|
45
|
+
.looseObject({ type: z.literal("attachment"), timestamp: z.iso.datetime(), attachment: z.looseObject({ type: z.literal("structured_output"), data: z.unknown() }) })
|
|
46
|
+
.transform(({ timestamp, attachment }) => ({ kind: "structured", data: attachment.data, at: Date.parse(timestamp) }) as const),
|
|
47
|
+
]);
|
|
48
|
+
|
|
49
|
+
type Row = z.infer<typeof Row>;
|
|
50
|
+
|
|
51
|
+
/** What one message cost. A message streams as several rows that each repeat its final usage, so cost is kept by message id. */
|
|
52
|
+
type Spent = { readonly billed: number; readonly output: number; readonly cacheRead: number; readonly model: string | undefined };
|
|
53
|
+
|
|
54
|
+
/** What a background run's transcript says so far. */
|
|
55
|
+
export type RunTranscript = {
|
|
56
|
+
readonly messages: Readonly<Record<string, Spent>>;
|
|
57
|
+
/** The structured result and the epoch ms it was written. */
|
|
58
|
+
readonly structured: { readonly data: unknown; readonly at: number } | undefined;
|
|
59
|
+
/** The API's error, when the run ended on one. */
|
|
60
|
+
readonly apiError: string | undefined;
|
|
61
|
+
/** The usage limit the run ran into: the reset time as epoch ms when the row carries one, and the row's own words. */
|
|
62
|
+
readonly limit: { readonly resetsAt: number | undefined; readonly text: string } | undefined;
|
|
63
|
+
};
|
|
64
|
+
|
|
65
|
+
/** A line that is no JSON, such as a last row still being written, says nothing. */
|
|
66
|
+
const parseRow = (line: string): Row | undefined => {
|
|
67
|
+
try {
|
|
68
|
+
return Row.safeParse(JSON.parse(line)).data;
|
|
69
|
+
} catch {
|
|
70
|
+
return undefined;
|
|
71
|
+
}
|
|
72
|
+
};
|
|
73
|
+
|
|
74
|
+
const readRow = (t: RunTranscript, row: Row | undefined): RunTranscript => {
|
|
75
|
+
if (row?.kind === "limit") return { ...t, limit: { resetsAt: row.resetsAt, text: row.text } };
|
|
76
|
+
|
|
77
|
+
if (row?.kind === "api-error") return { ...t, apiError: row.error };
|
|
78
|
+
|
|
79
|
+
if (row?.kind === "message") return { ...t, messages: { ...t.messages, [row.id]: row.spent } };
|
|
80
|
+
|
|
81
|
+
return row?.kind === "structured" ? { ...t, structured: { data: row.data, at: row.at } } : t;
|
|
82
|
+
};
|
|
83
|
+
|
|
84
|
+
const EMPTY: RunTranscript = { messages: {}, structured: undefined, apiError: undefined, limit: undefined };
|
|
85
|
+
|
|
86
|
+
/** Reads a run's transcript file. Tokens are summed over distinct message ids, as `-p` sums its `modelUsage`. */
|
|
87
|
+
export const readTranscript = (jsonl: string): RunTranscript => jsonl.split("\n").filter(Boolean).reduce((t, line) => readRow(t, parseRow(line)), EMPTY);
|
|
88
|
+
|
|
89
|
+
const sumOf = (t: RunTranscript, field: (spent: Spent) => number): number => Object.values(t.messages).reduce((sum, spent) => sum + field(spent), 0);
|
|
90
|
+
|
|
91
|
+
export const billedTokens = (t: RunTranscript): number => sumOf(t, (spent) => spent.billed);
|
|
92
|
+
|
|
93
|
+
/** Output tokens the transcript holds, which the job's own count is compared with. */
|
|
94
|
+
export const outputTokens = (t: RunTranscript): number => sumOf(t, (spent) => spent.output);
|
|
95
|
+
|
|
96
|
+
export const cacheReadTokens = (t: RunTranscript): number => sumOf(t, (spent) => spent.cacheRead);
|
|
97
|
+
|
|
98
|
+
/** The model ids that answered, each once. */
|
|
99
|
+
export const modelsOf = (t: RunTranscript): string[] => [...new Set(Object.values(t.messages).flatMap(({ model }) => (model === undefined ? [] : [model])))];
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { InvalidArgumentError } from "commander";
|
|
2
|
+
|
|
3
|
+
/** One flag of an op: its commander spelling, whether it may repeat, and how its value is read. */
|
|
4
|
+
export type Flag = { readonly flag: string; readonly repeats?: true; readonly parse?: (value: string) => number };
|
|
5
|
+
|
|
6
|
+
const wholeSeconds = (value: string): number => {
|
|
7
|
+
const seconds = Number(value);
|
|
8
|
+
|
|
9
|
+
if (!Number.isInteger(seconds) || seconds <= 0) throw new InvalidArgumentError("a positive whole number of seconds");
|
|
10
|
+
|
|
11
|
+
return seconds;
|
|
12
|
+
};
|
|
13
|
+
|
|
14
|
+
type Spec = { readonly summary: string; readonly args: string; readonly flags?: readonly Flag[] };
|
|
15
|
+
|
|
16
|
+
/** One `hum <op>`, as `hum help --json` prints it. */
|
|
17
|
+
export type Command = { readonly summary: string; readonly usage: string };
|
|
18
|
+
|
|
19
|
+
const specs = {
|
|
20
|
+
"list-ready": { summary: "List the items ready to claim.", args: "" },
|
|
21
|
+
claim: { summary: "Take an item for a holder; the first caller wins and a claim expires unless renewed.", args: "<item> <holder>", flags: [{ flag: "--ttl <seconds>", parse: wholeSeconds }, { flag: "--renew" }] },
|
|
22
|
+
read: { summary: "Print an item with its thread.", args: "<item>" },
|
|
23
|
+
comment: { summary: "Add a comment to an item's thread.", args: "<item> <text...>" },
|
|
24
|
+
ask: { summary: "Put a question to the owner on an item's thread.", args: "<item> <text...>", flags: [{ flag: "--option <word>", repeats: true }] },
|
|
25
|
+
answer: { summary: "Write the owner's answer into the item, commit it and push it with hooks off.", args: "<item> <text...>", flags: [{ flag: "--option <word>" }] },
|
|
26
|
+
watch: { summary: "Say whether anything changed since the last watch; costs no rate limit when idle.", args: "", flags: [{ flag: "--since <token>" }] },
|
|
27
|
+
"file-follow-up": { summary: "File a ready item from another item; the same title from the same item files once.", args: "<from-item> <title>", flags: [{ flag: "--body <text>" }] },
|
|
28
|
+
decide: { summary: "Record a choice made without the owner.", args: "<item> <text...>" },
|
|
29
|
+
publish: { summary: "Publish an item's artifact through the release integration.", args: "<item> <ref>" },
|
|
30
|
+
release: { summary: "Release a published artifact through the release integration.", args: "<item> <ref>" },
|
|
31
|
+
push: { summary: "Run git push with hooks off; every argument goes to git.", args: "[git push args...]" },
|
|
32
|
+
} as const satisfies Record<string, Spec>;
|
|
33
|
+
|
|
34
|
+
export type OpName = keyof typeof specs;
|
|
35
|
+
|
|
36
|
+
/** What commander registers for each op: the one place an op's arguments and flags are written. */
|
|
37
|
+
export const opSpecs: Readonly<Record<OpName, Spec>> = specs;
|
|
38
|
+
|
|
39
|
+
const usageOf = (name: string, { args, flags = [] }: Spec): string =>
|
|
40
|
+
["hum", name, args, ...flags.map(({ flag, repeats }) => `[${flag}]${repeats ? "..." : ""}`)].filter(Boolean).join(" ");
|
|
41
|
+
|
|
42
|
+
/** Every `hum <op>`, keyed by its name. Roles and machines name only these. */
|
|
43
|
+
// SAFETY: the entries are the keys of `specs`, mapped one to one.
|
|
44
|
+
export const commands = Object.fromEntries(
|
|
45
|
+
Object.entries(opSpecs).map(([name, spec]) => [name, { summary: spec.summary, usage: usageOf(name, spec) }]),
|
|
46
|
+
) as Readonly<Record<OpName, Command>>;
|
package/src/cli/main.ts
ADDED