@orboto/mcp 0.178.0

package/dist/tools/analytics.test.js

@@ -0,0 +1,71 @@
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeAnalyticsHandler } from './analytics.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}`);
+        const status = r.status ?? 200;
+        return { ok: status < 400, status, statusText: 'x', 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_analytics (ORB-1032)', () => {
+    it('routes a plain report to the analytics endpoint', async () => {
+        const calls = stub([{ json: PROJ }, { json: { total: 5 } }]);
+        const res = await makeAnalyticsHandler(client)({ projectKey: 'ACME', report: 'overview' });
+        expect(calls[1]).toContain('/projects/p1/analytics/overview');
+        expect(res.structuredContent).toMatchObject({ report: 'overview', projectKey: 'ACME', data: { total: 5 } });
+    });
+    it('routes estimation-accuracy to the analytics endpoint (ORB-1254)', async () => {
+        const calls = stub([{ json: PROJ }, { json: { cohorts: { combined: { confidence: 'insufficient' } } } }]);
+        const res = await makeAnalyticsHandler(client)({ projectKey: 'ACME', report: 'estimation-accuracy' });
+        expect(calls[1]).toContain('/projects/p1/analytics/estimation-accuracy');
+        expect(res.structuredContent).toMatchObject({ report: 'estimation-accuracy', projectKey: 'ACME' });
+    });
+    it('routes flow-time to the analytics endpoint (ORB-1257)', async () => {
+        const calls = stub([{ json: PROJ }, { json: { overall: { sampleSize: 0 } } }]);
+        const res = await makeAnalyticsHandler(client)({ projectKey: 'ACME', report: 'flow-time' });
+        expect(calls[1]).toContain('/projects/p1/analytics/flow-time');
+        expect(res.structuredContent).toMatchObject({ report: 'flow-time', projectKey: 'ACME' });
+    });
+    it('routes flow-metrics to the analytics endpoint (ORB-1258)', async () => {
+        const calls = stub([{ json: PROJ }, { json: { currentWip: 0 } }]);
+        const res = await makeAnalyticsHandler(client)({ projectKey: 'ACME', report: 'flow-metrics' });
+        expect(calls[1]).toContain('/projects/p1/analytics/flow-metrics');
+        expect(res.structuredContent).toMatchObject({ report: 'flow-metrics', projectKey: 'ACME' });
+    });
+    it('routes forecast (with milestone) to the forecast endpoint (ORB-1259)', async () => {
+        const calls = stub([{ json: PROJ }, { json: [{ id: 'm9', name: 'Sprint 9' }] }, { json: { confidence: 'ok' } }]);
+        const res = await makeAnalyticsHandler(client)({ projectKey: 'ACME', report: 'forecast', milestone: 'Sprint 9' });
+        expect(calls[2]).toContain('/projects/p1/analytics/forecast');
+        expect(calls[2]).toContain('milestoneId=m9');
+        expect(res.structuredContent).toMatchObject({ report: 'forecast', projectKey: 'ACME' });
+    });
+    it('routes bottleneck to the analytics endpoint (ORB-1260)', async () => {
+        const calls = stub([{ json: PROJ }, { json: { bottleneckCategory: 'in_review' } }]);
+        const res = await makeAnalyticsHandler(client)({ projectKey: 'ACME', report: 'bottleneck' });
+        expect(calls[1]).toContain('/projects/p1/analytics/bottleneck');
+        expect(res.structuredContent).toMatchObject({ report: 'bottleneck', projectKey: 'ACME' });
+    });
+    it('resolves a milestone + mode for earned-value', async () => {
+        const calls = stub([{ json: PROJ }, { json: [{ id: 'm2', name: 'Sprint 7' }] }, { json: { available: true } }]);
+        await makeAnalyticsHandler(client)({ projectKey: 'ACME', report: 'earned-value', milestone: 'Sprint 7', mode: 'money' });
+        expect(calls[2]).toContain('/projects/p1/earned-value');
+        expect(calls[2]).toContain('milestoneId=m2');
+        expect(calls[2]).toContain('mode=money');
+    });
+    it('surfaces a permission error as a forbidden envelope (not a throw)', async () => {
+        stub([{ json: PROJ }, { status: 403 }]);
+        const res = await makeAnalyticsHandler(client)({ projectKey: 'ACME', report: 'budget' });
+        expect(res.structuredContent).toMatchObject({ error: 'forbidden', requiredPermission: 'budget:view' });
+        expect(res.content[0].text).toMatch(/budget:view/);
+    });
+});

package/dist/tools/api-call.js

@@ -0,0 +1,72 @@
+/**
+ * ORB-1519 - `orboto_api_call`: the execute half of the Code-Mode
+ * escape hatch (epic ORB-1517).
+ *
+ * Wraps `POST /system/api-proxy`, which dispatches the described
+ * request through the API's full auth + permission + validation chain
+ * with the caller's own bearer. The inner status/body come back as data
+ * (the envelope), so a 403 tells the model it lacks a permission
+ * instead of surfacing as an opaque tool failure.
+ */
+import { z } from 'zod';
+export const apiCallToolConfig = {
+    title: 'Call any orboto REST endpoint',
+    description: 'Execute one REST API request - the escape hatch for every endpoint without a named tool. '
+        + 'Find the endpoint + its schema with `orboto_api_search` first. Runs with YOUR permissions '
+        + 'only (the API enforces them server-side); the response is an envelope carrying the inner '
+        + 'HTTP status + body verbatim, so react to a 403/404/422 as data. Auth/OAuth/setup/webhook '
+        + 'paths are blocked at the proxy. Prefer named tools when one exists - they are more ergonomic.',
+    inputSchema: z.object({
+        method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']),
+        path: z.string().min(1).max(500)
+            .describe('Route path, e.g. "/projects/<uuid>/milestones". No query string.'),
+        query: z.record(z.union([z.string(), z.number(), z.boolean(), z.array(z.string())])).optional()
+            .describe('Query parameters as an object.'),
+        // ORB-1710 - typed union, NOT z.unknown(): a typeless argument is
+        // serialized as a STRING by real MCP clients (the OCP-540 class),
+        // which used to reach the inner route without a JSON content type
+        // and 415. The union renders a typed anyOf so clients send real
+        // JSON; the handler still parses a string arrival as belt-and-braces.
+        body: z.union([z.record(z.unknown()), z.array(z.unknown()), z.string(), z.number(), z.boolean()]).optional()
+            .describe('JSON body - a real object/array, not a stringified one.'),
+    }).shape,
+    // Dispatches arbitrary methods - never advertise as read-only.
+    // ORB-1669 - the escape hatch can issue DELETE through the proxy: destructive by contract.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+};
+export function makeApiCallHandler(client) {
+    return async (input) => {
+        // ORB-1710 - belt-and-braces for clients that still stringify the
+        // body: a string that parses as JSON is un-stringified here, so the
+        // proxy receives real JSON even against an older API without the
+        // server-side coercion. An unparseable string passes through and
+        // gets the proxy's clear 400.
+        let body = input.body;
+        if (typeof body === 'string') {
+            try {
+                body = JSON.parse(body);
+            }
+            catch { /* pass through */ }
+        }
+        const envelope = await client.post('/system/api-proxy', {
+            method: input.method,
+            path: input.path,
+            ...(input.query ? { query: input.query } : {}),
+            ...(body !== undefined ? { body } : {}),
+        });
+        const bodyText = envelope.encoding === 'json'
+            ? JSON.stringify(envelope.body, null, 1)
+            : String(envelope.body ?? '');
+        const truncNote = envelope.truncated ? ' (body truncated by the proxy cap)' : '';
+        const okNote = envelope.status >= 400
+            ? ' - the API rejected the inner request; read the body for why (403 = missing permission).'
+            : '';
+        return {
+            content: [{
+                    type: 'text',
+                    text: `HTTP ${envelope.status} ${envelope.matchedRoute}${truncNote}${okNote}\n${bodyText}`,
+                }],
+            structuredContent: envelope,
+        };
+    };
+}

package/dist/tools/api-call.test.js

@@ -0,0 +1,104 @@
+/**
+ * ORB-1519 - unit tests for `orboto_api_call`.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeApiCallHandler } from './api-call.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');
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: 'OK',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => r.text ?? '',
+        };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+describe('orboto_api_call', () => {
+    it('POSTs the structured request to /system/api-proxy and renders the envelope', async () => {
+        const calls = stub([{
+                json: {
+                    status: 201,
+                    contentType: 'application/json',
+                    body: { id: 'm1', name: 'M' },
+                    encoding: 'json',
+                    truncated: false,
+                    matchedRoute: '/projects/{projectId}/milestones',
+                },
+            }]);
+        const res = await makeApiCallHandler(client)({
+            method: 'POST',
+            path: '/projects/p1/milestones',
+            body: { name: 'M', startDate: null, endDate: null },
+        });
+        expect(calls[0].url).toContain('/system/api-proxy');
+        expect(calls[0].body).toMatchObject({ method: 'POST', path: '/projects/p1/milestones' });
+        expect(res.isError).toBeUndefined();
+        expect(res.content[0].text).toContain('HTTP 201');
+        expect(res.structuredContent.status).toBe(201);
+    });
+    it('surfaces an inner 403 as data with a permission hint', async () => {
+        stub([{
+                json: {
+                    status: 403,
+                    contentType: 'application/json',
+                    body: { error: 'Forbidden', errorKey: 'errors.permissions.forbidden' },
+                    encoding: 'json',
+                    truncated: false,
+                    matchedRoute: '/projects/{projectId}/milestones',
+                },
+            }]);
+        const res = await makeApiCallHandler(client)({ method: 'POST', path: '/projects/p1/milestones', body: {} });
+        expect(res.isError).toBeUndefined(); // the tool call succeeded; the API said no
+        const text = res.content[0].text;
+        expect(text).toContain('HTTP 403');
+        expect(text).toMatch(/missing permission/i);
+    });
+    it('un-stringifies a client-stringified JSON body before posting (ORB-1710)', async () => {
+        const calls = stub([{
+                json: { status: 201, contentType: 'application/json', body: { ok: true }, encoding: 'json', truncated: false, matchedRoute: '/docs/{id}/append-section' },
+            }]);
+        await makeApiCallHandler(client)({
+            method: 'POST',
+            path: '/docs/abc/append-section',
+            body: '{"content":"# heading"}',
+        });
+        // The proxy must receive real JSON, not a double-encoded string.
+        expect(calls[0].body.body).toEqual({ content: '# heading' });
+    });
+    it('passes an unparseable string body through for the proxy\'s clear 400', async () => {
+        const calls = stub([{
+                json: { status: 400, contentType: 'application/json', body: { errorKey: 'errors.api_proxy.invalid_body' }, encoding: 'json', truncated: false, matchedRoute: '/x' },
+            }]);
+        await makeApiCallHandler(client)({ method: 'POST', path: '/projects', body: 'not json' });
+        expect(calls[0].body.body).toBe('not json');
+    });
+    it('forwards query params', async () => {
+        const calls = stub([{
+                json: { status: 200, contentType: 'application/json', body: [], encoding: 'json', truncated: false, matchedRoute: '/projects' },
+            }]);
+        await makeApiCallHandler(client)({ method: 'GET', path: '/projects', query: { limit: 5 } });
+        expect(calls[0].body).toMatchObject({ query: { limit: 5 } });
+    });
+    it('marks a truncated envelope in the text output', async () => {
+        stub([{
+                json: { status: 200, contentType: 'text/plain', body: 'x'.repeat(50), encoding: 'utf8', truncated: true, matchedRoute: '/export' },
+            }]);
+        const res = await makeApiCallHandler(client)({ method: 'GET', path: '/export' });
+        expect(res.content[0].text).toContain('truncated by the proxy cap');
+    });
+});

package/dist/tools/api-search.js

@@ -0,0 +1,77 @@
+/**
+ * ORB-1518 - `orboto_api_search`: the discovery half of the Code-Mode
+ * escape hatch (epic ORB-1517).
+ *
+ * Wraps the authenticated `GET /system/api-catalog` routes, which search
+ * the live OpenAPI spec server-side. Lets an agent find any REST
+ * endpoint + its schema on demand instead of needing a named MCP tool
+ * per endpoint - the long tail of the API stays reachable even on a
+ * curated (small) tool manifest. Execute the endpoint you found with
+ * `orboto_api_call` (ORB-1519).
+ */
+import { z } from 'zod';
+export const apiSearchToolConfig = {
+    title: 'Search the orboto REST API catalog',
+    description: 'Discover REST API endpoints on demand - the escape hatch that keeps the WHOLE orboto API '
+        + 'reachable without a named tool per endpoint. Two modes: pass `query` (free text, e.g. '
+        + '"create milestone", "backup runs", "primer fact") for ranked matches with method, path, '
+        + 'required permission slugs and parameter names; then pass `path` + `method` of one match to '
+        + 'get its full parameter/request-body/response schema. Execute the endpoint with '
+        + '`orboto_api_call`. Names with a `?` suffix are optional parameters.',
+    inputSchema: z.object({
+        query: z.string().min(1).max(200).optional()
+            .describe('Free-text search; mutually exclusive with path.'),
+        path: z.string().max(300).optional()
+            .describe('Path for detail mode, e.g. "/projects/{id}". Needs method.'),
+        method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).optional()
+            .describe('Method for detail mode.'),
+        limit: z.number().int().min(1).max(20).default(8)
+            .describe('Max search results.'),
+    }).shape,
+    annotations: { readOnlyHint: true },
+};
+export function makeApiSearchHandler(client) {
+    return async (input) => {
+        if (input.path) {
+            if (!input.method) {
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: 'Detail mode needs both `path` and `method`.' }],
+                };
+            }
+            const qs = new URLSearchParams({ path: input.path, method: input.method });
+            const detail = await client.get(`/system/api-catalog/operation?${qs}`);
+            const perms = detail.requiredPermissions.length > 0
+                ? ` (requires: ${detail.requiredPermissions.join(', ')})`
+                : '';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `${detail.method} ${detail.path}${perms}\n${detail.summary ?? ''}\n`
+                            + `Schema:\n${JSON.stringify({ parameters: detail.parameters, requestBody: detail.requestBody, responses: detail.responses }, null, 1)}`,
+                    }],
+                structuredContent: detail,
+            };
+        }
+        if (!input.query) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: 'Pass `query` to search, or `path` + `method` for one endpoint\'s schema.' }],
+            };
+        }
+        const qs = new URLSearchParams({ q: input.query, limit: String(input.limit ?? 8) });
+        const res = await client.get(`/system/api-catalog?${qs}`);
+        const text = res.results.length === 0
+            ? `No endpoints match "${input.query}". Try a shorter, more distinctive term.`
+            : res.results.map((r) => {
+                const perms = r.requiredPermissions.length > 0 ? ` [${r.requiredPermissions.join(', ')}]` : '';
+                const body = r.bodyProps.length > 0 ? ` body: ${r.bodyProps.join(', ')}` : '';
+                const query = r.queryParams.length > 0 ? ` query: ${r.queryParams.join(', ')}` : '';
+                return `- ${r.method} ${r.path}${perms} - ${r.summary ?? ''}${query}${body}`;
+            }).join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: res,
+        };
+    };
+}

package/dist/tools/api-search.test.js

@@ -0,0 +1,90 @@
+/**
+ * ORB-1518 - unit tests for `orboto_api_search`.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeApiSearchHandler } from './api-search.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');
+        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 ENTRY = {
+    method: 'POST',
+    path: '/projects/{projectId}/milestones',
+    summary: 'Create a milestone',
+    tags: ['Milestones'],
+    requiredPermissions: ['milestone:create'],
+    pathParams: ['projectId'],
+    queryParams: [],
+    bodyProps: ['name', 'startDate', 'endDate', 'isPrivate?'],
+    score: 12,
+};
+describe('orboto_api_search', () => {
+    it('search mode hits /system/api-catalog and renders matches with permissions', async () => {
+        const calls = stub([{ json: { query: 'create milestone', total: 1, results: [ENTRY] } }]);
+        const res = await makeApiSearchHandler(client)({ query: 'create milestone' });
+        expect(calls[0].url).toContain('/system/api-catalog?');
+        expect(calls[0].url).toContain('q=create+milestone');
+        expect(res.isError).toBeUndefined();
+        const text = res.content[0].text;
+        expect(text).toContain('POST /projects/{projectId}/milestones');
+        expect(text).toContain('milestone:create');
+        expect(res.structuredContent.total).toBe(1);
+    });
+    it('detail mode hits /operation with path + method', async () => {
+        const calls = stub([{
+                json: {
+                    method: 'POST',
+                    path: '/projects/{projectId}/milestones',
+                    summary: 'Create a milestone',
+                    description: null,
+                    tags: ['Milestones'],
+                    requiredPermissions: ['milestone:create'],
+                    parameters: [{ name: 'projectId', in: 'path', required: true }],
+                    requestBody: { type: 'object', required: ['name'], properties: { name: { type: 'string' } } },
+                    responses: { '200': { type: 'object' } },
+                },
+            }]);
+        const res = await makeApiSearchHandler(client)({
+            path: '/projects/{projectId}/milestones',
+            method: 'POST',
+        });
+        expect(calls[0].url).toContain('/system/api-catalog/operation?');
+        expect(calls[0].url).toContain('method=POST');
+        const sc = res.structuredContent;
+        expect(sc.requestBody.required).toContain('name');
+        expect(res.content[0].text).toContain('requires: milestone:create');
+    });
+    it('rejects detail mode without a method', async () => {
+        stub([]);
+        const res = await makeApiSearchHandler(client)({ path: '/projects' });
+        expect(res.isError).toBe(true);
+    });
+    it('rejects a call with neither query nor path', async () => {
+        stub([]);
+        const res = await makeApiSearchHandler(client)({});
+        expect(res.isError).toBe(true);
+    });
+    it('renders an empty-result hint instead of erroring', async () => {
+        stub([{ json: { query: 'xyzzy', total: 0, results: [] } }]);
+        const res = await makeApiSearchHandler(client)({ query: 'xyzzy' });
+        expect(res.isError).toBeUndefined();
+        expect(res.content[0].text).toMatch(/no endpoints match/i);
+    });
+});

package/dist/tools/approvals.js

@@ -0,0 +1,68 @@
+/**
+ * ORB-1223 - approval / sign-off gate tools.
+ *
+ *   - orboto_list_approvals   - list a ticket's approval / sign-off requests.
+ *   - orboto_approval_decide  - cast an approve/reject vote on a pending request.
+ *
+ * Policy configuration stays out of the MCP surface (admin config, like the
+ * other project-settings surfaces the agent tools deliberately don't expose).
+ */
+import { z } from 'zod';
+import { resolveTicketByKey } from './shared.js';
+function fmt(r) {
+    return `  ${r.id} → "${r.toStatusName}" [${r.status}] ${r.approveCount}/${r.requiredApprovals} approvals (${r.policyName})${r.canApprove ? ' - you can vote' : ''}`;
+}
+// ---------------------------------------------------------------------------
+// orboto_list_approvals
+// ---------------------------------------------------------------------------
+export const listApprovalsToolConfig = {
+    title: 'List a ticket\'s approval / sign-off requests',
+    description: 'List the approval / sign-off requests on a ticket (generic change-management gates on status transitions). Shows each request\'s target status, mode, approval progress, and whether YOU can vote on it right now. Use this before `orboto_approval_decide`.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3).describe('Ticket key, e.g. ORB-42.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeListApprovalsHandler(client) {
+    return async ({ ticketKey }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const rows = await client.get(`/projects/${ticket.projectId}/tickets/${ticket.id}/approval-requests`);
+        const text = rows.length === 0
+            ? `No approval requests on [${ticket.ticketKey}].`
+            : `Approval requests on [${ticket.ticketKey}]:\n${rows.map(fmt).join('\n')}`;
+        return { content: [{ type: 'text', text }], structuredContent: { ticketKey: ticket.ticketKey, requests: rows } };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_approval_decide
+// ---------------------------------------------------------------------------
+export const approvalDecideToolConfig = {
+    title: 'Approve or reject a ticket sign-off request',
+    description: 'Cast an approve/reject vote on a pending approval / sign-off request that gates a ticket status transition. You must be an eligible approver (a policy role, a named user, or a RACI role on the ticket) - otherwise the API returns 403. A single reject resolves the request; enough approvals unblock the transition (the requester then re-applies the status move). If the ticket has several pending requests, pass `requestId`.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3).describe('Ticket key, e.g. ORB-42.'),
+        decision: z.enum(['approve', 'reject']).describe('Your decision.'),
+        comment: z.string().optional().describe('Optional decision comment (recorded on the vote + notified to the requester).'),
+        requestId: z.string().uuid().optional().describe('Disambiguate when the ticket has more than one pending request.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeApprovalDecideHandler(client) {
+    return async ({ ticketKey, decision, comment, requestId }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const rows = await client.get(`/projects/${ticket.projectId}/tickets/${ticket.id}/approval-requests`);
+        const pending = rows.filter((r) => r.status === 'pending');
+        const target = requestId ? pending.find((r) => r.id === requestId) : pending.find((r) => r.canApprove) ?? pending[0];
+        if (!target) {
+            throw new Error(`No pending approval request to decide on [${ticket.ticketKey}]${requestId ? ` (requestId ${requestId} not pending)` : ''}.`);
+        }
+        const updated = await client.post(`/projects/${ticket.projectId}/approval-requests/${target.id}/decision`, { decision, comment: comment ?? null });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Recorded ${decision} on request for "${updated.toStatusName}" - now ${updated.status} (${updated.approveCount}/${updated.requiredApprovals}).`,
+                }],
+            structuredContent: { ticketKey: ticket.ticketKey, request: updated },
+        };
+    };
+}

package/dist/tools/approvals.test.js

@@ -0,0 +1,48 @@
+/**
+ * ORB-1223 - `orboto_list_approvals` / `orboto_approval_decide` unit tests.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeListApprovalsHandler, makeApprovalDecideHandler } from './approvals.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 PROJ = { id: 'p1', key: 'ACME', name: 'Acme', description: null, status: 'active' };
+const TICKET = { id: 't1', projectId: 'p1', ticketKey: 'ACME-1', ticketNumber: 1, title: 'Bug', description: null, status: 'IN_PROGRESS', statusName: 'In Progress', statusCategory: 'in_progress', type: 'bug', priority: 'normal', estimatedTimeMinutes: 0, dueDate: null, isPrivate: false };
+const REQ = { id: 'r1', toStatusName: 'In Review', policyName: 'Sign-off', mode: 'any_n', status: 'pending', requiredApprovals: 1, currentStep: 0, approveCount: 0, rejectCount: 0, requestedBy: 'u9', canApprove: true, votes: [] };
+describe('orboto_list_approvals', () => {
+    it('lists a ticket\'s approval requests', async () => {
+        stub([{ json: PROJ }, { json: TICKET }, { json: [REQ] }]);
+        const res = await makeListApprovalsHandler(client)({ ticketKey: 'ACME-1' });
+        expect(res.structuredContent?.requests).toHaveLength(1);
+        expect(res.content[0].text).toContain('In Review');
+    });
+});
+describe('orboto_approval_decide', () => {
+    it('approves the pending request the caller can vote on', async () => {
+        const calls = stub([
+            { json: PROJ }, { json: TICKET }, { json: [REQ] },
+            { json: { ...REQ, status: 'approved', approveCount: 1 } },
+        ]);
+        const res = await makeApprovalDecideHandler(client)({ ticketKey: 'ACME-1', decision: 'approve' });
+        const decide = calls.find((c) => c.method === 'POST');
+        expect(decide?.url).toContain('/approval-requests/r1/decision');
+        expect(decide?.body).toMatchObject({ decision: 'approve' });
+        expect(res.content[0].text).toContain('approved');
+    });
+    it('errors when no pending request exists', async () => {
+        stub([{ json: PROJ }, { json: TICKET }, { json: [{ ...REQ, status: 'consumed' }] }]);
+        await expect(makeApprovalDecideHandler(client)({ ticketKey: 'ACME-1', decision: 'approve' })).rejects.toThrow(/No pending approval/);
+    });
+});

package/dist/tools/attach.js

@@ -0,0 +1,108 @@
+/**
+ * ORB-799 - attach files to a ticket.
+ *
+ * Mirrors `orboto.mjs attach <ticket> <path...> [--alt "text"] [--embed]`.
+ *
+ * MCP-side, the model doesn't have local FS access, so the bytes come
+ * over the wire as a base64 `contentBase64` field - same approach as
+ * `orboto_ingest_file`. To keep the surface simple, this tool uploads
+ * one file per call; the wrapper's multi-file shorthand is unrolled
+ * into N tool calls on the agent side.
+ *
+ * Two modes, controlled by `embed`:
+ *
+ *   - embed=false (default): upload only, return the markdown image
+ *     line + raw URL. The agent typically uses this to compose a
+ *     follow-up `orboto_comment` body.
+ *   - embed=true: upload, then PATCH the ticket's description to
+ *     append the markdown image at the end. Idempotent only up to
+ *     duplicate detection (re-running with the same file *does*
+ *     append a fresh line; the API doesn't dedupe).
+ */
+import { z } from 'zod';
+import { resolveTicketByKey } from './shared.js';
+function mimetypeFor(filename) {
+    const lower = filename.toLowerCase();
+    if (lower.endsWith('.pdf'))
+        return 'application/pdf';
+    if (lower.endsWith('.png'))
+        return 'image/png';
+    if (lower.endsWith('.jpg') || lower.endsWith('.jpeg'))
+        return 'image/jpeg';
+    if (lower.endsWith('.gif'))
+        return 'image/gif';
+    if (lower.endsWith('.webp'))
+        return 'image/webp';
+    if (lower.endsWith('.svg'))
+        return 'image/svg+xml';
+    if (lower.endsWith('.txt') || lower.endsWith('.log'))
+        return 'text/plain';
+    if (lower.endsWith('.json'))
+        return 'application/json';
+    return 'application/octet-stream';
+}
+export const attachToTicketToolConfig = {
+    title: 'Attach a file to a ticket',
+    description: 'Upload a file as an attachment on a ticket and return its markdown image-embed line + raw URL. The bytes come in as base64 (`contentBase64`) so this works without local FS access on the agent side. Set `embed=true` to also PATCH the ticket\'s description with the markdown line appended (idempotent only up to duplicate detection - re-running with the same file appends another copy). Use `altText` for accessibility / image alt-text; defaults to the filename. Mirrors `orboto.mjs attach`.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3),
+        filename: z.string().min(1).describe('Display filename, e.g. "graph-q3.png".'),
+        contentBase64: z.string().min(1).describe('File content, base64-encoded.'),
+        altText: z.string().optional().describe('Alt-text for the markdown image line. Defaults to filename.'),
+        embed: z.boolean().optional().describe('If true, also PATCH the ticket\'s description to append the markdown image line.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeAttachToTicketHandler(client) {
+    return async ({ ticketKey, filename, contentBase64, altText, embed }) => {
+        let arrayBuffer;
+        try {
+            // Buffer → fresh ArrayBuffer copy. The Blob ctor's BlobPart type
+            // wants `ArrayBufferView<ArrayBuffer>` and Node @types reject a
+            // raw Buffer / Uint8Array because their backing buffer is the
+            // wider `ArrayBufferLike`. Copying the bytes into a fresh
+            // ArrayBuffer satisfies the constraint without losing data.
+            const buf = Buffer.from(contentBase64, 'base64');
+            arrayBuffer = new ArrayBuffer(buf.byteLength);
+            new Uint8Array(arrayBuffer).set(buf);
+        }
+        catch {
+            throw new Error('contentBase64 is not valid base64.');
+        }
+        if (arrayBuffer.byteLength === 0) {
+            throw new Error('contentBase64 decoded to 0 bytes - refuse to upload an empty file.');
+        }
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const form = new FormData();
+        form.append('file', new Blob([arrayBuffer], { type: mimetypeFor(filename) }), filename);
+        const att = await client.postMultipart(`/tickets/${ticket.id}/attachments`, form);
+        const alt = altText ?? att.filename;
+        const markdown = `![${alt}](${att.downloadUrl})`;
+        let embedded = false;
+        if (embed === true) {
+            // Read the current description first - the PATCH replaces, not
+            // appends, so we have to construct the new body.
+            const current = await client.get(`/projects/${ticket.projectId}/tickets/${ticket.id}`);
+            const existing = current.description ?? '';
+            const next = existing ? `${existing}\n\n${markdown}` : markdown;
+            await client.patch(`/projects/${ticket.projectId}/tickets/${ticket.id}`, { description: next });
+            embedded = true;
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Attached ${att.filename} (${Math.round(att.sizeBytes / 1024)} KB) to [${ticket.ticketKey}]${embedded ? ' and embedded in description' : ''}.\n${markdown}`,
+                }],
+            structuredContent: {
+                ticketKey: ticket.ticketKey,
+                attachmentId: att.id,
+                filename: att.filename,
+                sizeBytes: att.sizeBytes,
+                mimetype: att.mimetype,
+                url: att.downloadUrl,
+                markdown,
+                embedded,
+            },
+        };
+    };
+}