@almadar/agent 1.0.0

package/dist/api-types-BW_58thJ.d.ts

@@ -0,0 +1,557 @@
+import { z } from 'zod';
+
+/**
+ * DeepAgent API Types
+ *
+ * Request/response types for the skills-only DeepAgent API.
+ * All agent behavior is defined through skills - no custom prompts allowed.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Extracted requirements schema - from analysis phase.
+ * Used to provide more precise generation guidance.
+ */
+declare const ExtractedRequirementsSchema: z.ZodObject<{
+    /** Entity names to create */
+    entities: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /** State names that should exist */
+    states: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /** Event/action names */
+    events: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /** Business rules (become guards) */
+    guards: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /** Page types needed */
+    pages: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /** Notifications/side-effects */
+    effects: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    /** Raw requirement statements */
+    rawRequirements: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+}, "strip", z.ZodTypeAny, {
+    entities: string[];
+    states: string[];
+    events: string[];
+    guards: string[];
+    pages: string[];
+    effects: string[];
+    rawRequirements: string[];
+}, {
+    entities?: string[] | undefined;
+    states?: string[] | undefined;
+    events?: string[] | undefined;
+    guards?: string[] | undefined;
+    pages?: string[] | undefined;
+    effects?: string[] | undefined;
+    rawRequirements?: string[] | undefined;
+}>;
+type ExtractedRequirementsInput = z.infer<typeof ExtractedRequirementsSchema>;
+/**
+ * Generate request schema - skills only, no custom prompts.
+ */
+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 */
+    message: z.ZodString;
+    /** Optional: Thread ID for session continuity */
+    threadId: z.ZodOptional<z.ZodString>;
+    /** Optional: Workspace directory (defaults to temp dir) */
+    workspace: z.ZodOptional<z.ZodString>;
+    /** Optional: LLM provider */
+    provider: z.ZodOptional<z.ZodEnum<["anthropic", "openai", "deepseek"]>>;
+    /** Optional: Model name */
+    model: z.ZodOptional<z.ZodString>;
+    /** Optional: Disable human-in-the-loop interrupts (for eval/testing) */
+    noInterrupt: z.ZodOptional<z.ZodBoolean>;
+    /** Optional: App ID for persisting schema to Firestore */
+    appId: z.ZodOptional<z.ZodString>;
+    /** Optional: Extracted requirements from analysis phase (for orbital skill) */
+    requirements: z.ZodOptional<z.ZodObject<{
+        /** Entity names to create */
+        entities: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        /** State names that should exist */
+        states: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        /** Event/action names */
+        events: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        /** Business rules (become guards) */
+        guards: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        /** Page types needed */
+        pages: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        /** Notifications/side-effects */
+        effects: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+        /** Raw requirement statements */
+        rawRequirements: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString, "many">>>;
+    }, "strip", z.ZodTypeAny, {
+        entities: string[];
+        states: string[];
+        events: string[];
+        guards: string[];
+        pages: string[];
+        effects: string[];
+        rawRequirements: string[];
+    }, {
+        entities?: string[] | undefined;
+        states?: string[] | undefined;
+        events?: string[] | undefined;
+        guards?: string[] | undefined;
+        pages?: string[] | undefined;
+        effects?: string[] | undefined;
+        rawRequirements?: string[] | undefined;
+    }>>;
+    /** Optional: GitHub integration configuration */
+    github: z.ZodOptional<z.ZodObject<{
+        /** GitHub personal access token */
+        token: z.ZodString;
+        /** Repository owner (e.g., 'octocat') */
+        owner: z.ZodOptional<z.ZodString>;
+        /** Repository name (e.g., 'hello-world') */
+        repo: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        token: string;
+        owner?: string | undefined;
+        repo?: string | undefined;
+    }, {
+        token: string;
+        owner?: string | undefined;
+        repo?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    message: string;
+    skill: string | string[];
+    threadId?: string | undefined;
+    workspace?: string | undefined;
+    provider?: "anthropic" | "openai" | "deepseek" | undefined;
+    model?: string | undefined;
+    noInterrupt?: boolean | undefined;
+    appId?: string | undefined;
+    requirements?: {
+        entities: string[];
+        states: string[];
+        events: string[];
+        guards: string[];
+        pages: string[];
+        effects: string[];
+        rawRequirements: string[];
+    } | undefined;
+    github?: {
+        token: string;
+        owner?: string | undefined;
+        repo?: string | undefined;
+    } | undefined;
+}, {
+    message: string;
+    skill: string | string[];
+    threadId?: string | undefined;
+    workspace?: string | undefined;
+    provider?: "anthropic" | "openai" | "deepseek" | undefined;
+    model?: string | undefined;
+    noInterrupt?: boolean | undefined;
+    appId?: string | undefined;
+    requirements?: {
+        entities?: string[] | undefined;
+        states?: string[] | undefined;
+        events?: string[] | undefined;
+        guards?: string[] | undefined;
+        pages?: string[] | undefined;
+        effects?: string[] | undefined;
+        rawRequirements?: string[] | undefined;
+    } | undefined;
+    github?: {
+        token: string;
+        owner?: string | undefined;
+        repo?: string | undefined;
+    } | undefined;
+}>;
+type GenerateRequest = z.infer<typeof GenerateRequestSchema>;
+/**
+ * Resume request schema - for resuming after interrupt.
+ */
+declare const ResumeRequestSchema: z.ZodObject<{
+    /** Required: Thread ID to resume */
+    threadId: z.ZodString;
+    /** Required: Decisions for pending interrupts */
+    decisions: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<["approve", "edit", "reject"]>;
+        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "approve" | "edit" | "reject";
+        args?: Record<string, unknown> | undefined;
+    }, {
+        type: "approve" | "edit" | "reject";
+        args?: Record<string, unknown> | undefined;
+    }>, "many">;
+    /** Optional: Approve all future actions */
+    approveAll: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    threadId: string;
+    decisions: {
+        type: "approve" | "edit" | "reject";
+        args?: Record<string, unknown> | undefined;
+    }[];
+    approveAll?: boolean | undefined;
+}, {
+    threadId: string;
+    decisions: {
+        type: "approve" | "edit" | "reject";
+        args?: Record<string, unknown> | undefined;
+    }[];
+    approveAll?: boolean | undefined;
+}>;
+type ResumeRequest = z.infer<typeof ResumeRequestSchema>;
+/**
+ * Continue request schema - for multi-turn conversation.
+ */
+declare const ContinueRequestSchema: z.ZodObject<{
+    /** Required: Thread ID to continue */
+    threadId: z.ZodString;
+    /** Required: Follow-up message */
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    threadId: string;
+}, {
+    message: string;
+    threadId: string;
+}>;
+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';
+/**
+ * Base SSE event structure.
+ */
+interface SSEEventBase {
+    type: SSEEventType;
+    timestamp: number;
+}
+/**
+ * Start event - sent when streaming begins.
+ */
+interface StartEvent extends SSEEventBase {
+    type: 'start';
+    data: {
+        threadId: string;
+        skill: string;
+        workDir: string;
+    };
+}
+/**
+ * Message event - agent text output.
+ */
+interface MessageEvent extends SSEEventBase {
+    type: 'message';
+    data: {
+        content: string;
+        role: 'assistant' | 'user' | 'system';
+        isComplete: boolean;
+    };
+}
+/**
+ * Tool call event - when agent invokes a tool.
+ */
+interface ToolCallEvent extends SSEEventBase {
+    type: 'tool_call';
+    data: {
+        tool: string;
+        args: Record<string, unknown>;
+    };
+}
+/**
+ * Tool result event - tool execution result.
+ */
+interface ToolResultEvent extends SSEEventBase {
+    type: 'tool_result';
+    data: {
+        tool: string;
+        result: unknown;
+        success: boolean;
+    };
+}
+/**
+ * Todo update event - task progress.
+ */
+interface TodoUpdateEvent extends SSEEventBase {
+    type: 'todo_update';
+    data: {
+        todos: Array<{
+            id: string;
+            task: string;
+            status: 'pending' | 'in_progress' | 'completed';
+        }>;
+    };
+}
+/**
+ * Activity type for todo details.
+ */
+type TodoActivityType = 'thinking' | 'tool_call' | 'tool_result' | 'code_change';
+/**
+ * Todo detail event - shows LLM activity for a specific todo.
+ */
+interface TodoDetailEvent extends SSEEventBase {
+    type: 'todo_detail';
+    data: {
+        todoId: string;
+        activityType: TodoActivityType;
+        content: string;
+        tool?: string;
+        args?: Record<string, unknown>;
+        success?: boolean;
+        filePath?: string;
+        diff?: string;
+    };
+}
+/**
+ * File operation event.
+ */
+interface FileOperationEvent extends SSEEventBase {
+    type: 'file_operation';
+    data: {
+        operation: 'ls' | 'read_file' | 'write_file' | 'edit_file';
+        path: string;
+        success: boolean;
+    };
+}
+/**
+ * Schema update event.
+ */
+interface SchemaUpdateEvent extends SSEEventBase {
+    type: 'schema_update';
+    data: {
+        appId: string;
+        version: number;
+        schema: Record<string, unknown>;
+        isNew: boolean;
+        snapshotId?: string;
+        changesetId?: string;
+    };
+}
+/**
+ * Generation log event.
+ */
+interface GenerationLogEvent extends SSEEventBase {
+    type: 'generation_log';
+    data: {
+        level: 'info' | 'warn' | 'error' | 'debug';
+        message: string;
+        data?: Record<string, unknown>;
+        orbitalName?: string;
+    };
+}
+/**
+ * Interrupt event - awaiting human decision.
+ */
+interface InterruptEvent extends SSEEventBase {
+    type: 'interrupt';
+    data: {
+        threadId: string;
+        actionRequests: Array<{
+            tool: string;
+            args: Record<string, unknown>;
+            allowedDecisions: ('approve' | 'edit' | 'reject')[];
+            description?: string;
+        }>;
+    };
+}
+/**
+ * Error event.
+ */
+interface ErrorEvent extends SSEEventBase {
+    type: 'error';
+    data: {
+        error: string;
+        code?: string;
+    };
+}
+/**
+ * Cancelled event.
+ */
+interface CancelledEvent extends SSEEventBase {
+    type: 'cancelled';
+    data: {
+        threadId: string;
+        message: string;
+    };
+}
+/**
+ * Complete event - when generation finishes.
+ */
+interface CompleteEvent extends SSEEventBase {
+    type: 'complete';
+    data: {
+        threadId: string;
+        skill: string;
+        workDir: string;
+        schemaGenerated: boolean;
+        appCompiled: boolean;
+        schema?: Record<string, unknown>;
+        appId?: string;
+        schemaPersisted?: boolean;
+        snapshotId?: string;
+        changesetId?: string;
+    };
+}
+/**
+ * Subagent event - forwards events from nested agent.
+ */
+interface SubagentEvent extends SSEEventBase {
+    type: 'subagent_event';
+    data: {
+        orbitalName: string;
+        orbitalIndex: number;
+        totalOrbitals: number;
+        event: {
+            type: Exclude<SSEEventType, 'subagent_event'>;
+            data: Record<string, unknown>;
+            timestamp: number;
+        };
+    };
+}
+/**
+ * App created event.
+ */
+interface AppCreatedEvent extends SSEEventBase {
+    type: 'app_created';
+    data: {
+        appId: string;
+        name?: string;
+        orbitalCount?: number;
+        fromOrbitalPersistence?: boolean;
+    };
+}
+/**
+ * Schema phase validated event.
+ */
+interface SchemaPhaseValidatedEvent extends SSEEventBase {
+    type: 'schema_phase_validated';
+    data: {
+        appId: string;
+        success: boolean;
+        errors?: unknown[];
+    };
+}
+/**
+ * Schema phase update event.
+ */
+interface SchemaPhaseUpdateEvent extends SSEEventBase {
+    type: 'schema_phase_update';
+    data: Record<string, unknown>;
+}
+/**
+ * Orbital added event.
+ */
+interface OrbitalAddedEvent extends SSEEventBase {
+    type: 'orbital_added';
+    data: {
+        appId: string;
+        orbitalName: string;
+        orbitalIndex: number;
+        totalOrbitals: number;
+        isNew?: boolean;
+        orbitalSchema?: Record<string, unknown>;
+    };
+}
+/**
+ * Orbital schema complete event.
+ */
+interface OrbitalSchemaCompleteEvent extends SSEEventBase {
+    type: 'orbital_schema_complete';
+    data: {
+        appId: string;
+        totalOrbitals: number;
+        orbitalNames: string[];
+    };
+}
+/**
+ * Changeset recorded event.
+ */
+interface ChangesetRecordedEvent extends SSEEventBase {
+    type: 'changeset_recorded';
+    data: {
+        appId: string;
+        changesetId: string;
+        version: number;
+        trackingMode: 'initial' | 'update';
+        summary: {
+            added: number;
+            modified: number;
+            removed: number;
+        };
+        source?: string;
+    };
+}
+/**
+ * Snapshot created event.
+ */
+interface SnapshotCreatedEvent extends SSEEventBase {
+    type: 'snapshot_created';
+    data: {
+        appId: string;
+        snapshotId: string;
+        version: number;
+        reason: string;
+    };
+}
+/**
+ * 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;
+/**
+ * Create an SSE event with timestamp.
+ */
+declare function createSSEEvent<T extends SSEEventType>(type: T, data: Extract<SSEEvent, {
+    type: T;
+}>['data']): Extract<SSEEvent, {
+    type: T;
+}>;
+/**
+ * Format an SSE event for transmission.
+ */
+declare function formatSSEEvent(event: SSEEvent): string;
+/**
+ * Parse an SSE event from a data string.
+ */
+declare function parseSSEEvent(data: string): SSEEvent;
+/**
+ * Type guard for SSE start events.
+ */
+declare function isSSEStartEvent(event: SSEEvent): event is StartEvent;
+/**
+ * Type guard for SSE message events.
+ */
+declare function isSSEMessageEvent(event: SSEEvent): event is MessageEvent;
+/**
+ * Type guard for SSE interrupt events.
+ */
+declare function isSSEInterruptEvent(event: SSEEvent): event is InterruptEvent;
+/**
+ * Type guard for SSE complete events.
+ */
+declare function isSSECompleteEvent(event: SSEEvent): event is CompleteEvent;
+/**
+ * Type guard for SSE error events.
+ */
+declare function isSSEErrorEvent(event: SSEEvent): event is ErrorEvent;
+/**
+ * Type guard for SSE tool call events.
+ */
+declare function isSSEToolCallEvent(event: SSEEvent): event is ToolCallEvent;
+/**
+ * Type guard for SSE todo update events.
+ */
+declare function isSSETodoUpdateEvent(event: SSEEvent): event is TodoUpdateEvent;
+/**
+ * Type guard for SSE todo detail events.
+ */
+declare function isSSETodoDetailEvent(event: SSEEvent): event is TodoDetailEvent;
+/**
+ * Type guard for SSE subagent events.
+ */
+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 };

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

@@ -0,0 +1,125 @@
+import { a as SSEEvent } from '../api-types-BW_58thJ.js';
+import 'zod';
+
+/**
+ * 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)
+ */
+
+/**
+ * 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.
+ */
+declare function extractFileOperation(event: RawAgentEvent): {
+    operation: string;
+    path: string;
+} | null;
+
+export { type RawAgentEvent, extractFileOperation, extractInterruptData, hasInterrupt, isFileOperation, isTodoUpdate, transformAgentEvent, transformAgentEventMulti };