@kammcs/buildit-mcp 0.0.0-stage → 0.1.0

package/dist/tools/planning.js

@@ -0,0 +1,697 @@
+/**
+ * Planning: list_sprints, plan_sprint, list_releases, plan_release and
+ * write_release_notes.
+ *
+ * plan_sprint and plan_release take an action, so an agent sees two tools
+ * for the whole lifecycle instead of ten. Writing release notes is its own
+ * tool because it can overwrite the notes page, which makes it destructive;
+ * the other planning actions only move items between sprints and releases.
+ */
+import { z } from 'zod';
+import { ToolInputError } from '../errors.js';
+import { defineTool } from '../toolsets/registry.js';
+import { sanitizeLabel, wrapUntrusted } from '../untrusted.js';
+import { CursorInput, itemRef, ItemRefInput, limitInput, NAME_CHARS, nextPageHint, ProjectKeyInput, scopesOf, wrapLines, } from './shared.js';
+const label = (v, max = 200) => sanitizeLabel(v, max);
+const DateInput = z.iso.date();
+const ItemsInput = z
+    .array(ItemRefInput)
+    .min(1)
+    .max(50)
+    .describe('Item keys of the project, such as ["DEMO-12", "DEMO-13"]; at most 50.');
+// ---------------------------------------------------------------------------
+// Sprints
+// ---------------------------------------------------------------------------
+const SprintOut = z.object({
+    id: z.string(),
+    number: z.number(),
+    name: z.string(),
+    goal: z.string().nullable().describe('People-written; wrapped as untrusted content.'),
+    state: z.string().describe('planned, active or completed.'),
+    starts_on: z.string().nullable(),
+    ends_on: z.string().nullable(),
+    started_at: z.string().nullable(),
+    completed_at: z.string().nullable(),
+    item_count: z.number(),
+    done_count: z.number(),
+});
+function sprintOut(s) {
+    return {
+        id: s.id,
+        number: s.number,
+        name: label(s.name, NAME_CHARS),
+        goal: s.goal === null ? null : wrapUntrusted(s.goal, { source: 'sprint_goal', maxChars: 500 }),
+        state: s.state,
+        starts_on: s.starts_on,
+        ends_on: s.ends_on,
+        started_at: s.started_at,
+        completed_at: s.completed_at,
+        item_count: s.item_count,
+        done_count: s.done_count,
+    };
+}
+/** A sprint's line; without its counts when the caller states them another way. */
+function sprintLine(s, counts = true) {
+    const dates = s.starts_on || s.ends_on ? ` · ${s.starts_on ?? '?'} to ${s.ends_on ?? '?'}` : '';
+    return `- #${s.number} ${s.name} · ${s.state}${dates}${counts ? ` · done ${s.done_count} of ${s.item_count}` : ''}`;
+}
+/** A sprint's line, then its goal (people-written) flattened, for a block. */
+function sprintLines(s, goal, counts = true) {
+    return [sprintLine(s, counts), ...(goal ? [`  goal: ${label(goal, 500)}`] : [])];
+}
+/** One sprint, in its own block: its name and goal are people-written. */
+function sprintText(s, goal, counts = true) {
+    return wrapLines(sprintLines(s, goal, counts), 'sprint');
+}
+const BoardMoveOut = z.object({
+    key: z.string(),
+    title: z.string(),
+    from: z.string().describe('The backlog status it left.'),
+    to: z.string().describe("Its workflow's first not-started status on the board."),
+});
+const NotMovedOut = z.object({
+    key: z.string(),
+    title: z.string(),
+    status: z.string().describe('Its status, which it keeps.'),
+    reason: z
+        .string()
+        .describe('no_board_status, transition_not_allowed, required_fields or admins_only.'),
+    required_fields: z.array(z.string()).describe('For required_fields: the empty fields.'),
+});
+/**
+ * What starting a sprint did to its backlog items: those moved onto the
+ * board, and those that stay, with why. Titles and status names are
+ * people-written, so both lists are one block.
+ */
+function boardMovesText(moved, notMoved) {
+    const lines = [
+        ...moved.map((m) => `- moved ${m.key}: ${m.from} -> ${m.to} — ${m.title}`),
+        ...notMoved.map((n) => `- stays ${n.key} in ${n.status} (${n.reason}${n.required_fields.length > 0 ? `: needs ${n.required_fields.join(', ')}` : ''}) — ${n.title}`),
+    ];
+    if (lines.length === 0)
+        return [];
+    const head = [
+        ...(moved.length > 0 ? [`${moved.length} backlog item(s) moved onto the board`] : []),
+        ...(notMoved.length > 0
+            ? [`${notMoved.length} stay in the backlog (move them with transition_item)`]
+            : []),
+    ];
+    return [`${head.join('; ')}:`, wrapLines(lines, 'item_list')];
+}
+/**
+ * What completing a sprint did, with one set of counts: the completion's
+ * (committed, completed, carried), which agree with each other. The
+ * sprint's own counts are left out, since carried items no longer count
+ * in it.
+ */
+function completionText(s, goal, r) {
+    const lines = [
+        `Completed sprint #${s.number}: done ${r.completed_count} of ${r.committed_count} item(s) committed (${r.completed_points} of ${r.committed_points} points).`,
+    ];
+    if (r.carried_count > 0) {
+        const to = r.carried_to ? `sprint #${r.carried_to.number}` : 'the backlog (no sprint)';
+        lines.push(`${r.carried_count} open item(s) were carried to ${to}; they count there now, no longer in this sprint.`);
+    }
+    else {
+        lines.push('No open items were left to carry.');
+    }
+    const rest = r.committed_count - r.completed_count - r.carried_count;
+    if (rest > 0)
+        lines.push(`${rest} canceled item(s) stay in this sprint, not done.`);
+    lines.push(sprintText(s, goal, false));
+    return lines.join('\n');
+}
+export const listSprintsTool = defineTool({
+    name: 'list_sprints',
+    toolset: 'planning',
+    title: 'List sprints',
+    description: 'Lists a project\'s sprints, newest first: number, name, goal, state (planned, active, completed), dates and how many items each holds and has done. Filter by state, for example state=["active"] for the current sprint. Sprints are named in other tools by number, name, or "active". Paged: pass next_cursor as cursor for more.',
+    scopes: scopesOf('list_sprints'),
+    annotations: {
+        title: 'List sprints',
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    inputSchema: z.object({
+        project: ProjectKeyInput,
+        state: z
+            .array(z.enum(['planned', 'active', 'completed']))
+            .min(1)
+            .max(3)
+            .optional()
+            .describe('Only sprints in these states.'),
+        cursor: CursorInput.optional(),
+        limit: limitInput(100, 25),
+    }),
+    outputSchema: z.object({
+        project: z.string(),
+        sprints: z.array(SprintOut),
+        next_cursor: z.string().nullable(),
+    }),
+    async run(args, ctx) {
+        const page = await ctx.call('list_sprints', {
+            path: { key: args.project },
+            query: {
+                ...(args.state ? { state: args.state } : {}),
+                ...(args.cursor ? { cursor: args.cursor } : {}),
+                ...(args.limit ? { limit: args.limit } : {}),
+            },
+        });
+        const sprints = page.items.map(sprintOut);
+        const key = args.project.toUpperCase();
+        const text = [
+            sprints.length === 0 ? `No sprints in ${key}.` : `${sprints.length} sprint(s) in ${key}:`,
+            // One block for the list: names and goals are people-written.
+            ...(sprints.length > 0
+                ? [
+                    wrapLines(sprints.flatMap((s, n) => sprintLines(s, page.items[n]?.goal ?? null)), 'sprint_list'),
+                ]
+                : []),
+            nextPageHint('list_sprints', page.next_cursor),
+        ].join('\n');
+        return { structured: { project: key, sprints, next_cursor: page.next_cursor }, text };
+    },
+});
+const SprintActions = ['create', 'start', 'complete', 'add_items', 'remove_items'];
+export const planSprintTool = defineTool({
+    name: 'plan_sprint',
+    toolset: 'planning',
+    title: 'Plan a sprint',
+    description: `Creates, starts or completes a sprint, or moves items in or out of one. action:
+- "create": a planned sprint; needs name, optional goal, starts_on and ends_on (YYYY-MM-DD). The number is assigned.
+- "start": starts a planned sprint (project admins); optional starts_on, ends_on, goal. Only one sprint can be active. Its items in a backlog status move onto the board (To do); the result lists them, and those that stay and why.
+- "complete": completes the active sprint (project admins); its open items go to carry_to: "next" (the next planned sprint, created if there is none; the default), "new" (a new sprint) or "backlog" (no sprint). Returns the committed, completed and carried counts.
+- "add_items": puts up to 50 items of the project in the sprint (taking them out of any other).
+- "remove_items": takes up to 50 items out of the sprint, to the backlog.
+sprint names the sprint for every action but create: its number, name, or "active". Adding or removing items that are already where they should be changes nothing.`,
+    scopes: scopesOf('create_sprint', 'start_sprint', 'complete_sprint', 'add_sprint_items', 'remove_sprint_items'),
+    annotations: {
+        title: 'Plan a sprint',
+        readOnlyHint: false,
+        destructiveHint: false,
+        // Creating twice makes two sprints.
+        idempotentHint: false,
+        openWorldHint: false,
+    },
+    inputSchema: z.object({
+        project: ProjectKeyInput,
+        action: z.enum(SprintActions),
+        sprint: z
+            .string()
+            .min(1)
+            .max(80)
+            .optional()
+            .describe('The sprint: a number, a name or "active". Not for create.'),
+        name: z.string().min(1).max(80).optional().describe('For create: the sprint name.'),
+        goal: z.string().max(500).optional().describe('For create and start: the sprint goal.'),
+        starts_on: DateInput.optional().describe('For create and start: YYYY-MM-DD.'),
+        ends_on: DateInput.optional().describe('For create and start: YYYY-MM-DD.'),
+        carry_to: z
+            .enum(['next', 'new', 'backlog'])
+            .optional()
+            .describe('For complete: where open items go (default next).'),
+        items: ItemsInput.optional().describe('For add_items and remove_items: item keys, at most 50.'),
+    }),
+    outputSchema: z.object({
+        action: z.string(),
+        sprint: SprintOut,
+        changed: z
+            .array(z.string())
+            .optional()
+            .describe('add_items, remove_items: the keys of the items that moved.'),
+        summary: z
+            .object({
+            committed_count: z.number(),
+            committed_points: z.number(),
+            completed_count: z.number(),
+            completed_points: z.number(),
+            carried_count: z.number(),
+            carried_to: z.string().nullable(),
+        })
+            .optional()
+            .describe('complete: the sprint in numbers.'),
+        moved_to_board: z
+            .array(BoardMoveOut)
+            .optional()
+            .describe("start: the sprint's backlog items moved onto the board."),
+        not_moved: z
+            .array(NotMovedOut)
+            .optional()
+            .describe('start: backlog items that stay where they are, and why.'),
+    }),
+    async run(args, ctx) {
+        const key = args.project;
+        const needSprint = () => {
+            if (args.sprint === undefined) {
+                throw new ToolInputError(`action "${args.action}" needs sprint (a number, a name or "active").`);
+            }
+            return args.sprint;
+        };
+        const needItems = () => {
+            if (args.items === undefined)
+                throw new ToolInputError(`action "${args.action}" needs items.`);
+            return args.items.map(itemRef);
+        };
+        switch (args.action) {
+            case 'create': {
+                if (args.name === undefined)
+                    throw new ToolInputError('action "create" needs name.');
+                const r = await ctx.call('create_sprint', {
+                    path: { key },
+                    body: {
+                        name: args.name,
+                        ...(args.goal !== undefined ? { goal: args.goal } : {}),
+                        ...(args.starts_on !== undefined ? { starts_on: args.starts_on } : {}),
+                        ...(args.ends_on !== undefined ? { ends_on: args.ends_on } : {}),
+                    },
+                });
+                const sprint = sprintOut(r.sprint);
+                return {
+                    structured: { action: args.action, sprint },
+                    text: `Created sprint #${sprint.number} in ${key.toUpperCase()}:\n${sprintText(sprint, r.sprint.goal)}`,
+                };
+            }
+            case 'start': {
+                const r = await ctx.call('start_sprint', {
+                    path: { key, sprint: needSprint() },
+                    body: {
+                        ...(args.goal !== undefined ? { goal: args.goal } : {}),
+                        ...(args.starts_on !== undefined ? { starts_on: args.starts_on } : {}),
+                        ...(args.ends_on !== undefined ? { ends_on: args.ends_on } : {}),
+                    },
+                });
+                const sprint = sprintOut(r.sprint);
+                const moved = r.moved_to_board.map((m) => ({
+                    key: m.key,
+                    title: label(m.title, 300),
+                    from: label(m.from, NAME_CHARS),
+                    to: label(m.to, NAME_CHARS),
+                }));
+                const notMoved = r.not_moved.map((n) => ({
+                    key: n.key,
+                    title: label(n.title, 300),
+                    status: label(n.status, NAME_CHARS),
+                    reason: label(n.reason, 40),
+                    required_fields: n.required_fields.map((f) => label(f, NAME_CHARS)),
+                }));
+                return {
+                    structured: { action: args.action, sprint, moved_to_board: moved, not_moved: notMoved },
+                    text: [
+                        `Started sprint #${sprint.number}:\n${sprintText(sprint, r.sprint.goal)}`,
+                        ...boardMovesText(moved, notMoved),
+                    ].join('\n'),
+                };
+            }
+            case 'complete': {
+                const r = await ctx.call('complete_sprint', {
+                    path: { key, sprint: needSprint() },
+                    body: args.carry_to !== undefined ? { carry_to: args.carry_to } : {},
+                });
+                const sprint = sprintOut(r.sprint);
+                const carriedTo = r.carried_to
+                    ? `#${r.carried_to.number} ${label(r.carried_to.name, NAME_CHARS)}`
+                    : null;
+                const summary = {
+                    committed_count: r.committed_count,
+                    committed_points: r.committed_points,
+                    completed_count: r.completed_count,
+                    completed_points: r.completed_points,
+                    carried_count: r.carried_count,
+                    carried_to: carriedTo,
+                };
+                return {
+                    structured: { action: args.action, sprint, summary },
+                    text: completionText(sprint, r.sprint.goal, r),
+                };
+            }
+            case 'add_items':
+            case 'remove_items': {
+                const add = args.action === 'add_items';
+                const r = await ctx.call(add ? 'add_sprint_items' : 'remove_sprint_items', {
+                    path: { key, sprint: needSprint() },
+                    body: { items: needItems() },
+                });
+                const sprint = sprintOut(r.sprint);
+                const changed = r.changed.map((i) => i.key);
+                return {
+                    structured: { action: args.action, sprint, changed },
+                    text: [
+                        changed.length === 0
+                            ? 'Nothing changed: the items were already where they should be.'
+                            : `${add ? 'Added to' : 'Removed from'} sprint #${sprint.number}: ${changed.join(', ')}.`,
+                        wrapLines([sprintLine(sprint)], 'sprint'),
+                    ].join('\n'),
+                };
+            }
+        }
+    },
+});
+// ---------------------------------------------------------------------------
+// Releases
+// ---------------------------------------------------------------------------
+const ReleaseOut = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string().nullable().describe('People-written; wrapped as untrusted content.'),
+    status: z.string().describe('unreleased, released or archived.'),
+    start_date: z.string().nullable(),
+    target_date: z.string().nullable(),
+    released_at: z.string().nullable(),
+    notes_page_id: z.string().nullable().describe('The release notes page (get_page reads it).'),
+    item_count: z.number(),
+    done_count: z.number(),
+});
+function releaseOut(r) {
+    return {
+        id: r.id,
+        name: label(r.name, NAME_CHARS),
+        description: r.description === null
+            ? null
+            : wrapUntrusted(r.description, { source: 'release_description', maxChars: 1000 }),
+        status: r.status,
+        start_date: r.start_date,
+        target_date: r.target_date,
+        released_at: r.released_at,
+        notes_page_id: r.notes_page_id,
+        item_count: r.item_count,
+        done_count: r.done_count,
+    };
+}
+function releaseLine(r) {
+    return `- ${r.name} · ${r.status}${r.target_date ? ` · target ${r.target_date}` : ''}${r.released_at ? ` · released ${r.released_at}` : ''} · ${r.done_count}/${r.item_count} done`;
+}
+/** A release's line, then its description (people-written) flattened, for a block. */
+function releaseLines(r, description) {
+    return [releaseLine(r), ...(description ? [`  ${label(description, 500)}`] : [])];
+}
+/** One release, in its own block: its name and description are people-written. */
+function releaseText(r, description) {
+    return wrapLines(releaseLines(r, description), 'release');
+}
+export const listReleasesTool = defineTool({
+    name: 'list_releases',
+    toolset: 'planning',
+    title: 'List releases',
+    description: "Lists a project's releases (fix versions): name, description, status (unreleased, released, archived), dates, the notes page and how many items each holds and has done. Filter with status. Releases are named in other tools by name. To see a release's items, use search_items with release. Paged: pass next_cursor as cursor for more.",
+    scopes: scopesOf('list_releases'),
+    annotations: {
+        title: 'List releases',
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    inputSchema: z.object({
+        project: ProjectKeyInput,
+        status: z
+            .array(z.enum(['unreleased', 'released', 'archived']))
+            .min(1)
+            .max(3)
+            .optional()
+            .describe('Only releases with these statuses.'),
+        cursor: CursorInput.optional(),
+        limit: limitInput(100, 25),
+    }),
+    outputSchema: z.object({
+        project: z.string(),
+        releases: z.array(ReleaseOut),
+        next_cursor: z.string().nullable(),
+    }),
+    async run(args, ctx) {
+        const page = await ctx.call('list_releases', {
+            path: { key: args.project },
+            query: {
+                ...(args.status ? { status: args.status } : {}),
+                ...(args.cursor ? { cursor: args.cursor } : {}),
+                ...(args.limit ? { limit: args.limit } : {}),
+            },
+        });
+        const releases = page.items.map(releaseOut);
+        const key = args.project.toUpperCase();
+        const text = [
+            releases.length === 0 ? `No releases in ${key}.` : `${releases.length} release(s) in ${key}:`,
+            // One block for the list: names and descriptions are people-written.
+            ...(releases.length > 0
+                ? [
+                    wrapLines(releases.flatMap((r, n) => releaseLines(r, page.items[n]?.description ?? null)), 'release_list'),
+                ]
+                : []),
+            nextPageHint('list_releases', page.next_cursor),
+        ].join('\n');
+        return { structured: { project: key, releases, next_cursor: page.next_cursor }, text };
+    },
+});
+const ReleaseActions = [
+    'create',
+    'release',
+    'update',
+    'reopen',
+    'archive',
+    'restore',
+    'add_items',
+    'remove_items',
+];
+/** reopen, archive and restore: the operation each calls, and what the result says. */
+const STATE_CHANGES = {
+    reopen: { op: 'reopen_release', done: 'Reopened: the release is unreleased again' },
+    archive: { op: 'archive_release', done: 'Archived the release' },
+    restore: { op: 'restore_release', done: 'Restored the release' },
+};
+export const planReleaseTool = defineTool({
+    name: 'plan_release',
+    toolset: 'planning',
+    title: 'Plan a release',
+    description: `Creates, ships, corrects or archives a release, or sets which items it holds. action:
+- "create": an unreleased release; needs name (unique in the project), optional description, start_date and target_date (YYYY-MM-DD).
+- "release": marks it released (project admins), on released_on (default today); its open items move to move_open_to (another release's name) or lose their fix version. Releasing it again changes nothing.
+- "update": changes its name, description, start_date or target_date (null clears one) and, if it is released, released_on, which corrects the day it was released (project admins).
+- "reopen": a released release becomes unreleased again, for one marked released too early (project admins). Its items keep their fix version.
+- "archive": archives it once nothing more is expected from it; "restore" brings it back as it was (project admins). Items keep their fix version.
+- "add_items": sets up to 50 items' fix version to this release.
+- "remove_items": clears the fix version of up to 50 items, when it is this release.
+release names the release (by name) for every action but create. To write its notes page, use write_release_notes.`,
+    scopes: scopesOf('create_release', 'release_version', 'update_release', 'reopen_release', 'archive_release', 'restore_release', 'add_release_items', 'remove_release_items'),
+    annotations: {
+        title: 'Plan a release',
+        readOnlyHint: false,
+        destructiveHint: false,
+        // Creating twice is refused (names are unique), but it is a create.
+        idempotentHint: false,
+        openWorldHint: false,
+    },
+    inputSchema: z.object({
+        project: ProjectKeyInput,
+        action: z.enum(ReleaseActions),
+        release: z.string().min(1).max(80).optional().describe('The release, by name. Not for create.'),
+        name: z
+            .string()
+            .min(1)
+            .max(80)
+            .optional()
+            .describe('For create: the release name, such as 1.2.0; for update: its new name.'),
+        description: z
+            .string()
+            .max(10_000)
+            .nullable()
+            .optional()
+            .describe('For create and update (null clears it in update).'),
+        start_date: DateInput.nullable()
+            .optional()
+            .describe('For create and update: YYYY-MM-DD (null clears it in update).'),
+        target_date: DateInput.nullable()
+            .optional()
+            .describe('For create and update: YYYY-MM-DD (null clears it in update).'),
+        released_on: DateInput.optional().describe('For release: YYYY-MM-DD (default today). For update: the corrected day it was released.'),
+        move_open_to: z
+            .string()
+            .min(1)
+            .max(80)
+            .optional()
+            .describe('For release: the release that open items move to.'),
+        items: ItemsInput.optional().describe('For add_items and remove_items: item keys, at most 50.'),
+    }),
+    outputSchema: z.object({
+        action: z.string(),
+        release: ReleaseOut,
+        changed: z
+            .array(z.string())
+            .optional()
+            .describe('add_items, remove_items: the keys of the items that changed.'),
+    }),
+    async run(args, ctx) {
+        const key = args.project;
+        const needRelease = () => {
+            if (args.release === undefined) {
+                throw new ToolInputError(`action "${args.action}" needs release (its name).`);
+            }
+            return args.release;
+        };
+        switch (args.action) {
+            case 'create': {
+                if (args.name === undefined)
+                    throw new ToolInputError('action "create" needs name.');
+                if (args.description === null || args.start_date === null || args.target_date === null) {
+                    throw new ToolInputError('null clears a field only with action "update"; leave the field out to create without it.');
+                }
+                const r = await ctx.call('create_release', {
+                    path: { key },
+                    body: {
+                        name: args.name,
+                        ...(args.description !== undefined ? { description: args.description } : {}),
+                        ...(args.start_date !== undefined ? { start_date: args.start_date } : {}),
+                        ...(args.target_date !== undefined ? { target_date: args.target_date } : {}),
+                    },
+                });
+                const release = releaseOut(r.release);
+                return {
+                    structured: { action: args.action, release },
+                    text: `Created a release in ${key.toUpperCase()}:\n${releaseText(release, r.release.description)}`,
+                };
+            }
+            case 'release': {
+                const r = await ctx.call('release_version', {
+                    path: { key, release: needRelease() },
+                    body: {
+                        ...(args.released_on !== undefined ? { released_on: args.released_on } : {}),
+                        ...(args.move_open_to !== undefined ? { move_open_to: args.move_open_to } : {}),
+                    },
+                });
+                const release = releaseOut(r.release);
+                return {
+                    structured: { action: args.action, release },
+                    text: `The release is ${release.status}:\n${wrapLines([releaseLine(release)], 'release')}`,
+                };
+            }
+            case 'update': {
+                const body = {
+                    ...(args.name !== undefined ? { name: args.name } : {}),
+                    ...(args.description !== undefined ? { description: args.description } : {}),
+                    ...(args.start_date !== undefined ? { start_date: args.start_date } : {}),
+                    ...(args.target_date !== undefined ? { target_date: args.target_date } : {}),
+                    ...(args.released_on !== undefined ? { released_on: args.released_on } : {}),
+                };
+                if (Object.keys(body).length === 0) {
+                    throw new ToolInputError('action "update" needs at least one of name, description, start_date, target_date or released_on.');
+                }
+                const r = await ctx.call('update_release', {
+                    path: { key, release: needRelease() },
+                    body,
+                });
+                const release = releaseOut(r.release);
+                return {
+                    structured: { action: args.action, release },
+                    text: `Updated the release:\n${releaseText(release, r.release.description)}`,
+                };
+            }
+            case 'reopen':
+            case 'archive':
+            case 'restore': {
+                const change = STATE_CHANGES[args.action];
+                const r = await ctx.call(change.op, { path: { key, release: needRelease() } });
+                const release = releaseOut(r.release);
+                return {
+                    structured: { action: args.action, release },
+                    text: `${change.done} (its items keep their fix version):\n${wrapLines([releaseLine(release)], 'release')}`,
+                };
+            }
+            case 'add_items':
+            case 'remove_items': {
+                if (args.items === undefined)
+                    throw new ToolInputError(`action "${args.action}" needs items.`);
+                const add = args.action === 'add_items';
+                const r = await ctx.call(add ? 'add_release_items' : 'remove_release_items', {
+                    path: { key, release: needRelease() },
+                    body: { items: args.items.map(itemRef) },
+                });
+                const release = releaseOut(r.release);
+                const changed = r.changed.map((i) => i.key);
+                return {
+                    structured: { action: args.action, release, changed },
+                    text: [
+                        changed.length === 0
+                            ? 'Nothing changed: the items were already as asked.'
+                            : `${add ? 'Added to' : 'Removed from'} the release: ${changed.join(', ')}.`,
+                        wrapLines([releaseLine(release)], 'release'),
+                    ].join('\n'),
+                };
+            }
+        }
+    },
+});
+/** The most of the written notes one result shows (the text and structured content both carry it). */
+const NOTES_CHARS = 8000;
+export const writeReleaseNotesTool = defineTool({
+    name: 'write_release_notes',
+    toolset: 'planning',
+    title: 'Write release notes',
+    description: `Writes a release's notes page (in the project channel's pages) from the items it holds.
+- The first call creates the page; later calls rewrite it.
+- If a person edited the page since it was last written, nothing is overwritten: the result says needs_confirmation and gives the page's current version. Show the person, and only if they agree, call again with page_version set to that version, which replaces their edits.
+- locale: the language of the headings (en, es-419, fr-CA, sr-Cyrl or sr-Latn); default: the person's.
+Needs pages:write as well, since the notes are a page. Returns the notes as written (cut at ${NOTES_CHARS.toLocaleString('en')} characters; get_page reads the whole page).`,
+    scopes: scopesOf('generate_release_notes'),
+    annotations: {
+        title: 'Write release notes',
+        readOnlyHint: false,
+        // It can replace a page that people edited (only with page_version).
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    inputSchema: z.object({
+        project: ProjectKeyInput,
+        release: z.string().min(1).max(80).describe('The release, by name.'),
+        locale: z.enum(['en', 'es-419', 'fr-CA', 'sr-Cyrl', 'sr-Latn']).optional(),
+        page_version: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe('Only after the person agreed: the version from needs_confirmation, to replace their edits.'),
+    }),
+    outputSchema: z.object({
+        page_id: z.string().nullable(),
+        page_version: z.number().nullable(),
+        created: z.boolean(),
+        overwrote_edits: z.boolean(),
+        needs_confirmation: z
+            .boolean()
+            .describe('true: people edited the page; nothing was written (see page_version).'),
+        markdown: z
+            .string()
+            .nullable()
+            .describe('The notes as written, wrapped as untrusted content and cut; null when nothing was written.'),
+    }),
+    async run(args, ctx) {
+        const r = await ctx.call('generate_release_notes', {
+            path: { key: args.project, release: args.release },
+            body: {
+                ...(args.locale !== undefined ? { locale: args.locale } : {}),
+                ...(args.page_version !== undefined ? { page_version: args.page_version } : {}),
+            },
+        });
+        const structured = {
+            page_id: r.page_id,
+            page_version: r.page_version,
+            created: r.created,
+            overwrote_edits: r.overwrote_edits,
+            needs_confirmation: r.needs_confirmation,
+            // The notes quote item titles, which people wrote.
+            markdown: r.markdown === undefined
+                ? null
+                : wrapUntrusted(r.markdown, {
+                    source: 'release_notes',
+                    maxChars: NOTES_CHARS,
+                    moreHint: `Call get_page with page="${r.page_id ?? ''}" to read the whole page.`,
+                }),
+        };
+        // The release is named by what the agent sent, not repeated here: people wrote its name.
+        const text = r.needs_confirmation
+            ? `Nothing written: people edited the release notes page (page ${r.page_id ?? '?'}, version ${r.page_version ?? '?'}) since it was last written. Ask the person; only if they want their edits replaced, call write_release_notes again with page_version=${r.page_version ?? '?'}.`
+            : `${r.created ? 'Created' : 'Rewrote'} the release notes page (page ${r.page_id ?? '?'}, version ${r.page_version ?? '?'})${r.overwrote_edits ? ', replacing edits as confirmed' : ''}.`;
+        return {
+            structured,
+            text: structured.markdown ? `${text}\n${structured.markdown}` : text,
+        };
+    },
+});