refactored debug log for ai-collab

packages/framework/ai-collab/api-report/ai-collab.alpha.api.md

@@ -48,13 +48,9 @@ export function createMergableIdDiffSeries(oldObject: unknown, diffs: Difference
 
 // @alpha
 export interface DebugEvent {
-    // (undocumented)
     eventName?: string;
-    // (undocumented)
     id: string;
-    // (undocumented)
     timestamp: string;
-    // (undocumented)
     traceId?: string;
 }
 

packages/framework/ai-collab/src/aiCollabApi.ts

@@ -9,22 +9,44 @@ import type OpenAI from "openai";
 
 /**
  * Core Debug event type for the ai-collab
- *
  * @alpha
  */
 export interface DebugEvent {
+	/**
+	 * The unique id of the debug event.
+	 */
 	id: string;
+	/**
+	 * An id that will be shared across all debug events that originate from the same single execution of ai-collab.
+	 * @remarks This is intended to be used to correlate all debug events that originate from the same execution
+	 */
 	traceId?: string;
+	/**
+	 * The name of the debug event.
+	 */
 	eventName?: string;
+	/**
+	 * The date and time at which the debug event was created.
+	 */
 	timestamp: string;
 }
 
 /**
  * A Debug event that marks the start or end of a single core logic flow, such as generated tree edits, planning prompt, etc.
+ * @alpha
  */
 export interface EventFlowDebugEvent extends DebugEvent {
+	/**
+	 * The name of the particular event flow.
+	 */
 	eventFlowName: string;
-	eventFlowStatus: string;
+	/**
+	 * The status of the particular event flow.
+	 */
+	eventFlowStatus: "STARTED" | "COMPLETED";
+	/**
+	 * A unique id that will be shared across all debug events that are part of the same event flow.
+	 */
 	eventFlowTraceId?: string;
 }
 

packages/framework/ai-collab/src/explicit-strategy/debugEventLogTypes.ts → packages/framework/ai-collab/src/explicit-strategy/debugEvents.ts

@@ -36,7 +36,11 @@ export interface CoreEventLoopCompletedDebugEvent extends EventFlowDebugEvent {
 	errorMessage?: string;
 }
 
-// Planning Prompt Debug events: ------------------------------------------------------
+/**
+ * ----------------------------------------------------------------------------------
+ * Planning Prompt Debug events
+ * ----------------------------------------------------------------------------------
+ */
 
 /**
  * A debug event marking the initiation of the flow for prompting an LLM to generate a plan for accomplishing the user's goal.
@@ -67,7 +71,11 @@ export interface PlanningPromptCompletedDebugEvent extends EventFlowDebugEvent {
 	llmGeneratedPlan: string | undefined;
 }
 
-// Editing System prompt Debug events: ------------------------------------------------
+/**
+ * ----------------------------------------------------------------------------------
+ * Generate Tree Edit Debug events
+ * ----------------------------------------------------------------------------------
+ */
 
 /**
  * A debug event marking the initiation of the flow for prompting an LLM to generate an edit to a SharedTree.
@@ -103,15 +111,25 @@ export interface GenerateTreeEditCompletedDebugEvent extends EventFlowDebugEvent
 	llmGeneratedEdit?: TreeEdit | null;
 }
 
-// Apply Edit Debug events: ----------------------------------------------------------
+/**
+ * ----------------------------------------------------------------------------------
+ * Apply Edit Debug events
+ * ----------------------------------------------------------------------------------
+ */
 
 /**
  * A debug event marking the successful application of an LLM generated edit to a SharedTree.
  * @alpha
  */
 export interface ApplyEditSuccessDebugEvent extends DebugEvent {
 	eventName: "APPLIED_EDIT_SUCCESS";
+	/**
+	 * A unique id that will be shared across all debug events that are part of the same event flow.
+	 */
 	eventFlowTraceId?: string;
+	/**
+	 * The TreeEdit generated by the LLM.
+	 */
 	edit: TreeEdit;
 }
 
@@ -121,13 +139,29 @@ export interface ApplyEditSuccessDebugEvent extends DebugEvent {
  */
 export interface ApplyEditFailureDebugEvent extends DebugEvent {
 	eventName: "APPLIED_EDIT_FAILURE";
+	/**
+	 * A unique id that will be shared across all debug events that are part of the same event flow.
+	 */
 	eventFlowTraceId?: string;
+	/**
+	 * The TreeEdit generated by the LLM.
+	 */
 	edit: TreeEdit;
+	/**
+	 * The error message that was thrown when attempting to apply the edit.
+	 */
 	errorMessage: string;
+	/**
+	 * The total number of sequential errors that have occurred up until this point, not including this error.
+	 */
 	sequentialErrorCount: number;
 }
 
-// Generate Final Review Debug events: ----------------------------------------------------------
+/**
+ * ----------------------------------------------------------------------------------
+ * Generate Final Review Debug events
+ * ----------------------------------------------------------------------------------
+ */
 
 /**
  * A debug event marking the initiation of the flow for prompting an LLM to complete a final review of its edits
@@ -161,6 +195,9 @@ export interface FinalReviewCompletedDebugEvent extends EventFlowDebugEvent {
 	 * to things such as invalid json.
 	 */
 	status: "success" | "failure";
+	/**
+	 * The response from the LLM in regards to whether the user's goal was accomplished.
+	 */
 	llmReviewResponse?: {
 		goalAccomplished: "yes" | "no";
 	};
@@ -174,11 +211,30 @@ export interface FinalReviewCompletedDebugEvent extends EventFlowDebugEvent {
  */
 export interface LlmApiCallDebugEvent extends DebugEvent {
 	eventName: "LLM_API_CALL";
+	/**
+	 * The event flow name that made this LLM API call.
+	 */
 	triggeringEventFlowName?: "GENERATE_PLANNING_PROMPT" | "GENERATE_TREE_EDIT" | "FINAL_REVIEW";
+	/**
+	 * The unique id that will be shared across all debug events that are part of the same event flow.
+	 * @remarks This can be used to correlate all debug events that are part of the same event flow.
+	 */
 	eventFlowTraceId?: string;
+	/**
+	 * The LLM model name that was used for the API call.
+	 */
 	modelName: string;
+	/**
+	 * The request parameters sent in the API call to the LLM.
+	 */
 	requestParams: unknown;
+	/**
+	 * The raw response from the LLM.
+	 */
 	response: unknown;
+	/**
+	 * The total number of tokens used in the API call to the LLM.
+	 */
 	tokenUsage?: {
 		promptTokens: number;
 		completionTokens: number;

packages/framework/ai-collab/src/explicit-strategy/index.ts

@@ -41,7 +41,7 @@ import {
 	type CoreEventLoopCompletedDebugEvent,
 	generateDebugEvent,
 	type PlanningPromptStartedDebugEvent,
-} from "./debugEventLogTypes.js";
+} from "./debugEvents.js";
 import { IdGenerator } from "./idGenerator.js";
 import {
 	getEditingSystemPrompt,