From 71fcf88a48f6e6fa4b4cf93481226e13d9604ae3 Mon Sep 17 00:00:00 2001 From: iliya Date: Wed, 18 Mar 2026 09:36:16 +0200 Subject: [PATCH] feat: add process registration protocol text builder - Introduced a new function `buildProcessProtocolText` to generate context-free protocol text for background process registration. - Updated the `protocols` interface to include the new function, promoting code reuse across member and lead prompts. - Integrated the new protocol text into the team provisioning service for improved operational instructions. - Enhanced type definitions to reflect the addition of the new protocol functionality. --- agent-teams-controller/src/controller.js | 3 +++ agent-teams-controller/src/internal/tasks.js | 16 +++++++++++++--- mcp-server/src/agent-teams-controller.d.ts | 7 +++++++ .../services/team/TeamProvisioningService.ts | 5 ++++- src/types/agent-teams-controller.d.ts | 7 +++++++ .../TeamProvisioningServiceLiveMessages.test.ts | 4 ++++ .../team/TeamProvisioningServiceRelay.test.ts | 4 ++++ 7 files changed, 42 insertions(+), 4 deletions(-) diff --git a/agent-teams-controller/src/controller.js b/agent-teams-controller/src/controller.js index ece6bafc..9c4b1a6a 100644 --- a/agent-teams-controller/src/controller.js +++ b/agent-teams-controller/src/controller.js @@ -38,6 +38,9 @@ module.exports = { createController, createControllerContext, agentBlocks, + protocols: { + buildProcessProtocolText: tasks.buildProcessProtocolText, + }, tasks, kanban, review, diff --git a/agent-teams-controller/src/internal/tasks.js b/agent-teams-controller/src/internal/tasks.js index d4eff2ac..ae47db6c 100644 --- a/agent-teams-controller/src/internal/tasks.js +++ b/agent-teams-controller/src/internal/tasks.js @@ -443,8 +443,13 @@ function buildMemberTaskProtocol(teamName) { Failure to follow this protocol means the task board will show incorrect status.`); } -function buildMemberProcessProtocol(teamName) { - return wrapAgentBlock(`BACKGROUND PROCESS REGISTRATION — when you start a background process (dev server, watcher, database, etc.): +/** + * Raw process-registration protocol text (no agent-block wrapping). + * Shared between member briefing and lead provisioning prompt (DRY). + * Context-free — does NOT follow the (context, ...) convention. + */ +function buildProcessProtocolText(teamName) { + return `BACKGROUND PROCESS REGISTRATION — when you start a background process (dev server, watcher, database, etc.): 1. Launch with & to get PID: pnpm dev & 2. Register immediately with MCP tool process_register (--port and --url are optional, use when the process listens on a port): @@ -453,7 +458,11 @@ function buildMemberProcessProtocol(teamName) { { teamName: "${teamName}" } 4. When stopping a process, use MCP tool process_stop: { teamName: "${teamName}", pid: } -If verification in step 3 fails or the process is missing from the list, re-register it.`); +If verification in step 3 fails or the process is missing from the list, re-register it.`; +} + +function buildMemberProcessProtocol(teamName) { + return wrapAgentBlock(buildProcessProtocolText(teamName)); } function buildMemberFormattingProtocol() { @@ -593,6 +602,7 @@ module.exports = { setTaskStatus, softDeleteTask, startTask, + buildProcessProtocolText, memberBriefing, taskBriefing, unlinkTask, diff --git a/mcp-server/src/agent-teams-controller.d.ts b/mcp-server/src/agent-teams-controller.d.ts index 149dc08b..92eb7333 100644 --- a/mcp-server/src/agent-teams-controller.d.ts +++ b/mcp-server/src/agent-teams-controller.d.ts @@ -98,4 +98,11 @@ declare module 'agent-teams-controller' { } export const agentBlocks: AgentBlocksApi; + + /** Context-free protocol text builders, shared across lead and member prompts. */ + export interface ProtocolsApi { + buildProcessProtocolText(teamName: string): string; + } + + export const protocols: ProtocolsApi; } diff --git a/src/main/services/team/TeamProvisioningService.ts b/src/main/services/team/TeamProvisioningService.ts index ed847516..19355880 100644 --- a/src/main/services/team/TeamProvisioningService.ts +++ b/src/main/services/team/TeamProvisioningService.ts @@ -97,7 +97,7 @@ import type { } from '@shared/types'; const logger = createLogger('Service:TeamProvisioning'); -const { createController } = agentTeamsControllerModule; +const { createController, protocols } = agentTeamsControllerModule; const TEAM_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,127}$/; const RUN_TIMEOUT_MS = 300_000; const VERIFY_TIMEOUT_MS = 15_000; @@ -569,6 +569,9 @@ function buildTeamCtlOpsInstructions(teamName: string, leadName: string): string `- Request changes: review_request_changes { teamName: "${teamName}", taskId: "", comment: "" }`, `CRITICAL: Writing "approved" or "LGTM" as a task comment does NOT move the task on the kanban board. You MUST call the review_approve MCP tool. Without the tool call the task stays stuck in the REVIEW column.`, ``, + `Process operations — use MCP tools directly:`, + protocols.buildProcessProtocolText(teamName), + ``, `Attachment storage modes (IMPORTANT):`, `- Default is copy (safe, robust).`, `- Use mode: "link" to try a hardlink (no duplication). It may fall back to copy unless you disable fallback.`, diff --git a/src/types/agent-teams-controller.d.ts b/src/types/agent-teams-controller.d.ts index c5b8a8d9..0f726387 100644 --- a/src/types/agent-teams-controller.d.ts +++ b/src/types/agent-teams-controller.d.ts @@ -86,7 +86,14 @@ declare module 'agent-teams-controller' { crossTeam: ControllerCrossTeamApi; } + /** Context-free protocol text builders, shared across lead and member prompts. */ + export interface ProtocolsApi { + buildProcessProtocolText(teamName: string): string; + } + export function createController(options: ControllerContextOptions): AgentTeamsController; export const agentBlocks: AgentBlocksApi; + + export const protocols: ProtocolsApi; } diff --git a/test/main/services/team/TeamProvisioningServiceLiveMessages.test.ts b/test/main/services/team/TeamProvisioningServiceLiveMessages.test.ts index 0f8b68ac..29ff6f7f 100644 --- a/test/main/services/team/TeamProvisioningServiceLiveMessages.test.ts +++ b/test/main/services/team/TeamProvisioningServiceLiveMessages.test.ts @@ -103,6 +103,10 @@ vi.mock('agent-teams-controller', () => ({ hoisted.sendInboxMessage(teamName, message), }, }), + protocols: { + buildProcessProtocolText: (teamName: string) => + `BACKGROUND PROCESS REGISTRATION (mock for ${teamName})`, + }, })); import type { TeamChangeEvent } from '@shared/types/team'; diff --git a/test/main/services/team/TeamProvisioningServiceRelay.test.ts b/test/main/services/team/TeamProvisioningServiceRelay.test.ts index 355c4e89..4847ccb6 100644 --- a/test/main/services/team/TeamProvisioningServiceRelay.test.ts +++ b/test/main/services/team/TeamProvisioningServiceRelay.test.ts @@ -121,6 +121,10 @@ vi.mock('agent-teams-controller', () => ({ hoisted.sendInboxMessage(teamName, message), }, }), + protocols: { + buildProcessProtocolText: (teamName: string) => + `BACKGROUND PROCESS REGISTRATION (mock for ${teamName})`, + }, })); import { TeamProvisioningService } from '../../../../src/main/services/team/TeamProvisioningService';