hyacinth-ai 0.9.6

package/dist/machine/registry.js

@@ -0,0 +1,98 @@
+// ============================================================
+// MachineRegistry — 状态机注册表
+// ============================================================
+//
+// 管理多个 FlowController 的生命周期。
+// 同一时间只有一个 Flow 处于活跃状态——激活新 Flow 前
+// 自动停用当前活跃的 Flow。
+//
+// MachineRegistry 直接存储 FlowController（而非 MachineRunner），
+// 这样 ContextSource 可以直接调用 getInjection()，无需额外映射。
+// ============================================================
+import { createLogger } from '../logging/logger.js';
+const logger = createLogger('machine-registry');
+export class MachineRegistry {
+    flows = new Map();
+    activeId = null;
+    /** 注册 Flow */
+    register(flow) {
+        if (this.flows.has(flow.id)) {
+            logger.warn('Flow already registered, replacing', { id: flow.id });
+        }
+        this.flows.set(flow.id, flow);
+    }
+    /** 按 id 获取 Flow */
+    get(id) {
+        return this.flows.get(id);
+    }
+    /** 获取当前活跃的 Flow */
+    getActive() {
+        if (!this.activeId)
+            return undefined;
+        const flow = this.flows.get(this.activeId);
+        // 只有当 Flow 的 runner 处于 active 状态时才返回
+        if (flow?.runner.status === 'active')
+            return flow;
+        return undefined;
+    }
+    /** 激活指定 Flow（自动停用当前活跃 Flow） */
+    activate(id, context) {
+        const flow = this.flows.get(id);
+        if (!flow) {
+            logger.error('Cannot activate unknown flow', undefined, { id });
+            return;
+        }
+        // 停用当前活跃 Flow
+        if (this.activeId && this.activeId !== id) {
+            this.deactivate();
+        }
+        this.activeId = id;
+        flow.activate(context);
+        logger.info('Flow activated', { id });
+    }
+    /** 停用当前活跃 Flow */
+    deactivate() {
+        if (this.activeId) {
+            const flow = this.flows.get(this.activeId);
+            if (flow && flow.runner.status === 'active') {
+                flow.deactivate();
+            }
+            logger.info('Flow deactivated', { id: this.activeId });
+            this.activeId = null;
+        }
+    }
+    /**
+     * 步骤完成回调。
+     *
+     * 调用活跃 Flow 的 advance('flow_complete')。
+     * 如果转移结果 isTerminal，停用该 Flow。
+     *
+     * @deprecated 请使用 onAdvanceSucceeded — flow_complete 工具内部已调用 advance，
+     *   orchestrator loop 只需检查结果后调用 onAdvanceSucceeded 做清理。
+     */
+    async onStepComplete() {
+        const active = this.getActive();
+        if (!active)
+            return;
+        const result = active.advance('flow_complete');
+        if (result.isTerminal) {
+            // 所有步骤完成
+            logger.info('Flow completed', { id: active.id });
+            // runner 内部的 onComplete 已由 MachineRunner.advance() 触发
+            this.activeId = null;
+        }
+    }
+    /**
+     * 标记一次成功的 advance 的后续处理。
+     *
+     * flow_complete 工具内部已调用 advance()，
+     * 这里只做 post-advance 清理（terminal → deactivate）。
+     */
+    onAdvanceSucceeded(flowId, isTerminal) {
+        if (isTerminal) {
+            logger.info('Flow completed', { id: flowId });
+            this.activeId = null;
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/machine/runner.d.ts

@@ -0,0 +1,41 @@
+import type { MachineDef, MachineContext, MachineStatus, MachineSnapshot, AdvanceResult } from './types.js';
+export declare class MachineRunner {
+    readonly definition: MachineDef;
+    readonly context: MachineContext;
+    currentState: string;
+    status: MachineStatus;
+    private transitionHistory;
+    constructor(definition: MachineDef);
+    /** 激活状态机 */
+    activate(ctx?: MachineContext): void;
+    /** 停用状态机 */
+    deactivate(): void;
+    /**
+     * 通过事件推进状态机。
+     *
+     * 执行流程：
+     *   1. 找匹配的 TransitionDef（from 匹配 currentState，event 匹配）
+     *   2. 执行 guard（若有），不通过返回 { ok: false, reason }
+     *   3. 执行 onExit(currentState)
+     *   4. 执行 onTransition（若有）
+     *   5. 更新 currentState
+     *   6. 执行 onEnter(newState)
+     *   7. 记录 transitionHistory
+     *   8. 如果是 terminalState → status = 'completed' → 触发 onComplete
+     */
+    advance(event: string): AdvanceResult;
+    /** 当前状态下可触发的事件列表 */
+    getAvailableEvents(): string[];
+    /** 结构化快照（给 bypass agent 读） */
+    getSnapshot(): MachineSnapshot;
+    /** 是否已完成（到达终端状态） */
+    isComplete(): boolean;
+    /**
+     * 直接修改 context，不触发任何状态转移。
+     *
+     * 用途：add_todo_step 在 planning 阶段向 context.steps 追加步骤。
+     * 这不是状态转移——只是数据累积。
+     */
+    updateContext(patch: Partial<MachineContext>): void;
+}
+//# sourceMappingURL=runner.d.ts.map

package/dist/machine/runner.js

@@ -0,0 +1,177 @@
+// ============================================================
+// MachineRunner — 状态机执行引擎
+// ============================================================
+//
+// 包装 MachineDef，提供：
+//   - 生命周期管理（activate / deactivate）
+//   - 事件驱动的状态转移（advance）
+//   - Guard 检查（guard 不通过 → 拒绝转移）
+//   - 副作用执行（onEnter / onExit / onTransition）
+//   - 有限的转移历史（最近 20 条）
+//   - 结构化快照（getSnapshot — 给 bypass agent）
+//   - 直接上下文突变（updateContext — 给 add_todo_step）
+// ============================================================
+/** 转移历史最大保留条数 */
+const MAX_HISTORY = 20;
+/** fire-and-forget 调用——吞掉所有同步/异步异常 */
+function safeFire(fn, ctx) {
+    if (!fn)
+        return;
+    try {
+        const result = fn(ctx);
+        // 如果返回 Promise，附加 catch 避免 unhandled rejection
+        if (result instanceof Promise) {
+            result.catch(() => { });
+        }
+    }
+    catch {
+        // 副作用失败不影响状态机运行
+    }
+}
+export class MachineRunner {
+    definition;
+    context = {};
+    currentState;
+    status = 'idle';
+    transitionHistory = [];
+    constructor(definition) {
+        this.definition = definition;
+        this.currentState = definition.initial;
+    }
+    // ── 生命周期 ──────────────────────────────────────────────
+    /** 激活状态机 */
+    activate(ctx) {
+        // 合并初始上下文
+        if (ctx) {
+            Object.assign(this.context, ctx);
+        }
+        this.currentState = this.definition.initial;
+        this.transitionHistory = [];
+        this.status = 'active';
+        // 执行初始状态的 onEnter
+        const initialDef = this.definition.states[this.currentState];
+        safeFire(initialDef?.onEnter, this.context);
+    }
+    /** 停用状态机 */
+    deactivate() {
+        // 执行当前状态的 onExit
+        const currentDef = this.definition.states[this.currentState];
+        safeFire(currentDef?.onExit, this.context);
+        this.status = 'idle';
+    }
+    // ── 核心：事件驱动的状态转移 ──────────────────────────────
+    /**
+     * 通过事件推进状态机。
+     *
+     * 执行流程：
+     *   1. 找匹配的 TransitionDef（from 匹配 currentState，event 匹配）
+     *   2. 执行 guard（若有），不通过返回 { ok: false, reason }
+     *   3. 执行 onExit(currentState)
+     *   4. 执行 onTransition（若有）
+     *   5. 更新 currentState
+     *   6. 执行 onEnter(newState)
+     *   7. 记录 transitionHistory
+     *   8. 如果是 terminalState → status = 'completed' → 触发 onComplete
+     */
+    advance(event) {
+        if (this.status !== 'active') {
+            return { ok: false, reason: `Machine "${this.definition.id}" is not active (status: ${this.status}).` };
+        }
+        // 1. 找匹配的转移
+        const transition = this.definition.transitions.find((t) => {
+            const fromMatch = Array.isArray(t.from)
+                ? t.from.includes(this.currentState)
+                : t.from === this.currentState;
+            return fromMatch && t.event === event;
+        });
+        if (!transition) {
+            return {
+                ok: false,
+                reason: `Event "${event}" is not valid in state "${this.currentState}" of machine "${this.definition.id}". Available events: [${this.getAvailableEvents().join(', ')}]`,
+            };
+        }
+        // 2. Guard 检查
+        if (transition.guard) {
+            const guardResult = transition.guard(this.context);
+            if (!guardResult.ok) {
+                return {
+                    ok: false,
+                    reason: guardResult.reason ?? `Guard rejected transition from "${this.currentState}" to "${transition.to}" via "${event}".`,
+                };
+            }
+        }
+        // 3. onExit 副作用（fire-and-forget）
+        const oldState = this.currentState;
+        const oldDef = this.definition.states[oldState];
+        safeFire(oldDef?.onExit, this.context);
+        // 4. onTransition 副作用（同步执行——可阻塞）
+        transition.onTransition?.(this.context);
+        // 5. 更新状态
+        this.currentState = transition.to;
+        // 6. onEnter 副作用（fire-and-forget）
+        const newDef = this.definition.states[this.currentState];
+        safeFire(newDef?.onEnter, this.context);
+        // 7. 记录历史
+        this.transitionHistory.push({ from: oldState, to: transition.to, event });
+        if (this.transitionHistory.length > MAX_HISTORY) {
+            this.transitionHistory = this.transitionHistory.slice(-MAX_HISTORY);
+        }
+        // 8. 终端状态检查
+        const isTerminal = this.definition.terminalStates?.includes(this.currentState) ?? false;
+        if (isTerminal) {
+            this.status = 'completed';
+            // 触发 onComplete（异步，不阻塞）
+            if (this.definition.onComplete) {
+                Promise.resolve(this.definition.onComplete(this.context)).catch(() => {
+                    // onComplete 失败不影响状态机状态
+                });
+            }
+        }
+        return { ok: true, to: transition.to, isTerminal };
+    }
+    // ── 查询 ──────────────────────────────────────────────────
+    /** 当前状态下可触发的事件列表 */
+    getAvailableEvents() {
+        if (this.status !== 'active')
+            return [];
+        const events = new Set();
+        for (const t of this.definition.transitions) {
+            const fromMatch = Array.isArray(t.from)
+                ? t.from.includes(this.currentState)
+                : t.from === this.currentState;
+            if (fromMatch) {
+                events.add(t.event);
+            }
+        }
+        return [...events];
+    }
+    /** 结构化快照（给 bypass agent 读） */
+    getSnapshot() {
+        const stateDef = this.definition.states[this.currentState];
+        return {
+            machineId: this.definition.id,
+            currentState: this.currentState,
+            label: stateDef?.label ?? this.currentState,
+            availableEvents: this.getAvailableEvents(),
+            context: this.context,
+            status: this.status,
+            isTerminal: this.definition.terminalStates?.includes(this.currentState) ?? false,
+            history: [...this.transitionHistory],
+        };
+    }
+    /** 是否已完成（到达终端状态） */
+    isComplete() {
+        return this.status === 'completed';
+    }
+    // ── 上下文突变（非转移操作） ──────────────────────────────
+    /**
+     * 直接修改 context，不触发任何状态转移。
+     *
+     * 用途：add_todo_step 在 planning 阶段向 context.steps 追加步骤。
+     * 这不是状态转移——只是数据累积。
+     */
+    updateContext(patch) {
+        Object.assign(this.context, patch);
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/machine/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * MachineContext — 状态机携带的任意数据。
+ * 由 Flow 层定义具体结构（如 TODO 的 steps、stepIndex、task）。
+ */
+export interface MachineContext {
+    [key: string]: unknown;
+}
+/**
+ * GuardResult — 守卫返回值。
+ * 守卫不通过时，reason 会通过工具返回值告知模型。
+ */
+export interface GuardResult {
+    ok: boolean;
+    /** 不通过的原因（会展示给模型） */
+    reason?: string;
+}
+/**
+ * StateDef — 状态定义。
+ */
+export interface StateDef {
+    /** 状态名（在 MachineDef.states 的 key 中已体现，此处可选） */
+    name?: string;
+    /** 人类可读标签，如 "规划中"，用于快照和日志 */
+    label?: string;
+    /** 进入该状态时的副作用（fire-and-forget，可同步可异步） */
+    onEnter?: (ctx: MachineContext) => void | Promise<void>;
+    /** 离开该状态时的副作用（fire-and-forget，可同步可异步） */
+    onExit?: (ctx: MachineContext) => void | Promise<void>;
+}
+/**
+ * TransitionDef — 转移定义。
+ *
+ * 转移按定义顺序匹配：runner.advance(event) 找到第一个
+ * from 匹配 currentState 且 event 匹配的转移。
+ */
+export interface TransitionDef {
+    /** 源状态（单个或多个） */
+    from: string | string[];
+    /** 目标状态 */
+    to: string;
+    /** 触发事件名 */
+    event: string;
+    /** 守卫：返回 { ok: false } 阻止转移 */
+    guard?: (ctx: MachineContext) => GuardResult;
+    /** 转移时的副作用（同步执行） */
+    onTransition?: (ctx: MachineContext) => void;
+}
+/**
+ * MachineDef — 状态机定义（纯数据，无行为）。
+ *
+ * 声明式的转移表，由 MachineRunner 执行。
+ */
+export interface MachineDef {
+    /** 唯一标识（如 "todo"、"bootstrap"） */
+    id: string;
+    /** 初始状态名 */
+    initial: string;
+    /** 所有状态（key = state name） */
+    states: Record<string, StateDef>;
+    /** 转移规则（按优先级排列） */
+    transitions: TransitionDef[];
+    /** 终端状态：进入这些状态后 status 自动变为 'completed' */
+    terminalStates?: string[];
+    /** 机器完成时的回调（所有步骤结束） */
+    onComplete?: (ctx: MachineContext) => void | Promise<void>;
+}
+/**
+ * MachineStatus — 机器生命周期状态。
+ *   'idle'     — 未激活
+ *   'active'   — 运行中
+ *   'completed' — 已到达终端状态
+ */
+export type MachineStatus = 'idle' | 'active' | 'completed';
+/**
+ * HistoryEntry — 单次状态转移记录。
+ */
+export interface HistoryEntry {
+    from: string;
+    to: string;
+    event: string;
+}
+/**
+ * MachineSnapshot — 对外暴露的只读状态视图。
+ *
+ * bypass agent 通过此快照感知主线状态机状态，
+ * 决定是否介入（inject/interrupt/纠偏）。
+ */
+export interface MachineSnapshot {
+    /** 机器 ID */
+    machineId: string;
+    /** 当前状态名 */
+    currentState: string;
+    /** 当前状态的人类可读标签 */
+    label: string;
+    /** 当前状态下可触发的所有事件 */
+    availableEvents: string[];
+    /** 状态机上下文数据 */
+    context: Readonly<MachineContext>;
+    /** 生命周期状态 */
+    status: MachineStatus;
+    /** 当前状态是否为终端状态 */
+    isTerminal: boolean;
+    /** 最近 20 条转移历史（最近的在末尾） */
+    history: ReadonlyArray<HistoryEntry>;
+}
+/**
+ * AdvanceResult — advance() 返回值。
+ *
+ * ok=false 表示转移被拒绝（guard 不通过或无匹配转移），
+ * reason 会通过 complete_flow_step 工具返回值反馈给模型。
+ */
+export interface AdvanceResult {
+    ok: boolean;
+    /** 失败原因（guard 不通过时） */
+    reason?: string;
+    /** 转移到的目标状态 */
+    to?: string;
+    /** 本次转移后是否到达终端状态 */
+    isTerminal?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/machine/types.js

@@ -0,0 +1,9 @@
+// ============================================================
+// Machine Types — 通用状态机类型定义
+// ============================================================
+//
+// 与业务无关的纯状态机基础设施。不包含 LLM/Flow 概念。
+// Flow 层（flows/）在此基础上添加 getInjection、工具创建等。
+// ============================================================
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mcp/bridge.d.ts

@@ -0,0 +1,33 @@
+import type { ToolRegistry } from '../tools/registry.js';
+import type { MCPClient } from './client.js';
+import type { MCPServerManager } from './lifecycle.js';
+import { sanitizeMcpName } from './side-effect.js';
+export { sanitizeMcpName };
+/**
+ * MCPBridge — 将 MCP Server 的工具桥接到内部 ToolRegistry
+ *
+ * 为每个 MCP 工具创建一个桥接执行函数，注册到 ToolRegistry 中。
+ * 工具名称格式：mcp__{serverName}__{toolName}（避免命名冲突）
+ */
+export declare class MCPBridge {
+    private clients;
+    private managers;
+    private registeredTools;
+    private logger;
+    constructor(clients: MCPClient[], managers?: MCPServerManager[]);
+    /** 设置 MCPServerManager 列表（用于按需拉起） */
+    setManagers(managers: MCPServerManager[]): void;
+    /** 更新 clients/managers 列表（保留 registeredTools 历史） */
+    updateClients(clients: MCPClient[], managers: MCPServerManager[]): void;
+    /** 获取指定名称的 MCPServerManager */
+    getManager(name: string): MCPServerManager | undefined;
+    /** 将所有已连接 MCP Server 的工具注册到 ToolRegistry */
+    registerToRegistry(registry: ToolRegistry): void;
+    /** 注销指定 MCP Server 的所有已注册工具 */
+    unregisterTools(serverName: string, registry: ToolRegistry): void;
+    /** 获取所有已连接 MCP Server 的合并索引 */
+    getMergedIndex(): string;
+    /** 获取所有已连接 MCP Server 的工具名称列表 */
+    getAllToolNames(): string[];
+}
+//# sourceMappingURL=bridge.d.ts.map

package/dist/mcp/bridge.js

@@ -0,0 +1,99 @@
+import { createLogger } from '../logging/logger.js';
+import { hasSideEffect, sanitizeMcpName } from './side-effect.js';
+// 保持向后兼容：lifecycle.ts 从此处导入 sanitizeMcpName
+export { sanitizeMcpName };
+/**
+ * MCPBridge — 将 MCP Server 的工具桥接到内部 ToolRegistry
+ *
+ * 为每个 MCP 工具创建一个桥接执行函数，注册到 ToolRegistry 中。
+ * 工具名称格式：mcp__{serverName}__{toolName}（避免命名冲突）
+ */
+export class MCPBridge {
+    clients;
+    managers;
+    registeredTools = new Map();
+    logger = createLogger('mcp:bridge');
+    constructor(clients, managers = []) {
+        this.clients = clients;
+        this.managers = managers;
+    }
+    /** 设置 MCPServerManager 列表（用于按需拉起） */
+    setManagers(managers) {
+        this.managers = managers;
+    }
+    /** 更新 clients/managers 列表（保留 registeredTools 历史） */
+    updateClients(clients, managers) {
+        this.clients = clients;
+        this.managers = managers;
+    }
+    /** 获取指定名称的 MCPServerManager */
+    getManager(name) {
+        return this.managers.find(m => m.getName() === name);
+    }
+    /** 将所有已连接 MCP Server 的工具注册到 ToolRegistry */
+    registerToRegistry(registry) {
+        for (const client of this.clients) {
+            if (!client.isConnected()) {
+                this.logger.warn(`skipping disconnected MCP client: ${client.getName()}`);
+                continue;
+            }
+            const serverName = client.getName();
+            // 幂等性：如果该 server 已有旧注册记录，先清理
+            const oldNames = this.registeredTools.get(serverName);
+            if (oldNames) {
+                for (const name of oldNames) {
+                    registry.unregister(name);
+                }
+            }
+            const toolNames = [];
+            for (const tool of client.getTools()) {
+                const mcpToolName = `mcp__${sanitizeMcpName(serverName)}__${tool.name}`;
+                toolNames.push(mcpToolName);
+                registry.register({
+                    name: mcpToolName,
+                    description: `[MCP:${serverName}] ${tool.description ?? tool.name}${hasSideEffect(tool.name) ? ' [side-effect]' : ''}`,
+                    inputSchema: tool.inputSchema,
+                    execute: async (input) => {
+                        return client.callTool(tool.name, input);
+                    },
+                });
+            }
+            this.registeredTools.set(serverName, toolNames);
+        }
+    }
+    /** 注销指定 MCP Server 的所有已注册工具 */
+    unregisterTools(serverName, registry) {
+        const toolNames = this.registeredTools.get(serverName);
+        if (!toolNames)
+            return;
+        for (const name of toolNames) {
+            registry.unregister(name);
+        }
+        this.registeredTools.delete(serverName);
+    }
+    /** 获取所有已连接 MCP Server 的合并索引 */
+    getMergedIndex() {
+        const parts = [];
+        for (const client of this.clients) {
+            if (!client.isConnected())
+                continue;
+            const index = client.getToolIndex();
+            if (index)
+                parts.push(index);
+        }
+        return parts.join('\n\n');
+    }
+    /** 获取所有已连接 MCP Server 的工具名称列表 */
+    getAllToolNames() {
+        const names = [];
+        for (const client of this.clients) {
+            if (!client.isConnected())
+                continue;
+            for (const tool of client.getTools()) {
+                names.push(`mcp__${client.getName()}__${tool.name}`);
+            }
+        }
+        return names;
+    }
+}
+//# sourceMappingURL=bridge.js.map

package/dist/mcp/client.d.ts

@@ -0,0 +1,37 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { MCPConfig } from '../types.js';
+/** MCP 工具信息（从 MCP Server 获取） */
+export interface MCPToolInfo {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * MCPClient — 连接 MCP Server，获取工具列表，执行工具调用
+ *
+ * 支持 stdio 传输（子进程）和 HTTP SSE 传输
+ */
+export declare class MCPClient {
+    private config;
+    private client;
+    private transport;
+    private connected;
+    private tools;
+    private logger;
+    constructor(config: MCPConfig);
+    /** 连接到 MCP Server */
+    connect(externalTransport?: Transport): Promise<void>;
+    /** 断开连接 */
+    disconnect(): Promise<void>;
+    /** 是否已连接 */
+    isConnected(): boolean;
+    /** 获取 MCP Server 提供的工具列表 */
+    getTools(): MCPToolInfo[];
+    /** 获取工具索引（名称+描述列表） */
+    getToolIndex(): string;
+    /** 调用 MCP 工具 */
+    callTool(name: string, args: Record<string, unknown>): Promise<string>;
+    /** 获取 Server 名称 */
+    getName(): string;
+}
+//# sourceMappingURL=client.d.ts.map