@fenixforce/kernel 0.1.0

package/dist/extensions/defaults/65-job-dispatch.d.ts

@@ -0,0 +1,24 @@
+import type { ExtensionDefinition } from "../manager.js";
+export interface JobDispatchConfig {
+    /** Callback invoked when a job is dispatched from a tool result */
+    onJobDispatched?: (job: {
+        id: string;
+        type: string;
+        toolName: string;
+    }) => void;
+}
+/**
+ * Create the job-dispatch default extension.
+ *
+ * This extension listens for `tool:result` events and detects when
+ * a tool has returned a job submission (id + status=queued + type).
+ * It tracks dispatched jobs and optionally notifies via callback.
+ */
+export declare function createJobDispatchExtension(config?: JobDispatchConfig): ExtensionDefinition;
+/** Access tracked jobs from the extension (for testing/inspection) */
+export declare function getDispatchedJobs(ext: ExtensionDefinition): Array<{
+    id: string;
+    type: string;
+    toolName: string;
+    timestamp: number;
+}>;

package/dist/extensions/defaults/70-skill-loader.d.ts

@@ -0,0 +1,18 @@
+import type { ExtensionDefinition } from "../manager.js";
+import type { Skill } from "../../tools/skill-discovery.js";
+export interface SkillLoaderConfig {
+    /** Pre-discovered skills to search (avoids re-scanning disk) */
+    skills: Skill[];
+    /** Maximum number of skills to inject per prompt (default: 2) */
+    maxSkills?: number;
+    /** Callback when skills are loaded into context */
+    onSkillsLoaded?: (skills: string[]) => void;
+}
+/**
+ * Create the skill-loader default extension.
+ *
+ * During `prompt:build`, this extension looks at the user's query
+ * (from `context.data.query`), searches the skill library, and
+ * appends matching skill instructions to the messages array.
+ */
+export declare function createSkillLoaderExtension(config: SkillLoaderConfig): ExtensionDefinition;

package/dist/extensions/hooks.d.ts

@@ -0,0 +1,74 @@
+import type { AgentEvent, AgentEventType } from "../events/types.js";
+/**
+ * Hook points in the agent lifecycle.
+ *
+ * - "event" hooks fire on any AgentEvent (filtered by eventTypes).
+ * - Named hooks fire at specific lifecycle points.
+ */
+export type HookPoint = "prompt:build" | "tool:before" | "tool:after" | "response:before" | "response:after" | "event";
+/**
+ * Context passed to every hook invocation.
+ * The `data` field varies by hook point.
+ */
+export interface HookContext {
+    sessionId: string;
+    hookPoint: HookPoint;
+    /** The event that triggered this hook (for "event" hooks) */
+    event?: AgentEvent;
+    /** Mutable data bag — hooks can read/modify to pass data downstream */
+    data: Record<string, unknown>;
+    /** Accumulated messages for prompt:build hooks */
+    messages?: Array<{
+        role: string;
+        content: string;
+    }>;
+}
+/**
+ * Return value from a hook handler.
+ * - `continue`: proceed to next hook in chain (default)
+ * - `skip`: skip remaining hooks for this point
+ * - `halt`: stop the entire pipeline (agent loop should check this)
+ */
+export type HookResult = {
+    action: "continue" | "skip" | "halt";
+    /** Optional data to merge into HookContext.data */
+    data?: Record<string, unknown>;
+};
+/**
+ * A registered hook with its handler, priority, and metadata.
+ */
+export interface Hook {
+    /** Unique identifier for this hook */
+    id: string;
+    /** Which extension registered this hook */
+    extensionId: string;
+    /** Which point in the lifecycle to fire */
+    point: HookPoint;
+    /** Numeric priority — lower fires first (default: 50) */
+    priority: number;
+    /** For "event" hooks: which event types to listen to (empty = all) */
+    eventTypes?: AgentEventType[];
+    /** The handler function */
+    handler: HookHandler;
+    /** Whether this hook is currently enabled */
+    enabled: boolean;
+}
+export type HookHandler = (context: HookContext) => Promise<HookResult>;
+/**
+ * Execute a chain of hooks in priority order.
+ *
+ * Hooks are sorted by priority (ascending — lower first).
+ * The chain stops early if a hook returns `skip` or `halt`.
+ * Returns the final merged context data and the terminal action.
+ */
+export declare function executeHookChain(hooks: Hook[], context: HookContext): Promise<{
+    action: "continue" | "skip" | "halt";
+    data: Record<string, unknown>;
+}>;
+/** Create a hook with sensible defaults */
+export declare function createHook(extensionId: string, point: HookPoint, handler: HookHandler, opts?: {
+    id?: string;
+    priority?: number;
+    eventTypes?: AgentEventType[];
+    enabled?: boolean;
+}): Hook;

package/dist/extensions/index.d.ts

@@ -0,0 +1,21 @@
+export * from "./hooks.js";
+export { ExtensionManager, type ExtensionDefinition, type ExtensionAPI } from "./manager.js";
+export { ExtensionRunner, createExtensionRunner } from "./runner.js";
+export { registerSessionRepair } from "./defaults/05-session-repair.js";
+export { registerLogging } from "./defaults/10-logging.js";
+export { registerLoopGuard } from "./defaults/15-loop-guard.js";
+export { registerCostTracking } from "./defaults/20-cost-tracking.js";
+export { registerSsrfProtection } from "./defaults/25-ssrf-protection.js";
+export { registerRateLimiting } from "./defaults/30-rate-limiting.js";
+export { registerShellBleed } from "./defaults/35-shell-bleed.js";
+export { registerObservationCapture } from "./defaults/40-observation-capture.js";
+export { registerContextSurvival } from "./defaults/45-context-survival.js";
+export { registerContextBudget } from "./defaults/50-context-budget.js";
+export { registerSteeringRules } from "./defaults/55-steering-rules.js";
+export { registerQualityGates } from "./defaults/60-quality-gates.js";
+export { createJobDispatchExtension, getDispatchedJobs } from "./defaults/65-job-dispatch.js";
+export type { JobDispatchConfig } from "./defaults/65-job-dispatch.js";
+export { createSkillLoaderExtension } from "./defaults/70-skill-loader.js";
+export type { SkillLoaderConfig as SkillLoaderExtensionConfig } from "./defaults/70-skill-loader.js";
+export { createInterventionPipeline } from "./intervention.js";
+export type { InterventionMessage, InterventionAction, InterventionHandler, InterventionEventType, InterventionEvent, InterventionEventListener, InterventionPipeline, } from "./intervention.js";

package/dist/extensions/intervention.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Intervention Handlers — extension point for intercepting and modifying
+ * messages before agent processing. Operates on ALL messages (more
+ * powerful than tool:before/tool:after hooks).
+ *
+ * Use cases:
+ *   - Content filtering (strip PII before agent sees it)
+ *   - Audit logging
+ *   - Rate limiting
+ *   - Prompt injection scanning in agent-to-agent communication
+ *
+ * Yields intervention:requested and intervention:result events.
+ */
+export interface InterventionMessage {
+    role: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+export type InterventionAction = InterventionMessage | "drop";
+export interface InterventionHandler {
+    /** Unique handler identifier. */
+    id: string;
+    /** Priority (lower runs first). Default 50. */
+    priority?: number;
+    /** Intercept outbound messages before sending to a recipient. */
+    onSend?(message: InterventionMessage, recipient: string): InterventionAction | Promise<InterventionAction>;
+    /** Intercept messages before publishing to the event bus. */
+    onPublish?(message: InterventionMessage): InterventionAction | Promise<InterventionAction>;
+    /** Intercept inbound responses from a sender. */
+    onResponse?(message: InterventionMessage, sender: string): InterventionAction | Promise<InterventionAction>;
+}
+export type InterventionEventType = "intervention:requested" | "intervention:result";
+export interface InterventionEvent {
+    type: InterventionEventType;
+    timestamp: Date;
+    handlerId: string;
+    hook: "onSend" | "onPublish" | "onResponse";
+    action: "pass" | "modify" | "drop";
+    detail: string;
+}
+export type InterventionEventListener = (event: InterventionEvent) => void;
+export interface InterventionPipeline {
+    /** Register a handler. */
+    register(handler: InterventionHandler): void;
+    /** Unregister a handler by ID. */
+    unregister(handlerId: string): boolean;
+    /** List registered handler IDs in priority order. */
+    listHandlers(): string[];
+    /** Run the onSend pipeline. Returns modified message or null if dropped. */
+    runSend(message: InterventionMessage, recipient: string): Promise<InterventionMessage | null>;
+    /** Run the onPublish pipeline. Returns modified message or null if dropped. */
+    runPublish(message: InterventionMessage): Promise<InterventionMessage | null>;
+    /** Run the onResponse pipeline. Returns modified message or null if dropped. */
+    runResponse(message: InterventionMessage, sender: string): Promise<InterventionMessage | null>;
+    /** Events. */
+    on(listener: InterventionEventListener): void;
+    off(listener: InterventionEventListener): void;
+}
+export declare function createInterventionPipeline(): InterventionPipeline;

package/dist/extensions/manager.d.ts

@@ -0,0 +1,63 @@
+import type { AgentEvent } from "../events/types.js";
+import { type Hook, type HookPoint, type HookContext, type HookHandler } from "./hooks.js";
+export interface ExtensionDefinition {
+    /** Unique extension ID (e.g. "fenix.job-dispatch") */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Semver version */
+    version?: string;
+    /** Setup function — registers hooks, called during load */
+    setup: (api: ExtensionAPI) => void | Promise<void>;
+    /** Teardown function — cleanup on unload */
+    teardown?: () => void | Promise<void>;
+}
+/** API surface exposed to extensions during setup */
+export interface ExtensionAPI {
+    /** Register a hook at a lifecycle point */
+    registerHook(point: HookPoint, handler: HookHandler, opts?: {
+        id?: string;
+        priority?: number;
+        eventTypes?: AgentEvent["type"][];
+        enabled?: boolean;
+    }): string;
+    /** Access the extension's own ID */
+    extensionId: string;
+}
+export declare class ExtensionManager {
+    private extensions;
+    private hooks;
+    private allHooks;
+    /** Register and set up an extension */
+    register(ext: ExtensionDefinition): Promise<void>;
+    /** Register multiple extensions in order */
+    registerAll(exts: ExtensionDefinition[]): Promise<void>;
+    /** Unregister an extension, removing all its hooks */
+    unregister(extensionId: string): Promise<void>;
+    /** Check if an extension is registered */
+    has(extensionId: string): boolean;
+    /** Get all registered extension IDs */
+    listExtensions(): string[];
+    /** Get all hooks at a specific point, sorted by priority */
+    getHooks(point: HookPoint): Hook[];
+    /** Get a hook by ID */
+    getHook(hookId: string): Hook | undefined;
+    /** Enable or disable a specific hook */
+    setHookEnabled(hookId: string, enabled: boolean): boolean;
+    /** Total registered hooks */
+    get hookCount(): number;
+    /**
+     * Dispatch a lifecycle event to all hooks at the given point.
+     * Executes the hook chain in priority order.
+     */
+    dispatch(point: HookPoint, context: Omit<HookContext, "hookPoint">): Promise<{
+        action: "continue" | "skip" | "halt";
+        data: Record<string, unknown>;
+    }>;
+    /**
+     * Dispatch an AgentEvent to all "event" hooks.
+     * Filters hooks by their eventTypes configuration.
+     */
+    dispatchEvent(event: AgentEvent, sessionId: string, extraData?: Record<string, unknown>): Promise<void>;
+    private removeHook;
+}

package/dist/extensions/runner.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Extension Runner — loads and executes extensions from default, user,
+ * and project directories with numbered prefix ordering.
+ *
+ * Three-level override: default → user → project.
+ * Extensions with the same ID registered later replace earlier ones.
+ *
+ * Hooks: tool:before, tool:after, agent:init, agent:end,
+ *        memory:before-save, prompt:build, response:before, response:after, event
+ *
+ * Extension hooks are async, executed in priority order via the
+ * ExtensionManager's hook chain. A null/skip return from tool:before
+ * cancels the tool call.
+ */
+import { ExtensionManager, type ExtensionDefinition } from "./manager.js";
+export interface ExtensionSource {
+    /** Directory path containing extension files */
+    path: string;
+    /** Source level for override precedence */
+    level: "default" | "user" | "project";
+}
+export interface ExtensionRunnerConfig {
+    /** Extension sources in override order (later overrides earlier) */
+    sources: ExtensionSource[];
+    /** Optional filter — only load extensions matching these IDs */
+    filter?: string[];
+}
+export declare class ExtensionRunner {
+    private readonly manager;
+    private readonly config;
+    private loaded;
+    constructor(manager: ExtensionManager, config: ExtensionRunnerConfig);
+    /**
+     * Discover and load extensions from all configured sources.
+     *
+     * Extensions are loaded in order:
+     * 1. Sorted by numeric prefix (10-logging, 15-loop-guard, etc.)
+     * 2. Within same prefix, later levels override earlier (default < user < project)
+     *
+     * Returns the number of extensions loaded.
+     */
+    loadAll(): Promise<number>;
+    /**
+     * Load extensions from pre-built definitions (no filesystem discovery).
+     * Useful for testing or programmatic setup.
+     */
+    loadDefinitions(definitions: ExtensionDefinition[]): Promise<number>;
+    /** Unload all loaded extensions. */
+    unloadAll(): Promise<void>;
+    /** Get the list of loaded extensions with their metadata. */
+    listLoaded(): Array<{
+        id: string;
+        level: string;
+        order: number;
+    }>;
+    /** Access the underlying extension manager. */
+    getManager(): ExtensionManager;
+    private discoverFromDirectory;
+}
+/**
+ * Create a runner with default configuration for the standard extension directories.
+ */
+export declare function createExtensionRunner(manager: ExtensionManager, basePath: string): ExtensionRunner;

package/dist/hooks/hook-manager.d.ts

@@ -0,0 +1,39 @@
+import type { HookEvent, HookAction, HookContext, HookHandler, HookRegistrationOptions } from "./hook-types.js";
+export declare class HookManager {
+    private hooks;
+    /**
+     * Register a handler for a lifecycle event.
+     * Returns a disposer function to unregister.
+     */
+    on(event: HookEvent, handler: HookHandler, opts?: HookRegistrationOptions): () => void;
+    /**
+     * Execute all handlers for an event. Returns the first non-continue
+     * action, or { type: "continue" } if all handlers pass.
+     */
+    execute(ctx: HookContext): Promise<HookAction>;
+    /**
+     * Synchronous execute for performance-critical paths.
+     * Handlers must return synchronously; async handlers are skipped.
+     */
+    executeSync(ctx: HookContext): HookAction;
+    /** Number of registered hooks for a given event (or all events). */
+    count(event?: HookEvent): number;
+    /** Remove all hooks. */
+    clear(): void;
+    /** List all registered hook IDs for an event. */
+    list(event: HookEvent): string[];
+    private remove;
+    private matches;
+}
+export declare function dangerousCommandBlocker(ctx: HookContext): HookAction;
+export declare function syntaxChecker(ctx: HookContext): HookAction;
+export declare function contextWindowMonitor(ctx: HookContext): HookAction;
+export declare function setSessionUnattended(sessionId: string, unattended: boolean): void;
+export declare function autonomousDecisionEnforcer(ctx: HookContext): HookAction;
+/**
+ * Register the 4 default guard-rail hooks on a HookManager.
+ * Priority 0 ensures they fire before user-registered hooks.
+ */
+export declare function registerDefaultGuardRails(manager: HookManager): void;
+/** Reset guard rail state (for tests). */
+export declare function _resetHookState(): void;

package/dist/hooks/hook-types.d.ts

@@ -0,0 +1,60 @@
+import type { ToolResult } from "../tools/router.js";
+export type HookEvent = "swarm:start" | "swarm:stop" | "first:message" | "user:prompt" | "agent:step" | "agent:stop" | "pre:tool:use" | "post:tool:use" | "pre:delegation" | "post:delegation" | "context:warning" | "breakpoint:enter" | "breakpoint:exit";
+export type HookAction = {
+    type: "continue";
+} | {
+    type: "halt";
+    reason: string;
+} | {
+    type: "replace";
+    result: ToolResult;
+} | {
+    type: "reprompt";
+    prompt: string;
+} | {
+    type: "finish-agent";
+    reason: string;
+} | {
+    type: "finish-swarm";
+    reason: string;
+};
+export interface HookContext {
+    event: HookEvent;
+    sessionId: string;
+    agentId?: string;
+    swarmId?: string;
+    /** Tool name (for pre:tool:use / post:tool:use). */
+    toolName?: string;
+    /** Tool arguments (for pre:tool:use). */
+    toolArgs?: Record<string, unknown>;
+    /** Tool result (for post:tool:use). */
+    toolResult?: ToolResult;
+    /** Delegation target (for pre:delegation / post:delegation). */
+    delegationTarget?: string;
+    /** Context usage ratio 0–1 (for context:warning). */
+    contextUsage?: number;
+    /** User prompt text (for user:prompt / first:message). */
+    prompt?: string;
+    /** Arbitrary data bag for passing info between hooks. */
+    data?: Record<string, unknown>;
+}
+export type HookHandler = (ctx: HookContext) => HookAction | Promise<HookAction>;
+export interface HookRegistrationOptions {
+    /** Regex or exact tool name match (for pre:tool:use / post:tool:use). */
+    matcher?: string | RegExp;
+    /** Context usage threshold (for context:warning). */
+    threshold?: number;
+    /** Scope to a specific agent ID. */
+    scope?: string;
+    /** Numeric priority — lower fires first. Default 50. */
+    priority?: number;
+}
+export interface RegisteredHook {
+    id: string;
+    event: HookEvent;
+    handler: HookHandler;
+    matcher?: RegExp;
+    threshold?: number;
+    scope?: string;
+    priority: number;
+}

package/dist/identity/assembler.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Identity Assembler — reads identity files from workspace/identity/ directory,
+ * resolves per-channel overrides, and assembles into a single identity block
+ * for the system prompt.
+ *
+ * File resolution order:
+ * 1. soul.md      — platform-level personality (base layer)
+ * 2. persona.md   — workspace-level customization (overrides soul)
+ * 3. overrides/{channel}.md — channel-specific overrides
+ * 4. user.md      — auto-populated from LPM traits
+ *
+ * Respects identity token budget (default 800 tokens).
+ */
+import { type MemorySegmentLike } from "./user-populator.js";
+import type { StorageAdapter } from "../storage/interface.js";
+export interface IdentityBlock {
+    name: string;
+    role: string | null;
+    tone: string;
+    language: string;
+    content: string;
+    tokenEstimate: number;
+}
+export interface AssemblerOptions {
+    /** Max tokens for the assembled identity block (default: 800) */
+    tokenBudget?: number;
+    /** Channel name for per-channel overrides (e.g. "telegram", "discord") */
+    channel?: string;
+    /** User memory segments for auto-populating user traits */
+    userSegments?: MemorySegmentLike[];
+}
+export declare class IdentityAssembler {
+    private readonly storage;
+    constructor(storage: StorageAdapter);
+    /** Assemble a complete identity block for the system prompt. */
+    assemble(workspaceId: string, options?: AssemblerOptions): Promise<IdentityBlock>;
+    /** Assemble from raw markdown strings (for testing or non-storage use). */
+    static assembleFromStrings(soulMd: string | null, personaMd: string | null, channelOverrideMd?: string | null, options?: {
+        tokenBudget?: number;
+        userSegments?: MemorySegmentLike[];
+    }): IdentityBlock;
+    private loadFiles;
+    private findFile;
+    private findAndParse;
+}

package/dist/identity/ccc-adapter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * CCC Character Card Import/Export — Character Card V3 format adapter.
+ *
+ * Import: CCC JSON → Fenix identity files (persona.md, soul.md, knowledge.md).
+ * Export: Fenix identity files → CCC V3 JSON (or PNG with embedded metadata).
+ */
+export interface CharacterCardV3 {
+    spec: "chara_card_v3";
+    spec_version: "3.0";
+    data: {
+        name: string;
+        description?: string;
+        personality?: string;
+        scenario?: string;
+        system_prompt?: string;
+        post_history_instructions?: string;
+        first_mes?: string;
+        mes_example?: string;
+        tags?: string[];
+        creator?: string;
+        creator_notes?: string;
+        alternate_greetings?: string[];
+        extensions?: Record<string, unknown>;
+    };
+}
+export interface IdentityFiles {
+    "persona.md": string;
+    "soul.md": string;
+    "knowledge.md": string;
+    metadata: Record<string, unknown>;
+}
+export declare function importCharacterCard(source: string | Buffer): IdentityFiles;
+export declare function exportCharacterCard(identityDir: string): Promise<CharacterCardV3>;

package/dist/identity/index.d.ts

@@ -0,0 +1,6 @@
+export { IdentityAssembler, type IdentityBlock, type AssemblerOptions } from "./assembler.js";
+export { parseSoul, type SoulConfig } from "./soul-parser.js";
+export { parsePersona, type PersonaConfig } from "./persona-parser.js";
+export { extractTraits, renderUserBlock, type UserTraits } from "./user-populator.js";
+export { importCharacterCard, exportCharacterCard } from "./ccc-adapter.js";
+export type { CharacterCardV3, IdentityFiles } from "./ccc-adapter.js";

package/dist/identity/persona-parser.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Persona Parser — reads and parses persona.md (customer-defined overrides).
+ *
+ * persona.md allows workspace owners to customize the assistant's identity
+ * beyond the platform soul. Fields here take precedence over soul.md.
+ *
+ * Expected format:
+ * ---
+ * displayName: Aria
+ * role: Customer Success Agent
+ * language: en
+ * ---
+ * # Custom Instructions
+ * ...markdown content...
+ */
+export interface PersonaConfig {
+    displayName: string | null;
+    role: string | null;
+    language: string;
+    overrides: Record<string, string>;
+    content: string;
+}
+/** Parse a persona.md file into structured config. */
+export declare function parsePersona(markdown: string): PersonaConfig;

package/dist/identity/soul-parser.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Soul Parser — reads and parses soul.md (platform-level personality).
+ *
+ * soul.md defines the core personality traits, tone, and behavioral
+ * guidelines that apply across all workspaces. This is the base layer
+ * that persona.md overrides.
+ *
+ * Expected format:
+ * ---
+ * name: Fenix
+ * tone: warm, direct
+ * ---
+ * # Personality
+ * ...markdown content...
+ */
+export interface SoulConfig {
+    name: string;
+    tone: string;
+    traits: string[];
+    content: string;
+}
+/** Parse a soul.md file into structured config. */
+export declare function parseSoul(markdown: string): SoulConfig;

package/dist/identity/user-populator.d.ts

@@ -0,0 +1,20 @@
+/**
+ * User Populator — auto-populates user.md from LPM (Long-term Personal Memory) traits.
+ *
+ * Reads user preferences, facts, and traits from memory segments
+ * and assembles a user.md-style block for the system prompt.
+ */
+export interface UserTraits {
+    name: string | null;
+    preferences: string[];
+    facts: string[];
+    language: string | null;
+}
+export interface MemorySegmentLike {
+    content: string;
+    category: "fact" | "preference" | "experience" | "knowledge";
+}
+/** Extract user traits from memory segments. */
+export declare function extractTraits(segments: MemorySegmentLike[]): UserTraits;
+/** Render user traits into a user.md-style markdown block. */
+export declare function renderUserBlock(traits: UserTraits, maxTokens?: number): string;