agent-relay 1.1.0 → 1.2.3

package/dist/cloud/webhooks/rules-engine.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Webhook Rules Engine
+ *
+ * Matches normalized events against configured rules and determines actions to take.
+ */
+import type { NormalizedEvent, WebhookRule, WebhookAction } from './types.js';
+/**
+ * Check if a rule matches an event
+ */
+export declare function matchesRule(rule: WebhookRule, event: NormalizedEvent): boolean;
+/**
+ * Find all matching rules for an event, sorted by priority
+ */
+export declare function findMatchingRules(rules: WebhookRule[], event: NormalizedEvent): WebhookRule[];
+/**
+ * Resolve template variables in action configuration
+ * Supports: ${event.field}, ${event.field.subfield}
+ */
+export declare function resolveActionTemplate(action: WebhookAction, event: NormalizedEvent): WebhookAction;
+/**
+ * Default rules for common patterns
+ */
+export declare const defaultRules: WebhookRule[];
+//# sourceMappingURL=rules-engine.d.ts.map

package/dist/cloud/webhooks/rules-engine.js

@@ -0,0 +1,287 @@
+/**
+ * Webhook Rules Engine
+ *
+ * Matches normalized events against configured rules and determines actions to take.
+ */
+/**
+ * Simple JSONPath-like evaluator for conditions
+ * Supports: $.field, $.field.subfield, comparisons (==, !=, in, contains)
+ */
+function evaluateCondition(condition, event) {
+    if (!condition || condition.trim() === '')
+        return true;
+    try {
+        // Parse condition: $.path operator value
+        // Note: >= and <= must come before > and < in the alternation to match correctly
+        const conditionPattern = /^\$\.([a-zA-Z0-9_.]+)\s*(==|!=|>=|<=|>|<|in|contains)\s*(.+)$/;
+        const match = condition.match(conditionPattern);
+        if (!match) {
+            console.warn(`[rules-engine] Invalid condition format: ${condition}`);
+            return false;
+        }
+        const [, path, operator, rawValue] = match;
+        const value = rawValue.trim();
+        // Get the value from the event
+        const eventValue = getValueByPath(event, path);
+        // Parse the comparison value
+        let compareValue;
+        if (value.startsWith('[') && value.endsWith(']')) {
+            // Array literal
+            compareValue = JSON.parse(value);
+        }
+        else if (value.startsWith('"') && value.endsWith('"')) {
+            // String literal
+            compareValue = value.slice(1, -1);
+        }
+        else if (value === 'true') {
+            compareValue = true;
+        }
+        else if (value === 'false') {
+            compareValue = false;
+        }
+        else if (value === 'null') {
+            compareValue = null;
+        }
+        else if (!isNaN(Number(value))) {
+            compareValue = Number(value);
+        }
+        else {
+            // Treat as string
+            compareValue = value;
+        }
+        switch (operator) {
+            case '==':
+                // Handle null/undefined equivalence
+                if (compareValue === null) {
+                    return eventValue === null || eventValue === undefined;
+                }
+                return eventValue === compareValue;
+            case '!=':
+                return eventValue !== compareValue;
+            case 'in':
+                return Array.isArray(compareValue) && compareValue.includes(eventValue);
+            case 'contains':
+                if (Array.isArray(eventValue)) {
+                    return eventValue.includes(compareValue);
+                }
+                if (typeof eventValue === 'string' && typeof compareValue === 'string') {
+                    return eventValue.includes(compareValue);
+                }
+                return false;
+            case '>':
+                return typeof eventValue === 'number' && typeof compareValue === 'number' && eventValue > compareValue;
+            case '<':
+                return typeof eventValue === 'number' && typeof compareValue === 'number' && eventValue < compareValue;
+            case '>=':
+                return typeof eventValue === 'number' && typeof compareValue === 'number' && eventValue >= compareValue;
+            case '<=':
+                return typeof eventValue === 'number' && typeof compareValue === 'number' && eventValue <= compareValue;
+            default:
+                return false;
+        }
+    }
+    catch (error) {
+        console.error(`[rules-engine] Error evaluating condition: ${condition}`, error);
+        return false;
+    }
+}
+/**
+ * Get a value from an object by dot-separated path
+ */
+function getValueByPath(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined)
+            return undefined;
+        if (typeof current !== 'object')
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Check if a rule matches an event
+ */
+export function matchesRule(rule, event) {
+    // Check if rule is enabled
+    if (!rule.enabled)
+        return false;
+    // Check source match
+    if (rule.source !== '*' && rule.source !== event.source) {
+        return false;
+    }
+    // Check event type match
+    if (rule.eventType !== '*' && rule.eventType !== event.type) {
+        // Support wildcard prefix matching (e.g., 'ci_*' matches 'ci_failure')
+        if (rule.eventType.endsWith('*')) {
+            const prefix = rule.eventType.slice(0, -1);
+            if (!event.type.startsWith(prefix)) {
+                return false;
+            }
+        }
+        else {
+            return false;
+        }
+    }
+    // Check condition if present
+    if (rule.condition && !evaluateCondition(rule.condition, event)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Find all matching rules for an event, sorted by priority
+ */
+export function findMatchingRules(rules, event) {
+    return rules
+        .filter(rule => matchesRule(rule, event))
+        .sort((a, b) => a.priority - b.priority);
+}
+/**
+ * Resolve template variables in action configuration
+ * Supports: ${event.field}, ${event.field.subfield}
+ */
+export function resolveActionTemplate(action, event) {
+    const resolvedAction = { ...action };
+    // Resolve agentType if it references an event field
+    if (resolvedAction.agentType?.startsWith('$.')) {
+        const path = resolvedAction.agentType.slice(2);
+        const value = getValueByPath(event, path);
+        if (typeof value === 'string') {
+            resolvedAction.agentType = value;
+        }
+        else if (Array.isArray(value) && value.length > 0) {
+            // Use first mentioned agent
+            resolvedAction.agentType = String(value[0]);
+        }
+    }
+    // Resolve prompt template references
+    if (resolvedAction.prompt?.startsWith('${') && resolvedAction.prompt?.endsWith('}')) {
+        const path = resolvedAction.prompt.slice(2, -1);
+        const value = getValueByPath(event, path);
+        if (typeof value === 'string') {
+            resolvedAction.prompt = value;
+        }
+    }
+    return resolvedAction;
+}
+/**
+ * Default rules for common patterns
+ */
+export const defaultRules = [
+    // CI Failures
+    {
+        id: 'ci-failure',
+        name: 'CI Failure Handler',
+        enabled: true,
+        source: 'github',
+        eventType: 'ci_failure',
+        action: {
+            type: 'spawn_agent',
+            agentType: 'ci-fix',
+            prompt: 'ci-failure',
+        },
+        priority: 10,
+    },
+    // GitHub Mentions
+    {
+        id: 'github-mention',
+        name: 'GitHub Mention Handler',
+        enabled: true,
+        source: 'github',
+        eventType: 'mention',
+        action: {
+            type: 'spawn_agent',
+            agentType: '$.mentions', // Use first mentioned agent
+            prompt: 'mention',
+        },
+        priority: 20,
+    },
+    // GitHub Issues
+    {
+        id: 'github-issue',
+        name: 'GitHub Issue Handler',
+        enabled: true,
+        source: 'github',
+        eventType: 'issue_created',
+        condition: '$.priority in ["critical", "high"]',
+        action: {
+            type: 'spawn_agent',
+            agentType: 'developer',
+            prompt: 'issue',
+        },
+        priority: 30,
+    },
+    // Linear Issues
+    {
+        id: 'linear-issue',
+        name: 'Linear Issue Handler',
+        enabled: true,
+        source: 'linear',
+        eventType: 'issue_created',
+        action: {
+            type: 'spawn_agent',
+            agentType: 'developer',
+            prompt: 'linear-issue',
+        },
+        priority: 20,
+    },
+    // Linear Mentions
+    {
+        id: 'linear-mention',
+        name: 'Linear Mention Handler',
+        enabled: true,
+        source: 'linear',
+        eventType: 'mention',
+        action: {
+            type: 'spawn_agent',
+            agentType: '$.mentions',
+            prompt: 'mention',
+        },
+        priority: 20,
+    },
+    // Slack App Mentions
+    {
+        id: 'slack-mention',
+        name: 'Slack App Mention Handler',
+        enabled: true,
+        source: 'slack',
+        eventType: 'mention',
+        action: {
+            type: 'spawn_agent',
+            agentType: '$.mentions',
+            prompt: 'slack-request',
+        },
+        priority: 20,
+    },
+    // Linear Issue Assignments (native integration)
+    {
+        id: 'linear-assignment',
+        name: 'Linear Issue Assignment Handler',
+        enabled: true,
+        source: 'linear',
+        eventType: 'issue_assigned',
+        action: {
+            type: 'spawn_agent',
+            agentType: '$.mentions', // Use the assigned agent type
+            prompt: 'linear-issue',
+        },
+        priority: 15,
+    },
+    // GitHub Issue Assignments
+    {
+        id: 'github-assignment',
+        name: 'GitHub Issue Assignment Handler',
+        enabled: true,
+        source: 'github',
+        eventType: 'issue_assigned',
+        action: {
+            type: 'spawn_agent',
+            agentType: '$.mentions',
+            prompt: 'issue',
+        },
+        priority: 15,
+    },
+];
+//# sourceMappingURL=rules-engine.js.map

package/dist/cloud/webhooks/types.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Generic Webhook System - Type Definitions
+ *
+ * Defines the core types for a configurable webhook system
+ * that can handle events from any source (GitHub, GitLab, Linear, Slack, etc.)
+ */
+/**
+ * Normalized event format that all parsers produce
+ */
+export interface NormalizedEvent {
+    /** Unique event ID */
+    id: string;
+    /** Source system (github, gitlab, linear, slack, etc.) */
+    source: string;
+    /** Event type (e.g., 'ci_failure', 'mention', 'issue_created') */
+    type: string;
+    /** Timestamp of the event */
+    timestamp: Date;
+    /** Actor who triggered the event */
+    actor: {
+        id: string;
+        name: string;
+        email?: string;
+    };
+    /** Repository or project context */
+    context: {
+        /** Full name (e.g., 'owner/repo' or project ID) */
+        name: string;
+        /** URL to the repository/project */
+        url?: string;
+    };
+    /** The item this event relates to (issue, PR, ticket, message) */
+    item?: {
+        type: 'issue' | 'pull_request' | 'ticket' | 'message' | 'comment' | 'check';
+        id: string | number;
+        number?: number;
+        title?: string;
+        body?: string;
+        url?: string;
+        state?: string;
+    };
+    /** Mentioned agents or users */
+    mentions: string[];
+    /** Labels, tags, or categories */
+    labels: string[];
+    /** Priority level if applicable */
+    priority?: 'critical' | 'high' | 'medium' | 'low';
+    /** Additional source-specific data */
+    metadata: Record<string, unknown>;
+    /** Raw payload for debugging */
+    rawPayload: unknown;
+}
+/**
+ * Action to take in response to an event
+ */
+export interface WebhookAction {
+    type: 'spawn_agent' | 'message_agent' | 'post_comment' | 'create_issue' | 'custom';
+    /** Agent type or name to spawn/message */
+    agentType?: string;
+    /** Prompt template name or inline prompt */
+    prompt?: string;
+    /** Additional action-specific config */
+    config?: Record<string, unknown>;
+}
+/**
+ * Signature verification configuration
+ */
+export interface SignatureConfig {
+    /** Header containing the signature */
+    header: string;
+    /** Algorithm to use for verification */
+    algorithm: 'sha256' | 'sha1' | 'token' | 'slack-v0' | 'none';
+    /** Environment variable containing the secret */
+    secretEnvVar: string;
+    /** Optional prefix to strip from signature (e.g., 'sha256=') */
+    signaturePrefix?: string;
+}
+/**
+ * Webhook source configuration
+ */
+export interface WebhookSourceConfig {
+    /** Source identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Whether this source is enabled */
+    enabled: boolean;
+    /** Signature verification config */
+    signature: SignatureConfig;
+    /** Parser to use for this source */
+    parser: string;
+    /** Responder to use for sending responses */
+    responder: string;
+    /** Parser-specific configuration */
+    parserConfig?: Record<string, unknown>;
+    /** Responder-specific configuration */
+    responderConfig?: Record<string, unknown>;
+}
+/**
+ * Event routing rule
+ */
+export interface WebhookRule {
+    /** Rule identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Whether this rule is enabled */
+    enabled: boolean;
+    /** Source to match (* for any) */
+    source: string;
+    /** Event type to match (* for any) */
+    eventType: string;
+    /** JSONPath condition (optional) */
+    condition?: string;
+    /** Action to take when matched */
+    action: WebhookAction;
+    /** Priority (lower = higher priority) */
+    priority: number;
+}
+/**
+ * Complete webhook configuration
+ */
+export interface WebhookConfig {
+    sources: Record<string, WebhookSourceConfig>;
+    rules: WebhookRule[];
+}
+/**
+ * Parser interface - transforms source-specific payloads to normalized events
+ */
+export interface WebhookParser {
+    /** Parser identifier */
+    id: string;
+    /** Parse raw payload into normalized event(s) */
+    parse(payload: unknown, headers: Record<string, string | string[] | undefined>, config?: Record<string, unknown>): NormalizedEvent[];
+}
+/**
+ * Response to send back to the source system
+ */
+export interface WebhookResponse {
+    /** Type of response */
+    type: 'comment' | 'message' | 'reaction' | 'status';
+    /** Target (issue number, channel ID, etc.) */
+    target: string | number;
+    /** Response body/content */
+    body: string;
+    /** Additional response metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Responder interface - sends responses back to source systems
+ */
+export interface WebhookResponder {
+    /** Responder identifier */
+    id: string;
+    /** Send a response to the source system */
+    respond(event: NormalizedEvent, response: WebhookResponse, config?: Record<string, unknown>): Promise<{
+        success: boolean;
+        id?: string;
+        url?: string;
+        error?: string;
+    }>;
+}
+/**
+ * Result of processing a webhook
+ */
+export interface WebhookResult {
+    success: boolean;
+    eventId: string;
+    source: string;
+    eventType: string;
+    matchedRules: string[];
+    actions: Array<{
+        ruleId: string;
+        action: WebhookAction;
+        success: boolean;
+        error?: string;
+    }>;
+    responses: Array<{
+        type: string;
+        success: boolean;
+        id?: string;
+        url?: string;
+        error?: string;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cloud/webhooks/types.js

@@ -0,0 +1,8 @@
+/**
+ * Generic Webhook System - Type Definitions
+ *
+ * Defines the core types for a configurable webhook system
+ * that can handle events from any source (GitHub, GitLab, Linear, Slack, etc.)
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/continuity/formatter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Context Formatter
+ *
+ * Formats ledgers, handoffs, and learnings into markdown
+ * for injection into agent context.
+ */
+import type { Ledger, Handoff, StartupContext, FileRef, Decision } from './types.js';
+/**
+ * Format options for context injection
+ */
+export interface FormatOptions {
+    /** Maximum length of the formatted context */
+    maxLength?: number;
+    /** Include file references */
+    includeFiles?: boolean;
+    /** Include decisions */
+    includeDecisions?: boolean;
+    /** Include learnings */
+    includeLearnings?: boolean;
+    /** Compact mode (less verbose) */
+    compact?: boolean;
+}
+/**
+ * Format a startup context for injection
+ */
+export declare function formatStartupContext(context: Omit<StartupContext, 'formatted'>, options?: FormatOptions): string;
+/**
+ * Format a ledger for context injection
+ */
+export declare function formatLedger(ledger: Ledger, options?: FormatOptions): string;
+/**
+ * Format a handoff for context injection
+ */
+export declare function formatHandoff(handoff: Handoff, options?: FormatOptions): string;
+/**
+ * Format a search result summary
+ */
+export declare function formatSearchResults(handoffs: Handoff[], query: string): string;
+/**
+ * Format a brief status summary (for status line / dashboard)
+ */
+export declare function formatBriefStatus(ledger: Ledger | null, handoff: Handoff | null): string;
+/**
+ * Format file references for injection
+ */
+export declare function formatFileRefs(files: FileRef[]): string;
+/**
+ * Format decisions for injection
+ */
+export declare function formatDecisions(decisions: Decision[]): string;
+//# sourceMappingURL=formatter.d.ts.map