@axplusb/kepler 0.0.1 → 1.0.0

package/pulse/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

package/pulse/types/claude.ts

@@ -0,0 +1,294 @@
+// ─── Stats Cache ─────────────────────────────────────────────────────────────
+
+export interface DailyActivity {
+  date: string
+  messageCount: number
+  sessionCount: number
+  toolCallCount: number
+}
+
+export interface DailyTokens {
+  date: string
+  tokensByModel: Record<string, number>
+}
+
+export interface ModelUsage {
+  inputTokens: number
+  outputTokens: number
+  cacheReadInputTokens: number
+  cacheCreationInputTokens: number
+  costUSD: number
+  webSearchRequests: number
+}
+
+export interface LongestSession {
+  sessionId: string
+  duration: number
+  messageCount: number
+  timestamp: string
+}
+
+export interface StatsCache {
+  version: number
+  lastComputedDate: string
+  dailyActivity: DailyActivity[]
+  tokensByDate: DailyTokens[]
+  dailyModelTokens?: DailyTokens[]
+  modelUsage: Record<string, ModelUsage>
+  totalSessions: number
+  totalMessages: number
+  longestSession: LongestSession
+  firstSessionDate: string
+  hourCounts: Record<string, number>
+  totalSpeculationTimeSavedMs: number
+}
+
+// ─── Session Meta ─────────────────────────────────────────────────────────────
+
+export interface SessionMeta {
+  session_id: string
+  project_path: string
+  start_time: string
+  duration_minutes: number
+  user_message_count: number
+  assistant_message_count: number
+  tool_counts: Record<string, number>
+  languages: Record<string, number>
+  git_commits: number
+  git_pushes: number
+  input_tokens: number
+  output_tokens: number
+  cache_creation_input_tokens?: number
+  cache_read_input_tokens?: number
+  first_prompt: string
+  user_interruptions: number
+  user_response_times: number[]
+  tool_errors: number
+  tool_error_categories: Record<string, number>
+  uses_task_agent: boolean
+  uses_mcp: boolean
+  uses_web_search: boolean
+  uses_web_fetch: boolean
+  lines_added: number
+  lines_removed: number
+  files_modified: number
+  message_hours: number[]
+  user_message_timestamps: string[]
+}
+
+// ─── Facets ──────────────────────────────────────────────────────────────────
+
+export interface Facet {
+  session_id: string
+  underlying_goal: string
+  goal_categories: Record<string, number>
+  outcome: string
+  user_satisfaction_counts: Record<string, number>
+  claude_helpfulness: string
+  session_type: string
+  friction_counts: Record<string, number>
+  friction_detail: string
+  primary_success: string
+  brief_summary: string
+}
+
+// ─── Session with Facet joined ───────────────────────────────────────────────
+
+export interface SessionWithFacet extends SessionMeta {
+  facet?: Facet
+  estimated_cost: number
+  slug?: string
+  version?: string
+  git_branch?: string
+  has_compaction?: boolean
+  has_thinking?: boolean
+}
+
+// ─── Replay / JSONL ──────────────────────────────────────────────────────────
+
+export interface TurnUsage {
+  input_tokens: number
+  output_tokens: number
+  cache_creation_input_tokens: number
+  cache_read_input_tokens: number
+  cache_creation?: {
+    ephemeral_5m_input_tokens: number
+    ephemeral_1h_input_tokens: number
+  }
+  service_tier?: string
+  inference_geo?: string
+}
+
+export interface ToolCall {
+  id: string
+  name: string
+  input: Record<string, unknown>
+  result?: string
+  is_error?: boolean
+}
+
+export interface ReplayTurn {
+  uuid: string
+  parentUuid: string | null
+  type: 'user' | 'assistant'
+  timestamp: string
+  model?: string
+  usage?: TurnUsage
+  text?: string
+  tool_calls?: ToolCall[]
+  tool_results?: Array<{ tool_use_id: string; content: string; is_error: boolean }>
+  has_thinking?: boolean
+  thinking_text?: string
+  estimated_cost?: number
+  turn_duration_ms?: number
+  response_time_s?: number
+}
+
+export interface CompactionEvent {
+  uuid: string
+  timestamp: string
+  trigger: 'auto' | 'manual'
+  pre_tokens: number
+  summary?: string
+  turn_index: number
+}
+
+export interface SummaryEvent {
+  uuid: string
+  summary: string
+  leaf_uuid: string
+}
+
+export interface ReplayData {
+  session_id: string
+  slug?: string
+  version?: string
+  git_branch?: string
+  turns: ReplayTurn[]
+  compactions: CompactionEvent[]
+  summaries: SummaryEvent[]
+  total_cost: number
+}
+
+// ─── Project Summary ──────────────────────────────────────────────────────────
+
+export interface ProjectSummary {
+  slug: string
+  project_path: string
+  display_name: string
+  session_count: number
+  total_messages: number
+  total_duration_minutes: number
+  total_lines_added: number
+  total_lines_removed: number
+  total_files_modified: number
+  git_commits: number
+  git_pushes: number
+  estimated_cost: number
+  input_tokens: number
+  output_tokens: number
+  languages: Record<string, number>
+  tool_counts: Record<string, number>
+  last_active: string
+  first_active: string
+  uses_mcp: boolean
+  uses_task_agent: boolean
+  branches: string[]
+}
+
+// ─── Tool Analytics ───────────────────────────────────────────────────────────
+
+export interface ToolSummary {
+  name: string
+  category: string
+  total_calls: number
+  session_count: number
+  error_count: number
+}
+
+export interface McpServerSummary {
+  server_name: string
+  tools: Array<{ name: string; calls: number }>
+  total_calls: number
+  session_count: number
+}
+
+export interface VersionRecord {
+  version: string
+  session_count: number
+  first_seen: string
+  last_seen: string
+}
+
+export interface ToolsAnalytics {
+  tools: ToolSummary[]
+  mcp_servers: McpServerSummary[]
+  feature_adoption: Record<string, { sessions: number; pct: number }>
+  versions: VersionRecord[]
+  branches: Array<{ branch: string; turns: number }>
+  error_categories: Record<string, number>
+  total_tool_calls: number
+  total_errors: number
+}
+
+// ─── Cost Analytics ───────────────────────────────────────────────────────────
+
+export interface ModelCostBreakdown {
+  model: string
+  input_tokens: number
+  output_tokens: number
+  cache_write_tokens: number
+  cache_read_tokens: number
+  estimated_cost: number
+  cache_savings: number
+  cache_hit_rate: number
+}
+
+export interface DailyCost {
+  date: string
+  costs: Record<string, number>
+  total: number
+}
+
+export interface ProjectCost {
+  slug: string
+  display_name: string
+  estimated_cost: number
+  input_tokens: number
+  output_tokens: number
+}
+
+export interface CostAnalytics {
+  total_cost: number
+  total_savings: number
+  models: ModelCostBreakdown[]
+  daily: DailyCost[]
+  by_project: ProjectCost[]
+}
+
+// ─── History ──────────────────────────────────────────────────────────────────
+
+export interface HistoryEntry {
+  display: string
+  timestamp: number
+  project: string
+  sessionId?: string
+}
+
+// ─── Export ──────────────────────────────────────────────────────────────────
+
+export interface ExportPayload {
+  exportedAt: string
+  version: string
+  stats: StatsCache | null
+  sessions: SessionMeta[]
+  facets: Facet[]
+  history: HistoryEntry[]
+}
+
+export interface ImportDiff {
+  total_in_export: number
+  already_present: number
+  new_sessions: number
+  sessions_to_add: SessionMeta[]
+}

package/src/agents/loader.mjs

@@ -0,0 +1,89 @@
+/**
+ * Agent Loader — loads custom agent definitions from .claude/agents/
+ *
+ * Supports two formats:
+ * - JSON: .claude/agents/*.json
+ * - Markdown with YAML frontmatter: .claude/agents/*.md
+ *
+ * Agent definitions specify: name, description, model, tools, hooks, prompt.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { parseAgentDefinition } from './parser.mjs';
+
+export class AgentLoader {
+    constructor() {
+        this.agents = new Map();
+        this.searchPaths = [];
+    }
+
+    /**
+     * Load agents from standard directories.
+     * @param {string} [cwd] - project working directory
+     */
+    load(cwd = process.cwd()) {
+        this.searchPaths = [
+            path.join(cwd, '.claude', 'agents'),
+            path.join(process.env.HOME || '', '.claude', 'agents'),
+        ];
+
+        for (const dir of this.searchPaths) {
+            this._loadFromDir(dir);
+        }
+
+        return this;
+    }
+
+    _loadFromDir(dir) {
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile()) continue;
+                const ext = path.extname(entry.name);
+                if (ext !== '.json' && ext !== '.md') continue;
+
+                const filePath = path.join(dir, entry.name);
+                try {
+                    const content = fs.readFileSync(filePath, 'utf-8');
+                    const agent = parseAgentDefinition(content, ext);
+                    if (agent && agent.name) {
+                        this.agents.set(agent.name, { ...agent, source: filePath });
+                    }
+                } catch (err) {
+                    if (process.env.DEBUG) {
+                        console.error(`Failed to load agent ${filePath}: ${err.message}`);
+                    }
+                }
+            }
+        } catch {
+            // Directory does not exist
+        }
+    }
+
+    /**
+     * Get an agent definition by name.
+     * @param {string} name
+     * @returns {object|null}
+     */
+    get(name) {
+        return this.agents.get(name) || null;
+    }
+
+    /**
+     * List all loaded agents.
+     * @returns {Array<object>}
+     */
+    list() {
+        return [...this.agents.values()];
+    }
+
+    /**
+     * Check if an agent exists.
+     * @param {string} name
+     * @returns {boolean}
+     */
+    has(name) {
+        return this.agents.has(name);
+    }
+}

package/src/agents/parser.mjs

@@ -0,0 +1,98 @@
+/**
+ * Agent Parser — parses agent definitions from JSON and Markdown formats.
+ *
+ * JSON format:
+ * {
+ *   "name": "my-agent",
+ *   "description": "Does things",
+ *   "model": "claude-sonnet-4-6",
+ *   "tools": ["Bash", "Read", "Write"],
+ *   "hooks": { ... },
+ *   "prompt": "You are a specialized agent..."
+ * }
+ *
+ * Markdown format (YAML frontmatter):
+ * ---
+ * name: my-agent
+ * description: Does things
+ * model: claude-sonnet-4-6
+ * tools: [Bash, Read, Write]
+ * ---
+ * You are a specialized agent...
+ */
+
+/**
+ * Parse an agent definition from file content.
+ * @param {string} content - file content
+ * @param {string} ext - file extension (.json or .md)
+ * @returns {object} agent definition
+ */
+export function parseAgentDefinition(content, ext) {
+    if (ext === '.json') {
+        return parseJsonAgent(content);
+    }
+    if (ext === '.md') {
+        return parseMarkdownAgent(content);
+    }
+    throw new Error(`Unsupported agent format: ${ext}`);
+}
+
+function parseJsonAgent(content) {
+    const data = JSON.parse(content);
+    return normalizeAgent(data);
+}
+
+function parseMarkdownAgent(content) {
+    const { frontmatter, body } = parseFrontmatter(content);
+    return normalizeAgent({ ...frontmatter, prompt: body });
+}
+
+/**
+ * Parse YAML-like frontmatter from markdown.
+ * Simple key-value parser (no full YAML dependency).
+ */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*\n([\s\S]*)$/);
+    if (!match) {
+        return { frontmatter: {}, body: content };
+    }
+
+    const yamlBlock = match[1];
+    const body = match[2].trim();
+    const frontmatter = {};
+
+    for (const line of yamlBlock.split('\n')) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1) continue;
+
+        const key = line.slice(0, colonIdx).trim();
+        let value = line.slice(colonIdx + 1).trim();
+
+        // Parse arrays: [a, b, c]
+        if (value.startsWith('[') && value.endsWith(']')) {
+            value = value.slice(1, -1).split(',').map(s => s.trim()).filter(Boolean);
+        }
+        // Parse booleans
+        else if (value === 'true') value = true;
+        else if (value === 'false') value = false;
+        // Parse numbers
+        else if (/^\d+$/.test(value)) value = parseInt(value, 10);
+
+        frontmatter[key] = value;
+    }
+
+    return { frontmatter, body };
+}
+
+function normalizeAgent(data) {
+    return {
+        name: data.name || 'unnamed',
+        description: data.description || '',
+        model: data.model || null,
+        tools: Array.isArray(data.tools) ? data.tools : [],
+        hooks: data.hooks || {},
+        prompt: data.prompt || '',
+        maxTurns: data.maxTurns || data.max_turns || 10,
+        temperature: data.temperature || undefined,
+    };
+}

package/src/agents/teams.mjs

@@ -0,0 +1,123 @@
+/**
+ * Agent Teams — multi-agent coordination.
+ *
+ * Allows registering named agents that can communicate via messages.
+ * Each teammate is an agent loop that can be invoked with a prompt.
+ */
+
+export class AgentTeams {
+    constructor() {
+        /** @type {Map<string, { loop: object, role?: string, status: string }>} */
+        this.teammates = new Map();
+        this.messageLog = [];
+    }
+
+    /**
+     * Register a named agent.
+     * @param {string} name - unique agent name
+     * @param {object} agentLoop - agent loop with .run() async generator
+     * @param {object} [options]
+     * @param {string} [options.role] - agent role description
+     */
+    register(name, agentLoop, options = {}) {
+        if (this.teammates.has(name)) {
+            throw new Error(`Agent "${name}" is already registered`);
+        }
+        this.teammates.set(name, {
+            loop: agentLoop,
+            role: options.role || 'general',
+            status: 'idle',
+        });
+    }
+
+    /**
+     * Unregister an agent.
+     * @param {string} name
+     * @returns {boolean}
+     */
+    unregister(name) {
+        return this.teammates.delete(name);
+    }
+
+    /**
+     * Send a message to a teammate and collect all events.
+     * @param {string} to - target agent name
+     * @param {string} message - prompt to send
+     * @returns {Promise<Array<object>>} collected events
+     */
+    async sendMessage(to, message) {
+        const agent = this.teammates.get(to);
+        if (!agent) throw new Error(`Unknown teammate: ${to}`);
+
+        agent.status = 'running';
+        const results = [];
+
+        try {
+            for await (const event of agent.loop.run(message)) {
+                results.push(event);
+            }
+        } finally {
+            agent.status = 'idle';
+        }
+
+        this.messageLog.push({
+            to,
+            message: message.substring(0, 100),
+            resultCount: results.length,
+            timestamp: new Date().toISOString(),
+        });
+
+        return results;
+    }
+
+    /**
+     * Broadcast a message to all teammates.
+     * @param {string} message
+     * @returns {Promise<Map<string, Array<object>>>} results per agent
+     */
+    async broadcast(message) {
+        const results = new Map();
+        const promises = [];
+
+        for (const [name] of this.teammates) {
+            promises.push(
+                this.sendMessage(name, message)
+                    .then(events => results.set(name, events))
+                    .catch(err => results.set(name, [{ type: 'error', message: err.message }]))
+            );
+        }
+
+        await Promise.all(promises);
+        return results;
+    }
+
+    /**
+     * List all registered teammates.
+     * @returns {Array<{ name: string, role: string, status: string }>}
+     */
+    list() {
+        return [...this.teammates.entries()].map(([name, info]) => ({
+            name,
+            role: info.role,
+            status: info.status,
+        }));
+    }
+
+    /**
+     * Get the message log.
+     * @param {number} [limit] - max entries to return
+     * @returns {Array<object>}
+     */
+    getMessageLog(limit) {
+        if (limit) return this.messageLog.slice(-limit);
+        return [...this.messageLog];
+    }
+
+    /**
+     * Get count of registered teammates.
+     * @returns {number}
+     */
+    size() {
+        return this.teammates.size;
+    }
+}