@orboto/mcp 0.178.0

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

@@ -0,0 +1,120 @@
+/**
+ * ORB-244 Phase C Group 4 - admin-only tool tests.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeListUsersHandler, makeGetAuditLogHandler, makeTriggerBackupHandler, } from './admin-writes.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        const u = url.toString();
+        const m = init?.method ?? 'GET';
+        const b = init?.body ? JSON.parse(init.body) : undefined;
+        calls.push({ url: u, method: m, body: b });
+        const r = responses.shift();
+        if (!r)
+            throw new Error(`unexpected extra fetch ${m} ${u}`);
+        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' });
+describe('orboto_list_users', () => {
+    it('passes search + limit, surfaces user tags in text output', async () => {
+        const calls = stub([{
+                json: {
+                    items: [
+                        { id: 'u1', email: 'ada@acme', fullName: 'Ada', isActive: true, isExternal: false, isBot: false, createdAt: 'now' },
+                        { id: 'u2', email: 'bot@acme', fullName: 'CI Bot', isActive: true, isExternal: false, isBot: true, createdAt: 'now' },
+                        { id: 'u3', email: 'inactive@acme', fullName: 'Old', isActive: false, isExternal: false, isBot: false, createdAt: 'now' },
+                    ],
+                    nextCursor: null,
+                },
+            }]);
+        const res = await makeListUsersHandler(client)({ search: 'acme', limit: 10 });
+        expect(calls[0].url).toContain('search=acme');
+        expect(calls[0].url).toContain('limit=10');
+        const text = res.content[0].text;
+        expect(text).toContain('[bot]');
+        expect(text).toContain('[disabled]');
+    });
+    it('rewrites a 403 into a "super-admin required" message', async () => {
+        stub([{ ok: false, status: 403, json: { error: 'Forbidden' } }]);
+        await expect(makeListUsersHandler(client)({})).rejects.toThrow(/super-admin permissions/);
+    });
+});
+describe('orboto_get_audit_log', () => {
+    it('plain entityType filter just queries with entityType', async () => {
+        const calls = stub([{ json: { items: [], nextCursor: null } }]);
+        await makeGetAuditLogHandler(client)({ entityType: 'user', limit: 25 });
+        expect(calls[0].url).toContain('/admin/audit-log?');
+        expect(calls[0].url).toContain('entityType=user');
+        expect(calls[0].url).toContain('limit=25');
+    });
+    it('actorEmail resolves through admin-users to actorId', async () => {
+        const calls = stub([
+            { json: { items: [{ id: 'u1', email: 'ada@acme', fullName: 'Ada', isActive: true, isExternal: false, isBot: false, createdAt: 'now' }], nextCursor: null } },
+            { json: { items: [], nextCursor: null } },
+        ]);
+        await makeGetAuditLogHandler(client)({ actorEmail: 'ada@acme' });
+        // Call 0 = users-search lookup, Call 1 = audit-log with actorId=u1
+        expect(calls[0].url).toContain('/admin/users');
+        expect(calls[1].url).toContain('actorId=u1');
+    });
+    it('throws when actorEmail does not match a workspace user', async () => {
+        stub([
+            { json: { items: [], nextCursor: null } },
+        ]);
+        await expect(makeGetAuditLogHandler(client)({ actorEmail: 'ghost@acme' })).rejects.toThrow(/No workspace user with email/);
+    });
+    it('renders entries with actor + action + entity hint in text', async () => {
+        stub([{
+                json: {
+                    items: [
+                        { id: 'a1', actorId: 'u1', actorEmail: 'ada@acme', actorName: 'Ada', action: 'user.deactivated', entityType: 'user', entityId: 'u9-aaaaaaaa-...', details: {}, createdAt: '2026-04-25T07:00:00Z' },
+                    ],
+                    nextCursor: null,
+                },
+            }]);
+        const res = await makeGetAuditLogHandler(client)({});
+        const text = res.content[0].text;
+        expect(text).toContain('Ada → user.deactivated user:u9-aaaaa');
+    });
+});
+describe('orboto_trigger_backup', () => {
+    it('resolves jobName → jobId, then POSTs the run', async () => {
+        const calls = stub([
+            { json: [{ id: 'j1', name: 'nightly', scope: 'full', schedule: '0 3 * * *', isActive: true }] },
+            { json: { id: 'r1', jobId: 'j1', startedAt: 'now', finishedAt: null, status: 'running', storagePath: null, error: null } },
+        ]);
+        await makeTriggerBackupHandler(client)({ jobName: 'nightly' });
+        expect(calls[1].method).toBe('POST');
+        expect(calls[1].url).toContain('/admin/backup/jobs/j1/run');
+    });
+    it('throws when jobName does not match', async () => {
+        stub([
+            { json: [{ id: 'j1', name: 'nightly', scope: 'full', schedule: null, isActive: true }] },
+        ]);
+        await expect(makeTriggerBackupHandler(client)({ jobName: 'weekly' })).rejects.toThrow(/"weekly"/);
+    });
+    it('throws on a disabled job (don\'t silently no-op)', async () => {
+        stub([
+            { json: [{ id: 'j1', name: 'paused', scope: 'full', schedule: null, isActive: false }] },
+        ]);
+        await expect(makeTriggerBackupHandler(client)({ jobName: 'paused' })).rejects.toThrow(/currently disabled/);
+    });
+    it('rewrites a 403 from the API into a permission-clarifying error', async () => {
+        stub([
+            { ok: false, status: 403, json: { error: 'Forbidden' } },
+        ]);
+        await expect(makeTriggerBackupHandler(client)({ jobName: 'nightly' })).rejects.toThrow(/super-admin/);
+    });
+});

package/dist/tools/agent-coordination.js

@@ -0,0 +1,160 @@
+/**
+ * ORB-705 - MCP coordination tools.
+ *
+ * Three tools layered on the ORB-704 REST surface:
+ *   orboto_agent_heartbeat - wraps POST /v1/agent/heartbeat. Returns
+ *     the sessionToken the agent persists for next call.
+ *   orboto_agent_presence - wraps GET /v1/agent/presence. Returns
+ *     active sessions visible to the caller (own only for non-admin,
+ *     workspace-wide for super-admin).
+ *   orboto_agent_notify - wraps the existing notification surface
+ *     to dispatch a directed message to another agent / user.
+ *     Routing target is identified by email (works for both bots and
+ *     humans). Fire-and-forget; the recipient sees it via the
+ *     standard notifications channel (ORB-706 wires the bridge).
+ */
+import { z } from 'zod';
+import { mcpInstanceToken } from './shared.js';
+export const agentHeartbeatToolConfig = {
+    title: 'Agent heartbeat (Multi-Agent Coordination)',
+    description: 'Register or refresh this agent\'s presence in the workspace. Call on startup AND every ~30 s thereafter; rows missing for >90 s count as offline. Returns the `sessionToken` to persist + send on subsequent heartbeats so the same row is bumped instead of churning new ones. `status` can be `idle` (default), `working` (set `workingOnTicketId` too if relevant), or `blocked`. `capabilities` is a free-form list of strings the operator can use to filter (e.g. `["read-only", "writes-tickets", "writes-code"]`). `clientInfo` describes the runtime - fill `name` with the agent runtime (`claude-desktop`, `claude-code`, `dispatcher-daemon`, `cursor`, ...).',
+    inputSchema: z.object({
+        sessionToken: z.string().nullable().optional(),
+        status: z.enum(['idle', 'working', 'blocked']).optional(),
+        workingOnTicketId: z.string().uuid().nullable().optional(),
+        capabilities: z.array(z.string()).optional(),
+        clientInfo: z.object({
+            name: z.string().optional(),
+            version: z.string().optional(),
+            host: z.string().optional(),
+            user_agent: z.string().optional(),
+        }).optional(),
+    }).shape,
+    outputSchema: z.object({
+        sessionToken: z.string(),
+        sessionId: z.string().uuid(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeAgentHeartbeatHandler(client) {
+    return async (args) => {
+        const res = await client.post('/v1/agent/heartbeat', args);
+        return {
+            content: [{ type: 'text', text: `heartbeat ack - sessionToken=${res.sessionToken.slice(0, 8)}…` }],
+            structuredContent: { sessionToken: res.sessionToken, sessionId: res.sessionId },
+        };
+    };
+}
+export const agentPresenceToolConfig = {
+    title: 'Workspace agent presence',
+    description: 'Returns currently-active agent sessions in the workspace. Active = heartbeat within the last 90 s. Super-admins see every agent; regular users see only their own sessions (useful for "is my dispatcher daemon alive?" checks). Each row exposes `userId`, `userEmail`, the agent runtime (`clientInfo.name`), declared `capabilities`, current `status`, and the ticket the agent is working on if any. Use this to plan multi-agent work - e.g. before dispatching a sub-task, look up which other agents are active and what they\'re working on so you don\'t step on a parallel run.',
+    inputSchema: z.object({}).shape,
+    outputSchema: z.object({
+        sessions: z.array(z.object({
+            userId: z.string().uuid(),
+            userEmail: z.string(),
+            userFullName: z.string().nullable(),
+            sessionId: z.string().uuid(),
+            status: z.string(),
+            workingOnTicket: z.object({
+                id: z.string().uuid(),
+                key: z.string().nullable(),
+                title: z.string(),
+                projectKey: z.string().nullable(),
+            }).nullable(),
+            capabilities: z.array(z.string()),
+            clientInfo: z.record(z.string(), z.string()),
+            lastSeenAt: z.string(),
+            createdAt: z.string(),
+        })),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeAgentPresenceHandler(client) {
+    return async () => {
+        const sessions = await client.get('/v1/agent/presence');
+        const lines = [];
+        if (sessions.length === 0) {
+            lines.push('No active agent sessions in the workspace.');
+        }
+        else {
+            lines.push(`${sessions.length} active session(s):`);
+            for (const s of sessions) {
+                const name = s.userFullName ?? s.userEmail;
+                const runtime = s.clientInfo.name ?? 'unknown';
+                const work = s.workingOnTicket
+                    ? ` · working on [${s.workingOnTicket.projectKey ?? '?'}] ${s.workingOnTicket.key ?? s.workingOnTicket.id} (${s.workingOnTicket.title})`
+                    : '';
+                lines.push(`- ${name} (${runtime}) - ${s.status}${work}`);
+            }
+        }
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: { sessions },
+        };
+    };
+}
+export const agentNotifyToolConfig = {
+    title: 'Notify another agent / user',
+    description: 'Dispatch a fire-and-forget message to a target user (bot or human) identified by email. The recipient sees it via the standard notification channel - in-app for human users, MCP push for subscribed agents (ORB-706). Use cases: lead agent telling a worker a sub-task is ready; a worker reporting back to the orchestrator; a CI agent pinging a reviewer when a PR is staged. The `kind` field tags the semantic intent so the recipient can filter (`info` for general updates, `request` when a response is expected, `complete` when reporting a finished sub-task). `payload` is a free-form jsonb blob.',
+    inputSchema: z.object({
+        targetEmail: z.string().email(),
+        kind: z.enum(['info', 'request', 'complete', 'error']).default('info'),
+        subject: z.string().min(1).max(200),
+        payload: z.record(z.string(), z.unknown()).optional(),
+        // ORB-1727 - reply chaining: the id of the inbox message being answered.
+        threadId: z.string().uuid().optional(),
+        // ORB-1732 - optional project scope: address "the agent working project
+        // X" when the recipient identity runs multiple sessions.
+        project: z.string().min(1).max(64).optional().describe('Project key (ORB) or UUID: scope the message to the recipient session working that project. Recipients fetching with a project filter see scoped messages for their project plus unscoped ones.'),
+        // ORB-1742 - defaults to this MCP session's instance token so a shared
+        // identity never wakes itself with its own outbound mail.
+        senderRef: z.string().min(1).max(128).optional().describe('Sender-session ref for self-echo exclusion. Defaults to this MCP session automatically - only override when sending on behalf of another session.'),
+    }).shape,
+    outputSchema: z.object({
+        ok: z.literal(true),
+        messageId: z.string().uuid(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+// ---------------------------------------------------------------------------
+// orboto_agent_broadcast (ORB-964)
+// ---------------------------------------------------------------------------
+export const agentBroadcastToolConfig = {
+    title: 'Scoped broadcast to other agents',
+    description: 'Fan-out a message to every subscribed agent in a scope. `scopeType=workspace` reaches every internal member; `scopeType=project` reaches members of `scopeId` (project UUID); `scopeType=topic` reaches everyone subscribed to the topic string. The recipient sees it via a `notifications/resources/updated` push on `orboto://broadcast/<scope>/<scope_id>`. Use for lead-agent → workers (workspace), project-team status updates (project), or ad-hoc cross-cutting coordination (topic). Retention is 24 h - late subscribers can replay via the resource read.',
+    inputSchema: z.object({
+        scopeType: z.enum(['workspace', 'project', 'topic']),
+        scopeId: z.string().default(''),
+        message: z.record(z.string(), z.unknown()),
+    }).shape,
+    outputSchema: z.object({ id: z.string().uuid() }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeAgentBroadcastHandler(client) {
+    return async (args) => {
+        const res = await client.post('/v1/agent/broadcast', {
+            scopeType: args.scopeType,
+            scopeId: args.scopeId ?? '',
+            message: args.message,
+        });
+        return {
+            content: [{ type: 'text', text: `broadcast posted - id=${res.id}` }],
+            structuredContent: { id: res.id },
+        };
+    };
+}
+export function makeAgentNotifyHandler(client) {
+    return async (args, extra) => {
+        // ORB-1742 - stamp the sender session automatically.
+        const senderRef = mcpInstanceToken(args.senderRef, extra);
+        const res = await client.post('/v1/agent/notify', { ...args, senderRef });
+        return {
+            // ORB-1727 - the message is durable now: it reaches the recipient's
+            // inbox even when they are offline (delivery via the pending-mail
+            // pointer on their next tool call).
+            content: [{ type: 'text', text: `notified ${args.targetEmail} (message ${res.messageId} - delivered live if connected, waits in their inbox otherwise)` }],
+            structuredContent: { ok: true, messageId: res.messageId },
+        };
+    };
+}

package/dist/tools/agent-coordination.test.js

@@ -0,0 +1,156 @@
+/**
+ * ORB-705 - Multi-Agent Coordination MCP tools.
+ *
+ * Pins the contract that each tool wraps the right REST endpoint
+ * with the right body shape and surfaces the response. The actual
+ * end-to-end push behaviour is covered by the API-side tests in
+ * agent-sessions.test.ts.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeAgentHeartbeatHandler, makeAgentPresenceHandler, makeAgentNotifyHandler, } from './agent-coordination.js';
+import { makeAgentMessagesHandler } from './agent-messages.js';
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async () => {
+        const r = responses.shift();
+        if (!r)
+            throw new Error('unexpected fetch');
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: 'OK',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => '',
+        };
+    });
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+describe('orboto_agent_heartbeat', () => {
+    it('POSTs to /v1/agent/heartbeat with the merged body + returns the session token', async () => {
+        stub([{ json: { sessionToken: 'abc-123-token', sessionId: '00000000-0000-0000-0000-000000000001' } }]);
+        const handler = makeAgentHeartbeatHandler(client);
+        const result = await handler({
+            status: 'working',
+            capabilities: ['writes-tickets'],
+            clientInfo: { name: 'claude-code' },
+        });
+        expect(result.structuredContent).toMatchObject({
+            sessionToken: 'abc-123-token',
+            sessionId: '00000000-0000-0000-0000-000000000001',
+        });
+        expect(result.content[0].text).toContain('heartbeat ack');
+    });
+});
+describe('orboto_agent_presence', () => {
+    it('GETs /v1/agent/presence and renders one line per session', async () => {
+        stub([{
+                json: [
+                    {
+                        userId: '00000000-0000-0000-0000-000000000001',
+                        userEmail: 'alice@x.test',
+                        userFullName: 'Alice',
+                        sessionId: '00000000-0000-0000-0000-000000000010',
+                        status: 'working',
+                        workingOnTicket: { id: 't1', key: 'ORB-42', title: 'Test', projectKey: 'ORB' },
+                        capabilities: ['writes-tickets'],
+                        clientInfo: { name: 'claude-code' },
+                        lastSeenAt: new Date().toISOString(),
+                        createdAt: new Date().toISOString(),
+                    },
+                    {
+                        userId: '00000000-0000-0000-0000-000000000002',
+                        userEmail: 'bot@x.test',
+                        userFullName: null,
+                        sessionId: '00000000-0000-0000-0000-000000000011',
+                        status: 'idle',
+                        workingOnTicket: null,
+                        capabilities: [],
+                        clientInfo: { name: 'dispatcher-daemon' },
+                        lastSeenAt: new Date().toISOString(),
+                        createdAt: new Date().toISOString(),
+                    },
+                ],
+            }]);
+        const handler = makeAgentPresenceHandler(client);
+        const result = await handler();
+        const text = result.content[0].text;
+        expect(text).toContain('2 active session(s)');
+        expect(text).toContain('Alice (claude-code) - working · working on [ORB] ORB-42');
+        expect(text).toContain('bot@x.test (dispatcher-daemon) - idle');
+        expect(result.structuredContent.sessions).toHaveLength(2);
+    });
+    it('handles an empty workspace gracefully', async () => {
+        stub([{ json: [] }]);
+        const handler = makeAgentPresenceHandler(client);
+        const result = await handler();
+        expect(result.content[0].text).toBe('No active agent sessions in the workspace.');
+    });
+});
+describe('orboto_agent_notify', () => {
+    it('POSTs to /v1/agent/notify with the body the user supplied', async () => {
+        const capturedBody = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            capturedBody.push(JSON.parse(init?.body ?? '{}'));
+            return {
+                ok: true,
+                status: 200,
+                statusText: 'OK',
+                json: async () => ({ ok: true }),
+                text: async () => '',
+            };
+        });
+        const handler = makeAgentNotifyHandler(client);
+        const result = await handler({
+            targetEmail: 'bob@example.com',
+            kind: 'request',
+            subject: 'Please review ORB-42',
+            payload: { ticketKey: 'ORB-42' },
+        });
+        expect(capturedBody[0]).toMatchObject({
+            targetEmail: 'bob@example.com',
+            kind: 'request',
+            subject: 'Please review ORB-42',
+            payload: { ticketKey: 'ORB-42' },
+        });
+        expect(result.content[0].text).toContain('notified bob@example.com');
+        expect(result.structuredContent).toMatchObject({ ok: true });
+        // ORB-1742 - the sender session's ref is stamped automatically (per-
+        // process fallback here, since no MCP sessionId rides along).
+        expect(capturedBody[0].senderRef).toMatch(/^mcp-/);
+    });
+    it('ORB-1742: senderRef prefers the per-connection MCP session id, and an explicit ref wins outright', async () => {
+        const capturedBody = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            capturedBody.push(JSON.parse(init?.body ?? '{}'));
+            return {
+                ok: true, status: 200, statusText: 'OK',
+                json: async () => ({ ok: true, messageId: '00000000-0000-4000-8000-000000000000' }),
+                text: async () => '',
+            };
+        });
+        const handler = makeAgentNotifyHandler(client);
+        await handler({ targetEmail: 'bob@example.com', subject: 'hi' }, { sessionId: 'abc123' });
+        expect(capturedBody[0].senderRef).toBe('mcp-abc123');
+        await handler({ targetEmail: 'bob@example.com', subject: 'hi', senderRef: 'runner:custom' }, { sessionId: 'abc123' });
+        expect(capturedBody[1].senderRef).toBe('runner:custom');
+    });
+});
+describe('orboto_messages (ORB-1742 self-echo exclusion)', () => {
+    it('fetches with excludeRef = the session ref by default; includeOwnSends drops the filter', async () => {
+        const urls = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => {
+            urls.push(String(url));
+            return {
+                ok: true, status: 200, statusText: 'OK',
+                json: async () => ({ messages: [] }),
+                text: async () => '',
+            };
+        });
+        const handler = makeAgentMessagesHandler(client);
+        await handler({}, { sessionId: 'abc123' });
+        expect(urls[0]).toContain('excludeRef=mcp-abc123');
+        await handler({ includeOwnSends: true }, { sessionId: 'abc123' });
+        expect(urls[1]).not.toContain('excludeRef');
+    });
+});

package/dist/tools/agent-drift.js

@@ -0,0 +1,79 @@
+/**
+ * ORB-543 / ORB-1344 - agent-drift admin MCP tools.
+ *
+ * - `orboto_admin_agent_drift_list` - paginated drift log with filters
+ *    (user, drift type, date range, resolved status) + aggregate metrics.
+ * - `orboto_admin_agent_drift_resolve` - mark one drift event handled.
+ *
+ * Both wrap `/admin/agent-drift*` and require `admin:agent_drift:read` /
+ * `admin:agent_drift:write` (super-admin holds both).
+ */
+import { z } from 'zod';
+export const listAgentDriftToolConfig = {
+    title: 'List agent drift events',
+    description: 'List agent drift events (commits with no ticket key + no timer, or ticket transitions without a summary comment), newest first, with aggregate metrics. Filter by `userId`, `driftType` (untracked_commit | transition_without_summary), `from`/`to` ISO dates, and `resolved`. The response `enabled` flag is false when the operator has not turned drift detection on. Requires `admin:agent_drift:read`.',
+    inputSchema: z.object({
+        userId: z.string().uuid().optional().describe('Filter to one user.'),
+        driftType: z.enum(['untracked_commit', 'transition_without_summary']).optional(),
+        from: z.string().optional().describe('ISO timestamp lower bound (detected_at).'),
+        to: z.string().optional().describe('ISO timestamp upper bound (detected_at).'),
+        resolved: z.boolean().optional().describe('true = only resolved, false = only open.'),
+        limit: z.number().int().min(1).max(200).optional().describe('Default: 50.'),
+        cursor: z.string().optional().describe('Opaque cursor from a previous response.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeListAgentDriftHandler(client) {
+    return async (args) => {
+        const qs = new URLSearchParams();
+        if (args.userId)
+            qs.set('userId', args.userId);
+        if (args.driftType)
+            qs.set('driftType', args.driftType);
+        if (args.from)
+            qs.set('from', args.from);
+        if (args.to)
+            qs.set('to', args.to);
+        if (args.resolved !== undefined)
+            qs.set('resolved', String(args.resolved));
+        if (args.limit)
+            qs.set('limit', String(args.limit));
+        if (args.cursor)
+            qs.set('cursor', args.cursor);
+        const path = `/admin/agent-drift${qs.toString() ? `?${qs.toString()}` : ''}`;
+        const res = await client.get(path);
+        const header = res.enabled ? '' : '(drift detection is currently DISABLED - showing historical rows only)\n';
+        const lines = res.items.length === 0
+            ? '(no drift events)'
+            : res.items.map((e) => {
+                const who = e.userName ?? e.userEmail ?? e.userId.slice(0, 8);
+                const where = e.driftType === 'untracked_commit'
+                    ? `${e.commitSha?.slice(0, 8) ?? '?'} on ${e.repoUrl ?? '?'}`
+                    : `transition on ${e.ticketKey ?? e.ticketId?.slice(0, 8) ?? '?'}`;
+                const state = e.resolvedAt ? 'resolved' : (e.retroTicketKey ? `retro ${e.retroTicketKey}` : 'open');
+                return `- [${e.id.slice(0, 8)}] ${e.driftType} - ${who} - ${where} (${state}, ${e.detectedAt})`;
+            }).join('\n');
+        const metrics = `\n\nTotals: ${res.metrics.total} | ${Object.entries(res.metrics.byType).map(([k, v]) => `${k}=${v}`).join(', ')}`;
+        return {
+            content: [{ type: 'text', text: header + lines + metrics + (res.nextCursor ? `\n\n(next cursor: ${res.nextCursor})` : '') }],
+            structuredContent: res,
+        };
+    };
+}
+export const resolveAgentDriftToolConfig = {
+    title: 'Resolve an agent drift event',
+    description: 'Mark one agent drift event handled (stamps resolved_at). Idempotent. 404 if the id is unknown. Requires `admin:agent_drift:write`.',
+    inputSchema: z.object({
+        id: z.string().uuid().describe('UUID of the drift event to resolve.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeResolveAgentDriftHandler(client) {
+    return async ({ id }) => {
+        const res = await client.post(`/admin/agent-drift/${id}/resolve`, {});
+        return {
+            content: [{ type: 'text', text: `Resolved drift event ${id} at ${res.resolvedAt}.` }],
+            structuredContent: res,
+        };
+    };
+}

package/dist/tools/agent-drift.test.js

@@ -0,0 +1,87 @@
+/**
+ * ORB-543 / ORB-1344 - unit tests for the agent-drift admin MCP tools.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { makeListAgentDriftHandler, makeResolveAgentDriftHandler } from './agent-drift.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 EVENT = {
+    id: '11111111-1111-1111-1111-111111111111',
+    userId: '22222222-2222-2222-2222-222222222222',
+    userName: 'Claude Bot', userEmail: 'claude@orboto.io', userIsBot: true,
+    projectId: '33333333-3333-3333-3333-333333333333', projectKey: 'ORB',
+    driftType: 'untracked_commit',
+    commitSha: 'deadbeefcafe', repoUrl: 'https://github.com/x/y', commitMessage: 'wip',
+    pushId: 'abc', ticketId: null, ticketKey: null,
+    detectedAt: '2026-07-02T10:00:00.000Z', resolvedAt: null,
+    retroTicketId: null, retroTicketKey: null,
+};
+describe('orboto_admin_agent_drift_list', () => {
+    it('renders events + metrics and forwards filters to the querystring', async () => {
+        const calls = stub([
+            { json: { items: [EVENT], nextCursor: 'cur1', metrics: { total: 1, byType: { untracked_commit: 1 }, byUser: [] }, enabled: true } },
+        ]);
+        const res = await makeListAgentDriftHandler(client)({
+            userId: EVENT.userId, driftType: 'untracked_commit', resolved: false, limit: 10,
+        });
+        expect(calls[0].url).toContain('/admin/agent-drift?');
+        expect(calls[0].url).toContain('userId=22222222');
+        expect(calls[0].url).toContain('driftType=untracked_commit');
+        expect(calls[0].url).toContain('resolved=false');
+        expect(calls[0].url).toContain('limit=10');
+        const text = res.content[0].type === 'text' ? res.content[0].text : '';
+        expect(text).toContain('untracked_commit');
+        expect(text).toContain('Claude Bot');
+        expect(text).toContain('next cursor: cur1');
+    });
+    it('flags a disabled workspace in the header', async () => {
+        stub([
+            { json: { items: [], nextCursor: null, metrics: { total: 0, byType: {}, byUser: [] }, enabled: false } },
+        ]);
+        const res = await makeListAgentDriftHandler(client)({});
+        const text = res.content[0].type === 'text' ? res.content[0].text : '';
+        expect(text).toMatch(/DISABLED/);
+        expect(text).toContain('(no drift events)');
+    });
+    it('surfaces a 403 as an OrbotoApiError', async () => {
+        stub([{ ok: false, status: 403, json: { error: 'Forbidden' } }]);
+        await expect(makeListAgentDriftHandler(client)({})).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});
+describe('orboto_admin_agent_drift_resolve', () => {
+    it('POSTs to the resolve endpoint', async () => {
+        const calls = stub([{ json: { id: EVENT.id, resolvedAt: '2026-07-02T11:00:00.000Z' } }]);
+        const res = await makeResolveAgentDriftHandler(client)({ id: EVENT.id });
+        expect(calls[0].method).toBe('POST');
+        expect(calls[0].url).toContain(`/admin/agent-drift/${EVENT.id}/resolve`);
+        const text = res.content[0].type === 'text' ? res.content[0].text : '';
+        expect(text).toContain('Resolved drift event');
+    });
+    it('surfaces a 404 as an OrbotoApiError', async () => {
+        stub([{ ok: false, status: 404, json: { error: 'Drift event not found' } }]);
+        await expect(makeResolveAgentDriftHandler(client)({ id: EVENT.id })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});