@orboto/mcp 0.198.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/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-presence-schema.js

@@ -5,7 +5,7 @@ const WorkSessionResourceClaimSchema = z.object({
     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({

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/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.198.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",