@downcity/agent 1.1.438 → 1.1.446

package/src/executor/types/SessionLoop.ts

@@ -1,69 +0,0 @@
-/**
- * Session tool-loop 决策相关类型。
- *
- * 关键点（中文）
- * - 这里只描述“是否继续下一轮”的纯决策输入/输出。
- * - 不携带 runtime 实例，方便在测试中直接做纯函数验证。
- */
-
-/**
- * 单轮 loop 决策输入。
- */
-export interface SessionLoopDecisionInput {
-  /**
-   * 当前 step 是否检测到了不完整响应。
-   */
-  hasIncompleteResponse: boolean;
-
-  /**
-   * 当前已经执行过多少次不完整响应恢复。
-   */
-  incompleteRecoveryCount: number;
-
-  /**
-   * 允许执行的不完整响应恢复上限。
-   */
-  maxIncompleteRecoveries: number;
-
-  /**
-   * 当前 step 实际产出的工具调用数量。
-   */
-  toolCallCount: number;
-}
-
-/**
- * 单轮 loop 决策结果。
- */
-export interface SessionLoopDecision {
-  /**
-   * 本轮命中的主决策类型。
-   */
-  kind:
-    | "recover_incomplete"
-    | "continue_for_tool_calls"
-    | "stop";
-
-  /**
-   * 是否因为工具调用而继续下一轮。
-   */
-  continueForToolCalls: boolean;
-
-  /**
-   * 是否因为不完整响应恢复而继续下一轮。
-   */
-  continueForIncompleteRecovery: boolean;
-}
-
-/**
- * stop 分支上的尾部消息续跑判定输入。
- *
- * 关键点（中文）
- * - 用于处理“最后一个 step 结束后，恰好又有新的 user 消息写入”的窗口。
- * - 这里只关心是否真的合并到了新增 user message，不关心消息内容细节。
- */
-export interface SessionTailMergeContinuationInput {
-  /**
-   * stop 前最后一次 tail merge 实际合并到的 user message 数量。
-   */
-  mergedUserMessageCount: number;
-}

package/src/executor/types/SessionPrompts.ts

@@ -1,14 +0,0 @@
-/**
- * SessionSystemMessage：Session 运行阶段使用的 system message。
- *
- * 关键点（中文）
- * - 该类型属于 Downcity Session，不依赖第三方 Provider。
- */
-
-/** Session system 消息。 */
-export interface SessionSystemMessage {
-  /** 消息角色固定为 system。 */
-  role: "system";
-  /** 当前 system block 的文本内容。 */
-  content: string;
-}

package/src/session/DefaultSessionComposer.ts

@@ -1,123 +0,0 @@
-/**
- * 默认 Session Composer。
- *
- * 负责把 Session 运行快照与 Context Policy 结果组装为最终模型输入。
- */
-
-import { build_session_system_blocks } from "@/session/SessionSystem.js";
-import type {
-  SessionComposer,
-  SessionComposeInput,
-  SessionStepInput,
-} from "@/types/session/SessionComposer.js";
-import type { SessionContextPolicy } from "@/types/session/SessionContextPolicy.js";
-import { AdaptivePartContextPolicy } from "@/session/composer/policies/AdaptivePartContextPolicy.js";
-import type { SessionHookContextBlock } from "@downcity/type";
-import type { ModelMessage } from "@downcity/type";
-
-/** 把低权限 Plugin 内容渲染为与用户原文分离的模型参考区。 */
-function render_plugin_context_blocks(
-  blocks: readonly SessionHookContextBlock[],
-): string {
-  return blocks.map((block) => [
-    `<extension-context extension="${escape_xml_attribute(block.source_plugin)}" name="${escape_xml_attribute(block.name)}" trust="reference">`,
-    block.content,
-    "</extension-context>",
-  ].join("\n")).join("\n\n");
-}
-
-/** 转义模型上下文标签属性，避免 Plugin 名称破坏边界。 */
-function escape_xml_attribute(value: string): string {
-  return value
-    .replaceAll("&", "&amp;")
-    .replaceAll('"', "&quot;")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;");
-}
-
-/** 只修改模型消息副本，把动态参考信息前置到当前最后一条 User Message。 */
-function inject_plugin_context(
-  messages: ModelMessage[],
-  blocks: readonly SessionHookContextBlock[],
-): ModelMessage[] {
-  if (blocks.length === 0) return messages;
-  for (let index = messages.length - 1; index >= 0; index -= 1) {
-    const message = messages[index];
-    if (!message || message.role !== "user") continue;
-    messages[index] = {
-      ...message,
-      content: [{ type: "text", text: render_plugin_context_blocks(blocks) }, ...message.content],
-    };
-    break;
-  }
-  return messages;
-}
-
-/** 默认 Session 执行策略。 */
-export class DefaultSessionComposer implements SessionComposer {
-  readonly name = "default_session";
-
-  /** 当前 Composer 使用的上下文策略。 */
-  private readonly context_policy: SessionContextPolicy;
-
-  constructor(options?: {
-    /** 生成模型历史的上下文策略。 */
-    context_policy?: SessionContextPolicy;
-  }) {
-    this.context_policy = options?.context_policy || new AdaptivePartContextPolicy();
-  }
-
-  /** 初始化内部 Context Policy 的派生 schema。 */
-  async initialize(input: Parameters<SessionComposer["initialize"]>[0]): Promise<void> {
-    await this.context_policy.initialize({
-      storage: input.storage.composer_storage(this.context_policy.name),
-    });
-  }
-
-  /** 组装当前 Step 的 system、history 与 tools。 */
-  async compose(input: SessionComposeInput): Promise<SessionStepInput> {
-    const system_blocks = await build_session_system_blocks({
-      agent_id: input.session.agent_id,
-      project_root: input.session.project_root,
-      session_id: input.session.session_id,
-      created_at: input.session.created_at,
-      timezone: input.session.timezone,
-      get_instruction_system_blocks: () => [
-        ...(input.state.instruction_system_blocks ?? []),
-      ],
-      get_managed_plugin_system_blocks: async () => [
-        ...(input.state.managed_plugin_system_blocks ?? []),
-      ],
-      get_plugin_system_blocks: async () => [
-        ...(input.state.plugin_system_blocks ?? []),
-      ],
-    });
-
-    const context = await this.context_policy.resolve({
-      storage: input.storage.composer_storage(this.context_policy.name),
-      project_root: input.session.project_root,
-    });
-    system_blocks.push(...(context.system_blocks ?? []));
-    return {
-      system: system_blocks.map((block) => ({
-        role: "system" as const,
-        content: block.content,
-      })),
-      system_blocks,
-      messages: inject_plugin_context(context.messages, input.state.plugin_context_blocks ?? []),
-      tools: { ...input.state.tools },
-      context_diagnostics: context.diagnostics,
-    };
-  }
-
-  /** 把上下文恢复委托给当前 Policy。 */
-  async recover_context(input: Parameters<SessionComposer["recover_context"]>[0]): Promise<boolean> {
-    return await this.context_policy.recover({
-      storage: input.storage.composer_storage(this.context_policy.name),
-      project_root: input.session.project_root,
-      reason: input.reason,
-      model: input.model,
-      on_model_request_failure: input.on_model_request_failure,
-    });
-  }
-}

package/src/session/SessionComposition.ts

@@ -1,370 +0,0 @@
-/**
- * Session system 快照与模型输入组装边界。
- *
- * 关键点（中文）
- * - 拥有 Session 创建后固定的 system snapshot；env、Tool 与 Hook 在 Step 检查点读取。
- * - Composer 只读取本对象生成的不可变输入，不接触 Session 持久化编排。
- * - Plugin Hook 失败只降级对应扩展内容，不改变 canonical Message。
- */
-
-import type { JsonValue } from "@downcity/type";
-import type {
-  AgentSessionSystemBlock,
-  AgentSessionSystemSnapshot,
-} from "@/types/agent/SessionTypes.js";
-import type {
-  SessionComposeIdentity,
-  SessionComposeInput,
-  SessionStepInput,
-} from "@/types/session/SessionComposer.js";
-import type {
-  SessionHookContextBlock,
-  SessionTurnContextHookValue,
-} from "@downcity/type";
-import type { SessionTurnContext } from "@/types/executor/SessionTurnContext.js";
-import type { SessionCompositionOptions } from "@/types/session/SessionComposition.js";
-import { create_session_hook_context } from "@/session/runtime/SessionTurnContext.js";
-import { SESSION_HOOK_POINTS } from "@/session/SessionHookPoints.js";
-import { resolve_session_plugin_system_blocks } from "@/session/SessionSystem.js";
-
-/** 管理当前 Session 的 system snapshot 与 Step 组装输入。 */
-export class SessionComposition {
-  private readonly options: SessionCompositionOptions;
-  private effective_instruction_blocks: AgentSessionSystemBlock[];
-  /** 当前 Session 首次生成后固定的完整 system snapshot。 */
-  private snapshot_blocks: AgentSessionSystemBlock[] | null = null;
-  /** 当前 Session instruction 的一次性恢复任务。 */
-  private initialize_promise: Promise<void> | null = null;
-  /** 串行化 snapshot / syncshot 对 system 与 instruction.md 的修改。 */
-  private mutation_chain: Promise<void> = Promise.resolve();
-
-  constructor(options: SessionCompositionOptions) {
-    this.options = options;
-    this.effective_instruction_blocks = options.instruction_system_blocks.map(
-      (block) => ({ ...block }),
-    );
-  }
-
-  /** 恢复显式固化的完整 system snapshot。 */
-  async initialize(): Promise<void> {
-    if (!this.initialize_promise) {
-      this.initialize_promise = (async () => {
-        await this.options.store.initialize();
-        await this.options.composer.initialize({ storage: this.options.store });
-        const persisted_instruction = await this.options.store.read_instruction();
-        if (persisted_instruction === null) return;
-
-        const instruction = persisted_instruction.trim();
-        this.snapshot_blocks = instruction
-          ? [{
-              source: "instruction" as const,
-              name: "snapshot",
-              content: instruction,
-            }]
-          : [];
-        const stable_system_blocks = this.effective_instruction_blocks
-          .filter((block) => block.source !== "instruction")
-          .map((block) => ({ ...block }));
-        this.effective_instruction_blocks = [
-          ...(instruction
-            ? [{
-                source: "instruction" as const,
-                name: "agent",
-                content: instruction,
-              }]
-            : []),
-          ...stable_system_blocks,
-        ];
-      })();
-    }
-    const initialize_promise = this.initialize_promise;
-    try {
-      await initialize_promise;
-    } catch (error) {
-      if (this.initialize_promise === initialize_promise) {
-        this.initialize_promise = null;
-      }
-      throw error;
-    }
-  }
-
-  /** 把当前完整 system 显式固化到 instruction.md。 */
-  async snapshot(): Promise<void> {
-    await this.run_mutation(async () => {
-      const system_snapshot = await this.read();
-      await this.write_snapshot(system_snapshot.blocks);
-    });
-  }
-
-  /** 使用 Agent 当前 instruction 与 Plugin 重新生成完整 system。 */
-  async syncshot(): Promise<void> {
-    await this.run_mutation(async () => {
-      await this.initialize();
-      const should_persist = await this.options.store.has_instruction();
-      const composed = await this.options.composer.compose(
-        await this.create_compose_input(undefined, 0, true),
-      );
-      const next_blocks = resolve_composed_system_blocks(composed);
-
-      if (should_persist) await this.write_snapshot(next_blocks);
-      this.effective_instruction_blocks =
-        this.options.get_instruction_system_blocks().map((block) => ({ ...block }));
-      this.snapshot_blocks = next_blocks;
-    });
-  }
-
-  /** 读取当前 Session 生效的完整 system 快照。 */
-  async read(): Promise<AgentSessionSystemSnapshot> {
-    await this.initialize();
-    const composed = await this.compose_for_view();
-    return {
-      session_id: this.options.session_id,
-      session: {
-        agent_id: this.options.agent_id,
-        session_id: this.options.session_id,
-        project_root: this.options.workspace_path,
-        created_at: new Date(this.options.get_created_at()).toISOString(),
-        timezone: this.options.get_timezone(),
-      },
-      blocks: resolve_composed_system_blocks(composed),
-    };
-  }
-
-  /** 返回当前 Session 捕获的 instruction blocks 副本。 */
-  instruction_blocks(): AgentSessionSystemBlock[] {
-    return this.effective_instruction_blocks.map((block) => ({ ...block }));
-  }
-
-  /** 创建 Composer 共用的稳定 Session 身份快照。 */
-  compose_identity(): SessionComposeIdentity {
-    return {
-      agent_id: this.options.agent_id,
-      session_id: this.options.session_id,
-      project_root: this.options.workspace_path,
-      created_at: this.options.get_created_at(),
-      timezone: this.options.get_timezone(),
-    };
-  }
-
-  /** 为 Composer 创建当前 Step 的只读 Session 快照。 */
-  async create_compose_input(
-    turn_context: SessionTurnContext | undefined,
-    retry_count: number,
-    refresh_system = false,
-  ): Promise<SessionComposeInput> {
-    const instruction_system_blocks = refresh_system
-      ? this.options.get_instruction_system_blocks().map((block) => ({ ...block }))
-      : this.instruction_blocks();
-    const workspace_env = Object.freeze({ ...this.options.get_workspace_env() });
-    // Plugin system 参与 Compose，必须先看到当前检查点已确定的 env 与 instruction。
-    turn_context?.step.commit({
-      workspace_env,
-      agent_systems: instruction_system_blocks.map((block) => block.content),
-    });
-    const hook_context =
-      turn_context?.step.hook_context() ||
-      create_session_hook_context({
-        session_id: this.options.session_id,
-        session_origin: this.options.session_origin,
-        project_root: this.options.workspace_path,
-        workspace_env,
-        agent_systems: this.effective_instruction_blocks.map(
-          (block) => block.content,
-        ),
-      });
-    const plugin_runtime = refresh_system
-      ? this.options.get_hooks()
-      : turn_context?.step.hooks || this.options.get_hooks();
-    const resolved_plugin_system_blocks = this.snapshot_blocks && !refresh_system
-      ? []
-      : await resolve_session_plugin_system_blocks({
-          session_id: this.options.session_id,
-          ...(turn_context?.session.turn_id
-            ? { turn_id: turn_context.session.turn_id }
-            : {}),
-          hooks: plugin_runtime,
-          context: hook_context,
-          on_error: async (error) => await this.log_plugin_hook_warning(
-            SESSION_HOOK_POINTS.system_context,
-            error,
-            turn_context?.session.turn_id,
-          ),
-        });
-    const plugin_context_blocks = turn_context
-      ? await turn_context.step.resolve_plugin_context_blocks(async () => {
-          const hooks = turn_context.step.hooks;
-          if (!hooks) return [];
-          const value: SessionTurnContextHookValue = {
-            session_id: this.options.session_id,
-            turn_id: turn_context.session.turn_id,
-            user_messages: turn_context.input.user_messages().map((message) => ({
-                message_id: message.message_id,
-                text: message.parts
-                  .filter((part) => part.type === "text")
-                  .map((part) => part.text)
-                  .join("\n"),
-              })),
-            blocks: [],
-          };
-          try {
-            const output = await hooks.pipeline(
-              SESSION_HOOK_POINTS.turn_context,
-              value as unknown as JsonValue,
-            ) as unknown as SessionTurnContextHookValue;
-            return normalize_plugin_context_blocks(output?.blocks);
-          } catch (error) {
-            await this.log_plugin_hook_warning(
-              SESSION_HOOK_POINTS.turn_context,
-              error,
-              turn_context.session.turn_id,
-            );
-            return [];
-          }
-        })
-      : [];
-    return {
-      session: this.compose_identity(),
-      state: {
-        model: this.options.get_model(),
-        model_context_window: this.options.get_model_context_window(),
-        env: workspace_env,
-        systems: Object.freeze(
-          instruction_system_blocks.map((block) => block.content),
-        ),
-        tools: Object.freeze({ ...this.options.get_tools() }),
-        instruction_system_blocks,
-        managed_plugin_system_blocks:
-          this.snapshot_blocks && !refresh_system
-            ? []
-            : await this.options.get_managed_plugin_system_blocks(),
-        plugin_system_blocks: resolved_plugin_system_blocks,
-        plugin_context_blocks,
-      },
-      storage: this.options.store,
-      turn: {
-        ...(turn_context ? { turn_id: turn_context.session.turn_id } : {}),
-        retry_count,
-      },
-    };
-  }
-
-  /** 固定或应用当前 Session 的 system snapshot。 */
-  apply_snapshot(input: SessionStepInput): SessionStepInput {
-    if (!this.snapshot_blocks) {
-      this.snapshot_blocks = resolve_composed_system_blocks(input);
-    }
-    return {
-      ...input,
-      system: this.snapshot_blocks.map((block) => ({
-        role: "system" as const,
-        content: block.content,
-      })),
-      system_blocks: this.snapshot_blocks.map((block) => ({ ...block })),
-    };
-  }
-
-  /** Plugin 上下文 Hook 失败只降级当前扩展内容。 */
-  private async log_plugin_hook_warning(
-    point_name: string,
-    error: unknown,
-    turn_id?: string,
-  ): Promise<void> {
-    try {
-      await this.options.logger.log("warn", "[agent] session plugin hook failed", {
-        session_id: this.options.session_id,
-        ...(turn_id ? { turn_id } : {}),
-        point_name,
-        error: error instanceof Error ? error.message : String(error),
-      });
-    } catch {
-      // Plugin 已经降级，日志失败不能反向阻断 Session。
-    }
-  }
-
-  /** 使用统一 Composer 生成只读 system/history 查询结果。 */
-  private async compose_for_view(): Promise<SessionStepInput> {
-    const composed = await this.options.composer.compose(
-      await this.create_compose_input(undefined, 0),
-    );
-    return this.apply_snapshot(composed);
-  }
-
-  /** 串行执行一次 Session system 修改。 */
-  private async run_mutation(operation: () => Promise<void>): Promise<void> {
-    const next = this.mutation_chain.then(operation, operation);
-    this.mutation_chain = next.catch(() => undefined);
-    await next;
-  }
-
-  /** 把指定完整 system blocks 原子写入 instruction.md。 */
-  private async write_snapshot(
-    blocks: readonly AgentSessionSystemBlock[],
-  ): Promise<void> {
-    await this.options.store.write_instruction(
-      blocks.map((block) => block.content).join("\n\n"),
-    );
-  }
-}
-
-/** 把 Turn pipeline 输出限制为低权限动态参考内容块。 */
-function normalize_plugin_context_blocks(input: unknown): SessionHookContextBlock[] {
-  if (!Array.isArray(input)) return [];
-  return input.flatMap((item) => {
-    if (!item || typeof item !== "object" || Array.isArray(item)) return [];
-    const record = item as Record<string, unknown>;
-    const source_plugin = String(record.source_plugin || "").trim();
-    const name = String(record.name || "").trim();
-    const content = String(record.content || "").trim();
-    if (
-      !source_plugin ||
-      !name ||
-      !content ||
-      record.trust_level !== "reference"
-    ) return [];
-    const citations = Array.isArray(record.citations)
-      ? record.citations
-          .map((citation) => String(citation || "").trim())
-          .filter(Boolean)
-      : [];
-    const version = String(record.version || "").trim();
-    return [{
-      source_plugin,
-      name,
-      content,
-      trust_level: "reference" as const,
-      ...(citations.length > 0 ? { citations } : {}),
-      ...(version ? { version } : {}),
-    }];
-  });
-}
-
-/** 把自定义 Composer 的 system content 转为可展示文本。 */
-function stringify_system_content(content: unknown): string {
-  if (typeof content === "string") return content.trim();
-  if (content === null || content === undefined) return "";
-  try {
-    return JSON.stringify(content);
-  } catch {
-    return String(content || "").trim();
-  }
-}
-
-/** 以实际模型输入为准，保留仍与其一致的 system block 来源信息。 */
-function resolve_composed_system_blocks(
-  composed: SessionStepInput,
-): AgentSessionSystemBlock[] {
-  const declared_blocks = composed.system_blocks || [];
-  return composed.system.flatMap((message, index) => {
-    const content = stringify_system_content(message.content);
-    if (!content) return [];
-    const declared = declared_blocks[index];
-    if (declared && declared.content.trim() === content) {
-      return [{ ...declared, content }];
-    }
-    return [{
-      source: "session" as const,
-      name: `custom_system:${index + 1}`,
-      content,
-    }];
-  });
-}

package/src/session/SessionHookPoints.ts

@@ -1,17 +0,0 @@
-/**
- * Session 公开的稳定 Hook 检查点。
- *
- * 检查点由 Session 定义和触发，City Plugin 只选择是否注册处理器。
- */
-
-/** Session 运行时的 Hook point 目录。 */
-export const SESSION_HOOK_POINTS = Object.freeze({
-  /** 建立 Session system snapshot 时允许 Hook 追加命名 blocks。 */
-  system_context: "session.system_context",
-
-  /** 当前 Turn 首次组装模型输入时允许 Hook 追加低权限参考 blocks。 */
-  turn_context: "session.turn_context",
-
-  /** canonical Turn 完成提交后通知 Hook 执行副作用。 */
-  turn_committed: "session.turn_committed",
-} as const);

package/src/session/SessionHooks.ts

@@ -1,85 +0,0 @@
-/**
- * Session Hook 运行类。
- *
- * SessionHooks 是 Agent 对 Hook 的唯一认识。默认实例不产生任何行为；City 等上层
- * 组合根可以注入处理函数，并在 open() 时为单个 Step 捕获稳定作用域。
- */
-
-import type {
-  JsonValue,
-  SessionHookContext,
-  SessionHookHandlers,
-  SessionHookRuntime,
-  SessionHookScopeRuntime,
-  SessionSystemBlock,
-} from "@downcity/type";
-
-/** 单个 Session Step 捕获的稳定 Hook 作用域。 */
-export class SessionHookScope implements SessionHookScopeRuntime {
-  /** 当前作用域是否已经关闭。 */
-  private closed = false;
-
-  constructor(private readonly handlers: SessionHookHandlers = {}) {}
-
-  /** 读取当前作用域提供的 system blocks。 */
-  async system_blocks(context?: SessionHookContext): Promise<SessionSystemBlock[]> {
-    return await this.handlers.system_blocks?.(context) ?? [];
-  }
-
-  /** 运行一个可转换值的 Hook。 */
-  async pipeline<TValue = JsonValue>(point_name: string, value: TValue): Promise<TValue> {
-    return this.handlers.pipeline
-      ? await this.handlers.pipeline(point_name, value)
-      : value;
-  }
-
-  /** 运行一个只产生副作用的 Hook。 */
-  async effect<TValue = JsonValue>(point_name: string, value: TValue): Promise<void> {
-    await this.handlers.effect?.(point_name, value);
-  }
-
-  /** 幂等关闭当前作用域。 */
-  async close(): Promise<void> {
-    if (this.closed) return;
-    this.closed = true;
-    await this.handlers.close?.();
-  }
-}
-
-/** Session 级 Hook 集合。 */
-export class SessionHooks implements SessionHookRuntime {
-  constructor(private readonly handlers: SessionHookHandlers = {}) {}
-
-  /** 读取当前配置提供的 system blocks。 */
-  async system_blocks(context?: SessionHookContext): Promise<SessionSystemBlock[]> {
-    return await this.handlers.system_blocks?.(context) ?? [];
-  }
-
-  /** 运行一个可转换值的 Hook。 */
-  async pipeline<TValue = JsonValue>(point_name: string, value: TValue): Promise<TValue> {
-    return this.handlers.pipeline
-      ? await this.handlers.pipeline(point_name, value)
-      : value;
-  }
-
-  /** 运行一个只产生副作用的 Hook。 */
-  async effect<TValue = JsonValue>(point_name: string, value: TValue): Promise<void> {
-    await this.handlers.effect?.(point_name, value);
-  }
-
-  /** 为下一个 Session Step 打开稳定 Hook 作用域。 */
-  async open(): Promise<SessionHookScope> {
-    const scoped_handlers = await this.handlers.open?.();
-    if (scoped_handlers) return new SessionHookScope(scoped_handlers);
-    return new SessionHookScope({
-      system_blocks: async (context) => await this.system_blocks(context),
-      pipeline: async <TValue>(point_name: string, value: TValue) =>
-        await this.pipeline(point_name, value),
-      effect: async <TValue>(point_name: string, value: TValue) =>
-        await this.effect(point_name, value),
-    });
-  }
-}
-
-/** 不提供任何 Hook 的默认实例。 */
-export const EMPTY_SESSION_HOOKS = new SessionHooks();