@downcity/agent 1.1.438 → 1.1.445

package/src/session/execution/tools/SessionShellApprovalAdapter.ts

@@ -1,105 +0,0 @@
-/**
- * Shell 审批到 Session Interaction 的执行边界 Adapter。
- *
- * Shell 只理解高风险命令审批协议；本 Adapter 把它转换成 Session 的通用
- * approval Interaction，并把 Interaction 终态映射回 Shell 决策。
- */
-
-import type {
-  ShellApprovalGateway,
-  ShellApprovalHandle,
-  ShellApprovalRequest,
-  ShellApprovalStatus,
-} from "@downcity/type";
-import type { SessionInteractions } from "@/session/control/SessionInteractions.js";
-import type { SessionApprovalMode } from "@downcity/type";
-import { generate_id } from "@/utils/Id.js";
-
-/** 单个 Session 的 Shell 高风险操作审批 Adapter。 */
-export class SessionShellApprovalAdapter implements ShellApprovalGateway {
-  private readonly session_id: string;
-  private readonly interactions: SessionInteractions;
-  private mode: SessionApprovalMode = "ask";
-
-  constructor(options: {
-    /** 当前 Adapter 所属 Session 标识。 */
-    session_id: string;
-    /** 当前 Session 的异步用户交互入口。 */
-    interactions: SessionInteractions;
-  }) {
-    this.session_id = String(options.session_id || "").trim();
-    this.interactions = options.interactions;
-    if (!this.session_id) {
-      throw new Error(
-        "SessionShellApprovalAdapter requires a non-empty session_id",
-      );
-    }
-  }
-
-  /** 把 Shell 高风险操作请求转换成 approval Interaction。 */
-  async request(input: ShellApprovalRequest): Promise<ShellApprovalHandle> {
-    if (input.session_id !== this.session_id) {
-      throw new Error(`Approval Session mismatch: ${input.session_id}`);
-    }
-    const interaction_id = `interaction:${generate_id()}`;
-    if (this.mode === "always-allow") {
-      return {
-        approval_id: interaction_id,
-        requires_user_decision: false,
-        decision: Promise.resolve("approved"),
-      };
-    }
-
-    const created_at = Date.now();
-    const handle = await this.interactions.request({
-      interaction_id,
-      turn_id: input.turn_id,
-      type: "approval",
-      source: {
-        type: "shell",
-        tool_call_id: input.tool_call_id,
-        tool_name: input.tool_name,
-      },
-      title: `Approve ${input.tool_name}`,
-      description: input.reason,
-      payload: {
-        operation: input.operation,
-        command: input.command,
-        cwd: input.cwd,
-        reason: input.reason,
-      },
-      response_schema: {
-        type: "object",
-        required: ["decision"],
-        properties: {
-          decision: { type: "string", enum: ["approved", "denied"] },
-        },
-      },
-      created_at,
-      expires_at: created_at + input.timeout_ms,
-    });
-
-    return {
-      approval_id: interaction_id,
-      requires_user_decision: true,
-      decision: handle.result.then((result): ShellApprovalStatus => {
-        if (result.status === "expired") return "expired";
-        if (result.status !== "resolved") return "denied";
-        if (result.response.outcome !== "resolved" || result.response.type !== "approval") return "denied";
-        const payload = result.response.payload;
-        if (!payload || typeof payload !== "object" || Array.isArray(payload)) return "denied";
-        return (payload as { decision?: "approved" | "denied" }).decision || "denied";
-      }),
-    };
-  }
-
-  /** 读取当前 Session 执行面使用的高风险操作审批模式。 */
-  get_effective_mode(): SessionApprovalMode {
-    return this.mode;
-  }
-
-  /** 在 Session Step 检查点提交后续高风险操作请求使用的审批模式。 */
-  set_effective_mode(mode: SessionApprovalMode): void {
-    this.mode = mode === "always-allow" ? "always-allow" : "ask";
-  }
-}

package/src/session/messages/SessionAgentActionPartWriter.ts

@@ -1,54 +0,0 @@
-/**
- * 单个 canonical Action Part 的生命周期写入器。
- *
- * Writer 只保存目标 Message 身份与发布策略，实际状态仍由 SessionMessages
- * 持久化和接受，避免形成第二份 Action 状态。
- */
-
-import type { SessionMessages } from "@/session/SessionMessages.js";
-import type { CompleteSessionAgentActionPartInput } from "@/types/session/SessionMessages.js";
-
-/** 单个 Action Part 的生命周期 writer。 */
-export class SessionAgentActionPartWriter {
-  /** 当前 Action Part 所属 Agent Message 的稳定标识。 */
-  readonly message_id: string;
-  private readonly messages: SessionMessages;
-  private readonly publish_mutation: boolean;
-  private closed = false;
-
-  constructor(
-    messages: SessionMessages,
-    message_id: string,
-    publish_mutation = true,
-  ) {
-    this.messages = messages;
-    this.message_id = message_id;
-    this.publish_mutation = publish_mutation;
-  }
-
-  /** 把 Action 更新为 completed。 */
-  async complete(input?: CompleteSessionAgentActionPartInput): Promise<void> {
-    if (this.closed) return;
-    await this.messages.update_action_part(
-      this.message_id,
-      "completed",
-      input,
-      { publish_mutation: this.publish_mutation },
-    );
-    this.closed = true;
-  }
-
-  /** 把 Action 更新为 failed。 */
-  async fail(error: unknown): Promise<void> {
-    if (this.closed) return;
-    await this.messages.update_action_part(
-      this.message_id,
-      "failed",
-      {
-        description: error instanceof Error ? error.message : String(error),
-      },
-      { publish_mutation: this.publish_mutation },
-    );
-    this.closed = true;
-  }
-}

package/src/session/messages/SessionMessageInteractionWriter.ts

@@ -1,279 +0,0 @@
-/**
- * Session Message Interaction 写入器。
- *
- * 该模块只负责 Assistant Message 内 Interaction Part 与关联 Tool Part 的
- * 原子状态转换；消息持久化、revision 串行化和 Mutation 发布仍由
- * SessionMessages 提供，避免复制 canonical Message 状态。
- */
-
-import type {
-  SessionAgentInteractionPart,
-  SessionAgentMessage,
-  SessionAgentMessagePart,
-  SessionMessage,
-} from "@downcity/type";
-import type {
-  SessionInteractionCloseInput,
-  SessionInteractionRequest,
-  SessionInteractionResponse,
-} from "@downcity/type";
-import type { SessionStreamingToolLocation } from "@/types/session/SessionTool.js";
-
-/** Interaction 写入器依赖的最小 Message 能力。 */
-interface SessionMessageInteractionWriterOptions {
-  /** 返回当前 Session 内存中的 canonical Message 集合。 */
-  list_messages: () => Iterable<SessionMessage>;
-  /** 查找当前流式 Assistant 中的指定 Tool Part。 */
-  find_streaming_tool: (
-    tool_call_id: string,
-  ) => SessionStreamingToolLocation | undefined;
-  /** 在指定 Assistant Message 的串行事务链中执行写操作。 */
-  enqueue_assistant_write: <T>(
-    message_id: string,
-    operation: () => Promise<T>,
-  ) => Promise<T>;
-  /** 原子持久化 Assistant 完整快照并发布发生变化的 Part。 */
-  commit_assistant_snapshot: (
-    current: SessionAgentMessage,
-    parts: SessionAgentMessagePart[],
-  ) => Promise<void>;
-}
-
-/** 管理 canonical Assistant Message 内的 Interaction 生命周期。 */
-export class SessionMessageInteractionWriter {
-  private readonly options: SessionMessageInteractionWriterOptions;
-
-  constructor(options: SessionMessageInteractionWriterOptions) {
-    this.options = options;
-  }
-
-  /** 返回当前 Session 中全部等待用户响应的 canonical Interaction。 */
-  list_pending(): SessionAgentInteractionPart[] {
-    return [...this.options.list_messages()].flatMap((message) =>
-      message.role === "agent" && message.state === "streaming"
-        ? message.parts.flatMap((part) =>
-            part.type === "interaction" && part.status === "pending"
-              ? [structuredClone(part)]
-              : [],
-          )
-        : [],
-    );
-  }
-
-  /** 原子创建 Interaction，并把关联 Tool 转为 waiting-user。 */
-  async request(
-    request: SessionInteractionRequest,
-  ): Promise<SessionAgentInteractionPart> {
-    const tool_call_id = request.source.tool_call_id;
-    const message_id = tool_call_id
-      ? this.require_streaming_tool(tool_call_id).message_id
-      : this.require_streaming_assistant().message_id;
-    await this.options.enqueue_assistant_write(message_id, async () => {
-      const current = this.require_streaming_assistant(message_id);
-      if (
-        current.parts.some(
-          (part) =>
-            part.type === "interaction" &&
-            part.interaction_id === request.interaction_id,
-        )
-      ) {
-        throw new Error(`Session Interaction already exists: ${request.interaction_id}`);
-      }
-
-      let parts = current.parts;
-      if (tool_call_id) {
-        const tool = this.require_streaming_tool(tool_call_id);
-        if (tool.message_id !== message_id) {
-          throw new Error(
-            `Tool Assistant Message changed: ${tool_call_id}`,
-          );
-        }
-        if (tool.part.state !== "ready" && tool.part.state !== "waiting-user") {
-          throw new Error(
-            `Tool Interaction requires ready input: ${tool_call_id} (${tool.part.state})`,
-          );
-        }
-        if (tool.part.state === "ready") {
-          parts = parts.map((part) =>
-            part.part_id === tool.part.part_id
-              ? { ...tool.part, state: "waiting-user" as const }
-              : part,
-          );
-        }
-      }
-
-      const interaction: SessionAgentInteractionPart = {
-        part_id: `interaction:${request.interaction_id}`,
-        sequence: parts.reduce(
-          (sequence, part) => Math.max(sequence, part.sequence + 1),
-          1,
-        ),
-        type: "interaction",
-        interaction_id: request.interaction_id,
-        interaction_type: request.type,
-        status: "pending",
-        request: structuredClone(request),
-      };
-      await this.options.commit_assistant_snapshot(current, [...parts, interaction]);
-    });
-    return this.require_pending_interaction(request.interaction_id).part;
-  }
-
-  /** 原子保存用户响应，并按 Interaction 结果恢复或终止关联 Tool。 */
-  async resolve(
-    interaction_id: string,
-    response: SessionInteractionResponse,
-  ): Promise<SessionAgentInteractionPart> {
-    const { message_id } = this.require_pending_interaction(interaction_id);
-    await this.options.enqueue_assistant_write(message_id, async () => {
-      const current = this.require_streaming_assistant(message_id);
-      const interaction = this.require_pending_interaction(interaction_id);
-      if (interaction.message_id !== message_id) {
-        throw new Error(`Session Interaction Message changed: ${interaction_id}`);
-      }
-      if (interaction.part.interaction_type !== response.type) {
-        throw new Error(`Session Interaction response type mismatch: ${interaction_id}`);
-      }
-      const tool_call_id = interaction.part.request.source.tool_call_id;
-      const parts = current.parts.map((part) => {
-        if (part.part_id === interaction.part.part_id) {
-          return {
-            ...interaction.part,
-            status: response.outcome === "denied"
-              ? "denied" as const
-              : "resolved" as const,
-            response: structuredClone(response),
-            resolved_at: Date.now(),
-          };
-        }
-        if (
-          tool_call_id &&
-          part.type === "tool" &&
-          part.tool_call_id === tool_call_id
-        ) {
-          if (part.state !== "waiting-user") {
-            throw new Error(
-              `Tool is not waiting for Interaction: ${part.tool_call_id} (${part.state})`,
-            );
-          }
-          return response.outcome === "denied"
-            ? { ...part, state: "failed" as const, error: "Interaction denied" }
-            : { ...part, state: "running" as const };
-        }
-        return part;
-      });
-      await this.options.commit_assistant_snapshot(current, parts);
-    });
-    return this.require_interaction(interaction_id).part;
-  }
-
-  /** 原子结束未响应 Interaction，并把关联 Tool 标记为失败。 */
-  async close(
-    interaction_id: string,
-    input: SessionInteractionCloseInput,
-  ): Promise<SessionAgentInteractionPart> {
-    const { message_id } = this.require_pending_interaction(interaction_id);
-    await this.options.enqueue_assistant_write(message_id, async () => {
-      const current = this.require_streaming_assistant(message_id);
-      const interaction = this.require_pending_interaction(interaction_id);
-      const error = input.status === "expired"
-        ? "Interaction expired"
-        : "Interaction cancelled";
-      const parts = current.parts.map((part) => {
-        if (part.part_id === interaction.part.part_id) {
-          return {
-            ...interaction.part,
-            status: input.status,
-            resolved_at: Date.now(),
-            ...(input.status === "cancelled"
-              ? { cancel_reason: input.reason }
-              : {}),
-          };
-        }
-        const tool_call_id = interaction.part.request.source.tool_call_id;
-        if (
-          tool_call_id &&
-          part.type === "tool" &&
-          part.tool_call_id === tool_call_id
-        ) {
-          if (part.state !== "waiting-user") return part;
-          return { ...part, state: "failed" as const, error };
-        }
-        return part;
-      });
-      await this.options.commit_assistant_snapshot(current, parts);
-    });
-    return this.require_interaction(interaction_id).part;
-  }
-
-  /** 读取指定或当前唯一的流式 Assistant Message。 */
-  private require_streaming_assistant(
-    message_id?: string,
-  ): SessionAgentMessage {
-    const message = message_id
-      ? [...this.options.list_messages()].find(
-          (item) => item.message_id === message_id,
-        )
-      : [...this.options.list_messages()].find(
-          (item) => item.role === "agent" && item.state === "streaming",
-        );
-    if (!message || message.role !== "agent" || message.state !== "streaming") {
-      throw new Error(
-        message_id
-          ? `Streaming Assistant Message not found: ${message_id}`
-          : "Streaming Assistant Message not found",
-      );
-    }
-    return message;
-  }
-
-  /** 查找指定 Interaction Part 及其所属流式 Assistant。 */
-  private find_interaction(interaction_id: string):
-    | {
-        message_id: string;
-        part: SessionAgentInteractionPart;
-      }
-    | undefined {
-    for (const message of this.options.list_messages()) {
-      if (message.role !== "agent" || message.state !== "streaming") continue;
-      const part = message.parts.find(
-        (item): item is SessionAgentInteractionPart =>
-          item.type === "interaction" &&
-          item.interaction_id === interaction_id,
-      );
-      if (part) return { message_id: message.message_id, part };
-    }
-    return undefined;
-  }
-
-  /** 读取指定 Interaction，否则抛出稳定领域错误。 */
-  private require_interaction(interaction_id: string): {
-    message_id: string;
-    part: SessionAgentInteractionPart;
-  } {
-    const interaction = this.find_interaction(interaction_id);
-    if (interaction) return interaction;
-    throw new Error(`Session Interaction not found: ${interaction_id}`);
-  }
-
-  /** 读取指定 pending Interaction，否则拒绝重复响应终态 Interaction。 */
-  private require_pending_interaction(interaction_id: string): {
-    message_id: string;
-    part: SessionAgentInteractionPart;
-  } {
-    const interaction = this.require_interaction(interaction_id);
-    if (interaction.part.status !== "pending") {
-      throw new Error(
-        `Session Interaction is already ${interaction.part.status}: ${interaction_id}`,
-      );
-    }
-    return interaction;
-  }
-
-  /** 查找当前流式 Assistant 中的 Tool Part，否则抛出明确错误。 */
-  private require_streaming_tool(tool_call_id: string): SessionStreamingToolLocation {
-    const tool = this.options.find_streaming_tool(tool_call_id);
-    if (tool) return tool;
-    throw new Error(`Streaming Tool Part not found: ${tool_call_id}`);
-  }
-}

package/src/types/action/ActionResult.ts

@@ -1,50 +0,0 @@
-/**
- * Action 与 Session Tool 共用的执行结果协议。
- *
- * 关键点（中文）
- * - `output` 是标准 Tool Result，原样交给模型执行器和 canonical Tool Part。
- * - `messages` 是执行后产生的运行期 User 输入或 canonical Agent 内容。
- * - `effects` 是当前 Turn 只追加收集、并在收口检查点解释的已发生副作用。
- * - Message Parts 复用 Downcity Session UI 协议，不再建立文件、图片或 Plugin 专用桥接。
- */
-
-import type { RuntimeToolEffect } from "@downcity/type";
-import type {
-  SessionAgentContent,
-  SessionModelUserContent,
-} from "@downcity/type";
-
-/** Action 执行后产生的一条 Session 消息。 */
-export type ActionResultMessage =
-  | {
-      /** User 内容在下一 Step 生效。 */
-      role: "user";
-      /** 只在当前 Turn 生效、不会伪装成 canonical Message 的模型输入。 */
-      parts: SessionModelUserContent[];
-    }
-  | {
-      /** Agent 内容写入当前 canonical 回复。 */
-      role: "agent";
-      /** 等待追加到 canonical Agent Message 的内容。 */
-      parts: SessionAgentContent[];
-    };
-
-/** Action 或 Tool 内部实现返回的统一结果。 */
-export interface ActionResult<TOutput = unknown> {
-  /** 返回给调用方、模型执行器与 canonical Tool Part 的标准执行输出。 */
-  output: TOutput;
-
-  /** 执行产生的运行期 User 输入或 Agent 输出；没有附加内容时传入空数组。 */
-  messages: ActionResultMessage[];
-
-  /** 已经发生且需要由当前 Turn 收集的副作用；不会发送给模型或直接持久化。 */
-  effects?: readonly RuntimeToolEffect[];
-}
-
-/** 判断未知 Tool 输出是否使用统一 ActionResult 协议。 */
-export function is_action_result(value: unknown): value is ActionResult {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  const record = value as Record<string, unknown>;
-  return Object.prototype.hasOwnProperty.call(record, "output") &&
-    Array.isArray(record.messages);
-}

package/src/types/executor/SessionToolExecutionContext.ts

@@ -1,26 +0,0 @@
-/**
- * Session tool 显式执行上下文。
- *
- * 关键点（中文）
- * - 该对象由 Executor 在每个 Session step 绑定到 tool.execute。
- * - Agent 工具读取 session_turn_context，Shell 工具只读取 shell_execution_context。
- * - 上下文归属当前 Turn，不通过进程级或异步全局容器共享。
- */
-
-import type {
-  ShellExecutionContext,
-} from "@downcity/type/shell";
-import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
-import type { ToolActionExecutionContext } from "@/types/tools/ToolActionExecutionContext.js";
-
-/**
- * Agent 与 Shell 工具共用的单次执行上下文。
- */
-export interface SessionToolExecutionContext {
-  /** 业务 Tool 读取的最小执行上下文。 */
-  action_execution_context: ToolActionExecutionContext;
-  /** 当前 Shell Tool 的 canonical 执行上下文。 */
-  shell_execution_context: ShellExecutionContext;
-  /** 当前工具调用所属的完整 Session Turn 上下文。 */
-  session_turn_context: SessionTurnContext;
-}

package/src/types/session/SessionContextPolicy.ts

@@ -1,77 +0,0 @@
-/**
- * Session Composer 的上下文策略协议。
- *
- * Policy 只读取 canonical Message，并在自己的命名空间维护可删除、可重建的派生数据；
- * 它不修改 Session Message、State 或 Turn 生命周期。
- */
-
-import type { ModelClient, ModelMessage, SessionSystemBlock } from "@downcity/type";
-import type { ModelRequestFailureReporter } from "@/types/executor/ModelRequest.js";
-import type { SessionComposerStorage } from "@/types/store/SessionStorage.js";
-
-/** Composer 可以处理的上下文恢复原因。 */
-export type SessionContextRecoveryReason =
-  /** Provider 明确拒绝超出上下文窗口的请求。 */
-  | "provider_context_limit"
-  /** Provider usage 已达到主动压缩阈值。 */
-  | "usage_pressure";
-
-/** Policy 初始化输入。 */
-export interface SessionContextPolicyInitializeInput {
-  /** 当前 Policy 已限定命名空间的派生存储。 */
-  storage: SessionComposerStorage;
-}
-
-/** Policy 正常解析上下文的输入。 */
-export interface SessionContextPolicyInput {
-  /** 当前 Policy 已限定命名空间的派生存储。 */
-  storage: SessionComposerStorage;
-  /** 解析文件 Part 时使用的 Workspace 根目录。 */
-  project_root: string;
-}
-
-/** 上下文恢复输入。 */
-export interface SessionContextPolicyRecoveryInput extends SessionContextPolicyInput {
-  /** 触发当前恢复的稳定领域原因。 */
-  reason: SessionContextRecoveryReason;
-  /** 用于生成派生摘要的当前模型。 */
-  model?: ModelClient;
-  /** 模型请求逐次失败的可选观测入口。 */
-  on_model_request_failure?: ModelRequestFailureReporter;
-}
-
-/** Policy 对本次模型上下文的只读诊断。 */
-export interface SessionResolvedContextDiagnostics {
-  /** 生成当前上下文的 Policy 名称。 */
-  policy_name: string;
-  /** 当前上下文覆盖到的最新 canonical Message sequence。 */
-  through_sequence?: number;
-  /** 当前派生边界在 Message 内覆盖到的 Part sequence。 */
-  through_part_sequence?: number;
-  /** 当前上下文是否使用了派生摘要或检索结果。 */
-  derived: boolean;
-  /** 当前使用的可选派生记录标识。 */
-  derivation_id?: string;
-}
-
-/** Policy 已确定顺序的最终模型历史。 */
-export interface SessionResolvedContext {
-  /** 送入模型的标准历史消息。 */
-  messages: ModelMessage[];
-  /** 由 Policy 生成、且不伪装成普通历史消息的显式 system 上下文。 */
-  system_blocks?: SessionSystemBlock[];
-  /** 不进入 canonical history 的策略诊断。 */
-  diagnostics: SessionResolvedContextDiagnostics;
-}
-
-/** Session Composer 内部可替换的上下文策略。 */
-export interface SessionContextPolicy {
-  /** Policy 稳定名称，同时作为派生表命名空间。 */
-  readonly name: string;
-  /** 初始化当前 Policy 的派生 schema。 */
-  initialize(input: SessionContextPolicyInitializeInput): Promise<void>;
-  /** 从 canonical history 与派生数据生成模型历史。 */
-  resolve(input: SessionContextPolicyInput): Promise<SessionResolvedContext>;
-  /** 模型上下文失败后尝试推进派生状态；发生有效变化时返回 true。 */
-  recover(input: SessionContextPolicyRecoveryInput): Promise<boolean>;
-}

package/src/types/tools/ToolActionExecutionContext.ts

@@ -1,32 +0,0 @@
-/**
- * 普通 Tool 一次调用获得的最小执行上下文。
- *
- * 该类型只暴露业务 Tool 需要的调用身份、取消、Workspace 快照和可选
- * Session Interaction，不暴露 SessionTurnContext、消息写入器或 Plugin lease。
- */
-
-import type { SessionInteractionPort } from "@downcity/type";
-
-/** 普通 Tool 所属的 Session 范围。 */
-export interface ToolSessionExecutionScope {
-  /** 当前 Session 标识。 */
-  readonly session_id: string;
-  /** 当前 Turn 标识。 */
-  readonly turn_id: string;
-  /** 当前 Session 的用户交互端口；未启用 Interaction 时为空。 */
-  readonly interactions?: SessionInteractionPort;
-}
-
-/** 普通 Tool 的单次调用上下文。 */
-export interface ToolActionExecutionContext {
-  /** 当前 Tool Call 标识。 */
-  readonly call_id: string;
-  /** 当前 Tool 调用的取消信号。 */
-  readonly abort_signal: AbortSignal;
-  /** 当前 Tool 所属 Session 范围。 */
-  readonly session: ToolSessionExecutionScope;
-  /** 当前 Workspace 项目根目录。 */
-  readonly workspace_path?: string;
-  /** 当前 Step 已提交生效的 Workspace env。 */
-  readonly workspace_env?: Readonly<Record<string, string>>;
-}