profclaw 0.0.1-beta.1

package/dist/types/summary.js

@@ -0,0 +1,137 @@
+/**
+ * Structured Summary Types
+ *
+ * Schemas for AI work summaries. Replaces random MD files with
+ * structured, queryable data about what AI agents did.
+ */
+import { z } from 'zod';
+/**
+ * File change record
+ */
+export const FileChangeSchema = z.object({
+    path: z.string(),
+    action: z.enum(['created', 'modified', 'deleted', 'renamed']),
+    linesAdded: z.number().optional(),
+    linesRemoved: z.number().optional(),
+    oldPath: z.string().optional(), // For renames
+});
+/**
+ * Decision made during task execution
+ */
+export const DecisionSchema = z.object({
+    description: z.string(),
+    reason: z.string().optional(),
+    alternatives: z.array(z.string()).optional(),
+    confidence: z.number().min(0).max(1).optional(),
+});
+/**
+ * Blocker or issue encountered
+ */
+export const BlockerSchema = z.object({
+    description: z.string(),
+    severity: z.enum(['info', 'warning', 'error', 'critical']),
+    resolved: z.boolean().default(false),
+    resolution: z.string().optional(),
+});
+/**
+ * Artifact produced by the work
+ */
+export const ArtifactReferenceSchema = z.object({
+    type: z.enum(['commit', 'pull_request', 'branch', 'file', 'comment', 'deployment', 'other']),
+    url: z.string().optional(),
+    identifier: z.string().optional(), // SHA, PR number, etc.
+    title: z.string().optional(),
+    metadata: z.record(z.unknown()).optional(),
+});
+/**
+ * Full structured summary
+ */
+export const SummarySchema = z.object({
+    // Identity
+    id: z.string(),
+    taskId: z.string().optional(),
+    sessionId: z.string().optional(),
+    // Timing
+    createdAt: z.coerce.date(),
+    startedAt: z.coerce.date().optional(),
+    completedAt: z.coerce.date().optional(),
+    durationMs: z.number().optional(),
+    // Agent info
+    agent: z.string(), // 'claude-code', 'openclaw', etc.
+    model: z.string().optional(),
+    // Content
+    title: z.string(),
+    whatChanged: z.string(), // High-level summary
+    whyChanged: z.string().optional(), // Motivation
+    howChanged: z.string().optional(), // Technical approach
+    // Structured data
+    filesChanged: z.array(FileChangeSchema).default([]),
+    decisions: z.array(DecisionSchema).default([]),
+    blockers: z.array(BlockerSchema).default([]),
+    artifacts: z.array(ArtifactReferenceSchema).default([]),
+    // Metrics
+    tokensUsed: z.object({
+        input: z.number(),
+        output: z.number(),
+        total: z.number(),
+    }).optional(),
+    cost: z.object({
+        amount: z.number(),
+        currency: z.string().default('USD'),
+    }).optional(),
+    // Classification
+    taskType: z.string().optional(), // 'feature', 'bugfix', 'refactor', etc.
+    component: z.string().optional(), // 'auth', 'api', 'ui', etc.
+    labels: z.array(z.string()).default([]),
+    // Links
+    linkedIssue: z.string().optional(), // GitHub/Jira/Linear issue
+    linkedPr: z.string().optional(),
+    repository: z.string().optional(),
+    branch: z.string().optional(),
+    // Raw content (for search)
+    rawOutput: z.string().optional(), // Full agent output - lazy loaded from summary_blobs
+    // Blob storage flag (Phase 17)
+    hasBlobOutput: z.boolean().optional(), // True if rawOutput is in summary_blobs table
+    // Metadata
+    metadata: z.record(z.unknown()).optional(),
+});
+/**
+ * Input for creating a new summary
+ */
+export const CreateSummaryInputSchema = SummarySchema.omit({
+    id: true,
+    createdAt: true,
+}).partial({
+    filesChanged: true,
+    decisions: true,
+    blockers: true,
+    artifacts: true,
+    labels: true,
+});
+/**
+ * Query parameters for searching summaries
+ */
+export const SummaryQuerySchema = z.object({
+    // Filters
+    taskId: z.string().optional(),
+    sessionId: z.string().optional(),
+    agent: z.string().optional(),
+    taskType: z.string().optional(),
+    component: z.string().optional(),
+    repository: z.string().optional(),
+    // Date range
+    from: z.coerce.date().optional(),
+    to: z.coerce.date().optional(),
+    // Text search
+    search: z.string().optional(),
+    // Pagination
+    limit: z.number().min(1).max(100).default(50),
+    offset: z.number().min(0).default(0),
+    // Cursor-based pagination (Phase 17)
+    cursorCreatedAt: z.date().optional(),
+    cursorId: z.string().optional(),
+    // Sorting
+    sortBy: z.enum(['createdAt', 'durationMs', 'cost']).default('createdAt'),
+    sortOrder: z.enum(['asc', 'desc']).default('desc'),
+});
+//# sourceMappingURL=summary.js.map

package/dist/types/task.d.ts

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+export declare const TaskPriority: {
+    readonly CRITICAL: 1;
+    readonly HIGH: 2;
+    readonly MEDIUM: 3;
+    readonly LOW: 4;
+};
+export type TaskPriorityType = (typeof TaskPriority)[keyof typeof TaskPriority];
+export declare const TaskStatus: {
+    readonly PENDING: "pending";
+    readonly QUEUED: "queued";
+    readonly ASSIGNED: "assigned";
+    readonly IN_PROGRESS: "in_progress";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+    readonly CANCELLED: "cancelled";
+};
+export type TaskStatusType = (typeof TaskStatus)[keyof typeof TaskStatus];
+export declare const TaskSource: {
+    readonly GITHUB_ISSUE: "github_issue";
+    readonly GITHUB_PR: "github_pr";
+    readonly JIRA: "jira";
+    readonly LINEAR: "linear";
+    readonly SLACK: "slack";
+    readonly DISCORD: "discord";
+    readonly TELEGRAM: "telegram";
+    readonly API: "api";
+    readonly MANUAL: "manual";
+};
+export type TaskSourceType = (typeof TaskSource)[keyof typeof TaskSource];
+export declare const CreateTaskSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodString;
+    priority: z.ZodDefault<z.ZodNumber>;
+    source: z.ZodString;
+    sourceId: z.ZodOptional<z.ZodString>;
+    sourceUrl: z.ZodOptional<z.ZodString>;
+    repository: z.ZodOptional<z.ZodString>;
+    branch: z.ZodOptional<z.ZodString>;
+    labels: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    assignedAgent: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    prompt: string;
+    priority: number;
+    source: string;
+    labels: string[];
+    metadata: Record<string, unknown>;
+    description?: string | undefined;
+    sourceId?: string | undefined;
+    sourceUrl?: string | undefined;
+    repository?: string | undefined;
+    branch?: string | undefined;
+    assignedAgent?: string | undefined;
+}, {
+    title: string;
+    prompt: string;
+    source: string;
+    description?: string | undefined;
+    priority?: number | undefined;
+    sourceId?: string | undefined;
+    sourceUrl?: string | undefined;
+    repository?: string | undefined;
+    branch?: string | undefined;
+    labels?: string[] | undefined;
+    assignedAgent?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+export type CreateTaskInput = z.infer<typeof CreateTaskSchema>;
+export interface Task extends CreateTaskInput {
+    id: string;
+    status: TaskStatusType;
+    createdAt: Date;
+    updatedAt: Date;
+    startedAt?: Date;
+    completedAt?: Date;
+    assignedAgentId?: string;
+    ticketId?: string;
+    result?: TaskResult;
+    attempts: number;
+    maxAttempts: number;
+}
+export interface TaskResult {
+    success: boolean;
+    output: string;
+    artifacts?: TaskArtifact[];
+    tokensUsed?: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    cost?: {
+        amount: number;
+        currency: string;
+    };
+    duration?: number;
+    error?: {
+        code: string;
+        message: string;
+        stack?: string;
+    };
+    metadata?: Record<string, unknown>;
+}
+export interface TaskArtifact {
+    type: 'commit' | 'pull_request' | 'file' | 'comment' | 'branch' | 'other';
+    url?: string;
+    sha?: string;
+    path?: string;
+    content?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface TaskEvent {
+    id: string;
+    taskId: string;
+    type: 'created' | 'queued' | 'assigned' | 'started' | 'progress' | 'completed' | 'failed' | 'cancelled' | 'retried';
+    timestamp: Date;
+    agentId?: string;
+    message?: string;
+    metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=task.d.ts.map

package/dist/types/task.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+// Task priority levels
+export const TaskPriority = {
+    CRITICAL: 1,
+    HIGH: 2,
+    MEDIUM: 3,
+    LOW: 4,
+};
+// Task status
+export const TaskStatus = {
+    PENDING: 'pending',
+    QUEUED: 'queued',
+    ASSIGNED: 'assigned',
+    IN_PROGRESS: 'in_progress',
+    COMPLETED: 'completed',
+    FAILED: 'failed',
+    CANCELLED: 'cancelled',
+};
+// Source of the task (where it came from)
+export const TaskSource = {
+    GITHUB_ISSUE: 'github_issue',
+    GITHUB_PR: 'github_pr',
+    JIRA: 'jira',
+    LINEAR: 'linear',
+    SLACK: 'slack',
+    DISCORD: 'discord',
+    TELEGRAM: 'telegram',
+    API: 'api',
+    MANUAL: 'manual',
+};
+// Zod schema for task creation
+export const CreateTaskSchema = z.object({
+    title: z.string().min(1).max(500),
+    description: z.string().optional(),
+    prompt: z.string().min(1), // The actual prompt to send to AI
+    priority: z.number().min(1).max(4).default(3),
+    source: z.string(),
+    sourceId: z.string().optional(), // e.g., issue number, PR number
+    sourceUrl: z.string().url().optional(),
+    repository: z.string().optional(), // e.g., "profclaw/profclaw"
+    branch: z.string().optional(),
+    labels: z.array(z.string()).default([]),
+    assignedAgent: z.string().optional(), // Which agent adapter to use
+    metadata: z.record(z.unknown()).default({}),
+});
+//# sourceMappingURL=task.js.map

package/dist/utils/ai-cache.d.ts

@@ -0,0 +1,72 @@
+/**
+ * AI Inference Cache Utility
+ *
+ * Provides caching layer for AI inference results to avoid
+ * redundant API calls for identical inputs.
+ *
+ * Cache key = SHA256(cacheType + model + normalized_input)
+ */
+export type CacheType = 'categorize' | 'suggest' | 'summarize' | 'analyze_comment' | 'generate_response';
+export interface CacheEntry<T> {
+    id: string;
+    cacheType: CacheType;
+    inputHash: string;
+    model: string;
+    provider?: string;
+    response: T;
+    confidence?: number;
+    hitCount: number;
+    lastHitAt?: Date;
+    expiresAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface CacheStats {
+    totalEntries: number;
+    hitCount: number;
+    missCount: number;
+    hitRate: number;
+    byType: Record<string, {
+        entries: number;
+        hits: number;
+    }>;
+}
+/**
+ * Generate a consistent hash for cache lookup
+ */
+export declare function generateCacheKey(cacheType: CacheType, model: string, ...inputs: (string | undefined)[]): string;
+/**
+ * Get cached response if available and not expired
+ */
+export declare function getCachedResponse<T>(db: any, // Database instance
+cacheType: CacheType, model: string, ...inputs: (string | undefined)[]): Promise<T | null>;
+/**
+ * Store response in cache
+ */
+export declare function setCachedResponse<T>(db: any, cacheType: CacheType, model: string, response: T, options: {
+    inputs: (string | undefined)[];
+    provider?: string;
+    confidence?: number;
+    ttlMs?: number;
+}): Promise<void>;
+/**
+ * Invalidate cache entries by type or specific hash
+ */
+export declare function invalidateCache(db: any, options: {
+    cacheType?: CacheType;
+    inputHash?: string;
+    olderThanMs?: number;
+}): Promise<number>;
+/**
+ * Clean up expired cache entries
+ */
+export declare function cleanupExpiredCache(db: any): Promise<number>;
+/**
+ * Get cache statistics
+ */
+export declare function getCacheStats(db: any): Promise<CacheStats>;
+/**
+ * Reset in-memory stats (for testing)
+ */
+export declare function resetCacheStats(): void;
+//# sourceMappingURL=ai-cache.d.ts.map

package/dist/utils/ai-cache.js

@@ -0,0 +1,204 @@
+/**
+ * AI Inference Cache Utility
+ *
+ * Provides caching layer for AI inference results to avoid
+ * redundant API calls for identical inputs.
+ *
+ * Cache key = SHA256(cacheType + model + normalized_input)
+ */
+import { createHash } from 'crypto';
+import { logger } from './logger.js';
+// Default cache TTL: 7 days for most operations
+const DEFAULT_CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+// Cache TTLs by type (in milliseconds)
+const CACHE_TTL_BY_TYPE = {
+    categorize: 30 * 24 * 60 * 60 * 1000, // 30 days - categorization is stable
+    suggest: 7 * 24 * 60 * 60 * 1000, // 7 days - suggestions can evolve
+    summarize: 14 * 24 * 60 * 60 * 1000, // 14 days - summaries are fairly stable
+    analyze_comment: 7 * 24 * 60 * 60 * 1000, // 7 days
+    generate_response: 1 * 24 * 60 * 60 * 1000, // 1 day - responses should be fresh
+};
+// In-memory stats tracking
+let cacheHits = 0;
+let cacheMisses = 0;
+/**
+ * Generate a consistent hash for cache lookup
+ */
+export function generateCacheKey(cacheType, model, ...inputs) {
+    // Normalize inputs: lowercase, trim, remove extra whitespace
+    const normalizedInputs = inputs
+        .filter((i) => !!i)
+        .map((i) => i.toLowerCase().trim().replace(/\s+/g, ' '))
+        .join('|');
+    const keyData = `${cacheType}:${model}:${normalizedInputs}`;
+    return createHash('sha256').update(keyData).digest('hex');
+}
+/**
+ * Get cached response if available and not expired
+ */
+export async function getCachedResponse(db, // Database instance
+cacheType, model, ...inputs) {
+    try {
+        const inputHash = generateCacheKey(cacheType, model, ...inputs);
+        const now = Date.now();
+        const result = await db.query(`SELECT id, response, expires_at, confidence
+       FROM ai_inference_cache
+       WHERE cache_type = ? AND input_hash = ? AND model = ?`, [cacheType, inputHash, model]);
+        if (!result || result.length === 0) {
+            cacheMisses++;
+            return null;
+        }
+        const entry = result[0];
+        // Check expiration
+        if (entry.expires_at && entry.expires_at < now) {
+            cacheMisses++;
+            // Clean up expired entry
+            await db.execute(`DELETE FROM ai_inference_cache WHERE id = ?`, [entry.id]);
+            logger.debug('[AI Cache] Entry expired', { cacheType, inputHash: inputHash.slice(0, 8) });
+            return null;
+        }
+        // Update hit stats
+        await db.execute(`UPDATE ai_inference_cache SET hit_count = hit_count + 1, last_hit_at = ? WHERE id = ?`, [now, entry.id]);
+        cacheHits++;
+        logger.debug('[AI Cache] Cache hit', { cacheType, inputHash: inputHash.slice(0, 8) });
+        // Parse and return response
+        const response = typeof entry.response === 'string'
+            ? JSON.parse(entry.response)
+            : entry.response;
+        return response;
+    }
+    catch (error) {
+        logger.warn('[AI Cache] Error reading cache', { error });
+        cacheMisses++;
+        return null;
+    }
+}
+/**
+ * Store response in cache
+ */
+export async function setCachedResponse(db, cacheType, model, response, options) {
+    try {
+        const inputHash = generateCacheKey(cacheType, model, ...options.inputs);
+        const id = `cache_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+        const now = Date.now();
+        const ttl = options.ttlMs ?? CACHE_TTL_BY_TYPE[cacheType] ?? DEFAULT_CACHE_TTL_MS;
+        const expiresAt = ttl > 0 ? now + ttl : null;
+        // Upsert: delete existing then insert
+        await db.execute(`DELETE FROM ai_inference_cache WHERE cache_type = ? AND input_hash = ? AND model = ?`, [cacheType, inputHash, model]);
+        await db.execute(`INSERT INTO ai_inference_cache
+       (id, cache_type, input_hash, model, provider, response, confidence, hit_count, expires_at, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?)`, [
+            id,
+            cacheType,
+            inputHash,
+            model,
+            options.provider ?? null,
+            JSON.stringify(response),
+            options.confidence ?? null,
+            expiresAt,
+            now,
+            now,
+        ]);
+        logger.debug('[AI Cache] Stored response', { cacheType, inputHash: inputHash.slice(0, 8) });
+    }
+    catch (error) {
+        logger.warn('[AI Cache] Error storing cache', { error });
+    }
+}
+/**
+ * Invalidate cache entries by type or specific hash
+ */
+export async function invalidateCache(db, options) {
+    try {
+        const conditions = [];
+        const params = [];
+        if (options.cacheType) {
+            conditions.push('cache_type = ?');
+            params.push(options.cacheType);
+        }
+        if (options.inputHash) {
+            conditions.push('input_hash = ?');
+            params.push(options.inputHash);
+        }
+        if (options.olderThanMs) {
+            const cutoff = Date.now() - options.olderThanMs;
+            conditions.push('created_at < ?');
+            params.push(cutoff);
+        }
+        if (conditions.length === 0) {
+            return 0;
+        }
+        const result = await db.execute(`DELETE FROM ai_inference_cache WHERE ${conditions.join(' AND ')}`, params);
+        const deleted = result?.rowsAffected ?? 0;
+        logger.info('[AI Cache] Invalidated entries', { deleted, ...options });
+        return deleted;
+    }
+    catch (error) {
+        logger.warn('[AI Cache] Error invalidating cache', { error });
+        return 0;
+    }
+}
+/**
+ * Clean up expired cache entries
+ */
+export async function cleanupExpiredCache(db) {
+    try {
+        const now = Date.now();
+        const result = await db.execute(`DELETE FROM ai_inference_cache WHERE expires_at IS NOT NULL AND expires_at < ?`, [now]);
+        const deleted = result?.rowsAffected ?? 0;
+        if (deleted > 0) {
+            logger.info('[AI Cache] Cleaned up expired entries', { deleted });
+        }
+        return deleted;
+    }
+    catch (error) {
+        logger.warn('[AI Cache] Error cleaning up cache', { error });
+        return 0;
+    }
+}
+/**
+ * Get cache statistics
+ */
+export async function getCacheStats(db) {
+    try {
+        const totalResult = await db.query(`SELECT COUNT(*) as count FROM ai_inference_cache`);
+        const totalEntries = totalResult[0]?.count ?? 0;
+        const byTypeResult = await db.query(`SELECT cache_type, COUNT(*) as entries, SUM(hit_count) as hits
+       FROM ai_inference_cache
+       GROUP BY cache_type`);
+        const byType = {};
+        for (const row of byTypeResult) {
+            byType[row.cache_type] = { entries: row.entries, hits: row.hits ?? 0 };
+        }
+        const totalHits = cacheHits;
+        const totalMisses = cacheMisses;
+        const hitRate = totalHits + totalMisses > 0
+            ? (totalHits / (totalHits + totalMisses)) * 100
+            : 0;
+        return {
+            totalEntries,
+            hitCount: totalHits,
+            missCount: totalMisses,
+            hitRate: Math.round(hitRate * 100) / 100,
+            byType,
+        };
+    }
+    catch (error) {
+        logger.warn('[AI Cache] Error getting stats', { error });
+        return {
+            totalEntries: 0,
+            hitCount: cacheHits,
+            missCount: cacheMisses,
+            hitRate: 0,
+            byType: {},
+        };
+    }
+}
+/**
+ * Reset in-memory stats (for testing)
+ */
+export function resetCacheStats() {
+    cacheHits = 0;
+    cacheMisses = 0;
+}
+//# sourceMappingURL=ai-cache.js.map

package/dist/utils/ai-inference.d.ts

@@ -0,0 +1,57 @@
+/**
+ * AI Inference Utility
+ *
+ * Lightweight AI inference for quick tasks like:
+ * - Ticket categorization (type, priority, labels)
+ * - Text summarization
+ * - Similarity matching
+ * - Smart suggestions
+ *
+ * Uses Ollama for local inference, falls back gracefully.
+ */
+interface InferenceResult<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    durationMs?: number;
+}
+/**
+ * Check if AI inference is available
+ */
+export declare function isAIAvailable(): Promise<boolean>;
+/**
+ * Run a quick AI inference with structured output
+ */
+export declare function quickInference<T>(systemPrompt: string, userPrompt: string, parseResponse: (text: string) => T): Promise<InferenceResult<T>>;
+export interface TicketCategorization {
+    type: 'task' | 'bug' | 'feature' | 'epic' | 'story' | 'subtask';
+    priority: 'critical' | 'high' | 'medium' | 'low' | 'none';
+    labels: string[];
+    confidence: number;
+}
+/**
+ * Auto-categorize a ticket based on title and description
+ */
+export declare function categorizeTicket(title: string, description?: string): Promise<InferenceResult<TicketCategorization>>;
+export interface TicketSuggestion {
+    title?: string;
+    description?: string;
+    acceptanceCriteria?: string[];
+    suggestedLabels?: string[];
+    estimatedEffort?: 'small' | 'medium' | 'large';
+}
+/**
+ * Get AI suggestions to improve a ticket
+ */
+export declare function suggestTicketImprovements(title: string, description?: string, type?: string): Promise<InferenceResult<TicketSuggestion>>;
+/**
+ * Generate a summary from ticket content
+ */
+export declare function summarizeTicket(title: string, description?: string, comments?: string[]): Promise<InferenceResult<string>>;
+/**
+ * Calculate text similarity score (simple word overlap for now)
+ * Returns 0-1 where 1 is identical
+ */
+export declare function calculateSimilarity(text1: string, text2: string): number;
+export {};
+//# sourceMappingURL=ai-inference.d.ts.map