@orboto/mcp 0.206.1 → 0.207.0

package/dist/index.js

@@ -62,6 +62,8 @@ async function main() {
             const { InboxChannel, digestMinutesFromEnv, cliOutdatedNotice, CLI_OUTDATED_NOTICE } = await import('./inbox-channel.js');
             const { mcpProcessInstance } = await import('./tools/shared.js');
             const instanceToken = mcpProcessInstance();
+            const { declareEnvProjectScope } = await import('./project-scope.js');
+            await declareEnvProjectScope(preflightClient, instanceToken);
             const inbox = new InboxChannel({ ...clientConfig, instanceToken, mcp: server, digestMinutes: digestMinutesFromEnv(process.env.ORBOTO_MCP_CHANNEL_DIGEST_MINUTES) });
             inbox.start();
             const outdated = cliOutdatedNotice(process.env.ORBOTO_MCP_CLI_OUTDATED);

package/dist/project-scope.js

@@ -0,0 +1,28 @@
+import { rememberDeclaredScope } from './session-scope-memory.js';
+/** Must stay equal to ProjectKeyEnv in cli/internal/cmd/project_scope.go (drift test). */
+export const PROJECT_KEY_ENV = 'ORBOTO_PROJECT_KEY';
+const PROJECT_KEY = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+/** The worker scope on the project the environment names, or null. */
+export function envProjectScope(raw = process.env.ORBOTO_PROJECT_KEY) {
+    const key = raw?.trim();
+    if (!key || !PROJECT_KEY.test(key))
+        return null;
+    return { role: 'worker', projectKeys: [key.toUpperCase()] };
+}
+/** True when the scope names anything at all. */
+export function scopeDeclared(scope) {
+    return !!scope && (!!scope.role || (scope.projectKeys?.length ?? 0) > 0 || (scope.ticketKeys?.length ?? 0) > 0);
+}
+/** Declares the environment's project on the session row unless the row already carries a scope; answers the row. */
+export async function declareEnvProjectScope(client, instanceToken, raw = process.env.ORBOTO_PROJECT_KEY) {
+    const scope = envProjectScope(raw);
+    if (!scope)
+        return null;
+    const current = await client.get('/v1/agent/session', { instanceToken }).catch(() => null);
+    if (current && scopeDeclared(current.scope))
+        return current;
+    const row = await client.post('/v1/agent/heartbeat', { scope }, { instanceToken }).catch(() => null);
+    if (row && typeof row.sessionId === 'string')
+        rememberDeclaredScope(instanceToken, row.scope ?? scope);
+    return row;
+}

package/dist/project-scope.test.js

@@ -0,0 +1,86 @@
+/** ORB-2224 - the project a session declares from ORBOTO_PROJECT_KEY, and its drift against the CLI that writes it. */
+import { readFileSync } from 'node:fs';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { declareEnvProjectScope, envProjectScope, PROJECT_KEY_ENV, scopeDeclared } from './project-scope.js';
+import { _forgetDeclaredScopes, rememberedScope } from './session-scope-memory.js';
+import { OrbotoClient } from './orboto-client.js';
+import { makeSessionStartHandler } from './tools/session-start.js';
+const read = (relative) => readFileSync(new URL(`../../../${relative}`, import.meta.url), 'utf8');
+function fakeClient(row) {
+    const calls = [];
+    return {
+        calls,
+        get: async (path, opts) => { calls.push({ method: 'GET', path, instanceToken: opts?.instanceToken }); if (row instanceof Error)
+            throw row; return row; },
+        post: async (path, body, opts) => {
+            calls.push({ method: 'POST', path, body, instanceToken: opts?.instanceToken });
+            return { sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: body.scope };
+        },
+    };
+}
+beforeEach(() => { _forgetDeclaredScopes(); });
+afterEach(() => { vi.restoreAllMocks(); vi.unstubAllEnvs(); });
+describe('ORB-2224 - ORBOTO_PROJECT_KEY', () => {
+    it('names the same variable the CLI writes into the entry and hands to the session', () => {
+        const go = read('cli/internal/cmd/project_scope.go');
+        expect(go).toContain(`const ProjectKeyEnv = "${PROJECT_KEY_ENV}"`);
+        expect(read('apps/mcp/src/project-scope.ts')).toContain(`process.env.${PROJECT_KEY_ENV}`);
+        expect(read('docs/env.md')).toContain(`| \`${PROJECT_KEY_ENV}\` | mcp |`);
+    });
+    it('reads a worker scope on the upper-cased key and ignores anything that is no key', () => {
+        expect(envProjectScope(' acme ')).toEqual({ role: 'worker', projectKeys: ['ACME'] });
+        for (const value of [undefined, '', '  ', 'acme widgets', '1ACME', '${ORBOTO_PROJECT_KEY}']) {
+            expect(envProjectScope(value)).toBeNull();
+        }
+        expect(scopeDeclared(null)).toBe(false);
+        expect(scopeDeclared({})).toBe(false);
+        expect(scopeDeclared({ role: 'worker' })).toBe(true);
+    });
+    it('declares the project on a row without a scope and remembers it for the channel reconnect', async () => {
+        const client = fakeClient({ sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: null });
+        await declareEnvProjectScope(client, 'agent-abc', 'ACME');
+        expect(client.calls).toEqual([
+            { method: 'GET', path: '/v1/agent/session', instanceToken: 'agent-abc' },
+            { method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'worker', projectKeys: ['ACME'] } }, instanceToken: 'agent-abc' },
+        ]);
+        expect(rememberedScope('agent-abc')).toEqual({ role: 'worker', projectKeys: ['ACME'] });
+    });
+    it('declares on a token that has no row yet', async () => {
+        const client = fakeClient(new Error('404'));
+        await declareEnvProjectScope(client, 'agent-new', 'ACME');
+        expect(client.calls.map((c) => c.method)).toEqual(['GET', 'POST']);
+    });
+    it('keeps a scope the session already declares and does nothing without the variable', async () => {
+        const kept = fakeClient({ sessionId: 'x', scope: { role: 'integrator', projectKeys: ['ORB'] } });
+        await declareEnvProjectScope(kept, 'agent-kept', 'ACME');
+        expect(kept.calls.map((c) => c.method)).toEqual(['GET']);
+        const none = fakeClient({ sessionId: 'x', scope: null });
+        expect(await declareEnvProjectScope(none, 'agent-none', '')).toBeNull();
+        expect(none.calls).toEqual([]);
+    });
+    it('orboto_session_start without a scope declares the environment project on a row that has none', async () => {
+        vi.stubEnv(PROJECT_KEY_ENV, 'acme');
+        const beats = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            const u = new URL(url.toString());
+            let body = {};
+            if (u.pathname === '/v1/agent/heartbeat') {
+                const sent = init?.body ? JSON.parse(init.body) : {};
+                beats.push(sent);
+                body = { sessionToken: 'x', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: sent.scope ?? null };
+            }
+            else if (u.pathname === '/v1/agent/session') {
+                body = { sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: null };
+            }
+            else if (u.pathname === '/agent-instructions') {
+                body = { instructions: 'rules here', rulesHash: 'fixture' };
+            }
+            return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => '' };
+        });
+        const client = new OrbotoClient({ baseUrl: 'http://api.test', apiKey: 'k' });
+        const res = await makeSessionStartHandler(client)({}, { sessionId: 'scope1' });
+        expect(beats).toEqual([{}, { scope: { role: 'worker', projectKeys: ['ACME'] } }]);
+        expect(res.content[0].text).toContain('projects ACME');
+        expect(rememberedScope('mcp-scope1')).toEqual({ role: 'worker', projectKeys: ['ACME'] });
+    });
+});

package/dist/tools/session-start.js

@@ -16,6 +16,7 @@ import { loadRequiredRules } from '../required-rules.js';
 import { GIT_HEALTH_REASON_TEXT } from './git-health-reasons.js';
 import { channelStartLines } from '../inbox-channel.js';
 import { rememberDeclaredScope } from '../session-scope-memory.js';
+import { declareEnvProjectScope, envProjectScope } from '../project-scope.js';
 import { agentHeadText } from '../agent-head.js';
 export const sessionStartToolConfig = {
     title: 'Load the rules you must follow + re-orient',
@@ -175,11 +176,15 @@ export function makeSessionStartHandler(client, opts = {}) {
                 },
             };
         }
-        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, reconnects: r.reconnects, lastReconnectAt: r.lastReconnectAt } : null))
+        const toRegistration = (r) => (r && typeof r.sessionId === 'string' ? { sessionId: r.sessionId, scope: r.scope ?? null, reconnects: r.reconnects, lastReconnectAt: r.lastReconnectAt } : null);
+        let registration = await client.post('/v1/agent/heartbeat', input.scope !== undefined ? { scope: input.scope } : {}, { instanceToken })
+            .then(toRegistration)
             .catch(() => null);
         if (input.scope !== undefined && registration)
             rememberDeclaredScope(instanceToken, registration.scope);
+        if (input.scope === undefined && registration && !registration.scope && envProjectScope()) {
+            registration = toRegistration(await declareEnvProjectScope(client, instanceToken)) ?? registration;
+        }
         const [me, rules, assigned, timer, inboxRaw] = await Promise.all([
             client.get('/users/me').catch(() => null),
             loadRequiredRules(client, rulesPath, rulesParams.get('knownRulesHash') ?? undefined),

package/package.json

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