@orboto/mcp 0.212.3 → 0.212.5

package/dist/http-transport-binding.test.js

@@ -69,11 +69,11 @@ const store = {
     resolve: async () => false,
     remove: async () => { },
 };
-async function start() {
+async function start(limits) {
     api = fakeApiPerUser();
     await new Promise((r) => api.listen(0, r));
     const { port: apiPort } = api.address();
-    server = createHttpServer({ baseUrl: `http://127.0.0.1:${apiPort}`, sessionStore: store });
+    server = createHttpServer({ baseUrl: `http://127.0.0.1:${apiPort}`, sessionStore: store, limits });
     await new Promise((r) => server.listen(0, r));
     const { port } = server.address();
     return `http://127.0.0.1:${port}`;
@@ -145,4 +145,31 @@ describe('ORB-1576 - request body cap', () => {
         expect(errored || status === 400).toBe(true);
     });
 });
-void vi;
+function internals() {
+    return server.__mcp;
+}
+describe('per-user session cap and idle reap', () => {
+    it('closes the owner\'s least recently used session when a new one would exceed the cap', async () => {
+        const base = await start({ maxSessionsPerUser: 2 });
+        const first = await initSession(base, 'orb_alice');
+        const second = await initSession(base, 'orb_alice');
+        const mallory = await initSession(base, 'orb_mallory');
+        const third = await initSession(base, 'orb_alice');
+        const ids = [...internals().sessions.keys()];
+        expect(ids).not.toContain(first);
+        expect(ids).toEqual(expect.arrayContaining([second, third, mallory]));
+        expect([...internals().sessions.values()].filter((s) => s.userEmail === 'alice@example.com')).toHaveLength(2);
+    });
+    it('drops sessions that stayed idle past the limit', async () => {
+        const base = await start({ idleMs: 1_000, reapIntervalMs: 20 });
+        const sid = await initSession(base, 'orb_alice');
+        internals().sessions.get(sid).lastActiveAt = Date.now() - 5_000;
+        await vi.waitFor(() => expect(internals().sessions.has(sid)).toBe(false), { timeout: 2_000 });
+    });
+    it('keeps an active session past the idle limit check', async () => {
+        const base = await start({ idleMs: 60_000, reapIntervalMs: 20 });
+        const sid = await initSession(base, 'orb_alice');
+        await new Promise((r) => setTimeout(r, 100));
+        expect(internals().sessions.has(sid)).toBe(true);
+    });
+});

package/dist/http-transport.js

@@ -13,6 +13,7 @@ import { OrbotoClient, preflightMcpSession } from './orboto-client.js';
 import { EventBridge } from './event-bridge.js';
 import { mcpInstanceToken } from './tools/shared.js';
 import { releaseCapacityAtSessionEnd } from './tools/capacity-session.js';
+import { idleSessions, resolveSessionLimits, sessionsOverOwnerCap } from './session-limits.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. */
@@ -166,8 +167,14 @@ function wwwAuthChallenge(req, baseUrl, error, description) {
     const resourceMetadata = `${origin}/.well-known/oauth-protected-resource`;
     return `Bearer realm="orboto-mcp", error="${error}", error_description="${description.replace(/"/g, '\\"')}", resource_metadata="${resourceMetadata}"`;
 }
-export function createHttpServer({ baseUrl, sessionStore }) {
+export function createHttpServer({ baseUrl, sessionStore, limits: limitOverrides }) {
     const sessions = new Map();
+    const limits = resolveSessionLimits(undefined, limitOverrides);
+    async function makeRoomFor(userEmail) {
+        const over = sessionsOverOwnerCap(sessions.values(), userEmail, limits.maxSessionsPerUser);
+        if (over.length > 0)
+            await closeAllMcpSessions(over, `you reached the limit of ${limits.maxSessionsPerUser} open sessions; the least recently used one is closed.`);
+    }
     const store = sessionStore ?? createApiSessionStore(baseUrl);
     async function buildSessionCore(tokenHolder, userAgentSuffix, toolset, sessionId) {
         const tokenProvider = holderTokenProvider(tokenHolder);
@@ -191,13 +198,14 @@ export function createHttpServer({ baseUrl, sessionStore }) {
         }
     }
     async function establishForcedSession(tokenHolder, userAgentSuffix, chosenSessionId, userEmail, toolset) {
+        await makeRoomFor(userEmail);
         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);
         forceInitialized(transport, chosenSessionId);
         const session = {
-            transport, mcp, client: sessionClient, bridge, tokenHolder, userEmail, lastTouchAt: Date.now(),
+            transport, mcp, client: sessionClient, bridge, tokenHolder, userEmail, lastTouchAt: Date.now(), lastActiveAt: Date.now(),
         };
         sessions.set(chosenSessionId, session);
         bridge.start();
@@ -228,6 +236,12 @@ export function createHttpServer({ baseUrl, sessionStore }) {
     }
     const killSwitchTimer = setInterval(() => { void pollKillSwitch(); }, pollMs);
     killSwitchTimer.unref?.();
+    const reapTimer = setInterval(() => {
+        const idle = idleSessions(sessions.values(), Date.now(), limits.idleMs);
+        if (idle.length > 0)
+            void closeAllMcpSessions(idle, 'the session was idle too long.');
+    }, limits.reapIntervalMs);
+    reapTimer.unref?.();
     const server = createServer(async (req, res) => {
         if (req.method === 'GET' && req.url === '/health') {
             res.writeHead(200, { 'content-type': 'application/json' });
@@ -309,6 +323,7 @@ export function createHttpServer({ baseUrl, sessionStore }) {
                 process.stderr.write(`[orboto-mcp] session ${sessionId} bearer rotated - adopting client's current access token\n`);
                 session.tokenHolder.current = token;
             }
+            session.lastActiveAt = Date.now();
             await session.transport.handleRequest(req, res, body);
             const now = Date.now();
             if (now - session.lastTouchAt >= TOUCH_THROTTLE_MS) {
@@ -369,6 +384,7 @@ export function createHttpServer({ baseUrl, sessionStore }) {
                     'WWW-Authenticate': wwwAuthChallenge(req, baseUrl, 'invalid_token', err.message),
                 });
             }
+            await makeRoomFor(ownerEmail);
             const tokenHolder = { current: token };
             const { sessionClient, mcp, bridge } = await buildSessionCore(tokenHolder, userAgentSuffix, toolset);
             const clientInfo = clientInfoLabel(body);
@@ -376,7 +392,7 @@ export function createHttpServer({ baseUrl, sessionStore }) {
                 sessionIdGenerator: () => randomUUID(),
                 onsessioninitialized: (sid) => {
                     sessions.set(sid, {
-                        transport, mcp, client: sessionClient, bridge, tokenHolder, userEmail: ownerEmail, lastTouchAt: Date.now(),
+                        transport, mcp, client: sessionClient, bridge, tokenHolder, userEmail: ownerEmail, lastTouchAt: Date.now(), lastActiveAt: Date.now(),
                     });
                     bridge.setInstanceToken(mcpInstanceToken(undefined, { sessionId: sid }));
                     bridge.start();
@@ -396,7 +412,7 @@ export function createHttpServer({ baseUrl, sessionStore }) {
         }
         sendError(res, 400, 'Missing mcp-session-id header or initialize request');
     });
-    server.on('close', () => clearInterval(killSwitchTimer));
+    server.on('close', () => { clearInterval(killSwitchTimer); clearInterval(reapTimer); });
     server.__mcp = { sessions, store };
     return server;
 }

package/dist/http-transport.test.js

@@ -79,6 +79,7 @@ describe('ORB-941 - graceful close of in-flight MCP sessions on kill-switch', ()
             tokenHolder: { current: 'orb_dummy' },
             userEmail: 'owner@orboto.test',
             lastTouchAt: Date.now(),
+            lastActiveAt: Date.now(),
         };
         return { session, close, log };
     }

package/dist/oauth-bootstrap.js

@@ -262,12 +262,27 @@ export function createTokenProvider(initial, refresh, onRefreshed, now = Date.no
 }
 /** Open a URL in the user's default browser. Returns false if no opener is
  *  available (headless) so the caller can print the URL for manual paste. */
+/** The opener command for a platform; never a shell, so the URL is one argv entry (Windows uses the URL protocol handler like the Go CLI). */
+function browserOpenerCommand(platform, url) {
+    if (platform === 'darwin')
+        return { cmd: 'open', args: [url] };
+    if (platform === 'win32')
+        return { cmd: 'rundll32', args: ['url.dll,FileProtocolHandler', url] };
+    return { cmd: 'xdg-open', args: [url] };
+}
 export async function openInBrowser(url) {
     if (process.env.ORBOTO_MCP_NO_BROWSER === '1')
         return false;
-    const platform = process.platform;
-    const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
-    const args = platform === 'win32' ? ['/c', 'start', '""', url] : [url];
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+        return false;
+    const { cmd, args } = browserOpenerCommand(process.platform, parsed.href);
     try {
         const { spawn } = await import('node:child_process');
         const child = spawn(cmd, args, { stdio: 'ignore', detached: true });

package/dist/oauth-browser-opener.test.js

@@ -0,0 +1,37 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+const spawn = vi.fn(() => ({ unref: () => { } }));
+vi.mock('node:child_process', () => ({ spawn }));
+const { openInBrowser } = await import('./oauth-bootstrap.js');
+const realPlatform = process.platform;
+function setPlatform(p) {
+    Object.defineProperty(process, 'platform', { value: p, configurable: true });
+}
+afterEach(() => {
+    setPlatform(realPlatform);
+    spawn.mockClear();
+    delete process.env.ORBOTO_MCP_NO_BROWSER;
+});
+const URL_WITH_METACHARS = 'https://auth.example.test/authorize&calc.exe|x^y?client_id=a&state=b';
+describe('OAuth browser opener', () => {
+    it('opens the URL on Windows without a command shell, as a single argument', async () => {
+        setPlatform('win32');
+        expect(await openInBrowser(URL_WITH_METACHARS)).toBe(true);
+        expect(spawn).toHaveBeenCalledTimes(1);
+        const [cmd, args] = spawn.mock.calls[0];
+        expect(cmd).not.toMatch(/cmd|powershell/i);
+        expect(args.filter((a) => a.includes('auth.example.test'))).toHaveLength(1);
+        expect(args).not.toContain('/c');
+    });
+    it('opens the URL directly on macOS and Linux', async () => {
+        setPlatform('linux');
+        await openInBrowser('https://auth.example.test/authorize?x=1');
+        expect(spawn.mock.calls[0]).toEqual(['xdg-open', ['https://auth.example.test/authorize?x=1'], expect.anything()]);
+    });
+    it('refuses anything but an http or https URL', async () => {
+        setPlatform('win32');
+        for (const url of ['file:///C:/Windows/System32/calc.exe', 'javascript:alert(1)', 'not a url']) {
+            expect(await openInBrowser(url)).toBe(false);
+        }
+        expect(spawn).not.toHaveBeenCalled();
+    });
+});

package/dist/response-budget.js

@@ -127,15 +127,19 @@ function pruneHandles(now) {
         handles.delete(oldest.value);
     }
 }
-export function storePayload(toolName, payload, now = Date.now()) {
-    const handle = randomUUID().slice(0, 8);
-    handles.set(handle, { toolName, storedAt: now, ...payload });
+/** Owner used by single-session callers (stdio, tests); HTTP sessions pass their own client. */
+export const PROCESS_OWNER = Object.freeze({});
+export function storePayload(toolName, payload, now = Date.now(), owner = PROCESS_OWNER) {
+    const handle = randomUUID().replace(/-/g, '').slice(0, 16);
+    handles.set(handle, { toolName, storedAt: now, owner, ...payload });
     pruneHandles(now);
     return handle;
 }
-export function readPayload(handle, now = Date.now()) {
+/** The stored payload for a handle, or null when it expired or belongs to another session. */
+export function readPayload(handle, now = Date.now(), owner = PROCESS_OWNER) {
     pruneHandles(now);
-    return handles.get(handle) ?? null;
+    const stored = handles.get(handle);
+    return stored && stored.owner === owner ? stored : null;
 }
 /** Record what the shrink pass cut, so the expand tool can list the paths. */
 export function annotatePayload(handle, omitted) {
@@ -245,7 +249,7 @@ function stringMarker(omitted, handle, path) {
  * `/admin/mcp/instrument`, so budget pressure stays visible in the
  * admin MCP-usage panel instead of needing another transcript audit.
  */
-export function applyResponseBudget(toolName, result, env = process.env) {
+export function applyResponseBudget(toolName, result, env = process.env, owner = PROCESS_OWNER) {
     const protectText = takeProtectTextFlag(result);
     const originalChars = measureResult(result);
     if (!budgetEnabled(env)) {
@@ -256,20 +260,20 @@ export function applyResponseBudget(toolName, result, env = process.env) {
         return { result, responseChars: originalChars, originalChars, truncatedChars: 0 };
     }
     try {
-        return shrink(toolName, result, budget, originalChars, protectText);
+        return shrink(toolName, result, budget, originalChars, protectText, owner);
     }
     catch {
         return { result, responseChars: originalChars, originalChars, truncatedChars: 0 };
     }
 }
-function shrink(toolName, result, budget, originalChars, protectText = false) {
+function shrink(toolName, result, budget, originalChars, protectText = false, owner = PROCESS_OWNER) {
     const fullText = (result.content ?? [])
         .map((part) => textOf(part) ?? '')
         .join('\n');
     const handle = storePayload(toolName, {
         structuredContent: result.structuredContent,
         text: fullText,
-    });
+    }, Date.now(), owner);
     const omitted = [];
     const structured = result.structuredContent === undefined
         ? undefined

package/dist/response-budget.test.js

@@ -237,6 +237,23 @@ describe('nothing is lost - orboto_response_expand', () => {
         expect(resolvePath(root, '')).toBe(root);
     });
 });
+describe('a handle is readable only by the session that produced it', () => {
+    it('another session cannot read or expand a handle, the owner can', async () => {
+        const sessionA = {};
+        const sessionB = {};
+        const out = applyResponseBudget(TOOL, result({ description: 'private '.repeat(5_000) }), {}, sessionA);
+        expect(out.handle).toBeDefined();
+        expect(readPayload(out.handle, Date.now(), sessionB)).toBeNull();
+        const foreign = await makeResponseExpandHandler(sessionB)({ handle: out.handle, path: 'description' });
+        expect(foreign.isError).toBe(true);
+        expect(JSON.stringify(foreign)).not.toContain('private');
+        const own = await makeResponseExpandHandler(sessionA)({ handle: out.handle, path: 'description' });
+        expect(own.isError).toBeUndefined();
+    });
+    it('issues handles with at least 64 bits of randomness', () => {
+        expect(storePayload(TOOL, { text: 'a' })).toMatch(/^[0-9a-f]{16}$/);
+    });
+});
 describe('the handle store is bounded', () => {
     it('evicts the oldest beyond MAX_HANDLES', () => {
         const first = storePayload(TOOL, { text: 'a' });

package/dist/server.js

@@ -10,6 +10,7 @@ import { registerOrbotoPrompts } from './prompts.js';
 import { registerWithMetrics } from './with-metrics.js';
 import { CHANNEL_TOOLSET_INSTRUCTIONS, CHANNEL_TOOLSET_WAKE_INSTRUCTIONS, resolveToolset, toolInToolset } from './toolset.js';
 import { createNudgeState } from './session-nudge.js';
+import { assertSubscribable, uriForLog } from './session-limits.js';
 import { aiStatusToolConfig, makeAiStatusHandler } from './tools/ai-status.js';
 import { draftCustomerReplyToolConfig, makeDraftCustomerReplyHandler } from './tools/customer-draft.js';
 import { embeddingStatusToolConfig, makeEmbeddingStatusHandler } from './tools/embedding-status.js';
@@ -200,7 +201,7 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_ai_usage', aiUsageToolConfig, makeAiUsageHandler(client));
     reg('orboto_secret_scan', secretScanToolConfig, makeSecretScanHandler(client));
     reg('orboto_session_start', sessionStartToolConfig, makeSessionStartHandler(client, { channel: opts.channel }));
-    reg('orboto_response_expand', responseExpandToolConfig, makeResponseExpandHandler());
+    reg('orboto_response_expand', responseExpandToolConfig, makeResponseExpandHandler(client));
     reg('orboto_help', helpToolConfig, makeHelpHandler());
     reg('orboto_api_search', apiSearchToolConfig, makeApiSearchHandler(client));
     reg('orboto_api_call', apiCallToolConfig, makeApiCallHandler(client));
@@ -392,9 +393,10 @@ export async function buildOrbotoMcpServer(opts) {
     if (opts.subscriptions) {
         const subs = opts.subscriptions;
         server.server.setRequestHandler(SubscribeRequestSchema, async (req) => {
+            assertSubscribable(subs, req.params.uri);
             subs.add(req.params.uri);
             try {
-                process.stderr.write(`[orboto-mcp] subscribe → ${req.params.uri} (total subs: ${subs.size})\n`);
+                process.stderr.write(`[orboto-mcp] subscribe → ${uriForLog(req.params.uri)} (total subs: ${subs.size})\n`);
             }
             catch { /* ignore */ }
             return {};
@@ -402,7 +404,7 @@ export async function buildOrbotoMcpServer(opts) {
         server.server.setRequestHandler(UnsubscribeRequestSchema, async (req) => {
             subs.delete(req.params.uri);
             try {
-                process.stderr.write(`[orboto-mcp] unsubscribe → ${req.params.uri} (remaining: ${subs.size})\n`);
+                process.stderr.write(`[orboto-mcp] unsubscribe → ${uriForLog(req.params.uri)} (remaining: ${subs.size})\n`);
             }
             catch { /* ignore */ }
             return {};

package/dist/session-limits.js

@@ -0,0 +1,39 @@
+/** Bounds on in-memory MCP HTTP sessions and their resource subscriptions. */
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+function positiveInt(raw, fallback) {
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+export function resolveSessionLimits(env = {
+    ORBOTO_MCP_MAX_SESSIONS_PER_USER: process.env.ORBOTO_MCP_MAX_SESSIONS_PER_USER,
+    ORBOTO_MCP_SESSION_IDLE_MS: process.env.ORBOTO_MCP_SESSION_IDLE_MS,
+}, override = {}) {
+    const idleMs = override.idleMs ?? positiveInt(env.ORBOTO_MCP_SESSION_IDLE_MS, 6 * 60 * 60_000);
+    return {
+        maxSessionsPerUser: override.maxSessionsPerUser ?? positiveInt(env.ORBOTO_MCP_MAX_SESSIONS_PER_USER, 32),
+        idleMs,
+        reapIntervalMs: override.reapIntervalMs ?? Math.min(idleMs, 60_000),
+    };
+}
+/** The owner's least recently active sessions that must close so one more fits under the cap. */
+export function sessionsOverOwnerCap(sessions, userEmail, max) {
+    const owned = [...sessions].filter((s) => s.userEmail === userEmail).sort((a, b) => a.lastActiveAt - b.lastActiveAt);
+    return owned.slice(0, Math.max(0, owned.length - max + 1));
+}
+export function idleSessions(sessions, now, idleMs) {
+    return [...sessions].filter((s) => now - s.lastActiveAt >= idleMs);
+}
+export const MAX_SUBSCRIPTIONS_PER_SESSION = 500;
+export const MAX_SUBSCRIPTION_URI_LENGTH = 2048;
+/** Validates a resources/subscribe URI before it joins the session's set; throws InvalidParams otherwise. */
+export function assertSubscribable(subs, uri) {
+    if (typeof uri !== 'string' || !uri.startsWith('orboto://') || uri.length > MAX_SUBSCRIPTION_URI_LENGTH) {
+        throw new McpError(ErrorCode.InvalidParams, `Subscriptions accept orboto:// resource URIs up to ${MAX_SUBSCRIPTION_URI_LENGTH} characters`);
+    }
+    if (!subs.has(uri) && subs.size >= MAX_SUBSCRIPTIONS_PER_SESSION) {
+        throw new McpError(ErrorCode.InvalidParams, `A session holds at most ${MAX_SUBSCRIPTIONS_PER_SESSION} resource subscriptions`);
+    }
+}
+export function uriForLog(uri) {
+    return uri.length > 200 ? `${uri.slice(0, 200)}...` : uri;
+}

package/dist/session-limits.test.js

@@ -0,0 +1,60 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { buildOrbotoMcpServer } from './server.js';
+import { McpError } from '@modelcontextprotocol/sdk/types.js';
+import { assertSubscribable, MAX_SUBSCRIPTIONS_PER_SESSION, MAX_SUBSCRIPTION_URI_LENGTH, resolveSessionLimits, sessionsOverOwnerCap, uriForLog, } from './session-limits.js';
+describe('resource subscription bounds', () => {
+    it('accepts an orboto resource URI', () => {
+        expect(() => assertSubscribable(new Set(), 'orboto://ticket/ORB-1')).not.toThrow();
+    });
+    it('rejects a URI outside the orboto scheme or over the length limit', () => {
+        expect(() => assertSubscribable(new Set(), 'https://example.com/x')).toThrow(McpError);
+        expect(() => assertSubscribable(new Set(), `orboto://ticket/${'x'.repeat(MAX_SUBSCRIPTION_URI_LENGTH)}`)).toThrow(McpError);
+    });
+    it('rejects a new URI once the session holds the maximum, but re-subscribing a held one stays fine', () => {
+        const subs = new Set(Array.from({ length: MAX_SUBSCRIPTIONS_PER_SESSION }, (_, i) => `orboto://ticket/T-${i}`));
+        expect(() => assertSubscribable(subs, 'orboto://ticket/NEW-1')).toThrow(McpError);
+        expect(() => assertSubscribable(subs, 'orboto://ticket/T-0')).not.toThrow();
+    });
+    it('shortens long URIs in the log line', () => {
+        expect(uriForLog(`orboto://search/${'q'.repeat(1000)}`).length).toBeLessThan(210);
+    });
+});
+describe('resources/subscribe handler', () => {
+    afterEach(() => { vi.restoreAllMocks(); });
+    async function connect(subscriptions) {
+        vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('offline test'));
+        const server = await buildOrbotoMcpServer({ baseUrl: 'https://x.test', apiKey: 'orb_k', subscriptions, toolset: 'curated' });
+        const client = new Client({ name: 't', version: '0' });
+        const [a, b] = InMemoryTransport.createLinkedPair();
+        await Promise.all([server.connect(a), client.connect(b)]);
+        return client;
+    }
+    it('stores a valid URI and refuses an oversized or foreign one without storing it', async () => {
+        const subs = new Set();
+        const client = await connect(subs);
+        await client.subscribeResource({ uri: 'orboto://ticket/ORB-1' });
+        await expect(client.subscribeResource({ uri: `orboto://search/${'x'.repeat(5000)}` })).rejects.toThrow();
+        await expect(client.subscribeResource({ uri: 'file:///etc/passwd' })).rejects.toThrow();
+        expect([...subs]).toEqual(['orboto://ticket/ORB-1']);
+    });
+});
+describe('session cap selection', () => {
+    it('picks the oldest sessions of the owner only', () => {
+        const sessions = [
+            { id: 'a1', userEmail: 'a', lastActiveAt: 3 },
+            { id: 'a2', userEmail: 'a', lastActiveAt: 1 },
+            { id: 'b1', userEmail: 'b', lastActiveAt: 0 },
+            { id: 'a3', userEmail: 'a', lastActiveAt: 2 },
+        ];
+        expect(sessionsOverOwnerCap(sessions, 'a', 2).map((s) => s.id)).toEqual(['a2', 'a3']);
+        expect(sessionsOverOwnerCap(sessions, 'b', 2)).toEqual([]);
+    });
+    it('reads the limits from the environment with safe fallbacks', () => {
+        expect(resolveSessionLimits({ ORBOTO_MCP_MAX_SESSIONS_PER_USER: '4', ORBOTO_MCP_SESSION_IDLE_MS: '1000' })).toEqual({
+            maxSessionsPerUser: 4, idleMs: 1000, reapIntervalMs: 1000,
+        });
+        expect(resolveSessionLimits({ ORBOTO_MCP_MAX_SESSIONS_PER_USER: 'junk' }).maxSessionsPerUser).toBe(32);
+    });
+});

package/dist/tools/cross-project-links.ee.js

@@ -38,7 +38,7 @@ export function makeListCrossProjectLinksHandler(client) {
 }
 export const addCrossProjectLinkToolConfig = {
     title: 'Add a cross-project link between two tickets',
-    description: 'Create a formal relation between two tickets in different projects. Caller must be a member of BOTH the source and target projects. Relation types: counterpart (parallel work in two repos - bidirectional), depends_on (this ticket waits for the other), blocks (the other waits for this), related (loose association). Pass statusSyncEnabled=true to opt into auto-close: when a counterpart-linked ticket moves to done, the other auto-closes too. Off by default.',
+    description: 'Create a formal relation between two tickets in different projects. The caller must be a member of both projects and read both tickets. Relation types: counterpart (parallel work, bidirectional), depends_on (this waits for the other), blocks (the other waits for this), related (loose). statusSyncEnabled=true (default off) auto-closes the other end of a counterpart link when one moves to done; it needs ticket:edit and ticket:change_status in both projects (403 otherwise). A close by a user lacking those grants or read access on the far end leaves it open, audited and notified.',
     inputSchema: z.object({
         sourceTicketKey: z.string().min(3),
         targetTicketKey: z.string().min(3),
@@ -61,7 +61,7 @@ export function makeAddCrossProjectLinkHandler(client) {
 }
 export const updateCrossProjectLinkToolConfig = {
     title: 'Toggle status-sync on a cross-project link',
-    description: 'Flip the statusSyncEnabled flag on an existing cross-project link. When enabled on a counterpart-typed link, the other end auto-closes when this one moves to done (and vice versa). Other relation types ignore the flag at runtime, so toggling it on them is a no-op as far as status-sync goes.',
+    description: 'Flip statusSyncEnabled on an existing cross-project link. Enabling needs ticket:edit and ticket:change_status in both projects (403 otherwise); disabling is always allowed. On a counterpart link the other end auto-closes when one moves to done, if the closing user holds those grants and read access there. Other relation types ignore the flag.',
     inputSchema: z.object({
         sourceTicketKey: z.string().min(3),
         linkId: z.string().uuid(),

package/dist/tools/cross-project-links.ee.test.js

@@ -9,7 +9,7 @@
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
-import { makeListCrossProjectLinksHandler, makeAddCrossProjectLinkHandler, makeUpdateCrossProjectLinkHandler, makeRemoveCrossProjectLinkHandler, } from './cross-project-links.ee.js';
+import { makeListCrossProjectLinksHandler, makeAddCrossProjectLinkHandler, makeUpdateCrossProjectLinkHandler, makeRemoveCrossProjectLinkHandler, addCrossProjectLinkToolConfig, updateCrossProjectLinkToolConfig, } from './cross-project-links.ee.js';
 beforeEach(() => { vi.restoreAllMocks(); });
 afterEach(() => { vi.restoreAllMocks(); });
 const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
@@ -161,3 +161,10 @@ describe('orboto_remove_cross_project_link', () => {
         await expect(makeRemoveCrossProjectLinkHandler(client)({ sourceTicketKey: 'ORB-42', linkId: LINK_ID })).rejects.toBeInstanceOf(OrbotoApiError);
     });
 });
+describe('ORB-2437 status-sync grant in the tool descriptions', () => {
+    it('add and update name ticket:edit and ticket:change_status as the grant for enabling sync', () => {
+        expect(addCrossProjectLinkToolConfig.description).toContain('ticket:edit and ticket:change_status in both projects');
+        expect(updateCrossProjectLinkToolConfig.description).toContain('ticket:edit and ticket:change_status in both projects');
+        expect(addCrossProjectLinkToolConfig.description).not.toContain('Caller must be a member of BOTH');
+    });
+});

package/dist/tools/list-git-app-installations.js

@@ -11,7 +11,7 @@
 import { z } from 'zod';
 export const listGitAppInstallationsToolConfig = {
     title: 'List GitHub App installations',
-    description: 'Every GitHub App installation orboto knows, across projects (super-admin): org/user, install time, suspended state.',
+    description: 'Every GitHub App installation orboto knows (admin:system:read): org/user, install time, suspended state and the project keys allowed to use it.',
     inputSchema: z.object({}).shape,
     annotations: { readOnlyHint: true, idempotentHint: true },
 };
@@ -19,15 +19,17 @@ export function makeListGitAppInstallationsHandler(client) {
     return async () => {
         const rows = await client.get('/admin/git-app-installations');
         const out = rows.map((r) => ({
+            id: r.id,
             provider: r.provider,
             accountLogin: r.accountLogin,
             accountType: r.accountType,
             installedAt: r.installedAt,
             suspended: r.suspendedAt !== null,
+            projects: (r.projects ?? []).map((p) => p.key),
         }));
         const text = out.length === 0
             ? 'No GitHub App installations registered.'
-            : out.map((r) => `- ${r.accountLogin} (${r.accountType}) - installed ${r.installedAt}${r.suspended ? ' - SUSPENDED' : ''}`).join('\n');
+            : out.map((r) => `- ${r.accountLogin} (${r.accountType}) - installed ${r.installedAt}${r.suspended ? ' - SUSPENDED' : ''} - projects: ${r.projects.length > 0 ? r.projects.join(', ') : 'none'}`).join('\n');
         return {
             content: [{ type: 'text', text }],
             structuredContent: { installations: out },

package/dist/tools/response-expand.js

@@ -3,7 +3,7 @@
  * response.
  */
 import { z } from 'zod';
-import { budgetFor, readPayload, resolvePath, } from '../response-budget.js';
+import { budgetFor, PROCESS_OWNER, readPayload, resolvePath, } from '../response-budget.js';
 export const responseExpandToolConfig = {
     title: 'Fetch the omitted part of a truncated response',
     description: 'Return the content a previous tool response omitted. When a result exceeds its response budget it comes back with a `__truncation` block containing a `handle` and the list of cut paths; pass that handle here to read the omitted remainder. Call with `handle` alone to list what is available, then with `path` (e.g. "description" or "ticketBundle.primer.markdown", or "$text" for the human-readable block) to read it, following `nextCursor` while it is not null. Handles live 15 minutes in the MCP server process - if one has expired, re-run the original tool. Read-only; returns nothing the original call did not already return.',
@@ -28,9 +28,9 @@ function describeOmitted(entries) {
         : `- ${e.path} (array, ${e.omittedItems ?? 0} of ${(e.keptItems ?? 0) + (e.omittedItems ?? 0)} items omitted)`)
         .join('\n');
 }
-export function makeResponseExpandHandler() {
+export function makeResponseExpandHandler(owner = PROCESS_OWNER) {
     return async (input) => {
-        const stored = readPayload(input.handle);
+        const stored = readPayload(input.handle, Date.now(), owner);
         if (!stored)
             return expired(input.handle);
         const omitted = stored.omitted ?? [];

package/dist/tools/session-start.js

@@ -11,7 +11,7 @@
 import { z } from 'zod';
 import { resolveTicketByKey, applyAgentProfile, mcpInstanceToken } from './shared.js';
 import { AgentSessionScopeSchema } from './agent-session-scope.js';
-import { PROTECT_TEXT_META, storePayload } from '../response-budget.js';
+import { PROCESS_OWNER, PROTECT_TEXT_META, storePayload } from '../response-budget.js';
 import { loadRequiredRules } from '../required-rules.js';
 import { GIT_HEALTH_REASON_TEXT } from './git-health-reasons.js';
 import { channelStartLines } from '../inbox-channel.js';
@@ -135,7 +135,7 @@ async function buildTicketBundle(client, ticketKey) {
 }
 /** ORB-2225 - the Knowledge block stays small; the rest is one expand away. */
 export const KNOWLEDGE_BLOCK_CHARS = 1500;
-export function knowledgeLines(text) {
+export function knowledgeLines(text, owner = PROCESS_OWNER) {
     if (text.length <= KNOWLEDGE_BLOCK_CHARS)
         return { lines: text.split('\n') };
     const cut = text.slice(0, KNOWLEDGE_BLOCK_CHARS);
@@ -143,7 +143,7 @@ export function knowledgeLines(text) {
     const handle = storePayload('orboto_session_start', {
         structuredContent: { knowledge: text }, text,
         omitted: [{ path: 'knowledge', kind: 'string', omittedChars: text.length - kept.length }],
-    });
+    }, Date.now(), owner);
     return {
         handle,
         lines: [...kept.split('\n'), `(Knowledge block cut at ${kept.length} of ${text.length} characters: orboto_response_expand { handle: "${handle}", path: "knowledge" }, or GET /knowledge.)`],
@@ -270,7 +270,7 @@ export function makeSessionStartHandler(client, opts = {}) {
                 structuredContent: { rules: rules.instructions ?? '' },
                 text: rules.instructions ?? '',
                 omitted: [{ path: 'rules', kind: 'string', omittedChars: rulesText.length }],
-            });
+            }, Date.now(), client);
             lines.push(`${rulesIndex.length} rule(s) bind you (${rulesChars} characters, hash ${rules.rulesHash}). Titles only - the full text is NOT in this response.`, `${HOW_TO_READ_RULES} Read any rule below whose title touches what you are about to do BEFORE you do it. (orboto_response_expand { handle: "${rulesHandle}", path: "rules" } serves the same text from this process for 15 minutes.)`, ...rulesIndex.map((title, i) => `${i + 1}. ${title}`));
         }
         else {
@@ -295,7 +295,7 @@ export function makeSessionStartHandler(client, opts = {}) {
         }
         lines.push('', '## Timer');
         lines.push(timer?.ticketId ? `Running on ${timer.ticketKey ?? timer.ticketId} since ${timer.startedAt ?? 'earlier'}.` : 'No timer running.');
-        const knowledgeBlock = knowledge?.text ? knowledgeLines(knowledge.text) : null;
+        const knowledgeBlock = knowledge?.text ? knowledgeLines(knowledge.text, client) : null;
         if (knowledgeBlock)
             lines.push('', ...knowledgeBlock.lines);
         lines.push('', '## This session');

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

@@ -453,12 +453,12 @@ describe('ORB-1818 - rules index instead of the full rule text', () => {
         stubDigest(rulesFull);
         const res = await makeSessionStartHandler(client)();
         const { rulesHandle } = res.structuredContent;
-        const expand = await makeResponseExpandHandler()({ handle: rulesHandle, path: 'rules' });
+        const expand = await makeResponseExpandHandler(client)({ handle: rulesHandle, path: 'rules' });
         const chunks = [];
         let cursor = 0;
         let guard = 0;
         while (cursor !== null && guard++ < 20) {
-            const page = await makeResponseExpandHandler()({ handle: rulesHandle, path: 'rules', cursor });
+            const page = await makeResponseExpandHandler(client)({ handle: rulesHandle, path: 'rules', cursor });
             const s = page.structuredContent;
             chunks.push(s.chunk);
             cursor = s.nextCursor;

package/dist/tools/ticket-writes.js

@@ -719,7 +719,7 @@ export function makeRemoveTicketDependencyHandler(client) {
 }
 export const listTicketDependenciesToolConfig = {
     title: 'List a ticket\'s dependencies',
-    description: 'Show both directions of a ticket\'s dependency graph: `blockedBy` (must finish first) and `blocks` (waiting on this one). ORB-1614: an edge to a ticket in another project you cannot read comes back as an opaque "external dependency" entry (no title/key/status - just whether it is still open).',
+    description: 'Show both directions of a ticket\'s dependency graph: `blockedBy` (must finish first) and `blocks` (waiting on this one). ORB-1614: an edge to a ticket you cannot read comes back as an opaque stub (no title/key/status - just whether it is still open); `external` marks another project.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
     }).shape,

package/dist/with-metrics.js

@@ -61,7 +61,7 @@ export function withMetrics(client, toolName, clientHint, handler, nudge) {
         const label = metricsToolName(toolName, args);
         try {
             const handlerResult = await handler(args, extra);
-            const budgeted = applyResponseBudget(toolName, handlerResult);
+            const budgeted = applyResponseBudget(toolName, handlerResult, process.env, client);
             const result = budgeted.result;
             const inner = label === toolName ? undefined : envelopeStatus(handlerResult.structuredContent);
             const isError = result.isError === true || (inner !== undefined && inner >= 400);

package/package.json

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