@gt-fe/eap-runtime 0.0.8

package/dist/task/index.js

@@ -0,0 +1,5 @@
+// Task Module — 任务生命周期管理
+export * from './contracts/index.js';
+export { TaskService, InMemoryTaskRepository } from './task.service.js';
+export { TaskTimeoutManager } from './task-timeout.js';
+export { TaskProgressTracker } from './task-progress-tracker.js';

package/dist/task/pg-task.repository.d.ts

@@ -0,0 +1,47 @@
+/**
+ * PostgresTaskRepository — Task 持久化 PostgreSQL 实现
+ *
+ * 基于 pg 连接池实现 ITaskRepository 接口。
+ * JSON 字段（input, output, token_usage）使用 JSONB 类型存储。
+ * 支持审计字段和软删除。
+ *
+ * @see design.md §1.3 数据模型 — tasks 表
+ * @see task.service.ts ITaskRepository 接口定义
+ */
+import type { TaskRecord } from './contracts/task-manager.contract.js';
+import type { ITaskRepository } from './task.service.js';
+/** pg Pool 抽象接口 */
+export interface IPgPool {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+}
+export declare class PostgresTaskRepository implements ITaskRepository {
+    private readonly pool;
+    constructor(pool: IPgPool);
+    /**
+     * INSERT task record with all fields including audit fields
+     */
+    save(task: TaskRecord): Promise<void>;
+    /**
+     * SELECT task by id, deserialize JSON fields
+     * Excludes soft-deleted records
+     */
+    findById(id: string): Promise<TaskRecord | null>;
+    /**
+     * UPDATE all mutable fields by id
+     */
+    update(task: TaskRecord): Promise<void>;
+    /**
+     * Soft delete task
+     */
+    softDelete(id: string, deletedBy: string): Promise<void>;
+    /**
+     * 将 PostgreSQL 行数据转换为 TaskRecord
+     */
+    private rowToRecord;
+    /**
+     * 解析 JSON 字段 — pg 可能已自动解析 JSONB 列，也可能返回字符串
+     */
+    private parseJson;
+}

package/dist/task/pg-task.repository.js

@@ -0,0 +1,131 @@
+/**
+ * PostgresTaskRepository — Task 持久化 PostgreSQL 实现
+ *
+ * 基于 pg 连接池实现 ITaskRepository 接口。
+ * JSON 字段（input, output, token_usage）使用 JSONB 类型存储。
+ * 支持审计字段和软删除。
+ *
+ * @see design.md §1.3 数据模型 — tasks 表
+ * @see task.service.ts ITaskRepository 接口定义
+ */
+// ─────────────────────────────────────────────
+// PostgresTaskRepository
+// ─────────────────────────────────────────────
+export class PostgresTaskRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * INSERT task record with all fields including audit fields
+     */
+    async save(task) {
+        const sql = `
+      INSERT INTO tasks (id, agent_id, session_id, user_id, correlation_id, input, output, status, trace_id, token_usage, cost, started_at, completed_at, created_by, created_at, updated_by, updated_at)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16, $17)
+    `;
+        await this.pool.query(sql, [
+            task.id,
+            task.agentId,
+            task.sessionId,
+            task.userId,
+            task.correlationId,
+            JSON.stringify(task.input),
+            task.output != null ? JSON.stringify(task.output) : null,
+            task.status,
+            task.traceId,
+            JSON.stringify(task.tokenUsage),
+            task.cost,
+            task.startedAt,
+            task.completedAt,
+            task.createdBy || 'system',
+            task.createdAt,
+            task.updatedBy || 'system',
+            task.updatedAt,
+        ]);
+    }
+    /**
+     * SELECT task by id, deserialize JSON fields
+     * Excludes soft-deleted records
+     */
+    async findById(id) {
+        const sql = `SELECT * FROM tasks WHERE id = $1 AND is_deleted = FALSE`;
+        const { rows } = await this.pool.query(sql, [id]);
+        if (rows.length === 0) {
+            return null;
+        }
+        return this.rowToRecord(rows[0]);
+    }
+    /**
+     * UPDATE all mutable fields by id
+     */
+    async update(task) {
+        const sql = `
+      UPDATE tasks
+      SET output = $1, status = $2, trace_id = $3, token_usage = $4, cost = $5, started_at = $6, completed_at = $7, updated_by = $8, updated_at = $9
+      WHERE id = $10 AND is_deleted = FALSE
+    `;
+        await this.pool.query(sql, [
+            task.output != null ? JSON.stringify(task.output) : null,
+            task.status,
+            task.traceId,
+            JSON.stringify(task.tokenUsage),
+            task.cost,
+            task.startedAt,
+            task.completedAt,
+            task.updatedBy || 'system',
+            task.updatedAt,
+            task.id,
+        ]);
+    }
+    /**
+     * Soft delete task
+     */
+    async softDelete(id, deletedBy) {
+        const sql = `
+      UPDATE tasks
+      SET is_deleted = TRUE, deleted_by = $1, deleted_at = NOW()
+      WHERE id = $2 AND is_deleted = FALSE
+    `;
+        await this.pool.query(sql, [deletedBy, id]);
+    }
+    // ─────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────
+    /**
+     * 将 PostgreSQL 行数据转换为 TaskRecord
+     */
+    rowToRecord(row) {
+        return {
+            id: row.id,
+            agentId: row.agent_id,
+            sessionId: row.session_id,
+            userId: row.user_id,
+            correlationId: row.correlation_id,
+            input: this.parseJson(row.input),
+            output: row.output != null ? this.parseJson(row.output) : null,
+            status: row.status,
+            traceId: row.trace_id,
+            tokenUsage: this.parseJson(row.token_usage),
+            cost: parseFloat(String(row.cost)),
+            startedAt: row.started_at ? row.started_at.toISOString() : null,
+            completedAt: row.completed_at ? row.completed_at.toISOString() : null,
+            createdBy: row.created_by,
+            createdAt: row.created_at.toISOString(),
+            updatedBy: row.updated_by,
+            updatedAt: row.updated_at.toISOString(),
+            isDeleted: row.is_deleted,
+            deletedBy: row.deleted_by,
+            deletedAt: row.deleted_at?.toISOString(),
+        };
+    }
+    /**
+     * 解析 JSON 字段 — pg 可能已自动解析 JSONB 列，也可能返回字符串
+     */
+    parseJson(value) {
+        if (typeof value === 'string') {
+            return JSON.parse(value);
+        }
+        return value;
+    }
+}

package/dist/task/task-progress-tracker.d.ts

@@ -0,0 +1,67 @@
+/**
+ * TaskProgressTracker — 长任务细粒度进度跟踪
+ *
+ * 支持两种进度模式：
+ * 1. 显式设置：调用方直接 updateProgress(taskId, progress)
+ * 2. 基于 Graph 节点：根据已完成节点 / 总节点数自动计算
+ *
+ * 当没有显式进度时，TaskService.getStatus() 回退到基于状态的粗粒度计算。
+ *
+ * @see requirements.md Requirement 7 AC5
+ * @see design.md §1.1 长任务支持
+ */
+/**
+ * 单个 Task 的进度信息
+ */
+export interface TaskProgressInfo {
+    /** 当前进度百分比 (0-100) */
+    progress: number;
+    /** 已完成的节点数 */
+    completedNodes: number;
+    /** 总节点数 */
+    totalNodes: number;
+    /** 最后更新时间 (ISO 8601) */
+    updatedAt: string;
+}
+/**
+ * TaskProgressTracker — 内存进度跟踪器
+ *
+ * 用于 Graph 执行过程中跟踪任务进度，供 getStatus() 返回细粒度进度。
+ */
+export declare class TaskProgressTracker {
+    private readonly progressMap;
+    /**
+     * 设置显式进度百分比
+     *
+     * @param taskId - Task ID
+     * @param progress - 进度百分比 (0-100)，会被 clamp 到合法范围
+     */
+    updateProgress(taskId: string, progress: number): void;
+    /**
+     * 基于 Graph 节点执行进度更新
+     *
+     * 根据 completedNodes / totalNodes 自动计算百分比。
+     *
+     * @param taskId - Task ID
+     * @param completedNodes - 已完成的节点数
+     * @param totalNodes - Graph 中总节点数
+     */
+    updateNodeProgress(taskId: string, completedNodes: number, totalNodes: number): void;
+    /**
+     * 获取 Task 的进度信息
+     *
+     * @param taskId - Task ID
+     * @returns 进度信息，若未跟踪则返回 null
+     */
+    getProgress(taskId: string): TaskProgressInfo | null;
+    /**
+     * 移除 Task 的进度跟踪（Task 结束后清理）
+     *
+     * @param taskId - Task ID
+     */
+    removeProgress(taskId: string): void;
+    /**
+     * 清空所有进度跟踪数据（测试用）
+     */
+    clear(): void;
+}

package/dist/task/task-progress-tracker.js

@@ -0,0 +1,80 @@
+/**
+ * TaskProgressTracker — 长任务细粒度进度跟踪
+ *
+ * 支持两种进度模式：
+ * 1. 显式设置：调用方直接 updateProgress(taskId, progress)
+ * 2. 基于 Graph 节点：根据已完成节点 / 总节点数自动计算
+ *
+ * 当没有显式进度时，TaskService.getStatus() 回退到基于状态的粗粒度计算。
+ *
+ * @see requirements.md Requirement 7 AC5
+ * @see design.md §1.1 长任务支持
+ */
+/**
+ * TaskProgressTracker — 内存进度跟踪器
+ *
+ * 用于 Graph 执行过程中跟踪任务进度，供 getStatus() 返回细粒度进度。
+ */
+export class TaskProgressTracker {
+    progressMap = new Map();
+    /**
+     * 设置显式进度百分比
+     *
+     * @param taskId - Task ID
+     * @param progress - 进度百分比 (0-100)，会被 clamp 到合法范围
+     */
+    updateProgress(taskId, progress) {
+        const clamped = Math.max(0, Math.min(100, progress));
+        const existing = this.progressMap.get(taskId);
+        this.progressMap.set(taskId, {
+            progress: clamped,
+            completedNodes: existing?.completedNodes ?? 0,
+            totalNodes: existing?.totalNodes ?? 0,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    /**
+     * 基于 Graph 节点执行进度更新
+     *
+     * 根据 completedNodes / totalNodes 自动计算百分比。
+     *
+     * @param taskId - Task ID
+     * @param completedNodes - 已完成的节点数
+     * @param totalNodes - Graph 中总节点数
+     */
+    updateNodeProgress(taskId, completedNodes, totalNodes) {
+        if (totalNodes <= 0) {
+            return;
+        }
+        const progress = Math.round((completedNodes / totalNodes) * 100);
+        this.progressMap.set(taskId, {
+            progress: Math.max(0, Math.min(100, progress)),
+            completedNodes,
+            totalNodes,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    /**
+     * 获取 Task 的进度信息
+     *
+     * @param taskId - Task ID
+     * @returns 进度信息，若未跟踪则返回 null
+     */
+    getProgress(taskId) {
+        return this.progressMap.get(taskId) ?? null;
+    }
+    /**
+     * 移除 Task 的进度跟踪（Task 结束后清理）
+     *
+     * @param taskId - Task ID
+     */
+    removeProgress(taskId) {
+        this.progressMap.delete(taskId);
+    }
+    /**
+     * 清空所有进度跟踪数据（测试用）
+     */
+    clear() {
+        this.progressMap.clear();
+    }
+}

package/dist/task/task-timeout.d.ts

@@ -0,0 +1,70 @@
+/**
+ * TaskTimeoutManager — Task 超时检测管理器
+ *
+ * 管理 Task 执行超时：
+ * - 当 Task 进入 running 状态时启动计时器
+ * - 超时触发时通过 onTimeout 回调标记 Task 为 timeout 并终止 Graph 执行
+ * - 使用 AbortController/AbortSignal 模式传递取消信号
+ *
+ * @see design.md §1.1 任务管理 — Task级超时
+ * @see requirements.md Requirement 7 AC4
+ */
+/**
+ * TaskTimeoutManager 配置选项
+ */
+export interface TaskTimeoutManagerOptions {
+    /** 默认超时时间（毫秒），默认 60000 (60s) */
+    defaultTimeoutMs?: number;
+}
+/**
+ * TaskTimeoutManager — 管理 running 状态 Task 的超时计时器
+ *
+ * 使用方式：
+ * 1. Task 进入 running 时调用 startTimer() 启动倒计时
+ * 2. Task 正常完成时调用 clearTimer() 取消倒计时
+ * 3. 超时触发时执行 onTimeout 回调（标记 task 为 timeout + abort graph）
+ * 4. 服务关停时调用 dispose() 清理所有活跃计时器
+ */
+export declare class TaskTimeoutManager {
+    private readonly entries;
+    private readonly defaultTimeoutMs;
+    constructor(options?: TaskTimeoutManagerOptions);
+    /**
+     * 启动超时计时器
+     *
+     * @param taskId - Task ID
+     * @param timeoutMs - 超时时间（毫秒），若不传则使用默认值。上限 3600s。
+     * @param onTimeout - 超时触发时执行的回调（应标记 task 状态并终止 graph）
+     * @returns AbortSignal，供 Graph 执行引擎监听取消信号
+     * @throws 如果该 taskId 已存在活跃计时器
+     */
+    startTimer(taskId: string, timeoutMs: number | undefined, onTimeout: () => Promise<void>): AbortSignal;
+    /**
+     * 取消超时计时器（Task 正常完成时调用）
+     *
+     * @param taskId - Task ID
+     * @returns true 表示成功取消，false 表示该 taskId 无活跃计时器
+     */
+    clearTimer(taskId: string): boolean;
+    /**
+     * 获取指定 Task 的 AbortSignal（用于后续关联 Graph 执行取消）
+     *
+     * @param taskId - Task ID
+     * @returns AbortSignal 或 undefined（若无活跃计时器）
+     */
+    getAbortSignal(taskId: string): AbortSignal | undefined;
+    /**
+     * 检查指定 Task 是否有活跃的超时计时器
+     */
+    hasTimer(taskId: string): boolean;
+    /**
+     * 获取当前活跃计时器数量
+     */
+    get activeCount(): number;
+    /**
+     * 清理所有活跃计时器（graceful shutdown 时调用）
+     *
+     * 不会触发 onTimeout 回调，仅取消定时器和 abort 信号。
+     */
+    dispose(): void;
+}

package/dist/task/task-timeout.js

@@ -0,0 +1,116 @@
+/**
+ * TaskTimeoutManager — Task 超时检测管理器
+ *
+ * 管理 Task 执行超时：
+ * - 当 Task 进入 running 状态时启动计时器
+ * - 超时触发时通过 onTimeout 回调标记 Task 为 timeout 并终止 Graph 执行
+ * - 使用 AbortController/AbortSignal 模式传递取消信号
+ *
+ * @see design.md §1.1 任务管理 — Task级超时
+ * @see requirements.md Requirement 7 AC4
+ */
+// ─────────────────────────────────────────────
+// Default Constants
+// ─────────────────────────────────────────────
+/** 默认超时：60 秒 */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/** 最大允许超时：3600 秒（1 小时） */
+const MAX_TIMEOUT_MS = 3_600_000;
+// ─────────────────────────────────────────────
+// TaskTimeoutManager
+// ─────────────────────────────────────────────
+/**
+ * TaskTimeoutManager — 管理 running 状态 Task 的超时计时器
+ *
+ * 使用方式：
+ * 1. Task 进入 running 时调用 startTimer() 启动倒计时
+ * 2. Task 正常完成时调用 clearTimer() 取消倒计时
+ * 3. 超时触发时执行 onTimeout 回调（标记 task 为 timeout + abort graph）
+ * 4. 服务关停时调用 dispose() 清理所有活跃计时器
+ */
+export class TaskTimeoutManager {
+    entries = new Map();
+    defaultTimeoutMs;
+    constructor(options) {
+        this.defaultTimeoutMs = options?.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    /**
+     * 启动超时计时器
+     *
+     * @param taskId - Task ID
+     * @param timeoutMs - 超时时间（毫秒），若不传则使用默认值。上限 3600s。
+     * @param onTimeout - 超时触发时执行的回调（应标记 task 状态并终止 graph）
+     * @returns AbortSignal，供 Graph 执行引擎监听取消信号
+     * @throws 如果该 taskId 已存在活跃计时器
+     */
+    startTimer(taskId, timeoutMs, onTimeout) {
+        if (this.entries.has(taskId)) {
+            throw new Error(`Timeout timer already exists for task '${taskId}'. Call clearTimer() first.`);
+        }
+        const effectiveTimeout = Math.min(Math.max(timeoutMs ?? this.defaultTimeoutMs, 0), MAX_TIMEOUT_MS);
+        const abortController = new AbortController();
+        const timer = setTimeout(() => {
+            // 超时触发：abort signal + 执行回调
+            abortController.abort(new Error(`Task '${taskId}' timed out after ${effectiveTimeout}ms`));
+            this.entries.delete(taskId);
+            // 触发外部回调（fire-and-forget，错误不应阻塞清理）
+            void onTimeout().catch(() => {
+                // onTimeout 回调的错误由调用方处理，这里静默忽略
+            });
+        }, effectiveTimeout);
+        // 防止 timer 阻止进程退出
+        if (timer.unref) {
+            timer.unref();
+        }
+        this.entries.set(taskId, { timer, abortController });
+        return abortController.signal;
+    }
+    /**
+     * 取消超时计时器（Task 正常完成时调用）
+     *
+     * @param taskId - Task ID
+     * @returns true 表示成功取消，false 表示该 taskId 无活跃计时器
+     */
+    clearTimer(taskId) {
+        const entry = this.entries.get(taskId);
+        if (!entry) {
+            return false;
+        }
+        clearTimeout(entry.timer);
+        this.entries.delete(taskId);
+        return true;
+    }
+    /**
+     * 获取指定 Task 的 AbortSignal（用于后续关联 Graph 执行取消）
+     *
+     * @param taskId - Task ID
+     * @returns AbortSignal 或 undefined（若无活跃计时器）
+     */
+    getAbortSignal(taskId) {
+        return this.entries.get(taskId)?.abortController.signal;
+    }
+    /**
+     * 检查指定 Task 是否有活跃的超时计时器
+     */
+    hasTimer(taskId) {
+        return this.entries.has(taskId);
+    }
+    /**
+     * 获取当前活跃计时器数量
+     */
+    get activeCount() {
+        return this.entries.size;
+    }
+    /**
+     * 清理所有活跃计时器（graceful shutdown 时调用）
+     *
+     * 不会触发 onTimeout 回调，仅取消定时器和 abort 信号。
+     */
+    dispose() {
+        for (const [taskId, entry] of this.entries) {
+            clearTimeout(entry.timer);
+            entry.abortController.abort(new Error(`TaskTimeoutManager disposed, task '${taskId}' aborted`));
+        }
+        this.entries.clear();
+    }
+}

package/dist/task/task.service.d.ts

@@ -0,0 +1,84 @@
+/**
+ * TaskService — ITaskManager 实现
+ *
+ * 管理 Task 生命周期：创建、状态流转、查询、Token消耗记录、进度跟踪。
+ * v1 使用 in-memory Map 存储，后续由 TaskRepository 替换。
+ *
+ * @see task-manager.contract.ts
+ * @see requirements.md Requirement 7 AC1-AC5
+ */
+import type { TaskStatus } from '../common/types.js';
+import type { CreateTaskParams, ITaskManager, TaskRecord, TaskStatusInfo, TokenUsageRecord } from './contracts/task-manager.contract.js';
+import { TaskProgressTracker } from './task-progress-tracker.js';
+export type { CreateTaskParams, ITaskManager, TaskRecord, TaskStatusInfo, TokenUsageRecord };
+/**
+ * ITaskRepository — Task 持久化接口
+ *
+ * TaskService 通过此接口访问存储层，默认使用 InMemoryTaskRepository。
+ * Task 3.2 将提供 MySQL 实现。
+ */
+export interface ITaskRepository {
+    save(task: TaskRecord): Promise<void>;
+    findById(id: string): Promise<TaskRecord | null>;
+    update(task: TaskRecord): Promise<void>;
+}
+/**
+ * InMemoryTaskRepository — 内存存储实现
+ *
+ * 用于开发/测试阶段，后续替换为 MySQL 实现。
+ */
+export declare class InMemoryTaskRepository implements ITaskRepository {
+    private readonly store;
+    save(task: TaskRecord): Promise<void>;
+    findById(id: string): Promise<TaskRecord | null>;
+    update(task: TaskRecord): Promise<void>;
+}
+export declare class TaskService implements ITaskManager {
+    private readonly repository;
+    private readonly progressTracker;
+    constructor(repository?: ITaskRepository, progressTracker?: TaskProgressTracker);
+    /**
+     * 获取内部 progressTracker 实例（供 Graph 引擎更新节点进度）
+     */
+    getProgressTracker(): TaskProgressTracker;
+    /**
+     * 创建新 Task，初始状态为 pending
+     */
+    create(params: CreateTaskParams): Promise<TaskRecord>;
+    /**
+     * 获取完整 Task 记录（供 AgentRuntime.resumeHitl / fork 使用）
+     */
+    getTask(taskId: string): Promise<TaskRecord | null>;
+    /**
+     * 更新 Task 状态
+     *
+     * 验证状态流转合法性，设置时间戳：
+     * - pending→running: 设置 startedAt
+     * - running→终态: 设置 completedAt 和 output
+     */
+    updateStatus(taskId: string, status: TaskStatus, output?: unknown): Promise<void>;
+    /**
+     * 仅当当前状态为 `from` 时流转。并发下 timeout/resume 抢占时返回 false，不抛错。
+     */
+    tryUpdateStatus(taskId: string, from: TaskStatus, to: TaskStatus, output?: unknown): Promise<boolean>;
+    /**
+     * 获取 Task 当前状态信息（供轮询使用）
+     *
+     * 优先返回 progressTracker 中的显式进度，回退到基于状态的粗粒度计算。
+     */
+    getStatus(taskId: string): Promise<TaskStatusInfo>;
+    /**
+     * 记录一次 Token 消耗，累加到 Task 的 tokenUsage 和 cost
+     */
+    recordTokenUsage(taskId: string, usage: TokenUsageRecord): Promise<void>;
+    /**
+     * 更新 Task 执行进度（用于长任务轮询）
+     *
+     * 进度值会被 clamp 到 0-100 范围。仅 running 状态的 Task 可更新进度。
+     */
+    updateProgress(taskId: string, progress: number): Promise<void>;
+    private findTaskOrThrow;
+    private isValidTransition;
+    private calculateProgress;
+    private calculateDuration;
+}