@orboto/mcp 0.195.1 → 0.198.0

package/dist/event-bridge.js

@@ -67,6 +67,10 @@ export class EventBridge {
         }
         catch { /* ignore */ } });
     }
+    /** ORB-2132 - pin the instance token once the transport session id is known; applies to the next (re)connect. */
+    setInstanceToken(token) {
+        this.opts = { ...this.opts, instanceToken: token };
+    }
     /** Open the SSE stream and start forwarding. Resolves immediately;
      *  the actual forwarding happens on the returned background loop. */
     start() {
@@ -114,6 +118,7 @@ export class EventBridge {
             headers: {
                 Authorization: `Bearer ${bearer}`,
                 Accept: 'text/event-stream',
+                ...(this.opts.instanceToken ? { 'x-orboto-agent-session': this.opts.instanceToken } : {}),
             },
             signal: this.abort.signal,
         });

package/dist/event-bridge.test.js

@@ -144,3 +144,37 @@ describe('EventBridge.dispatch', () => {
         expect(mcp.sendResourceUpdated).toHaveBeenCalledTimes(2);
     });
 });
+describe('ORB-2132 - the bridge identifies its tool session', () => {
+    async function connectOnce(opts) {
+        const fetchFn = vi.fn().mockResolvedValue(mockSseResponse([]));
+        const bridge = new EventBridge({
+            baseUrl: 'https://orboto.example.com',
+            apiKey: 'orb_x',
+            ...(opts.instanceToken ? { instanceToken: opts.instanceToken } : {}),
+            mcp: mockMcp(),
+            subscriptions: new Set(),
+            fetchFn: fetchFn,
+            log: () => { },
+        });
+        if (opts.pin)
+            bridge.setInstanceToken(opts.pin);
+        bridge.start();
+        await new Promise((r) => setTimeout(r, 30));
+        bridge.close();
+        expect(fetchFn).toHaveBeenCalledTimes(1);
+        const [url, init] = fetchFn.mock.calls[0];
+        expect(url).toBe('https://orboto.example.com/sse/mcp-events');
+        return init.headers;
+    }
+    it('sends x-orboto-agent-session with the instance token given at construction', async () => {
+        expect(await connectOnce({ instanceToken: 'mcp-session-1' })).toMatchObject({
+            Authorization: 'Bearer orb_x', 'x-orboto-agent-session': 'mcp-session-1',
+        });
+    });
+    it('sends the token pinned after construction, once the transport session id is known', async () => {
+        expect((await connectOnce({ pin: 'mcp-session-2' }))['x-orboto-agent-session']).toBe('mcp-session-2');
+    });
+    it('omits the header when no instance token is known', async () => {
+        expect(await connectOnce({})).not.toHaveProperty('x-orboto-agent-session');
+    });
+});

package/dist/http-transport.js

@@ -11,6 +11,7 @@ import { buildOrbotoMcpServer } from './server.js';
 import { resolveToolset } from './toolset.js';
 import { OrbotoClient, preflightMcpSession } from './orboto-client.js';
 import { EventBridge } from './event-bridge.js';
+import { mcpInstanceToken } from './tools/shared.js';
 /** Default store backed by the api's `/system/mcp/sessions` endpoints. Each
  *  call builds a short-lived OrbotoClient bound to the request's token so the
  *  api scopes every read/write to that identity. */
@@ -167,12 +168,13 @@ function wwwAuthChallenge(req, baseUrl, error, description) {
 export function createHttpServer({ baseUrl, sessionStore }) {
     const sessions = new Map();
     const store = sessionStore ?? createApiSessionStore(baseUrl);
-    async function buildSessionCore(tokenHolder, userAgentSuffix, toolset) {
+    async function buildSessionCore(tokenHolder, userAgentSuffix, toolset, sessionId) {
         const tokenProvider = holderTokenProvider(tokenHolder);
         const sessionClient = new OrbotoClient({ baseUrl, tokenProvider, userAgentSuffix });
         const subscriptions = new Set();
         const mcp = await buildOrbotoMcpServer({ baseUrl, tokenProvider, userAgentSuffix, subscriptions, toolset });
-        const bridge = new EventBridge({ baseUrl, tokenProvider, mcp, subscriptions });
+        const bridge = new EventBridge({ baseUrl, tokenProvider, mcp, subscriptions,
+            ...(sessionId ? { instanceToken: mcpInstanceToken(undefined, { sessionId }) } : {}) });
         return { sessionClient, subscriptions, mcp, bridge };
     }
     /** ORB-1576 - resolve a bearer's owner identity via the status preflight;
@@ -188,7 +190,7 @@ export function createHttpServer({ baseUrl, sessionStore }) {
         }
     }
     async function establishForcedSession(tokenHolder, userAgentSuffix, chosenSessionId, userEmail, toolset) {
-        const { sessionClient, mcp, bridge } = await buildSessionCore(tokenHolder, userAgentSuffix, toolset);
+        const { sessionClient, mcp, bridge } = await buildSessionCore(tokenHolder, userAgentSuffix, toolset, chosenSessionId);
         const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
         transport.onclose = () => { sessions.delete(chosenSessionId); bridge.close(); };
         await mcp.connect(transport);
@@ -373,6 +375,7 @@ export function createHttpServer({ baseUrl, sessionStore }) {
                     sessions.set(sid, {
                         transport, mcp, client: sessionClient, bridge, tokenHolder, userEmail: ownerEmail, lastTouchAt: Date.now(),
                     });
+                    bridge.setInstanceToken(mcpInstanceToken(undefined, { sessionId: sid }));
                     bridge.start();
                     void store
                         .register(token, { sessionId: sid, clientInfo, userAgent })

package/dist/manifest-size.test.js

@@ -24,12 +24,18 @@ afterEach(() => { vi.restoreAllMocks(); });
  * edits - a description essay creeping back in is exactly what these
  * must catch, so the headroom is deliberately tighter than the old
  * 20 %. Shrink-only: raising either number is a conscious decision to
- * grow every session's connect cost.
+ * grow every session's connect cost. ORB-2132 raised the full ceiling by
+ * 2,000 chars because the agent_presence output schema now carries kind,
+ * actsAs, projects and connections (measured full = 165,759 chars).
+ * ORB-2136 raised all three: session_start and agent_heartbeat carry the
+ * session scope schema, agent_notify the toSessionRef, and orboto_messages
+ * renders sender and receiver identities in its output schema (measured
+ * curated = 38,640, full = 168,029 chars, minimal = 3,140 tokens).
  *
  * @see ORB-1805, ORB-1669, ORB-1910
  */
-const CURATED_MAX_CHARS = 37_500;
-const FULL_MAX_CHARS = 165_000;
+const CURATED_MAX_CHARS = 39_000;
+const FULL_MAX_CHARS = 169_000;
 /**
  * ORB-1805 - the estimator the ticket measured the failure with
  * (`n_keep: 13533 >= n_ctx: 8192` in LM Studio): characters / 3.6. It is
@@ -45,12 +51,12 @@ const estTokens = (chars) => Math.round(chars / CHARS_PER_TOKEN);
  * left for the conversation. 3,000 was the ticket's number; 3,100 since
  * ORB-1669 added the annotations block to every tool (+688 chars).
  */
-const MINIMAL_MAX_TOKENS = 3_100;
+const MINIMAL_MAX_TOKENS = 3_200;
 /**
  * The curated tier is ratcheted on its TOOL SCHEMAS (the instructions
  * block has its own budget, enforced in instructions-budget.test.ts).
  */
-const CURATED_SCHEMA_MAX_TOKENS = 10_450;
+const CURATED_SCHEMA_MAX_TOKENS = 10_800;
 async function measuredManifest(toolset) {
     const server = await buildOrbotoMcpServer({
         baseUrl: 'https://orboto.example.com',

package/dist/orboto-client.js

@@ -80,14 +80,14 @@ export class OrbotoClient {
     }
     /** GET a JSON endpoint. Throws `OrbotoApiError` on non-2xx. */
     async get(path, options = {}) {
-        const res = await this.authedFetch(this.fullUrl(path), { method: 'GET', signal: options.signal });
+        const res = await this.authedFetch(this.fullUrl(path), { method: 'GET', signal: options.signal, ...(options.instanceToken ? { headers: { 'x-orboto-agent-session': options.instanceToken } } : {}) });
         return (await res.json());
     }
-    /** POST a JSON body. */
-    async post(path, body) {
+    /** POST a JSON body. `instanceToken` sends `x-orboto-agent-session` so the api attributes the call to this MCP session (ORB-2136). */
+    async post(path, body, options = {}) {
         const res = await this.authedFetch(this.fullUrl(path), {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
+            headers: { 'Content-Type': 'application/json', ...(options.instanceToken ? { 'x-orboto-agent-session': options.instanceToken } : {}) },
             body: JSON.stringify(body),
         });
         if (res.status === 204)

package/dist/server.js

@@ -23,9 +23,11 @@ import { apiCallToolConfig, makeApiCallHandler } from './tools/api-call.js';
 import { listAgentInstructionsToolConfig, makeListAgentInstructionsHandler, createAgentInstructionToolConfig, makeCreateAgentInstructionHandler, updateAgentInstructionToolConfig, makeUpdateAgentInstructionHandler, resetAgentInstructionToolConfig, makeResetAgentInstructionHandler, deleteAgentInstructionToolConfig, makeDeleteAgentInstructionHandler, } from './tools/agent-instructions.js';
 import { agentHeartbeatToolConfig, makeAgentHeartbeatHandler, agentPresenceToolConfig, makeAgentPresenceHandler, agentNotifyToolConfig, makeAgentNotifyHandler, } from './tools/agent-coordination.js';
 import { agentBroadcastToolConfig, makeAgentBroadcastHandler, } from './tools/agent-coordination.js';
+import { agentMessageWorkToolConfig, makeAgentMessageWorkHandler } from './tools/agent-message-work.js';
 import { agentMessagesToolConfig, makeAgentMessagesHandler } from './tools/agent-messages.js';
 import { listProjectsToolConfig, makeListProjectsHandler } from './tools/list-projects.js';
 import { getProjectToolConfig, makeGetProjectHandler } from './tools/get-project.js';
+import { projectReadinessToolConfig, makeProjectReadinessHandler } from './tools/project-readiness.js';
 import { getProjectPrimerToolConfig, makeGetProjectPrimerHandler } from './tools/get-project-primer.js';
 import { listTicketsToolConfig, makeListTicketsHandler } from './tools/list-tickets.js';
 import { criticalPathToolConfig, makeCriticalPathHandler } from './tools/critical-path.js';
@@ -39,6 +41,7 @@ import { searchToolConfig, makeSearchHandler } from './tools/search.js';
 import { queryToolConfig, makeQueryHandler } from './tools/query.js';
 import { customerReportToolConfig, makeCustomerReportHandler } from './tools/customer-report.js';
 import { requirementsSpecToolConfig, makeRequirementsSpecHandler } from './tools/requirements-spec.js';
+import { specCheckToolConfig, makeSpecCheckHandler } from './tools/spec-check.js';
 import { wikiIngestUrlToolConfig, makeWikiIngestUrlHandler, wikiAskToolConfig, makeWikiAskHandler, wikiLintToolConfig, makeWikiLintHandler, wikiPlanUpdateToolConfig, makeWikiPlanUpdateHandler, wikiApplyPlanToolConfig, makeWikiApplyPlanHandler, wikiRecordToolConfig, makeWikiRecordHandler, wikiAppendSectionToolConfig, makeWikiAppendSectionHandler, wikiFlagStaleToolConfig, makeWikiFlagStaleHandler, wikiSaveAnswerToolConfig, makeWikiSaveAnswerHandler, } from './tools/wiki.js';
 import { personalFactListToolConfig, makePersonalFactListHandler, personalFactAddToolConfig, makePersonalFactAddHandler, personalFactUpdateToolConfig, makePersonalFactUpdateHandler, personalFactDeleteToolConfig, makePersonalFactDeleteHandler, } from './tools/personal-facts.js';
 import { listDocSpacesToolConfig, makeListDocSpacesHandler, getDocToolConfig, makeGetDocHandler, createDocSpaceToolConfig, makeCreateDocSpaceHandler, updateDocSpaceToolConfig, makeUpdateDocSpaceHandler, deleteDocSpaceToolConfig, makeDeleteDocSpaceHandler, listDocsInSpaceToolConfig, makeListDocsInSpaceHandler, createDocToolConfig, makeCreateDocHandler, updateDocToolConfig, makeUpdateDocHandler, deleteDocToolConfig, makeDeleteDocHandler, moveDocToolConfig, makeMoveDocHandler, duplicateDocSpaceToolConfig, makeDuplicateDocSpaceHandler, resolveDocSmartLinksToolConfig, makeResolveDocSmartLinksHandler, } from './tools/docs.js';
@@ -53,6 +56,8 @@ import { listCrossProjectLinksToolConfig, makeListCrossProjectLinksHandler, addC
 import { getTimerToolConfig, makeGetTimerHandler } from './tools/get-timer.js';
 import { getChecklistsToolConfig, makeGetChecklistsHandler } from './tools/get-checklists.js';
 import { listGitAppInstallationsToolConfig, makeListGitAppInstallationsHandler } from './tools/list-git-app-installations.js';
+import { gitRotateTokenToolConfig, makeGitRotateTokenHandler } from './tools/git-rotate-token.js';
+import { sentryToolConfig, makeSentryHandler } from './tools/sentry.js';
 import { createTicketToolConfig, makeCreateTicketHandler, updateTicketToolConfig, makeUpdateTicketHandler, moveTicketToolConfig, makeMoveTicketHandler, closeTicketToolConfig, makeCloseTicketHandler, deleteTicketToolConfig, makeDeleteTicketHandler, commentToolConfig, makeCommentHandler, updateCommentToolConfig, makeUpdateCommentHandler, deleteCommentToolConfig, makeDeleteCommentHandler, assignToolConfig, makeAssignHandler, unassignToolConfig, makeUnassignHandler, labelTicketToolConfig, makeLabelTicketHandler, unlabelTicketToolConfig, makeUnlabelTicketHandler, setMilestoneToolConfig, makeSetMilestoneHandler, addTicketDependencyToolConfig, makeAddTicketDependencyHandler, removeTicketDependencyToolConfig, makeRemoveTicketDependencyHandler, listTicketDependenciesToolConfig, makeListTicketDependenciesHandler, } from './tools/ticket-writes.js';
 import { timerStartToolConfig, makeTimerStartHandler, timerStopToolConfig, makeTimerStopHandler, logTimeToolConfig, makeLogTimeHandler, listTimeEntriesToolConfig, makeListTimeEntriesHandler, editTimeEntryToolConfig, makeEditTimeEntryHandler, deleteTimeEntryToolConfig, makeDeleteTimeEntryHandler, } from './tools/time-writes.js';
 import { listTicketSchedulesToolConfig, makeListTicketSchedulesHandler, scheduleTicketSessionToolConfig, makeScheduleTicketSessionHandler, cancelTicketSessionToolConfig, makeCancelTicketSessionHandler, } from './tools/ticket-schedules.js';
@@ -191,6 +196,7 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_agent_heartbeat', agentHeartbeatToolConfig, makeAgentHeartbeatHandler(client));
     reg('orboto_agent_presence', agentPresenceToolConfig, makeAgentPresenceHandler(client));
     reg('orboto_agent_notify', agentNotifyToolConfig, makeAgentNotifyHandler(client));
+    reg('orboto_message_work', agentMessageWorkToolConfig, makeAgentMessageWorkHandler(client));
     reg('orboto_messages', agentMessagesToolConfig, makeAgentMessagesHandler(client));
     reg('orboto_agent_broadcast', agentBroadcastToolConfig, makeAgentBroadcastHandler(client));
     reg('orboto_list_projects', listProjectsToolConfig, makeListProjectsHandler(client));
@@ -209,6 +215,7 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_query', queryToolConfig, makeQueryHandler(client));
     reg('orboto_customer_report', customerReportToolConfig, makeCustomerReportHandler(client));
     reg('orboto_requirements_spec', requirementsSpecToolConfig, makeRequirementsSpecHandler(client));
+    reg('orboto_spec_check', specCheckToolConfig, makeSpecCheckHandler(client));
     reg('orboto_list_doc_spaces', listDocSpacesToolConfig, makeListDocSpacesHandler(client));
     reg('orboto_get_doc', getDocToolConfig, makeGetDocHandler(client));
     reg('orboto_search_docs', searchDocsToolConfig, makeSearchDocsHandler(client));
@@ -261,6 +268,8 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_personal_fact_delete', personalFactDeleteToolConfig, makePersonalFactDeleteHandler(client));
     reg('orboto_get_timer', getTimerToolConfig, makeGetTimerHandler(client));
     reg('orboto_list_git_app_installations', listGitAppInstallationsToolConfig, makeListGitAppInstallationsHandler(client));
+    reg('orboto_git_rotate_token', gitRotateTokenToolConfig, makeGitRotateTokenHandler(client));
+    reg('orboto_sentry', sentryToolConfig, makeSentryHandler(client));
     reg('orboto_create_ticket', createTicketToolConfig, makeCreateTicketHandler(client));
     reg('orboto_update_ticket', updateTicketToolConfig, makeUpdateTicketHandler(client));
     reg('orboto_move_ticket', moveTicketToolConfig, makeMoveTicketHandler(client));
@@ -336,6 +345,7 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_attach_to_ticket', attachToTicketToolConfig, makeAttachToTicketHandler(client));
     reg('orboto_set_parent', setParentToolConfig, makeSetParentHandler(client));
     reg('orboto_update_project', updateProjectToolConfig, makeUpdateProjectHandler(client));
+    reg('orboto_project_readiness', projectReadinessToolConfig, makeProjectReadinessHandler(client));
     reg('orboto_create_project', createProjectToolConfig, makeCreateProjectHandler(client));
     reg('orboto_archive_project', archiveProjectToolConfig, makeArchiveProjectHandler(client));
     reg('orboto_check_similar', checkSimilarToolConfig, makeCheckSimilarHandler(client));

package/dist/tool-docs.js

@@ -13,7 +13,7 @@ export const SUMMARY_MAX_CHARS = 220;
  */
 const SUMMARY_OVERRIDES = {
     orboto_create_full_backup: 'Start a full-workspace backup job (all projects, users, config, attachments); returns the job id to poll via orboto_list_backups.',
-    orboto_get_ticket: 'Fetch one ticket by key (ORB-42) or UUID: full detail incl. description, status, assignees, checklists, dependencies and comments.',
+    orboto_get_ticket: 'Fetch one ticket by key or UUID with description, status, assignees, checklists and comments.',
     orboto_requirements_spec: 'Generate a structured requirements spec for a project or milestone from its tickets (scope, actors, functional + non-functional requirements).',
     orboto_update_doc_space: 'Update a doc space\'s name, description, icon, project binding or access mode (open/restricted) by space id.',
     orboto_search_docs: 'Full-text search over doc/wiki pages (query, optional space or project filter); returns matching pages with snippets.',

package/dist/tools/agent-coordination.js

@@ -4,12 +4,15 @@
  * @see ORB-704, ORB-706
  */
 import { z } from 'zod';
+import { AgentInventoryEntrySchema, AgentInventoryKindSchema } from './agent-presence-schema.js';
 import { mcpInstanceToken } from './shared.js';
+import { 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.',
+    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.',
     inputSchema: z.object({
         sessionToken: z.string().nullable().optional(),
+        scope: AgentSessionScopeSchema.optional(),
         status: z.enum(['idle', 'working', 'blocked']).optional(),
         workingOnTicketId: z.string().uuid().nullable().optional(),
         capabilities: z.array(z.string()).optional(),
@@ -23,49 +26,44 @@ export const agentHeartbeatToolConfig = {
     outputSchema: z.object({
         sessionToken: z.string(),
         sessionId: z.string().uuid(),
+        scope: AgentSessionScopeSchema.nullable(),
     }).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 async (args, extra) => {
+        const res = await client.post('/v1/agent/heartbeat', args, { instanceToken: mcpInstanceToken(undefined, extra) });
+        const scope = res.scope ? ` scope=${JSON.stringify(res.scope)}` : '';
         return {
-            content: [{ type: 'text', text: `heartbeat ack - sessionToken=${res.sessionToken.slice(0, 8)}…` }],
-            structuredContent: { sessionToken: res.sessionToken, sessionId: res.sessionId },
+            content: [{ type: 'text', text: `heartbeat ack - sessionToken=${res.sessionToken.slice(0, 8)}… session ${res.sessionId.slice(0, 8)}${scope}` }],
+            structuredContent: { sessionToken: res.sessionToken, sessionId: res.sessionId, scope: res.scope ?? null },
         };
     };
 }
 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,
+    description: 'Returns all active orboto agent instances, including lane workers/reviewers, inbox and MCP connections and registered runners. Session freshness is 90 seconds; lanes retain their 300-second heartbeat grace. Unexpired work leases keep their owning instance visible. Ticket metadata and claims retain ordinary ticket visibility. Rows include `kind` (agent or human, classified by the credential: agent API key, OAuth grant, lane, external token or bot account; `isBot` is its alias), `actsAs` (the human account an AI client acts under), `projects` (memberships plus lane projects), `connections` (type + label per credential or attachment, `live_events` for the MCP event bridge), owner, lane and stable sessionId; separate instances of one account remain separate. Callers with admin:system:read see every agent; other 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. Filters `projectKey` (rows whose `projects` contain the key) and `kind` (agent | human) narrow the list client-side, the same way `orboto agents --project KEY --bots|--humans` does.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).max(64).optional().describe('Keep only rows whose projects contain this project key (case-insensitive).'),
+        kind: AgentInventoryKindSchema.optional().describe('Keep only rows classified as agent or human by their credential.'),
+    }).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(),
-        })),
+        sessions: z.array(AgentInventoryEntrySchema),
     }).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 () => {
-        const sessions = await client.get('/v1/agent/presence');
+    return async (args = {}) => {
+        const all = await client.get('/v1/agent/inventory');
+        const sessions = filterPresenceRows(all, args);
         const lines = [];
         if (sessions.length === 0) {
-            lines.push('No active agent sessions in the workspace.');
+            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):`);
@@ -75,7 +73,7 @@ export function makeAgentPresenceHandler(client) {
                 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}`);
+                lines.push(`- ${name} <${s.userEmail}> (${runtime}, instance ${s.sessionId}) - ${s.status}${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(', ')}` : ''}`);
             }
         }
         return {
@@ -86,7 +84,7 @@ export function makeAgentPresenceHandler(client) {
 }
 export const agentNotifyToolConfig = {
     title: 'Notify another agent / user',
-    description: 'Send a fire-and-forget message to a user (bot or human) by email; it lands in their inbox (orboto_messages) and, for humans, in-app. kind: info | request (answer expected) | complete (sub-task done) | error. payload: free-form JSON; threadId links a reply to the message it answers.',
+    description: 'Send a fire-and-forget message to a user (bot or human) by email; it lands in their inbox (orboto_messages) and, for humans, in-app. kind: info | request (answer expected) | complete (sub-task done) | error. payload: free-form 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 (ORB-2136).',
     inputSchema: z.object({
         targetEmail: z.string().email(),
         kind: z.enum(['info', 'request', 'complete', 'error']).default('info'),
@@ -95,10 +93,12 @@ export const agentNotifyToolConfig = {
         threadId: z.string().uuid().optional(),
         project: z.string().min(1).max(64).optional().describe('Project key or UUID: scope the message to the recipient session working that project.'),
         senderRef: z.string().min(1).max(128).optional().describe('Sender-session ref for self-echo exclusion; defaults to this MCP session.'),
+        toSessionRef: z.string().min(1).max(200).optional(),
     }).shape,
     outputSchema: z.object({
         ok: z.literal(true),
         messageId: z.string().uuid(),
+        toSessionId: z.string().uuid().nullable(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
@@ -129,10 +129,11 @@ export function makeAgentBroadcastHandler(client) {
 export function makeAgentNotifyHandler(client) {
     return async (args, extra) => {
         const senderRef = mcpInstanceToken(args.senderRef, extra);
-        const res = await client.post('/v1/agent/notify', { ...args, senderRef });
+        const res = await client.post('/v1/agent/notify', { ...args, senderRef }, { instanceToken: mcpInstanceToken(undefined, extra) });
+        const target = res.toSessionId ? `${args.targetEmail} session ${res.toSessionId.slice(0, 8)}` : args.targetEmail;
         return {
-            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 },
+            content: [{ type: 'text', text: `notified ${target} (message ${res.messageId} - delivered live if connected, waits in their inbox otherwise)` }],
+            structuredContent: { ok: true, messageId: res.messageId, toSessionId: res.toSessionId ?? null },
         };
     };
 }

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

@@ -43,16 +43,16 @@ describe('orboto_agent_heartbeat', () => {
     });
 });
 describe('orboto_agent_presence', () => {
-    it('GETs /v1/agent/presence and renders one line per session', async () => {
+    it('GETs /v1/agent/inventory and renders one line per session', async () => {
         stub([{
                 json: [
                     {
                         userId: '00000000-0000-0000-0000-000000000001',
                         userEmail: 'alice@x.test',
-                        userFullName: 'Alice',
+                        userFullName: 'Alice', kind: 'human', isBot: false, actsAs: null, owner: null, autonomyPaused: false, lane: null, projects: [], connections: [], workSessions: [],
                         sessionId: '00000000-0000-0000-0000-000000000010',
                         status: 'working',
-                        workingOnTicket: { id: 't1', key: 'ORB-42', title: 'Test', projectKey: 'ORB' },
+                        workingOnTicket: { id: '00000000-0000-0000-0000-000000000020', key: 'ORB-42', title: 'Test', projectKey: 'ORB' },
                         capabilities: ['writes-tickets'],
                         clientInfo: { name: 'claude-code' },
                         lastSeenAt: new Date().toISOString(),
@@ -61,7 +61,8 @@ describe('orboto_agent_presence', () => {
                     {
                         userId: '00000000-0000-0000-0000-000000000002',
                         userEmail: 'bot@x.test',
-                        userFullName: null,
+                        userFullName: null, kind: 'agent', isBot: true, actsAs: null, owner: { id: '00000000-0000-0000-0000-000000000001', name: 'Alice', email: 'alice@x.test' },
+                        autonomyPaused: false, lane: null, projects: [{ id: '00000000-0000-0000-0000-000000000030', key: 'ORB', name: 'orboto' }], connections: [{ type: 'api_key', label: 'dispatcher' }], workSessions: [],
                         sessionId: '00000000-0000-0000-0000-000000000011',
                         status: 'idle',
                         workingOnTicket: null,
@@ -76,8 +77,9 @@ describe('orboto_agent_presence', () => {
         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(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; owner: Alice');
+        expect(vi.mocked(fetch).mock.calls[0][0]).toBe('https://orboto.example.com/v1/agent/inventory');
         expect(result.structuredContent.sessions).toHaveLength(2);
     });
     it('handles an empty workspace gracefully', async () => {
@@ -86,6 +88,38 @@ describe('orboto_agent_presence', () => {
         const result = await handler();
         expect(result.content[0].text).toBe('No active agent sessions in the workspace.');
     });
+    const presenceRows = () => [
+        { userId: '00000000-0000-0000-0000-000000000001', userEmail: 'alice@x.test', userFullName: 'Alice', kind: 'human', isBot: false, actsAs: null, owner: null, autonomyPaused: false, lane: null, projects: [{ id: '00000000-0000-0000-0000-000000000030', key: 'ORB', name: 'orboto' }], connections: [{ type: 'api_key', label: 'laptop' }], workSessions: [], sessionId: '00000000-0000-0000-0000-000000000010', status: 'working', workingOnTicket: null, capabilities: [], clientInfo: { name: 'claude-code' }, lastSeenAt: new Date().toISOString(), createdAt: new Date().toISOString() },
+        { 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 () => {
+        const handler = makeAgentPresenceHandler(client);
+        const ids = async (args) => {
+            stub([{ json: presenceRows() }]);
+            const result = await handler(args);
+            expect(vi.mocked(fetch).mock.calls.at(-1)?.[0]).toBe('https://orboto.example.com/v1/agent/inventory');
+            return result.structuredContent.sessions.map((s) => s.sessionId.slice(-2));
+        };
+        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: presenceRows() }]);
+        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).');
+    });
+    it('renders acts-as, lane, projects and connection types on each line', async () => {
+        stub([{ json: 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');
+        expect(text).toContain('owner: acts as Alice; connections: oauth');
+    });
 });
 describe('orboto_agent_notify', () => {
     it('POSTs to /v1/agent/notify with the body the user supplied', async () => {
@@ -152,3 +186,50 @@ describe('orboto_messages (ORB-1742 self-echo exclusion)', () => {
         expect(urls[1]).not.toContain('excludeRef');
     });
 });
+describe('ORB-2136 - session addressing', () => {
+    it('agent_notify forwards toSessionRef and sends this MCP session as x-orboto-agent-session', async () => {
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            seen.push({ body: JSON.parse(init?.body ?? '{}'), headers: (init?.headers ?? {}) });
+            return { ok: true, status: 200, statusText: 'OK', json: async () => ({ ok: true, messageId: '00000000-0000-4000-8000-000000000000', toSessionId: 'cbb52195-0000-4000-8000-000000000000' }), text: async () => '' };
+        });
+        const result = await makeAgentNotifyHandler(client)({ targetEmail: 'bob@example.com', subject: 'hi', toSessionRef: 'cbb52195' }, { sessionId: 'abc123' });
+        expect(seen[0].body).toMatchObject({ toSessionRef: 'cbb52195', senderRef: 'mcp-abc123' });
+        expect(seen[0].headers['x-orboto-agent-session']).toBe('mcp-abc123');
+        expect(result.content[0].text).toContain('bob@example.com session cbb52195');
+        expect(result.structuredContent).toMatchObject({ toSessionId: 'cbb52195-0000-4000-8000-000000000000' });
+    });
+    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) => {
+            seen.push({ url: String(url), headers: (init?.headers ?? {}) });
+            return {
+                ok: true, status: 200, statusText: 'OK',
+                json: async () => ({ sessionId: 'cbb52195-0000-4000-8000-000000000000', messages: [{
+                            id: 'm1', fromUserId: 'u1', toUserId: 'u2', fromSessionId: 's1', toSessionId: 's2',
+                            from: { userId: 'u1', email: 'spec@orboto.io', sessionId: 's1', role: 'spec', label: 'spec@orboto.io (spec, s1)' },
+                            to: { userId: 'u2', email: 'claude@orboto.io', sessionId: 's2', role: 'integrator', label: 'claude@orboto.io (integrator, s2)' },
+                            kind: 'request', subject: 'ticket-ready:ORB-1', payload: null, threadId: null, projectKey: 'ORB', createdAt: 'now', deliveredAt: null, readAt: null,
+                        }] }),
+                text: async () => '',
+            };
+        });
+        const result = await makeAgentMessagesHandler(client)({}, { sessionId: 'abc123' });
+        expect(seen[0].headers['x-orboto-agent-session']).toBe('mcp-abc123');
+        const text = result.content[0].text;
+        expect(text).toContain('from spec@orboto.io (spec, s1) to claude@orboto.io (integrator, s2)');
+        expect(text).toContain('This session: cbb52195 (ref mcp-abc123)');
+        expect(result.structuredContent).toMatchObject({ sessionId: 'cbb52195-0000-4000-8000-000000000000', messages: [{ from: { role: 'spec' }, to: { sessionId: 's2' } }] });
+    });
+    it('agent_heartbeat carries the scope and the session header', async () => {
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            seen.push({ body: JSON.parse(init?.body ?? '{}'), headers: (init?.headers ?? {}) });
+            return { ok: true, status: 200, statusText: 'OK', json: async () => ({ sessionToken: 'mcp-abc123', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: { role: 'integrator', projectKeys: ['ORB'] } }), text: async () => '' };
+        });
+        const result = await makeAgentHeartbeatHandler(client)({ scope: { role: 'integrator', projectKeys: ['orb'] } }, { sessionId: 'abc123' });
+        expect(seen[0].body).toMatchObject({ scope: { role: 'integrator', projectKeys: ['orb'] } });
+        expect(seen[0].headers['x-orboto-agent-session']).toBe('mcp-abc123');
+        expect(result.structuredContent).toMatchObject({ scope: { role: 'integrator', projectKeys: ['ORB'] } });
+    });
+});

package/dist/tools/agent-message-work.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { mcpInstanceToken } from './shared.js';
+export const agentMessageWorkToolConfig = {
+    title: 'Inspect or explicitly handle message work',
+    description: 'List, inspect or mutate durable message work (mutation schema: orboto_api_search). ACK is a separate read receipt and finishes nothing.',
+    inputSchema: z.object({ messageId: z.string().uuid().optional(), mutation: z.record(z.unknown()).optional(),
+        cursor: z.string().optional(), limit: z.number().int().min(1).max(100).default(25), openOnly: z.boolean().default(true) }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+};
+export function makeAgentMessageWorkHandler(client) {
+    return async (args, extra) => {
+        if (args.mutation && !args.messageId)
+            throw new Error('messageId is required for a mutation');
+        const q = new URLSearchParams({ limit: String(args.limit ?? 25), openOnly: String(args.openOnly ?? true) });
+        if (args.cursor)
+            q.set('cursor', args.cursor);
+        const result = args.mutation
+            ? await client.post(`/v1/agent/messages/${args.messageId}/work`, { ...args.mutation, instanceToken: mcpInstanceToken(undefined, extra) })
+            : await client.get(`${args.messageId ? `/v1/agent/messages/${args.messageId}` : '/v1/agent/message-work'}?${q}`, { instanceToken: mcpInstanceToken(undefined, extra) });
+        return { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+    };
+}

package/dist/tools/agent-message-work.test.js

@@ -0,0 +1,33 @@
+import { describe, expect, it, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { agentMessageWorkToolConfig, makeAgentMessageWorkHandler } from './agent-message-work.js';
+import { makeAgentMessagesHandler } from './agent-messages.js';
+describe('message work MCP parity', () => {
+    it('carries no second copy of the shared mutation schema', () => {
+        const shared = readFileSync(new URL('../../../../packages/shared-schema/src/agent-message-work.ts', import.meta.url), 'utf8');
+        const local = readFileSync(new URL('./agent-message-work.ts', import.meta.url), 'utf8');
+        const stepBlock = shared.slice(shared.indexOf('export const MessageWorkStepSchema'), shared.indexOf('export const MessageWorkMutationSchema'));
+        expect(local).not.toContain(stepBlock.replaceAll('export const', 'const'));
+        expect(local).not.toContain('MessageWorkStepSchema');
+        expect(agentMessageWorkToolConfig.description).toContain('orboto_api_search');
+    });
+    it('uses each MCP connection identity and reads exact IDs without ACK', async () => {
+        const get = vi.fn().mockResolvedValueOnce({ message: { id: 'message' } }).mockResolvedValue({ messages: [] });
+        const post = vi.fn().mockResolvedValue({ state: 'in_work' });
+        const client = { get, post };
+        const handler = makeAgentMessageWorkHandler(client);
+        await handler({ messageId: 'message' }, { sessionId: 'a' });
+        expect(get).toHaveBeenCalledWith('/v1/agent/messages/message?limit=25&openOnly=true', { instanceToken: 'mcp-a' });
+        expect(post).not.toHaveBeenCalled();
+        await handler({ messageId: 'message', mutation: { action: 'claim', summary: 'Explicit acceptance', evidence: [], leaseSeconds: 900 } }, { sessionId: 'a' });
+        expect(post).toHaveBeenCalledWith('/v1/agent/messages/message/work', expect.objectContaining({ instanceToken: 'mcp-a' }));
+    });
+    it('ACK is a plain read receipt - no evidence travels with it', async () => {
+        const get = vi.fn().mockResolvedValue({ messages: [] });
+        const post = vi.fn().mockResolvedValue({ acked: 1 });
+        const client = { get, post };
+        await makeAgentMessagesHandler(client)({ ackIds: ['message'] }, { sessionId: 'b' });
+        expect(post).toHaveBeenCalledWith('/v1/agent/messages/ack', { ids: ['message'], instanceToken: 'mcp-b' });
+        expect(JSON.stringify(post.mock.calls)).not.toContain('evidence');
+    });
+});