@downcity/agent 1.1.287 → 1.1.310

package/src/session/approval/SessionApprovalBroker.ts

@@ -1,164 +0,0 @@
-/**
- * Session 级 Tool 审批 Broker。
- *
- * 关键点（中文）
- * - pending approval、审批模式、超时与用户决定只归当前 Session 所有。
- * - Shell 通过强类型 Gateway 等待结果，不保存或反向发布 Session 状态。
- */
-
-import { generateId } from "@/utils/Id.js";
-import type {
-  ShellApprovalGateway,
-  ShellApprovalHandle,
-  ShellApprovalRequest,
-  ShellApprovalStatus,
-} from "@downcity/shell";
-import type {
-  SessionApproval,
-  SessionApprovalDecision,
-  SessionApprovalMode,
-  SessionApprovalModeSnapshot,
-  SessionApprovalResult,
-} from "@/types/session/SessionApproval.js";
-import type { SessionPendingApproval } from "@/types/session/SessionApprovalBroker.js";
-import type { SessionMessages } from "@/session/SessionMessages.js";
-
-/** 单个 Session 的审批状态与决定入口。 */
-export class SessionApprovalBroker implements ShellApprovalGateway {
-  private readonly session_id: string;
-  private readonly messages: SessionMessages;
-  private readonly pending_by_id = new Map<string, SessionPendingApproval>();
-  private mode: SessionApprovalMode = "ask";
-
-  /**
-   * @param options Broker 所属 Session 与 Tool Runtime。
-   */
-  constructor(options: {
-    /** 当前 Broker 所属 Session。 */
-    session_id: string;
-    /** 当前 Session 的 Message 领域入口。 */
-    messages: SessionMessages;
-  }) {
-    this.session_id = options.session_id;
-    this.messages = options.messages;
-  }
-
-  /** Shell 调用的强类型审批网关入口。 */
-  async request(input: ShellApprovalRequest): Promise<ShellApprovalHandle> {
-    if (input.session_id !== this.session_id) {
-      throw new Error(`Approval Session mismatch: ${input.session_id}`);
-    }
-    const approval_id = `ap_${generateId()}`;
-    if (this.mode === "always-allow") {
-      return {
-        approval_id,
-        requires_user_decision: false,
-        decision: Promise.resolve("approved"),
-      };
-    }
-
-    const created_at = Date.now();
-    const approval: SessionApproval = {
-      approval_id,
-      session_id: this.session_id,
-      turn_id: input.turn_id,
-      tool_call_id: input.tool_call_id,
-      tool_name: input.tool_name,
-      command: input.command,
-      cwd: input.cwd,
-      reason: input.reason,
-      operation: input.operation,
-      created_at,
-      expires_at: created_at + input.timeout_ms,
-    };
-    let resolve_decision!: (decision: ShellApprovalStatus) => void;
-    const decision = new Promise<ShellApprovalStatus>((resolve) => {
-      resolve_decision = resolve;
-    });
-    const timer = setTimeout(() => {
-      void this.expire(approval_id);
-    }, input.timeout_ms);
-    if (typeof timer.unref === "function") timer.unref();
-    this.pending_by_id.set(approval_id, {
-      approval,
-      resolve: resolve_decision,
-      timer,
-    });
-
-    try {
-      await this.messages.request_tool_approval(approval);
-    } catch (error) {
-      clearTimeout(timer);
-      this.pending_by_id.delete(approval_id);
-      resolve_decision("denied");
-      throw error;
-    }
-    return {
-      approval_id,
-      requires_user_decision: true,
-      decision,
-    };
-  }
-
-  /** 返回当前 Session 的全部 pending approval 快照。 */
-  list(): SessionApproval[] {
-    return [...this.pending_by_id.values()].map((item) => structuredClone(item.approval));
-  }
-
-  /** 返回当前 Session 的审批模式。 */
-  get_mode(): SessionApprovalModeSnapshot {
-    return { session_id: this.session_id, mode: this.mode };
-  }
-
-  /** 更新当前 Session 的审批模式。 */
-  set_mode(mode: SessionApprovalMode): SessionApprovalModeSnapshot {
-    this.mode = mode === "always-allow" ? "always-allow" : "ask";
-    return this.get_mode();
-  }
-
-  /** 处理用户提交的审批决定。 */
-  async resolve(input: {
-    /** 当前审批请求标识。 */
-    approval_id: string;
-    /** 用户提交的审批决定。 */
-    decision: SessionApprovalDecision;
-  }): Promise<SessionApprovalResult> {
-    const success = await this.settle(input.approval_id, input.decision, false);
-    return { success, approval_id: input.approval_id, decision: input.decision };
-  }
-
-  /** 让当前 Session 的全部 pending 请求过期，用于停止或销毁执行。 */
-  async expire_all(): Promise<void> {
-    await Promise.all([...this.pending_by_id.keys()].map((approval_id) =>
-      this.settle(approval_id, "expired", true)
-    ));
-  }
-
-  /** 处理单个自动过期请求。 */
-  private async expire(approval_id: string): Promise<void> {
-    await this.settle(approval_id, "expired", true);
-  }
-
-  /** 先提交 Tool 状态，再兑现 Shell 等待 Promise，保证执行顺序稳定。 */
-  private async settle(
-    approval_id: string,
-    decision: ShellApprovalStatus,
-    force: boolean,
-  ): Promise<boolean> {
-    const pending = this.pending_by_id.get(approval_id);
-    if (!pending) return false;
-    try {
-      await this.messages.resolve_tool_approval({
-        approval_id,
-        decision,
-        tool_call_id: pending.approval.tool_call_id,
-      });
-    } catch (error) {
-      if (!force) throw error;
-    }
-    clearTimeout(pending.timer);
-    this.pending_by_id.delete(approval_id);
-    pending.resolve(decision);
-    return true;
-  }
-}

package/src/session/storage/Instruction.ts

@@ -1,72 +0,0 @@
-/**
- * Session system 显式快照存储。
- *
- * 关键点（中文）
- * - instruction.md 是可选文件，不存在时由 Session 在内存中重新生成完整 system。
- * - 空文件也是有效的完整 system 快照。
- * - 写入使用同目录临时文件替换，避免进程中断留下半份内容。
- */
-
-import { randomUUID } from "node:crypto";
-import path from "node:path";
-import fs from "fs-extra";
-import { getSdkAgentSessionInstructionPath } from "@/session/storage/Paths.js";
-import type {
-  SessionInstructionStorageLocation,
-  WriteSessionInstructionInput,
-} from "@/types/session/SessionInstruction.js";
-
-/** 读取 Session 显式固化的完整 system；文件不存在时返回 null。 */
-export async function read_session_instruction(
-  input: SessionInstructionStorageLocation,
-): Promise<string | null> {
-  const instruction_path = getSdkAgentSessionInstructionPath(
-    input.project_root,
-    input.agent_id,
-    input.session_id,
-  );
-  try {
-    return await fs.readFile(instruction_path, "utf8");
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
-    throw error;
-  }
-}
-
-/** 判断当前 Session 是否已经显式持久化 instruction.md。 */
-export async function has_session_instruction(
-  input: SessionInstructionStorageLocation,
-): Promise<boolean> {
-  return await fs.pathExists(
-    getSdkAgentSessionInstructionPath(
-      input.project_root,
-      input.agent_id,
-      input.session_id,
-    ),
-  );
-}
-
-/** 使用完整 system Markdown 原子覆盖当前 Session 的 instruction.md。 */
-export async function write_session_instruction(
-  input: WriteSessionInstructionInput,
-): Promise<void> {
-  const instruction_path = getSdkAgentSessionInstructionPath(
-    input.project_root,
-    input.agent_id,
-    input.session_id,
-  );
-  const temporary_path = [
-    instruction_path,
-    process.pid,
-    Date.now(),
-    randomUUID(),
-    "tmp",
-  ].join(".");
-  await fs.ensureDir(path.dirname(instruction_path));
-  try {
-    await fs.writeFile(temporary_path, input.instruction, "utf8");
-    await fs.move(temporary_path, instruction_path, { overwrite: true });
-  } finally {
-    await fs.remove(temporary_path);
-  }
-}

package/src/session/storage/Paths.ts

@@ -1,209 +0,0 @@
-/**
- * SDK Session 路径规则。
- *
- * 关键点（中文）
- * - 所有 agent session 统一落盘到 `.downcity/agents/<agentId>/sessions/<sessionId>/...`。
- * - `agentId` 是唯一隔离维度，不再保留第二套旧 session 根目录。
- */
-
-import path from "node:path";
-
-/**
- * `.downcity` 根目录路径。
- */
-export function getSdkDowncityDirPath(projectRoot: string): string {
-  return path.join(projectRoot, ".downcity");
-}
-
-/**
- * SDK agents 根目录路径。
- */
-export function getSdkAgentsRootDirPath(projectRoot: string): string {
-  return path.join(getSdkDowncityDirPath(projectRoot), "agents");
-}
-
-/**
- * 单个 agent 根目录路径。
- */
-export function getSdkAgentDirPath(
-  projectRoot: string,
-  agentId: string,
-): string {
-  return path.join(
-    getSdkAgentsRootDirPath(projectRoot),
-    encodeURIComponent(String(agentId || "").trim()),
-  );
-}
-
-/**
- * 单个 agent 的 sessions 根目录路径。
- */
-export function getSdkAgentSessionsRootDirPath(
-  projectRoot: string,
-  agentId: string,
-): string {
-  return path.join(getSdkAgentDirPath(projectRoot, agentId), "sessions");
-}
-
-/**
- * 单个 agent 的已归档 sessions 根目录路径。
- *
- * 关键点（中文）
- * - `archive_session` 会把整个 session 目录从 `sessions/<sessionId>` 移动到此处。
- * - `clean_archive` 会永久删除该目录下的全部内容。
- */
-export function getSdkAgentArchivedSessionsDirPath(
-  projectRoot: string,
-  agentId: string,
-): string {
-  return path.join(getSdkAgentDirPath(projectRoot, agentId), "archived-sessions");
-}
-
-/**
- * 单个已归档 session 的根目录路径。
- */
-export function getSdkAgentArchivedSessionDirPath(
-  projectRoot: string,
-  agentId: string,
-  sessionId: string,
-): string {
-  return path.join(
-    getSdkAgentArchivedSessionsDirPath(projectRoot, agentId),
-    encodeURIComponent(String(sessionId || "").trim()),
-  );
-}
-
-/**
- * 单个已归档 session 的消息目录路径。
- */
-export function getSdkAgentArchivedSessionMessagesDirPath(
-  projectRoot: string,
-  agentId: string,
-  sessionId: string,
-): string {
-  return path.join(
-    getSdkAgentArchivedSessionDirPath(projectRoot, agentId, sessionId),
-    "messages",
-  );
-}
-
-/**
- * 单个已归档 session 的 Active JSONL 文件路径。
- */
-export function getSdkAgentArchivedSessionMessagesPath(
-  projectRoot: string,
-  agentId: string,
-  sessionId: string,
-): string {
-  return path.join(
-    getSdkAgentArchivedSessionMessagesDirPath(projectRoot, agentId, sessionId),
-    "active.jsonl",
-  );
-}
-
-/**
- * 单个已归档 session 的 meta.json 路径。
- */
-export function getSdkAgentArchivedSessionMetaPath(
-  projectRoot: string,
-  agentId: string,
-  sessionId: string,
-): string {
-  return path.join(
-    getSdkAgentArchivedSessionMessagesDirPath(projectRoot, agentId, sessionId),
-    "meta.json",
-  );
-}
-
-/**
- * 单个 session 根目录路径。
- */
-export function getSdkAgentSessionDirPath(
-  projectRoot: string,
-  agentId: string,
-  sessionId: string,
-): string {
-  return path.join(
-    getSdkAgentSessionsRootDirPath(projectRoot, agentId),
-    encodeURIComponent(String(sessionId || "").trim()),
-  );
-}
-
-/**
- * 单个 session 显式固化完整 system 的 instruction.md 路径。
- *
- * 关键点（中文）
- * - 文件不存在表示 Session 恢复时继续采用 Agent 当前 instruction。
- * - 空文件表示调用方显式固化了空 system。
- */
-export function getSdkAgentSessionInstructionPath(
-  projectRoot: string,
-  agentId: string,
-  sessionId: string,
-): string {
-  return path.join(
-    getSdkAgentSessionDirPath(projectRoot, agentId, sessionId),
-    "instruction.md",
-  );
-}
-
-/**
- * 单个 session 的消息目录路径。
- */
-export function getSdkAgentSessionMessagesDirPath(
-  projectRoot: string,
-  agentId: string,
-  sessionId: string,
-): string {
-  return path.join(
-    getSdkAgentSessionDirPath(projectRoot, agentId, sessionId),
-    "messages",
-  );
-}
-
-/**
- * 单个 session 的 Active JSONL 文件路径。
- */
-export function getSdkAgentSessionMessagesPath(
-  projectRoot: string,
-  agentId: string,
-  sessionId: string,
-): string {
-  return path.join(
-    getSdkAgentSessionMessagesDirPath(projectRoot, agentId, sessionId),
-    "active.jsonl",
-  );
-}
-
-/**
- * 单个 session 的 meta.json 路径。
- */
-export function getSdkAgentSessionMetaPath(
-  projectRoot: string,
-  agentId: string,
-  sessionId: string,
-): string {
-  return path.join(
-    getSdkAgentSessionMessagesDirPath(projectRoot, agentId, sessionId),
-    "meta.json",
-  );
-}
-
-/**
- * 单个 session 的 inflight assistant 路径。
- *
- * 关键点（中文）
- * - 运行中的 assistant 只保留一份增量快照。
- * - step / tool 过程会持续重写这个文件，避免中途中断后过程完全丢失。
- * - 完成后再把最终 assistant 合并进 `active.jsonl`，并清理该文件。
- */
-export function getSdkAgentSessionAssistantMessagePath(
-  projectRoot: string,
-  agentId: string,
-  sessionId: string,
-): string {
-  return path.join(
-    getSdkAgentSessionMessagesDirPath(projectRoot, agentId, sessionId),
-    "assistant_message.json",
-  );
-}

package/src/types/common/EnvFile.ts

@@ -1,31 +0,0 @@
-/**
- * Env 文件工具相关类型定义。
- *
- * 职责说明（中文）
- * - 统一描述项目 `.env` 写入工具使用的最小数据结构。
- * - 避免工具模块直接内联匿名对象，便于后续在其他初始化流程中复用。
- * - 这里只描述“文件写入条目”，不承载运行时环境变量快照语义。
- */
-
-/**
- * Env 文件中的单条键值项。
- */
-export interface EnvFileEntry {
-  /**
-   * 环境变量键名。
-   *
-   * 关键点（中文）
-   * - 调用方应传入已规范化的变量名。
-   * - 工具层不会自动把任意字符串修正成合法变量名。
-   */
-  key: string;
-
-  /**
-   * 环境变量值。
-   *
-   * 关键点（中文）
-   * - 会按字面量写入目标文件。
-   * - 当前工具不额外做引号包裹或 shell 转义。
-   */
-  value: string;
-}

package/src/types/config/AgentProject.ts

@@ -1,85 +0,0 @@
-/**
- * Agent 项目初始化相关类型定义。
- *
- * 关键点（中文）
- * - 统一承载 CLI 与 control plane 共用的初始化输入/输出结构。
- * - 所有字段都面向"项目骨架创建"语义，不掺杂 runtime 状态。
- */
-
-import type { ExecutionBindingConfig } from "@/types/config/ExecutionBinding.js";
-
-/**
- * 可选的 chat channel 标识。
- */
-export type AgentProjectChannel = "telegram" | "feishu" | "qq";
-
-/**
- * 初始化 agent 项目的输入参数。
- */
-export interface AgentProjectInitializationInput {
-  /**
-   * agent 项目根目录（绝对路径或可解析相对路径）。
-   */
-  projectRoot: string;
-
-  /**
-   * agent 唯一标识。
-   *
-   * 关键点（中文）
-   * - 为空时会自动回退到目录名推导出的默认 id。
-   * - CLI 可把该字段写入自己的全局配置存储。
-   */
-  id?: string;
-
-  /**
-   * 项目执行绑定配置。
-   *
-   * 说明（中文）
-   * - 绑定 City AIService 暴露的模型 ID。
-   */
-  execution: ExecutionBindingConfig;
-
-  /**
-   * 需要启用的 chat channels。
-   *
-   * 关键点（中文）
-   * - SDK 初始化器只返回选择结果，不负责配置持久化。
-   */
-  channels?: AgentProjectChannel[];
-
-}
-
-/**
- * 初始化完成后的摘要结果。
- */
-export interface AgentProjectInitializationResult {
-  /**
-   * 已解析后的 agent 项目根目录（绝对路径）。
-   */
-  projectRoot: string;
-
-  /**
-   * 最终写入的 agent id。
-   */
-  id: string;
-
-  /**
-   * 最终启用的 chat channels。
-   */
-  channels: AgentProjectChannel[];
-
-  /**
-   * 最终选择的 City AIService 模型 ID。
-   */
-  modelId?: string;
-
-  /**
-   * 本次实际创建/写入的文件列表。
-   */
-  createdFiles: string[];
-
-  /**
-   * 因已存在而跳过的文件列表。
-   */
-  skippedFiles: string[];
-}

package/src/types/config/DowncityConfig.ts

@@ -1,153 +0,0 @@
-/**
- * Downcity 配置类型定义。
- *
- * 关键点（中文）
- * - 作为全局共享类型，不挂在 console 目录下。
- * - 供 agent、plugin、control plane 宿主层多处复用，避免反向类型依赖。
- */
-import type { LlmConfig } from "@/types/config/LlmConfig.js";
-import type { ExecutionBindingConfig } from "@/types/config/ExecutionBinding.js";
-import type { JsonObject } from "@/types/common/Json.js";
-
-/**
- * 单个聊天渠道配置。
- */
-export interface DowncityChatChannelConfig {
-  /**
-   * 当前渠道是否启用。
-   */
-  enabled?: boolean;
-  /**
-   * 绑定的渠道账户 ID。
-   */
-  channelAccountId?: string;
-}
-
-/**
- * 聊天插件渠道配置集合。
- */
-export interface DowncityChatPluginChannelsConfig {
-  /**
-   * Telegram 渠道配置。
-   */
-  telegram?: DowncityChatChannelConfig;
-  /**
-   * Feishu 渠道配置。
-   */
-  feishu?: DowncityChatChannelConfig;
-  /**
-   * QQ 渠道配置。
-   */
-  qq?: DowncityChatChannelConfig;
-}
-
-/**
- * 聊天插件队列配置。
- */
-export interface DowncityChatPluginQueueConfig {
-  /**
-   * 全局最大并发（不同 chatKey 之间）。
-   * 默认：2
-   */
-  maxConcurrency?: number;
-  /**
-   * 入站消息合并的防抖窗口（毫秒）。
-   *
-   * 关键点（中文）
-   * - 同一 chatKey 在该窗口内连续到达的多条消息，会在一次 run 前一起并入上下文。
-   * - 典型场景：用户先发一句话，再紧接着转发链接/卡片。
-   * - 设为 `0` 或负数可关闭该能力（立即执行首条消息）。
-   *
-   * 默认：600
-   */
-  mergeDebounceMs?: number;
-  /**
-   * 入站消息合并的最长等待时间（毫秒）。
-   *
-   * 关键点（中文）
-   * - 即使用户持续发送新消息，也不会无限延期；达到该上限后会立刻启动 run。
-   * - 用于平衡“尽量合并上下文”与“响应时延可控”。
-   * - 当 `mergeDebounceMs <= 0` 时该字段不会生效。
-   *
-   * 默认：2000
-   */
-  mergeMaxWaitMs?: number;
-}
-
-/**
- * 聊天插件配置。
- */
-export interface DowncityChatPluginConfig {
-  /**
-   * Chat 调度队列（按 chatKey 分 lane）。
-   */
-  queue?: DowncityChatPluginQueueConfig;
-  /**
-   * 消息平台 channel 配置。
-   */
-  channels?: DowncityChatPluginChannelsConfig;
-}
-
-/**
- * Agent 全局配置中的插件配置映射。
- */
-export interface DowncityPluginConfigMap {
-  /**
-   * chat 插件配置。
-   */
-  chat?: DowncityChatPluginConfig;
-  /**
-   * 其他插件配置。
-   */
-  [pluginName: string]:
-    | JsonObject
-    | DowncityChatPluginConfig
-    | undefined;
-}
-
-export interface DowncityConfig {
-  /**
-   * agent 唯一标识。
-   *
-   * 关键点（中文）
-   * - `@downcity/agent` 只关心稳定标识，不承担展示名语义。
-   * - 该字段同时用于 session/runtime/storage 目录归属。
-   */
-  id: string;
-  version: string;
-  /**
-   * Runtime startup configuration used by `downcity agent start`.
-   * CLI flags (if provided) take precedence over this config.
-   */
-  start?: {
-    port?: number;
-    host?: string;
-  };
-  /**
-   * plugins 配置。
-   *
-   * 关键点（中文）
-   * - 所有可配置能力统一收敛到 `plugins`，不再保留独立 `services` 域。
-   * - 需要持久化的 plugin 配置（例如 `plugins.chat.channels`）由宿主写入全局配置存储。
-   * - key 为 plugin 名称，value 为对应插件的结构化配置对象。
-   * - 当前阶段允许各 plugin 自定义字段，但必须保持 JSON 可序列化。
-   */
-  plugins?: DowncityPluginConfigMap;
-  /**
-   * 项目执行绑定配置。
-   *
-   * 关键点（中文）
-   * - 项目只有一种执行模式：`api`。
-   * - 绑定 City AIService 暴露的模型 ID。
-   */
-  execution?: ExecutionBindingConfig;
-  /**
-   * LLM 全量配置（通常来自平台全局层合并结果）。
-   *
-   * 关键点（中文）
-   * - `@downcity/agent` 本地 SDK 不直接消费该字段。
-   * - 宿主侧（例如 `downcity`）可读取该字段控制模型工厂行为，例如 `llm.logMessages`。
-   * - 该字段通常由宿主平台装配，不由 Agent SDK 解析。
-   */
-  llm?: LlmConfig;
-}