@almadar/agent 1.6.4 → 2.0.1

package/dist/evals/online-sampling.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Online Evaluations - Phase 3.2a: Simple Sampling
+ *
+ * 10% traffic sampling with async validation and basic alerting.
+ * Non-blocking - runs in background without affecting user response.
+ *
+ * @packageDocumentation
+ */
+import { EventEmitter } from 'events';
+export interface SamplingConfig {
+    /** Sampling rate (0.0 - 1.0) */
+    sampleRate: number;
+    /** Async queue size */
+    maxQueueSize: number;
+    /** Validation timeout */
+    validationTimeoutMs: number;
+    /** Alert threshold for error rate */
+    errorRateThreshold: number;
+    /** Alert window in ms */
+    alertWindowMs: number;
+}
+export interface EvalSample {
+    sampleId: string;
+    timestamp: number;
+    request: {
+        prompt: string;
+        provider: string;
+        model: string;
+    };
+    result: {
+        success: boolean;
+        schema?: unknown;
+        error?: string;
+        latencyMs: number;
+    };
+    validation?: {
+        automatedScore: number;
+        syntaxErrors: number;
+        structureWarnings: number;
+        timestamp: number;
+    };
+}
+export interface ErrorAlert {
+    alertId: string;
+    timestamp: number;
+    errorRate: number;
+    threshold: number;
+    windowStart: number;
+    sampleCount: number;
+    errorCount: number;
+}
+export interface SamplingStats {
+    totalSampled: number;
+    totalValidated: number;
+    averageScore: number;
+    currentErrorRate: number;
+    queueSize: number;
+    isHealthy: boolean;
+}
+export declare class OnlineEvalSampler extends EventEmitter {
+    private config;
+    private queue;
+    private samples;
+    private errorWindow;
+    private isProcessing;
+    constructor(config?: Partial<SamplingConfig>);
+    /**
+     * Check if a request should be sampled
+     * Uses hash-based sampling for consistency
+     */
+    shouldSample(requestId: string): boolean;
+    /**
+     * Add a sample to the queue for async validation
+     */
+    sample(requestId: string, request: {
+        prompt: string;
+        provider: string;
+        model: string;
+    }, result: {
+        success: boolean;
+        schema?: unknown;
+        error?: string;
+        latencyMs: number;
+    }): Promise<void>;
+    /**
+     * Pull samples for manual review
+     */
+    pullSamples(options?: {
+        date?: Date;
+        limit?: number;
+        minScore?: number;
+    }): Promise<EvalSample[]>;
+    /**
+     * Get current stats
+     */
+    getStats(): SamplingStats;
+    /**
+     * Stop the processor
+     */
+    stop(): void;
+    private startProcessor;
+    private validateSample;
+    private runAutomatedValidation;
+    private trackError;
+    private calculateErrorRate;
+}
+export interface ReviewOptions {
+    date?: string;
+    limit?: number;
+    minScore?: number;
+    format?: 'json' | 'table';
+}
+export declare function reviewSamples(sampler: OnlineEvalSampler, options?: ReviewOptions): Promise<void>;
+export declare function createOnlineEvalSampler(config?: Partial<SamplingConfig>): OnlineEvalSampler;

package/dist/evals/utils/compact-orbital.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Orbital Compaction Utility
+ *
+ * Compresses a full orbital JSON into a structural summary (~90% token reduction).
+ * The main agent only needs to know what was generated (entity names, trait names,
+ * field counts) — not the full s-expression trees, guard clauses, and render-ui
+ * prop objects.
+ *
+ * @packageDocumentation
+ */
+interface OrbitalField {
+    name: string;
+    type: string;
+    required?: boolean;
+    values?: string[];
+    relation?: {
+        entity: string;
+    };
+}
+interface OrbitalTrait {
+    name: string;
+    stateMachine?: {
+        states?: Array<{
+            name: string;
+            isInitial?: boolean;
+        } | string>;
+        events?: string[];
+        transitions?: unknown[];
+    };
+}
+interface OrbitalPage {
+    name: string;
+    path: string;
+    traits?: Array<{
+        ref: string;
+    } | string>;
+}
+interface OrbitalEntity {
+    name: string;
+    collection?: string;
+    persistence?: string;
+    fields?: OrbitalField[];
+}
+interface OrbitalUnit {
+    name: string;
+    entity?: OrbitalEntity;
+    traits?: OrbitalTrait[];
+    pages?: OrbitalPage[];
+    emits?: string[];
+    listens?: Array<{
+        event: string;
+        triggers: string;
+    }>;
+}
+interface OrbitalSchema {
+    name?: string;
+    version?: string;
+    orbitals?: OrbitalUnit[];
+}
+/**
+ * Compact a single orbital unit into a structural summary.
+ *
+ * Full orbital (~800 tokens) → Summary (~80 tokens, 90% reduction)
+ *
+ * Example output:
+ * ```
+ * orbital: Task Management
+ *   entity: Task (tasks) [title:string*, status:enum(3), assignee:rel→User] 3 fields
+ *   trait: TaskInteraction [Browsing→Creating→Viewing→Editing→Deleting] 5 states, 8 events, 8 transitions
+ *   page: /tasks → TaskInteraction
+ *   emits: TASK_CREATED, TASK_UPDATED
+ *   listens: USER_SELECTED → ViewUser
+ * ```
+ */
+export declare function compactOrbital(orbital: OrbitalUnit): string;
+/**
+ * Compact a full OrbitalSchema (multiple orbitals) into a summary.
+ */
+export declare function compactSchema(schema: OrbitalSchema): string;
+/**
+ * Compact result from generate_orbital tool call.
+ * Returns the compact summary string to use instead of full JSON in tool results.
+ */
+export declare function compactOrbitalResult(result: {
+    success: boolean;
+    orbital?: unknown;
+    fingerprint?: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    validation?: {
+        valid?: boolean;
+        errors?: Array<{
+            message: string;
+        }>;
+    };
+}): string;
+export {};

package/dist/event-transformer/event-transformer.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Event Transformer for DeepAgent
+ *
+ * Transforms raw LangGraph/deepagents events into SSE events.
+ * Handles special events like todo updates and file operations.
+ *
+ * Supports both:
+ * - LangGraph event structures (event.tools, event.model_request)
+ * - Legacy flat event structures (event.todos, event.tool_call)
+ */
+import { type SSEEvent } from '../api-types.js';
+/**
+ * Raw agent event from LangGraph/deepagents.
+ */
+export interface RawAgentEvent {
+    tools?: {
+        todos?: Array<{
+            content?: string;
+            task?: string;
+            status?: string;
+            id?: string;
+        }>;
+        messages?: Array<Record<string, unknown>>;
+    };
+    model_request?: {
+        messages?: Array<Record<string, unknown>>;
+    };
+    messages?: Array<{
+        role?: string;
+        content?: string;
+    }>;
+    tool_call?: {
+        name?: string;
+        args?: Record<string, unknown>;
+    };
+    toolCall?: {
+        name?: string;
+        args?: Record<string, unknown>;
+    };
+    tool_result?: {
+        name?: string;
+        result?: unknown;
+    };
+    toolResult?: {
+        name?: string;
+        result?: unknown;
+    };
+    todos?: Array<{
+        id?: string;
+        task?: string;
+        status?: 'pending' | 'in_progress' | 'completed';
+    }>;
+    __interrupt__?: Array<{
+        value?: {
+            actionRequests?: Array<{
+                name?: string;
+                args?: Record<string, unknown>;
+                description?: string;
+            }>;
+            reviewConfigs?: Array<{
+                allowedDecisions?: string[];
+            }>;
+        };
+        action?: {
+            tool?: string;
+            toolInput?: Record<string, unknown>;
+        };
+        config?: {
+            allowedDecisions?: string[];
+        };
+    }>;
+    [key: string]: unknown;
+}
+/**
+ * Transform a raw agent event to SSE event(s).
+ *
+ * Handles both LangGraph nested structures and legacy flat structures.
+ * Returns an array for consistency with multi-event scenarios.
+ *
+ * @param event Raw agent event
+ * @param threadId Thread ID for context
+ * @returns Array of SSE events
+ */
+export declare function transformAgentEvent(event: RawAgentEvent, threadId?: string): SSEEvent;
+/**
+ * Transform a raw agent event to multiple SSE events.
+ * Use this when you need to handle all events from a single LangGraph event.
+ */
+export declare function transformAgentEventMulti(event: RawAgentEvent, threadId?: string): SSEEvent[];
+/**
+ * Check if an event contains an interrupt.
+ */
+export declare function hasInterrupt(event: RawAgentEvent): boolean;
+/**
+ * Extract interrupt data from an event.
+ */
+export declare function extractInterruptData(event: RawAgentEvent, threadId: string): {
+    threadId: string;
+    actionRequests: Array<{
+        tool: string;
+        args: Record<string, unknown>;
+        allowedDecisions: ('approve' | 'edit' | 'reject')[];
+        description?: string;
+    }>;
+};
+/**
+ * Check if an event is a todo update.
+ */
+export declare function isTodoUpdate(event: RawAgentEvent): boolean;
+/**
+ * Check if an event is a file operation.
+ */
+export declare function isFileOperation(event: RawAgentEvent): boolean;
+/**
+ * Extract file operation details from an event.
+ */
+export declare function extractFileOperation(event: RawAgentEvent): {
+    operation: string;
+    path: string;
+} | null;

package/dist/event-transformer/index.d.ts

@@ -1,125 +1,7 @@
-import { a as SSEEvent } from '../api-types-CXrq-fts.js';
-import 'zod';
-
 /**
- * Event Transformer for DeepAgent
+ * Event Transformer
  *
- * Transforms raw LangGraph/deepagents events into SSE events.
- * Handles special events like todo updates and file operations.
- *
- * Supports both:
- * - LangGraph event structures (event.tools, event.model_request)
- * - Legacy flat event structures (event.todos, event.tool_call)
- */
-
-/**
- * Raw agent event from LangGraph/deepagents.
- */
-interface RawAgentEvent {
-    tools?: {
-        todos?: Array<{
-            content?: string;
-            task?: string;
-            status?: string;
-            id?: string;
-        }>;
-        messages?: Array<Record<string, unknown>>;
-    };
-    model_request?: {
-        messages?: Array<Record<string, unknown>>;
-    };
-    messages?: Array<{
-        role?: string;
-        content?: string;
-    }>;
-    tool_call?: {
-        name?: string;
-        args?: Record<string, unknown>;
-    };
-    toolCall?: {
-        name?: string;
-        args?: Record<string, unknown>;
-    };
-    tool_result?: {
-        name?: string;
-        result?: unknown;
-    };
-    toolResult?: {
-        name?: string;
-        result?: unknown;
-    };
-    todos?: Array<{
-        id?: string;
-        task?: string;
-        status?: 'pending' | 'in_progress' | 'completed';
-    }>;
-    __interrupt__?: Array<{
-        value?: {
-            actionRequests?: Array<{
-                name?: string;
-                args?: Record<string, unknown>;
-                description?: string;
-            }>;
-            reviewConfigs?: Array<{
-                allowedDecisions?: string[];
-            }>;
-        };
-        action?: {
-            tool?: string;
-            toolInput?: Record<string, unknown>;
-        };
-        config?: {
-            allowedDecisions?: string[];
-        };
-    }>;
-    [key: string]: unknown;
-}
-/**
- * Transform a raw agent event to SSE event(s).
- *
- * Handles both LangGraph nested structures and legacy flat structures.
- * Returns an array for consistency with multi-event scenarios.
- *
- * @param event Raw agent event
- * @param threadId Thread ID for context
- * @returns Array of SSE events
- */
-declare function transformAgentEvent(event: RawAgentEvent, threadId?: string): SSEEvent;
-/**
- * Transform a raw agent event to multiple SSE events.
- * Use this when you need to handle all events from a single LangGraph event.
- */
-declare function transformAgentEventMulti(event: RawAgentEvent, threadId?: string): SSEEvent[];
-/**
- * Check if an event contains an interrupt.
- */
-declare function hasInterrupt(event: RawAgentEvent): boolean;
-/**
- * Extract interrupt data from an event.
- */
-declare function extractInterruptData(event: RawAgentEvent, threadId: string): {
-    threadId: string;
-    actionRequests: Array<{
-        tool: string;
-        args: Record<string, unknown>;
-        allowedDecisions: ('approve' | 'edit' | 'reject')[];
-        description?: string;
-    }>;
-};
-/**
- * Check if an event is a todo update.
- */
-declare function isTodoUpdate(event: RawAgentEvent): boolean;
-/**
- * Check if an event is a file operation.
- */
-declare function isFileOperation(event: RawAgentEvent): boolean;
-/**
- * Extract file operation details from an event.
+ * Transforms raw LangGraph/deepagents events into typed SSE events.
  */
-declare function extractFileOperation(event: RawAgentEvent): {
-    operation: string;
-    path: string;
-} | null;
-
-export { type RawAgentEvent, extractFileOperation, extractInterruptData, hasInterrupt, isFileOperation, isTodoUpdate, transformAgentEvent, transformAgentEventMulti };
+export { transformAgentEvent, transformAgentEventMulti, hasInterrupt, extractInterruptData, isTodoUpdate, isFileOperation, extractFileOperation, } from './event-transformer.js';
+export type { RawAgentEvent, } from './event-transformer.js';

package/dist/events.d.ts

@@ -0,0 +1,85 @@
+/**
+ * DeepAgent SSE Event Types
+ *
+ * Type definitions for Server-Sent Events from the DeepAgent streaming endpoint.
+ * Use these types for client-side consumption of /deepagent/generate-stream.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Initial event sent when streaming begins.
+ */
+export interface DeepAgentStartEvent {
+    type: 'start';
+    sessionId: string;
+}
+/**
+ * Agent execution event (tool calls, messages, etc.).
+ */
+export interface DeepAgentExecutionEvent {
+    type: 'event';
+    node?: string;
+    toolCall?: {
+        name: string;
+        args: Record<string, unknown>;
+    };
+    toolResult?: {
+        name: string;
+        result: unknown;
+    };
+    message?: {
+        role: 'assistant' | 'user' | 'system';
+        content: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Schema generated event.
+ */
+export interface DeepAgentSchemaEvent {
+    type: 'schema';
+    schema: Record<string, unknown>;
+}
+/**
+ * Completion event sent when generation finishes successfully.
+ */
+export interface DeepAgentCompleteEvent {
+    type: 'complete';
+    sessionId: string;
+    appCompiled: boolean;
+}
+/**
+ * Error event sent when generation fails.
+ */
+export interface DeepAgentErrorEvent {
+    type: 'error';
+    error: string;
+}
+/**
+ * Union of all possible DeepAgent SSE events.
+ */
+export type DeepAgentEvent = DeepAgentStartEvent | DeepAgentExecutionEvent | DeepAgentSchemaEvent | DeepAgentCompleteEvent | DeepAgentErrorEvent;
+/**
+ * Parse an SSE data line into a DeepAgentEvent.
+ */
+export declare function parseDeepAgentEvent(data: string): DeepAgentEvent;
+/**
+ * Type guard for start events.
+ */
+export declare function isStartEvent(event: DeepAgentEvent): event is DeepAgentStartEvent;
+/**
+ * Type guard for execution events.
+ */
+export declare function isExecutionEvent(event: DeepAgentEvent): event is DeepAgentExecutionEvent;
+/**
+ * Type guard for schema events.
+ */
+export declare function isSchemaEvent(event: DeepAgentEvent): event is DeepAgentSchemaEvent;
+/**
+ * Type guard for complete events.
+ */
+export declare function isCompleteEvent(event: DeepAgentEvent): event is DeepAgentCompleteEvent;
+/**
+ * Type guard for error events.
+ */
+export declare function isErrorEvent(event: DeepAgentEvent): event is DeepAgentErrorEvent;