@orboto/mcp 0.178.0

package/dist/tools/set-parent.test.js

@@ -0,0 +1,115 @@
+/**
+ * ORB-799 - `orboto_set_parent` unit tests.
+ *
+ * Covers: re-parent happy path, detach (parentTicketKey=null),
+ * cross-project rejection, self-parent rejection, API cycle rejection.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeSetParentHandler } from './set-parent.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 () => '',
+        };
+    });
+    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: 'Child', status: 'TODO', statusName: 'To Do', statusCategory: 'todo',
+    type: 'task', priority: 'normal', estimatedTimeMinutes: 0, dueDate: null, isPrivate: false,
+};
+const PARENT = {
+    ...TICKET, id: 't10', ticketKey: 'ACME-10', ticketNumber: 10, title: 'Parent epic', type: 'epic',
+};
+describe('orboto_set_parent', () => {
+    it('happy path: re-parents and PATCHes parentTicketId', async () => {
+        const calls = stub([
+            { json: PROJ }, // ticket: by-key project
+            { json: TICKET }, // ticket: by-key ticket
+            { json: PROJ }, // parent: by-key project
+            { json: PARENT }, // parent: by-key ticket
+            { json: { ...TICKET, parentTicketId: 't10' } }, // PATCH
+        ]);
+        const res = await makeSetParentHandler(client)({
+            ticketKey: 'ACME-1', parentTicketKey: 'ACME-10',
+        });
+        expect(calls[4]).toMatchObject({
+            method: 'PATCH',
+            url: 'https://orboto.example.com/projects/p1/tickets/t1',
+            body: { parentTicketId: 't10' },
+        });
+        expect(res.structuredContent).toMatchObject({
+            ticketKey: 'ACME-1',
+            parentTicketKey: 'ACME-10',
+            parentTicketId: 't10',
+        });
+    });
+    it('detach: parentTicketKey=null PATCHes parentTicketId=null', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: { ...TICKET, parentTicketId: null } },
+        ]);
+        await makeSetParentHandler(client)({
+            ticketKey: 'ACME-1', parentTicketKey: null,
+        });
+        expect(calls[2]).toMatchObject({
+            method: 'PATCH',
+            body: { parentTicketId: null },
+        });
+    });
+    it('refuses cross-project parenting', async () => {
+        const OTHER_PROJ = { ...PROJ, id: 'p2', key: 'OTHER' };
+        stub([
+            { json: PROJ }, // ACME-1 project
+            { json: TICKET }, // ACME-1 ticket (projectId p1)
+            { json: OTHER_PROJ }, // OTHER-5 project
+            { json: { ...PARENT, projectId: 'p2', ticketKey: 'OTHER-5' } }, // OTHER-5 ticket
+        ]);
+        await expect(makeSetParentHandler(client)({
+            ticketKey: 'ACME-1', parentTicketKey: 'OTHER-5',
+        })).rejects.toThrow(/Cross-project parenting/);
+    });
+    it('refuses self-parenting', async () => {
+        stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: PROJ },
+            { json: TICKET }, // same ticket
+        ]);
+        await expect(makeSetParentHandler(client)({
+            ticketKey: 'ACME-1', parentTicketKey: 'ACME-1',
+        })).rejects.toThrow(/cannot be its own parent/);
+    });
+    it('translates a 400 from the PATCH (API cycle-detection) into a clear message', async () => {
+        stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: PROJ },
+            { json: PARENT },
+            { ok: false, status: 400, json: { error: 'cycle detected' } },
+        ]);
+        await expect(makeSetParentHandler(client)({
+            ticketKey: 'ACME-1', parentTicketKey: 'ACME-10',
+        })).rejects.toThrow(/Re-parent rejected by the API/);
+    });
+});

package/dist/tools/shared.js

@@ -0,0 +1,226 @@
+import { OrbotoApiError } from '../orboto-client.js';
+export async function resolveProjectByKey(client, key) {
+    try {
+        return await client.get(`/projects/by-key/${encodeURIComponent(key)}`);
+    }
+    catch (err) {
+        if (err instanceof OrbotoApiError && err.status === 404) {
+            throw new Error(`Project "${key}" not found (or not visible to your account).`);
+        }
+        throw err;
+    }
+}
+/**
+ * ORB-1699 - the ONE agent-facing list-row builder. A list call is a
+ * decision aid ("which of these do I open?"); the default row carries
+ * exactly what that decision + the filters read back. `verbose: true`
+ * restores the full shape (uuid, labels, minutes, ingestion signal).
+ * list_tickets, my_tickets and query all consume THIS builder - trimming
+ * one tool and leaving the siblings fat is the class-not-instance
+ * failure the workspace rules warn about.
+ */
+export function agentTicketListRow(t, verbose = false) {
+    if (verbose) {
+        return {
+            // ORB-1179 - uuid for write tools that want it without a lookup.
+            id: t.id,
+            key: t.ticketKey,
+            title: t.title,
+            status: t.statusName ?? t.status,
+            statusCategory: t.statusCategory ?? null,
+            priority: t.priority,
+            type: t.type,
+            dueDate: t.dueDate ?? null,
+            assigneeNames: (t.assignees ?? []).map((a) => a.fullName || a.email),
+            labels: (t.labels ?? []).map((l) => l.name),
+            estimatedTimeMinutes: t.estimatedTimeMinutes,
+            loggedMinutes: t.loggedMinutes ?? 0,
+            milestoneName: t.milestoneName ?? null,
+            createdAt: t.createdAt ?? null,
+            updatedAt: t.updatedAt ?? null,
+            ...(t.waitingForGitIngestion ? { waitingForGitIngestion: true } : {}),
+        };
+    }
+    // Lean row: fields at their DEFAULT value are omitted entirely - a
+    // reader treats absence as "task / normal / no due date / unassigned".
+    // The list is a decision aid; the full picture is one get_ticket away.
+    const assigneeNames = (t.assignees ?? []).map((a) => a.fullName || a.email);
+    return {
+        key: t.ticketKey,
+        title: t.title,
+        statusCategory: t.statusCategory ?? null,
+        ...(t.priority && t.priority !== 'normal' ? { priority: t.priority } : {}),
+        ...(t.type && t.type !== 'task' ? { type: t.type } : {}),
+        ...(t.dueDate ? { dueDate: t.dueDate } : {}),
+        ...(assigneeNames.length > 0 ? { assigneeNames } : {}),
+        // ORB-1605 - only present when it fires; absent costs zero chars.
+        ...(t.waitingForGitIngestion ? { waitingForGitIngestion: true } : {}),
+    };
+}
+/**
+ * Resolve a `PROJ-123` ticket key to a fully-hydrated ticket row.
+ * Splits on the first `-` - project keys are upper-case alphanumerics
+ * (max 20 chars) and never contain `-`, so the split is unambiguous.
+ */
+export async function resolveTicketByKey(client, ticketKey) {
+    const idx = ticketKey.indexOf('-');
+    if (idx <= 0) {
+        throw new Error(`Invalid ticket key "${ticketKey}" - expected format "PROJ-123".`);
+    }
+    const projectKey = ticketKey.slice(0, idx);
+    const numberPart = ticketKey.slice(idx + 1);
+    const project = await resolveProjectByKey(client, projectKey);
+    try {
+        return await client.get(`/projects/${project.id}/tickets/by-key/${encodeURIComponent(numberPart)}`);
+    }
+    catch (err) {
+        if (err instanceof OrbotoApiError && err.status === 404) {
+            throw new Error(`Ticket "${ticketKey}" not found in project "${project.key}".`);
+        }
+        throw err;
+    }
+}
+/** Shorten a ticket row to the single-line summary used by list tools. */
+export function ticketLine(t) {
+    const parts = [];
+    if (t.ticketKey)
+        parts.push(`[${t.ticketKey}]`);
+    parts.push(t.title);
+    parts.push(`(${t.statusName ?? t.status})`);
+    if (t.priority && t.priority !== 'normal')
+        parts.push(`<${t.priority}>`);
+    if (t.assignees && t.assignees.length > 0) {
+        parts.push(`→ ${t.assignees.map((a) => a.fullName || a.email).join(', ')}`);
+    }
+    // ORB-1605 - flag a ticket that's genuinely just waiting on stalled
+    // commit/PR ingestion, not a ticket someone forgot to close.
+    if (t.waitingForGitIngestion)
+        parts.push('[waiting on Git ingestion]');
+    return parts.join(' ');
+}
+// ---------------------------------------------------------------------------
+// ORB-1252 / ORB-1283 / ORB-1609 - the agent-instance token.
+//
+// One MCP server process = one agent instance. Every surface that scopes work
+// to an instance (timers, and since ORB-1609 work-session leases) MUST derive
+// the token the same way, or the same agent ends up in two lanes: a claim
+// starting a timer in lane A while its work session holds the lease in lane B
+// is precisely the class of bug ORB-1603 had to paper over.
+//
+// A per-process random UUID rather than the PID: PIDs are recycled by the OS,
+// so a fresh process could inherit a recycled PID and adopt a previous
+// instance's stale timer or lease.
+// ---------------------------------------------------------------------------
+import { randomUUID } from 'node:crypto';
+const MCP_PROCESS_INSTANCE = `mcp-${randomUUID()}`;
+/** Precedence: explicit caller-supplied token > per-connection MCP session id
+ *  (distinct per client even on a shared HTTP server) > per-process id (stdio). */
+export function mcpInstanceToken(explicit, extra) {
+    return explicit ?? (extra?.sessionId ? `mcp-${extra.sessionId}` : MCP_PROCESS_INSTANCE);
+}
+/** ORB-1753 - the caller's self-declared agent profile from the process
+ *  environment (stdio servers / runners). The api-key standing profile
+ *  (ORB-1751) already covers keys server-side; these env vars let a
+ *  keyless or per-process deployment declare without code. Explicit tool
+ *  inputs override. */
+export function envAgentProfile() {
+    const kind = process.env.ORBOTO_AGENT_KIND?.trim().toLowerCase();
+    const tier = process.env.ORBOTO_MODEL_TIER?.trim().toLowerCase();
+    return { ...(kind ? { agentKind: kind } : {}), ...(tier ? { modelTier: tier } : {}) };
+}
+/** ORB-1753 - append the resolved profile to a querystring. */
+export function applyAgentProfile(params, explicit) {
+    const env = envAgentProfile();
+    const kind = explicit?.agentKind ?? env.agentKind;
+    const tier = explicit?.modelTier ?? env.modelTier;
+    if (kind)
+        params.set('agentKind', kind);
+    if (tier)
+        params.set('modelTier', tier);
+}
+export function sizeBlockResult(err, verb) {
+    if (!(err instanceof OrbotoApiError) || err.status !== 422)
+        return null;
+    let parsed = {};
+    try {
+        parsed = JSON.parse(err.body);
+    }
+    catch { /* non-JSON body */ }
+    if (!parsed.sizeWarning)
+        return null;
+    const sw = parsed.sizeWarning;
+    const text = `⛔ ${verb} blocked - content is ${sw.chars} characters, over the ${sw.limit}-character hard limit.\n` +
+        `${sw.hint}\n` +
+        `Only if you are sure the length is genuinely necessary, retry the same call with allowOversize=true and an oversizeReason (10+ characters explaining why).`;
+    return {
+        content: [{ type: 'text', text }],
+        structuredContent: { blocked: true, sizeWarning: sw },
+        isError: true,
+    };
+}
+// ---------------------------------------------------------------------------
+// ORB-1826 - shared name-matching normaliser for free-text milestone /
+// label / status resolvers. An agent surface can hand back a name that
+// differs from the canonical DB row only in mechanically-recoverable ways:
+// leftover HTML entities from a rendering step upstream of the agent
+// (`QA &amp; Testing`), a different case, or extra/collapsed whitespace.
+// The workspace rule is normalise, never reject - if the canonical form is
+// mechanically derivable, derive it instead of rejecting the call.
+//
+// Resolution order for every call site that uses `resolveByName`: raw exact
+// match first (zero-cost, preserves today's behaviour for clean names),
+// then a UNIQUE normalised match, then the existing ambiguity error listing
+// the candidates.
+//
+// Twin: `apps/api/src/lib/name-normalize.ts` (same two functions, same
+// semantics). This package ships standalone to npm with a deliberately
+// minimal dependency set (MCP SDK + zod only) and does not depend on the
+// API workspace package, so the ~20 lines below are duplicated rather than
+// imported. The Go CLI (`cli/internal/cmd/normalize.go`) carries a third
+// copy for the same reason. Keep all three in sync.
+// ---------------------------------------------------------------------------
+const NAMED_HTML_ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+};
+/** Decode the five XML-safe named entities plus numeric character
+ *  references (`&#38;`, `&#x26;`). Intentionally NOT a general HTML
+ *  decoder - just enough to undo a stray HTML-escaping step. */
+export function decodeHtmlEntities(input) {
+    return input.replace(/&(#\d+|#x[0-9a-fA-F]+|[a-zA-Z]+);/g, (match, entity) => {
+        if (entity[0] === '#') {
+            const isHex = entity[1] === 'x' || entity[1] === 'X';
+            const codePoint = isHex ? parseInt(entity.slice(2), 16) : parseInt(entity.slice(1), 10);
+            return Number.isFinite(codePoint) && codePoint > 0 ? String.fromCodePoint(codePoint) : match;
+        }
+        const decoded = NAMED_HTML_ENTITIES[entity.toLowerCase()];
+        return decoded ?? match;
+    });
+}
+/** Canonical comparison key for a free-text name: HTML-entity-decoded,
+ *  trimmed, internal whitespace collapsed to a single space, casefolded. */
+export function normalizeName(input) {
+    return decodeHtmlEntities(input).trim().replace(/\s+/g, ' ').toLowerCase();
+}
+/**
+ * Resolve `ref` against `candidates` by name: exact (raw) match wins
+ * first; falls back to a unique normalised match. `ambiguous` is set
+ * whenever more than one candidate ties at either stage.
+ */
+export function resolveByName(candidates, ref, getName) {
+    const exactMatches = candidates.filter((c) => getName(c) === ref);
+    if (exactMatches.length === 1)
+        return { match: exactMatches[0], ambiguous: null };
+    if (exactMatches.length > 1)
+        return { match: null, ambiguous: exactMatches };
+    const normalizedRef = normalizeName(ref);
+    const normMatches = candidates.filter((c) => normalizeName(getName(c)) === normalizedRef);
+    if (normMatches.length === 1)
+        return { match: normMatches[0], ambiguous: null };
+    if (normMatches.length > 1)
+        return { match: null, ambiguous: normMatches };
+    return { match: null, ambiguous: null };
+}

package/dist/tools/shared.test.js

@@ -0,0 +1,169 @@
+/**
+ * ORB-244 Phase B - key-resolver helpers.
+ *
+ * The two-step ticket resolution (project key → project UUID →
+ * ticket) is the most reused code path in the tool suite, so
+ * exercising the edge cases here beats duplicating them in every
+ * tool test.
+ */
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { resolveProjectByKey, resolveTicketByKey, ticketLine, normalizeName, resolveByName } from './shared.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function sequence(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');
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: 'OK',
+            json: async () => r.json ?? {},
+            text: async () => r.text ?? '',
+        };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+describe('resolveProjectByKey', () => {
+    it('returns the project on success', async () => {
+        sequence([{ json: { id: 'p1', key: 'ACME', name: 'Acme', description: null, status: 'active' } }]);
+        const p = await resolveProjectByKey(client, 'acme');
+        expect(p.key).toBe('ACME');
+    });
+    it('rewrites a 404 into a helpful message', async () => {
+        sequence([{ ok: false, status: 404, text: '{"error":"Project not found"}' }]);
+        await expect(resolveProjectByKey(client, 'NOPE')).rejects.toThrow(/Project "NOPE" not found/);
+    });
+    it('URL-encodes the key', async () => {
+        const calls = sequence([{ json: { id: 'p1', key: 'AB CD', name: 'x', description: null, status: 'active' } }]);
+        await resolveProjectByKey(client, 'AB CD');
+        expect(calls[0]).toBe('https://orboto.example.com/projects/by-key/AB%20CD');
+    });
+});
+describe('resolveTicketByKey', () => {
+    it('splits on the first dash, resolves project then ticket', async () => {
+        const calls = sequence([
+            { json: { id: 'p1', key: 'ACME', name: 'Acme', description: null, status: 'active' } },
+            { json: { id: 't1', projectId: 'p1', ticketKey: 'ACME-42', title: 'Fix it' } },
+        ]);
+        const t = await resolveTicketByKey(client, 'ACME-42');
+        expect(t.ticketKey).toBe('ACME-42');
+        expect(calls[0]).toContain('/projects/by-key/ACME');
+        expect(calls[1]).toContain('/projects/p1/tickets/by-key/42');
+    });
+    it('rejects malformed keys (no dash)', async () => {
+        await expect(resolveTicketByKey(client, 'PLAIN')).rejects.toThrow(/expected format "PROJ-123"/);
+    });
+    it('rewrites a 404 into a ticket-scoped message', async () => {
+        sequence([
+            { json: { id: 'p1', key: 'ACME', name: 'Acme', description: null, status: 'active' } },
+            { ok: false, status: 404, text: 'not found' },
+        ]);
+        await expect(resolveTicketByKey(client, 'ACME-999')).rejects.toThrow(/Ticket "ACME-999" not found in project "ACME"/);
+    });
+});
+describe('ticketLine', () => {
+    it('renders key, title, status, priority, assignees', () => {
+        const line = ticketLine({
+            id: 't1', projectId: 'p1', milestoneId: null,
+            ticketKey: 'ACME-1', ticketNumber: 1,
+            title: 'Login broken',
+            status: 'IN_PROGRESS', statusName: 'In Progress',
+            type: 'bug', priority: 'high',
+            estimatedTimeMinutes: 0, dueDate: null, isPrivate: false,
+            assignees: [{ id: 'u1', email: 'a@b.c', fullName: 'Ada Lovelace' }],
+        });
+        expect(line).toBe('[ACME-1] Login broken (In Progress) <high> → Ada Lovelace');
+    });
+    it('omits priority marker when normal, omits assignee clause when none', () => {
+        const line = ticketLine({
+            id: 't1', projectId: 'p1', milestoneId: null,
+            ticketKey: 'ACME-2', ticketNumber: 2,
+            title: 'Docs update',
+            status: 'TODO', statusName: 'To Do',
+            type: 'task', priority: 'normal',
+            estimatedTimeMinutes: 0, dueDate: null, isPrivate: false,
+        });
+        expect(line).toBe('[ACME-2] Docs update (To Do)');
+    });
+    // ORB-1605 - flags the stalled-ingestion signal in the one-line summary.
+    it('appends the waiting-on-ingestion marker when waitingForGitIngestion is true', () => {
+        const line = ticketLine({
+            id: 't1', projectId: 'p1', milestoneId: null,
+            ticketKey: 'ACME-3', ticketNumber: 3,
+            title: 'Docs change',
+            status: 'IN_REVIEW', statusName: 'In Review',
+            type: 'task', priority: 'normal',
+            estimatedTimeMinutes: 0, dueDate: null, isPrivate: false,
+            waitingForGitIngestion: true,
+        });
+        expect(line).toBe('[ACME-3] Docs change (In Review) [waiting on Git ingestion]');
+    });
+    it('omits the marker when waitingForGitIngestion is false or absent', () => {
+        const line = ticketLine({
+            id: 't1', projectId: 'p1', milestoneId: null,
+            ticketKey: 'ACME-4', ticketNumber: 4,
+            title: 'Docs change',
+            status: 'IN_REVIEW', statusName: 'In Review',
+            type: 'task', priority: 'normal',
+            estimatedTimeMinutes: 0, dueDate: null, isPrivate: false,
+            waitingForGitIngestion: false,
+        });
+        expect(line).toBe('[ACME-4] Docs change (In Review)');
+    });
+});
+// ORB-1826 - production MCP error log showed `Milestone "QA &amp; Testing"
+// not found` for a milestone literally named "QA & Testing": some upstream
+// surface handed the agent an HTML-escaped name. "Normalise, never reject."
+describe('normalizeName', () => {
+    it('decodes the five XML-safe named entities', () => {
+        expect(normalizeName('QA &amp; Testing')).toBe('qa & testing');
+        expect(normalizeName('A &lt;b&gt; &quot;C&quot; &apos;D&apos;')).toBe(`a <b> "c" 'd'`);
+    });
+    it('decodes decimal and hex numeric character references', () => {
+        expect(normalizeName('Caf&#233;')).toBe('café');
+        expect(normalizeName('Caf&#xe9;')).toBe('café');
+    });
+    it('trims and collapses internal whitespace', () => {
+        expect(normalizeName('  QA   &   Testing  ')).toBe('qa & testing');
+    });
+    it('leaves an unrecognised entity-shaped sequence untouched (case-folded)', () => {
+        expect(normalizeName('R&D Sprint')).toBe('r&d sprint');
+    });
+});
+describe('resolveByName', () => {
+    const rows = [
+        { id: 'm1', name: 'QA & Testing' },
+        { id: 'm2', name: 'Launch Readiness' },
+    ];
+    it('matches the raw exact name with zero normalisation', () => {
+        const { match, ambiguous } = resolveByName(rows, 'QA & Testing', (r) => r.name);
+        expect(match?.id).toBe('m1');
+        expect(ambiguous).toBeNull();
+    });
+    it('falls back to a unique normalised match for an HTML-escaped name', () => {
+        const { match, ambiguous } = resolveByName(rows, 'QA &amp; Testing', (r) => r.name);
+        expect(match?.id).toBe('m1');
+        expect(ambiguous).toBeNull();
+    });
+    it('falls back to a unique normalised match for case/whitespace variants', () => {
+        expect(resolveByName(rows, 'qa & testing', (r) => r.name).match?.id).toBe('m1');
+        expect(resolveByName(rows, '  QA   &   Testing  ', (r) => r.name).match?.id).toBe('m1');
+    });
+    it('returns no match for an unknown name', () => {
+        const { match, ambiguous } = resolveByName(rows, 'Nonexistent', (r) => r.name);
+        expect(match).toBeNull();
+        expect(ambiguous).toBeNull();
+    });
+    it('reports ambiguity when two names normalise to the same key', () => {
+        const dup = [...rows, { id: 'm3', name: 'qa &amp; testing' }];
+        const { match, ambiguous } = resolveByName(dup, 'QA &amp; Testing', (r) => r.name);
+        expect(match).toBeNull();
+        expect(ambiguous?.map((r) => r.id).sort()).toEqual(['m1', 'm3']);
+    });
+});

package/dist/tools/similar-projection.js

@@ -0,0 +1,30 @@
+/**
+ * ORB-1693 - the agent-facing projection of a duplicate-warning entry.
+ *
+ * Measured: `similarWarnings` was 76% of the entire create_ticket response
+ * volume (~329k tokens over the corpus), and most of each entry was
+ * decision-irrelevant: a CSS hex colour, a UUID next to the key, a
+ * redundant statusName next to statusCategory, and similarity at 15
+ * decimal places. The agent decision needs exactly:
+ *
+ *   { ticketKey, title, statusCategory, similarity (2dp), relation }
+ *
+ * The rich shape stays on the REST response for the web UI - this trims
+ * only what agent surfaces emit. Same projection everywhere a warning
+ * reaches an agent: create_ticket, the duplicate-block 409, check_similar
+ * (mirrored in the chat registry + skill wrapper - keep them in sync).
+ */
+export function trimSimilarEntry(w) {
+    return {
+        // Keys over UUIDs (repo rule); the short-id fallback only exists for
+        // pre-backfill rows that never got a key.
+        ticketKey: w.ticketKey ?? w.id.slice(0, 8),
+        title: w.title,
+        statusCategory: w.statusCategory ?? null,
+        similarity: Math.round(w.similarity * 100) / 100,
+        relation: w.relation ?? null,
+    };
+}
+export function trimSimilarEntries(list) {
+    return (list ?? []).map(trimSimilarEntry);
+}

package/dist/tools/ticket-attachments.js

@@ -0,0 +1,131 @@
+/**
+ * ORB-1455 - read + view ticket attachments from MCP.
+ *
+ * Every agent surface could WRITE attachments (orboto_attach_to_ticket) but
+ * none could READ them: an agent working a ticket could not tell the ticket
+ * HAD files, let alone SEE an attached screenshot. These two tools close that
+ * hole (orboto_get_ticket also gains an `attachments` array):
+ *
+ *   - orboto_list_ticket_attachments - thin wrapper on the ticket-attachment
+ *     list route; mirrors orboto_list_doc_attachments (ORB-914).
+ *   - orboto_get_attachment - fetch an attachment's bytes via the new
+ *     authenticated base64 route and return them to the model:
+ *       * images (image/*)      -> an MCP image content block so the model
+ *                                  actually VIEWS the screenshot, plus a text
+ *                                  line with filename/size.
+ *       * everything else       -> a text block with metadata + the base64
+ *                                  (small files) or a pointer to the skill
+ *                                  download shortcut (large files).
+ *     Works for ticket/doc/comment attachments - the id is global.
+ */
+import { z } from 'zod';
+import { resolveTicketByKey } from './shared.js';
+/** Max bytes we inline into a tool result. Screenshots are well under this;
+ *  anything larger is pointed at the skill download shortcut so we don't
+ *  bloat the model's context with a multi-MB base64 blob. */
+const MAX_INLINE_BYTES = 5 * 1024 * 1024;
+function isImage(mimetype) {
+    return mimetype.startsWith('image/');
+}
+// ---------------------------------------------------------------------------
+// orboto_list_ticket_attachments
+// ---------------------------------------------------------------------------
+export const listTicketAttachmentsToolConfig = {
+    title: 'List attachments on a ticket',
+    description: 'Return a ticket\'s attachments newest-first, with each attachment\'s id, filename, content type, size, and stable download URL. Use the returned id with orboto_get_attachment to actually view an image or fetch the bytes. Empty list = no attachments. Input is the ticket key like "ACME-42".',
+    inputSchema: z.object({
+        ticketKey: z.string().min(3).describe('Ticket key like "ACME-42".'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeListTicketAttachmentsHandler(client) {
+    return async ({ ticketKey }) => {
+        const ticket = await resolveTicketByKey(client, ticketKey);
+        const rows = await client.get(`/tickets/${ticket.id}/attachments`);
+        if (rows.length === 0) {
+            return {
+                content: [{ type: 'text', text: `No attachments on [${ticket.ticketKey}].` }],
+                structuredContent: { ticketKey: ticket.ticketKey, attachments: [] },
+            };
+        }
+        const lines = rows.map((r) => {
+            const url = r.downloadUrl ?? `/attachments/${r.id}`;
+            const kb = Math.round(r.sizeBytes / 1024);
+            return `- ${r.filename}  (${kb} KB, ${r.contentType})  id=${r.id} → ${url}`;
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Attachments on [${ticket.ticketKey}]:\n${lines.join('\n')}\n\nUse orboto_get_attachment with an id to view an image or fetch bytes.`,
+                }],
+            structuredContent: {
+                ticketKey: ticket.ticketKey,
+                attachments: rows.map((r) => ({
+                    id: r.id,
+                    filename: r.filename,
+                    contentType: r.contentType,
+                    sizeBytes: r.sizeBytes,
+                    uploadedAt: r.uploadedAt ?? null,
+                    uploadedBy: r.uploadedBy ?? null,
+                    downloadUrl: r.downloadUrl ?? `/attachments/${r.id}`,
+                })),
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_get_attachment
+// ---------------------------------------------------------------------------
+export const getAttachmentToolConfig = {
+    title: 'View or fetch an attachment\'s bytes',
+    description: 'Fetch a single attachment by its id (from orboto_list_ticket_attachments, orboto_get_ticket, or orboto_list_doc_attachments) and return its content. For an image, the model receives an image content block so it actually SEES the screenshot, plus a text line with filename and size. For a non-image, the model gets a text block with metadata and, for small files, the base64 content; large binaries point at the skill\'s download-attachment shortcut. Works for ticket, doc, and comment attachments (the id is global). Enforces the same project/space access check as listing the attachment.',
+    inputSchema: z.object({
+        attachmentId: z.string().uuid().describe('Attachment UUID from a list/get call.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeGetAttachmentHandler(client) {
+    return async ({ attachmentId }) => {
+        const att = await client.get(`/attachments/${attachmentId}/base64`);
+        const kb = Math.round(att.sizeBytes / 1024);
+        // Over the inline cap: refuse to spill a multi-MB blob into the model's
+        // context. Point at the skill download shortcut, which streams to disk.
+        if (att.sizeBytes > MAX_INLINE_BYTES) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `${att.filename} (${kb} KB, ${att.contentType}) is larger than the ${Math.round(MAX_INLINE_BYTES / (1024 * 1024))} MB inline limit. Download it with the skill shortcut: \`orboto.mjs download-attachment ${att.id}\`.`,
+                    }],
+                structuredContent: {
+                    id: att.id, filename: att.filename, contentType: att.contentType, sizeBytes: att.sizeBytes, inlined: false,
+                },
+            };
+        }
+        if (isImage(att.contentType)) {
+            return {
+                content: [
+                    { type: 'text', text: `${att.filename} (${kb} KB, ${att.contentType})` },
+                    { type: 'image', data: att.contentBase64, mimeType: att.contentType },
+                ],
+                structuredContent: {
+                    id: att.id, filename: att.filename, contentType: att.contentType, sizeBytes: att.sizeBytes, inlined: true,
+                },
+            };
+        }
+        // Non-image: return metadata + the base64 so an agent can decode / save it.
+        return {
+            content: [{
+                    type: 'text',
+                    text: `${att.filename} (${kb} KB, ${att.contentType})\nbase64:\n${att.contentBase64}`,
+                }],
+            structuredContent: {
+                id: att.id,
+                filename: att.filename,
+                contentType: att.contentType,
+                sizeBytes: att.sizeBytes,
+                inlined: true,
+                contentBase64: att.contentBase64,
+            },
+        };
+    };
+}