agentop-conventions

AgentOp Project Conventions

Core domain model, attention system, and architectural patterns specific to AgentOp.

When to Use This Skill

• Implementing features touching the core domain
• Working with task hierarchies
• Handling agent sessions and steps
• Implementing the attention system
• Building decision point flows
• Adding new entity types

Core Data Model

Entity Relationships

Task (tree hierarchy via parentId)
  └── Outcome (many per task, represents expected results)
        └── AgentSession (many per outcome, AI execution attempts)
              └── AgentStep (stream of: thinking | action | decision_point)
                    └── DecisionPoint (user approval for sensitive actions)

Type Definitions

// packages/core/src/types.ts

// ============================================
// Enums
// ============================================

export type TaskStatus = 
  | 'pending'      // Not started
  | 'in_progress'  // Being worked on
  | 'completed'    // Successfully done
  | 'blocked';     // Waiting on dependency

export type AttentionType =
  | 'supervised'   // Every action needs approval
  | 'delegated'    // Runs autonomously
  | 'sensitive';   // Only sensitive actions need approval

export type SessionStatus =
  | 'pending'      // Queued to start
  | 'running'      // Currently executing
  | 'completed'    // Finished successfully
  | 'error'        // Failed with error
  | 'cancelled';   // User cancelled

export type StepType =
  | 'thinking'        // LLM reasoning output
  | 'action'          // Tool execution
  | 'decision_point'; // Awaiting user decision

export type DecisionStatus =
  | 'pending'    // Waiting for user
  | 'approved'   // User approved
  | 'denied'     // User denied
  | 'timeout';   // Auto-denied after timeout

// ============================================
// Entities
// ============================================

export interface Task {
  id: string;
  title: string;
  description?: string;
  parentId: string | null;  // null = root task
  status: TaskStatus;
  attentionType: AttentionType;
  orderIndex: number;       // Fractional index for drag reorder
  createdAt: Date;
  updatedAt: Date;
}

export interface Outcome {
  id: string;
  taskId: string;
  title: string;
  description?: string;
  status: TaskStatus;
  createdAt: Date;
  updatedAt: Date;
}

export interface AgentSession {
  id: string;
  outcomeId: string;
  status: SessionStatus;
  attentionType: AttentionType;
  startedAt: Date;
  completedAt?: Date;
  error?: string;
  tokenUsage?: {
    prompt: number;
    completion: number;
    total: number;
  };
}

export interface AgentStep {
  id: string;
  sessionId: string;
  type: StepType;
  status: 'in_progress' | 'completed' | 'error' | DecisionStatus;
  content?: string;         // For thinking steps
  toolCall?: ToolCall;      // For action steps
  result?: ToolResult;      // After tool execution
  createdAt: Date;
}

export interface ToolCall {
  id: string;
  name: string;
  arguments: Record<string, unknown>;
}

export interface ToolResult {
  success: boolean;
  result?: string;
  error?: string;
}

// ============================================
// Event Log (Immutable Audit Trail)
// ============================================

export interface EventLog {
  id: string;
  timestamp: Date;
  eventType: string;
  entityType: 'task' | 'outcome' | 'session' | 'step';
  entityId: string;
  payload: Record<string, unknown>;
  userId?: string;
}