@orboto/mcp 0.178.0

package/dist/tools/attach.test.js

@@ -0,0 +1,117 @@
+/**
+ * ORB-799 - `orboto_attach_to_ticket` unit tests.
+ *
+ * Covers upload-only, embed=true (re-PATCHes description), and the
+ * empty-base64 refusal. The multipart wire format is opaque to JSON
+ * inspection so we just assert the request shape (route, method,
+ * FormData body).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeAttachToTicketHandler } from './attach.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const PROJ = { id: 'p1', key: 'ACME', name: 'Acme', description: null, status: 'active' };
+const TICKET = {
+    id: 't1', projectId: 'p1', ticketKey: 'ACME-1', ticketNumber: 1,
+    title: 'Bug', description: 'existing body', status: 'TODO', statusName: 'To Do',
+    statusCategory: 'todo', type: 'bug', priority: 'normal',
+    estimatedTimeMinutes: 0, dueDate: null, isPrivate: false,
+};
+const ATTACHMENT = {
+    id: 'att1', filename: 'logo.png', mimetype: 'image/png',
+    sizeBytes: 5, downloadUrl: '/attachments/att1',
+};
+function makeFetchMock(stages) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        const ct = init?.headers
+            ? init.headers['Content-Type']
+            : undefined;
+        let parsedBody;
+        if (typeof init?.body === 'string' && ct?.startsWith('application/json')) {
+            parsedBody = JSON.parse(init.body);
+        }
+        calls.push({
+            url: url.toString(),
+            method: init?.method ?? 'GET',
+            bodyType: init?.body?.constructor?.name ?? 'undefined',
+            body: parsedBody,
+        });
+        const r = stages.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;
+}
+describe('orboto_attach_to_ticket', () => {
+    it('upload-only (embed=false) returns markdown line + URL', async () => {
+        const calls = makeFetchMock([
+            { json: PROJ }, // resolveTicketByKey: project
+            { json: TICKET }, // resolveTicketByKey: ticket
+            { json: ATTACHMENT }, // multipart POST attachments
+        ]);
+        const base64 = Buffer.from('PNGBYTES').toString('base64');
+        const res = await makeAttachToTicketHandler(client)({
+            ticketKey: 'ACME-1', filename: 'logo.png', contentBase64: base64,
+        });
+        const uploadCall = calls.find((c) => c.url.endsWith('/attachments'));
+        expect(uploadCall).toMatchObject({
+            method: 'POST',
+            bodyType: 'FormData',
+        });
+        expect(res.structuredContent).toMatchObject({
+            ticketKey: 'ACME-1',
+            attachmentId: 'att1',
+            url: '/attachments/att1',
+            markdown: '![logo.png](/attachments/att1)',
+            embedded: false,
+        });
+    });
+    it('embed=true re-fetches the ticket and PATCHes the description with appended markdown', async () => {
+        const calls = makeFetchMock([
+            { json: PROJ },
+            { json: TICKET },
+            { json: ATTACHMENT }, // multipart upload
+            { json: TICKET }, // GET ticket (current description)
+            { json: { ...TICKET, description: 'existing body\n\n![logo.png](/attachments/att1)' } }, // PATCH
+        ]);
+        const base64 = Buffer.from('PNGBYTES').toString('base64');
+        const res = await makeAttachToTicketHandler(client)({
+            ticketKey: 'ACME-1', filename: 'logo.png', contentBase64: base64, embed: true,
+        });
+        const patch = calls.find((c) => c.method === 'PATCH');
+        expect(patch?.body).toMatchObject({
+            description: 'existing body\n\n![logo.png](/attachments/att1)',
+        });
+        expect(res.structuredContent).toMatchObject({ embedded: true });
+    });
+    it('refuses an empty base64 payload', async () => {
+        await expect(makeAttachToTicketHandler(client)({
+            ticketKey: 'ACME-1', filename: 'empty.txt', contentBase64: '',
+        })).rejects.toThrow();
+    });
+    it('honors a custom altText', async () => {
+        makeFetchMock([
+            { json: PROJ },
+            { json: TICKET },
+            { json: ATTACHMENT },
+        ]);
+        const base64 = Buffer.from('PNGBYTES').toString('base64');
+        const res = await makeAttachToTicketHandler(client)({
+            ticketKey: 'ACME-1', filename: 'logo.png', contentBase64: base64,
+            altText: 'Brand mark for orboto',
+        });
+        expect(res.structuredContent).toMatchObject({
+            markdown: '![Brand mark for orboto](/attachments/att1)',
+        });
+    });
+});

package/dist/tools/backup.js

@@ -0,0 +1,93 @@
+/**
+ * ORB-1301 - backup MCP tools. Four-way parity with the skill/UI, which can
+ * create an on-demand full backup and download the ZIP. The MCP previously only
+ * had orboto_trigger_backup (run a pre-configured named job).
+ *
+ * Binary archives are returned as MCP `resource` content attachments (base64
+ * blob + mimeType + uri), exactly like orboto_export_doc_pdf (ORB-915) - no new
+ * download mechanism. `OrbotoClient.postBinary` / `getBinary` fetch the bytes.
+ */
+import { z } from 'zod';
+const mb = (n) => `${Math.round((n / 1024 / 1024) * 10) / 10} MB`;
+// ---------------------------------------------------------------------------
+// orboto_create_full_backup
+// ---------------------------------------------------------------------------
+export const createFullBackupToolConfig = {
+    title: 'Create + download a full workspace backup',
+    description: 'Create an on-demand FULL workspace backup (database + storage) and return the ZIP as a base64 application/zip resource attachment - create, wait and download in one call (the server runs the export as a background run and this tool polls it; large workspaces can take minutes). Requires admin:backup:export. For the scheduled named jobs use orboto_trigger_backup instead.',
+    inputSchema: z.object({}).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeCreateFullBackupHandler(client) {
+    return async () => {
+        // ORB-1717 - the export is async server-side (the old synchronous
+        // stream aborted silently under load). Enqueue, poll the run row to a
+        // terminal state, then download the stored artifact - so an aborted
+        // wait never yields a partial ZIP.
+        const { runId } = await client.post('/admin/backup/full', {});
+        const t0 = Date.now();
+        for (;;) {
+            await new Promise((r) => setTimeout(r, 3000));
+            const run = await client.get(`/admin/backup/runs/${runId}`);
+            if (run.status === 'success')
+                break;
+            if (run.status === 'failed')
+                throw new Error(`backup export failed: ${run.errorMessage ?? 'unknown error'}`);
+            if (Date.now() - t0 > 30 * 60_000)
+                throw new Error(`backup export still running after 30 min - check run ${runId} in the backups list`);
+        }
+        const { bytes, contentType } = await client.getBinary(`/admin/backup/runs/${runId}/download`);
+        const base64 = Buffer.from(bytes).toString('base64');
+        return {
+            content: [
+                { type: 'resource', resource: { uri: 'orboto://backup/full.zip', mimeType: contentType, blob: base64 } },
+                { type: 'text', text: `Created full workspace backup (${mb(bytes.byteLength)}), run ${runId}.` },
+            ],
+            structuredContent: { sizeBytes: bytes.byteLength, contentType, runId },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_list_backups
+// ---------------------------------------------------------------------------
+export const listBackupsToolConfig = {
+    title: 'List backup runs',
+    description: 'List recent backup runs (id, status, size, time) so you can pick one to download with orboto_download_backup. Requires admin:backup:read.',
+    inputSchema: z.object({}).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeListBackupsHandler(client) {
+    return async () => {
+        const page = await client.get('/admin/backup/runs');
+        const items = page.items ?? [];
+        const lines = items.map((r) => `- ${r.id} - ${r.status}${r.fileSizeBytes ? ` (${mb(r.fileSizeBytes)})` : ''} - ${r.completedAt ?? r.startedAt}`);
+        return {
+            content: [{ type: 'text', text: items.length ? `Backup runs:\n${lines.join('\n')}` : 'No backup runs yet.' }],
+            structuredContent: { runs: items },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_download_backup
+// ---------------------------------------------------------------------------
+export const downloadBackupToolConfig = {
+    title: 'Download a stored backup run',
+    description: 'Download a stored backup run\'s ZIP by run id (from orboto_list_backups - e.g. the nightly job\'s run) as a base64 application/zip resource attachment. Requires admin:backup:read.',
+    inputSchema: z.object({
+        runId: z.string().uuid().describe('Backup run id from orboto_list_backups.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeDownloadBackupHandler(client) {
+    return async ({ runId }) => {
+        const { bytes, contentType } = await client.getBinary(`/admin/backup/runs/${runId}/download`);
+        const base64 = Buffer.from(bytes).toString('base64');
+        return {
+            content: [
+                { type: 'resource', resource: { uri: `orboto://backup/run-${runId}.zip`, mimeType: contentType, blob: base64 } },
+                { type: 'text', text: `Downloaded backup run ${runId.slice(0, 8)} (${mb(bytes.byteLength)}).` },
+            ],
+            structuredContent: { runId, sizeBytes: bytes.byteLength, contentType },
+        };
+    };
+}

package/dist/tools/backup.test.js

@@ -0,0 +1,108 @@
+/**
+ * ORB-1301 - backup tool tests.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeCreateFullBackupHandler, makeListBackupsHandler, makeDownloadBackupHandler, } from './backup.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+function stubBinary(bytes, contentType = 'application/zip') {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({ url: url.toString(), method: init?.method ?? 'GET' });
+        return {
+            ok: true, status: 200, statusText: 'OK',
+            headers: new Headers({ 'content-type': contentType }),
+            text: async () => '',
+            arrayBuffer: async () => bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
+            json: async () => { throw new Error('not json'); },
+        };
+    });
+    return calls;
+}
+function stubJson(body) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({ url: url.toString(), method: init?.method ?? 'GET' });
+        return {
+            ok: true, status: 200, statusText: 'OK',
+            headers: new Headers({ 'content-type': 'application/json' }),
+            json: async () => body,
+            text: async () => JSON.stringify(body),
+        };
+    });
+    return calls;
+}
+describe('orboto_create_full_backup (ORB-1301 / async since ORB-1717)', () => {
+    it('enqueues, polls the run to success, then downloads the stored ZIP', async () => {
+        vi.useFakeTimers();
+        const zip = new Uint8Array([0x50, 0x4b, 0x03, 0x04]); // PK\x03\x04
+        const calls = [];
+        let polls = 0;
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            const u = url.toString();
+            calls.push({ url: u, method: init?.method ?? 'GET' });
+            if (u.endsWith('/admin/backup/full')) {
+                return { ok: true, status: 202, statusText: 'Accepted', headers: new Headers({ 'content-type': 'application/json' }), json: async () => ({ runId: 'run-1' }), text: async () => '' };
+            }
+            if (u.includes('/admin/backup/runs/run-1/download')) {
+                return { ok: true, status: 200, statusText: 'OK', headers: new Headers({ 'content-type': 'application/zip' }), arrayBuffer: async () => zip.buffer.slice(0), text: async () => '' };
+            }
+            // poll: running twice, then success
+            polls += 1;
+            return { ok: true, status: 200, statusText: 'OK', headers: new Headers({ 'content-type': 'application/json' }), json: async () => ({ status: polls < 3 ? 'running' : 'success', errorMessage: null }), text: async () => '' };
+        });
+        try {
+            const pending = makeCreateFullBackupHandler(client)();
+            await vi.advanceTimersByTimeAsync(15_000);
+            const res = await pending;
+            expect(calls[0].method).toBe('POST');
+            expect(calls[0].url).toContain('/admin/backup/full');
+            const resource = res.content.find((c) => c.type === 'resource');
+            expect(resource.resource.mimeType).toBe('application/zip');
+            expect(Buffer.from(resource.resource.blob, 'base64')).toEqual(Buffer.from(zip));
+            expect(res.structuredContent.runId).toBe('run-1');
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+    it('a failed run surfaces the error instead of a partial ZIP', async () => {
+        vi.useFakeTimers();
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, _init) => {
+            const u = url.toString();
+            if (u.endsWith('/admin/backup/full')) {
+                return { ok: true, status: 202, statusText: 'Accepted', headers: new Headers({ 'content-type': 'application/json' }), json: async () => ({ runId: 'run-2' }), text: async () => '' };
+            }
+            return { ok: true, status: 200, statusText: 'OK', headers: new Headers({ 'content-type': 'application/json' }), json: async () => ({ status: 'failed', errorMessage: 'disk full' }), text: async () => '' };
+        });
+        try {
+            const pending = makeCreateFullBackupHandler(client)();
+            const assertion = expect(pending).rejects.toThrow('disk full');
+            await vi.advanceTimersByTimeAsync(6_000);
+            await assertion;
+        }
+        finally {
+            vi.useRealTimers();
+        }
+    });
+});
+describe('orboto_list_backups (ORB-1301)', () => {
+    it('GETs /admin/backup/runs and returns the runs', async () => {
+        const calls = stubJson({ items: [{ id: 'r1', status: 'success', fileSizeBytes: 1048576, completedAt: 'now' }] });
+        const res = await makeListBackupsHandler(client)();
+        expect(calls[0].url).toContain('/admin/backup/runs');
+        expect(res.structuredContent.runs).toHaveLength(1);
+    });
+});
+describe('orboto_download_backup (ORB-1301)', () => {
+    it('GETs the run download and returns the ZIP as a resource', async () => {
+        const zip = new Uint8Array([0x50, 0x4b]);
+        const calls = stubBinary(zip);
+        const res = await makeDownloadBackupHandler(client)({ runId: 'r1' });
+        expect(calls[0].method).toBe('GET');
+        expect(calls[0].url).toContain('/admin/backup/runs/r1/download');
+        expect(res.structuredContent.runId).toBe('r1');
+    });
+});

package/dist/tools/bulk-create.js

@@ -0,0 +1,213 @@
+/**
+ * ORB-1694 - bulk create + bulk dependency writes.
+ *
+ * Measured over 32 transcripts: `orboto_create_ticket` ran in 48
+ * consecutive-call clusters (longest 49 in a row) and
+ * `orboto_add_ticket_dependency` in 13 (longest 27) - the two longest
+ * runs in the whole tool corpus, each call paying a full round trip
+ * plus a ~1.1k-character response into the calling agent's context.
+ * These two tools collapse a milestone-planning session into one call
+ * with ONE compact aggregated response.
+ *
+ * Same family contract as bulk-writes.ts: serial per-item against the
+ * existing single-item REST endpoints (per-tenant rate-limit posture),
+ * per-item error reporting - one bad item never drops the rest - and a
+ * `{successful, failed}` outcome the model can branch on. Duplicate
+ * findings are reported COMPACTLY: one line per flagged draft, never
+ * the single-tool's full warning block (pairs with ORB-1693).
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+import { resolveProjectByKey, resolveTicketByKey } from './shared.js';
+import { resolveMilestoneByNameOrId } from './milestones.js';
+// ---------------------------------------------------------------------------
+// orboto_bulk_create_tickets
+// ---------------------------------------------------------------------------
+const TicketDraftSchema = z.object({
+    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(),
+    milestone: z.string().optional().describe('Key ("ORB-M3"), name, or UUID; overrides the call-level one.'),
+    assigneeEmails: z.array(z.string().email()).optional(),
+    labels: z.array(z.string()).optional().describe('Existing label names.'),
+    parentTicketKey: z.string().optional(),
+    dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+    isPrivate: z.boolean().optional(),
+});
+export const bulkCreateTicketsToolConfig = {
+    title: 'Create many tickets in one call',
+    description: 'Create up to 50 tickets in one call - the right tool whenever you are about to create more than ~3 tickets (milestone planning, epic breakdown, import). Per-draft error isolation: a rejected draft (bad label, language block, hard duplicate-block) is reported in `failed` while the rest are still created. Duplicate detection runs per draft and is reported compactly - one line per flagged draft in `duplicateFlags`; review those before treating them as new work. A call-level `milestone` / `parentTicketKey` applies to every draft unless the draft overrides it. Drafts are created in array order, so a draft can NOT reference a sibling draft as parent - create parents first (or in a first call).',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key - all drafts land here.'),
+        tickets: z.array(TicketDraftSchema).min(1).max(50).describe('The ticket drafts, created in order.'),
+        milestone: z.string().optional().describe('Applied to every draft without its own.'),
+        parentTicketKey: z.string().optional().describe('Applied to every draft without its own.'),
+        allowLanguageMismatch: z.boolean().optional().describe('Override the language block for every draft.'),
+    }).shape,
+    outputSchema: z.object({
+        created: z.array(z.string()).describe('Keys, in draft order.'),
+        failed: z.array(z.object({ index: z.number().int(), title: z.string(), error: z.string() })),
+        duplicateFlags: z.array(z.object({
+            key: z.string().describe('The new, flagged ticket.'),
+            matches: z.array(z.object({ ticketKey: z.string().nullable(), similarity: z.number() })),
+        })),
+        languageWarnings: z.number().int().describe('Drafts with a language warning.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeBulkCreateTicketsHandler(client) {
+    return async (input) => {
+        const project = await resolveProjectByKey(client, input.projectKey);
+        // Resolve shared + per-draft milestone/parent references ONCE per
+        // distinct value - 20 drafts on one milestone = one lookup.
+        const milestoneIds = new Map();
+        const resolveMilestone = async (ref) => {
+            const cached = milestoneIds.get(ref);
+            if (cached)
+                return cached;
+            const id = (await resolveMilestoneByNameOrId(client, project.id, ref)).id;
+            milestoneIds.set(ref, id);
+            return id;
+        };
+        const parentIds = new Map();
+        const resolveParent = async (key) => {
+            const cached = parentIds.get(key);
+            if (cached)
+                return cached;
+            const id = (await resolveTicketByKey(client, key)).id;
+            parentIds.set(key, id);
+            return id;
+        };
+        const created = [];
+        const failed = [];
+        const duplicateFlags = [];
+        let languageWarnings = 0;
+        for (let i = 0; i < input.tickets.length; i++) {
+            const draft = input.tickets[i];
+            try {
+                const body = {
+                    title: draft.title,
+                    description: draft.description ?? null,
+                    type: draft.type ?? 'task',
+                    priority: draft.priority ?? 'normal',
+                    isPrivate: draft.isPrivate ?? false,
+                    ...(draft.deliveryMode ? { deliveryMode: draft.deliveryMode } : {}),
+                    ...(draft.dueDate ? { dueDate: draft.dueDate } : {}),
+                    ...(draft.labels?.length ? { labelNames: draft.labels } : {}),
+                    ...(draft.assigneeEmails?.length ? { assigneeEmails: draft.assigneeEmails } : {}),
+                };
+                const milestoneRef = draft.milestone ?? input.milestone;
+                if (milestoneRef)
+                    body.milestoneId = await resolveMilestone(milestoneRef);
+                const parentRef = draft.parentTicketKey ?? input.parentTicketKey;
+                if (parentRef)
+                    body.parentTicketId = await resolveParent(parentRef);
+                const qs = input.allowLanguageMismatch ? '?allowLanguageMismatch=true' : '';
+                const res = await client.post(`/projects/${project.id}/tickets${qs}`, body);
+                created.push(res.ticketKey ?? res.id);
+                if (res.languageWarning)
+                    languageWarnings++;
+                const warnings = res.similarWarnings ?? [];
+                if (warnings.length > 0) {
+                    duplicateFlags.push({
+                        key: res.ticketKey ?? res.id,
+                        matches: warnings.slice(0, 3).map((w) => ({
+                            ticketKey: w.ticketKey,
+                            similarity: Math.round(w.similarity * 100) / 100,
+                        })),
+                    });
+                }
+            }
+            catch (err) {
+                const msg = err instanceof OrbotoApiError
+                    ? `${err.status}: ${err.message}`
+                    : err instanceof Error ? err.message : String(err);
+                failed.push({ index: i, title: draft.title.slice(0, 60), error: msg.slice(0, 200) });
+            }
+        }
+        const lines = [
+            `bulk_create - ${created.length} created, ${failed.length} failed${duplicateFlags.length ? `, ${duplicateFlags.length} flagged as possible duplicates` : ''}${languageWarnings ? `, ${languageWarnings} language warnings` : ''}.`,
+        ];
+        if (created.length > 0)
+            lines.push(`Created: ${created.join(', ')}`);
+        for (const f of duplicateFlags) {
+            lines.push(`⚠ ${f.key} may duplicate ${f.matches.map((m) => `${m.ticketKey ?? '?'} (${m.similarity})`).join(', ')} - review before treating as new work.`);
+        }
+        for (const f of failed) {
+            lines.push(`✗ draft ${f.index} "${f.title}": ${f.error}`);
+        }
+        if (languageWarnings > 0) {
+            lines.push(`⚠ ${languageWarnings} draft(s) in a non-workspace language - consider rewriting for search/duplicate consistency.`);
+        }
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: { created, failed, duplicateFlags, languageWarnings },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_bulk_add_ticket_dependencies
+// ---------------------------------------------------------------------------
+export const bulkAddTicketDependenciesToolConfig = {
+    title: 'Add many ticket dependencies in one call',
+    description: 'Create up to 200 blocked-by edges in one call - use instead of repeated orboto_add_ticket_dependency whenever wiring more than ~3 edges (dependency graphs after a bulk create). Each pair is (ticketKey, dependsOnKey) = "ticket is blocked by dependsOn". Per-pair error isolation; an already-existing edge counts as ok, a cycle rejection lands in `failed` with the API\'s reason.',
+    inputSchema: z.object({
+        pairs: z.array(z.object({
+            ticketKey: z.string().min(3).describe('The blocked ticket.'),
+            dependsOnKey: z.string().min(3).describe('The blocking ticket.'),
+        })).min(1).max(200),
+    }).shape,
+    outputSchema: z.object({
+        successful: z.array(z.string()).describe('"A->B" pairs written (or already present).'),
+        failed: z.array(z.object({ pair: z.string(), error: z.string() })),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeBulkAddTicketDependenciesHandler(client) {
+    return async (input) => {
+        // Resolve every distinct key once, not once per edge.
+        const resolved = new Map();
+        const resolve = async (key) => {
+            const cached = resolved.get(key);
+            if (cached)
+                return cached;
+            const t = await resolveTicketByKey(client, key);
+            resolved.set(key, t);
+            return t;
+        };
+        const successful = [];
+        const failed = [];
+        for (const { ticketKey, dependsOnKey } of input.pairs) {
+            const label = `${ticketKey}->${dependsOnKey}`;
+            try {
+                const ticket = await resolve(ticketKey);
+                const dependsOn = await resolve(dependsOnKey);
+                try {
+                    await client.post(`/projects/${ticket.projectId}/tickets/${ticket.id}/dependencies`, { dependsOnId: dependsOn.id });
+                }
+                catch (err) {
+                    // 409 = edge already exists - idempotent success, same as the
+                    // single-edge tool.
+                    if (!(err instanceof OrbotoApiError && err.status === 409))
+                        throw err;
+                }
+                successful.push(label);
+            }
+            catch (err) {
+                const msg = err instanceof OrbotoApiError
+                    ? `${err.status}: ${err.message}`
+                    : err instanceof Error ? err.message : String(err);
+                failed.push({ pair: label, error: msg.slice(0, 200) });
+            }
+        }
+        const lines = [`bulk_add_dependencies - ${successful.length} ok, ${failed.length} failed.`];
+        for (const f of failed)
+            lines.push(`✗ ${f.pair}: ${f.error}`);
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: { successful, failed },
+        };
+    };
+}

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

@@ -0,0 +1,135 @@
+/**
+ * ORB-1694 - bulk create + bulk dependency writes.
+ *
+ * Pins the family contract: per-item error isolation (one bad draft
+ * never drops the rest), compact one-line duplicate flags, reference
+ * resolution cached per distinct value, 409-on-existing-edge counted
+ * as success - and the acceptance criterion that a 20-item bulk create
+ * answers in ONE response under ~2k characters.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeBulkCreateTicketsHandler, makeBulkAddTicketDependenciesHandler, } from './bulk-create.js';
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+/** Route-aware fetch stub: project + milestone resolution, then per-draft
+ *  create responses driven by the draft title. */
+function stubApi(opts = {}) {
+    const calls = [];
+    let seq = 0;
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        const u = String(url);
+        const body = init?.body ? JSON.parse(init.body) : undefined;
+        calls.push({ method: init?.method ?? 'GET', url: u, body });
+        const json = (payload, status = 200) => ({
+            ok: status < 400, status, statusText: 'X',
+            json: async () => payload, text: async () => JSON.stringify(payload),
+        });
+        if (u.includes('/projects/by-key/')) {
+            return json({ id: 'proj-1', key: 'ACME', name: 'Acme' });
+        }
+        if (u.includes('/milestones')) {
+            return json([{ id: 'ms-1', name: 'Sprint 1', milestoneKey: 'ACME-M1' }]);
+        }
+        if (u.includes('/tickets') && init?.method === 'POST') {
+            const title = body.title;
+            if (opts.failTitles?.includes(title)) {
+                return json({ error: 'label not found' }, 400);
+            }
+            seq++;
+            return json({
+                id: `t-${seq}`, ticketKey: `ACME-${seq}`, title,
+                status: 'TODO', statusName: 'Todo', type: 'task', priority: 'normal',
+                ...(opts.dupTitles?.includes(title)
+                    ? { similarWarnings: [{ id: 'x', ticketKey: 'ACME-99', title: 'existing', similarity: 0.87, matchMode: 'embedding' }] }
+                    : {}),
+            }, 201);
+        }
+        throw new Error(`unexpected fetch ${u}`);
+    });
+    return calls;
+}
+describe('orboto_bulk_create_tickets', () => {
+    it('20 drafts -> one compact response under 2k chars, milestone resolved once', async () => {
+        const calls = stubApi();
+        const handler = makeBulkCreateTicketsHandler(client);
+        const result = await handler({
+            projectKey: 'ACME',
+            milestone: 'Sprint 1',
+            tickets: Array.from({ length: 20 }, (_, i) => ({ title: `Task number ${i + 1}` })),
+        });
+        const sc = result.structuredContent;
+        expect(sc.created).toHaveLength(20);
+        expect(sc.failed).toHaveLength(0);
+        const text = result.content[0].text;
+        expect(text.length).toBeLessThan(2000);
+        expect(JSON.stringify(result.structuredContent).length).toBeLessThan(2000);
+        // Milestone resolved once, not once per draft.
+        expect(calls.filter((c) => c.url.includes('/milestones')).length).toBe(1);
+        // Every create carried the resolved milestone id.
+        const creates = calls.filter((c) => c.method === 'POST' && c.url.includes('/tickets'));
+        expect(creates).toHaveLength(20);
+        expect(creates.every((c) => c.body.milestoneId === 'ms-1')).toBe(true);
+    });
+    it('per-draft isolation: a failed draft is reported while the rest are created; duplicates flag compactly', async () => {
+        stubApi({ failTitles: ['broken draft'], dupTitles: ['maybe dup'] });
+        const handler = makeBulkCreateTicketsHandler(client);
+        const result = await handler({
+            projectKey: 'ACME',
+            tickets: [{ title: 'good one' }, { title: 'broken draft' }, { title: 'maybe dup' }],
+        });
+        const sc = result.structuredContent;
+        expect(sc.created).toHaveLength(2);
+        expect(sc.failed).toEqual([expect.objectContaining({ index: 1, title: 'broken draft' })]);
+        expect(sc.duplicateFlags).toHaveLength(1);
+        expect(sc.duplicateFlags[0].matches[0]).toMatchObject({ ticketKey: 'ACME-99', similarity: 0.87 });
+        const text = result.content[0].text;
+        expect(text).toContain('may duplicate ACME-99');
+        expect(text).toContain('draft 1 "broken draft"');
+    });
+});
+describe('orboto_bulk_add_ticket_dependencies', () => {
+    it('resolves each key once, treats an existing edge (409) as ok, isolates per-pair failures', async () => {
+        const calls = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            const u = String(url);
+            calls.push({ method: init?.method ?? 'GET', url: u, body: init?.body ? JSON.parse(init.body) : undefined });
+            const json = (payload, status = 200) => ({
+                ok: status < 400, status, statusText: 'X',
+                json: async () => payload, text: async () => JSON.stringify(payload),
+            });
+            if (u.includes('/projects/by-key/')) {
+                return json({ id: 'proj-1', key: 'ACME', name: 'Acme' });
+            }
+            if (u.includes('/tickets/by-key/')) {
+                const num = decodeURIComponent(u.split('/tickets/by-key/')[1]);
+                if (num === '404')
+                    return json({ error: 'not found' }, 404);
+                return json({ id: `id-ACME-${num}`, ticketKey: `ACME-${num}`, projectId: 'proj-1', title: `ACME-${num}`, status: 'TODO', type: 'task', priority: 'normal' });
+            }
+            if (u.includes('/dependencies') && init?.method === 'POST') {
+                const dependsOnId = JSON.parse(init.body).dependsOnId;
+                if (dependsOnId === 'id-ACME-1')
+                    return json({ error: 'exists' }, 409);
+                return json({ ok: true }, 201);
+            }
+            throw new Error(`unexpected fetch ${u}`);
+        });
+        const handler = makeBulkAddTicketDependenciesHandler(client);
+        const result = await handler({
+            pairs: [
+                { ticketKey: 'ACME-2', dependsOnKey: 'ACME-1' }, // 409 -> ok
+                { ticketKey: 'ACME-3', dependsOnKey: 'ACME-2' }, // fresh edge
+                { ticketKey: 'ACME-404', dependsOnKey: 'ACME-1' }, // unresolvable
+            ],
+        });
+        const sc = result.structuredContent;
+        expect(sc.successful).toEqual(['ACME-2->ACME-1', 'ACME-3->ACME-2']);
+        expect(sc.failed).toHaveLength(1);
+        expect(sc.failed[0].pair).toBe('ACME-404->ACME-1');
+        // Distinct keys resolved once each (ACME-1, ACME-2, ACME-3, ACME-404).
+        expect(calls.filter((c) => c.url.includes('/tickets/by-key/')).length).toBe(4);
+        // 409 on the first edge write still counted as successful (idempotent).
+        expect(calls.filter((c) => c.method === 'POST' && c.url.includes('/dependencies')).length).toBe(2);
+    });
+});