@orboto/mcp 0.192.0 → 0.194.0

package/dist/tools/ticket-attachments.js

@@ -1,22 +1,7 @@
 /**
  * ORB-1455 - read + view ticket attachments from MCP.
  *
- * Every agent surface could WRITE attachments (orboto_attach_to_ticket) but
- * none could READ them: an agent working a ticket could not tell the ticket
- * HAD files, let alone SEE an attached screenshot. These two tools close that
- * hole (orboto_get_ticket also gains an `attachments` array):
- *
- *   - orboto_list_ticket_attachments - thin wrapper on the ticket-attachment
- *     list route; mirrors orboto_list_doc_attachments (ORB-914).
- *   - orboto_get_attachment - fetch an attachment's bytes via the new
- *     authenticated base64 route and return them to the model:
- *       * images (image/*)      -> an MCP image content block so the model
- *                                  actually VIEWS the screenshot, plus a text
- *                                  line with filename/size.
- *       * everything else       -> a text block with metadata + the base64
- *                                  (small files) or a pointer to the skill
- *                                  download shortcut (large files).
- *     Works for ticket/doc/comment attachments - the id is global.
+ * @see ORB-914
  */
 import { z } from 'zod';
 import { resolveTicketByKey } from './shared.js';
@@ -27,9 +12,6 @@ const MAX_INLINE_BYTES = 5 * 1024 * 1024;
 function isImage(mimetype) {
     return mimetype.startsWith('image/');
 }
-// ---------------------------------------------------------------------------
-// orboto_list_ticket_attachments
-// ---------------------------------------------------------------------------
 export const listTicketAttachmentsToolConfig = {
     title: 'List attachments on a ticket',
     description: 'Return a ticket\'s attachments newest-first, with each attachment\'s id, filename, content type, size, and stable download URL. Use the returned id with orboto_get_attachment to actually view an image or fetch the bytes. Empty list = no attachments. Input is the ticket key like "ACME-42".',
@@ -73,9 +55,6 @@ export function makeListTicketAttachmentsHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_get_attachment
-// ---------------------------------------------------------------------------
 export const getAttachmentToolConfig = {
     title: 'View or fetch an attachment\'s bytes',
     description: 'Fetch a single attachment by its id (from orboto_list_ticket_attachments, orboto_get_ticket, or orboto_list_doc_attachments) and return its content. For an image, the model receives an image content block so it actually SEES the screenshot, plus a text line with filename and size. For a non-image, the model gets a text block with metadata and, for small files, the base64 content; large binaries point at the skill\'s download-attachment shortcut. Works for ticket, doc, and comment attachments (the id is global). Enforces the same project/space access check as listing the attachment.',
@@ -88,8 +67,6 @@ export function makeGetAttachmentHandler(client) {
     return async ({ attachmentId }) => {
         const att = await client.get(`/attachments/${attachmentId}/base64`);
         const kb = Math.round(att.sizeBytes / 1024);
-        // Over the inline cap: refuse to spill a multi-MB blob into the model's
-        // context. Point at the skill download shortcut, which streams to disk.
         if (att.sizeBytes > MAX_INLINE_BYTES) {
             return {
                 content: [{
@@ -112,7 +89,6 @@ export function makeGetAttachmentHandler(client) {
                 },
             };
         }
-        // Non-image: return metadata + the base64 so an agent can decode / save it.
         return {
             content: [{
                     type: 'text',

package/dist/tools/ticket-schedules.js

@@ -16,9 +16,6 @@ function scheduleLine(s) {
     const state = s.cancelledAt ? ' [CANCELLED]' : '';
     return `- ${s.title}${state} - ${when} - ${people} attendee(s) (id ${s.id})`;
 }
-// ---------------------------------------------------------------------------
-// orboto_list_ticket_schedules
-// ---------------------------------------------------------------------------
 export const listTicketSchedulesToolConfig = {
     title: 'List a ticket\'s scheduled working sessions',
     description: 'List the meeting / working sessions scheduled on a ticket (by key). Active sessions only by default; pass includeCancelled=true for history. Returns each session\'s id, title, window and attendee count - get the id here before cancelling one with orboto_cancel_ticket_session.',
@@ -44,9 +41,6 @@ export function makeListTicketSchedulesHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_schedule_ticket_session
-// ---------------------------------------------------------------------------
 export const scheduleTicketSessionToolConfig = {
     title: 'Schedule a working session on a ticket',
     description: 'Schedule a working session ("scope review", "design crit") on a ticket. Drops a plan-block on every orboto attendee and emails each attendee an iCal invite. startsAt/endsAt are ISO 8601 datetimes. attendeeUserIds are orboto user UUIDs (from orboto_list_users); externalEmails are non-orboto guests who get the invite but no plan-block. Title defaults to "Working session: <TICKET-KEY>".',
@@ -88,9 +82,6 @@ export function makeScheduleTicketSessionHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_cancel_ticket_session
-// ---------------------------------------------------------------------------
 export const cancelTicketSessionToolConfig = {
     title: 'Cancel a scheduled working session',
     description: 'Cancel a working session on a ticket. Removes every attendee\'s plan-block and emails an iCal cancellation to all attendees. Get the scheduleId from orboto_list_ticket_schedules.',

package/dist/tools/ticket-schedules.test.js

@@ -22,7 +22,6 @@ function stub(responses) {
             status: r.status ?? 200,
             statusText: 'OK',
             json: async () => payload,
-            // delete<T> reads text() then JSON.parses it - serialise the payload.
             text: async () => JSON.stringify(payload),
         };
     });

package/dist/tools/ticket-writes.js

@@ -1,39 +1,13 @@
 /**
  * ORB-244 Phase C Group 1 - ticket mutation tools.
  *
- * Eight tools that round-trip the API's existing PBAC cascade. Every
- * write is gated on the caller's project-level permissions; a 403
- * from the API surfaces as `isError: true` on the MCP response with
- * the API's error message intact, so the model can either retry
- * elsewhere or explain the lock to the user.
- *
- * Resolution patterns mirror Phase B:
- *   - `projectKey` (`ACME`) → UUID via `/projects/by-key/:key`
- *   - `ticketKey` (`ACME-42`) → UUID via `/projects/:id/tickets/by-key/:n`
- *   - `assigneeEmail` → userId via the project members list
- *   - `milestone` (name) → milestoneId via the project milestones list
- *
- * Tools in this file:
- *   - orboto_create_ticket
- *   - orboto_update_ticket
- *   - orboto_move_ticket
- *   - orboto_close_ticket
- *   - orboto_comment
- *   - orboto_assign
- *   - orboto_unassign
- *   - orboto_set_milestone
- *   - orboto_add_ticket_dependency       (ORB-453)
- *   - orboto_remove_ticket_dependency    (ORB-453)
- *   - orboto_list_ticket_dependencies    (ORB-453)
+ * @see ORB-453
  */
 import { z } from 'zod';
 import { trimSimilarEntries } from './similar-projection.js';
 import { OrbotoApiError } from '../orboto-client.js';
 import { resolveProjectByKey, resolveTicketByKey, resolveByName } from './shared.js';
 import { resolveMilestoneByNameOrId } from './milestones.js';
-// ---------------------------------------------------------------------------
-// Local helpers
-// ---------------------------------------------------------------------------
 const STATUS_CATEGORIES = ['todo', 'in_progress', 'in_review', 'done', 'wont_fix'];
 const CATEGORY_TO_LEGACY = {
     todo: 'TODO',
@@ -68,24 +42,14 @@ function ticketStructured(t) {
         statusCategory: t.statusCategory ?? null,
         type: t.type,
         priority: t.priority,
-        // ORB-1608 - role-aware commit policy. Absent on responses the API's
-        // enrich pipeline didn't touch; the API itself defaults unset rows to
-        // 'implementation'.
         deliveryMode: t.deliveryMode ?? 'implementation',
         dueDate: t.dueDate,
         isPrivate: t.isPrivate,
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_create_ticket
-// ---------------------------------------------------------------------------
 export const createTicketToolConfig = {
     title: 'Create a ticket',
     description: 'Create a new ticket in the given project. Creating more than ~3 tickets? Use `orboto_bulk_create_tickets` instead - one call, one compact response. Returns the new ticket\'s key (e.g. "ACME-42") so callers can chain follow-ups. **Read the new key from `structuredContent.createdTicketKey` (ORB-1176) - never from `similarWarnings[].ticketKey`, which are OTHER, possibly-duplicate tickets.** The caller must have `ticket:create` on the project. **Duplicate-detection safety-net (ORB-831):** if `similarWarnings` appears in the response with one or more entries, the ticket WAS created but you should review whether to close it as a duplicate of the listed ticket(s) instead. The warnings are advisory - never blocking - but each entry is a ticket the system thinks the new one overlaps with. Prefer `orboto_check_similar` BEFORE creating when you want a dry-run. **Deferred check under load (ORB-1437):** if `duplicateCheckDeferred: true` appears, the project was under a create burst so the duplicate-check was run in the background instead of inline - `similarWarnings` is then empty because it did NOT run synchronously, which is NOT the same as "no duplicates found". A strong match, if any, is posted as an advisory comment on the new ticket a moment later; check the ticket comments before treating it as new work. **Duplicate-check recall (ORB-1121):** when you search/check-similar first, results rank by term co-occurrence - a long, solution-framed title with rare terms can return 0 hits even when a short, symptom-framed dup sharing one distinctive token exists. Probe with a single distinctive STABLE token (file/component/error-string fragment), keep queries SHORT, and search the SYMPTOM not your fix; a 0-result long query is not "no dup". **Language-mismatch warning (ORB-890):** if `languageWarning` appears, the ticket was written in a language different from the workspace default. Consider rewriting in the expected language so search + duplicate-detection stay consistent. Non-blocking. **Before a mass-create (ORB-989):** call `orboto_whoami` first - its `workspaceLocale` field is the language you should write every ticket in. If the same `languageWarning` repeats, stop and clarify the intended language rather than pushing through the whole batch. **Strict mode (ORB-990):** if the workspace enforces ticket language, a mismatch is rejected (the tool returns a `blocked` result, not a created ticket) - rewrite in the workspace language, or set `allowLanguageMismatch: true` only when the language is genuinely intentional. **Hard duplicate-block (ORB-1471):** some workspaces REFUSE a create whose top similarity match is at/above a configured threshold - the tool returns a `duplicateBlocked` result (NOT a created ticket) listing the matching tickets. Extend or comment on one of those instead. If you have confirmed none of them cover this work, retry with `allowDuplicate: true` AND a `duplicateJustification` explaining why - the justification is persisted as a comment on the new ticket. '
-        // ORB-1805 - parameter prose moved out of the input schema (which
-        // every client pays for on connect) into this text, which the
-        // manifest summarises to one sentence and orboto_help serves in
-        // full. Same rows also live in the skill's REFERENCE.md.
         + '**Parameter notes.** `deliveryMode` (ORB-1608) is the role-aware commit policy that replaced the blanket one-commit-per-ticket rule: implementation/docs expect exactly one linked commit (closing without one is a non-blocking warning); review/admin/epic never expect one - reviews are read-only, admin work carries external evidence, epics derive completion from their children; unset defaults to "epic" when type=epic, else "implementation". `milestone` takes a key ("ORB-M3"), a name, or a UUID and is looked up in the project including closed milestones - unknown or ambiguous is an error, so pass the key/UUID when a name repeats. `labels` and `assigneeEmails` attach ATOMICALLY inside the create (ORB-1416): an unknown label or non-member email rolls the whole create back with a 400, leaving no orphan ticket - there is no separate attach call to retry.',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
@@ -115,12 +79,8 @@ export function makeCreateTicketHandler(client) {
             type: input.type ?? 'task',
             priority: input.priority ?? 'normal',
             isPrivate: input.isPrivate ?? false,
-            // ORB-1608 - leave unset when the caller didn't pass one; the API
-            // defaults it (epic for type=epic, else implementation).
             ...(input.deliveryMode ? { deliveryMode: input.deliveryMode } : {}),
         };
-        // ORB-1471 - the override justification rides in the body; the override
-        // flag itself is a querystring param (see createPath below).
         if (input.allowDuplicate && input.duplicateJustification)
             body.duplicateJustification = input.duplicateJustification;
         if (input.dueDate)
@@ -131,18 +91,10 @@ export function makeCreateTicketHandler(client) {
             const parent = await resolveTicketByKey(client, input.parentTicketKey);
             body.parentTicketId = parent.id;
         }
-        // ORB-1416 - labels + assignees attach INLINE in the create
-        // transaction so the whole thing is atomic (one round-trip). No more
-        // post-create attach loops: a bad label/assignee reference now rolls
-        // the create back on the API side (clean 400, no orphan ticket) rather
-        // than leaving a half-created ticket the agent retries into a dup.
         if (input.labels && input.labels.length > 0)
             body.labelNames = input.labels;
         if (input.assigneeEmails && input.assigneeEmails.length > 0)
             body.assigneeEmails = input.assigneeEmails;
-        // ORB-990 - strict ticket-language enforcement may reject this with a
-        // 422; ORB-1471 - the hard duplicate-block may reject it with a 409.
-        // Surface each as a clear block result instead of a raw error.
         const qs = [];
         if (input.allowLanguageMismatch)
             qs.push('allowLanguageMismatch=true');
@@ -162,21 +114,11 @@ export function makeCreateTicketHandler(client) {
                 return blocked;
             throw err;
         }
-        // ORB-831 / ORB-887 - surface the backend's `similarWarnings` to the
-        // calling agent. The text block prepends a clearly-visible warning
-        // when matches exist so a model scanning the result for "warning"
-        // / "duplicate" notices and self-corrects.
-        // ORB-890 / ORB-891 - same surface for `languageWarning` when the
-        // detected language doesn't match the workspace default.
         const warnings = created.similarWarnings ?? [];
         const langWarning = created.languageWarning;
         const deferred = created.duplicateCheckDeferred === true;
         const baseText = ticketSummaryText('Created', created);
         const parts = [baseText];
-        // ORB-1437 - under a create burst the backend defers the duplicate-check
-        // to a background job (empty similarWarnings, duplicateCheckDeferred:true).
-        // Tell the agent so an empty warnings list isn't read as "no duplicates":
-        // a strong match will land as an advisory comment on the new ticket shortly.
         if (deferred) {
             parts.push(`\nℹ Duplicate-check deferred - the project is under high create load, so the check runs in the background. `
                 + `An empty duplicate list here does NOT mean "no duplicates". If a strong match is found, an advisory comment `
@@ -193,14 +135,7 @@ export function makeCreateTicketHandler(client) {
             content: [{ type: 'text', text }],
             structuredContent: {
                 ...ticketStructured(created),
-                // ORB-1176 - the one unambiguous field for the NEW ticket's key.
-                // `similarWarnings[].ticketKey` are OTHER tickets; read
-                // `createdTicketKey` (never a warning's key) to avoid grabbing the
-                // wrong one.
                 createdTicketKey: created.ticketKey,
-                // ORB-1693 - agent projection: key/title/category/2dp-similarity/
-                // relation only. The rich shape (UUID, colours, statusName, 15dp)
-                // stays on the REST response for the web UI.
                 similarWarnings: trimSimilarEntries(warnings),
                 ...(deferred ? { duplicateCheckDeferred: true } : {}),
                 ...(langWarning ? { languageWarning: langWarning } : {}),
@@ -277,8 +212,6 @@ function duplicateBlockResult(err) {
         parsed = JSON.parse(err.body);
     }
     catch { /* non-JSON body */ }
-    // Only OUR duplicate-block 409 carries similarWarnings; a different 409
-    // (none currently on this route) should bubble as a normal error.
     if (!parsed.similarWarnings)
         return null;
     const candidates = parsed.similarWarnings;
@@ -301,9 +234,6 @@ function formatSimilarity(w) {
     const pct = `${Math.round(w.similarity * 100)}% ${w.matchMode === 'embedding' ? 'AI match' : 'text match'}`;
     return w.statusName ? `${w.statusName}, ${pct}` : pct;
 }
-// ---------------------------------------------------------------------------
-// orboto_update_ticket
-// ---------------------------------------------------------------------------
 export const updateTicketToolConfig = {
     title: 'Update a ticket',
     description: 'Patch one or more fields on a ticket. Patchable: title, description, customerSummary, type, priority, deliveryMode, dueDate, startDate, isPrivate, estimatedTimeMinutes. `customerSummary` is the customer-facing text shown in the customer project report instead of the internal description; null or empty falls back to an AI distillation or the title. `deliveryMode` is the role-aware commit policy (ORB-1608) - see `orboto_create_ticket` for the mode semantics. Use `orboto_move_ticket` for status, `orboto_set_milestone` for milestone, and `orboto_assign` / `orboto_unassign` for members.',
@@ -328,8 +258,6 @@ export const updateTicketToolConfig = {
 export function makeUpdateTicketHandler(client) {
     return async ({ ticketKey, patch, allowLanguageMismatch }) => {
         const ticket = await resolveTicketByKey(client, ticketKey);
-        // ORB-990 - strict ticket-language enforcement may reject a
-        // title/description patch with a 422; surface a clear block result.
         const patchPath = `/projects/${ticket.projectId}/tickets/${ticket.id}${allowLanguageMismatch ? '?allowLanguageMismatch=true' : ''}`;
         let updated;
         try {
@@ -355,9 +283,6 @@ export function makeUpdateTicketHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_move_ticket
-// ---------------------------------------------------------------------------
 export const moveTicketToolConfig = {
     title: 'Move a ticket between status categories',
     description: 'Move a ticket to a new status category - todo / in_progress / in_review / done / wont_fix. The API picks the project\'s first status with that category. Caller must have `ticket:change_status`. **Summary warning (ORB-1332):** moving to `in_review` or `done` without having just posted a summary comment returns a non-blocking `summaryWarning` - the move still succeeds, but you should post what changed, the commit SHA, and how to verify. Use `orboto_close_ticket` with a `comment` (or comment first, then move) to avoid it. **Delivery-mode warning (ORB-1608/1642):** moving to `done` on an `implementation`/`docs` ticket with zero linked commits returns a non-blocking `deliveryModeWarning` - UNLESS the project has no git connection at all, in which case it\'s omitted (a link isn\'t possible there). Code `no_commit_linked` means the connection looks healthy - link a commit, or change deliveryMode via `orboto_update_ticket` if the work genuinely is not commit-shaped. Code `git_delivery_failing` means the connection itself looks unhealthy - a commit may already exist and just hasn\'t arrived; check the connection before assuming none was made.',
@@ -377,9 +302,6 @@ export function makeMoveTicketHandler(client) {
         }, updated.summaryWarning), updated.deliveryModeWarning);
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_close_ticket
-// ---------------------------------------------------------------------------
 export const closeTicketToolConfig = {
     title: 'Close a ticket',
     description: 'Move a ticket to `done` and optionally post a closing comment in one call. Closing more than ~3 tickets? Use `orboto_bulk_close_tickets` instead. Convenience wrapper around `orboto_move_ticket` + `orboto_comment` so the model doesn\'t need to chain two writes. Passing a `comment` is the recommended way to close - it doubles as the transition summary and suppresses the ORB-1332 `summaryWarning`. Closing with no comment (and none posted in the last few minutes) returns a non-blocking `summaryWarning`; the close still succeeds. **Delivery-mode warning (ORB-1608/1642):** on an `implementation`/`docs` ticket, closing with zero linked commits returns a non-blocking `deliveryModeWarning` too - UNLESS the project has no git connection at all, in which case it\'s omitted. `no_commit_linked` = healthy connection, link a commit or change deliveryMode via `orboto_update_ticket`. `git_delivery_failing` = the connection itself looks unhealthy - check it before assuming no commit was made.',
@@ -393,9 +315,6 @@ export function makeCloseTicketHandler(client) {
     return async ({ ticketKey, comment }) => {
         const ticket = await resolveTicketByKey(client, ticketKey);
         if (comment) {
-            // Comment first so the close-comment lands in the audit trail
-            // even if the status move 403s. Mirrors the wrapper's `close`
-            // behaviour.
             await client.post(`/tickets/${ticket.id}/comments`, { content: comment });
         }
         const updated = await client.patch(`/projects/${ticket.projectId}/tickets/${ticket.id}`, { status: 'DONE' });
@@ -405,9 +324,6 @@ export function makeCloseTicketHandler(client) {
         }, updated.summaryWarning), updated.deliveryModeWarning);
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_delete_ticket
-// ---------------------------------------------------------------------------
 export const deleteTicketToolConfig = {
     title: 'Permanently delete a ticket',
     description: 'DESTRUCTIVE, IRREVERSIBLE hard-delete of a ticket (by key): the row and its history are gone, and a `ticket.deleted` event + webhook fire. Strongly prefer moving the ticket to `wont_fix` (orboto_move_ticket) or closing it instead - wont_fix keeps the history and analytics intact. Only hard-delete a ticket that should truly never have existed (accidental duplicate, spam). Caller must have `ticket:delete`.',
@@ -456,9 +372,6 @@ export function makeCommentHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_update_comment  (ORB-1285)
-// ---------------------------------------------------------------------------
 export const updateCommentToolConfig = {
     title: 'Edit a ticket comment',
     description: 'Edit the text of a comment you authored (super-admins can edit any). Markdown. The prior text is snapshotted into the comment\'s revision history. Pass the commentId - from orboto_comment\'s response or orboto_get_ticket.',
@@ -479,9 +392,6 @@ export function makeUpdateCommentHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_delete_comment  (ORB-1285)
-// ---------------------------------------------------------------------------
 export const deleteCommentToolConfig = {
     title: 'Delete a ticket comment',
     description: 'Delete a comment. You can always delete your own; deleting another user\'s comment needs the `comment:delete_others` permission in the project (super-admins always can). Pass the commentId - from orboto_comment\'s response or orboto_get_ticket.',
@@ -501,9 +411,6 @@ export function makeDeleteCommentHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_assign / orboto_unassign
-// ---------------------------------------------------------------------------
 export const assignToolConfig = {
     title: 'Assign a user to a ticket',
     description: 'Add a project member as an assignee on a ticket. Multi-assignee is supported - this adds, it does not replace. Use `orboto_unassign` to remove.',
@@ -522,7 +429,6 @@ export function makeAssignHandler(client) {
         }
         catch (err) {
             if (err instanceof OrbotoApiError && err.status === 409) {
-                // Already assigned - idempotent success.
                 return {
                     content: [{ type: 'text', text: `[${ticket.ticketKey}] already assigned to ${assigneeEmail}.` }],
                     structuredContent: { ticketKey: ticket.ticketKey, alreadyAssigned: true },
@@ -553,7 +459,6 @@ export function makeUnassignHandler(client) {
             await client.delete(`/projects/${ticket.projectId}/tickets/${ticket.id}/assignees/${userId}`);
         }
         catch (err) {
-            // 404 = wasn't assigned. Idempotent success.
             if (err instanceof OrbotoApiError && err.status === 404) {
                 return {
                     content: [{ type: 'text', text: `${assigneeEmail} wasn't assigned to [${ticket.ticketKey}].` }],
@@ -568,17 +473,8 @@ export function makeUnassignHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_label_ticket / orboto_unlabel_ticket - ORB-1043
-// ---------------------------------------------------------------------------
 async function resolveLabelId(client, projectId, name) {
     const labels = await client.get(`/projects/${projectId}/labels`);
-    // ORB-1826 - exact match wins first, then a unique normalised match
-    // (HTML-entity-decoded, trimmed, whitespace-collapsed, casefolded) so
-    // case/whitespace/entity variants of an existing label name resolve
-    // instead of rejecting. Labels have no unique-name constraint, so an
-    // ambiguous normalised match (two labels differing only by case) still
-    // errors rather than silently picking one.
     const { match, ambiguous } = resolveByName(labels, name, (l) => l.name);
     if (ambiguous) {
         const list = ambiguous.map((l) => `"${l.name}" (${l.id})`).join(', ');
@@ -629,9 +525,6 @@ export function makeUnlabelTicketHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_set_milestone
-// ---------------------------------------------------------------------------
 export const setMilestoneToolConfig = {
     title: 'Set a ticket\'s milestone',
     description: 'Move a ticket onto a different milestone (or off all milestones with milestone=null/undefined). Resolves the milestone by key (e.g. "ORB-M3"), name, OR UUID within the ticket\'s project (including closed/archived). If two milestones share a name, pass the key or UUID - an ambiguous name is rejected, not silently guessed.',
@@ -677,7 +570,6 @@ export function makeAddTicketDependencyHandler(client) {
             await client.post(`/projects/${ticket.projectId}/tickets/${ticket.id}/dependencies`, { dependsOnId: dependsOn.id });
         }
         catch (err) {
-            // 409 = edge already exists - idempotent success.
             if (err instanceof OrbotoApiError && err.status === 409) {
                 return {
                     content: [{ type: 'text', text: `[${ticket.ticketKey}] already depends on [${dependsOn.ticketKey}].` }],
@@ -715,7 +607,6 @@ export function makeRemoveTicketDependencyHandler(client) {
             await client.delete(`/projects/${ticket.projectId}/tickets/${ticket.id}/dependencies/${dependsOn.id}`);
         }
         catch (err) {
-            // 404 = edge wasn't there. Idempotent success.
             if (err instanceof OrbotoApiError && err.status === 404) {
                 return {
                     content: [{ type: 'text', text: `[${ticket.ticketKey}] didn't depend on [${dependsOn.ticketKey}].` }],

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

@@ -63,9 +63,6 @@ describe('orboto_create_ticket', () => {
             projectKey: 'ACME', title: 'Labelled', labels: ['bug', 'ui'],
             assigneeEmails: ['dev@example.com'],
         });
-        // Exactly one POST - the atomic create - carrying labels + assignees
-        // in its body. No follow-up /labels/ or /assignees/ round-trips, so a
-        // bad reference can't leave an orphan ticket the agent retries into a dup.
         const posts = calls.filter((c) => c.method === 'POST');
         expect(posts).toHaveLength(1);
         expect(posts[0].url).toBe('https://orboto.example.com/projects/p1/tickets');
@@ -121,12 +118,8 @@ describe('orboto_create_ticket', () => {
         expect(text).toContain('ACME-13');
         const sc = res.structuredContent;
         expect(sc.similarWarnings).toHaveLength(2);
-        // ORB-1176 - createdTicketKey is the NEW key, never a warning's key.
         expect(sc.createdTicketKey).toBe('ACME-99');
         expect(sc.similarWarnings.map((w) => w.ticketKey)).not.toContain(sc.createdTicketKey);
-        // ORB-1693 - the agent projection is pinned: exactly these fields, no
-        // UUID, no colours, no statusName, similarity at 2dp. A re-grow of the
-        // rich shape is a regression, not an enhancement.
         for (const w of sc.similarWarnings) {
             expect(Object.keys(w).sort()).toEqual(['relation', 'similarity', 'statusCategory', 'ticketKey', 'title']);
         }
@@ -204,13 +197,12 @@ describe('orboto_create_ticket', () => {
             if (m === 'GET') {
                 return { ok: true, status: 200, statusText: 'OK', json: async () => PROJ, text: async () => '' };
             }
-            createUrl = u; // the POST /tickets call
+            createUrl = u;
             return { ok: false, status: 422, statusText: 'Unprocessable', json: async () => ({}), text: async () => blockBody };
         });
         const res = await makeCreateTicketHandler(client)({
             projectKey: 'ACME', title: 'Authentifizierung schlägt fehl bei externen Nutzern',
         });
-        // No override flag → no query param on the create call.
         expect(createUrl).not.toContain('allowLanguageMismatch');
         expect(res.isError).toBe(true);
         const text = res.content[0].text;
@@ -236,8 +228,6 @@ describe('orboto_create_ticket', () => {
         });
         expect(createUrl).toContain('allowLanguageMismatch=true');
     });
-    // ORB-1471 - hard duplicate-block 409 becomes a clear duplicateBlocked
-    // result that surfaces the candidate list verbatim + the override recipe.
     it('turns a hard duplicate-block 409 into a duplicateBlocked result listing the candidates (ORB-1471)', async () => {
         const blockBody = JSON.stringify({
             error: 'This ticket looks like a duplicate (98% match to an existing ticket).',
@@ -595,10 +585,6 @@ describe('orboto_add_ticket_dependency / remove / list - ORB-453', () => {
         expect(text).toContain('Blocks');
         expect(text).toContain('_(none)_');
     });
-    // ORB-1614 - a cross-project blocker the caller cannot read comes back
-    // as an opaque stub (title/ticketKey/projectId/status all null). The
-    // rendered text must never print the literal "null" and must not need
-    // any of those fields to say something useful.
     it('list renders an opaque placeholder for an unreadable cross-project stub, never "null"', async () => {
         stub([
             { json: PROJ }, { json: TICKET },

package/dist/tools/time-writes.js

@@ -1,27 +1,9 @@
 /**
  * ORB-244 Phase C Group 2 - time-tracking tools.
- *
- * Three tools that wrap the existing /time/timer/* + /tickets/:id/time-entries
- * endpoints:
- *   - orboto_timer_start (ticketKey, description?, replace?)
- * - orboto_timer_stop - closes the running timer; the API converts
- *                         elapsed time into a time_entries row using the
- *                         description set at start.
- * - orboto_log_time - direct time-entry POST for after-the-fact
- *                         logging (no running timer involved).
- *
- * Note: the wrapper's `timer-stop "note"` syntax sends a `note` field
- * the API silently ignores - the time entry's description is whatever
- * was set on `start`. To attach a note to a stopped session, post a
- * comment afterwards via `orboto_comment`. The MCP tool only accepts
- * what the API actually accepts.
  */
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
 import { resolveTicketByKey } from './shared.js';
-// ---------------------------------------------------------------------------
-// orboto_timer_start
-// ---------------------------------------------------------------------------
 export const timerStartToolConfig = {
     title: 'Start a timer on a ticket',
     description: 'Start the user\'s stopwatch on a ticket. If a timer is already running on a different ticket, pass replace=true to auto-stop the previous one (its elapsed time is committed to time_entries before the new timer begins). Description becomes the time entry\'s note when this timer eventually stops.',
@@ -55,9 +37,6 @@ export function makeTimerStartHandler(client) {
             };
         }
         catch (err) {
-            // 409 = a timer is already running on a different ticket.
-            // Surface the API's hint about `replace` rather than letting
-            // the model guess.
             if (err instanceof OrbotoApiError && err.status === 409) {
                 throw new Error('A timer is already running on a different ticket. Pass replace=true to commit its elapsed time and start fresh on this one.');
             }
@@ -65,9 +44,6 @@ export function makeTimerStartHandler(client) {
         }
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_timer_stop
-// ---------------------------------------------------------------------------
 export const timerStopToolConfig = {
     title: 'Stop the running timer',
     description: 'Stop the user\'s stopwatch. The API commits a time_entries row using the description set at start (or pause/resume), then deletes the active-timer record. Returns the duration in minutes.',
@@ -77,10 +53,6 @@ export const timerStopToolConfig = {
 export function makeTimerStopHandler(client) {
     return async () => {
         try {
-            // ORB-1603 - the API stop is idempotent now: nothing-to-stop returns
-            // 200 { stopped:false } instead of a 404 (the 404 branch below stays
-            // for older servers), and laneFallback flags that the timer was found
-            // via the single-active-timer fallback after an instance-token mismatch.
             const res = await client.post('/time/timer/stop', {});
             if (res.stopped === false) {
                 return {
@@ -107,23 +79,43 @@ export function makeTimerStopHandler(client) {
         }
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_log_time
-// ---------------------------------------------------------------------------
 export const logTimeToolConfig = {
     title: 'Log a time entry on a ticket',
-    description: 'Direct time-entry POST - for "I just spent 90 minutes on this last Tuesday but forgot to start a timer". `loggedAt` defaults to now; pass an ISO datetime to back-date.',
+    description: 'Direct time-entry POST - for "I just spent 90 minutes on this last Tuesday but forgot to start a timer". `loggedAt` defaults to now; pass an ISO datetime to back-date. Pass `dates` (YYYY-MM-DD list) to book the same entry on several days in one call (ORB-2056): all-or-nothing, a day inside an approved timesheet refuses the set and names the day, capacity warnings come back advisory.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
         durationMinutes: z.number().int().positive().describe('Minutes, > 0.'),
         description: z.string().optional(),
-        loggedAt: z.string().datetime().optional().describe('ISO 8601. Default: now.'),
+        loggedAt: z.string().datetime().optional().describe('ISO 8601. Default: now. Ignored when `dates` is set.'),
+        dates: z.array(z.string().regex(/^\d{4}-\d{2}-\d{2}$/)).min(1).max(200).optional().describe('Book this entry on each of these days (YYYY-MM-DD).'),
+        time: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/).optional().describe('Wall-clock start for `dates`, workspace timezone. Default 09:00.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
 export function makeLogTimeHandler(client) {
-    return async ({ ticketKey, durationMinutes, description, loggedAt }) => {
+    return async ({ ticketKey, durationMinutes, description, loggedAt, dates, time }) => {
         const ticket = await resolveTicketByKey(client, ticketKey);
+        if (dates && dates.length > 0) {
+            const template = { ticketId: ticket.id, durationMinutes };
+            if (description !== undefined)
+                template.description = description;
+            if (time)
+                template.time = time;
+            const booked = await client.post('/time-entries/bulk', { template, dates });
+            const warn = booked.warnings.length ? ` - ${booked.warnings.length} capacity warning(s): ${booked.warnings.map((w) => `${w.date} ${w.kind}`).join(', ')}` : '';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Logged ${durationMinutes} min on [${ticket.ticketKey}] on ${booked.entries.length} day(s) (${booked.totalMinutes} min total)${warn}`,
+                    }],
+                structuredContent: {
+                    ticketKey: ticket.ticketKey,
+                    entries: booked.entries.map((e) => ({ entryId: e.id, loggedAt: e.loggedAt, durationMinutes: e.durationMinutes })),
+                    totalMinutes: booked.totalMinutes,
+                    warnings: booked.warnings,
+                },
+            };
+        }
         const body = { durationMinutes };
         if (description !== undefined)
             body.description = description;
@@ -145,9 +137,6 @@ export function makeLogTimeHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_list_time_entries  (ORB-1292)
-// ---------------------------------------------------------------------------
 export const listTimeEntriesToolConfig = {
     title: 'List a ticket\'s time entries',
     description: 'List the time entries on a ticket (most recent first) with each entry\'s id, duration, date and agent label. Use this to FIND an over-tracked entry before fixing it with orboto_edit_time_entry / orboto_delete_time_entry.',
@@ -162,9 +151,6 @@ export function makeListTimeEntriesHandler(client) {
         const ticket = await resolveTicketByKey(client, ticketKey);
         const page = await client.get(`/tickets/${ticket.id}/time-entries?limit=${limit ?? 25}`);
         const lines = page.items.map((e) => {
-            // ORB-1368 - agentLabel already flags a known agent instance; add a
-            // bare [agent] marker for agent work with no instance label (a bot's
-            // NULL-lane entry).
             const agentMark = e.agentLabel ? ` [${e.agentLabel}]` : (e.isAgentWork ? ' [agent]' : '');
             return `- ${e.durationMinutes} min - ${e.loggedAt}${agentMark}${e.description ? ` - ${e.description}` : ''} (id ${e.id})`;
         });
@@ -177,9 +163,6 @@ export function makeListTimeEntriesHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_edit_time_entry  (ORB-1292)
-// ---------------------------------------------------------------------------
 export const editTimeEntryToolConfig = {
     title: 'Edit / correct a time entry',
     description: 'Correct a time entry - fix an over-tracked duration, edit its note, change its date, or re-target it to another ticket. Use THIS (not orboto_log_time) to fix a wrong entry: log_time is additive and only makes the total worse. Get the entryId from orboto_list_time_entries (or an orboto_log_time response). Blocked if the entry is locked by an approved timesheet.',
@@ -214,9 +197,6 @@ export function makeEditTimeEntryHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_delete_time_entry  (ORB-1292)
-// ---------------------------------------------------------------------------
 export const deleteTimeEntryToolConfig = {
     title: 'Delete a time entry',
     description: 'Delete a time entry - e.g. a bogus over-tracked entry that should not exist at all (prefer orboto_edit_time_entry when it should just have a different duration). You can delete your own; deleting another user\'s needs the `time:delete_others` permission. Blocked if locked by an approved timesheet. Get the entryId from orboto_list_time_entries.',

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

@@ -101,6 +101,24 @@ describe('orboto_log_time', () => {
         expect(calls[2].body).toEqual({ durationMinutes: 30, loggedAt: '2026-04-20T10:00:00Z' });
     });
 });
+describe('orboto_log_time with dates (ORB-2056)', () => {
+    it('books through POST /time-entries/bulk with a template and reports the total', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: { entries: [{ id: 'e1', ticketId: 't1', userId: 'u1', durationMinutes: 120, description: 'sprint', loggedAt: '2026-06-01T07:00:00.000Z' }, { id: 'e2', ticketId: 't1', userId: 'u1', durationMinutes: 120, description: 'sprint', loggedAt: '2026-06-02T07:00:00.000Z' }], warnings: [{ kind: 'non_working_day', date: '2026-06-06', message: 'x' }], lockedDates: [], dryRun: false, totalMinutes: 240 } },
+        ]);
+        const out = await makeLogTimeHandler(client)({
+            ticketKey: 'ACME-1', durationMinutes: 120, description: 'sprint', dates: ['2026-06-01', '2026-06-02'], time: '09:00', loggedAt: '2026-01-01T00:00:00Z',
+        });
+        expect(calls[2].method).toBe('POST');
+        expect(calls[2].url).toContain('/time-entries/bulk');
+        expect(calls[2].body).toEqual({ template: { ticketId: 't1', durationMinutes: 120, description: 'sprint', time: '09:00' }, dates: ['2026-06-01', '2026-06-02'] });
+        expect(out.structuredContent.totalMinutes).toBe(240);
+        expect(out.content[0].text).toContain('2 day(s)');
+        expect(out.content[0].text).toContain('capacity warning');
+    });
+});
 describe('orboto_list_time_entries / edit / delete (ORB-1292)', () => {
     it('list GETs the ticket time entries and returns them structured', async () => {
         const calls = stub([