@evo-dev/core 0.0.1-alpha → 0.0.1-alpha.10

package/src/team/mcp.ts

@@ -0,0 +1,405 @@
+import { createInterface } from "node:readline";
+import type { Readable, Writable } from "node:stream";
+import { TeamMessageBroker, type TeamMessageBrokerOptions, type TeamMessageType } from "./index.ts";
+
+export interface TeamsMcpServerOptions extends TeamMessageBrokerOptions {
+  defaultRunId?: string;
+  defaultFromRoleId?: string;
+  now?: Date;
+}
+
+export type JsonRpcId = string | number;
+
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: JsonRpcId | null;
+  result?: Record<string, unknown>;
+  error?: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}
+
+export interface McpToolDefinition {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+}
+
+const PROTOCOL_VERSION = "2025-11-25";
+const SUPPORTED_PROTOCOL_VERSIONS = new Set([PROTOCOL_VERSION, "2025-06-18"]);
+const MESSAGE_TYPES = new Set<TeamMessageType>(["request", "result", "issue", "notice"]);
+
+export function getTeamsMcpTools(): McpToolDefinition[] {
+  return [
+    {
+      name: "list_agents",
+      title: "List EvoDev Team Agents",
+      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,
+        properties: {
+          runId: {
+            type: "string",
+            description: "Optional EvoDev team run id. Defaults to the latest run.",
+          },
+        },
+      },
+      outputSchema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          agents: { type: "array" },
+        },
+        required: ["agents"],
+      },
+    },
+    {
+      name: "send_message",
+      title: "Send EvoDev Team Message",
+      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,
+        properties: {
+          runId: {
+            type: "string",
+            description: "Optional EvoDev team run id. Defaults to the latest run.",
+          },
+          toRoleId: {
+            type: "string",
+            description: "Target role id.",
+          },
+          message: {
+            type: "string",
+            description: "Message body to deliver.",
+          },
+          type: {
+            type: "string",
+            enum: ["request", "result", "issue", "notice"],
+            description: "Message type.",
+          },
+          fromRoleId: {
+            type: "string",
+            description: "Optional sender role id for audit context.",
+          },
+        },
+        required: ["toRoleId", "message"],
+      },
+      outputSchema: {
+        type: "object",
+        additionalProperties: true,
+        properties: {
+          ok: { type: "boolean" },
+          messageId: { type: "string" },
+          delivery: { type: "string", enum: ["queued"] },
+          queuedFor: { type: "string" },
+          cc: { type: "array" },
+        },
+        required: ["ok"],
+      },
+    },
+    {
+      name: "spawn_role",
+      title: "Spawn 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,
+        properties: {
+          runId: {
+            type: "string",
+            description: "Optional EvoDev team run id. Defaults to the current team run.",
+          },
+          roleId: {
+            type: "string",
+            description: "Role id to create or reuse.",
+          },
+          reason: {
+            type: "string",
+            description: "Reason for lifecycle change.",
+          },
+          fromRoleId: {
+            type: "string",
+            description: "Optional sender role id for audit context.",
+          },
+        },
+        required: ["roleId"],
+      },
+      outputSchema: {
+        type: "object",
+        additionalProperties: true,
+        properties: {
+          ok: { type: "boolean" },
+          created: { type: "boolean" },
+          agent: { type: "object" },
+          error: { type: "string" },
+          message: { type: "string" },
+        },
+        required: ["ok"],
+      },
+    },
+    {
+      name: "stop_role",
+      title: "Stop EvoDev Role Agent",
+      description: "Stop one EvoDev role agent.",
+      inputSchema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          runId: {
+            type: "string",
+            description: "Optional EvoDev team run id. Defaults to the current team run.",
+          },
+          roleId: {
+            type: "string",
+            description: "Role id to stop.",
+          },
+          reason: {
+            type: "string",
+            description: "Reason for lifecycle change.",
+          },
+          fromRoleId: {
+            type: "string",
+            description: "Optional sender role id for audit context.",
+          },
+        },
+        required: ["roleId"],
+      },
+      outputSchema: {
+        type: "object",
+        additionalProperties: true,
+        properties: {
+          ok: { type: "boolean" },
+          stopped: { type: "boolean" },
+          agent: { type: "object" },
+          error: { type: "string" },
+          message: { type: "string" },
+        },
+        required: ["ok"],
+      },
+    },
+  ];
+}
+
+export async function handleTeamsMcpLine(
+  line: string,
+  options: TeamsMcpServerOptions = {},
+): Promise<JsonRpcResponse | null> {
+  try {
+    return await handleTeamsMcpMessage(JSON.parse(line), options);
+  } catch (error) {
+    return jsonRpcError(null, -32700, "Parse error", describeError(error));
+  }
+}
+
+export async function handleTeamsMcpMessage(
+  message: unknown,
+  options: TeamsMcpServerOptions = {},
+): Promise<JsonRpcResponse | null> {
+  const request = parseRequest(message);
+  if (request === null) return null;
+
+  try {
+    if (request.method === "initialize")
+      return jsonRpcResult(request.id, initializeResult(request));
+    if (request.method === "ping") return jsonRpcResult(request.id, {});
+    if (request.method === "tools/list") {
+      return jsonRpcResult(request.id, { tools: getTeamsMcpTools() });
+    }
+    if (request.method === "tools/call") {
+      return jsonRpcResult(request.id, await callTeamsTool(request.params, options));
+    }
+    return jsonRpcError(request.id, -32601, `Method not found: ${request.method}`);
+  } catch (error) {
+    return jsonRpcError(request.id, -32603, describeError(error));
+  }
+}
+
+export async function runTeamsMcpStdioServer(
+  options: TeamsMcpServerOptions & {
+    input?: Readable;
+    output?: Writable;
+  } = {},
+): Promise<void> {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const lines = createInterface({ input, crlfDelay: Number.POSITIVE_INFINITY });
+
+  for await (const line of lines) {
+    if (line.trim() === "") continue;
+    const response = await handleTeamsMcpLine(line, options);
+    if (response !== null) {
+      output.write(`${JSON.stringify(response)}\n`);
+    }
+  }
+}
+
+function initializeResult(request: ParsedRequest): Record<string, unknown> {
+  const params = isRecord(request.params) ? request.params : {};
+  const requestedVersion =
+    typeof params.protocolVersion === "string" ? params.protocolVersion : PROTOCOL_VERSION;
+  const protocolVersion = SUPPORTED_PROTOCOL_VERSIONS.has(requestedVersion)
+    ? requestedVersion
+    : PROTOCOL_VERSION;
+  return {
+    protocolVersion,
+    capabilities: {
+      tools: {
+        listChanged: false,
+      },
+    },
+    serverInfo: {
+      name: "evodev-teams",
+      version: "0.0.1-alpha",
+    },
+    instructions:
+      "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.",
+  };
+}
+
+async function callTeamsTool(
+  params: unknown,
+  options: TeamsMcpServerOptions,
+): Promise<Record<string, unknown>> {
+  const input = expectRecord(params, "tools/call params");
+  const name = expectString(input.name, "tools/call params.name");
+  const args = input.arguments === undefined ? {} : expectRecord(input.arguments, "arguments");
+  const broker = new TeamMessageBroker(options);
+
+  if (name === "list_agents") {
+    const agents = await broker.listAgents({
+      runId: optionalString(args.runId) ?? options.defaultRunId,
+    });
+    return toolResult({ agents });
+  }
+
+  if (name === "send_message") {
+    const toRoleId = expectString(args.toRoleId, "arguments.toRoleId");
+    const message = expectString(args.message, "arguments.message");
+    const type = parseMessageType(args.type);
+    const fromRoleId = optionalString(args.fromRoleId) ?? options.defaultFromRoleId;
+    const result = await broker.send({
+      runId: optionalString(args.runId) ?? options.defaultRunId,
+      fromRoleId,
+      toRoleId,
+      message,
+      type,
+      now: options.now,
+    });
+    return result.ok ? toolResult({ ...result }) : toolResult({ ...result }, true);
+  }
+
+  if (name === "spawn_role") {
+    const roleId = expectString(args.roleId, "arguments.roleId");
+    const fromRoleId = optionalString(args.fromRoleId) ?? options.defaultFromRoleId;
+    const result = await broker.spawnRole({
+      runId: optionalString(args.runId) ?? options.defaultRunId,
+      fromRoleId,
+      roleId,
+      reason: optionalString(args.reason),
+      now: options.now,
+    });
+    return result.ok ? toolResult({ ...result }) : toolResult({ ...result }, true);
+  }
+
+  if (name === "stop_role") {
+    const roleId = expectString(args.roleId, "arguments.roleId");
+    const fromRoleId = optionalString(args.fromRoleId) ?? options.defaultFromRoleId;
+    const result = await broker.stopRole({
+      runId: optionalString(args.runId) ?? options.defaultRunId,
+      fromRoleId,
+      roleId,
+      reason: optionalString(args.reason),
+      now: options.now,
+    });
+    return result.ok ? toolResult({ ...result }) : toolResult({ ...result }, true);
+  }
+
+  throw new Error(`Unknown Teams MCP tool: ${name}`);
+}
+
+function toolResult(
+  structuredContent: Record<string, unknown>,
+  isError = false,
+): Record<string, unknown> {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(structuredContent, null, 2),
+      },
+    ],
+    structuredContent,
+    isError,
+  };
+}
+
+interface ParsedRequest {
+  id: JsonRpcId;
+  method: string;
+  params?: unknown;
+}
+
+function parseRequest(message: unknown): ParsedRequest | null {
+  if (!isRecord(message)) throw new Error("Invalid JSON-RPC message; expected object.");
+  if (message.jsonrpc !== "2.0") throw new Error("Invalid JSON-RPC version.");
+  if (message.id === undefined) return null;
+  if (typeof message.id !== "string" && typeof message.id !== "number") {
+    throw new Error("Invalid JSON-RPC id.");
+  }
+  const method = expectString(message.method, "method");
+  return { id: message.id, method, params: message.params };
+}
+
+function parseMessageType(value: unknown): TeamMessageType | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === "string" && MESSAGE_TYPES.has(value as TeamMessageType)) {
+    return value as TeamMessageType;
+  }
+  throw new Error("arguments.type must be request, result, issue, or notice.");
+}
+
+function jsonRpcResult(id: JsonRpcId, result: Record<string, unknown>): JsonRpcResponse {
+  return { jsonrpc: "2.0", id, result };
+}
+
+function jsonRpcError(
+  id: JsonRpcId | null,
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcResponse {
+  return { jsonrpc: "2.0", id, error: { code, message, data } };
+}
+
+function expectRecord(value: unknown, path: string): Record<string, unknown> {
+  if (!isRecord(value)) throw new Error(`Invalid ${path}; expected object.`);
+  return value;
+}
+
+function expectString(value: unknown, path: string): string {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`Invalid ${path}; expected non-empty string.`);
+  }
+  return value;
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

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.`;
+}

package/src/utils/errors.ts

@@ -0,0 +1,13 @@
+export function isNotFoundError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    (("code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") ||
+      error.message.includes("ENOENT"))
+  );
+}
+
+export function isFileExistsError(error: unknown): boolean {
+  return (
+    error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "EEXIST"
+  );
+}

package/src/utils/fs.ts

@@ -0,0 +1,40 @@
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { isNotFoundError } from "./errors.ts";
+
+export async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (isNotFoundError(error)) return false;
+    throw error;
+  }
+}
+
+export async function readJsonFile<T>(path: string, parse: (value: unknown) => T): Promise<T> {
+  return parse(JSON.parse(await readFile(path, "utf8")) as unknown);
+}
+
+export async function readJsonFiles<T>(dir: string, parse: (value: unknown) => T): Promise<T[]> {
+  if (!(await pathExists(dir))) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  const values: T[] = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    values.push(await readJsonFile(join(dir, entry.name), parse));
+  }
+  return values;
+}
+
+export async function writeJsonFile(
+  path: string,
+  value: unknown,
+  options: { overwrite?: boolean } = {},
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, {
+    encoding: "utf8",
+    flag: options.overwrite === false ? "wx" : "w",
+  });
+}

package/src/utils/hash.ts

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+
+export function sha256Hex(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function sha256Short(value: string, length = 16): string {
+  return sha256Hex(value).slice(0, length);
+}

package/src/utils/ids.ts

@@ -0,0 +1,12 @@
+import { sha256Short } from "./hash.ts";
+
+export function createStableId(prefix: string, parts: string[]): string {
+  return `${prefix}-${sha256Short(parts.join("\0"))}`;
+}
+
+export function sanitizeStorageId(value: string, fallbackPrefix: string): string {
+  const sanitized = value.replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 120);
+  return sanitized === "" || sanitized === "." || sanitized === ".."
+    ? `${fallbackPrefix}-local`
+    : sanitized;
+}

package/src/utils/index.ts

@@ -0,0 +1,7 @@
+export * from "./errors.ts";
+export * from "./fs.ts";
+export * from "./hash.ts";
+export * from "./ids.ts";
+export * from "./parsing.ts";
+export * from "./text.ts";
+export * from "./time.ts";

package/src/utils/parsing.ts

@@ -0,0 +1,11 @@
+export function optionalString(value: unknown): string | null {
+  return typeof value === "string" && value.trim() !== "" ? value : null;
+}
+
+export function optionalBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+export function positiveInteger(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
+}

package/src/utils/text.ts

@@ -0,0 +1,18 @@
+export function sanitizeSummary(value: string): string {
+  const trimmed = value.replace(/\s+/g, " ").trim();
+  return trimmed.length === 0 ? "Session memory event observed." : trimmed.slice(0, 600);
+}
+
+export function truncateUtf8Tail(
+  value: string,
+  maxBytes: number,
+): { content: string; truncated: boolean } {
+  if (Buffer.byteLength(value, "utf8") <= maxBytes) {
+    return { content: value, truncated: false };
+  }
+  let content = value.slice(Math.max(0, value.length - maxBytes));
+  while (Buffer.byteLength(content, "utf8") > maxBytes && content.length > 0) {
+    content = content.slice(1);
+  }
+  return { content, truncated: true };
+}

package/src/utils/time.ts

@@ -0,0 +1,5 @@
+export function normalizeTimestamp(value?: string | Date): string {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === "string" && value.trim() !== "") return new Date(value).toISOString();
+  return new Date().toISOString();
+}