@orboto/mcp 0.178.0

package/dist/tool-parameters.test.js

@@ -0,0 +1,145 @@
+/**
+ * ORB-1805 - the schema diet must never cost a PARAMETER.
+ *
+ * The diet trims description text: tool prose moved into
+ * `orboto_help` / the skill's REFERENCE.md, per-parameter prose
+ * shortened to the phrase a caller acts on. What it must never do is
+ * drop a field, flip a required field to optional, or shrink an enum -
+ * those are the changes that silently break a caller.
+ *
+ * `tool-parameters.baseline.json` is the snapshot taken from the FULL
+ * manifest immediately BEFORE the ORB-1805 diet: for every tool, every
+ * property path in its input schema (nested objects and array items
+ * included, as dotted paths), its required list, and every enum's
+ * values. This test walks the live manifest the same way and fails on
+ * any loss.
+ *
+ * Direction matters: it is a SUPERSET check. Adding a parameter, making
+ * a required one optional-to-required is caught, and adding an enum
+ * value is fine - only removal fails. Re-baseline ONLY when a parameter
+ * is intentionally removed (which is an API break in its own right and
+ * belongs in its own ticket), never to make this test go quiet.
+ */
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { buildOrbotoMcpServer } from './server.js';
+const baseline = JSON.parse(readFileSync(fileURLToPath(new URL('./tool-parameters.baseline.json', import.meta.url)), 'utf8'));
+beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('offline test'));
+    delete process.env.ORBOTO_MCP_TOOLSET;
+});
+afterEach(() => { vi.restoreAllMocks(); });
+/** Same walk the baseline was generated with: dotted property paths,
+ *  `[]` for an array hop, union branches flattened onto the same path. */
+function walk(schema, prefix, params, enums) {
+    if (!schema || typeof schema !== 'object')
+        return;
+    if (Array.isArray(schema.enum) && prefix) {
+        (enums[prefix] ??= new Set());
+        for (const v of schema.enum)
+            enums[prefix].add(String(v));
+    }
+    for (const branch of [schema.anyOf, schema.oneOf, schema.allOf]) {
+        if (Array.isArray(branch))
+            for (const s of branch)
+                walk(s, prefix, params, enums);
+    }
+    if (schema.items)
+        walk(schema.items, `${prefix}[]`, params, enums);
+    if (schema.properties) {
+        for (const [k, v] of Object.entries(schema.properties)) {
+            const p = prefix ? `${prefix}.${k}` : k;
+            params.add(p);
+            walk(v, p, params, enums);
+        }
+    }
+}
+async function liveShapes() {
+    const server = await buildOrbotoMcpServer({
+        baseUrl: 'https://orboto.example.com',
+        apiKey: 'orb_test',
+        toolset: 'full',
+    });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: 'param-shape', version: '0.0.0' });
+    await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+    try {
+        let cursor;
+        const tools = [];
+        do {
+            const page = await client.listTools(cursor ? { cursor } : {});
+            tools.push(...page.tools);
+            cursor = page.nextCursor;
+        } while (cursor);
+        const out = {};
+        for (const t of tools) {
+            const params = new Set();
+            const enums = {};
+            walk(t.inputSchema, '', params, enums);
+            out[t.name] = {
+                params: [...params].sort(),
+                required: (t.inputSchema?.required ?? []).slice().sort(),
+                enums: Object.fromEntries(Object.entries(enums).map(([k, v]) => [k, [...v].sort()])),
+            };
+        }
+        return out;
+    }
+    finally {
+        await client.close();
+        await server.close();
+    }
+}
+describe('ORB-1805 - no parameter lost to the schema diet', () => {
+    it('the baseline fixture is the pre-diet full manifest, not an empty file', () => {
+        expect(Object.keys(baseline).length).toBeGreaterThan(150);
+        expect(baseline.orboto_create_ticket?.params).toContain('duplicateJustification');
+        expect(baseline.orboto_update_ticket?.params).toContain('patch.customerSummary');
+    });
+    it('every tool in the baseline still exists', async () => {
+        const live = await liveShapes();
+        const missing = Object.keys(baseline).filter((t) => !live[t]);
+        expect(missing).toEqual([]);
+    });
+    it('every baseline parameter path still exists on its tool', async () => {
+        const live = await liveShapes();
+        const lost = [];
+        for (const [tool, shape] of Object.entries(baseline)) {
+            for (const p of shape.params) {
+                if (!live[tool]?.params.includes(p))
+                    lost.push(`${tool}.${p}`);
+            }
+        }
+        expect(lost).toEqual([]);
+    });
+    it('no required parameter became optional (and none appeared)', async () => {
+        const live = await liveShapes();
+        const changed = [];
+        for (const [tool, shape] of Object.entries(baseline)) {
+            const now = live[tool]?.required ?? [];
+            for (const r of shape.required)
+                if (!now.includes(r))
+                    changed.push(`${tool}.${r} no longer required`);
+            for (const r of now)
+                if (!shape.required.includes(r))
+                    changed.push(`${tool}.${r} newly required`);
+        }
+        expect(changed).toEqual([]);
+    });
+    it('no enum value disappeared', async () => {
+        const live = await liveShapes();
+        const lost = [];
+        for (const [tool, shape] of Object.entries(baseline)) {
+            for (const [path, values] of Object.entries(shape.enums)) {
+                const now = live[tool]?.enums[path] ?? [];
+                for (const v of values)
+                    if (!now.includes(v))
+                        lost.push(`${tool}.${path}: "${v}"`);
+            }
+        }
+        expect(lost).toEqual([]);
+    });
+});

package/dist/tools/absence-writes.js

@@ -0,0 +1,93 @@
+/**
+ * ORB-933 - write-side MCP tools for absences and the two admin tables
+ * that ride alongside them (public holidays, company closures).
+ *
+ * - orboto_update_public_holiday - PATCH /admin/public-holidays/:id
+ * - orboto_update_company_closure - PATCH /admin/company-closures/:id
+ * - orboto_update_absence - PATCH /absences/:id
+ *
+ * Today these surfaces only had POST + DELETE - typo correction or date
+ * fix meant delete + recreate, losing the original row id. PATCH fills
+ * that gap. Listing endpoints stay on the existing routes (no read tools
+ * here yet - that's Phase 3 of the CRUD parity epic, ORB-935).
+ */
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// orboto_update_public_holiday
+// ---------------------------------------------------------------------------
+export const updatePublicHolidayToolConfig = {
+    title: 'Edit a public holiday',
+    description: 'Correct a typo or wrong date on a public holiday without losing the row id. Admin-only (`admin:absences:write`). Pass only the fields you want to change; at least one field is required.',
+    inputSchema: z.object({
+        id: z.string().uuid(),
+        name: z.string().min(1).max(100).optional(),
+        date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('YYYY-MM-DD'),
+        countryCode: z.string().max(10).nullable().optional(),
+        regionCode: z.string().max(10).nullable().optional(),
+        isRecurring: z.boolean().optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeUpdatePublicHolidayHandler(client) {
+    return async (input) => {
+        const { id, ...patch } = input;
+        const row = await client.patch(`/admin/public-holidays/${id}`, patch);
+        return {
+            content: [{ type: 'text', text: `Public holiday ${row.id} updated (${row.name} on ${row.date}).` }],
+            structuredContent: row,
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_update_company_closure
+// ---------------------------------------------------------------------------
+export const updateCompanyClosureToolConfig = {
+    title: 'Edit a company closure',
+    description: 'Update a workspace-wide non-working block (company offsite, holiday shutdown). Admin-only (`admin:absences:write`). Pass only the fields you want to change; at least one field is required. If only one of `startDate`/`endDate` is passed, the other is left as-is - the API still validates start ≤ end after the partial patch.',
+    inputSchema: z.object({
+        id: z.string().uuid(),
+        name: z.string().min(1).optional(),
+        startDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('YYYY-MM-DD'),
+        endDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('YYYY-MM-DD'),
+        note: z.string().nullish(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeUpdateCompanyClosureHandler(client) {
+    return async (input) => {
+        const { id, ...patch } = input;
+        const row = await client.patch(`/admin/company-closures/${id}`, patch);
+        return {
+            content: [{ type: 'text', text: `Company closure ${row.id} updated (${row.name}, ${row.startDate} → ${row.endDate}).` }],
+            structuredContent: row,
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_update_absence
+// ---------------------------------------------------------------------------
+export const updateAbsenceToolConfig = {
+    title: 'Edit a pending or draft absence request',
+    description: 'Edit your own absence request before a reviewer acts on it. Locked once the status is `approved`, `rejected`, or `cancelled` - those transitions go through the approve / reject / cancel endpoints, not this one. Caller must be the absence owner or a super-admin. `durationDays` is recomputed automatically when dates move (uses the owner\'s working-day rules + holidays + closures).',
+    inputSchema: z.object({
+        id: z.string().uuid(),
+        typeId: z.string().uuid().optional().describe('Absence-type id (vacation, sick, etc.).'),
+        startDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('YYYY-MM-DD'),
+        endDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('YYYY-MM-DD'),
+        note: z.string().nullish(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeUpdateAbsenceHandler(client) {
+    return async (input) => {
+        const { id, ...patch } = input;
+        const row = await client.patch(`/absences/${id}`, patch);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Absence ${row.id} updated (${row.startDate} → ${row.endDate}, ${row.durationDays} days, status=${row.status}).`,
+                }],
+            structuredContent: row,
+        };
+    };
+}

package/dist/tools/absence-writes.test.js

@@ -0,0 +1,106 @@
+/**
+ * ORB-933 - tests for the PATCH-side MCP tools across the
+ * absences / public-holidays / company-closures resources.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { makeUpdatePublicHolidayHandler, makeUpdateCompanyClosureHandler, makeUpdateAbsenceHandler, } from './absence-writes.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const PH_ID = 'aaaaaaaa-0000-0000-0000-000000000001';
+const CC_ID = 'bbbbbbbb-0000-0000-0000-000000000001';
+const ABS_ID = 'cccccccc-0000-0000-0000-000000000001';
+function stubJSON(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({
+            url: url.toString(),
+            method: init?.method ?? 'GET',
+            body: typeof init?.body === 'string' ? JSON.parse(init.body) : init?.body,
+        });
+        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;
+}
+describe('orboto_update_public_holiday', () => {
+    it('PATCHes only the supplied fields', async () => {
+        const calls = stubJSON([{
+                json: { id: PH_ID, name: 'Day of German Unity', date: '2026-10-03', countryCode: 'DE', regionCode: null, isRecurring: true },
+            }]);
+        const res = await makeUpdatePublicHolidayHandler(client)({ id: PH_ID, date: '2026-10-03' });
+        expect(calls[0]).toMatchObject({
+            method: 'PATCH',
+            url: `https://orboto.example.com/admin/public-holidays/${PH_ID}`,
+            body: { date: '2026-10-03' },
+        });
+        expect(res.structuredContent.date).toBe('2026-10-03');
+    });
+    it('bubbles up a 403 when caller lacks admin:absences:write', async () => {
+        stubJSON([{ ok: false, status: 403, json: { error: 'Forbidden' } }]);
+        await expect(makeUpdatePublicHolidayHandler(client)({ id: PH_ID, name: 'X' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});
+describe('orboto_update_company_closure', () => {
+    it('PATCHes the named fields only', async () => {
+        const calls = stubJSON([{
+                json: { id: CC_ID, name: 'Summer break', startDate: '2026-07-20', endDate: '2026-08-02', note: null },
+            }]);
+        const res = await makeUpdateCompanyClosureHandler(client)({ id: CC_ID, endDate: '2026-08-02' });
+        expect(calls[0]).toMatchObject({
+            method: 'PATCH',
+            url: `https://orboto.example.com/admin/company-closures/${CC_ID}`,
+            body: { endDate: '2026-08-02' },
+        });
+        expect(res.structuredContent.endDate).toBe('2026-08-02');
+    });
+    it('bubbles up a 400 when start > end after the partial patch', async () => {
+        stubJSON([{ ok: false, status: 400, json: { error: 'Start date must be before end date' } }]);
+        await expect(makeUpdateCompanyClosureHandler(client)({ id: CC_ID, startDate: '2026-09-01' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});
+describe('orboto_update_absence', () => {
+    it('PATCHes typeId + dates and surfaces the recomputed durationDays', async () => {
+        const calls = stubJSON([{
+                json: {
+                    id: ABS_ID,
+                    userId: 'u1',
+                    typeId: 'aaaaaaaa-1111-1111-1111-111111111111',
+                    startDate: '2026-08-01',
+                    endDate: '2026-08-07',
+                    durationDays: '5.0',
+                    status: 'pending',
+                    note: 'family trip',
+                },
+            }]);
+        const res = await makeUpdateAbsenceHandler(client)({
+            id: ABS_ID,
+            startDate: '2026-08-01',
+            endDate: '2026-08-07',
+            note: 'family trip',
+        });
+        expect(calls[0]).toMatchObject({
+            method: 'PATCH',
+            url: `https://orboto.example.com/absences/${ABS_ID}`,
+            body: { startDate: '2026-08-01', endDate: '2026-08-07', note: 'family trip' },
+        });
+        expect(res.structuredContent.durationDays).toBe('5.0');
+    });
+    it('bubbles up a 400 when the absence is already approved (status-locked)', async () => {
+        stubJSON([{ ok: false, status: 400, json: { error: 'Can only edit pending or draft absences' } }]);
+        await expect(makeUpdateAbsenceHandler(client)({ id: ABS_ID, note: 'late change' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+    it('bubbles up a 403 when caller is not the owner', async () => {
+        stubJSON([{ ok: false, status: 403, json: { error: 'Forbidden' } }]);
+        await expect(makeUpdateAbsenceHandler(client)({ id: ABS_ID, note: 'x' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});

package/dist/tools/admin-translations.js

@@ -0,0 +1,83 @@
+/**
+ * ORB-893 - admin-translation review queue MCP tools.
+ *
+ * Three thin wrappers around `/admin/tickets/translations*`:
+ *
+ * - `orboto_admin_translation_list` - paginated list of
+ *    auto-translated tickets (pending review by default, or `all`).
+ * - `orboto_admin_translation_approve` - stamp the row reviewed.
+ * - `orboto_admin_translation_revert` - restore the pre-translation
+ *    title + description from the audit comment.
+ *
+ * All three require `admin:translation_review` (super-admin holds it
+ * by default).
+ */
+import { z } from 'zod';
+export const listAdminTranslationsToolConfig = {
+    title: 'List auto-translated tickets for review',
+    description: 'List tickets the AI auto-translate flow rewrote, sorted newest-updated first. Default surface is the pending queue (tickets the admin has not yet approved). Pass `status: "all"` to include reviewed rows too. Returns up to `limit` (default 25) rows + a `nextCursor` for paging. Requires `admin:translation_review`.',
+    inputSchema: z.object({
+        status: z.enum(['pending', 'all']).optional().describe('Default: pending.'),
+        limit: z.number().int().min(1).max(100).optional().describe('Default: 25.'),
+        cursor: z.string().optional().describe('Opaque cursor from a previous response.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeListAdminTranslationsHandler(client) {
+    return async ({ status, limit, cursor }) => {
+        const qs = new URLSearchParams();
+        if (status)
+            qs.set('status', status);
+        if (limit)
+            qs.set('limit', String(limit));
+        if (cursor)
+            qs.set('cursor', cursor);
+        const path = `/admin/tickets/translations${qs.toString() ? `?${qs.toString()}` : ''}`;
+        const res = await client.get(path);
+        const lines = res.items.length === 0
+            ? '(no auto-translated tickets)'
+            : res.items.map((r) => {
+                const reviewer = r.reviewedBy ? ` ✓ ${r.reviewedBy.fullName ?? r.reviewedBy.email}` : ' (pending review)';
+                const key = r.ticketKey ?? r.id.slice(0, 8);
+                return `- [${key}] ${r.title}  (${r.autoTranslatedFrom} → ${r.defaultLocale}${reviewer})`;
+            }).join('\n');
+        return {
+            content: [{ type: 'text', text: lines + (res.nextCursor ? `\n\n(next cursor: ${res.nextCursor})` : '') }],
+            structuredContent: { items: res.items, nextCursor: res.nextCursor },
+        };
+    };
+}
+export const approveTranslationToolConfig = {
+    title: 'Approve an auto-translated ticket',
+    description: 'Stamp `translation_reviewed_at` + `translation_reviewed_by` on a ticket the AI auto-translate flow rewrote. Idempotent - re-approving the same row simply refreshes the timestamp + reviewer. 409 if the ticket was never auto-translated. Requires `admin:translation_review`.',
+    inputSchema: z.object({
+        ticketId: z.string().uuid().describe('UUID of the ticket to approve.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeApproveTranslationHandler(client) {
+    return async ({ ticketId }) => {
+        const res = await client.post(`/admin/tickets/${ticketId}/translations/approve`, {});
+        return {
+            content: [{ type: 'text', text: `Approved translation for ticket ${ticketId} at ${res.reviewedAt}.` }],
+            structuredContent: res,
+        };
+    };
+}
+export const revertTranslationToolConfig = {
+    title: 'Revert an auto-translated ticket back to the original',
+    description: 'Restore the pre-translation title + description from the auto-translated audit comment and clear the auto-translate marker + any prior approval. Use when the AI got the translation wrong and the operator wants to start over. 409 if the ticket was never auto-translated. Requires `admin:translation_review`.',
+    inputSchema: z.object({
+        ticketId: z.string().uuid().describe('UUID of the ticket to revert.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeAdminRevertTranslationHandler(client) {
+    return async ({ ticketId }) => {
+        const res = await client.post(`/admin/tickets/${ticketId}/translations/revert`, {});
+        return {
+            content: [{ type: 'text', text: `Reverted ticket ${ticketId} to its original content.` }],
+            structuredContent: res,
+        };
+    };
+}

package/dist/tools/admin-writes.js

@@ -0,0 +1,174 @@
+/**
+ * ORB-244 Phase C Group 4 - admin-only tools.
+ *
+ * These three are listed under "write tools" in the ticket because
+ * they're privileged surfaces, but two of them (`list_users`,
+ * `get_audit_log`) are read-only - the gating is what makes them
+ * "writes" from a permission perspective. `trigger_backup` is the
+ * only true mutation.
+ *
+ * Gating: the API enforces super-admin via the `admin:*` permission
+ * slugs. A non-admin's request lands a 403 from the API, which
+ * surfaces as OrbotoApiError on the MCP side. The tools themselves
+ * don't double-check - that would race against the API anyway. We
+ * just rewrite 403 into a clear message.
+ *
+ * Tools:
+ * - orboto_list_users - admin user directory with cursor pagination
+ * - orboto_get_audit_log - recent admin / mutation events
+ * - orboto_trigger_backup - run a configured backup job by name
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+function rewrite403(action) {
+    return (err) => {
+        if (err instanceof OrbotoApiError && err.status === 403) {
+            throw new Error(`${action} requires super-admin permissions on this workspace.`);
+        }
+        throw err;
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_list_users
+// ---------------------------------------------------------------------------
+export const listUsersToolConfig = {
+    title: 'List workspace users (admin)',
+    description: 'Return the workspace user directory. Super-admin only. Useful for AI agents that need to look up an email beyond their visible project members (e.g. to assign someone who isn\'t on the current project yet). Imported placeholder users (`*@imported.ghost`) are hidden by default; set `showGhosts=true` to include them.',
+    inputSchema: z.object({
+        search: z.string().optional().describe('Substring match against fullName + email.'),
+        limit: z.number().int().min(1).max(100).default(50),
+        showGhosts: z.boolean().optional().describe('Include `*@imported.ghost` placeholder users created during project imports. Off by default.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeListUsersHandler(client) {
+    return async ({ search, limit, showGhosts }) => {
+        const qs = new URLSearchParams();
+        qs.set('limit', String(limit ?? 50));
+        if (search)
+            qs.set('search', search);
+        if (showGhosts)
+            qs.set('hideGhosts', 'false');
+        const page = await client.get(`/admin/users?${qs}`).catch(rewrite403('list_users'));
+        const text = page.items.length === 0
+            ? 'No users matched.'
+            : page.items.map((u) => {
+                const tags = [];
+                if (u.isBot)
+                    tags.push('bot');
+                if (u.isExternal)
+                    tags.push('external');
+                if (!u.isActive)
+                    tags.push('disabled');
+                return `- ${u.fullName} <${u.email}>${tags.length ? ` [${tags.join(', ')}]` : ''}`;
+            }).join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: {
+                count: page.items.length,
+                hasMore: !!page.nextCursor,
+                users: page.items.map((u) => ({
+                    email: u.email,
+                    fullName: u.fullName,
+                    isActive: u.isActive,
+                    isExternal: u.isExternal,
+                    isBot: u.isBot,
+                    lastSeenAt: u.lastSeenAt ?? null,
+                })),
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_get_audit_log
+// ---------------------------------------------------------------------------
+export const getAuditLogToolConfig = {
+    title: 'Read the workspace audit log (admin)',
+    description: 'Recent audit events - admin actions, role changes, ticket deletions, federation handshakes, etc. Super-admin only. Filter by actor or entity to narrow the window.',
+    inputSchema: z.object({
+        actorEmail: z.string().email().optional().describe('Filter to one actor.'),
+        entityType: z.string().optional().describe('e.g. "user", "project", "ticket", "federation_link".'),
+        limit: z.number().int().min(1).max(100).default(50),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeGetAuditLogHandler(client) {
+    return async ({ actorEmail, entityType, limit }) => {
+        const qs = new URLSearchParams();
+        qs.set('limit', String(limit ?? 50));
+        if (entityType)
+            qs.set('entityType', entityType);
+        if (actorEmail) {
+            // Resolve actor email → userId via the admin users list.
+            const userPage = await client.get(`/admin/users?search=${encodeURIComponent(actorEmail)}&limit=10`).catch(rewrite403('audit log lookup'));
+            const actor = userPage.items.find((u) => u.email.toLowerCase() === actorEmail.toLowerCase());
+            if (!actor)
+                throw new Error(`No workspace user with email "${actorEmail}".`);
+            qs.set('actorId', actor.id);
+        }
+        const page = await client.get(`/admin/audit-log?${qs}`).catch(rewrite403('audit log'));
+        const text = page.items.length === 0
+            ? 'No matching audit entries.'
+            : page.items.map((e) => {
+                const who = e.actorName ?? e.actorEmail ?? '(system)';
+                // ORB-1368 - mark agent-performed actions.
+                const agentMark = e.isAgentWork ? ' [agent]' : '';
+                const what = e.entityType
+                    ? ` ${e.entityType}${e.entityId ? `:${e.entityId.slice(0, 8)}` : ''}`
+                    : '';
+                return `- ${e.createdAt} · ${who}${agentMark} → ${e.action}${what}`;
+            }).join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: {
+                count: page.items.length,
+                hasMore: !!page.nextCursor,
+                entries: page.items.map((e) => ({
+                    actorEmail: e.actorEmail,
+                    action: e.action,
+                    entityType: e.entityType,
+                    entityId: e.entityId,
+                    createdAt: e.createdAt,
+                })),
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_trigger_backup
+// ---------------------------------------------------------------------------
+export const triggerBackupToolConfig = {
+    title: 'Run a configured backup job now (admin)',
+    description: 'Manually trigger a backup job by name. Resolves to the job\'s UUID via /admin/backup/jobs and POSTs to the run endpoint. Super-admin only.',
+    inputSchema: z.object({
+        jobName: z.string().min(1).describe('Name of an existing backup job (configured at /admin/backup).'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeTriggerBackupHandler(client) {
+    return async ({ jobName }) => {
+        const jobs = await client.get('/admin/backup/jobs')
+            .catch(rewrite403('list_backup_jobs'));
+        const job = jobs.find((j) => j.name === jobName);
+        if (!job) {
+            throw new Error(`No backup job named "${jobName}". Existing jobs: ${jobs.map((j) => `"${j.name}"`).join(', ') || '(none)'}`);
+        }
+        if (!job.isActive) {
+            throw new Error(`Backup job "${jobName}" is currently disabled - enable it in /admin/backup first.`);
+        }
+        const run = await client.post(`/admin/backup/jobs/${job.id}/run`, {})
+            .catch(rewrite403('trigger_backup'));
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Started backup job "${jobName}" (run id ${run.id.slice(0, 8)}, status: ${run.status}).`,
+                }],
+            structuredContent: {
+                jobName,
+                runId: run.id,
+                status: run.status,
+                startedAt: run.startedAt,
+            },
+        };
+    };
+}