hyacinth-ai 0.9.6

package/dist/orchestrator/plan-store.d.ts

@@ -0,0 +1,81 @@
+/** Status of a plan step */
+export type PlanStepStatus = 'pending' | 'in_progress' | 'done' | 'skipped';
+/** Status of the overall plan */
+export type PlanStatus = 'active' | 'completed' | 'abandoned';
+/** A single step in the execution plan */
+export interface PlanStep {
+    id: string;
+    description: string;
+    selectedTools: string[];
+    status: PlanStepStatus;
+    result?: string;
+    assignedAgent?: string;
+    agentResult?: string;
+}
+/** The execution plan */
+export interface Plan {
+    id: string;
+    userGoal: string;
+    steps: PlanStep[];
+    selectedTools: string[];
+    estimatedTurns: number;
+    reasoning: string;
+    createdAt: string;
+    updatedAt: string;
+    status: PlanStatus;
+}
+/**
+ * Persists Plan objects to a JSONL file in the session directory.
+ * Each write appends a new line; the latest active entry is the current state.
+ */
+export declare class PlanStore {
+    /**
+     * Create a new plan and persist it.
+     * Writes a line to {sessionDir}/plan.jsonl
+     */
+    create(sessionDir: string, plan: Plan): Promise<void>;
+    /**
+     * Update an existing plan (append updated version to JSONL).
+     * The latest entry in the file is the current state.
+     */
+    update(sessionDir: string, plan: Plan): Promise<void>;
+    /**
+     * Read the latest plan from the session directory.
+     * Returns undefined if no plan exists.
+     */
+    readLatest(sessionDir: string): Promise<Plan | undefined>;
+    /**
+     * Update plan progress based on tool calls made in the current turn.
+     * Returns the updated Plan.
+     *
+     * Algorithm:
+     * 1. Find the first step with status 'in_progress' — if found, check if any
+     *    of its selectedTools were called this turn. If yes, mark it as 'done'
+     *    and move to the next pending step.
+     * 2. If no step is 'in_progress', find the first 'pending' step whose
+     *    selectedTools overlap with the tools called this turn, and mark it as
+     *    'in_progress'.
+     * 3. If ALL steps are 'done' or 'skipped', mark the Plan's status as
+     *    'completed'.
+     */
+    updateProgress(sessionDir: string, toolCallsThisTurn: string[]): Promise<Plan | undefined>;
+}
+/**
+ * Format a Plan as human-readable text for injection into Zone 3.
+ */
+export declare function formatPlanAsText(plan: Plan): string;
+/**
+ * Create a new Plan object with generated id and timestamps.
+ */
+export declare function createPlan(params: {
+    userGoal: string;
+    steps: Array<{
+        description: string;
+        selectedTools: string[];
+        assignedAgent?: string;
+    }>;
+    selectedTools: string[];
+    estimatedTurns: number;
+    reasoning: string;
+}): Plan;
+//# sourceMappingURL=plan-store.d.ts.map

package/dist/orchestrator/plan-store.js

@@ -0,0 +1,167 @@
+import { appendFile, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// PlanStore
+// ---------------------------------------------------------------------------
+/**
+ * Persists Plan objects to a JSONL file in the session directory.
+ * Each write appends a new line; the latest active entry is the current state.
+ */
+export class PlanStore {
+    /**
+     * Create a new plan and persist it.
+     * Writes a line to {sessionDir}/plan.jsonl
+     */
+    async create(sessionDir, plan) {
+        const filePath = join(sessionDir, 'plan.jsonl');
+        await appendFile(filePath, JSON.stringify(plan) + '\n', 'utf-8');
+    }
+    /**
+     * Update an existing plan (append updated version to JSONL).
+     * The latest entry in the file is the current state.
+     */
+    async update(sessionDir, plan) {
+        const updated = {
+            ...plan,
+            updatedAt: new Date().toISOString(),
+        };
+        const filePath = join(sessionDir, 'plan.jsonl');
+        await appendFile(filePath, JSON.stringify(updated) + '\n', 'utf-8');
+    }
+    /**
+     * Read the latest plan from the session directory.
+     * Returns undefined if no plan exists.
+     */
+    async readLatest(sessionDir) {
+        const filePath = join(sessionDir, 'plan.jsonl');
+        let content;
+        try {
+            content = await readFile(filePath, 'utf-8');
+        }
+        catch {
+            return undefined;
+        }
+        const lines = content
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        if (lines.length === 0)
+            return undefined;
+        // Parse all lines and return the last one with status 'active'
+        let latestActive;
+        for (const line of lines) {
+            try {
+                const plan = JSON.parse(line);
+                if (plan.status === 'active') {
+                    latestActive = plan;
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        return latestActive;
+    }
+    /**
+     * Update plan progress based on tool calls made in the current turn.
+     * Returns the updated Plan.
+     *
+     * Algorithm:
+     * 1. Find the first step with status 'in_progress' — if found, check if any
+     *    of its selectedTools were called this turn. If yes, mark it as 'done'
+     *    and move to the next pending step.
+     * 2. If no step is 'in_progress', find the first 'pending' step whose
+     *    selectedTools overlap with the tools called this turn, and mark it as
+     *    'in_progress'.
+     * 3. If ALL steps are 'done' or 'skipped', mark the Plan's status as
+     *    'completed'.
+     */
+    async updateProgress(sessionDir, toolCallsThisTurn) {
+        const plan = await this.readLatest(sessionDir);
+        if (!plan || plan.status !== 'active')
+            return undefined;
+        if (toolCallsThisTurn.length === 0)
+            return plan;
+        const toolSet = new Set(toolCallsThisTurn);
+        const steps = plan.steps.map((s) => ({ ...s })); // shallow clone steps
+        // 1. Check for in_progress step
+        const inProgressIdx = steps.findIndex((s) => s.status === 'in_progress');
+        if (inProgressIdx !== -1) {
+            const step = steps[inProgressIdx];
+            const hasOverlap = step.selectedTools.some((t) => toolSet.has(t));
+            if (hasOverlap) {
+                step.status = 'done';
+                // Move to next pending step whose tools overlap
+                const nextIdx = steps.findIndex((s, i) => i > inProgressIdx && s.status === 'pending' && s.selectedTools.some((t) => toolSet.has(t)));
+                if (nextIdx !== -1) {
+                    steps[nextIdx].status = 'in_progress';
+                }
+            }
+        }
+        else {
+            // 2. No in_progress step — find first pending step with tool overlap
+            const pendingIdx = steps.findIndex((s) => s.status === 'pending' && s.selectedTools.some((t) => toolSet.has(t)));
+            if (pendingIdx !== -1) {
+                steps[pendingIdx].status = 'in_progress';
+            }
+        }
+        // 3. Check if all steps are done or skipped
+        const allDone = steps.every((s) => s.status === 'done' || s.status === 'skipped');
+        const updatedPlan = {
+            ...plan,
+            steps,
+            status: allDone ? 'completed' : 'active',
+            updatedAt: new Date().toISOString(),
+        };
+        await this.update(sessionDir, updatedPlan);
+        return updatedPlan;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helper: formatPlanAsText
+// ---------------------------------------------------------------------------
+/**
+ * Format a Plan as human-readable text for injection into Zone 3.
+ */
+export function formatPlanAsText(plan) {
+    const stepsText = plan.steps
+        .map((step, i) => {
+        const statusIcon = step.status === 'done'
+            ? '\u2713'
+            : step.status === 'in_progress'
+                ? '\u2192'
+                : step.status === 'skipped'
+                    ? '\u2205'
+                    : '\u25CB';
+        return `${statusIcon} Step ${i + 1}: ${step.description} [${step.selectedTools.join(', ')}]${step.assignedAgent ? ` → @${step.assignedAgent}` : ''}${step.result ? `\n  Result: ${step.result}` : ''}${step.agentResult ? `\n  Agent Result: ${step.agentResult}` : ''}`;
+    })
+        .join('\n');
+    return `Execution Plan: ${plan.userGoal}\nReasoning: ${plan.reasoning}\nEstimated Turns: ${plan.estimatedTurns}\n\nSteps:\n${stepsText}`;
+}
+// ---------------------------------------------------------------------------
+// Helper: createPlan
+// ---------------------------------------------------------------------------
+/**
+ * Create a new Plan object with generated id and timestamps.
+ */
+export function createPlan(params) {
+    const now = new Date().toISOString();
+    return {
+        id: Date.now().toString(36) + Math.random().toString(36).slice(2),
+        userGoal: params.userGoal,
+        steps: params.steps.map((s, i) => ({
+            id: `step_${i + 1}`,
+            description: s.description,
+            selectedTools: s.selectedTools,
+            status: 'pending',
+            ...(s.assignedAgent ? { assignedAgent: s.assignedAgent } : {}),
+        })),
+        selectedTools: params.selectedTools,
+        estimatedTurns: params.estimatedTurns,
+        reasoning: params.reasoning,
+        createdAt: now,
+        updatedAt: now,
+        status: 'active',
+    };
+}
+//# sourceMappingURL=plan-store.js.map

package/dist/orchestrator/planner.d.ts

@@ -0,0 +1,20 @@
+import type { Provider } from '../provider/interface.js';
+import type { Plan } from './plan-store.js';
+import type { ModelRouter } from '../provider/model-router.js';
+import { PlanStore } from './plan-store.js';
+/**
+ * LLMOrchestrator — 编排器骨架。
+ *
+ * 注意: assess/plan LLM 编排功能已在 v2026-06-07 移除（由工具包系统取代）。
+ * 此类保留作为 Provider 切换和计划进度追踪的挂载点。
+ */
+export declare class LLMOrchestrator {
+    private provider;
+    private planStore;
+    private sessionDir;
+    private modelRouter?;
+    constructor(provider: Provider, planStore: PlanStore, sessionDir: string, modelRouter?: ModelRouter);
+    setProvider(provider: Provider): void;
+    updatePlanProgress(plan: Plan, toolName: string): Plan;
+}
+//# sourceMappingURL=planner.d.ts.map

package/dist/orchestrator/planner.js

@@ -0,0 +1,34 @@
+/**
+ * LLMOrchestrator — 编排器骨架。
+ *
+ * 注意: assess/plan LLM 编排功能已在 v2026-06-07 移除（由工具包系统取代）。
+ * 此类保留作为 Provider 切换和计划进度追踪的挂载点。
+ */
+export class LLMOrchestrator {
+    provider;
+    planStore;
+    sessionDir;
+    modelRouter;
+    constructor(provider, planStore, sessionDir, modelRouter) {
+        this.provider = provider;
+        this.planStore = planStore;
+        this.sessionDir = sessionDir;
+        this.modelRouter = modelRouter;
+    }
+    setProvider(provider) {
+        this.provider = provider;
+        this.modelRouter?.setMainProvider(provider);
+    }
+    updatePlanProgress(plan, toolName) {
+        for (const step of plan.steps) {
+            if (step.status !== 'pending' && step.status !== 'in_progress')
+                continue;
+            if (step.selectedTools.includes(toolName)) {
+                step.status = 'completed';
+                break;
+            }
+        }
+        return plan;
+    }
+}
+//# sourceMappingURL=planner.js.map

package/dist/parser/index.d.ts

@@ -0,0 +1,2 @@
+export { OutputRouter } from './router.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/parser/index.js

@@ -0,0 +1,2 @@
+export { OutputRouter } from './router.js';
+//# sourceMappingURL=index.js.map

package/dist/parser/router.d.ts

@@ -0,0 +1,30 @@
+import type { StreamEvent } from '../types.js';
+/**
+ * 根据 StreamEvent 类型路由到不同的处理器。
+ *
+ * 使用方式：
+ * ```ts
+ * const router = new OutputRouter();
+ * router.onText = (content) => process.stdout.write(content);
+ * router.onThinking = (content) => logger.debug(content);
+ * router.onToolUse = (id, name, input) => executeTool(id, name, input);
+ * router.onUsage = (input, output) => trackUsage(input, output);
+ * router.onStop = (reason) => handleStop(reason);
+ *
+ * // 与 parser 配合使用
+ * await parseAnthropicStream(stream, (event) => router.route(event));
+ * ```
+ */
+export declare class OutputRouter {
+    onText: ((content: string) => void) | null;
+    onThinking: ((content: string) => void) | null;
+    onToolUse: ((id: string, name: string, input: Record<string, unknown>) => void) | null;
+    onUsage: ((inputTokens: number, outputTokens: number, cacheHitTokens?: number, cacheMissTokens?: number, cacheReadInputTokens?: number, cacheCreationInputTokens?: number) => void) | null;
+    onStop: ((reason: string) => void) | null;
+    /**
+     * 将 StreamEvent 路由到对应的处理器回调。
+     * 如果某个事件类型没有注册处理器，则静默忽略。
+     */
+    route(event: StreamEvent): void;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/parser/router.js

@@ -0,0 +1,61 @@
+/**
+ * 根据 StreamEvent 类型路由到不同的处理器。
+ *
+ * 使用方式：
+ * ```ts
+ * const router = new OutputRouter();
+ * router.onText = (content) => process.stdout.write(content);
+ * router.onThinking = (content) => logger.debug(content);
+ * router.onToolUse = (id, name, input) => executeTool(id, name, input);
+ * router.onUsage = (input, output) => trackUsage(input, output);
+ * router.onStop = (reason) => handleStop(reason);
+ *
+ * // 与 parser 配合使用
+ * await parseAnthropicStream(stream, (event) => router.route(event));
+ * ```
+ */
+export class OutputRouter {
+    onText = null;
+    onThinking = null;
+    onToolUse = null;
+    onUsage = null;
+    onStop = null;
+    /**
+     * 将 StreamEvent 路由到对应的处理器回调。
+     * 如果某个事件类型没有注册处理器，则静默忽略。
+     */
+    route(event) {
+        switch (event.type) {
+            case 'TEXT': {
+                this.onText?.(event.content);
+                break;
+            }
+            case 'THINKING': {
+                this.onThinking?.(event.content);
+                break;
+            }
+            case 'TOOL_USE': {
+                this.onToolUse?.(event.id, event.name, event.input);
+                break;
+            }
+            case 'USAGE': {
+                this.onUsage?.(event.input_tokens, event.output_tokens, event.cache_hit_tokens, event.cache_miss_tokens, event.cache_read_input_tokens, event.cache_creation_input_tokens);
+                break;
+            }
+            case 'STOP': {
+                this.onStop?.(event.reason);
+                break;
+            }
+            case 'IMAGE': {
+                // 模型生成的图片 — 后续由 loop.ts 写入 responseMessages
+                break;
+            }
+            default: {
+                // 类型安全：确保所有 StreamEventType 都已处理
+                const _exhaustive = event;
+                break;
+            }
+        }
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/plugins/api.d.ts

@@ -0,0 +1,39 @@
+import type { ToolRegistry } from '../tools/registry.js';
+import type { SkillRegistry } from '../skills/registry.js';
+import type { MCPConfig } from '../types.js';
+import type { ContextSource } from '../context/interface.js';
+import type { ContextComposer } from '../context/interface.js';
+import type { ChannelHandler, ChannelConfig } from '../channels/interface.js';
+import type { PluginApi } from './types.js';
+/** PluginApi 构造参数 */
+export interface PluginApiOptions {
+    pluginId: string;
+    toolRegistry: ToolRegistry;
+    skillRegistry: SkillRegistry;
+    contextComposer: ContextComposer & {
+        registerSource?: (source: ContextSource) => void;
+        unregisterSource?: (name: string) => void;
+    };
+    pluginConfig: Record<string, unknown>;
+    onMcpServerRegister: (pluginId: string, config: MCPConfig) => void;
+    /** 渠道注册回调 → ChannelManager.register() */
+    onChannelRegister: (handler: ChannelHandler, config?: ChannelConfig) => void;
+    /** MCP Server 注册队列，用于 unregister */
+    pendingMcpConfigs?: Array<{
+        pluginId: string;
+        config: MCPConfig;
+    }>;
+    /** 注册追踪回调（供 PluginManager 追踪插件注册项） */
+    onToolRegister?: (name: string) => void;
+    onSkillRegister?: (name: string) => void;
+    onContextSourceRegister?: (name: string) => void;
+    onMcpServerUnregister?: (name: string) => void;
+}
+/**
+ * 创建 PluginApi 实例
+ *
+ * 每个插件在 register() 时获得一个独立的 PluginApi，
+ * 其操作会直接作用于宿主系统的各注册表。
+ */
+export declare function createPluginApi(options: PluginApiOptions): PluginApi;
+//# sourceMappingURL=api.d.ts.map

package/dist/plugins/api.js

@@ -0,0 +1,85 @@
+import { createLogger } from '../logging/logger.js';
+/**
+ * 创建 PluginApi 实例
+ *
+ * 每个插件在 register() 时获得一个独立的 PluginApi，
+ * 其操作会直接作用于宿主系统的各注册表。
+ */
+export function createPluginApi(options) {
+    const { pluginId, toolRegistry, skillRegistry, contextComposer, pluginConfig, onMcpServerRegister, onChannelRegister, pendingMcpConfigs, onToolRegister, onSkillRegister, onContextSourceRegister, onMcpServerUnregister, } = options;
+    const pluginLogger = createLogger(`plugin:${pluginId}`);
+    const logger = {
+        info: (msg, ...args) => pluginLogger.info(msg, { args }),
+        warn: (msg, ...args) => pluginLogger.warn(msg, { args }),
+        error: (msg, ...args) => pluginLogger.error(msg, undefined, { args }),
+        debug: (msg, ...args) => {
+            if (process.env.DEBUG_PLUGIN) {
+                pluginLogger.debug(msg, { args });
+            }
+        },
+    };
+    const api = {
+        pluginId,
+        logger,
+        registerTool(tool) {
+            toolRegistry.register(tool);
+            onToolRegister?.(tool.name);
+            logger.debug(`registered tool: ${tool.name}`);
+        },
+        registerSkill(skill) {
+            skillRegistry.register(skill);
+            onSkillRegister?.(skill.name);
+            logger.debug(`registered skill: ${skill.name}`);
+        },
+        registerContextSource(source) {
+            if (contextComposer.registerSource) {
+                contextComposer.registerSource(source);
+                onContextSourceRegister?.(source.name);
+                logger.debug(`registered context source: ${source.name}`);
+            }
+            else {
+                logger.warn(`ContextComposer does not support registerSource; cannot register "${source.name}"`);
+            }
+        },
+        registerMcpServer(config) {
+            onMcpServerRegister(pluginId, config);
+            logger.debug(`registered MCP server config: ${config.name}`);
+        },
+        registerChannel(handler, config) {
+            onChannelRegister(handler, config);
+            logger.debug(`registered channel: ${handler.id} (${handler.name})`);
+        },
+        unregisterTool(name) {
+            toolRegistry.unregister(name);
+            logger.debug(`unregistered tool: ${name}`);
+        },
+        unregisterSkill(name) {
+            skillRegistry.unregister(name);
+            logger.debug(`unregistered skill: ${name}`);
+        },
+        unregisterMcpServer(name) {
+            onMcpServerUnregister?.(name);
+            // Remove from pendingMcpConfigs if provided
+            if (pendingMcpConfigs) {
+                const idx = pendingMcpConfigs.findIndex((c) => c.pluginId === pluginId && c.config.name === name);
+                if (idx >= 0)
+                    pendingMcpConfigs.splice(idx, 1);
+            }
+            logger.debug(`unregistered MCP server: ${name}`);
+        },
+        unregisterContextSource(name) {
+            if (contextComposer.unregisterSource) {
+                contextComposer.unregisterSource(name);
+                logger.debug(`unregistered context source: ${name}`);
+            }
+            else {
+                logger.warn(`ContextComposer does not support unregisterSource; cannot unregister "${name}"`);
+            }
+        },
+        getConfig() {
+            return pluginConfig;
+        },
+    };
+    return api;
+}
+//# sourceMappingURL=api.js.map

package/dist/plugins/define.d.ts

@@ -0,0 +1,27 @@
+import type { PluginDefinition, PluginApi } from './types.js';
+export type DefinePluginOptions = {
+    id: string;
+    name: string;
+    description: string;
+    configSchema?: Record<string, unknown>;
+    register: (api: PluginApi) => void | Promise<void>;
+    onActivate?: (api: PluginApi) => void | Promise<void>;
+    onDeactivate?: (api: PluginApi) => void | Promise<void>;
+};
+/**
+ * 定义插件入口。
+ *
+ * 用法：
+ * ```ts
+ * export default definePlugin({
+ *   id: 'my-plugin',
+ *   name: 'My Plugin',
+ *   description: 'Does something',
+ *   register: (api) => {
+ *     api.registerTool(myTool);
+ *   },
+ * });
+ * ```
+ */
+export declare function definePlugin(options: DefinePluginOptions): PluginDefinition;
+//# sourceMappingURL=define.d.ts.map

package/dist/plugins/define.js

@@ -0,0 +1,32 @@
+/**
+ * 定义插件入口。
+ *
+ * 用法：
+ * ```ts
+ * export default definePlugin({
+ *   id: 'my-plugin',
+ *   name: 'My Plugin',
+ *   description: 'Does something',
+ *   register: (api) => {
+ *     api.registerTool(myTool);
+ *   },
+ * });
+ * ```
+ */
+export function definePlugin(options) {
+    const { id, name, description, configSchema, register, onActivate, onDeactivate } = options;
+    const def = {
+        id,
+        name,
+        description,
+        register,
+    };
+    if (configSchema)
+        def.configSchema = configSchema;
+    if (onActivate)
+        def.onActivate = onActivate;
+    if (onDeactivate)
+        def.onDeactivate = onDeactivate;
+    return def;
+}
+//# sourceMappingURL=define.js.map

package/dist/plugins/index.d.ts

@@ -0,0 +1,9 @@
+export { definePlugin } from './define.js';
+export type { DefinePluginOptions } from './define.js';
+export { createPluginApi } from './api.js';
+export type { PluginApiOptions } from './api.js';
+export { PluginLoader } from './loader.js';
+export { PluginManager } from './manager.js';
+export type { PluginManagerDeps } from './manager.js';
+export type { PluginManifest, PluginDefinition, PluginApi, PluginLogger, PluginInstance, PluginStatus, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/index.js

@@ -0,0 +1,5 @@
+export { definePlugin } from './define.js';
+export { createPluginApi } from './api.js';
+export { PluginLoader } from './loader.js';
+export { PluginManager } from './manager.js';
+//# sourceMappingURL=index.js.map

package/dist/plugins/loader.d.ts

@@ -0,0 +1,39 @@
+import type { PluginManifest } from './types.js';
+/**
+ * 插件加载器
+ *
+ * 负责扫描插件目录、加载 plugin.json manifest、dynamic import 入口模块。
+ * 搜索路径（按优先级）：
+ *   1. <projectDir>/.agent/plugins/<plugin-id>/
+ *   2. <projectDir>/plugins/                        （内置/开发用）
+ */
+export declare class PluginLoader {
+    private projectDir;
+    constructor(projectDir: string);
+    /**
+     * 扫描所有候选目录，返回发现的 manifest 列表
+     */
+    discover(): Promise<PluginManifest[]>;
+    /**
+     * 扫描单个目录下的所有插件子目录
+     */
+    private scanDirectory;
+    /**
+     * 加载 manifest 指向的入口模块
+     * 返回模块的 default export（应为 PluginDefinition）
+     */
+    loadEntryModule<T>(manifest: PluginManifest): Promise<T | null>;
+    /**
+     * 获取插件目录的绝对路径
+     */
+    getPluginDir(manifest: PluginManifest): Promise<string | null>;
+    /**
+     * 读取插件配置文件（.agent/plugins.config.json）
+     */
+    loadPluginConfig(): Promise<Record<string, Record<string, unknown>>>;
+    /**
+     * 解析插件目录位置
+     */
+    private resolvePluginDir;
+}
+//# sourceMappingURL=loader.d.ts.map