@fenixforce/kernel 0.1.0

package/dist/agent/execution-result.d.ts

@@ -0,0 +1,27 @@
+export type FinishReason = "completed" | "interrupted" | "timeout" | "error" | "hook-halted" | "max-iterations";
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}
+export interface ExecutionResult {
+    /** Final output text from the agent. */
+    output: string;
+    /** Why execution ended. */
+    finishReason: FinishReason;
+    /** Whether the run was interrupted by user or stop signal. */
+    interrupted: boolean;
+    /** Wall-clock duration in milliseconds. */
+    durationMs: number;
+    /** Number of agent loop iterations completed. */
+    iterationCount: number;
+    /** Aggregated token usage across all LLM calls. */
+    tokenUsage?: TokenUsage;
+}
+export declare function createResult(output: string, finishReason: FinishReason, opts: {
+    durationMs: number;
+    iterationCount: number;
+    tokenUsage?: TokenUsage;
+}): ExecutionResult;
+export declare function mergeTokenUsage(a?: TokenUsage, b?: TokenUsage): TokenUsage;

package/dist/agent-loop.d.ts

@@ -0,0 +1,55 @@
+import type { ProviderManager } from "./providers/manager.js";
+import type { ToolRouter } from "./tools/router.js";
+import type { JobQueue } from "./job-queue.js";
+import type { ExtensionManager } from "./extensions/manager.js";
+import type { AgentEvent, AgentMode, AgentInput, AgentContext, QueryClassification, BlockType, BlockPatch } from "./events/types.js";
+export interface AgentLoopConfig {
+    /** Provider manager for slot-based routing */
+    providers: ProviderManager;
+    /** Tool router for dispatching tool calls */
+    toolRouter: ToolRouter;
+    /** Job queue for async work (optional) */
+    jobQueue?: JobQueue;
+    /** Extension manager for hook dispatch (optional) */
+    extensions?: ExtensionManager;
+    /** Session ID */
+    sessionId: string;
+    /** Maximum turns before forced stop */
+    maxTurns?: number;
+    /** Token budget per session */
+    tokenBudget?: number;
+    /** Context window size for overflow detection */
+    contextWindowTokens?: number;
+    /** Initial mode */
+    initialMode?: AgentMode;
+    /** System prompt */
+    systemPrompt?: string;
+    /** Mode permissions for tool context */
+    permissions?: string[];
+    /** Query classifier — if provided, runs pre-classification (G26) */
+    classifyQuery?: QueryClassifier;
+    /** Whether to emit structured blocks (G25) instead of raw tokens */
+    emitBlocks?: boolean;
+    /** Read-only tool names for parallel execution */
+    readOnlyTools?: Set<string>;
+}
+/** G26 query pre-classifier function */
+export type QueryClassifier = (query: string, context: AgentContext) => Promise<QueryClassificationResult>;
+export interface QueryClassificationResult {
+    classification: QueryClassification;
+    standaloneQuery: string;
+    skipAgent: boolean;
+    directResponse?: string;
+}
+export declare class BlockManager {
+    private blocks;
+    private nextId;
+    create(type: BlockType, data: unknown): string;
+    append(blockId: string, content: string): BlockPatch | null;
+    get(blockId: string): {
+        type: BlockType;
+        data: unknown;
+    } | undefined;
+    get size(): number;
+}
+export declare function agentLoop(config: AgentLoopConfig, input: AgentInput): AsyncGenerator<AgentEvent, void, undefined>;

package/dist/api/dashboard.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Mission Control Dashboard API — unified API surface for the Fenix
+ * dashboard frontend. Three pillars: Activity Feed, Task Calendar,
+ * Global Search, plus stats/providers/jobs/costs endpoints.
+ *
+ * Endpoints:
+ *   GET /api/v1/dashboard/activity   — Activity feed with filters
+ *   GET /api/v1/dashboard/calendar   — Scheduled tasks for date range
+ *   GET /api/v1/dashboard/search     — Global search
+ *   GET /api/v1/dashboard/stats      — Token usage, provider health, memory
+ *   GET /api/v1/dashboard/providers  — Circuit breaker states, cost per provider
+ *   GET /api/v1/dashboard/jobs       — Job queue status
+ *   GET /api/v1/dashboard/costs      — Cost breakdown by provider/time
+ */
+export interface ActivityEntry {
+    id: string;
+    /** Event type from the agent event system. */
+    eventType: string;
+    /** Channel that generated this event. */
+    channel?: string;
+    /** Session ID. */
+    sessionId?: string;
+    /** Short human-readable description. */
+    summary: string;
+    /** Status indicator. */
+    status: "info" | "success" | "warning" | "error";
+    /** Full event payload. */
+    payload: Record<string, unknown>;
+    /** When this event occurred. */
+    timestamp: Date;
+}
+export interface ActivityFilter {
+    /** Filter by event types. */
+    eventTypes?: string[];
+    /** Filter by channel. */
+    channels?: string[];
+    /** Filter by date range. */
+    dateRange?: {
+        from: Date;
+        to: Date;
+    };
+    /** Filter by status. */
+    status?: ActivityEntry["status"];
+    /** Full-text search in summary. */
+    search?: string;
+    /** Maximum results. Default 50. */
+    limit?: number;
+    /** Offset for pagination. */
+    offset?: number;
+}
+export interface ActivityFeed {
+    /** Log an agent event to the activity feed. */
+    log(entry: Omit<ActivityEntry, "id" | "timestamp">): ActivityEntry;
+    /** Query the activity feed. */
+    query(filter?: ActivityFilter): ActivityEntry[];
+    /** Total count matching filter (for pagination). */
+    count(filter?: ActivityFilter): number;
+    /** Clear all entries. */
+    clear(): void;
+}
+export interface CalendarTask {
+    id: string;
+    /** Task or job name. */
+    name: string;
+    /** Schedule type. */
+    scheduleType: "cron" | "once" | "recurring";
+    /** Next scheduled execution time. */
+    nextRun: Date | null;
+    /** Last execution time. */
+    lastRun: Date | null;
+    /** Current status. */
+    status: "active" | "paused" | "completed" | "cancelled";
+    /** Source: scheduler or job queue. */
+    source: "scheduler" | "job_queue";
+    /** Additional metadata. */
+    metadata?: Record<string, unknown>;
+}
+export interface CalendarQuery {
+    /** Start of date range. */
+    from: Date;
+    /** End of date range. */
+    to: Date;
+    /** Filter by status. */
+    status?: CalendarTask["status"];
+    /** Filter by source. */
+    source?: CalendarTask["source"];
+}
+export interface TaskCalendar {
+    /** Get scheduled tasks for a date range. */
+    query(opts: CalendarQuery): CalendarTask[];
+    /** Pause a scheduled task. */
+    pause(taskId: string): boolean;
+    /** Resume a paused task. */
+    resume(taskId: string): boolean;
+    /** Cancel a scheduled task. */
+    cancel(taskId: string): boolean;
+    /** Reschedule a task to a new time. */
+    reschedule(taskId: string, newTime: Date): boolean;
+}
+export type SearchScope = "memory" | "conversations" | "tools" | "tasks" | "content" | "all";
+export interface GlobalSearchResult {
+    /** Result identifier. */
+    id: string;
+    /** Which scope this result came from. */
+    scope: SearchScope;
+    /** Display title. */
+    title: string;
+    /** Content snippet. */
+    snippet: string;
+    /** Relevance score. */
+    score: number;
+    /** Metadata. */
+    metadata?: Record<string, unknown>;
+}
+export interface GlobalSearchOpts {
+    /** Scopes to search. Default ["all"]. */
+    scopes?: SearchScope[];
+    /** Maximum results per scope. Default 10. */
+    maxResults?: number;
+}
+export type GlobalSearchFn = (query: string, opts?: GlobalSearchOpts) => Promise<GlobalSearchResult[]>;
+export interface DashboardStats {
+    /** Token usage summary. */
+    tokenUsage: {
+        totalInput: number;
+        totalOutput: number;
+        totalCost: number;
+        period: string;
+    };
+    /** Provider health overview. */
+    providerHealth: ProviderStatus[];
+    /** Memory breakdown. */
+    memory: {
+        totalEntities: number;
+        totalRelations: number;
+        totalFacts: number;
+        totalContentSources: number;
+    };
+    /** Active sessions. */
+    activeSessions: number;
+    /** Pending jobs. */
+    pendingJobs: number;
+}
+export interface ProviderStatus {
+    name: string;
+    /** Circuit breaker state. */
+    circuitState: "closed" | "open" | "half-open";
+    /** Total cost for this provider. */
+    totalCost: number;
+    /** Request count. */
+    requestCount: number;
+    /** Error count. */
+    errorCount: number;
+    /** Average latency in ms. */
+    avgLatencyMs: number;
+}
+export interface CostBreakdown {
+    /** Provider name. */
+    provider: string;
+    /** Time period label. */
+    period: string;
+    /** Input token cost. */
+    inputCost: number;
+    /** Output token cost. */
+    outputCost: number;
+    /** Total cost. */
+    totalCost: number;
+    /** Request count. */
+    requestCount: number;
+}
+export interface JobStatus {
+    /** Total jobs. */
+    total: number;
+    /** Breakdown by status. */
+    queued: number;
+    running: number;
+    completed: number;
+    failed: number;
+    dead: number;
+    /** Recent completions. */
+    recentCompletions: Array<{
+        id: string;
+        type: string;
+        completedAt: Date;
+    }>;
+    /** Recent failures. */
+    recentFailures: Array<{
+        id: string;
+        type: string;
+        error: string;
+        failedAt: Date;
+    }>;
+}
+export interface DashboardConfig {
+    /** Maximum activity entries to retain in memory. Default 1000. */
+    maxActivityEntries?: number;
+    /** Stats data providers (pluggable). */
+    getStats?: () => Promise<DashboardStats>;
+    /** Provider status data. */
+    getProviders?: () => Promise<ProviderStatus[]>;
+    /** Job status data. */
+    getJobs?: () => Promise<JobStatus>;
+    /** Cost breakdown data. */
+    getCosts?: (period?: string) => Promise<CostBreakdown[]>;
+    /** Global search implementation (e.g. backed by DualSearch). */
+    searchFn?: GlobalSearchFn;
+}
+export interface Dashboard {
+    /** Activity feed. */
+    readonly activity: ActivityFeed;
+    /** Task calendar. */
+    readonly calendar: TaskCalendar;
+    /** Global search. */
+    search(query: string, opts?: GlobalSearchOpts): Promise<GlobalSearchResult[]>;
+    /** Get dashboard stats. */
+    getStats(): Promise<DashboardStats>;
+    /** Get provider statuses. */
+    getProviders(): Promise<ProviderStatus[]>;
+    /** Get job status overview. */
+    getJobs(): Promise<JobStatus>;
+    /** Get cost breakdown. */
+    getCosts(period?: string): Promise<CostBreakdown[]>;
+    /** Handle GET /api/v1/dashboard/activity */
+    handleActivity(params: Record<string, string | undefined>): {
+        status: number;
+        body: unknown;
+    };
+    /** Handle GET /api/v1/dashboard/calendar */
+    handleCalendar(params: Record<string, string | undefined>): {
+        status: number;
+        body: unknown;
+    };
+    /** Handle GET /api/v1/dashboard/search */
+    handleSearch(params: Record<string, string | undefined>): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+    /** Handle GET /api/v1/dashboard/stats */
+    handleStats(): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+    /** Handle GET /api/v1/dashboard/providers */
+    handleProviders(): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+    /** Handle GET /api/v1/dashboard/jobs */
+    handleJobs(): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+    /** Handle GET /api/v1/dashboard/costs */
+    handleCosts(params: Record<string, string | undefined>): Promise<{
+        status: number;
+        body: unknown;
+    }>;
+}
+export declare function _resetDashboardIds(): void;
+export declare function createDashboard(config?: DashboardConfig): Dashboard;

package/dist/api/index.d.ts

@@ -0,0 +1,9 @@
+export { createApiServer, type ApiServer, type ApiServerConfig } from "./server.js";
+export { createSSEStream, createSSEStreamFromIterable } from "./streaming.js";
+export { jsonResponse, errorResponse, parseJsonBody, CORS_HEADERS, corsPreflightResponse, validateAuth, validateRequired, withErrorHandling, buildRoute, matchRoute, ApiException, type ApiError, type RouteHandler, type Route, } from "./middleware.js";
+export { createDashboard, _resetDashboardIds } from "./dashboard.js";
+export type { ActivityEntry, ActivityFilter, ActivityFeed, CalendarTask, CalendarQuery, TaskCalendar, SearchScope, GlobalSearchResult, GlobalSearchOpts, GlobalSearchFn, DashboardStats, ProviderStatus, CostBreakdown, JobStatus, DashboardConfig, Dashboard, } from "./dashboard.js";
+export { validateRequest, createOpenAICompatHandler, _resetCompletionIds, } from "./openai-compat.js";
+export type { ChatRole, ChatMessage, ChatCompletionRequest, ChatCompletionChoice, CompletionUsage, ChatCompletionResponse, ChatCompletionChunkDelta, ChatCompletionChunkChoice, ChatCompletionChunk, AgentCompletionResult, AgentCompletionFn, AgentStreamFn, CompatEventType, CompatEvent, CompatEventListener, ValidationError, OpenAICompatConfig, OpenAICompatHandler, } from "./openai-compat.js";
+export { safeEqual, verifyGitHubSignature, verifyStripeSignature, verifyGenericAuth, extractWebhookContent, createWebhookEnvelope, createWebhookHandler, } from "./webhook-triggers.js";
+export type { WebhookMessageEnvelope, WebhookProvider, GitHubWebhookConfig, StripeWebhookConfig, GenericWebhookConfig, WebhookConfig, WebhookRegistration, WebhookRequest, WebhookResult, WebhookEventType, WebhookEvent, WebhookEventListener, WebhookJobQueue, WebhookHandlerConfig, WebhookHandler, } from "./webhook-triggers.js";

package/dist/api/middleware.d.ts

@@ -0,0 +1,46 @@
+export interface ApiError {
+    error: string;
+    code?: string;
+    status: number;
+}
+export type RouteHandler = (req: Request, params: Record<string, string>) => Promise<Response> | Response;
+export declare const CORS_HEADERS: Record<string, string>;
+export declare function corsPreflightResponse(): Response;
+export declare function errorResponse(status: number, error: string, code?: string): Response;
+export declare function jsonResponse(data: unknown, status?: number): Response;
+/**
+ * Wrap a route handler with error handling.
+ * Catches thrown errors and returns structured JSON error responses.
+ */
+export declare function withErrorHandling(handler: RouteHandler): RouteHandler;
+/**
+ * Validate bearer token from Authorization header.
+ * Returns null if valid or missing (when optional), throws if invalid.
+ */
+export declare function validateAuth(req: Request, expectedToken?: string): string | null;
+export declare function parseJsonBody<T = unknown>(req: Request): Promise<T>;
+export declare function validateRequired(body: Record<string, unknown>, fields: string[]): void;
+export interface Route {
+    method: string;
+    pattern: RegExp;
+    paramNames: string[];
+    handler: RouteHandler;
+}
+/**
+ * Build a route from a pattern like "/api/v1/jobs/:id/cancel".
+ * Extracts named parameters from the URL.
+ */
+export declare function buildRoute(method: string, path: string, handler: RouteHandler): Route;
+/**
+ * Match a request against a list of routes.
+ * Returns the matched route and extracted parameters, or null.
+ */
+export declare function matchRoute(routes: Route[], method: string, pathname: string): {
+    route: Route;
+    params: Record<string, string>;
+} | null;
+export declare class ApiException extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}

package/dist/api/openai-compat.d.ts

@@ -0,0 +1,163 @@
+/**
+ * OpenAI-Compatible API — accepts POST /v1/chat/completions in the
+ * OpenAI SDK format, runs the request through the Fenix agent loop,
+ * and returns a response shaped exactly like OpenAI's API.
+ *
+ * Supports:
+ *  - Non-streaming completions (returns full JSON body)
+ *  - Streaming via SSE (Server-Sent Events) with `stream: true`
+ *  - Token usage tracking
+ *  - Multiple message roles (system, user, assistant, tool)
+ *  - Model routing (passed through to the completion function)
+ *  - stop reasons (stop, length, tool_calls)
+ */
+export type ChatRole = "system" | "user" | "assistant" | "tool";
+export interface ChatMessage {
+    role: ChatRole;
+    content: string | null;
+    name?: string;
+    tool_call_id?: string;
+}
+export interface ChatCompletionRequest {
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    top_p?: number;
+    max_tokens?: number;
+    stream?: boolean;
+    stop?: string | string[];
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    user?: string;
+    /** Fenix extension: pass-through metadata for the agent loop. */
+    metadata?: Record<string, unknown>;
+}
+export interface ChatCompletionChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason: "stop" | "length" | "tool_calls" | null;
+}
+export interface CompletionUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+export interface ChatCompletionResponse {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage: CompletionUsage;
+}
+export interface ChatCompletionChunkDelta {
+    role?: ChatRole;
+    content?: string;
+}
+export interface ChatCompletionChunkChoice {
+    index: number;
+    delta: ChatCompletionChunkDelta;
+    finish_reason: "stop" | "length" | "tool_calls" | null;
+}
+export interface ChatCompletionChunk {
+    id: string;
+    object: "chat.completion.chunk";
+    created: number;
+    model: string;
+    choices: ChatCompletionChunkChoice[];
+}
+export interface AgentCompletionResult {
+    content: string;
+    finishReason?: "stop" | "length" | "tool_calls";
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+}
+/**
+ * A completion function that the Fenix agent loop exposes.
+ * The OpenAI compat layer calls this, and it runs through the full
+ * agent pipeline (instruction hierarchy, approval gates, cost metering, etc.)
+ */
+export type AgentCompletionFn = (opts: {
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    stop?: string | string[];
+    user?: string;
+    metadata?: Record<string, unknown>;
+}) => Promise<AgentCompletionResult>;
+/**
+ * Streaming variant — yields content chunks.
+ */
+export type AgentStreamFn = (opts: {
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    stop?: string | string[];
+    user?: string;
+    metadata?: Record<string, unknown>;
+}) => AsyncIterable<{
+    content: string;
+    done: boolean;
+}>;
+export declare function _resetCompletionIds(): void;
+export type CompatEventType = "request_received" | "completion_success" | "completion_error" | "stream_start" | "stream_end" | "validation_error";
+export interface CompatEvent {
+    type: CompatEventType;
+    timestamp: Date;
+    requestId?: string;
+    model?: string;
+    detail: string;
+}
+export type CompatEventListener = (event: CompatEvent) => void;
+export interface ValidationError {
+    error: {
+        message: string;
+        type: "invalid_request_error";
+        param: string | null;
+        code: string | null;
+    };
+}
+export declare function validateRequest(body: unknown): {
+    valid: true;
+    request: ChatCompletionRequest;
+} | {
+    valid: false;
+    error: ValidationError;
+};
+export interface OpenAICompatConfig {
+    /** The agent completion function (non-streaming). */
+    complete: AgentCompletionFn;
+    /** Optional streaming completion function. If not provided,
+     *  streaming requests fall back to non-streaming + single chunk. */
+    stream?: AgentStreamFn;
+    /** Default model name when none specified in routing. */
+    defaultModel?: string;
+}
+export interface OpenAICompatHandler {
+    /** Handle a /v1/chat/completions request. Returns the response
+     *  body and status code. For streaming, returns an AsyncIterable of SSE lines. */
+    handleCompletion(body: unknown): Promise<{
+        status: number;
+        body: ChatCompletionResponse | ValidationError;
+    } | {
+        status: number;
+        stream: AsyncIterable<string>;
+    }>;
+    /** Handle just validation (useful for middleware). */
+    validate(body: unknown): {
+        valid: true;
+        request: ChatCompletionRequest;
+    } | {
+        valid: false;
+        error: ValidationError;
+    };
+    on(listener: CompatEventListener): void;
+    off(listener: CompatEventListener): void;
+}
+export declare function createOpenAICompatHandler(config: OpenAICompatConfig): OpenAICompatHandler;

package/dist/api/server.d.ts

@@ -0,0 +1,44 @@
+import type { AgentEvent } from "../events/types.js";
+import type { EventBus } from "../events/bus.js";
+import type { SessionManager } from "../events/session-manager.js";
+import type { JobQueue } from "../job-queue.js";
+export interface ApiServerConfig {
+    /** Port to listen on (default: 3000) */
+    port?: number;
+    /** Hostname to bind to (default: "0.0.0.0") */
+    hostname?: string;
+    /** EventBus for pub/sub */
+    bus: EventBus;
+    /** Session manager for reconnection */
+    sessions: SessionManager;
+    /** Job queue for async work (optional) */
+    jobQueue?: JobQueue;
+    /** Bearer token for auth (optional — no auth if omitted) */
+    authToken?: string;
+    /** Handler for incoming messages — should return an async iterable of events */
+    onMessage?: (sessionId: string, message: string) => AsyncIterable<AgentEvent>;
+}
+export interface ApiServer {
+    /** The underlying Bun server */
+    server: ReturnType<typeof Bun.serve>;
+    /** The port the server is listening on */
+    port: number;
+    /** Stop the server */
+    stop(): void;
+}
+/**
+ * Create and start the Fenix HTTP API server.
+ *
+ * Endpoints:
+ * - GET  /api/v1/health
+ * - POST /api/v1/conversations
+ * - GET  /api/v1/conversations/:id
+ * - DELETE /api/v1/conversations/:id
+ * - POST /api/v1/conversations/:id/messages
+ * - GET  /api/v1/jobs
+ * - GET  /api/v1/jobs/:id
+ * - POST /api/v1/jobs/:id/cancel
+ * - POST /api/v1/jobs/:id/retry
+ * - POST /api/v1/reconnect/:sessionId
+ */
+export declare function createApiServer(config: ApiServerConfig): ApiServer;

package/dist/api/streaming.d.ts

@@ -0,0 +1,15 @@
+import type { AgentEvent } from "../events/types.js";
+import type { SessionManager } from "../events/session-manager.js";
+/**
+ * Create an SSE streaming response that replays buffered events
+ * then streams live events from a session.
+ *
+ * Used by both the message endpoint (new session) and the
+ * reconnect endpoint (existing session).
+ */
+export declare function createSSEStream(sessionManager: SessionManager, sessionId: string): Response;
+/**
+ * Create an SSE stream that pipes events from an async iterable.
+ * Used when running a fresh agent loop (not reconnecting).
+ */
+export declare function createSSEStreamFromIterable(events: AsyncIterable<AgentEvent>): Response;