@downcity/plugins 1.0.4

package/bin/chat/runtime/ChatSendActionInput.js

@@ -0,0 +1,205 @@
+/**
+ * Chat send action 输入映射。
+ *
+ * 关键点（中文）
+ * - 专门处理 `chat send` 的 CLI/API payload 标准化。
+ * - frontmatter metadata 与 `<file>` 协议在这里转换为统一正文。
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { buildChatMessageText, parseChatMessageMarkup, } from "@downcity/agent/internal/executor/messages/ChatMessageMarkup.js";
+import { parseChatSendOptionsFromMetadata } from "../../chat/runtime/ChatSendMetadata.js";
+import { normalizeChatSendText, resolveChatKey, } from "../../chat/Action.js";
+import { getBooleanOpt, getStringOpt } from "./ChatActionInputSupport.js";
+/**
+ * 解析非负整数 option。
+ */
+function parseNonNegativeIntOptionOrThrow(value, fieldName) {
+    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;
+}
+/**
+ * 判断 ISO datetime 是否缺少时区。
+ */
+function looksLikeIsoDatetimeWithoutTimezone(value) {
+    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, fieldName) {
+    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 正文协议。
+ */
+function parseChatSendTextProtocol(params) {
+    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 } : {}),
+    };
+}
+/**
+ * 解析 `chat send` 的命令输入。
+ *
+ * 关键点（中文）
+ * - `--text / --stdin / --text-file` 三选一
+ * - 文本读取失败直接抛错，由上层统一输出
+ */
+export async function mapChatSendCommandInput(input) {
+    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 = [];
+        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 } : {}),
+    };
+}
+/**
+ * 解析 `chat send` 的 API 输入。
+ */
+export function mapChatSendApiInput(body) {
+    if (!body || typeof body !== "object" || Array.isArray(body)) {
+        throw new Error("Invalid JSON body");
+    }
+    const payload = body;
+    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() }
+            : {}),
+    });
+}
+//# sourceMappingURL=ChatSendActionInput.js.map

package/bin/chat/runtime/ChatSendActionInput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatSendActionInput.js","sourceRoot":"","sources":["../../../src/chat/runtime/ChatSendActionInput.ts"],"names":[],"mappings":"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"}

package/bin/chat/runtime/ChatSendMetadata.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Chat send frontmatter metadata 解析工具。
+ *
+ * 关键点（中文）
+ * - frontmatter 中的字段语义与 `city chat send` 参数保持一致。
+ * - direct 模式也复用同一解析逻辑，避免 metadata 协议分叉。
+ */
+import type { ChatMessageSendOptions } from "@downcity/agent/internal/executor/messages/ChatMessageMarkupTypes.js";
+/**
+ * 从 frontmatter metadata 中解析发送参数。
+ *
+ * 说明（中文）
+ * - `strict=true` 时，非法 delay/time 会直接抛错，适用于 CLI/API 输入。
+ * - `strict=false` 时，非法字段会被忽略，适用于 direct 模式的宽容解析。
+ */
+export declare function parseChatSendOptionsFromMetadata(params: {
+    metadata: Record<string, unknown>;
+    strict?: boolean;
+}): ChatMessageSendOptions;
+//# sourceMappingURL=ChatSendMetadata.d.ts.map

package/bin/chat/runtime/ChatSendMetadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatSendMetadata.d.ts","sourceRoot":"","sources":["../../../src/chat/runtime/ChatSendMetadata.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sEAAsE,CAAC;AA8GnH;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE;IACvD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,sBAAsB,CAyCzB"}

package/bin/chat/runtime/ChatSendMetadata.js

@@ -0,0 +1,130 @@
+/**
+ * Chat send frontmatter metadata 解析工具。
+ *
+ * 关键点（中文）
+ * - frontmatter 中的字段语义与 `city chat send` 参数保持一致。
+ * - direct 模式也复用同一解析逻辑，避免 metadata 协议分叉。
+ */
+function normalizeText(value) {
+    return String(value ?? "").trim();
+}
+function pickMetadataValue(metadata, keys) {
+    for (const key of keys) {
+        if (Object.hasOwn(metadata, key)) {
+            return metadata[key];
+        }
+    }
+    return undefined;
+}
+function parseBoolean(value) {
+    if (typeof value === "boolean")
+        return value;
+    const text = normalizeText(value).toLowerCase();
+    if (!text)
+        return undefined;
+    if (text === "true" || text === "1" || text === "yes")
+        return true;
+    if (text === "false" || text === "0" || text === "no")
+        return false;
+    return undefined;
+}
+function parseOptionalMessageId(value) {
+    if (typeof value === "number" && Number.isFinite(value) && !Number.isNaN(value)) {
+        const text = String(Math.trunc(value)).trim();
+        return text ? text : undefined;
+    }
+    if (typeof value === "string") {
+        const text = value.trim();
+        return text ? text : undefined;
+    }
+    return undefined;
+}
+function looksLikeIsoDatetimeWithoutTimezone(value) {
+    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);
+}
+function parseNonNegativeInt(value, fieldName, strict) {
+    const text = normalizeText(value);
+    if (!text)
+        return undefined;
+    if (!/^\d+$/.test(text)) {
+        if (strict) {
+            throw new Error(`Invalid ${fieldName}: ${String(value)}`);
+        }
+        return undefined;
+    }
+    const parsed = Number.parseInt(text, 10);
+    if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed < 0) {
+        if (strict) {
+            throw new Error(`Invalid ${fieldName}: ${String(value)}`);
+        }
+        return undefined;
+    }
+    return parsed;
+}
+function parseSendAtMs(value, fieldName, strict) {
+    const text = normalizeText(value);
+    if (!text)
+        return undefined;
+    if (/^\d+$/.test(text)) {
+        const parsed = Number.parseInt(text, 10);
+        if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
+            if (strict) {
+                throw new Error(`Invalid ${fieldName}: ${String(value)}`);
+            }
+            return undefined;
+        }
+        return parsed < 1_000_000_000_000 ? parsed * 1000 : parsed;
+    }
+    if (looksLikeIsoDatetimeWithoutTimezone(text)) {
+        if (strict) {
+            throw new Error(`Invalid ${fieldName}: ${String(value)}. ISO datetime must include timezone offset (e.g. +08:00 or Z).`);
+        }
+        return undefined;
+    }
+    const parsed = Date.parse(text);
+    if (!Number.isFinite(parsed) || Number.isNaN(parsed) || parsed <= 0) {
+        if (strict) {
+            throw new Error(`Invalid ${fieldName}: ${String(value)}. Use Unix timestamp (seconds/ms) or ISO datetime.`);
+        }
+        return undefined;
+    }
+    return parsed;
+}
+/**
+ * 从 frontmatter metadata 中解析发送参数。
+ *
+ * 说明（中文）
+ * - `strict=true` 时，非法 delay/time 会直接抛错，适用于 CLI/API 输入。
+ * - `strict=false` 时，非法字段会被忽略，适用于 direct 模式的宽容解析。
+ */
+export function parseChatSendOptionsFromMetadata(params) {
+    const metadata = params.metadata && typeof params.metadata === "object" && !Array.isArray(params.metadata)
+        ? params.metadata
+        : {};
+    const strict = params.strict === true;
+    const chatKey = normalizeText(pickMetadataValue(metadata, ["chatKey", "chat-key"]));
+    const delayMs = parseNonNegativeInt(pickMetadataValue(metadata, ["delayMs", "delay-ms", "delay"]), "delay", strict);
+    const sendAtMs = parseSendAtMs(pickMetadataValue(metadata, ["sendAtMs", "send-at-ms", "sendAt", "send-at", "time"]), "time", strict);
+    if (typeof delayMs === "number" && typeof sendAtMs === "number") {
+        throw new Error("`delay` and `time` cannot be used together.");
+    }
+    const explicitMessageId = parseOptionalMessageId(pickMetadataValue(metadata, ["messageId", "message-id"]));
+    const replyRaw = pickMetadataValue(metadata, ["reply"]);
+    const replyAsBoolean = parseBoolean(replyRaw);
+    const replyAsMessageId = explicitMessageId || (replyAsBoolean === undefined ? parseOptionalMessageId(replyRaw) : undefined);
+    const replyToMessage = replyAsBoolean === true || typeof replyAsMessageId === "string";
+    return {
+        ...(chatKey ? { chatKey } : {}),
+        ...(typeof delayMs === "number" ? { delayMs } : {}),
+        ...(typeof sendAtMs === "number" ? { sendAtMs } : {}),
+        ...(replyToMessage ? { replyToMessage: true } : {}),
+        ...(typeof replyAsMessageId === "string" ? { messageId: replyAsMessageId } : {}),
+    };
+}
+//# sourceMappingURL=ChatSendMetadata.js.map

package/bin/chat/runtime/ChatSendMetadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatSendMetadata.js","sourceRoot":"","sources":["../../../src/chat/runtime/ChatSendMetadata.ts"],"names":[],"mappings":"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"}

package/bin/chat/runtime/ChatSendRegistry.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Chat egress dispatcher registry（按 channel 路由回包能力）。
+ *
+ * 关键点（中文）
+ * - tool（如 `chat_send`）通过 dispatcher 把消息发回对应平台
+ * - dispatcher 本身不关心 chatKey/history，只关心“怎么把一段 text 发出去”
+ */
+import type { ChatDispatchChannel, ChatDispatcher } from "../../chat/types/ChatDispatcher.js";
+/**
+ * 注册 channel -> dispatcher 映射。
+ *
+ * 约束（中文）
+ * - 同一 channel 重复注册时以后者覆盖，便于 server 启动阶段统一重建。
+ */
+export declare function registerChatSender(channel: ChatDispatchChannel, dispatcher: ChatDispatcher): void;
+/**
+ * 移除 channel 的 dispatcher 映射。
+ *
+ * 关键点（中文）
+ * - 主要用于测试场景回收全局注册状态。
+ */
+export declare function unregisterChatSender(channel: ChatDispatchChannel): void;
+/**
+ * 获取指定 channel 的 dispatcher。
+ */
+export declare function getChatSender(channel: ChatDispatchChannel): ChatDispatcher | undefined;
+//# sourceMappingURL=ChatSendRegistry.d.ts.map

package/bin/chat/runtime/ChatSendRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatSendRegistry.d.ts","sourceRoot":"","sources":["../../../src/chat/runtime/ChatSendRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACf,MAAM,gCAAgC,CAAC;AAIxC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,mBAAmB,EAC5B,UAAU,EAAE,cAAc,GACzB,IAAI,CAEN;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAEvE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,cAAc,GAAG,SAAS,CAEtF"}

package/bin/chat/runtime/ChatSendRegistry.js

@@ -0,0 +1,26 @@
+const dispatchers = new Map();
+/**
+ * 注册 channel -> dispatcher 映射。
+ *
+ * 约束（中文）
+ * - 同一 channel 重复注册时以后者覆盖，便于 server 启动阶段统一重建。
+ */
+export function registerChatSender(channel, dispatcher) {
+    dispatchers.set(channel, dispatcher);
+}
+/**
+ * 移除 channel 的 dispatcher 映射。
+ *
+ * 关键点（中文）
+ * - 主要用于测试场景回收全局注册状态。
+ */
+export function unregisterChatSender(channel) {
+    dispatchers.delete(channel);
+}
+/**
+ * 获取指定 channel 的 dispatcher。
+ */
+export function getChatSender(channel) {
+    return dispatchers.get(channel);
+}
+//# sourceMappingURL=ChatSendRegistry.js.map

package/bin/chat/runtime/ChatSendRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatSendRegistry.js","sourceRoot":"","sources":["../../../src/chat/runtime/ChatSendRegistry.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,GAAG,IAAI,GAAG,EAAuC,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA4B,EAC5B,UAA0B;IAE1B,WAAW,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AACvC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAA4B;IAC/D,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAA4B;IACxD,OAAO,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AAClC,CAAC"}

package/bin/chat/runtime/ChatSession.d.ts

@@ -0,0 +1,97 @@
+/**
+ * ChatSession：chat 专用 Executor 实现。
+ *
+ * 关键点（中文）
+ * - ChatSession 在实例化时持有自己的 context composer 实例。
+ * - chat 当前 turn 的 step 合并/step 回发状态都绑定在 Session 自身，不再新增 `runChat` 一层入口。
+ * - 外层仍只调用标准 `run(...)`；chat 语义由 ChatSession 内部收敛。
+ */
+import type { LanguageModel, Tool } from "ai";
+import { Executor } from "@downcity/agent/internal/executor/Executor.js";
+import type { SessionHistoryComposer } from "@downcity/agent/internal/executor/composer/history/SessionHistoryComposer.js";
+import type { SessionHistoryStore } from "@downcity/agent/internal/executor/store/history/SessionHistoryStore.js";
+import type { SessionCompactionComposer } from "@downcity/agent/internal/executor/composer/compaction/SessionCompactionComposer.js";
+import type { SessionSystemComposer } from "@downcity/agent/internal/executor/composer/system/SessionSystemComposer.js";
+import type { ChatSessionContextComposer } from "../../chat/runtime/ChatSessionContextComposer.js";
+import type { Logger } from "@downcity/agent/internal/utils/logger/Logger.js";
+import type { SessionRunResult } from "@downcity/agent/internal/executor/types/SessionRun.js";
+import type { ChatSessionTurnState } from "../../chat/runtime/ChatSessionTypes.js";
+type ChatSessionOptions = {
+    /**
+     * 当前会话 ID。
+     */
+    sessionId: string;
+    /**
+     * 当前 session 的 history store。
+     */
+    historyStore: SessionHistoryStore;
+    /**
+     * 当前 session 的 history composer。
+     */
+    historyComposer: SessionHistoryComposer;
+    /**
+     * 读取当前 session 使用的模型实例。
+     */
+    getModel: () => LanguageModel | undefined;
+    /**
+     * 统一日志器。
+     */
+    logger: Logger;
+    /**
+     * 当前 session 对应的 compaction Composer。
+     */
+    compactionComposer: SessionCompactionComposer;
+    /**
+     * 当前 session 对应的 system Composer。
+     */
+    systemComposer: SessionSystemComposer;
+    /**
+     * 获取当前可用工具集合。
+     */
+    getTools: () => Record<string, Tool>;
+    /**
+     * 当前 session 绑定的 chat context composer。
+     */
+    contextComposer: ChatSessionContextComposer;
+    /**
+     * session 更新后的异步回调。
+     */
+    runAfterSessionUpdated?: (sessionId: string) => Promise<void>;
+};
+/**
+ * Chat 专用 Session。
+ */
+export declare class ChatSession extends Executor {
+    /**
+     * ChatSession 持有的 composer 实例。
+     */
+    readonly contextComposer: ChatSessionContextComposer;
+    private activeTurnState;
+    constructor(options: ChatSessionOptions);
+    /**
+     * 读取当前绑定的 chat turn 状态。
+     */
+    getTurnState(): ChatSessionTurnState | null;
+    /**
+     * 处理一次 assistant step 回发。
+     *
+     * 关键点（中文）
+     * - step 持久化由基类 `Session.run` 先完成。
+     * - 这里仅负责把当前 turn 绑定的外部回发钩子继续调出去。
+     */
+    private readonly forwardAssistantStep;
+    /**
+     * 运行当前 chat session 的一次请求。
+     *
+     * 关键点（中文）
+     * - 外层继续走统一的内部执行入口。
+     * - ChatSession 只是在 run 生命周期里临时绑定 turn 状态给自己的 composer。
+     */
+    run(params: {
+        query: string;
+        onStepCallback?: ChatSessionTurnState["onStepCallback"];
+        onAssistantStepCallback?: ChatSessionTurnState["onAssistantStepCallback"];
+    }): Promise<SessionRunResult>;
+}
+export {};
+//# sourceMappingURL=ChatSession.d.ts.map

package/bin/chat/runtime/ChatSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatSession.d.ts","sourceRoot":"","sources":["../../../src/chat/runtime/ChatSession.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,+CAA+C,CAAC;AACzE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8EAA8E,CAAC;AAC3H,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wEAAwE,CAAC;AAClH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oFAAoF,CAAC;AACpI,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4EAA4E,CAAC;AACxH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,8CAA8C,CAAC;AAC/F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iDAAiD,CAAC;AAE9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uDAAuD,CAAC;AAC9F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAE/E,KAAK,kBAAkB,GAAG;IACxB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,YAAY,EAAE,mBAAmB,CAAC;IAElC;;OAEG;IACH,eAAe,EAAE,sBAAsB,CAAC;IAExC;;OAEG;IACH,QAAQ,EAAE,MAAM,aAAa,GAAG,SAAS,CAAC;IAE1C;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,kBAAkB,EAAE,yBAAyB,CAAC;IAE9C;;OAEG;IACH,cAAc,EAAE,qBAAqB,CAAC;IAEtC;;OAEG;IACH,QAAQ,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAErC;;OAEG;IACH,eAAe,EAAE,0BAA0B,CAAC;IAE5C;;OAEG;IACH,sBAAsB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D,CAAC;AAEF;;GAEG;AACH,qBAAa,WAAY,SAAQ,QAAQ;IACvC;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,0BAA0B,CAAC;IAErD,OAAO,CAAC,eAAe,CAAqC;gBAEhD,OAAO,EAAE,kBAAkB;IAmBvC;;OAEG;IACH,YAAY,IAAI,oBAAoB,GAAG,IAAI;IAI3C;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAMnC;IAEF;;;;;;OAMG;IACY,GAAG,CAAC,MAAM,EAAE;QACzB,KAAK,EAAE,MAAM,CAAC;QACd,cAAc,CAAC,EAAE,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;QACxD,uBAAuB,CAAC,EAAE,oBAAoB,CAAC,yBAAyB,CAAC,CAAC;KAC3E,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAmB9B"}

package/bin/chat/runtime/ChatSession.js

@@ -0,0 +1,84 @@
+/**
+ * ChatSession：chat 专用 Executor 实现。
+ *
+ * 关键点（中文）
+ * - ChatSession 在实例化时持有自己的 context composer 实例。
+ * - chat 当前 turn 的 step 合并/step 回发状态都绑定在 Session 自身，不再新增 `runChat` 一层入口。
+ * - 外层仍只调用标准 `run(...)`；chat 语义由 ChatSession 内部收敛。
+ */
+import { Executor } from "@downcity/agent/internal/executor/Executor.js";
+/**
+ * Chat 专用 Session。
+ */
+export class ChatSession extends Executor {
+    /**
+     * ChatSession 持有的 composer 实例。
+     */
+    contextComposer;
+    activeTurnState = null;
+    constructor(options) {
+        const contextComposer = options.contextComposer;
+        super({
+            sessionId: options.sessionId,
+            historyStore: options.historyStore,
+            historyComposer: options.historyComposer,
+            getModel: options.getModel,
+            logger: options.logger,
+            compactionComposer: options.compactionComposer,
+            systemComposer: options.systemComposer,
+            getTools: options.getTools,
+            contextComposer,
+            ...(options.runAfterSessionUpdated
+                ? { runAfterSessionUpdated: options.runAfterSessionUpdated }
+                : {}),
+        });
+        this.contextComposer = contextComposer;
+    }
+    /**
+     * 读取当前绑定的 chat turn 状态。
+     */
+    getTurnState() {
+        return this.activeTurnState;
+    }
+    /**
+     * 处理一次 assistant step 回发。
+     *
+     * 关键点（中文）
+     * - step 持久化由基类 `Session.run` 先完成。
+     * - 这里仅负责把当前 turn 绑定的外部回发钩子继续调出去。
+     */
+    forwardAssistantStep = async (step) => {
+        const callback = this.activeTurnState?.onAssistantStepCallback;
+        if (typeof callback !== "function")
+            return;
+        await callback(step);
+    };
+    /**
+     * 运行当前 chat session 的一次请求。
+     *
+     * 关键点（中文）
+     * - 外层继续走统一的内部执行入口。
+     * - ChatSession 只是在 run 生命周期里临时绑定 turn 状态给自己的 composer。
+     */
+    async run(params) {
+        this.activeTurnState = {
+            ...(typeof params.onStepCallback === "function"
+                ? { onStepCallback: params.onStepCallback }
+                : {}),
+            ...(typeof params.onAssistantStepCallback === "function"
+                ? { onAssistantStepCallback: params.onAssistantStepCallback }
+                : {}),
+        };
+        try {
+            return await super.run({
+                query: params.query,
+                onStepCallback: params.onStepCallback,
+                onAssistantStepCallback: this.forwardAssistantStep,
+            });
+        }
+        finally {
+            this.activeTurnState = null;
+        }
+    }
+}
+//# sourceMappingURL=ChatSession.js.map

package/bin/chat/runtime/ChatSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatSession.js","sourceRoot":"","sources":["../../../src/chat/runtime/ChatSession.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,+CAA+C,CAAC;AA+DzE;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,QAAQ;IACvC;;OAEG;IACM,eAAe,CAA6B;IAE7C,eAAe,GAAgC,IAAI,CAAC;IAE5D,YAAY,OAA2B;QACrC,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAChD,KAAK,CAAC;YACJ,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,eAAe,EAAE,OAAO,CAAC,eAAe;YACxC,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;YAC9C,cAAc,EAAE,OAAO,CAAC,cAAc;YACtC,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,eAAe;YACf,GAAG,CAAC,OAAO,CAAC,sBAAsB;gBAChC,CAAC,CAAC,EAAE,sBAAsB,EAAE,OAAO,CAAC,sBAAsB,EAAE;gBAC5D,CAAC,CAAC,EAAE,CAAC;SACR,CAAC,CAAC;QACH,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;IACzC,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;IAED;;;;;;OAMG;IACc,oBAAoB,GAAiC,KAAK,EACzE,IAAI,EACW,EAAE;QACjB,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,EAAE,uBAAuB,CAAC;QAC/D,IAAI,OAAO,QAAQ,KAAK,UAAU;YAAE,OAAO;QAC3C,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC,CAAC;IAEF;;;;;;OAMG;IACM,KAAK,CAAC,GAAG,CAAC,MAIlB;QACC,IAAI,CAAC,eAAe,GAAG;YACrB,GAAG,CAAC,OAAO,MAAM,CAAC,cAAc,KAAK,UAAU;gBAC7C,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,CAAC,cAAc,EAAE;gBAC3C,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,OAAO,MAAM,CAAC,uBAAuB,KAAK,UAAU;gBACtD,CAAC,CAAC,EAAE,uBAAuB,EAAE,MAAM,CAAC,uBAAuB,EAAE;gBAC7D,CAAC,CAAC,EAAE,CAAC;SACR,CAAC;QACF,IAAI,CAAC;YACH,OAAO,MAAM,KAAK,CAAC,GAAG,CAAC;gBACrB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,cAAc,EAAE,MAAM,CAAC,cAAc;gBACrC,uBAAuB,EAAE,IAAI,CAAC,oBAAoB;aACnD,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC9B,CAAC;IACH,CAAC;CACF"}