cognitive-core 0.2.4 → 0.3.1

package/src/types/team-trajectory.ts

@@ -1,673 +0,0 @@
-/**
- * Team Trajectory Types
- *
- * TeamTrajectory - Complete record of a team's collective execution.
- * The team-level analog of Trajectory. Where an individual trajectory
- * records thought → action → observation, a team trajectory records
- * events across all members with an interaction graph overlay.
- */
-
-import type { Trajectory } from './trajectory.js';
-import type { Step } from './step.js';
-
-// ============================================================
-// Interaction Types (from DESIGN doc)
-// ============================================================
-
-/**
- * Fine-grained interaction type between agents.
- * Used in InteractionTag and RoleInteractionGuidance.
- */
-export type InteractionType =
-  | 'delegation'
-  | 'result_return'
-  | 'message'
-  | 'signal'
-  | 'spawn'
-  | 'escalation';
-
-/**
- * Runtime step metadata tag linking agent interactions.
- * Attached to individual trajectory steps to build the interaction graph.
- */
-export interface InteractionTag {
-  /** Unique ID grouping source + target steps of one interaction */
-  interactionId: string;
-  /** Type of interaction */
-  interactionType: InteractionType;
-  /** The other agent involved */
-  counterpartAgentId: string;
-  /** Whether this step is the source or target of the interaction */
-  stepRole: 'source' | 'target';
-  /** Communication channel used, if any */
-  channel?: string;
-  /** Signal name, if any */
-  signal?: string;
-}
-
-/**
- * Expected interaction pattern from team.yaml for comparison.
- */
-export interface ExpectedInteractionPattern {
-  /** Pattern name */
-  name: string;
-  /** From role */
-  fromRole: string;
-  /** To role */
-  toRole: string;
-  /** Expected interaction type */
-  type: InteractionType;
-  /** Frequency expectation */
-  frequency: 'once' | 'per-task' | 'continuous';
-}
-
-// ============================================================
-// Team Trajectory Input (entry point for ingestion)
-// ============================================================
-
-/**
- * TeamTrajectoryInput - Entry point for the team learning pipeline.
- * Contains individual agent trajectories that get converted to a
- * TeamTrajectory with interaction graph.
- */
-export interface TeamTrajectoryInput {
-  objective: string;
-  domain: string;
-  complexity: 'simple' | 'moderate' | 'complex' | 'epic';
-  teamName: string;
-  templateName: string;
-  topologyType: 'hierarchical' | 'flat' | 'wave' | 'custom';
-  enforcement: 'strict' | 'permissive' | 'audit';
-  /** Individual agent trajectories */
-  memberTrajectories: MemberTrajectoryInput[];
-  /** Expected coordination patterns from team.yaml */
-  expectedPatterns?: ExpectedInteractionPattern[];
-  /** Collective team outcome */
-  outcome: TeamOutcome;
-  /** Additional metadata */
-  metadata?: Record<string, unknown>;
-}
-
-/**
- * Individual member's trajectory within the team input.
- */
-export interface MemberTrajectoryInput {
-  agentId: string;
-  role: string;
-  trajectory: Trajectory;
-}
-
-// ============================================================
-// Graph Model Types (from DESIGN doc)
-// ============================================================
-
-/**
- * MemberTrajectory - A node in the team trajectory graph.
- * Wraps an individual agent's full trajectory with team identity.
- */
-export interface MemberTrajectory {
-  agentId: string;
-  role: string;
-  trajectory: Trajectory;
-}
-
-/**
- * AgentInteraction - An edge in the team trajectory graph.
- * Links a specific step in one agent's trajectory to a step in another's.
- */
-export interface AgentInteraction {
-  id: string;
-  type: InteractionType;
-  from: { agentId: string; role: string; stepIndex: number };
-  to: { agentId: string; role: string; stepIndex: number };
-  content: string;
-  channel?: string;
-  signal?: string;
-  timestamp: Date;
-  latencyMs?: number;
-  /** Whether this interaction matches an expected pattern from team.yaml */
-  wasExpected: boolean;
-}
-
-/**
- * StructuralMetrics computed from the graph model.
- * Richer than CoordinationMetrics — computed from per-agent steps + interactions.
- */
-export interface GraphStructuralMetrics {
-  teamSize: number;
-  totalSteps: number;
-  totalInteractions: number;
-  interactionDensity: number;
-  maxInDegree: { agentId: string; count: number };
-  maxOutDegree: { agentId: string; count: number };
-  parallelismRatio: number;
-  totalWallTimeSeconds: number;
-  totalTokens: number;
-}
-
-// ============================================================
-// Events
-// ============================================================
-
-/**
- * A single event in a team's execution history.
- * These are the "steps" of team-level learning.
- */
-export interface TeamEvent {
-  /** When this event occurred */
-  timestamp: Date;
-  /** Which event type */
-  type: TeamEventType;
-  /** Which agent produced this event */
-  agentId: string;
-  /** Role of the agent at event time */
-  role: string;
-  /** Event-specific payload */
-  payload: Record<string, unknown>;
-}
-
-export type TeamEventType =
-  | 'agent_spawned'
-  | 'agent_shutdown'
-  | 'task_delegated'
-  | 'task_completed'
-  | 'task_failed'
-  | 'signal_emitted'
-  | 'message_sent'
-  | 'message_broadcast'
-  | 'plan_proposed'
-  | 'plan_approved'
-  | 'plan_rejected'
-  | 'checkpoint_reached'
-  | 'role_changed'
-  | 'escalation';
-
-/**
- * Interaction edge in the team communication graph.
- * Built from events during analysis.
- */
-export interface InteractionEdge {
-  /** Sender role */
-  from: string;
-  /** Receiver role */
-  to: string;
-  /** Number of interactions */
-  count: number;
-  /** Types of interactions */
-  types: TeamEventType[];
-  /** Average latency between send and response (ms) */
-  avgResponseLatencyMs?: number;
-}
-
-/**
- * Coordination metrics computed from team events.
- */
-export interface CoordinationMetrics {
-  /** Total wall time for the team execution */
-  totalWallTimeSeconds: number;
-  /** Time from team creation to first task completion */
-  timeToFirstOutputSeconds: number;
-  /** Fraction of total tokens spent on coordination vs. production */
-  coordinationOverheadRatio: number;
-  /** Agent with most inbound messages (potential bottleneck) */
-  bottleneckAgent?: string;
-  /** Number of communication cycles (back-and-forth exchanges) */
-  communicationCycles: number;
-  /** Maximum task dependency chain length executed */
-  maxDependencyDepth: number;
-  /** Number of tasks that were re-delegated after failure */
-  reDelegationCount: number;
-  /** Parallelism efficiency: tasks completed concurrently / total tasks */
-  parallelismRatio: number;
-}
-
-/**
- * Per-member outcome within the team trajectory.
- */
-export interface MemberOutcome {
-  agentId: string;
-  role: string;
-  tasksAssigned: number;
-  tasksCompleted: number;
-  tasksFailed: number;
-  llmCalls: number;
-  totalTokens: number;
-  /** Link to individual trajectory if available */
-  trajectoryId?: string;
-}
-
-/**
- * Collective team outcome.
- */
-export interface TeamOutcome {
-  success: boolean;
-  /** 0-1 score for partial success */
-  partialScore: number;
-  /** Quality assessment */
-  quality: 'excellent' | 'good' | 'acceptable' | 'poor';
-  /** Total LLM calls across all members */
-  totalLlmCalls: number;
-  /** Total tokens across all members */
-  totalTokens: number;
-  /** Total wall time */
-  totalWallTimeSeconds: number;
-  /** Optional error information */
-  errorInfo?: string;
-}
-
-/**
- * TeamTrajectory - Complete record of a team's collective execution.
- * The team-level analog of Trajectory.
- */
-export interface TeamTrajectory {
-  id: string;
-
-  // === TEAM IDENTITY ===
-  /** Team name (from OpenTeams) */
-  teamName: string;
-  /** Template that defined this team */
-  templateName: string;
-
-  // === TEAM STRUCTURE (snapshot at execution time) ===
-  /** Topology type used */
-  topologyType: 'hierarchical' | 'flat' | 'wave' | 'custom';
-  /** Roles that participated */
-  roles: string[];
-  /** Number of agents */
-  teamSize: number;
-  /** Communication enforcement mode */
-  enforcement: 'strict' | 'permissive' | 'audit';
-
-  // === TASK ===
-  /** High-level description of what the team was trying to accomplish */
-  objective: string;
-  /** Domain of the work */
-  domain: string;
-  /** Task complexity estimate */
-  complexity: 'simple' | 'moderate' | 'complex' | 'epic';
-
-  // === EVENTS (the "steps") ===
-  events: TeamEvent[];
-
-  // === DERIVED STRUCTURE ===
-  /** Communication graph (built from events) */
-  interactionGraph: InteractionEdge[];
-  /** Coordination metrics (computed from events) */
-  metrics: CoordinationMetrics;
-
-  // === OUTCOMES ===
-  /** Per-member outcomes */
-  memberOutcomes: MemberOutcome[];
-  /** Collective outcome */
-  outcome: TeamOutcome;
-
-  // === GRAPH DATA (primary representation) ===
-  /** Full per-agent trajectories (graph nodes) */
-  members: MemberTrajectory[];
-  /** Step-level interactions between agents (graph edges) */
-  interactions: AgentInteraction[];
-  /** Graph-level structural metrics */
-  graphMetrics: GraphStructuralMetrics;
-  /** Expected interaction patterns from team.yaml */
-  expectedPatterns?: ExpectedInteractionPattern[];
-
-  /** When the trajectory was recorded */
-  timestamp: Date;
-  /** Additional metadata */
-  metadata: Record<string, unknown>;
-}
-
-/**
- * Create a new team trajectory with defaults.
- */
-export function createTeamTrajectory(params: {
-  id?: string;
-  teamName: string;
-  templateName: string;
-  topologyType: TeamTrajectory['topologyType'];
-  roles: string[];
-  teamSize: number;
-  enforcement: TeamTrajectory['enforcement'];
-  objective: string;
-  domain: string;
-  complexity: TeamTrajectory['complexity'];
-  events: TeamEvent[];
-  interactionGraph: InteractionEdge[];
-  metrics: CoordinationMetrics;
-  memberOutcomes: MemberOutcome[];
-  outcome: TeamOutcome;
-  metadata?: Record<string, unknown>;
-  // Graph data (required)
-  members: MemberTrajectory[];
-  interactions: AgentInteraction[];
-  graphMetrics: GraphStructuralMetrics;
-  expectedPatterns?: ExpectedInteractionPattern[];
-}): TeamTrajectory {
-  return {
-    id: params.id ?? crypto.randomUUID(),
-    teamName: params.teamName,
-    templateName: params.templateName,
-    topologyType: params.topologyType,
-    roles: params.roles,
-    teamSize: params.teamSize,
-    enforcement: params.enforcement,
-    objective: params.objective,
-    domain: params.domain,
-    complexity: params.complexity,
-    events: params.events,
-    interactionGraph: params.interactionGraph,
-    metrics: params.metrics,
-    memberOutcomes: params.memberOutcomes,
-    outcome: params.outcome,
-    members: params.members,
-    interactions: params.interactions,
-    graphMetrics: params.graphMetrics,
-    expectedPatterns: params.expectedPatterns,
-    timestamp: new Date(),
-    metadata: params.metadata ?? {},
-  };
-}
-
-/**
- * Check if a team trajectory was successful.
- */
-export function isTeamSuccessful(trajectory: TeamTrajectory): boolean {
-  return trajectory.outcome.success;
-}
-
-/**
- * Build an interaction graph from InteractionTags embedded in member trajectories.
- * Groups by interactionId, links source to target, aggregates into InteractionEdge[].
- */
-export function buildInteractionGraph(
-  members: MemberTrajectoryInput[]
-): InteractionEdge[] {
-  // Collect all interaction tags from step metadata
-  const tagsByInteraction = new Map<string, { source?: { role: string; agentId: string; type: InteractionType }; target?: { role: string; agentId: string } }>();
-
-  for (const member of members) {
-    for (const step of member.trajectory.steps) {
-      const tag = (step.metadata as Record<string, unknown>)?.interactionTag as InteractionTag | undefined;
-      if (!tag) continue;
-
-      if (!tagsByInteraction.has(tag.interactionId)) {
-        tagsByInteraction.set(tag.interactionId, {});
-      }
-      const entry = tagsByInteraction.get(tag.interactionId)!;
-      if (tag.stepRole === 'source') {
-        entry.source = { role: member.role, agentId: member.agentId, type: tag.interactionType };
-      } else {
-        entry.target = { role: member.role, agentId: member.agentId };
-      }
-    }
-  }
-
-  // Aggregate into edges (from role → to role)
-  const edgeMap = new Map<string, InteractionEdge>();
-  for (const entry of tagsByInteraction.values()) {
-    if (!entry.source || !entry.target) continue;
-    const key = `${entry.source.role}->${entry.target.role}`;
-    if (!edgeMap.has(key)) {
-      edgeMap.set(key, {
-        from: entry.source.role,
-        to: entry.target.role,
-        count: 0,
-        types: [],
-      });
-    }
-    const edge = edgeMap.get(key)!;
-    edge.count++;
-    const eventType = interactionTypeToEventType(entry.source.type);
-    if (eventType && !edge.types.includes(eventType)) {
-      edge.types.push(eventType);
-    }
-  }
-
-  return [...edgeMap.values()];
-}
-
-/**
- * Map InteractionType to closest TeamEventType.
- */
-function interactionTypeToEventType(type: InteractionType): TeamEventType | null {
-  switch (type) {
-    case 'delegation': return 'task_delegated';
-    case 'result_return': return 'task_completed';
-    case 'message': return 'message_sent';
-    case 'signal': return 'signal_emitted';
-    case 'spawn': return 'agent_spawned';
-    case 'escalation': return 'escalation';
-    default: return null;
-  }
-}
-
-/**
- * Build a TeamTrajectory from TeamTrajectoryInput.
- * Populates both graph data (members, interactions, graphMetrics) and
- * derived flat data (events, interactionGraph, metrics, memberOutcomes).
- */
-export function buildTeamTrajectory(input: TeamTrajectoryInput): TeamTrajectory {
-  // === GRAPH DATA (primary) ===
-
-  // Preserve full member trajectories as graph nodes
-  const members: MemberTrajectory[] = input.memberTrajectories.map(m => ({
-    agentId: m.agentId,
-    role: m.role,
-    trajectory: m.trajectory,
-  }));
-
-  // Build step-level interactions from InteractionTag metadata
-  const interactions = buildAgentInteractions(input.memberTrajectories, input.expectedPatterns);
-
-  // Build aggregated interaction graph (flat, for backward compat)
-  const interactionGraph = buildInteractionGraph(input.memberTrajectories);
-
-  // === FLAT DATA (derived from graph for backward compat) ===
-
-  // Convert individual trajectories to team events
-  const events: TeamEvent[] = [];
-  const memberOutcomes: MemberOutcome[] = [];
-
-  for (const member of input.memberTrajectories) {
-    // Add spawn event
-    events.push({
-      timestamp: new Date(member.trajectory.steps[0]?.metadata?.timestamp as string ?? Date.now()),
-      type: 'agent_spawned',
-      agentId: member.agentId,
-      role: member.role,
-      payload: {},
-    });
-
-    // Convert steps to events
-    for (const step of member.trajectory.steps) {
-      events.push({
-        timestamp: new Date(step.metadata?.timestamp as string ?? Date.now()),
-        type: stepToEventType(step),
-        agentId: member.agentId,
-        role: member.role,
-        payload: { action: step.action, result: step.observation },
-      });
-    }
-
-    // Build member outcome
-    const traj = member.trajectory;
-    memberOutcomes.push({
-      agentId: member.agentId,
-      role: member.role,
-      tasksAssigned: traj.steps.length,
-      tasksCompleted: traj.outcome?.success ? traj.steps.length : Math.floor(traj.steps.length * (traj.outcome?.partialScore ?? 0)),
-      tasksFailed: traj.outcome?.success ? 0 : Math.ceil(traj.steps.length * (1 - (traj.outcome?.partialScore ?? 0))),
-      llmCalls: traj.steps.length,
-      totalTokens: traj.steps.reduce((sum, s) => sum + (Number(s.metadata?.tokens) || 0), 0),
-      trajectoryId: traj.id,
-    });
-  }
-
-  // Sort events by timestamp
-  events.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
-
-  // Compute coordination metrics (flat)
-  const wallTime = input.outcome.totalWallTimeSeconds;
-  const metrics: CoordinationMetrics = {
-    totalWallTimeSeconds: wallTime,
-    timeToFirstOutputSeconds: wallTime > 0 ? wallTime * 0.1 : 0,
-    coordinationOverheadRatio: interactionGraph.length > 0
-      ? Math.min(interactionGraph.reduce((s, e) => s + e.count, 0) / Math.max(events.length, 1), 1)
-      : 0,
-    bottleneckAgent: findBottleneck(memberOutcomes),
-    communicationCycles: interactionGraph.filter(e => interactionGraph.some(e2 => e2.from === e.to && e2.to === e.from)).length,
-    maxDependencyDepth: 1,
-    reDelegationCount: 0,
-    parallelismRatio: input.memberTrajectories.length > 1 ? 0.5 : 0,
-  };
-
-  // Compute graph structural metrics
-  const totalSteps = members.reduce((s, m) => s + m.trajectory.steps.length, 0);
-  const totalTokens = members.reduce((s, m) => s + (m.trajectory.totalTokens ?? 0), 0);
-  const graphMetrics = computeGraphMetrics(members, interactions, wallTime, totalSteps, totalTokens, metrics.parallelismRatio);
-
-  return createTeamTrajectory({
-    teamName: input.teamName,
-    templateName: input.templateName,
-    topologyType: input.topologyType,
-    roles: [...new Set(input.memberTrajectories.map(m => m.role))],
-    teamSize: input.memberTrajectories.length,
-    enforcement: input.enforcement,
-    objective: input.objective,
-    domain: input.domain,
-    complexity: input.complexity,
-    events,
-    interactionGraph,
-    metrics,
-    memberOutcomes,
-    outcome: input.outcome,
-    metadata: input.metadata ?? {},
-    // Graph data
-    members,
-    interactions,
-    graphMetrics,
-    expectedPatterns: input.expectedPatterns,
-  });
-}
-
-/**
- * Build step-level AgentInteraction objects from InteractionTag metadata.
- */
-function buildAgentInteractions(
-  memberTrajectories: MemberTrajectoryInput[],
-  expectedPatterns?: ExpectedInteractionPattern[]
-): AgentInteraction[] {
-  // Collect all tagged steps, grouped by interactionId
-  const tagGroups = new Map<string, {
-    source?: { agentId: string; role: string; stepIndex: number; step: Step; tag: InteractionTag };
-    target?: { agentId: string; role: string; stepIndex: number; step: Step; tag: InteractionTag };
-  }>();
-
-  for (const member of memberTrajectories) {
-    for (let i = 0; i < member.trajectory.steps.length; i++) {
-      const step = member.trajectory.steps[i];
-      const tag = (step.metadata as Record<string, unknown>)?.interactionTag as InteractionTag | undefined;
-      if (!tag) continue;
-
-      if (!tagGroups.has(tag.interactionId)) {
-        tagGroups.set(tag.interactionId, {});
-      }
-      const group = tagGroups.get(tag.interactionId)!;
-      const entry = { agentId: member.agentId, role: member.role, stepIndex: i, step, tag };
-      if (tag.stepRole === 'source') {
-        group.source = entry;
-      } else {
-        group.target = entry;
-      }
-    }
-  }
-
-  // Build AgentInteraction for each complete pair
-  const interactions: AgentInteraction[] = [];
-  for (const [interactionId, group] of tagGroups) {
-    if (!group.source || !group.target) continue;
-
-    const { source, target } = group;
-    const sourceTs = source.step.timestamp?.getTime() ?? 0;
-    const targetTs = target.step.timestamp?.getTime() ?? 0;
-
-    // Check if this interaction was expected
-    const wasExpected = expectedPatterns?.some(p =>
-      p.fromRole === source.role &&
-      p.toRole === target.role &&
-      p.type === source.tag.interactionType
-    ) ?? false;
-
-    interactions.push({
-      id: interactionId,
-      type: source.tag.interactionType,
-      from: { agentId: source.agentId, role: source.role, stepIndex: source.stepIndex },
-      to: { agentId: target.agentId, role: target.role, stepIndex: target.stepIndex },
-      content: source.step.observation ?? '',
-      channel: source.tag.channel,
-      signal: source.tag.signal,
-      timestamp: source.step.timestamp ?? new Date(),
-      latencyMs: sourceTs > 0 && targetTs > 0 ? Math.abs(targetTs - sourceTs) : undefined,
-      wasExpected,
-    });
-  }
-
-  return interactions.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
-}
-
-/**
- * Compute GraphStructuralMetrics from members and interactions.
- */
-function computeGraphMetrics(
-  members: MemberTrajectory[],
-  interactions: AgentInteraction[],
-  wallTime: number,
-  totalSteps: number,
-  totalTokens: number,
-  parallelismRatio: number,
-): GraphStructuralMetrics {
-  // Compute in-degree and out-degree per agent
-  const inDegree = new Map<string, number>();
-  const outDegree = new Map<string, number>();
-  for (const interaction of interactions) {
-    inDegree.set(interaction.to.agentId, (inDegree.get(interaction.to.agentId) ?? 0) + 1);
-    outDegree.set(interaction.from.agentId, (outDegree.get(interaction.from.agentId) ?? 0) + 1);
-  }
-
-  let maxIn = { agentId: '', count: 0 };
-  for (const [agentId, count] of inDegree) {
-    if (count > maxIn.count) maxIn = { agentId, count };
-  }
-  let maxOut = { agentId: '', count: 0 };
-  for (const [agentId, count] of outDegree) {
-    if (count > maxOut.count) maxOut = { agentId, count };
-  }
-
-  return {
-    teamSize: members.length,
-    totalSteps,
-    totalInteractions: interactions.length,
-    interactionDensity: totalSteps > 0 ? interactions.length / totalSteps : 0,
-    maxInDegree: maxIn,
-    maxOutDegree: maxOut,
-    parallelismRatio,
-    totalWallTimeSeconds: wallTime,
-    totalTokens,
-  };
-}
-
-function stepToEventType(step: { action: string }): TeamEventType {
-  const action = step.action.toLowerCase();
-  if (action.includes('delegate')) return 'task_delegated';
-  if (action.includes('signal') || action.includes('emit')) return 'signal_emitted';
-  if (action.includes('message') || action.includes('send')) return 'message_sent';
-  if (action.includes('plan')) return 'plan_proposed';
-  return 'task_completed';
-}
-
-function findBottleneck(outcomes: MemberOutcome[]): string | undefined {
-  if (outcomes.length === 0) return undefined;
-  const maxTokens = Math.max(...outcomes.map(m => m.totalTokens));
-  const bottleneck = outcomes.find(m => m.totalTokens === maxTokens);
-  return bottleneck?.agentId;
-}