@downcity/agent 1.1.1

package/src/http/dashboard/ExecuteBySession.ts

@@ -0,0 +1,151 @@
+/**
+ * Dashboard execute by session helper。
+ *
+ * 关键点（中文）
+ * - chatKey session 优先复用 chat 平台队列链路（与平台入站执行一致）。
+ * - 非 chat session 保留原有直接执行语义。
+ */
+
+import type { AgentRuntime } from "@/agent/AgentRuntime.js";
+import type { AgentContext } from "@/types/agent/AgentContext.js";
+import type { JsonObject } from "@/shared/types/Json.js";
+import type { DashboardSessionExecuteAttachmentInput } from "@/shared/types/DashboardSessionExecute.js";
+import { drainDeferredPersistedUserMessages } from "@session/SessionRunScope.js";
+import { resolveChatQueueStore } from "@services/chat/runtime/ChatQueue.js";
+import { resolveDispatchTargetByChatKey } from "@services/chat/runtime/ChatkeySend.js";
+import { appendExecIngress } from "@services/chat/runtime/ChatIngressStore.js";
+import { buildQueuedUserMessageWithInfo } from "@services/chat/runtime/QueuedUserMessage.js";
+import {
+  pickLastSuccessfulChatSendText,
+  resolveAssistantMessageForPersistence,
+} from "@services/chat/runtime/UserVisibleText.js";
+import { buildExecuteInputText } from "./Helpers.js";
+
+/**
+ * 在指定 session 中执行一轮请求。
+ *
+ * 说明（中文）
+ * - 若 `sessionId` 能解析为 chat 分发目标，则改为入 chat queue。
+ * - 否则按普通 session 同步执行。
+ */
+export async function executeBySessionId(params: {
+  agentState: AgentRuntime;
+  executionContext: AgentContext;
+  sessionId: string;
+  instructions: string;
+  attachments?: DashboardSessionExecuteAttachmentInput[];
+}) {
+  const sessionId = String(params.sessionId || "").trim();
+  const instructions = String(params.instructions || "").trim();
+  if (!sessionId) throw new Error("Missing sessionId");
+  if (!instructions) throw new Error("Missing instructions");
+
+  const executeInput = await buildExecuteInputText({
+    projectRoot: params.agentState.rootPath,
+    sessionId,
+    instructions,
+    attachments: params.attachments,
+  });
+
+  const dispatchTarget = await resolveDispatchTargetByChatKey({
+    context: params.executionContext,
+    chatKey: sessionId,
+  });
+  if (dispatchTarget) {
+    const queuedText = buildQueuedUserMessageWithInfo({
+      messageId: dispatchTarget.messageId,
+      text: executeInput,
+    });
+    const ingressExtra: JsonObject = {
+      source: "tui_session_execute",
+      ingressKind: "exec",
+      trigger: "api_execute",
+    };
+
+    try {
+      await appendExecIngress({
+        context: params.executionContext,
+        sessionId,
+        channel: dispatchTarget.channel,
+        chatId: dispatchTarget.chatId,
+        text: queuedText,
+        ...(dispatchTarget.chatType ? { targetType: dispatchTarget.chatType } : {}),
+        ...(typeof dispatchTarget.messageThreadId === "number"
+          ? { threadId: dispatchTarget.messageThreadId }
+          : {}),
+        ...(dispatchTarget.messageId ? { messageId: dispatchTarget.messageId } : {}),
+        extra: ingressExtra,
+      });
+    } catch (error) {
+      params.agentState.logger.warn("Dashboard execute ingress append failed", {
+        sessionId,
+        error: String(error),
+      });
+    }
+
+    const enqueueResult = resolveChatQueueStore(params.executionContext).enqueue({
+      kind: "exec",
+      channel: dispatchTarget.channel,
+      targetId: dispatchTarget.chatId,
+      sessionId,
+      text: queuedText,
+      ...(dispatchTarget.chatType ? { targetType: dispatchTarget.chatType } : {}),
+      ...(typeof dispatchTarget.messageThreadId === "number"
+        ? { threadId: dispatchTarget.messageThreadId }
+        : {}),
+      ...(dispatchTarget.messageId ? { messageId: dispatchTarget.messageId } : {}),
+      sessionPersisted: true,
+      extra: ingressExtra,
+    });
+
+    return {
+      success: true,
+      queued: true,
+      queueItemId: enqueueResult.itemId,
+      queuePosition: enqueueResult.lanePosition,
+      userVisible: "",
+    };
+  }
+
+  const session = params.agentState.getSession(sessionId);
+  await session.appendUserMessage({
+    text: executeInput,
+  });
+
+  const result = await session.run({
+    query: executeInput,
+  });
+
+  const userVisible = pickLastSuccessfulChatSendText(result.assistantMessage).trim();
+  try {
+    const messageForPersistence = resolveAssistantMessageForPersistence(
+      result.assistantMessage,
+    );
+    if (messageForPersistence) {
+      await session.appendAssistantMessage({
+        message: messageForPersistence,
+        fallbackText: userVisible,
+        extra: {
+          via: "tui_session_execute",
+          note: "assistant_message_missing",
+        },
+      });
+    }
+    const deferredInjectedMessages = drainDeferredPersistedUserMessages(
+      sessionId,
+    );
+    for (const message of deferredInjectedMessages) {
+      await session.appendUserMessage({
+        message,
+      });
+    }
+  } catch {
+    // ignore
+  }
+
+  return {
+    ...result,
+    userVisible,
+    queued: false,
+  };
+}

package/src/http/dashboard/ExecuteInput.ts

@@ -0,0 +1,236 @@
+/**
+ * Dashboard execute 输入拼装 helper。
+ *
+ * 关键点（中文）
+ * - 负责把 API 传入的附件规范化并落盘。
+ * - 最终统一转成 `<file>` 标签注入到 user message。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import { getCacheDirPath } from "@/config/Paths.js";
+import { renderChatMessageFileTag } from "@services/chat/runtime/ChatMessageMarkup.js";
+import type {
+  DashboardSessionExecuteAttachmentInput,
+  DashboardSessionExecuteAttachmentType,
+} from "@/shared/types/DashboardSessionExecute.js";
+
+const EXECUTE_ATTACHMENT_MAX_COUNT = 8;
+const EXECUTE_ATTACHMENT_MAX_BYTES = 2 * 1024 * 1024;
+const EXECUTE_ATTACHMENT_CONTENT_MAX_CHARS = 1_500_000;
+const EXECUTE_ATTACHMENT_FALLBACK_TEXT = "请查看以上附件并按用户要求处理。";
+
+function normalizeExecuteAttachmentType(
+  value: unknown,
+): DashboardSessionExecuteAttachmentType {
+  const raw = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (
+    raw === "photo" ||
+    raw === "voice" ||
+    raw === "audio" ||
+    raw === "video"
+  ) {
+    return raw;
+  }
+  return "document";
+}
+
+function normalizeAttachmentCaption(value: unknown): string | undefined {
+  const text = String(value || "")
+    .replace(/\r?\n+/g, " ")
+    .replace(/\s+/g, " ")
+    .replace(/\|/g, "/")
+    .trim();
+  if (!text) return undefined;
+  return text.slice(0, 180);
+}
+
+function toProjectRelativePath(projectRoot: string, absPath: string): string | null {
+  const relative = path.relative(projectRoot, absPath);
+  if (!relative) return null;
+  if (relative.startsWith("..")) return null;
+  if (path.isAbsolute(relative)) return null;
+  return relative.split(path.sep).join("/");
+}
+
+function normalizeAttachmentFileName(params: {
+  fileName?: string;
+  fallbackExt: string;
+}): string {
+  const raw = String(params.fileName || "").trim();
+  const base = (raw || "attachment")
+    .replace(/[\\/:*?"<>|]/g, "-")
+    .replace(/\s+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^\.+/, "")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 72);
+  const safeBase = base || "attachment";
+  const fallbackExt = params.fallbackExt.startsWith(".")
+    ? params.fallbackExt
+    : `.${params.fallbackExt}`;
+  const hasExt = /\.[A-Za-z0-9]+$/.test(safeBase);
+  return hasExt ? safeBase : `${safeBase}${fallbackExt}`;
+}
+
+function inferAttachmentExt(params: {
+  type: DashboardSessionExecuteAttachmentType;
+  fileName?: string;
+  contentType?: string;
+}): string {
+  const fromFileName = path.extname(String(params.fileName || "").trim())
+    .toLowerCase()
+    .trim();
+  if (fromFileName) return fromFileName;
+  const contentType = String(params.contentType || "").toLowerCase();
+  if (contentType.includes("markdown")) return ".md";
+  if (contentType.includes("json")) return ".json";
+  if (contentType.includes("html")) return ".html";
+  if (contentType.includes("plain")) return ".txt";
+  if (params.type === "photo") return ".jpg";
+  if (params.type === "voice" || params.type === "audio") return ".mp3";
+  if (params.type === "video") return ".mp4";
+  return ".md";
+}
+
+async function resolveAttachmentPathFromInput(params: {
+  projectRoot: string;
+  attachment: DashboardSessionExecuteAttachmentInput;
+}): Promise<string | null> {
+  const rawPath = String(params.attachment.path || "").trim();
+  if (!rawPath) return null;
+  const abs = path.isAbsolute(rawPath)
+    ? path.normalize(rawPath)
+    : path.resolve(params.projectRoot, rawPath);
+  const relative = toProjectRelativePath(params.projectRoot, abs);
+  if (!relative) return null;
+  const stat = await fs
+    .stat(abs)
+    .then((value) => value)
+    .catch(() => null);
+  if (!stat?.isFile()) return null;
+  return relative;
+}
+
+function resolveAttachmentBytes(
+  attachment: DashboardSessionExecuteAttachmentInput,
+): Buffer | null {
+  const textContent =
+    typeof attachment.content === "string" ? attachment.content : "";
+  if (textContent) {
+    const clipped = textContent.slice(0, EXECUTE_ATTACHMENT_CONTENT_MAX_CHARS);
+    return Buffer.from(clipped, "utf8");
+  }
+
+  const base64 = String(attachment.contentBase64 || "").trim();
+  if (!base64) return null;
+  try {
+    return Buffer.from(base64, "base64");
+  } catch {
+    return null;
+  }
+}
+
+async function materializeAttachmentContent(params: {
+  projectRoot: string;
+  sessionId: string;
+  attachment: DashboardSessionExecuteAttachmentInput;
+  index: number;
+}): Promise<string | null> {
+  const bytes = resolveAttachmentBytes(params.attachment);
+  if (!bytes || bytes.length <= 0) return null;
+  if (bytes.length > EXECUTE_ATTACHMENT_MAX_BYTES) {
+    throw new Error(
+      `Attachment too large (>${EXECUTE_ATTACHMENT_MAX_BYTES} bytes)`,
+    );
+  }
+
+  const type = normalizeExecuteAttachmentType(params.attachment.type);
+  const ext = inferAttachmentExt({
+    type,
+    fileName: params.attachment.fileName,
+    contentType: params.attachment.contentType,
+  });
+  const safeName = normalizeAttachmentFileName({
+    fileName: params.attachment.fileName,
+    fallbackExt: ext,
+  });
+  const safeContext = String(params.sessionId || "session")
+    .replace(/[^A-Za-z0-9_-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32);
+  const prefix = safeContext || "context";
+  const fileName = `${Date.now()}-${prefix}-${String(params.index + 1).padStart(2, "0")}-${safeName}`;
+  const cacheDir = path.join(getCacheDirPath(params.projectRoot), "chrome-extension");
+  await fs.ensureDir(cacheDir);
+  const absPath = path.join(cacheDir, fileName);
+  await fs.writeFile(absPath, bytes);
+  return toProjectRelativePath(params.projectRoot, absPath);
+}
+
+function toAttachmentLine(params: {
+  type: DashboardSessionExecuteAttachmentType;
+  relativePath: string;
+  caption?: string;
+}): string {
+  return renderChatMessageFileTag({
+    type: params.type,
+    path: params.relativePath,
+    ...(params.caption ? { caption: params.caption } : {}),
+  });
+}
+
+/**
+ * 构造 execute 入站文本。
+ */
+export async function buildExecuteInputText(params: {
+  projectRoot: string;
+  sessionId: string;
+  instructions: string;
+  attachments?: DashboardSessionExecuteAttachmentInput[];
+}): Promise<string> {
+  const instructions = String(params.instructions || "").trim();
+  const inputAttachments = Array.isArray(params.attachments)
+    ? params.attachments.slice(0, EXECUTE_ATTACHMENT_MAX_COUNT)
+    : [];
+  if (inputAttachments.length === 0) return instructions;
+
+  const lines: string[] = [];
+  for (let index = 0; index < inputAttachments.length; index += 1) {
+    const attachment = inputAttachments[index];
+    if (!attachment || typeof attachment !== "object") continue;
+    const type = normalizeExecuteAttachmentType(attachment.type);
+    const caption = normalizeAttachmentCaption(attachment.caption);
+
+    const reusePath = await resolveAttachmentPathFromInput({
+      projectRoot: params.projectRoot,
+      attachment,
+    });
+    const relativePath =
+      reusePath ||
+      (await materializeAttachmentContent({
+        projectRoot: params.projectRoot,
+        sessionId: params.sessionId,
+        attachment,
+        index,
+      }));
+    if (!relativePath) continue;
+
+    lines.push(
+      toAttachmentLine({
+        type,
+        relativePath,
+        ...(caption ? { caption } : {}),
+      }),
+    );
+  }
+
+  if (lines.length === 0) return instructions;
+  return [lines.join("\n"), instructions || EXECUTE_ATTACHMENT_FALLBACK_TEXT]
+    .filter(Boolean)
+    .join("\n\n")
+    .trim();
+}

package/src/http/dashboard/Helpers.ts

@@ -0,0 +1,22 @@
+/**
+ * Dashboard helper 聚合出口。
+ *
+ * 关键点（中文）
+ * - 兼容 dashboard 路由层现有 import 路径。
+ * - 具体实现已拆分到独立子模块，避免单文件继续膨胀。
+ */
+
+export { toLimit, toOptionalString, decodeMaybe } from "./CommonHelpers.js";
+export { buildExecuteInputText } from "./ExecuteInput.js";
+export {
+  loadSessionMessagesFromFile,
+  resolveUiMessagePreview,
+  toUiMessageTimeline,
+} from "./MessageTimeline.js";
+export { listDashboardSessionSummaries } from "./SessionSummaryStore.js";
+export {
+  TASK_RUN_DIR_REGEX,
+  listTaskRuns,
+  readRecentLogs,
+  readTaskRunDetail,
+} from "./TaskStore.js";

package/src/http/dashboard/MessageTimeline.ts

@@ -0,0 +1,269 @@
+/**
+ * Dashboard 消息时间线 helper。
+ *
+ * 关键点（中文）
+ * - 负责把上下文消息映射成 dashboard 可视时间线。
+ * - 同时提供消息文件读取能力。
+ */
+
+import fs from "fs-extra";
+import {
+  getToolName,
+  isTextUIPart,
+  isToolUIPart,
+  type UIMessagePart,
+} from "ai";
+import type {
+  SessionMessageV1,
+  SessionMetadataV1,
+} from "@/types/session/SessionMessages.js";
+import { pickLastSuccessfulChatSendText } from "@services/chat/runtime/UserVisibleText.js";
+import { extractToolCallsFromUiMessage } from "@services/chat/runtime/UIMessageTransformer.js";
+import type { DashboardTimelineEvent, DashboardTimelineRole } from "@/shared/types/DashboardData.js";
+import { truncateText } from "./CommonHelpers.js";
+
+type AnyUiPart = UIMessagePart<Record<string, never>, Record<string, never>>;
+
+type ToolPartCompatShape = {
+  type?: unknown;
+  state?: unknown;
+  input?: unknown;
+  output?: unknown;
+  errorText?: unknown;
+  error?: unknown;
+  approval?: { reason?: unknown } | null;
+};
+
+function stringifyForDisplay(input: unknown, maxChars = 2400): string {
+  if (input === undefined) return "";
+  if (input === null) return "null";
+  if (typeof input === "string") {
+    const value = input.trim();
+    if (!value) return "";
+    try {
+      const parsed = JSON.parse(value);
+      return truncateText(JSON.stringify(parsed, null, 2), maxChars);
+    } catch {
+      return truncateText(value, maxChars);
+    }
+  }
+  if (typeof input === "number" || typeof input === "boolean") {
+    return truncateText(String(input), maxChars);
+  }
+  try {
+    return truncateText(JSON.stringify(input, null, 2), maxChars);
+  } catch {
+    return truncateText(String(input), maxChars);
+  }
+}
+
+function extractMessageText(parts: unknown): string {
+  if (!Array.isArray(parts)) return "";
+  const texts: string[] = [];
+  for (const part of parts) {
+    if (!part || typeof part !== "object") continue;
+    const p = part as { type?: unknown; text?: unknown };
+    if (p.type !== "text") continue;
+    if (typeof p.text !== "string") continue;
+    const value = p.text.trim();
+    if (!value) continue;
+    texts.push(value);
+  }
+  return texts.join("\n").trim();
+}
+
+function extractAssistantToolSummary(message: SessionMessageV1): string {
+  const toolCalls = extractToolCallsFromUiMessage(message);
+  if (!Array.isArray(toolCalls) || toolCalls.length === 0) return "";
+  const toolNames = Array.from(
+    new Set(toolCalls.map((item) => String(item.tool || "").trim()).filter(Boolean)),
+  );
+  if (toolNames.length === 0) return "";
+  return `[tool] ${toolNames.join(", ")}`;
+}
+
+function resolveToolName(part: ToolPartCompatShape, aiToolName?: string): string {
+  const fromAi = String(aiToolName || "").trim();
+  if (fromAi) return fromAi;
+
+  const rawType = typeof part.type === "string" ? part.type.trim() : "";
+  if (rawType.startsWith("tool-")) return rawType.slice("tool-".length);
+  return "unknown_tool";
+}
+
+function extractToolCallInput(part: ToolPartCompatShape): unknown {
+  return part.input ?? undefined;
+}
+
+function extractToolResultOutput(part: ToolPartCompatShape): unknown {
+  const state = typeof part.state === "string" ? part.state.trim() : "";
+  if (state === "output-available") return part.output;
+  if (state === "output-error") {
+    return { error: part.errorText ?? part.error ?? "tool_error" };
+  }
+  if (state === "output-denied") {
+    return {
+      error: "tool_denied",
+      reason: part.approval?.reason ?? "",
+    };
+  }
+  if (
+    state === "input-available" ||
+    state === "input-streaming" ||
+    state === "output-streaming"
+  ) {
+    return undefined;
+  }
+  return undefined;
+}
+
+function toUiMessageEvent(params: {
+  message: SessionMessageV1;
+  role: DashboardTimelineRole;
+  text: string;
+  sequence: number;
+  toolName?: string;
+}): DashboardTimelineEvent {
+  const { message, role, text, sequence, toolName } = params;
+  const metadata = (message.metadata || null) as SessionMetadataV1 | null;
+
+  return {
+    id: `${String(message.id || "")}:${sequence}`,
+    role,
+    ...(typeof metadata?.ts === "number" ? { ts: metadata.ts } : {}),
+    ...(typeof metadata?.kind === "string" ? { kind: metadata.kind } : {}),
+    ...(typeof metadata?.source === "string" ? { source: metadata.source } : {}),
+    text,
+    ...(toolName ? { toolName } : {}),
+  };
+}
+
+function resolveUiMessageText(message: SessionMessageV1): string {
+  const plainText = extractMessageText(message.parts);
+  if (plainText) return plainText;
+
+  if (message.role !== "assistant") return "";
+
+  const userVisible = pickLastSuccessfulChatSendText(message).trim();
+  if (userVisible) return userVisible;
+
+  return extractAssistantToolSummary(message);
+}
+
+/**
+ * 转成 dashboard 时间线。
+ */
+export function toUiMessageTimeline(
+  message: SessionMessageV1,
+): DashboardTimelineEvent[] {
+  if (message.role !== "assistant") {
+    return [
+      toUiMessageEvent({
+        message,
+        role: message.role,
+        text: resolveUiMessageText(message),
+        sequence: 0,
+      }),
+    ];
+  }
+
+  const parts = Array.isArray(message.parts)
+    ? (message.parts as AnyUiPart[])
+    : [];
+  const events: DashboardTimelineEvent[] = [];
+  let sequence = 0;
+
+  for (const part of parts) {
+    if (!part || typeof part !== "object") continue;
+    const partObject = part as ToolPartCompatShape;
+
+    if (isTextUIPart(part)) {
+      const text = String(part.text || "").trim();
+      if (!text) continue;
+      events.push(
+        toUiMessageEvent({
+          message,
+          role: "assistant",
+          text,
+          sequence,
+        }),
+      );
+      sequence += 1;
+      continue;
+    }
+
+    if (isToolUIPart(part)) {
+      const toolName = resolveToolName(partObject, String(getToolName(part) || ""));
+      const inputText = stringifyForDisplay(extractToolCallInput(partObject));
+      events.push(
+        toUiMessageEvent({
+          message,
+          role: "tool-call",
+          text: inputText || "(empty)",
+          sequence,
+          toolName,
+        }),
+      );
+      sequence += 1;
+
+      const output = extractToolResultOutput(partObject);
+      if (output !== undefined) {
+        events.push(
+          toUiMessageEvent({
+            message,
+            role: "tool-result",
+            text: stringifyForDisplay(output) || "(empty)",
+            sequence,
+            toolName,
+          }),
+        );
+        sequence += 1;
+      }
+      continue;
+    }
+  }
+
+  // 关键点（中文）：assistant 若没有文本 part，也要保留一条可见事件，避免 dashboard 空白。
+  if (events.length === 0) {
+    events.push(
+      toUiMessageEvent({
+        message,
+        role: "assistant",
+        text: resolveUiMessageText(message),
+        sequence: 0,
+      }),
+    );
+  }
+
+  return events;
+}
+
+/**
+ * 读取 session 消息文件。
+ */
+export async function loadSessionMessagesFromFile(
+  filePath: string,
+): Promise<SessionMessageV1[]> {
+  if (!(await fs.pathExists(filePath))) return [];
+  const raw = await fs.readFile(filePath, "utf-8");
+  const lines = raw.split("\n").filter(Boolean);
+  const out: SessionMessageV1[] = [];
+  for (const line of lines) {
+    try {
+      const item = JSON.parse(line) as SessionMessageV1;
+      if (!item || typeof item !== "object") continue;
+      if (item.role !== "user" && item.role !== "assistant") continue;
+      out.push(item);
+    } catch {
+      // 关键点（中文）：单行损坏不应影响整体可读性。
+    }
+  }
+  return out;
+}
+
+/**
+ * 读取适合摘要展示的消息预览文本。
+ */
+export function resolveUiMessagePreview(message: SessionMessageV1): string {
+  return resolveUiMessageText(message);
+}