@orboto/mcp 0.178.0

package/dist/tools/query.test.js

@@ -0,0 +1,128 @@
+/**
+ * ORB-273 Phase F - `orboto_query` MCP tool tests.
+ *
+ * Confirms the handler:
+ *   - posts to /query with the right body shape
+ *   - emits a human-readable text block + structured-content envelope
+ *   - surfaces nextCursor + a "more pages" hint
+ *   - propagates the syntax flag (jql vs oql) verbatim
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeQueryHandler } from './query.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function mockFetch(json) {
+    return vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+        ok: true, status: 200, statusText: 'OK',
+        json: async () => json,
+    });
+}
+describe('tools/query', () => {
+    const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+    it('renders matched tickets + structured payload', async () => {
+        const spy = mockFetch({
+            items: [
+                {
+                    id: 't1',
+                    ticketKey: 'ORB-1',
+                    title: 'Fix the bug',
+                    status: 'IN_PROGRESS',
+                    statusName: 'In Progress',
+                    statusCategory: 'in_progress',
+                    priority: 'high',
+                    type: 'bug',
+                    dueDate: '2026-05-10',
+                    estimatedTimeMinutes: 60,
+                    loggedMinutes: 15,
+                    assignees: [{ email: 'a@example.com' }],
+                    labels: [{ name: 'frontend' }],
+                },
+            ],
+            nextCursor: null,
+        });
+        const result = await makeQueryHandler(client)({ oql: 'project = ORB' });
+        expect(spy).toHaveBeenCalledWith('https://orboto.example.com/query', expect.objectContaining({
+            method: 'POST',
+            body: JSON.stringify({ oql: 'project = ORB', syntax: 'oql', cursor: undefined, limit: 25 }),
+        }));
+        expect(result.content[0]).toMatchObject({ type: 'text', text: expect.stringContaining('ORB-1') });
+        // ORB-1699 - the default row is the shared lean projection: no uuid,
+        // no labels, no minutes; assignee NAMES (fullName || email).
+        expect(result.structuredContent).toMatchObject({
+            count: 1,
+            nextCursor: null,
+            tickets: [
+                expect.objectContaining({
+                    key: 'ORB-1',
+                    statusCategory: 'in_progress',
+                    assigneeNames: ['a@example.com'],
+                }),
+            ],
+        });
+        const row = result.structuredContent.tickets[0];
+        expect(row.id).toBeUndefined();
+        expect(row.labels).toBeUndefined();
+        expect(row.estimatedTimeMinutes).toBeUndefined();
+    });
+    it('renders the empty-result text block', async () => {
+        mockFetch({ items: [], nextCursor: null });
+        const result = await makeQueryHandler(client)({ oql: 'priority = blocker' });
+        expect(result.content[0]).toEqual({ type: 'text', text: 'No tickets matched.' });
+    });
+    it('hints at the next cursor when more pages exist', async () => {
+        mockFetch({
+            items: [{ id: 't1', ticketKey: 'ORB-1', title: 'a', status: 'TODO', priority: 'normal', type: 'task' }],
+            nextCursor: 'opaque-cursor-token',
+        });
+        const result = await makeQueryHandler(client)({ oql: '' });
+        const text = result.content[0].text;
+        expect(text).toContain('opaque-cursor-token');
+        expect(result.structuredContent).toMatchObject({ nextCursor: 'opaque-cursor-token' });
+    });
+    it('forwards syntax="jql" verbatim so the API runs the JQL adapter', async () => {
+        const spy = mockFetch({ items: [], nextCursor: null });
+        await makeQueryHandler(client)({ oql: 'resolution = Done', syntax: 'jql' });
+        expect(spy).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
+            body: JSON.stringify({ oql: 'resolution = Done', syntax: 'jql', cursor: undefined, limit: 25 }),
+        }));
+    });
+});
+// ORB-1699 - the ONE row builder, asserted from one place: the lean shape
+// omits uuid/timestamps/minutes; verbose restores them. list_tickets,
+// my_tickets and query all consume agentTicketListRow, so this single
+// test pins the row for all three.
+import { agentTicketListRow } from './shared.js';
+describe('agentTicketListRow (ORB-1699)', () => {
+    const FULL = {
+        id: 'u-u-i-d', projectId: 'p1', milestoneId: null, milestoneName: 'M', ticketKey: 'ORB-9',
+        ticketNumber: 9, title: 'T', status: 'TODO', statusName: 'To Do', statusCategory: 'todo',
+        type: 'task', priority: 'high', estimatedTimeMinutes: 120, loggedMinutes: 30,
+        dueDate: '2026-09-01', isPrivate: false, createdAt: 'c', updatedAt: 'u',
+        assignees: [{ id: 'a1', email: 'a@x', fullName: 'Ada' }],
+        labels: [{ id: 'l1', name: 'bug' }],
+    };
+    it('lean row: decision fields only, defaults omitted', () => {
+        const row = agentTicketListRow(FULL);
+        // priority 'high' and dueDate present -> included; type stays only
+        // when it deviates from 'task'; status NAME is verbose-only.
+        expect(Object.keys(row).sort()).toEqual(['assigneeNames', 'dueDate', 'key', 'priority', 'statusCategory', 'title']);
+        expect(row.assigneeNames).toEqual(['Ada']);
+    });
+    it('lean row omits default-valued fields entirely', () => {
+        const row = agentTicketListRow({ ...FULL, priority: 'normal', type: 'task', dueDate: null, assignees: [] });
+        expect(Object.keys(row).sort()).toEqual(['key', 'statusCategory', 'title']);
+    });
+    it('verbose restores uuid, labels, minutes, timestamps', () => {
+        const row = agentTicketListRow(FULL, true);
+        expect(row.id).toBe('u-u-i-d');
+        expect(row.labels).toEqual(['bug']);
+        expect(row.estimatedTimeMinutes).toBe(120);
+        expect(row.loggedMinutes).toBe(30);
+        expect(row.createdAt).toBe('c');
+    });
+    it('waitingForGitIngestion appears only when it fires', () => {
+        expect(agentTicketListRow(FULL).waitingForGitIngestion).toBeUndefined();
+        expect(agentTicketListRow({ ...FULL, waitingForGitIngestion: true }).waitingForGitIngestion).toBe(true);
+    });
+});

package/dist/tools/raci.js

@@ -0,0 +1,108 @@
+/**
+ * ORB-1037 - RACI agent surfaces.
+ *   - orboto_raci      : read the RACI matrix (tickets x members x role).
+ *   - orboto_set_raci  : set a person's R/A/C/I role on a ticket.
+ * Both wrap the same routes the web UI uses. Setting a second Accountable
+ * returns the single-A error from Phase 1 as a friendly message, not a throw.
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+import { resolveProjectByKey, resolveTicketByKey } from './shared.js';
+import { resolveMilestoneByNameOrId } from './milestones.js';
+const ROLES = ['R', 'A', 'C', 'I'];
+async function resolveMemberId(client, projectId, email) {
+    const members = await client.get(`/projects/${projectId}/members`);
+    const m = members.find((x) => x.user.email.toLowerCase() === email.toLowerCase());
+    if (!m)
+        throw new Error(`No project member with email "${email}".`);
+    return m.userId;
+}
+// ---------------------------------------------------------------------------
+// orboto_raci - read the matrix
+// ---------------------------------------------------------------------------
+export const raciToolConfig = {
+    title: 'RACI matrix',
+    description: "Read a project's RACI matrix (tickets x members, cells = R/A/C/I). `milestone` scopes to one milestone; `epicsOnly` narrows rows to epics. RACI is OPT-IN per project: only use this when the project has RACI enabled (check `raciEnabled` on orboto_get_project / the primer). Do NOT raise or suggest RACI on projects that haven't enabled it. Returns empty when RACI is off.",
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key (e.g. "ORB").'),
+        milestone: z.string().optional().describe('Milestone name to scope the matrix.'),
+        epicsOnly: z.boolean().optional().describe('Only include epics as rows.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeRaciHandler(client) {
+    return async (input) => {
+        const project = await resolveProjectByKey(client, input.projectKey);
+        const qs = 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);
+            qs.set('milestoneId', m.id);
+        }
+        if (input.epicsOnly)
+            qs.set('epicsOnly', 'true');
+        const data = await client.get(`/projects/${project.id}/raci-matrix${qs.toString() ? `?${qs}` : ''}`);
+        if (!data.raciEnabled) {
+            return {
+                content: [{ type: 'text', text: `RACI is not enabled for ${project.key}. Turn it on in Project Settings.` }],
+                structuredContent: { raciEnabled: false, projectKey: project.key, members: [], rows: [] },
+            };
+        }
+        // Compact text rendering: one line per ticket listing each held role.
+        const lines = data.rows.map((r) => {
+            const byUser = new Map(data.members.map((m) => [m.userId, m.fullName]));
+            const held = Object.entries(r.cells)
+                .map(([uid, role]) => `${role}:${byUser.get(uid) ?? uid}`)
+                .join(', ');
+            return `[${r.ticketKey ?? '?'}] ${r.title}${held ? ` - ${held}` : ''}`;
+        });
+        const text = lines.length ? lines.join('\n') : 'No tickets match the filters.';
+        return {
+            content: [{ type: 'text', text: `RACI matrix for ${project.key}:\n${text}` }],
+            structuredContent: { raciEnabled: true, projectKey: project.key, members: data.members, rows: data.rows },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_set_raci - write a role
+// ---------------------------------------------------------------------------
+export const setRaciToolConfig = {
+    title: 'Set a RACI role',
+    description: "Set a person's RACI role on a ticket: R (Responsible), A (Accountable, max one per ticket), C (Consulted), or I (Informed). RACI is OPT-IN per project: only use this when the project has RACI enabled (`raciEnabled` true) - do NOT suggest or set RACI on projects that haven't opted in. Resolves the user by email within the ticket's project. Requires ticket:manage_raci. A second Accountable is rejected with the current holder's name.",
+    inputSchema: z.object({
+        ticketKey: z.string().min(3).describe('Ticket key (e.g. "ORB-42").'),
+        userEmail: z.string().email().describe('Email of a project member.'),
+        role: z.enum(ROLES).describe('R, A, C, or I.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeSetRaciHandler(client) {
+    return async ({ ticketKey, userEmail, role }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const userId = await resolveMemberId(client, ticket.projectId, userEmail);
+        try {
+            await client.put(`/projects/${ticket.projectId}/tickets/${ticket.id}/raci/${userId}`, { role });
+        }
+        catch (err) {
+            if (err instanceof OrbotoApiError && err.status === 409) {
+                // Single-A violation or RACI-not-enabled - surface the clean message
+                // the API put in the response body.
+                let msg = err.body;
+                try {
+                    msg = JSON.parse(err.body).error ?? err.body;
+                }
+                catch { /* keep raw */ }
+                return {
+                    content: [{ type: 'text', text: `Could not set ${role} on [${ticket.ticketKey}]: ${msg}` }],
+                    structuredContent: { error: 'conflict', ticketKey: ticket.ticketKey, message: msg },
+                };
+            }
+            throw err;
+        }
+        return {
+            content: [{ type: 'text', text: `Set ${userEmail} as ${role} on [${ticket.ticketKey}].` }],
+            structuredContent: { ticketKey: ticket.ticketKey, userEmail, role },
+        };
+    };
+}

package/dist/tools/raci.test.js

@@ -0,0 +1,70 @@
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeRaciHandler, makeSetRaciHandler } from './raci.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' });
+        const r = responses.shift();
+        if (!r)
+            throw new Error(`unexpected extra fetch to ${url}`);
+        const status = r.status ?? 200;
+        return {
+            ok: status < 400,
+            status,
+            statusText: 'x',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => r.text ?? (r.json ? JSON.stringify(r.json) : ''),
+        };
+    });
+    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' };
+const TICKET = { id: 't1', projectId: 'p1', ticketKey: 'ACME-42', title: 'Thing', type: 'task' };
+const MEMBERS = [{ userId: 'u1', user: { email: 'dana@x.io', fullName: 'Dana' } }];
+describe('orboto_set_raci (ORB-1037)', () => {
+    it('resolves ticket + member and PUTs the role', async () => {
+        const calls = stub([{ json: PROJ }, { json: TICKET }, { json: MEMBERS }, { json: { ok: true, role: 'A' } }]);
+        const res = await makeSetRaciHandler(client)({ ticketKey: 'ACME-42', userEmail: 'dana@x.io', role: 'A' });
+        const put = calls.find((c) => c.method === 'PUT');
+        expect(put.url).toContain('/projects/p1/tickets/t1/raci/u1');
+        expect(res.structuredContent).toMatchObject({ ticketKey: 'ACME-42', userEmail: 'dana@x.io', role: 'A' });
+    });
+    it('surfaces a single-Accountable 409 as a conflict envelope, not a throw', async () => {
+        stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: MEMBERS },
+            { status: 409, json: { error: 'This ticket already has an Accountable (Tom). Change their role first.' } },
+        ]);
+        const res = await makeSetRaciHandler(client)({ ticketKey: 'ACME-42', userEmail: 'dana@x.io', role: 'A' });
+        expect(res.structuredContent).toMatchObject({ error: 'conflict' });
+        expect(res.content[0].text).toMatch(/already has an Accountable/);
+    });
+});
+describe('orboto_raci (ORB-1037)', () => {
+    it('reads the matrix and renders one line per ticket', async () => {
+        const calls = stub([
+            { json: PROJ },
+            {
+                json: {
+                    raciEnabled: true,
+                    members: [{ userId: 'u1', fullName: 'Dana', email: 'dana@x.io' }],
+                    rows: [{ ticketId: 't1', ticketKey: 'ACME-42', title: 'Thing', cells: { u1: 'A' } }],
+                },
+            },
+        ]);
+        const res = await makeRaciHandler(client)({ projectKey: 'ACME' });
+        expect(calls[1].url).toContain('/projects/p1/raci-matrix');
+        expect(res.content[0].text).toMatch(/ACME-42/);
+        expect(res.content[0].text).toMatch(/A:Dana/);
+    });
+    it('reports the disabled state', async () => {
+        stub([{ json: PROJ }, { json: { raciEnabled: false, members: [], rows: [] } }]);
+        const res = await makeRaciHandler(client)({ projectKey: 'ACME' });
+        expect(res.structuredContent).toMatchObject({ raciEnabled: false });
+    });
+});

package/dist/tools/requirements-spec.js

@@ -0,0 +1,89 @@
+/**
+ * ORB-1409 (epic ORB-1390) - `orboto_requirements_spec`.
+ *
+ * Generates the requirements specification (Pflichtenheft) as Markdown:
+ * numbered functional requirements (FA-1, FA-1.1...) each traceable to its
+ * ticket and tagged muss/soll/kann from priority, plus non-functional
+ * requirements distilled from primer facts. `outlineVariant` picks the chapter
+ * naming/order: `neutral` (default), `industry` (VDI-3694 style), or `software`
+ * (IEEE-830 style). Private tickets/milestones are always excluded server-side.
+ * Wraps `POST /projects/:id/requirements-spec/generate` with `format: 'markdown'`.
+ * Money price mode needs budget:view on top of requirements_spec:generate (the
+ * API returns 403 otherwise).
+ *
+ * The route existed since ORB-1391; ORB-1409 fills in the missing MCP + skill
+ * surfaces (the Pflichtenheft feature shipped route + chat only).
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+import { resolveProjectByKey } from './shared.js';
+const LOCALES = ['en', 'de', 'fr', 'it', 'es', 'sv'];
+const OUTLINE_VARIANTS = ['neutral', 'industry', 'software'];
+export const requirementsSpecToolConfig = {
+    title: 'Requirements specification (Pflichtenheft)',
+    description: 'Generate the requirements specification (Pflichtenheft) as Markdown - numbered functional requirements (FA-1, FA-1.1...) each traceable to its ticket and tagged muss/soll/kann from priority, plus non-functional requirements distilled from primer facts. '
+        + '`outlineVariant`: "neutral" (default), "industry" (VDI-3694 naming/order), or "software" (IEEE-830 naming/order). '
+        + '`locale` sets the document language (en/de/fr/it/es/sv) independently of your own locale; structure labels are catalog-translated. '
+        + '`priceMode`: "hours" (estimates, default), "money" (customer rates - needs the budget:view permission), or "lumpSum" (a flat price - pass `lumpSumAmount`). '
+        + 'Private tickets and milestones are always excluded, and internal cost/overhead is never included. Requires the requirements_spec:generate permission on the project.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key (e.g. "ORB").'),
+        outlineVariant: z.enum(OUTLINE_VARIANTS).default('neutral').describe('Outline variant (default "neutral"). "industry" = VDI-3694 style, "software" = IEEE-830 style.'),
+        locale: z.enum(LOCALES).default('en').describe('Document language (default "en").'),
+        priceMode: z.enum(['hours', 'money', 'lumpSum']).default('hours').describe('Pricing mode (default "hours"). "money" needs budget:view.'),
+        lumpSumAmount: z.number().nonnegative().optional().describe('Flat price for priceMode="lumpSum".'),
+        lumpSumCurrency: z.string().min(1).max(8).optional().describe('Currency for the lump sum (default EUR).'),
+        showAssigneeNames: z.boolean().optional().describe('Include assignee names (opt-in, default off).'),
+        showTicketKeys: z.boolean().optional().describe('Show ticket keys in the output (default on).'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeRequirementsSpecHandler(client) {
+    return async (input) => {
+        const project = await resolveProjectByKey(client, input.projectKey);
+        const priceMode = input.priceMode ?? 'hours';
+        const options = {
+            priceMode,
+            showAssigneeNames: input.showAssigneeNames ?? false,
+            showTicketKeys: input.showTicketKeys ?? true,
+        };
+        if (priceMode === 'lumpSum') {
+            options.lumpSum = {
+                amount: input.lumpSumAmount ?? 0,
+                currency: input.lumpSumCurrency ?? 'EUR',
+            };
+        }
+        const body = {
+            outlineVariant: input.outlineVariant ?? 'neutral',
+            locale: input.locale ?? 'en',
+            options,
+            format: 'markdown',
+        };
+        let res;
+        try {
+            res = await client.post(`/projects/${project.id}/requirements-spec/generate`, body);
+        }
+        catch (err) {
+            if (err instanceof OrbotoApiError && err.status === 403 && priceMode === 'money') {
+                return {
+                    content: [{ type: 'text', text: `Not permitted: money price mode needs the budget:view permission on ${project.key}.` }],
+                    structuredContent: { error: 'forbidden', requiredPermission: 'budget:view' },
+                };
+            }
+            throw err;
+        }
+        return {
+            content: [{ type: 'text', text: res.markdown }],
+            structuredContent: {
+                projectKey: project.key,
+                outlineVariant: res.outlineVariant,
+                locale: res.locale,
+                priceMode: res.priceMode,
+                aiSkipped: res.aiSkipped,
+                reviewFlags: res.reviewFlags,
+                languageFallback: res.languageFallback,
+                languageNote: res.languageNote,
+            },
+        };
+    };
+}

package/dist/tools/requirements-spec.test.js

@@ -0,0 +1,62 @@
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeRequirementsSpecHandler } from './requirements-spec.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        const body = init?.body ? JSON.parse(String(init.body)) : undefined;
+        calls.push({ url: url.toString(), body });
+        const r = responses.shift();
+        if (!r)
+            throw new Error(`unexpected extra fetch to ${url}`);
+        const status = r.status ?? 200;
+        return {
+            ok: status < 400, status, 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' };
+const MD = {
+    markdown: '# Pflichtenheft - Acme\n\n## Functional requirements\n\nFA-1 ...\n',
+    outlineVariant: 'neutral', locale: 'de', priceMode: 'hours',
+    aiSkipped: null,
+    reviewFlags: { executiveSummaryGenerated: false, contentTranslated: false, translatedFields: 0 },
+    languageFallback: false,
+    languageNote: null,
+};
+describe('orboto_requirements_spec (ORB-1409)', () => {
+    it('resolves the project and posts a markdown generate with outlineVariant + locale', async () => {
+        const calls = stub([{ json: PROJ }, { json: MD }]);
+        const res = await makeRequirementsSpecHandler(client)({ projectKey: 'ACME', outlineVariant: 'neutral', locale: 'de' });
+        expect(calls[1].url).toContain('/projects/p1/requirements-spec/generate');
+        expect(calls[1].body).toMatchObject({ outlineVariant: 'neutral', locale: 'de', format: 'markdown' });
+        expect(res.content[0].text).toContain('Pflichtenheft');
+        expect(res.structuredContent).toMatchObject({ projectKey: 'ACME', outlineVariant: 'neutral', locale: 'de', aiSkipped: null });
+    });
+    it('passes the industry outlineVariant through to the request body', async () => {
+        const calls = stub([{ json: PROJ }, { json: { ...MD, outlineVariant: 'industry' } }]);
+        await makeRequirementsSpecHandler(client)({ projectKey: 'ACME', outlineVariant: 'industry' });
+        expect(calls[1].body).toMatchObject({ outlineVariant: 'industry' });
+    });
+    it('passes lump-sum amount/currency in the options', async () => {
+        const calls = stub([{ json: PROJ }, { json: { ...MD, priceMode: 'lumpSum' } }]);
+        await makeRequirementsSpecHandler(client)({ projectKey: 'ACME', priceMode: 'lumpSum', lumpSumAmount: 5000, lumpSumCurrency: 'USD' });
+        expect(calls[1].body).toMatchObject({ options: { priceMode: 'lumpSum', lumpSum: { amount: 5000, currency: 'USD' } } });
+    });
+    it('surfaces a budget:view 403 for money mode as a clean structured error', async () => {
+        stub([{ json: PROJ }, { status: 403, json: { error: 'Forbidden' } }]);
+        const res = await makeRequirementsSpecHandler(client)({ projectKey: 'ACME', priceMode: 'money' });
+        expect(res.structuredContent.requiredPermission).toBe('budget:view');
+        expect(res.content[0].text).toMatch(/budget:view/);
+    });
+    it('defaults to neutral outline variant + hours mode', async () => {
+        const calls = stub([{ json: PROJ }, { json: MD }]);
+        await makeRequirementsSpecHandler(client)({ projectKey: 'ACME' });
+        expect(calls[1].body).toMatchObject({ outlineVariant: 'neutral', options: { priceMode: 'hours' } });
+    });
+});

package/dist/tools/response-expand.js

@@ -0,0 +1,104 @@
+/**
+ * ORB-1697 - `orboto_response_expand`: the way back from a truncated
+ * response.
+ *
+ * The central response budget (`../response-budget.ts`) caps what a
+ * single tool result may inject into the session, because a result is
+ * re-sent on every later request and therefore costs its size times the
+ * turns that follow it. A cap is only acceptable if nothing is lost, so
+ * every truncated response carries a handle, and this tool serves the
+ * omitted remainder from the in-process store in budget-sized chunks.
+ *
+ * Deliberately NOT a REST call: the handle addresses the payload the
+ * ORIGINAL call already produced, so expanding cannot return anything
+ * the caller was not already authorised to see, and it costs no
+ * additional API round-trip. The store is per-process and short-lived
+ * (15 min, 16 payloads) - an expired handle is answered with "re-run the
+ * original tool", never with a wrong or stale chunk.
+ */
+import { z } from 'zod';
+import { budgetFor, readPayload, resolvePath, } from '../response-budget.js';
+export const responseExpandToolConfig = {
+    title: 'Fetch the omitted part of a truncated response',
+    description: 'Return the content a previous tool response omitted. When a result exceeds its response budget it comes back with a `__truncation` block containing a `handle` and the list of cut paths; pass that handle here to read the omitted remainder. Call with `handle` alone to list what is available, then with `path` (e.g. "description" or "ticketBundle.primer.markdown", or "$text" for the human-readable block) to read it, following `nextCursor` while it is not null. Handles live 15 minutes in the MCP server process - if one has expired, re-run the original tool. Read-only; returns nothing the original call did not already return.',
+    inputSchema: z.object({
+        handle: z.string().min(4).max(64).describe('From a response\'s `__truncation` block.'),
+        path: z.string().max(400).optional().describe('One of `__truncation.omitted[].path`, or "$text". Omit to list them.'),
+        cursor: z.number().int().min(0).optional().describe('`nextCursor` from the previous chunk.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+function expired(handle) {
+    const text = `No stored payload for handle "${handle}". Handles live 15 minutes in the MCP server process and only the `
+        + '16 most recent are kept, so this one has expired or the server restarted. Re-run the original tool to get a fresh handle.';
+    return { isError: true, content: [{ type: 'text', text }] };
+}
+function describeOmitted(entries) {
+    if (entries.length === 0)
+        return '(nothing recorded as omitted for this handle)';
+    return entries
+        .map((e) => e.kind === 'string'
+        ? `- ${e.path} (string, ${e.omittedChars ?? 0} chars omitted)`
+        : `- ${e.path} (array, ${e.omittedItems ?? 0} of ${(e.keptItems ?? 0) + (e.omittedItems ?? 0)} items omitted)`)
+        .join('\n');
+}
+export function makeResponseExpandHandler() {
+    return async (input) => {
+        const stored = readPayload(input.handle);
+        if (!stored)
+            return expired(input.handle);
+        const omitted = stored.omitted ?? [];
+        // No path - list what can be expanded. Cheap by construction: paths
+        // and counts only, never the content itself.
+        if (!input.path) {
+            const lines = [
+                `# Truncated content available for handle "${input.handle}"`,
+                `Original tool: ${stored.toolName}`,
+                '',
+                describeOmitted(omitted),
+                '',
+                'Call again with one of these `path` values to read it.',
+            ];
+            return {
+                content: [{ type: 'text', text: lines.join('\n') }],
+                structuredContent: {
+                    handle: input.handle,
+                    toolName: stored.toolName,
+                    omitted,
+                },
+            };
+        }
+        const raw = input.path === '$text'
+            ? stored.text
+            : resolvePath(stored.structuredContent, input.path);
+        if (raw === undefined) {
+            const text = `Path "${input.path}" does not exist in the stored payload for handle "${input.handle}". `
+                + `Available paths:\n${describeOmitted(omitted)}`;
+            return { isError: true, content: [{ type: 'text', text }] };
+        }
+        const full = typeof raw === 'string' ? raw : JSON.stringify(raw, null, 1) ?? '';
+        // Leave room for the framing lines so a chunk plus its header still
+        // fits this tool's own budget - a continuation tool that gets
+        // truncated itself would be a loop, not a fix.
+        const chunkSize = Math.max(500, budgetFor('orboto_response_expand') - 800);
+        const cursor = Math.min(input.cursor ?? 0, full.length);
+        const chunk = full.slice(cursor, cursor + chunkSize);
+        const nextCursor = cursor + chunk.length < full.length ? cursor + chunk.length : null;
+        const header = `# ${input.path} (chars ${cursor}-${cursor + chunk.length} of ${full.length})`;
+        const footer = nextCursor === null
+            ? '(end of value)'
+            : `(more follows - call again with cursor=${nextCursor})`;
+        return {
+            content: [{ type: 'text', text: `${header}\n\n${chunk}\n\n${footer}` }],
+            structuredContent: {
+                handle: input.handle,
+                path: input.path,
+                chunk,
+                cursor,
+                nextCursor,
+                totalChars: full.length,
+                isString: typeof raw === 'string',
+            },
+        };
+    };
+}