@almadar/agent 1.6.4 → 2.0.1

package/dist/{api-types-CXrq-fts.d.ts → api-types.d.ts}

@@ -1,5 +1,3 @@
-import { z } from 'zod';
-
 /**
  * DeepAgent API Types
  *
@@ -8,12 +6,12 @@ import { z } from 'zod';
  *
  * @packageDocumentation
  */
-
+import { z } from 'zod';
 /**
  * Extracted requirements schema - from analysis phase.
  * Used to provide more precise generation guidance.
  */
-declare const ExtractedRequirementsSchema: z.ZodObject<{
+export declare const ExtractedRequirementsSchema: z.ZodObject<{
     /** Entity names to create */
     entities: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
     /** State names that should exist */
@@ -45,11 +43,11 @@ declare const ExtractedRequirementsSchema: z.ZodObject<{
     effects?: string[] | undefined;
     rawRequirements?: string[] | undefined;
 }>;
-type ExtractedRequirementsInput = z.infer<typeof ExtractedRequirementsSchema>;
+export type ExtractedRequirementsInput = z.infer<typeof ExtractedRequirementsSchema>;
 /**
  * Generate request schema - skills only, no custom prompts.
  */
-declare const GenerateRequestSchema: z.ZodObject<{
+export declare const GenerateRequestSchema: z.ZodObject<{
     /** Required: The skill(s) to use for this generation */
     skill: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
     /** The user's task/message */
@@ -167,11 +165,11 @@ declare const GenerateRequestSchema: z.ZodObject<{
     } | undefined;
     useOrchestration?: boolean | undefined;
 }>;
-type GenerateRequest = z.infer<typeof GenerateRequestSchema>;
+export type GenerateRequest = z.infer<typeof GenerateRequestSchema>;
 /**
  * Resume request schema - for resuming after interrupt.
  */
-declare const ResumeRequestSchema: z.ZodObject<{
+export declare const ResumeRequestSchema: z.ZodObject<{
     /** Required: Thread ID to resume */
     threadId: z.ZodString;
     /** Required: Decisions for pending interrupts */
@@ -202,11 +200,18 @@ declare const ResumeRequestSchema: z.ZodObject<{
     }[];
     approveAll?: boolean | undefined;
 }>;
-type ResumeRequest = z.infer<typeof ResumeRequestSchema>;
+export type ResumeRequest = z.infer<typeof ResumeRequestSchema>;
+/**
+ * Decision type for interrupt responses.
+ */
+export interface Decision {
+    type: 'approve' | 'edit' | 'reject';
+    args?: Record<string, unknown>;
+}
 /**
  * Continue request schema - for multi-turn conversation.
  */
-declare const ContinueRequestSchema: z.ZodObject<{
+export declare const ContinueRequestSchema: z.ZodObject<{
     /** Required: Thread ID to continue */
     threadId: z.ZodString;
     /** Required: Follow-up message */
@@ -218,22 +223,22 @@ declare const ContinueRequestSchema: z.ZodObject<{
     message: string;
     threadId: string;
 }>;
-type ContinueRequest = z.infer<typeof ContinueRequestSchema>;
+export type ContinueRequest = z.infer<typeof ContinueRequestSchema>;
 /**
  * All possible SSE event types.
  */
-type SSEEventType = 'start' | 'message' | 'tool_call' | 'tool_result' | 'todo_update' | 'todo_detail' | 'file_operation' | 'schema_update' | 'generation_log' | 'subagent_event' | 'interrupt' | 'error' | 'complete' | 'cancelled' | 'app_created' | 'schema_phase_validated' | 'schema_phase_update' | 'orbital_added' | 'orbital_schema_complete' | 'changeset_recorded' | 'snapshot_created';
+export type SSEEventType = 'start' | 'message' | 'tool_call' | 'tool_result' | 'todo_update' | 'todo_detail' | 'file_operation' | 'schema_update' | 'generation_log' | 'subagent_event' | 'interrupt' | 'error' | 'complete' | 'cancelled' | 'app_created' | 'schema_phase_validated' | 'schema_phase_update' | 'orbital_added' | 'orbital_schema_complete' | 'changeset_recorded' | 'snapshot_created';
 /**
  * Base SSE event structure.
  */
-interface SSEEventBase {
+export interface SSEEventBase {
     type: SSEEventType;
     timestamp: number;
 }
 /**
  * Start event - sent when streaming begins.
  */
-interface StartEvent extends SSEEventBase {
+export interface StartEvent extends SSEEventBase {
     type: 'start';
     data: {
         threadId: string;
@@ -244,7 +249,7 @@ interface StartEvent extends SSEEventBase {
 /**
  * Message event - agent text output.
  */
-interface MessageEvent extends SSEEventBase {
+export interface MessageEvent extends SSEEventBase {
     type: 'message';
     data: {
         content: string;
@@ -255,7 +260,7 @@ interface MessageEvent extends SSEEventBase {
 /**
  * Tool call event - when agent invokes a tool.
  */
-interface ToolCallEvent extends SSEEventBase {
+export interface ToolCallEvent extends SSEEventBase {
     type: 'tool_call';
     data: {
         tool: string;
@@ -265,7 +270,7 @@ interface ToolCallEvent extends SSEEventBase {
 /**
  * Tool result event - tool execution result.
  */
-interface ToolResultEvent extends SSEEventBase {
+export interface ToolResultEvent extends SSEEventBase {
     type: 'tool_result';
     data: {
         tool: string;
@@ -276,7 +281,7 @@ interface ToolResultEvent extends SSEEventBase {
 /**
  * Todo update event - task progress.
  */
-interface TodoUpdateEvent extends SSEEventBase {
+export interface TodoUpdateEvent extends SSEEventBase {
     type: 'todo_update';
     data: {
         todos: Array<{
@@ -289,11 +294,11 @@ interface TodoUpdateEvent extends SSEEventBase {
 /**
  * Activity type for todo details.
  */
-type TodoActivityType = 'thinking' | 'tool_call' | 'tool_result' | 'code_change';
+export type TodoActivityType = 'thinking' | 'tool_call' | 'tool_result' | 'code_change';
 /**
  * Todo detail event - shows LLM activity for a specific todo.
  */
-interface TodoDetailEvent extends SSEEventBase {
+export interface TodoDetailEvent extends SSEEventBase {
     type: 'todo_detail';
     data: {
         todoId: string;
@@ -309,7 +314,7 @@ interface TodoDetailEvent extends SSEEventBase {
 /**
  * File operation event.
  */
-interface FileOperationEvent extends SSEEventBase {
+export interface FileOperationEvent extends SSEEventBase {
     type: 'file_operation';
     data: {
         operation: 'ls' | 'read_file' | 'write_file' | 'edit_file';
@@ -320,7 +325,7 @@ interface FileOperationEvent extends SSEEventBase {
 /**
  * Schema update event.
  */
-interface SchemaUpdateEvent extends SSEEventBase {
+export interface SchemaUpdateEvent extends SSEEventBase {
     type: 'schema_update';
     data: {
         appId: string;
@@ -334,7 +339,7 @@ interface SchemaUpdateEvent extends SSEEventBase {
 /**
  * Generation log event.
  */
-interface GenerationLogEvent extends SSEEventBase {
+export interface GenerationLogEvent extends SSEEventBase {
     type: 'generation_log';
     data: {
         level: 'info' | 'warn' | 'error' | 'debug';
@@ -346,7 +351,7 @@ interface GenerationLogEvent extends SSEEventBase {
 /**
  * Interrupt event - awaiting human decision.
  */
-interface InterruptEvent extends SSEEventBase {
+export interface InterruptEvent extends SSEEventBase {
     type: 'interrupt';
     data: {
         threadId: string;
@@ -361,7 +366,7 @@ interface InterruptEvent extends SSEEventBase {
 /**
  * Error event.
  */
-interface ErrorEvent extends SSEEventBase {
+export interface ErrorEvent extends SSEEventBase {
     type: 'error';
     data: {
         error: string;
@@ -371,7 +376,7 @@ interface ErrorEvent extends SSEEventBase {
 /**
  * Cancelled event.
  */
-interface CancelledEvent extends SSEEventBase {
+export interface CancelledEvent extends SSEEventBase {
     type: 'cancelled';
     data: {
         threadId: string;
@@ -381,7 +386,7 @@ interface CancelledEvent extends SSEEventBase {
 /**
  * Complete event - when generation finishes.
  */
-interface CompleteEvent extends SSEEventBase {
+export interface CompleteEvent extends SSEEventBase {
     type: 'complete';
     data: {
         threadId: string;
@@ -399,7 +404,7 @@ interface CompleteEvent extends SSEEventBase {
 /**
  * Subagent event - forwards events from nested agent.
  */
-interface SubagentEvent extends SSEEventBase {
+export interface SubagentEvent extends SSEEventBase {
     type: 'subagent_event';
     data: {
         orbitalName: string;
@@ -415,7 +420,7 @@ interface SubagentEvent extends SSEEventBase {
 /**
  * App created event.
  */
-interface AppCreatedEvent extends SSEEventBase {
+export interface AppCreatedEvent extends SSEEventBase {
     type: 'app_created';
     data: {
         appId: string;
@@ -427,7 +432,7 @@ interface AppCreatedEvent extends SSEEventBase {
 /**
  * Schema phase validated event.
  */
-interface SchemaPhaseValidatedEvent extends SSEEventBase {
+export interface SchemaPhaseValidatedEvent extends SSEEventBase {
     type: 'schema_phase_validated';
     data: {
         appId: string;
@@ -438,14 +443,14 @@ interface SchemaPhaseValidatedEvent extends SSEEventBase {
 /**
  * Schema phase update event.
  */
-interface SchemaPhaseUpdateEvent extends SSEEventBase {
+export interface SchemaPhaseUpdateEvent extends SSEEventBase {
     type: 'schema_phase_update';
     data: Record<string, unknown>;
 }
 /**
  * Orbital added event.
  */
-interface OrbitalAddedEvent extends SSEEventBase {
+export interface OrbitalAddedEvent extends SSEEventBase {
     type: 'orbital_added';
     data: {
         appId: string;
@@ -459,7 +464,7 @@ interface OrbitalAddedEvent extends SSEEventBase {
 /**
  * Orbital schema complete event.
  */
-interface OrbitalSchemaCompleteEvent extends SSEEventBase {
+export interface OrbitalSchemaCompleteEvent extends SSEEventBase {
     type: 'orbital_schema_complete';
     data: {
         appId: string;
@@ -470,7 +475,7 @@ interface OrbitalSchemaCompleteEvent extends SSEEventBase {
 /**
  * Changeset recorded event.
  */
-interface ChangesetRecordedEvent extends SSEEventBase {
+export interface ChangesetRecordedEvent extends SSEEventBase {
     type: 'changeset_recorded';
     data: {
         appId: string;
@@ -488,7 +493,7 @@ interface ChangesetRecordedEvent extends SSEEventBase {
 /**
  * Snapshot created event.
  */
-interface SnapshotCreatedEvent extends SSEEventBase {
+export interface SnapshotCreatedEvent extends SSEEventBase {
     type: 'snapshot_created';
     data: {
         appId: string;
@@ -500,11 +505,42 @@ interface SnapshotCreatedEvent extends SSEEventBase {
 /**
  * Union of all SSE event types.
  */
-type SSEEvent = StartEvent | MessageEvent | ToolCallEvent | ToolResultEvent | TodoUpdateEvent | TodoDetailEvent | FileOperationEvent | SchemaUpdateEvent | GenerationLogEvent | SubagentEvent | InterruptEvent | ErrorEvent | CancelledEvent | CompleteEvent | AppCreatedEvent | SchemaPhaseValidatedEvent | SchemaPhaseUpdateEvent | OrbitalAddedEvent | OrbitalSchemaCompleteEvent | ChangesetRecordedEvent | SnapshotCreatedEvent;
+export type SSEEvent = StartEvent | MessageEvent | ToolCallEvent | ToolResultEvent | TodoUpdateEvent | TodoDetailEvent | FileOperationEvent | SchemaUpdateEvent | GenerationLogEvent | SubagentEvent | InterruptEvent | ErrorEvent | CancelledEvent | CompleteEvent | AppCreatedEvent | SchemaPhaseValidatedEvent | SchemaPhaseUpdateEvent | OrbitalAddedEvent | OrbitalSchemaCompleteEvent | ChangesetRecordedEvent | SnapshotCreatedEvent;
+/**
+ * List skills response.
+ */
+export interface ListSkillsResponse {
+    available: Array<{
+        name: string;
+        description: string;
+        allowedTools?: string[];
+    }>;
+    installed: Array<{
+        name: string;
+        description: string;
+        allowedTools?: string[];
+    }>;
+}
+/**
+ * Session info response.
+ */
+export interface SessionInfo {
+    threadId: string;
+    skill: string;
+    workDir: string;
+    createdAt: number;
+    lastActivityAt: number;
+}
+/**
+ * List sessions response.
+ */
+export interface ListSessionsResponse {
+    sessions: SessionInfo[];
+}
 /**
  * Create an SSE event with timestamp.
  */
-declare function createSSEEvent<T extends SSEEventType>(type: T, data: Extract<SSEEvent, {
+export declare function createSSEEvent<T extends SSEEventType>(type: T, data: Extract<SSEEvent, {
     type: T;
 }>['data']): Extract<SSEEvent, {
     type: T;
@@ -512,50 +548,48 @@ declare function createSSEEvent<T extends SSEEventType>(type: T, data: Extract<S
 /**
  * Format an SSE event for transmission.
  */
-declare function formatSSEEvent(event: SSEEvent): string;
+export declare function formatSSEEvent(event: SSEEvent): string;
 /**
  * Parse an SSE event from a data string.
  */
-declare function parseSSEEvent(data: string): SSEEvent;
+export declare function parseSSEEvent(data: string): SSEEvent;
 /**
  * Type guard for SSE start events.
  */
-declare function isSSEStartEvent(event: SSEEvent): event is StartEvent;
+export declare function isSSEStartEvent(event: SSEEvent): event is StartEvent;
 /**
  * Type guard for SSE message events.
  */
-declare function isSSEMessageEvent(event: SSEEvent): event is MessageEvent;
+export declare function isSSEMessageEvent(event: SSEEvent): event is MessageEvent;
 /**
  * Type guard for SSE interrupt events.
  */
-declare function isSSEInterruptEvent(event: SSEEvent): event is InterruptEvent;
+export declare function isSSEInterruptEvent(event: SSEEvent): event is InterruptEvent;
 /**
  * Type guard for SSE complete events.
  */
-declare function isSSECompleteEvent(event: SSEEvent): event is CompleteEvent;
+export declare function isSSECompleteEvent(event: SSEEvent): event is CompleteEvent;
 /**
  * Type guard for SSE error events.
  */
-declare function isSSEErrorEvent(event: SSEEvent): event is ErrorEvent;
+export declare function isSSEErrorEvent(event: SSEEvent): event is ErrorEvent;
 /**
  * Type guard for SSE tool call events.
  */
-declare function isSSEToolCallEvent(event: SSEEvent): event is ToolCallEvent;
+export declare function isSSEToolCallEvent(event: SSEEvent): event is ToolCallEvent;
 /**
  * Type guard for SSE todo update events.
  */
-declare function isSSETodoUpdateEvent(event: SSEEvent): event is TodoUpdateEvent;
+export declare function isSSETodoUpdateEvent(event: SSEEvent): event is TodoUpdateEvent;
 /**
  * Type guard for SSE todo detail events.
  */
-declare function isSSETodoDetailEvent(event: SSEEvent): event is TodoDetailEvent;
+export declare function isSSETodoDetailEvent(event: SSEEvent): event is TodoDetailEvent;
 /**
  * Type guard for SSE subagent events.
  */
-declare function isSSESubagentEvent(event: SSEEvent): event is SubagentEvent;
+export declare function isSSESubagentEvent(event: SSEEvent): event is SubagentEvent;
 /**
  * Type guard for SSE generation log events.
  */
-declare function isSSEGenerationLogEvent(event: SSEEvent): event is GenerationLogEvent;
-
-export { type CompleteEvent as C, type ErrorEvent as E, type GenerateRequest as G, type InterruptEvent as I, type MessageEvent as M, type ResumeRequest as R, type SSEEventType as S, type TodoUpdateEvent as T, type SSEEvent as a, type ContinueRequest as b, ContinueRequestSchema as c, type ExtractedRequirementsInput as d, ExtractedRequirementsSchema as e, GenerateRequestSchema as f, type GenerationLogEvent as g, ResumeRequestSchema as h, type StartEvent as i, type SubagentEvent as j, type ToolCallEvent as k, type ToolResultEvent as l, createSSEEvent as m, formatSSEEvent as n, isSSECompleteEvent as o, isSSEErrorEvent as p, isSSEGenerationLogEvent as q, isSSEInterruptEvent as r, isSSEMessageEvent as s, isSSEStartEvent as t, isSSESubagentEvent as u, isSSETodoDetailEvent as v, isSSETodoUpdateEvent as w, isSSEToolCallEvent as x, parseSSEEvent as y };
+export declare function isSSEGenerationLogEvent(event: SSEEvent): event is GenerationLogEvent;

package/dist/context/compaction.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Context Compaction - Phase 1.4 Implementation
+ *
+ * Handle long conversations without token overflow by:
+ * - Summarizing old tool results
+ * - Extracting key user decisions
+ * - Enforcing token limits (80% threshold)
+ *
+ * @packageDocumentation
+ */
+/**
+ * Message type for context compaction.
+ * Defines the minimal shape needed for token estimation and compaction.
+ */
+export interface Message {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | Array<string | {
+        text: string;
+        [key: string]: unknown;
+    }>;
+}
+/**
+ * Compaction strategy
+ */
+export type CompactionStrategy = 'summarize' | 'truncate' | 'extract' | 'hybrid';
+/**
+ * Compaction configuration
+ */
+export interface CompactionConfig {
+    /** Maximum tokens allowed (default: 8000) */
+    maxTokens: number;
+    /** Trigger compaction at this percentage (default: 0.8 = 80%) */
+    triggerThreshold: number;
+    /** Strategy for compaction */
+    strategy: CompactionStrategy;
+    /** Number of recent messages to always preserve */
+    preserveRecent: number;
+    /** Minimum messages before compaction */
+    minMessages: number;
+    /** Max summary length in tokens */
+    maxSummaryTokens: number;
+}
+/**
+ * Token count for a message
+ */
+export interface MessageTokenCount {
+    messageId: string;
+    tokens: number;
+    content: string;
+}
+/**
+ * Context state
+ */
+export interface ContextState {
+    /** Messages in context */
+    messages: Message[];
+    /** Total token count */
+    totalTokens: number;
+    /** Token limit */
+    maxTokens: number;
+    /** Whether compaction was performed */
+    wasCompacted: boolean;
+    /** Compaction history */
+    compactionHistory: CompactionRecord[];
+}
+/**
+ * Compaction record
+ */
+export interface CompactionRecord {
+    /** When compaction occurred */
+    timestamp: number;
+    /** Strategy used */
+    strategy: CompactionStrategy;
+    /** Messages before compaction */
+    messagesBefore: number;
+    /** Messages after compaction */
+    messagesAfter: number;
+    /** Tokens before compaction */
+    tokensBefore: number;
+    /** Tokens after compaction */
+    tokensAfter: number;
+    /** Summary generated (if any) */
+    summary?: string;
+    /** Key decisions extracted */
+    keyDecisions?: string[];
+}
+/**
+ * Extracted decision
+ */
+export interface ExtractedDecision {
+    /** Decision ID */
+    id: string;
+    /** What was decided */
+    decision: string;
+    /** Context around the decision */
+    context: string;
+    /** Who made the decision (user/assistant) */
+    actor: 'user' | 'assistant';
+    /** When it was made */
+    timestamp: number;
+    /** Impact level */
+    impact: 'high' | 'medium' | 'low';
+}
+/**
+ * Estimate token count for text
+ * Rough approximation: ~4 characters per token for English
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Estimate tokens for a message
+ */
+export declare function estimateMessageTokens(message: Message): number;
+export declare class ContextCompactionEngine {
+    private config;
+    private compactionHistory;
+    constructor(config?: Partial<CompactionConfig>);
+    /**
+     * Check if compaction is needed
+     */
+    shouldCompact(messages: Message[]): boolean;
+    /**
+     * Get current context state
+     */
+    getContextState(messages: Message[]): ContextState;
+    /**
+     * Compact context using configured strategy
+     */
+    compact(messages: Message[]): Promise<{
+        messages: Message[];
+        record: CompactionRecord;
+    }>;
+    /**
+     * Summarize old messages, keep recent ones intact
+     */
+    private summarizeStrategy;
+    /**
+     * Truncate oldest messages
+     */
+    private truncateStrategy;
+    /**
+     * Extract key decisions, discard rest
+     */
+    private extractStrategy;
+    /**
+     * Hybrid: Summarize + extract key decisions
+     */
+    private hybridStrategy;
+    /**
+     * Generate summary of messages (simplified version)
+     * In production, this would call an LLM
+     */
+    private generateSummary;
+    /**
+     * Extract decisions from messages
+     */
+    private extractDecisions;
+    /**
+     * Extract topics from messages
+     */
+    private extractTopics;
+    /**
+     * Convert message to text
+     */
+    private messageToText;
+    /**
+     * Get compaction statistics
+     */
+    getStatistics(): {
+        totalCompactions: number;
+        averageReduction: number;
+        averageTokenReduction: number;
+        strategiesUsed: Record<CompactionStrategy, number>;
+    };
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<CompactionConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): CompactionConfig;
+}
+export declare function createContextCompactionEngine(config?: Partial<CompactionConfig>): ContextCompactionEngine;
+/**
+ * Auto-compact context if needed
+ */
+export declare function autoCompact(messages: Message[], config?: Partial<CompactionConfig>): Promise<{
+    messages: Message[];
+    wasCompacted: boolean;
+    record?: CompactionRecord;
+}>;

package/dist/context-compaction.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Context Compaction for DeepAgent
+ *
+ * Provides middleware to manage context length in long-running agent sessions.
+ * Uses @langchain/core's trimMessages to keep context within token limits.
+ *
+ * @packageDocumentation
+ */
+import { type BaseMessage } from '@langchain/core/messages';
+import type { BaseLanguageModel } from '@langchain/core/language_models/base';
+/**
+ * Configuration for context compaction.
+ */
+export interface ContextCompactionConfig {
+    /**
+     * Maximum number of tokens before triggering compaction.
+     * Default: 150000 (leaves headroom for Claude's 200K context)
+     */
+    maxTokens?: number;
+    /**
+     * Number of recent messages to always keep.
+     * Default: 10
+     */
+    keepRecentMessages?: number;
+    /**
+     * Whether to include the system message in trimming.
+     * Default: false (system message is always kept)
+     */
+    includeSystem?: boolean;
+    /**
+     * Strategy for trimming: 'first' keeps first messages, 'last' keeps last messages.
+     * Default: 'last'
+     */
+    strategy?: 'first' | 'last';
+}
+/**
+ * Default configuration for context compaction.
+ */
+export declare const DEFAULT_COMPACTION_CONFIG: Required<ContextCompactionConfig>;
+/**
+ * Compact messages to fit within token limit.
+ */
+export declare function compactMessages(messages: BaseMessage[], model: BaseLanguageModel, config?: ContextCompactionConfig): Promise<BaseMessage[]>;
+/**
+ * Check if messages need compaction based on estimated token count.
+ */
+export declare function needsCompaction(messages: BaseMessage[], threshold?: number): boolean;
+/**
+ * Create a message summarizer prompt for compacting old context.
+ */
+export declare function createSummaryPrompt(messages: BaseMessage[]): string;
+/**
+ * Estimate token count for messages using character-based heuristic.
+ */
+export declare function estimateTokens(messages: BaseMessage[]): number;