@almadar/agent 1.6.4 → 2.0.1

package/dist/state-sync.d.ts

@@ -0,0 +1,171 @@
+/**
+ * State Synchronization Support - GAP-010
+ *
+ * Provides agent-side support for real-time state synchronization.
+ * The actual transport (WebSocket/SSE) is handled by @almadar/server.
+ *
+ * This module provides:
+ * - State change notifications
+ * - Conflict resolution utilities
+ * - State serialization for sync
+ * - Event emitters for server integration
+ *
+ * @packageDocumentation
+ */
+import { EventEmitter } from 'events';
+import type { Checkpoint } from '@langchain/langgraph-checkpoint';
+/**
+ * State change event types
+ */
+export type StateChangeType = 'checkpoint_created' | 'checkpoint_updated' | 'session_started' | 'session_ended' | 'tool_executed' | 'memory_updated' | 'interrupt_triggered' | 'interrupt_resolved';
+/**
+ * State change event
+ */
+export interface StateChangeEvent {
+    /** Change type */
+    type: StateChangeType;
+    /** Thread/session ID */
+    threadId: string;
+    /** User ID */
+    userId?: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Change payload */
+    payload: Record<string, unknown>;
+    /** Version vector for conflict resolution */
+    version: VersionVector;
+    /** Source client ID */
+    sourceClientId?: string;
+}
+/**
+ * Version vector for conflict resolution
+ */
+export interface VersionVector {
+    /** Logical timestamp */
+    timestamp: number;
+    /** Sequence number */
+    sequence: number;
+    /** Node/client ID */
+    nodeId: string;
+}
+/**
+ * Sync state snapshot
+ */
+export interface StateSyncSnapshot {
+    /** Thread ID */
+    threadId: string;
+    /** Current checkpoint */
+    checkpoint?: Checkpoint;
+    /** Session metadata */
+    sessionMetadata?: Record<string, unknown>;
+    /** Memory state */
+    memoryState?: Record<string, unknown>;
+    /** Version vector */
+    version: VersionVector;
+    /** Last updated */
+    lastUpdated: number;
+}
+/**
+ * Conflict resolution result
+ */
+export interface ConflictResolution {
+    /** Whether conflict was resolved */
+    resolved: boolean;
+    /** Winning state if resolved */
+    winningState?: StateSyncSnapshot;
+    /** Conflicting changes if not resolved */
+    conflicts?: Array<{
+        clientA: StateChangeEvent;
+        clientB: StateChangeEvent;
+    }>;
+    /** Resolution strategy used */
+    strategy: 'last_write_wins' | 'merge' | 'manual';
+}
+/**
+ * Sync configuration
+ */
+export interface StateSyncConfig {
+    /** Enable sync */
+    enabled: boolean;
+    /** Conflict resolution strategy */
+    conflictStrategy: 'last_write_wins' | 'merge' | 'manual';
+    /** Throttle interval (ms) */
+    throttleInterval: number;
+    /** Max retry attempts */
+    maxRetries: number;
+    /** Client ID */
+    clientId: string;
+}
+export declare class StateSyncManager extends EventEmitter {
+    private config;
+    private sequenceNumber;
+    private pendingChanges;
+    private throttleTimer;
+    constructor(config?: Partial<StateSyncConfig>);
+    /**
+     * Notify that state has changed (called by agent internals)
+     */
+    notifyStateChange(type: StateChangeType, threadId: string, payload: Record<string, unknown>, userId?: string): void;
+    /**
+     * Receive state change from server (called by server transport)
+     */
+    receiveRemoteChange(event: StateChangeEvent): void;
+    /**
+     * Create sync snapshot for current state
+     */
+    createSnapshot(threadId: string, state: {
+        checkpoint?: Checkpoint;
+        sessionMetadata?: Record<string, unknown>;
+        memoryState?: Record<string, unknown>;
+    }): StateSyncSnapshot;
+    /**
+     * Compare two version vectors
+     * Returns: -1 if a < b, 0 if concurrent/equal, 1 if a > b
+     */
+    compareVersions(a: VersionVector, b: VersionVector): number;
+    /**
+     * Check if there are pending changes to sync
+     */
+    hasPendingChanges(): boolean;
+    /**
+     * Get and clear pending changes
+     */
+    flushPendingChanges(): StateChangeEvent[];
+    /**
+     * Get sync configuration
+     */
+    getConfig(): StateSyncConfig;
+    /**
+     * Update sync configuration
+     */
+    updateConfig(config: Partial<StateSyncConfig>): void;
+    /**
+     * Dispose resources
+     */
+    dispose(): void;
+    private generateClientId;
+    private createVersionVector;
+    private scheduleSync;
+    private findConflicts;
+    private resolveConflicts;
+}
+/**
+ * Get or create global state sync manager
+ */
+export declare function getStateSyncManager(config?: Partial<StateSyncConfig>): StateSyncManager;
+/**
+ * Reset global state sync manager
+ */
+export declare function resetStateSyncManager(): void;
+/**
+ * Create a synchronized wrapper for session operations
+ */
+export declare function withSync<T extends (...args: unknown[]) => unknown>(fn: T, syncManager: StateSyncManager, options: {
+    threadId: string;
+    type: StateChangeType;
+    getPayload: (...args: unknown[]) => Record<string, unknown>;
+}): T;
+/**
+ * Debounce sync notifications
+ */
+export declare function debounceSync(syncManager: StateSyncManager, delay?: number): (type: StateChangeType, threadId: string, payload: Record<string, unknown>) => void;

package/dist/subagents.d.ts

@@ -0,0 +1,38 @@
+/**
+ * KFlow DeepAgent Subagents
+ *
+ * Specialized subagents for complex schema generation tasks.
+ * These are spawned via the `task()` built-in tool.
+ *
+ * Uses @almadar/skills for schema reference documentation.
+ *
+ * @packageDocumentation
+ */
+import type { SubAgent } from './types.js';
+/**
+ * Create the Schema Generator Subagent configuration.
+ *
+ * Focused agent for generating KFlow schemas from requirements.
+ * Writes schema to file and verifies it exists.
+ */
+export declare function createSchemaGeneratorSubagent(): SubAgent;
+/**
+ * Create the Error Fixer Subagent configuration.
+ *
+ * Focused agent for fixing validation and compilation errors.
+ */
+export declare function createErrorFixerSubagent(): SubAgent;
+/**
+ * Create the Test Analyzer Subagent configuration.
+ *
+ * Focused agent for analyzing test failures and suggesting fixes.
+ */
+export declare function createTestAnalyzerSubagent(): SubAgent;
+/**
+ * Create all subagent configurations.
+ */
+export declare function createSubagents(): SubAgent[];
+/**
+ * Create subagent configs as a record for easy lookup.
+ */
+export declare function createSubagentConfigs(): Record<string, SubAgent>;

package/dist/tools/combine-schemas.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Construct Combined Schema Tool
+ *
+ * Deterministically combines generated orbitals into a single OrbitalSchema
+ * without LLM involvement.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/**
+ * Create the construct_combined_schema tool.
+ */
+export declare function createCombineSchemasTool(workDir?: string): import("@langchain/core/tools").DynamicStructuredTool<z.ZodObject<{
+    orbitals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        entity: z.ZodObject<{
+            name: z.ZodString;
+            collection: z.ZodOptional<z.ZodString>;
+            fields: z.ZodArray<z.ZodAny, "many">;
+            timestamps: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            fields: any[];
+            collection?: string | undefined;
+            timestamps?: boolean | undefined;
+        }, {
+            name: string;
+            fields: any[];
+            collection?: string | undefined;
+            timestamps?: boolean | undefined;
+        }>;
+        traits: z.ZodArray<z.ZodAny, "many">;
+        pages: z.ZodArray<z.ZodAny, "many">;
+        emits: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        listens: z.ZodOptional<z.ZodArray<z.ZodAny, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        pages: any[];
+        traits: any[];
+        name: string;
+        entity: {
+            name: string;
+            fields: any[];
+            collection?: string | undefined;
+            timestamps?: boolean | undefined;
+        };
+        description?: string | undefined;
+        emits?: string[] | undefined;
+        listens?: any[] | undefined;
+    }, {
+        pages: any[];
+        traits: any[];
+        name: string;
+        entity: {
+            name: string;
+            fields: any[];
+            collection?: string | undefined;
+            timestamps?: boolean | undefined;
+        };
+        description?: string | undefined;
+        emits?: string[] | undefined;
+        listens?: any[] | undefined;
+    }>, "many">>;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    theme: z.ZodOptional<z.ZodString>;
+    defaultRoute: z.ZodOptional<z.ZodString>;
+    validate: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    validate: boolean;
+    version?: string | undefined;
+    name?: string | undefined;
+    description?: string | undefined;
+    theme?: string | undefined;
+    orbitals?: {
+        pages: any[];
+        traits: any[];
+        name: string;
+        entity: {
+            name: string;
+            fields: any[];
+            collection?: string | undefined;
+            timestamps?: boolean | undefined;
+        };
+        description?: string | undefined;
+        emits?: string[] | undefined;
+        listens?: any[] | undefined;
+    }[] | undefined;
+    defaultRoute?: string | undefined;
+}, {
+    version?: string | undefined;
+    name?: string | undefined;
+    description?: string | undefined;
+    validate?: boolean | undefined;
+    theme?: string | undefined;
+    orbitals?: {
+        pages: any[];
+        traits: any[];
+        name: string;
+        entity: {
+            name: string;
+            fields: any[];
+            collection?: string | undefined;
+            timestamps?: boolean | undefined;
+        };
+        description?: string | undefined;
+        emits?: string[] | undefined;
+        listens?: any[] | undefined;
+    }[] | undefined;
+    defaultRoute?: string | undefined;
+}>, {
+    validate: boolean;
+    version?: string | undefined;
+    name?: string | undefined;
+    description?: string | undefined;
+    theme?: string | undefined;
+    orbitals?: {
+        pages: any[];
+        traits: any[];
+        name: string;
+        entity: {
+            name: string;
+            fields: any[];
+            collection?: string | undefined;
+            timestamps?: boolean | undefined;
+        };
+        description?: string | undefined;
+        emits?: string[] | undefined;
+        listens?: any[] | undefined;
+    }[] | undefined;
+    defaultRoute?: string | undefined;
+}, {
+    version?: string | undefined;
+    name?: string | undefined;
+    description?: string | undefined;
+    validate?: boolean | undefined;
+    theme?: string | undefined;
+    orbitals?: {
+        pages: any[];
+        traits: any[];
+        name: string;
+        entity: {
+            name: string;
+            fields: any[];
+            collection?: string | undefined;
+            timestamps?: boolean | undefined;
+        };
+        description?: string | undefined;
+        emits?: string[] | undefined;
+        listens?: any[] | undefined;
+    }[] | undefined;
+    defaultRoute?: string | undefined;
+}, string, "construct_combined_schema">;

package/dist/tools/composition.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Tool Composition & Chaining - Phase 3.3
+ *
+ * Composable tool workflows with parallel execution, error handling,
+ * and conditional branching.
+ *
+ * @packageDocumentation
+ */
+export type ToolStepStatus = 'pending' | 'running' | 'success' | 'error' | 'skipped';
+export interface ToolStep {
+    id: string;
+    name: string;
+    tool: string;
+    input: Record<string, unknown> | ((context: WorkflowContext) => Record<string, unknown>);
+    condition?: (context: WorkflowContext) => boolean;
+    dependsOn?: string[];
+    status: ToolStepStatus;
+    output?: unknown;
+    error?: string;
+    startTime?: number;
+    endTime?: number;
+}
+export interface WorkflowContext {
+    workflowId: string;
+    inputs: Record<string, unknown>;
+    outputs: Record<string, unknown>;
+    stepResults: Map<string, {
+        success: boolean;
+        output?: unknown;
+        error?: string;
+    }>;
+    metadata: {
+        startTime: number;
+        stepsCompleted: number;
+        stepsFailed: number;
+    };
+}
+export interface WorkflowDefinition {
+    name: string;
+    description: string;
+    inputs: Record<string, {
+        type: string;
+        required: boolean;
+        default?: unknown;
+    }>;
+    steps: ToolStep[];
+    onError?: 'stop' | 'continue' | 'retry';
+    maxRetries?: number;
+}
+export interface WorkflowExecutionResult {
+    success: boolean;
+    workflowId: string;
+    context: WorkflowContext;
+    steps: ToolStep[];
+    durationMs: number;
+    error?: string;
+}
+export interface ParallelExecutionResult {
+    stepId: string;
+    success: boolean;
+    output?: unknown;
+    error?: string;
+    durationMs: number;
+}
+export interface ToolExecutor {
+    execute(tool: string, input: Record<string, unknown>): Promise<unknown>;
+}
+export declare class WorkflowEngine {
+    private executor;
+    private workflows;
+    constructor(executor: ToolExecutor);
+    /**
+     * Register a workflow definition
+     */
+    registerWorkflow(definition: WorkflowDefinition): void;
+    /**
+     * Execute a workflow by name
+     */
+    executeWorkflow(workflowName: string, inputs: Record<string, unknown>): Promise<WorkflowExecutionResult>;
+    /**
+     * Execute a workflow definition directly
+     */
+    runWorkflow(definition: WorkflowDefinition, inputs: Record<string, unknown>): Promise<WorkflowExecutionResult>;
+    /**
+     * Execute independent steps in parallel
+     */
+    executeParallel(steps: Array<{
+        id: string;
+        tool: string;
+        input: Record<string, unknown>;
+    }>, context: WorkflowContext): Promise<ParallelExecutionResult[]>;
+    /**
+     * Create a workflow builder for fluent API
+     */
+    createWorkflow(name: string, description: string): WorkflowBuilder;
+    private executeStep;
+    private resolveDependencies;
+}
+export declare class WorkflowBuilder {
+    private engine;
+    private definition;
+    constructor(engine: WorkflowEngine, name: string, description: string);
+    input(name: string, type: string, required?: boolean, defaultValue?: unknown): this;
+    step(id: string, tool: string, input: Record<string, unknown> | ((context: WorkflowContext) => Record<string, unknown>), options?: {
+        dependsOn?: string[];
+        condition?: (context: WorkflowContext) => boolean;
+    }): this;
+    parallel(steps: Array<{
+        id: string;
+        tool: string;
+        input: Record<string, unknown>;
+    }>): this;
+    onError(policy: 'stop' | 'continue' | 'retry'): this;
+    retry(maxRetries: number): this;
+    build(): WorkflowDefinition;
+    execute(inputs: Record<string, unknown>): Promise<WorkflowExecutionResult>;
+}
+export declare function createSchemaGenerationWorkflow(engine: WorkflowEngine): WorkflowDefinition;
+export declare function createWorkflowEngine(executor: ToolExecutor): WorkflowEngine;