@downcity/agent 1.1.437 → 1.1.445

package/bin/types/tool/BoundAgentTool.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 已绑定工具的内部执行协议。
+ *
+ * 公开契约 `AgentTool` 的执行签名要求完整的 `ToolCallContext`；而模型 Step 只知道
+ * 本次调用自身的身份与消息。因此 Agent 在执行前把 AgentTool 包装成 BoundAgentTool：
+ * 包装层捕获 Session 级上下文，Step 侧只补本次调用信息，两者在包装层合并。
+ *
+ * 关键点（中文）
+ * - `BoundAgentTool` 不对外暴露，只存在于 Agent 内部的模型 Step 执行路径。
+ * - 这一层存在的意义是让上下文注入点唯一：工具实现永远拿到完整的 ToolCallContext。
+ */
+import type { ModelMessage } from "@downcity/type";
+/** 一次模型工具调用自身携带的信息。 */
+export interface ToolCallSite {
+    /** 当前模型工具调用的稳定唯一标识。 */
+    readonly tool_call_id: string;
+    /** 当前模型 Step 使用的完整消息快照。 */
+    readonly messages: readonly ModelMessage[];
+    /** 当前 Turn 的可选取消信号。 */
+    readonly abort_signal?: AbortSignal;
+}
+/** 允许异构工具注册表保留每个工具自己的输入类型。 */
+type BoundAgentToolHandler<TInput, TResult> = {
+    bivariance_handler(input: TInput, site: ToolCallSite): TResult;
+}["bivariance_handler"];
+/** 已完成 Session 上下文绑定的工具；执行时只需补充本次调用信息。 */
+export interface BoundAgentTool<TInput = unknown, TOutput = unknown> {
+    /** 面向模型的工具用途说明。 */
+    readonly description?: string;
+    /** JSON Schema 或可转换为 JSON Schema 的输入定义。 */
+    readonly input_schema: unknown;
+    /** 可选执行实现；缺少时该工具只向模型声明能力。 */
+    readonly execute?: BoundAgentToolHandler<TInput, TOutput | Promise<TOutput>>;
+}
+export {};
+//# sourceMappingURL=BoundAgentTool.d.ts.map

package/bin/types/tool/BoundAgentTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BoundAgentTool.d.ts","sourceRoot":"","sources":["../../../src/types/tool/BoundAgentTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,uBAAuB;AACvB,MAAM,WAAW,YAAY;IAC3B,uBAAuB;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,2BAA2B;IAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,uBAAuB;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC;CACrC;AAED,8BAA8B;AAC9B,KAAK,qBAAqB,CAAC,MAAM,EAAE,OAAO,IAAI;IAC5C,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC;CAChE,CAAC,oBAAoB,CAAC,CAAC;AAExB,0CAA0C;AAC1C,MAAM,WAAW,cAAc,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IACjE,mBAAmB;IACnB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;CAC9E"}

package/bin/types/tool/BoundAgentTool.js

@@ -0,0 +1,13 @@
+/**
+ * 已绑定工具的内部执行协议。
+ *
+ * 公开契约 `AgentTool` 的执行签名要求完整的 `ToolCallContext`；而模型 Step 只知道
+ * 本次调用自身的身份与消息。因此 Agent 在执行前把 AgentTool 包装成 BoundAgentTool：
+ * 包装层捕获 Session 级上下文，Step 侧只补本次调用信息，两者在包装层合并。
+ *
+ * 关键点（中文）
+ * - `BoundAgentTool` 不对外暴露，只存在于 Agent 内部的模型 Step 执行路径。
+ * - 这一层存在的意义是让上下文注入点唯一：工具实现永远拿到完整的 ToolCallContext。
+ */
+export {};
+//# sourceMappingURL=BoundAgentTool.js.map

package/bin/types/tool/BoundAgentTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BoundAgentTool.js","sourceRoot":"","sources":["../../../src/types/tool/BoundAgentTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/bin/types/tools/ask/AskQuestionsTool.d.ts

@@ -1,19 +1,13 @@
 /**
  * ask_question Tool 的输入与输出协议。
  *
- * 该协议只描述模型发起问题和收到回答时可见的数据；Interaction 标识、Turn 标识与
- * 生命周期状态由 Session 运行时维护，不交给模型生成。
+ * 问题字段与 canonical Interaction 保持一致，只少一个由 Session 生成的 `question_id`；
+ * 模型写的形状就是落库与渲染的形状。Interaction 标识、Turn 标识与生命周期状态由 Session
+ * 运行时维护，不交给模型生成。
  */
-import type { SessionInteractionAnswer, SessionInteractionOption, SessionInteractionQuestion } from "@downcity/type";
-/** 模型调用 ask_question 时提交的一条问题。 */
-export interface AskQuestionsToolQuestion {
-    /** 向用户展示的完整问题文本。 */
-    question: string;
-    /** 当前问题要求的回答形式，所有问题都必须显式提供。 */
-    type: SessionInteractionQuestion["response_type"];
-    /** 单选或多选问题允许选择的候选项。 */
-    options?: SessionInteractionOption[];
-}
+import type { SessionInteractionAnswer, SessionInteractionQuestion } from "@downcity/type";
+/** 模型调用 ask_question 时提交的一条问题；`question_id` 由 Session 生成，不由模型提供。 */
+export type AskQuestionsToolQuestion = Omit<SessionInteractionQuestion, "question_id">;
 /** 模型调用 ask_question 时提交的结构化输入。 */
 export interface AskQuestionsToolInput {
     /** 问题卡片向用户展示的简短标题。 */
@@ -25,7 +19,9 @@ export interface AskQuestionsToolInput {
 export interface AskQuestionsToolOutput {
     /** 当前提问已由用户完整回答。 */
     status: "resolved";
-    /** 按 question_id 关联的完整回答集合。 */
+    /** 按 question_id 关联的完整回答集合，顺序与提问一致。 */
     answers: SessionInteractionAnswer[];
+    /** 用户随回答提交的可选补充说明。 */
+    note?: string;
 }
 //# sourceMappingURL=AskQuestionsTool.d.ts.map

package/bin/types/tools/ask/AskQuestionsTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AskQuestionsTool.d.ts","sourceRoot":"","sources":["../../../../src/types/tools/ask/AskQuestionsTool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,wBAAwB,EACxB,wBAAwB,EACxB,0BAA0B,EAC3B,MAAM,gBAAgB,CAAC;AAExB,kCAAkC;AAClC,MAAM,WAAW,wBAAwB;IACvC,oBAAoB;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,IAAI,EAAE,0BAA0B,CAAC,eAAe,CAAC,CAAC;IAClD,uBAAuB;IACvB,OAAO,CAAC,EAAE,wBAAwB,EAAE,CAAC;CACtC;AAED,mCAAmC;AACnC,MAAM,WAAW,qBAAqB;IACpC,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,SAAS,EAAE,wBAAwB,EAAE,CAAC;CACvC;AAED,oCAAoC;AACpC,MAAM,WAAW,sBAAsB;IACrC,oBAAoB;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,+BAA+B;IAC/B,OAAO,EAAE,wBAAwB,EAAE,CAAC;CACrC"}
+{"version":3,"file":"AskQuestionsTool.d.ts","sourceRoot":"","sources":["../../../../src/types/tools/ask/AskQuestionsTool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,wBAAwB,EACxB,0BAA0B,EAC3B,MAAM,gBAAgB,CAAC;AAExB,oEAAoE;AACpE,MAAM,MAAM,wBAAwB,GAAG,IAAI,CACzC,0BAA0B,EAC1B,aAAa,CACd,CAAC;AAEF,mCAAmC;AACnC,MAAM,WAAW,qBAAqB;IACpC,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,SAAS,EAAE,wBAAwB,EAAE,CAAC;CACvC;AAED,oCAAoC;AACpC,MAAM,WAAW,sBAAsB;IACrC,oBAAoB;IACpB,MAAM,EAAE,UAAU,CAAC;IACnB,uCAAuC;IACvC,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACpC,sBAAsB;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

package/bin/types/tools/ask/AskQuestionsTool.js

@@ -1,8 +1,9 @@
 /**
  * ask_question Tool 的输入与输出协议。
  *
- * 该协议只描述模型发起问题和收到回答时可见的数据；Interaction 标识、Turn 标识与
- * 生命周期状态由 Session 运行时维护，不交给模型生成。
+ * 问题字段与 canonical Interaction 保持一致，只少一个由 Session 生成的 `question_id`；
+ * 模型写的形状就是落库与渲染的形状。Interaction 标识、Turn 标识与生命周期状态由 Session
+ * 运行时维护，不交给模型生成。
  */
 export {};
 //# sourceMappingURL=AskQuestionsTool.js.map

package/bin/types/tools/ask/AskQuestionsTool.js.map

@@ -1 +1 @@
-{"version":3,"file":"AskQuestionsTool.js","sourceRoot":"","sources":["../../../../src/types/tools/ask/AskQuestionsTool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}
+{"version":3,"file":"AskQuestionsTool.js","sourceRoot":"","sources":["../../../../src/types/tools/ask/AskQuestionsTool.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/bin/types/turn/SessionAssistantOutput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionAssistantOutput.d.ts","sourceRoot":"","sources":["../../../src/types/turn/SessionAssistantOutput.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,KAAK,EACV,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,gCAAgC,CAAC;AAExC,kDAAkD;AAClD,MAAM,WAAW,sBAAsB;IACrC,gCAAgC;IAChC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,qBAAqB;IACrB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,2BAA2B;IAC3B,kBAAkB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,oBAAoB;IACpB,iBAAiB,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,2CAA2C;IAC3C,WAAW,CAAC,KAAK,EAAE,uBAAuB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,2BAA2B;IAC3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,8CAA8C;IAC9C,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,+CAA+C;IAC/C,mBAAmB,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAC/F,iDAAiD;IACjD,YAAY,CAAC,KAAK,EAAE;QAClB,cAAc;QACd,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC;QAC1B,aAAa;QACb,IAAI,EAAE,MAAM,CAAC;QACb,gBAAgB;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,oBAAoB;QACpB,WAAW,EAAE,OAAO,CAAC;KACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClB,kCAAkC;IAClC,MAAM,CAAC,KAAK,EAAE;QACZ,sBAAsB;QACtB,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;QAC3C,qCAAqC;QACrC,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnB"}

package/bin/types/turn/SessionAssistantOutput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionAssistantOutput.js","sourceRoot":"","sources":["../../../src/types/turn/SessionAssistantOutput.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/bin/types/{executor → turn}/SessionTurnContext.d.ts

@@ -6,14 +6,11 @@
  * - 分区用于表达领域职责，不引入多套彼此独立的 Context。
  * - 可变状态只能通过行为方法更新，消费者不能直接操作内部数组、lease 或 callback。
  */
-import type { RuntimeToolEffect } from "@downcity/type";
-import type { ShellApprovalGateway } from "@downcity/type";
+import type { ToolEffect } from "@downcity/type";
 import type { SessionModelUserContent, SessionUserMessage } from "@downcity/type";
 import type { SessionAgentContent } from "@downcity/type";
-import type { SessionAssistantOutput } from "../../types/executor/SessionAssistantOutput.js";
-import type { SessionHookContext } from "@downcity/type";
-import type { SessionHookScopeRuntime } from "@downcity/type";
-import type { AgentSessionActionCallback, AgentSessionActionEvent, AgentSessionActionRecord } from "../../types/sdk/AgentSessionAction.js";
+import type { SessionAssistantOutput } from "../../types/turn/SessionAssistantOutput.js";
+import type { AgentSessionActionCallback, AgentSessionActionEvent } from "../../types/sdk/AgentSessionAction.js";
 import type { SessionInteractionPort } from "@downcity/type";
 import type { SessionOrigin } from "@downcity/type";
 import type { SessionHookContextBlock } from "@downcity/type";
@@ -44,10 +41,8 @@ export interface SessionTurnContextInit {
     assistant_output?: SessionAssistantOutput;
     /** 当前 Session 执行面创建用户异步交互的端口。 */
     interactions?: SessionInteractionPort;
-    /** 当前 Session 提供的 host Shell 审批网关。 */
-    shell_approval_gateway?: ShellApprovalGateway;
     /** 当前 Turn effects 追加后触发的实时观测回调，宿主可据此广播文件改动摘要。 */
-    on_effects_changed?: (effects: readonly RuntimeToolEffect[]) => void;
+    on_effects_changed?: (effects: readonly ToolEffect[]) => void;
     /** 把辅助 Action 持久化并发布为 Session 事件的回调。 */
     publish_action?: AgentSessionActionCallback;
     /** 把内部模型请求失败交给 Session 边界投影。 */
@@ -83,10 +78,8 @@ export interface SessionTurnContext {
         readonly workspace_env?: Readonly<Record<string, string>>;
         /** 当前 Step 已提交生效的 Agent instruction 快照。 */
         readonly agent_systems: readonly string[];
-        /** 当前 Step 持有的稳定 Hook 作用域。 */
-        readonly hooks?: SessionHookScopeRuntime;
-        /** 当前 Turn 首次解析后冻结的 Plugin 动态上下文。 */
-        readonly plugin_context_blocks: readonly SessionHookContextBlock[];
+        /** 当前 Turn 首次解析后冻结的扩展动态上下文。 */
+        readonly power_context_blocks: readonly SessionHookContextBlock[];
         /** 原子提交当前 Step 使用的 env 与 instruction 快照。 */
         commit(input: {
             /** 即将在当前 Step 生效的 Workspace env。 */
@@ -94,14 +87,8 @@ export interface SessionTurnContext {
             /** 即将在当前 Step 生效的 Agent instruction。 */
             agent_systems: readonly string[];
         }): void;
-        /** 切换当前 Step 的 Hook 作用域，并先关闭前一个作用域。 */
-        replace_hooks(hooks?: SessionHookScopeRuntime): Promise<void>;
         /** 首次调用时解析并冻结动态上下文，后续 Step 与重试复用同一快照。 */
-        resolve_plugin_context_blocks(resolver: () => Promise<readonly SessionHookContextBlock[]>): Promise<readonly SessionHookContextBlock[]>;
-        /** 释放当前 Step 持有的 Plugin Hook 作用域。 */
-        release(): Promise<void>;
-        /** 为 City Plugin 生成只包含稳定、只读运行快照的新对象。 */
-        hook_context(call_id?: string): SessionHookContext;
+        resolve_power_context_blocks(resolver: () => Promise<readonly SessionHookContextBlock[]>): Promise<readonly SessionHookContextBlock[]>;
     };
     /** 当前运行的动态 User 输入。 */
     readonly input: {
@@ -132,17 +119,12 @@ export interface SessionTurnContext {
     /** 当前 Turn 已经发生、等待在收口检查点投影的 Tool 副作用。 */
     readonly effects: {
         /** 按实际发生顺序追加 Tool 副作用。 */
-        append(effects: readonly RuntimeToolEffect[]): void;
+        append(effects: readonly ToolEffect[]): void;
         /** 返回当前 Turn 已收集副作用的不可变快照。 */
-        snapshot(): readonly RuntimeToolEffect[];
+        snapshot(): readonly ToolEffect[];
     };
     /** 当前 Session 执行面创建用户异步交互的端口。 */
     readonly interactions?: SessionInteractionPort;
-    /** 当前运行可使用的 Shell 协作能力。 */
-    readonly shell: {
-        /** 当前 Session 提供的 host 执行审批网关。 */
-        readonly approval_gateway?: ShellApprovalGateway;
-    };
 }
-export type { AgentSessionActionCallback, AgentSessionActionEvent, AgentSessionActionRecord, };
+export type { AgentSessionActionCallback, AgentSessionActionEvent, };
 //# sourceMappingURL=SessionTurnContext.d.ts.map

package/bin/types/turn/SessionTurnContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionTurnContext.d.ts","sourceRoot":"","sources":["../../../src/types/turn/SessionTurnContext.ts"],"names":[],"mappings":"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"}

package/bin/types/turn/SessionTurnContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SessionTurnContext.js","sourceRoot":"","sources":["../../../src/types/turn/SessionTurnContext.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/bin/{executor/ids/resolveSessionId.d.ts → utils/ResolveSessionId.d.ts}

@@ -8,4 +8,4 @@
 export declare function resolve_session_id(input?: {
     session_id?: string;
 }): string | undefined;
-//# sourceMappingURL=resolveSessionId.d.ts.map
+//# sourceMappingURL=ResolveSessionId.d.ts.map

package/bin/utils/ResolveSessionId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResolveSessionId.d.ts","sourceRoot":"","sources":["../../src/utils/ResolveSessionId.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,EAAE;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,GAAG,SAAS,CAQrB"}

package/bin/{executor/ids/resolveSessionId.js → utils/ResolveSessionId.js}

@@ -14,4 +14,4 @@ export function resolve_session_id(input) {
         return envSessionId;
     return undefined;
 }
-//# sourceMappingURL=resolveSessionId.js.map
+//# sourceMappingURL=ResolveSessionId.js.map

package/bin/utils/ResolveSessionId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResolveSessionId.js","sourceRoot":"","sources":["../../src/utils/ResolveSessionId.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAElC;IACC,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACxD,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAE9B,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACpE,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IAEtC,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/bin/utils/Time.d.ts

@@ -1,14 +1,11 @@
 /**
  * 时间格式工具模块。
  *
- * 职责说明：
- * 1. 提供统一时间戳格式。
- * 2. 提供耗时格式化，便于日志和 CLI 输出使用一致单位。
- * 3. 提供 runtime 时区格式化，确保 prompt / message / task 共享同一时间口径。
+ * 关键点（中文）
+ * - 时区与日期格式的实现已归位到 `@downcity/type`，与 City Power 共享同一口径。
+ * - 本模块只保留 Agent 侧独有的时间戳能力，并重导出定义层函数，避免出现两份实现。
  */
+export { format_date_in_timezone, format_date_time_in_timezone, format_year_in_timezone, resolve_runtime_timezone, } from "@downcity/type";
+/** 返回当前 UTC 时间戳的 ISO 字符串。 */
 export declare function get_timestamp(): string;
-export declare function resolve_runtime_timezone(): string;
-export declare function format_date_in_timezone(date?: Date, timezone?: string): string;
-export declare function format_date_time_in_timezone(date?: Date, timezone?: string): string;
-export declare function format_year_in_timezone(date?: Date, timezone?: string): string;
 //# sourceMappingURL=Time.d.ts.map

package/bin/utils/Time.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/utils/Time.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,wBAAgB,wBAAwB,IAAI,MAAM,CAGjD;AAED,wBAAgB,uBAAuB,CACrC,IAAI,GAAE,IAAiB,EACvB,QAAQ,GAAE,MAAmC,GAC5C,MAAM,CAYR;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,GAAE,IAAiB,EACvB,QAAQ,GAAE,MAAmC,GAC5C,MAAM,CAmBR;AAED,wBAAgB,uBAAuB,CACrC,IAAI,GAAE,IAAiB,EACvB,QAAQ,GAAE,MAAmC,GAC5C,MAAM,CASR"}
+{"version":3,"file":"Time.d.ts","sourceRoot":"","sources":["../../src/utils/Time.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AAExB,6BAA6B;AAC7B,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/bin/utils/Time.js

@@ -1,62 +1,13 @@
 /**
  * 时间格式工具模块。
  *
- * 职责说明：
- * 1. 提供统一时间戳格式。
- * 2. 提供耗时格式化，便于日志和 CLI 输出使用一致单位。
- * 3. 提供 runtime 时区格式化，确保 prompt / message / task 共享同一时间口径。
+ * 关键点（中文）
+ * - 时区与日期格式的实现已归位到 `@downcity/type`，与 City Power 共享同一口径。
+ * - 本模块只保留 Agent 侧独有的时间戳能力，并重导出定义层函数，避免出现两份实现。
  */
+export { format_date_in_timezone, format_date_time_in_timezone, format_year_in_timezone, resolve_runtime_timezone, } from "@downcity/type";
+/** 返回当前 UTC 时间戳的 ISO 字符串。 */
 export function get_timestamp() {
     return new Date().toISOString();
 }
-export function resolve_runtime_timezone() {
-    const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
-    return String(timezone || "").trim() || "UTC";
-}
-export function format_date_in_timezone(date = new Date(), timezone = resolve_runtime_timezone()) {
-    try {
-        // 关键点（中文）：sv-SE locale 默认输出 ISO 风格日期，便于模型稳定解析。
-        return new Intl.DateTimeFormat("sv-SE", {
-            timeZone: timezone,
-            year: "numeric",
-            month: "2-digit",
-            day: "2-digit",
-        }).format(date);
-    }
-    catch {
-        return date.toISOString().slice(0, 10);
-    }
-}
-export function format_date_time_in_timezone(date = new Date(), timezone = resolve_runtime_timezone()) {
-    try {
-        // 关键点（中文）：使用固定格式，确保模型读取时区信息时稳定。
-        const formatted = new Intl.DateTimeFormat("sv-SE", {
-            timeZone: timezone,
-            year: "numeric",
-            month: "2-digit",
-            day: "2-digit",
-            hour: "2-digit",
-            minute: "2-digit",
-            second: "2-digit",
-            hour12: false,
-        })
-            .format(date)
-            .replace(" ", "T");
-        return `${formatted} (${timezone})`;
-    }
-    catch {
-        return date.toISOString();
-    }
-}
-export function format_year_in_timezone(date = new Date(), timezone = resolve_runtime_timezone()) {
-    try {
-        return new Intl.DateTimeFormat("en-US", {
-            timeZone: timezone,
-            year: "numeric",
-        }).format(date);
-    }
-    catch {
-        return String(date.getUTCFullYear());
-    }
-}
 //# sourceMappingURL=Time.js.map

package/bin/utils/Time.js.map

@@ -1 +1 @@
-{"version":3,"file":"Time.js","sourceRoot":"","sources":["../../src/utils/Time.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,wBAAwB;IACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC,eAAe,EAAE,CAAC,QAAQ,IAAI,KAAK,CAAC;IAC3E,OAAO,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,OAAa,IAAI,IAAI,EAAE,EACvB,WAAmB,wBAAwB,EAAE;IAE7C,IAAI,CAAC;QACH,+CAA+C;QAC/C,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE;YACtC,QAAQ,EAAE,QAAQ;YAClB,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,SAAS;YAChB,GAAG,EAAE,SAAS;SACf,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,4BAA4B,CAC1C,OAAa,IAAI,IAAI,EAAE,EACvB,WAAmB,wBAAwB,EAAE;IAE7C,IAAI,CAAC;QACH,gCAAgC;QAChC,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE;YACjD,QAAQ,EAAE,QAAQ;YAClB,IAAI,EAAE,SAAS;YACf,KAAK,EAAE,SAAS;YAChB,GAAG,EAAE,SAAS;YACd,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,KAAK;SACd,CAAC;aACC,MAAM,CAAC,IAAI,CAAC;aACZ,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACrB,OAAO,GAAG,SAAS,KAAK,QAAQ,GAAG,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC;IAC5B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,OAAa,IAAI,IAAI,EAAE,EACvB,WAAmB,wBAAwB,EAAE;IAE7C,IAAI,CAAC;QACH,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE;YACtC,QAAQ,EAAE,QAAQ;YAClB,IAAI,EAAE,SAAS;SAChB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC;IACvC,CAAC;AACH,CAAC"}
+{"version":3,"file":"Time.js","sourceRoot":"","sources":["../../src/utils/Time.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,gBAAgB,CAAC;AAExB,6BAA6B;AAC7B,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAClC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downcity/agent",
-  "version": "1.1.437",
+  "version": "1.1.445",
   "type": "module",
   "description": "Downcity 单 Agent SDK 与执行运行时",
   "main": "./bin/index.js",
@@ -24,7 +24,7 @@
     }
   },
   "dependencies": {
-    "@downcity/type": "0.1.213",
+    "@downcity/type": "0.1.218",
     "diff": "^8.0.4",
     "fs-extra": "^11.3.5",
     "js-yaml": "^4.1.1",

package/scripts/ask-question-answers.test.mjs

@@ -0,0 +1,132 @@
+/**
+ * @file 验证 ask_question 对自己 Interaction 回答 payload 的解释。
+ *
+ * Interaction 核心只认信封，回答的形状与合法性由生产者负责，所以这些规则必须由
+ * Tool 一侧守住。回归点：客户端曾把单选回答提交成数组，而核心当时用「不是多选就必须
+ * 是字符串」拒收整次响应（`Session Interaction answer must be a string`）。
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  read_ask_question_note,
+  resolve_ask_question_answers,
+} from "../bin/tools/ask/AskQuestionAnswers.js";
+
+/** 构造一条已生成 question_id 的问题。 */
+function create_question(overrides = {}) {
+  return {
+    question_id: "question-1",
+    question: "需要部署到哪个区域？",
+    type: "single_select",
+    options: [
+      { value: "cn", label: "中国" },
+      { value: "us", label: "美国" },
+    ],
+    ...overrides,
+  };
+}
+
+test("单选回答收到数组时收敛为首项，而不是让整次交互失败", () => {
+  const answers = resolve_ask_question_answers(
+    [create_question()],
+    { answers: [{ question_id: "question-1", value: ["cn"] }] },
+  );
+
+  assert.deepEqual(answers, [{ question_id: "question-1", value: "cn" }]);
+});
+
+test("多选回答的形状保持为字符串数组", () => {
+  const answers = resolve_ask_question_answers(
+    [create_question({ type: "multi_select" })],
+    { answers: [{ question_id: "question-1", value: ["cn", "us"] }] },
+  );
+
+  assert.deepEqual(answers, [{ question_id: "question-1", value: ["cn", "us"] }]);
+});
+
+test("多选回答收到字符串时收编为单元素数组", () => {
+  const answers = resolve_ask_question_answers(
+    [create_question({ type: "multi_select" })],
+    { answers: [{ question_id: "question-1", value: "cn" }] },
+  );
+
+  assert.deepEqual(answers, [{ question_id: "question-1", value: ["cn"] }]);
+});
+
+test("文本回答保持字符串，即使问题带了候选项", () => {
+  const answers = resolve_ask_question_answers(
+    [create_question({ type: "text" })],
+    { answers: [{ question_id: "question-1", value: "在上海部署" }] },
+  );
+
+  assert.deepEqual(answers, [{ question_id: "question-1", value: "在上海部署" }]);
+});
+
+test("回答顺序跟随提问顺序，而不是提交顺序", () => {
+  const answers = resolve_ask_question_answers(
+    [
+      create_question({ question_id: "question-1" }),
+      create_question({ question_id: "question-2" }),
+    ],
+    {
+      answers: [
+        { question_id: "question-2", value: "us" },
+        { question_id: "question-1", value: "cn" },
+      ],
+    },
+  );
+
+  assert.deepEqual(answers, [
+    { question_id: "question-1", value: "cn" },
+    { question_id: "question-2", value: "us" },
+  ]);
+});
+
+test("缺答、重复与越界选项都会抛出可读错误", () => {
+  assert.throws(
+    () => resolve_ask_question_answers([create_question()], { answers: [] }),
+    /expected 1 answers but received 0/u,
+  );
+  assert.throws(
+    () =>
+      resolve_ask_question_answers([create_question()], {
+        answers: [
+          { question_id: "question-1", value: "cn" },
+          { question_id: "question-1", value: "us" },
+        ],
+      }),
+    /Duplicate ask_question answer/u,
+  );
+  assert.throws(
+    () =>
+      resolve_ask_question_answers([create_question()], {
+        answers: [{ question_id: "question-1", value: "eu" }],
+      }),
+    /not a valid option/u,
+  );
+});
+
+test("回答值不是字符串或字符串数组时抛出，不把对象当成答案", () => {
+  assert.throws(
+    () =>
+      resolve_ask_question_answers([create_question({ type: "text" })], {
+        answers: [{ question_id: "question-1", value: { text: "cn" } }],
+      }),
+    /must be a string or string array/u,
+  );
+});
+
+test("payload 结构不可用时视为未提交回答", () => {
+  assert.throws(
+    () => resolve_ask_question_answers([create_question()], null),
+    /expected 1 answers but received 0/u,
+  );
+});
+
+test("补充说明只在非空字符串时透出", () => {
+  assert.equal(read_ask_question_note({ answers: [], note: "已确认" }), "已确认");
+  assert.equal(read_ask_question_note({ answers: [], note: "   " }), undefined);
+  assert.equal(read_ask_question_note({ answers: [] }), undefined);
+  assert.equal(read_ask_question_note(null), undefined);
+});