@webpresso/agent-kit 0.21.0

package/dist/esm/ai-prompts/circuit-breaker.js

@@ -0,0 +1,171 @@
+export const DEFAULT_CIRCUIT_BREAKER_CONFIG = {
+    maxTokensPerDebate: 50000,
+    requireHumanReviewFor: ['approved', 'rejected'],
+    similarityThreshold: 0.85,
+    minRoundsForSimilarityCheck: 2,
+};
+export function createCircuitBreakerState() {
+    return {
+        totalTokensUsed: 0,
+        roundSimilarities: [],
+        humanReviewRequired: false,
+        breakerTripped: false,
+    };
+}
+export function updateTokens(state, inputTokens, outputTokens, config = DEFAULT_CIRCUIT_BREAKER_CONFIG) {
+    const newTotal = state.totalTokensUsed + inputTokens + outputTokens;
+    if (newTotal >= config.maxTokensPerDebate && !state.breakerTripped) {
+        return {
+            ...state,
+            totalTokensUsed: newTotal,
+            breakerTripped: true,
+            tripReason: 'max_tokens_exceeded',
+            trippedAt: new Date(),
+        };
+    }
+    return {
+        ...state,
+        totalTokensUsed: newTotal,
+    };
+}
+function extractWords(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((w) => w.length >= 4)
+        .map((w) => w.replace(/[^a-z0-9]/g, ''))
+        .filter((w) => w.length >= 4));
+}
+export function calculateSimilarity(text1, text2) {
+    const words1 = extractWords(text1);
+    const words2 = extractWords(text2);
+    if (words1.size === 0 && words2.size === 0)
+        return 1;
+    if (words1.size === 0 || words2.size === 0)
+        return 0;
+    const intersection = new Set([...words1].filter((x) => words2.has(x)));
+    const union = new Set([...words1, ...words2]);
+    return intersection.size / union.size;
+}
+function getRoundText(contributions) {
+    return contributions.map((c) => c.content).join('\n');
+}
+export function checkForHallucinationLoop(state, config = DEFAULT_CIRCUIT_BREAKER_CONFIG) {
+    const { rounds } = state;
+    if (rounds.length < config.minRoundsForSimilarityCheck) {
+        return { detected: false, similarity: 0 };
+    }
+    const currentRound = rounds[rounds.length - 1];
+    const previousRound = rounds[rounds.length - 2];
+    if (!currentRound || !previousRound) {
+        return { detected: false, similarity: 0 };
+    }
+    const currentText = getRoundText(currentRound.contributions);
+    const previousText = getRoundText(previousRound.contributions);
+    const similarity = calculateSimilarity(currentText, previousText);
+    return {
+        detected: similarity >= config.similarityThreshold,
+        similarity,
+    };
+}
+export function updateSimilarity(state, similarity, isLoop) {
+    const newSimilarities = [...state.roundSimilarities, similarity];
+    if (isLoop && !state.breakerTripped) {
+        return {
+            ...state,
+            roundSimilarities: newSimilarities,
+            breakerTripped: true,
+            tripReason: 'hallucination_loop_detected',
+            trippedAt: new Date(),
+        };
+    }
+    return {
+        ...state,
+        roundSimilarities: newSimilarities,
+    };
+}
+export function requiresHumanReview(outcome, config = DEFAULT_CIRCUIT_BREAKER_CONFIG) {
+    return config.requireHumanReviewFor.includes(outcome.decision);
+}
+export function flagForHumanReview(state) {
+    return {
+        ...state,
+        humanReviewRequired: true,
+    };
+}
+function checkAlreadyTripped(breakerState) {
+    if (breakerState.breakerTripped) {
+        return {
+            shouldContinue: false,
+            state: breakerState,
+            message: `Circuit breaker tripped: ${breakerState.tripReason}`,
+        };
+    }
+    return null;
+}
+function checkTokenLimit(breakerState, config) {
+    if (breakerState.totalTokensUsed >= config.maxTokensPerDebate) {
+        const newState = {
+            ...breakerState,
+            breakerTripped: true,
+            tripReason: 'max_tokens_exceeded',
+            trippedAt: new Date(),
+        };
+        return {
+            shouldContinue: false,
+            state: newState,
+            message: `Token limit exceeded: ${breakerState.totalTokensUsed}/${config.maxTokensPerDebate}`,
+        };
+    }
+    return null;
+}
+function checkHallucinationLoopDetection(debateState, breakerState, config) {
+    const loopCheck = checkForHallucinationLoop(debateState, config);
+    if (loopCheck.detected) {
+        const newState = {
+            ...breakerState,
+            roundSimilarities: [...breakerState.roundSimilarities, loopCheck.similarity],
+            breakerTripped: true,
+            tripReason: 'hallucination_loop_detected',
+            trippedAt: new Date(),
+        };
+        return {
+            shouldContinue: false,
+            state: newState,
+            message: `Potential hallucination loop detected: ${Math.round(loopCheck.similarity * 100)}% similarity between rounds`,
+        };
+    }
+    return {
+        shouldContinue: true,
+        state: {
+            ...breakerState,
+            roundSimilarities: [...breakerState.roundSimilarities, loopCheck.similarity],
+        },
+    };
+}
+export function checkCircuitBreaker(debateState, breakerState, config = DEFAULT_CIRCUIT_BREAKER_CONFIG) {
+    const trippedCheck = checkAlreadyTripped(breakerState);
+    if (trippedCheck) {
+        return trippedCheck;
+    }
+    const tokenCheck = checkTokenLimit(breakerState, config);
+    if (tokenCheck) {
+        return tokenCheck;
+    }
+    return checkHallucinationLoopDetection(debateState, breakerState, config);
+}
+export function createCircuitBreakerLog(debateId, state, event) {
+    return {
+        timestamp: new Date().toISOString(),
+        level: event === 'trip' ? 'warn' : 'info',
+        component: 'circuit-breaker',
+        debateId,
+        event,
+        totalTokensUsed: state.totalTokensUsed,
+        roundSimilarities: state.roundSimilarities,
+        breakerTripped: state.breakerTripped,
+        tripReason: state.tripReason,
+        humanReviewRequired: state.humanReviewRequired,
+    };
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/esm/ai-prompts/experiment-draft.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Experiment draft generation from analytics signals
+ *
+ * Converts analytics data into structured experiment drafts with
+ * hypothesis, primary metric, guardrails, and rollout plan.
+ */
+export interface AnalyticsSignal {
+    metricName: string;
+    currentValue: number;
+    previousValue: number;
+    trend: 'improving' | 'declining' | 'stable';
+    sampleSize: number;
+    periodDays: number;
+    metadata?: Record<string, unknown>;
+}
+export interface ExperimentDraftInput {
+    projectId: string;
+    projectName: string;
+    signals: AnalyticsSignal[];
+    existingFlagKeys?: string[];
+}
+export interface VariantDraft {
+    name: string;
+    description: string;
+    isControl: boolean;
+}
+export interface GuardrailDraft {
+    metricName: string;
+    operator: string;
+    threshold: number;
+}
+export interface RolloutMilestone {
+    percentage: number;
+    criteria: string;
+}
+export interface RolloutPlan {
+    initialPercentage: number;
+    milestones: RolloutMilestone[];
+}
+export interface ExperimentDraft {
+    name: string;
+    hypothesis: string;
+    primaryMetric: string;
+    guardrails: GuardrailDraft[];
+    variants: VariantDraft[];
+    rolloutPlan: RolloutPlan;
+    rationale: string;
+    confidence: number;
+    estimatedImpact: string;
+}
+export type DraftDisposition = 'auto_queue' | 'require_approval' | 'suggest_only';
+export interface ExperimentDecisionEvent {
+    type: 'experiment_draft_generated';
+    projectId: string;
+    draftName: string;
+    disposition: DraftDisposition;
+    autonomyLevel: string;
+    primaryMetric: string;
+    confidence: number;
+    timestamp: string;
+    signals: Array<{
+        metricName: string;
+        trend: string;
+        deltaPercent: number;
+    }>;
+}
+/**
+ * Compute urgency score for a signal.
+ * Higher = more urgent to experiment on.
+ */
+export declare function computeSignalUrgency(signal: AnalyticsSignal): number;
+/**
+ * Select the primary signal to experiment on.
+ * Prefers declining signals with largest delta.
+ */
+export declare function selectPrimarySignal(signals: AnalyticsSignal[]): AnalyticsSignal;
+/**
+ * Build the LLM prompt for experiment draft generation.
+ */
+export declare function buildExperimentDraftPrompt(input: ExperimentDraftInput): string;
+/**
+ * Parse and validate an LLM response into an ExperimentDraft.
+ * Returns null if the response is invalid or incomplete.
+ */
+export declare function parseExperimentDraftResponse(response: string): ExperimentDraft | null;
+//# sourceMappingURL=experiment-draft.d.ts.map

package/dist/esm/ai-prompts/experiment-draft.js

@@ -0,0 +1,188 @@
+/**
+ * Experiment draft generation from analytics signals
+ *
+ * Converts analytics data into structured experiment drafts with
+ * hypothesis, primary metric, guardrails, and rollout plan.
+ */
+// ---------------------------------------------------------------------------
+// Signal analysis
+// ---------------------------------------------------------------------------
+/**
+ * Compute urgency score for a signal.
+ * Higher = more urgent to experiment on.
+ */
+export function computeSignalUrgency(signal) {
+    if (signal.previousValue === 0 && signal.currentValue === 0)
+        return 0;
+    const deltaPercent = Math.abs((signal.currentValue - signal.previousValue) /
+        Math.max(Math.abs(signal.previousValue), Number.EPSILON));
+    const trendMultiplier = signal.trend === 'declining' ? 2 : signal.trend === 'improving' ? 0.5 : 0.1;
+    const sampleConfidence = Math.min(signal.sampleSize / 1000, 1);
+    return deltaPercent * trendMultiplier * sampleConfidence;
+}
+/**
+ * Select the primary signal to experiment on.
+ * Prefers declining signals with largest delta.
+ */
+export function selectPrimarySignal(signals) {
+    if (signals.length === 0) {
+        throw new Error('No analytics signals provided');
+    }
+    const scored = signals
+        .map((s) => ({ signal: s, score: computeSignalUrgency(s) }))
+        .toSorted((a, b) => b.score - a.score);
+    return scored[0].signal;
+}
+// ---------------------------------------------------------------------------
+// Prompt building
+// ---------------------------------------------------------------------------
+/**
+ * Build the LLM prompt for experiment draft generation.
+ */
+export function buildExperimentDraftPrompt(input) {
+    const primary = selectPrimarySignal(input.signals);
+    const signalDescriptions = input.signals
+        .map((s) => {
+        const delta = s.previousValue !== 0
+            ? (((s.currentValue - s.previousValue) / Math.abs(s.previousValue)) * 100).toFixed(1)
+            : 'N/A';
+        return `- ${s.metricName}: ${s.currentValue} (was ${s.previousValue}, ${delta}% change, trend: ${s.trend}, sample: ${s.sampleSize} over ${s.periodDays} days)`;
+    })
+        .join('\n');
+    const existingFlagsSection = input.existingFlagKeys && input.existingFlagKeys.length > 0
+        ? `\n<existing_flags>\n${input.existingFlagKeys.join(', ')}\n</existing_flags>\nDo NOT propose experiments for these existing flag keys.`
+        : '';
+    return `You are an experimentation engineer analyzing analytics signals for project "${input.projectName}".
+
+<analytics_signals>
+${signalDescriptions}
+</analytics_signals>
+
+Primary concern: ${primary.metricName} (trend: ${primary.trend}, sample: ${primary.sampleSize})
+${existingFlagsSection}
+
+<instructions>
+Based on these analytics signals, propose a concrete experiment draft. The experiment should:
+1. Address the most impactful signal (especially declining metrics)
+2. Have a clear, testable hypothesis
+3. Define primary metric and guardrails
+4. Include a safe rollout plan with milestones
+5. Estimate confidence and expected impact
+
+Respond in JSON format only:
+{
+  "name": "Short experiment name",
+  "hypothesis": "If we [change], then [metric] will [improve] because [reasoning]",
+  "primaryMetric": "metric_name",
+  "guardrails": [
+    { "metricName": "error_rate", "operator": "lt", "threshold": 0.05 }
+  ],
+  "variants": [
+    { "name": "control", "description": "Current behavior", "isControl": true },
+    { "name": "treatment", "description": "Proposed change", "isControl": false }
+  ],
+  "rolloutPlan": {
+    "initialPercentage": 10,
+    "milestones": [
+      { "percentage": 25, "criteria": "No guardrail violations after 48h" },
+      { "percentage": 50, "criteria": "Primary metric shows improvement after 7 days" }
+    ]
+  },
+  "rationale": "Why this experiment is worth running",
+  "confidence": 0.75,
+  "estimatedImpact": "Expected impact range on the primary metric"
+}
+</instructions>`;
+}
+// ---------------------------------------------------------------------------
+// Response parsing
+// ---------------------------------------------------------------------------
+const VALID_OPERATORS = new Set(['lt', 'lte', 'gt', 'gte']);
+/**
+ * Parse and validate an LLM response into an ExperimentDraft.
+ * Returns null if the response is invalid or incomplete.
+ */
+export function parseExperimentDraftResponse(response) {
+    const jsonMatch = response.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const jsonStr = jsonMatch?.[1]?.trim() ?? response.trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonStr);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed.name || typeof parsed.name !== 'string')
+        return null;
+    if (!parsed.hypothesis || typeof parsed.hypothesis !== 'string')
+        return null;
+    if (!parsed.primaryMetric || typeof parsed.primaryMetric !== 'string')
+        return null;
+    // Validate variants
+    if (!Array.isArray(parsed.variants) || parsed.variants.length === 0)
+        return null;
+    const variants = [];
+    for (const v of parsed.variants) {
+        if (!v || typeof v !== 'object')
+            return null;
+        const obj = v;
+        if (typeof obj.name !== 'string' ||
+            typeof obj.description !== 'string' ||
+            typeof obj.isControl !== 'boolean') {
+            return null;
+        }
+        variants.push({ name: obj.name, description: obj.description, isControl: obj.isControl });
+    }
+    const hasControl = variants.some((v) => v.isControl);
+    if (!hasControl)
+        return null;
+    // Validate guardrails
+    const guardrails = [];
+    if (Array.isArray(parsed.guardrails)) {
+        for (const g of parsed.guardrails) {
+            if (!g || typeof g !== 'object')
+                continue;
+            const obj = g;
+            if (typeof obj.metricName !== 'string' ||
+                typeof obj.operator !== 'string' ||
+                typeof obj.threshold !== 'number') {
+                continue;
+            }
+            const operator = obj.operator.toLowerCase();
+            if (!VALID_OPERATORS.has(operator))
+                continue;
+            guardrails.push({ metricName: obj.metricName, operator, threshold: obj.threshold });
+        }
+    }
+    // Validate rollout plan
+    const rawPlan = parsed.rolloutPlan;
+    const initialPercentage = typeof rawPlan?.initialPercentage === 'number'
+        ? Math.max(1, Math.min(100, rawPlan.initialPercentage))
+        : 10;
+    const milestones = [];
+    if (Array.isArray(rawPlan?.milestones)) {
+        for (const m of rawPlan.milestones) {
+            if (!m || typeof m !== 'object')
+                continue;
+            const obj = m;
+            if (typeof obj.percentage === 'number' && typeof obj.criteria === 'string') {
+                milestones.push({ percentage: obj.percentage, criteria: obj.criteria });
+            }
+        }
+    }
+    // Clamp confidence
+    let confidence = typeof parsed.confidence === 'number' ? parsed.confidence : 0.5;
+    confidence = Math.max(0, Math.min(1, confidence));
+    return {
+        name: parsed.name,
+        hypothesis: parsed.hypothesis,
+        primaryMetric: parsed.primaryMetric,
+        guardrails,
+        variants,
+        rolloutPlan: { initialPercentage, milestones },
+        rationale: typeof parsed.rationale === 'string' ? parsed.rationale : '',
+        confidence,
+        estimatedImpact: typeof parsed.estimatedImpact === 'string' ? parsed.estimatedImpact : 'Unknown',
+    };
+}
+//# sourceMappingURL=experiment-draft.js.map

package/dist/esm/ai-prompts/index.d.ts

@@ -0,0 +1,12 @@
+export { AGENT_PERSONAS } from './types.js';
+export type { AgentPersona } from './types.js';
+export { BUSINESS_CANVAS_SYSTEM_PROMPT, BUSINESS_CANVAS_USER_PROMPT, isValidBusinessCanvas, parseBusinessCanvas, type BusinessCanvas, type FeatureProposal, type MarketResearch, type ParsedSteveResponse, type SuccessMetric, type TargetAudience, type ViabilityDecision, } from './business-canvas.js';
+export { BAZIL_PROMPT, JERAMY_PROMPT, OZBY_PROMPT, PERSONA_PROMPTS, RACHEL_PROMPT, RODRIGO_PROMPT, VOLKER_PROMPT, } from './personas.js';
+export { formatPersonaContext, getPersonaContextHeader, type BusinessContext, type EngineeringContext, type PersonaContext, type ProductContext, } from './persona-context.js';
+export { addContribution, calculateConsensus, createDebateState, DEBATE_PROMPTS, DEFAULT_DEBATE_CONFIG, finalizeDebate, generateDebateId, parseConfidence, parsePosition, shouldContinueDebate, startNewRound, type AgentContribution, type DebateConfig, type DebateOutcome, type DebateRound, type DebateState, type DebateType, } from './persona-debate.js';
+export { ALL_TOOLS, filterToolsForPersona, getPersonaToolDescription, getRestrictedToolsForPersona, isToolAllowedForPersona, PERSONA_TOOL_CONFIG, TOOL_CATEGORIES, type PersonaToolConfig, type ToolName, } from './persona-tools.js';
+export { calculateSimilarity, checkCircuitBreaker, checkForHallucinationLoop, createCircuitBreakerLog, createCircuitBreakerState, DEFAULT_CIRCUIT_BREAKER_CONFIG, flagForHumanReview, requiresHumanReview, updateSimilarity, updateTokens, type CircuitBreakerCheckResult, type CircuitBreakerConfig, type CircuitBreakerState, type CircuitBreakerTripReason, } from './circuit-breaker.js';
+export { getRachelPromptForGranularity, GRANULARITY_INSTRUCTIONS, isNonEmptyString, isValidTechBreakdown, parseRachelBreakdown, RACHEL_FEATURE_PROMPT, RACHEL_PLANNING_PROMPT, type Complexity, type ComponentType, type ParsedRachelResponse, type TechBreakdown, type TechComponent, } from './rachel-planning.js';
+export { AGENT_FOCUS_AREAS, AGENT_SUGGESTED_FIELDS, buildTaskAnalysisPrompt, parseTaskAnalysisResponse, TASK_ANALYSIS_PROMPTS, type SuggestedFields, type TaskAnalysisResponse, type TaskContext, } from './task-analysis.js';
+export { buildExperimentDraftPrompt, computeSignalUrgency, parseExperimentDraftResponse, selectPrimarySignal, type AnalyticsSignal, type DraftDisposition, type ExperimentDecisionEvent, type ExperimentDraft, type ExperimentDraftInput, type GuardrailDraft, type RolloutMilestone, type RolloutPlan, type VariantDraft, } from './experiment-draft.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/ai-prompts/index.js

@@ -0,0 +1,11 @@
+export { AGENT_PERSONAS } from './types.js';
+export { BUSINESS_CANVAS_SYSTEM_PROMPT, BUSINESS_CANVAS_USER_PROMPT, isValidBusinessCanvas, parseBusinessCanvas, } from './business-canvas.js';
+export { BAZIL_PROMPT, JERAMY_PROMPT, OZBY_PROMPT, PERSONA_PROMPTS, RACHEL_PROMPT, RODRIGO_PROMPT, VOLKER_PROMPT, } from './personas.js';
+export { formatPersonaContext, getPersonaContextHeader, } from './persona-context.js';
+export { addContribution, calculateConsensus, createDebateState, DEBATE_PROMPTS, DEFAULT_DEBATE_CONFIG, finalizeDebate, generateDebateId, parseConfidence, parsePosition, shouldContinueDebate, startNewRound, } from './persona-debate.js';
+export { ALL_TOOLS, filterToolsForPersona, getPersonaToolDescription, getRestrictedToolsForPersona, isToolAllowedForPersona, PERSONA_TOOL_CONFIG, TOOL_CATEGORIES, } from './persona-tools.js';
+export { calculateSimilarity, checkCircuitBreaker, checkForHallucinationLoop, createCircuitBreakerLog, createCircuitBreakerState, DEFAULT_CIRCUIT_BREAKER_CONFIG, flagForHumanReview, requiresHumanReview, updateSimilarity, updateTokens, } from './circuit-breaker.js';
+export { getRachelPromptForGranularity, GRANULARITY_INSTRUCTIONS, isNonEmptyString, isValidTechBreakdown, parseRachelBreakdown, RACHEL_FEATURE_PROMPT, RACHEL_PLANNING_PROMPT, } from './rachel-planning.js';
+export { AGENT_FOCUS_AREAS, AGENT_SUGGESTED_FIELDS, buildTaskAnalysisPrompt, parseTaskAnalysisResponse, TASK_ANALYSIS_PROMPTS, } from './task-analysis.js';
+export { buildExperimentDraftPrompt, computeSignalUrgency, parseExperimentDraftResponse, selectPrimarySignal, } from './experiment-draft.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/ai-prompts/persona-context.d.ts

@@ -0,0 +1,70 @@
+import type { AgentPersona } from './types.js';
+export interface BusinessContext {
+    mrr?: number;
+    arr?: number;
+    mau?: number;
+    dau?: number;
+    cac?: number;
+    ltv?: number;
+    churnRate?: number;
+    conversionRate?: number;
+    growth?: {
+        mrrGrowth?: number;
+        userGrowth?: number;
+        period?: string;
+    };
+    competitors?: string[];
+    priorities?: string[];
+}
+export interface ProductContext {
+    nps?: number;
+    csat?: number;
+    feedbackThemes?: Array<{
+        theme: string;
+        count: number;
+        sentiment: 'positive' | 'neutral' | 'negative';
+    }>;
+    featureRequests?: Array<{
+        title: string;
+        votes: number;
+        status: 'open' | 'planned' | 'in_progress' | 'completed';
+    }>;
+    funnelMetrics?: Array<{
+        step: string;
+        dropOffRate: number;
+    }>;
+    accessibilityScore?: number;
+    supportThemes?: string[];
+    userPersonas?: string[];
+}
+export interface EngineeringContext {
+    testCoverage?: number;
+    lintErrors?: number;
+    typeErrors?: number;
+    techDebt?: Array<{
+        description: string;
+        severity: 'low' | 'medium' | 'high' | 'critical';
+        file?: string;
+    }>;
+    vulnerabilities?: Array<{
+        package: string;
+        severity: 'low' | 'medium' | 'high' | 'critical';
+        fixAvailable: boolean;
+    }>;
+    errorRate?: number;
+    performance?: {
+        p50Latency?: number;
+        p95Latency?: number;
+        p99Latency?: number;
+    };
+    buildStatus?: 'passing' | 'failing' | 'unknown';
+    openPRs?: number;
+}
+export interface PersonaContext {
+    business?: BusinessContext;
+    product?: ProductContext;
+    engineering?: EngineeringContext;
+}
+export declare function formatPersonaContext(persona: AgentPersona, context: PersonaContext): string | undefined;
+export declare function getPersonaContextHeader(persona: AgentPersona): string;
+//# sourceMappingURL=persona-context.d.ts.map