@orboto/mcp 0.226.2 → 0.227.0

package/dist/tools/agent-coordination.js

@@ -4,10 +4,11 @@
  * @see ORB-704, ORB-706
  */
 import { z } from 'zod';
-import { AGENT_WAKE_LABELS, AgentInventoryEntrySchema, AgentInventoryKindSchema } from './agent-presence-schema.js';
+import { AGENT_WAKE_LABELS, AgentInventoryKindSchema, AgentSessionWakeSchema, } from './agent-presence-schema.js';
+import { AgentPresenceRowSchema } from './agent-presence-row.js';
 import { OrbotoApiError } from '../orboto-client.js';
 import { mcpInstanceToken } from './shared.js';
-import { AgentSessionScopeSchema } from './agent-session-scope.js';
+import { AgentSessionRoleSchema, AgentSessionScopeSchema } from './agent-session-scope.js';
 export const agentHeartbeatToolConfig = {
     title: 'Agent heartbeat (Multi-Agent Coordination)',
     description: 'Register or refresh this agent\'s presence with status detail. A live connection already counts as online (an open MCP event stream, `orboto messages --follow`, the agent WebSocket) - the heartbeat adds status: idle (default) | working (+workingOnTicketId) | blocked, capabilities (free-form strings for operator filters) and clientInfo.name (the runtime), and is the only presence path for turn-based clients without a standing connection. Rows older than 90 s count as offline; persist the returned sessionToken and send it on later heartbeats. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility (ORB-2136); an empty object clears it. `startedBy`: starter session id, same account.',
@@ -54,45 +55,99 @@ export function originText(s) {
     const where = [o.host ?? 'unknown host', o.repo, o.pid ? `pid ${o.pid}` : null, o.harness, o.client ? `${o.client}${o.clientVersion ? ` ${o.clientVersion}` : ''}` : null].filter(Boolean).join(' ');
     return ` [${s.state ?? 'live'}] on ${where}${o.startedAt ? ` since ${o.startedAt}` : ''}`;
 }
+/** ORB-2548 - the page an MCP presence read returns by default, sized so four rows fit the 4,000-character budget. */
+export const PRESENCE_PAGE_LIMIT = 4;
+export const PresenceFilterShape = {
+    role: AgentSessionRoleSchema.optional(),
+    state: z.enum(['live', 'quiet', 'orphaned', 'unknown_origin']).optional(),
+    email: z.string().min(3).max(320).optional(),
+    sessionId: z.string().min(8).max(36).optional(),
+    kind: AgentInventoryKindSchema.optional(),
+    wake: AgentSessionWakeSchema.optional(),
+    limit: z.number().int().min(1).max(200).optional(),
+    cursor: z.string().max(500).optional(),
+};
+export function presenceQuery(args, extra = {}) {
+    const qs = new URLSearchParams(extra);
+    for (const key of ['project', 'role', 'state', 'email', 'sessionId', 'kind', 'wake', 'cursor', 'for']) {
+        const value = args[key]?.trim();
+        if (value)
+            qs.set(key, value);
+    }
+    qs.set('limit', String(args.limit ?? PRESENCE_PAGE_LIMIT));
+    return qs.toString();
+}
+/** ORB-2548 - the answer for a project filter the API does not know or the caller may not see (its 404). */
+export function unknownProjectText(key) {
+    return `Project "${key.trim().toUpperCase()}" is unknown or not visible to you - no session is listed for it.`;
+}
+/** Runs the presence read; a 404 for a project filter becomes null, so the tool answers unknownProjectText instead of a raw error. */
+export async function readPresence(client, path, project) {
+    try {
+        return await client.get(path);
+    }
+    catch (err) {
+        if (project?.trim() && err instanceof OrbotoApiError && err.status === 404)
+            return null;
+        throw err;
+    }
+}
+/** The line that ends a page with more rows behind it. */
+export function nextPageLine(nextCursor) {
+    return nextCursor ? [`More sessions: call again with cursor "${nextCursor}", or narrow with email, sessionId, project, role, kind, wake or state.`] : [];
+}
+function presenceRow(s) {
+    const o = s.origin;
+    return {
+        sessionId: s.sessionId, userEmail: s.userEmail, userFullName: s.userFullName, kind: s.kind,
+        owner: s.owner?.name ?? s.owner?.email ?? (s.actsAs ? `acts as ${s.actsAs.name ?? s.actsAs.email}` : null),
+        status: s.status, lane: s.lane?.name ?? null, scope: s.scope ?? null, memberProjects: s.projects.length,
+        connections: [...new Set(s.connections.map((c) => c.type))], ...(s.wake ? { wake: s.wake } : {}), ...(s.state ? { state: s.state } : {}),
+        origin: o ? { host: o.host, repo: o.repo, pid: o.pid, harness: o.harness, client: o.client } : null,
+        workingOn: s.workingOnTicket ? s.workingOnTicket.key ?? s.workingOnTicket.id : null,
+        lastSeenAt: String(s.lastSeenAt), ...(s.redacted ? { redacted: true } : {}),
+    };
+}
+function presenceLine(s) {
+    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})` : '';
+    const owner = s.owner?.name ?? s.owner?.email ?? (s.actsAs ? `acts as ${s.actsAs.name ?? s.actsAs.email}` : s.kind === 'agent' ? 'unassigned' : 'self');
+    const declared = s.scope?.projectKeys ?? [];
+    const scope = s.scope?.role || declared.length ? `; scope: ${s.scope?.role ?? 'no role'}${declared.length ? ` on ${declared.join(', ')}` : ''}` : '';
+    const keys = s.projects.map((p) => p.key);
+    const projects = keys.length === 0 ? '' : keys.length <= 8 ? `; projects: ${keys.join(', ')}` : `; member of ${keys.length} projects`;
+    const connections = s.connections.length ? `; connections: ${[...new Set(s.connections.map((c) => c.type))].join(', ')}` : '';
+    return `- ${name} <${s.userEmail}> (${runtime}, instance ${s.sessionId}) - ${s.status}${originText(s)}${work}; owner: ${owner}${s.lane ? `; lane: ${s.lane.name}` : ''}${scope}${projects}${connections}${s.wake ? `; ${AGENT_WAKE_LABELS[s.wake]}` : ''}`;
+}
 export const agentPresenceToolConfig = {
     title: 'Workspace agent presence',
-    description: 'Active agent instances. The orboto_who set: lane workers and reviewers, inbox, MCP and runner connections; rows carry kind (agent | human by credential; alias isBot), actsAs, owner, projects, connections, wake (on_call: nothing wakes it), lane, sessionId, userEmail, runtime, capabilities, status, current ticket, reconnects, origin (host, repo, pid, client, harness, credential), state (live | quiet | orphaned | unknown_origin). Operators (admin:agents:read or admin:system:read) see the workspace, others their own sessions and those on their projects, a foreign row redacted (no pid, repo, machine, connections, inbox, owner). projectKey and kind filter client-side (`orboto agents --project KEY --bots|--humans`).',
+    description: 'Active agent instances. The orboto_who set from GET /v1/agent/who?include=inventory: lane workers and reviewers, inbox, MCP and runner connections. Each row: sessionId, account, kind (agent | human by credential), owner or acts-as, status, lane, declared scope, member project count, connection types, wake (on_call: nothing wakes it), state (live | quiet | orphaned | unknown_origin), origin (host, repo, pid, harness, client), current ticket. Filters run on the server: email, sessionId (id or 8+ character prefix), projectKey (sessions declared on it), role, kind, wake, state; 4 rows a page, nextCursor continues (cursor). A projectKey that is unknown or not visible to you answers so in one line, with no rows. Operators (admin:agents:read or admin:system:read) see the workspace, others their own sessions and those on their projects, a foreign row redacted. The full inventory row: `orboto agents --json`.',
     inputSchema: z.object({
-        projectKey: z.string().min(1).max(64).optional().describe('Only rows whose projects hold this key.'),
-        kind: AgentInventoryKindSchema.optional().describe('Only rows of this kind (by credential).'),
+        projectKey: z.string().min(1).max(64).optional(),
+        ...PresenceFilterShape,
     }).shape,
     outputSchema: z.object({
-        sessions: z.array(AgentInventoryEntrySchema),
+        sessions: z.array(AgentPresenceRowSchema),
+        nextCursor: z.string().nullable(),
     }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
-/** Client-side view filter (ORB-2135); the inventory route stays unfiltered and the chat mirror applies the same rule. */
-export function filterPresenceRows(rows, args) {
-    const key = args.projectKey?.trim().toUpperCase();
-    return rows.filter((row) => (!args.kind || row.kind === args.kind) && (!key || row.projects.some((p) => p.key.toUpperCase() === key)));
-}
 export function makeAgentPresenceHandler(client) {
     return async (args = {}) => {
-        const all = (await client.get('/v1/agent/who?include=inventory')).inventory ?? [];
-        const sessions = filterPresenceRows(all, args);
-        const lines = [];
-        if (sessions.length === 0) {
-            lines.push(all.length === 0 ? 'No active agent sessions in the workspace.' : `No active agent sessions match the filter (${all.length} active 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} <${s.userEmail}> (${runtime}, instance ${s.sessionId}) - ${s.status}${originText(s)}${work}; owner: ${s.owner?.name ?? s.owner?.email ?? (s.actsAs ? `acts as ${s.actsAs.name ?? s.actsAs.email}` : s.kind === 'agent' ? 'unassigned' : 'self')}${s.lane ? `; lane: ${s.lane.name}` : ''}${s.projects.length ? `; projects: ${s.projects.map((p) => p.key).join(', ')}` : ''}${s.connections.length ? `; connections: ${s.connections.map((c) => c.type).join(', ')}` : ''}${s.wake ? `; ${AGENT_WAKE_LABELS[s.wake]}` : ''}`);
-            }
-        }
+        const { projectKey, ...filters } = args;
+        const project = projectKey ?? filters.project;
+        const res = await readPresence(client, `/v1/agent/who?${presenceQuery({ ...filters, project }, { include: 'inventory' })}`, project);
+        if (!res)
+            return { content: [{ type: 'text', text: unknownProjectText(project) }], structuredContent: { sessions: [], nextCursor: null } };
+        const rows = res.inventory ?? [];
+        const filtered = Object.entries(args).some(([key, value]) => key !== 'limit' && key !== 'cursor' && value !== undefined && value !== '');
+        const lines = rows.length === 0
+            ? [filtered ? 'No active agent session matches the filter.' : 'No active agent sessions in the workspace.']
+            : [`${rows.length} active session(s)${res.nextCursor ? ' on this page' : ''}:`, ...rows.map(presenceLine), ...nextPageLine(res.nextCursor)];
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
-            structuredContent: { sessions },
+            structuredContent: { sessions: rows.map(presenceRow), nextCursor: res.nextCursor ?? null },
         };
     };
 }
@@ -163,7 +218,7 @@ export function reminderTooSoonText(err) {
 }
 export const agentNotifyToolConfig = {
     title: 'Notify an agent or user',
-    description: 'Message an agent or user. `to` takes a role address integrator@KEY (every live session with that role on the project, any account), an account email or a session id; targetEmail names the account (with a role address it narrows to that account). kind: request|error = work inside the scope the recipient holds (request needs a target + outcome); info = information; complete = result (needs outcome). outcome: one sentence, 10 to 1000 characters; body: the plain text of the message (any length, lands in payload.body; payload may carry other JSON); threadId links a reply to the message it answers. toSessionRef (instance short id, session ref or id) reaches ONE session of the account; project scopes an account message to sessions declared on it. A request to an account email without project or toSessionRef goes to its one live session, with several it is refused listing them (pick one with toSessionRef). A request no live session can receive is refused (no_recipient, naming the live sessions of the project; see orboto_who) unless queue: true holds it until a session declares the project. The answer names routedTo; routingNote "no session declared KEY" means nothing wakes - escalate. A request on a topic another role owns (orboto_who for) is refused; route: true sends it to the owner, forceTarget: true keeps the target. project is a key or UUID; senderRef defaults to this MCP session. An identical send (same recipient, project, kind, subject, payload; no threadId, no attachments) within the dedupe window (default 24 h) is not delivered again: the text says so and names the existing message. remind: true is a deliberate reminder of it (notifies again, at most one per 15 min, faster is refused with retryAfter); urgent: true is never suppressed and counts as a reminder. Loops and retries never set remind or urgent.',
+    description: 'Message an agent or user. `to` takes a role address integrator@KEY (every live session with that role on the project, any account), an account email or a session id; targetEmail names the account (with a role address it narrows to that account). kind: request|error = work inside the scope the recipient holds (request needs a target + outcome); info = information; complete = result (needs outcome). outcome: one sentence, 10 to 1000 characters; body: the plain text of the message (any length, lands in payload.body; payload may carry other JSON); threadId links a reply to the message it answers. toSessionRef (instance short id, session ref or id) reaches ONE session of the account; alone (no to, no targetEmail) a session id or short id addresses that session; project scopes an account message to sessions declared on it. A request to an account email without project or toSessionRef goes to its one live session, with several it is refused listing them (pick one with toSessionRef). A request no live session can receive is refused (no_recipient, naming the live sessions of the project; see orboto_who) unless queue: true holds it until a session declares the project. The answer names routedTo; routingNote "no session declared KEY" means nothing wakes - escalate. A request on a topic another role owns (orboto_who for) is refused; route: true sends it to the owner, forceTarget: true keeps the target. project is a key or UUID; senderRef defaults to this MCP session. An identical send (same recipient, project, kind, subject, payload; no threadId, no attachments) within the dedupe window (default 24 h) is not delivered again: the text says so and names the existing message. remind: true is a deliberate reminder of it (notifies again, at most one per 15 min, faster is refused with retryAfter); urgent: true is never suppressed and counts as a reminder. Loops and retries never set remind or urgent.',
     inputSchema: z.object({
         targetEmail: z.string().email().optional(),
         to: z.string().min(3).max(200).optional(),
@@ -235,8 +290,8 @@ export function notifyExample(kind, to) {
 export function notifyDefinitionError(args) {
     const kind = args.kind ?? 'info';
     const example = (text) => `Invalid arguments: ${text} Example: ${notifyExample(kind, args.to)}`;
-    if (!args.to && !args.targetEmail)
-        return example('name a recipient - `to` (integrator@KEY, an email or a session id) or `targetEmail`.');
+    if (!args.to && !args.targetEmail && !args.toSessionRef?.trim())
+        return example('name a recipient - `to` (integrator@KEY, an email or a session id), `targetEmail`, or `toSessionRef` (a session id or its short id).');
     const outcome = args.outcome?.trim() ?? '';
     if ((kind === 'request' || kind === 'complete') && !outcome) {
         return example(`\`outcome\` is required for a ${kind} - the outcome sentence (what must be true when it is done, or what was delivered), ${NOTIFY_OUTCOME_MIN} to ${NOTIFY_OUTCOME_MAX} characters.`);
@@ -275,7 +330,8 @@ export function makeAgentNotifyHandler(client) {
         }
         const who = res.ownerHint?.routed ? res.ownerHint.ownerAddress : args.to ?? args.targetEmail ?? '?';
         const recipients = (res.recipients ?? []).map((r) => r.label);
-        const target = recipients.length > 1 ? recipients.join(', ') : res.toSessionId ? `${who} session ${res.toSessionId.slice(0, 8)}` : who;
+        const sessionOnly = !res.ownerHint?.routed && !args.to && !args.targetEmail;
+        const target = recipients.length > 1 ? recipients.join(', ') : res.toSessionId ? `${sessionOnly ? '' : `${who} `}session ${res.toSessionId.slice(0, 8)}` : who;
         const routedTo = res.routedTo ?? (res.toSessionId ? 'session' : 'account');
         const note = res.routingNote ? ` - ${res.routingNote}` : '';
         if (res.deduplicated) {

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

@@ -82,7 +82,7 @@ describe('orboto_agent_presence', () => {
         expect(text).toContain('2 active session(s)');
         expect(text).toContain('Alice <alice@x.test> (claude-code, instance 00000000-0000-0000-0000-000000000010) - working · working on [ORB] ORB-42');
         expect(text).toContain('bot@x.test <bot@x.test> (dispatcher-daemon, instance 00000000-0000-0000-0000-000000000011) - idle [orphaned] on build-host sample-repo pid 4242 claude-code orboto-cli 1.2.3; owner: Alice');
-        expect(vi.mocked(fetch).mock.calls[0][0]).toBe('https://orboto.example.com/v1/agent/who?include=inventory');
+        expect(vi.mocked(fetch).mock.calls[0][0]).toBe('https://orboto.example.com/v1/agent/who?include=inventory&limit=4');
         expect(result.structuredContent.sessions).toHaveLength(2);
     });
     it('handles an empty workspace gracefully', async () => {
@@ -96,32 +96,56 @@ describe('orboto_agent_presence', () => {
         { userId: '00000000-0000-0000-0000-000000000002', userEmail: 'worker@x.test', userFullName: null, kind: 'agent', isBot: true, actsAs: null, owner: { id: '00000000-0000-0000-0000-000000000001', name: 'Alice', email: 'alice@x.test' }, autonomyPaused: false, lane: { id: '00000000-0000-0000-0000-000000000040', name: 'worker-1', role: 'implementation', paused: false }, projects: [{ id: '00000000-0000-0000-0000-000000000031', key: 'ACME', name: 'Acme' }, { id: '00000000-0000-0000-0000-000000000030', key: 'ORB', name: 'orboto' }], connections: [{ type: 'lane', label: 'worker-1' }, { type: 'live_events', label: 'MCP live events' }], workSessions: [], sessionId: '00000000-0000-0000-0000-000000000011', status: 'idle', workingOnTicket: null, capabilities: [], clientInfo: { name: 'pi' }, lastSeenAt: new Date().toISOString(), createdAt: new Date().toISOString() },
         { userId: '00000000-0000-0000-0000-000000000001', userEmail: 'alice@x.test', userFullName: 'Alice', kind: 'agent', isBot: true, actsAs: { id: '00000000-0000-0000-0000-000000000001', name: 'Alice', email: 'alice@x.test' }, owner: null, autonomyPaused: false, lane: null, projects: [], connections: [{ type: 'oauth', label: 'claude.ai' }], workSessions: [], sessionId: '00000000-0000-0000-0000-000000000012', status: 'idle', workingOnTicket: null, capabilities: [], clientInfo: {}, lastSeenAt: new Date().toISOString(), createdAt: new Date().toISOString() },
     ];
-    it('filters by projectKey (case-insensitive, projects only) and kind on the client side (ORB-2135)', async () => {
+    it('ORB-2548: sends every filter to the one presence read, projectKey as project, four rows a page by default', async () => {
         const handler = makeAgentPresenceHandler(client);
-        const ids = async (args) => {
-            stub([{ json: { sessions: [], inventory: presenceRows() } }]);
-            const result = await handler(args);
-            expect(vi.mocked(fetch).mock.calls.at(-1)?.[0]).toBe('https://orboto.example.com/v1/agent/who?include=inventory');
-            return result.structuredContent.sessions.map((s) => s.sessionId.slice(-2));
+        const url = async (args) => {
+            stub([{ json: { sessions: [], inventory: [] } }]);
+            await handler(args);
+            return String(vi.mocked(fetch).mock.calls.at(-1)?.[0]);
         };
-        expect(await ids({})).toEqual(['10', '11', '12']);
-        expect(await ids({ kind: 'agent' })).toEqual(['11', '12']);
-        expect(await ids({ kind: 'human' })).toEqual(['10']);
-        expect(await ids({ projectKey: 'acme' })).toEqual(['11']);
-        expect(await ids({ projectKey: 'ORB', kind: 'human' })).toEqual(['10']);
-        expect(await ids({ projectKey: 'NONE' })).toEqual([]);
-    });
-    it('says when a filter matched nothing but the workspace is not empty', async () => {
-        stub([{ json: { sessions: [], inventory: presenceRows() } }]);
+        expect(await url({})).toBe('https://orboto.example.com/v1/agent/who?include=inventory&limit=4');
+        expect(await url({ projectKey: 'acme', kind: 'agent' })).toBe('https://orboto.example.com/v1/agent/who?include=inventory&project=acme&kind=agent&limit=4');
+        expect(await url({ email: 'w@x.test', sessionId: 'c785946f', role: 'worker', wake: 'on_call', state: 'live', limit: 2, cursor: 'next-1' }))
+            .toBe('https://orboto.example.com/v1/agent/who?include=inventory&role=worker&state=live&email=w%40x.test&sessionId=c785946f&wake=on_call&cursor=next-1&limit=2');
+    });
+    it('ORB-2548: a projectKey that is unknown or not visible answers in one line instead of a raw 404', async () => {
+        stub([{ ok: false, status: 404, json: { errorKey: 'errors.agents.message_project_not_found' } }]);
+        const result = await makeAgentPresenceHandler(client)({ projectKey: 'nope' });
+        expect(result.isError).toBeUndefined();
+        expect(result.content[0].text).toBe('Project "NOPE" is unknown or not visible to you - no session is listed for it.');
+        expect(result.structuredContent).toEqual({ sessions: [], nextCursor: null });
+        stub([{ ok: false, status: 404, json: {} }]);
+        await expect(makeAgentPresenceHandler(client)({ email: 'x@y.test' })).rejects.toThrow();
+    });
+    it('says when a filter matched nothing', async () => {
+        stub([{ json: { sessions: [], inventory: [] } }]);
         const result = await makeAgentPresenceHandler(client)({ projectKey: 'NONE' });
-        expect(result.content[0].text).toBe('No active agent sessions match the filter (3 active in the workspace).');
+        expect(result.content[0].text).toBe('No active agent session matches the filter.');
     });
-    it('renders acts-as, lane, projects and connection types on each line', async () => {
-        stub([{ json: { sessions: [], inventory: presenceRows() } }]);
-        const text = (await makeAgentPresenceHandler(client)({ kind: 'agent' })).content[0].text;
-        expect(text).toContain('2 active session(s)');
-        expect(text).toContain('owner: Alice; lane: worker-1; projects: ACME, ORB; connections: lane, live_events');
+    it('renders acts-as, lane, scope, projects and connection types on each line and returns the compact row', async () => {
+        const rows = presenceRows().filter((row) => row.kind === 'agent').map((row, i) => (i === 0 ? { ...row, scope: { role: 'worker', projectKeys: ['ACME'] }, wake: 'channel' } : row));
+        stub([{ json: { sessions: [], inventory: rows, nextCursor: 'cursor-2' } }]);
+        const result = await makeAgentPresenceHandler(client)({ kind: 'agent' });
+        const text = result.content[0].text;
+        expect(text).toContain('2 active session(s) on this page');
+        expect(text).toContain('owner: Alice; lane: worker-1; scope: worker on ACME; projects: ACME, ORB; connections: lane, live_events; reachable by channel');
         expect(text).toContain('owner: acts as Alice; connections: oauth');
+        expect(text).toContain('More sessions: call again with cursor "cursor-2"');
+        const structured = result.structuredContent;
+        expect(structured.nextCursor).toBe('cursor-2');
+        expect(structured.sessions[0]).toEqual({
+            sessionId: '00000000-0000-0000-0000-000000000011', userEmail: 'worker@x.test', userFullName: null, kind: 'agent', owner: 'Alice',
+            status: 'idle', lane: 'worker-1', scope: { role: 'worker', projectKeys: ['ACME'] }, memberProjects: 2, connections: ['lane', 'live_events'],
+            wake: 'channel', origin: null, workingOn: null, lastSeenAt: rows[0].lastSeenAt,
+        });
+        expect(structured.sessions[1]).toMatchObject({ owner: 'acts as Alice', memberProjects: 0, connections: ['oauth'] });
+    });
+    it('names the member count instead of listing more than eight projects', async () => {
+        const many = Array.from({ length: 99 }, (_, i) => ({ id: '00000000-0000-0000-0000-000000000030', key: `P${i}`, name: `Project ${i}` }));
+        stub([{ json: { sessions: [], inventory: [{ ...presenceRows()[1], projects: many }] } }]);
+        const text = (await makeAgentPresenceHandler(client)({})).content[0].text;
+        expect(text).toContain('; member of 99 projects;');
+        expect(text).not.toContain('P98');
     });
 });
 describe('orboto_agent_notify', () => {
@@ -263,6 +287,22 @@ describe('ORB-2136 - session addressing', () => {
         expect(result.content[0].text).toContain('bob@example.com session cbb52195');
         expect(result.structuredContent).toMatchObject({ toSessionId: 'cbb52195-0000-4000-8000-000000000000' });
     });
+    it('ORB-2548: toSessionRef alone is a recipient - sent without to or targetEmail, the answer names the session', async () => {
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            seen.push(JSON.parse(init?.body ?? '{}'));
+            return { ok: true, status: 200, statusText: 'OK', json: async () => ({ ok: true, messageId: '00000000-0000-4000-8000-000000000000', toSessionId: 'cbb52195-0000-4000-8000-000000000000', routedTo: 'session' }), text: async () => '' };
+        });
+        const result = await makeAgentNotifyHandler(client)({ subject: 'hi', toSessionRef: 'cbb52195' }, { sessionId: 'abc123' });
+        expect(result.isError).toBeUndefined();
+        expect(seen[0]).toMatchObject({ toSessionRef: 'cbb52195', subject: 'hi' });
+        expect(seen[0]).not.toHaveProperty('to');
+        expect(result.content[0].text).toContain('notified session cbb52195 (message');
+        vi.restoreAllMocks();
+        const none = await makeAgentNotifyHandler(client)({ subject: 'hi' });
+        expect(none.isError).toBe(true);
+        expect(none.content[0].text).toContain('`toSessionRef` (a session id or its short id)');
+    });
     it('orboto_messages identifies this session on the fetch and renders sender and receiver identities', async () => {
         const seen = [];
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {

package/dist/tools/agent-messages-compact.test.js

@@ -1,5 +1,5 @@
 /**
- * ORB-2502 - orboto_messages lists the newest 10 unread compactly with the exact count; all:true keeps every message in full.
+ * ORB-2502 - orboto_messages lists the newest 4 unread compactly (10 before ORB-2548) with the exact count; all:true keeps every message in full.
  */
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { OrbotoClient } from '../orboto-client.js';
@@ -23,11 +23,11 @@ function stubInbox(urls) {
     });
 }
 describe('ORB-2502 - the compact inbox on MCP', () => {
-    it('asks for the newest 10 compactly, prints the excerpt and the count, and leaves the payload out of the structured answer', async () => {
+    it('asks for the newest 4 compactly, prints the excerpt and the count, and leaves the payload out of the structured answer', async () => {
         const urls = [];
         stubInbox(urls);
         const result = await makeAgentMessagesHandler(client)({ since: '2026-09-30T00:00:00Z' }, { sessionId: 'abc' });
-        expect(urls[0]).toContain('limit=10');
+        expect(urls[0]).toContain('limit=4');
         expect(urls[0]).toContain('compact=true');
         expect(urls[0]).toContain('since=2026-09-30T00%3A00%3A00Z');
         const text = result.content[0].text;

package/dist/tools/agent-messages.js

@@ -22,10 +22,12 @@ export function repeatMarks(m) {
     ].filter(Boolean);
     return marks.length ? ` [${marks.join(', ')}]` : '';
 }
+/** ORB-2548 - the compact page an MCP inbox read returns by default, sized so it fits the 4,000-character budget. */
+export const COMPACT_PAGE_LIMIT = 4;
 const UNREGISTERED_INBOX_HINT = 'Not registered: only account mail is listed. Register with orboto_session_start to see the mail addressed to your session.';
 export const agentMessagesToolConfig = {
     title: 'Agent inbox and message work',
-    description: 'Your inbox as THIS session sees it. It holds mail to this session, account mail inside your declared scope, broadcasts; sibling-session mail and own sends stay out (includeOwnSends lists your sends with recipient session, delivered/read state, thread), all:true is the account view in full (ORB-2136). Default: the newest 10 unread, newest first, a header plus 300 payload characters each, then `N unread, M older than 7 days`; limit and since (ISO time or message id) narrow it. Before orboto_session_start only account mail is listed; register to see mail addressed to your session (ORB-2347). messageWork carries durable work ownership (mutation schema: orboto_api_search) - claim before executing. ackIds (message ids) acks: it completes an unclaimed request; claimed work with open steps is refused until messageWork completes or blocks it. dismiss: not_mine hides it here and tells the sender, obsolete/duplicate close it for the account (note or duplicateOf required). Never leave mail you read and judged. Reply via orboto_agent_notify with threadId (toSessionRef = from.sessionId).',
+    description: 'Your inbox as THIS session sees it. It holds mail to this session, account mail inside your declared scope, broadcasts; sibling-session mail and own sends stay out (includeOwnSends lists your sends with recipient session, delivered/read state, thread), all:true is the account view in full (ORB-2136). Default: the newest 4 unread, newest first, a header plus 300 payload characters each, then `N unread, M older than 7 days`; limit and since (ISO time or message id) narrow it. Server-side filters (ORB-2548): direction sent (only your sends, any read state), threadId (that message and its answers), kind; nextCursor continues the page (cursor). Before orboto_session_start only account mail is listed; register to see mail addressed to your session (ORB-2347). messageWork carries durable work ownership (mutation schema: orboto_api_search) - claim before executing. ackIds (message ids) acks: it completes an unclaimed request; claimed work with open steps is refused until messageWork completes or blocks it. dismiss: not_mine hides it here and tells the sender, obsolete/duplicate close it for the account (note or duplicateOf required). Never leave mail you read and judged. Reply via orboto_agent_notify with threadId (toSessionRef = from.sessionId).',
     inputSchema: z.object({
         messageWork: z.record(z.unknown()).optional()
             .describe('Work envelope {messageId, mutation, cursor, limit, openOnly}.'),
@@ -34,6 +36,10 @@ export const agentMessagesToolConfig = {
         since: z.string().optional(),
         project: z.string().min(1).max(64).optional().describe('Key/UUID; includes unscoped mail.'),
         includeOwnSends: z.boolean().default(false),
+        direction: z.enum(['received', 'sent']).optional(),
+        threadId: z.string().uuid().optional(),
+        kind: z.enum(['request', 'error', 'info', 'complete']).optional(),
+        cursor: z.string().max(500).optional(),
         ackIds: z.array(z.string().uuid()).max(200).optional(),
         dismiss: z.object({
             ids: z.array(z.string().uuid()).min(1).max(200),
@@ -66,6 +72,7 @@ export const agentMessagesToolConfig = {
         acked: z.number().int(),
         dismissed: z.number().int().optional(),
         closed: z.number().int().optional(),
+        nextCursor: z.string().nullable().optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
 };
@@ -116,28 +123,40 @@ export function makeAgentMessagesHandler(client) {
         const q = new URLSearchParams();
         if (args.all)
             q.set('all', 'true');
-        q.set('limit', String(args.limit ?? (compact ? 10 : 50)));
+        q.set('limit', String(args.limit ?? (compact ? COMPACT_PAGE_LIMIT : 50)));
         if (compact)
             q.set('compact', 'true');
         if (args.since)
             q.set('since', args.since);
         if (args.project)
             q.set('project', args.project);
+        if (args.direction)
+            q.set('direction', args.direction);
+        if (args.threadId)
+            q.set('threadId', args.threadId);
+        if (args.kind)
+            q.set('kind', args.kind);
+        if (args.cursor)
+            q.set('cursor', args.cursor);
         const instanceToken = mcpInstanceToken(undefined, extra);
         if (args.includeOwnSends)
             q.set('includeOwn', 'true');
-        else
+        else if (args.direction !== 'sent')
             q.set('excludeRef', instanceToken);
-        const { messages, sessionId, counts } = await client.get(`/v1/agent/messages?${q.toString()}`, { instanceToken });
+        const { messages, sessionId, counts, nextCursor } = await client.get(`/v1/agent/messages?${q.toString()}`, { instanceToken });
         const header = (m) => `${m.own ? `[sent] ${sentState(m)} ` : ''}[${m.kind}]${m.projectKey ? ` [${m.projectKey}]` : ''}${repeatMarks(m)} ${m.subject} (from ${m.from?.label ?? m.fromUserId} to ${m.to?.label ?? m.toUserId}, ${m.createdAt}, id ${m.id}${m.threadId ? `, thread ${m.threadId}` : ''})`;
         const lines = messages.length === 0
             ? [acked > 0 ? `Acknowledged ${acked} message(s). Inbox empty.` : 'Inbox empty.']
             : messages.flatMap((m) => (compact ? compactLines(m, header(m)) : [`${header(m)}${m.payload ? ` payload: ${JSON.stringify(m.payload)}` : ''}`]));
+        if (messages.length === 0 && args.direction === 'sent')
+            lines[0] = 'Nothing sent matches.';
         if (messages.length > 0) {
             lines.push(`Acknowledge with ackIds once handled; reply via orboto_agent_notify with threadId (toSessionRef = the sender's instance short id reaches that session only).`);
         }
         if (compact && counts)
             lines.push(`${counts.unread} unread, ${counts.olderThan7Days} older than 7 days (all, limit N, since)`);
+        if (nextCursor)
+            lines.push(`More messages: call again with cursor "${nextCursor}".`);
         if (args.dismiss) {
             lines.unshift(`Dismissed ${dismissedCount} message(s) as ${args.dismiss.reason}${closedCount > 0 ? `, ${closedCount} closed for the account` : ''}${feedbackSent > 0 ? `, ${feedbackSent} sender(s) told about the misroute` : ''}.`);
         }
@@ -160,6 +179,7 @@ export function makeAgentMessagesHandler(client) {
                 acked,
                 dismissed: dismissedCount,
                 closed: closedCount,
+                nextCursor: nextCursor ?? null,
             },
         };
     };

package/dist/tools/agent-presence-row.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { AgentInventoryKindSchema, AgentSessionWakeSchema } from './agent-presence-schema.js';
+import { AgentSessionScopeSchema } from './agent-session-scope.js';
+/** ORB-2548 - one presence row as orboto_agent_presence returns it; the full inventory row is `orboto agents --json` and `GET /v1/agent/who?include=inventory`. */
+export const AgentPresenceRowSchema = z.object({
+    sessionId: z.string().uuid(),
+    userEmail: z.string(),
+    userFullName: z.string().nullable(),
+    kind: AgentInventoryKindSchema,
+    owner: z.string().nullable(),
+    status: z.string(),
+    lane: z.string().nullable(),
+    scope: AgentSessionScopeSchema.nullable(),
+    memberProjects: z.number().int(),
+    connections: z.array(z.string()),
+    wake: AgentSessionWakeSchema.optional(),
+    state: z.string().optional(),
+    origin: z.object({ host: z.string().nullable(), repo: z.string().nullable(), pid: z.number().nullable(), harness: z.string().nullable(), client: z.string().nullable() }).nullable(),
+    workingOn: z.string().nullable(),
+    lastSeenAt: z.string(),
+    redacted: z.boolean().optional(),
+});

package/dist/tools/agent-who.js

@@ -1,19 +1,17 @@
 /** ORB-2264 - the live directory: who a sender can address before sending. */
 import { z } from 'zod';
-import { AgentSessionRoleSchema } from './agent-session-scope.js';
 import { ownerLine } from './responsibilities.js';
-import { originText } from './agent-coordination.js';
+import { nextPageLine, originText, PresenceFilterShape, presenceQuery, readPresence, unknownProjectText } from './agent-coordination.js';
 import { AGENT_WAKE_LABELS } from './agent-presence-schema.js';
 export const agentWhoToolConfig = {
     title: 'Who receives agent mail',
-    description: 'Live agent sessions and the role addresses (integrator@KEY) they answer to. Each row names account, role, declared projects, last seen, wake channel and current ticket; address a role from here, never a session id copied from a log. `for` (free text) names the topic owner and keeps its sessions; `state` keeps one state (orphaned: only another process touches it).',
+    description: 'Live agent sessions and the role addresses (integrator@KEY) they answer to. GET /v1/agent/who; each row names account, role, declared projects, last seen, wake channel and current ticket; address a role from here, never a session id copied from a log. `for` (free text) names the topic owner and keeps its sessions; `state` keeps one state (orphaned: only another process touches it); email, sessionId (id or 8+ character prefix), kind and wake narrow on the server; 4 rows a page, nextCursor continues (cursor); a project that is unknown or not visible to you answers so in one line.',
     inputSchema: z.object({
         project: z.string().min(1).max(64).optional(),
-        role: AgentSessionRoleSchema.optional(),
         for: z.string().min(2).max(2000).optional(),
-        state: z.enum(['live', 'quiet', 'orphaned', 'unknown_origin']).optional(),
+        ...PresenceFilterShape,
     }).shape,
-    outputSchema: z.object({ sessions: z.array(z.unknown()), owner: z.unknown().optional() }).shape,
+    outputSchema: z.object({ sessions: z.array(z.unknown()), owner: z.unknown().optional(), nextCursor: z.string().nullable() }).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
 /** One directory row as a line: address, account, session, projects, channel, ticket. */
@@ -28,25 +26,18 @@ export function whoLine(s) {
 }
 export function makeAgentWhoHandler(client) {
     return async (args = {}) => {
-        const qs = new URLSearchParams();
-        if (args.state)
-            qs.set('state', args.state);
-        if (args.project)
-            qs.set('project', args.project);
-        if (args.role)
-            qs.set('role', args.role);
-        if (args.for)
-            qs.set('for', args.for);
-        const res = await client.get(`/v1/agent/who${qs.size ? `?${qs.toString()}` : ''}`);
+        const res = await readPresence(client, `/v1/agent/who?${presenceQuery(args)}`, args.project);
+        if (!res)
+            return { content: [{ type: 'text', text: unknownProjectText(args.project) }], structuredContent: { sessions: [], nextCursor: null } };
         const ownerLines = args.for
             ? [res.owner ? `Owner:\n${ownerLine(res.owner)}` : `No entry in the responsibility map matches "${args.for}".`]
             : [];
         const lines = res.sessions.length
-            ? [...ownerLines, `${res.sessions.length} live session(s):`, ...res.sessions.map(whoLine)]
+            ? [...ownerLines, `${res.sessions.length} live session(s)${res.nextCursor ? ' on this page' : ''}:`, ...res.sessions.map(whoLine), ...nextPageLine(res.nextCursor)]
             : [...ownerLines, res.owner ? `No live session answers to ${res.owner.entry.ownerAddress} - send with queue: true and project ${res.owner.entry.ownerAddress.split('@')[1]} to keep it until one declares it.` : 'No live session matches - a request sent now answers no_recipient unless it is queued.'];
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
-            structuredContent: { sessions: res.sessions, ...(args.for ? { owner: (res.owner ?? null) } : {}) },
+            structuredContent: { sessions: res.sessions, ...(args.for ? { owner: (res.owner ?? null) } : {}), nextCursor: res.nextCursor ?? null },
         };
     };
 }

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

@@ -17,10 +17,17 @@ describe('orboto_who', () => {
             return { ok: true, status: 200, statusText: 'OK', text: async () => '', json: async () => ({ sessions: [entry] }) };
         });
         const result = await makeAgentWhoHandler(client)({ project: 'ORB', role: 'integrator' });
-        expect(urls[0]).toBe('https://orboto.example.com/v1/agent/who?project=ORB&role=integrator');
+        expect(urls[0]).toBe('https://orboto.example.com/v1/agent/who?project=ORB&role=integrator&limit=4');
         expect(result.content[0].text).toContain('integrator@ORB - claude@orboto.io session f072e1c5, working, claude-code online');
         expect(result.structuredContent).toMatchObject({ sessions: [expect.objectContaining({ shortId: 'f072e1c5' })] });
     });
+    it('ORB-2548: a project that is unknown or not visible answers in one line instead of a raw 404', async () => {
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({ ok: false, status: 404, statusText: 'Not Found', headers: new Headers(), text: async () => '{"errorKey":"errors.agents.message_project_not_found"}', json: async () => ({}) }));
+        const result = await makeAgentWhoHandler(client)({ project: 'gone' });
+        expect(result.isError).toBeUndefined();
+        expect(result.content[0].text).toBe('Project "GONE" is unknown or not visible to you - no session is listed for it.');
+        expect(result.structuredContent).toEqual({ sessions: [], nextCursor: null });
+    });
     it('says a request would be refused when nobody matches, and is read-only', async () => {
         vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({ ok: true, status: 200, statusText: 'OK', text: async () => '', json: async () => ({ sessions: [] }) }));
         const result = await makeAgentWhoHandler(client)({});
@@ -41,6 +48,6 @@ describe('orboto_who', () => {
             return { ok: true, status: 200, statusText: 'OK', text: async () => '', json: async () => ({ sessions: [] }) };
         });
         await makeAgentWhoHandler(client)({ state: 'unknown_origin' });
-        expect(urls[0]).toBe('https://orboto.example.com/v1/agent/who?state=unknown_origin');
+        expect(urls[0]).toBe('https://orboto.example.com/v1/agent/who?state=unknown_origin&limit=4');
     });
 });

package/dist/tools/primer-facts.js

@@ -99,14 +99,14 @@ export function makePrimerFactListHandler(client) {
 }
 export const primerFactAddToolConfig = {
     title: 'Record a new project primer fact',
-    description: 'Record a new structured fact about the project that future AI agents should see at session start. Use when you learn something during work that is missing from the primer (a library version, a convention, a deployment quirk, an architecture decision). Note: the auto-generated primer does NOT automatically include CLAUDE.md / AGENTS.md content unless the operator configured repo briefings and the API host can read those files from disk - most deployments cannot. Treat key conventions documented in CLAUDE.md / AGENTS.md as fair game to record here so they survive cross-deployment. Set observed=true when you are recording from a bot/agent context - the fact will land as agent_observed and require operator verification before losing the (observed) marker.'
+    description: 'Record a new structured fact about the project that future AI agents should see at session start. Use when you learn something during work that is missing from the primer (a library version, a convention, a deployment quirk, an architecture decision). Note: the auto-generated primer does NOT automatically include CLAUDE.md / AGENTS.md content unless the operator configured repo briefings and the API host can read those files from disk - most deployments cannot. Treat key conventions documented in CLAUDE.md / AGENTS.md as fair game to record here so they survive cross-deployment. Set observed=true when you are recording from a bot/agent context - the fact will land as agent_observed and require a person to verify it before it loses the (observed) marker (CLI: orboto primer-fact add <KEY> --category <c> --key <k> --value "<v>" --observed).'
         + FACT_WRITING_CONTRACT,
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key, e.g. "ORB". Case-insensitive.'),
         category: PrimerFactCategoryEnum.describe('Category bucket. Pick the closest fit; categories are fixed. Use "non_functional" to capture an explicit non-functional requirement (performance / security / DSGVO / operations / i18n) - the key names the sub-area, the value is the requirement; these render verbatim in the requirements-spec NFR chapter. Use "glossary" for a term/definition pair - these render only in the requirements-spec glossary chapter.'),
         key: z.string().min(1).max(120).describe('Short machine-readable identifier, e.g. "package-manager", "node-version", "css-framework". Lowercase + dashes preferred.'),
         value: z.string().min(1).max(8000).describe('Human-readable Markdown body, 1-3 sentences typically. Include a version number, a path, or a command where relevant.'),
-        observed: z.boolean().default(false).describe('True = source is agent_observed (needs operator verification). False = manual entry by operator. Bots without project:edit get coerced to agent_observed server-side regardless.'),
+        observed: z.boolean().default(false).describe('True = source is agent_observed (needs operator verification). False = manual entry by operator. A bot account or an agent key is always coerced to agent_observed server-side, whatever is sent.'),
         allowOversize: z.boolean().optional().describe('Override the hard size-cap block (300*2 chars). Only after a call was blocked.'),
         oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true - why this value genuinely needs the length. Audit-logged.'),
     }).shape,
@@ -151,7 +151,7 @@ export function makePrimerFactAddHandler(client) {
 }
 export const primerFactUpdateToolConfig = {
     title: 'Update an existing primer fact',
-    description: 'Update an existing fact. Use this when the value has changed (e.g. version bumped) or you are renaming the key. Bumps last_verified_at automatically when the value changes; pure renames leave it untouched. To replace a fact while preserving history, use orboto_primer_fact_supersede instead.'
+    description: 'Update an existing fact. Use this when the value has changed (e.g. version bumped) or you are renaming the key. Bumps last_verified_at automatically when the value changes; pure renames leave it untouched. To replace a fact while preserving history, use orboto_primer_fact_supersede instead. A person decides: a bot account or an agent key gets 403 errors.primer_facts.update_needs_person and proposes a corrected fact with orboto_primer_fact_add (observed) instead.'
         + FACT_WRITING_CONTRACT,
     inputSchema: z.object({
         factId: z.string().min(1).describe('UUID of the fact to update. Read it from orboto_primer_fact_list output.'),
@@ -206,7 +206,7 @@ export function makePrimerFactUpdateHandler(client) {
 }
 export const primerFactSupersedeToolConfig = {
     title: 'Replace a primer fact while preserving history',
-    description: 'Replace a fact with a corrected version, preserving the old one in history (linked via superseded_by_id). Use when you discover a previously recorded fact was wrong; do not just delete it. The old row gets a tombstoned key suffix so the partial unique index does not collide; the new row starts unverified and needs operator verification before losing the (observed) marker.'
+    description: 'Replace a fact with a corrected version, preserving the old one in history (linked via superseded_by_id). Use when you discover a previously recorded fact was wrong; do not just delete it. The old row gets a tombstoned key suffix so the partial unique index does not collide; the new row starts unverified and needs a person to verify it before it loses the (observed) marker. A person decides: a bot account or an agent key gets 403 errors.primer_facts.supersede_needs_person and proposes the corrected fact with orboto_primer_fact_add (observed) instead.'
         + FACT_WRITING_CONTRACT,
     inputSchema: z.object({
         oldFactId: z.string().min(1).describe('UUID of the fact being replaced.'),
@@ -247,7 +247,7 @@ export function makePrimerFactSupersedeHandler(client) {
 }
 export const primerFactVerifyToolConfig = {
     title: 'Verify an agent-observed primer fact',
-    description: 'Promote an agent-observed fact to verified. A person verifies: a bot account or an agent key gets 403 errors.primer_facts.verify_needs_person, so an agent proposes and never confirms. Removes the (observed) marker from the rendered primer and stamps verifiedBy / verifiedAt.',
+    description: 'Promote an agent-observed fact to verified. A person verifies: a bot account or an agent key gets 403 errors.primer_facts.verify_needs_person, so an agent proposes and never confirms (CLI: orboto primer-fact verify). Removes the (observed) marker from the rendered primer and stamps verifiedBy / verifiedAt.',
     inputSchema: z.object({
         factId: z.string().min(1).describe('UUID of the fact to verify.'),
     }).shape,
@@ -274,7 +274,7 @@ export function makePrimerFactVerifyHandler(client) {
 }
 export const primerFactDeleteToolConfig = {
     title: 'Delete a primer fact',
-    description: 'Hard-delete a fact. Prefer orboto_primer_fact_supersede when the fact is being replaced; only delete when the fact was wrong from the start or no longer relevant. Writes an audit-log entry; the row itself is gone (no soft-delete).',
+    description: 'Hard-delete a fact. Prefer orboto_primer_fact_supersede when the fact is being replaced; only delete when the fact was wrong from the start or no longer relevant. Writes an audit-log entry; the row itself is gone (no soft-delete). Deleting an unverified agent-observed fact is the Reject of the review queue. A person decides: a bot account or an agent key gets 403 errors.primer_facts.reject_needs_person (observed proposal) or errors.primer_facts.delete_needs_person (CLI: orboto primer-fact reject).',
     inputSchema: z.object({
         factId: z.string().min(1).describe('UUID of the fact to delete.'),
         reason: z.string().max(500).optional().describe('Optional human-readable reason; recorded in the audit log details for future operators.'),

package/dist/tools/read-budget.test.js

@@ -0,0 +1,161 @@
+/**
+ * ORB-2548 - the evidence cases of the OCP integrator (2026-10-16) answered
+ * inside the 4,000-character budget: presence returned 236,455 characters
+ * with 1 of 32 rows kept, and finding one session took ~230 kB of expand
+ * calls; the inbox needed one to three expand calls.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { DEFAULT_BUDGET_CHARS, applyResponseBudget, budgetFor, measureHalves } from '../response-budget.js';
+import { makeAgentPresenceHandler } from './agent-coordination.js';
+import { makeAgentWhoHandler } from './agent-who.js';
+import { makeAgentMessagesHandler } from './agent-messages.js';
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+const uuid = (n, tail = 0) => `${String(n).padStart(8, '0')}-0000-4000-8000-${String(tail).padStart(12, '0')}`;
+/** One inventory row in the shape the evidence measured: a bot account that is a member of 80 projects (~10 kB, the live rows measured 1.7 to 10.3 kB). */
+function inventoryRow(i) {
+    const account = Math.floor(i / 4);
+    return {
+        userId: uuid(account, 1), userEmail: `agent-${account}-f82fd0ea@agents.internal`, userFullName: `Agent ${account}`, kind: 'agent', isBot: true,
+        actsAs: null, owner: { id: uuid(900, 2), name: 'Operator Person', email: 'operator@example.test' }, autonomyPaused: false,
+        sessionId: uuid(i, 3), status: 'idle', lane: null,
+        projects: Array.from({ length: 80 }, (_, p) => ({ id: uuid(p, 4), key: `P${String(p).padStart(3, '0')}`, name: `Project number ${p} - long name` })),
+        connections: [{ type: 'api_key', label: 'agent key for the build host' }, { type: 'channel', label: 'claude-code wake channel' }],
+        wake: 'channel', workingOnTicket: { id: uuid(i, 5), key: `ORB-${2500 + i}`, title: 'A ticket title of ordinary length for a working session', projectKey: 'ORB' },
+        workSessions: [{ ticketId: uuid(i, 5), ticketKey: `ORB-${2500 + i}`, role: 'implementation', leaseUntil: '2026-10-16T10:15:00.000Z', resourceClaims: [] }],
+        capabilities: ['writes-tickets', 'reviews'],
+        clientInfo: { name: 'claude-code', host: 'build-host.fritz.box', channel: 'claude-code', credential: 'api_key', credentialId: uuid(i, 6), credentialActor: 'agent', channelStart: 'orboto-claude', contextReportedAt: '2026-10-16T09:51:55.631Z' },
+        scope: { projectKeys: ['OCP'], role: i === 17 ? 'integrator' : 'worker' },
+        unreadMessages: 3, wakes: { count: 4, precision: 1, wrongWakeContextTokens: 0, backlogSeen: 0 },
+        guard: { held: 0, released: 2, stalled: 0, consecutiveHolds: 0, lastOutcome: 'released', lastReason: null, lastAt: '2026-10-16T09:50:00.000Z', paused: false },
+        knowledge: { writes: 0, asks: 1, lastAt: null, localPending: false },
+        restartPending: false, restartReason: null, restartable: true, reconnects: 2, lastReconnectAt: '2026-10-16T09:40:00.000Z',
+        lastSeenAt: '2026-10-16 09:54:00.504+00', createdAt: '2026-10-16 08:01:12.719715+00',
+        origin: { host: 'build-host', machineId: '4ea7904991187bf1', repo: 'orboto-control-plane', pid: 15503 + i, startedAt: '2026-10-16T08:00:00.000Z', client: 'orboto-mcp', clientVersion: '0.224.0', harness: 'claude-code', credential: 'api_key', known: true },
+        state: 'live', activity: 'live', touchedAt: '2026-10-16 09:54:00.504+00',
+    };
+}
+const WORKSPACE = Array.from({ length: 32 }, (_, i) => inventoryRow(i));
+/** The presence read as the API answers it: the ORB-2548 filters and the page on the server (the API side is tested in apps/api). */
+function servePresence() {
+    const urls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+        const url = new URL(String(input));
+        urls.push(url.pathname + url.search);
+        const q = url.searchParams;
+        const rows = WORKSPACE.filter((r) => (!q.get('sessionId') || r.sessionId.startsWith(q.get('sessionId')))
+            && (!q.get('email') || r.userEmail === q.get('email'))
+            && (!q.get('role') || r.scope.role === q.get('role')));
+        const start = q.get('cursor') ? Number(q.get('cursor')) : 0;
+        const limit = Number(q.get('limit') ?? rows.length);
+        const page = rows.slice(start, start + limit);
+        const nextCursor = start + limit < rows.length ? String(start + limit) : null;
+        const sessions = page.map((r) => ({
+            sessionId: r.sessionId, shortId: r.sessionId.slice(0, 8), userId: r.userId, email: r.userEmail, isBot: true, role: r.scope.role,
+            projectKeys: r.scope.projectKeys, ticketKeys: [], addresses: [`${r.scope.role}@OCP`], lastSeenAt: r.lastSeenAt,
+            channel: { announced: 'claude-code', online: true }, wake: r.wake, currentTicket: { key: r.workingOnTicket.key, title: r.workingOnTicket.title },
+            status: r.status, host: 'build-host.fritz.box', origin: r.origin, state: r.state, activity: r.activity, createdAt: r.createdAt,
+        }));
+        const body = q.get('include') === 'inventory' ? { sessions, inventory: page, nextCursor } : { sessions, nextCursor };
+        return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => JSON.stringify(body) };
+    });
+    return urls;
+}
+function underBudget(tool, result) {
+    const halves = measureHalves(result);
+    const outcome = applyResponseBudget(tool, result, {});
+    return { ...halves, truncated: outcome.truncatedChars, budget: budgetFor(tool, {}) };
+}
+describe('ORB-2548 - presence reads fit the MCP response budget', () => {
+    it('reproduces the evidence: the unfiltered inventory of 32 sessions is over 230 kB, far over the 4,000 budget', () => {
+        const all = JSON.stringify({ sessions: WORKSPACE }).length;
+        expect(all).toBeGreaterThan(230_000);
+        expect(budgetFor('orboto_agent_presence', {})).toBe(DEFAULT_BUDGET_CHARS);
+    });
+    it('one session by its short id comes back whole, under budget, without an expand handle', async () => {
+        const urls = servePresence();
+        const result = await makeAgentPresenceHandler(client)({ sessionId: uuid(17, 3).slice(0, 8) });
+        const m = underBudget('orboto_agent_presence', result);
+        expect(urls[0]).toBe(`/v1/agent/who?include=inventory&sessionId=${uuid(17, 3).slice(0, 8)}&limit=4`);
+        expect(m.truncated).toBe(0);
+        expect(m.structuredChars).toBeLessThan(DEFAULT_BUDGET_CHARS);
+        expect(m.textChars).toBeLessThan(DEFAULT_BUDGET_CHARS);
+        const { sessions } = result.structuredContent;
+        expect(sessions).toEqual([expect.objectContaining({ sessionId: uuid(17, 3), scope: { projectKeys: ['OCP'], role: 'integrator' } })]);
+        expect(result.content[0].text).toContain(`instance ${uuid(17, 3)}`);
+    });
+    it('an account email with four sessions, and the unfiltered first page of four, stay under budget with nextCursor for the rest', async () => {
+        servePresence();
+        const byEmail = await makeAgentPresenceHandler(client)({ email: 'agent-2-f82fd0ea@agents.internal' });
+        expect(byEmail.structuredContent.sessions).toHaveLength(4);
+        expect(underBudget('orboto_agent_presence', byEmail)).toMatchObject({ truncated: 0 });
+        const first = await makeAgentPresenceHandler(client)({});
+        const m = underBudget('orboto_agent_presence', first);
+        expect(m.truncated).toBe(0);
+        expect(Math.max(m.textChars, m.structuredChars)).toBeLessThan(DEFAULT_BUDGET_CHARS);
+        expect(first.structuredContent.nextCursor).toBe('4');
+        expect(first.content[0].text).toContain('call again with cursor "4"');
+    });
+    it('orboto_who answers the same filtered set under budget', async () => {
+        const urls = servePresence();
+        const result = await makeAgentWhoHandler(client)({ role: 'integrator' });
+        expect(urls[0]).toBe('/v1/agent/who?role=integrator&limit=4');
+        expect(result.structuredContent.sessions.map((s) => s.sessionId)).toEqual([uuid(17, 3)]);
+        expect(underBudget('orboto_who', result)).toMatchObject({ truncated: 0 });
+        const page = await makeAgentWhoHandler(client)({});
+        expect(underBudget('orboto_who', page)).toMatchObject({ truncated: 0 });
+    });
+});
+const party = (n, role) => ({ userId: uuid(n, 7), email: `agent-${n}@orboto.io`, sessionId: uuid(n, 8), role, label: `agent-${n}@orboto.io (${role}, ${uuid(n, 8).slice(0, 8)})` });
+/** An inbox message in the measured live shape: a 182-character subject, a 1 kB payload, the compact excerpt. */
+function message(i, threadId) {
+    const body = `${'Status of the rollout on the tenant hosts, with the commands that ran and their exit codes. '.repeat(11)}`;
+    return {
+        id: uuid(100 + i, 9), fromUserId: uuid(1, 7), toUserId: uuid(2, 7), fromSessionId: uuid(1, 8), toSessionId: null,
+        from: party(1, 'integrator'), to: party(2, 'worker'), kind: i % 2 ? 'complete' : 'request',
+        subject: `OCP-${800 + i}: ${'rollout of the verified release to every tenant host, the backup first and core before the tenants, '.repeat(2).slice(0, 172)}`,
+        payload: { body }, threadId, projectKey: 'OCP', createdAt: `2026-10-16 09:${String(10 + i).padStart(2, '0')}:00.504123+00`,
+        deliveredAt: null, readAt: null, dismissed: null, excerpt: `body: ${body.slice(0, 294)}`, payloadChars: body.length + 6,
+    };
+}
+function serveInbox(messages) {
+    const urls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+        const url = new URL(String(input));
+        urls.push(url.pathname + url.search);
+        const q = url.searchParams;
+        const rows = messages.filter((m) => (!q.get('threadId') || m.id === q.get('threadId') || m.threadId === q.get('threadId')) && (!q.get('kind') || m.kind === q.get('kind')));
+        const limit = Number(q.get('limit'));
+        const body = { messages: rows.slice(0, limit), sessionId: uuid(2, 8), counts: { unread: rows.length, olderThan7Days: 0 }, nextCursor: rows.length > limit ? 'next-page' : null };
+        return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => JSON.stringify(body) };
+    });
+    return urls;
+}
+describe('ORB-2548 - inbox reads fit the MCP response budget', () => {
+    const inbox = [...Array.from({ length: 12 }, (_, i) => message(i, null)), ...Array.from({ length: 4 }, (_, i) => message(20 + i, uuid(100, 9)))];
+    it('the default compact page (4) of full-size messages fits; the old default of 10 did not', async () => {
+        serveInbox(inbox);
+        const page = await makeAgentMessagesHandler(client)({});
+        const m = underBudget('orboto_messages', page);
+        expect(m.truncated).toBe(0);
+        expect(Math.max(m.textChars, m.structuredChars)).toBeLessThan(DEFAULT_BUDGET_CHARS);
+        expect(page.structuredContent.nextCursor).toBe('next-page');
+        serveInbox(inbox);
+        const old = await makeAgentMessagesHandler(client)({ limit: 10 });
+        expect(underBudget('orboto_messages', old).truncated).toBeGreaterThan(0);
+    });
+    it('one thread and one kind are filtered on the server and come back under budget', async () => {
+        const urls = serveInbox(inbox);
+        const thread = await makeAgentMessagesHandler(client)({ threadId: uuid(100, 9) });
+        expect(urls[0]).toContain(`threadId=${uuid(100, 9)}`);
+        expect(thread.structuredContent).toMatchObject({ nextCursor: 'next-page' });
+        expect(thread.structuredContent.messages).toHaveLength(4);
+        expect(underBudget('orboto_messages', thread)).toMatchObject({ truncated: 0 });
+        const sent = await makeAgentMessagesHandler(client)({ direction: 'sent', kind: 'request', limit: 3 });
+        expect(urls[1]).toContain('direction=sent');
+        expect(urls[1]).toContain('kind=request');
+        expect(urls[1]).not.toContain('excludeRef');
+        expect(underBudget('orboto_messages', sent)).toMatchObject({ truncated: 0 });
+    });
+});

package/dist/tools/responsibilities.test.js

@@ -51,7 +51,7 @@ describe('orboto_who for', () => {
         const urls = [];
         respond(200, { sessions: [], owner: match }, urls);
         const result = await makeAgentWhoHandler(client)({ for: 'unity asset' });
-        expect(urls[0]).toBe('https://orboto.example.com/v1/agent/who?for=unity+asset');
+        expect(urls[0]).toBe('https://orboto.example.com/v1/agent/who?for=unity+asset&limit=4');
         const text = result.content[0].text;
         expect(text).toContain('Owner:\n- worker@GAMES');
         expect(text).toContain('No live session answers to worker@GAMES - send with queue: true and project GAMES');

package/dist/tools/session-start.test.js

@@ -189,7 +189,7 @@ describe('orboto_session_start - rules-hash ack (ORB-1607, ORB-2576)', () => {
     });
 });
 describe('orboto_session_start - knowledge layers and project facts (ORB-2575)', () => {
-    const FACTS_TEXT = '## Where knowledge lives\n- Rules: binding behaviour.\n\n## Project facts\n### ORB (project id proj-1): 1 of 3 facts\n- tech_stack/stack: Go and Postgres\n2 more: `orboto primer ORB`';
+    const FACTS_TEXT = '## Where knowledge lives\n- Rules: binding behaviour.\n\n## Project facts\n### ORB: 1 of 3 facts\n- tech_stack/stack: Go and Postgres\n2 more: `orboto primer ORB`';
     const facts = (text) => ({
         source: 'session', unknown: [], text,
         projects: [{ projectKey: 'ORB', projectId: 'proj-1', total: 3, facts: [{ category: 'tech_stack', key: 'stack', value: 'Go and Postgres', observed: false }] }],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.226.2",
+  "version": "0.227.0",
   "description": "Model Context Protocol server for orboto - exposes tickets, projects, milestones, time, docs, primer-facts, alerts and absences as MCP tools for Claude Desktop / Cursor / Copilot Chat / any MCP-aware AI client.",
   "license": "MIT",
   "type": "module",