hyacinth-ai 0.9.6

package/dist/local-model/model-registry.d.ts

@@ -0,0 +1,47 @@
+import { EventEmitter } from 'node:events';
+import type { ModelEntry, ModelBackend, ModelRegisterOptions } from './types.js';
+export type { ModelEntry, ModelBackend, ModelRegisterOptions };
+declare interface ModelRegistryEvents {
+    changed: [];
+    added: [ModelEntry];
+    removed: [ModelEntry];
+}
+/**
+ * 模型注册中心 — 管理 models.json 与 models/ 目录
+ *
+ * 职责：
+ * - 读写 .agent/models.json 作为模型注册表
+ * - 扫描 models/ 目录发现未注册的 GGUF 文件
+ * - 热插拔：监听 models/ 目录变更
+ * - 增删改查模型注册项
+ */
+export declare class ModelRegistry extends EventEmitter<ModelRegistryEvents> {
+    private entries;
+    private registryPath;
+    private modelsDir;
+    private watcher;
+    private static instance;
+    static getInstance(projectRoot?: string): ModelRegistry;
+    private constructor();
+    init(): ModelEntry[];
+    destroy(): void;
+    private load;
+    private save;
+    scanDirectory(): string[];
+    /**
+     * 扫描 models/ 目录，自动发现未注册的 GGUF 文件并添加到注册表。
+     * 返回新发现并注册的条目。
+     */
+    scanAndMerge(): ModelEntry[];
+    private startWatcher;
+    register(options: ModelRegisterOptions): ModelEntry;
+    unregister(name: string): boolean;
+    list(): ModelEntry[];
+    find(name: string): ModelEntry | undefined;
+    findByPort(port: number): ModelEntry | undefined;
+    count(): number;
+    getModelsDir(): string;
+    getRegistryPath(): string;
+    private getExtension;
+}
+//# sourceMappingURL=model-registry.d.ts.map

package/dist/local-model/model-registry.js

@@ -0,0 +1,188 @@
+import { EventEmitter } from 'node:events';
+import { existsSync, readdirSync, readFileSync, watch, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+/**
+ * 模型注册中心 — 管理 models.json 与 models/ 目录
+ *
+ * 职责：
+ * - 读写 .agent/models.json 作为模型注册表
+ * - 扫描 models/ 目录发现未注册的 GGUF 文件
+ * - 热插拔：监听 models/ 目录变更
+ * - 增删改查模型注册项
+ */
+export class ModelRegistry extends EventEmitter {
+    entries = [];
+    registryPath;
+    modelsDir;
+    watcher = null;
+    static instance = null;
+    static getInstance(projectRoot) {
+        if (!ModelRegistry.instance) {
+            ModelRegistry.instance = new ModelRegistry(projectRoot ?? process.cwd());
+        }
+        return ModelRegistry.instance;
+    }
+    constructor(projectRoot) {
+        super();
+        this.registryPath = join(projectRoot, '.agent', 'models.json');
+        this.modelsDir = join(projectRoot, 'models');
+    }
+    // ── 初始化 ──
+    init() {
+        this.load();
+        this.scanAndMerge();
+        this.startWatcher();
+        return this.entries;
+    }
+    destroy() {
+        if (this.watcher) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+        this.removeAllListeners();
+        ModelRegistry.instance = null;
+    }
+    // ── 持久化 ──
+    load() {
+        if (!existsSync(this.registryPath)) {
+            this.entries = [];
+            return;
+        }
+        try {
+            const raw = readFileSync(this.registryPath, 'utf-8');
+            this.entries = JSON.parse(raw);
+        }
+        catch {
+            this.entries = [];
+        }
+    }
+    save() {
+        writeFileSync(this.registryPath, JSON.stringify(this.entries, null, 2), 'utf-8');
+    }
+    // ── 目录扫描 ──
+    scanDirectory() {
+        if (!existsSync(this.modelsDir)) {
+            return [];
+        }
+        return readdirSync(this.modelsDir).filter((f) => f.endsWith('.gguf') || f.endsWith('.GGUF'));
+    }
+    /**
+     * 扫描 models/ 目录，自动发现未注册的 GGUF 文件并添加到注册表。
+     * 返回新发现并注册的条目。
+     */
+    scanAndMerge() {
+        const ggufFiles = this.scanDirectory();
+        const registeredFiles = new Set(this.entries.map((e) => e.modelFile));
+        const newlyAdded = [];
+        for (const file of ggufFiles) {
+            if (registeredFiles.has(file))
+                continue;
+            const entry = {
+                name: basename(file, this.getExtension(file)),
+                modelFile: file,
+                modelPath: join(this.modelsDir, file),
+                backend: 'llama.cpp',
+                addedAt: new Date().toISOString(),
+                enabled: true,
+            };
+            this.entries.push(entry);
+            newlyAdded.push(entry);
+        }
+        if (newlyAdded.length > 0) {
+            this.save();
+            for (const e of newlyAdded) {
+                this.emit('added', e);
+            }
+            this.emit('changed');
+        }
+        return newlyAdded;
+    }
+    // ── 热插拔 ──
+    startWatcher() {
+        if (this.watcher)
+            return;
+        if (!existsSync(this.modelsDir)) {
+            return;
+        }
+        try {
+            this.watcher = watch(this.modelsDir, (_eventType, filename) => {
+                if (filename && (filename.endsWith('.gguf') || filename.endsWith('.GGUF'))) {
+                    // 延迟一下等文件写完
+                    setTimeout(() => this.scanAndMerge(), 500);
+                }
+            });
+        }
+        catch {
+            // watch 可能在部分环境下不可用，静默忽略
+        }
+    }
+    // ── CRUD ──
+    register(options) {
+        const existing = this.find(options.name);
+        const backend = options.backend ?? 'llama.cpp';
+        const modelPath = join(this.modelsDir, options.modelFile);
+        // 仅 llama.cpp 需要验证 GGUF 文件存在；Ollama 模型由 ollama 管理
+        if (backend === 'llama.cpp' && !existsSync(modelPath)) {
+            throw new Error(`模型文件不存在: ${modelPath}\n` +
+                `请将 ${options.modelFile} 放到 ${this.modelsDir} 目录下。`);
+        }
+        const entry = {
+            name: options.name,
+            modelFile: options.modelFile,
+            modelPath: backend === 'ollama' ? options.modelFile : modelPath,
+            backend,
+            port: options.port,
+            host: options.host,
+            ctxSize: options.ctxSize,
+            nGpuLayers: options.nGpuLayers,
+            addedAt: new Date().toISOString(),
+            enabled: true,
+        };
+        if (existing) {
+            Object.assign(existing, entry);
+        }
+        else {
+            this.entries.push(entry);
+        }
+        this.save();
+        this.emit('changed');
+        this.emit('added', entry);
+        return entry;
+    }
+    unregister(name) {
+        const idx = this.entries.findIndex((e) => e.name === name);
+        if (idx === -1)
+            return false;
+        const removed = this.entries.splice(idx, 1)[0];
+        this.save();
+        this.emit('changed');
+        this.emit('removed', removed);
+        return true;
+    }
+    // ── 查询 ──
+    list() {
+        return [...this.entries];
+    }
+    find(name) {
+        return this.entries.find((e) => e.name === name);
+    }
+    findByPort(port) {
+        return this.entries.find((e) => e.port === port);
+    }
+    count() {
+        return this.entries.length;
+    }
+    // ── 常用路径 ──
+    getModelsDir() {
+        return this.modelsDir;
+    }
+    getRegistryPath() {
+        return this.registryPath;
+    }
+    // ── 私有 ──
+    getExtension(filename) {
+        const dot = filename.lastIndexOf('.');
+        return dot > 0 ? filename.slice(dot) : '';
+    }
+}
+//# sourceMappingURL=model-registry.js.map

package/dist/local-model/types.d.ts

@@ -0,0 +1,49 @@
+import type { ProcessState } from '../lifecycle/interface.js';
+/** 模型后端类型 */
+export type ModelBackend = 'llama.cpp' | 'ollama' | 'vllm' | 'lm-studio' | 'custom';
+/** 模型注册条目 */
+export interface ModelEntry {
+    name: string;
+    modelFile: string;
+    modelPath: string;
+    backend: ModelBackend;
+    port?: number;
+    host?: string;
+    ctxSize?: number;
+    nGpuLayers?: number;
+    addedAt: string;
+    enabled: boolean;
+}
+/** 模型注册选项 */
+export interface ModelRegisterOptions {
+    name: string;
+    modelFile: string;
+    backend?: ModelBackend;
+    port?: number;
+    host?: string;
+    ctxSize?: number;
+    nGpuLayers?: number;
+}
+/** 运行中模型信息 */
+export interface RunningModelInfo {
+    name: string;
+    modelFile: string;
+    backend: string;
+    port: number;
+    host: string;
+    state: ProcessState;
+    pid: number | null;
+    baseUrl: string;
+}
+/** LlamaCppProvider 构造选项 */
+export interface LlamaCppOptions {
+    /** llama-server 地址，默认 http://127.0.0.1:8080 */
+    endpoint?: string;
+    /** 模型名称，默认 llama-3-8b-q4_k_m */
+    model?: string;
+    /** 最大输出 token 数，默认 4096 */
+    maxTokens?: number;
+    /** 最大上下文 token 数（用于 getCapabilities），默认 8192 */
+    maxContextTokens?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/local-model/types.js

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

package/dist/logging/index.d.ts

@@ -0,0 +1,3 @@
+export { createLogger, ConsoleLogger, NoopLogger } from './logger.js';
+export type { Logger, LogLevel, LogEntry } from './logger.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/logging/index.js

@@ -0,0 +1,3 @@
+// Logging module exports
+export { createLogger, ConsoleLogger, NoopLogger } from './logger.js';
+//# sourceMappingURL=index.js.map

package/dist/logging/logger.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Structured Logging System
+ *
+ * JSON-lines format to stderr for machine readability.
+ * stdout is reserved for agent output, so all logs go to stderr.
+ *
+ * Levels: debug < info < warn < error
+ * Environment: LOG_LEVEL=debug|info|warn|error (default: info)
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogEntry {
+    ts: string;
+    lvl: LogLevel;
+    mod: string;
+    msg: string;
+    ctx?: Record<string, unknown>;
+    err?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+export interface Logger {
+    debug(msg: string, context?: Record<string, unknown>): void;
+    info(msg: string, context?: Record<string, unknown>): void;
+    warn(msg: string, context?: Record<string, unknown>): void;
+    error(msg: string, error?: Error, context?: Record<string, unknown>): void;
+    /** Create a child logger with additional default context */
+    child(extraModule: string, extraContext?: Record<string, unknown>): Logger;
+}
+export declare class ConsoleLogger implements Logger {
+    private module;
+    private minLevel;
+    private defaultContext;
+    constructor(module: string, minLevel?: LogLevel, defaultContext?: Record<string, unknown>);
+    debug(msg: string, context?: Record<string, unknown>): void;
+    info(msg: string, context?: Record<string, unknown>): void;
+    warn(msg: string, context?: Record<string, unknown>): void;
+    error(msg: string, error?: Error, context?: Record<string, unknown>): void;
+    child(extraModule: string, extraContext?: Record<string, unknown>): Logger;
+    private log;
+}
+export declare class NoopLogger implements Logger {
+    debug(): void;
+    info(): void;
+    warn(): void;
+    error(): void;
+    child(_extraModule: string, _extraContext?: Record<string, unknown>): Logger;
+}
+/**
+ * Create a logger for the given module.
+ * Use LOG_LEVEL=off environment variable to disable all logging.
+ */
+export declare function createLogger(module: string): Logger;
+export { NoopLogger as _NoopLogger };
+//# sourceMappingURL=logger.d.ts.map

package/dist/logging/logger.js

@@ -0,0 +1,94 @@
+/**
+ * Structured Logging System
+ *
+ * JSON-lines format to stderr for machine readability.
+ * stdout is reserved for agent output, so all logs go to stderr.
+ *
+ * Levels: debug < info < warn < error
+ * Environment: LOG_LEVEL=debug|info|warn|error (default: info)
+ */
+const LEVEL_WEIGHT = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+// ─── Console Logger ────────────────────────────────────────────────
+function getMinLevel() {
+    const env = (process.env.LOG_LEVEL ?? 'info').toLowerCase();
+    if (env === 'debug')
+        return 'debug';
+    if (env === 'warn')
+        return 'warn';
+    if (env === 'error')
+        return 'error';
+    return 'info';
+}
+export class ConsoleLogger {
+    module;
+    minLevel;
+    defaultContext;
+    constructor(module, minLevel, defaultContext) {
+        this.module = module;
+        this.minLevel = minLevel ?? getMinLevel();
+        this.defaultContext = defaultContext ?? {};
+    }
+    debug(msg, context) {
+        this.log('debug', msg, undefined, context);
+    }
+    info(msg, context) {
+        this.log('info', msg, undefined, context);
+    }
+    warn(msg, context) {
+        this.log('warn', msg, undefined, context);
+    }
+    error(msg, error, context) {
+        this.log('error', msg, error, context);
+    }
+    child(extraModule, extraContext) {
+        return new ConsoleLogger(`${this.module}:${extraModule}`, this.minLevel, { ...this.defaultContext, ...extraContext });
+    }
+    log(level, message, error, context) {
+        if (LEVEL_WEIGHT[level] < LEVEL_WEIGHT[this.minLevel])
+            return;
+        const entry = {
+            ts: new Date().toISOString(),
+            lvl: level,
+            mod: this.module,
+            msg: message,
+            ctx: context ? { ...this.defaultContext, ...context } : (Object.keys(this.defaultContext).length > 0 ? this.defaultContext : undefined),
+        };
+        if (error) {
+            entry.err = {
+                name: error.name,
+                message: error.message,
+                stack: error.stack,
+            };
+        }
+        // JSON line to stderr
+        process.stderr.write(JSON.stringify(entry) + '\n');
+    }
+}
+// ─── Noop Logger (for tests / disabled logging) ────────────────────
+export class NoopLogger {
+    debug() { }
+    info() { }
+    warn() { }
+    error() { }
+    child(_extraModule, _extraContext) {
+        return this;
+    }
+}
+// ─── Factory ───────────────────────────────────────────────────────
+/**
+ * Create a logger for the given module.
+ * Use LOG_LEVEL=off environment variable to disable all logging.
+ */
+export function createLogger(module) {
+    if (process.env.LOG_LEVEL === 'off')
+        return new NoopLogger();
+    return new ConsoleLogger(module);
+}
+// Re-export the class for testing
+export { NoopLogger as _NoopLogger };
+//# sourceMappingURL=logger.js.map

package/dist/machine/flows/bootstrap.d.ts

@@ -0,0 +1,18 @@
+import type { MachineContext, MachineSnapshot, AdvanceResult } from '../types.js';
+import { MachineRunner } from '../runner.js';
+import type { FlowController } from './types.js';
+export declare class BootstrapFlow implements FlowController {
+    readonly id = "bootstrap";
+    readonly runner: MachineRunner;
+    private personaDir;
+    private stepPrompts;
+    constructor(personaDir: string);
+    activate(_context?: MachineContext): void;
+    deactivate(): void;
+    advance(event: string): AdvanceResult;
+    getSnapshot(): MachineSnapshot;
+    isComplete(): boolean;
+    getInjection(): string | null;
+    private loadPromptOnce;
+}
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/machine/flows/bootstrap.js

@@ -0,0 +1,119 @@
+// ============================================================
+// BootstrapFlow — 身份引导 Flow
+// ============================================================
+//
+// 首次安装后自动运行一次。通过 4 个步骤引导模型与用户交流，
+// 逐步填写 SOUL.md、IDENTITY.md、USER.md，完成后永久标记。
+//
+// 基于 MachineDef：4 个固定状态，线性推进，无 guard，无动态步骤。
+// 步骤提示词从 src/prompts/flows/bootstrap-*.md 加载。
+// ============================================================
+import { MachineRunner } from '../runner.js';
+import { loadPrompt } from '../../prompts/loader.js';
+import { markBootstrapComplete } from '../../setup/persona-bootstrap.js';
+// ── 步骤定义 ────────────────────────────────────────────────
+const STEP_FILES = [
+    'bootstrap-soul',
+    'bootstrap-identity',
+    'bootstrap-user',
+    'bootstrap-confirm',
+];
+const STATE_NAMES = ['soul', 'identity', 'user', 'confirm'];
+// ── MachineDef ──────────────────────────────────────────────
+/**
+ * Bootstrap 状态机定义。
+ *
+ * States:  soul → identity → user → confirm → __completed__
+ * Initial: soul
+ * Terminal: __completed__
+ *
+ * 线性推进，无 guard——每步的 complete_flow_step 无条件转移。
+ * 最后一步 (confirm → __completed__) 的 onTransition 中调用
+ * markBootstrapComplete() 做永久标记。
+ */
+function createBootstrapMachineDef(personaDir) {
+    return {
+        id: 'bootstrap',
+        initial: 'soul',
+        states: {
+            soul: { label: '设定灵魂' },
+            identity: { label: '设定身份' },
+            user: { label: '了解用户' },
+            confirm: { label: '确认配置' },
+            __completed__: { label: '已完成' },
+        },
+        transitions: [
+            { from: 'soul', to: 'identity', event: 'complete_flow_step' },
+            { from: 'identity', to: 'user', event: 'complete_flow_step' },
+            { from: 'user', to: 'confirm', event: 'complete_flow_step' },
+            {
+                from: 'confirm',
+                to: '__completed__',
+                event: 'flow_complete',
+            },
+        ],
+        terminalStates: ['__completed__'],
+        onComplete: async (_ctx) => {
+            await markBootstrapComplete(personaDir);
+        },
+    };
+}
+// ── BootstrapFlow ────────────────────────────────────────────
+export class BootstrapFlow {
+    id = 'bootstrap';
+    runner;
+    personaDir;
+    stepPrompts = new Map();
+    constructor(personaDir) {
+        this.personaDir = personaDir;
+        this.runner = new MachineRunner(createBootstrapMachineDef(personaDir));
+    }
+    // ── 生命周期 ──────────────────────────────────────────────
+    activate(_context) {
+        // Bootstrap 不需要 context——步骤是固定的
+        this.runner.activate();
+    }
+    deactivate() {
+        this.runner.deactivate();
+    }
+    advance(event) {
+        return this.runner.advance(event);
+    }
+    getSnapshot() {
+        return this.runner.getSnapshot();
+    }
+    isComplete() {
+        return this.runner.isComplete();
+    }
+    // ── Zone 5 注入 ───────────────────────────────────────────
+    getInjection() {
+        const snap = this.runner.getSnapshot();
+        if (snap.status !== 'active')
+            return null;
+        // 从状态名映射到步骤文件
+        const stateToFile = {
+            soul: 'bootstrap-soul',
+            identity: 'bootstrap-identity',
+            user: 'bootstrap-user',
+            confirm: 'bootstrap-confirm',
+        };
+        const fileKey = stateToFile[snap.currentState];
+        if (!fileKey)
+            return null;
+        // 懒加载提示词
+        const prompt = this.loadPromptOnce(fileKey)
+            .replace(/\{\{personaDir\}\}/g, this.personaDir);
+        const stepIndex = STATE_NAMES.indexOf(snap.currentState);
+        const stepNum = stepIndex >= 0 ? stepIndex + 1 : 1;
+        const header = `\n[Bootstrap ${stepNum}/4]\n`;
+        return header + prompt;
+    }
+    // ── 内部 ──────────────────────────────────────────────────
+    loadPromptOnce(file) {
+        if (!this.stepPrompts.has(file)) {
+            this.stepPrompts.set(file, loadPrompt(`flows/${file}`));
+        }
+        return this.stepPrompts.get(file);
+    }
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/machine/flows/index.d.ts

@@ -0,0 +1,6 @@
+export { MachineRegistry } from '../registry.js';
+export type { FlowController } from './types.js';
+export { TodoFlow } from './todo.js';
+export { BootstrapFlow } from './bootstrap.js';
+export { createCompleteFlowStepTool, createActivateTodoTool, createAddTodoStepTool, isFlowTool, } from './tools.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/machine/flows/index.js

@@ -0,0 +1,11 @@
+// ============================================================
+// Flows — 桶导出
+// ============================================================
+// 从 machine 层透出（统一入口）
+export { MachineRegistry } from '../registry.js';
+// Flow 实现
+export { TodoFlow } from './todo.js';
+export { BootstrapFlow } from './bootstrap.js';
+// 工具
+export { createCompleteFlowStepTool, createActivateTodoTool, createAddTodoStepTool, isFlowTool, } from './tools.js';
+//# sourceMappingURL=index.js.map

package/dist/machine/flows/spec.d.ts

@@ -0,0 +1,17 @@
+import type { MachineContext, MachineSnapshot, AdvanceResult } from '../types.js';
+import { MachineRunner } from '../runner.js';
+import type { FlowController } from './types.js';
+export declare class SpecFlow implements FlowController {
+    readonly id = "spec";
+    readonly runner: MachineRunner;
+    private prompts;
+    constructor();
+    activate(context?: MachineContext): void;
+    deactivate(): void;
+    advance(event: string): AdvanceResult;
+    getSnapshot(): MachineSnapshot;
+    isComplete(): boolean;
+    getInjection(): string | null;
+    private loadPrompt;
+}
+//# sourceMappingURL=spec.d.ts.map