C5: forge_merged lists a repository's merged pull requests by number

From..to inclusive, each read from the forge one by one, with its merge
commit, when it was merged and the merge call that made it when a kept call
names it merged; at most 768 KB, capped with the next number as the cursor.

Builds: design 47 H2 §812, §811; H-A-402
This commit is contained in:
2026-11-22 00:52:01 +01:00
parent b93253e698
commit 6b17965d98
3 changed files with 80 additions and 1 deletions
+2 -1
View File
@@ -47,7 +47,7 @@ import { failedStepsTools } from "./tools/failedsteps.js";
import { Calls, callRetentionDays, sayUnsaid } from "./calls.js";
import { Once, askTakenBoundMs, takenState } from "./taken.js";
import { Partials } from "./partials.js";
import { callTools } from "./tools/calls.js";
import { callTools, mergedTool } from "./tools/calls.js";
import { seatPublish } from "@novox/mesh-sdk/runtime";
import { seat as GIT, events as GIT_EVENTS, type BranchMovedEvent, type PullClosedEvent, type PullMergedEvent, type PullUpdatedEvent } from "@novox/mesh-delivery-contracts-git";
import { seat as RUNNER, events as RUNNER_EVENTS, type StepEndedEvent } from "@novox/mesh-delivery-contracts-mesh-pipeline-runner";
@@ -304,6 +304,7 @@ registerModuleTools("gitea", () => [eventsTool(pace), ...readAllTools(readAll),
...(gitea ? seatTools(gitea, { run, container: FORGE_CONTAINER, registered: () => registrations.written, judge: (head) => failedSteps.judge(head),
watched: () => registrations.watched, calls, say: seatPublish, partials, once }) : []),
...callTools(calls, partials, seatPublish, async (act) => { await broker().request("seat:mesh-hand-acts.hand-act", act); }),
...(gitea ? [mergedTool(gitea, calls)] : []),
...failedStepsTools(failedSteps, async (act) => { await broker().request("seat:mesh-hand-acts.hand-act", act); })]);
/** What the forge's event asks of the announcer at once (issue 729, 1422): see watch.ts. */
+24
View File
@@ -117,3 +117,27 @@ test("forge_calls reads the calls newest first; forge_call_say_again says one ag
const none: any = await tool("forge_call_say_again").run({ call: "00000000000000bb", why: "x" });
assert.equal(none.said, false, "a call that landed none says none");
});
// 47 H2 §812, §811, H-A-402: forge_merged lists a repository's merged pull requests by number, from..to, each with its merge
// commit, when, and the merge call that made it; a number the forge does not hold or one not merged is left out; capped at
// 768 KB with the next number as the cursor.
test("forge_merged lists merged pull requests by number with the merge call that made each", async () => {
const { mergedTool, ANSWER_CAP_BYTES } = await import("../dist/tools/calls.js");
const sha = (n: number) => String(n % 10).repeat(40);
const forge = { getPullRequest: async (_o: string, _r: string, n: number) => {
if (n === 3) throw new Error("Gitea API /repos/novox/app/pulls/3: 404 Not Found");
return n === 4 ? { number: n, state: "open", merged: false } : { number: n, state: "closed", merged: true, merge_commit_sha: sha(n), merged_at: `2026-11-2${n}T10:00:00Z` };
} };
const calls = { all: async () => [{ call: "00000000000000aa", members: [{ repository: "novox/app", number: 2, state: "merged" }, { repository: "novox/lib", number: 1, state: "merged" }] }] };
const got: any = await mergedTool(forge as any, calls as any).run({ repository: "novox/app", from: 1, to: 5 });
assert.deepEqual(got, { repository: "novox/app", from: 1, to: 5, total: 5, merged: [
{ number: 1, "merge-commit": sha(1), "merged-at": "2026-11-21T10:00:00Z" },
{ number: 2, "merge-commit": sha(2), "merged-at": "2026-11-22T10:00:00Z", call: "00000000000000aa" },
{ number: 5, "merge-commit": sha(5), "merged-at": "2026-11-25T10:00:00Z" }] });
await assert.rejects(mergedTool(forge as any, calls as any).run({ repository: "novox/app", from: 5, to: 4 }), /to not below from/);
// Past 768 KB it is capped, the cursor the next number to read from.
const many: any = await mergedTool(forge as any, { all: async () => [] } as any).run({ repository: "novox/app", from: 5, to: 20_000 });
assert.equal(many.capped, true);
assert.ok(JSON.stringify(many.merged).length <= ANSWER_CAP_BYTES);
assert.equal(many.cursor, many.merged.at(-1).number + 1);
});
+54
View File
@@ -7,6 +7,8 @@ import { callerOf } from "@novox/mesh-sdk/callers";
import type { HandAct } from "@novox/mesh-sdk/views";
import type { Partials } from "../partials.js";
import { sayCall, type Calls, type Say } from "../calls.js";
import type { GiteaClient } from "../client.js";
import { repositoryOf } from "../seat.js";
const word = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
@@ -70,3 +72,55 @@ export function callTools(calls: Calls, partials: Partials, say: Say, acts: (act
},
];
}
/** The most a read tool answers (design 47 H2 §811). */
export const ANSWER_CAP_BYTES = 768 * 1024;
/**
* forge_merged (design 47 H2 §812, §811; H-A-402): a repository's merged pull requests by number, from `from` to `to`
* inclusive, each read from the forge one by one (the forge lists none by number), with its merge commit, when it was
* merged, and the merge call that made it when a kept call names it merged. A number the forge does not hold, or a pull
* request not merged, is left out. At most 768 KB: past it `capped`, with `cursor` the next number to give as `from`.
*/
export function mergedTool(forge: Pick<GiteaClient, "getPullRequest">, calls: Pick<Calls, "all">): ToolDefinition {
return {
name: "forge_merged",
description: "A repository's merged pull requests by number, from..to inclusive: each with its merge commit, when it was merged, and " +
"the merge call that made it (none when it was merged outside a merge call). At most 768 KB: capped, with the cursor to give as from " +
"(design 47 H2 §812).",
input: { type: "object", required: ["repository", "from", "to"], properties: {
repository: { type: "string", description: "the repository, <owner>/<name>" },
from: { type: "integer", description: "the first pull request number" },
to: { type: "integer", description: "the last pull request number" } } },
run: async (args: Record<string, unknown>) => {
const { owner, repo, full } = repositoryOf(args.repository);
const from = Number(args.from), to = Number(args.to);
if (!Number.isInteger(from) || from < 1 || !Number.isInteger(to) || to < from) {
throw new Error("forge_merged names from and to, pull request numbers from 1, to not below from");
}
const madeBy = new Map<number, string>();
for (const c of await calls.all()) {
for (const m of c.members) if (m.repository === full && m.state === "merged") madeBy.set(m.number, c.call);
}
const merged: { number: number; "merge-commit": string; "merged-at"?: string; call?: string }[] = [];
let size = 0;
for (let n = from; n <= to; n++) {
let p;
try {
p = await forge.getPullRequest(owner, repo, n);
} catch (err) {
if (/: 404 /.test(err instanceof Error ? err.message : "")) continue;
throw err;
}
if (!p.merged || !p.merge_commit_sha) continue;
const row = { number: n, "merge-commit": p.merge_commit_sha, ...(p.merged_at ? { "merged-at": p.merged_at } : {}),
...(madeBy.has(n) ? { call: madeBy.get(n) } : {}) };
const rowSize = JSON.stringify(row).length + 1;
if (size + rowSize > ANSWER_CAP_BYTES) return { repository: full, from, to, total: to - from + 1, merged, capped: true, cursor: n };
size += rowSize;
merged.push(row);
}
return { repository: full, from, to, total: to - from + 1, merged };
},
};
}