@evo-dev/core 0.0.1-alpha.1 → 0.0.1-alpha.2

package/src/team/mcp.ts

@@ -38,7 +38,8 @@ export function getTeamsMcpTools(): McpToolDefinition[] {
     {
       name: "list_agents",
       title: "List EvoDev Team Agents",
-      description: "List role agents in the current EvoDev team run.",
+      description:
+        "List role agents in the current EvoDev team run for one-time roster discovery. Do not use this as a progress polling loop.",
       inputSchema: {
         type: "object",
         additionalProperties: false,
@@ -61,7 +62,8 @@ export function getTeamsMcpTools(): McpToolDefinition[] {
     {
       name: "send_message",
       title: "Send EvoDev Team Message",
-      description: "Send a structured message to another EvoDev role agent.",
+      description:
+        "Queue a structured message to another EvoDev role agent. Delivery happens through hook safe points; callers should not wait or poll for immediate progress.",
       inputSchema: {
         type: "object",
         additionalProperties: false,
@@ -96,7 +98,8 @@ export function getTeamsMcpTools(): McpToolDefinition[] {
         properties: {
           ok: { type: "boolean" },
           messageId: { type: "string" },
-          deliveredTo: { type: "string" },
+          delivery: { type: "string", enum: ["queued"] },
+          queuedFor: { type: "string" },
           cc: { type: "array" },
         },
         required: ["ok"],
@@ -105,7 +108,8 @@ export function getTeamsMcpTools(): McpToolDefinition[] {
     {
       name: "spawn_role",
       title: "Spawn EvoDev Role Agent",
-      description: "Create or reuse one EvoDev role agent.",
+      description:
+        "Create or reuse one EvoDev role agent. For main, spawn needed roles, send their task messages, then finish the current turn unless new input or hook-delivered messages require coordination.",
       inputSchema: {
         type: "object",
         additionalProperties: false,
@@ -257,7 +261,7 @@ function initializeResult(request: ParsedRequest): Record<string, unknown> {
       version: "0.0.1-alpha",
     },
     instructions:
-      "Use list_agents to discover EvoDev role agents, spawn_role to create or reuse role agents in the current EvoDev team run, send_message to communicate through the EvoDev broker, and stop_role to stop roles. Role lifecycle is tracked by EvoDev Teams MCP/CLI (`evodev team ...`), not direct tmux orchestration.",
+      "Use list_agents only for one-time roster discovery, spawn_role to create or reuse role agents in the current EvoDev team run, send_message to queue brokered role messages, and stop_role to stop roles. send_message does not paste into live prompts; pending messages surface through hook safe points. Main should delegate runnable role tasks, then finish the current turn instead of sleeping, waiting, or polling list_agents/status for progress. Role lifecycle is tracked by EvoDev Teams MCP/CLI (`evodev team ...`), not direct tmux orchestration.",
   };
 }
 

package/src/team/prompts.ts

@@ -0,0 +1,141 @@
+export interface TeamStartupPromptRole {
+  roleId: string;
+  roleName: string;
+  runtime: string;
+  model: string | null;
+  thinkingLevel: string | null;
+  prompt: string;
+  permissions: {
+    writeMode: string;
+  };
+  teamPolicy: {
+    recordTranscript: boolean;
+  };
+  nativeAgent: {
+    target: string;
+    agentName: string;
+    scope: string;
+  } | null;
+}
+
+export interface TeamStartupPromptRosterAgent {
+  roleId: string;
+  status: string;
+  roleName: string;
+}
+
+export interface RenderTeamRoleStartupPromptInput {
+  runId: string;
+  repoRoot: string;
+  role: TeamStartupPromptRole;
+  roster: TeamStartupPromptRosterAgent[];
+  scopedContext?: string | null;
+}
+
+const TEAM_ROLE_STARTUP_PROMPT_TEMPLATE = [
+  "You are an EvoDev managed role agent.",
+  "Team run: {{runId}}",
+  "Repository: {{repoRoot}}",
+  "Role id: {{roleId}}",
+  "Role name: {{roleName}}",
+  "Runtime: {{runtime}}",
+  "Native Code Agent binding: {{nativeAgentBinding}}",
+  "Model: {{model}}",
+  "Thinking level: {{thinkingLevel}}",
+  "Write mode: {{writeMode}}",
+  "Transcript recording: {{transcriptRecording}}",
+  "",
+  "Current known agents:",
+  "{{roster}}",
+  "",
+  "EvoDev team runtime control contract:",
+  "This run is already inside the EvoDev-managed team runtime.",
+  "For EvoDev role-agent lifecycle, use the current EvoDev run control plane.",
+  "Unprefixed user requests such as 'start the team', 'execute team', 'create agents', or 'spawn roles' mean: use the current EvoDev run control plane.",
+  "Do not answer those requests with only a role plan when a role agent should be created.",
+  "",
+  "Use Teams MCP as the primary control plane:",
+  "- list_agents: discover current EvoDev role agents.",
+  "- spawn_role: create or reuse exactly one EvoDev role agent.",
+  "- send_message: communicate through the EvoDev broker.",
+  "- stop_role: stop a role agent when allowed.",
+  "If Teams MCP is unavailable, fall back to the EvoDev CLI from this repository:",
+  "- evodev team spawn --role <roleId>",
+  "- evodev team send --to <roleId> --message <text>",
+  "- evodev team status",
+  "Teams MCP defaults are inherited from the environment:",
+  "EVODEV_TEAM_RUN_ID={{runId}}",
+  "EVODEV_TEAM_ROLE_ID={{roleId}}",
+  "When calling Teams MCP tools, let the MCP server-bound environment identify this run and role.",
+  "Do not operate tmux directly for role lifecycle; let EvoDev create and track panes.",
+  "Any server-bound role may request role lifecycle changes; EvoDev records and tracks panes but does not use role policy to stop execution.",
+  "{{roleGuidance}}",
+  "{{nativeAgentInstruction}}",
+  "Team messages are durably queued and delivered at hook safe points, not pasted into a live prompt. cc values are audit context; they are not an instruction for main to immediately forward or act.",
+  "{{scopedContext}}",
+  "",
+  "{{rolePrompt}}",
+].join("\n");
+
+const MAIN_ROLE_GUIDANCE = [
+  "As main, you are the planner and delegator for complex work, not a standby worker.",
+  "On each user prompt or hook-delivered inbox message, decide whether to answer directly, ask for clarification, or use team execution.",
+  "Use team execution only when role separation improves correctness, coverage, safety, or latency.",
+  "When team execution is needed, create an upfront task plan with required role ids, role-specific assignments, dependencies, and runnable batches.",
+  "Spawn or reuse all roles needed for the first runnable batch and send each role a self-contained task message.",
+  "After all currently runnable tasks are delegated, finish your current turn immediately; do not call sleep, wait idly, poll list_agents/status, or keep the turn alive to watch progress.",
+  "Use list_agents only for one-time roster discovery when the current roster is genuinely unknown, never as a progress check.",
+  "Resume coordination only when the user sends new input or a role message is delivered by hooks; then decide whether to adjust tasks, send supplemental instructions, spawn dependent roles, synthesize completed results, or ask the user.",
+  "While delegated role work is pending, do not perform concrete implementation, testing, package research, or review work yourself.",
+].join(" ");
+
+const NON_MAIN_ROLE_GUIDANCE =
+  "As a non-main role, send results or issues to the role that needs to act next. Coordinate with main only when the decision affects scope, assignment, user-facing synthesis, or unresolved tradeoffs.";
+
+const PLACEHOLDER_PATTERN = /\{\{([A-Za-z][A-Za-z0-9]*)\}\}/g;
+
+export function renderTeamRoleStartupPrompt(input: RenderTeamRoleStartupPromptInput): string {
+  const values: Record<string, string> = {
+    runId: input.runId,
+    repoRoot: input.repoRoot,
+    roleId: input.role.roleId,
+    roleName: input.role.roleName,
+    runtime: input.role.runtime,
+    nativeAgentBinding: formatNativeAgentBinding(input.role),
+    model: input.role.model ?? "default",
+    thinkingLevel: input.role.thinkingLevel ?? "default",
+    writeMode: input.role.permissions.writeMode,
+    transcriptRecording: input.role.teamPolicy.recordTranscript ? "enabled" : "disabled",
+    roster: formatStartupPromptRoster(input.roster),
+    roleGuidance: input.role.roleId === "main" ? MAIN_ROLE_GUIDANCE : NON_MAIN_ROLE_GUIDANCE,
+    nativeAgentInstruction: formatNativeAgentInstruction(input.role),
+    scopedContext: input.scopedContext ?? "",
+    rolePrompt: input.role.prompt,
+  };
+
+  return renderPromptTemplate(TEAM_ROLE_STARTUP_PROMPT_TEMPLATE, values);
+}
+
+function renderPromptTemplate(template: string, values: Record<string, string>): string {
+  return template.replace(PLACEHOLDER_PATTERN, (_placeholder, key: string) => {
+    if (!Object.hasOwn(values, key)) {
+      throw new Error(`Missing team startup prompt template value: ${key}`);
+    }
+    return values[key];
+  });
+}
+
+function formatStartupPromptRoster(roster: TeamStartupPromptRosterAgent[]): string {
+  if (roster.length === 0) return "- main: starting";
+  return roster.map((agent) => `- ${agent.roleId}: ${agent.status} (${agent.roleName})`).join("\n");
+}
+
+function formatNativeAgentBinding(role: TeamStartupPromptRole): string {
+  if (role.nativeAgent === null) return "none";
+  return `${role.nativeAgent.target}/${role.nativeAgent.agentName} (${role.nativeAgent.scope})`;
+}
+
+function formatNativeAgentInstruction(role: TeamStartupPromptRole): string {
+  if (role.nativeAgent === null) return "No native Code Agent agent is bound to this role.";
+  return `Use the bound native Code Agent agent name '${role.nativeAgent.agentName}' as role context when the runtime supports named agents; EvoDev does not load or transform the native agent file.`;
+}