@orboto/mcp 0.178.0

package/dist/tools/review-policy.js

@@ -0,0 +1,105 @@
+/**
+ * ORB-1615 - structural review policy tools.
+ *
+ *   - orboto_review_fingerprint     - normalize + hash raw diff text into a
+ *                                     canonical fingerprint (+ real size
+ *                                     metrics), server-side (one algorithm,
+ *                                     not one per client).
+ *   - orboto_review_policy_check    - the consult-before-invoking-a-model
+ *     call: what risk level does this ticket carry, and (if a fingerprint
+ *     is supplied) is there already a valid approval for THIS exact diff.
+ *   - orboto_review_approval_record - record an approve/reject decision
+ *     against a ticket's diff fingerprint.
+ *
+ * Rule CONFIGURATION (path pattern / deliveryMode / size -> risk level)
+ * stays out of the MCP surface, same call as approval_policies' CRUD in
+ * tools/approvals.ts: it's project-settings admin config, not something an
+ * autonomous agent tool should expose.
+ */
+import { z } from 'zod';
+import { resolveTicketByKey } from './shared.js';
+// ---------------------------------------------------------------------------
+// orboto_review_fingerprint
+// ---------------------------------------------------------------------------
+export const reviewFingerprintToolConfig = {
+    title: 'Compute a canonical diff fingerprint',
+    description: 'Normalize + hash raw diff text (e.g. `git diff` output) into a canonical fingerprint, server-side - so every agent hashes the same way instead of each fudging its own. Whitespace-only / blank-line-only edits and file ORDER are invisible to the hash (an approval survives a reflow); any real content change, a permission/mode change, or an added/removed/renamed file is NOT (an approval never survives those). Also returns real size metrics (filesChanged/linesAdded/linesRemoved/paths) derived from the same diff. Use the returned `fingerprint` with `orboto_review_policy_check` and `orboto_review_approval_record`.',
+    inputSchema: z.object({
+        diff: z.string().min(1).describe('Raw unified diff text, e.g. the output of `git diff` / `git diff --no-color`.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeReviewFingerprintHandler(client) {
+    return async ({ diff }) => {
+        const result = await client.post('/review-policy/fingerprint', { diff });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Fingerprint ${result.fingerprint} (${result.algo}) - ${result.filesChanged} file(s), +${result.linesAdded}/-${result.linesRemoved}.`,
+                }],
+            structuredContent: result,
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_review_policy_check
+// ---------------------------------------------------------------------------
+export const reviewPolicyCheckToolConfig = {
+    title: 'Check a ticket\'s review policy before invoking a reviewer',
+    description: 'Consult a ticket\'s structural review policy BEFORE spawning a review session or invoking a model. Called with no diff context (the common case, right after picking up a ticket) it resolves the per-ticket override or a deliveryMode-only rule; passing `paths`/`linesChanged` (from `orboto_review_fingerprint`) additionally matches path/size-scoped rules and, if `fingerprint` is passed too, checks whether a VALID approval already covers this exact diff - so a low-risk ticket, or one already reviewed at this fingerprint, can close without spawning a reviewer. `riskLevel: "required"` with `source: "fail_safe"` means the policy engine itself errored - treat that as "review required", never as "no review needed".',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3).describe('Ticket key, e.g. ORB-42.'),
+        fingerprint: z.string().min(8).optional().describe('From orboto_review_fingerprint - checks for an existing valid approval at this exact diff.'),
+        paths: z.array(z.string()).max(500).optional().describe('Changed file paths (from orboto_review_fingerprint) - refines the match against path-scoped rules.'),
+        linesChanged: z.number().int().nonnegative().optional().describe('Total changed lines (linesAdded + linesRemoved) - refines the match against size-scoped rules.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeReviewPolicyCheckHandler(client) {
+    return async ({ ticketKey, fingerprint, paths, linesChanged }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const decision = await client.post(`/projects/${ticket.projectId}/tickets/${ticket.id}/review-policy/check`, { fingerprint, paths, linesChanged });
+        const parts = [`[${ticket.ticketKey}] review risk: ${decision.riskLevel} (${decision.source}${decision.matchedRuleName ? `: "${decision.matchedRuleName}"` : ''}).`];
+        if (decision.evaluationError)
+            parts.push(`Policy engine error - treat as required: ${decision.evaluationError}`);
+        if (decision.fingerprintChecked) {
+            parts.push(decision.hasValidApproval ? 'A valid approval already covers this exact diff.' : 'No valid approval for this diff - the fingerprint changed or none was recorded.');
+        }
+        return {
+            content: [{ type: 'text', text: parts.join(' ') }],
+            structuredContent: { ticketKey: ticket.ticketKey, ...decision },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_review_approval_record
+// ---------------------------------------------------------------------------
+export const reviewApprovalRecordToolConfig = {
+    title: 'Record a review decision against a diff fingerprint',
+    description: 'Record your review verdict (approve/reject) against a ticket\'s diff fingerprint (from orboto_review_fingerprint). A recorded APPROVAL is reusable: orboto_review_policy_check reports it as valid for the SAME fingerprint, letting a later finish/close skip re-review - until the diff changes, which produces a different fingerprint and naturally stops matching. Requires ticket:record_review_approval.',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3).describe('Ticket key, e.g. ORB-42.'),
+        fingerprint: z.string().min(8).describe('From orboto_review_fingerprint.'),
+        decision: z.enum(['approved', 'rejected']).describe('Your review verdict.'),
+        note: z.string().max(2000).optional().describe('Optional review comment.'),
+        filesChanged: z.number().int().nonnegative().optional(),
+        linesAdded: z.number().int().nonnegative().optional(),
+        linesRemoved: z.number().int().nonnegative().optional(),
+        paths: z.array(z.string()).max(500).optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeReviewApprovalRecordHandler(client) {
+    return async (args) => {
+        const ticket = await resolveTicketByKey(client, args.ticketKey);
+        const { ticketKey: _ticketKey, ...body } = args;
+        const approval = await client.post(`/projects/${ticket.projectId}/tickets/${ticket.id}/review-approvals`, body);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Recorded ${approval.decision} on [${ticket.ticketKey}] for fingerprint ${approval.fingerprint}.`,
+                }],
+            structuredContent: { ticketKey: ticket.ticketKey, approval: approval },
+        };
+    };
+}

package/dist/tools/review-policy.test.js

@@ -0,0 +1,71 @@
+/**
+ * ORB-1615 - `orboto_review_fingerprint` / `orboto_review_policy_check` /
+ * `orboto_review_approval_record` unit tests.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeReviewFingerprintHandler, makeReviewPolicyCheckHandler, makeReviewApprovalRecordHandler, } from './review-policy.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 };
+describe('orboto_review_fingerprint', () => {
+    it('computes a fingerprint + size metrics from raw diff text', async () => {
+        const calls = stub([{ json: { fingerprint: 'abc123', algo: 'sha256-diff-v1', filesChanged: 1, linesAdded: 1, linesRemoved: 1, paths: ['src/foo.ts'] } }]);
+        const res = await makeReviewFingerprintHandler(client)({ diff: 'diff --git a/src/foo.ts b/src/foo.ts\n-a\n+b\n' });
+        expect(calls[0].url).toContain('/review-policy/fingerprint');
+        expect(calls[0].method).toBe('POST');
+        expect(res.structuredContent?.fingerprint).toBe('abc123');
+        expect(res.content[0].text).toContain('abc123');
+    });
+});
+describe('orboto_review_policy_check', () => {
+    it('reports the resolved risk level and whether a valid approval exists', async () => {
+        const decision = {
+            riskLevel: 'required', source: 'rule', matchedRuleName: 'api routes', evaluationError: null,
+            fingerprintChecked: true, hasValidApproval: false, latestApproval: null,
+        };
+        const calls = stub([{ json: PROJ }, { json: TICKET }, { json: decision }]);
+        const res = await makeReviewPolicyCheckHandler(client)({ ticketKey: 'ACME-1', fingerprint: 'abc123' });
+        const check = calls.find((c) => c.method === 'POST');
+        expect(check?.url).toContain('/projects/p1/tickets/t1/review-policy/check');
+        expect(check?.body).toMatchObject({ fingerprint: 'abc123' });
+        expect(res.structuredContent).toMatchObject({ riskLevel: 'required', hasValidApproval: false });
+        expect(res.content[0].text).toContain('required');
+        expect(res.content[0].text).toContain('No valid approval');
+    });
+    it('surfaces the fail-safe direction distinctly when the policy engine errored', async () => {
+        const decision = {
+            riskLevel: 'required', source: 'fail_safe', matchedRuleName: null, evaluationError: 'db timeout',
+            fingerprintChecked: false, hasValidApproval: false, latestApproval: null,
+        };
+        stub([{ json: PROJ }, { json: TICKET }, { json: decision }]);
+        const res = await makeReviewPolicyCheckHandler(client)({ ticketKey: 'ACME-1' });
+        expect(res.content[0].text).toContain('treat as required');
+    });
+});
+describe('orboto_review_approval_record', () => {
+    it('records an approval against a fingerprint', async () => {
+        const approval = { id: 'ra1', ticketId: 't1', fingerprint: 'abc123', decision: 'approved', reviewerLabel: 'reviewer@orboto.test', note: null, revokedAt: null, createdAt: '2026-01-01T00:00:00Z' };
+        const calls = stub([{ json: PROJ }, { json: TICKET }, { json: approval }]);
+        const res = await makeReviewApprovalRecordHandler(client)({ ticketKey: 'ACME-1', fingerprint: 'abc123', decision: 'approved', note: 'looks good' });
+        const record = calls.find((c) => c.method === 'POST' && c.url.includes('review-approvals'));
+        expect(record?.body).toMatchObject({ fingerprint: 'abc123', decision: 'approved', note: 'looks good' });
+        // ticketKey must NOT leak into the request body sent to the API - the
+        // route resolves the ticket from the URL, not the payload.
+        expect(record?.body).not.toHaveProperty('ticketKey');
+        expect(res.content[0].text).toContain('approved');
+    });
+});

package/dist/tools/search.js

@@ -0,0 +1,78 @@
+/**
+ * ORB-244 Phase B - `orboto_search`.
+ *
+ * Unified full-text search across tickets, comments, and docs. Maps
+ * to the existing `/search` route (Phase 21 global search) which
+ * already respects PBAC visibility (private tickets, internal
+ * comments, doc ACL).
+ *
+ * ORB-272: /search is cursor-paginated. Response shape is
+ * `{items, nextCursor, total}`. We surface `total` so the model
+ * knows how many hits exist globally, but don't expose `cursor` on
+ * the tool input - repeat MCP tool calls to walk a search cursor is
+ * an awkward UX. Users who need to see more narrow the query or
+ * open the full-page /search in the web UI.
+ */
+import { z } from 'zod';
+import { resolveProjectByKey } from './shared.js';
+export const searchToolConfig = {
+    title: 'Search across orboto',
+    description: 'Full-text search across tickets, comments, and docs. Honours the caller\'s visibility - private tickets and internal comments never appear unless the caller can already see them. Recall (ORB-1695): when the strict all-terms pass finds nothing, the server automatically retries with an OR-relaxed pass plus semantic (embedding) recall - the response\'s `pass` field says which pass produced the hits, and relaxed-pass hits deserve a skeptical read (they matched SOME terms or only the meaning, not all terms). Still prefer a single distinctive STABLE token (file/component/error-string fragment like "AdminCodesPage") and search the SYMPTOM, not your intended fix.',
+    inputSchema: z.object({
+        query: z.string().min(1).describe('Search terms, e.g. "queue worker retry".'),
+        types: z.array(z.enum(['ticket', 'comment', 'doc'])).optional()
+            .describe('Restrict to entity types. Omit for all.'),
+        projectKey: z.string().optional().describe('Restrict to one project.'),
+        limit: z.number().int().min(1).max(50).default(15),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeSearchHandler(client) {
+    return async (input) => {
+        const qs = new URLSearchParams();
+        qs.set('q', input.query);
+        qs.set('limit', String(input.limit ?? 15));
+        if (input.types && input.types.length > 0)
+            qs.set('types', input.types.join(','));
+        if (input.projectKey) {
+            const project = await resolveProjectByKey(client, input.projectKey);
+            qs.set('projectId', project.id);
+        }
+        const res = await client.get(`/search?${qs}`);
+        const shown = res.items.length;
+        const hasMore = !!res.nextCursor && res.total > shown;
+        const headerHint = hasMore ? ` (showing ${shown} of ${res.total})` : '';
+        const relaxedNote = res.pass === 'relaxed'
+            ? ' [relaxed pass: no row matched ALL terms - these matched some terms or the meaning]'
+            : '';
+        const text = res.items.length === 0
+            ? `No hits for "${input.query}".`
+            : `Hits${headerHint}${relaxedNote}:\n\n` + res.items.map((h) => {
+                const tag = h.type.toUpperCase();
+                // ORB-1084 - non-ticket hits carry the FULL id: the truncated
+                // form was unusable as input for the doc write tools.
+                const ident = h.ticketKey ?? h.id;
+                const project = h.projectName ? ` · ${h.projectName}` : '';
+                return `- [${tag} ${ident}${project}] ${h.title}\n  ${h.excerpt}`;
+            }).join('\n\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: {
+                total: res.total,
+                shown,
+                hasMore,
+                pass: res.pass ?? 'strict',
+                hits: res.items.map((h) => ({
+                    type: h.type,
+                    id: h.id, // ORB-1084 - full id, usable as write-tool input
+                    title: h.title,
+                    excerpt: h.excerpt,
+                    ticketKey: h.ticketKey ?? null,
+                    projectName: h.projectName,
+                    spaceName: h.spaceName,
+                    url: h.url,
+                })),
+            },
+        };
+    };
+}