@townco/debugger 0.1.28 → 0.1.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@townco/debugger",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "type": "module",
   "engines": {
     "bun": ">=1.3.0"
@@ -15,24 +15,27 @@
     "check": "tsc --noEmit"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.70.0",
+    "@lancedb/lancedb": "^0.22.3",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-label": "^2.1.7",
     "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-slot": "^1.2.3",
     "@radix-ui/react-tabs": "^1.1.0",
-    "@townco/otlp-server": "0.1.28",
-    "@townco/ui": "0.1.73",
+    "@townco/otlp-server": "0.1.30",
+    "@townco/ui": "0.1.75",
     "bun-plugin-tailwind": "^0.1.2",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.545.0",
+    "openai": "^4.77.3",
     "react": "19.2.1",
     "react-dom": "19.2.1",
     "tailwind-merge": "^3.3.1",
     "zod": "^4.1.13"
   },
   "devDependencies": {
-    "@townco/tsconfig": "0.1.70",
+    "@townco/tsconfig": "0.1.72",
     "@types/bun": "latest",
     "@types/react": "^19",
     "@types/react-dom": "^19",

package/src/App.tsx

@@ -2,6 +2,7 @@ import { ThemeProvider } from "@townco/ui/gui";
 import { Component, type ReactNode } from "react";
 import "./index.css";
 import { ComparisonView } from "./pages/ComparisonView";
+import { FindSessions } from "./pages/FindSessions";
 import { SessionList } from "./pages/SessionList";
 import { SessionView } from "./pages/SessionView";
 import { TownHall } from "./pages/TownHall";
@@ -108,6 +109,11 @@ function AppContent() {
     return <TownHall />;
   }
 
+  // Route: /find-sessions
+  if (pathname === "/find-sessions") {
+    return <FindSessions />;
+  }
+
   // Default: Session list
   return <SessionList />;
 }

package/src/analysis/analyzer.ts

@@ -0,0 +1,272 @@
+/**
+ * Session analyzer - analyzes agent sessions using Claude to extract high-level insights
+ */
+
+import Anthropic from "@anthropic-ai/sdk";
+import { LLMAnalysisOutputSchema, SessionAnalysisSchema } from "./schema";
+import type {
+  AnalysisMetrics,
+  DetailedToolCall,
+  LLMAnalysisOutput,
+  PreComputedFields,
+  SessionAnalysis,
+} from "./types";
+
+// Import session types from the agent package
+type StoredSession = {
+  sessionId: string;
+  messages: SessionMessage[];
+  metadata: {
+    createdAt: string;
+    updatedAt: string;
+    agentName: string;
+  };
+  context: unknown[];
+};
+
+type SessionMessage = {
+  role: "user" | "assistant";
+  content: ContentBlock[];
+  timestamp: string;
+};
+
+type ContentBlock =
+  | { type: "text"; text: string }
+  | { type: "image"; [key: string]: unknown }
+  | {
+      type: "tool_call";
+      id: string;
+      title: string;
+      status: "pending" | "in_progress" | "completed" | "failed";
+      error?: string;
+    };
+
+const anthropic = new Anthropic({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+
+const ANALYSIS_MODEL = "claude-sonnet-4-5-20250929";
+
+const ANALYSIS_SYSTEM_PROMPT = `You are analyzing an AI agent session to provide structured insights.
+
+Your task is to analyze the session transcript and generate a structured analysis.
+
+You must respond with valid JSON matching this schema:
+{
+  "task_summary": "Brief 1-2 sentence summary of what the user wanted",
+  "intent_type": "One of: RETRIEVE_INFORMATION, RESEARCH_TOPIC, ANALYZE_DATA, SUMMARIZE_CONTENT, COMPARE_OPTIONS, CODE_GENERATION, CODE_MODIFICATION, CODE_REVIEW, DEBUG_ISSUE, REFACTOR_CODE, FILE_MANIPULATION, CONTENT_SEARCH, PLANNING, TASK_EXECUTION, TROUBLESHOOTING, CONVERSATION, OTHER",
+  "high_level_plan": "One paragraph describing the strategy the agent used",
+  "status": "One of: SUCCESS, FAILURE, ABORTED, TIMEOUT, PARTIAL_SUCCESS",
+  "answer_type": "One of: FACTUAL_RESPONSE, STRUCTURED_DATA, SUMMARY, ANALYSIS, RECOMMENDATION, CODE, FILE_MODIFICATIONS, CLARIFYING_QUESTION, ACKNOWLEDGMENT, ERROR_MESSAGE, PARTIAL_COMPLETION, NO_RESPONSE, OTHER",
+  "assessment": "2-3 sentence explanation of why you chose the status and answer_type"
+}
+
+Guidelines:
+- task_summary: Concise goal description in user's terms
+- intent_type: Primary user intent (choose most specific match)
+- high_level_plan: Describe the strategy/approach the agent followed (focus on HOW it tried to solve the task, not whether it succeeded)
+- status: Evaluate if task was completed successfully
+- answer_type: What form the final response took
+- assessment: Explain your reasoning for the status and answer_type choices (focus on OUTCOME - did it succeed, what was delivered, any issues encountered)
+
+Respond with ONLY the JSON object, no additional text.`;
+
+/**
+ * Extract pre-computed fields from session data
+ */
+function extractPreComputedFields(session: StoredSession): PreComputedFields {
+  // First user message
+  const firstUserMsg = session.messages.find(
+    (m: SessionMessage) => m.role === "user",
+  );
+  const textBlock = firstUserMsg?.content.find(
+    (c: ContentBlock) => c.type === "text",
+  );
+  const userQuery = textBlock && "text" in textBlock ? textBlock.text : "";
+
+  // Count assistant messages
+  const numSteps = session.messages.filter(
+    (m: SessionMessage) => m.role === "assistant",
+  ).length;
+
+  // Extract tool calls and tool names
+  const toolCalls: string[] = [];
+  for (const msg of session.messages) {
+    for (const block of msg.content) {
+      if (block.type === "tool_call" && "title" in block) {
+        toolCalls.push(block.title);
+      }
+    }
+  }
+
+  return {
+    userQuery,
+    numSteps,
+    numToolCalls: toolCalls.length,
+    toolsUsed: [...new Set(toolCalls)], // Unique tool names
+  };
+}
+
+/**
+ * Format conversation transcript for LLM analysis
+ */
+function formatConversationTranscript(session: StoredSession): string {
+  let transcript = "";
+
+  for (const msg of session.messages) {
+    transcript += `\n## ${msg.role.toUpperCase()}\n`;
+
+    for (const block of msg.content) {
+      if (block.type === "text") {
+        transcript += block.text + "\n";
+      } else if (block.type === "tool_call") {
+        transcript += `[Tool: ${block.title}`;
+        if (block.status === "completed") {
+          transcript += " - completed]\n";
+        } else if (block.status === "failed") {
+          transcript += ` - failed: ${block.error}]\n`;
+        } else {
+          transcript += `]\n`;
+        }
+      }
+    }
+  }
+
+  return transcript;
+}
+
+/**
+ * Build analysis prompt for the LLM
+ */
+function buildPrompt(
+  transcript: string,
+  preComputed: PreComputedFields,
+): string {
+  return `Analyze this AI agent session and provide structured insights.
+
+Session Metadata:
+- First user message: ${preComputed.userQuery.slice(0, 200)}${preComputed.userQuery.length > 200 ? "..." : ""}
+- Number of steps: ${preComputed.numSteps}
+- Number of tool calls: ${preComputed.numToolCalls}
+- Tools used: ${preComputed.toolsUsed.join(", ") || "none"}
+
+Conversation Transcript:
+${transcript}
+
+Analyze the above session and respond with the required JSON structure.`;
+}
+
+/**
+ * Extract JSON from potential markdown code blocks
+ */
+function extractJSON(text: string): string {
+  // Try to find JSON in markdown code block
+  const jsonMatch = text.match(/```(?:json)?\n([\s\S]*?)\n```/);
+  if (jsonMatch?.[1]) {
+    return jsonMatch[1];
+  }
+
+  // Otherwise return the whole text
+  return text.trim();
+}
+
+/**
+ * Options for session analysis
+ */
+export interface AnalyzeSessionOptions {
+  session: StoredSession;
+  metrics?: AnalysisMetrics;
+  toolCalls?: DetailedToolCall[];
+}
+
+/**
+ * Analyze a session using Claude
+ */
+export async function analyzeSession(
+  options: AnalyzeSessionOptions,
+): Promise<SessionAnalysis> {
+  const { session, metrics, toolCalls } = options;
+
+  // 1. Pre-compute extractable fields
+  const preComputed = extractPreComputedFields(session);
+
+  // 2. Build conversation transcript for LLM
+  const transcript = formatConversationTranscript(session);
+
+  // 3. Build analysis prompt
+  const prompt = buildPrompt(transcript, preComputed);
+
+  // 4. Call Claude
+  const response = await anthropic.messages.create({
+    model: ANALYSIS_MODEL,
+    max_tokens: 4096,
+    temperature: 0,
+    system: ANALYSIS_SYSTEM_PROMPT,
+    messages: [{ role: "user", content: prompt }],
+  });
+
+  // 5. Parse and validate response
+  const content = response.content[0];
+  if (!content) {
+    throw new Error("No content in response");
+  }
+  if (content.type !== "text") {
+    throw new Error("Unexpected response format");
+  }
+
+  // Extract JSON from potential markdown code blocks
+  const jsonText = extractJSON(content.text);
+  const parsed = JSON.parse(jsonText);
+  const llmOutput = LLMAnalysisOutputSchema.parse(parsed);
+
+  // Use provided metrics or create defaults
+  const sessionDurationMs = metrics?.durationMs ?? calculateDurationMs(session);
+  const analysisMetrics: AnalysisMetrics = metrics ?? {
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+    estimatedCost: 0,
+    durationMs: sessionDurationMs,
+  };
+
+  // Use provided tool calls or empty array
+  const detailedToolCalls: DetailedToolCall[] = toolCalls ?? [];
+
+  // 6. Combine pre-computed and LLM data
+  const analysis: SessionAnalysis = {
+    session_id: session.sessionId,
+    agent_name: session.metadata.agentName,
+    started_at: session.metadata.createdAt,
+    ended_at: session.metadata.updatedAt,
+    task: {
+      user_query: preComputed.userQuery,
+      task_summary: llmOutput.task_summary,
+      intent_type: llmOutput.intent_type,
+    },
+    trajectory: {
+      high_level_plan: llmOutput.high_level_plan,
+      tools_used: preComputed.toolsUsed,
+      num_steps: preComputed.numSteps,
+      num_tool_calls: preComputed.numToolCalls,
+      tool_calls: detailedToolCalls,
+    },
+    outcome: {
+      status: llmOutput.status,
+      answer_type: llmOutput.answer_type,
+      assessment: llmOutput.assessment,
+    },
+    metrics: analysisMetrics,
+  };
+
+  // 7. Validate final schema
+  return SessionAnalysisSchema.parse(analysis);
+}
+
+/**
+ * Calculate duration from session timestamps
+ */
+function calculateDurationMs(session: StoredSession): number {
+  const startTime = new Date(session.metadata.createdAt).getTime();
+  const endTime = new Date(session.metadata.updatedAt).getTime();
+  return endTime - startTime;
+}

package/src/analysis/embeddings.ts

@@ -0,0 +1,97 @@
+/**
+ * Session Analysis Embeddings Module
+ *
+ * Generates embeddings for session analyses using OpenAI's text-embedding-3-small model.
+ * These embeddings enable semantic search and similarity analysis of sessions.
+ */
+
+import OpenAI from "openai";
+import type { SessionAnalysis } from "./types";
+
+/**
+ * Generates structured text from a SessionAnalysis for embedding.
+ * Format captures all key aspects of the session for semantic search.
+ */
+export function generateEmbeddingText(analysis: SessionAnalysis): string {
+  const toolsList = analysis.trajectory.tools_used.join(", ");
+
+  return `Agent: ${analysis.agent_name}
+
+IntentType: ${analysis.task.intent_type}
+AnswerType: ${analysis.outcome.answer_type}
+OutcomeStatus: ${analysis.outcome.status}
+
+UserQuery:
+${analysis.task.user_query}
+
+TaskSummary:
+${analysis.task.task_summary}
+
+HighLevelPlan:
+${analysis.trajectory.high_level_plan}
+
+ToolsUsed: ${toolsList}
+NumSteps: ${analysis.trajectory.num_steps}
+NumToolCalls: ${analysis.trajectory.num_tool_calls}
+
+OutcomeAssessment:
+${analysis.outcome.assessment}`;
+}
+
+/**
+ * Generates an embedding vector for the given text using OpenAI's API.
+ * Uses text-embedding-3-small model (1536 dimensions).
+ *
+ * @throws Error if API key is missing or API call fails
+ */
+export async function generateEmbedding(
+  text: string,
+  apiKey: string,
+): Promise<Float32Array> {
+  if (!apiKey) {
+    throw new Error("OpenAI API key is required for embedding generation");
+  }
+
+  const openai = new OpenAI({ apiKey });
+
+  try {
+    const response = await openai.embeddings.create({
+      model: "text-embedding-3-small",
+      input: text,
+      encoding_format: "float",
+    });
+
+    const embedding = response.data[0]?.embedding;
+    if (!embedding) {
+      throw new Error("No embedding returned from OpenAI API");
+    }
+
+    return new Float32Array(embedding);
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(`OpenAI API error: ${error.message}`);
+    }
+    throw new Error("Unknown error generating embedding");
+  }
+}
+
+/**
+ * Convenience wrapper that generates an embedding for a SessionAnalysis.
+ * Reads OPENAI_API_KEY from environment.
+ *
+ * @throws Error if OPENAI_API_KEY is not set or API call fails
+ */
+export async function embedAnalysis(
+  analysis: SessionAnalysis,
+): Promise<Float32Array> {
+  const apiKey = process.env.OPENAI_API_KEY;
+
+  if (!apiKey) {
+    throw new Error(
+      "OPENAI_API_KEY environment variable not set. Embedding generation requires an OpenAI API key.",
+    );
+  }
+
+  const text = generateEmbeddingText(analysis);
+  return generateEmbedding(text, apiKey);
+}

package/src/analysis/schema.ts

@@ -0,0 +1,91 @@
+/**
+ * Zod schemas for session analysis validation
+ */
+
+import { z } from "zod";
+import { AnswerType, IntentType, OutcomeStatus } from "./types";
+
+/**
+ * Intent type schema
+ */
+export const IntentTypeSchema = z.nativeEnum(IntentType);
+
+/**
+ * Answer type schema
+ */
+export const AnswerTypeSchema = z.nativeEnum(AnswerType);
+
+/**
+ * Outcome status schema
+ */
+export const OutcomeStatusSchema = z.nativeEnum(OutcomeStatus);
+
+/**
+ * LLM output schema - what we expect the LLM to generate
+ */
+export const LLMAnalysisOutputSchema = z.object({
+  task_summary: z
+    .string()
+    .describe("Brief 1-2 sentence summary of what the user wanted"),
+  intent_type: IntentTypeSchema.describe("Primary user intent"),
+  high_level_plan: z
+    .string()
+    .describe("One paragraph describing the strategy the agent used"),
+  status: OutcomeStatusSchema.describe(
+    "Whether the task was completed successfully",
+  ),
+  answer_type: AnswerTypeSchema.describe("What form the final response took"),
+  assessment: z
+    .string()
+    .describe("Explanation of why the status and answer_type were chosen"),
+});
+
+/**
+ * Detailed tool call schema
+ */
+export const DetailedToolCallSchema = z.object({
+  name: z.string(),
+  input: z.unknown(),
+  output: z.unknown(),
+  startTimeUnixNano: z.number().optional(),
+  endTimeUnixNano: z.number().optional(),
+});
+
+/**
+ * Metrics schema
+ */
+export const AnalysisMetricsSchema = z.object({
+  inputTokens: z.number(),
+  outputTokens: z.number(),
+  totalTokens: z.number(),
+  estimatedCost: z.number(),
+  durationMs: z.number(),
+});
+
+/**
+ * Complete session analysis schema
+ */
+export const SessionAnalysisSchema = z.object({
+  session_id: z.string(),
+  agent_name: z.string(),
+  started_at: z.string(),
+  ended_at: z.string(),
+  task: z.object({
+    user_query: z.string(),
+    task_summary: z.string(),
+    intent_type: IntentTypeSchema,
+  }),
+  trajectory: z.object({
+    high_level_plan: z.string(),
+    tools_used: z.array(z.string()),
+    num_steps: z.number(),
+    num_tool_calls: z.number(),
+    tool_calls: z.array(DetailedToolCallSchema),
+  }),
+  outcome: z.object({
+    status: OutcomeStatusSchema,
+    answer_type: AnswerTypeSchema,
+    assessment: z.string(),
+  }),
+  metrics: AnalysisMetricsSchema,
+});

package/src/analysis/types.ts

@@ -0,0 +1,157 @@
+/**
+ * Session Analysis Types
+ *
+ * This module defines the types for analyzing AI agent sessions to extract
+ * high-level insights about task execution and trajectory.
+ */
+
+/**
+ * Intent types - What the user wanted to accomplish
+ */
+export enum IntentType {
+  // Information & Research
+  RETRIEVE_INFORMATION = "RETRIEVE_INFORMATION", // Lookup facts/data
+  RESEARCH_TOPIC = "RESEARCH_TOPIC", // Deep investigation
+
+  // Data & Analysis
+  ANALYZE_DATA = "ANALYZE_DATA", // Examine/interpret data
+  SUMMARIZE_CONTENT = "SUMMARIZE_CONTENT", // Condense information
+  COMPARE_OPTIONS = "COMPARE_OPTIONS", // Evaluate alternatives
+
+  // Code & Development
+  CODE_GENERATION = "CODE_GENERATION", // Write new code
+  CODE_MODIFICATION = "CODE_MODIFICATION", // Edit existing code
+  CODE_REVIEW = "CODE_REVIEW", // Analyze code quality
+  DEBUG_ISSUE = "DEBUG_ISSUE", // Fix bugs
+  REFACTOR_CODE = "REFACTOR_CODE", // Improve structure
+
+  // File Operations
+  FILE_MANIPULATION = "FILE_MANIPULATION", // Create/edit/move files
+  CONTENT_SEARCH = "CONTENT_SEARCH", // Find in files
+
+  // Task Management
+  PLANNING = "PLANNING", // Create task plans
+  TASK_EXECUTION = "TASK_EXECUTION", // Complete multi-step task
+
+  // System & Troubleshooting
+  TROUBLESHOOTING = "TROUBLESHOOTING", // Diagnose problems
+
+  // Meta
+  CONVERSATION = "CONVERSATION", // General chat
+  OTHER = "OTHER", // Fallback
+}
+
+/**
+ * Answer types - What form the agent's response took
+ */
+export enum AnswerType {
+  // Direct responses
+  FACTUAL_RESPONSE = "FACTUAL_RESPONSE", // Direct facts/data
+  STRUCTURED_DATA = "STRUCTURED_DATA", // JSON/tables
+  SUMMARY = "SUMMARY", // Condensed information
+  ANALYSIS = "ANALYSIS", // Interpretation/insights
+  RECOMMENDATION = "RECOMMENDATION", // Suggested actions
+
+  // Artifacts
+  CODE = "CODE", // Code snippets/files
+  FILE_MODIFICATIONS = "FILE_MODIFICATIONS", // Changed files
+
+  // Interactive
+  CLARIFYING_QUESTION = "CLARIFYING_QUESTION", // Needs more input
+  ACKNOWLEDGMENT = "ACKNOWLEDGMENT", // Confirmed action
+
+  // Status
+  ERROR_MESSAGE = "ERROR_MESSAGE", // Failed with error
+  PARTIAL_COMPLETION = "PARTIAL_COMPLETION", // Incomplete success
+
+  // Empty
+  NO_RESPONSE = "NO_RESPONSE", // Aborted/timeout
+  OTHER = "OTHER", // Fallback
+}
+
+/**
+ * Outcome status - Whether the task was completed successfully
+ */
+export enum OutcomeStatus {
+  SUCCESS = "SUCCESS", // Completed successfully
+  FAILURE = "FAILURE", // Failed with error
+  ABORTED = "ABORTED", // User cancelled
+  TIMEOUT = "TIMEOUT", // Exceeded time limit
+  PARTIAL_SUCCESS = "PARTIAL_SUCCESS", // Some goals achieved
+}
+
+/**
+ * Detailed tool call with input/output
+ */
+export interface DetailedToolCall {
+  name: string;
+  input: unknown;
+  output: unknown;
+  startTimeUnixNano?: number | undefined;
+  endTimeUnixNano?: number | undefined;
+}
+
+/**
+ * Session metrics (tokens, cost, etc.)
+ */
+export interface AnalysisMetrics {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  estimatedCost: number;
+  durationMs: number;
+}
+
+/**
+ * Complete session analysis result
+ */
+export interface SessionAnalysis {
+  session_id: string;
+  agent_name: string;
+  started_at: string; // ISO8601
+  ended_at: string; // ISO8601
+
+  task: {
+    user_query: string; // First user message text
+    task_summary: string; // LLM-generated summary
+    intent_type: IntentType; // LLM-selected from enum
+  };
+
+  trajectory: {
+    high_level_plan: string; // LLM-generated paragraph
+    tools_used: string[]; // Pre-computed from tool calls
+    num_steps: number; // Pre-computed (count assistant messages)
+    num_tool_calls: number; // Pre-computed
+    tool_calls: DetailedToolCall[]; // Detailed tool call info with args/results
+  };
+
+  outcome: {
+    status: OutcomeStatus; // LLM-selected from enum
+    answer_type: AnswerType; // LLM-selected from enum
+    assessment: string; // LLM-generated explanation of status and answer_type
+  };
+
+  metrics: AnalysisMetrics; // Token counts, cost, duration
+}
+
+/**
+ * LLM output schema (what the LLM generates)
+ */
+export interface LLMAnalysisOutput {
+  task_summary: string;
+  intent_type: IntentType;
+  high_level_plan: string;
+  status: OutcomeStatus;
+  answer_type: AnswerType;
+  assessment: string;
+}
+
+/**
+ * Pre-computed fields (extracted from session data)
+ */
+export interface PreComputedFields {
+  userQuery: string;
+  numSteps: number;
+  numToolCalls: number;
+  toolsUsed: string[];
+}