@ai-setting/roy-agent-core 1.7.52 → 1.7.53

package/dist/env/session/types.d.ts

@@ -0,0 +1,705 @@
+/**
+ * @fileoverview Session Component Types
+ */
+import { z } from "zod";
+/**
+ * Session Component configuration schema
+ */
+export declare const SessionConfigSchema: z.ZodEffects<z.ZodObject<{
+    /** Default working directory */
+    defaultDirectory: z.ZodDefault<z.ZodString>;
+    /** Default title template */
+    defaultTitleTemplate: z.ZodDefault<z.ZodString>;
+    /** Maximum number of messages per session */
+    maxMessages: z.ZodDefault<z.ZodNumber>;
+    /** Context compaction threshold (percentage) */
+    compactionThreshold: z.ZodDefault<z.ZodNumber>;
+    /** Enable auto compaction */
+    autoCompact: z.ZodDefault<z.ZodBoolean>;
+    /** Storage configuration */
+    storage: z.ZodDefault<z.ZodObject<{
+        type: z.ZodDefault<z.ZodEnum<["memory", "sqlite"]>>;
+        dbPath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: "memory" | "sqlite";
+        dbPath?: string | undefined;
+    }, {
+        type?: "memory" | "sqlite" | undefined;
+        dbPath?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    compactionThreshold: number;
+    storage: {
+        type: "memory" | "sqlite";
+        dbPath?: string | undefined;
+    };
+    defaultDirectory: string;
+    defaultTitleTemplate: string;
+    maxMessages: number;
+    autoCompact: boolean;
+}, {
+    compactionThreshold?: number | undefined;
+    storage?: {
+        type?: "memory" | "sqlite" | undefined;
+        dbPath?: string | undefined;
+    } | undefined;
+    defaultDirectory?: string | undefined;
+    defaultTitleTemplate?: string | undefined;
+    maxMessages?: number | undefined;
+    autoCompact?: boolean | undefined;
+}>, {
+    defaultDirectory: string;
+    compactionThreshold: number;
+    storage: {
+        type: "memory" | "sqlite";
+        dbPath?: string | undefined;
+    };
+    defaultTitleTemplate: string;
+    maxMessages: number;
+    autoCompact: boolean;
+}, {
+    compactionThreshold?: number | undefined;
+    storage?: {
+        type?: "memory" | "sqlite" | undefined;
+        dbPath?: string | undefined;
+    } | undefined;
+    defaultDirectory?: string | undefined;
+    defaultTitleTemplate?: string | undefined;
+    maxMessages?: number | undefined;
+    autoCompact?: boolean | undefined;
+}>;
+export type SessionConfig = z.infer<typeof SessionConfigSchema>;
+/**
+ * Checkpoint type
+ */
+export type CheckpointType = "compact" | "manual";
+/**
+ * Checkpoint metadata (stored in Session.metadata)
+ */
+export interface CheckpointMeta {
+    id: string;
+    messageIndex: number;
+    title: string;
+    createdAt: number;
+    type: CheckpointType;
+}
+/**
+ * User Intent type - represents a user's intent extracted from conversation
+ */
+export type UserIntent = string;
+/**
+ * Recent message for checkpoint
+ *
+ * Stores a simplified version of a message for context preservation
+ */
+export interface RecentMessage {
+    role: string;
+    content: string;
+}
+/**
+ * Complete checkpoint information (includes generated content)
+ */
+export interface SessionCheckpoint extends CheckpointMeta {
+    summary: string;
+    processKeyPoints: string[];
+    currentState: string;
+    nextSteps: string[];
+    messageCountBefore: number;
+    metadata?: Record<string, unknown>;
+    /** User intents extracted from the conversation */
+    userIntents: UserIntent[];
+    /**
+     * Recent messages preserved from the compacted conversation
+     *
+     * Contains the last N turns of user query + assistant text response
+     * (excluding tool calls and tool results).
+     * This allows the checkpoint to serve as a fresh history context.
+     *
+     * Format: [user, assistant, user, assistant, ...] from most recent
+     */
+    recentMessages?: RecentMessage[];
+}
+/**
+ * Checkpoints metadata in session
+ */
+export interface SessionCheckpointsMeta {
+    latestCheckpointId?: string;
+    checkpoints: CheckpointMeta[];
+}
+/**
+ * Checkpoint message metadata (stored in message metadata)
+ */
+export interface CheckpointMessageMeta {
+    isCheckpoint: boolean;
+    checkpointId: string;
+    checkpointMeta: SessionCheckpoint;
+}
+/**
+ * Session entity
+ */
+export interface Session {
+    id: string;
+    title: string;
+    directory: string;
+    /**
+     * Top-level parent session id (Task #1739).
+     *
+     * - `null` when this session has no parent, or when the underlying storage
+     *   row pre-dates the field (no backward migration is performed).
+     * - Persisted in SQLite via the existing `parent_id` column to avoid a
+     *   schema migration; the column is shared with the legacy `parentID`.
+     *
+     * New code should prefer this field. `parentID` is kept as a deprecated
+     * alias that always mirrors `parentSessionId`.
+     */
+    parentSessionId: string | null;
+    /**
+     * @deprecated Kept for backward compatibility. Mirrors `parentSessionId`.
+     * New code should set/read `parentSessionId` instead.
+     */
+    parentID?: string;
+    createdAt: number;
+    updatedAt: number;
+    messageCount: number;
+    metadata?: SessionMetadata;
+}
+/**
+ * Session metadata
+ */
+export interface SessionMetadata extends Record<string, unknown> {
+    /** Total number of messages in the session */
+    messageCount?: number;
+    checkpoints?: SessionCheckpointsMeta;
+    checkpointDetails?: Record<string, SessionCheckpoint>;
+    larkChat?: ChatTaskBinding;
+}
+/**
+ * 飞书群聊 → task 绑定关系
+ *
+ * 存储位置：session.metadata.larkChat（session id = chat_id）
+ *
+ * 关键约束：
+ * - chatId 是 session 主键（PRIMARY KEY），天然唯一
+ * - taskId 与 chatId 是 1:1（每个 task 群对应唯一一个 task）
+ * - rebindCount > 0 时表示曾尝试绑定到不同 task（保留旧 taskId 防误覆盖）
+ */
+export interface ChatTaskBinding {
+    /** 飞书群聊 ID（与 session.id 相同，冗余便于诊断） */
+    chatId: string;
+    /** 绑定的 task ID */
+    taskId: number;
+    /** 创建群聊时使用的 lark-cli profile */
+    profile?: string;
+    /** 绑定时间（ISO 8601） */
+    boundAt: string;
+    /** 绑定状态：creating→ready 成功，failed 标记失败可重试 */
+    status: "creating" | "ready" | "failed";
+    /** 失败时的错误信息（成功时为 null） */
+    errorMessage?: string | null;
+    /** 不同 taskId 重绑次数（>0 时表示检测到冲突） */
+    rebindCount: number;
+}
+/**
+ * upsertChatTaskBinding 入参
+ */
+export interface UpsertChatTaskBindingOptions {
+    /** 飞书群聊 ID（必填） */
+    chatId: string;
+    /** 绑定的 task ID（必填，必须为正整数） */
+    taskId: number;
+    /** lark-cli profile（可选） */
+    profile?: string;
+    /** 绑定状态，默认 "ready" */
+    status?: "creating" | "ready" | "failed";
+    /** 失败时的错误信息 */
+    errorMessage?: string | null;
+}
+/**
+ * Agent Sub-session reference
+ */
+export interface AgentSessionRef {
+    nodeId: string;
+    sessionId: string;
+    status: 'active' | 'paused' | 'completed';
+}
+/**
+ * Workflow Session metadata
+ * Extends SessionMetadata with workflow-specific fields
+ */
+export interface WorkflowSessionMetadata extends SessionMetadata {
+    type: 'workflow';
+    workflowId?: string;
+    workflowName: string;
+    workflowVersion?: string;
+    status: 'running' | 'paused' | 'completed' | 'failed';
+    input?: unknown;
+    rootNodeId?: string;
+    agentSessions?: AgentSessionRef[];
+}
+/**
+ * Session message
+ */
+export interface SessionMessage {
+    id: string;
+    sessionID: string;
+    role: Role;
+    content: string;
+    timestamp: number;
+    parts?: MessagePart[];
+    /** Whether the message has been archived (compacted) */
+    isArchived?: boolean;
+    /** Timestamp when the message was archived */
+    archivedAt?: number;
+    /** Checkpoint ID this message belongs to */
+    checkpointId?: string;
+    /** Message metadata (includes checkpoint info if this is a checkpoint message) */
+    metadata?: MessageMetadata;
+}
+/**
+ * Message metadata
+ */
+export interface MessageMetadata extends Record<string, unknown> {
+    /** 消息类型标识，用于过滤和分类 */
+    type?: "tool_call" | "tool_result" | "checkpoint" | "user_intent" | "workflow.node.start" | "workflow.node.interrupt" | "workflow.node.end" | "workflow.node.resume";
+    isCheckpoint?: boolean;
+    checkpointId?: string;
+    checkpointMeta?: SessionCheckpoint;
+    /** Workflow node ID (for workflow.node.* messages) */
+    workflowNodeId?: string;
+    /** Workflow node type (for workflow.node.* messages) */
+    workflowNodeType?: string;
+    /** Agent session ID (for agent nodes in workflow) */
+    agentSessionId?: string;
+    /** User response (for workflow.node.resume messages) */
+    response?: string;
+    /** Success flag (for workflow.node.end messages) */
+    success?: boolean;
+}
+/**
+ * Message role
+ */
+export type Role = "user" | "assistant" | "system" | "tool" | "workflow.node.start" | "workflow.node.interrupt" | "workflow.node.end" | "workflow.node.resume";
+/**
+ * Message part
+ */
+export type MessagePart = SessionPart;
+/**
+ * Text part - plain text content
+ */
+export interface TextPart {
+    type: "text";
+    content: string;
+    /** If true, this part was generated by the system (e.g., auto-summary) */
+    synthetic?: boolean;
+    /** If true, this part should be ignored (e.g., replaced by reasoning) */
+    ignored?: boolean;
+}
+/**
+ * Tool call part - represents a tool invocation
+ */
+export interface ToolCallPart {
+    type: "tool-call";
+    /** AI SDK standard field name */
+    toolCallId: string;
+    toolName: string;
+    /** Tool arguments - can be string (JSON) or object */
+    arguments: string | Record<string, unknown>;
+    state: "pending" | "running";
+}
+/**
+ * Tool result part - represents the result of a tool execution
+ */
+export interface ToolResultPart {
+    type: "tool-result";
+    toolCallId: string;
+    toolName: string;
+    output: string;
+    error?: string;
+    state: "completed" | "error";
+}
+/**
+ * Reasoning part - AI thinking/thought content
+ */
+export interface ReasoningPart {
+    type: "reasoning";
+    /** Reasoning content */
+    content: string;
+    /** Reasoning type (for different models) */
+    reasoningType?: "core" | "effort" | "summary";
+    /** State */
+    state?: "thinking" | "completed";
+    /** Whether to collapse by default (like AI SDK default) */
+    isCollapsed?: boolean;
+    /** Metadata */
+    metadata?: {
+        tokenCount?: number;
+        time?: {
+            start: number;
+            end?: number;
+        };
+    };
+}
+/**
+ * File part - file attachment
+ */
+export interface FilePart {
+    type: "file";
+    mime: string;
+    url: string;
+    filename?: string;
+}
+/**
+ * Image part - multimodal image attachment
+ *
+ * Used in user messages for vision-capable LLM calls. Field shape mirrors
+ * the AI SDK v6 `ImagePart` ({ type: 'image', image: DataContent | URL })
+ * so that round-trip through `toModelMessage` / `fromModelMessage` is
+ * lossless. Stores the image data as a `data:` URL string, a remote URL
+ * string, or a `URL` object instance.
+ *
+ * @see packages/core/src/env/llm/invoke.ts convertToSDKMessages
+ *      for how LLMMessage.image parts map to the AI SDK ImagePart shape.
+ */
+export interface ImagePart {
+    type: "image";
+    /** Image data (data: URL / base64 / remote URL / URL object) */
+    image: string | URL;
+    /** Optional MIME type (e.g. "image/png") — best-effort metadata */
+    mimeType?: string;
+}
+/**
+ * Checkpoint part - compaction checkpoint marker
+ *
+ * Represents a checkpoint message in the conversation history.
+ * This is stored as a user role message with markdown content summarizing
+ * the compacted conversation segment.
+ */
+export interface CheckpointPart {
+    type: "checkpoint";
+    /** Checkpoint ID reference */
+    checkpointId: string;
+    /** Markdown content summarizing the checkpoint */
+    content: string;
+    /** Title of the checkpoint */
+    title?: string;
+    /** Process key points */
+    processKeyPoints?: string[];
+    /** Current state description */
+    currentState?: string;
+    /** Next steps */
+    nextSteps?: string[];
+    /** Number of messages that were compacted */
+    messageCountBefore?: number;
+    /** Creation timestamp */
+    createdAt?: number;
+}
+/**
+ * Union type for all Session Part types
+ */
+export type SessionPart = TextPart | ToolCallPart | ToolResultPart | ReasoningPart | FilePart | ImagePart | CheckpointPart | WorkflowNodeStartPart | WorkflowNodeInterruptPart | WorkflowNodeEndPart | WorkflowNodeResumePart;
+/**
+ * workflow.node.start 消息 part (对应 tool-call)
+ */
+export interface WorkflowNodeStartPart {
+    type: 'workflow-node-start';
+    nodeId: string;
+    nodeType: string;
+    input?: unknown;
+    startTime: number;
+    /** Agent session ID (only for agent nodes) */
+    agentSessionId?: string;
+}
+/**
+ * workflow.node.interrupt 消息 part
+ */
+export interface WorkflowNodeInterruptPart {
+    type: 'workflow-node-interrupt';
+    nodeId: string;
+    nodeType: string;
+    query: string;
+    options?: string[];
+    timestamp: number;
+    /** Agent session ID (only for agent nodes) */
+    agentSessionId?: string;
+}
+/**
+ * workflow.node.end 消息 part (对应 tool-result)
+ */
+export interface WorkflowNodeEndPart {
+    type: 'workflow-node-end';
+    nodeId: string;
+    nodeType: string;
+    output?: unknown;
+    error?: string;
+    durationMs: number;
+    /** Agent session ID (only for agent nodes) */
+    agentSessionId?: string;
+}
+/**
+ * workflow.node.resume 消息 part
+ */
+export interface WorkflowNodeResumePart {
+    type: 'workflow-node-resume';
+    nodeId: string;
+    response: string;
+    timestamp: number;
+    /** Agent session ID (only for agent nodes) */
+    agentSessionId?: string;
+}
+/**
+ * Context usage statistics
+ */
+export interface ContextUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    contextWindow?: number;
+    usagePercent?: number;
+    requestCount: number;
+    lastUpdated: number;
+}
+/**
+ * Options for creating a session
+ */
+export interface CreateSessionOptions {
+    /** Custom session ID (optional, will be generated if not provided) */
+    id?: string;
+    title?: string;
+    directory?: string;
+    /**
+     * @deprecated Use `parentSessionId` instead. Retained as alias for
+     * backward compatibility — passing `parentID` is equivalent to
+     * passing `parentSessionId` and the same value will be set on both
+     * fields of the resulting Session.
+     */
+    parentID?: string;
+    /**
+     * ID of the parent session whose execution spawned this one.
+     * Mirrored to the legacy `parentID` field on the resulting Session.
+     */
+    parentSessionId?: string | null;
+    metadata?: Record<string, unknown>;
+    hooks?: SessionHooksConfig;
+}
+/**
+ * Options for updating a session
+ */
+export interface UpdateSessionOptions {
+    title?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Options for listing sessions
+ */
+export interface ListSessionsOptions {
+    filter?: {
+        metadata?: Record<string, unknown>;
+        startTime?: number;
+        endTime?: number;
+    };
+    sort?: {
+        field: "updatedAt" | "createdAt" | "title";
+        order: "asc" | "desc";
+    };
+    offset?: number;
+    limit?: number;
+}
+/**
+ * Options for adding a message
+ */
+export interface AddMessageOptions {
+    role: Role;
+    content: string;
+    parts?: MessagePart[];
+    metadata?: MessageMetadata;
+}
+/**
+ * Options for compact operation
+ */
+export interface CompactOptions {
+    /** User-provided summary hint for checkpoint generation */
+    summary?: string;
+    /** User-provided process key points hint */
+    processKeyPoints?: string[];
+    /** User-provided current state hint */
+    currentState?: string;
+    /** User-provided next steps hint */
+    nextSteps?: string[];
+    /** Whether this is auto-triggered compact */
+    auto?: boolean;
+    /**
+     * Scenario hint for guiding checkpoint generation
+     *
+     * A natural language description that provides context about the current scenario.
+     * This helps the SummaryAgent generate more relevant checkpoints based on the specific
+     * situation. Examples:
+     * - "Task execution in progress: implementing feature X, current working directory is /path/to/project"
+     * - "Bug investigation: analyzing crash dump, current hypothesis is memory corruption"
+     * - "Code review session: reviewing PR #123, focus on security implications"
+     *
+     * When provided, this will be prepended to the system prompt to guide the checkpoint
+     * generation with scenario-specific emphasis.
+     */
+    scenarioHint?: string;
+}
+/**
+ * Result of compact operation
+ */
+export interface CompactResult {
+    checkpoint: SessionCheckpoint;
+    deletedMessageCount: number;
+    remainingMessageCount: number;
+    checkpointCount: number;
+}
+/**
+ * Preview of compact operation
+ */
+export interface CompactPreview {
+    messageCountToCompact: number;
+    estimatedCheckpointTokens: number;
+    wouldTrigger: boolean;
+}
+/**
+ * Options for getting session context
+ */
+export interface GetContextOptions {
+    /** Start from specified checkpoint */
+    fromCheckpoint?: string;
+    /** Start from latest checkpoint (default: true) */
+    fromLatestCheckpoint?: boolean;
+    /** Read full history (ignore checkpoints) */
+    fullHistory?: boolean;
+    /** Message limit */
+    messageLimit?: number;
+    /** Minimum user messages to include (ensures starting from user message boundary) */
+    minUserMessages?: number;
+    /** Include checkpoint details */
+    includeCheckpoints?: boolean;
+}
+/**
+ * Result of getting session context
+ */
+export interface GetContextResult {
+    session: Session;
+    checkpoints: SessionCheckpoint[];
+    startCheckpoint?: SessionCheckpoint;
+    messages: SessionMessage[];
+    totalMessageCount: number;
+    activeMessageCount: number;
+    archivedMessageCount: number;
+    estimatedTokens: number;
+}
+/**
+ * Options for getting messages
+ */
+export interface GetMessagesOptions {
+    /** Include archived messages */
+    includeArchived?: boolean;
+    /** From checkpoint ID */
+    fromCheckpointId?: string;
+    /** Reverse order */
+    reverse?: boolean;
+}
+/**
+ * Session hook type
+ */
+export type SessionHookType = "before.session.create" | "after.session.create" | "before.session.get" | "after.session.get" | "before.session.list" | "after.session.list" | "before.session.update" | "after.session.update" | "before.session.delete" | "after.session.delete" | "before.session.compact" | "after.session.compact" | "before.session.createCheckpoint" | "after.session.createCheckpoint" | "before.session.deleteCheckpoint" | "after.session.deleteCheckpoint";
+/**
+ * Session hook context
+ */
+export interface SessionHookContext {
+    session?: Session;
+    id?: string;
+    options?: CreateSessionOptions | UpdateSessionOptions;
+    checkpoint?: SessionCheckpoint;
+}
+/**
+ * Session hook callback
+ */
+export type SessionHookCallback = (context?: any) => Promise<void>;
+/**
+ * Session hook definition
+ */
+export interface SessionHook {
+    name: string;
+    before?: SessionHookCallback;
+    after?: SessionHookCallback;
+}
+/**
+ * Session hooks configuration
+ */
+export interface SessionHooksConfig {
+    [key: string]: SessionHook[];
+}
+/**
+ * Options for searching messages
+ */
+export interface SearchMessagesOptions {
+    /** Search query (supports AND/OR/NOT syntax) */
+    query: string;
+    /** Limit search to specific session ID */
+    sessionId?: string;
+    /** Maximum number of results per session */
+    limit?: number;
+    /** Maximum total results */
+    maxResults?: number;
+    /** Only search messages before this timestamp */
+    beforeTime?: number;
+    /** Only search messages after this timestamp */
+    afterTime?: number;
+    /** Include archived messages */
+    includeArchived?: boolean;
+    /** Include context (messages before/after matches) */
+    includeContext?: boolean;
+    /** Number of context lines before/after */
+    contextLines?: number;
+}
+/**
+ * A single message match
+ */
+export interface MessageMatch {
+    /** Message ID */
+    messageId: string;
+    /** Session ID */
+    sessionId: string;
+    /** Message role */
+    role: Role;
+    /** Message content */
+    content: string;
+    /** Message timestamp */
+    timestamp: number;
+    /** Context before the match (if enabled) */
+    contextBefore?: string;
+    /** Context after the match (if enabled) */
+    contextAfter?: string;
+    /** Match score (relevance) */
+    score?: number;
+}
+/**
+ * Search result aggregated by session
+ */
+export interface SearchResult {
+    /** Session ID */
+    sessionId: string;
+    /** Session title */
+    sessionTitle: string;
+    /** Session directory */
+    sessionDirectory: string;
+    /** Session update timestamp */
+    updatedAt: number;
+    /** Total message count in session */
+    messageCount: number;
+    /** Matching messages in this session */
+    matches: MessageMatch[];
+}
+/**
+ * Search result with metadata
+ */
+export interface SearchResultWithMeta {
+    /** Total number of matching messages */
+    totalMatches: number;
+    /** Number of sessions with matches */
+    sessionCount: number;
+    /** Results grouped by session */
+    results: SearchResult[];
+}