@downcity/agent 1.1.10 → 1.1.11

package/src/service/builtins/chat/runtime/ChatActionInput.ts

@@ -7,9 +7,7 @@
  * - `chat send` 的 frontmatter / <file> 协议也在这里完成标准化解析。
  */
 
-import fs from "node:fs/promises";
-import path from "node:path";
-import type { JsonObject, JsonValue } from "@/utils/types/Json.js";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 import type { ServiceActionCommandInput } from "@/service/types/Service.js";
 import type {
   ChatConfigureActionPayload,
@@ -18,176 +16,21 @@ import type {
   ChatInfoActionPayload,
   ChatListActionPayload,
   ChatReactActionPayload,
-  ChatSendActionPayload,
 } from "@/service/builtins/chat/types/ChatService.js";
-import { buildChatMessageText, parseChatMessageMarkup } from "@/service/builtins/chat/runtime/ChatMessageMarkup.js";
-import { parseChatSendOptionsFromMetadata } from "@/service/builtins/chat/runtime/ChatSendMetadata.js";
-import { normalizeChatSendText, resolveChatKey } from "@/service/builtins/chat/Action.js";
+import { resolveChatKey } from "@/service/builtins/chat/Action.js";
 import { resolveChatChannelNameOrThrow } from "@/service/builtins/chat/runtime/ChatChannelFacade.js";
-
-function isJsonObject(value: JsonValue): value is JsonObject {
-  return !!value && typeof value === "object" && !Array.isArray(value);
-}
-
-function getStringOpt(opts: Record<string, JsonValue>, key: string): string {
-  return typeof opts[key] === "string" ? String(opts[key]).trim() : "";
-}
-
-function getBooleanOpt(opts: Record<string, JsonValue>, key: string): boolean {
-  return opts[key] === true;
-}
-
-function parsePositiveIntOptionOrThrow(value: string, fieldName: string): number {
-  const text = String(value || "").trim();
-  if (!text) {
-    throw new Error(`${fieldName} is required`);
-  }
-  if (!/^\d+$/.test(text)) {
-    throw new Error(`Invalid ${fieldName}: ${value}`);
-  }
-  const parsed = Number.parseInt(text, 10);
-  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
-    throw new Error(`Invalid ${fieldName}: ${value}`);
-  }
-  return parsed;
-}
-
-function parseNonNegativeIntOptionOrThrow(value: string, fieldName: string): number {
-  const text = String(value || "").trim();
-  if (!text) {
-    throw new Error(`${fieldName} is required`);
-  }
-  if (!/^\d+$/.test(text)) {
-    throw new Error(`Invalid ${fieldName}: ${value}`);
-  }
-  const parsed = Number.parseInt(text, 10);
-  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed < 0) {
-    throw new Error(`Invalid ${fieldName}: ${value}`);
-  }
-  return parsed;
-}
-
-function looksLikeIsoDatetimeWithoutTimezone(value: string): boolean {
-  const text = String(value || "").trim();
-  if (!text) return false;
-  const isoLike = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/.test(text);
-  if (!isoLike) return false;
-  return !/(?:Z|[+-]\d{2}:\d{2})$/i.test(text);
-}
-
-/**
- * 解析定时发送时间。
- *
- * 支持格式（中文）
- * - Unix 时间戳：秒或毫秒（纯数字）
- * - ISO 时间字符串：例如 `2026-03-05T20:30:00+08:00`
- */
-function parseSendTimeOptionOrThrow(value: string, fieldName: string): number {
-  const text = String(value || "").trim();
-  if (!text) {
-    throw new Error(`${fieldName} is required`);
-  }
-
-  if (/^\d+$/.test(text)) {
-    const parsed = Number.parseInt(text, 10);
-    if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
-      throw new Error(`Invalid ${fieldName}: ${value}`);
-    }
-    // 关键点（中文）：10 位通常是秒级时间戳，统一转换为毫秒。
-    return parsed < 1_000_000_000_000 ? parsed * 1000 : parsed;
-  }
-  if (looksLikeIsoDatetimeWithoutTimezone(text)) {
-    throw new Error(
-      `Invalid ${fieldName}: ${value}. ISO datetime must include timezone offset (e.g. +08:00 or Z).`,
-    );
-  }
-
-  const parsed = Date.parse(text);
-  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
-    throw new Error(
-      `Invalid ${fieldName}: ${value}. Use Unix timestamp (seconds/ms) or ISO datetime.`,
-    );
-  }
-  return parsed;
-}
-
-/**
- * 解析 chat send 正文协议。
- *
- * 关键点（中文）
- * - 正文支持 frontmatter metadata，字段语义与 `city chat send` 参数一致。
- * - `<file>` 为唯一附件协议；会保留在规范化正文里，交给渠道出站阶段解析。
- * - 显式 CLI/API 参数优先，但与 metadata 冲突的 delay/time 组合会报错。
- */
-function parseChatSendTextProtocol(params: {
-  rawText: string;
-  explicitChatKey?: string;
-  explicitDelayMs?: number;
-  explicitSendAtMs?: number;
-  explicitReplyToMessage?: boolean;
-  explicitMessageId?: string;
-}): ChatSendActionPayload {
-  const parsed = parseChatMessageMarkup(normalizeChatSendText(params.rawText));
-  const metadataOptions = parseChatSendOptionsFromMetadata({
-    metadata: parsed.metadata,
-    strict: true,
-  });
-
-  const delayMs =
-    typeof params.explicitDelayMs === "number"
-      ? params.explicitDelayMs
-      : metadataOptions.delayMs;
-  const sendAtMs =
-    typeof params.explicitSendAtMs === "number"
-      ? params.explicitSendAtMs
-      : metadataOptions.sendAtMs;
-  if (typeof delayMs === "number" && typeof sendAtMs === "number") {
-    throw new Error("`delay` and `time` cannot be used together.");
-  }
-
-  const chatKey = resolveChatKey({
-    chatKey: params.explicitChatKey || metadataOptions.chatKey,
-  });
-  const messageId = String(
-    params.explicitMessageId || metadataOptions.messageId || "",
-  ).trim();
-  const replyToMessage =
-    params.explicitReplyToMessage === true ||
-    metadataOptions.replyToMessage === true;
-
-  return {
-    text: buildChatMessageText({
-      segments: parsed.segments,
-    }),
-    ...(chatKey ? { chatKey } : {}),
-    ...(typeof delayMs === "number" ? { delayMs } : {}),
-    ...(typeof sendAtMs === "number" ? { sendAtMs } : {}),
-    ...(replyToMessage ? { replyToMessage: true } : {}),
-    ...(messageId ? { messageId } : {}),
-  };
-}
-
-function parseOptionalTimestampOrThrow(
-  value: string,
-  fieldName: string,
-): number | undefined {
-  const text = String(value || "").trim();
-  if (!text) return undefined;
-  return parsePositiveIntOptionOrThrow(text, fieldName);
-}
-
-function readHistoryDirectionOrThrow(
-  value: string,
-): "all" | "inbound" | "outbound" | undefined {
-  const text = String(value || "")
-    .trim()
-    .toLowerCase();
-  if (!text) return undefined;
-  if (text === "all" || text === "inbound" || text === "outbound") {
-    return text;
-  }
-  throw new Error(`Invalid direction: ${value}. Use all|inbound|outbound.`);
-}
+import {
+  getBooleanOpt,
+  getStringOpt,
+  isJsonObject,
+  parseOptionalTimestampOrThrow,
+  parsePositiveIntOptionOrThrow,
+  readHistoryDirectionOrThrow,
+} from "./ChatActionInputSupport.js";
+export {
+  mapChatSendApiInput,
+  mapChatSendCommandInput,
+} from "./ChatSendActionInput.js";
 
 export function mapChatChannelCommandInput(
   input: ServiceActionCommandInput,
@@ -411,116 +254,6 @@ export function mapChatHistoryApiInput(query: {
   };
 }
 
-/**
- * 解析 `chat send` 的命令输入。
- *
- * 关键点（中文）
- * - `--text / --stdin / --text-file` 三选一
- * - 文本读取失败直接抛错，由上层统一输出
- */
-export async function mapChatSendCommandInput(
-  input: ServiceActionCommandInput,
-): Promise<ChatSendActionPayload> {
-  const explicitText = getStringOpt(input.opts, "text");
-  const useStdin = getBooleanOpt(input.opts, "stdin");
-  const textFile = getStringOpt(input.opts, "textFile");
-  const inputSourcesCount =
-    (explicitText ? 1 : 0) + (useStdin ? 1 : 0) + (textFile ? 1 : 0);
-
-  if (inputSourcesCount !== 1) {
-    throw new Error(
-      "Exactly one text source is required: use one of --text, --stdin, or --text-file.",
-    );
-  }
-
-  let text = explicitText;
-  if (useStdin) {
-    const chunks: Buffer[] = [];
-    for await (const chunk of process.stdin) {
-      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
-    }
-    text = Buffer.concat(chunks).toString("utf8");
-  } else if (textFile) {
-    const filePath = path.resolve(process.cwd(), textFile);
-    text = await fs.readFile(filePath, "utf8");
-  }
-
-  const delayRaw = getStringOpt(input.opts, "delay");
-  const timeRaw = getStringOpt(input.opts, "time");
-  const replyToMessage = getBooleanOpt(input.opts, "reply");
-  const messageId = getStringOpt(input.opts, "messageId");
-  const delayMs = delayRaw
-    ? parseNonNegativeIntOptionOrThrow(delayRaw, "delay")
-    : undefined;
-  const sendAtMs = timeRaw ? parseSendTimeOptionOrThrow(timeRaw, "time") : undefined;
-  if (typeof delayMs === "number" && typeof sendAtMs === "number") {
-    throw new Error("`--delay` and `--time` cannot be used together.");
-  }
-  const payload = parseChatSendTextProtocol({
-    rawText: text,
-    explicitChatKey: getStringOpt(input.opts, "chatKey"),
-    ...(typeof delayMs === "number" ? { explicitDelayMs: delayMs } : {}),
-    ...(typeof sendAtMs === "number" ? { explicitSendAtMs: sendAtMs } : {}),
-    ...(replyToMessage ? { explicitReplyToMessage: true } : {}),
-    ...(messageId ? { explicitMessageId: messageId } : {}),
-  });
-  const chatKey = resolveChatKey({
-    chatKey: payload.chatKey,
-  });
-  if (!chatKey) {
-    throw new Error(
-      "Missing chatKey. Provide --chat-key or ensure DC_CTX_CHAT_KEY is injected in current shell context.",
-    );
-  }
-
-  return {
-    text: payload.text,
-    chatKey,
-    ...(typeof payload.delayMs === "number" ? { delayMs: payload.delayMs } : {}),
-    ...(typeof payload.sendAtMs === "number" ? { sendAtMs: payload.sendAtMs } : {}),
-    ...(payload.replyToMessage === true ? { replyToMessage: true } : {}),
-    ...(payload.messageId ? { messageId: payload.messageId } : {}),
-  };
-}
-
-export function mapChatSendApiInput(body: JsonValue): ChatSendActionPayload {
-  if (!body || typeof body !== "object" || Array.isArray(body)) {
-    throw new Error("Invalid JSON body");
-  }
-  const payload = body as JsonObject;
-  const delayRaw = payload.delayMs ?? payload.delay;
-  const timeRaw = payload.sendAtMs ?? payload.sendAt ?? payload.time;
-  const replyRaw = payload.replyToMessage ?? payload.reply;
-  const delayText =
-    typeof delayRaw === "string" || typeof delayRaw === "number"
-      ? String(delayRaw).trim()
-      : "";
-  const timeText =
-    typeof timeRaw === "string" || typeof timeRaw === "number"
-      ? String(timeRaw).trim()
-      : "";
-  const delayMs = delayText
-    ? parseNonNegativeIntOptionOrThrow(delayText, "delayMs")
-    : undefined;
-  const sendAtMs = timeText
-    ? parseSendTimeOptionOrThrow(timeText, "sendAtMs")
-    : undefined;
-  if (typeof delayMs === "number" && typeof sendAtMs === "number") {
-    throw new Error("`delayMs` and `sendAtMs` cannot be used together.");
-  }
-  return parseChatSendTextProtocol({
-    rawText: String(payload.text ?? ""),
-    explicitChatKey:
-      typeof payload.chatKey === "string" ? payload.chatKey.trim() : undefined,
-    ...(typeof delayMs === "number" ? { explicitDelayMs: delayMs } : {}),
-    ...(typeof sendAtMs === "number" ? { explicitSendAtMs: sendAtMs } : {}),
-    ...(replyRaw === true ? { explicitReplyToMessage: true } : {}),
-    ...(typeof payload.messageId === "string" || typeof payload.messageId === "number"
-      ? { explicitMessageId: String(payload.messageId).trim() }
-      : {}),
-  });
-}
-
 export function mapChatReactCommandInput(
   input: ServiceActionCommandInput,
 ): ChatReactActionPayload {

package/src/service/builtins/chat/runtime/ChatActionInputSupport.ts

@@ -0,0 +1,85 @@
+/**
+ * Chat action 输入映射共享辅助。
+ *
+ * 关键点（中文）
+ * - 只放 CLI/API 输入映射复用的轻量解析函数。
+ * - 具体 action 的 payload 组装留在各 action input 模块中。
+ */
+
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+
+/**
+ * 判断 JsonValue 是否为对象。
+ */
+export function isJsonObject(value: JsonValue): value is JsonObject {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * 读取字符串 option。
+ */
+export function getStringOpt(
+  opts: Record<string, JsonValue>,
+  key: string,
+): string {
+  return typeof opts[key] === "string" ? String(opts[key]).trim() : "";
+}
+
+/**
+ * 读取布尔 option。
+ */
+export function getBooleanOpt(
+  opts: Record<string, JsonValue>,
+  key: string,
+): boolean {
+  return opts[key] === true;
+}
+
+/**
+ * 解析正整数 option。
+ */
+export function parsePositiveIntOptionOrThrow(
+  value: string,
+  fieldName: string,
+): number {
+  const text = String(value || "").trim();
+  if (!text) {
+    throw new Error(`${fieldName} is required`);
+  }
+  if (!/^\d+$/.test(text)) {
+    throw new Error(`Invalid ${fieldName}: ${value}`);
+  }
+  const parsed = Number.parseInt(text, 10);
+  if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
+    throw new Error(`Invalid ${fieldName}: ${value}`);
+  }
+  return parsed;
+}
+
+/**
+ * 解析可选时间戳。
+ */
+export function parseOptionalTimestampOrThrow(
+  value: string,
+  fieldName: string,
+): number | undefined {
+  const text = String(value || "").trim();
+  if (!text) return undefined;
+  return parsePositiveIntOptionOrThrow(text, fieldName);
+}
+
+/**
+ * 读取 history direction。
+ */
+export function readHistoryDirectionOrThrow(
+  value: string,
+): "all" | "inbound" | "outbound" | undefined {
+  const text = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!text) return undefined;
+  if (text === "all" || text === "inbound" || text === "outbound") {
+    return text;
+  }
+  throw new Error(`Invalid direction: ${value}. Use all|inbound|outbound.`);
+}

package/src/service/builtins/chat/runtime/ChatChannelActions.ts

@@ -7,7 +7,7 @@
  * - 对外只暴露 action 级入口，供 ChatServiceActions 装配使用。
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type { ChatChannelState } from "@/service/builtins/chat/types/ChatRuntime.js";
 import type {
   ChatCloseActionPayload,

package/src/service/builtins/chat/runtime/ChatChannelConfig.ts

@@ -9,9 +9,9 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
-import type { JsonObject, JsonValue } from "@/utils/types/Json.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { StoredChannelAccount } from "@/host/types/Store.js";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { StoredChannelAccount } from "@/types/host/Store.js";
 import type {
   ChatChannelName,
   ChatChannelStateSnapshot,

package/src/service/builtins/chat/runtime/ChatChannelCore.ts

@@ -7,8 +7,8 @@
  * - 目标是让 chat channel 子模块共享同一套最小公共基元。
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { StoredChannelAccount } from "@/host/types/Store.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { StoredChannelAccount } from "@/types/host/Store.js";
 import type { ChatChannelName } from "@/service/builtins/chat/types/ChannelStatus.js";
 import type { ChatChannelState } from "@/service/builtins/chat/types/ChatRuntime.js";
 

package/src/service/builtins/chat/runtime/ChatChannelLifecycle.ts

@@ -7,7 +7,7 @@
  * - 本模块不处理 downcity.json 写入，也不负责 action 输入输出包装。
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type { ChatChannelState } from "@/service/builtins/chat/types/ChatRuntime.js";
 import type { ChatChannelName } from "@/service/builtins/chat/types/ChannelStatus.js";
 import { createTelegramBot } from "@/service/builtins/chat/channels/telegram/Bot.js";

package/src/service/builtins/chat/runtime/ChatHistoryStore.ts

@@ -10,8 +10,8 @@
 import fs from "fs-extra";
 import path from "node:path";
 import { generateId } from "@/utils/Id.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import type { ChatDispatchChannel } from "@/service/builtins/chat/types/ChatDispatcher.js";
 import type {
   ChatHistoryDirection,

package/src/service/builtins/chat/runtime/ChatIngressStore.ts

@@ -7,8 +7,8 @@
  * - 后续 extension / control UI / 其他外部入口都应复用这里
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import type { ChatDispatchChannel } from "@/service/builtins/chat/types/ChatDispatcher.js";
 import { appendInboundChatHistory } from "./ChatHistoryStore.js";
 

package/src/service/builtins/chat/runtime/ChatMetaStore.ts

@@ -2,12 +2,12 @@
  * ChatMetaStore：按 sessionId 维护 chat 路由元信息。
  *
  * 关键点（中文）
- * - 入站消息到达时由 services/chat 写入
- * - 出站按 sessionId/chatKey 发送时由 services/chat 读取
+ * - 入站消息到达时由 service/builtins/chat 写入
+ * - 出站按 sessionId/chatKey 发送时由 service/builtins/chat 读取
  * - 底层数据落在 `.downcity/channel/meta.json`，由 ChannelContextStore 统一维护
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type { ChatMetaV1 } from "@/service/builtins/chat/types/ChatMeta.js";
 import type { ChatDispatchChannel } from "@/service/builtins/chat/types/ChatDispatcher.js";
 import {

package/src/service/builtins/chat/runtime/ChatQueueReplyDispatch.ts

@@ -7,7 +7,7 @@
  */
 
 import type { Logger } from "@/utils/logger/Logger.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import { parseDirectDispatchAssistantText } from "./DirectDispatchParser.js";
 import { sendActionByChatKey } from "./ChatkeySend.js";
 import { sendChatTextByChatKey } from "../Action.js";

package/src/service/builtins/chat/runtime/ChatQueueSessionBridge.ts

@@ -8,10 +8,10 @@
  */
 
 import { drainDeferredPersistedUserMessages } from "@session/SessionRunScope.js";
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import type { SessionRunResult } from "@/session/types/SessionRun.js";
 import type { SessionUserMessageV1 } from "@/session/types/SessionMessages.js";
-import type { SessionPort } from "@/agent/AgentContextTypes.js";
+import type { SessionPort } from "@/runtime/AgentContextTypes.js";
 import type { ChatQueueItem } from "@/service/builtins/chat/types/ChatQueue.js";
 import { resolveAssistantMessageForPersistence } from "./UserVisibleText.js";
 

package/src/service/builtins/chat/runtime/ChatQueueStore.ts

@@ -7,7 +7,7 @@
  * - 旧的 `ChatQueue.ts` 会保留共享门面，逐步迁移到显式实例注入。
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type {
   ChatQueueEnqueueParams,
   ChatQueueEnqueueResult,

package/src/service/builtins/chat/runtime/ChatQueueWorker.ts

@@ -12,9 +12,9 @@ import type { SessionRunResult } from "@/session/types/SessionRun.js";
 import type {
   SessionUserMessageV1,
 } from "@/session/types/SessionMessages.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type { ChatQueueWorkerConfig } from "@/service/builtins/chat/types/ChatQueueWorker.js";
-import type { JsonObject } from "@/utils/types/Json.js";
+import type { JsonObject } from "@/types/common/Json.js";
 import type { ChatQueueItem } from "@/service/builtins/chat/types/ChatQueue.js";
 import {
   getSharedChatQueueStore,