@orboto/mcp 0.212.6 → 0.213.0

package/dist/project-scope.js

@@ -1,9 +1,15 @@
 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';
+/** ORB-2448 - must stay equal to SessionRoleEnv in cli/internal/cmd/claude_control_session.go (drift test). */
+export const SESSION_ROLE_ENV = 'ORBOTO_SESSION_ROLE';
+/** ORB-2448 - must stay equal to ControlRoleDefault in the CLI and AGENT_CONTROL_ROLES in shared-schema. */
+export const CONTROL_ROLE = 'coordinator';
 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) {
+/** The control session the remembered role names (ORB-2448), else the worker scope on the project the environment names, or null. */
+export function envProjectScope(raw = process.env.ORBOTO_PROJECT_KEY, role = process.env.ORBOTO_SESSION_ROLE) {
+    if (role?.trim().toLowerCase() === CONTROL_ROLE)
+        return { role: CONTROL_ROLE };
     const key = raw?.trim();
     if (!key || !PROJECT_KEY.test(key))
         return null;
@@ -14,8 +20,8 @@ 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);
+export async function declareEnvProjectScope(client, instanceToken, raw = process.env.ORBOTO_PROJECT_KEY, role = process.env.ORBOTO_SESSION_ROLE) {
+    const scope = envProjectScope(raw, role);
     if (!scope)
         return null;
     const current = await client.get('/v1/agent/session', { instanceToken }).catch(() => null);

package/dist/project-scope.test.js

@@ -1,7 +1,7 @@
 /** 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 { CONTROL_ROLE, declareEnvProjectScope, envProjectScope, PROJECT_KEY_ENV, SESSION_ROLE_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';
@@ -84,3 +84,47 @@ describe('ORB-2224 - ORBOTO_PROJECT_KEY', () => {
         expect(rememberedScope('mcp-scope1')).toEqual({ role: 'worker', projectKeys: ['ACME'] });
     });
 });
+describe('ORB-2448 - ORBOTO_SESSION_ROLE', () => {
+    it('names the variable and the role the CLI and shared-schema use', () => {
+        expect(read('cli/internal/cmd/claude_control_session.go')).toContain(`const SessionRoleEnv = "${SESSION_ROLE_ENV}"`);
+        expect(read('cli/internal/cmd/claude_control_session.go')).toContain(`const ControlRoleDefault = "${CONTROL_ROLE}"`);
+        expect(read('packages/shared-schema/src/agent-session-scope.ts')).toContain(`AGENT_CONTROL_ROLES: readonly AgentSessionRole[] = ['${CONTROL_ROLE}']`);
+        expect(read('apps/mcp/src/project-scope.ts')).toContain(`process.env.${SESSION_ROLE_ENV}`);
+        expect(read('docs/env.md')).toContain(`| \`${SESSION_ROLE_ENV}\` | mcp |`);
+    });
+    it('declares a control session without a project ahead of the project key; any other role is ignored', async () => {
+        expect(envProjectScope('ACME', ' Coordinator ')).toEqual({ role: 'coordinator' });
+        expect(envProjectScope(undefined, 'coordinator')).toEqual({ role: 'coordinator' });
+        expect(envProjectScope('ACME', 'lead')).toEqual({ role: 'worker', projectKeys: ['ACME'] });
+        expect(envProjectScope(undefined, 'lead')).toBeNull();
+        const client = fakeClient({ sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: null });
+        await declareEnvProjectScope(client, 'agent-control', undefined, 'coordinator');
+        expect(client.calls[1]).toEqual({ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'coordinator' } }, instanceToken: 'agent-control' });
+        expect(rememberedScope('agent-control')).toEqual({ role: 'coordinator' });
+    });
+    it('orboto_session_start without a scope declares the control session the environment names', async () => {
+        vi.stubEnv(SESSION_ROLE_ENV, 'coordinator');
+        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' });
+        await makeSessionStartHandler(client)({}, { sessionId: 'control1' });
+        expect(beats).toEqual([{}, { scope: { role: 'coordinator' } }]);
+        expect(rememberedScope('mcp-control1')).toEqual({ role: 'coordinator' });
+    });
+});

package/package.json

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