@orboto/mcp 0.178.0

package/dist/tools/claim.js

@@ -0,0 +1,236 @@
+/**
+ * ORB-799 - composite ticket-lifecycle tools.
+ *
+ * Two tools that bundle the most-used wrapper composites:
+ *
+ *   - orboto_claim   ≈ assign_self + move(in_progress) + timer_start
+ *   - orboto_unclaim ≈ unassign_self + move(todo)
+ *
+ * The composite-atomic behaviour is the real value here - these are
+ * the most-typed wrapper commands by agents during ticket pickup. The
+ * 1:1 mirror of `orboto.mjs claim` semantics matters:
+ *
+ *   - `--sole` (`sole=true`) - destructive take-over: remove every
+ *     other assignee before adding self. Use sparingly; the API has
+ *     no atomic swap so this is a delete-loop + add.
+ *   - `--force` (`force=true`) - allow re-claiming a `done` ticket
+ *     (the wrapper refuses without it to prevent accidental reopen).
+ *   - `--no-timer` (`noTimer=true`) - skip the timer_start side
+ *     effect. Useful when the agent only wants ownership-by-assignee
+ *     without committing time.
+ *
+ * Both tools are **idempotent** on the happy paths:
+ *   - claim of a ticket where the caller is already an assignee and
+ *     statusCategory is already `in_progress` → no PATCH, no extra
+ *     assignee POST (the wrapper still POSTs once and 409s; we skip).
+ *   - unclaim of a ticket where the caller isn't an assignee → 404 on
+ *     DELETE is swallowed, status move still happens.
+ *
+ * Timer side-effects mirror ORB-179 (`claim`) + ORB-181 (`close`):
+ *   - If a different ticket has an active timer, stop it first
+ *     (commits the elapsed time-entry under the previous ticket's
+ *     description), then start a fresh timer on this one.
+ *   - Timer failures never roll back the assign/status work - we
+ *     surface them as a `timerWarning` field on the structured
+ *     response, same shape as the wrapper.
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+import { mcpInstanceToken, resolveTicketByKey } from './shared.js';
+// `statusCategory` is the discriminator the API exposes on every
+// ticket-read response; we map it (rather than `status` legacy enum)
+// because that's what the wrapper inspects too.
+const CATEGORY_TO_LEGACY = {
+    todo: 'TODO',
+    in_progress: 'IN_PROGRESS',
+    in_review: 'IN_REVIEW',
+    done: 'DONE',
+    wont_fix: 'WONT_FIX',
+};
+// ---------------------------------------------------------------------------
+// orboto_claim
+// ---------------------------------------------------------------------------
+export const claimToolConfig = {
+    title: 'Claim a ticket (assign self + in_progress + timer)',
+    description: 'Composite of `assign self → move to in_progress → start timer` - the canonical "I am picking this up now" move. Idempotent: re-claiming an already-claimed in_progress ticket is a no-op. Set `sole=true` to remove every other assignee first (destructive take-over). Set `force=true` to allow re-claiming a `done` ticket (otherwise refuses, to prevent accidental reopens). Set `noTimer=true` to skip the timer start (e.g. when you only want ownership, not time tracking). If a different ticket has an active timer, it is stopped first (its elapsed time commits a time entry under the previous ticket). '
+        // ORB-1805 - moved out of the input schema, which every client pays
+        // for at connect; orboto_help serves this text in full.
+        + '`agentSessionToken` is a stable per-agent-instance token: on a bot/service account it scopes the timer to YOUR instance - concurrent per-instance timers and NO auto-stop, so you own both start and stop. Omit it on human accounts, which keep the single-timer behaviour.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        sole: z.boolean().optional().describe('Take-over: remove every other assignee first.'),
+        force: z.boolean().optional().describe('Allow re-claiming a `done` ticket.'),
+        noTimer: z.boolean().optional().describe('Skip the timer start.'),
+        agentSessionToken: z.string().optional().describe('Per-agent-instance token; scopes the timer on bot accounts.'),
+    }).shape,
+    // ORB-1669 - destructive because of `sole=true`, which strips every
+    // other assignee. Annotations are per-tool and cannot be conditioned on
+    // an argument, so the hint has to cover the worst call the tool allows.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeClaimHandler(client) {
+    return async ({ ticketKey, sole, force, noTimer, agentSessionToken }, extra) => {
+        const me = await client.get('/users/me');
+        const current = await resolveTicketByKey(client, ticketKey);
+        const currentAssignees = current.assignees ?? [];
+        const alreadyAssigned = currentAssignees.some((a) => a.id === me.id);
+        const currentCategory = current.statusCategory;
+        if (currentCategory === 'done' && !force) {
+            throw new Error(`Refusing to claim [${current.ticketKey}]: status is "done". Pass force=true to reopen + claim.`);
+        }
+        // --sole: destructive take-over. Remove every other assignee
+        // first. Each DELETE tolerates a 404 (race condition where another
+        // process already unassigned them).
+        if (sole) {
+            for (const a of currentAssignees) {
+                if (a.id === me.id)
+                    continue;
+                try {
+                    await client.delete(`/projects/${current.projectId}/tickets/${current.id}/assignees/${a.id}`);
+                }
+                catch (err) {
+                    if (!(err instanceof OrbotoApiError) || err.status !== 404)
+                        throw err;
+                }
+            }
+        }
+        // Additive self-add. Skip if we're already on the ticket - POSTing
+        // again would 409; idempotency here matters because agents call
+        // claim defensively at the start of every operation.
+        if (!alreadyAssigned) {
+            try {
+                await client.post(`/projects/${current.projectId}/tickets/${current.id}/assignees/${me.id}`, {});
+            }
+            catch (err) {
+                // 409 = race-added by another process while we were checking.
+                // Treat as already-assigned success.
+                if (!(err instanceof OrbotoApiError) || err.status !== 409)
+                    throw err;
+            }
+        }
+        // Only PATCH if we're not already in_progress. Saves an audit row
+        // + websocket broadcast on the common re-claim path.
+        let finalTicket = current;
+        if (currentCategory !== 'in_progress') {
+            finalTicket = await client.patch(`/projects/${current.projectId}/tickets/${current.id}`, { status: CATEGORY_TO_LEGACY.in_progress });
+        }
+        // Timer side-effects. Mirrors the wrapper's ORB-179 path: stop a
+        // timer running on a different ticket, then start fresh here. A
+        // 409 on the start side is captured as a warning rather than
+        // raised, so the assign/status work still counts as success.
+        let timerStarted = false;
+        let timerWarning = null;
+        // Bot/service accounts own their timer (per-instance, no auto-stop). Instance
+        // id: explicit arg > per-connection MCP session id (distinct per client even
+        // on a shared HTTP server) > per-process id (stdio). Human accounts fall
+        // through to the legacy auto-stop path.
+        const effectiveToken = agentSessionToken ?? (me.isBot ? mcpInstanceToken(undefined, extra) : undefined);
+        if (!noTimer) {
+            try {
+                if (effectiveToken) {
+                    // ORB-1252 - agent instance owns its timer: per-session, no auto-stop.
+                    // Idempotent on the same ticket; 409 if this session already runs a
+                    // different ticket (surfaced as a warning below).
+                    await client.post('/time/timer/start', { ticketId: current.id, agentSessionToken: effectiveToken });
+                    timerStarted = true;
+                }
+                else {
+                    const active = await client.get('/time/timer').catch(() => null);
+                    if (active && active.ticketId && active.ticketId !== current.id) {
+                        const other = active.ticketTitle ? `"${active.ticketTitle}"` : active.ticketId;
+                        await client.post('/time/timer/stop', {
+                            note: `Auto-stopped by claim of ${finalTicket.ticketKey ?? current.id}`,
+                        }).catch(() => {
+                            // Swallow - we'll try start below; if start 409s we surface
+                            // the warning then.
+                            timerWarning = `Failed to stop timer on ${other}; new timer not started.`;
+                        });
+                    }
+                    else if (active && active.ticketId === current.id) {
+                        // Same ticket - effectively already started.
+                        timerStarted = true;
+                    }
+                    if (!timerStarted && !timerWarning) {
+                        await client.post('/time/timer/start', { ticketId: current.id });
+                        timerStarted = true;
+                    }
+                }
+            }
+            catch (err) {
+                if (err instanceof OrbotoApiError && err.status === 409) {
+                    timerWarning = 'A timer is already running on another ticket; could not start one here. Run `orboto_timer_stop` first.';
+                }
+                else {
+                    // Any other timer error → keep the claim, surface the issue.
+                    timerWarning = err instanceof Error ? err.message : String(err);
+                }
+            }
+        }
+        const noop = alreadyAssigned &&
+            currentCategory === 'in_progress' &&
+            !sole &&
+            (noTimer || timerStarted);
+        const lines = [
+            `Claimed [${finalTicket.ticketKey}] ${finalTicket.title}`,
+            `  status: ${finalTicket.statusName ?? finalTicket.status}`,
+            noTimer ? '  timer: skipped (noTimer=true)' : `  timer: ${timerStarted ? 'started' : 'not started'}`,
+            timerWarning ? `  warning: ${timerWarning}` : null,
+            noop ? '  (no-op - already claimed + in_progress)' : null,
+        ].filter((l) => l !== null);
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                ticketKey: finalTicket.ticketKey,
+                status: finalTicket.statusName ?? finalTicket.status,
+                statusCategory: finalTicket.statusCategory,
+                assignedSelf: true,
+                soleTakeover: sole === true,
+                timerStarted,
+                timerWarning,
+                noop,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_unclaim
+// ---------------------------------------------------------------------------
+export const unclaimToolConfig = {
+    title: 'Unclaim a ticket (composite: unassign self + move to todo)',
+    description: 'Inverse of `orboto_claim`: remove the calling user as an assignee and move the ticket back to `todo`. Idempotent - if the caller wasn\'t an assignee, the unassign step is a no-op and the status move still happens. Does not stop a running timer (use `orboto_timer_stop` if you want that side-effect; staying separate avoids surprising the next claimant).',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeUnclaimHandler(client) {
+    return async ({ ticketKey }) => {
+        const me = await client.get('/users/me');
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        let alreadyUnassigned = false;
+        try {
+            await client.delete(`/projects/${ticket.projectId}/tickets/${ticket.id}/assignees/${me.id}`);
+        }
+        catch (err) {
+            if (err instanceof OrbotoApiError && err.status === 404) {
+                alreadyUnassigned = true;
+            }
+            else {
+                throw err;
+            }
+        }
+        const updated = await client.patch(`/projects/${ticket.projectId}/tickets/${ticket.id}`, { status: CATEGORY_TO_LEGACY.todo });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Unclaimed [${updated.ticketKey}] - moved to ${updated.statusName ?? updated.status}${alreadyUnassigned ? ' (was not assigned)' : ''}.`,
+                }],
+            structuredContent: {
+                ticketKey: updated.ticketKey,
+                status: updated.statusName ?? updated.status,
+                statusCategory: updated.statusCategory,
+                alreadyUnassigned,
+            },
+        };
+    };
+}

package/dist/tools/claim.test.js

@@ -0,0 +1,207 @@
+/**
+ * ORB-799 - `orboto_claim` / `orboto_unclaim` unit tests.
+ *
+ * Covers the composite happy paths, the idempotent re-claim shortcut,
+ * the `sole=true` destructive take-over, the `force=true` reopen-done
+ * guard, and the `noTimer=true` skip. The timer-warning branch (where
+ * a 409 surfaces from `/time/timer/start`) is exercised in the
+ * dedicated test below.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { makeClaimHandler, makeUnclaimHandler } from './claim.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({
+            url: url.toString(),
+            method: init?.method ?? 'GET',
+            body: init?.body ? JSON.parse(init.body) : undefined,
+        });
+        const r = responses.shift();
+        if (!r)
+            throw new Error(`unexpected extra fetch ${init?.method ?? 'GET'} ${url}`);
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: 'OK',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => '',
+        };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const ME = { id: 'me1', email: 'agent-e@orboto.io', fullName: 'Agent E' };
+const PROJ = { id: 'p1', key: 'ACME', name: 'Acme', description: null, status: 'active' };
+const TICKET_TODO = {
+    id: 't1', projectId: 'p1', ticketKey: 'ACME-1', ticketNumber: 1,
+    title: 'Bug', description: null, status: 'TODO', statusName: 'To Do',
+    statusCategory: 'todo', type: 'bug', priority: 'normal',
+    estimatedTimeMinutes: 0, dueDate: null, isPrivate: false, assignees: [],
+};
+describe('orboto_claim', () => {
+    it('happy path: assigns self + moves to in_progress + starts timer (no active timer)', async () => {
+        const calls = stub([
+            { json: ME }, // /users/me
+            { json: PROJ }, // resolveTicketByKey: by-key project
+            { json: TICKET_TODO }, // resolveTicketByKey: ticket
+            { json: {} }, // POST assignees/me
+            { json: { ...TICKET_TODO, status: 'IN_PROGRESS', statusName: 'In Progress', statusCategory: 'in_progress' } }, // PATCH status
+            { json: null }, // GET /time/timer (no active)
+            { json: { id: 'tm1', ticketId: 't1', startedAt: '2026-05-14T16:00:00Z' } }, // POST timer/start
+        ]);
+        const res = await makeClaimHandler(client)({ ticketKey: 'ACME-1' });
+        expect(calls[3]).toMatchObject({
+            method: 'POST',
+            url: 'https://orboto.example.com/projects/p1/tickets/t1/assignees/me1',
+        });
+        expect(calls[4]).toMatchObject({
+            method: 'PATCH',
+            url: 'https://orboto.example.com/projects/p1/tickets/t1',
+            body: { status: 'IN_PROGRESS' },
+        });
+        expect(calls[6]).toMatchObject({
+            method: 'POST',
+            url: 'https://orboto.example.com/time/timer/start',
+            body: { ticketId: 't1' },
+        });
+        expect(res.structuredContent).toMatchObject({
+            ticketKey: 'ACME-1',
+            timerStarted: true,
+            timerWarning: null,
+            noop: false,
+        });
+    });
+    it('idempotent: skip assign POST + status PATCH when already-in-progress + already-assigned', async () => {
+        const calls = stub([
+            { json: ME },
+            { json: PROJ },
+            { json: {
+                    ...TICKET_TODO, status: 'IN_PROGRESS', statusName: 'In Progress', statusCategory: 'in_progress',
+                    assignees: [{ id: 'me1', email: 'agent-e@orboto.io', fullName: 'Agent E' }],
+                } },
+            { json: { ticketId: 't1' } }, // GET /time/timer - already on same ticket
+        ]);
+        const res = await makeClaimHandler(client)({ ticketKey: 'ACME-1' });
+        // 4 calls total: /users/me, by-key project, by-key ticket, GET /time/timer.
+        // No POST /assignees, no PATCH status, no POST /timer/start.
+        expect(calls).toHaveLength(4);
+        expect(calls.some((c) => c.method === 'PATCH')).toBe(false);
+        expect(calls.some((c) => c.url.includes('/timer/start'))).toBe(false);
+        expect(res.structuredContent).toMatchObject({
+            ticketKey: 'ACME-1',
+            noop: true,
+        });
+    });
+    it('sole=true removes every other assignee before adding self', async () => {
+        const calls = stub([
+            { json: ME },
+            { json: PROJ },
+            { json: { ...TICKET_TODO, assignees: [
+                        { id: 'other1', email: 'a@x', fullName: 'A' },
+                        { id: 'other2', email: 'b@x', fullName: 'B' },
+                    ] } },
+            { ok: true, status: 204 }, // DELETE other1
+            { ok: true, status: 204 }, // DELETE other2
+            { json: {} }, // POST assignees/me
+            { json: { ...TICKET_TODO, status: 'IN_PROGRESS', statusName: 'In Progress', statusCategory: 'in_progress' } },
+            { json: null }, // GET timer
+            { json: {} }, // POST timer/start
+        ]);
+        await makeClaimHandler(client)({ ticketKey: 'ACME-1', sole: true });
+        expect(calls.filter((c) => c.method === 'DELETE')).toHaveLength(2);
+        expect(calls[3].url).toContain('/assignees/other1');
+        expect(calls[4].url).toContain('/assignees/other2');
+    });
+    it('refuses to claim a done ticket without force=true', async () => {
+        stub([
+            { json: ME },
+            { json: PROJ },
+            { json: { ...TICKET_TODO, status: 'DONE', statusName: 'Done', statusCategory: 'done' } },
+        ]);
+        await expect(makeClaimHandler(client)({ ticketKey: 'ACME-1' })).rejects.toThrow(/Refusing to claim/);
+    });
+    it('force=true claims a done ticket and re-opens to in_progress', async () => {
+        const calls = stub([
+            { json: ME },
+            { json: PROJ },
+            { json: { ...TICKET_TODO, status: 'DONE', statusName: 'Done', statusCategory: 'done' } },
+            { json: {} }, // POST assignees/me
+            { json: { ...TICKET_TODO, status: 'IN_PROGRESS', statusName: 'In Progress', statusCategory: 'in_progress' } },
+            { json: null },
+            { json: {} },
+        ]);
+        await makeClaimHandler(client)({ ticketKey: 'ACME-1', force: true });
+        expect(calls.find((c) => c.method === 'PATCH')?.body).toEqual({ status: 'IN_PROGRESS' });
+    });
+    it('noTimer=true skips the timer interaction', async () => {
+        const calls = stub([
+            { json: ME },
+            { json: PROJ },
+            { json: TICKET_TODO },
+            { json: {} },
+            { json: { ...TICKET_TODO, status: 'IN_PROGRESS', statusName: 'In Progress', statusCategory: 'in_progress' } },
+        ]);
+        const res = await makeClaimHandler(client)({ ticketKey: 'ACME-1', noTimer: true });
+        expect(calls.some((c) => c.url.includes('/timer'))).toBe(false);
+        expect(res.structuredContent).toMatchObject({ timerStarted: false });
+    });
+    it('timer 409 → assign/status succeed, timerWarning surfaces', async () => {
+        stub([
+            { json: ME },
+            { json: PROJ },
+            { json: TICKET_TODO },
+            { json: {} },
+            { json: { ...TICKET_TODO, status: 'IN_PROGRESS', statusName: 'In Progress', statusCategory: 'in_progress' } },
+            { json: null }, // GET /time/timer - empty
+            { ok: false, status: 409, json: { error: 'timer already running' } }, // POST /timer/start fails
+        ]);
+        const res = await makeClaimHandler(client)({ ticketKey: 'ACME-1' });
+        expect(res.structuredContent).toMatchObject({
+            ticketKey: 'ACME-1',
+            timerStarted: false,
+        });
+        expect(res.structuredContent.timerWarning).toMatch(/timer is already running/i);
+    });
+});
+describe('orboto_unclaim', () => {
+    it('unassigns self + moves to todo', async () => {
+        const calls = stub([
+            { json: ME },
+            { json: PROJ },
+            { json: { ...TICKET_TODO, status: 'IN_PROGRESS', statusName: 'In Progress', statusCategory: 'in_progress' } },
+            { ok: true, status: 204 }, // DELETE assignees/me
+            { json: { ...TICKET_TODO, status: 'TODO', statusName: 'To Do', statusCategory: 'todo' } },
+        ]);
+        const res = await makeUnclaimHandler(client)({ ticketKey: 'ACME-1' });
+        expect(calls[3]).toMatchObject({ method: 'DELETE', url: 'https://orboto.example.com/projects/p1/tickets/t1/assignees/me1' });
+        expect(calls[4]).toMatchObject({ method: 'PATCH', body: { status: 'TODO' } });
+        expect(res.structuredContent).toMatchObject({
+            ticketKey: 'ACME-1',
+            alreadyUnassigned: false,
+        });
+    });
+    it('idempotent: 404 on unassign is treated as alreadyUnassigned', async () => {
+        stub([
+            { json: ME },
+            { json: PROJ },
+            { json: TICKET_TODO },
+            { ok: false, status: 404, json: { error: 'not assigned' } },
+            { json: { ...TICKET_TODO, statusCategory: 'todo' } },
+        ]);
+        const res = await makeUnclaimHandler(client)({ ticketKey: 'ACME-1' });
+        expect(res.structuredContent).toMatchObject({ alreadyUnassigned: true });
+    });
+    it('surfaces non-404 errors from the unassign delete', async () => {
+        stub([
+            { json: ME },
+            { json: PROJ },
+            { json: TICKET_TODO },
+            { ok: false, status: 500, json: { error: 'boom' } },
+        ]);
+        await expect(makeUnclaimHandler(client)({ ticketKey: 'ACME-1' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});

package/dist/tools/critical-path.js

@@ -0,0 +1,83 @@
+/**
+ * ORB-1028 - `orboto_critical_path`. Phase 4 agent surface for the CPM
+ * endpoint shipped in Phase 1. Wraps GET /projects/:id/critical-path,
+ * resolving the project key (and optional milestone name) for the caller.
+ */
+import { z } from 'zod';
+import { resolveProjectByKey } from './shared.js';
+import { resolveMilestoneByNameOrId } from './milestones.js';
+export const criticalPathToolConfig = {
+    title: 'Critical path (CPM)',
+    description: "Compute a project's (or one milestone's) critical path via the Critical Path Method: the longest finish-to-start dependency chain that sets the delivery date, plus each ticket's slack (total float, in working days). Durations come from `estimatedTimeMinutes` (8h/day, floored at 1 day). Deadline-aware (ORB-1459): a ticket's due date (or its milestone's, when tighter) seeds the backward pass, so total float can go NEGATIVE when a chain cannot meet its deadline - those tickets are reported under `deadlineRisks` with the shortfall in working days. ORB-1614: a dependency edge to a ticket in ANOTHER project is followed one hop (that ticket's own further cross-project blockers are not) when you can read it, and marked `external: true` in the result - an edge to a foreign ticket you cannot read is silently absent from the graph, same as any other out-of-window ticket. Returns the critical path (ticket keys in order), the total working-day duration, per-ticket float, and the deadline risks. A dependency cycle (including one spanning projects) returns the tangled ticket keys instead of a path. By default tickets in completed/archived milestones are excluded (matching the board); set includeClosedMilestones to include them.",
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
+        milestone: z.string().optional().describe('Milestone name to scope to. Omit for the whole project.'),
+        includeClosedMilestones: z.boolean().optional().describe('Include tickets from completed/archived milestones. Default false (hidden, matching the board).'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeCriticalPathHandler(client) {
+    return async (input) => {
+        const project = await resolveProjectByKey(client, input.projectKey);
+        const params = new URLSearchParams();
+        if (input.milestone) {
+            // ORB-1696 - shared resolver: key (ORB-M3), name or UUID, ambiguous
+            // name -> explicit error. Matches create_ticket/set_milestone/OQL.
+            const m = await resolveMilestoneByNameOrId(client, project.id, input.milestone);
+            params.set('milestoneId', m.id);
+        }
+        if (input.includeClosedMilestones)
+            params.set('includeClosedMilestones', 'true');
+        const qs = params.toString();
+        const url = `/projects/${project.id}/critical-path${qs ? `?${qs}` : ''}`;
+        const res = await client.get(url);
+        if (res.cycle) {
+            return {
+                content: [{ type: 'text', text: `Dependency cycle - the critical path is undefined until it's broken. Tickets involved: ${res.cycle.ticketKeys.join(', ')}` }],
+                structuredContent: { cycle: res.cycle, criticalPath: [], projectDurationDays: 0, tickets: [] },
+            };
+        }
+        // ORB-1614 - flag cross-project neighbours pulled into the graph so the
+        // reader knows a key like "OVB-55" is not a typo for this project.
+        const externalKeys = new Set(res.tickets.filter((t) => t.external).map((t) => t.ticketKey));
+        const slack = res.tickets
+            .filter((t) => !t.isCritical && t.totalFloat > 0)
+            .sort((a, b) => a.totalFloat - b.totalFloat)
+            .map((t) => `  ${t.ticketKey}${t.external ? ' [external]' : ''}: ${t.totalFloat}d slack`)
+            .join('\n');
+        // ORB-1459 - surface tickets whose deadline can't be met (negative float).
+        const risks = (res.deadlineRisks ?? [])
+            .map((r) => {
+            const via = r.constrainingTicketKey && r.constrainingTicketKey !== r.ticketKey
+                ? ` (via ${r.constrainingTicketKey}${r.dueDate ? ` due ${r.dueDate}` : ''})`
+                : r.dueDate ? ` (due ${r.dueDate})` : '';
+            return `  ${r.ticketKey}: ${r.shortfallDays}d short${via}`;
+        })
+            .join('\n');
+        const pathDisplay = res.criticalPath.length
+            ? res.criticalPath.map((k) => (externalKeys.has(k) ? `${k} [external]` : k)).join(' -> ')
+            : '(none)';
+        const text = `Critical path (${res.projectDurationDays} working day${res.projectDurationDays === 1 ? '' : 's'}): ${pathDisplay}` +
+            (slack ? `\nSlack on non-critical tickets:\n${slack}` : '\nAll in-scope tickets are on the critical path.') +
+            (risks ? `\nDEADLINE RISKS (negative float - cannot meet the deadline):\n${risks}` : '');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: {
+                criticalPath: res.criticalPath,
+                projectDurationDays: res.projectDurationDays,
+                tickets: res.tickets.map((t) => ({
+                    ticketKey: t.ticketKey,
+                    isCritical: t.isCritical,
+                    deadlineCritical: t.deadlineCritical ?? false,
+                    bindingConstraint: t.bindingConstraint ?? 'project_end',
+                    totalFloat: t.totalFloat,
+                    durationDays: t.durationDays,
+                    external: t.external ?? false,
+                    externalProjectId: t.externalProjectId ?? null,
+                })),
+                deadlineRisks: res.deadlineRisks ?? [],
+                cycle: null,
+            },
+        };
+    };
+}

package/dist/tools/critical-path.test.js

@@ -0,0 +1,114 @@
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeCriticalPathHandler } from './critical-path.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => {
+        calls.push(url.toString());
+        const r = responses.shift();
+        if (!r)
+            throw new Error(`unexpected extra fetch to ${url}`);
+        return { ok: true, status: 200, statusText: 'OK', json: async () => ('json' in r ? r.json : {}), text: async () => '' };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const PROJ = { id: 'p1', key: 'ACME', name: 'Acme', description: '', status: 'active' };
+describe('orboto_critical_path (ORB-1028)', () => {
+    it('resolves the project and returns the path + per-ticket float', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: {
+                    tickets: [
+                        { ticketKey: 'ACME-1', title: 'A', durationDays: 1, totalFloat: 0, isCritical: true },
+                        { ticketKey: 'ACME-2', title: 'B', durationDays: 1, totalFloat: 2, isCritical: false },
+                    ],
+                    criticalPath: ['ACME-1'],
+                    dependencies: [],
+                    projectDurationDays: 1,
+                    cycle: null,
+                } },
+        ]);
+        const res = await makeCriticalPathHandler(client)({ projectKey: 'ACME' });
+        expect(calls[1]).toContain('/projects/p1/critical-path');
+        expect(calls[1]).not.toContain('milestoneId');
+        const sc = res.structuredContent;
+        expect(sc.criticalPath).toEqual(['ACME-1']);
+        expect(sc.tickets.find((t) => t.ticketKey === 'ACME-2')).toMatchObject({ isCritical: false, totalFloat: 2 });
+        expect(res.content[0].text).toContain('ACME-1');
+    });
+    it('resolves a milestone name to its id query param', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: [{ id: 'm2', name: 'Sprint 7' }] },
+            { json: { tickets: [], criticalPath: [], dependencies: [], projectDurationDays: 0, cycle: null } },
+        ]);
+        await makeCriticalPathHandler(client)({ projectKey: 'ACME', milestone: 'Sprint 7' });
+        expect(calls[2]).toContain('milestoneId=m2');
+    });
+    it('surfaces deadline risks (negative float) in text + structured output', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: {
+                    tickets: [
+                        { ticketKey: 'ACME-1', title: 'A', durationDays: 3, totalFloat: -2, isCritical: true, deadlineCritical: true, bindingConstraint: 'successors' },
+                        { ticketKey: 'ACME-2', title: 'B', durationDays: 2, totalFloat: -2, isCritical: true, deadlineCritical: true, bindingConstraint: 'due_date' },
+                    ],
+                    criticalPath: ['ACME-1', 'ACME-2'],
+                    deadlineRisks: [
+                        { ticketKey: 'ACME-1', constrainingTicketKey: 'ACME-2', dueDate: '2026-07-18', shortfallDays: 2 },
+                        { ticketKey: 'ACME-2', constrainingTicketKey: 'ACME-2', dueDate: '2026-07-18', shortfallDays: 2 },
+                    ],
+                    dependencies: [],
+                    projectDurationDays: 5,
+                    cycle: null,
+                } },
+        ]);
+        const res = await makeCriticalPathHandler(client)({ projectKey: 'ACME' });
+        expect(calls[1]).toContain('/projects/p1/critical-path');
+        const text = res.content[0].text;
+        expect(text).toMatch(/DEADLINE RISKS/);
+        expect(text).toContain('ACME-2: 2d short');
+        const sc = res.structuredContent;
+        expect(sc.deadlineRisks).toHaveLength(2);
+        expect(sc.deadlineRisks[0]).toMatchObject({ ticketKey: 'ACME-1', shortfallDays: 2 });
+    });
+    // ORB-1614 - a 1-hop cross-project neighbour is marked external:true by
+    // the API; the tool should flag it in both the text (so "OVB-55" isn't
+    // mistaken for a typo of this project's key) and the structured output.
+    it('flags a cross-project neighbour with [external] in text and structured output', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: {
+                    tickets: [
+                        { ticketKey: 'ACME-1', title: 'A', durationDays: 1, totalFloat: 0, isCritical: true, external: false },
+                        { ticketKey: 'OVB-6', title: 'Foreign blocker', durationDays: 2, totalFloat: 0, isCritical: true, external: true, externalProjectId: 'p2' },
+                    ],
+                    criticalPath: ['OVB-6', 'ACME-1'],
+                    dependencies: [{ ticketId: 'ACME-1', dependsOnId: 'OVB-6' }],
+                    projectDurationDays: 3,
+                    cycle: null,
+                } },
+        ]);
+        const res = await makeCriticalPathHandler(client)({ projectKey: 'ACME' });
+        expect(calls[1]).toContain('/projects/p1/critical-path');
+        const text = res.content[0].text;
+        expect(text).toContain('OVB-6 [external]');
+        const sc = res.structuredContent;
+        const foreign = sc.tickets.find((t) => t.ticketKey === 'OVB-6');
+        expect(foreign).toMatchObject({ external: true, externalProjectId: 'p2' });
+        const local = sc.tickets.find((t) => t.ticketKey === 'ACME-1');
+        expect(local).toMatchObject({ external: false, externalProjectId: null });
+    });
+    it('surfaces a dependency cycle', async () => {
+        stub([
+            { json: PROJ },
+            { json: { tickets: [], criticalPath: [], dependencies: [], projectDurationDays: 0, cycle: { ticketKeys: ['ACME-1', 'ACME-2'] } } },
+        ]);
+        const res = await makeCriticalPathHandler(client)({ projectKey: 'ACME' });
+        expect(res.content[0].text).toMatch(/cycle/i);
+        expect(res.structuredContent.cycle.ticketKeys).toEqual(['ACME-1', 'ACME-2']);
+    });
+});