@orboto/mcp 0.178.0

package/dist/tools/ticket-writes.js

@@ -0,0 +1,778 @@
+/**
+ * ORB-244 Phase C Group 1 - ticket mutation tools.
+ *
+ * Eight tools that round-trip the API's existing PBAC cascade. Every
+ * write is gated on the caller's project-level permissions; a 403
+ * from the API surfaces as `isError: true` on the MCP response with
+ * the API's error message intact, so the model can either retry
+ * elsewhere or explain the lock to the user.
+ *
+ * Resolution patterns mirror Phase B:
+ *   - `projectKey` (`ACME`) → UUID via `/projects/by-key/:key`
+ *   - `ticketKey` (`ACME-42`) → UUID via `/projects/:id/tickets/by-key/:n`
+ *   - `assigneeEmail` → userId via the project members list
+ *   - `milestone` (name) → milestoneId via the project milestones list
+ *
+ * Tools in this file:
+ *   - orboto_create_ticket
+ *   - orboto_update_ticket
+ *   - orboto_move_ticket
+ *   - orboto_close_ticket
+ *   - orboto_comment
+ *   - orboto_assign
+ *   - orboto_unassign
+ *   - orboto_set_milestone
+ *   - orboto_add_ticket_dependency       (ORB-453)
+ *   - orboto_remove_ticket_dependency    (ORB-453)
+ *   - orboto_list_ticket_dependencies    (ORB-453)
+ */
+import { z } from 'zod';
+import { trimSimilarEntries } from './similar-projection.js';
+import { OrbotoApiError } from '../orboto-client.js';
+import { resolveProjectByKey, resolveTicketByKey, resolveByName } from './shared.js';
+import { resolveMilestoneByNameOrId } from './milestones.js';
+// ---------------------------------------------------------------------------
+// Local helpers
+// ---------------------------------------------------------------------------
+const STATUS_CATEGORIES = ['todo', 'in_progress', 'in_review', 'done', 'wont_fix'];
+const CATEGORY_TO_LEGACY = {
+    todo: 'TODO',
+    in_progress: 'IN_PROGRESS',
+    in_review: 'IN_REVIEW',
+    done: 'DONE',
+    wont_fix: 'WONT_FIX',
+};
+async function resolveAssigneeId(client, projectId, email) {
+    const members = await client.get(`/projects/${projectId}/members`);
+    const m = members.find((x) => x.user.email.toLowerCase() === email.toLowerCase());
+    if (!m)
+        throw new Error(`No project member with email "${email}".`);
+    return m.userId;
+}
+/** Resolve a milestone reference (name OR UUID) to its id. Delegates to
+ *  the shared resolver so UUID lookups + ambiguous-name rejection behave
+ *  identically here and on the milestone CRUD tools (ORB-1058). */
+async function resolveMilestoneId(client, projectId, milestoneNameOrId) {
+    return (await resolveMilestoneByNameOrId(client, projectId, milestoneNameOrId)).id;
+}
+/** Render the "ticket created/updated" line every mutation tool ends
+ *  with - keeps responses uniform and easy to chain. */
+function ticketSummaryText(action, t) {
+    return `${action}: [${t.ticketKey}] ${t.title} (${t.statusName ?? t.status})`;
+}
+function ticketStructured(t) {
+    return {
+        key: t.ticketKey,
+        title: t.title,
+        status: t.statusName ?? t.status,
+        statusCategory: t.statusCategory ?? null,
+        type: t.type,
+        priority: t.priority,
+        // ORB-1608 - role-aware commit policy. Absent on responses the API's
+        // enrich pipeline didn't touch; the API itself defaults unset rows to
+        // 'implementation'.
+        deliveryMode: t.deliveryMode ?? 'implementation',
+        dueDate: t.dueDate,
+        isPrivate: t.isPrivate,
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_create_ticket
+// ---------------------------------------------------------------------------
+export const createTicketToolConfig = {
+    title: 'Create a ticket',
+    description: 'Create a new ticket in the given project. Creating more than ~3 tickets? Use `orboto_bulk_create_tickets` instead - one call, one compact response. Returns the new ticket\'s key (e.g. "ACME-42") so callers can chain follow-ups. **Read the new key from `structuredContent.createdTicketKey` (ORB-1176) - never from `similarWarnings[].ticketKey`, which are OTHER, possibly-duplicate tickets.** The caller must have `ticket:create` on the project. **Duplicate-detection safety-net (ORB-831):** if `similarWarnings` appears in the response with one or more entries, the ticket WAS created but you should review whether to close it as a duplicate of the listed ticket(s) instead. The warnings are advisory - never blocking - but each entry is a ticket the system thinks the new one overlaps with. Prefer `orboto_check_similar` BEFORE creating when you want a dry-run. **Deferred check under load (ORB-1437):** if `duplicateCheckDeferred: true` appears, the project was under a create burst so the duplicate-check was run in the background instead of inline - `similarWarnings` is then empty because it did NOT run synchronously, which is NOT the same as "no duplicates found". A strong match, if any, is posted as an advisory comment on the new ticket a moment later; check the ticket comments before treating it as new work. **Duplicate-check recall (ORB-1121):** when you search/check-similar first, results rank by term co-occurrence - a long, solution-framed title with rare terms can return 0 hits even when a short, symptom-framed dup sharing one distinctive token exists. Probe with a single distinctive STABLE token (file/component/error-string fragment), keep queries SHORT, and search the SYMPTOM not your fix; a 0-result long query is not "no dup". **Language-mismatch warning (ORB-890):** if `languageWarning` appears, the ticket was written in a language different from the workspace default. Consider rewriting in the expected language so search + duplicate-detection stay consistent. Non-blocking. **Before a mass-create (ORB-989):** call `orboto_whoami` first - its `workspaceLocale` field is the language you should write every ticket in. If the same `languageWarning` repeats, stop and clarify the intended language rather than pushing through the whole batch. **Strict mode (ORB-990):** if the workspace enforces ticket language, a mismatch is rejected (the tool returns a `blocked` result, not a created ticket) - rewrite in the workspace language, or set `allowLanguageMismatch: true` only when the language is genuinely intentional. **Hard duplicate-block (ORB-1471):** some workspaces REFUSE a create whose top similarity match is at/above a configured threshold - the tool returns a `duplicateBlocked` result (NOT a created ticket) listing the matching tickets. Extend or comment on one of those instead. If you have confirmed none of them cover this work, retry with `allowDuplicate: true` AND a `duplicateJustification` explaining why - the justification is persisted as a comment on the new ticket. '
+        // ORB-1805 - parameter prose moved out of the input schema (which
+        // every client pays for on connect) into this text, which the
+        // manifest summarises to one sentence and orboto_help serves in
+        // full. Same rows also live in the skill's REFERENCE.md.
+        + '**Parameter notes.** `deliveryMode` (ORB-1608) is the role-aware commit policy that replaced the blanket one-commit-per-ticket rule: implementation/docs expect exactly one linked commit (closing without one is a non-blocking warning); review/admin/epic never expect one - reviews are read-only, admin work carries external evidence, epics derive completion from their children; unset defaults to "epic" when type=epic, else "implementation". `milestone` takes a key ("ORB-M3"), a name, or a UUID and is looked up in the project including closed milestones - unknown or ambiguous is an error, so pass the key/UUID when a name repeats. `labels` and `assigneeEmails` attach ATOMICALLY inside the create (ORB-1416): an unknown label or non-member email rolls the whole create back with a 400, leaving no orphan ticket - there is no separate attach call to retry.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
+        title: z.string().min(1).max(255),
+        description: z.string().optional(),
+        type: z.enum(['task', 'bug', 'story', 'epic']).optional().describe('Default: task.'),
+        priority: z.enum(['blocker', 'high', 'normal', 'low', 'trivial']).optional().describe('Default: normal.'),
+        deliveryMode: z.enum(['implementation', 'docs', 'review', 'admin', 'epic']).optional().describe('Default: epic when type=epic, else implementation.'),
+        milestone: z.string().optional().describe('Key ("ORB-M3"), name, or UUID.'),
+        assigneeEmails: z.array(z.string().email()).optional().describe('Project-member emails.'),
+        labels: z.array(z.string()).optional().describe('Existing label names.'),
+        parentTicketKey: z.string().optional().describe('Parent key - makes this a sub-ticket.'),
+        dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('YYYY-MM-DD.'),
+        isPrivate: z.boolean().optional(),
+        allowLanguageMismatch: z.boolean().optional().describe('Override the language block.'),
+        allowDuplicate: z.boolean().optional().describe('Override the duplicate block.'),
+        duplicateJustification: z.string().optional().describe('Why this is not a duplicate.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeCreateTicketHandler(client) {
+    return async (input) => {
+        const project = await resolveProjectByKey(client, input.projectKey);
+        const body = {
+            title: input.title,
+            description: input.description ?? null,
+            type: input.type ?? 'task',
+            priority: input.priority ?? 'normal',
+            isPrivate: input.isPrivate ?? false,
+            // ORB-1608 - leave unset when the caller didn't pass one; the API
+            // defaults it (epic for type=epic, else implementation).
+            ...(input.deliveryMode ? { deliveryMode: input.deliveryMode } : {}),
+        };
+        // ORB-1471 - the override justification rides in the body; the override
+        // flag itself is a querystring param (see createPath below).
+        if (input.allowDuplicate && input.duplicateJustification)
+            body.duplicateJustification = input.duplicateJustification;
+        if (input.dueDate)
+            body.dueDate = input.dueDate;
+        if (input.milestone)
+            body.milestoneId = await resolveMilestoneId(client, project.id, input.milestone);
+        if (input.parentTicketKey) {
+            const parent = await resolveTicketByKey(client, input.parentTicketKey);
+            body.parentTicketId = parent.id;
+        }
+        // ORB-1416 - labels + assignees attach INLINE in the create
+        // transaction so the whole thing is atomic (one round-trip). No more
+        // post-create attach loops: a bad label/assignee reference now rolls
+        // the create back on the API side (clean 400, no orphan ticket) rather
+        // than leaving a half-created ticket the agent retries into a dup.
+        if (input.labels && input.labels.length > 0)
+            body.labelNames = input.labels;
+        if (input.assigneeEmails && input.assigneeEmails.length > 0)
+            body.assigneeEmails = input.assigneeEmails;
+        // ORB-990 - strict ticket-language enforcement may reject this with a
+        // 422; ORB-1471 - the hard duplicate-block may reject it with a 409.
+        // Surface each as a clear block result instead of a raw error.
+        const qs = [];
+        if (input.allowLanguageMismatch)
+            qs.push('allowLanguageMismatch=true');
+        if (input.allowDuplicate)
+            qs.push('allowDuplicate=true');
+        const createPath = `/projects/${project.id}/tickets${qs.length ? `?${qs.join('&')}` : ''}`;
+        let created;
+        try {
+            created = await client.post(createPath, body);
+        }
+        catch (err) {
+            const dup = duplicateBlockResult(err);
+            if (dup)
+                return dup;
+            const blocked = languageBlockResult(err, 'Ticket create');
+            if (blocked)
+                return blocked;
+            throw err;
+        }
+        // ORB-831 / ORB-887 - surface the backend's `similarWarnings` to the
+        // calling agent. The text block prepends a clearly-visible warning
+        // when matches exist so a model scanning the result for "warning"
+        // / "duplicate" notices and self-corrects.
+        // ORB-890 / ORB-891 - same surface for `languageWarning` when the
+        // detected language doesn't match the workspace default.
+        const warnings = created.similarWarnings ?? [];
+        const langWarning = created.languageWarning;
+        const deferred = created.duplicateCheckDeferred === true;
+        const baseText = ticketSummaryText('Created', created);
+        const parts = [baseText];
+        // ORB-1437 - under a create burst the backend defers the duplicate-check
+        // to a background job (empty similarWarnings, duplicateCheckDeferred:true).
+        // Tell the agent so an empty warnings list isn't read as "no duplicates":
+        // a strong match will land as an advisory comment on the new ticket shortly.
+        if (deferred) {
+            parts.push(`\nℹ Duplicate-check deferred - the project is under high create load, so the check runs in the background. `
+                + `An empty duplicate list here does NOT mean "no duplicates". If a strong match is found, an advisory comment `
+                + `will be posted on [${created.ticketKey}] shortly; review it before treating this as new work.`);
+        }
+        if (warnings.length > 0) {
+            parts.push(`\n⚠ Potential duplicates found - review before treating this as new work:\n${warnings.map((w) => `  - [${w.ticketKey ?? w.id.slice(0, 8)}] "${w.title}" (${formatSimilarity(w)})`).join('\n')}\n  If one of these covers the work, close [${created.ticketKey}] as a duplicate via orboto_close_ticket.`);
+        }
+        if (langWarning) {
+            parts.push(`\n⚠ Language mismatch - this ticket reads as "${langWarning.detected}" but the workspace default is "${langWarning.expected}". Consider rewriting in ${langWarning.expected.toUpperCase()} to keep search + duplicate-detection consistent across the project.`);
+        }
+        const text = parts.join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: {
+                ...ticketStructured(created),
+                // ORB-1176 - the one unambiguous field for the NEW ticket's key.
+                // `similarWarnings[].ticketKey` are OTHER tickets; read
+                // `createdTicketKey` (never a warning's key) to avoid grabbing the
+                // wrong one.
+                createdTicketKey: created.ticketKey,
+                // ORB-1693 - agent projection: key/title/category/2dp-similarity/
+                // relation only. The rich shape (UUID, colours, statusName, 15dp)
+                // stays on the REST response for the web UI.
+                similarWarnings: trimSimilarEntries(warnings),
+                ...(deferred ? { duplicateCheckDeferred: true } : {}),
+                ...(langWarning ? { languageWarning: langWarning } : {}),
+            },
+        };
+    };
+}
+/** Append the summaryWarning (ORB-1332) to a move/close result - extra text
+ *  line + the structured field - so both the model's prose read and any
+ *  structured consumer see it. No-op when the backend didn't warn. */
+function withSummaryWarning(result, warning) {
+    if (!warning)
+        return result;
+    const existing = result.content[0];
+    const baseText = existing && existing.type === 'text' ? existing.text : '';
+    return {
+        content: [{ type: 'text', text: `${baseText}\n⚠ ${warning.message}` }],
+        structuredContent: { ...(result.structuredContent ?? {}), summaryWarning: warning },
+    };
+}
+/** Append the deliveryModeWarning (ORB-1608) to a move/close result - same
+ *  shape as `withSummaryWarning` above, sibling advisory. Chainable: both
+ *  can append onto the same result independently. No-op when the backend
+ *  didn't warn. */
+function withDeliveryModeWarning(result, warning) {
+    if (!warning)
+        return result;
+    const existing = result.content[0];
+    const baseText = existing && existing.type === 'text' ? existing.text : '';
+    return {
+        content: [{ type: 'text', text: `${baseText}\n⚠ ${warning.message}` }],
+        structuredContent: { ...(result.structuredContent ?? {}), deliveryModeWarning: warning },
+    };
+}
+/**
+ * ORB-990 - turn a strict-language 422 into a clear, non-throwing tool
+ * result. The backend body is `{ error, languageWarning }`; we surface
+ * the block reason and tell the agent how to proceed (rewrite, or retry
+ * with the override) instead of letting the raw API error bubble up.
+ * Returns null if the error isn't a language-enforcement 422.
+ */
+function languageBlockResult(err, verb) {
+    if (!(err instanceof OrbotoApiError) || err.status !== 422)
+        return null;
+    let parsed = {};
+    try {
+        parsed = JSON.parse(err.body);
+    }
+    catch { /* non-JSON body */ }
+    if (!parsed.languageWarning)
+        return null;
+    const lw = parsed.languageWarning;
+    const text = `⛔ ${verb} blocked - strict ticket-language enforcement is on.\n` +
+        `This content reads as "${lw.detected}" but the workspace language is "${lw.expected}".\n` +
+        `Rewrite it in ${lw.expected.toUpperCase()}, or - only if you are sure the language is intentional - retry the same call with allowLanguageMismatch=true.`;
+    return {
+        content: [{ type: 'text', text }],
+        structuredContent: { blocked: true, languageWarning: lw },
+        isError: true,
+    };
+}
+/**
+ * ORB-1471 - turn the hard duplicate-block 409 into a clear, non-throwing
+ * tool result that surfaces the candidate list VERBATIM plus the exact
+ * override recipe. The backend body is
+ * `{ error, errorKey, similarWarnings, threshold, topSimilarity }`.
+ * Returns null if the error isn't a duplicate-block 409.
+ */
+function duplicateBlockResult(err) {
+    if (!(err instanceof OrbotoApiError) || err.status !== 409)
+        return null;
+    let parsed = {};
+    try {
+        parsed = JSON.parse(err.body);
+    }
+    catch { /* non-JSON body */ }
+    // Only OUR duplicate-block 409 carries similarWarnings; a different 409
+    // (none currently on this route) should bubble as a normal error.
+    if (!parsed.similarWarnings)
+        return null;
+    const candidates = parsed.similarWarnings;
+    const lines = candidates.map((w) => `  - [${w.ticketKey ?? w.id.slice(0, 8)}] "${w.title}" (${formatSimilarity(w)})`);
+    const text = `⛔ Ticket create BLOCKED - this looks like a duplicate (top match ${Math.round((parsed.topSimilarity ?? 0) * 100)}%, block threshold ${Math.round((parsed.threshold ?? 0) * 100)}%).\n` +
+        `Existing tickets it overlaps with:\n${lines.join('\n')}\n` +
+        `Extend or comment on one of these instead. If you have confirmed NONE of them cover this work, retry orboto_create_ticket with allowDuplicate: true AND a duplicateJustification explaining why it is not a duplicate (it is saved as a comment on the new ticket).`;
+    return {
+        content: [{ type: 'text', text }],
+        structuredContent: {
+            duplicateBlocked: true,
+            threshold: parsed.threshold ?? null,
+            topSimilarity: parsed.topSimilarity ?? null,
+            similarWarnings: trimSimilarEntries(candidates),
+        },
+        isError: true,
+    };
+}
+function formatSimilarity(w) {
+    const pct = `${Math.round(w.similarity * 100)}% ${w.matchMode === 'embedding' ? 'AI match' : 'text match'}`;
+    return w.statusName ? `${w.statusName}, ${pct}` : pct;
+}
+// ---------------------------------------------------------------------------
+// orboto_update_ticket
+// ---------------------------------------------------------------------------
+export const updateTicketToolConfig = {
+    title: 'Update a ticket',
+    description: 'Patch one or more fields on a ticket. Patchable: title, description, customerSummary, type, priority, deliveryMode, dueDate, startDate, isPrivate, estimatedTimeMinutes. `customerSummary` is the customer-facing text shown in the customer project report instead of the internal description; null or empty falls back to an AI distillation or the title. `deliveryMode` is the role-aware commit policy (ORB-1608) - see `orboto_create_ticket` for the mode semantics. Use `orboto_move_ticket` for status, `orboto_set_milestone` for milestone, and `orboto_assign` / `orboto_unassign` for members.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        patch: z.object({
+            title: z.string().min(1).max(255).optional(),
+            description: z.string().optional(),
+            customerSummary: z.string().max(2000).nullable().optional().describe('Customer-facing report text; null falls back to AI/title.'),
+            type: z.enum(['task', 'bug', 'story', 'epic']).optional(),
+            priority: z.enum(['blocker', 'high', 'normal', 'low', 'trivial']).optional(),
+            deliveryMode: z.enum(['implementation', 'docs', 'review', 'admin', 'epic']).optional().describe('Commit policy; see orboto_create_ticket.'),
+            dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).nullable().optional(),
+            startDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).nullable().optional(),
+            isPrivate: z.boolean().optional(),
+            estimatedTimeMinutes: z.number().int().nonnegative().optional(),
+        }).refine((p) => Object.keys(p).length > 0, { message: 'patch must include at least one field' }),
+        allowLanguageMismatch: z.boolean().optional().describe('Override the language block; only after a call was blocked.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeUpdateTicketHandler(client) {
+    return async ({ ticketKey, patch, allowLanguageMismatch }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        // ORB-990 - strict ticket-language enforcement may reject a
+        // title/description patch with a 422; surface a clear block result.
+        const patchPath = `/projects/${ticket.projectId}/tickets/${ticket.id}${allowLanguageMismatch ? '?allowLanguageMismatch=true' : ''}`;
+        let updated;
+        try {
+            updated = await client.patch(patchPath, patch);
+        }
+        catch (err) {
+            const blocked = languageBlockResult(err, 'Ticket update');
+            if (blocked)
+                return blocked;
+            throw err;
+        }
+        const langWarning = updated.languageWarning;
+        const parts = [ticketSummaryText('Updated', updated)];
+        if (langWarning) {
+            parts.push(`\n⚠ Language mismatch - this ticket reads as "${langWarning.detected}" but the workspace default is "${langWarning.expected}". Consider rewriting in ${langWarning.expected.toUpperCase()} to keep search + duplicate-detection consistent.`);
+        }
+        return {
+            content: [{ type: 'text', text: parts.join('\n') }],
+            structuredContent: {
+                ...ticketStructured(updated),
+                ...(langWarning ? { languageWarning: langWarning } : {}),
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_move_ticket
+// ---------------------------------------------------------------------------
+export const moveTicketToolConfig = {
+    title: 'Move a ticket between status categories',
+    description: 'Move a ticket to a new status category - todo / in_progress / in_review / done / wont_fix. The API picks the project\'s first status with that category. Caller must have `ticket:change_status`. **Summary warning (ORB-1332):** moving to `in_review` or `done` without having just posted a summary comment returns a non-blocking `summaryWarning` - the move still succeeds, but you should post what changed, the commit SHA, and how to verify. Use `orboto_close_ticket` with a `comment` (or comment first, then move) to avoid it. **Delivery-mode warning (ORB-1608/1642):** moving to `done` on an `implementation`/`docs` ticket with zero linked commits returns a non-blocking `deliveryModeWarning` - UNLESS the project has no git connection at all, in which case it\'s omitted (a link isn\'t possible there). Code `no_commit_linked` means the connection looks healthy - link a commit, or change deliveryMode via `orboto_update_ticket` if the work genuinely is not commit-shaped. Code `git_delivery_failing` means the connection itself looks unhealthy - a commit may already exist and just hasn\'t arrived; check the connection before assuming none was made.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        statusCategory: z.enum(STATUS_CATEGORIES),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeMoveTicketHandler(client) {
+    return async ({ ticketKey, statusCategory }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const updated = await client.patch(`/projects/${ticket.projectId}/tickets/${ticket.id}`, { status: CATEGORY_TO_LEGACY[statusCategory] });
+        return withDeliveryModeWarning(withSummaryWarning({
+            content: [{ type: 'text', text: ticketSummaryText('Moved', updated) }],
+            structuredContent: ticketStructured(updated),
+        }, updated.summaryWarning), updated.deliveryModeWarning);
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_close_ticket
+// ---------------------------------------------------------------------------
+export const closeTicketToolConfig = {
+    title: 'Close a ticket',
+    description: 'Move a ticket to `done` and optionally post a closing comment in one call. Closing more than ~3 tickets? Use `orboto_bulk_close_tickets` instead. Convenience wrapper around `orboto_move_ticket` + `orboto_comment` so the model doesn\'t need to chain two writes. Passing a `comment` is the recommended way to close - it doubles as the transition summary and suppresses the ORB-1332 `summaryWarning`. Closing with no comment (and none posted in the last few minutes) returns a non-blocking `summaryWarning`; the close still succeeds. **Delivery-mode warning (ORB-1608/1642):** on an `implementation`/`docs` ticket, closing with zero linked commits returns a non-blocking `deliveryModeWarning` too - UNLESS the project has no git connection at all, in which case it\'s omitted. `no_commit_linked` = healthy connection, link a commit or change deliveryMode via `orboto_update_ticket`. `git_delivery_failing` = the connection itself looks unhealthy - check it before assuming no commit was made.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        comment: z.string().min(1).optional().describe('Closing comment; doubles as the transition summary.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeCloseTicketHandler(client) {
+    return async ({ ticketKey, comment }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        if (comment) {
+            // Comment first so the close-comment lands in the audit trail
+            // even if the status move 403s. Mirrors the wrapper's `close`
+            // behaviour.
+            await client.post(`/tickets/${ticket.id}/comments`, { content: comment });
+        }
+        const updated = await client.patch(`/projects/${ticket.projectId}/tickets/${ticket.id}`, { status: 'DONE' });
+        return withDeliveryModeWarning(withSummaryWarning({
+            content: [{ type: 'text', text: ticketSummaryText('Closed', updated) }],
+            structuredContent: ticketStructured(updated),
+        }, updated.summaryWarning), updated.deliveryModeWarning);
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_delete_ticket
+// ---------------------------------------------------------------------------
+export const deleteTicketToolConfig = {
+    title: 'Permanently delete a ticket',
+    description: 'DESTRUCTIVE, IRREVERSIBLE hard-delete of a ticket (by key): the row and its history are gone, and a `ticket.deleted` event + webhook fire. Strongly prefer moving the ticket to `wont_fix` (orboto_move_ticket) or closing it instead - wont_fix keeps the history and analytics intact. Only hard-delete a ticket that should truly never have existed (accidental duplicate, spam). Caller must have `ticket:delete`.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeDeleteTicketHandler(client) {
+    return async ({ ticketKey }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        await client.delete(`/projects/${ticket.projectId}/tickets/${ticket.id}`);
+        const key = ticket.ticketKey ?? ticketKey;
+        return {
+            content: [{ type: 'text', text: `Permanently deleted ${key}. This cannot be undone.` }],
+            structuredContent: { deleted: true, ticketKey: key, id: ticket.id },
+        };
+    };
+}
+export const commentToolConfig = {
+    title: 'Post a comment on a ticket',
+    description: 'Append a comment. Supports Markdown. `isInternal=true` hides the comment from external/guest users (use for implementation chatter the customer shouldn\'t see).',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        text: z.string().min(1),
+        isInternal: z.boolean().optional().describe('Default: false (visible to all members + guests).'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeCommentHandler(client) {
+    return async ({ ticketKey, text, isInternal }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const created = await client.post(`/tickets/${ticket.id}/comments`, { content: text, isInternal: isInternal ?? false });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Posted comment on [${ticket.ticketKey}]${created.isInternal ? ' (internal)' : ''}.`,
+                }],
+            structuredContent: {
+                ticketKey: ticket.ticketKey,
+                commentId: created.id,
+                isInternal: created.isInternal,
+                createdAt: created.createdAt,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_update_comment  (ORB-1285)
+// ---------------------------------------------------------------------------
+export const updateCommentToolConfig = {
+    title: 'Edit a ticket comment',
+    description: 'Edit the text of a comment you authored (super-admins can edit any). Markdown. The prior text is snapshotted into the comment\'s revision history. Pass the commentId - from orboto_comment\'s response or orboto_get_ticket.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        commentId: z.string().uuid(),
+        text: z.string().min(1).describe('New comment body (replaces the old text).'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeUpdateCommentHandler(client) {
+    return async ({ ticketKey, commentId, text }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const updated = await client.patch(`/tickets/${ticket.id}/comments/${commentId}`, { content: text });
+        return {
+            content: [{ type: 'text', text: `Edited comment ${commentId.slice(0, 8)} on [${ticket.ticketKey}].` }],
+            structuredContent: { ticketKey: ticket.ticketKey, commentId: updated.id, editedAt: updated.createdAt },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_delete_comment  (ORB-1285)
+// ---------------------------------------------------------------------------
+export const deleteCommentToolConfig = {
+    title: 'Delete a ticket comment',
+    description: 'Delete a comment. You can always delete your own; deleting another user\'s comment needs the `comment:delete_others` permission in the project (super-admins always can). Pass the commentId - from orboto_comment\'s response or orboto_get_ticket.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        commentId: z.string().uuid(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeDeleteCommentHandler(client) {
+    return async ({ ticketKey, commentId }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        await client.delete(`/tickets/${ticket.id}/comments/${commentId}`);
+        return {
+            content: [{ type: 'text', text: `Deleted comment ${commentId.slice(0, 8)} on [${ticket.ticketKey}].` }],
+            structuredContent: { ticketKey: ticket.ticketKey, commentId, deleted: true },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_assign / orboto_unassign
+// ---------------------------------------------------------------------------
+export const assignToolConfig = {
+    title: 'Assign a user to a ticket',
+    description: 'Add a project member as an assignee on a ticket. Multi-assignee is supported - this adds, it does not replace. Use `orboto_unassign` to remove.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        assigneeEmail: z.string().email(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeAssignHandler(client) {
+    return async ({ ticketKey, assigneeEmail }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const userId = await resolveAssigneeId(client, ticket.projectId, assigneeEmail);
+        try {
+            await client.post(`/projects/${ticket.projectId}/tickets/${ticket.id}/assignees/${userId}`, {});
+        }
+        catch (err) {
+            if (err instanceof OrbotoApiError && err.status === 409) {
+                // Already assigned - idempotent success.
+                return {
+                    content: [{ type: 'text', text: `[${ticket.ticketKey}] already assigned to ${assigneeEmail}.` }],
+                    structuredContent: { ticketKey: ticket.ticketKey, alreadyAssigned: true },
+                };
+            }
+            throw err;
+        }
+        return {
+            content: [{ type: 'text', text: `Assigned ${assigneeEmail} to [${ticket.ticketKey}].` }],
+            structuredContent: { ticketKey: ticket.ticketKey, assignedEmail: assigneeEmail },
+        };
+    };
+}
+export const unassignToolConfig = {
+    title: 'Unassign a user from a ticket',
+    description: 'Remove a project member as an assignee. The ticket can become unassigned.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        assigneeEmail: z.string().email(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeUnassignHandler(client) {
+    return async ({ ticketKey, assigneeEmail }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const userId = await resolveAssigneeId(client, ticket.projectId, assigneeEmail);
+        try {
+            await client.delete(`/projects/${ticket.projectId}/tickets/${ticket.id}/assignees/${userId}`);
+        }
+        catch (err) {
+            // 404 = wasn't assigned. Idempotent success.
+            if (err instanceof OrbotoApiError && err.status === 404) {
+                return {
+                    content: [{ type: 'text', text: `${assigneeEmail} wasn't assigned to [${ticket.ticketKey}].` }],
+                    structuredContent: { ticketKey: ticket.ticketKey, alreadyUnassigned: true },
+                };
+            }
+            throw err;
+        }
+        return {
+            content: [{ type: 'text', text: `Unassigned ${assigneeEmail} from [${ticket.ticketKey}].` }],
+            structuredContent: { ticketKey: ticket.ticketKey, unassignedEmail: assigneeEmail },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_label_ticket / orboto_unlabel_ticket - ORB-1043
+// ---------------------------------------------------------------------------
+async function resolveLabelId(client, projectId, name) {
+    const labels = await client.get(`/projects/${projectId}/labels`);
+    // ORB-1826 - exact match wins first, then a unique normalised match
+    // (HTML-entity-decoded, trimmed, whitespace-collapsed, casefolded) so
+    // case/whitespace/entity variants of an existing label name resolve
+    // instead of rejecting. Labels have no unique-name constraint, so an
+    // ambiguous normalised match (two labels differing only by case) still
+    // errors rather than silently picking one.
+    const { match, ambiguous } = resolveByName(labels, name, (l) => l.name);
+    if (ambiguous) {
+        const list = ambiguous.map((l) => `"${l.name}" (${l.id})`).join(', ');
+        throw new Error(`Label name "${name}" is ambiguous - ${ambiguous.length} labels match: ${list}.`);
+    }
+    if (!match) {
+        throw new Error(`No label named "${name}" in this project. Create it first with orboto_create_label.`);
+    }
+    return match.id;
+}
+export const labelTicketToolConfig = {
+    title: 'Add a label to a ticket',
+    description: 'Attach an existing label (by name) to an existing ticket (by key). The label must already exist - create it with orboto_create_label first. Idempotent: a label already on the ticket is a no-op. Needs ticket:edit.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        label: z.string().min(1).describe('Label name (must exist on the project).'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeLabelTicketHandler(client) {
+    return async ({ ticketKey, label }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const labelId = await resolveLabelId(client, ticket.projectId, label);
+        await client.post(`/projects/tickets/${ticket.id}/labels/${labelId}`, {});
+        return {
+            content: [{ type: 'text', text: `Added label "${label}" to [${ticket.ticketKey}].` }],
+            structuredContent: { ticketKey: ticket.ticketKey, label },
+        };
+    };
+}
+export const unlabelTicketToolConfig = {
+    title: 'Remove a label from a ticket',
+    description: 'Detach a label (by name) from a ticket (by key). Idempotent: a label not on the ticket is a no-op. Needs ticket:edit.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        label: z.string().min(1).describe('Label name.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeUnlabelTicketHandler(client) {
+    return async ({ ticketKey, label }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const labelId = await resolveLabelId(client, ticket.projectId, label);
+        await client.delete(`/projects/tickets/${ticket.id}/labels/${labelId}`);
+        return {
+            content: [{ type: 'text', text: `Removed label "${label}" from [${ticket.ticketKey}].` }],
+            structuredContent: { ticketKey: ticket.ticketKey, label, removed: true },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_set_milestone
+// ---------------------------------------------------------------------------
+export const setMilestoneToolConfig = {
+    title: 'Set a ticket\'s milestone',
+    description: 'Move a ticket onto a different milestone (or off all milestones with milestone=null/undefined). Resolves the milestone by key (e.g. "ORB-M3"), name, OR UUID within the ticket\'s project (including closed/archived). If two milestones share a name, pass the key or UUID - an ambiguous name is rejected, not silently guessed.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        milestone: z.string().nullable().optional().describe('Milestone key (e.g. "ORB-M3"), name, or UUID. Pass the key/UUID when the name is ambiguous. Pass null to remove from any milestone.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeSetMilestoneHandler(client) {
+    return async ({ ticketKey, milestone }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        let milestoneId = null;
+        if (milestone) {
+            milestoneId = await resolveMilestoneId(client, ticket.projectId, milestone);
+        }
+        const updated = await client.patch(`/projects/${ticket.projectId}/tickets/${ticket.id}`, { milestoneId });
+        return {
+            content: [{
+                    type: 'text',
+                    text: milestoneId
+                        ? `Moved [${ticket.ticketKey}] to milestone "${milestone}".`
+                        : `Removed [${ticket.ticketKey}] from any milestone.`,
+                }],
+            structuredContent: ticketStructured(updated),
+        };
+    };
+}
+export const addTicketDependencyToolConfig = {
+    title: 'Add a ticket dependency',
+    description: 'Mark `ticketKey` as depending on `dependsOnKey` - i.e. `dependsOnKey` blocks `ticketKey`. Wiring more than ~3 edges? Use `orboto_bulk_add_ticket_dependencies` instead. ORB-1614: the two tickets may live in DIFFERENT projects, as long as you can read both - the API 403s with a forbidden error otherwise. Self-dependencies and cycles (including cycles that span projects) are rejected.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3).describe('The blocked ticket.'),
+        dependsOnKey: z.string().min(3).describe('The blocker; may be in another project.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeAddTicketDependencyHandler(client) {
+    return async ({ ticketKey, dependsOnKey }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const dependsOn = await resolveTicketByKey(client, dependsOnKey);
+        try {
+            await client.post(`/projects/${ticket.projectId}/tickets/${ticket.id}/dependencies`, { dependsOnId: dependsOn.id });
+        }
+        catch (err) {
+            // 409 = edge already exists - idempotent success.
+            if (err instanceof OrbotoApiError && err.status === 409) {
+                return {
+                    content: [{ type: 'text', text: `[${ticket.ticketKey}] already depends on [${dependsOn.ticketKey}].` }],
+                    structuredContent: { ticketKey: ticket.ticketKey, dependsOnKey: dependsOn.ticketKey, alreadyExisted: true },
+                };
+            }
+            throw err;
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `[${ticket.ticketKey}] now depends on [${dependsOn.ticketKey}] - must complete first.`,
+                }],
+            structuredContent: {
+                ticketKey: ticket.ticketKey,
+                dependsOnKey: dependsOn.ticketKey,
+            },
+        };
+    };
+}
+export const removeTicketDependencyToolConfig = {
+    title: 'Remove a ticket dependency',
+    description: 'Drop the dependency edge from `ticketKey` to `dependsOnKey`. Idempotent - removing an edge that isn\'t there returns the same success.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        dependsOnKey: z.string().min(3),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeRemoveTicketDependencyHandler(client) {
+    return async ({ ticketKey, dependsOnKey }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const dependsOn = await resolveTicketByKey(client, dependsOnKey);
+        try {
+            await client.delete(`/projects/${ticket.projectId}/tickets/${ticket.id}/dependencies/${dependsOn.id}`);
+        }
+        catch (err) {
+            // 404 = edge wasn't there. Idempotent success.
+            if (err instanceof OrbotoApiError && err.status === 404) {
+                return {
+                    content: [{ type: 'text', text: `[${ticket.ticketKey}] didn't depend on [${dependsOn.ticketKey}].` }],
+                    structuredContent: { ticketKey: ticket.ticketKey, dependsOnKey: dependsOn.ticketKey, alreadyAbsent: true },
+                };
+            }
+            throw err;
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Removed dependency [${ticket.ticketKey}] → [${dependsOn.ticketKey}].`,
+                }],
+            structuredContent: {
+                ticketKey: ticket.ticketKey,
+                dependsOnKey: dependsOn.ticketKey,
+            },
+        };
+    };
+}
+export const listTicketDependenciesToolConfig = {
+    title: 'List a ticket\'s dependencies',
+    description: 'Show both directions of the dependency graph for a ticket: `blockedBy` (tickets that must finish first) and `blocks` (tickets waiting on this one). ORB-1614: an edge to a ticket in another project you cannot read comes back as an opaque "external dependency" entry (no title/key/status - just whether it is still open).',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+/** ORB-1614 - a stubbed cross-project entry has `title: null`; render a
+ *  fixed, non-identifying placeholder instead of the literal "null". */
+function fmtDependencyEntry(e) {
+    const key = e.ticketKey ?? e.id.slice(0, 8);
+    if (e.title == null) {
+        return `- [${key}] External dependency (access restricted)${e.resolved ? ' - resolved' : ' - still open'}`;
+    }
+    return `- [${key}] ${e.title}${e.statusName ? ` - ${e.statusName}` : ''}`;
+}
+export function makeListTicketDependenciesHandler(client) {
+    return async ({ ticketKey }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const data = await client.get(`/projects/${ticket.projectId}/tickets/${ticket.id}/dependencies`);
+        const fmt = (edges) => edges.length === 0 ? '_(none)_' : edges.map(fmtDependencyEntry).join('\n');
+        const lines = [
+            `# Dependencies for [${ticket.ticketKey}]`,
+            '',
+            '## Blocked by (must complete first)',
+            fmt(data.blockedBy),
+            '',
+            '## Blocks (waiting on this ticket)',
+            fmt(data.blocks),
+        ];
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                ticketKey: ticket.ticketKey,
+                blockedBy: data.blockedBy.map((e) => ({ ticketKey: e.ticketKey, title: e.title, statusName: e.statusName, external: e.external, resolved: e.resolved })),
+                blocks: data.blocks.map((e) => ({ ticketKey: e.ticketKey, title: e.title, statusName: e.statusName, external: e.external, resolved: e.resolved })),
+            },
+        };
+    };
+}