cognitive-core 0.0.2 → 0.1.2

package/src/workspace/templates/team-trajectory-analysis.ts

@@ -0,0 +1,564 @@
+/**
+ * Team Trajectory Analysis Template
+ *
+ * Agentic analysis of multi-agent team executions.
+ * The agent gets a prepared workspace with compressed trajectories,
+ * interaction graph, structural metrics, and critical moment annotations.
+ *
+ * - Small teams with simple outcomes → heuristic fallback
+ * - Complex team executions → full agentic analysis
+ */
+
+import type { WorkspaceHandle } from 'agent-workspace';
+import type {
+  TeamAnalysisResult,
+  AgentCredit,
+  InteractionCredit,
+  CoordinationAssessment,
+  RoleLessonEntry,
+  TeamLessonEntry,
+  TeamMetaObservationEntry,
+} from '../../memory/team-experience.js';
+import type {
+  IngestionResult,
+} from '../../learning/team-ingester.js';
+import type {
+  AgenticTaskTemplate,
+  AnalysisComplexity,
+  ProcessingContext,
+} from '../types.js';
+import type { ComputeRequirements } from '../../runtime/compute-provider.js';
+
+// ============================================================
+// Input / Output Types
+// ============================================================
+
+export interface TeamTrajectoryAnalysisInput {
+  /** Pre-processed ingestion result from TeamTrajectoryIngester */
+  ingestion: IngestionResult;
+}
+
+// Output is TeamAnalysisResult from memory/team-experience.ts
+
+// ============================================================
+// Heuristic Fallback
+// ============================================================
+
+/**
+ * Heuristic analysis for simple team trajectories.
+ * Used when team is small, outcome is clear, and few events.
+ */
+function heuristicTeamAnalysis(input: TeamTrajectoryAnalysisInput): TeamAnalysisResult {
+  const { teamTrajectory, structuralMetrics } = input.ingestion;
+
+  // Per-agent credit from graph data
+  const agentCredits: AgentCredit[] = teamTrajectory.members.map((member) => {
+    const traj = member.trajectory;
+    const success = traj.outcome?.success ?? false;
+    const partialScore = traj.outcome?.partialScore ?? 0;
+    const contributionScore = success ? 1.0 : partialScore;
+
+    // Check if this agent had meaningful work
+    const hadMeaningfulWork = traj.steps.length > 0 && (traj.totalTokens ?? 0) > 500;
+
+    return {
+      agentId: member.agentId,
+      role: member.role,
+      contributionScore,
+      assessment: success
+        ? `${member.role} completed ${traj.steps.length} steps successfully`
+        : `${member.role} completed ${traj.steps.length} steps with partial score ${partialScore.toFixed(2)}`,
+      roleAssessment: success && hadMeaningfulWork
+        ? ('essential' as const)
+        : hadMeaningfulWork
+          ? ('helpful' as const)
+          : traj.steps.length === 0
+            ? ('redundant' as const)
+            : ('neutral' as const),
+    };
+  });
+
+  // Interaction credits from step-level interactions
+  const interactionCredits: InteractionCredit[] = teamTrajectory.interactions.map((interaction) => ({
+    interactionId: interaction.id,
+    fromRole: interaction.from.role,
+    toRole: interaction.to.role,
+    value: 'helpful' as const,
+    creditScore: interaction.wasExpected ? 0.6 : 0.4,
+    reasoning: `${interaction.type} from ${interaction.from.role} to ${interaction.to.role}${interaction.wasExpected ? ' (expected)' : ' (emergent)'}`,
+    necessity: interaction.wasExpected ? ('useful' as const) : ('useful' as const),
+    type: interaction.type,
+  }));
+
+  // Coordination assessment with graph pattern data
+  const coordinationAssessment: CoordinationAssessment = {
+    quality: teamTrajectory.outcome.success ? 'good' : 'acceptable',
+    observedPatterns: [],
+    observedAntiPatterns: [],
+    narrative: teamTrajectory.outcome.success
+      ? `Team of ${teamTrajectory.teamSize} completed objective successfully with ${structuralMetrics.totalInteractions} interactions.`
+      : `Team of ${teamTrajectory.teamSize} failed with ${structuralMetrics.totalInteractions} interactions. Coordination overhead ratio: ${teamTrajectory.metrics.coordinationOverheadRatio}.`,
+  };
+
+  // Detect emergent coordination patterns
+  const unexpectedCount = teamTrajectory.interactions.filter(i => !i.wasExpected).length;
+  if (unexpectedCount > 0) {
+    coordinationAssessment.observedPatterns.push({
+      name: 'emergent-coordination',
+      description: `${unexpectedCount} unexpected interactions emerged during execution`,
+      correlatedWithSuccess: teamTrajectory.outcome.success,
+    });
+  }
+
+  // Role lessons from per-agent trajectory data
+  const roleLessons: RoleLessonEntry[] = teamTrajectory.members.map((member) => {
+    const traj = member.trajectory;
+    const strengths: string[] = [];
+    const improvements: string[] = [];
+
+    if (traj.outcome?.success) {
+      strengths.push(`Completed ${traj.steps.length} steps successfully`);
+    }
+    if (traj.steps.length === 0) {
+      improvements.push('No steps executed — role may be unnecessary');
+    }
+    if (!traj.outcome?.success && traj.steps.length > 0) {
+      improvements.push('Task execution did not succeed');
+    }
+
+    return { role: member.role, strengths, improvements };
+  });
+
+  // Basic team lessons
+  const teamLessons: TeamLessonEntry[] = [];
+  if (teamTrajectory.metrics.coordinationOverheadRatio > 0.35) {
+    teamLessons.push({
+      category: 'coordination',
+      lesson: 'High coordination overhead detected',
+      evidence: `Coordination overhead ratio: ${teamTrajectory.metrics.coordinationOverheadRatio}`,
+      confidence: 0.6,
+    });
+  }
+  if (teamTrajectory.metrics.reDelegationCount > 0) {
+    teamLessons.push({
+      category: 'delegation',
+      lesson: `${teamTrajectory.metrics.reDelegationCount} tasks were re-delegated`,
+      evidence: 'Re-delegation events in trajectory',
+      confidence: 0.7,
+    });
+  }
+
+  // Meta-observation
+  const metaObservation: TeamMetaObservationEntry = {
+    formationEffective: teamTrajectory.outcome.success,
+    teamSizeAssessment: 'right-sized',
+    topologyAssessment: teamTrajectory.outcome.success ? 'effective' : 'neutral',
+    formationSuggestions: [],
+    coordinationSuggestions: [],
+  };
+
+  return {
+    teamTrajectoryId: teamTrajectory.id,
+    agentCredits,
+    interactionCredits,
+    coordinationAssessment,
+    roleLessons,
+    teamLessons,
+    metaObservation,
+    analysisMetrics: {
+      analysisTokens: 0,
+      analysisTimeMs: 0,
+      analysisToolCalls: 0,
+    },
+  };
+}
+
+// ============================================================
+// Template Implementation
+// ============================================================
+
+export const teamTrajectoryAnalysisTemplate: AgenticTaskTemplate<
+  TeamTrajectoryAnalysisInput,
+  TeamAnalysisResult
+> = {
+  taskType: 'team-trajectory-analysis',
+  domain: 'team-analysis',
+  description: 'Analyze multi-agent team trajectory for credit assignment, coordination patterns, and lessons',
+
+  // === COMPLEXITY ASSESSMENT ===
+
+  assessComplexity(input: TeamTrajectoryAnalysisInput): AnalysisComplexity {
+    const { teamTrajectory } = input.ingestion;
+    const totalItems = teamTrajectory.members.reduce((s, m) => s + m.trajectory.steps.length, 0);
+
+    // Small successful teams with few items → heuristic
+    if (
+      teamTrajectory.teamSize <= 2 &&
+      totalItems <= 10 &&
+      teamTrajectory.outcome.success
+    ) {
+      return 'heuristic';
+    }
+
+    // Very small count → lightweight
+    if (totalItems <= 5) {
+      return 'lightweight';
+    }
+
+    // Failed teams, large teams, or many items → standard/thorough
+    if (
+      !teamTrajectory.outcome.success ||
+      teamTrajectory.teamSize > 5 ||
+      totalItems > 50
+    ) {
+      return 'standard';
+    }
+
+    return 'lightweight';
+  },
+
+  // === HEURISTIC FALLBACK ===
+
+  async heuristicFallback(
+    input: TeamTrajectoryAnalysisInput
+  ): Promise<TeamAnalysisResult> {
+    return heuristicTeamAnalysis(input);
+  },
+
+  // === WORKSPACE SETUP ===
+
+  async prepareWorkspace(
+    input: TeamTrajectoryAnalysisInput,
+    handle: WorkspaceHandle
+  ): Promise<void> {
+    const { teamTrajectory, structuralMetrics, criticalSteps, criticalInteractions } =
+      input.ingestion;
+
+    // Write objective
+    await handle.writeRaw(
+      'input',
+      'objective.md',
+      [
+        `# Team Objective`,
+        '',
+        `**Objective:** ${teamTrajectory.objective}`,
+        `**Domain:** ${teamTrajectory.domain}`,
+        `**Complexity:** ${teamTrajectory.complexity}`,
+        `**Outcome:** ${teamTrajectory.outcome.success ? 'SUCCESS' : 'FAILURE'} (quality: ${teamTrajectory.outcome.quality})`,
+      ].join('\n')
+    );
+
+    // Write team config
+    await handle.writeJson('input', 'team-config.json', {
+      teamName: teamTrajectory.teamName,
+      templateName: teamTrajectory.templateName,
+      topologyType: teamTrajectory.topologyType,
+      roles: teamTrajectory.roles,
+      teamSize: teamTrajectory.teamSize,
+      enforcement: teamTrajectory.enforcement,
+    });
+
+    // Write outcome
+    await handle.writeJson('input', 'outcome.json', {
+      teamOutcome: teamTrajectory.outcome,
+      members: teamTrajectory.members.map(m => ({
+        agentId: m.agentId,
+        role: m.role,
+        outcome: m.trajectory.outcome,
+        stepCount: m.trajectory.steps.length,
+        totalTokens: m.trajectory.totalTokens ?? 0,
+      })),
+    });
+
+    // Write structural metrics
+    await handle.writeJson('input', 'structural-metrics.json', structuralMetrics);
+
+    // Write critical moments
+    await handle.writeJson('input', 'critical-moments.json', {
+      criticalSteps: criticalSteps.map((cs) => ({
+        agentId: cs.agentId,
+        role: cs.role,
+        eventIndex: cs.eventIndex,
+        eventType: cs.event.type,
+        scores: cs.scores,
+        stepContent: cs.stepContent,
+        contentScore: cs.contentScore,
+      })),
+      criticalInteractions: criticalInteractions.map((ci) => ({
+        from: ci.edge.from,
+        to: ci.edge.to,
+        count: ci.edge.count,
+        types: ci.edge.types,
+        scores: ci.scores,
+        interaction: ci.interaction,
+        downstreamSuccessScore: ci.downstreamSuccessScore,
+      })),
+      totalSteps: teamTrajectory.members.reduce((s, m) => s + m.trajectory.steps.length, 0),
+      criticalRatio: input.ingestion.compressionStats.criticalRatio,
+    });
+
+    // Write step-level interactions
+    if (teamTrajectory.interactions.length > 0) {
+      await handle.writeJson('input', 'interactions/step-interactions.json',
+        teamTrajectory.interactions.map(i => ({
+          id: i.id,
+          type: i.type,
+          from: i.from,
+          to: i.to,
+          content: i.content.slice(0, 200),
+          channel: i.channel,
+          signal: i.signal,
+          timestamp: i.timestamp,
+          latencyMs: i.latencyMs,
+          wasExpected: i.wasExpected,
+        }))
+      );
+    }
+
+    // Write graph metrics
+    await handle.writeJson('input', 'graph-metrics.json', teamTrajectory.graphMetrics);
+
+    // Write per-member trajectory data
+    for (const member of teamTrajectory.members) {
+      const traj = member.trajectory;
+      await handle.writeJson('input', `trajectories/${member.role}.json`, {
+        agentId: member.agentId,
+        role: member.role,
+        stepCount: traj.steps.length,
+        outcome: traj.outcome,
+        totalTokens: traj.totalTokens ?? 0,
+        llmCalls: traj.llmCalls ?? 0,
+        trajectoryId: traj.id,
+        steps: traj.steps.map((step, i) => ({
+          index: i,
+          thought: step.thought ? step.thought.slice(0, 200) : undefined,
+          action: step.action.slice(0, 200),
+          observation: step.observation.slice(0, 200),
+          timestamp: step.timestamp,
+          attributionScore: step.attributionScore,
+        })),
+      });
+    }
+  },
+
+  // === PROMPT ===
+
+  buildTaskPrompt(input: TeamTrajectoryAnalysisInput): string {
+    const { teamTrajectory } = input.ingestion;
+    const outcomeStr = teamTrajectory.outcome.success ? 'SUCCESSFUL' : 'FAILED';
+    const totalItems = teamTrajectory.members.reduce((s, m) => s + m.trajectory.steps.length, 0);
+
+    return [
+      `Analyze this ${outcomeStr} multi-agent team execution (${teamTrajectory.teamSize} agents, ${teamTrajectory.topologyType} topology, ${totalItems} steps). Per-agent step-level trajectories and step-level interactions are available.`,
+      '',
+      '## Workspace Layout',
+      '',
+      'input/',
+      '  objective.md                  - What the team was trying to accomplish',
+      '  team-config.json              - Team structure (topology, roles, enforcement)',
+      '  outcome.json                  - Team and per-member outcomes',
+      '  structural-metrics.json       - Pre-computed structural metrics',
+      '  critical-moments.json         - Steps and interactions flagged as high-impact',
+      '  graph-metrics.json            - Graph-level structural metrics',
+      '  trajectories/                 - Per-agent step-level execution data',
+      '  interactions/',
+      '    step-interactions.json      - Step-level interactions between agents',
+      '',
+      'workspace/                      - Your scratch space',
+      'output/                         - Write structured analysis here',
+      '',
+      '## Your Task',
+      '',
+      '1. Read objective.md, outcome.json, and team-config.json for context.',
+      '2. Examine structural-metrics.json and interactions/graph.json for coordination patterns.',
+      '3. Review critical-moments.json, then selectively read trajectories for details.',
+      '4. For each agent/role, assess contribution. Write to output/analysis.json.',
+      '',
+      'Write your complete analysis to output/analysis.json with this schema:',
+      '```json',
+      '{',
+      '  "agentCredits": [{ "agentId": string, "role": string, "contributionScore": 0-1, "assessment": string, "roleAssessment": "essential"|"helpful"|"neutral"|"redundant" }],',
+      '  "interactionCredits": [{ "interactionId": string, "fromRole": string, "toRole": string, "value": "helpful"|"neutral"|"harmful", "creditScore": -1 to 1, "reasoning": string, "necessity": "critical"|"useful"|"unnecessary"|"harmful" }],',
+      '  "coordinationAssessment": { "quality": "excellent"|"good"|"acceptable"|"poor", "observedPatterns": [{ "name": string, "description": string, "correlatedWithSuccess": boolean }], "observedAntiPatterns": [{ "name": string, "description": string, "impact": string, "suggestedFix": string }], "narrative": string },',
+      '  "roleLessons": [{ "role": string, "strengths": string[], "improvements": string[] }],',
+      '  "teamLessons": [{ "category": "composition"|"coordination"|"delegation"|"communication", "lesson": string, "evidence": string, "confidence": 0-1 }],',
+      '  "metaObservation": { "formationEffective": boolean, "teamSizeAssessment": "too-small"|"right-sized"|"too-large", "topologyAssessment": "effective"|"neutral"|"hindering", "formationSuggestions": string[], "coordinationSuggestions": string[] }',
+      '}',
+      '```',
+    ].join('\n');
+  },
+
+  // === SKILLS & RESOURCES ===
+
+  getSkills() { return []; },
+  getResources() { return []; },
+
+  // === OUTPUT ===
+
+  outputConfig: {
+    files: [
+      {
+        path: 'analysis.json',
+        format: 'json' as const,
+        required: true,
+        description: 'Team trajectory analysis with credits, coordination assessment, and lessons',
+      },
+    ],
+  },
+
+  async collectOutput(handle: WorkspaceHandle): Promise<TeamAnalysisResult> {
+    const raw = await handle.readJson('output', 'analysis.json') as Record<string, unknown>;
+
+    // Parse agent credits
+    const agentCredits: AgentCredit[] = Array.isArray(raw.agentCredits)
+      ? (raw.agentCredits as Record<string, unknown>[]).map((c) => ({
+          agentId: String(c.agentId ?? ''),
+          role: String(c.role ?? ''),
+          contributionScore: Number(c.contributionScore ?? 0),
+          assessment: String(c.assessment ?? ''),
+          roleAssessment: (['essential', 'helpful', 'neutral', 'redundant'].includes(
+            String(c.roleAssessment)
+          )
+            ? String(c.roleAssessment)
+            : 'neutral') as AgentCredit['roleAssessment'],
+        }))
+      : [];
+
+    // Parse interaction credits
+    const interactionCredits: InteractionCredit[] = Array.isArray(raw.interactionCredits)
+      ? (raw.interactionCredits as Record<string, unknown>[]).map((c) => ({
+          interactionId: String(c.interactionId ?? ''),
+          fromRole: String(c.fromRole ?? ''),
+          toRole: String(c.toRole ?? ''),
+          value: (['helpful', 'neutral', 'harmful'].includes(String(c.value))
+            ? String(c.value)
+            : 'neutral') as InteractionCredit['value'],
+          creditScore: Number(c.creditScore ?? 0),
+          reasoning: String(c.reasoning ?? ''),
+          necessity: (['critical', 'useful', 'unnecessary', 'harmful'].includes(
+            String(c.necessity)
+          )
+            ? String(c.necessity)
+            : 'useful') as InteractionCredit['necessity'],
+        }))
+      : [];
+
+    // Parse coordination assessment
+    const coordRaw = (raw.coordinationAssessment ?? {}) as Record<string, unknown>;
+    const coordinationAssessment: CoordinationAssessment = {
+      quality: (['excellent', 'good', 'acceptable', 'poor'].includes(
+        String(coordRaw.quality)
+      )
+        ? String(coordRaw.quality)
+        : 'acceptable') as CoordinationAssessment['quality'],
+      observedPatterns: Array.isArray(coordRaw.observedPatterns)
+        ? (coordRaw.observedPatterns as Record<string, unknown>[]).map((p) => ({
+            name: String(p.name ?? ''),
+            description: String(p.description ?? ''),
+            correlatedWithSuccess: Boolean(p.correlatedWithSuccess),
+          }))
+        : [],
+      observedAntiPatterns: Array.isArray(coordRaw.observedAntiPatterns)
+        ? (coordRaw.observedAntiPatterns as Record<string, unknown>[]).map((p) => ({
+            name: String(p.name ?? ''),
+            description: String(p.description ?? ''),
+            impact: String(p.impact ?? ''),
+            suggestedFix: String(p.suggestedFix ?? ''),
+          }))
+        : [],
+      narrative: String(coordRaw.narrative ?? ''),
+    };
+
+    // Parse role lessons
+    const roleLessons: RoleLessonEntry[] = Array.isArray(raw.roleLessons)
+      ? (raw.roleLessons as Record<string, unknown>[]).map((r) => ({
+          role: String(r.role ?? ''),
+          strengths: Array.isArray(r.strengths) ? r.strengths.map(String) : [],
+          improvements: Array.isArray(r.improvements) ? r.improvements.map(String) : [],
+        }))
+      : [];
+
+    // Parse team lessons
+    const teamLessons: TeamLessonEntry[] = Array.isArray(raw.teamLessons)
+      ? (raw.teamLessons as Record<string, unknown>[]).map((l) => ({
+          category: (['composition', 'coordination', 'delegation', 'communication'].includes(
+            String(l.category)
+          )
+            ? String(l.category)
+            : 'coordination') as TeamLessonEntry['category'],
+          lesson: String(l.lesson ?? ''),
+          evidence: String(l.evidence ?? ''),
+          confidence: Number(l.confidence ?? 0.5),
+        }))
+      : [];
+
+    // Parse meta-observation
+    const metaRaw = (raw.metaObservation ?? {}) as Record<string, unknown>;
+    const metaObservation: TeamMetaObservationEntry = {
+      formationEffective: Boolean(metaRaw.formationEffective),
+      teamSizeAssessment: (['too-small', 'right-sized', 'too-large'].includes(
+        String(metaRaw.teamSizeAssessment)
+      )
+        ? String(metaRaw.teamSizeAssessment)
+        : 'right-sized') as TeamMetaObservationEntry['teamSizeAssessment'],
+      topologyAssessment: (['effective', 'neutral', 'hindering'].includes(
+        String(metaRaw.topologyAssessment)
+      )
+        ? String(metaRaw.topologyAssessment)
+        : 'neutral') as TeamMetaObservationEntry['topologyAssessment'],
+      formationSuggestions: Array.isArray(metaRaw.formationSuggestions)
+        ? metaRaw.formationSuggestions.map(String)
+        : [],
+      coordinationSuggestions: Array.isArray(metaRaw.coordinationSuggestions)
+        ? metaRaw.coordinationSuggestions.map(String)
+        : [],
+    };
+
+    return {
+      teamTrajectoryId: '', // Filled by pipeline from input
+      agentCredits,
+      interactionCredits,
+      coordinationAssessment,
+      roleLessons,
+      teamLessons,
+      metaObservation,
+      analysisMetrics: {
+        analysisTokens: 0,
+        analysisTimeMs: 0,
+        analysisToolCalls: 0,
+      },
+    };
+  },
+
+  async processOutput(
+    _output: TeamAnalysisResult,
+    _input: TeamTrajectoryAnalysisInput,
+    _context: ProcessingContext
+  ): Promise<void> {
+    // Pipeline handles storage
+  },
+
+  // === COMPUTE ===
+
+  computeRequirements: {
+    mode: 'local',
+    complexity: 'standard',
+  },
+
+  getComputeRequirements(
+    _input: TeamTrajectoryAnalysisInput,
+    complexity: AnalysisComplexity
+  ): ComputeRequirements {
+    return {
+      mode: 'local',
+      complexity,
+      timeout: complexity === 'standard' ? 300_000 : 180_000,
+    };
+  },
+
+  // === CONFIG ===
+
+  agentType: 'claude-code',
+  timeout: 300_000,
+  captureToolCalls: true,
+};