@downcity/city 1.1.4 → 1.1.6

package/src/cli/agent/AgentChat.ts

@@ -0,0 +1,415 @@
+/**
+ * `city agent chat` 命令实现。
+ *
+ * 关键点（中文）
+ * - 统一覆盖交互式持续对话与一次性消息模式，不再保留独立 `quest` 命令。
+ * - 目标 agent 始终按 managed agent registry 名称解析，不依赖当前工作目录。
+ * - 默认使用独立 local-cli 主会话：`local-cli-chat-main`。
+ */
+
+import { createInterface } from "node:readline/promises";
+import chalk from "chalk";
+import prompts from "prompts";
+import { callAgentTransport } from "@downcity/agent";
+import { emitCliBlock } from "../shared/CliReporter.js";
+import {
+  createSpinner,
+  runWithSpinner,
+  shouldRenderSpinner,
+  type Spinner,
+} from "@/utils/cli/Spinner.js";
+import { printResult } from "@/utils/cli/CliOutput.js";
+import {
+  resolveProjectRootByAgentName,
+  validateAgentProjectRoot,
+} from "../service/ServiceCommandSupport.js";
+import { listRegisteredAgentsForCli } from "./AgentSelection.js";
+import type {
+  AgentChatCliOptions,
+  AgentChatExecutionOutcome,
+  AgentChatExecuteResponse,
+  AgentChatTransportOptions,
+} from "./AgentChatTypes.js";
+import { AGENT_CHAT_DEFAULT_SESSION_ID } from "./AgentChatTypes.js";
+
+const AGENT_CHAT_EXECUTE_TIMEOUT_MS = 120_000;
+function normalizeChatMessage(input: string): string {
+  return String(input || "").trim();
+}
+
+function isChatSuccess(payload: AgentChatExecuteResponse | undefined): boolean {
+  if (!payload || payload.success !== true) return false;
+  if (payload.result?.success === false) return false;
+  return true;
+}
+
+async function resolveChatTargetAgentName(inputName?: string): Promise<string | null> {
+  const explicit = String(inputName || "").trim();
+  if (explicit) return explicit;
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    emitCliBlock({
+      tone: "error",
+      title: "Agent name is required",
+      note: "Use `city agent chat --to <agentName>` or run this command in an interactive terminal.",
+    });
+    return null;
+  }
+
+  const runningAgents = (await listRegisteredAgentsForCli()).filter(
+    (item) => item.status === "running",
+  );
+  if (runningAgents.length === 0) {
+    emitCliBlock({
+      tone: "error",
+      title: "No running agents",
+      note: "Run `city agent start` first.",
+    });
+    return null;
+  }
+
+  const response = (await prompts({
+    type: "select",
+    name: "agentName",
+    message: "选择要聊天的 Agent",
+    choices: runningAgents.map((agent) => ({
+      title: agent.name,
+      description: agent.projectRoot,
+      value: agent.name,
+    })),
+    initial: 0,
+  })) as { agentName?: string };
+  const agentName = String(response.agentName || "").trim();
+  if (!agentName) {
+    emitCliBlock({
+      tone: "info",
+      title: "Agent chat cancelled",
+    });
+    return null;
+  }
+  return agentName;
+}
+
+function printAssistantReply(replyText: string): void {
+  const text = String(replyText || "").trim();
+  if (!text) {
+    emitCliBlock({
+      tone: "info",
+      title: "No visible reply",
+      note: "The turn completed, but no user-visible text was returned.",
+    });
+    return;
+  }
+  console.log(`\n${text}\n`);
+}
+
+function printQueuedResult(params: {
+  agentName: string;
+  payload: AgentChatExecuteResponse;
+}): void {
+  emitCliBlock({
+    tone: "info",
+    title: "Turn queued",
+    facts: [
+      {
+        label: "agent",
+        value: params.agentName,
+      },
+      ...(params.payload.result?.queueItemId
+        ? [
+            {
+              label: "queue item",
+              value: params.payload.result.queueItemId,
+            },
+          ]
+        : []),
+    ],
+  });
+}
+
+/**
+ * 向目标 agent 的 Console 主会话发送一轮消息。
+ */
+export async function executeAgentChatTurn(params: {
+  agentName: string;
+  message: string;
+  transport?: AgentChatTransportOptions;
+}): Promise<AgentChatExecutionOutcome> {
+  const agentName = String(params.agentName || "").trim();
+  const message = normalizeChatMessage(params.message);
+  const sessionId = AGENT_CHAT_DEFAULT_SESSION_ID;
+
+  if (!agentName) {
+    return {
+      agentName: "",
+      sessionId,
+      success: false,
+      error: "Missing target agent name.",
+    };
+  }
+
+  if (!message) {
+    return {
+      agentName,
+      sessionId,
+      success: false,
+      error: "Chat message is required.",
+    };
+  }
+
+  const resolved = await resolveProjectRootByAgentName(agentName);
+  if (!resolved.projectRoot) {
+    return {
+      agentName,
+      sessionId,
+      success: false,
+      error: resolved.error || "Failed to resolve agent project path",
+    };
+  }
+
+  const pathError = validateAgentProjectRoot(resolved.projectRoot);
+  if (pathError) {
+    return {
+      agentName,
+      projectRoot: resolved.projectRoot,
+      sessionId,
+      success: false,
+      error: pathError,
+    };
+  }
+
+  const remote = await callAgentTransport<AgentChatExecuteResponse>({
+    projectRoot: resolved.projectRoot,
+    path: `/api/control/sessions/${encodeURIComponent(sessionId)}/execute`,
+    method: "POST",
+    timeoutMs: AGENT_CHAT_EXECUTE_TIMEOUT_MS,
+    host: params.transport?.host,
+    port: params.transport?.port,
+    authToken: params.transport?.token,
+    body: {
+      instructions: message,
+    },
+  });
+
+  if (!remote.success || !remote.data) {
+    return {
+      agentName,
+      projectRoot: resolved.projectRoot,
+      sessionId,
+      success: false,
+      error: remote.error || "Agent daemon unreachable or returned empty error (try `city agent restart`)",
+    };
+  }
+
+  return {
+    agentName,
+    projectRoot: resolved.projectRoot,
+    sessionId: String(remote.data.sessionId || sessionId),
+    success: isChatSuccess(remote.data),
+    payload: remote.data,
+    ...(isChatSuccess(remote.data)
+      ? {}
+      : {
+          error:
+            String(remote.data.result?.error || remote.data.error || "").trim() ||
+            "Daemon error (check `city agent status` and `city agent doctor`)",
+        }),
+  };
+}
+
+async function runOneShotChat(params: {
+  agentName: string;
+  message: string;
+  options: AgentChatCliOptions;
+}): Promise<void> {
+  const outcome = await runWithSpinner(async () => {
+    return await executeAgentChatTurn({
+      agentName: params.agentName,
+      message: params.message,
+      transport: {
+        host: params.options.host,
+        port: params.options.port,
+        token: params.options.token,
+      },
+    });
+  }, {
+    text: `${params.agentName} is replying...`,
+    disabled: params.options.json === true,
+  });
+
+  if (params.options.json === true) {
+    printResult({
+      asJson: true,
+      success: outcome.success,
+      title: "agent chat",
+      payload: {
+        agent: params.agentName,
+        ...(outcome.projectRoot ? { projectRoot: outcome.projectRoot } : {}),
+        sessionId: outcome.sessionId,
+        ...(outcome.payload?.result ? { result: outcome.payload.result } : {}),
+        ...(outcome.error ? { error: outcome.error } : {}),
+      },
+    });
+    return;
+  }
+
+  if (!outcome.success || !outcome.payload) {
+    emitCliBlock({
+      tone: "error",
+      title: "Agent chat failed",
+      facts: [
+        {
+          label: "agent",
+          value: params.agentName,
+        },
+        {
+          label: "error",
+          value: outcome.error || "Agent daemon returned empty error (check config with `city agent status`)",
+        },
+      ],
+    });
+    return;
+  }
+
+  if (outcome.payload.result?.queued === true) {
+    printQueuedResult({
+      agentName: params.agentName,
+      payload: outcome.payload,
+    });
+    return;
+  }
+
+  printAssistantReply(String(outcome.payload.result?.userVisible || ""));
+}
+
+/**
+ * 启动交互式持续对话。
+ */
+async function runInteractiveChat(params: {
+  agentName: string;
+  options: AgentChatCliOptions;
+}): Promise<void> {
+  const prompt = `${chalk.cyan(params.agentName)} ${chalk.dim("›")} `;
+  const helpText = [
+    `${chalk.dim("/exit, /quit  — 退出对话")}`,
+    `${chalk.dim("/clear       — 清屏")}`,
+    `${chalk.dim("/help        — 显示此帮助")}`,
+    `${chalk.dim("Ctrl+C       — 退出对话")}`,
+  ];
+
+  emitCliBlock({
+    tone: "info",
+    title: `Agent chat · ${params.agentName}`,
+    note: `Session: local-cli-chat-main · ${helpText[0].replace(chalk.dim(""), "").trim()}`,
+  });
+  console.log(helpText.join("\n"));
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true,
+  });
+
+  try {
+    while (true) {
+      const line = await rl.question(prompt);
+      const text = normalizeChatMessage(line);
+      if (!text) continue;
+      if (text === "/exit" || text === "/quit") break;
+      if (text === "/clear") {
+        console.clear();
+        continue;
+      }
+      if (text === "/help") {
+        console.log(helpText.join("\n"));
+        continue;
+      }
+
+      const outcome = await runWithSpinner(async () => {
+        return await executeAgentChatTurn({
+          agentName: params.agentName,
+          message: text,
+          transport: {
+            host: params.options.host,
+            port: params.options.port,
+            token: params.options.token,
+          },
+        });
+      }, {
+        text: `${params.agentName} is replying...`,
+      });
+
+      if (!outcome.success || !outcome.payload) {
+        emitCliBlock({
+          tone: "error",
+          title: "Agent chat failed",
+          facts: [
+            {
+              label: "agent",
+              value: params.agentName,
+            },
+            {
+              label: "error",
+              value: outcome.error || "Agent daemon returned empty error (check config with `city agent status`)",
+            },
+          ],
+        });
+        continue;
+      }
+
+      if (outcome.payload.result?.queued === true) {
+        printQueuedResult({
+          agentName: params.agentName,
+          payload: outcome.payload,
+        });
+        continue;
+      }
+
+      printAssistantReply(String(outcome.payload.result?.userVisible || ""));
+    }
+  } finally {
+    rl.close();
+  }
+  console.log(chalk.dim("Chat ended."));
+}
+
+/**
+ * `city agent chat` 统一入口。
+ */
+export async function chatCommand(options: AgentChatCliOptions): Promise<void> {
+  const agentName = await resolveChatTargetAgentName(options.to);
+  if (!agentName) return;
+
+  const oneShotMessage = normalizeChatMessage(String(options.message || ""));
+  if (oneShotMessage) {
+    await runOneShotChat({
+      agentName,
+      message: oneShotMessage,
+      options,
+    });
+    return;
+  }
+
+  if (options.json === true) {
+    emitCliBlock({
+      tone: "error",
+      title: "JSON mode requires --message",
+      note: "Use `city agent chat --message <text> --json` for one-shot structured output.",
+    });
+    return;
+  }
+
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    emitCliBlock({
+      tone: "error",
+      title: "Interactive terminal required",
+      note: "Use this command in a local terminal with TTY support, or pass `--message` for one-shot mode.",
+    });
+    return;
+  }
+
+  await runInteractiveChat({
+    agentName,
+    options,
+  });
+}

package/src/cli/agent/AgentChatTypes.ts

@@ -0,0 +1,92 @@
+/**
+ * `city agent chat` CLI 类型。
+ *
+ * 关键点（中文）
+ * - 统一覆盖交互式持续对话与一次性消息两种入口。
+ * - 默认使用独立的 local-cli 会话，避免与控制面 UI 上下文互相污染。
+ */
+
+/**
+ * `city agent chat` 默认使用的 local-cli 会话 ID。
+ */
+export const AGENT_CHAT_DEFAULT_SESSION_ID = "local-cli-chat-main";
+
+/**
+ * `city agent chat` 命令选项。
+ */
+export interface AgentChatCliOptions {
+  /** 目标 agent 名称。 */
+  to?: string;
+  /** 一次性发送的消息文本。 */
+  message?: string;
+  /** 是否输出 JSON。 */
+  json?: boolean;
+  /** 覆盖目标 runtime host。 */
+  host?: string;
+  /** 覆盖目标 runtime port。 */
+  port?: number;
+  /** 显式覆盖 Bearer Token。 */
+  token?: string;
+}
+
+/**
+ * Control execute 结果片段。
+ */
+export interface AgentChatExecuteResult {
+  /** 本轮执行是否成功。 */
+  success?: boolean;
+  /** 是否已经进入队列。 */
+  queued?: boolean;
+  /** 队列项 ID。 */
+  queueItemId?: string;
+  /** 当前队列位置。 */
+  queuePosition?: number;
+  /** 面向用户可直接阅读的回复文本。 */
+  userVisible?: string;
+  /** 错误信息。 */
+  error?: string;
+}
+
+/**
+ * Control execute 响应体。
+ */
+export interface AgentChatExecuteResponse {
+  /** HTTP 路由层是否成功处理请求。 */
+  success: boolean;
+  /** 实际执行使用的 sessionId。 */
+  sessionId?: string;
+  /** 执行结果。 */
+  result?: AgentChatExecuteResult;
+  /** 顶层错误信息。 */
+  error?: string;
+}
+
+/**
+ * 复用 chat transport 时的基础选项。
+ */
+export interface AgentChatTransportOptions {
+  /** 覆盖目标 runtime host。 */
+  host?: string;
+  /** 覆盖目标 runtime port。 */
+  port?: number;
+  /** 显式覆盖 Bearer Token。 */
+  token?: string;
+}
+
+/**
+ * 单轮 chat 执行结果。
+ */
+export interface AgentChatExecutionOutcome {
+  /** 目标 agent 名称。 */
+  agentName: string;
+  /** 目标 agent 项目根目录。 */
+  projectRoot?: string;
+  /** 实际执行使用的 sessionId。 */
+  sessionId: string;
+  /** 请求是否成功。 */
+  success: boolean;
+  /** 执行结果响应体。 */
+  payload?: AgentChatExecuteResponse;
+  /** 失败时的错误文本。 */
+  error?: string;
+}

package/src/cli/agent/AgentHistory.ts

@@ -0,0 +1,187 @@
+/**
+ * AgentHistory：`city agent history` 维护命令。
+ *
+ * 关键点（中文）
+ * - 面向用户提供定点硬清理能力，用于处理单个坏 session。
+ * - 清理范围固定为 session messages、chat audit、channel route 三处。
+ * - 命令必须显式传 `--hard`，避免误删运行时历史。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import {
+  getDowncityChannelDirPath,
+  getDowncityChannelMetaPath,
+  getDowncityChatSessionDirPath,
+  getDowncitySessionDirPath,
+} from "@/config/Paths.js";
+import { CliError } from "../shared/CliError.js";
+import type {
+  AgentHistoryChannelMetaFile,
+  AgentHistoryCleanOptions,
+  AgentHistoryCleanResult,
+} from "./AgentHistoryTypes.js";
+import { emitCliBlock } from "../shared/CliReporter.js";
+import { printResult } from "@/utils/cli/CliOutput.js";
+
+function normalizeText(input: unknown): string {
+  return String(input || "").trim();
+}
+
+function normalizeThreadId(input: unknown): string {
+  const text = normalizeText(input);
+  if (!text) return "";
+  const numberValue = Number(text);
+  if (!Number.isFinite(numberValue) || numberValue <= 0) return "";
+  return String(Math.trunc(numberValue));
+}
+
+function buildTargetKey(options: AgentHistoryCleanOptions): string {
+  const channel = normalizeText(options.channel);
+  const chatId = normalizeText(options.chatId);
+  if (!channel || !chatId) return "";
+  return [
+    channel,
+    chatId,
+    normalizeText(options.targetType),
+    normalizeThreadId(options.threadId),
+  ].join("|");
+}
+
+async function readChannelMeta(projectRoot: string): Promise<AgentHistoryChannelMetaFile> {
+  const filePath = getDowncityChannelMetaPath(projectRoot);
+  const raw = (await fs.readJson(filePath).catch(() => null)) as
+    | AgentHistoryChannelMetaFile
+    | null;
+  return raw && typeof raw === "object" ? raw : {};
+}
+
+function resolveSessionIdFromMeta(
+  meta: AgentHistoryChannelMetaFile,
+  options: AgentHistoryCleanOptions,
+): string {
+  const targetKey = buildTargetKey(options);
+  if (!targetKey) return "";
+
+  const mapped = normalizeText(meta.sessionIdByTargetKey?.[targetKey]);
+  if (mapped) return mapped;
+
+  const routes = meta.routesBySessionId || {};
+  const channel = normalizeText(options.channel);
+  const chatId = normalizeText(options.chatId);
+  const targetType = normalizeText(options.targetType);
+  const threadId = normalizeThreadId(options.threadId);
+  for (const route of Object.values(routes)) {
+    if (normalizeText(route.channel) !== channel) continue;
+    if (normalizeText(route.chatId) !== chatId) continue;
+    if (targetType && normalizeText(route.targetType) !== targetType) continue;
+    if (threadId && normalizeThreadId(route.threadId) !== threadId) continue;
+    const sessionId = normalizeText(route.sessionId);
+    if (sessionId) return sessionId;
+  }
+  return "";
+}
+
+async function removeRouteFromMeta(params: {
+  projectRoot: string;
+  sessionId: string;
+}): Promise<boolean> {
+  const metaPath = getDowncityChannelMetaPath(params.projectRoot);
+  const meta = await readChannelMeta(params.projectRoot);
+  const routesBySessionId = meta.routesBySessionId || {};
+  const sessionIdByTargetKey = meta.sessionIdByTargetKey || {};
+  let removed = false;
+
+  if (routesBySessionId[params.sessionId]) {
+    delete routesBySessionId[params.sessionId];
+    removed = true;
+  }
+
+  for (const [targetKey, mappedSessionId] of Object.entries(sessionIdByTargetKey)) {
+    if (normalizeText(mappedSessionId) !== params.sessionId) continue;
+    delete sessionIdByTargetKey[targetKey];
+    removed = true;
+  }
+
+  if (!removed) return false;
+
+  await fs.ensureDir(getDowncityChannelDirPath(params.projectRoot));
+  await fs.writeJson(
+    metaPath,
+    {
+      ...meta,
+      v: 1,
+      updatedAt: Date.now(),
+      sessionIdByTargetKey,
+      routesBySessionId,
+    },
+    { spaces: 2 },
+  );
+  return true;
+}
+
+/**
+ * 执行 `city agent history clean`。
+ */
+export async function agentHistoryCleanCommand(
+  projectRoot: string,
+  options: AgentHistoryCleanOptions,
+): Promise<AgentHistoryCleanResult> {
+  if (options.hard !== true) {
+    throw new CliError({
+      title: "Hard clean requires --hard",
+      note: "History clean deletes runtime files for one session.",
+      fix: "Add --hard after verifying --session-id or --channel/--chat-id.",
+    });
+  }
+
+  const meta = await readChannelMeta(projectRoot);
+  const sessionId =
+    normalizeText(options.sessionId) || resolveSessionIdFromMeta(meta, options);
+  if (!sessionId) {
+    throw new CliError({
+      title: "Cannot resolve target session",
+      note: "Provide --session-id, or provide --channel and --chat-id for a known chat route.",
+      fix: "Example: city agent history clean <path> --channel telegram --chat-id 8444574557 --hard",
+    });
+  }
+
+  const sessionDir = getDowncitySessionDirPath(projectRoot, sessionId);
+  const chatDir = getDowncityChatSessionDirPath(projectRoot, sessionId);
+  const removedSessionDir = await fs.pathExists(sessionDir);
+  const removedChatDir = await fs.pathExists(chatDir);
+  if (removedSessionDir) await fs.remove(sessionDir);
+  if (removedChatDir) await fs.remove(chatDir);
+  const removedRoute = await removeRouteFromMeta({ projectRoot, sessionId });
+
+  const result: AgentHistoryCleanResult = {
+    projectRoot: path.resolve(projectRoot),
+    sessionId,
+    removedSessionDir,
+    removedChatDir,
+    removedRoute,
+  };
+
+  if (options.json === true) {
+    printResult({
+      asJson: true,
+      success: true,
+      title: "agent history cleaned",
+      payload: { ...result },
+    });
+    return result;
+  }
+
+  emitCliBlock({
+    tone: "success",
+    title: "Agent history cleaned",
+    facts: [
+      { label: "Project", value: result.projectRoot },
+      { label: "Session", value: result.sessionId },
+      { label: "Session dir", value: result.removedSessionDir ? "removed" : "not found" },
+      { label: "Chat dir", value: result.removedChatDir ? "removed" : "not found" },
+      { label: "Route", value: result.removedRoute ? "removed" : "not found" },
+    ],
+  });
+  return result;
+}