@downcity/agent 1.1.408 → 1.1.437

package/src/remote/transports/RpcRemoteAgentTransport.ts

@@ -1,187 +0,0 @@
-/**
- * RemoteAgent RPC transport。
- *
- * 关键点（中文）
- * - 只把 RemoteAgent 的 session actor 方法映射到 RpcClient。
- * - 长连接生命周期由 RpcClient 管理。
- */
-
-import type {
-  AgentCreateSessionInput,
-  AgentListSessionsInput,
-  AgentArchiveSessionInput,
-  AgentArchiveSessionsInput,
-  AgentArchiveSessionResult,
-  AgentArchiveSessionsResult,
-  AgentCleanArchiveResult,
-  AgentSessionForkInput,
-  AgentSessionInfo,
-  AgentSessionSetOptions,
-  AgentSessionStatus,
-  AgentSessionSummaryPage,
-  AgentSessionSystemSnapshot,
-  RemoteSessionSetInput,
-} from "@/types/agent/SessionTypes.js";
-import type {
-  ListSessionMessagesInput,
-  SessionMessagePage,
-} from "@/types/session/SessionMessage.js";
-import type {
-  RemoteAgentPluginActionInput,
-  RemoteAgentPluginActionResult,
-} from "@/types/agent/RemoteAgentPluginAction.js";
-import type { SessionMutation } from "@/types/session/SessionMutation.js";
-import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
-import type { AgentSessionStopResult } from "@/types/sdk/AgentSessionStop.js";
-import { RpcClient, parse_rpc_url } from "@/remote/transports/RpcClient.js";
-import type {
-  RemoteAgentTransport,
-  TransportSubscription,
-} from "@/remote/RemoteTransport.js";
-import type {
-  RespondSessionInteractionInput,
-  SessionInteractionResult,
-  SessionPendingInteraction,
-} from "@/types/session/SessionInteraction.js";
-
-/**
- * 本机 RPC transport。
- */
-export class RpcRemoteAgentTransport implements RemoteAgentTransport {
-  private readonly client: RpcClient;
-
-  constructor(url: string) {
-    this.client = new RpcClient(parse_rpc_url(url));
-  }
-
-  async create_session(input?: AgentCreateSessionInput): Promise<AgentSessionInfo> {
-    return await this.client.create_session(input);
-  }
-
-  async get_info(session_id: string): Promise<AgentSessionInfo> {
-    return await this.client.get_session(session_id);
-  }
-
-  async prompt(
-    session_id: string,
-    input: AgentSessionPromptInput,
-  ): Promise<{ id: string }> {
-    return await this.client.prompt_session({
-      session_id,
-      input,
-    });
-  }
-
-  async stop(session_id: string): Promise<AgentSessionStopResult> {
-    return await this.client.stop_session(session_id);
-  }
-
-  async compact(session_id: string): Promise<{ id: string }> {
-    return await this.client.compact_session(session_id);
-  }
-
-  async subscribe(params: {
-    session_id: string;
-    on_ready: () => void;
-    on_event: (event: SessionMutation) => void;
-    on_close: (error?: unknown) => void;
-  }): Promise<TransportSubscription> {
-    const subscription = await this.client.subscribe_session({
-      session_id: params.session_id,
-      on_ready: params.on_ready,
-      on_event: params.on_event,
-      on_close: params.on_close,
-    });
-    return {
-      close: async () => {
-        await subscription.unsubscribe();
-      },
-    };
-  }
-
-  async messages(
-    session_id: string,
-    input?: ListSessionMessagesInput,
-  ): Promise<SessionMessagePage> {
-    return await this.client.get_session_messages({
-      session_id,
-      input,
-    });
-  }
-
-  async system(session_id: string): Promise<AgentSessionSystemSnapshot> {
-    return await this.client.get_session_system(session_id);
-  }
-
-  async fork(
-    session_id: string,
-    input?: AgentSessionForkInput | string,
-  ): Promise<AgentSessionInfo> {
-    const message_id =
-      typeof input === "string"
-        ? String(input || "").trim() || undefined
-        : String(input?.message_id || "").trim() || undefined;
-    return await this.client.fork_session({
-      session_id,
-      ...(message_id ? { message_id } : {}),
-      ...(typeof input !== "string" && input?.include_message === false ? { include_message: false } : {}),
-    });
-  }
-
-  async list_sessions(input?: AgentListSessionsInput): Promise<AgentSessionSummaryPage> {
-    return await this.client.list_sessions(input);
-  }
-
-  async archive_session(
-    input: AgentArchiveSessionInput,
-  ): Promise<AgentArchiveSessionResult> {
-    return await this.client.archive_session(input);
-  }
-
-  async archive_sessions(
-    input?: AgentArchiveSessionsInput,
-  ): Promise<AgentArchiveSessionsResult> {
-    return await this.client.archive_sessions(input);
-  }
-
-  async clean_archive(): Promise<AgentCleanArchiveResult> {
-    return await this.client.clean_archive();
-  }
-
-  async run_plugin_action(
-    input: RemoteAgentPluginActionInput,
-  ): Promise<RemoteAgentPluginActionResult> {
-    return await this.client.run_internal_plugin_action({
-      plugin_name: input.plugin,
-      action_name: input.action,
-      ...(input.payload !== undefined ? { payload: input.payload } : {}),
-    });
-  }
-
-  async interactions(session_id: string): Promise<SessionPendingInteraction[]> {
-    return await this.client.get_session_interactions(session_id);
-  }
-
-  async status(session_id: string): Promise<AgentSessionStatus> {
-    return await this.client.get_session_status(session_id);
-  }
-
-  async set(
-    session_id: string,
-    input: RemoteSessionSetInput,
-    options?: AgentSessionSetOptions,
-  ): Promise<void> {
-    await this.client.set_session(session_id, input, options);
-  }
-
-  async respond(
-    session_id: string,
-    input: RespondSessionInteractionInput,
-  ): Promise<SessionInteractionResult> {
-    return await this.client.respond_session_interaction(session_id, input);
-  }
-
-  async close(): Promise<void> {
-    await this.client.close();
-  }
-}

package/src/session/SessionCommand.ts

@@ -1,42 +0,0 @@
-/**
- * Session 有序输入队列中的可执行 Command。
- *
- * Command 对象封装一次需要遵守 Session FIFO 与检查点顺序的行为。Queue 只保存
- * 对象和维护顺序，不识别 Prompt、配置、Compact 等业务种类。
- */
-
-import type {
-  SessionCommandCompletion,
-  SessionCommandOptions,
-} from "@/types/session/SessionCommand.js";
-
-/** 一次等待在 Session 检查点执行的 Command。 */
-export class SessionCommand {
-  private readonly execute_command: SessionCommandOptions["execute"];
-  private readonly cancel_command?: SessionCommandOptions["cancel"];
-  private readonly completion_info?: SessionCommandOptions["completion"];
-
-  /** @param options 当前 Command 的执行与可选取消行为。 */
-  constructor(options: SessionCommandOptions) {
-    this.execute_command = options.execute;
-    this.cancel_command = options.cancel;
-    this.completion_info = options.completion;
-  }
-
-  /** 执行当前 Command，并返回成功后需要持久化的完成信息。 */
-  async execute(): Promise<SessionCommandCompletion | undefined> {
-    await this.execute_command();
-    return this.completion_info;
-  }
-
-  /**
-   * 在 Session stop 时尝试取消当前 Command。
-   *
-   * @returns true 表示 Command 已取消并应从 Queue 移除；false 表示继续保留。
-   */
-  cancel(): boolean {
-    if (!this.cancel_command) return false;
-    this.cancel_command();
-    return true;
-  }
-}

package/src/session/messages/SessionMessageCompaction.ts

@@ -1,147 +0,0 @@
-/**
- * SessionMessages Active/Segment 上下文压缩计划生成。
- *
- * 关键点（中文）
- * - 按 Active 中 User/Assistant Message 数量选择最旧的 `floor(n / 2)` 条。
- * - 旧累计 Summary 与选中前缀只执行一次摘要模型调用。
- * - 较新的消息不进入摘要输入；摘要失败时不生成计划、不修改 canonical history。
- * - 成功计划由 SessionMessages 把连续 Active 前缀写入不可变 Segment，并保存累计 Summary。
- */
-
-import type { ModelClient } from "@downcity/type";
-import {
-  build_text_model_messages,
-  generate_model,
-} from "@executor/model/ModelGenerate.js";
-import { generate_id } from "@/utils/Id.js";
-import {
-  build_initial_session_compaction_prompt,
-  build_update_session_compaction_prompt,
-  SESSION_COMPACTION_SYSTEM_PROMPT,
-} from "@executor/composer/compaction/jsonl/JsonlSessionCompactionPrompts.js";
-import type {
-  SessionAssistantMessagePart,
-  SessionMessage,
-  SessionUserMessagePart,
-} from "@/types/session/SessionMessage.js";
-import type {
-  SessionCompactionPlan,
-} from "@/types/session/SessionComposer.js";
-import type { SessionContextSnapshot } from "@/types/session/SessionSegment.js";
-
-/** 摘要模型的最大输出 token，用于避免 Summary 自身无限增长。 */
-const SUMMARY_MAX_OUTPUT_TOKENS = 4_000;
-
-/**
- * 根据只读 Message 快照生成持久化压缩计划。
- *
- * 该函数可以调用模型生成 Summary，但不会写文件、修改 Recorder 或发布事件。
- */
-export async function compose_session_compaction(input: {
-  /** 当前 Session 标识。 */
-  session_id: string;
-  /** 当前累计 Summary 与 Active Message 快照。 */
-  snapshot: Readonly<SessionContextSnapshot>;
-  /** 生成累计 Summary 使用的模型。 */
-  model: ModelClient;
-}): Promise<SessionCompactionPlan | null> {
-  const context_messages = input.snapshot.messages.filter(
-    (message) => message.type === "user" || message.type === "assistant",
-  );
-  const compact_message_count = Math.floor(context_messages.length / 2);
-  if (compact_message_count <= 0) return null;
-  const compact_messages = context_messages.slice(0, compact_message_count);
-  const boundary = compact_messages.at(-1);
-  if (!boundary) return null;
-
-  const conversation_text = compact_messages
-    .map((message) => message_to_compaction_text(message))
-    .filter(Boolean)
-    .join("\n");
-  if (!conversation_text) {
-    throw new Error("Compaction requires non-empty Message context");
-  }
-  const previous_summary = String(input.snapshot.summary?.text || "").trim();
-  const prompt = previous_summary
-    ? build_update_session_compaction_prompt({
-        previous_summary,
-        new_conversation_text: conversation_text,
-      })
-    : build_initial_session_compaction_prompt({ conversation_text });
-  const result = await generate_model(input.model, {
-    messages: build_text_model_messages(SESSION_COMPACTION_SYSTEM_PROMPT, prompt),
-    max_output_tokens: SUMMARY_MAX_OUTPUT_TOKENS,
-  });
-  const summary = String(result.text || "").trim();
-  if (!summary) {
-    throw new Error("Compaction model returned an empty Summary");
-  }
-
-  return {
-    through_sequence: boundary.sequence,
-    boundary_message_id: boundary.message_id,
-    summary: {
-      record_type: "summary",
-      session_id: input.session_id,
-      summary_id: `summary:${input.session_id}:${generate_id()}`,
-      through_sequence: boundary.sequence,
-      text: summary,
-      created_at: Date.now(),
-    },
-  };
-}
-
-function message_to_compaction_text(message: SessionMessage): string {
-  if (message.type !== "user" && message.type !== "assistant") return "";
-  const parts = message.parts
-    .map(to_compaction_part)
-    .filter((part) => part !== null);
-  return safe_stringify({
-    role: message.type,
-    parts,
-  });
-}
-
-/** 把 canonical Part 收窄为 Summary 模型需要的稳定会话事实。 */
-function to_compaction_part(
-  part: SessionUserMessagePart | SessionAssistantMessagePart,
-): Record<string, unknown> | null {
-  if (part.type === "text") return { type: "text", text: part.text };
-  if (part.type === "reasoning" || part.type === "interaction") return null;
-  if (part.type === "file") {
-    return {
-      type: "file",
-      media_type: part.media_type,
-      url: part.url,
-      ...(part.filename ? { filename: part.filename } : {}),
-    };
-  }
-  if (part.type === "data") {
-    return {
-      type: "data",
-      data_type: part.data_type,
-      data: part.data,
-      ...(part.data_id ? { data_id: part.data_id } : {}),
-    };
-  }
-  if (part.type === "tool") {
-    return {
-      type: "tool",
-      tool_call_id: part.tool_call_id,
-      tool_name: part.tool_name,
-      state: part.state,
-      ...(part.input !== undefined ? { input: part.input } : {}),
-      ...(part.output !== undefined ? { output: part.output } : {}),
-      ...(part.error ? { error: part.error } : {}),
-    };
-  }
-  return null;
-}
-
-function safe_stringify(value: unknown): string {
-  try {
-    return JSON.stringify(value) || String(value || "");
-  } catch {
-    return String(value || "");
-  }
-}

package/src/session/runtime/SessionCompactOperation.ts

@@ -1,93 +0,0 @@
-/**
- * Session 显式压缩操作生命周期。
- *
- * 该模块只负责把队列 Command 的异步执行映射为公开 Compact Handle；压缩计划、
- * canonical 历史提交与事件发布仍由 Session 领域拥有。
- */
-
-import type {
-  AgentSessionCompactHandle,
-  AgentSessionCompactResult,
-} from "@/types/sdk/AgentSessionCompact.js";
-import type { SessionCompactHistory } from "@/types/session/SessionExecution.js";
-
-/** 创建显式压缩操作所需的领域回调。 */
-export interface CreateSessionCompactOperationOptions {
-  /** 当前显式压缩请求的稳定标识。 */
-  compact_id: string;
-  /** 在 Session Queue 检查点执行统一历史压缩。 */
-  run: () => ReturnType<SessionCompactHistory>;
-  /** 发布最终 Compact Mutation；观测失败不能改变结果。 */
-  publish_finish: (result: AgentSessionCompactResult) => void;
-  /** 尽力记录未被压缩领域入口吸收的异常。 */
-  log_error: (error_message: string) => Promise<void>;
-}
-
-/** 显式压缩操作暴露给 Session Queue 的内部能力。 */
-export interface SessionCompactOperation {
-  /** 立即返回给 SDK 调用方的等待句柄。 */
-  handle: AgentSessionCompactHandle;
-  /** 由排队的 Session Command 调用并负责最终兑现句柄。 */
-  execute: () => Promise<void>;
-}
-
-/** 创建一个与单次 Session Compact Command 绑定的操作生命周期。 */
-export function create_session_compact_operation(
-  options: CreateSessionCompactOperationOptions,
-): SessionCompactOperation {
-  let result: AgentSessionCompactResult | null = null;
-  let resolve_finished!: (value: AgentSessionCompactResult) => void;
-  const finished = new Promise<AgentSessionCompactResult>((resolve) => {
-    resolve_finished = resolve;
-  });
-
-  return {
-    handle: {
-      id: options.compact_id,
-      get result() {
-        return result;
-      },
-      finished,
-    },
-    execute: async () => {
-      let final_result: AgentSessionCompactResult;
-      try {
-        const outcome = await options.run();
-        const reason = outcome.compacted
-          ? "compacted"
-          : outcome.reason === "nothing_to_compact"
-            ? "nothing_to_compact"
-            : "compact_failed";
-        final_result = {
-          compact_id: options.compact_id,
-          success: reason !== "compact_failed",
-          compacted: outcome.compacted,
-          reason,
-          ...(outcome.error ? { error: outcome.error } : {}),
-        };
-      } catch (error) {
-        const error_message = error instanceof Error ? error.message : String(error);
-        final_result = {
-          compact_id: options.compact_id,
-          success: false,
-          compacted: false,
-          reason: "compact_failed",
-          error: error_message,
-        };
-        try {
-          await options.log_error(error_message);
-        } catch {
-          // 关键点（中文）：日志属于观测侧，失败不能阻止 Handle 收口。
-        }
-      }
-
-      result = final_result;
-      try {
-        options.publish_finish(final_result);
-      } catch {
-        // 关键点（中文）：事件发布失败不能让已完成的 Command 反向失败。
-      }
-      resolve_finished(final_result);
-    },
-  };
-}

package/src/session/runtime/SessionHistoryCompaction.ts

@@ -1,45 +0,0 @@
-/**
- * Session 历史压缩结果收口器。
- *
- * Session 仍提供 Composer 输入和 canonical 提交回调；本模块统一成功、空计划、
- * 失败与 best-effort 日志的结果映射，供显式压缩和自动恢复共同复用。
- */
-
-import type { SessionCompactionPlan } from "@/types/session/SessionComposer.js";
-import type { SessionCompactHistory } from "@/types/session/SessionExecution.js";
-
-/** 执行一次历史压缩所需的 Session 领域回调。 */
-export interface RunSessionHistoryCompactionOptions {
-  /** 当前压缩所属 Turn；空值表示显式队列命令尚未进入 Turn。 */
-  turn_id?: string;
-  /** 让 Composer 基于只读 Session 快照生成压缩计划。 */
-  create_plan: () => Promise<SessionCompactionPlan | null>;
-  /** 原子提交 Composer 返回的 canonical 压缩计划。 */
-  commit_plan: (plan: SessionCompactionPlan) => Promise<void>;
-  /** 尽力记录压缩错误，不得覆盖领域结果。 */
-  log_error: (error_message: string) => Promise<void>;
-}
-
-/** 执行并收口一次统一 Session 历史压缩。 */
-export async function run_session_history_compaction(
-  options: RunSessionHistoryCompactionOptions,
-): ReturnType<SessionCompactHistory> {
-  try {
-    const plan = await options.create_plan();
-    if (!plan) return { compacted: false, reason: "nothing_to_compact" };
-    await options.commit_plan(plan);
-    return { compacted: true };
-  } catch (error) {
-    const error_message = error instanceof Error ? error.message : String(error);
-    try {
-      await options.log_error(error_message);
-    } catch {
-      // 关键点（中文）：日志失败不能覆盖稳定的压缩领域结果。
-    }
-    return {
-      compacted: false,
-      reason: "compact_failed",
-      error: error_message,
-    };
-  }
-}

package/src/types/agent/RemoteAgentOptions.ts

@@ -1,29 +0,0 @@
-/**
- * RemoteAgent 构造类型。
- *
- * 关键点（中文）
- * - RemoteAgent 只关心远程访问地址与可选鉴权 token。
- * - HTTP 鉴权与 RPC 本机直连语义在 transport 层实现。
- */
-
-/**
- * 远程 Agent 构造参数。
- */
-export interface RemoteAgentOptions {
-  /**
-   * 远程 agent 访问地址。
-   *
-   * 例如：`https://city.example.com/agents/lucas`、`http://127.0.0.1:5314/agents/lucas`
-   * 或 `rpc://127.0.0.1:15314/lucas`
-   */
-  url: string;
-
-  /**
-   * 访问远程 HTTP Agent 时使用的 Bearer token。
-   *
-   * 关键点（中文）
-   * - 仅 `http://` / `https://` transport 会携带该 token。
-   * - `rpc://` 是本机内部直连通道，不读取也不发送 token。
-   */
-  token?: string;
-}

package/src/types/agent/RemoteAgentPluginAction.ts

@@ -1,52 +0,0 @@
-/**
- * RemoteAgent plugin action 类型。
- *
- * 关键点（中文）
- * - RemoteAgent 是远程 runtime 的瘦客户端，因此这里只描述远程调用协议。
- * - 业务 action 的具体 payload 与 data 由目标 plugin 自己定义。
- */
-
-import type { JsonValue } from "@/types/common/Json.js";
-import type { PluginActionResult } from "@/types/plugin/PluginAction.js";
-
-/**
- * RemoteAgent 远程 plugin action 调用输入。
- */
-export interface RemoteAgentPluginActionInput {
-  /**
-   * 目标 plugin 名称。
-   *
-   * 示例：`shell`、`chat`、`task`。
-   */
-  plugin: string;
-
-  /**
-   * 目标 action 名称。
-   *
-   * 示例：`approve`、`deny`、`send`。
-   */
-  action: string;
-
-  /**
-   * 传给目标 action 的 JSON payload。
-   *
-   * shell approval 示例：`{ "approvalId": "ap_xxx" }`。
-   */
-  payload?: JsonValue;
-}
-
-/**
- * RemoteAgent 远程 plugin action 调用结果。
- */
-export type RemoteAgentPluginActionResult =
-  PluginActionResult<JsonValue> & {
-    /**
-     * Runtime 回传的 plugin 名称。
-     */
-    plugin_name?: string;
-
-    /**
-     * Runtime 回传的 action 名称。
-     */
-    action_name?: string;
-  };

package/src/types/agent/WorkspaceEntryOptions.ts

@@ -1,18 +0,0 @@
-/**
- * WorkspaceEntry 装配参数。
- *
- * WorkspaceEntry 只表达 Agent 已进入某个 Workspace，不拥有 Agent 身份或 Plugin
- * 定义。Workspace 资源的生命周期在离开时由该作用域统一关闭。
- */
-
-import type { Agent } from "@/agent/Agent.js";
-import type { WorkspaceBase } from "@downcity/workspace";
-
-/** Agent 进入 Workspace 时使用的内部装配参数。 */
-export interface WorkspaceEntryOptions {
-  /** 拥有当前作用域的 Agent。 */
-  agent: Agent;
-
-  /** 当前进入的项目资源容器。 */
-  workspace: WorkspaceBase;
-}

package/src/types/common/Json.ts

@@ -1,34 +0,0 @@
-/**
- * JSON 通用类型定义。
- *
- * 关键点（中文）
- * - 用于约束跨模块传递的可序列化数据结构。
- * - 避免在业务代码中使用宽泛断言，统一采用明确 JSON 类型。
- */
-
-/**
- * JSON 原子值。
- *
- * 说明（中文）
- * - 对应 JSON 规范里的不可再展开标量值。
- */
-export type JsonPrimitive = string | number | boolean | null;
-
-/**
- * 任意 JSON 值。
- *
- * 说明（中文）
- * - 可为标量、对象或数组。
- */
-export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
-
-/**
- * JSON 对象。
- *
- * 说明（中文）
- * - key 固定为字符串。
- * - value 继续递归约束为 `JsonValue`。
- */
-export type JsonObject = {
-  [key: string]: JsonValue;
-};

package/src/types/common/Template.ts

@@ -1,9 +0,0 @@
-/**
- * 字符串模板变量类型定义。
- *
- * 职责说明（中文）
- * - 统一描述 `{{variable}}` 模板渲染时的变量映射结构。
- * - 供 init 与 runtime prompt 渲染等场景复用。
- */
-
-export type TemplateVariableMap = Record<string, string>;

package/src/types/plugin/AgentPluginContext.ts

@@ -1,30 +0,0 @@
-/**
- * AgentPluginContext：Plugin 在 Agent 级生命周期中可访问的最小能力。
- *
- * 边界说明（中文）
- * - 该上下文不包含 Workspace，避免 Agent 级资源意外绑定第一个项目。
- * - 该上下文不暴露完整 City，只暴露宿主明确注入的 Embassy 能力。
- * - Plugin 是否需要 Agent 级生命周期，由 Plugin 自己是否实现 start/stop 决定。
- */
-
-import type { Logger } from "@/utils/logger/Logger.js";
-import type { PluginWebServices } from "@/types/plugin/PluginServices.js";
-import type { Embassy } from "@downcity/federation";
-
-/** Plugin 的 Agent 级生命周期上下文。 */
-export interface AgentPluginContext {
-  /** 当前 Agent 的稳定标识。 */
-  readonly agent_id: string;
-
-  /** 当前 Agent 的全局日志器，不绑定任何 Workspace 文件系统。 */
-  readonly logger: Logger;
-
-  /** 当前 Agent 持有的 Web 搜索与文档能力。 */
-  readonly web?: PluginWebServices;
-
-  /** City 注入的 Embassy 能力；Agent 未加入 City 时为空。 */
-  readonly embassy?: Embassy;
-
-  /** 动态读取当前 Agent 静态指令的只读快照。 */
-  readonly instructions: readonly string[];
-}