@orboto/mcp 0.212.6 → 0.213.1

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/dist/response-budget.js

@@ -239,7 +239,7 @@ export const TruncationBlockSchema = z.object({
  */
 export const TruncationBlockAdvertisedSchema = z.object({ handle: z.string() })
     .passthrough()
-    .describe('Response was cut; pass `handle` to orboto_response_expand.');
+    .describe('Response cut; pass `handle` to orboto_response_expand.');
 function stringMarker(omitted, handle, path) {
     return `... [truncated ${omitted} chars - full value: orboto_response_expand handle="${handle}" path="${path}"]`;
 }

package/dist/tools/agent-coordination.js

@@ -10,7 +10,7 @@ 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. `scope` { projectKeys, ticketKeys, role } declares this session\'s responsibility (ORB-2136); an empty object clears it.',
+    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. `startedBy`: starter session id, same account.',
     inputSchema: z.object({
         sessionToken: z.string().nullable().optional(),
         scope: AgentSessionScopeSchema.optional(),
@@ -23,11 +23,13 @@ export const agentHeartbeatToolConfig = {
             host: z.string().optional(),
             user_agent: z.string().optional(),
         }).optional(),
+        startedBy: z.string().uuid().optional(),
     }).shape,
     outputSchema: z.object({
         sessionToken: z.string(),
         sessionId: z.string().uuid(),
         scope: AgentSessionScopeSchema.nullable(),
+        startedBy: z.string().uuid().nullable().optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };
@@ -37,7 +39,7 @@ export function makeAgentHeartbeatHandler(client) {
         const scope = res.scope ? ` scope=${JSON.stringify(res.scope)}` : '';
         return {
             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 },
+            structuredContent: { sessionToken: res.sessionToken, sessionId: res.sessionId, scope: res.scope ?? null, ...(res.startedBy !== undefined ? { startedBy: res.startedBy } : {}) },
         };
     };
 }

package/dist/tools/agent-coordination.test.js

@@ -266,6 +266,17 @@ describe('ORB-2136 - session addressing', () => {
         expect(seen[0].headers['x-orboto-agent-session']).toBe('mcp-abc123');
         expect(result.structuredContent).toMatchObject({ scope: { role: 'integrator', projectKeys: ['ORB'] } });
     });
+    it('agent_heartbeat names the starter and answers the recorded one (ORB-2449)', async () => {
+        const starter = '5a1c0d2e-7b3f-4c11-9e2a-0c0ffee00001';
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            seen.push(JSON.parse(init?.body ?? '{}'));
+            return { ok: true, status: 200, statusText: 'OK', json: async () => ({ sessionToken: 'mcp-abc123', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: { role: 'worker' }, startedBy: starter }), text: async () => '' };
+        });
+        const result = await makeAgentHeartbeatHandler(client)({ scope: { role: 'worker' }, startedBy: starter }, { sessionId: 'abc123' });
+        expect(seen[0]).toMatchObject({ startedBy: starter });
+        expect(result.structuredContent).toMatchObject({ startedBy: starter });
+    });
 });
 describe('orboto_agent_notify role addresses (ORB-2264)', () => {
     it('sends `to` as written, lists every recipient and needs no targetEmail', async () => {

package/package.json

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