@orboto/mcp 0.178.0

package/dist/tools/bulk-writes.js

@@ -0,0 +1,339 @@
+/**
+ * ORB-799 - bulk-* writes.
+ *
+ * The wrapper's `bulk-*` family is one of its most-used clusters, used
+ * in every phase-cleanup pass. MCP-side we collapse the wrapper's
+ * `--from=- | @file | "ORB-1,ORB-2"` UX into a single typed `ticketKeys:
+ * string[]` array - the calling agent already has the list as JSON, so
+ * the wrapper's stdin/file-roundtrip is a regression there.
+ *
+ * Each tool:
+ *   - Takes `ticketKeys: string[]` (1..200 keys) + tool-specific params
+ *   - Has a `dryRun: boolean` modifier - when true, resolves every key
+ *     to verify visibility + permission but does NOT issue the
+ *     mutating call. Returns the same outcome shape with a
+ *     `dryRun: true` marker so the caller can preview.
+ *   - Returns `{ successful: [...], failed: [{ticketKey, error}], skipped: [...] }`
+ *     so the model can branch on partial failures instead of parsing
+ *     stderr progress lines like the wrapper does.
+ *
+ * Concurrency: serial per-ticket. Bulk operations land on a tenant DB
+ * that other operators may be writing concurrently; spraying parallel
+ * PATCHes against the same tickets is the kind of thing tenant rate
+ * limits exist to slow down. A 200-ticket bulk-close at ~80ms/ticket
+ * is ~16s - acceptable.
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+import { resolveTicketByKey } from './shared.js';
+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',
+};
+const TICKET_KEY_ARRAY = z.array(z.string().min(3)).min(1).max(200)
+    .describe('Ticket keys (e.g. ["ACME-1", "ACME-2"]). Capped at 200 per call to keep the per-tenant rate-limit budget reasonable.');
+function emptyOutcome(dryRun) {
+    return { successful: [], failed: [], skipped: [], dryRun };
+}
+function bulkResult(action, outcome) {
+    const lines = [
+        `${outcome.dryRun ? '[dry-run] ' : ''}${action} - ${outcome.successful.length} ok, ${outcome.failed.length} failed${outcome.skipped.length ? `, ${outcome.skipped.length} skipped` : ''}.`,
+    ];
+    if (outcome.failed.length > 0) {
+        lines.push('');
+        lines.push('Failed:');
+        for (const f of outcome.failed)
+            lines.push(`  - ${f.ticketKey}: ${f.error}`);
+    }
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        structuredContent: outcome,
+    };
+}
+function errMessage(err) {
+    if (err instanceof OrbotoApiError) {
+        if (err.status === 403)
+            return 'Forbidden - caller lacks permission on this ticket.';
+        if (err.status === 404)
+            return 'Not found.';
+        return `HTTP ${err.status}: ${err.body || '(empty body)'}`;
+    }
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+/** Resolve N keys to N TicketRows. On any failure, record the ticketKey
+ *  + error in `failed` and continue; downstream loops skip those. */
+async function resolveBatch(client, ticketKeys, outcome) {
+    const resolved = new Map();
+    for (const k of ticketKeys) {
+        try {
+            const t = await resolveTicketByKey(client, k);
+            resolved.set(k, t);
+        }
+        catch (err) {
+            outcome.failed.push({ ticketKey: k, error: errMessage(err) });
+        }
+    }
+    return resolved;
+}
+// ---------------------------------------------------------------------------
+// orboto_bulk_patch_tickets
+// ---------------------------------------------------------------------------
+export const bulkPatchTicketsToolConfig = {
+    title: 'Apply the same patch to many tickets',
+    description: 'PATCH every ticket in `ticketKeys` with the same `patch` body. The patch shape mirrors `orboto_update_ticket`: title, description, type, priority, dueDate, startDate, isPrivate, estimatedTimeMinutes. To move many tickets between status categories, use `orboto_bulk_move_tickets` instead. Returns `{successful, failed, skipped, dryRun}` so the caller can branch on partial failures.',
+    inputSchema: z.object({
+        ticketKeys: TICKET_KEY_ARRAY,
+        patch: z.object({
+            title: z.string().min(1).max(255).optional(),
+            description: z.string().optional(),
+            type: z.enum(['task', 'bug', 'story', 'epic']).optional(),
+            priority: z.enum(['blocker', 'high', 'normal', 'low', 'trivial']).optional(),
+            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' }),
+        dryRun: z.boolean().optional().describe('Resolve every ticket to verify visibility/permission, but skip the actual PATCH.'),
+    }).shape,
+    // ORB-1669 - the mutating bulk_* tools are destructive by blast radius:
+    // they overwrite state across N tickets in one call with no undo. The
+    // purely additive ones (bulk_comment, bulk_assign) are not.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+};
+export function makeBulkPatchTicketsHandler(client) {
+    return async ({ ticketKeys, patch, dryRun }) => {
+        const outcome = emptyOutcome(dryRun === true);
+        const resolved = await resolveBatch(client, ticketKeys, outcome);
+        for (const [k, t] of resolved) {
+            if (dryRun) {
+                outcome.skipped.push(k);
+                continue;
+            }
+            try {
+                await client.patch(`/projects/${t.projectId}/tickets/${t.id}`, patch);
+                outcome.successful.push(k);
+            }
+            catch (err) {
+                outcome.failed.push({ ticketKey: k, error: errMessage(err) });
+            }
+        }
+        return bulkResult(`bulk_patch (${Object.keys(patch).join(',')})`, outcome);
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_bulk_move_tickets
+// ---------------------------------------------------------------------------
+export const bulkMoveTicketsToolConfig = {
+    title: 'Move many tickets to a status category',
+    description: 'Move every ticket in `ticketKeys` to the same status category (todo / in_progress / in_review / done / wont_fix). Each ticket lands on its own project\'s first status with that category. Returns the per-ticket outcome.',
+    inputSchema: z.object({
+        ticketKeys: TICKET_KEY_ARRAY,
+        statusCategory: z.enum(STATUS_CATEGORIES),
+        dryRun: z.boolean().optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeBulkMoveTicketsHandler(client) {
+    return async ({ ticketKeys, statusCategory, dryRun }) => {
+        const outcome = emptyOutcome(dryRun === true);
+        const resolved = await resolveBatch(client, ticketKeys, outcome);
+        const legacy = CATEGORY_TO_LEGACY[statusCategory];
+        for (const [k, t] of resolved) {
+            if (dryRun) {
+                outcome.skipped.push(k);
+                continue;
+            }
+            try {
+                await client.patch(`/projects/${t.projectId}/tickets/${t.id}`, { status: legacy });
+                outcome.successful.push(k);
+            }
+            catch (err) {
+                outcome.failed.push({ ticketKey: k, error: errMessage(err) });
+            }
+        }
+        return bulkResult(`bulk_move → ${statusCategory}`, outcome);
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_bulk_close_tickets
+// ---------------------------------------------------------------------------
+export const bulkCloseTicketsToolConfig = {
+    title: 'Close many tickets (optionally with a shared comment)',
+    description: 'For every ticket in `ticketKeys`: optionally post the same `comment` first, then move it to `done`. Mirrors `orboto.mjs bulk-close`. Comment-first ordering means the close note lands in the audit trail even if the status PATCH 403s.',
+    inputSchema: z.object({
+        ticketKeys: TICKET_KEY_ARRAY,
+        comment: z.string().min(1).optional().describe('Optional shared closing comment posted on each ticket before its status move.'),
+        dryRun: z.boolean().optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+};
+export function makeBulkCloseTicketsHandler(client) {
+    return async ({ ticketKeys, comment, dryRun }) => {
+        const outcome = emptyOutcome(dryRun === true);
+        const resolved = await resolveBatch(client, ticketKeys, outcome);
+        for (const [k, t] of resolved) {
+            if (dryRun) {
+                outcome.skipped.push(k);
+                continue;
+            }
+            try {
+                if (comment) {
+                    await client.post(`/tickets/${t.id}/comments`, { content: comment });
+                }
+                await client.patch(`/projects/${t.projectId}/tickets/${t.id}`, { status: 'DONE' });
+                outcome.successful.push(k);
+            }
+            catch (err) {
+                outcome.failed.push({ ticketKey: k, error: errMessage(err) });
+            }
+        }
+        return bulkResult(comment ? 'bulk_close + comment' : 'bulk_close', outcome);
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_bulk_comment_tickets
+// ---------------------------------------------------------------------------
+export const bulkCommentTicketsToolConfig = {
+    title: 'Post the same comment on many tickets',
+    description: 'Append the same comment body to every ticket in `ticketKeys`. Useful for "I am back-propagating decision X to all affected tickets" workflows. `isInternal=true` hides from external/guest users.',
+    inputSchema: z.object({
+        ticketKeys: TICKET_KEY_ARRAY,
+        text: z.string().min(1),
+        isInternal: z.boolean().optional(),
+        dryRun: z.boolean().optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeBulkCommentTicketsHandler(client) {
+    return async ({ ticketKeys, text, isInternal, dryRun }) => {
+        const outcome = emptyOutcome(dryRun === true);
+        const resolved = await resolveBatch(client, ticketKeys, outcome);
+        for (const [k, t] of resolved) {
+            if (dryRun) {
+                outcome.skipped.push(k);
+                continue;
+            }
+            try {
+                await client.post(`/tickets/${t.id}/comments`, {
+                    content: text,
+                    isInternal: isInternal ?? false,
+                });
+                outcome.successful.push(k);
+            }
+            catch (err) {
+                outcome.failed.push({ ticketKey: k, error: errMessage(err) });
+            }
+        }
+        return bulkResult('bulk_comment', outcome);
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_bulk_assign_tickets / orboto_bulk_unassign_tickets
+// ---------------------------------------------------------------------------
+/** Resolve email → userId once per project. The bulk operation may
+ *  touch tickets across multiple projects; we memoize the lookup so we
+ *  don't refetch the members list for every ticket. */
+async function makeAssigneeResolver(client, email) {
+    const cache = new Map();
+    return async (projectId) => {
+        const cached = cache.get(projectId);
+        if (cached)
+            return cached;
+        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}" in this project.`);
+        cache.set(projectId, m.userId);
+        return m.userId;
+    };
+}
+export const bulkAssignTicketsToolConfig = {
+    title: 'Assign the same user to many tickets',
+    description: 'POST `assigneeEmail` as an additional assignee on every ticket in `ticketKeys`. Multi-assignee is supported - this adds, it does not replace. Idempotent: a 409 (already assigned) counts as success.',
+    inputSchema: z.object({
+        ticketKeys: TICKET_KEY_ARRAY,
+        assigneeEmail: z.string().email(),
+        dryRun: z.boolean().optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeBulkAssignTicketsHandler(client) {
+    return async ({ ticketKeys, assigneeEmail, dryRun }) => {
+        const outcome = emptyOutcome(dryRun === true);
+        const resolved = await resolveBatch(client, ticketKeys, outcome);
+        const resolveAssignee = await makeAssigneeResolver(client, assigneeEmail);
+        for (const [k, t] of resolved) {
+            if (dryRun) {
+                outcome.skipped.push(k);
+                continue;
+            }
+            try {
+                const userId = await resolveAssignee(t.projectId);
+                try {
+                    await client.post(`/projects/${t.projectId}/tickets/${t.id}/assignees/${userId}`, {});
+                }
+                catch (err) {
+                    if (err instanceof OrbotoApiError && err.status === 409) {
+                        // Already assigned → idempotent success.
+                        outcome.successful.push(k);
+                        continue;
+                    }
+                    throw err;
+                }
+                outcome.successful.push(k);
+            }
+            catch (err) {
+                outcome.failed.push({ ticketKey: k, error: errMessage(err) });
+            }
+        }
+        return bulkResult(`bulk_assign ${assigneeEmail}`, outcome);
+    };
+}
+export const bulkUnassignTicketsToolConfig = {
+    title: 'Unassign the same user from many tickets',
+    description: 'DELETE `assigneeEmail` from every ticket in `ticketKeys`. Idempotent: a 404 (was not assigned) counts as success.',
+    inputSchema: z.object({
+        ticketKeys: TICKET_KEY_ARRAY,
+        assigneeEmail: z.string().email(),
+        dryRun: z.boolean().optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeBulkUnassignTicketsHandler(client) {
+    return async ({ ticketKeys, assigneeEmail, dryRun }) => {
+        const outcome = emptyOutcome(dryRun === true);
+        const resolved = await resolveBatch(client, ticketKeys, outcome);
+        const resolveAssignee = await makeAssigneeResolver(client, assigneeEmail);
+        for (const [k, t] of resolved) {
+            if (dryRun) {
+                outcome.skipped.push(k);
+                continue;
+            }
+            try {
+                const userId = await resolveAssignee(t.projectId);
+                try {
+                    await client.delete(`/projects/${t.projectId}/tickets/${t.id}/assignees/${userId}`);
+                }
+                catch (err) {
+                    if (err instanceof OrbotoApiError && err.status === 404) {
+                        // Wasn't assigned → idempotent success.
+                        outcome.successful.push(k);
+                        continue;
+                    }
+                    throw err;
+                }
+                outcome.successful.push(k);
+            }
+            catch (err) {
+                outcome.failed.push({ ticketKey: k, error: errMessage(err) });
+            }
+        }
+        return bulkResult(`bulk_unassign ${assigneeEmail}`, outcome);
+    };
+}

package/dist/tools/bulk-writes.test.js

@@ -0,0 +1,239 @@
+/**
+ * ORB-799 - bulk-* tools unit tests.
+ *
+ * Each tool gets one happy-path test (all keys succeed, structured
+ * outcome shape correct) and one partial-failure test (a mix of
+ * resolvable + 403/404 keys to verify the `failed` list shape).
+ *
+ * Resolution chain per ticket: GET /projects/by-key/PROJ +
+ * GET /projects/:id/tickets/by-key/:N. We mock both per ticket.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeBulkPatchTicketsHandler, makeBulkMoveTicketsHandler, makeBulkCloseTicketsHandler, makeBulkCommentTicketsHandler, makeBulkAssignTicketsHandler, makeBulkUnassignTicketsHandler, } from './bulk-writes.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({
+            url: url.toString(),
+            method: init?.method ?? 'GET',
+            body: init?.body ? JSON.parse(init.body) : undefined,
+        });
+        const r = responses.shift();
+        if (!r)
+            throw new Error(`unexpected extra fetch`);
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: 'OK',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => '',
+        };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const PROJ = { id: 'p1', key: 'ACME', name: 'Acme', description: null, status: 'active' };
+function ticket(n) {
+    return {
+        id: `t${n}`, projectId: 'p1', ticketKey: `ACME-${n}`, ticketNumber: n,
+        title: `Ticket ${n}`, status: 'TODO', statusName: 'To Do', statusCategory: 'todo',
+        type: 'task', priority: 'normal', estimatedTimeMinutes: 0, dueDate: null, isPrivate: false,
+    };
+}
+// Resolution responses for keys ACME-1, ACME-2 (project lookup is shared
+// - but the client re-fetches each time. We supply one per key.)
+function resolveOK(n) {
+    return [
+        { json: PROJ },
+        { json: ticket(n) },
+    ];
+}
+describe('orboto_bulk_patch_tickets', () => {
+    it('PATCHes each ticket with the supplied body', async () => {
+        const calls = stub([
+            ...resolveOK(1),
+            ...resolveOK(2),
+            { json: ticket(1) }, // PATCH 1
+            { json: ticket(2) }, // PATCH 2
+        ]);
+        const res = await makeBulkPatchTicketsHandler(client)({
+            ticketKeys: ['ACME-1', 'ACME-2'],
+            patch: { priority: 'high' },
+        });
+        const patchCalls = calls.filter((c) => c.method === 'PATCH');
+        expect(patchCalls).toHaveLength(2);
+        expect(patchCalls[0].body).toEqual({ priority: 'high' });
+        expect(res.structuredContent).toMatchObject({
+            successful: ['ACME-1', 'ACME-2'],
+            failed: [],
+            skipped: [],
+            dryRun: false,
+        });
+    });
+    it('dryRun=true resolves but does not PATCH', async () => {
+        const calls = stub([
+            ...resolveOK(1),
+            ...resolveOK(2),
+        ]);
+        const res = await makeBulkPatchTicketsHandler(client)({
+            ticketKeys: ['ACME-1', 'ACME-2'],
+            patch: { priority: 'high' },
+            dryRun: true,
+        });
+        expect(calls.some((c) => c.method === 'PATCH')).toBe(false);
+        expect(res.structuredContent).toMatchObject({
+            successful: [],
+            skipped: ['ACME-1', 'ACME-2'],
+            dryRun: true,
+        });
+    });
+    it('records per-ticket failures in `failed` and continues', async () => {
+        stub([
+            ...resolveOK(1),
+            ...resolveOK(2),
+            { json: ticket(1) }, // PATCH 1 OK
+            { ok: false, status: 403, json: { error: 'forbidden' } }, // PATCH 2 fails
+        ]);
+        const res = await makeBulkPatchTicketsHandler(client)({
+            ticketKeys: ['ACME-1', 'ACME-2'],
+            patch: { priority: 'high' },
+        });
+        expect(res.structuredContent).toMatchObject({
+            successful: ['ACME-1'],
+            failed: [{ ticketKey: 'ACME-2', error: expect.stringMatching(/Forbidden/) }],
+        });
+    });
+    it('records resolution failures in `failed` and continues with the rest', async () => {
+        stub([
+            ...resolveOK(1),
+            { ok: false, status: 404, json: { error: 'not found' } }, // ACME-2 by-key project fails
+            { json: ticket(1) }, // PATCH 1 OK
+        ]);
+        const res = await makeBulkPatchTicketsHandler(client)({
+            ticketKeys: ['ACME-1', 'ACME-2'],
+            patch: { priority: 'high' },
+        });
+        expect(res.structuredContent).toMatchObject({
+            successful: ['ACME-1'],
+            failed: [{ ticketKey: 'ACME-2' }],
+        });
+    });
+});
+describe('orboto_bulk_move_tickets', () => {
+    it('PATCHes status mapped to legacy enum', async () => {
+        const calls = stub([
+            ...resolveOK(1),
+            ...resolveOK(2),
+            { json: ticket(1) },
+            { json: ticket(2) },
+        ]);
+        await makeBulkMoveTicketsHandler(client)({
+            ticketKeys: ['ACME-1', 'ACME-2'],
+            statusCategory: 'in_review',
+        });
+        const patchCalls = calls.filter((c) => c.method === 'PATCH');
+        expect(patchCalls[0].body).toEqual({ status: 'IN_REVIEW' });
+        expect(patchCalls[1].body).toEqual({ status: 'IN_REVIEW' });
+    });
+});
+describe('orboto_bulk_close_tickets', () => {
+    it('POSTs comment before PATCH when comment is set', async () => {
+        const calls = stub([
+            ...resolveOK(1),
+            { json: { id: 'c1', content: 'closed', isInternal: false, createdAt: 'now' } }, // POST comment
+            { json: { ...ticket(1), status: 'DONE' } }, // PATCH
+        ]);
+        await makeBulkCloseTicketsHandler(client)({
+            ticketKeys: ['ACME-1'],
+            comment: 'closing the loop',
+        });
+        const commentCall = calls.find((c) => c.url.includes('/comments'));
+        const patchCall = calls.find((c) => c.method === 'PATCH');
+        expect(commentCall).toBeDefined();
+        expect(patchCall?.body).toEqual({ status: 'DONE' });
+        // Comment must be BEFORE the patch.
+        expect(calls.indexOf(commentCall)).toBeLessThan(calls.indexOf(patchCall));
+    });
+    it('without comment, only PATCHes status=DONE', async () => {
+        const calls = stub([
+            ...resolveOK(1),
+            { json: { ...ticket(1), status: 'DONE' } },
+        ]);
+        await makeBulkCloseTicketsHandler(client)({ ticketKeys: ['ACME-1'] });
+        expect(calls.some((c) => c.url.includes('/comments'))).toBe(false);
+    });
+});
+describe('orboto_bulk_comment_tickets', () => {
+    it('POSTs the same comment on each ticket', async () => {
+        const calls = stub([
+            ...resolveOK(1),
+            ...resolveOK(2),
+            { json: { id: 'c1', content: 'x', isInternal: false, createdAt: 'now' } },
+            { json: { id: 'c2', content: 'x', isInternal: false, createdAt: 'now' } },
+        ]);
+        await makeBulkCommentTicketsHandler(client)({
+            ticketKeys: ['ACME-1', 'ACME-2'],
+            text: 'heads up',
+            isInternal: true,
+        });
+        const commentCalls = calls.filter((c) => c.url.includes('/comments'));
+        expect(commentCalls).toHaveLength(2);
+        expect(commentCalls[0].body).toEqual({ content: 'heads up', isInternal: true });
+    });
+});
+describe('orboto_bulk_assign_tickets', () => {
+    it('resolves email → userId once per project, then POSTs assignee', async () => {
+        const calls = stub([
+            ...resolveOK(1),
+            ...resolveOK(2),
+            { json: [{ userId: 'u1', user: { email: 'who@orboto.io', fullName: 'Who' }, role: { name: 'dev' } }] }, // members for p1
+            { json: {} }, // POST assignees t1
+            { json: {} }, // POST assignees t2 (member cache hit)
+        ]);
+        const res = await makeBulkAssignTicketsHandler(client)({
+            ticketKeys: ['ACME-1', 'ACME-2'],
+            assigneeEmail: 'who@orboto.io',
+        });
+        // Members fetched exactly once thanks to the per-project cache.
+        expect(calls.filter((c) => c.url.includes('/members'))).toHaveLength(1);
+        expect(res.structuredContent).toMatchObject({
+            successful: ['ACME-1', 'ACME-2'],
+            failed: [],
+        });
+    });
+    it('treats 409 (already assigned) as success', async () => {
+        stub([
+            ...resolveOK(1),
+            { json: [{ userId: 'u1', user: { email: 'who@orboto.io', fullName: 'Who' }, role: { name: 'dev' } }] },
+            { ok: false, status: 409, json: { error: 'already assigned' } },
+        ]);
+        const res = await makeBulkAssignTicketsHandler(client)({
+            ticketKeys: ['ACME-1'],
+            assigneeEmail: 'who@orboto.io',
+        });
+        expect(res.structuredContent).toMatchObject({
+            successful: ['ACME-1'],
+            failed: [],
+        });
+    });
+});
+describe('orboto_bulk_unassign_tickets', () => {
+    it('DELETEs each assignee, treats 404 as success', async () => {
+        stub([
+            ...resolveOK(1),
+            { json: [{ userId: 'u1', user: { email: 'who@orboto.io', fullName: 'Who' }, role: { name: 'dev' } }] },
+            { ok: false, status: 404, json: { error: 'not assigned' } },
+        ]);
+        const res = await makeBulkUnassignTicketsHandler(client)({
+            ticketKeys: ['ACME-1'],
+            assigneeEmail: 'who@orboto.io',
+        });
+        expect(res.structuredContent).toMatchObject({
+            successful: ['ACME-1'],
+            failed: [],
+        });
+    });
+});

package/dist/tools/check-similar.js

@@ -0,0 +1,84 @@
+/**
+ * ORB-831 / ORB-887 - `orboto_check_similar`.
+ *
+ * Dry-run sibling of `orboto_create_ticket`: takes a proposed title +
+ * description and returns the tickets that would land in
+ * `similarWarnings` if the create were to happen now. Intended as the
+ * cautious agent's pre-create probe - call this first when the task
+ * scope feels close to existing work, decide whether to follow up on
+ * the existing ticket instead, then either commit (`orboto_create_ticket`)
+ * or pivot.
+ *
+ * Wraps the existing `GET /projects/:id/tickets/similar` route so the
+ * matching pipeline (tsvector + optional embedding rerank) is shared
+ * with both the UI new-ticket form and the POST-create safety-net.
+ */
+import { z } from 'zod';
+import { trimSimilarEntries } from './similar-projection.js';
+import { resolveProjectByKey, resolveTicketByKey } from './shared.js';
+export const checkSimilarToolConfig = {
+    title: 'Check for similar tickets before creating',
+    description: 'Run the duplicate-detection pipeline (tsvector + AI-embedding rerank when configured) against a proposed title + description, without creating anything. Returns up to `limit` candidates ranked by similarity. Use this BEFORE `orboto_create_ticket` when you want to confirm a feature is not already tracked - if a high-similarity candidate exists, prefer to comment on / claim / extend it instead of opening a new ticket. Empty result = safe to create. `orboto_create_ticket` runs the same check after the fact and surfaces `similarWarnings` in its response, so this tool is optional but cheaper than a create-then-close round trip. An empty result from a LONG, solution-framed title is weak evidence - detection ranks by term co-occurrence, so also probe with a single distinctive STABLE token (file/component/error-string fragment) and the SYMPTOM wording, not just your intended fix.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
+        title: z.string().min(1).describe('Proposed ticket title.'),
+        description: z.string().optional().describe('Proposed description - improves recall.'),
+        limit: z.number().int().min(1).max(10).optional().describe('Max candidates. Default 5.'),
+        parentTicketKey: z.string().optional().describe('Intended parent; makes the check hierarchy-aware.'),
+        forType: z.string().optional().describe('Intended type (task/bug/story/epic).'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeCheckSimilarHandler(client) {
+    return async ({ projectKey, title, description, limit, parentTicketKey, forType }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        const qs = new URLSearchParams({
+            title,
+            limit: String(limit ?? 5),
+        });
+        if (description)
+            qs.set('description', description);
+        // ORB-1604 - hierarchy-aware classification inputs.
+        if (parentTicketKey) {
+            const parent = await resolveTicketByKey(client, parentTicketKey);
+            qs.set('parentTicketId', parent.id);
+        }
+        if (forType)
+            qs.set('forType', forType);
+        const result = await client.get(`/projects/${project.id}/tickets/similar?${qs.toString()}`);
+        // ORB-1604 - only relation-free candidates are duplicate signals; the
+        // parent, siblings and epics are related context (they drove the 70%
+        // --allow-duplicate override rate in the field).
+        const realDuplicates = result.candidates.filter((c) => !c.relation);
+        const related = result.candidates.filter((c) => c.relation);
+        const recommendation = realDuplicates.length === 0
+            ? (related.length === 0
+                ? 'No similar tickets found - safe to create.'
+                : 'Only related context found (parent/sibling/epic) - safe to create; link them instead of treating as duplicates.')
+            : (realDuplicates[0].similarity >= 0.9)
+                ? `HIGH-SIMILARITY MATCH FOUND - review [${realDuplicates[0].ticketKey ?? realDuplicates[0].id.slice(0, 8)}] "${realDuplicates[0].title}" before creating; this may already be tracked.`
+                : 'Possible related tickets - review the list and decide whether the new ticket adds distinct scope.';
+        const text = result.candidates.length === 0
+            ? `${recommendation} (match mode: ${result.mode})`
+            : [
+                recommendation,
+                `Found ${result.candidates.length} candidate(s) via ${result.mode === 'embedding' ? 'AI embedding rerank' : 'tsvector search'}:`,
+                ...result.candidates.map((c) => {
+                    const pct = `${Math.round(c.similarity * 100)}%`;
+                    const status = c.statusName ? ` [${c.statusName}]` : '';
+                    const key = c.ticketKey ?? c.id.slice(0, 8);
+                    const rel = c.relation ? ` (related: ${c.relation})` : '';
+                    return `  - ${key}${status} (${pct} ${c.matchMode})${rel}: ${c.title}`;
+                }),
+            ].join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: {
+                // ORB-1693 - same agent projection as create_ticket's warnings.
+                similar: trimSimilarEntries(result.candidates),
+                mode: result.mode,
+                recommendation,
+            },
+        };
+    };
+}