macro-agent 0.1.1 → 0.1.3

package/src/mcp/tools/done.ts

@@ -1,338 +0,0 @@
-/**
- * done() MCP Tool
- *
- * Allows agents with `lifecycle.done` capability to signal completion
- * and trigger role-appropriate cleanup.
- *
- * @module mcp/tools/done
- * @see s-32xs Self-Cleaning Workers spec
- */
-
-import { z } from "zod";
-import type { EventStore } from "../../store/event-store.js";
-import type { AgentManager } from "../../agent/agent-manager.js";
-import type { MessageRouter } from "../../router/message-router.js";
-import type { TaskManager } from "../../task/task-manager.js";
-import type { ToolContext } from "../types.js";
-import type { DoneArgs, DoneResult, LifecycleContext } from "../../lifecycle/types.js";
-import { detectCleanupStatus } from "../../lifecycle/cleanup.js";
-import { dispatchDone, type AllHandlerDeps } from "../../lifecycle/handlers/index.js";
-
-// =============================================================================
-// Schema Definition
-// =============================================================================
-
-/**
- * Zod schema for done() tool input
- */
-export const DoneSchema = {
-  status: z
-    .enum(["completed", "failed", "blocked", "deferred"])
-    .describe("Completion status of the agent's work"),
-  summary: z
-    .string()
-    .optional()
-    .describe("Summary of work completed or reason for status"),
-  details: z
-    .record(z.string(), z.unknown())
-    .optional()
-    .describe("Additional structured details"),
-  task_id: z
-    .string()
-    .optional()
-    .describe("Task ID to update (defaults to agent's bound task)"),
-};
-
-// =============================================================================
-// Tool Dependencies
-// =============================================================================
-
-/**
- * Dependencies for the done() tool
- */
-export interface DoneToolDeps {
-  eventStore: EventStore;
-  agentManager: AgentManager;
-  messageRouter: MessageRouter;
-  taskManager: TaskManager;
-  workspaceManager?: {
-    /** Get workspace for an agent */
-    getWorkspace(agentId: string): {
-      integrationBranch?: string;
-      path?: string;
-      streamId?: string;
-    } | null;
-    /** Get merge queue for coordinating worker merges */
-    getMergeQueue?(): AllHandlerDeps["mergeQueue"];
-  };
-  /** Optional RoleRegistry for capability-based done() checks */
-  roleRegistry?: import("../../roles/types.js").RoleRegistry;
-  /** Optional MailService for recording completion turns */
-  mailService?: import("../../mail/mail-service.js").MailService;
-  /** Optional ConversationMap for agent-to-conversation lookup */
-  conversationMap?: import("../../mail/conversation-map.js").ConversationMap;
-  /** Optional integration strategy (from team config) */
-  integrationStrategy?: import("../../workspace/strategies/types.js").IntegrationStrategy;
-  /** Optional task mode from team config */
-  taskMode?: "push" | "pull";
-}
-
-// =============================================================================
-// Capability Check
-// =============================================================================
-
-/**
- * Check if an agent has the lifecycle.done capability.
- *
- * Uses RoleRegistry for capability resolution, supporting both built-in
- * roles and team-defined roles that extend them.
- */
-export function hasLifecycleDoneCapability(
-  eventStore: EventStore,
-  agentId: string,
-  roleRegistry?: import("../../roles/types.js").RoleRegistry
-): { hasCapability: boolean; role: string } {
-  // Get the agent to find their role
-  const agent = eventStore.getAgent(agentId);
-  if (!agent) {
-    return { hasCapability: false, role: "unknown" };
-  }
-
-  const role = agent.role ?? "worker";
-
-  // Use RoleRegistry for capability lookup when available
-  if (roleRegistry) {
-    const hasCapability = roleRegistry.hasCapability(role, "lifecycle.done");
-    return { hasCapability, role };
-  }
-
-  // Fallback: check base role via prefix match against known built-in roles
-  const rolesWithDoneCapability = new Set([
-    "worker",
-    "worker.resolver",
-    "integrator",
-    "monitor",
-  ]);
-
-  const hasCapability =
-    rolesWithDoneCapability.has(role) ||
-    rolesWithDoneCapability.has(role.split(".")[0]);
-
-  return { hasCapability, role };
-}
-
-// =============================================================================
-// Build Lifecycle Context
-// =============================================================================
-
-/**
- * Build the lifecycle context for a done() call
- */
-export function buildLifecycleContext(
-  toolContext: ToolContext,
-  eventStore: EventStore,
-  role: string,
-  workspaceManager?: DoneToolDeps["workspaceManager"]
-): LifecycleContext {
-  const agent = eventStore.getAgent(toolContext.agent_id);
-
-  // Try to get workspace info from workspace manager
-  let integrationBranch: string | undefined;
-  let workspacePath: string | undefined;
-  let streamId: string | undefined;
-  if (workspaceManager) {
-    const workspace = workspaceManager.getWorkspace(toolContext.agent_id);
-    integrationBranch = workspace?.integrationBranch;
-    workspacePath = workspace?.path;
-    streamId = workspace?.streamId;
-  }
-
-  return {
-    agentId: toolContext.agent_id,
-    role,
-    taskId: toolContext.task_id,
-    parentId: agent?.parent ?? undefined,
-    workspacePath: workspacePath ?? toolContext.cwd,
-    branch: undefined, // Will be detected from workspace if needed
-    integrationBranch,
-    streamId,
-  };
-}
-
-// =============================================================================
-// Tool Handler
-// =============================================================================
-
-/**
- * Create the done() tool handler
- */
-export function createDoneHandler(context: ToolContext, deps: DoneToolDeps) {
-  return async (args: {
-    status: "completed" | "failed" | "blocked" | "deferred";
-    summary?: string;
-    details?: Record<string, unknown>;
-    task_id?: string;
-  }): Promise<DoneResult> => {
-    const { eventStore, agentManager, messageRouter, taskManager, workspaceManager, roleRegistry, mailService, conversationMap } = deps;
-
-    // ─────────────────────────────────────────────────────────────────────────
-    // Step 1: Check capability
-    // ─────────────────────────────────────────────────────────────────────────
-
-    const { hasCapability, role } = hasLifecycleDoneCapability(
-      eventStore,
-      context.agent_id,
-      roleRegistry
-    );
-
-    if (!hasCapability) {
-      return {
-        success: false,
-        shouldTerminate: false,
-        status: args.status,
-        cleanupStatus: { ready: false, reason: "Capability check failed" },
-        error: `Agent ${context.agent_id} does not have lifecycle.done capability (role: ${role})`,
-      };
-    }
-
-    // ─────────────────────────────────────────────────────────────────────────
-    // Step 2: Build context and detect cleanup status
-    // ─────────────────────────────────────────────────────────────────────────
-
-    const lifecycleContext = buildLifecycleContext(
-      context,
-      eventStore,
-      role,
-      workspaceManager
-    );
-
-    const cleanupStatus = detectCleanupStatus(lifecycleContext, {
-      messageRouter,
-    });
-
-    // ─────────────────────────────────────────────────────────────────────────
-    // Step 3: Update task status via TaskManager
-    // ─────────────────────────────────────────────────────────────────────────
-
-    const taskId = args.task_id ?? context.task_id;
-    if (taskId) {
-      try {
-        const taskStatus =
-          args.status === "completed"
-            ? "completed"
-            : args.status === "failed"
-              ? "failed"
-              : "in_progress";
-        taskManager.updateStatus(taskId, taskStatus);
-      } catch {
-        // Task may not exist - continue anyway
-      }
-    }
-
-    // ─────────────────────────────────────────────────────────────────────────
-    // Step 4: Emit status via MessageRouter (for compatibility with emit_status)
-    // ─────────────────────────────────────────────────────────────────────────
-
-    try {
-      messageRouter.emitStatus({
-        from: { agent_id: context.agent_id },
-        status_type:
-          args.status === "completed"
-            ? "completed"
-            : args.status === "failed"
-              ? "failed"
-              : "checkpoint",
-        summary: args.summary ?? `Agent done with status: ${args.status}`,
-        details: args.details,
-      });
-    } catch {
-      // Continue even if emit fails
-    }
-
-    // ─────────────────────────────────────────────────────────────────────────
-    // Step 4b: Record completion turn and close conversation (Mail)
-    // ─────────────────────────────────────────────────────────────────────────
-    if (mailService && conversationMap) {
-      try {
-        const convId = conversationMap.getAgentConversation(context.agent_id);
-        if (convId) {
-          // Record completion turn
-          mailService.recordTurn({
-            conversationId: convId,
-            participant: context.agent_id,
-            contentType: "event",
-            content: {
-              event: `agent.${args.status}`,
-              summary: args.summary,
-              details: args.details,
-            },
-          });
-
-          // Close the conversation
-          mailService.closeConversation({
-            conversationId: convId,
-            closedBy: context.agent_id,
-            reason: args.status,
-          });
-        }
-      } catch {
-        // Never fail done() due to mail errors
-      }
-    }
-
-    // ─────────────────────────────────────────────────────────────────────────
-    // Step 5: Dispatch to role-specific handler
-    // ─────────────────────────────────────────────────────────────────────────
-
-    const doneArgs: DoneArgs = {
-      status: args.status,
-      summary: args.summary,
-      details: args.details,
-      taskId,
-    };
-
-    const handlerDeps: AllHandlerDeps = {
-      messageRouter,
-      agentManager,
-      mergeQueue: workspaceManager?.getMergeQueue?.(),
-      getWorkspacePath: workspaceManager
-        ? (agentId: string) => workspaceManager.getWorkspace(agentId)?.path
-        : undefined,
-      integrationStrategy: deps.integrationStrategy,
-      taskMode: deps.taskMode,
-    };
-
-    const handlerResult = await dispatchDone(
-      lifecycleContext,
-      doneArgs,
-      cleanupStatus,
-      handlerDeps
-    );
-
-    // ─────────────────────────────────────────────────────────────────────────
-    // Step 6: Return result
-    // ─────────────────────────────────────────────────────────────────────────
-
-    return {
-      success: true,
-      shouldTerminate: handlerResult.shouldTerminate,
-      status: args.status,
-      cleanupStatus,
-      warnings: handlerResult.warnings,
-    };
-  };
-}
-
-// =============================================================================
-// Tool Registration Helper
-// =============================================================================
-
-/**
- * Tool registration info for use with MCP server
- */
-export const DONE_TOOL_INFO = {
-  name: "done",
-  description:
-    "Signal that the agent has completed its work. Triggers role-appropriate cleanup and termination. Requires lifecycle.done capability.",
-  schema: DoneSchema,
-};

package/src/mcp/tools/inject_context.ts

@@ -1,173 +0,0 @@
-/**
- * inject_context MCP Tool
- *
- * Allows agents to inject context into another agent's session.
- * Used for time-sensitive steering that can't wait for message checking.
- *
- * @module mcp/tools/inject_context
- * @see s-9rld In-Flight Steering spec section 3.1
- */
-
-import { z } from "zod";
-import type { AgentId } from "../../store/types/index.js";
-import type { AgentManager } from "../../agent/agent-manager.js";
-import type { MessageRouter } from "../../router/message-router.js";
-import {
-  injectContext,
-  type InjectionDeps,
-  type InjectionResult,
-} from "../../steering/index.js";
-
-// =============================================================================
-// Schema Definition
-// =============================================================================
-
-/**
- * Zod schema for inject_context tool input
- */
-export const InjectContextSchema = {
-  target_agent_id: z
-    .string()
-    .describe("The agent ID to inject context into"),
-  content: z
-    .string()
-    .describe("The context message to inject"),
-  urgent: z
-    .boolean()
-    .optional()
-    .default(false)
-    .describe("If true, interrupts current work immediately instead of queueing"),
-  reason: z
-    .string()
-    .optional()
-    .describe("Optional reason for the injection (for audit logs)"),
-};
-
-/**
- * Tool info for registration
- */
-export const INJECT_CONTEXT_TOOL_INFO = {
-  name: "inject_context",
-  description: `Inject context into another agent's session. Use this for time-sensitive
-steering that can't wait for the agent to check messages.
-
-The context will appear in the target agent's next turn, or immediately if urgent=true.
-
-Fallback behavior:
-- If injection not supported, falls back to interrupting the agent
-- If that fails, sends a high-priority message instead
-
-Use cases:
-- Priority changes ("Pause feature X, work on Y first")
-- Urgent information ("Build is failing, check your types")
-- Health checks ("Are you stuck? Report status")
-- Context updates ("Worker 2 finished the API, you can use it now")`,
-};
-
-// =============================================================================
-// Tool Dependencies
-// =============================================================================
-
-/**
- * Dependencies for the inject_context tool
- */
-export interface InjectContextToolDeps {
-  agentManager: AgentManager;
-  messageRouter: MessageRouter;
-}
-
-// =============================================================================
-// Tool Handler
-// =============================================================================
-
-/**
- * Input args for the inject_context tool
- */
-export interface InjectContextArgs {
-  target_agent_id: string;
-  content: string;
-  urgent?: boolean;
-  reason?: string;
-}
-
-/**
- * Create the handler for the inject_context tool
- */
-export function createInjectContextHandler(
-  deps: InjectContextToolDeps,
-  callerAgentId: AgentId
-) {
-  // Create injection deps that wrap AgentManager and MessageRouter
-  const injectionDeps: InjectionDeps = {
-    getSession(agentId: AgentId) {
-      const session = deps.agentManager.getSession(agentId);
-      if (!session) return null;
-
-      // Cast to InjectableSession interface
-      return {
-        inject: async (content: string) => session.inject(content),
-        supportsInject: () => session.supportsInject(),
-        checkInjectSupport: async () => {
-          // Try a no-op inject to check support
-          try {
-            const result = await session.inject("");
-            return result.success;
-          } catch {
-            return false;
-          }
-        },
-        interruptWith: (content: string) => session.interruptWith(content),
-      };
-    },
-
-    isPrompting(agentId: AgentId) {
-      return deps.agentManager.isPrompting(agentId);
-    },
-
-    async sendMessage(
-      fromAgentId: AgentId | undefined,
-      toAgentId: AgentId,
-      content: string,
-      priority: "high"
-    ) {
-      await deps.messageRouter.sendToAddress({
-        from: fromAgentId ?? callerAgentId,
-        to: { agent: toAgentId },
-        content,
-        options: { priority },
-      });
-    },
-  };
-
-  return async (args: InjectContextArgs): Promise<InjectionResult> => {
-    return injectContext(injectionDeps, args.target_agent_id, args.content, {
-      urgent: args.urgent,
-      allowInterrupt: true, // MCP tool always allows interrupt fallback
-      source: { type: "agent", agentId: callerAgentId },
-      reason: args.reason,
-    });
-  };
-}
-
-/**
- * Format the tool result for MCP response
- */
-export function formatInjectContextResult(result: InjectionResult): {
-  content: Array<{ type: "text"; text: string }>;
-  isError?: boolean;
-} {
-  if (result.success) {
-    let text = `Context injected via ${result.method}`;
-    if (result.note) {
-      text += `: ${result.note}`;
-    }
-    return {
-      content: [{ type: "text", text }],
-    };
-  } else {
-    return {
-      content: [{ type: "text", text: `Injection failed: ${result.error}` }],
-      isError: true,
-    };
-  }
-}

package/src/mcp/tools/list_claimable_tasks.ts

@@ -1,93 +0,0 @@
-/**
- * list_claimable_tasks() MCP Tool
- *
- * Lists tasks available for claiming. Allows agents to preview
- * what's in the task pool before claiming.
- *
- * @module mcp/tools/list_claimable_tasks
- */
-
-import { z } from "zod";
-import type { TaskBackend, ClaimFilter, ExtendedTask } from "../../task/backend/types.js";
-import type { ToolContext } from "../types.js";
-
-// =============================================================================
-// Schema
-// =============================================================================
-
-export const ListClaimableTasksSchema = {
-  tags: z
-    .array(z.string())
-    .optional()
-    .describe("Only list tasks with at least one matching tag"),
-  root_tasks_only: z
-    .boolean()
-    .optional()
-    .describe("Only list root tasks (no parent)"),
-  limit: z
-    .number()
-    .optional()
-    .describe("Maximum number of tasks to return (default: 20)"),
-};
-
-// =============================================================================
-// Handler
-// =============================================================================
-
-export interface ListClaimableTasksDeps {
-  taskBackend: TaskBackend;
-}
-
-export function createListClaimableTasksHandler(
-  _context: ToolContext,
-  deps: ListClaimableTasksDeps
-) {
-  return async (args: {
-    tags?: string[];
-    root_tasks_only?: boolean;
-    limit?: number;
-  }): Promise<{
-    tasks: ExtendedTask[];
-    count: number;
-    message: string;
-  }> => {
-    if (!deps.taskBackend.listClaimable) {
-      return {
-        tasks: [],
-        count: 0,
-        message: "Task backend does not support listClaimable operations",
-      };
-    }
-
-    const filter: ClaimFilter = {};
-    if (args.tags) filter.tags = args.tags;
-    if (args.root_tasks_only) filter.rootTasksOnly = args.root_tasks_only;
-
-    let tasks = await deps.taskBackend.listClaimable(filter);
-
-    const limit = args.limit ?? 20;
-    if (tasks.length > limit) {
-      tasks = tasks.slice(0, limit);
-    }
-
-    return {
-      tasks,
-      count: tasks.length,
-      message:
-        tasks.length > 0
-          ? `Found ${tasks.length} claimable task(s)`
-          : "No claimable tasks available",
-    };
-  };
-}
-
-// =============================================================================
-// Tool Info
-// =============================================================================
-
-export const LIST_CLAIMABLE_TASKS_TOOL_INFO = {
-  name: "list_claimable_tasks",
-  description:
-    "List tasks available for claiming. Shows pending, unblocked, unassigned tasks. Requires task.claim capability.",
-  schema: ListClaimableTasksSchema,
-};

package/src/mcp/tools/unclaim_task.ts

@@ -1,71 +0,0 @@
-/**
- * unclaim_task() MCP Tool
- *
- * Allows agents with `task.claim` capability to release a claimed task
- * back to the pending pool.
- *
- * @module mcp/tools/unclaim_task
- */
-
-import { z } from "zod";
-import type { TaskBackend } from "../../task/backend/types.js";
-import type { ToolContext } from "../types.js";
-
-// =============================================================================
-// Schema
-// =============================================================================
-
-export const UnclaimTaskSchema = {
-  task_id: z.string().describe("ID of the task to unclaim"),
-};
-
-// =============================================================================
-// Handler
-// =============================================================================
-
-export interface UnclaimTaskDeps {
-  taskBackend: TaskBackend;
-}
-
-export function createUnclaimTaskHandler(
-  _context: ToolContext,
-  deps: UnclaimTaskDeps
-) {
-  return async (args: {
-    task_id: string;
-  }): Promise<{
-    success: boolean;
-    message: string;
-  }> => {
-    if (!deps.taskBackend.unclaim) {
-      return {
-        success: false,
-        message: "Task backend does not support unclaim operations",
-      };
-    }
-
-    try {
-      await deps.taskBackend.unclaim(args.task_id);
-      return {
-        success: true,
-        message: `Task ${args.task_id} unclaimed and returned to pending pool`,
-      };
-    } catch (error) {
-      return {
-        success: false,
-        message: `Failed to unclaim task: ${error instanceof Error ? error.message : String(error)}`,
-      };
-    }
-  };
-}
-
-// =============================================================================
-// Tool Info
-// =============================================================================
-
-export const UNCLAIM_TASK_TOOL_INFO = {
-  name: "unclaim_task",
-  description:
-    "Release a claimed task back to the pending pool so another agent can pick it up. Requires task.claim capability.",
-  schema: UnclaimTaskSchema,
-};