@orboto/mcp 0.192.0 → 0.194.0

package/dist/tools/bulk-create.js

@@ -1,28 +1,12 @@
 /**
  * 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).
+ * @see 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(),
@@ -60,8 +44,6 @@ export const bulkCreateTicketsToolConfig = {
 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);
@@ -147,9 +129,6 @@ export function makeBulkCreateTicketsHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// 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.',
@@ -167,7 +146,6 @@ export const bulkAddTicketDependenciesToolConfig = {
 };
 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);
@@ -188,8 +166,6 @@ export function makeBulkAddTicketDependenciesHandler(client) {
                     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;
                 }

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

@@ -64,9 +64,7 @@ describe('orboto_bulk_create_tickets', () => {
         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);
@@ -127,9 +125,7 @@ describe('orboto_bulk_add_ticket_dependencies', () => {
         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);
     });
 });

package/dist/tools/bulk-writes.js

@@ -1,27 +1,7 @@
 /**
  * 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.
+ * @see ORB-1, ORB-2
  */
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
@@ -34,8 +14,44 @@ const CATEGORY_TO_LEGACY = {
     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.');
+const TICKET_KEY_ARRAY = z.array(z.string().min(3)).min(1).max(200).optional()
+    .describe('Ticket keys (e.g. ["ACME-1", "ACME-2"]). Capped at 200 per call to keep the per-tenant rate-limit budget reasonable. Give either ticketKeys or query.');
+/** ORB-2054 - the target set can be an OQL query instead of a key list. */
+const QUERY_SOURCE = z.string().min(1).max(8000).optional()
+    .describe('OQL query selecting the tickets instead of ticketKeys (same grammar as orboto_query, caller ACL applies). At most 200 matches per call - narrow it or use POST /projects/{id}/tickets/bulk with `query` for a server-side run.');
+const QUERY_PROJECT = z.string().optional()
+    .describe('Project key that scopes `query` (prepended as project = KEY).');
+/** Matches per call the MCP loop will process; above that the server-side bulk route is the right tool. */
+export const BULK_QUERY_MAX = 200;
+/** Resolve `query` to ticket keys through POST /query, paging until the cap. */
+export async function resolveQueryKeys(client, query, projectKey) {
+    const oql = projectKey ? `project = ${projectKey} AND (${query})` : query;
+    const keys = [];
+    let cursor;
+    for (;;) {
+        const page = await client.post('/query', {
+            oql, syntax: 'oql', limit: 100, ...(cursor ? { cursor } : {}),
+        });
+        for (const t of page.items)
+            keys.push(t.ticketKey ?? t.id);
+        if (keys.length > BULK_QUERY_MAX) {
+            throw new Error(`The query matches more than ${BULK_QUERY_MAX} tickets - narrow it, or call POST /projects/{id}/tickets/bulk with \`query\` (dryRun first) for a server-side run.`);
+        }
+        if (!page.nextCursor)
+            break;
+        cursor = page.nextCursor;
+    }
+    if (keys.length === 0)
+        throw new Error('The query matched no tickets.');
+    return keys;
+}
+/** One of ticketKeys / query, resolved to the key list the loops iterate. */
+async function targetKeys(client, input) {
+    if ((input.ticketKeys ? 1 : 0) + (input.query ? 1 : 0) !== 1) {
+        throw new Error('Give exactly one of ticketKeys or query.');
+    }
+    return input.query ? resolveQueryKeys(client, input.query, input.projectKey) : input.ticketKeys;
+}
 function emptyOutcome(dryRun) {
     return { successful: [], failed: [], skipped: [], dryRun };
 }
@@ -81,14 +97,13 @@ async function resolveBatch(client, ticketKeys, outcome) {
     }
     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.',
+    description: 'PATCH every ticket in `ticketKeys` (or the tickets `query` selects) 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,
+        query: QUERY_SOURCE,
+        projectKey: QUERY_PROJECT,
         patch: z.object({
             title: z.string().min(1).max(255).optional(),
             description: z.string().optional(),
@@ -101,15 +116,12 @@ export const bulkPatchTicketsToolConfig = {
         }).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 }) => {
+    return async ({ ticketKeys, query, projectKey, patch, dryRun }) => {
         const outcome = emptyOutcome(dryRun === true);
-        const resolved = await resolveBatch(client, ticketKeys, outcome);
+        const resolved = await resolveBatch(client, await targetKeys(client, { ticketKeys, query, projectKey }), outcome);
         for (const [k, t] of resolved) {
             if (dryRun) {
                 outcome.skipped.push(k);
@@ -126,23 +138,22 @@ export function makeBulkPatchTicketsHandler(client) {
         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.',
+    description: 'Move every ticket in `ticketKeys` (or the tickets `query` selects) 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,
+        query: QUERY_SOURCE,
+        projectKey: QUERY_PROJECT,
         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 }) => {
+    return async ({ ticketKeys, query, projectKey, statusCategory, dryRun }) => {
         const outcome = emptyOutcome(dryRun === true);
-        const resolved = await resolveBatch(client, ticketKeys, outcome);
+        const resolved = await resolveBatch(client, await targetKeys(client, { ticketKeys, query, projectKey }), outcome);
         const legacy = CATEGORY_TO_LEGACY[statusCategory];
         for (const [k, t] of resolved) {
             if (dryRun) {
@@ -160,23 +171,22 @@ export function makeBulkMoveTicketsHandler(client) {
         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.',
+    description: 'For every ticket in `ticketKeys` (or the tickets `query` selects): 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,
+        query: QUERY_SOURCE,
+        projectKey: QUERY_PROJECT,
         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 }) => {
+    return async ({ ticketKeys, query, projectKey, comment, dryRun }) => {
         const outcome = emptyOutcome(dryRun === true);
-        const resolved = await resolveBatch(client, ticketKeys, outcome);
+        const resolved = await resolveBatch(client, await targetKeys(client, { ticketKeys, query, projectKey }), outcome);
         for (const [k, t] of resolved) {
             if (dryRun) {
                 outcome.skipped.push(k);
@@ -196,14 +206,13 @@ export function makeBulkCloseTicketsHandler(client) {
         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.',
+    description: 'Append the same comment body to every ticket in `ticketKeys` (or the tickets `query` selects). 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,
+        query: QUERY_SOURCE,
+        projectKey: QUERY_PROJECT,
         text: z.string().min(1),
         isInternal: z.boolean().optional(),
         dryRun: z.boolean().optional(),
@@ -211,9 +220,9 @@ export const bulkCommentTicketsToolConfig = {
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
 export function makeBulkCommentTicketsHandler(client) {
-    return async ({ ticketKeys, text, isInternal, dryRun }) => {
+    return async ({ ticketKeys, query, projectKey, text, isInternal, dryRun }) => {
         const outcome = emptyOutcome(dryRun === true);
-        const resolved = await resolveBatch(client, ticketKeys, outcome);
+        const resolved = await resolveBatch(client, await targetKeys(client, { ticketKeys, query, projectKey }), outcome);
         for (const [k, t] of resolved) {
             if (dryRun) {
                 outcome.skipped.push(k);
@@ -233,9 +242,6 @@ export function makeBulkCommentTicketsHandler(client) {
         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. */
@@ -255,18 +261,20 @@ async function makeAssigneeResolver(client, email) {
 }
 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.',
+    description: 'POST `assigneeEmail` as an additional assignee on every ticket in `ticketKeys` (or the tickets `query` selects). 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,
+        query: QUERY_SOURCE,
+        projectKey: QUERY_PROJECT,
         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 }) => {
+    return async ({ ticketKeys, query, projectKey, assigneeEmail, dryRun }) => {
         const outcome = emptyOutcome(dryRun === true);
-        const resolved = await resolveBatch(client, ticketKeys, outcome);
+        const resolved = await resolveBatch(client, await targetKeys(client, { ticketKeys, query, projectKey }), outcome);
         const resolveAssignee = await makeAssigneeResolver(client, assigneeEmail);
         for (const [k, t] of resolved) {
             if (dryRun) {
@@ -280,7 +288,6 @@ export function makeBulkAssignTicketsHandler(client) {
                 }
                 catch (err) {
                     if (err instanceof OrbotoApiError && err.status === 409) {
-                        // Already assigned → idempotent success.
                         outcome.successful.push(k);
                         continue;
                     }
@@ -297,18 +304,20 @@ export function makeBulkAssignTicketsHandler(client) {
 }
 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.',
+    description: 'DELETE `assigneeEmail` from every ticket in `ticketKeys` (or the tickets `query` selects). Idempotent: a 404 (was not assigned) counts as success.',
     inputSchema: z.object({
         ticketKeys: TICKET_KEY_ARRAY,
+        query: QUERY_SOURCE,
+        projectKey: QUERY_PROJECT,
         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 }) => {
+    return async ({ ticketKeys, query, projectKey, assigneeEmail, dryRun }) => {
         const outcome = emptyOutcome(dryRun === true);
-        const resolved = await resolveBatch(client, ticketKeys, outcome);
+        const resolved = await resolveBatch(client, await targetKeys(client, { ticketKeys, query, projectKey }), outcome);
         const resolveAssignee = await makeAssigneeResolver(client, assigneeEmail);
         for (const [k, t] of resolved) {
             if (dryRun) {
@@ -322,7 +331,6 @@ export function makeBulkUnassignTicketsHandler(client) {
                 }
                 catch (err) {
                     if (err instanceof OrbotoApiError && err.status === 404) {
-                        // Wasn't assigned → idempotent success.
                         outcome.successful.push(k);
                         continue;
                     }

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

@@ -43,8 +43,6 @@ function ticket(n) {
         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 },
@@ -154,7 +152,6 @@ describe('orboto_bulk_close_tickets', () => {
         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 () => {
@@ -197,7 +194,6 @@ describe('orboto_bulk_assign_tickets', () => {
             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'],
@@ -237,3 +233,37 @@ describe('orboto_bulk_unassign_tickets', () => {
         });
     });
 });
+describe('query-driven bulk targets', () => {
+    it('resolves the query through POST /query (paged) and then patches each match', async () => {
+        const calls = stub([
+            { json: { items: [ticket(1)], nextCursor: 'c2' } },
+            { json: { items: [ticket(2)], nextCursor: null } },
+            ...resolveOK(1),
+            ...resolveOK(2),
+            { json: ticket(1) },
+            { json: ticket(2) },
+        ]);
+        const res = await makeBulkPatchTicketsHandler(client)({
+            query: 'status = todo AND labels = "triage"',
+            projectKey: 'ACME',
+            patch: { priority: 'high' },
+        });
+        const queryCalls = calls.filter((c) => c.url.endsWith('/query'));
+        expect(queryCalls).toHaveLength(2);
+        expect(queryCalls[0].body).toMatchObject({ oql: 'project = ACME AND (status = todo AND labels = "triage")', limit: 100 });
+        expect(queryCalls[1].body).toMatchObject({ cursor: 'c2' });
+        expect(calls.filter((c) => c.method === 'PATCH')).toHaveLength(2);
+        expect(res.structuredContent).toMatchObject({ successful: ['ACME-1', 'ACME-2'], failed: [] });
+    });
+    it('refuses both or neither source, an empty match, and more than the per-call cap', async () => {
+        await expect(makeBulkMoveTicketsHandler(client)({ ticketKeys: ['ACME-1'], query: 'x', statusCategory: 'done' }))
+            .rejects.toThrow(/exactly one/);
+        await expect(makeBulkMoveTicketsHandler(client)({ statusCategory: 'done' })).rejects.toThrow(/exactly one/);
+        stub([{ json: { items: [], nextCursor: null } }]);
+        await expect(makeBulkCloseTicketsHandler(client)({ query: 'status = todo' })).rejects.toThrow(/matched no tickets/);
+        stub([{ json: { items: Array.from({ length: 100 }, (_, i) => ticket(i + 1)), nextCursor: 'c2' } },
+            { json: { items: Array.from({ length: 100 }, (_, i) => ticket(i + 101)), nextCursor: 'c3' } },
+            { json: { items: [ticket(201)], nextCursor: null } }]);
+        await expect(makeBulkCommentTicketsHandler(client)({ query: 'status = todo', text: 'hi' })).rejects.toThrow(/more than 200/);
+    });
+});

package/dist/tools/check-similar.js

@@ -1,17 +1,5 @@
 /**
  * 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';
@@ -38,7 +26,6 @@ export function makeCheckSimilarHandler(client) {
         });
         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);
@@ -46,9 +33,6 @@ export function makeCheckSimilarHandler(client) {
         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
@@ -74,7 +58,6 @@ export function makeCheckSimilarHandler(client) {
         return {
             content: [{ type: 'text', text }],
             structuredContent: {
-                // ORB-1693 - same agent projection as create_ticket's warnings.
                 similar: trimSimilarEntries(result.candidates),
                 mode: result.mode,
                 recommendation,

package/dist/tools/checklist-writes.js

@@ -1,21 +1,33 @@
 /**
  * ORB-244 Phase C Group 3 - checklist write tools (ORB-234).
  *
- * Four tools:
- * - orboto_check / orboto_uncheck - toggle a single item's `isCompleted`
- * - orboto_add_check - append a new item to a list (default: first list
- *                       on the ticket)
- * - orboto_new_checklist - create a fresh list with optional triggers-done
- *
- * Item identifier: agents prefer 1-based indexes ("check item 3 on
- * ACME-42") because UUIDs are ergonomic disasters in a chat. The
- * helper resolves either form by reading the ticket's checklists
- * once. UUID input is honoured directly so callers that already have
- * the ID can skip the lookup.
+ * @see ORB-235
  */
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
 import { resolveTicketByKey } from './shared.js';
+const ISO_DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * ORB-235 - resolve an assignee reference (user UUID, email, or full name)
+ * to a member of the ticket's project. Names the members on a miss so the
+ * agent can pick instead of guessing.
+ */
+async function resolveMemberId(client, projectId, ref) {
+    const members = await client.get(`/projects/${projectId}/members`);
+    if (UUID_RE.test(ref) && members.some((m) => m.userId === ref))
+        return ref;
+    const needle = ref.trim().toLowerCase();
+    const hit = members.find((m) => m.user.email.toLowerCase() === needle || m.user.fullName.toLowerCase() === needle);
+    if (!hit) {
+        throw new Error(`"${ref}" is not a member of this project. Members: ${members.map((m) => `${m.user.fullName} <${m.user.email}>`).join(', ') || '(none)'}`);
+    }
+    return hit.userId;
+}
+function assertIsoDay(value) {
+    if (!ISO_DAY_RE.test(value))
+        throw new Error(`dueDate must be YYYY-MM-DD, got "${value}".`);
+    return value;
+}
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
  * Resolve an item identifier (1-based index OR UUID) to its UUID.
@@ -39,9 +51,6 @@ async function resolveItemId(client, ticketId, identifier) {
     }
     return { itemId: target.id, checklists };
 }
-// ---------------------------------------------------------------------------
-// orboto_check / orboto_uncheck
-// ---------------------------------------------------------------------------
 function makeToggleHandler(client, completed) {
     return async ({ ticketKey, item }) => {
         const ticket = await resolveTicketByKey(client, ticketKey);
@@ -83,10 +92,6 @@ export const uncheckToolConfig = {
 };
 export const makeCheckHandler = (client) => makeToggleHandler(client, true);
 export const makeUncheckHandler = (client) => makeToggleHandler(client, false);
-// ---------------------------------------------------------------------------
-// orboto_remove_check (ORB-1095) - agent parity for DELETE
-// /checklist-items/:id. The surfaces could append but not remove.
-// ---------------------------------------------------------------------------
 export const removeCheckToolConfig = {
     title: 'Remove a checklist item',
     description: 'Delete a checklist item from a ticket. `item` is either a 1-based index (global across all checklists on the ticket, top to bottom) or the item\'s UUID - same semantics as orboto_check. Destructive: the item is gone, not just unchecked.',
@@ -105,22 +110,21 @@ export function makeRemoveCheckHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_add_check
-// ---------------------------------------------------------------------------
 export const addCheckToolConfig = {
     title: 'Add a checklist item',
-    description: 'Append an item to a checklist on a ticket. By default appends to the FIRST checklist on the ticket; pass `listTitle` to target a specific one. Pass `linkedTicketKey` to make the item track another ticket\'s status (the new item\'s `effectiveCompleted` mirrors that ticket\'s done-status from then on).',
+    description: 'Append an item to a checklist on a ticket. By default appends to the FIRST checklist on the ticket; pass `listTitle` to target a specific one. Pass `linkedTicketKey` to make the item track another ticket\'s status (the new item\'s `effectiveCompleted` mirrors that ticket\'s done-status from then on). `assignee` (a project member: email, full name or user id) and `dueDate` (YYYY-MM-DD) give the item its own owner and deadline - the assignee is notified, reminded the day before, and sees the item in their upcoming deadlines.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
         content: z.string().min(1).max(2000),
         listTitle: z.string().optional().describe('Target checklist title. Default: first checklist on the ticket.'),
         linkedTicketKey: z.string().optional().describe('Make this item track another ticket\'s done-status (e.g. "ACME-99").'),
+        assignee: z.string().optional().describe('Project member to own this item - email, full name or user id.'),
+        dueDate: z.string().optional().describe('Due date of this item, YYYY-MM-DD.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
 export function makeAddCheckHandler(client) {
-    return async ({ ticketKey, content, listTitle, linkedTicketKey }) => {
+    return async ({ ticketKey, content, listTitle, linkedTicketKey, assignee, dueDate }) => {
         const ticket = await resolveTicketByKey(client, ticketKey);
         const checklists = await client.get(`/tickets/${ticket.id}/checklists`);
         if (checklists.length === 0) {
@@ -137,11 +141,15 @@ export function makeAddCheckHandler(client) {
             const linked = await resolveTicketByKey(client, linkedTicketKey);
             body.linkedTicketId = linked.id;
         }
+        if (assignee)
+            body.assignedTo = await resolveMemberId(client, ticket.projectId, assignee);
+        if (dueDate)
+            body.dueDate = assertIsoDay(dueDate);
         const item = await client.post(`/tickets/${ticket.id}/checklists/${target.id}/items`, body);
         return {
             content: [{
                     type: 'text',
-                    text: `Added to "${target.title}" on [${ticket.ticketKey}]: ${content}${linkedTicketKey ? ` ↪ [${linkedTicketKey}]` : ''}`,
+                    text: `Added to "${target.title}" on [${ticket.ticketKey}]: ${content}${linkedTicketKey ? ` ↪ [${linkedTicketKey}]` : ''}${assignee ? ` @${assignee}` : ''}${dueDate ? ` due ${dueDate}` : ''}`,
                 }],
             structuredContent: {
                 ticketKey: ticket.ticketKey,
@@ -149,13 +157,60 @@ export function makeAddCheckHandler(client) {
                 itemId: item.id,
                 content: item.content,
                 linkedTicketKey: linkedTicketKey ?? null,
+                assignedTo: body.assignedTo ?? null,
+                dueDate: body.dueDate ?? null,
+            },
+        };
+    };
+}
+export const updateCheckToolConfig = {
+    title: 'Update a checklist item',
+    description: 'Change a checklist item\'s text, assignee or due date. `item` is a 1-based index (global across all checklists on the ticket, top to bottom) or the item\'s UUID - same as orboto_check. `assignee` is a project member (email, full name or user id) or `null` to unassign; `dueDate` is YYYY-MM-DD or `null` to clear. A new assignee is notified; a new due date gets its own day-before reminder.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        item: z.union([
+            z.number().int().min(1).describe('1-based index, global across all checklists on this ticket'),
+            z.string().describe('Item UUID - for callers that already have it'),
+        ]),
+        content: z.string().min(1).max(2000).optional().describe('New item text.'),
+        assignee: z.string().nullable().optional().describe('Project member (email, full name or user id); null unassigns.'),
+        dueDate: z.string().nullable().optional().describe('YYYY-MM-DD; null clears the due date.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeUpdateCheckHandler(client) {
+    return async ({ ticketKey, item, content, assignee, dueDate }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const { itemId, checklists } = await resolveItemId(client, ticket.id, item);
+        const before = checklists.flatMap((c) => c.items).find((i) => i.id === itemId);
+        const body = {};
+        if (content !== undefined)
+            body.content = content;
+        if (assignee !== undefined)
+            body.assignedTo = assignee === null ? null : await resolveMemberId(client, ticket.projectId, assignee);
+        if (dueDate !== undefined)
+            body.dueDate = dueDate === null ? null : assertIsoDay(dueDate);
+        if (Object.keys(body).length === 0)
+            throw new Error('Nothing to update - pass content, assignee and/or dueDate.');
+        const res = await client.patch(`/checklist-items/${itemId}`, body);
+        const after = res.item;
+        const parts = [
+            after.assigneeName ? `@${after.assigneeName}` : (assignee === null ? 'unassigned' : null),
+            after.dueDate ? `due ${after.dueDate}` : (dueDate === null ? 'no due date' : null),
+        ].filter(Boolean);
+        return {
+            content: [{ type: 'text', text: `Updated on [${ticket.ticketKey}]: ${after.content ?? before?.content ?? '(item)'}${parts.length ? ` (${parts.join(', ')})` : ''}` }],
+            structuredContent: {
+                ticketKey: ticket.ticketKey,
+                itemId,
+                content: after.content ?? null,
+                assignedTo: after.assignedTo ?? null,
+                assigneeName: after.assigneeName ?? null,
+                dueDate: after.dueDate ?? null,
             },
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_new_checklist
-// ---------------------------------------------------------------------------
 export const newChecklistToolConfig = {
     title: 'Create a new checklist on a ticket',
     description: 'Create a fresh checklist on a ticket. `triggersDone=true` gates the ticket\'s auto-done transition on this list (the ticket can\'t move to done until every item here is checked). Optional `items` seed the list with content in one call - saves a round-trip per item.',