Files
mesh-catalog/modules/gitea/tools/calls.ts
T
jschoubben 6b17965d98 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
2026-11-22 00:52:01 +01:00

127 lines
7.3 KiB
TypeScript

// The tools of the forge module's merge calls (novox/hq design 47 H §766, §767): forge_calls reads the calls, newest first,
// with each member's state; forge_call_say_again says a call's merge-called again; forge_partial_clear clears a call's
// merge-partial by hand. Each act is written in the hand-act log before it is done.
import type { ToolDefinition } from "@novox/mesh-sdk/tools";
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() : "");
export function callTools(calls: Calls, partials: Partials, say: Say, acts: (act: HandAct) => Promise<void>): ToolDefinition[] {
return [
{
name: "forge_calls",
description: "The merge calls the forge module keeps (its state calls), newest first: each call's by, account, when, whether its merge-called " +
"was said, and each member with its base, head and state (judged, merged with its commit, or refused with why) (design 47 H §766).",
input: { type: "object", properties: { call: { type: "string", description: "only this merge call" } } },
run: async (args: Record<string, unknown>) => {
const only = word(args.call);
const all = await calls.all();
return { calls: only ? all.filter((c) => c.call === only) : all };
},
},
{
name: "forge_call_say_again",
description: "Says one merge call's merge-called again, for what it landed, with why: a gate that missed it takes the call in. " +
"Written in the hand-act log first (design 47 H §766).",
input: { type: "object", required: ["call", "why"], properties: {
call: { type: "string", description: "the merge call, 16 lowercase hex characters" },
why: { type: "string", description: "why it is said again, in plain words" } } },
run: async (args: Record<string, unknown>) => {
const call = word(args.call), why = word(args.why);
if (!/^[0-9a-f]{16}$/.test(call) || !why) throw new Error("forge_call_say_again names the call (16 lowercase hex characters) and why");
const kept = await calls.get(call);
if (!kept) throw new Error(`the forge module keeps no merge call ${call}`);
const by = callerOf(args);
try {
await acts({ what: `said the merge-called of the merge call ${call} again`, why: `${why} (${by})`, cause: "merge-called-said-again", verb: "forge_call_say_again" });
} catch (err) {
throw new Error(`the hand act was not recorded, so nothing was said: ${err instanceof Error ? err.message : String(err)}`);
}
const said = await sayCall(kept, say);
if (said && !kept.said) {
const { call: _c, ...value } = kept;
await calls.put(call, { ...value, said: true });
}
return { call, said, why, by, ...(said ? {} : { "said-none": "the call landed no member, so it says no merge-called" }) };
},
},
{
name: "forge_partial_clear",
description: "Clears the finding merge-partial of one merge call (a call the forge refused a member of after every member was judged), " +
"with why, when its refused members are not to be merged. Written in the hand-act log first (design 47 H §767).",
input: { type: "object", required: ["call", "why"], properties: {
call: { type: "string", description: "the merge call, 16 lowercase hex characters" },
why: { type: "string", description: "why it is cleared, in plain words" } } },
run: async (args: Record<string, unknown>) => {
const call = word(args.call), why = word(args.why);
if (!/^[0-9a-f]{16}$/.test(call) || !why) throw new Error("forge_partial_clear names the call (16 lowercase hex characters) and why");
const by = callerOf(args);
try {
await acts({ what: `cleared the merge-partial of the merge call ${call}`, why: `${why} (${by})`, cause: "merge-partial-cleared", verb: "forge_partial_clear" });
} catch (err) {
throw new Error(`the hand act was not recorded, so nothing was cleared: ${err instanceof Error ? err.message : String(err)}`);
}
return { call, cleared: await partials.clear(call), why, by };
},
},
];
}
/** 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 };
},
};
}