maestro-agent 0.0.1 → 0.0.3

package/src/api/chat.ts

@@ -0,0 +1,801 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { existsSync, readFileSync } from "fs";
+import { join } from "path";
+import { generateId, now } from "../core/db";
+import type { Router } from "../core/router";
+import { body, json } from "../core/router";
+import type { HubContext } from "../core/server";
+import { createWorkspaceRole } from "../roles/workspace-role";
+import { computeNextFireAt, validateScheduleInput } from "../scheduler";
+import { getConfig } from "./config";
+import { claimTaskForAgent } from "./tasks";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface ConversationRow {
+  workspace_id: string;
+  messages_json: string;
+  model: string;
+  system_prompt: string | null;
+  updated_at: number;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const DEFAULT_MODEL = "claude-sonnet-4-20250514";
+const MAX_TURNS = 10;
+
+const DEFAULT_SYSTEM = `You are MAESTRO Agent, an AI assistant collaborating with the user on their workspace.
+You can use tools to manage tasks, agents, and projects within the MAESTRO system.
+Be concise, helpful, and action-oriented. When given instructions, execute them directly.`;
+
+// ─── Route Registration ──────────────────────────────────────────────────────
+
+export function registerChatRoutes(router: Router, ctx: HubContext) {
+  // 查历史消息
+  router.get("/api/chat/messages", (req) => {
+    const url = new URL(req.url);
+    const workspaceId = url.searchParams.get("workspace_id");
+    if (!workspaceId) return json({ error: "workspace_id required" }, 400);
+
+    const limit = Math.min(Number(url.searchParams.get("limit") || "50"), 200);
+    const beforeSeq = url.searchParams.get("before_seq");
+
+    let sql = "SELECT * FROM chat_message WHERE workspace_id = ?";
+    const params: any[] = [workspaceId];
+    if (beforeSeq) {
+      sql += " AND seq < ?";
+      params.push(Number(beforeSeq));
+    }
+    sql += " ORDER BY seq DESC LIMIT ?";
+    params.push(limit);
+
+    const rows = ctx.db.query(sql).all(...params) as any[];
+    return json(rows.reverse());
+  });
+
+  // 发送消息 — 检测 @mention 并触发 agentic loop
+  router.post("/api/chat/messages", async (req) => {
+    const input = await body(req);
+    const { workspace_id, content } = input;
+    if (!workspace_id || !content) {
+      return json({ error: "workspace_id and content are required" }, 400);
+    }
+
+    // 写入人类消息
+    const humanMsg = insertChatMessage(ctx, workspace_id, "human", "user", content);
+    ctx.bus.publish("chat.message", { workspace_id, message_id: humanMsg.id, seq: humanMsg.seq, sender_type: "human" });
+
+    // 触发 agentic loop（@mention 信息会通过 system prompt 注入，让主 Agent 决定如何拆分任务）
+    runAgentLoop(ctx, workspace_id).catch((err) => {
+      console.error(`[chat] agent loop error for ${workspace_id}:`, err.message);
+      insertChatMessage(ctx, workspace_id, "agent", "system", `[Error] ${err.message}`);
+      ctx.bus.publish("chat.message", { workspace_id, sender_type: "agent", error: true });
+    });
+
+    return json(humanMsg, 201);
+  });
+
+  // 获取/设置 conversation 配置
+  router.get("/api/chat/conversation/:workspaceId", (req, params) => {
+    const conv = getOrCreateConversation(ctx, params.workspaceId);
+    return json({ workspace_id: conv.workspace_id, model: getEffectiveModel(ctx, conv), system_prompt: conv.system_prompt, updated_at: conv.updated_at });
+  });
+
+  router.patch("/api/chat/conversation/:workspaceId", async (req, params) => {
+    const input = await body(req);
+    const conv = getOrCreateConversation(ctx, params.workspaceId);
+    if (input.model) {
+      ctx.db.run("UPDATE chat_conversation SET model = ?, updated_at = ? WHERE workspace_id = ?", [input.model, now(), params.workspaceId]);
+    }
+    if (input.system_prompt !== undefined) {
+      ctx.db.run("UPDATE chat_conversation SET system_prompt = ?, updated_at = ? WHERE workspace_id = ?", [input.system_prompt, now(), params.workspaceId]);
+    }
+    if (input.reset_conversation) {
+      ctx.db.run("UPDATE chat_conversation SET messages_json = '[]', updated_at = ? WHERE workspace_id = ?", [now(), params.workspaceId]);
+    }
+    return json({ ok: true });
+  });
+}
+
+// ─── Agentic Loop ────────────────────────────────────────────────────────────
+
+export async function runAgentLoop(ctx: HubContext, workspaceId: string) {
+  const apiKey = getConfig(ctx, "chief_api_key", "") || process.env.ANTHROPIC_API_KEY || "";
+  if (!apiKey) {
+    insertChatMessage(ctx, workspaceId, "agent", "system", "[Error] API Key not configured. Set it in Settings.");
+    ctx.bus.publish("chat.message", { workspace_id: workspaceId, sender_type: "agent", error: true });
+    return;
+  }
+
+  const baseURL = getConfig(ctx, "chief_base_url", "") || process.env.MAESTRO_CHIEF_BASE_URL || undefined;
+  const client = new Anthropic({ apiKey, baseURL });
+  const conv = getOrCreateConversation(ctx, workspaceId);
+  const model = getEffectiveModel(ctx, conv);
+  const systemPrompt = conv.system_prompt || buildSystemPrompt(ctx, workspaceId);
+
+  // 获取 agent 显示名（从 workspace 关联的角色）
+  const agentDisplayName = getAgentDisplayName(ctx, workspaceId);
+
+  // 加载 conversation state
+  let messages: Anthropic.MessageParam[] = JSON.parse(conv.messages_json);
+
+  // 追加最新的人类消息（从 chat_message 表取最近一条 human 消息的 content）
+  const latestHuman = ctx.db.query(
+    "SELECT content FROM chat_message WHERE workspace_id = ? AND sender_type = 'human' ORDER BY seq DESC LIMIT 1"
+  ).get(workspaceId) as any;
+
+  if (latestHuman) {
+    messages.push({ role: "user", content: latestHuman.content });
+  }
+
+  // Agentic loop
+  for (let turn = 0; turn < MAX_TURNS; turn++) {
+    const response = await client.messages.create({
+      model,
+      max_tokens: 4096,
+      system: systemPrompt,
+      messages,
+      tools: chatTools(ctx, workspaceId),
+    });
+
+    // 提取文本回复
+    const textBlocks = response.content.filter(
+      (b): b is Anthropic.TextBlock => b.type === "text"
+    );
+    const toolUses = response.content.filter(
+      (b): b is Anthropic.ToolUseBlock => b.type === "tool_use"
+    );
+
+    // 如果有文本回复，写入 chat_message
+    if (textBlocks.length > 0) {
+      const text = textBlocks.map((b) => b.text).join("\n");
+      if (text.trim()) {
+        const agentMsg = insertChatMessage(ctx, workspaceId, "agent", agentDisplayName, text);
+        ctx.bus.publish("chat.message", { workspace_id: workspaceId, message_id: agentMsg.id, seq: agentMsg.seq, sender_type: "agent" });
+      }
+    }
+
+    // 追加 assistant 回复到 conversation
+    messages.push({ role: "assistant", content: response.content });
+
+    // 如果没有 tool_use，结束循环
+    if (toolUses.length === 0 || response.stop_reason !== "tool_use") {
+      break;
+    }
+
+    // 执行 tools 并构造 tool_result
+    const toolResults: Anthropic.ToolResultBlockParam[] = [];
+    for (const tu of toolUses) {
+      const result = await executeToolCall(ctx, workspaceId, tu.name, tu.input as Record<string, any>);
+      toolResults.push({
+        type: "tool_result",
+        tool_use_id: tu.id,
+        content: JSON.stringify(result),
+      });
+    }
+
+    messages.push({ role: "user", content: toolResults });
+  }
+
+  // 持久化 conversation state
+  saveConversation(ctx, workspaceId, messages);
+}
+
+// ─── Tool Definitions ────────────────────────────────────────────────────────
+
+export function chatTools(_ctx: HubContext, _workspaceId: string): Anthropic.Tool[] {
+  return [
+    {
+      name: "create_task",
+      description: "Create a new task in the workspace's project. When the user @mentions a role, use assignee_role to assign the task to that role's agent.",
+      input_schema: {
+        type: "object" as const,
+        properties: {
+          title: { type: "string", description: "Task title" },
+          description: { type: "string", description: "Task description" },
+          priority: { type: "number", description: "Priority (0=normal, 1=high, -1=low)" },
+          assignee_role: { type: "string", description: "Role name to assign this task to (e.g. 'Engineer', 'Critic')" },
+        },
+        required: ["title"],
+      },
+    },
+    {
+      name: "create_scheduled_task",
+      description: "Create a scheduled task in the current workspace. Use cron_expr for recurring schedules or run_at for a one-time trigger. Use assignee_role to assign the created task to that role's agent.",
+      input_schema: {
+        type: "object" as const,
+        properties: {
+          title: { type: "string" },
+          description: { type: "string" },
+          priority: { type: "number" },
+          project_id: { type: "string" },
+          schedule_type: { type: "string", description: "cron or once" },
+          cron_expr: { type: "string", description: "5-field cron expression, e.g. 0 9 * * 1" },
+          run_at: { type: "number", description: "Unix timestamp in milliseconds for one-time schedules" },
+          assignee_role: { type: "string", description: "Role name to assign the task to when it fires" },
+        },
+        required: ["title"],
+      },
+    },
+    {
+      name: "list_scheduled_tasks",
+      description: "List scheduled tasks in this workspace.",
+      input_schema: { type: "object" as const, properties: {} },
+    },
+    {
+      name: "update_scheduled_task",
+      description: "Edit, enable, or disable an existing scheduled task.",
+      input_schema: {
+        type: "object" as const,
+        properties: {
+          scheduled_task_id: { type: "string" },
+          title: { type: "string" },
+          description: { type: "string" },
+          priority: { type: "number" },
+          schedule_type: { type: "string" },
+          cron_expr: { type: "string" },
+          run_at: { type: "number" },
+          assignee_role: { type: "string" },
+          enabled: { type: "boolean" },
+        },
+        required: ["scheduled_task_id"],
+      },
+    },
+    {
+      name: "delete_scheduled_task",
+      description: "Delete a scheduled task.",
+      input_schema: {
+        type: "object" as const,
+        properties: { scheduled_task_id: { type: "string" } },
+        required: ["scheduled_task_id"],
+      },
+    },
+    {
+      name: "list_tasks",
+      description: "List tasks in this workspace.",
+      input_schema: {
+        type: "object" as const,
+        properties: {
+          status: { type: "string", description: "Filter by status: open, done, blocked" },
+        },
+      },
+    },
+    {
+      name: "update_task",
+      description: "Update a task's status or details.",
+      input_schema: {
+        type: "object" as const,
+        properties: {
+          task_id: { type: "string" },
+          status: { type: "string", description: "New status: open, in_progress, done, blocked" },
+          summary: { type: "string", description: "Completion summary" },
+        },
+        required: ["task_id"],
+      },
+    },
+    {
+      name: "list_agents",
+      description: "List all agents and their status.",
+      input_schema: { type: "object" as const, properties: {} },
+    },
+    {
+      name: "list_runtimes",
+      description: "List available agent runtimes. Use this first to get a real runtime_id before calling spawn_agent.",
+      input_schema: { type: "object" as const, properties: {} },
+    },
+    {
+      name: "spawn_agent",
+      description: "Start a new agent session for a specific role. Call list_runtimes first and pass the returned agent_runtime.id as runtime_id.",
+      input_schema: {
+        type: "object" as const,
+        properties: {
+          role_id: { type: "string" },
+          runtime_id: { type: "string" },
+        },
+        required: ["role_id", "runtime_id"],
+      },
+    },
+    {
+      name: "create_role",
+      description: "Create a workspace role. A role is the primary object; runtime_id selects the agent runtime used for the role's initial agent.",
+      input_schema: {
+        type: "object" as const,
+        properties: {
+          name: { type: "string" },
+          headcount: { type: "number" },
+          capabilities: { type: "array", items: { type: "string" } },
+          preferred_runtimes: { type: "array", items: { type: "string" } },
+          runtime_id: { type: "string" },
+        },
+        required: ["name"],
+      },
+    },
+    {
+      name: "list_projects",
+      description: "List projects in this workspace.",
+      input_schema: { type: "object" as const, properties: {} },
+    },
+    {
+      name: "create_project",
+      description: "Create a project in the current workspace. Use this before creating tasks when no suitable project exists.",
+      input_schema: {
+        type: "object" as const,
+        properties: {
+          name: { type: "string" },
+          rationale: { type: "string" },
+          charter_template: { type: "string" },
+          auto_kickoff: { type: "boolean" },
+        },
+        required: ["name"],
+      },
+    },
+    {
+      name: "workspace_info",
+      description: "Get information about the current workspace.",
+      input_schema: { type: "object" as const, properties: {} },
+    },
+  ];
+}
+
+// ─── Tool Execution ──────────────────────────────────────────────────────────
+
+export async function executeToolCall(ctx: HubContext, workspaceId: string, toolName: string, args: Record<string, any>): Promise<any> {
+  try {
+    switch (toolName) {
+      case "create_task": {
+        const project = ctx.db.query("SELECT id FROM project WHERE workspace_id = ? LIMIT 1").get(workspaceId) as any;
+        if (!project) return { error: "No project found for this workspace. Create a project first." };
+
+        // 如果指定了 assignee_role，找到对应 agent
+        let assigneeAgentId: string | null = null;
+        if (args.assignee_role) {
+          const role = ctx.db.query(
+            "SELECT id FROM role WHERE workspace_id = ? AND LOWER(name) = LOWER(?)"
+          ).get(workspaceId, args.assignee_role) as any;
+          if (role) {
+            const agent = ctx.db.query(
+              "SELECT id FROM agent WHERE role_id = ? ORDER BY last_active_at DESC LIMIT 1"
+            ).get(role.id) as any;
+            assigneeAgentId = agent?.id || null;
+          }
+        }
+
+        const id = generateId("task");
+        const ts = now();
+        ctx.db.run(
+          `INSERT INTO task (id, project_id, title, description, status, priority, assignee_agent_id, required_capabilities_json, lineage_depth, created_by, created_at, updated_at)
+           VALUES (?, ?, ?, ?, 'open', ?, ?, '[]', 0, 'agent', ?, ?)`,
+          [id, project.id, args.title, args.description || "", args.priority || 0, assigneeAgentId, ts, ts]
+        );
+        ctx.bus.publish("task.created", { task_id: id, project_id: project.id });
+        if (assigneeAgentId) {
+          const claimResult = await claimTaskForAgent(ctx, id, assigneeAgentId, { deferIfProjectBusy: true });
+          if ("error" in claimResult) {
+            return {
+              ok: false,
+              task_id: id,
+              title: args.title,
+              assigned_to: args.assignee_role || null,
+              assigned_agent_id: assigneeAgentId,
+              error: claimResult.error,
+            };
+          }
+          if ("deferred" in claimResult) {
+            return {
+              ok: true,
+              task_id: id,
+              title: args.title,
+              status: claimResult.task.status,
+              assigned_to: args.assignee_role || null,
+              assigned_agent_id: assigneeAgentId,
+              assignment_deferred: true,
+              blocked_by_task_id: claimResult.blocked_by_task_id,
+            };
+          }
+          return {
+            ok: true,
+            task_id: id,
+            title: args.title,
+            status: claimResult.task.status,
+            assigned_to: args.assignee_role || null,
+            assigned_agent_id: assigneeAgentId,
+            session_id: claimResult.session_id,
+          };
+        }
+        return { ok: true, task_id: id, title: args.title, status: "open", assigned_to: args.assignee_role || null };
+      }
+
+      case "create_scheduled_task": {
+        const normalized = normalizeScheduledTaskToolArgs(ctx, workspaceId, args);
+        if ("error" in normalized) return normalized;
+        const id = generateId("sched");
+        const ts = now();
+        const nextFireAt = computeNextFireAt(normalized, ts);
+        ctx.db.run(
+          `INSERT INTO scheduled_task (
+            id, workspace_id, project_id, title, description, priority, schedule_type, cron_expr, run_at,
+            assignee_role_id, assignee_role_name, enabled, next_fire_at, created_by, created_at, updated_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, 'agent', ?, ?)`,
+          [
+            id,
+            workspaceId,
+            normalized.project_id,
+            normalized.title,
+            normalized.description || null,
+            normalized.priority,
+            normalized.schedule_type,
+            normalized.cron_expr || null,
+            normalized.run_at || null,
+            normalized.assignee_role_id || null,
+            normalized.assignee_role_name || null,
+            nextFireAt,
+            ts,
+            ts,
+          ],
+        );
+        ctx.bus?.publish?.("scheduled_task.created", { id, workspace_id: workspaceId, next_fire_at: nextFireAt });
+        return { ok: true, scheduled_task_id: id, next_fire_at: nextFireAt, assigned_to: normalized.assignee_role_name };
+      }
+
+      case "list_scheduled_tasks": {
+        const rows = ctx.db.query(
+          `SELECT scheduled_task.*, project.name AS project_name, role.name AS resolved_role_name
+           FROM scheduled_task
+           LEFT JOIN project ON project.id = scheduled_task.project_id
+           LEFT JOIN role ON role.id = scheduled_task.assignee_role_id
+           WHERE scheduled_task.workspace_id = ?
+           ORDER BY scheduled_task.enabled DESC, scheduled_task.next_fire_at ASC, scheduled_task.created_at DESC`,
+        ).all(workspaceId);
+        return { scheduled_tasks: rows };
+      }
+
+      case "update_scheduled_task": {
+        const existing = ctx.db.query("SELECT * FROM scheduled_task WHERE id = ? AND workspace_id = ?").get(args.scheduled_task_id, workspaceId) as any;
+        if (!existing) return { error: `Scheduled task not found: ${args.scheduled_task_id}` };
+        const normalized = normalizeScheduledTaskToolArgs(ctx, workspaceId, { ...existing, ...args, project_id: args.project_id || existing.project_id }, existing);
+        if ("error" in normalized) return normalized;
+        const ts = now();
+        const scheduleChanged = args.schedule_type !== undefined || args.cron_expr !== undefined || args.run_at !== undefined || args.enabled !== undefined;
+        const enabled = args.enabled === undefined ? Number(existing.enabled) : (args.enabled ? 1 : 0);
+        const nextFireAt = enabled ? (scheduleChanged ? computeNextFireAt(normalized, ts) : existing.next_fire_at) : null;
+        ctx.db.run(
+          `UPDATE scheduled_task SET title = ?, description = ?, priority = ?, schedule_type = ?, cron_expr = ?, run_at = ?,
+             assignee_role_id = ?, assignee_role_name = ?, enabled = ?, next_fire_at = ?, updated_at = ?
+           WHERE id = ?`,
+          [
+            normalized.title,
+            normalized.description || null,
+            normalized.priority,
+            normalized.schedule_type,
+            normalized.cron_expr || null,
+            normalized.run_at || null,
+            normalized.assignee_role_id || null,
+            normalized.assignee_role_name || null,
+            enabled,
+            nextFireAt,
+            ts,
+            existing.id,
+          ],
+        );
+        return { ok: true, scheduled_task_id: existing.id, next_fire_at: nextFireAt, enabled };
+      }
+
+      case "delete_scheduled_task": {
+        const existing = ctx.db.query("SELECT * FROM scheduled_task WHERE id = ? AND workspace_id = ?").get(args.scheduled_task_id, workspaceId) as any;
+        if (!existing) return { error: `Scheduled task not found: ${args.scheduled_task_id}` };
+        ctx.db.run("DELETE FROM scheduled_task WHERE id = ?", [existing.id]);
+        return { ok: true, scheduled_task_id: existing.id, deleted: true };
+      }
+
+      case "list_tasks": {
+        const projects = ctx.db.query("SELECT id FROM project WHERE workspace_id = ?").all(workspaceId) as any[];
+        if (projects.length === 0) return { tasks: [] };
+        const projectIds = projects.map(p => p.id);
+        const placeholders = projectIds.map(() => "?").join(",");
+        let sql = `SELECT id, title, status, priority, assigned_to FROM task WHERE project_id IN (${placeholders})`;
+        const params: any[] = [...projectIds];
+        if (args.status) { sql += " AND status = ?"; params.push(args.status); }
+        sql += " ORDER BY priority DESC, created_at DESC LIMIT 20";
+        return { tasks: ctx.db.query(sql).all(...params) };
+      }
+
+      case "update_task": {
+        const task = ctx.db.query("SELECT * FROM task WHERE id = ?").get(args.task_id) as any;
+        if (!task) return { error: `Task not found: ${args.task_id}` };
+        const updates: string[] = [];
+        const values: any[] = [];
+        if (args.status) { updates.push("status = ?"); values.push(args.status); }
+        if (args.summary) { updates.push("acceptance_criteria = ?"); values.push(args.summary); }
+        updates.push("updated_at = ?"); values.push(now());
+        values.push(args.task_id);
+        ctx.db.run(`UPDATE task SET ${updates.join(", ")} WHERE id = ?`, values);
+        return { ok: true, task_id: args.task_id, status: args.status || task.status };
+      }
+
+      case "list_agents": {
+        const agents = ctx.db.query("SELECT id, name, status, role_id FROM agent WHERE status != 'offline' ORDER BY created_at DESC LIMIT 20").all();
+        return { agents };
+      }
+
+      case "list_runtimes": {
+        const runtimes = ctx.db.query(`
+          SELECT
+            id,
+            type,
+            transport,
+            status,
+            capacity,
+            target
+          FROM agent_runtime
+          ORDER BY created_at DESC
+          LIMIT 20
+        `).all();
+        return { runtimes };
+      }
+
+      case "spawn_agent": {
+        const role = ctx.db.query("SELECT * FROM role WHERE id = ?").get(args.role_id) as any;
+        const runtime = ctx.db.query("SELECT * FROM agent_runtime WHERE id = ?").get(args.runtime_id) as any;
+        if (!role) return { error: `Role not found: ${args.role_id}` };
+        if (!runtime) return { error: `Agent runtime not found: ${args.runtime_id}` };
+        const id = generateId("agent");
+        const ts = now();
+        ctx.db.run(
+          "INSERT INTO agent (id, role_id, runtime_id, name, status, metrics_json, created_at, last_active_at) VALUES (?, ?, ?, ?, 'idle', '{}', ?, ?)",
+          [id, role.id, runtime.id, `${role.name}-${id.slice(-4)}`, ts, ts]
+        );
+        return { ok: true, agent_id: id, name: `${role.name}-${id.slice(-4)}` };
+      }
+
+      case "create_role": {
+        const created = createWorkspaceRole(ctx.db, {
+          workspaceId,
+          name: String(args.name || "").trim(),
+          capabilities: Array.isArray(args.capabilities) ? args.capabilities : [],
+          preferredRuntimes: Array.isArray(args.preferred_runtimes) ? args.preferred_runtimes : [],
+          headcount: Number(args.headcount || 1),
+          runtimeId: args.runtime_id || null,
+          hubDir: ctx.hubDir,
+        }, ctx.bus?.publish ? ctx.bus.publish.bind(ctx.bus) : undefined);
+        return {
+          ok: true,
+          agents: created.agents,
+          role: {
+            id: created.role.id,
+            workspace_id: workspaceId,
+            name: created.role.name,
+            headcount: created.role.headcount,
+            role_md_path: created.role.role_md_path,
+            capabilities: Array.isArray(args.capabilities) ? args.capabilities : [],
+            preferred_runtimes: Array.isArray(args.preferred_runtimes) ? args.preferred_runtimes : [],
+          },
+        };
+      }
+
+      case "list_projects": {
+        const projects = ctx.db.query("SELECT id, name, status FROM project WHERE workspace_id = ?").all(workspaceId);
+        return { projects };
+      }
+
+      case "create_project": {
+        const workspace = ctx.db.query("SELECT * FROM workspace WHERE id = ?").get(workspaceId) as any;
+        if (!workspace) return { error: `Workspace not found: ${workspaceId}` };
+        const name = String(args.name || "").trim();
+        if (!name) return { error: "Project name is required" };
+        const id = generateId("proj");
+        const ts = now();
+        ctx.db.run(
+          "INSERT INTO project (id, workspace_id, name, charter_template, status, rationale, created_by, created_at, updated_at) VALUES (?, ?, ?, ?, 'active', ?, 'agent', ?, ?)",
+          [id, workspaceId, name, args.charter_template || null, args.rationale || null, ts, ts],
+        );
+        ctx.bus?.publish?.("project.created", { id, workspace_id: workspaceId, name });
+        const initialTasks = args.auto_kickoff ? createKickoffTasks(ctx, id, ts) : undefined;
+        return {
+          ok: true,
+          project: {
+            id,
+            workspace_id: workspaceId,
+            name,
+            status: "active",
+            rationale: args.rationale || null,
+            created_at: ts,
+          },
+          ...(initialTasks ? { initial_tasks: initialTasks } : {}),
+        };
+      }
+
+      case "workspace_info": {
+        const workspace = ctx.db.query("SELECT * FROM workspace WHERE id = ?").get(workspaceId);
+        return workspace || { error: "Workspace not found" };
+      }
+
+      default:
+        return { error: `Unknown tool: ${toolName}` };
+    }
+  } catch (err: any) {
+    return { error: err.message };
+  }
+}
+
+function createKickoffTasks(ctx: HubContext, projectId: string, ts: number): any[] {
+  const templatePath = join(import.meta.dir, "../../templates/kickoff-tasks.json");
+  if (!existsSync(templatePath)) return [];
+  const initialTasks: any[] = [];
+  try {
+    const tasks = JSON.parse(readFileSync(templatePath, "utf-8")) as any[];
+    for (const task of tasks) {
+      const taskId = generateId("task");
+      ctx.db.run(
+        `INSERT INTO task (id, project_id, title, description, status, required_capabilities_json, priority, lineage_depth, created_by, created_at, updated_at)
+         VALUES (?, ?, ?, ?, 'open', ?, ?, 0, 'template', ?, ?)`,
+        [
+          taskId,
+          projectId,
+          task.title,
+          task.description || null,
+          JSON.stringify(task.skill ? [task.skill] : []),
+          task.priority || 0,
+          ts,
+          ts,
+        ],
+      );
+      initialTasks.push({ id: taskId, title: task.title, status: "open", priority: task.priority || 0 });
+      ctx.bus?.publish?.("task.created", { id: taskId, project_id: projectId, title: task.title });
+    }
+  } catch {}
+  return initialTasks;
+}
+
+function normalizeScheduledTaskToolArgs(ctx: HubContext, workspaceId: string, args: Record<string, any>, existing?: any):
+  | {
+    project_id: string;
+    title: string;
+    description: string;
+    priority: number;
+    schedule_type: "cron" | "once";
+    cron_expr: string | null;
+    run_at: number | null;
+    assignee_role_id: string | null;
+    assignee_role_name: string | null;
+  }
+  | { error: string } {
+  const projectId = resolveToolProjectId(ctx, workspaceId, args.project_id || existing?.project_id);
+  if (!projectId) return { error: "No project found for this workspace. Create a project first." };
+
+  const title = String(args.title || existing?.title || "").trim();
+  if (!title) return { error: "title is required" };
+
+  let scheduleType: "cron" | "once";
+  try {
+    scheduleType = validateScheduleInput(args) as "cron" | "once";
+  } catch (err: any) {
+    return { error: err.message };
+  }
+
+  const assigneeRoleName = String(args.assignee_role || args.assignee_role_name || existing?.assignee_role_name || "").trim();
+  let assigneeRoleId: string | null = args.assignee_role_id || existing?.assignee_role_id || null;
+  let resolvedRoleName: string | null = assigneeRoleName || existing?.assignee_role_name || null;
+  if (assigneeRoleName) {
+    const role = ctx.db.query(
+      "SELECT * FROM role WHERE workspace_id = ? AND LOWER(name) = LOWER(?) ORDER BY created_at ASC LIMIT 1",
+    ).get(workspaceId, assigneeRoleName) as any;
+    if (!role) return { error: `Assignee role not found: ${assigneeRoleName}` };
+    assigneeRoleId = role.id;
+    resolvedRoleName = role.name;
+  }
+
+  return {
+    project_id: projectId,
+    title,
+    description: String(args.description ?? existing?.description ?? ""),
+    priority: Number(args.priority ?? existing?.priority ?? 0),
+    schedule_type: scheduleType,
+    cron_expr: scheduleType === "cron" ? String(args.cron_expr || existing?.cron_expr || "").trim() : null,
+    run_at: scheduleType === "once" ? Number(args.run_at ?? existing?.run_at) : null,
+    assignee_role_id: assigneeRoleId,
+    assignee_role_name: resolvedRoleName,
+  };
+}
+
+function resolveToolProjectId(ctx: HubContext, workspaceId: string, projectId?: string | null) {
+  if (projectId) {
+    const project = ctx.db.query("SELECT id FROM project WHERE id = ? AND workspace_id = ?").get(projectId, workspaceId) as any;
+    return project?.id || null;
+  }
+  const project = ctx.db.query("SELECT id FROM project WHERE workspace_id = ? ORDER BY created_at ASC LIMIT 1").get(workspaceId) as any;
+  return project?.id || null;
+}
+
+// ─── Conversation State ──────────────────────────────────────────────────────
+
+function getOrCreateConversation(ctx: HubContext, workspaceId: string): ConversationRow {
+  let conv = ctx.db.query("SELECT * FROM chat_conversation WHERE workspace_id = ?").get(workspaceId) as ConversationRow | null;
+  if (!conv) {
+    const ts = now();
+    const model = getConfig(ctx, "chief_model", "") || DEFAULT_MODEL;
+    ctx.db.run(
+      "INSERT INTO chat_conversation (workspace_id, messages_json, model, system_prompt, updated_at) VALUES (?, '[]', ?, NULL, ?)",
+      [workspaceId, model, ts]
+    );
+    conv = ctx.db.query("SELECT * FROM chat_conversation WHERE workspace_id = ?").get(workspaceId) as ConversationRow;
+  }
+  return conv;
+}
+
+function getEffectiveModel(ctx: HubContext, conv: ConversationRow): string {
+  return getConfig(ctx, "chief_model", "") || conv.model || DEFAULT_MODEL;
+}
+
+function saveConversation(ctx: HubContext, workspaceId: string, messages: Anthropic.MessageParam[]) {
+  // 只保留最近 50 轮对话，防止 token 爆炸
+  const trimmed = messages.slice(-100);
+  ctx.db.run(
+    "UPDATE chat_conversation SET messages_json = ?, updated_at = ? WHERE workspace_id = ?",
+    [JSON.stringify(trimmed), now(), workspaceId]
+  );
+}
+
+function buildSystemPrompt(ctx: HubContext, workspaceId: string): string {
+  const workspace = ctx.db.query("SELECT name, goal FROM workspace WHERE id = ?").get(workspaceId) as any;
+  const roles = ctx.db.query("SELECT name FROM role WHERE workspace_id = ? ORDER BY name").all(workspaceId) as any[];
+  // 排除 Chief — 用户直接对话就是和主 Agent 说话，不需要 @mention
+  const assignableRoles = roles.filter((r: any) => r.name.toLowerCase() !== "chief");
+  const roleList = assignableRoles.map((r: any) => r.name).join(", ");
+
+  let prompt = `${DEFAULT_SYSTEM}
+
+Current Workspace: "${workspace?.name || "Unknown"}"
+Goal: ${workspace?.goal || "Not specified"}
+Workspace ID: ${workspaceId}`;
+
+  if (roleList) {
+    prompt += `
+
+Available Roles for task assignment: ${roleList}
+
+When the user @mentions a role name (e.g. "@Engineer do X"), you MUST use the create_task tool with assignee_role set to that role name.
+If multiple roles are mentioned, create separate tasks for each with appropriate subtask descriptions.
+When the user asks to run work at a future time or on a recurrence, use create_scheduled_task and set assignee_role when a role is specified.
+Confirm to the user what tasks were created and who they were assigned to.`;
+  }
+
+  return prompt;
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function getAgentDisplayName(ctx: HubContext, workspaceId: string): string {
+  // 优先从 workspace.primary_agent_id 关联的 agent 取名
+  const workspace = ctx.db.query("SELECT primary_agent_id FROM workspace WHERE id = ?").get(workspaceId) as any;
+  if (workspace?.primary_agent_id) {
+    const agent = ctx.db.query("SELECT name FROM agent WHERE id = ?").get(workspace.primary_agent_id) as any;
+    if (agent?.name) return agent.name;
+  }
+  // 从 workspace 关联的 role 取名
+  const role = ctx.db.query(`
+    SELECT r.name FROM role r
+    JOIN project p ON r.workspace_id = p.workspace_id
+    WHERE p.workspace_id = ?
+    ORDER BY r.created_at ASC LIMIT 1
+  `).get(workspaceId) as any;
+  if (role?.name) return role.name;
+  return "MAESTRO";
+}
+
+export function insertChatMessage(ctx: HubContext, workspaceId: string, senderType: string, senderId: string, content: string) {
+  const id = generateId("cm");
+  const ts = now();
+
+  const maxSeq = (ctx.db.query(
+    "SELECT MAX(seq) as s FROM chat_message WHERE workspace_id = ?"
+  ).get(workspaceId) as any)?.s || 0;
+  const seq = maxSeq + 1;
+
+  ctx.db.run(`
+    INSERT INTO chat_message (id, workspace_id, sender_type, sender_id, content, mentions_json, seq, created_at)
+    VALUES (?, ?, ?, ?, ?, '[]', ?, ?)
+  `, [id, workspaceId, senderType, senderId, content, seq, ts]);
+
+  return { id, workspace_id: workspaceId, sender_type: senderType, sender_id: senderId, content, seq, created_at: ts };
+}