@almadar/agent 2.0.0 → 2.0.1

package/dist/metrics.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Metrics Collection for DeepAgent Evaluation
+ *
+ * Tracks success rates, iteration counts, token usage, and timing
+ * for agent generation tests.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Metrics for a single generation attempt.
+ */
+export interface GenerationMetrics {
+    testName: string;
+    complexity: 'simple' | 'medium' | 'complex';
+    success: boolean;
+    iterations: number;
+    timeMs: number;
+    tokenUsage?: {
+        input: number;
+        output: number;
+        total: number;
+    };
+    error?: string;
+    timestamp?: number;
+}
+/**
+ * Aggregated metrics summary.
+ */
+export interface MetricsSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    successRate: number;
+    avgIterations: number;
+    avgTimeMs: number;
+    avgTokens: number;
+    byComplexity: {
+        simple: {
+            total: number;
+            passed: number;
+            successRate: number;
+        };
+        medium: {
+            total: number;
+            passed: number;
+            successRate: number;
+        };
+        complex: {
+            total: number;
+            passed: number;
+            successRate: number;
+        };
+    };
+}
+/**
+ * Collects and aggregates generation metrics.
+ */
+export declare class MetricsCollector {
+    private metrics;
+    record(metrics: GenerationMetrics): void;
+    getAll(): GenerationMetrics[];
+    getSummary(): MetricsSummary;
+    private getComplexitySummary;
+    getFailures(): GenerationMetrics[];
+    getMultiIterationTests(): GenerationMetrics[];
+    clear(): void;
+    saveToFile(filePath: string): Promise<void>;
+    loadFromFile(filePath: string): Promise<void>;
+}
+/**
+ * Format metrics summary as a readable string.
+ */
+export declare function formatSummary(summary: MetricsSummary): string;
+/**
+ * Analyze failure patterns to suggest prompt improvements.
+ */
+export declare function analyzeFailures(failures: GenerationMetrics[]): string[];

package/dist/multi-user.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Multi-User Support - GAP-009
+ *
+ * Provides proper user isolation and session scoping for multi-user environments.
+ * Ensures users can only access their own sessions, memory, and data.
+ *
+ * @packageDocumentation
+ */
+import type { SessionMetadata } from './persistence/types.js';
+/**
+ * User context for multi-user operations
+ */
+export interface UserContext {
+    /** User ID */
+    userId: string;
+    /** Organization/tenant ID (for multi-tenant) */
+    orgId?: string;
+    /** User roles/permissions */
+    roles?: string[];
+    /** Session ID scope (optional) */
+    sessionScope?: string[];
+}
+/**
+ * Scoped session metadata with user ownership
+ */
+export interface ScopedSessionMetadata extends SessionMetadata {
+    /** Owning user ID */
+    userId: string;
+    /** Organization ID */
+    orgId?: string;
+    /** Created by (for audit) */
+    createdBy: string;
+    /** Last accessed by */
+    lastAccessedBy?: string;
+    /** Access control list */
+    acl?: {
+        /** Users who can read this session */
+        readers?: string[];
+        /** Users who can write/modify */
+        writers?: string[];
+        /** Publicly accessible */
+        isPublic?: boolean;
+    };
+}
+/**
+ * Access check result
+ */
+export interface AccessCheckResult {
+    /** Whether access is granted */
+    allowed: boolean;
+    /** Reason if denied */
+    reason?: string;
+    /** Required permission level */
+    requiredRole?: string;
+}
+/**
+ * User session stats
+ */
+export interface UserSessionStats {
+    /** User ID */
+    userId: string;
+    /** Total sessions */
+    totalSessions: number;
+    /** Active sessions */
+    activeSessions: number;
+    /** Completed sessions */
+    completedSessions: number;
+    /** Sessions by skill */
+    sessionsBySkill: Record<string, number>;
+    /** Last activity timestamp */
+    lastActivityAt?: number;
+}
+export declare class MultiUserManager {
+    private sessionOwnership;
+    private userSessions;
+    /**
+     * Check if a user owns a session
+     */
+    isSessionOwner(threadId: string, userId: string): boolean;
+    /**
+     * Check if a user can access a session
+     */
+    canAccessSession(threadId: string, userContext: UserContext): AccessCheckResult;
+    /**
+     * Assign session ownership
+     */
+    assignSessionOwnership(threadId: string, userId: string): void;
+    /**
+     * Get all sessions for a user
+     */
+    getUserSessions(userId: string): string[];
+    /**
+     * Get session owner
+     */
+    getSessionOwner(threadId: string): string | undefined;
+    /**
+     * Remove session ownership
+     */
+    removeSession(threadId: string): void;
+    /**
+     * Check if user has any sessions
+     */
+    hasSessions(userId: string): boolean;
+    /**
+     * Get user session count
+     */
+    getSessionCount(userId: string): number;
+    /**
+     * Transfer session ownership
+     */
+    transferOwnership(threadId: string, fromUserId: string, toUserId: string): AccessCheckResult;
+    /**
+     * Share session with another user
+     */
+    shareSession(threadId: string, ownerId: string, targetUserId: string, permission?: 'read' | 'write'): AccessCheckResult;
+    /**
+     * Get all user IDs with sessions
+     */
+    getAllUsers(): string[];
+    /**
+     * Clear all data (for testing)
+     */
+    clear(): void;
+    /**
+     * Create scoped session metadata
+     */
+    createScopedMetadata(metadata: SessionMetadata, userContext: UserContext): ScopedSessionMetadata;
+    /**
+     * Validate user context
+     */
+    validateUserContext(userContext: unknown): userContext is UserContext;
+}
+/**
+ * Get or create global multi-user manager
+ */
+export declare function getMultiUserManager(): MultiUserManager;
+/**
+ * Reset global multi-user manager
+ */
+export declare function resetMultiUserManager(): void;
+/**
+ * Create user context from request
+ */
+export declare function createUserContext(userId: string, options?: {
+    orgId?: string;
+    roles?: string[];
+}): UserContext;
+/**
+ * Check if user is admin
+ */
+export declare function isAdmin(userContext: UserContext): boolean;
+/**
+ * Require ownership or throw
+ */
+export declare function requireOwnership(threadId: string, userContext: UserContext, manager?: MultiUserManager): void;

package/dist/observability/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Observability Module - Phase 1.2 Implementation
+ *
+ * Enhanced observability with LangSmith integration:
+ * - Run tracking with custom metadata
+ * - Error classification
+ * - Token usage alerts
+ * - Business metrics dashboard
+ * - Latency SLO monitoring
+ *
+ * @packageDocumentation
+ */
+export { LangSmithIntegration, getLangSmithIntegration, resetLangSmithIntegration, type ErrorCategory, type SessionMetadata, type TokenAlertConfig, type TokenAlert, type BusinessMetrics, type LatencySLOConfig, type SLOBreach, } from './langsmith-integration.js';
+export { ObservabilityCollector, getObservabilityCollector, resetObservabilityCollector, recordEvent, startObservabilitySession, endObservabilitySession, getPerformanceSnapshot, type ObservableEvent, type ObservableEventType, type SessionTelemetry, type PerformanceSnapshot, type HealthCheckResult, } from '../observability.js';

package/dist/observability/langsmith-integration.d.ts

@@ -0,0 +1,203 @@
+/**
+ * LangSmith Integration for Enhanced Observability
+ *
+ * Phase 1.2: Observability Enhancements
+ * - LangSmith run tracking (session = 1 run)
+ * - Custom metadata tags (orbitalCount, provider, success)
+ * - Error classification (timeout, schema, validation)
+ * - Token usage tracking with alerts
+ *
+ * @packageDocumentation
+ */
+import { Client as LangSmithClient, RunTree } from 'langsmith';
+/**
+ * Error classification categories
+ */
+export type ErrorCategory = 'timeout' | 'schema' | 'validation' | 'parse' | 'memory' | 'network' | 'rate_limit' | 'unknown';
+/**
+ * Session metadata for LangSmith
+ */
+export interface SessionMetadata {
+    /** Number of orbitals in request */
+    orbitalCount?: number;
+    /** LLM provider used */
+    provider?: string;
+    /** Model name */
+    model?: string;
+    /** User ID */
+    userId?: string;
+    /** Project ID */
+    projectId?: string;
+    /** Session complexity estimate */
+    complexity?: 'simple' | 'medium' | 'complex';
+    /** Generation success status */
+    success?: boolean;
+    /** Approach used: workflow or sequential */
+    approach?: 'workflow' | 'sequential';
+    /** Error category if failed */
+    errorCategory?: ErrorCategory;
+    /** Total tokens used */
+    totalTokens?: number;
+    /** Cost in USD */
+    costUsd?: number;
+    /** Duration in ms */
+    durationMs?: number;
+}
+/**
+ * Token usage alert configuration
+ */
+export interface TokenAlertConfig {
+    /** Threshold for warning (default: 8000) */
+    warningThreshold: number;
+    /** Threshold for critical (default: 10000) */
+    criticalThreshold: number;
+    /** Callback when threshold exceeded */
+    onAlert?: (alert: TokenAlert) => void;
+}
+/**
+ * Token usage alert
+ */
+export interface TokenAlert {
+    level: 'warning' | 'critical';
+    sessionId: string;
+    tokenCount: number;
+    threshold: number;
+    timestamp: number;
+    message: string;
+}
+/**
+ * Business metrics snapshot
+ */
+export interface BusinessMetrics {
+    /** Timestamp */
+    timestamp: number;
+    /** Time window in hours */
+    windowHours: number;
+    /** Total generations */
+    totalGenerations: number;
+    /** Successful generations */
+    successfulGenerations: number;
+    /** Failed generations */
+    failedGenerations: number;
+    /** Success rate (0-1) */
+    successRate: number;
+    /** Total cost in USD */
+    totalCostUsd: number;
+    /** Average cost per generation */
+    avgCostPerGeneration: number;
+    /** Average latency in ms */
+    avgLatencyMs: number;
+    /** P95 latency in ms */
+    p95LatencyMs: number;
+    /** Token usage distribution */
+    tokenDistribution: {
+        totalInput: number;
+        totalOutput: number;
+        avgPerGeneration: number;
+    };
+    /** Provider usage breakdown */
+    providerBreakdown: Record<string, {
+        count: number;
+        cost: number;
+    }>;
+}
+/**
+ * Latency SLO configuration
+ */
+export interface LatencySLOConfig {
+    /** Simple apps: P95 < 60s */
+    simple: {
+        p95Ms: number;
+    };
+    /** Complex apps: P95 < 300s */
+    complex: {
+        p95Ms: number;
+    };
+    /** Callback on SLO breach */
+    onBreach?: (breach: SLOBreach) => void;
+}
+/**
+ * SLO breach event
+ */
+export interface SLOBreach {
+    type: 'latency';
+    complexity: 'simple' | 'complex';
+    actualP95Ms: number;
+    thresholdMs: number;
+    timestamp: number;
+    message: string;
+}
+export declare class LangSmithIntegration {
+    private client;
+    private projectName;
+    private activeRuns;
+    private sessionMetadata;
+    private tokenAlerts;
+    private latencySLO;
+    private metricsHistory;
+    constructor(options?: {
+        apiKey?: string;
+        apiUrl?: string;
+        projectName?: string;
+        tokenAlerts?: Partial<TokenAlertConfig>;
+        latencySLO?: Partial<LatencySLOConfig>;
+    });
+    /**
+     * Start a new LangSmith run for a session
+     */
+    startSessionRun(sessionId: string, inputs: Record<string, unknown>, metadata?: Partial<SessionMetadata>): Promise<RunTree>;
+    /**
+     * Add metadata to an active session
+     */
+    addSessionMetadata(sessionId: string, metadata: Partial<SessionMetadata>): void;
+    /**
+     * Record an LLM call within a session
+     */
+    recordLLMCall(sessionId: string, options: {
+        model: string;
+        provider: string;
+        input: string;
+        output: string;
+        tokenCount: {
+            input: number;
+            output: number;
+        };
+        durationMs: number;
+        costUsd?: number;
+    }): Promise<void>;
+    /**
+     * Record a tool call within a session
+     */
+    recordToolCall(sessionId: string, toolName: string, inputs: Record<string, unknown>, outputs?: Record<string, unknown>, durationMs?: number): Promise<void>;
+    /**
+     * End a session run
+     */
+    endSessionRun(sessionId: string, outputs: Record<string, unknown>, error?: Error): Promise<void>;
+    /**
+     * Classify an error into categories
+     */
+    classifyError(error: Error): ErrorCategory;
+    /**
+     * Check token usage and trigger alerts
+     */
+    private checkTokenAlert;
+    /**
+     * Check latency SLO compliance
+     */
+    private checkLatencySLO;
+    /**
+     * Get business metrics for a time window
+     */
+    getBusinessMetrics(windowHours?: number): BusinessMetrics;
+    /**
+     * Get error breakdown by category
+     */
+    getErrorBreakdown(windowHours?: number): Record<ErrorCategory, number>;
+    /**
+     * Clean up old metrics (prevent memory leak)
+     */
+    pruneMetrics(olderThanHours?: number): void;
+}
+export declare function getLangSmithIntegration(): LangSmithIntegration;
+export declare function resetLangSmithIntegration(): void;
+export type { LangSmithClient, RunTree, };

package/dist/observability.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Observability - GAP-008
+ *
+ * Comprehensive observability layer for DeepAgent including:
+ * - Event tracking
+ * - Session metrics
+ * - Performance monitoring
+ * - Health checks
+ *
+ * @packageDocumentation
+ */
+/**
+ * Observable event types
+ */
+export type ObservableEventType = 'session_start' | 'session_end' | 'tool_call' | 'tool_result' | 'interrupt' | 'checkpoint_save' | 'checkpoint_restore' | 'error' | 'llm_call' | 'memory_sync';
+/**
+ * Observable event
+ */
+export interface ObservableEvent {
+    /** Event type */
+    type: ObservableEventType;
+    /** Timestamp */
+    timestamp: number;
+    /** Session/thread ID */
+    sessionId: string;
+    /** User ID */
+    userId?: string;
+    /** Event payload */
+    payload: Record<string, unknown>;
+    /** Duration in ms (if applicable) */
+    duration?: number;
+    /** Error information */
+    error?: {
+        message: string;
+        code?: string;
+        stack?: string;
+    };
+}
+/**
+ * Session telemetry
+ */
+export interface SessionTelemetry {
+    /** Session ID */
+    sessionId: string;
+    /** User ID */
+    userId?: string;
+    /** Session start time */
+    startedAt: number;
+    /** Session end time */
+    endedAt?: number;
+    /** Number of tool calls */
+    toolCallCount: number;
+    /** Number of LLM calls */
+    llmCallCount: number;
+    /** Number of interrupts */
+    interruptCount: number;
+    /** Number of checkpoints */
+    checkpointCount: number;
+    /** Total tokens used */
+    totalTokens: number;
+    /** Errors encountered */
+    errors: Array<{
+        timestamp: number;
+        message: string;
+        type: string;
+    }>;
+    /** Final status */
+    status: 'running' | 'completed' | 'failed' | 'interrupted';
+}
+/**
+ * Performance snapshot
+ */
+export interface PerformanceSnapshot {
+    /** Timestamp */
+    timestamp: number;
+    /** Active sessions */
+    activeSessions: number;
+    /** Total sessions (all time) */
+    totalSessions: number;
+    /** Average session duration */
+    avgSessionDuration: number;
+    /** Success rate (last 24h) */
+    successRate24h: number;
+    /** Error rate (last 24h) */
+    errorRate24h: number;
+    /** Average tokens per session */
+    avgTokensPerSession: number;
+}
+/**
+ * Health check result
+ */
+export interface HealthCheckResult {
+    /** Component name */
+    component: string;
+    /** Health status */
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    /** Response time in ms */
+    responseTime: number;
+    /** Last checked timestamp */
+    checkedAt: number;
+    /** Error message if unhealthy */
+    error?: string;
+}
+export declare class ObservabilityCollector {
+    private events;
+    private sessions;
+    private maxEvents;
+    constructor(options?: {
+        maxEvents?: number;
+    });
+    /**
+     * Record an observable event
+     */
+    recordEvent(event: Omit<ObservableEvent, 'timestamp'>): void;
+    /**
+     * Start session tracking
+     */
+    startSession(sessionId: string, userId?: string): void;
+    /**
+     * End session tracking
+     */
+    endSession(sessionId: string, status?: SessionTelemetry['status']): void;
+    /**
+     * Record tool call
+     */
+    recordToolCall(sessionId: string, toolName: string, args: Record<string, unknown>, duration?: number): void;
+    /**
+     * Record LLM call
+     */
+    recordLLMCall(sessionId: string, model: string, tokens: {
+        input: number;
+        output: number;
+    }, duration?: number): void;
+    /**
+     * Record error
+     */
+    recordError(sessionId: string, error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Get events by type
+     */
+    getEvents(type?: ObservableEventType, sessionId?: string): ObservableEvent[];
+    /**
+     * Get session telemetry
+     */
+    getSessionTelemetry(sessionId: string): SessionTelemetry | undefined;
+    /**
+     * Get all active sessions
+     */
+    getActiveSessions(): SessionTelemetry[];
+    /**
+     * Get performance snapshot
+     */
+    getPerformanceSnapshot(): PerformanceSnapshot;
+    /**
+     * Perform health check
+     */
+    healthCheck(): Promise<HealthCheckResult[]>;
+    /**
+     * Export metrics for external systems
+     */
+    exportMetrics(): {
+        events: ObservableEvent[];
+        sessions: SessionTelemetry[];
+        snapshot: PerformanceSnapshot;
+        health: HealthCheckResult[];
+    };
+    /**
+     * Clear all data
+     */
+    clear(): void;
+    private updateSessionTelemetry;
+}
+/**
+ * Get or create global observability collector
+ */
+export declare function getObservabilityCollector(): ObservabilityCollector;
+/**
+ * Reset global observability collector
+ */
+export declare function resetObservabilityCollector(): void;
+/**
+ * Record event to global collector
+ */
+export declare function recordEvent(event: Omit<ObservableEvent, 'timestamp'>): void;
+/**
+ * Start session in global collector
+ */
+export declare function startObservabilitySession(sessionId: string, userId?: string): void;
+/**
+ * End session in global collector
+ */
+export declare function endObservabilitySession(sessionId: string, status?: SessionTelemetry['status']): void;
+/**
+ * Get performance snapshot from global collector
+ */
+export declare function getPerformanceSnapshot(): PerformanceSnapshot;

package/dist/orbitals/archive/sanitize.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Orbital Sanitization
+ *
+ * Fixes common LLM generation errors in orbital JSON before validation.
+ * These are deterministic type coercions for known error patterns:
+ *
+ * 1. `field.type` as boolean/array instead of string
+ * 2. `field.values` as string/boolean instead of string[]
+ * 3. `field.required` as string instead of boolean
+ * 4. Invalid binding functions like `@count(...)`, `@length(...)`
+ * 5. Nested arrays where flat arrays expected
+ *
+ * @packageDocumentation
+ */
+/**
+ * Sanitize an orbital definition in-place, fixing common LLM type errors.
+ * Returns the same object (mutated) for convenience.
+ */
+export declare function sanitizeOrbital(orbital: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Sanitize a full schema (array of orbitals).
+ * Also removes relations to non-existent entities.
+ */
+export declare function sanitizeSchema(schema: Record<string, unknown>): Record<string, unknown>;