@ai-setting/roy-agent-core 1.0.0

package/src/env/session/types.ts

@@ -0,0 +1,742 @@
+/**
+ * @fileoverview Session Component Types
+ */
+
+import { z } from "zod";
+
+// ============================================================================
+// Config Schema
+// ============================================================================
+
+/**
+ * Session Component configuration schema
+ */
+export const SessionConfigSchema = z.object({
+  /** Default working directory */
+  defaultDirectory: z.string().default("/tmp"),
+
+  /** Default title template */
+  defaultTitleTemplate: z.string().default("Session - {date}"),
+
+  /** Maximum number of messages per session */
+  maxMessages: z.number().default(100),
+
+  /** Context compaction threshold (percentage) */
+  compactionThreshold: z.number().default(80),
+
+  /** Enable auto compaction */
+  autoCompact: z.boolean().default(true),
+
+  /** Storage configuration */
+  storage: z.object({
+    type: z.enum(["memory", "sqlite"]).default("sqlite"),
+    dbPath: z.string().optional(),
+  }).default({}),
+}).transform((config) => ({
+  ...config,
+  // Set defaultDirectory to cwd if not provided and equals default
+  defaultDirectory: config.defaultDirectory === "/tmp" ? (typeof process !== 'undefined' ? process.cwd() : "/tmp") : config.defaultDirectory,
+}));
+
+export type SessionConfig = z.infer<typeof SessionConfigSchema>;
+
+// ============================================================================
+// Checkpoint Types (new)
+// ============================================================================
+
+/**
+ * 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
+// ============================================================================
+
+/**
+ * Session entity
+ */
+export interface Session {
+  id: string;
+  title: string;
+  directory: string;
+  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>;
+}
+
+// ============================================================================
+// Workflow Session Types (new)
+// ============================================================================
+
+/**
+ * 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.call"      // Workflow node execution started
+    | "workflow.node.interrupt"  // Workflow node waiting for user input
+    | "workflow.node.result"     // Workflow node execution result
+    | "workflow.node.resume";    // Workflow node resumed after user response
+  isCheckpoint?: boolean;
+  checkpointId?: string;
+  checkpointMeta?: SessionCheckpoint;
+  
+  // Workflow-specific metadata fields
+  /** 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.result messages) */
+  success?: boolean;
+}
+
+/**
+ * Message role
+ */
+export type Role = "user" | "assistant" | "system" | "tool"
+  | "workflow.node.call"      // Workflow node execution started
+  | "workflow.node.interrupt"  // Workflow node waiting for user input
+  | "workflow.node.result"     // Workflow node execution result
+  | "workflow.node.resume";    // Workflow node resumed after user response
+
+/**
+ * Message part
+ */
+export type MessagePart = SessionPart;
+
+// ============================================================================
+// New Session Part Types (AI SDK v6 compatible)
+// ============================================================================
+
+/**
+ * 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;
+}
+
+/**
+ * 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 
+  | CheckpointPart
+  // Workflow-specific parts
+  | WorkflowNodeCallPart
+  | WorkflowNodeInterruptPart
+  | WorkflowNodeResultPart
+  | WorkflowNodeResumePart;
+
+/**
+ * workflow.node.call 消息 part (for workflow sessions)
+ */
+export interface WorkflowNodeCallPart {
+  type: 'workflow-node-call';
+  nodeId: string;
+  nodeType: string;
+  input?: unknown;
+  startTime: number;
+  /** Agent session ID (only for agent nodes) */
+  agentSessionId?: string;
+}
+
+/**
+ * workflow.node.interrupt 消息 part (for workflow sessions)
+ */
+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.result 消息 part (for workflow sessions)
+ */
+export interface WorkflowNodeResultPart {
+  type: 'workflow-node-result';
+  nodeId: string;
+  nodeType: string;
+  output?: unknown;
+  error?: string;
+  durationMs: number;
+}
+
+/**
+ * workflow.node.resume 消息 part (for workflow sessions)
+ */
+export interface WorkflowNodeResumePart {
+  type: 'workflow-node-resume';
+  response: string;
+  timestamp: number;
+}
+
+/**
+ * Context usage statistics
+ */
+export interface ContextUsage {
+  inputTokens: number;
+  outputTokens: number;
+  totalTokens: number;
+  contextWindow?: number;
+  usagePercent?: number;
+  requestCount: number;
+  lastUpdated: number;
+}
+
+// ============================================================================
+// Options
+// ============================================================================
+
+/**
+ * Options for creating a session
+ */
+export interface CreateSessionOptions {
+  /** Custom session ID (optional, will be generated if not provided) */
+  id?: string;
+  title?: string;
+  directory?: string;
+  parentID?: string;
+  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;
+}
+
+// ============================================================================
+// Compact Options & Result (new)
+// ============================================================================
+
+/**
+ * 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;
+}
+
+// ============================================================================
+// Context Reading Options (new)
+// ============================================================================
+
+/**
+ * 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;
+}
+
+// ============================================================================
+// Get Messages Options (new)
+// ============================================================================
+
+/**
+ * Options for getting messages
+ */
+export interface GetMessagesOptions {
+  /** Include archived messages */
+  includeArchived?: boolean;
+  
+  /** From checkpoint ID */
+  fromCheckpointId?: string;
+  
+  /** Reverse order */
+  reverse?: boolean;
+}
+
+// ============================================================================
+// Hooks
+// ============================================================================
+
+/**
+ * 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"           // (new)
+  | "after.session.compact"             // (new)
+  | "before.session.createCheckpoint"   // (new)
+  | "after.session.createCheckpoint"    // (new)
+  | "before.session.deleteCheckpoint"  // (new)
+  | "after.session.deleteCheckpoint";   // (new)
+
+/**
+ * Session hook context
+ */
+export interface SessionHookContext {
+  session?: Session;
+  id?: string;
+  options?: CreateSessionOptions | UpdateSessionOptions;
+  checkpoint?: SessionCheckpoint;  // [new] For checkpoint hooks
+}
+
+/**
+ * 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[];
+}
+
+// ============================================================================
+// Search Types (new)
+// ============================================================================
+
+/**
+ * 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[];
+}