hyacinth-ai 0.9.6

package/dist/tools/xref/xref-graph.js

@@ -0,0 +1,88 @@
+/**
+ * xref_graph — 可视化调用图/依赖图。
+ *
+ * 将交叉引用关系输出为：
+ *   - text:    缩进文本树（├── └── 风格）
+ *   - mermaid: Mermaid.js 流程图（可在 Markdown 中渲染）
+ *   - graphviz: Graphviz DOT 格式
+ *
+ * 需要先运行 xref_build 构建索引。
+ *
+ * 注册链：
+ *   factory.ts → new XrefGraphTool(manager) → toolRegistry.register()
+ */
+const FORMATS = ['text', 'mermaid', 'graphviz'];
+export class XrefGraphTool {
+    name = 'xref_graph';
+    description = 'Visualize the cross-reference graph as a text tree, Mermaid.js diagram, or Graphviz DOT. ' +
+        'Supports two modes:\n' +
+        '  1. Symbol-centered call graph — who calls this function, and what does it call?\n' +
+        '  2. File-centered dependency graph — what files import/depend on this file?\n\n' +
+        'Output formats:\n' +
+        '  - "text": indented tree (├── └──), readable directly in terminal\n' +
+        '  - "mermaid": Mermaid graph LR/flowchart, renderable in Markdown viewers\n' +
+        '  - "graphviz": DOT digraph format for Graphviz renderers\n\n' +
+        'Use "max_depth" to limit traversal (default: 3). ' +
+        'Use "direction" to control call graph traversal: "callers" (up), "callees" (down), or "both" (default).';
+    inputSchema = {
+        type: 'object',
+        properties: {
+            symbol: {
+                type: 'string',
+                description: 'Symbol (function/class) to center the call graph on. ' +
+                    'If provided, generates a call graph. ' +
+                    'Mutually exclusive with "file". At least one is required.',
+            },
+            file: {
+                type: 'string',
+                description: 'File path to center the dependency graph on. ' +
+                    'If provided, generates a file dependency graph. ' +
+                    'Mutually exclusive with "symbol". At least one is required.',
+            },
+            format: {
+                type: 'string',
+                enum: FORMATS,
+                description: 'Output format. Default: "mermaid" (renderable in Markdown). "text" for terminal trees. "graphviz" for DOT.',
+            },
+            max_depth: {
+                type: 'number',
+                description: 'Max traversal depth for the graph. Default: 3. WARNING: larger depth = more nodes exponentially.',
+            },
+            direction: {
+                type: 'string',
+                enum: ['callers', 'callees', 'both'],
+                description: 'For symbol call graphs: traverse callers (who calls it), callees (what it calls), or both. Default: "both".',
+            },
+        },
+        required: [],
+    };
+    manager;
+    constructor(manager) {
+        this.manager = manager;
+    }
+    async execute(args) {
+        const symbol = args.symbol;
+        const file = args.file;
+        const format = args.format ?? 'mermaid';
+        const maxDepth = args.max_depth ?? 3;
+        const direction = args.direction ?? 'both';
+        if (!symbol && !file) {
+            return 'Error: at least one of "symbol" or "file" is required.';
+        }
+        if (!FORMATS.includes(format)) {
+            return `Unknown format: "${format}". Supported: ${FORMATS.join(', ')}`;
+        }
+        if (!this.manager.isReady()) {
+            return 'Error: Xref index not built. Run xref_build first to index the project.';
+        }
+        const result = this.manager.graph({
+            format,
+            symbol,
+            file,
+            max_depth: maxDepth,
+            direction,
+        });
+        return result;
+    }
+}
+//# sourceMappingURL=xref-graph.js.map

package/dist/tools/xref/xref-query.d.ts

@@ -0,0 +1,30 @@
+/**
+ * xref_query — 查询交叉引用索引。
+ *
+ * 支持 9 种查询操作：
+ *   refs       — 查符号被哪些地方引用
+ *   defs       — 查符号的定义位置
+ *   callers    — 谁调用了该函数
+ *   callees    — 该函数调用了谁
+ *   deps       — 文件依赖了哪些模块
+ *   dependents — 哪些文件依赖了该文件
+ *   hierarchy  — 类的继承关系树
+ *   impact     — 修改文件的影响面分析（BFS）
+ *   trace      — 变量在文件内的数据流追踪
+ *
+ * 需要先运行 xref_build 构建索引。
+ *
+ * 注册链：
+ *   factory.ts → new XrefQueryTool(manager) → toolRegistry.register()
+ */
+import type { Tool } from '../interface.js';
+import type { XrefManager } from './manager.js';
+export declare class XrefQueryTool implements Tool {
+    readonly name = "xref_query";
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    private manager;
+    constructor(manager: XrefManager);
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+//# sourceMappingURL=xref-query.d.ts.map

package/dist/tools/xref/xref-query.js

@@ -0,0 +1,123 @@
+/**
+ * xref_query — 查询交叉引用索引。
+ *
+ * 支持 9 种查询操作：
+ *   refs       — 查符号被哪些地方引用
+ *   defs       — 查符号的定义位置
+ *   callers    — 谁调用了该函数
+ *   callees    — 该函数调用了谁
+ *   deps       — 文件依赖了哪些模块
+ *   dependents — 哪些文件依赖了该文件
+ *   hierarchy  — 类的继承关系树
+ *   impact     — 修改文件的影响面分析（BFS）
+ *   trace      — 变量在文件内的数据流追踪
+ *
+ * 需要先运行 xref_build 构建索引。
+ *
+ * 注册链：
+ *   factory.ts → new XrefQueryTool(manager) → toolRegistry.register()
+ */
+const ACTIONS = [
+    'refs', 'defs', 'callers', 'callees',
+    'deps', 'dependents', 'hierarchy', 'impact', 'trace',
+    'symbol_search',
+];
+export class XrefQueryTool {
+    name = 'xref_query';
+    description = 'Query the cross-reference index (built by xref_build). Supports 10 actions:\n\n' +
+        'L1 — Symbol queries:\n' +
+        '  - "refs": find all references to a symbol across the project\n' +
+        '  - "defs": find where a symbol is defined (with signature)\n' +
+        '  - "callers": who calls this function?\n' +
+        '  - "callees": what does this function call? (supports depth for call chain)\n\n' +
+        'L2 — File dependency queries:\n' +
+        '  - "deps": what modules does this file import?\n' +
+        '  - "dependents": what files import this file?\n' +
+        '  - "symbol_search": which files import a given symbol? (across all imports)\n\n' +
+        'L3 — Structural queries:\n' +
+        '  - "hierarchy": class inheritance tree (parents & children)\n' +
+        '  - "impact": BFS — what files are affected if I change X? (supports depth)\n' +
+        '  - "trace": data flow for a variable within a file (declaration, assignments, reads)\n\n' +
+        'IMPORTANT: Run xref_build first before querying. ' +
+        'Use "depth" to control traversal depth (default: 1-2). ' +
+        'For callees/impact, larger depth = exponential growth — start small.';
+    inputSchema = {
+        type: 'object',
+        properties: {
+            action: {
+                type: 'string',
+                enum: ACTIONS,
+                description: 'Query action:\n' +
+                    'L1: "refs" | "defs" | "callers" | "callees"\n' +
+                    'L2: "deps" | "dependents"\n' +
+                    'L3: "hierarchy" | "impact" | "trace"',
+            },
+            symbol: {
+                type: 'string',
+                description: 'Symbol name (function, class, variable, etc.). ' +
+                    'Required for: refs, defs, callers, callees, hierarchy, trace. ' +
+                    'Optional for: impact (filters by symbol).',
+            },
+            file: {
+                type: 'string',
+                description: 'File path (relative to project root or absolute). ' +
+                    'Required for: deps, dependents, impact, trace. ' +
+                    'Optional for: refs, defs, callers, callees (narrows search scope).',
+            },
+            depth: {
+                type: 'number',
+                description: 'Max traversal depth. Default: 1-2 depending on action. ' +
+                    'WARNING: larger depth = more results exponentially. ' +
+                    'Applies to: callees, impact.',
+            },
+            kind: {
+                type: 'string',
+                enum: ['function', 'method', 'arrow', 'class', 'interface', 'type', 'enum', 'variable', 'parameter', 'property'],
+                description: 'Filter symbols by kind. Useful with "defs" when a name is overloaded.',
+            },
+            format: {
+                type: 'string',
+                enum: ['text', 'json'],
+                description: 'Output format. Default: "text" (human-readable). Use "json" for structured data.',
+            },
+        },
+        required: ['action'],
+    };
+    manager;
+    constructor(manager) {
+        this.manager = manager;
+    }
+    async execute(args) {
+        const action = args.action;
+        const symbol = args.symbol;
+        const file = args.file;
+        const depth = args.depth;
+        const kind = args.kind;
+        const format = args.format ?? 'text';
+        if (!ACTIONS.includes(action)) {
+            return `Unknown action: "${action}". Supported: ${ACTIONS.join(', ')}`;
+        }
+        // 验证必需参数
+        const requiresSymbol = ['refs', 'defs', 'callers', 'callees', 'hierarchy', 'trace'];
+        const requiresFile = ['deps', 'dependents', 'impact', 'trace'];
+        if (requiresSymbol.includes(action) && !symbol) {
+            return `Error: "symbol" is required for action "${action}".`;
+        }
+        if (requiresFile.includes(action) && !file) {
+            return `Error: "file" is required for action "${action}".`;
+        }
+        if (!this.manager.isReady()) {
+            return 'Error: Xref index not built. Run xref_build first to index the project.';
+        }
+        const result = this.manager.query({
+            action,
+            symbol,
+            file,
+            depth,
+            kind,
+            format: format,
+        });
+        return result;
+    }
+}
+//# sourceMappingURL=xref-query.js.map

package/dist/types.d.ts

@@ -0,0 +1,217 @@
+export type MessageRole = 'system' | 'user' | 'assistant';
+export interface TextContent {
+    type: 'text';
+    text: string;
+    cache_control?: {
+        type: 'ephemeral';
+    };
+}
+export interface ThinkingContent {
+    type: 'thinking';
+    thinking: string;
+}
+export interface ToolUseContent {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface ToolResultContent {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+}
+export type ImageSource = {
+    type: 'base64';
+    media_type: string;
+    data: string;
+} | {
+    type: 'url';
+    url: string;
+};
+export interface ImageContent {
+    type: 'image';
+    source: ImageSource;
+    cache_control?: {
+        type: 'ephemeral';
+    };
+}
+export type MessageContent = TextContent | ThinkingContent | ToolUseContent | ToolResultContent | ImageContent;
+export interface Message {
+    role: MessageRole;
+    content: MessageContent | MessageContent[];
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface ToolResult {
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+}
+export type StreamEventType = 'TEXT' | 'THINKING' | 'TOOL_USE' | 'IMAGE' | 'USAGE' | 'STOP';
+export type StreamEvent = {
+    type: 'TEXT';
+    content: string;
+} | {
+    type: 'THINKING';
+    content: string;
+} | {
+    type: 'TOOL_USE';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'IMAGE';
+    source: ImageSource;
+} | {
+    type: 'USAGE';
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cache_hit_tokens?: number;
+    cache_miss_tokens?: number;
+} | {
+    type: 'STOP';
+    reason: string;
+};
+export interface Session {
+    id: string;
+    projectKey: string;
+    createdAt: string;
+    updatedAt: string;
+    type?: 'normal' | 'precise' | 'companion';
+    /** 创建此 session 的渠道：'webui' | 'tui' | 'feishu' 等 */
+    channel?: string;
+}
+export interface SessionStats {
+    input_tokens: number;
+    output_tokens: number;
+    turn_count: number;
+    compact_count: number;
+    current_context_tokens: number;
+    /** 每轮缓存命中记录（用于分析前缀缓存稳定性） */
+    cache_turns?: Array<{
+        turn: number;
+        timestamp: string;
+        inputTokens: number;
+        outputTokens: number;
+        hitTokens: number;
+        missTokens: number;
+        hitRate: number;
+    }>;
+}
+export type ProviderType = 'anthropic' | 'openai' | 'deepseek' | 'local' | 'llamacpp' | 'ollama' | 'groq' | 'xai' | 'mistral' | 'openrouter' | 'gemini' | 'moonshot' | 'qwen' | 'zhipu' | 'minimax' | 'mimo';
+export interface ProviderConfig {
+    type: ProviderType;
+    apiKey: string;
+    baseUrl?: string;
+    model: string;
+    /** 单次请求最大输出 token 数。不传则从模型目录/Provider 配置中自动获取。 */
+    maxOutputTokens?: number;
+    /** DeepSeek KVCache 隔离 ID。不同角色应使用不同的 userId 避免缓存互相污染。 */
+    userId?: string;
+}
+export interface FilePosition {
+    file: string;
+    line: number;
+    column?: number;
+}
+export interface SymbolReference {
+    symbol: string;
+    kind: 'variable' | 'function' | 'class' | 'import' | 'type';
+    definedAt: FilePosition;
+    references: FilePosition[];
+}
+export interface ChangeImpact {
+    modifiedSymbols: SymbolReference[];
+    affectedFiles: string[];
+    affectedReferences: FilePosition[];
+    riskLevel: 'low' | 'medium' | 'high';
+    recommendation: string;
+}
+export interface MCPConfig {
+    /** MCP Server 唯一名称 */
+    name: string;
+    /** stdio 传输：启动子进程的命令 */
+    command?: string;
+    /** stdio 传输：命令参数 */
+    args?: string[];
+    /** HTTP SSE 传输：Server URL */
+    url?: string;
+    /** 环境变量 */
+    env?: Record<string, string>;
+    /** SSE 认证请求头 */
+    headers?: Record<string, string>;
+    /** 包类型："npm" | "python"，指定则需要框架统一安装 */
+    packageType?: 'npm' | 'python';
+    /** npm/python 包名 */
+    package?: string;
+    /** 目标版本，省略则用 latest */
+    packageVersion?: string;
+    /** 连接超时（毫秒），默认 30000 */
+    connectTimeout?: number;
+    /** 工具调用超时（毫秒），默认 60000 */
+    callTimeout?: number;
+}
+export interface SkillDefinition {
+    /** 唯一名称 */
+    name: string;
+    /** 简短描述（用于索引显示） */
+    description: string;
+    /** 提示词模板（支持 {{variable}} 占位符） */
+    promptTemplate: string;
+    /** 关联的工具名称列表 */
+    relatedTools: string[];
+    /** 来源：内置 / 文件加载 / 插件注册 */
+    source: 'builtin' | 'file' | 'plugin';
+}
+export type CollaborationMode = 'delegate' | 'adversarial' | 'parallel';
+export interface AgentDefinition {
+    /** 唯一标识符 */
+    name: string;
+    /** 运行时实例 ID（支持同一 name 的多实例分身，自动生成） */
+    instanceId?: string;
+    /** 角色描述，供主 Agent 判断何时使用该子 Agent */
+    description: string;
+    /** 系统提示词模板（支持 {{task}} 占位符） */
+    systemPrompt: string;
+    /** 工具白名单（空数组表示允许所有工具） */
+    allowedTools: string[];
+    /** 可选的模型偏好 */
+    modelPreference?: string;
+    /** 该子 Agent 的最大执行轮次 */
+    maxTurns: number;
+    /** 协作模式 */
+    collaborationMode: CollaborationMode;
+    /** 输出格式（默认 text） */
+    outputFormat?: 'text' | 'json';
+    /** JSON 模式的输出 schema */
+    outputSchema?: Record<string, unknown>;
+    /** 子 Agent 会话 TTL（分钟），超时未调用则自动清理重建。默认 10 */
+    sessionTtlMinutes?: number;
+}
+export interface AgentResult {
+    /** 子 Agent 名称 */
+    agentName: string;
+    /** 分配的任务 */
+    task: string;
+    /** 执行状态 */
+    status: 'completed' | 'max_turns_reached' | 'error';
+    /** 执行摘要 */
+    summary: string;
+    /** 实际执行轮次 */
+    turns: number;
+    /** 修改的文件列表 */
+    filesModified: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/ui/assistant-message.d.ts

@@ -0,0 +1,7 @@
+import { Container } from '@earendil-works/pi-tui';
+export declare class AssistantMessageComponent extends Container {
+    private body;
+    constructor(text: string);
+    setText(text: string): void;
+}
+//# sourceMappingURL=assistant-message.d.ts.map

package/dist/ui/assistant-message.js

@@ -0,0 +1,18 @@
+import { Container, Spacer } from '@earendil-works/pi-tui';
+import { markdownTheme, theme } from './theme.js';
+import { HyperlinkMarkdown } from './hyperlink-markdown.js';
+export class AssistantMessageComponent extends Container {
+    body;
+    constructor(text) {
+        super();
+        this.body = new HyperlinkMarkdown(text, 0, 0, markdownTheme, {
+            color: (line) => theme.assistantText(line),
+        });
+        this.addChild(new Spacer(1));
+        this.addChild(this.body);
+    }
+    setText(text) {
+        this.body.setText(text);
+    }
+}
+//# sourceMappingURL=assistant-message.js.map

package/dist/ui/chat-log.d.ts

@@ -0,0 +1,52 @@
+import { Container } from '@earendil-works/pi-tui';
+import { AssistantMessageComponent } from './assistant-message.js';
+import { ToolExecutionComponent } from './tool-execution.js';
+import { type DiffLineItem } from './diff-component.js';
+export declare class ChatLog extends Container {
+    private readonly maxComponents;
+    private toolById;
+    private streamingRuns;
+    private toolsExpanded;
+    private repeatableSystemMessage;
+    private _scrollOffset;
+    private _viewportHeight;
+    private _pinnedToBottom;
+    private _unreadCount;
+    constructor(maxComponents?: number);
+    private dropComponentReferences;
+    private pruneOverflow;
+    private append;
+    private appendNonSystem;
+    private formatRepeatedSystemText;
+    private createSystemMessage;
+    addSystem(text: string, opts?: {
+        coalesceConsecutive?: boolean;
+    }): void;
+    addUser(text: string): void;
+    private resolveRunId;
+    startAssistant(text: string, runId?: string): AssistantMessageComponent;
+    updateAssistant(text: string, runId?: string): void;
+    finalizeAssistant(text: string, runId?: string): void;
+    dropAssistant(runId?: string): void;
+    startTool(toolCallId: string, toolName: string, args: unknown): ToolExecutionComponent;
+    updateToolArgs(toolCallId: string, args: unknown): void;
+    updateToolResult(toolCallId: string, result: unknown, opts?: {
+        isError?: boolean;
+        partial?: boolean;
+    }): void;
+    showDiff(_toolId: string, filePath: string, diffLines: DiffLineItem[]): void;
+    setToolsExpanded(expanded: boolean): void;
+    toggleToolsExpanded(): boolean;
+    getToolsExpanded(): boolean;
+    clearAll(): void;
+    getContentLines(): string[];
+    getLineCount(): number;
+    setViewportHeight(height: number): void;
+    scrollToLine(line: number): void;
+    /** Pin to bottom (called on End key or user requesting bottom) */
+    pinToBottom(): void;
+    get isPinnedToBottom(): boolean;
+    get unreadCount(): number;
+    get scrollOffset(): number;
+}
+//# sourceMappingURL=chat-log.d.ts.map