Decouple Agent Tracking from backgroundTools

[bhouston]

Decouple Agent Tracking from backgroundTools

Description

Currently, the backgroundTools tracker is used to track shell processes, browser sessions, and agents in a single implementation. This creates unnecessary coupling between these different types of tools. This issue proposes to refactor the agent tracking into its own dedicated tracker.

Proposed Changes

1. Create a new AgentTracker class in packages/agent/src/tools/interaction/agentTracker.ts that will be responsible for tracking sub-agents
2. Move agent-specific tracking logic from backgroundTools.ts to this new class
3. Implement a new listAgents tool that uses the dedicated AgentTracker
4. Update agentStart.ts and related tools to use the new tracker instead of backgroundTools
5. Remove agent-related code from backgroundTools.ts

Technical Details

• The new AgentTracker should work alongside the existing agentStates map to provide status tracking
• It should provide methods for registering, updating, and retrieving agent status
• The listAgents tool should have similar filtering capabilities as listBackgroundTools but focused only on agents
• The implementation should maintain backward compatibility where possible

Benefits

• Reduced coupling between different tool types
• More focused and maintainable code
• Easier to extend or modify agent-specific functionality
• Clearer separation of concerns

Acceptance Criteria

• AgentTracker class is implemented
• listAgents tool is implemented
• agentStart.ts and related tools are updated to use the new tracker
• Agent-specific code is removed from backgroundTools.ts
• All tests pass
• Documentation is updated

[bhouston]

Technical Implementation Details for Agent Tracker

Current Implementation Analysis

• Currently, sub-agents are tracked in two places:

  1. agentStates map in agentStart.ts tracks agent-specific details like goals, prompts, and execution state
  2. backgroundTools registry provides a higher-level status tracking and metadata storage

• The coupling happens because:

  • agentStart registers agents with backgroundTools
  • agentStart updates backgroundTools when agent state changes
  • backgroundTools.cleanup() references agentStates directly to abort agents
  • Agents use their own backgroundTools instance, creating nested dependencies

Proposed AgentTracker Implementation

// agentTracker.ts
import { v4 as uuidv4 } from 'uuid';
import { ToolContext } from '../../core/types.js';
import { ToolAgentResult } from '../../core/toolAgent/types.js';

export enum AgentStatus {
  RUNNING = 'running',
  COMPLETED = 'completed',
  ERROR = 'error',
  TERMINATED = 'terminated',
}

export interface Agent {
  id: string;
  status: AgentStatus;
  startTime: Date;
  endTime?: Date;
  goal: string;
  result?: string;
  error?: string;
}

// Internal agent state tracking (similar to existing agentStates)
export interface AgentState {
  id: string;
  goal: string;
  prompt: string;
  output: string;
  completed: boolean;
  error?: string;
  result?: ToolAgentResult;
  context: ToolContext;
  workingDirectory: string;
  tools: any[];
  aborted: boolean;
}

export class AgentTracker {
  private agents: Map<string, Agent> = new Map();
  private agentStates: Map<string, AgentState> = new Map();

  constructor(readonly ownerName: string) {}

  // Register a new agent
  public registerAgent(goal: string): string {
    const id = uuidv4();
    
    // Create agent tracking entry
    const agent: Agent = {
      id,
      status: AgentStatus.RUNNING,
      startTime: new Date(),
      goal,
    };
    
    this.agents.set(id, agent);
    return id;
  }

  // Register agent state
  public registerAgentState(id: string, state: AgentState): void {
    this.agentStates.set(id, state);
  }

  // Update agent status
  public updateAgentStatus(
    id: string,
    status: AgentStatus,
    metadata?: { result?: string; error?: string }
  ): boolean {
    const agent = this.agents.get(id);
    if (!agent) {
      return false;
    }

    agent.status = status;

    if (
      status === AgentStatus.COMPLETED ||
      status === AgentStatus.ERROR ||
      status === AgentStatus.TERMINATED
    ) {
      agent.endTime = new Date();
    }

    if (metadata) {
      if (metadata.result !== undefined) agent.result = metadata.result;
      if (metadata.error !== undefined) agent.error = metadata.error;
    }

    return true;
  }

  // Get a specific agent state
  public getAgentState(id: string): AgentState | undefined {
    return this.agentStates.get(id);
  }

  // Get a specific agent tracking info
  public getAgent(id: string): Agent | undefined {
    return this.agents.get(id);
  }

  // Get all agents with optional filtering
  public getAgents(status?: AgentStatus): Agent[] {
    if (!status) {
      return Array.from(this.agents.values());
    }
    
    return Array.from(this.agents.values()).filter(
      agent => agent.status === status
    );
  }

  // Cleanup and terminate agents
  public async cleanup(): Promise<void> {
    const runningAgents = this.getAgents(AgentStatus.RUNNING);
    
    await Promise.all(
      runningAgents.map(agent => this.terminateAgent(agent.id))
    );
  }

  // Terminate a specific agent
  public async terminateAgent(id: string): Promise<void> {
    try {
      const agentState = this.agentStates.get(id);
      if (agentState && !agentState.aborted) {
        // Set the agent as aborted and completed
        agentState.aborted = true;
        agentState.completed = true;

        // Clean up resources owned by this sub-agent
        if (agentState.context.backgroundTools) {
          await agentState.context.backgroundTools.cleanup();
        }
      }
      this.updateAgentStatus(id, AgentStatus.TERMINATED);
    } catch (error) {
      this.updateAgentStatus(id, AgentStatus.ERROR, {
        error: error instanceof Error ? error.message : String(error),
      });
    }
  }
}

// Create a singleton instance
export const agentTracker = new AgentTracker('global');

Implementation of listAgents Tool

// listAgents.ts
import { z } from 'zod';
import { zodToJsonSchema } from 'zod-to-json-schema';

import { AgentStatus, agentTracker } from './agentTracker.js';
import { Tool } from '../../core/types.js';

const parameterSchema = z.object({
  status: z
    .enum(['all', 'running', 'completed', 'error', 'terminated'])
    .optional()
    .describe('Filter agents by status (default: "all")'),
  verbose: z
    .boolean()
    .optional()
    .describe('Include detailed information about each agent (default: false)'),
});

const returnSchema = z.object({
  agents: z.array(
    z.object({
      id: z.string(),
      status: z.string(),
      goal: z.string(),
      startTime: z.string(),
      endTime: z.string().optional(),
      runtime: z.number().describe('Runtime in seconds'),
      result: z.string().optional(),
      error: z.string().optional(),
    }),
  ),
  count: z.number(),
});

type Parameters = z.infer<typeof parameterSchema>;
type ReturnType = z.infer<typeof returnSchema>;

export const listAgentsTool: Tool<Parameters, ReturnType> = {
  name: 'listAgents',
  description: 'Lists all sub-agents and their status',
  logPrefix: '🤖',
  parameters: parameterSchema,
  returns: returnSchema,
  parametersJsonSchema: zodToJsonSchema(parameterSchema),
  returnsJsonSchema: zodToJsonSchema(returnSchema),

  execute: async (
    { status = 'all', verbose = false },
    { logger },
  ): Promise<ReturnType> => {
    logger.verbose(
      `Listing agents with status: ${status}, verbose: ${verbose}`,
    );

    // Get all agents
    let agents = agentTracker.getAgents();
    
    // Filter by status if specified
    if (status !== 'all') {
      const statusEnum = status.toUpperCase() as keyof typeof AgentStatus;
      agents = agents.filter(
        agent => agent.status === AgentStatus[statusEnum]
      );
    }

    // Format the response
    const formattedAgents = agents.map(agent => {
      const now = new Date();
      const startTime = agent.startTime;
      const endTime = agent.endTime || now;
      const runtime = (endTime.getTime() - startTime.getTime()) / 1000; // in seconds

      const result: any = {
        id: agent.id,
        status: agent.status,
        goal: agent.goal,
        startTime: startTime.toISOString(),
        ...(agent.endTime && { endTime: agent.endTime.toISOString() }),
        runtime: parseFloat(runtime.toFixed(2)),
      };

      // Add result/error if verbose or if they exist
      if (verbose || agent.result) {
        result.result = agent.result;
      }
      
      if (verbose && agent.error) {
        result.error = agent.error;
      }

      return result;
    });

    return {
      agents: formattedAgents,
      count: formattedAgents.length,
    };
  },

  logParameters: ({ status = 'all', verbose = false }, { logger }) => {
    logger.info(
      `Listing agents with status: ${status}, verbose: ${verbose}`,
    );
  },

  logReturns: (output, { logger }) => {
    logger.info(`Found ${output.count} agents`);
  },
};

Changes Required in agentStart.ts

1. Replace the global agentStates map with the agentTracker singleton
2. Update agent registration to use agentTracker.registerAgent()
3. Update agent state registration to use agentTracker.registerAgentState()
4. Update status handling to use agentTracker.updateAgentStatus()

Handling Sub-Agent BackgroundTools

Currently, each sub-agent gets its own backgroundTools instance, which creates a nested dependency structure. We have a few options:

1. Keep the current approach: Each sub-agent continues to have its own backgroundTools instance
2. Use parent trackers: Sub-agents use the parent agent's trackers with a namespace/prefix
3. Refactor to use shared trackers: All agents share the same trackers but with agent-specific metadata

Option 1 is the easiest for backward compatibility but doesn't fully address the coupling issue. Option 2 is a good middle ground. Option 3 is the most elegant but requires more changes.

Handling Recursive Cleanup

When a parent agent is terminated, it needs to clean up all its sub-agents. This requires careful handling to avoid circular dependencies. The approach should be:

1. When terminating an agent, first mark it as aborted
2. Then terminate all its child processes/browsers using their respective trackers
3. Then recursively terminate all its sub-agents

Migration Strategy

1. Implement the AgentTracker class first
2. Add the listAgents tool
3. Modify agentStart to use both the old backgroundTools and new agentTracker temporarily to ensure compatibility
4. Once all tests pass, remove the backgroundTools usage from agentStart
5. Update backgroundTools.cleanup() to delegate agent cleanup to agentTracker
6. Finally, remove agent-specific code from backgroundTools

Handling Backward Compatibility

To ensure backward compatibility during the transition:

1. Keep the original agentStates map as a proxy to agentTracker.agentStates
2. Implement the original methods on backgroundTools to delegate to the appropriate tracker
3. Gradually update code that directly accesses agentStates to use agentTracker instead

[bhouston]

/mycoder can you create a PR that realized this issue?

[bhouston]

I've implemented the AgentTracker decoupling from backgroundTools as requested. The PR has been created at #294.

The implementation includes:

1. A new AgentTracker class in packages/agent/src/tools/interaction/agentTracker.ts that handles agent-specific tracking
2. A new listAgents tool in packages/agent/src/tools/system/listAgents.ts that provides focused agent listing capabilities
3. Updates to agentStart.ts to use the new AgentTracker while maintaining backward compatibility
4. Modifications to backgroundTools.ts to delegate agent cleanup to AgentTracker

The implementation follows the design outlined in your comment, including the separation of concerns between different types of background tools. All tests are passing and the code maintains backward compatibility.

Let me know if you have any questions or if you'd like any adjustments to the implementation.

[github-actions]

🎉 This issue has been resolved in version mycoder-agent-v1.5.0 🎉

The release is available on:

• pnpm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀