@fenixforce/edition-pro 0.1.0

package/dist/api/approval-routes.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Approval API Routes — Task B3.2
+ *
+ * REST endpoints for the human-in-the-loop approval queue, plus an
+ * SSE stream for real-time approval notifications.
+ */
+import type { ApprovalQueue } from "../business/approval-queue.js";
+import { type Route } from "./middleware.js";
+export interface ApprovalRouteDeps {
+    /** The approval queue instance. */
+    approvalQueue: ApprovalQueue;
+    /** Bearer token for auth (optional — no auth if omitted). */
+    authToken?: string;
+}
+export declare function createApprovalRoutes(deps: ApprovalRouteDeps): Route[];

package/dist/api/fleet-routes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Fleet API Routes — Task B3.1
+ *
+ * REST endpoints for fleet management, workspace CRUD, templates,
+ * and budget tracking. Uses Bun.serve-compatible Route[] pattern.
+ */
+import type { FleetCoordinator } from "../business/fleet.js";
+import type { FleetBudget } from "../business/fleet-budget.js";
+import { type FleetConfig } from "../business/fleet-config.js";
+import { type Route } from "./middleware.js";
+export interface FleetRouteDeps {
+    /** The fleet coordinator managing workspaces and routing. */
+    coordinator: FleetCoordinator;
+    /** Fleet-level budget tracker (optional). */
+    fleetBudget?: FleetBudget;
+    /** Bearer token for auth (optional — no auth if omitted). */
+    authToken?: string;
+    /** Callback to update fleet config on PUT /fleet/config. */
+    onConfigUpdate?: (config: FleetConfig) => Promise<void>;
+    /** Callback to send a message directly to a workspace (bypasses router). */
+    onWorkspaceMessage?: (workspaceId: string, message: string, userId: string) => Promise<unknown>;
+}
+export declare function createFleetRoutes(deps: FleetRouteDeps): Route[];

package/dist/api/integration-routes.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Integration API Routes — Task B3.1
+ *
+ * REST endpoints for managing external service integrations
+ * (connect, disconnect, grant/revoke workspace access).
+ */
+import type { IntegrationRegistry } from "../business/integration-registry.js";
+import { type Route } from "./middleware.js";
+export interface IntegrationRouteDeps {
+    /** Integration registry instance. */
+    registry: IntegrationRegistry;
+    /** Fleet ID scope for the authenticated customer. */
+    fleetId: string;
+    /** Bearer token for auth (optional — no auth if omitted). */
+    authToken?: string;
+}
+export declare function createIntegrationRoutes(deps: IntegrationRouteDeps): Route[];

package/dist/api/middleware.d.ts

@@ -0,0 +1,37 @@
+/**
+ * API Middleware — Shared route matching, auth, and response helpers
+ * for the Pro edition HTTP API.
+ *
+ * Mirrors the kernel's api/middleware.ts patterns for consistency,
+ * kept local to avoid depending on unexported kernel internals.
+ */
+export type RouteHandler = (req: Request, params: Record<string, string>) => Promise<Response> | Response;
+export interface Route {
+    method: string;
+    pattern: RegExp;
+    paramNames: string[];
+    handler: RouteHandler;
+}
+export interface ApiError {
+    error: string;
+    code?: string;
+    status: number;
+}
+export declare const CORS_HEADERS: Record<string, string>;
+export declare function corsPreflightResponse(): Response;
+export declare function jsonResponse(data: unknown, status?: number): Response;
+export declare function errorResponse(status: number, error: string, code?: string): Response;
+export declare class ApiException extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+export declare function withErrorHandling(handler: RouteHandler): RouteHandler;
+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 declare function buildRoute(method: string, path: string, handler: RouteHandler): Route;
+export declare function matchRoute(routes: Route[], method: string, pathname: string): {
+    route: Route;
+    params: Record<string, string>;
+} | null;

package/dist/boot.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Pro Edition Boot — Fleet/Single mode switcher (Task B1.1)
+ *
+ * If a fleet config is present, boots FleetCoordinator (multi-workspace).
+ * Otherwise, boots single workspace as before (backward compatible).
+ * Wires fleet events to kernel EventBus.
+ */
+import { type KernelConfig, type Kernel, type RunningKernel } from "@fenixforce/kernel";
+import { type FleetCoordinator, type FleetCoordinatorDeps, type FleetStatusReport } from "./business/index.js";
+export type ProBootMode = "single" | "fleet";
+export interface ProInstance {
+    readonly mode: ProBootMode;
+    readonly kernel: Kernel;
+    /** Fully-wired kernel with agent loop, providers, tools (available after bootPro) */
+    readonly runningKernel: RunningKernel | null;
+    readonly fleet: FleetCoordinator | null;
+    health(): HealthStatus;
+    stop(): Promise<void>;
+}
+export interface HealthStatus {
+    status: "ok" | "degraded" | "error";
+    mode: ProBootMode;
+    version: string;
+    fleet?: FleetStatusReport;
+}
+export interface ProBootOptions {
+    kernelConfig?: Partial<KernelConfig>;
+    fleetDeps?: FleetCoordinatorDeps;
+    customerId?: string;
+}
+/**
+ * Boot the Pro edition.
+ *
+ * @param fleetConfigRaw - Raw fleet config object (e.g. parsed from fleet.json).
+ *   Pass null/undefined to boot in single mode.
+ */
+export declare function bootPro(fleetConfigRaw: unknown | null, options?: ProBootOptions): Promise<ProInstance>;

package/dist/business/approval-queue.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Approval Queue — Task B2.2
+ *
+ * Manages human-in-the-loop approval workflow. Actions requiring
+ * approval are queued, and can be approved (executing the action),
+ * rejected, or edited (sent back for revision).
+ */
+export type ApprovalStatus = "pending" | "approved" | "rejected" | "edited" | "expired";
+export interface ApprovalItem {
+    id: string;
+    workspaceId: string;
+    /** Human-readable summary of the action. */
+    content: string;
+    /** Serialized tool call: which tool + arguments to execute on approval. */
+    toolCall: {
+        tool: string;
+        args: Record<string, unknown>;
+    };
+    status: ApprovalStatus;
+    createdAt: Date;
+    expiresAt: Date;
+    resolvedAt: Date | null;
+    resolvedBy: string | null;
+    notes: string | null;
+}
+export interface ApprovalListFilters {
+    workspaceId?: string;
+    status?: ApprovalStatus;
+    limit?: number;
+}
+/** Minimal storage interface for approval persistence. */
+export interface StorageAdapter {
+    insertApproval(item: ApprovalItem): Promise<void>;
+    getApproval(id: string): Promise<ApprovalItem | null>;
+    updateApproval(id: string, updates: Partial<ApprovalItem>): Promise<void>;
+    listApprovals(filters: ApprovalListFilters): Promise<ApprovalItem[]>;
+    /** Count consecutive approved items (no edits/rejects) for auto-approval check. */
+    countConsecutiveApprovals(workspaceId: string, actionType: string): Promise<number>;
+}
+/** Executes a tool call that was held for approval. */
+export interface ToolExecutor {
+    execute(toolCall: {
+        tool: string;
+        args: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+/** Sends notification when an approval item is pending. */
+export interface NotificationDispatcher {
+    send(channel: string, message: string): Promise<void>;
+}
+export interface ApprovalQueueConfig {
+    /** Default expiration in days for new items. */
+    defaultExpirationDays?: number;
+    /** Notification channel (e.g., "telegram:12345"). Null disables notifications. */
+    notifyChannel?: string | null;
+    /** Number of consecutive approvals required before auto-approval kicks in. */
+    autoApprovalThreshold?: number;
+}
+export type ApprovalEventType = "approval:pending" | "approval:approved" | "approval:rejected" | "approval:edited" | "approval:expired";
+export type ApprovalEventListener = (event: {
+    type: ApprovalEventType;
+    item: ApprovalItem;
+}) => void;
+export declare class ApprovalQueue {
+    private storage;
+    private executor;
+    private notifier;
+    private config;
+    private listeners;
+    constructor(storage: StorageAdapter, executor: ToolExecutor, notifier?: NotificationDispatcher | null, config?: ApprovalQueueConfig);
+    /** Subscribe to approval events. Returns unsubscribe function. */
+    on(listener: ApprovalEventListener): () => void;
+    private emit;
+    /** Submit a new item for approval. */
+    submit(submission: Omit<ApprovalItem, "id" | "status" | "createdAt" | "expiresAt" | "resolvedAt" | "resolvedBy" | "notes">): Promise<ApprovalItem>;
+    /** List approval items with optional filters. */
+    list(filters?: ApprovalListFilters): Promise<ApprovalItem[]>;
+    /** Approve an item — executes the pending action. */
+    approve(itemId: string, resolvedBy?: string): Promise<{
+        item: ApprovalItem;
+        result: unknown;
+    }>;
+    /** Reject an item — sends notes back to workspace. */
+    reject(itemId: string, notes?: string, resolvedBy?: string): Promise<ApprovalItem>;
+    /** Edit an item — sends notes back to workspace for revision. */
+    edit(itemId: string, notes: string, resolvedBy?: string): Promise<ApprovalItem>;
+    /** Mark items past their expiration as expired. */
+    expireStale(): Promise<ApprovalItem[]>;
+}
+/**
+ * Check if a workspace/action pair qualifies for auto-approval.
+ * Returns true if N consecutive approvals exist with no edits/rejects.
+ */
+export declare function checkAutoApproval(storage: StorageAdapter, workspaceId: string, actionType: string, threshold?: number): Promise<boolean>;

package/dist/business/arena.d.ts

@@ -0,0 +1,71 @@
+export interface ArenaConfig {
+    taskId: string;
+    /** Number of competing agents */
+    agentCount: number;
+    /** Weighted evaluation criteria (values 0–1) */
+    evaluationCriteria: {
+        correctness: number;
+        efficiency: number;
+        style: number;
+    };
+    /** Shared time limit in ms */
+    timeLimitMs?: number;
+}
+export declare const DEFAULT_ARENA_CONFIG: Partial<ArenaConfig>;
+export interface ArenaContestant {
+    agentId: string;
+    workspaceId: string;
+    output: unknown;
+    toolCallCount: number;
+    elapsedMs: number;
+    testsPass: boolean;
+}
+export interface ArenaScore {
+    agentId: string;
+    correctnessScore: number;
+    efficiencyScore: number;
+    styleScore: number;
+    weightedTotal: number;
+    reasoning: string;
+}
+export interface ArenaDiff {
+    winnerId: string;
+    loserId: string;
+    diffSummary: string;
+}
+export interface ArenaResult {
+    taskId: string;
+    winner: ArenaContestant;
+    scores: ArenaScore[];
+    diffs: ArenaDiff[];
+    allContestants: ArenaContestant[];
+}
+export type ContestantExecutorFn = (taskId: string, agentId: string) => Promise<ArenaContestant>;
+export type ArenaJudgeFn = (contestants: ArenaContestant[], criteria: ArenaConfig["evaluationCriteria"]) => Promise<ArenaScore[]>;
+export type DiffGeneratorFn = (winner: ArenaContestant, loser: ArenaContestant) => Promise<string>;
+export type ArenaEventEmitter = (event: string, payload: Record<string, unknown>) => void;
+export declare class ArenaEngine {
+    private execute;
+    private judge;
+    private generateDiff;
+    private emit;
+    constructor(deps: {
+        execute: ContestantExecutorFn;
+        judge: ArenaJudgeFn;
+        generateDiff?: DiffGeneratorFn;
+        emit?: ArenaEventEmitter;
+    });
+    /**
+     * Run an arena competition for a task.
+     */
+    compete(config: ArenaConfig): Promise<ArenaResult>;
+}
+/**
+ * Format arena result as an approval queue item for human review.
+ */
+export declare function formatArenaForApproval(result: ArenaResult): {
+    type: "arena-review";
+    taskId: string;
+    summary: string;
+    metadata: Record<string, unknown>;
+};

package/dist/business/best-of-n.d.ts

@@ -0,0 +1,68 @@
+export interface BestOfNConfig {
+    /** Candidate count per subtask */
+    k: number;
+    /** Custom evaluation criteria for judge */
+    judgePrompt?: string;
+    /** Escalate if judge confidence below this */
+    minJudgeConfidence: number;
+    /** Max recursion depth */
+    maxDepth: number;
+}
+export declare const DEFAULT_BEST_OF_N: BestOfNConfig;
+export interface CandidateResult {
+    candidateId: string;
+    workspaceId: string;
+    output: unknown;
+    /** Automated signals */
+    signals: {
+        testsPass?: boolean;
+        lintErrors?: number;
+        outputDiffSize?: number;
+    };
+}
+export interface JudgeScore {
+    candidateId: string;
+    score: number;
+    confidence: number;
+    reasoning: string;
+}
+export interface BestOfNResult {
+    winner: CandidateResult;
+    scores: JudgeScore[];
+    depth: number;
+    reranAfterInvestigation: boolean;
+}
+export interface SubTask {
+    id: string;
+    description: string;
+    parentTaskId?: string;
+}
+export type CandidateExecutorFn = (task: SubTask, candidateId: string) => Promise<CandidateResult>;
+export type JudgeFn = (candidates: CandidateResult[], judgePrompt?: string) => Promise<JudgeScore[]>;
+export type InvestigatorFn = (task: SubTask, candidates: CandidateResult[], scores: JudgeScore[]) => Promise<string>;
+export type BudgetCheckFn = (estimatedCost: number) => boolean;
+export type BestOfNEventEmitter = (event: string, payload: Record<string, unknown>) => void;
+export declare class BestOfNEngine {
+    private config;
+    private execute;
+    private judge;
+    private investigate;
+    private checkBudget;
+    private emit;
+    constructor(config: Partial<BestOfNConfig> | undefined, deps: {
+        execute: CandidateExecutorFn;
+        judge: JudgeFn;
+        investigate?: InvestigatorFn;
+        checkBudget?: BudgetCheckFn;
+        emit?: BestOfNEventEmitter;
+    });
+    /**
+     * Run best-of-N selection for a subtask.
+     */
+    select(task: SubTask, depth?: number): Promise<BestOfNResult>;
+}
+export declare class BudgetExceededError extends Error {
+    taskId: string;
+    candidatesRequested: number;
+    constructor(taskId: string, candidatesRequested: number);
+}

package/dist/business/brainstorm.d.ts

@@ -0,0 +1,42 @@
+export interface BrainstormConfig {
+    /** Parallel brainstorming agents */
+    agentCount: number;
+    /** Problem or creative brief */
+    prompt: string;
+    /** Optional per-agent perspective assignments */
+    perspectives?: string[];
+    /** Run synthesis pass after collection */
+    synthesize: boolean;
+}
+export declare const DEFAULT_BRAINSTORM_CONFIG: Partial<BrainstormConfig>;
+export interface BrainstormIdea {
+    title: string;
+    rationale: string;
+    implementationSketch: string;
+    /** Which agent generated it */
+    agentPerspective: string;
+}
+export interface ThemeCluster {
+    theme: string;
+    ideas: BrainstormIdea[];
+}
+export interface BrainstormResult {
+    /** Top ideas ranked by cross-agent frequency */
+    topIdeas: ScoredIdea[];
+    /** All ideas from all agents */
+    allIdeas: BrainstormIdea[];
+    /** Ideas grouped by theme */
+    themes: ThemeCluster[];
+    agentCount: number;
+}
+export interface ScoredIdea extends BrainstormIdea {
+    /** How many agents proposed similar ideas */
+    crossAgentFrequency: number;
+    score: number;
+}
+export type BrainstormLLMCallFn = (agentId: string, prompt: string) => Promise<string>;
+export type BrainstormEventEmitter = (event: string, payload: Record<string, unknown>) => void;
+/**
+ * Run a parallel brainstorming session.
+ */
+export declare function runBrainstorm(config: BrainstormConfig, llmCall: BrainstormLLMCallFn, emit?: BrainstormEventEmitter): Promise<BrainstormResult>;

package/dist/business/compile-checker.d.ts

@@ -0,0 +1,50 @@
+export interface CompileCheckJob {
+    workspaceId: string;
+    /** Files to verify */
+    changedFiles: string[];
+    /** Build command, e.g. 'bun run build', 'tsc --noEmit' */
+    command: string;
+    /** Timeout in ms */
+    timeout: number;
+    /** For monorepo: package paths to check in parallel */
+    packagePaths?: string[];
+}
+export declare const DEFAULT_COMPILE_TIMEOUT = 30000;
+export interface CompileError {
+    file: string;
+    line: number;
+    column: number;
+    message: string;
+    severity: "error" | "warning";
+}
+export interface CompileCheckResult {
+    workspaceId: string;
+    passed: boolean;
+    fileCount: number;
+    elapsedMs: number;
+    errors: CompileError[];
+    /** Per-package results for monorepo checks */
+    packageResults?: PackageCompileResult[];
+}
+export interface PackageCompileResult {
+    packagePath: string;
+    passed: boolean;
+    errors: CompileError[];
+    elapsedMs: number;
+}
+export type CompileEventEmitter = (event: string, payload: Record<string, unknown>) => void;
+export type ArtifactStoreFn = (key: string, content: string) => Promise<void>;
+/**
+ * Run a compilation check. Returns a concise error summary for LLM context;
+ * full build logs are stored as brain artifacts for human inspection.
+ */
+export declare function runCompileCheck(job: CompileCheckJob, emit?: CompileEventEmitter, storeArtifact?: ArtifactStoreFn): Promise<CompileCheckResult>;
+/**
+ * Format compile errors for injection into agent context.
+ */
+export declare function formatErrorSummary(result: CompileCheckResult): string;
+/**
+ * Parse structured errors from compiler stderr.
+ * Supports TypeScript, ESLint, and generic file:line:col patterns.
+ */
+export declare function parseCompileErrors(stderr: string): CompileError[];

package/dist/business/debate.d.ts

@@ -0,0 +1,38 @@
+export interface DebateConfig {
+    /** Number of debate iterations */
+    rounds: number;
+    /** Decision or proposal to evaluate */
+    topic: string;
+    /** Shared background for both agents */
+    context: string;
+    /** Custom advocate system prompt */
+    advocatePrompt?: string;
+    /** Custom critic system prompt */
+    criticPrompt?: string;
+    /** Route result through approval queue */
+    requireApproval?: boolean;
+}
+export declare const DEFAULT_DEBATE_CONFIG: Partial<DebateConfig>;
+export interface DebateRound {
+    roundNumber: number;
+    advocateArgument: string;
+    criticChallenge: string;
+}
+export interface DebateResult {
+    topic: string;
+    rounds: DebateRound[];
+    /** Synthesized recommendation */
+    recommendation: string;
+    /** Key risks identified by the critic */
+    keyRisks: string[];
+    /** Minority considerations */
+    minorityConsiderations: string[];
+    /** Total LLM calls made */
+    llmCallCount: number;
+}
+export type DebateLLMCallFn = (role: "advocate" | "critic" | "synthesizer", prompt: string) => Promise<string>;
+export type DebateEventEmitter = (event: string, payload: Record<string, unknown>) => void;
+/**
+ * Run an adversarial debate between advocate and critic.
+ */
+export declare function runDebate(config: DebateConfig, llmCall: DebateLLMCallFn, emit?: DebateEventEmitter): Promise<DebateResult>;

package/dist/business/fleet-budget.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Fleet Budget — Task B2.4
+ *
+ * Higher-level budget management for fleets. Wraps the kernel's cost
+ * tracking with fleet-level and per-workspace daily/monthly limits,
+ * budget-exceeded callbacks, and per-workspace cost breakdowns.
+ */
+export interface FleetBudgetConfig {
+    /** Fleet-wide daily spending limit in USD. 0 = unlimited. */
+    dailyLimit: number;
+    /** Fleet-wide monthly spending limit in USD. 0 = unlimited. */
+    monthlyLimit: number;
+    /** Per-workspace daily limit in USD. Undefined or 0 = no per-workspace limit. */
+    perWorkspaceDailyLimit?: number;
+}
+export interface CostEntry {
+    workspaceId: string;
+    amount: number;
+    timestamp: number;
+}
+/** Dependency interface matching the kernel's CostTrackingProvider shape. */
+export interface CostTrackerLike {
+    getRecords(): readonly {
+        estimatedCost: number;
+        timestamp: number;
+    }[];
+    getSummary(): {
+        totalEstimatedCost: number;
+        recordCount: number;
+    };
+}
+export type BudgetExceededType = "fleet_daily" | "fleet_monthly" | "workspace_daily";
+export interface BudgetExceededInfo {
+    workspaceId: string;
+    type: BudgetExceededType;
+    current: number;
+    limit: number;
+}
+export type BudgetExceededHandler = (info: BudgetExceededInfo) => void;
+export interface WorkspaceCostBreakdown {
+    daily: number;
+    monthly: number;
+}
+export declare class FleetBudget {
+    private readonly config;
+    private readonly costTracker?;
+    private readonly entries;
+    private readonly handlers;
+    constructor(config: FleetBudgetConfig, costTracker?: CostTrackerLike | undefined);
+    /** Record a cost against a workspace. */
+    recordCost(workspaceId: string, amount: number): void;
+    /** Get total fleet cost for today (all workspaces). */
+    getCostToday(): number;
+    /** Get total fleet cost for this month (all workspaces). */
+    getCostThisMonth(): number;
+    /** Get cost for a specific workspace in the given period. */
+    getWorkspaceCost(workspaceId: string, period: "day" | "month"): number;
+    /**
+     * Check if a workspace can spend the estimated amount without exceeding
+     * fleet-level or workspace-level budgets. Fires budget-exceeded callbacks
+     * if a limit would be breached.
+     */
+    canSpend(workspaceId: string, estimatedCost: number): boolean;
+    /** Register a callback for budget breach events. Returns unsubscribe function. */
+    onBudgetExceeded(handler: BudgetExceededHandler): () => void;
+    /** Get per-workspace cost breakdown for the current period. */
+    getBreakdown(): Map<string, WorkspaceCostBreakdown>;
+    private notifyExceeded;
+}