@ai-setting/roy-agent-core 1.0.0

package/src/env/task/tools/task-types.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Task Tool Parameter Schemas
+ */
+
+import { z } from "zod";
+
+/**
+ * task_create tool parameters
+ */
+export const CreateTaskToolSchema = z.object({
+  title: z.string().describe("Task title"),
+  description: z.string().optional().describe("Task description"),
+  priority: z.enum(["low", "medium", "high"]).optional().describe("Task priority"),
+  goals_and_expected_deliverables: z.string().optional().describe("Goals and expected deliverables"),
+  due_date: z.string().optional().describe("Due date (ISO format)"),
+  tags: z.array(z.string()).optional().describe("Task tags (for search, stored in task.tags JSON field)"),
+});
+
+export type CreateTaskToolParams = z.infer<typeof CreateTaskToolSchema>;
+
+/**
+ * task_get tool parameters
+ */
+export const GetTaskToolSchema = z.object({
+  task_id: z.number().describe("Task ID"),
+  include_operations: z.boolean().optional().default(false).describe("Include operation records"),
+});
+
+export type GetTaskToolParams = z.infer<typeof GetTaskToolSchema>;
+
+/**
+ * task_list tool parameters
+ */
+export const ListTasksToolSchema = z.object({
+  status: z.enum(["todo", "active", "completed", "paused", "cancelled"]).optional(),
+  priority: z.enum(["low", "medium", "high"]).optional(),
+  limit: z.number().optional().default(20),
+  offset: z.number().optional().default(0),
+});
+
+export type ListTasksToolParams = z.infer<typeof ListTasksToolSchema>;
+
+/**
+ * task_update tool parameters
+ */
+export const UpdateTaskToolSchema = z.object({
+  task_id: z.number().describe("Task ID"),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  status: z.enum(["todo", "active", "completed", "paused", "cancelled"]).optional(),
+  priority: z.enum(["low", "medium", "high"]).optional(),
+  progress: z.number().min(0).max(100).optional(),
+  current_status: z.string().optional(),
+  goals_and_expected_deliverables: z.string().optional(),
+  due_date: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+});
+
+export type UpdateTaskToolParams = z.infer<typeof UpdateTaskToolSchema>;
+
+/**
+ * task_delete tool parameters
+ */
+export const DeleteTaskToolSchema = z.object({
+  task_id: z.number().describe("Task ID"),
+});
+
+export type DeleteTaskToolParams = z.infer<typeof DeleteTaskToolSchema>;

package/src/env/task/tools/update-tool.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Task Update Tool
+ */
+
+import type { Tool, ToolContext, ToolResult } from "../../tool/types";
+import { UpdateTaskToolSchema, type UpdateTaskToolParams } from "./task-types";
+import type { TaskComponent } from "../task-component";
+
+export function updateTaskTool(taskComponent: TaskComponent): Tool {
+  return {
+    name: "task_update",
+    description: "Update an existing task's properties. Status and progress changes will create operation records.",
+    parameters: UpdateTaskToolSchema,
+    execute: async (args: unknown, ctx: ToolContext): Promise<ToolResult> => {
+      const params = UpdateTaskToolSchema.parse(args) as UpdateTaskToolParams;
+      const sessionId = ctx.session_id || "unknown";
+      
+      try {
+        const task = await taskComponent.updateTask(params.task_id, {
+          title: params.title,
+          description: params.description,
+          status: params.status,
+          priority: params.priority,
+          progress: params.progress,
+          current_status: params.current_status,
+          goals_and_expected_deliverables: params.goals_and_expected_deliverables,
+          due_date: params.due_date,
+          tags: params.tags,
+        });
+        
+        if (!task) {
+          return { 
+            success: false, 
+            output: "", 
+            error: `Task not found: ${params.task_id}`,
+            metadata: { execution_time_ms: 0 },
+          };
+        }
+        
+        // Create operation record for status/progress changes
+        if (params.status || params.progress !== undefined || params.current_status) {
+          await taskComponent.createOperation({
+            taskId: params.task_id,
+            sessionId,
+            actionType: "progress",
+            actionTitle: params.current_status || `Updated: ${params.status || `${params.progress}%`}`,
+            actionDescription: JSON.stringify({
+              status: params.status,
+              progress: params.progress,
+              current_status: params.current_status,
+            }),
+          });
+        }
+        
+        return {
+          success: true,
+          output: `Task updated: #${task.id} - ${task.title}`,
+          metadata: { execution_time_ms: 0, task },
+        };
+      } catch (error) {
+        return {
+          success: false,
+          output: "",
+          error: error instanceof Error ? error.message : String(error),
+          metadata: { execution_time_ms: 0 },
+        };
+      }
+    },
+  };
+}

package/src/env/task/types.ts

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview Task Component Types
+ */
+
+import { z } from "zod";
+
+// ============================================================================
+// Enums
+// ============================================================================
+
+/**
+ * Task status enum
+ */
+export const TaskStatusEnum = z.enum(["todo", "active", "completed", "paused", "cancelled"]);
+export type TaskStatus = z.infer<typeof TaskStatusEnum>;
+
+/**
+ * Task priority enum
+ */
+export const TaskPriorityEnum = z.enum(["low", "medium", "high"]);
+export type TaskPriority = z.infer<typeof TaskPriorityEnum>;
+
+/**
+ * Action type for task operations
+ */
+export const ActionTypeEnum = z.enum([
+  "create",
+  "progress",
+  "milestone",
+  "problem",
+  "solution",
+  "decision",
+  "review",
+  "completed",
+  "workflow_extracted",
+]);
+export type ActionType = z.infer<typeof ActionTypeEnum>;
+
+// ============================================================================
+// Task Entity
+// ============================================================================
+
+/**
+ * Task entity
+ */
+export interface Task {
+  id: number;
+  title: string;
+  description: string;
+  status: TaskStatus;
+  priority: TaskPriority;
+  progress: number;
+  current_status: string;
+  goals_and_expected_deliverables: string;
+  parent_task_id?: number;
+  createdAt: string;
+  updatedAt: string;
+  due_date?: string;
+  tags?: string[];
+}
+
+// ============================================================================
+// TaskOperation Entity
+// ============================================================================
+
+/**
+ * TaskOperation entity
+ * 
+ * 记录任务的操作历史，每个操作关联到一个 sessionId
+ */
+export interface TaskOperation {
+  id: number;
+  taskId: number;
+  sessionId: string;  // 必填！标记在哪发生
+  actionType: ActionType;
+  actionTitle: string;
+  actionDescription: string;
+  timestamp: string;
+  mdPath?: string;
+}
+
+// ============================================================================
+// TaskTag Entity
+// ============================================================================
+
+/**
+ * TaskTag entity
+ * 
+ * Tag 池中的单个 Tag
+ */
+export interface TaskTag {
+  id: number;
+  name: string;
+  createdAt: string;
+  taskCount: number;
+}
+
+// ============================================================================
+// Config Schema
+// ============================================================================
+
+export const TaskConfigSchema = z.object({
+  storage: z.object({
+    type: z.enum(["memory", "sqlite"]).default("sqlite"),
+    dbPath: z.string().optional(),
+  }).default({}),
+}).default({});
+
+export type TaskConfig = z.infer<typeof TaskConfigSchema>;
+
+// ============================================================================
+// Operation Options
+// ============================================================================
+
+export interface CreateTaskOptions {
+  title: string;
+  description?: string;
+  priority?: TaskPriority;
+  parent_task_id?: number;
+  goals_and_expected_deliverables?: string;
+  due_date?: string;
+  tags?: string[];
+  sessionId: string;  // 必填
+}
+
+export interface UpdateTaskOptions {
+  title?: string;
+  description?: string;
+  status?: TaskStatus;
+  priority?: TaskPriority;
+  progress?: number;
+  current_status?: string;
+  goals_and_expected_deliverables?: string;
+  due_date?: string;
+  tags?: string[];
+}
+
+export interface ListTasksOptions {
+  status?: TaskStatus;
+  priority?: TaskPriority;
+  parent_task_id?: number;
+  limit?: number;
+  offset?: number;
+}
+
+export interface CreateOperationOptions {
+  taskId: number;
+  sessionId: string;  // 必填
+  actionType: ActionType;
+  actionTitle: string;
+  actionDescription?: string;
+  mdPath?: string;
+}
+
+export interface ListOperationsOptions {
+  taskId: number;
+  actionType?: ActionType;
+  limit?: number;
+  offset?: number;
+}

package/src/env/tool/built-in/bash.ts

@@ -0,0 +1,201 @@
+import { z } from "zod";
+import { exec } from "child_process";
+import { promisify } from "util";
+import type { Tool, ToolContext, ToolResult } from "../types";
+import { propagation } from "../../log-trace/opentelemetry/propagation";
+
+const execAsync = promisify(exec);
+
+/**
+ * 获取当前 Span Context（用于设置父 span）
+ */
+function getCurrentSpanContext(): { traceId: string; spanId: string; parentSpanId?: string } | undefined {
+  try {
+    const { getTracerProvider } = require("../../log-trace/opentelemetry/tracer-provider");
+    const provider = getTracerProvider();
+    if (!provider.isInitialized()) {
+      throw new Error("Provider not initialized");
+    }
+    const tracer = provider.getTracer('roy-tracer');
+    const ctx = tracer.getCurrentContext();
+    if (ctx && ctx.traceId && ctx.spanId) {
+      return ctx;
+    }
+  } catch {
+    // OTel tracer 未初始化或没有当前上下文
+  }
+  return undefined;
+}
+
+/**
+ * 获取当前 traceId
+ */
+function getCurrentTraceId(): string | undefined {
+  const ctx = getCurrentSpanContext();
+  if (ctx) {
+    return ctx.traceId;
+  }
+  
+  // Fallback: 从环境变量读取
+  return process.env.TRACE_ID;
+}
+
+/**
+ * Bash 工具
+ * 执行 shell 命令
+ * 
+ * 支持 OpenTelemetry W3C TraceContext 跨进程追踪：
+ * - 通过 TRACEPARENT 环境变量传递 traceId 和 parentSpanId
+ * - 子进程可以正确关联到父 trace
+ */
+export const bashTool: Tool = {
+  name: "bash",
+  description: "Execute shell commands in the terminal. Use this to run system commands, scripts, or interact with the file system.",
+  parameters: z.object({
+    command: z.string().describe("The shell command to execute"),
+    workdir: z.string().optional().describe("Working directory for the command"),
+    timeout: z.number().int().positive().optional().describe("Timeout in milliseconds"),
+    env: z.record(z.string()).optional().describe("Additional environment variables"),
+  }),
+  sandbox: {
+    enabled: true,
+    config: {
+      filesystem: {
+        denyRead: ["/etc/shadow", "/etc/sudoers", "/etc/sudoers.d/*"],
+        denyWrite: ["/etc", "/usr/bin", "/usr/sbin", "/bin", "/sbin"],
+      },
+    },
+  },
+  permission: {
+    requireConfirmation: true,
+    level: "dangerous",
+  },
+  metadata: {
+    category: "system",
+    tags: ["shell", "command", "terminal", "exec"],
+    version: "1.2.0",
+  },
+  execute: async (args, ctx: ToolContext): Promise<ToolResult> => {
+    const startTime = Date.now();
+    const { command, workdir, timeout = 60000, env } = args;
+
+    // 获取当前 span 上下文
+    const currentSpanCtx = getCurrentSpanContext();
+    const traceId = currentSpanCtx?.traceId || getCurrentTraceId();
+
+    // 构建执行选项
+    const options: {
+      cwd?: string;
+      timeout?: number;
+      env?: Record<string, string>;
+    } = {
+      timeout,
+    };
+
+    if (workdir || ctx.workdir) {
+      options.cwd = workdir || ctx.workdir;
+    }
+
+    // 构建子进程的环境变量
+    const childEnv: Record<string, string> = {};
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== undefined) {
+        childEnv[key] = value;
+      }
+    }
+
+    // 使用 W3C TraceContext 注入 TRACEPARENT
+    if (currentSpanCtx) {
+      const carrier: Record<string, string | undefined> = {};
+      propagation.inject(carrier, currentSpanCtx);
+      if (carrier['TRACEPARENT']) {
+        childEnv['TRACEPARENT'] = carrier['TRACEPARENT'];
+      }
+      // 保留向后兼容的环境变量
+      childEnv['TRACE_ID'] = currentSpanCtx.traceId;
+      childEnv['PARENT_SPAN_ID'] = currentSpanCtx.spanId;
+    } else if (traceId) {
+      // 如果没有当前上下文但有 traceId，创建根 span 的 traceparent
+      const spanId = Math.floor(Math.random() * 0xFFFFFFFFFFFFFFFF)
+        .toString(16)
+        .padStart(16, "0");
+      childEnv['TRACEPARENT'] = `00-${traceId}-${spanId}-01`;
+      childEnv['TRACE_ID'] = traceId;
+    }
+
+    // 用户提供的 env 优先级最高
+    if (env) {
+      Object.assign(childEnv, env);
+    }
+    options.env = childEnv;
+
+    // 使用 OTel tracer 创建 span
+    let otelSpan: any = undefined;
+    try {
+      const { getTracerProvider } = require("../../log-trace/opentelemetry/tracer-provider");
+      const provider = getTracerProvider();
+      const tracer = provider.getTracer('roy-tracer');
+      otelSpan = tracer.startSpan(`bash: ${command.slice(0, 50)}${command.length > 50 ? "..." : ""}`, {
+        attributes: {
+          'bash.command': command.slice(0, 200),
+          'bash.workdir': workdir || ctx.workdir || '',
+          'bash.timeout': timeout,
+        },
+      });
+    } catch {
+      // OTel tracer 不可用，继续执行
+    }
+
+    const spanId = otelSpan?.spanContext?.spanId;
+
+    try {
+      const { stdout, stderr } = await execAsync(command, options);
+
+      // 结束 span
+      if (otelSpan) {
+        otelSpan.end({ stdout, stderr });
+      }
+
+      return {
+        success: true,
+        output: stdout || "(no output)",
+        metadata: {
+          execution_time_ms: Date.now() - startTime,
+          stdout,
+          stderr,
+          exit_code: 0,
+          trace_id: traceId,
+          parent_span_id: currentSpanCtx?.spanId,
+          span_id: spanId,
+        },
+      };
+    } catch (error: any) {
+      const exitCode = error.code || 1;
+      const stdout = error.stdout || "";
+      const stderr = error.stderr || error.message;
+
+      // 结束 span（带错误）
+      const execError = new Error(stderr);
+      execError.name = "BashExecutionError";
+
+      if (otelSpan) {
+        otelSpan.end(undefined, execError);
+      }
+
+      return {
+        success: exitCode === 0,
+        output: stdout || "(no output)",
+        error: stderr,
+        metadata: {
+          execution_time_ms: Date.now() - startTime,
+          stdout,
+          stderr,
+          exit_code: exitCode,
+          trace_id: traceId,
+          parent_span_id: currentSpanCtx?.spanId,
+          span_id: spanId,
+        },
+      };
+    }
+  },
+};

package/src/env/tool/built-in/echo.ts

@@ -0,0 +1,29 @@
+import type { Tool, ToolContext, ToolResult } from "../types";
+
+/**
+ * Echo tool - simple echo command
+ * 
+ * This is a convenience tool for logging messages in workflows.
+ */
+export const echoTool: Tool = {
+  name: "echo",
+  description: "Echo a message to the console. Useful for logging in workflows.",
+  parameters: {
+    name: "message",
+    schema: {
+      type: "string",
+      description: "The message to echo",
+    },
+  } as any,
+  execute: async (args: { message?: string }, _ctx: ToolContext): Promise<ToolResult> => {
+    const message = args?.message || "(no message)";
+    
+    return {
+      success: true,
+      output: message,
+      metadata: {
+        execution_time_ms: 0,
+      },
+    };
+  },
+};

package/src/env/tool/built-in/edit-file.test.ts

@@ -0,0 +1,136 @@
+import { describe, test, expect, beforeEach } from "bun:test";
+import { editFileTool } from "./edit-file";
+import { writeFile, mkdir } from "fs/promises";
+import { join } from "path";
+
+describe("editFileTool", () => {
+  const testDir = join("/tmp", `edit-test-${Date.now()}`);
+  const testFile = join(testDir, "test.txt");
+
+  beforeEach(async () => {
+    await mkdir(testDir, { recursive: true });
+    await writeFile(testFile, "Hello, World!\nThis is a test.\nEnd of file.");
+  });
+
+  describe("parameters", () => {
+    test("should validate required parameters", async () => {
+      const result = await editFileTool.execute(
+        { path: testFile, oldString: "Hello", newString: "Hi" },
+        {}
+      );
+      
+      expect(result.success).toBe(true);
+    });
+
+    test("should handle missing oldString gracefully", async () => {
+      const result = await editFileTool.execute(
+        { path: testFile, newString: "Hi" } as any,
+        {}
+      );
+      // 会因为找不到空字符串而失败
+      expect(result).toBeDefined();
+    });
+
+    test("should handle missing newString gracefully", async () => {
+      const result = await editFileTool.execute(
+        { path: testFile, oldString: "Hello" } as any,
+        {}
+      );
+      // 会成功替换为空字符串
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe("execution", () => {
+    test("should replace text in file", async () => {
+      const result = await editFileTool.execute(
+        { path: testFile, oldString: "Hello", newString: "Hi" },
+        {}
+      );
+      
+      expect(result.success).toBe(true);
+      
+      const content = await Bun.file(testFile).text();
+      expect(content).toContain("Hi, World!");
+      expect(content).not.toContain("Hello, World!");
+    });
+
+    test("should replace all occurrences with replaceAll", async () => {
+      await writeFile(testFile, "foo bar foo baz foo");
+      
+      const result = await editFileTool.execute(
+        { path: testFile, oldString: "foo", newString: "qux", replaceAll: true },
+        {}
+      );
+      
+      expect(result.success).toBe(true);
+      
+      const content = await Bun.file(testFile).text();
+      expect(content).toBe("qux bar qux baz qux");
+    });
+
+    test("should replace only first occurrence without replaceAll", async () => {
+      await writeFile(testFile, "foo bar foo baz foo");
+      
+      const result = await editFileTool.execute(
+        { path: testFile, oldString: "foo", newString: "qux" },
+        {}
+      );
+      
+      expect(result.success).toBe(true);
+      
+      const content = await Bun.file(testFile).text();
+      expect(content).toBe("qux bar foo baz foo");
+    });
+
+    test("should return error when text not found", async () => {
+      const result = await editFileTool.execute(
+        { path: testFile, oldString: "NonExistent", newString: "Something" },
+        {}
+      );
+      
+      expect(result.success).toBe(false);
+      expect(result.error).toContain("Could not find");
+    });
+
+    test("should handle multiline replacement", async () => {
+      const result = await editFileTool.execute(
+        {
+          path: testFile,
+          oldString: "Hello, World!\nThis is a test.",
+          newString: "Greetings!\nThis has been updated."
+        },
+        {}
+      );
+      
+      expect(result.success).toBe(true);
+      
+      const content = await Bun.file(testFile).text();
+      expect(content).toContain("Greetings!");
+      expect(content).toContain("This has been updated.");
+    });
+
+    test("should include metadata", async () => {
+      const result = await editFileTool.execute(
+        { path: testFile, oldString: "Hello", newString: "Hi" },
+        {}
+      );
+      
+      expect(result.metadata?.execution_time_ms).toBeDefined();
+      expect(result.metadata?.file_path).toBe(testFile);
+    });
+  });
+
+  describe("metadata", () => {
+    test("should have correct metadata", () => {
+      expect(editFileTool.name).toBe("edit_file");
+      expect(editFileTool.metadata?.category).toBe("file");
+      expect(editFileTool.metadata?.tags).toContain("edit");
+    });
+
+    test("should require confirmation", () => {
+      expect(editFileTool.permission?.requireConfirmation).toBe(true);
+      expect(editFileTool.permission?.level).toBe("dangerous");
+    });
+  });
+});