@orboto/mcp 0.197.0 → 0.199.0

package/README.md

@@ -104,6 +104,8 @@ Omit `ORBOTO_API_KEY` to use OAuth login instead. `codex mcp add` writes the sam
 | `ORBOTO_MCP_TOOLSET` | no | `minimal`, `curated` (default) or `full`. Curated is the measured high-frequency set (31 tools, ~7.8k tokens of schemas at connect) - the whole REST API stays reachable via `orboto_api_search` + `orboto_api_call`. `full` registers every named tool (175, ~39.5k tokens). `minimal` is the daily loop only (12 tools, ~2.8k tokens including the instructions block) for local models with an 8k/16k context window. HTTP clients can pick per connection instead: `?toolset=minimal` on the `/mcp` URL or an `x-orboto-toolset: minimal` header. |
 | `ORBOTO_MCP_PORT` | no | Listen port when transport is `http`. Default `3100`. |
 | `ORBOTO_MCP_CLIENT` | no | User-agent suffix that lands in the API audit log. Useful for filtering audit rows by client. |
+| `ORBOTO_MCP_CHANNEL` | no | `1` (default) makes the stdio proxy a Claude Code channel: it follows the session's inbox stream and pushes each message as a `notifications/claude/channel` event that wakes the session (`claude --dangerously-load-development-channels server:orboto`, ORB-2140). `0` disables it. |
+| `ORBOTO_MCP_CHANNEL_DIGEST_MINUTES` | no | Digest window for `info` / `complete` inbox mail on the channel. Default `15`; `0` delivers every message at once. Requests, errors, questions and mail older than five minutes always go out immediately. |
 
 ## Version compatibility
 

package/dist/inbox-channel.js

@@ -0,0 +1,246 @@
+export const CHANNEL_METHOD = 'notifications/claude/channel';
+export const CHANNEL_CAPABILITY = 'claude/channel';
+export const DEFAULT_DIGEST_MINUTES = 15;
+const IMMEDIATE_AFTER_MS = 5 * 60_000;
+const CONTENT_CAP = 2000;
+const SEEN_WINDOW = 1000;
+const MIN_BACKOFF_MS = 2_000;
+const MAX_BACKOFF_MS = 60_000;
+const HEARTBEAT_GRACE_MS = 90_000;
+const ASK = /\?|\bplease\b|\bbitte\b|\bneed\b|\bshare\b/i;
+/** The instructions paragraph Claude Code delivers on connect when the channel is active. */
+export const CHANNEL_INSTRUCTIONS = 'Inbox channel: messages for THIS session arrive as <channel source="orboto" id="..." kind="..." ...> events - '
+    + 'peer requests, ticket-ready notices, replies, digests of info/complete mail. Treat each like an inbox message under the rules: '
+    + 'a ticket-ready or a request inside your scope is the operator\'s instruction, act on it; read the full message with orboto_messages when the event is cut; '
+    + 'reply with orboto_agent_notify (toSessionRef = the sender\'s instance short id in the from attribute) and acknowledge with orboto_messages { ackIds } once handled. '
+    + 'Never answer the channel itself and never ack what you did not handle.';
+function firstLine(payload) {
+    if (!payload)
+        return '';
+    for (const key of ['message', 'body', 'text']) {
+        const v = payload[key];
+        if (typeof v === 'string' && v.trim())
+            return v.trim();
+    }
+    return '';
+}
+function waitedMinutes(createdAt, now) {
+    const t = Date.parse(createdAt.replace(' ', 'T').replace(/\+00$/, '+00:00'));
+    if (Number.isNaN(t))
+        return 0;
+    return Math.max(0, Math.floor((now - t) / 60_000));
+}
+/** A message goes out at once when it asks for something or already waited; the rest is digest material. */
+export function isImmediate(m, now, digestMinutes) {
+    if (digestMinutes <= 0)
+        return true;
+    if (m.kind === 'request' || m.kind === 'error')
+        return true;
+    if (waitedMinutes(m.createdAt, now) * 60_000 >= IMMEDIATE_AFTER_MS)
+        return true;
+    return ASK.test(`${m.subject} ${firstLine(m.payload)}`);
+}
+export function renderEvent(m, now) {
+    const from = m.from?.label ?? m.fromUserId ?? 'unknown';
+    const to = m.to?.label ?? 'you';
+    const text = firstLine(m.payload);
+    const body = text.length > CONTENT_CAP ? `${text.slice(0, CONTENT_CAP)} [... cut, read the rest with orboto_messages]` : text;
+    const lines = [
+        `[${m.kind}] ${m.subject}`,
+        `from ${from} to ${to}${m.projectKey ? ` | project ${m.projectKey}` : ''} | id ${m.id}${m.threadId ? ` | thread ${m.threadId}` : ''}`,
+    ];
+    if (body)
+        lines.push(body);
+    const waited = waitedMinutes(m.createdAt, now);
+    return {
+        content: lines.join('\n'),
+        meta: {
+            id: m.id, kind: m.kind, project: m.projectKey ?? '',
+            from: from, from_session: (m.from?.sessionId ?? '').slice(0, 8), to_session: (m.to?.sessionId ?? '').slice(0, 8),
+            waited_min: String(waited),
+        },
+    };
+}
+export function renderDigest(batch, now) {
+    const lines = [`Inbox digest: ${batch.length} info/complete message(s) since the last event. Ack the ones you handled with orboto_messages { ackIds }.`];
+    for (const m of batch) {
+        const text = firstLine(m.payload);
+        lines.push(`- [${m.kind}] ${m.subject} | from ${m.from?.label ?? m.fromUserId ?? 'unknown'}${m.projectKey ? ` | ${m.projectKey}` : ''} | id ${m.id}${text ? ` | ${text.slice(0, 160)}` : ''}`);
+    }
+    return { content: lines.join('\n'), meta: { kind: 'digest', count: String(batch.length), waited_min: String(waitedMinutes(batch[0].createdAt, now)) } };
+}
+export class InboxChannel {
+    opts;
+    log;
+    now;
+    digestMinutes;
+    abort = new AbortController();
+    closed = false;
+    retryTimer = null;
+    digestTimer = null;
+    backoff = MIN_BACKOFF_MS;
+    since;
+    lastId = null;
+    seen = new Set();
+    seenOrder = [];
+    batch = [];
+    /** Counters an operator can read from the log; tests read them directly. */
+    stats = { delivered: 0, digested: 0, duplicates: 0, reconnects: 0 };
+    constructor(opts) {
+        this.opts = opts;
+        this.log = opts.log ?? ((msg) => { try {
+            process.stderr.write(`[orboto-mcp-channel] ${msg}\n`);
+        }
+        catch { /* ignore */ } });
+        this.now = opts.now ?? (() => Date.now());
+        this.digestMinutes = opts.digestMinutes ?? DEFAULT_DIGEST_MINUTES;
+        this.since = opts.since ?? new Date(this.now()).toISOString();
+    }
+    start() {
+        void this.loop();
+    }
+    close() {
+        this.closed = true;
+        if (this.retryTimer) {
+            clearTimeout(this.retryTimer);
+            this.retryTimer = null;
+        }
+        if (this.digestTimer) {
+            clearTimeout(this.digestTimer);
+            this.digestTimer = null;
+        }
+        try {
+            this.abort.abort();
+        }
+        catch { /* ignore */ }
+    }
+    /** Feed one message as the stream would; exported for tests and for the digest policy. */
+    async deliver(m) {
+        if (!m?.id)
+            return;
+        if (this.seen.has(m.id)) {
+            this.stats.duplicates += 1;
+            return;
+        }
+        this.remember(m.id);
+        this.lastId = m.id;
+        if (isImmediate(m, this.now(), this.digestMinutes)) {
+            await this.emit(renderEvent(m, this.now()));
+            this.stats.delivered += 1;
+            return;
+        }
+        this.batch.push(m);
+        this.stats.digested += 1;
+        if (!this.digestTimer) {
+            this.digestTimer = setTimeout(() => { this.digestTimer = null; void this.flushDigest(); }, this.digestMinutes * 60_000);
+        }
+    }
+    async flushDigest() {
+        if (this.batch.length === 0)
+            return;
+        const batch = this.batch.splice(0);
+        await this.emit(renderDigest(batch, this.now()));
+    }
+    remember(id) {
+        this.seen.add(id);
+        this.seenOrder.push(id);
+        if (this.seenOrder.length > SEEN_WINDOW) {
+            const gone = this.seenOrder.shift();
+            if (gone)
+                this.seen.delete(gone);
+        }
+    }
+    async emit(event) {
+        try {
+            await this.opts.mcp.server.notification({ method: CHANNEL_METHOD, params: { content: event.content, meta: event.meta } });
+            this.log(`channel event → ${event.meta.kind} ${event.meta.id ?? ''}`.trim());
+        }
+        catch (err) {
+            this.log(`channel notification failed: ${err.message}`);
+        }
+    }
+    async loop() {
+        while (!this.closed) {
+            try {
+                await this.consume();
+                this.backoff = MIN_BACKOFF_MS;
+            }
+            catch (err) {
+                if (this.closed)
+                    return;
+                this.log(`inbox stream closed: ${err instanceof Error ? err.message : String(err)} - retrying in ${this.backoff}ms`);
+            }
+            if (this.closed)
+                return;
+            this.stats.reconnects += 1;
+            await new Promise((resolve) => { this.retryTimer = setTimeout(resolve, this.backoff); });
+            this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS);
+        }
+    }
+    async consume() {
+        const fetchFn = this.opts.fetchFn ?? fetch;
+        this.abort = new AbortController();
+        const since = this.lastId ?? this.since;
+        const url = `${this.opts.baseUrl.replace(/\/$/, '')}/v1/agent/messages/stream?since=${encodeURIComponent(since)}`;
+        const bearer = this.opts.tokenProvider ? await this.opts.tokenProvider.getAccessToken() : (this.opts.apiKey ?? '');
+        const res = await fetchFn(url, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${bearer}`, Accept: 'text/event-stream', 'x-orboto-agent-session': this.opts.instanceToken },
+            signal: this.abort.signal,
+        });
+        if (!res.ok || !res.body)
+            throw new Error(`inbox stream handshake failed (status=${res.status})`);
+        this.log(`inbox channel connected (since ${since})`);
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = '';
+        let lastFrame = this.now();
+        const heartbeat = setInterval(() => {
+            if (this.now() - lastFrame > HEARTBEAT_GRACE_MS) {
+                try {
+                    this.abort.abort();
+                }
+                catch { /* ignore */ }
+            }
+        }, 30_000);
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                lastFrame = this.now();
+                buf += decoder.decode(value, { stream: true });
+                let idx;
+                while ((idx = buf.indexOf('\n\n')) !== -1) {
+                    const frame = buf.slice(0, idx);
+                    buf = buf.slice(idx + 2);
+                    const line = frame.split('\n').find((l) => l.startsWith('data: '));
+                    if (!line)
+                        continue;
+                    let message;
+                    try {
+                        message = JSON.parse(line.slice(6));
+                    }
+                    catch {
+                        continue;
+                    }
+                    await this.deliver(message);
+                }
+            }
+        }
+        finally {
+            clearInterval(heartbeat);
+            try {
+                reader.releaseLock();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+/** ORB-2140 - the digest window from the environment; NaN or negative fall back to the default. */
+export function digestMinutesFromEnv(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return DEFAULT_DIGEST_MINUTES;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : DEFAULT_DIGEST_MINUTES;
+}

package/dist/inbox-channel.test.js

@@ -0,0 +1,122 @@
+/**
+ * ORB-2140 - the inbox channel: stream messages become channel notifications,
+ * digest policy, dedupe across reconnects, and the capability declaration.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS, CHANNEL_METHOD, InboxChannel, digestMinutesFromEnv, isImmediate, renderEvent } from './inbox-channel.js';
+import { buildOrbotoMcpServer } from './server.js';
+function mockMcp() {
+    const notification = vi.fn().mockResolvedValue(undefined);
+    return { mcp: { server: { notification } }, notification };
+}
+function sse(frames) {
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+        start(controller) {
+            for (const frame of frames)
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify(frame)}\n\n`));
+            controller.close();
+        },
+    });
+    return new Response(stream, { status: 200, headers: { 'content-type': 'text/event-stream' } });
+}
+const NOW = Date.parse('2026-09-18T10:00:00Z');
+const msg = (over = {}) => ({
+    id: 'm1', fromUserId: 'u-spec', kind: 'request', subject: 'ticket-ready:ORB-1', payload: { message: 'please take it' },
+    threadId: null, projectKey: 'ORB', createdAt: '2026-09-18 09:59:30+00',
+    from: { email: 'spec@orboto.io', sessionId: 'aaaaaaaa-0000-4000-8000-000000000000', role: 'spec', label: 'spec@orboto.io (spec, aaaaaaaa)' },
+    to: { email: 'claude@orboto.io', sessionId: 'bbbbbbbb-0000-4000-8000-000000000000', role: 'integrator', label: 'claude@orboto.io (integrator, bbbbbbbb)' },
+    ...over,
+});
+beforeEach(() => { vi.useFakeTimers(); vi.setSystemTime(NOW); });
+afterEach(() => { vi.useRealTimers(); vi.restoreAllMocks(); });
+describe('renderEvent / isImmediate', () => {
+    it('names both parties, carries id, project and thread, and caps the body', () => {
+        const e = renderEvent(msg({ threadId: 't1', payload: { message: 'x'.repeat(2500) } }), NOW);
+        expect(e.content.split('\n')[0]).toBe('[request] ticket-ready:ORB-1');
+        expect(e.content.split('\n')[1]).toBe('from spec@orboto.io (spec, aaaaaaaa) to claude@orboto.io (integrator, bbbbbbbb) | project ORB | id m1 | thread t1');
+        expect(e.content).toContain('[... cut, read the rest with orboto_messages]');
+        expect(e.meta).toMatchObject({ id: 'm1', kind: 'request', project: 'ORB', from_session: 'aaaaaaaa', to_session: 'bbbbbbbb', waited_min: '0' });
+    });
+    it('request, error, a question and a message that waited over five minutes go out at once; plain info is digest material', () => {
+        expect(isImmediate(msg({ kind: 'info', payload: { message: 'pushed abc' } }), NOW, 15)).toBe(false);
+        expect(isImmediate(msg({ kind: 'request' }), NOW, 15)).toBe(true);
+        expect(isImmediate(msg({ kind: 'error', payload: null }), NOW, 15)).toBe(true);
+        expect(isImmediate(msg({ kind: 'info', payload: { message: 'can you check?' } }), NOW, 15)).toBe(true);
+        expect(isImmediate(msg({ kind: 'info', payload: { message: 'old' }, createdAt: '2026-09-18 09:50:00+00' }), NOW, 15)).toBe(true);
+        expect(isImmediate(msg({ kind: 'info', payload: { message: 'pushed abc' } }), NOW, 0)).toBe(true);
+    });
+    it('reads the digest window from the environment with a safe default', () => {
+        expect(digestMinutesFromEnv(undefined)).toBe(15);
+        expect(digestMinutesFromEnv('0')).toBe(0);
+        expect(digestMinutesFromEnv('7.9')).toBe(7);
+        expect(digestMinutesFromEnv('nope')).toBe(15);
+        expect(digestMinutesFromEnv('-3')).toBe(15);
+    });
+});
+describe('InboxChannel', () => {
+    it('turns each streamed message into one channel notification and batches info into a digest', async () => {
+        const { mcp, notification } = mockMcp();
+        const fetchFn = vi.fn().mockResolvedValueOnce(sse([
+            msg(),
+            msg({ id: 'm2', kind: 'info', subject: 'pushed 1', payload: { message: 'ok' }, createdAt: '2026-09-18 09:59:50+00' }),
+            msg({ id: 'm3', kind: 'complete', subject: 'done 2', payload: null, createdAt: '2026-09-18 09:59:55+00' }),
+        ])).mockImplementation(() => new Promise(() => { }));
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp, fetchFn, log: () => { }, digestMinutes: 15 });
+        channel.start();
+        await vi.waitFor(() => expect(notification).toHaveBeenCalledTimes(1));
+        const first = notification.mock.calls[0][0];
+        expect(first.method).toBe(CHANNEL_METHOD);
+        expect(first.params.meta.id).toBe('m1');
+        expect(fetchFn.mock.calls[0][1].headers['x-orboto-agent-session']).toBe('mcp-proc');
+        expect(String(fetchFn.mock.calls[0][0])).toContain('/v1/agent/messages/stream?since=2026-09-18T10%3A00%3A00.000Z');
+        expect(channel.stats).toMatchObject({ delivered: 1, digested: 2 });
+        await vi.advanceTimersByTimeAsync(15 * 60_000);
+        expect(notification).toHaveBeenCalledTimes(2);
+        const digest = notification.mock.calls[1][0];
+        expect(digest.params.meta).toMatchObject({ kind: 'digest', count: '2' });
+        expect(digest.params.content).toContain('- [info] pushed 1');
+        expect(digest.params.content).toContain('- [complete] done 2');
+        channel.close();
+    });
+    it('reconnects from the last delivered id and never delivers a message twice', async () => {
+        const { mcp, notification } = mockMcp();
+        const fetchFn = vi.fn()
+            .mockResolvedValueOnce(sse([msg()]))
+            .mockResolvedValueOnce(sse([msg(), msg({ id: 'm9', subject: 'second' })]))
+            .mockImplementation(() => new Promise(() => { }));
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp, fetchFn, log: () => { }, digestMinutes: 0 });
+        channel.start();
+        await vi.waitFor(() => expect(notification).toHaveBeenCalledTimes(1));
+        await vi.advanceTimersByTimeAsync(2_000);
+        await vi.waitFor(() => expect(notification).toHaveBeenCalledTimes(2));
+        expect(String(fetchFn.mock.calls[1][0])).toContain('since=m1');
+        expect(channel.stats).toMatchObject({ delivered: 2, duplicates: 1 });
+        expect(channel.stats.reconnects).toBeGreaterThanOrEqual(1);
+        channel.close();
+    });
+});
+describe('server capability', () => {
+    async function connect(channel) {
+        vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('offline test'));
+        const server = await buildOrbotoMcpServer({ baseUrl: 'https://x.test', apiKey: 'orb_k', channel });
+        const client = new Client({ name: 't', version: '0' });
+        const [a, b] = InMemoryTransport.createLinkedPair();
+        await Promise.all([server.connect(a), client.connect(b)]);
+        return { server, client };
+    }
+    it('declares claude/channel and the channel instructions only when asked (stdio)', async () => {
+        const on = await connect(true);
+        expect(on.client.getServerCapabilities()?.experimental).toHaveProperty(CHANNEL_CAPABILITY);
+        expect(on.client.getInstructions()).toContain(CHANNEL_INSTRUCTIONS.slice(0, 40));
+        await on.client.close();
+        await on.server.close();
+        const off = await connect(false);
+        expect(off.client.getServerCapabilities()?.experimental ?? {}).not.toHaveProperty(CHANNEL_CAPABILITY);
+        expect(off.client.getInstructions() ?? '').not.toContain('Inbox channel:');
+        await off.client.close();
+        await off.server.close();
+    });
+});

package/dist/index.js

@@ -53,10 +53,21 @@ async function main() {
             console.error(`[orboto-mcp] ${err.message}`);
             process.exit(1);
         }
-        const server = await buildOrbotoMcpServer(clientConfig);
+        const channel = (process.env.ORBOTO_MCP_CHANNEL ?? '1') !== '0';
+        const server = await buildOrbotoMcpServer({ ...clientConfig, channel });
         const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
         const stdio = new StdioServerTransport();
         await server.connect(stdio);
+        if (channel) {
+            const { InboxChannel, digestMinutesFromEnv } = await import('./inbox-channel.js');
+            const { mcpProcessInstance } = await import('./tools/shared.js');
+            const instanceToken = mcpProcessInstance();
+            const inbox = new InboxChannel({ ...clientConfig, instanceToken, mcp: server, digestMinutes: digestMinutesFromEnv(process.env.ORBOTO_MCP_CHANNEL_DIGEST_MINUTES) });
+            inbox.start();
+            preflightClient.post('/v1/agent/heartbeat', { clientInfo: { channel: 'claude-code' } }, { instanceToken })
+                .catch((err) => { console.error(`[orboto-mcp] channel heartbeat failed: ${err.message}`); });
+            stdio.onclose = () => { inbox.close(); };
+        }
         return;
     }
     if (transport === 'http') {

package/dist/manifest-size.test.js

@@ -27,11 +27,15 @@ afterEach(() => { vi.restoreAllMocks(); });
  * 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 = 167_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
@@ -47,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

@@ -83,11 +83,11 @@ export class OrbotoClient {
         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

@@ -15,6 +15,7 @@ import { draftCustomerReplyToolConfig, makeDraftCustomerReplyHandler } from './t
 import { embeddingStatusToolConfig, makeEmbeddingStatusHandler } from './tools/embedding-status.js';
 import { aiUsageToolConfig, makeAiUsageHandler } from './tools/ai-usage.js';
 import { sessionStartToolConfig, makeSessionStartHandler } from './tools/session-start.js';
+import { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS } from './inbox-channel.js';
 import { loadRequiredRules } from './required-rules.js';
 import { responseExpandToolConfig, makeResponseExpandHandler } from './tools/response-expand.js';
 import { helpToolConfig, makeHelpHandler } from './tools/help.js';
@@ -155,18 +156,22 @@ export async function buildOrbotoMcpServer(opts) {
     catch {
         workingRules = 'Workspace rules are unavailable. Built-in hints are not a substitute. Call orboto_session_start with forceRules and retry after connectivity or authentication recovers.';
     }
+    const channelHint = opts.channel ? [CHANNEL_INSTRUCTIONS] : [];
     const server = new McpServer({ name: 'orboto', version: VERSION }, {
         capabilities: {
             resources: { subscribe: true, listChanged: true },
+            ...(opts.channel ? { experimental: { [CHANNEL_CAPABILITY]: {} } } : {}),
         },
         instructions: toolset === 'minimal'
             ? [
                 staticMcpHints(toolset),
                 'FIRST ACTION: call `orboto_session_start` - it returns the binding workspace rules plus your in-progress work. Re-run it after any context compaction. Non-negotiables: claim or create a ticket before touching code, one commit per ticket with the ticket key in the subject, push after each commit, never mark work done that is not done.',
+                ...channelHint,
             ].join('\n\n')
             : assembleInstructions([
                 staticMcpHints(toolset),
                 'FIRST ACTION this session: call the `orboto_session_start` tool - it returns the complete, authoritative binding rules you must follow (plus your in-progress work). Re-run it after any context compaction. If the rules below look cut off, `orboto_session_start` and the `orboto://rules` resource always have the full set. (Do NOT use `orboto_list_agent_instructions` to read the rules - that manages rule blocks for admins.) Core non-negotiables: ticket-first (claim or create a ticket before touching code), one commit per ticket with the ticket key in the subject line, push after each commit, and never mark work done that is not actually done.',
+                ...channelHint,
             ].join('\n\n'), workingRules),
     });
     const nudgeState = createNudgeState(requireSessionStart);

package/dist/tools/agent-coordination.js

@@ -6,11 +6,13 @@
 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(),
@@ -24,15 +26,17 @@ 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 },
         };
     };
 }
@@ -80,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'),
@@ -89,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 },
 };
@@ -123,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

@@ -186,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-messages.js

@@ -10,9 +10,10 @@
 import { z } from 'zod';
 import { makeAgentMessageWorkHandler } from './agent-message-work.js';
 import { mcpInstanceToken } from './shared.js';
+const PartySchema = z.object({ userId: z.string(), email: z.string(), sessionId: z.string().nullable(), role: z.string().nullable(), label: z.string() });
 export const agentMessagesToolConfig = {
     title: 'Agent inbox and message work',
-    description: 'Your inbox. messageWork carries durable work ownership - claim before executing. ackIds is a plain read receipt: no claim needed, finishes nothing. Reply via orboto_agent_notify with threadId.',
+    description: 'Your inbox as THIS session sees it: mail to this session, account mail inside your declared scope, broadcasts; sibling-session mail and own sends stay out, all:true shows the whole account (ORB-2136). messageWork carries durable work ownership - claim before executing. ackIds is a plain read receipt: no claim needed, finishes nothing. Reply via orboto_agent_notify with threadId (toSessionRef = from.sessionId reaches that instance).',
     inputSchema: z.object({
         messageWork: z.record(z.unknown()).optional()
             .describe('Work envelope {messageId, mutation, cursor, limit, openOnly}; schema: orboto_api_search.'),
@@ -24,9 +25,12 @@ export const agentMessagesToolConfig = {
     }).shape,
     outputSchema: z.object({
         work: z.record(z.unknown()).optional(),
+        sessionId: z.string().nullable().optional(),
         messages: z.array(z.object({
             id: z.string(),
             fromUserId: z.string(),
+            from: PartySchema,
+            to: PartySchema,
             kind: z.string(),
             subject: z.string(),
             payload: z.record(z.string(), z.unknown()).nullable(),
@@ -59,21 +63,24 @@ export function makeAgentMessagesHandler(client) {
             q.set('limit', String(args.limit));
         if (args.project)
             q.set('project', args.project);
-        if (!args.includeOwnSends) {
-            q.set('excludeRef', mcpInstanceToken(undefined, extra));
-        }
-        const { messages } = await client.get(`/v1/agent/messages${q.toString() ? `?${q.toString()}` : ''}`);
+        const instanceToken = mcpInstanceToken(undefined, extra);
+        if (!args.includeOwnSends)
+            q.set('excludeRef', instanceToken);
+        const { messages, sessionId } = await client.get(`/v1/agent/messages${q.toString() ? `?${q.toString()}` : ''}`, { instanceToken });
         const lines = messages.length === 0
             ? [acked > 0 ? `Acknowledged ${acked} message(s). Inbox empty.` : 'Inbox empty.']
-            : messages.map((m) => `[${m.kind}]${m.projectKey ? ` [${m.projectKey}]` : ''} ${m.subject} (from ${m.fromUserId}, ${m.createdAt}, id ${m.id}${m.threadId ? `, thread ${m.threadId}` : ''})${m.payload ? ` payload: ${JSON.stringify(m.payload)}` : ''}`);
+            : messages.map((m) => `[${m.kind}]${m.projectKey ? ` [${m.projectKey}]` : ''} ${m.subject} (from ${m.from?.label ?? m.fromUserId} to ${m.to?.label ?? m.toUserId}, ${m.createdAt}, id ${m.id}${m.threadId ? `, thread ${m.threadId}` : ''})${m.payload ? ` payload: ${JSON.stringify(m.payload)}` : ''}`);
         if (messages.length > 0) {
-            lines.push(`Acknowledge with ackIds once handled; reply via orboto_agent_notify with threadId.`);
+            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 (sessionId)
+            lines.push(`This session: ${sessionId.slice(0, 8)} (ref ${instanceToken}).`);
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
             structuredContent: {
+                sessionId: sessionId ?? null,
                 messages: messages.map((m) => ({
-                    id: m.id, fromUserId: m.fromUserId, kind: m.kind, subject: m.subject,
+                    id: m.id, fromUserId: m.fromUserId, from: m.from, to: m.to, kind: m.kind, subject: m.subject,
                     payload: m.payload, threadId: m.threadId, projectKey: m.projectKey ?? null,
                     createdAt: m.createdAt, readAt: m.readAt,
                 })),

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

@@ -1,10 +1,11 @@
 import { z } from 'zod';
+import { AgentSessionScopeSchema } from './agent-session-scope.js';
 const WorkSessionResourceClaimSchema = z.object({
     kind: z.enum(['path', 'named']), value: z.string().min(1).max(500), mode: z.enum(['read', 'write']),
     state: z.enum(['granted', 'waiting']).optional(), requestedAt: z.string().optional(),
 });
 export const AgentInventoryKindSchema = z.enum(['agent', 'human']);
-export const AgentConnectionTypeSchema = z.enum(['api_key', 'oauth', 'lane', 'external_token', 'live_events', 'web']);
+export const AgentConnectionTypeSchema = z.enum(['api_key', 'oauth', 'lane', 'external_token', 'live_events', 'web', 'channel']);
 export const AgentInventoryConnectionSchema = z.object({ type: AgentConnectionTypeSchema, label: z.string() });
 export const AgentInventoryProjectSchema = z.object({ id: z.string().uuid(), key: z.string(), name: z.string() });
 export const AgentInventoryEntrySchema = z.object({
@@ -29,6 +30,10 @@ export const AgentInventoryEntrySchema = z.object({
     })),
     capabilities: z.array(z.string()),
     clientInfo: z.record(z.string(), z.string()),
+    /** ORB-2136 - the scope the session declared; null when it declared none. */
+    scope: AgentSessionScopeSchema.nullable(),
+    /** ORB-2136 - unread inbox messages this session would list. */
+    unreadMessages: z.number().int(),
     lastSeenAt: z.string(),
     createdAt: z.string(),
 });

package/dist/tools/agent-session-scope.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+/** ORB-2136 - standalone mirror of `@orboto/shared-schema` agent-session-scope (the MCP package does not depend on it). */
+export const AgentSessionRoleSchema = z.enum(['integrator', 'lead', 'worker', 'spec', 'review', 'coordinator']);
+export const AgentSessionScopeSchema = z.object({
+    projectKeys: z.array(z.string()).optional(),
+    ticketKeys: z.array(z.string()).optional(),
+    role: AgentSessionRoleSchema.optional(),
+});

package/dist/tools/api-call.js

@@ -9,6 +9,7 @@
  * instead of surfacing as an opaque tool failure.
  */
 import { z } from 'zod';
+import { mcpInstanceToken } from './shared.js';
 export const apiCallToolConfig = {
     title: 'Call any orboto REST endpoint',
     description: 'Execute one REST API request - the escape hatch for every endpoint without a named tool. '
@@ -28,7 +29,7 @@ export const apiCallToolConfig = {
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
 };
 export function makeApiCallHandler(client) {
-    return async (input) => {
+    return async (input, extra) => {
         let body = input.body;
         if (typeof body === 'string') {
             try {
@@ -41,7 +42,7 @@ export function makeApiCallHandler(client) {
             path: input.path,
             ...(input.query ? { query: input.query } : {}),
             ...(body !== undefined ? { body } : {}),
-        });
+        }, { instanceToken: mcpInstanceToken(undefined, extra) });
         const bodyText = envelope.encoding === 'json'
             ? JSON.stringify(envelope.body, null, 1)
             : String(envelope.body ?? '');

package/dist/tools/api-call.test.js

@@ -100,4 +100,15 @@ describe('orboto_api_call', () => {
         const res = await makeApiCallHandler(client)({ method: 'GET', path: '/export' });
         expect(res.content[0].text).toContain('truncated by the proxy cap');
     });
+    it('ORB-2144: the proxy request carries this MCP session as x-orboto-agent-session', async () => {
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            seen.push((init?.headers ?? {}));
+            return { ok: true, status: 200, statusText: 'OK', json: async () => ({ status: 200, contentType: 'application/json', body: { sessionId: 's' }, encoding: 'json', truncated: false, matchedRoute: '/v1/agent/heartbeat' }), text: async () => '' };
+        });
+        await makeApiCallHandler(client)({ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'spec' } } }, { sessionId: 'abc123' });
+        expect(seen[0]['x-orboto-agent-session']).toBe('mcp-abc123');
+        await makeApiCallHandler(client)({ method: 'GET', path: '/v1/agent/messages' });
+        expect(seen[1]['x-orboto-agent-session']).toMatch(/^mcp-/);
+    });
 });

package/dist/tools/session-start.js

@@ -9,14 +9,15 @@
  * @see ORB-1605, ORB-1607, ORB-1818
  */
 import { z } from 'zod';
-import { resolveTicketByKey, applyAgentProfile } from './shared.js';
+import { resolveTicketByKey, applyAgentProfile, mcpInstanceToken } from './shared.js';
+import { AgentSessionScopeSchema } from './agent-session-scope.js';
 import { PROTECT_TEXT_META, storePayload } from '../response-budget.js';
 import { loadRequiredRules } from '../required-rules.js';
 import { GIT_HEALTH_REASON_TEXT } from './git-health-reasons.js';
 export const sessionStartToolConfig = {
     title: 'Load the rules you must follow + re-orient',
-    description: 'THE canonical way to LOAD the binding workspace rules you must follow as an agent. Run it as your FIRST action in a session and immediately AFTER any context compaction. Returns a one-line-per-rule INDEX of the binding working-rules plus their hash (or a compact "unchanged" ack on a repeat call within the same connection) - read the index, then call this tool again with `rulesOnly: true` to read the full text of the rules whenever you do not already hold that exact hash, and expand before acting on any rule whose title touches what you are about to do. Also returns your in-progress tickets - each flagged LANDED, IDLE when it has a linked commit but has not moved for days, i.e. finished work you never handed to review - your running timer, and a warning if a project\'s git connection looks unhealthy (commit ingestion may be stalled). Pass `ticketKey` to also get a one-shot bundle for that ticket: project primer, the full ticket with dependencies + checklists, that project\'s git health, and any other agent sessions currently on it - replacing several separate calls. (Do NOT use orboto_list_agent_instructions to read the rules - that tool MANAGES/edits rule blocks for admins; this one is what you read to know how to work.) Read-only; no side effects. '
-        + '**Parameters.** `rulesOnly: true` returns ONLY the complete rules text (nothing else) and is never truncated - the cheapest way to read the rules the index listed. `projectId` adds that project\'s rules on top of the workspace + personal ones. `ticketKey` ("ACME-42") bundles that ticket\'s primer, full detail, dependencies, checklists, git health and other active agent sessions into the same response. `forceRules: true` returns the full rules text inline with the rest of the digest even when this connection already delivered them - use it whenever the rules are NOT in your context right now: after a compaction, a /clear, or a fresh agent taking over an existing connection. `agentKind` (coding, orchestrator, reviewer, runner) and `modelTier` (frontier, standard, small) are your self-declared classification; rule blocks and per-tier rule text are targeted by them.',
+    description: 'THE canonical way to LOAD the binding workspace rules you must follow as an agent. Run it as your FIRST action in a session and immediately AFTER any context compaction. Returns a one-line-per-rule INDEX of the binding working-rules plus their hash (or a compact "unchanged" ack on a repeat call within the same connection) - read the index, then call this tool again with `rulesOnly: true` to read the full text of the rules whenever you do not already hold that exact hash, and expand before acting on any rule whose title touches what you are about to do. Also returns your in-progress tickets - each flagged LANDED, IDLE when it has a linked commit but has not moved for days, i.e. finished work you never handed to review - your running timer, and a warning if a project\'s git connection looks unhealthy (commit ingestion may be stalled). Pass `ticketKey` to also get a one-shot bundle for that ticket: project primer, the full ticket with dependencies + checklists, that project\'s git health, and any other agent sessions currently on it - replacing several separate calls. (Do NOT use orboto_list_agent_instructions to read the rules - that tool MANAGES/edits rule blocks for admins; this one is what you read to know how to work.) Registers this session (a heartbeat on its instance row) and is otherwise read-only. '
+        + '**Parameters.** `rulesOnly: true` returns ONLY the complete rules text (nothing else) and is never truncated - the cheapest way to read the rules the index listed. `projectId` adds that project\'s rules on top of the workspace + personal ones. `ticketKey` ("ACME-42") bundles that ticket\'s primer, full detail, dependencies, checklists, git health and other active agent sessions into the same response. `forceRules: true` returns the full rules text inline with the rest of the digest even when this connection already delivered them - use it whenever the rules are NOT in your context right now: after a compaction, a /clear, or a fresh agent taking over an existing connection. `agentKind` (coding, orchestrator, reviewer, runner) and `modelTier` (frontier, standard, small) are your self-declared classification; rule blocks and per-tier rule text are targeted by them. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility; the returned session.ref is what peers pass as toSessionRef (ORB-2136).',
     inputSchema: z.object({
         projectId: z.string().uuid().optional().describe('Also load this project\'s rules.'),
         ticketKey: z.string().min(3).optional().describe('Ticket key ("ACME-42") - bundles that ticket\'s full context.'),
@@ -24,8 +25,9 @@ export const sessionStartToolConfig = {
         rulesOnly: z.boolean().optional().describe('Return ONLY the complete rules text.'),
         agentKind: z.string().min(1).max(32).optional().describe('coding | orchestrator | reviewer | runner.'),
         modelTier: z.string().min(1).max(32).optional().describe('frontier | standard | small.'),
+        scope: AgentSessionScopeSchema.optional(),
     }).shape,
-    annotations: { readOnlyHint: true, idempotentHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };
 const MAX_GIT_HEALTH_PROJECTS = 8;
 /** ORB-1607 - build the `--ticket` one-shot bundle. Never throws: an
@@ -128,7 +130,8 @@ async function buildTicketBundle(client, ticketKey) {
 }
 export function makeSessionStartHandler(client) {
     let lastKnownRulesHash;
-    return async (input = {}) => {
+    return async (input = {}, extra) => {
+        const instanceToken = mcpInstanceToken(undefined, extra);
         const rulesParams = new URLSearchParams();
         if (input.projectId)
             rulesParams.set('projectId', input.projectId);
@@ -163,16 +166,19 @@ export function makeSessionStartHandler(client) {
                 },
             };
         }
+        const registration = await client.post('/v1/agent/heartbeat', input.scope !== undefined ? { scope: input.scope } : {}, { instanceToken })
+            .then((r) => (r && typeof r.sessionId === 'string' ? { sessionId: r.sessionId, scope: r.scope ?? null } : null))
+            .catch(() => null);
         const [me, rules, assigned, timer, inboxRaw] = await Promise.all([
             client.get('/users/me').catch(() => null),
             loadRequiredRules(client, rulesPath, rulesParams.get('knownRulesHash') ?? undefined),
             client.get('/users/me/assigned-tickets?statuses=IN_PROGRESS,IN_REVIEW&limit=20').catch(() => ({ items: [] })),
             client.get('/time/timer').catch(() => null),
-            client.get('/v1/agent/messages?limit=10')
+            client.get('/v1/agent/messages?limit=10', { instanceToken })
                 .then((r) => (Array.isArray(r?.messages) ? r.messages : []))
                 .catch(() => []),
         ]);
-        const pendingMessages = inboxRaw.map((m) => ({ id: m.id, fromUserId: m.fromUserId, kind: m.kind, subject: m.subject, createdAt: m.createdAt }));
+        const pendingMessages = inboxRaw.map((m) => ({ id: m.id, fromUserId: m.fromUserId, from: m.from?.label ?? m.fromUserId, kind: m.kind, subject: m.subject, createdAt: m.createdAt }));
         const tickets = Array.isArray(assigned) ? assigned : (assigned?.items ?? []);
         const projectIds = [...new Set(tickets.map((t) => t.projectId).filter((id) => !!id))].slice(0, MAX_GIT_HEALTH_PROJECTS);
         const gitHealthByProject = await Promise.all(projectIds.map(async (projectId) => ({
@@ -245,10 +251,15 @@ export function makeSessionStartHandler(client) {
         }
         lines.push('', '## Timer');
         lines.push(timer?.ticketId ? `Running on ${timer.ticketKey ?? timer.ticketId} since ${timer.startedAt ?? 'earlier'}.` : 'No timer running.');
+        lines.push('', '## This session');
+        const scopeText = registration?.scope
+            ? [registration.scope.role ? `role ${registration.scope.role}` : null, registration.scope.projectKeys?.length ? `projects ${registration.scope.projectKeys.join(', ')}` : null, registration.scope.ticketKeys?.length ? `tickets ${registration.scope.ticketKeys.join(', ')}` : null].filter(Boolean).join('; ')
+            : 'no scope declared - this session lists every account-addressed message; pass scope: { projectKeys, role } to narrow it';
+        lines.push(`ref ${instanceToken}${registration ? `, instance ${registration.sessionId.slice(0, 8)}` : ''}. ${scopeText}. Peers reach exactly this session with orboto_agent_notify { toSessionRef: "${registration ? registration.sessionId.slice(0, 8) : instanceToken}" }.`);
         if (pendingMessages.length > 0) {
             lines.push('', '## Agent messages - unread');
             for (const m of pendingMessages)
-                lines.push(`- [${m.kind}] ${m.subject} (from ${m.fromUserId}, ${m.createdAt}, id ${m.id})`);
+                lines.push(`- [${m.kind}] ${m.subject} (from ${m.from}, ${m.createdAt}, id ${m.id})`);
             lines.push('Handle them, then acknowledge via orboto_messages { ackIds: [...] }; reply via orboto_agent_notify with threadId.');
         }
         if (bundle)
@@ -274,6 +285,7 @@ export function makeSessionStartHandler(client) {
                 })),
                 ...(elsewhereCount > 0 ? { inProgressElsewhereCount: elsewhereCount } : {}),
                 timer: timer?.ticketId ? { ticketKey: timer.ticketKey ?? null, startedAt: timer.startedAt ?? null } : null,
+                session: { ref: instanceToken, id: registration?.sessionId ?? null, scope: registration?.scope ?? null },
                 gitHealth: {
                     unhealthy: gitHealthWithConnections
                         .map((p) => ({ projectId: p.projectId, connections: p.connections.filter((c) => !c.healthy) }))

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

@@ -523,3 +523,47 @@ describe('ORB-1818 - rules index instead of the full rule text', () => {
         expect(res.content[0].text).toContain(RULES_TEXT);
     });
 });
+describe('ORB-2136 - session scope and ref', () => {
+    it('registers the scope on this MCP session via heartbeat with the session header and reports the session ref', async () => {
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            const u = new URL(url.toString());
+            const path = u.pathname + u.search;
+            seen.push({ path, headers: (init?.headers ?? {}), body: init?.body ? JSON.parse(init.body) : undefined });
+            const map = {
+                '/v1/agent/heartbeat': { sessionToken: 'mcp-abc123', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: { role: 'integrator', projectKeys: ['ORB'] } },
+                '/users/me/assigned-tickets': { items: [] },
+                '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
+                '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
+                '/time/timer': {},
+                '/v1/agent/messages': { sessionId: 'cbb52195-0000-4000-8000-000000000000', messages: [{ id: 'm1', fromUserId: 'u1', from: { label: 'spec@orboto.io (spec, s1)' }, kind: 'request', subject: 'ticket-ready:ORB-1', createdAt: 'now' }] },
+            };
+            const key = Object.keys(map).find((k) => path.startsWith(k));
+            return { ok: true, status: 200, statusText: 'OK', json: async () => (key ? map[key] : {}), text: async () => '' };
+        });
+        const res = await makeSessionStartHandler(client)({ scope: { role: 'integrator', projectKeys: ['orb'] } }, { sessionId: 'abc123' });
+        const beat = seen.find((c) => c.path === '/v1/agent/heartbeat');
+        expect(beat?.headers['x-orboto-agent-session']).toBe('mcp-abc123');
+        expect(beat?.body).toEqual({ scope: { role: 'integrator', projectKeys: ['orb'] } });
+        expect(seen.find((c) => c.path.startsWith('/v1/agent/messages'))?.headers['x-orboto-agent-session']).toBe('mcp-abc123');
+        const text = res.content[0].text;
+        expect(text).toContain('ref mcp-abc123, instance cbb52195. role integrator; projects ORB');
+        expect(text).toContain('toSessionRef: "cbb52195"');
+        expect(text).toContain('from spec@orboto.io (spec, s1)');
+        expect(res.structuredContent).toMatchObject({ session: { ref: 'mcp-abc123', id: 'cbb52195-0000-4000-8000-000000000000', scope: { role: 'integrator', projectKeys: ['ORB'] } } });
+    });
+    it('without a scope the heartbeat body stays empty and the digest says no scope is declared', async () => {
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            const u = new URL(url.toString());
+            seen.push({ path: u.pathname, body: init?.body ? JSON.parse(init.body) : undefined });
+            const body = u.pathname === '/v1/agent/heartbeat'
+                ? { sessionToken: 'x', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: null }
+                : u.pathname === '/agent-instructions' ? { instructions: 'rules here', rulesHash: 'fixture' } : {};
+            return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => '' };
+        });
+        const res = await makeSessionStartHandler(client)({}, { sessionId: 'abc123' });
+        expect(seen.find((c) => c.path === '/v1/agent/heartbeat')?.body).toEqual({});
+        expect(res.content[0].text).toContain('no scope declared');
+    });
+});

package/dist/tools/shared.js

@@ -102,6 +102,10 @@ const MCP_PROCESS_INSTANCE = `mcp-${randomUUID()}`;
 export function mcpInstanceToken(explicit, extra) {
     return explicit ?? (extra?.sessionId ? `mcp-${extra.sessionId}` : MCP_PROCESS_INSTANCE);
 }
+/** ORB-2140 - the stdio process's own instance token, the one the inbox channel follows the stream with. */
+export function mcpProcessInstance() {
+    return MCP_PROCESS_INSTANCE;
+}
 /** ORB-1753 - the caller's self-declared agent profile from the process
  *  environment (stdio servers / runners). The api-key standing profile
  *  (ORB-1751) already covers keys server-side; these env vars let a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.197.0",
+  "version": "0.199.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",