@almadar/agent 2.0.0 → 2.0.1

package/dist/api-types.d.ts

@@ -0,0 +1,595 @@
+/**
+ * DeepAgent API Types
+ *
+ * Request/response types for the skills-only DeepAgent API.
+ * All agent behavior is defined through skills - no custom prompts allowed.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/**
+ * Extracted requirements schema - from analysis phase.
+ * Used to provide more precise generation guidance.
+ */
+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 */
+    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;
+}>;
+export type ExtractedRequirementsInput = z.infer<typeof ExtractedRequirementsSchema>;
+/**
+ * Generate request schema - skills only, no custom prompts.
+ */
+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 */
+    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", "kimi", "openrouter"]>>;
+    /** 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;
+    }>>;
+    /** Optional: Use orchestrated generation with complexity-based provider routing (default: false) */
+    useOrchestration: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    message: string;
+    skill: string | string[];
+    threadId?: string | undefined;
+    workspace?: string | undefined;
+    provider?: "anthropic" | "openai" | "deepseek" | "kimi" | "openrouter" | 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;
+    useOrchestration?: boolean | undefined;
+}, {
+    message: string;
+    skill: string | string[];
+    threadId?: string | undefined;
+    workspace?: string | undefined;
+    provider?: "anthropic" | "openai" | "deepseek" | "kimi" | "openrouter" | 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;
+    useOrchestration?: boolean | undefined;
+}>;
+export type GenerateRequest = z.infer<typeof GenerateRequestSchema>;
+/**
+ * Resume request schema - for resuming after interrupt.
+ */
+export 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;
+}>;
+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.
+ */
+export 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;
+}>;
+export type ContinueRequest = z.infer<typeof ContinueRequestSchema>;
+/**
+ * All possible SSE event types.
+ */
+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.
+ */
+export interface SSEEventBase {
+    type: SSEEventType;
+    timestamp: number;
+}
+/**
+ * Start event - sent when streaming begins.
+ */
+export interface StartEvent extends SSEEventBase {
+    type: 'start';
+    data: {
+        threadId: string;
+        skill: string;
+        workDir: string;
+    };
+}
+/**
+ * Message event - agent text output.
+ */
+export interface MessageEvent extends SSEEventBase {
+    type: 'message';
+    data: {
+        content: string;
+        role: 'assistant' | 'user' | 'system';
+        isComplete: boolean;
+    };
+}
+/**
+ * Tool call event - when agent invokes a tool.
+ */
+export interface ToolCallEvent extends SSEEventBase {
+    type: 'tool_call';
+    data: {
+        tool: string;
+        args: Record<string, unknown>;
+    };
+}
+/**
+ * Tool result event - tool execution result.
+ */
+export interface ToolResultEvent extends SSEEventBase {
+    type: 'tool_result';
+    data: {
+        tool: string;
+        result: unknown;
+        success: boolean;
+    };
+}
+/**
+ * Todo update event - task progress.
+ */
+export interface TodoUpdateEvent extends SSEEventBase {
+    type: 'todo_update';
+    data: {
+        todos: Array<{
+            id: string;
+            task: string;
+            status: 'pending' | 'in_progress' | 'completed';
+        }>;
+    };
+}
+/**
+ * Activity type for todo details.
+ */
+export type TodoActivityType = 'thinking' | 'tool_call' | 'tool_result' | 'code_change';
+/**
+ * Todo detail event - shows LLM activity for a specific todo.
+ */
+export 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.
+ */
+export interface FileOperationEvent extends SSEEventBase {
+    type: 'file_operation';
+    data: {
+        operation: 'ls' | 'read_file' | 'write_file' | 'edit_file';
+        path: string;
+        success: boolean;
+    };
+}
+/**
+ * Schema update event.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export interface ErrorEvent extends SSEEventBase {
+    type: 'error';
+    data: {
+        error: string;
+        code?: string;
+    };
+}
+/**
+ * Cancelled event.
+ */
+export interface CancelledEvent extends SSEEventBase {
+    type: 'cancelled';
+    data: {
+        threadId: string;
+        message: string;
+    };
+}
+/**
+ * Complete event - when generation finishes.
+ */
+export 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.
+ */
+export 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.
+ */
+export interface AppCreatedEvent extends SSEEventBase {
+    type: 'app_created';
+    data: {
+        appId: string;
+        name?: string;
+        orbitalCount?: number;
+        fromOrbitalPersistence?: boolean;
+    };
+}
+/**
+ * Schema phase validated event.
+ */
+export interface SchemaPhaseValidatedEvent extends SSEEventBase {
+    type: 'schema_phase_validated';
+    data: {
+        appId: string;
+        success: boolean;
+        errors?: unknown[];
+    };
+}
+/**
+ * Schema phase update event.
+ */
+export interface SchemaPhaseUpdateEvent extends SSEEventBase {
+    type: 'schema_phase_update';
+    data: Record<string, unknown>;
+}
+/**
+ * Orbital added event.
+ */
+export 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.
+ */
+export interface OrbitalSchemaCompleteEvent extends SSEEventBase {
+    type: 'orbital_schema_complete';
+    data: {
+        appId: string;
+        totalOrbitals: number;
+        orbitalNames: string[];
+    };
+}
+/**
+ * Changeset recorded event.
+ */
+export 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.
+ */
+export interface SnapshotCreatedEvent extends SSEEventBase {
+    type: 'snapshot_created';
+    data: {
+        appId: string;
+        snapshotId: string;
+        version: number;
+        reason: string;
+    };
+}
+/**
+ * Union of all SSE event types.
+ */
+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.
+ */
+export declare function createSSEEvent<T extends SSEEventType>(type: T, data: Extract<SSEEvent, {
+    type: T;
+}>['data']): Extract<SSEEvent, {
+    type: T;
+}>;
+/**
+ * Format an SSE event for transmission.
+ */
+export declare function formatSSEEvent(event: SSEEvent): string;
+/**
+ * Parse an SSE event from a data string.
+ */
+export declare function parseSSEEvent(data: string): SSEEvent;
+/**
+ * Type guard for SSE start events.
+ */
+export declare function isSSEStartEvent(event: SSEEvent): event is StartEvent;
+/**
+ * Type guard for SSE message events.
+ */
+export declare function isSSEMessageEvent(event: SSEEvent): event is MessageEvent;
+/**
+ * Type guard for SSE interrupt events.
+ */
+export declare function isSSEInterruptEvent(event: SSEEvent): event is InterruptEvent;
+/**
+ * Type guard for SSE complete events.
+ */
+export declare function isSSECompleteEvent(event: SSEEvent): event is CompleteEvent;
+/**
+ * Type guard for SSE error events.
+ */
+export declare function isSSEErrorEvent(event: SSEEvent): event is ErrorEvent;
+/**
+ * Type guard for SSE tool call events.
+ */
+export declare function isSSEToolCallEvent(event: SSEEvent): event is ToolCallEvent;
+/**
+ * Type guard for SSE todo update events.
+ */
+export declare function isSSETodoUpdateEvent(event: SSEEvent): event is TodoUpdateEvent;
+/**
+ * Type guard for SSE todo detail events.
+ */
+export declare function isSSETodoDetailEvent(event: SSEEvent): event is TodoDetailEvent;
+/**
+ * Type guard for SSE subagent events.
+ */
+export declare function isSSESubagentEvent(event: SSEEvent): event is SubagentEvent;
+/**
+ * Type guard for SSE generation log events.
+ */
+export declare function isSSEGenerationLogEvent(event: SSEEvent): event is GenerationLogEvent;