cognitive-core 0.1.0 → 0.1.2

package/src/types/team-trajectory.ts

@@ -0,0 +1,673 @@
+/**
+ * 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;
+}