@zhin.js/agent 0.0.0

package/lib/follow-up.js

@@ -0,0 +1,265 @@
+/**
+ * FollowUpStore — 定时跟进任务的持久化存储
+ *
+ * 解决纯 setTimeout 重启即丢失的问题：
+ *   1. 创建任务时同步写入数据库
+ *   2. 执行完成 / 过期后从数据库中删除
+ *   3. 机器人启动时从数据库加载所有未完成任务，重新挂定时器
+ *   4. 同一会话创建新任务时，自动取消旧的 pending 任务（防止重复提醒）
+ *
+ *   ai_followups 表：
+ *   ┌──────────────────────────────────────────────────────────────────┐
+ *   │ id (PK)  | session_id | platform | sender_id | scene_id        │
+ *   │          | message    | fire_at  | created_at | status          │
+ *   └──────────────────────────────────────────────────────────────────┘
+ */
+import { Logger } from '@zhin.js/logger';
+const logger = new Logger(null, 'FollowUp');
+// ============================================================================
+// 数据库模型
+// ============================================================================
+export const AI_FOLLOWUP_MODEL = {
+    session_id: { type: 'text', nullable: false },
+    platform: { type: 'text', nullable: false },
+    bot_id: { type: 'text', nullable: false },
+    sender_id: { type: 'text', nullable: false },
+    scene_id: { type: 'text', nullable: false },
+    scene_type: { type: 'text', nullable: false },
+    message: { type: 'text', nullable: false },
+    /** 触发时间戳 (ms) */
+    fire_at: { type: 'integer', nullable: false },
+    created_at: { type: 'integer', default: 0 },
+    /** pending | fired | cancelled */
+    status: { type: 'text', default: 'pending' },
+};
+// ============================================================================
+// 内存实现
+// ============================================================================
+class MemoryFollowUpStore {
+    records = [];
+    nextId = 1;
+    async create(record) {
+        const full = { ...record, id: this.nextId++ };
+        this.records.push(full);
+        return full;
+    }
+    async markFired(id) {
+        const r = this.records.find(r => r.id === id);
+        if (r)
+            r.status = 'fired';
+    }
+    async cancel(id) {
+        const r = this.records.find(r => r.id === id);
+        if (r)
+            r.status = 'cancelled';
+    }
+    async getPending() {
+        return this.records.filter(r => r.status === 'pending');
+    }
+    async getPendingBySession(sessionId) {
+        return this.records.filter(r => r.status === 'pending' && r.session_id === sessionId);
+    }
+    dispose() {
+        this.records = [];
+    }
+}
+// ============================================================================
+// 数据库实现
+// ============================================================================
+class DatabaseFollowUpStore {
+    model;
+    constructor(model) {
+        this.model = model;
+    }
+    async create(record) {
+        const created = await this.model.create(record);
+        return { ...record, id: created.id ?? created };
+    }
+    async markFired(id) {
+        await this.model.update({ status: 'fired' }).where({ id });
+    }
+    async cancel(id) {
+        await this.model.update({ status: 'cancelled' }).where({ id });
+    }
+    async getPending() {
+        return this.model.select().where({ status: 'pending' });
+    }
+    async getPendingBySession(sessionId) {
+        return this.model.select().where({ status: 'pending', session_id: sessionId });
+    }
+    dispose() { }
+}
+// ============================================================================
+// FollowUpManager
+// ============================================================================
+export class FollowUpManager {
+    store;
+    /** 内存中活跃的定时器: recordId → timer */
+    timers = new Map();
+    sender = null;
+    constructor() {
+        this.store = new MemoryFollowUpStore();
+    }
+    /** 注入消息发送回调 */
+    setSender(sender) {
+        this.sender = sender;
+    }
+    /** 升级到数据库存储 */
+    upgradeToDatabase(model) {
+        const old = this.store;
+        this.store = new DatabaseFollowUpStore(model);
+        old.dispose();
+        logger.debug('FollowUpManager: 已升级到数据库存储');
+    }
+    /**
+     * 创建一个跟进任务
+     *
+     * 重要：同一会话的旧 pending 任务会被自动取消，防止重复提醒。
+     *
+     * @returns 人类可读的确认文本
+     */
+    async schedule(params) {
+        const { sessionId, platform, botId, senderId, sceneId, sceneType, message, delayMinutes } = params;
+        // ── 详细参数日志（方便排查问题） ──
+        logger.debug(`[跟进] 收到请求: delay_minutes=${delayMinutes}, message="${message}", session=${sessionId}`);
+        // 限制最大延迟 7 天
+        const maxDelay = 7 * 24 * 60;
+        const actualDelay = Math.min(Math.max(delayMinutes, 1), maxDelay);
+        const delayMs = actualDelay * 60 * 1000;
+        const fireAt = Date.now() + delayMs;
+        // ── 自动取消同一会话的旧 pending 任务 ──
+        const existingPending = await this.store.getPendingBySession(sessionId);
+        if (existingPending.length > 0) {
+            for (const old of existingPending) {
+                if (old.id != null) {
+                    // 取消数据库记录
+                    await this.store.cancel(old.id);
+                    // 清除内存中的定时器
+                    const timer = this.timers.get(old.id);
+                    if (timer) {
+                        clearTimeout(timer);
+                        this.timers.delete(old.id);
+                    }
+                    logger.debug(`[跟进] 自动取消旧任务: id=${old.id}, "${old.message}"`);
+                }
+            }
+        }
+        const record = await this.store.create({
+            session_id: sessionId,
+            platform,
+            bot_id: botId,
+            sender_id: senderId,
+            scene_id: sceneId,
+            scene_type: sceneType,
+            message,
+            fire_at: fireAt,
+            created_at: Date.now(),
+            status: 'pending',
+        });
+        // 挂定时器
+        this.scheduleTimer(record);
+        const readableTime = actualDelay >= 1440
+            ? `${(actualDelay / 1440).toFixed(1)} 天后`
+            : actualDelay >= 60
+                ? `${(actualDelay / 60).toFixed(1)} 小时后`
+                : `${actualDelay} 分钟后`;
+        // 精确触发时间（方便日志对照）
+        const fireDate = new Date(fireAt);
+        const fireTimeStr = fireDate.toLocaleString('zh-CN', { hour12: false });
+        logger.debug(`[跟进] 已创建: id=${record.id}, delay=${actualDelay}分钟(${delayMs}ms), 触发时间=${fireTimeStr}, "${message}"`);
+        return `✅ 已安排提醒，将在 ${readableTime}（${fireTimeStr}）提醒你：${message}`;
+    }
+    /**
+     * 取消指定会话的所有 pending 任务
+     */
+    async cancelBySession(sessionId) {
+        const pending = await this.store.getPendingBySession(sessionId);
+        let count = 0;
+        for (const record of pending) {
+            if (record.id != null) {
+                await this.store.cancel(record.id);
+                const timer = this.timers.get(record.id);
+                if (timer) {
+                    clearTimeout(timer);
+                    this.timers.delete(record.id);
+                }
+                count++;
+            }
+        }
+        if (count > 0) {
+            logger.debug(`[跟进] 已取消 ${count} 个待执行任务 (session=${sessionId})`);
+        }
+        return count;
+    }
+    /**
+     * 启动时从数据库恢复所有未完成的跟进任务
+     */
+    async restore() {
+        const pending = await this.store.getPending();
+        const now = Date.now();
+        let restored = 0;
+        for (const record of pending) {
+            if (record.fire_at <= now) {
+                // 已过期但未执行 → 立即触发（延迟 2 秒，等系统完全就绪）
+                const overdueSec = Math.round((now - record.fire_at) / 1000);
+                logger.debug(`[跟进恢复] id=${record.id} 已过期 ${overdueSec}s，立即触发`);
+                this.scheduleTimerWithDelay(record, 2000);
+                restored++;
+            }
+            else {
+                // 还没到时间 → 重新挂定时器
+                this.scheduleTimer(record);
+                const remainMs = record.fire_at - now;
+                const remainMin = (remainMs / 60_000).toFixed(1);
+                logger.debug(`[跟进恢复] id=${record.id} 剩余 ${remainMin} 分钟, "${record.message}"`);
+                restored++;
+            }
+        }
+        if (restored > 0) {
+            logger.info(`[跟进恢复] 共恢复 ${restored} 个待执行任务`);
+        }
+        return restored;
+    }
+    /**
+     * 为一条记录挂定时器
+     */
+    scheduleTimer(record) {
+        const delay = Math.max(record.fire_at - Date.now(), 0);
+        this.scheduleTimerWithDelay(record, delay);
+    }
+    scheduleTimerWithDelay(record, delayMs) {
+        if (!record.id)
+            return;
+        // 清除旧定时器（如果有）
+        const existing = this.timers.get(record.id);
+        if (existing)
+            clearTimeout(existing);
+        const timer = setTimeout(async () => {
+            try {
+                this.timers.delete(record.id);
+                // 发送提醒
+                if (this.sender) {
+                    await this.sender(record);
+                    logger.info(`[跟进提醒] 已发送: id=${record.id}, "${record.message}"`);
+                }
+                else {
+                    logger.warn(`[跟进提醒] 无法发送 (sender 未注入): id=${record.id}`);
+                }
+                // 标记完成
+                await this.store.markFired(record.id);
+            }
+            catch (e) {
+                logger.warn(`[跟进提醒] 发送失败: id=${record.id}`, e);
+            }
+        }, delayMs);
+        this.timers.set(record.id, timer);
+    }
+    dispose() {
+        for (const timer of this.timers.values()) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
+        this.store.dispose();
+    }
+}
+//# sourceMappingURL=follow-up.js.map

package/lib/follow-up.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"follow-up.js","sourceRoot":"","sources":["../src/follow-up.ts"],"names":[],"mappings":"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"}

package/lib/hooks.d.ts

@@ -0,0 +1,143 @@
+/**
+ * AI Hooks — AI 生命周期事件钩子系统
+ *
+ * 借鉴 OpenClaw 的 Hooks 设计，提供可扩展的事件驱动钩子：
+ *
+ *   - message:received   — 收到消息时触发
+ *   - message:sent       — 发送消息时触发
+ *   - session:compact    — 会话压缩时触发
+ *   - session:new        — 新建会话时触发
+ *   - agent:bootstrap    — Agent 初始化时触发
+ *   - agent:tool-call    — 工具调用时触发
+ *
+ * 钩子按注册顺序执行，错误不会中断其他钩子。
+ */
+/** 事件类型 */
+export type AIHookEventType = 'message' | 'session' | 'agent' | 'tool';
+/** Hook 事件基础接口 */
+export interface AIHookEvent {
+    /** 事件类型 */
+    type: AIHookEventType;
+    /** 具体动作 */
+    action: string;
+    /** 会话标识 */
+    sessionId?: string;
+    /** 附加上下文 */
+    context: Record<string, unknown>;
+    /** 事件时间戳 */
+    timestamp: Date;
+    /** 钩子可以推送消息到这个数组 */
+    messages: string[];
+}
+/** 消息接收事件 */
+export interface MessageReceivedEvent extends AIHookEvent {
+    type: 'message';
+    action: 'received';
+    context: {
+        from: string;
+        content: string;
+        platform: string;
+        channelId?: string;
+        messageId?: string;
+    };
+}
+/** 消息发送事件 */
+export interface MessageSentEvent extends AIHookEvent {
+    type: 'message';
+    action: 'sent';
+    context: {
+        to: string;
+        content: string;
+        success: boolean;
+        error?: string;
+        platform: string;
+    };
+}
+/** 会话压缩事件 */
+export interface SessionCompactEvent extends AIHookEvent {
+    type: 'session';
+    action: 'compact';
+    context: {
+        compactedCount: number;
+        savedTokens: number;
+        summary: string;
+    };
+}
+/** 会话新建事件 */
+export interface SessionNewEvent extends AIHookEvent {
+    type: 'session';
+    action: 'new';
+    context: {
+        previousSessionId?: string;
+    };
+}
+/** Agent 初始化事件 */
+export interface AgentBootstrapEvent extends AIHookEvent {
+    type: 'agent';
+    action: 'bootstrap';
+    context: {
+        workspaceDir: string;
+        toolCount: number;
+        skillCount: number;
+        bootstrapFiles: string[];
+    };
+}
+/** 工具调用事件 */
+export interface ToolCallEvent extends AIHookEvent {
+    type: 'tool';
+    action: 'call';
+    context: {
+        toolName: string;
+        args: Record<string, unknown>;
+        result?: string;
+        durationMs?: number;
+        success: boolean;
+        error?: string;
+    };
+}
+/** Hook 处理函数 */
+export type AIHookHandler = (event: AIHookEvent) => Promise<void> | void;
+/**
+ * 注册 Hook 处理函数
+ *
+ * @param eventKey - 事件类型（如 'message'）或具体动作（如 'message:received'）
+ * @param handler - 处理函数
+ *
+ * @example
+ * ```ts
+ * // 监听所有消息事件
+ * registerAIHook('message', async (event) => {
+ *   console.log('消息事件:', event.action);
+ * });
+ *
+ * // 只监听消息接收
+ * registerAIHook('message:received', async (event) => {
+ *   console.log('收到消息:', event.context.content);
+ * });
+ * ```
+ */
+export declare function registerAIHook(eventKey: string, handler: AIHookHandler): () => void;
+/**
+ * 注销 Hook 处理函数
+ */
+export declare function unregisterAIHook(eventKey: string, handler: AIHookHandler): void;
+/**
+ * 清除所有 Hook（测试用）
+ */
+export declare function clearAIHooks(): void;
+/**
+ * 获取已注册的事件 key 列表（调试用）
+ */
+export declare function getRegisteredAIHookKeys(): string[];
+/**
+ * 触发 Hook 事件
+ *
+ * 同时调用通用类型（如 'message'）和具体动作（如 'message:received'）的处理函数。
+ * 处理函数按注册顺序执行，错误被捕获并记录，不影响其他处理函数。
+ */
+export declare function triggerAIHook(event: AIHookEvent): Promise<void>;
+/**
+ * 创建 Hook 事件（辅助函数）
+ */
+export declare function createAIHookEvent(type: AIHookEventType, action: string, sessionId?: string, context?: Record<string, unknown>): AIHookEvent;
+//# sourceMappingURL=hooks.d.ts.map

package/lib/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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"}

package/lib/hooks.js

@@ -0,0 +1,108 @@
+/**
+ * AI Hooks — AI 生命周期事件钩子系统
+ *
+ * 借鉴 OpenClaw 的 Hooks 设计，提供可扩展的事件驱动钩子：
+ *
+ *   - message:received   — 收到消息时触发
+ *   - message:sent       — 发送消息时触发
+ *   - session:compact    — 会话压缩时触发
+ *   - session:new        — 新建会话时触发
+ *   - agent:bootstrap    — Agent 初始化时触发
+ *   - agent:tool-call    — 工具调用时触发
+ *
+ * 钩子按注册顺序执行，错误不会中断其他钩子。
+ */
+import { Logger } from '@zhin.js/logger';
+const logger = new Logger(null, 'AI-Hooks');
+// ============================================================================
+// Hook 管理器
+// ============================================================================
+/** 按事件 key 存储的处理函数注册表 */
+const handlers = new Map();
+/**
+ * 注册 Hook 处理函数
+ *
+ * @param eventKey - 事件类型（如 'message'）或具体动作（如 'message:received'）
+ * @param handler - 处理函数
+ *
+ * @example
+ * ```ts
+ * // 监听所有消息事件
+ * registerAIHook('message', async (event) => {
+ *   console.log('消息事件:', event.action);
+ * });
+ *
+ * // 只监听消息接收
+ * registerAIHook('message:received', async (event) => {
+ *   console.log('收到消息:', event.context.content);
+ * });
+ * ```
+ */
+export function registerAIHook(eventKey, handler) {
+    if (!handlers.has(eventKey)) {
+        handlers.set(eventKey, []);
+    }
+    handlers.get(eventKey).push(handler);
+    // 返回注销函数
+    return () => unregisterAIHook(eventKey, handler);
+}
+/**
+ * 注销 Hook 处理函数
+ */
+export function unregisterAIHook(eventKey, handler) {
+    const eventHandlers = handlers.get(eventKey);
+    if (!eventHandlers)
+        return;
+    const index = eventHandlers.indexOf(handler);
+    if (index !== -1)
+        eventHandlers.splice(index, 1);
+    if (eventHandlers.length === 0)
+        handlers.delete(eventKey);
+}
+/**
+ * 清除所有 Hook（测试用）
+ */
+export function clearAIHooks() {
+    handlers.clear();
+}
+/**
+ * 获取已注册的事件 key 列表（调试用）
+ */
+export function getRegisteredAIHookKeys() {
+    return Array.from(handlers.keys());
+}
+/**
+ * 触发 Hook 事件
+ *
+ * 同时调用通用类型（如 'message'）和具体动作（如 'message:received'）的处理函数。
+ * 处理函数按注册顺序执行，错误被捕获并记录，不影响其他处理函数。
+ */
+export async function triggerAIHook(event) {
+    const typeHandlers = handlers.get(event.type) ?? [];
+    const specificHandlers = handlers.get(`${event.type}:${event.action}`) ?? [];
+    const allHandlers = [...typeHandlers, ...specificHandlers];
+    if (allHandlers.length === 0)
+        return;
+    for (const handler of allHandlers) {
+        try {
+            await handler(event);
+        }
+        catch (err) {
+            logger.error(`Hook 错误 [${event.type}:${event.action}]: ${err.message}`);
+        }
+    }
+}
+/**
+ * 创建 Hook 事件（辅助函数）
+ */
+export function createAIHookEvent(type, action, sessionId, context = {}) {
+    return {
+        type,
+        action,
+        sessionId,
+        context,
+        timestamp: new Date(),
+        messages: [],
+    };
+}
+//# sourceMappingURL=hooks.js.map

package/lib/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAEzC,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AAwG5C,+EAA+E;AAC/E,WAAW;AACX,+EAA+E;AAE/E,yBAAyB;AACzB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;AAEpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,OAAsB;IACrE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC7B,CAAC;IACD,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAEtC,SAAS;IACT,OAAO,GAAG,EAAE,CAAC,gBAAgB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,OAAsB;IACvE,MAAM,aAAa,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,CAAC,aAAa;QAAE,OAAO;IAE3B,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,aAAa,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACjD,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;QAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC5D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY;IAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,uBAAuB;IACrC,OAAO,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;AACrC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAkB;IACpD,MAAM,YAAY,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACpD,MAAM,gBAAgB,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC;IAC7E,MAAM,WAAW,GAAG,CAAC,GAAG,YAAY,EAAE,GAAG,gBAAgB,CAAC,CAAC;IAE3D,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAErC,KAAK,MAAM,OAAO,IAAI,WAAW,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,MAAM,CAAC,KAAK,CAAC,YAAY,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAqB,EACrB,MAAc,EACd,SAAkB,EAClB,UAAmC,EAAE;IAErC,OAAO;QACL,IAAI;QACJ,MAAM;QACN,SAAS;QACT,OAAO;QACP,SAAS,EAAE,IAAI,IAAI,EAAE;QACrB,QAAQ,EAAE,EAAE;KACb,CAAC;AACJ,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @zhin.js/agent — AI Agent composition
+ * Composes providers, tools, skills from @zhin.js/core into session, ZhinAgent, init.
+ */
+export type { AIConfig, AIProvider, ChatMessage, ContentPart, AgentTool, AgentConfig, AgentResult, } from '@zhin.js/core';
+export { Agent, createAgent, formatToolTitle } from './agent.js';
+export type { AgentState, AgentEvents } from './agent.js';
+export { AIService } from './service.js';
+export { SessionManager, MemorySessionManager, DatabaseSessionManager, createMemorySessionManager, createDatabaseSessionManager, AI_SESSION_MODEL, } from './session.js';
+export { ContextManager, createContextManager, CHAT_MESSAGE_MODEL, CONTEXT_SUMMARY_MODEL, } from './context-manager.js';
+export type { ContextConfig, MessageRecord } from './context-manager.js';
+export { ZhinAgent } from './zhin-agent/index.js';
+export type { ZhinAgentConfig, OnChunkCallback } from './zhin-agent/index.js';
+export { PERM_MAP, DEFAULT_CONFIG as ZHIN_AGENT_DEFAULT_CONFIG, SECTION_SEP } from './zhin-agent/config.js';
+export { checkExecPolicy, applyExecPolicyToTools, resolveExecAllowlist, EXEC_PRESETS } from './zhin-agent/exec-policy.js';
+export { collectRelevantTools, toAgentTool } from './zhin-agent/tool-collector.js';
+export { buildRichSystemPrompt, buildContextHint, buildEnhancedPersona, buildUserMessageWithHistory, contentToText } from './zhin-agent/prompt.js';
+export type { RichSystemPromptContext } from './zhin-agent/prompt.js';
+export { createChatHistoryTool, createUserProfileTool, createScheduleFollowUpTool, createSpawnTaskTool } from './zhin-agent/builtin-tools.js';
+export { ConversationMemory, AI_MESSAGE_MODEL, AI_SUMMARY_MODEL, } from './conversation-memory.js';
+export type { ConversationMemoryConfig } from './conversation-memory.js';
+export { UserProfileStore, AI_USER_PROFILE_MODEL } from './user-profile.js';
+export { RateLimiter } from './rate-limiter.js';
+export type { RateLimitConfig, RateLimitResult } from './rate-limiter.js';
+export { FollowUpManager, AI_FOLLOWUP_MODEL } from './follow-up.js';
+export type { FollowUpRecord, FollowUpSender } from './follow-up.js';
+export { SubagentManager } from './subagent.js';
+export type { SubagentOrigin, SubagentResultSender, SpawnOptions, SubagentManagerOptions, } from './subagent.js';
+export { PersistentCronEngine, readCronJobsFile, writeCronJobsFile, getCronJobsFilePath, generateCronJobId, createCronTools, setCronManager, getCronManager, CRON_JOBS_FILENAME, } from './cron-engine.js';
+export type { CronJobRecord, CronRunner, AddCronFn, PersistentCronEngineOptions, CronManager, } from './cron-engine.js';
+export { estimateTokens, estimateMessagesTokens, splitMessagesByTokenShare, chunkMessagesByMaxTokens, computeAdaptiveChunkRatio, resolveContextWindowTokens, evaluateContextWindowGuard, summarizeWithFallback, summarizeInStages, pruneHistoryForContext, compactSession, DEFAULT_CONTEXT_TOKENS, } from './compaction.js';
+export type { ContextWindowSource, ContextWindowInfo, ContextWindowGuardResult, PruneResult } from './compaction.js';
+export { loadBootstrapFiles, buildContextFiles, buildBootstrapContextSection, loadSoulPersona, loadToolsGuide, loadAgentsMemory, clearBootstrapCache, } from './bootstrap.js';
+export type { BootstrapFile, ContextFile } from './bootstrap.js';
+export { registerAIHook, unregisterAIHook, triggerAIHook, createAIHookEvent, clearAIHooks, getRegisteredAIHookKeys, } from './hooks.js';
+export type { AIHookEvent, AIHookEventType, AIHookHandler, MessageReceivedEvent, MessageSentEvent, SessionCompactEvent, SessionNewEvent, AgentBootstrapEvent, ToolCallEvent, } from './hooks.js';
+export { detectTone } from './tone-detector.js';
+export type { Tone } from './tone-detector.js';
+export { parseOutput, renderToPlainText, renderToSatori, } from './output.js';
+export type { OutputElement, TextElement, ImageElement, AudioElement, VideoElement, CardElement, FileElement, CardField, CardButton, } from './output.js';
+export { calculatorTool, timeTool, searchTool, codeRunnerTool, httpTool, memoryTool, getBuiltinTools, getAllBuiltinTools, } from './tools.js';
+export { initAgentModule } from './init.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/index.js

@@ -0,0 +1,28 @@
+/**
+ * @zhin.js/agent — AI Agent composition
+ * Composes providers, tools, skills from @zhin.js/core into session, ZhinAgent, init.
+ */
+export { Agent, createAgent, formatToolTitle } from './agent.js';
+export { AIService } from './service.js';
+export { SessionManager, MemorySessionManager, DatabaseSessionManager, createMemorySessionManager, createDatabaseSessionManager, AI_SESSION_MODEL, } from './session.js';
+export { ContextManager, createContextManager, CHAT_MESSAGE_MODEL, CONTEXT_SUMMARY_MODEL, } from './context-manager.js';
+export { ZhinAgent } from './zhin-agent/index.js';
+export { PERM_MAP, DEFAULT_CONFIG as ZHIN_AGENT_DEFAULT_CONFIG, SECTION_SEP } from './zhin-agent/config.js';
+export { checkExecPolicy, applyExecPolicyToTools, resolveExecAllowlist, EXEC_PRESETS } from './zhin-agent/exec-policy.js';
+export { collectRelevantTools, toAgentTool } from './zhin-agent/tool-collector.js';
+export { buildRichSystemPrompt, buildContextHint, buildEnhancedPersona, buildUserMessageWithHistory, contentToText } from './zhin-agent/prompt.js';
+export { createChatHistoryTool, createUserProfileTool, createScheduleFollowUpTool, createSpawnTaskTool } from './zhin-agent/builtin-tools.js';
+export { ConversationMemory, AI_MESSAGE_MODEL, AI_SUMMARY_MODEL, } from './conversation-memory.js';
+export { UserProfileStore, AI_USER_PROFILE_MODEL } from './user-profile.js';
+export { RateLimiter } from './rate-limiter.js';
+export { FollowUpManager, AI_FOLLOWUP_MODEL } from './follow-up.js';
+export { SubagentManager } from './subagent.js';
+export { PersistentCronEngine, readCronJobsFile, writeCronJobsFile, getCronJobsFilePath, generateCronJobId, createCronTools, setCronManager, getCronManager, CRON_JOBS_FILENAME, } from './cron-engine.js';
+export { estimateTokens, estimateMessagesTokens, splitMessagesByTokenShare, chunkMessagesByMaxTokens, computeAdaptiveChunkRatio, resolveContextWindowTokens, evaluateContextWindowGuard, summarizeWithFallback, summarizeInStages, pruneHistoryForContext, compactSession, DEFAULT_CONTEXT_TOKENS, } from './compaction.js';
+export { loadBootstrapFiles, buildContextFiles, buildBootstrapContextSection, loadSoulPersona, loadToolsGuide, loadAgentsMemory, clearBootstrapCache, } from './bootstrap.js';
+export { registerAIHook, unregisterAIHook, triggerAIHook, createAIHookEvent, clearAIHooks, getRegisteredAIHookKeys, } from './hooks.js';
+export { detectTone } from './tone-detector.js';
+export { parseOutput, renderToPlainText, renderToSatori, } from './output.js';
+export { calculatorTool, timeTool, searchTool, codeRunnerTool, httpTool, memoryTool, getBuiltinTools, getAllBuiltinTools, } from './tools.js';
+export { initAgentModule } from './init.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGjE,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,4BAA4B,EAC5B,gBAAgB,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD,OAAO,EAAE,QAAQ,EAAE,cAAc,IAAI,yBAAyB,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC5G,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC1H,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AACnF,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEnJ,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAE9I,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE5E,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGpE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAQhD,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,EACd,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAS1B,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,EAC1B,qBAAqB,EACrB,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACd,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,4BAA4B,EAC5B,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,uBAAuB,GACxB,MAAM,YAAY,CAAC;AAapB,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAGhD,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,cAAc,GACf,MAAM,aAAa,CAAC;AAarB,OAAO,EACL,cAAc,EACd,QAAQ,EACR,UAAU,EACV,cAAc,EACd,QAAQ,EACR,UAAU,EACV,eAAe,EACf,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}