@fenixforce/kernel 0.1.0

package/dist/api/webhook-triggers.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Webhook Triggers — handles POST /api/v1/webhooks/:id
+ *
+ * Validates incoming webhook signatures, creates MessageEnvelopes,
+ * enqueues to the job queue for async processing, and returns 200
+ * immediately. The worker processes the webhook asynchronously.
+ *
+ * Supported providers:
+ *  - GitHub:  SHA-256 HMAC via x-hub-signature-256
+ *  - Stripe:  Custom t=...,v1=... signature via stripe-signature
+ *  - Generic: Bearer token, custom header, or IP allowlist
+ *
+ * All signature comparisons use crypto.timingSafeEqual.
+ */
+export interface WebhookMessageEnvelope {
+    channel: "webhook";
+    userId: string;
+    userName?: string;
+    conversationId: string;
+    messageType: "text";
+    content: string;
+    attachments?: undefined;
+    metadata: Record<string, unknown>;
+    timestamp: Date;
+}
+export type WebhookProvider = "github" | "stripe" | "generic";
+export interface GitHubWebhookConfig {
+    provider: "github";
+    /** The shared HMAC secret configured in GitHub webhook settings. */
+    secret: string;
+}
+export interface StripeWebhookConfig {
+    provider: "stripe";
+    /** The Stripe webhook signing secret (whsec_...). */
+    secret: string;
+    /** Tolerance in seconds for timestamp validation. Default 300 (5 min). */
+    toleranceSec?: number;
+}
+export interface GenericWebhookConfig {
+    provider: "generic";
+    /** Bearer token for Authorization header validation. */
+    bearerToken?: string;
+    /** Custom header name + expected value. */
+    customHeader?: {
+        name: string;
+        value: string;
+    };
+    /** List of allowed source IPs. */
+    ipAllowlist?: string[];
+}
+export type WebhookConfig = GitHubWebhookConfig | StripeWebhookConfig | GenericWebhookConfig;
+export interface WebhookRegistration {
+    id: string;
+    config: WebhookConfig;
+    /** Optional label for this webhook. */
+    label?: string;
+    /** Optional conversation/chat ID to route to. Defaults to "webhook:<id>". */
+    conversationId?: string;
+    /** Whether the webhook is active. Default true. */
+    active: boolean;
+    createdAt: Date;
+}
+export interface WebhookRequest {
+    /** Raw body as string (for signature verification). */
+    rawBody: string;
+    /** Parsed JSON body. */
+    body: Record<string, unknown>;
+    /** HTTP headers (lowercased keys). */
+    headers: Record<string, string>;
+    /** Source IP address. */
+    sourceIp?: string;
+}
+export interface WebhookResult {
+    status: number;
+    body: Record<string, unknown>;
+}
+export type WebhookEventType = "webhook_received" | "webhook_validated" | "webhook_enqueued" | "webhook_validation_failed" | "webhook_not_found" | "webhook_inactive";
+export interface WebhookEvent {
+    type: WebhookEventType;
+    timestamp: Date;
+    webhookId?: string;
+    detail: string;
+}
+export type WebhookEventListener = (event: WebhookEvent) => void;
+export interface WebhookJobQueue {
+    enqueue(type: string, payload: unknown, chatId?: string): {
+        id: string;
+    };
+}
+/**
+ * Timing-safe string comparison using crypto.timingSafeEqual.
+ */
+export declare function safeEqual(a: string, b: string): boolean;
+/**
+ * Verify GitHub webhook signature (x-hub-signature-256).
+ * Format: sha256=<hex-digest>
+ */
+export declare function verifyGitHubSignature(rawBody: string, secret: string, signatureHeader: string): boolean;
+/**
+ * Verify Stripe webhook signature (stripe-signature header).
+ * Format: t=<timestamp>,v1=<signature>[,v1=<signature>...]
+ */
+export declare function verifyStripeSignature(rawBody: string, secret: string, signatureHeader: string, toleranceSec?: number): boolean;
+/**
+ * Verify generic webhook authentication.
+ */
+export declare function verifyGenericAuth(request: WebhookRequest, config: GenericWebhookConfig): boolean;
+/**
+ * Extract a meaningful content summary from a webhook payload.
+ */
+export declare function extractWebhookContent(provider: WebhookProvider, body: Record<string, unknown>, headers: Record<string, string>): string;
+export declare function createWebhookEnvelope(webhookId: string, provider: WebhookProvider, request: WebhookRequest, conversationId?: string): WebhookMessageEnvelope;
+export interface WebhookHandlerConfig {
+    /** Job queue to enqueue validated webhooks into. */
+    queue: WebhookJobQueue;
+    /** Job type to use when enqueuing. Default "tool.execute". */
+    jobType?: string;
+}
+export interface WebhookHandler {
+    /** Register a new webhook endpoint. Returns the registration. */
+    register(id: string, config: WebhookConfig, opts?: {
+        label?: string;
+        conversationId?: string;
+    }): WebhookRegistration;
+    /** Unregister a webhook. */
+    unregister(id: string): boolean;
+    /** Get a webhook registration. */
+    get(id: string): WebhookRegistration | undefined;
+    /** List all registrations. */
+    list(): WebhookRegistration[];
+    /** Enable/disable a webhook. */
+    setActive(id: string, active: boolean): boolean;
+    /** Handle an incoming webhook request (POST /api/v1/webhooks/:id).
+     *  Validates, creates envelope, enqueues to job queue, returns 200. */
+    handleRequest(webhookId: string, request: WebhookRequest): WebhookResult;
+    on(listener: WebhookEventListener): void;
+    off(listener: WebhookEventListener): void;
+}
+export declare function createWebhookHandler(config: WebhookHandlerConfig): WebhookHandler;

package/dist/billing/cost-meter.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Cost Meter — tracks LLM token usage, enforces per-user budgets,
+ * emits warning events at 80% threshold, supports admin overrides,
+ * and provides usage dashboard data.
+ */
+export interface ModelPricing {
+    /** Cost per 1M input tokens in USD. */
+    inputPer1M: number;
+    /** Cost per 1M output tokens in USD. */
+    outputPer1M: number;
+}
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+export interface UsageRecord {
+    id: string;
+    userId: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cost: number;
+    timestamp: Date;
+    /** Optional context (e.g. tool name, job type). */
+    context?: string;
+}
+export type BudgetPeriod = "hourly" | "daily" | "monthly";
+export interface BudgetConfig {
+    /** Maximum spend in USD for this budget period. */
+    limit: number;
+    /** Budget period. */
+    period: BudgetPeriod;
+    /** Warning threshold as fraction (default 0.8 = 80%). */
+    warningThreshold?: number;
+}
+export interface UserBudget {
+    userId: string;
+    config: BudgetConfig;
+    /** Whether admin override is active (bypasses budget). */
+    adminOverride: boolean;
+}
+export type MeterEventType = "usage_recorded" | "budget_warning" | "budget_exceeded" | "quota:warning" | "quota:exceeded" | "budget_override_set" | "budget_override_cleared" | "budget_reset";
+export interface MeterEvent {
+    type: MeterEventType;
+    userId: string;
+    timestamp: Date;
+    data: Record<string, unknown>;
+}
+export type MeterEventListener = (event: MeterEvent) => void;
+export interface PreCallCheck {
+    allowed: boolean;
+    reason?: string;
+    remainingBudget?: number;
+    usedFraction?: number;
+}
+/** Per-period usage summary for dashboard. */
+export interface PeriodSummary {
+    userId: string;
+    period: string;
+    totalCost: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    requestCount: number;
+    budgetLimit?: number;
+    usedFraction?: number;
+}
+/** Model-level breakdown for dashboard. */
+export interface ModelBreakdown {
+    model: string;
+    totalCost: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    requestCount: number;
+}
+export interface DashboardData {
+    userId: string;
+    currentPeriod: PeriodSummary;
+    modelBreakdown: ModelBreakdown[];
+    recentRecords: UsageRecord[];
+    budget?: {
+        limit: number;
+        period: string;
+        used: number;
+        remaining: number;
+        fraction: number;
+        adminOverride: boolean;
+    };
+}
+export interface CostMeter {
+    /** Register pricing for a model. */
+    setModelPricing(model: string, pricing: ModelPricing): void;
+    /** Get pricing for a model, or undefined. */
+    getModelPricing(model: string): ModelPricing | undefined;
+    /** Set a budget for a user. */
+    setBudget(userId: string, config: BudgetConfig): void;
+    /** Get budget for a user. */
+    getBudget(userId: string): UserBudget | undefined;
+    /** Remove a user's budget entirely. */
+    removeBudget(userId: string): boolean;
+    /** Enable admin override: user's calls bypass budget checks. */
+    setAdminOverride(userId: string, enabled: boolean): void;
+    /** Check if a call should be allowed, given estimated cost. */
+    checkBudget(userId: string, estimatedCost: number): PreCallCheck;
+    /** Convenience: estimate cost for a given model + token count. */
+    estimateCost(model: string, usage: TokenUsage): number;
+    /** Record actual usage after a call completes. */
+    recordUsage(userId: string, model: string, usage: TokenUsage, context?: string): UsageRecord;
+    /** Get total spend for user in the current budget period. */
+    getCurrentPeriodSpend(userId: string): number;
+    /** Get all records for a user (optionally filtered by period). */
+    getRecords(userId: string, periodKey?: string): UsageRecord[];
+    /** Get usage dashboard data for a user. */
+    getDashboardData(userId: string): DashboardData;
+    /** Subscribe to meter events. */
+    on(listener: MeterEventListener): void;
+    /** Unsubscribe. */
+    off(listener: MeterEventListener): void;
+    /** Reset spend tracking for a user (new period). */
+    resetPeriod(userId: string): void;
+}
+export declare function _resetMeterIds(): void;
+export declare function createCostMeter(): CostMeter;

package/dist/billing/index.d.ts

@@ -0,0 +1,2 @@
+export { CostMeter, createCostMeter, _resetMeterIds } from "./cost-meter.js";
+export type { ModelPricing, TokenUsage, UsageRecord, BudgetPeriod, BudgetConfig, UserBudget, MeterEventType, MeterEvent, MeterEventListener, PreCallCheck, PeriodSummary, ModelBreakdown, DashboardData, } from "./cost-meter.js";

package/dist/boot.d.ts

@@ -0,0 +1,109 @@
+import type { AgentEvent, AgentInput } from "./events/types.js";
+import type { StorageAdapter } from "./storage/interface.js";
+import type { MemoryBackend } from "./tools/routers/memory-router.js";
+import type { WebBackend } from "./tools/routers/web-router.js";
+import type { CodeBackend } from "./tools/routers/code-router.js";
+import type { FileBackend } from "./tools/routers/file-router.js";
+import type { ScheduleBackend } from "./tools/routers/schedule-router.js";
+import type { TaskPlanBackend } from "./tools/routers/task-router.js";
+import type { BrowserEngine } from "./tools/browser-engine.js";
+import { EventBus } from "./events/bus.js";
+import { SessionManager } from "./events/session-manager.js";
+import { ProviderManager } from "./providers/manager.js";
+import { ExtensionManager } from "./extensions/manager.js";
+import { ToolRegistry } from "./tools/registry.js";
+import { ToolRouter } from "./tools/router.js";
+import { SidecarManager } from "./voice/sidecar-manager.js";
+import { SpeechQueue } from "./voice/speech-intent.js";
+import { parseMarkers, stripMarkers } from "./voice/marker-parser.js";
+import { ProgressiveSearch } from "./memory/progressive-search.js";
+import { verifiedGenerateObject } from "./providers/structured-verify.js";
+export interface BootConfig {
+    /** Edition name */
+    edition: string;
+    /** Database URL for PostgreSQL storage */
+    databaseUrl?: string;
+    /** Storage backend override */
+    storageBackend?: "postgres" | "sqlite";
+    /** Provider configuration overrides */
+    providers?: Record<string, {
+        provider: string;
+        model: string;
+        apiKey?: string;
+        baseUrl?: string;
+    }>;
+    /** Channels to enable */
+    channels?: string[];
+    /** Tool categories to enable ("*" for all) */
+    tools?: string[];
+    /** Domain-specific layers */
+    layers?: string[];
+    /** Maximum agent loop turns */
+    maxTurns?: number;
+    /** Token budget per session */
+    tokenBudget?: number;
+    /** Context window token limit */
+    contextWindowTokens?: number;
+    /** Enable query pre-classification */
+    enablePreClassification?: boolean;
+    /** Enable structured block emission */
+    emitBlocks?: boolean;
+    /** System prompt text (when provided, skips dynamic prompt building) */
+    systemPrompt?: string;
+    /** Read-only tool names for parallel execution */
+    readOnlyTools?: string[];
+}
+/** Optional backend dependencies for tool routers */
+export interface BootDeps {
+    memoryBackend?: MemoryBackend;
+    webBackend?: WebBackend;
+    codeBackend?: CodeBackend;
+    fileBackend?: FileBackend;
+    scheduleBackend?: ScheduleBackend;
+    taskBackend?: TaskPlanBackend;
+    browserEngine?: BrowserEngine;
+    storage?: StorageAdapter;
+}
+export interface RunningKernel {
+    readonly edition: string;
+    readonly version: string;
+    readonly config: BootConfig;
+    readonly bus: EventBus;
+    readonly sessions: SessionManager;
+    readonly providers: ProviderManager;
+    readonly extensions: ExtensionManager;
+    readonly toolRegistry: ToolRegistry;
+    readonly toolRouter: ToolRouter;
+    readonly storage: StorageAdapter | null;
+    /** Voice utilities (available when voice modules are loaded) */
+    readonly voice: {
+        sidecarManager: SidecarManager;
+        speechQueue: SpeechQueue;
+        parseMarkers: typeof parseMarkers;
+        stripMarkers: typeof stripMarkers;
+    };
+    /** Memory utilities */
+    readonly memory: {
+        progressiveSearch: ProgressiveSearch | null;
+    };
+    /** Verified structured output wrapper */
+    readonly verifiedGenerateObject: typeof verifiedGenerateObject;
+    /** Send a message through the agent loop */
+    sendMessage(sessionId: string, input: AgentInput): AsyncGenerator<AgentEvent, void, undefined>;
+    health(): KernelHealth;
+    stop(): Promise<void>;
+}
+export interface KernelHealth {
+    status: "ok" | "degraded" | "error";
+    edition: string;
+    version: string;
+    providers: {
+        slot: string;
+        healthy: boolean;
+    }[];
+    storage: boolean;
+    extensions: number;
+    tools: number;
+}
+export declare const KERNEL_VERSION = "0.1.0";
+export declare function bootKernel(config: BootConfig, deps?: BootDeps): Promise<RunningKernel>;

package/dist/channels/discord.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Discord Channel Adapter
+ *
+ * Connects to Discord via Gateway WebSocket using discord.js.
+ * Supports slash commands, thread-based conversations, voice channels,
+ * rich embeds, message chunking, and reaction-based approval gates.
+ */
+import type { MessageHandler } from "./types.js";
+import type { STTProvider, TTSProvider, TaskInfo, JobInfo } from "./telegram.js";
+export interface DiscordConfig {
+    botToken: string;
+    onMessage: MessageHandler;
+    onReset?: (conversationId: string) => Promise<string>;
+    onTasks?: (conversationId: string) => Promise<TaskInfo[]>;
+    onJobs?: (conversationId: string) => Promise<JobInfo[]>;
+    /** Restrict to specific servers (guild IDs). */
+    guildIds?: string[];
+    /** Restrict to specific channels. */
+    allowedChannelIds?: string[];
+    /** Join voice channels for audio I/O. */
+    enableVoice?: boolean;
+    /** Command prefix for text commands (e.g. "!"). Default: use slash commands only. */
+    commandPrefix?: string;
+    stt?: STTProvider;
+    tts?: TTSProvider;
+    /** Override fetch for testing. */
+    fetchFn?: typeof globalThis.fetch;
+}
+/** Discord message structure (subset). */
+export interface DiscordMessage {
+    id: string;
+    channel_id: string;
+    guild_id?: string;
+    author: {
+        id: string;
+        username: string;
+        discriminator?: string;
+        bot?: boolean;
+    };
+    content: string;
+    timestamp: string;
+    attachments?: DiscordAttachment[];
+    referenced_message?: DiscordMessage | null;
+    thread?: {
+        id: string;
+    };
+    type?: number;
+}
+export interface DiscordAttachment {
+    id: string;
+    filename: string;
+    content_type?: string;
+    url: string;
+    size: number;
+}
+export interface DiscordInteraction {
+    id: string;
+    type: number;
+    data?: {
+        name: string;
+        options?: Array<{
+            name: string;
+            value: unknown;
+            type: number;
+        }>;
+    };
+    channel_id: string;
+    guild_id?: string;
+    member?: {
+        user: {
+            id: string;
+            username: string;
+        };
+    };
+    user?: {
+        id: string;
+        username: string;
+    };
+    token: string;
+}
+export interface PendingDiscordApproval {
+    id: string;
+    channelId: string;
+    messageId: string;
+    resolve: (choice: string) => void;
+}
+export interface DiscordChannelAdapter {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    sendMessage(conversationId: string, text: string): Promise<void>;
+    /** Process inbound message (for testing). */
+    handleMessage(message: DiscordMessage): Promise<void>;
+    /** Process inbound interaction (slash command). */
+    handleInteraction(interaction: DiscordInteraction): Promise<void>;
+    /** Process reaction add for approval gates. */
+    handleReaction(messageId: string, emoji: string, userId: string): Promise<void>;
+    readonly isRunning: boolean;
+}
+export declare function createDiscordAdapter(config: DiscordConfig): DiscordChannelAdapter;

package/dist/channels/email.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Email Channel Adapter (IMAP/SMTP)
+ *
+ * Polls an IMAP mailbox for inbound emails, converts them to
+ * MessageEnvelopes, and sends replies via SMTP with proper
+ * threading (In-Reply-To / References headers).
+ *
+ * Supports consent gating, sender allow-lists, HTML-to-text
+ * conversion, attachment extraction, and rate limiting.
+ */
+import type { MessageHandler } from "./types.js";
+export interface EmailConfig {
+    imap: {
+        host: string;
+        port: number;
+        user: string;
+        password: string;
+        tls: boolean;
+        /** Mailbox to poll. Default: "INBOX". */
+        mailbox?: string;
+        /** Poll interval in ms. Default: 30000. */
+        pollIntervalMs?: number;
+    };
+    smtp: {
+        host: string;
+        port: number;
+        user: string;
+        password: string;
+        tls: boolean;
+    };
+    onMessage: MessageHandler;
+    /** Only process emails from these addresses. Empty = allow all. */
+    allowedSenders?: string[];
+    /** Require explicit opt-in before processing. Default: false. */
+    consentRequired?: boolean;
+    /** Prefix prepended to reply subject lines. Default: "[Fenix] ". */
+    subjectPrefix?: string;
+    /** Max outbound emails per sender per hour. Default: 10. */
+    rateLimitPerHour?: number;
+    /** Override for testing — inject mock IMAP fetch. */
+    fetchEmails?: () => Promise<InboundEmail[]>;
+    /** Override for testing — inject mock SMTP send. */
+    sendEmail?: (email: OutboundEmail) => Promise<void>;
+}
+/** Parsed inbound email. */
+export interface InboundEmail {
+    messageId: string;
+    from: string;
+    fromName?: string;
+    to: string;
+    subject: string;
+    textBody: string;
+    htmlBody?: string;
+    date: Date;
+    inReplyTo?: string;
+    references?: string[];
+    attachments?: EmailAttachment[];
+}
+export interface EmailAttachment {
+    filename: string;
+    contentType: string;
+    content: string;
+    size: number;
+}
+/** Outbound email for SMTP. */
+export interface OutboundEmail {
+    from: string;
+    to: string;
+    subject: string;
+    textBody: string;
+    htmlBody?: string;
+    inReplyTo?: string;
+    references?: string[];
+    attachments?: EmailAttachment[];
+}
+export interface EmailChannelAdapter {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    sendMessage(conversationId: string, text: string): Promise<void>;
+    /** Process a batch of inbound emails (for testing / manual trigger). */
+    processInbox(emails: InboundEmail[]): Promise<void>;
+    /** Check consent status for a sender. */
+    hasConsent(senderEmail: string): boolean;
+    /** Grant consent for a sender. */
+    grantConsent(senderEmail: string): void;
+    readonly isRunning: boolean;
+}
+export declare function createEmailAdapter(config: EmailConfig): EmailChannelAdapter;