@ai-setting/roy-agent-cli 1.3.15 → 1.3.17

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

@@ -0,0 +1,613 @@
+/**
+ * @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;
+    }, {
+        type?: "memory" | "sqlite";
+        dbPath?: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    compactionThreshold?: number;
+    defaultDirectory?: string;
+    defaultTitleTemplate?: string;
+    maxMessages?: number;
+    autoCompact?: boolean;
+    storage?: {
+        type?: "memory" | "sqlite";
+        dbPath?: string;
+    };
+}, {
+    compactionThreshold?: number;
+    defaultDirectory?: string;
+    defaultTitleTemplate?: string;
+    maxMessages?: number;
+    autoCompact?: boolean;
+    storage?: {
+        type?: "memory" | "sqlite";
+        dbPath?: string;
+    };
+}>, {
+    defaultDirectory: string;
+    compactionThreshold?: number;
+    defaultTitleTemplate?: string;
+    maxMessages?: number;
+    autoCompact?: boolean;
+    storage?: {
+        type?: "memory" | "sqlite";
+        dbPath?: string;
+    };
+}, {
+    compactionThreshold?: number;
+    defaultDirectory?: string;
+    defaultTitleTemplate?: string;
+    maxMessages?: number;
+    autoCompact?: boolean;
+    storage?: {
+        type?: "memory" | "sqlite";
+        dbPath?: string;
+    };
+}>;
+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;
+    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>;
+}
+/**
+ * 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.interrupt" | "workflow.node.result" | "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.result messages) */
+    success?: boolean;
+}
+/**
+ * Message role
+ */
+export type Role = "user" | "assistant" | "system" | "tool" | "workflow.node.call" | "workflow.node.interrupt" | "workflow.node.result" | "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;
+}
+/**
+ * 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 | 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 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;
+}
+/**
+ * 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[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/src/env/session/types.js

@@ -0,0 +1,32 @@
+/**
+ * @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,
+}));
+//# sourceMappingURL=types.js.map

package/dist/core/src/env/skill/config.d.ts

@@ -0,0 +1,14 @@
+import { type SkillConfig } from "./types";
+/**
+ * 默认配置
+ */
+export declare const DEFAULT_SKILL_CONFIG: SkillConfig;
+/**
+ * 优先级映射（后面的优先级更高）
+ */
+export declare const SOURCE_PRIORITY: Record<string, number>;
+/**
+ * 获取来源优先级
+ */
+export declare function getSourcePriority(source: string): number;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/src/env/skill/config.js

@@ -0,0 +1,36 @@
+import path from "path";
+import os from "os";
+/**
+ * 默认配置
+ */
+export const DEFAULT_SKILL_CONFIG = {
+    skillPaths: [
+        // 用户路径 (~/.config/roy-agent/skills/)
+        {
+            type: "user",
+            path: path.join(os.homedir(), ".config", "roy-agent", "skills"),
+        },
+        // 项目路径 (.roy/skills/)
+        {
+            type: "project",
+            path: ".roy/skills",
+        },
+    ],
+    recursive: true,
+    cacheEnabled: true,
+};
+/**
+ * 优先级映射（后面的优先级更高）
+ */
+export const SOURCE_PRIORITY = {
+    "built-in": 0,
+    "user": 1,
+    "project": 2,
+};
+/**
+ * 获取来源优先级
+ */
+export function getSourcePriority(source) {
+    return SOURCE_PRIORITY[source] ?? 0;
+}
+//# sourceMappingURL=config.js.map

package/dist/core/src/env/skill/index.d.ts

@@ -0,0 +1,7 @@
+export { SkillComponent } from "./skill-component";
+export * from "./types";
+export * from "./config";
+export * from "./parser";
+export * from "./scanner";
+export * from "./tool";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/src/env/skill/index.js

@@ -0,0 +1,7 @@
+export { SkillComponent } from "./skill-component.js";
+export * from "./types.js";
+export * from "./config.js";
+export * from "./parser.js";
+export * from "./scanner.js";
+export * from "./tool/index.js";
+//# sourceMappingURL=index.js.map