@downcity/agent 1.1.228 → 1.1.232

package/src/types/agent/SessionTypes.ts

@@ -90,6 +90,8 @@ export interface AgentSessionConfigSnapshot {
   modelLabel?: string;
   /** 当前 session 绑定的稳定模型 ID。 */
   modelId?: string;
+  /** 当前模型支持的总上下文窗口长度，单位为 token。 */
+  model_context_window?: number;
 }
 
 /**
@@ -305,14 +307,6 @@ export interface AgentSessionRecordsInput {
   limit?: number;
   /** 分页游标。 */
   cursor?: string;
-  /**
-   * 要读取的 compact archive 层 ID。
-   *
-   * 说明（中文）
-   * - 省略时读取当前 `messages.jsonl`。
-   * - 传入时读取 `messages/archive/<archive_id>.json` 中保存的上一层历史。
-   */
-  archive_id?: string;
   /**
    * 返回顺序。
    *
@@ -359,22 +353,6 @@ export interface AgentSessionRecordsPage {
   next_cursor?: string;
   /** 是否仍有更多数据。 */
   has_more: boolean;
-  /**
-   * 当前读取的 compact archive 层 ID。
-   *
-   * 说明（中文）
-   * - 省略表示当前页来自主历史 `messages.jsonl`。
-   * - 有值表示当前页来自指定 compact archive。
-   */
-  archive_id?: string;
-  /**
-   * 当前层更早一次 compact 对应的 archive ID。
-   *
-   * 关键点（中文）
-   * - compact summary 不会出现在 `items` 中。
-   * - 若当前层包含 compact summary，则这里暴露其 archive ID，供调用方继续 `session.records({ archive_id })`。
-   */
-  previous_archive_id?: string;
 }
 
 /**

package/src/types/executor/SessionRunContext.ts

@@ -18,6 +18,7 @@ import type {
 } from "@/executor/types/SessionRun.js";
 import type { SessionUserMessageV1 } from "@/executor/types/SessionRecords.js";
 import type { FileUIPart } from "ai";
+import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
 
 /**
  * 单次 session run 的运行上下文。
@@ -55,6 +56,30 @@ export interface SessionRunContext {
    */
   onStepCallback?: () => Promise<SessionUserMessageV1[]>;
 
+  /**
+   * 判断是否仍有等待并入下一模型 turn 的 steer prompt。
+   *
+   * 关键点（中文）
+   * - 只检查 prompt，不把单独的配置 mutation 当成继续调用模型的理由。
+   * - 真正的队列消费统一发生在 `onStepCallback`。
+   */
+  hasPendingStepInput?: () => boolean;
+
+  /**
+   * 当前模型 turn 实际使用的 Agent env。
+   *
+   * 关键点（中文）
+   * - 由 Session 配置队列在模型 turn 开始前更新。
+   * - tool/plugin 深层调用通过 run scope 读取，避免看到刚写入但尚未生效的 env。
+   */
+  agentEnv?: Readonly<Record<string, string>>;
+
+  /** 当前模型 turn 已提交生效的 Agent instruction 文本。 */
+  agentSystems?: readonly string[];
+
+  /** 当前模型 turn 捕获的 Plugin 执行视图。 */
+  agentPlugins?: AgentPluginExecutionRuntime;
+
   /**
    * assistant step 完成回调。
    *

package/src/types/plugin/PluginRuntime.ts

@@ -142,6 +142,33 @@ export interface AgentPlugins {
     pointName: string,
     value: TInput,
   ): Promise<TOutput>;
+
+}
+
+/**
+ * 单次模型 turn 可使用的 Plugin 能力视图。
+ */
+export interface AgentPluginExecutionRuntime {
+  /** 读取当前视图中的 plugin/action metadata。 */
+  read(params: {
+    /** Plugin 名称（可选）。 */
+    plugin?: string;
+    /** Action 名称（可选）。 */
+    action?: string;
+  }): PluginReadView | { plugins: PluginView[] };
+
+  /** 运行当前视图中捕获的 plugin action。 */
+  runAction(params: {
+    /** Plugin 名称。 */
+    plugin: string;
+    /** Action 名称。 */
+    action: string;
+    /** Action Payload（可选）。 */
+    payload?: JsonValue;
+  }): Promise<PluginActionResult<JsonValue>>;
+
+  /** 解析当前视图中捕获的 plugin system blocks。 */
+  systemBlocks(): Promise<AgentSessionSystemBlock[]>;
 }
 
 /**

package/src/types/runtime/agent/AgentContext.ts

@@ -34,6 +34,7 @@ import type {
 } from "@/types/session/SessionMutation.js";
 import type { SessionApprovalRuntimeEvent } from "@/types/session/SessionApproval.js";
 import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
+import { getSessionRunContext } from "@/executor/SessionRunScope.js";
 
 /**
  * 跨 plugin runtime 调用参数。
@@ -233,7 +234,7 @@ export interface AgentContextOptions {
    *
    * 关键点（中文）
    * - 必须是 Agent 持有的同一个 mutable 引用，不要克隆后再传入。
-   * - 通过 `agent.setEnv` / `agent.patchEnv` 原地更新会被本 context 立即感知。
+   * - Session 模型 turn 内优先读取队列已经提交的 effective env。
    */
   env: Record<string, string>;
   /** 当前生效的 system 文本集合。 */
@@ -267,10 +268,10 @@ export class AgentContext {
   readonly logger: Logger;
   /** 当前运行时已解析配置。 */
   readonly config: DowncityConfig;
-  /** 当前项目环境变量共享视图。 */
-  readonly env: Record<string, string>;
-  /** 当前生效的 system 文本集合。 */
-  readonly systems: string[];
+  /** 当前 Agent configured env 共享对象。 */
+  private readonly configured_env: Record<string, string>;
+  /** 当前 Agent configured system 文本。 */
+  private readonly configured_systems: string[];
   /** 当前可见的路径能力集合。 */
   readonly paths: AgentPathRuntime;
   /** 当前可见的 plugin 配置持久化能力集合。 */
@@ -289,8 +290,8 @@ export class AgentContext {
     this.rootPath = options.rootPath;
     this.logger = options.logger;
     this.config = options.config;
-    this.env = options.env;
-    this.systems = options.systems;
+    this.configured_env = options.env;
+    this.configured_systems = options.systems;
     this.paths = options.paths;
     this.pluginConfig = options.pluginConfig;
     this.pluginInstances = options.pluginInstances;
@@ -301,6 +302,30 @@ export class AgentContext {
     };
   }
 
+  /**
+   * 读取当前调用链可见的 Agent env。
+   *
+   * 关键点（中文）
+   * - 模型 turn 内优先返回统一输入队列已经提交的 effective env。
+   * - Session 运行外返回 Agent 配置 API 最近一次成功写入的 configured env。
+   */
+  get env(): Record<string, string> {
+    const effective_env = getSessionRunContext()?.agentEnv;
+    return effective_env
+      ? { ...effective_env }
+      : this.configured_env;
+  }
+
+  /**
+   * 读取当前调用链可见的 Agent instruction。
+   */
+  get systems(): string[] {
+    const effective_systems = getSessionRunContext()?.agentSystems;
+    return effective_systems
+      ? [...effective_systems]
+      : this.configured_systems;
+  }
+
   /**
    * 读取指定 sessionId 对应的 session 端口。
    *

package/src/types/session/SessionConfigMutation.ts

@@ -0,0 +1,78 @@
+/**
+ * Session 配置 Mutation 运行时类型。
+ *
+ * 关键点（中文）
+ * - 配置 API 负责把 configured state 修改成功后创建 mutation。
+ * - mutation 与 steer 共用 Session 输入队列，并在下一次模型 turn 开始前提交。
+ * - 这里只描述进程内提交协议，不属于持久化格式或公开 SDK 协议。
+ */
+
+import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
+
+/**
+ * 配置 Mutation 的归属作用域。
+ */
+export type SessionConfigMutationScope = "agent" | "session";
+
+/**
+ * 配置 Mutation 生效时的模型 turn 上下文。
+ */
+export interface SessionConfigMutationApplyContext {
+  /** 当前公开 Session turn 标识。 */
+  turn_id: string;
+
+  /** 当前 Session turn 内即将开始的模型 turn 序号。 */
+  model_turn_index: number;
+}
+
+/**
+ * 等待在下一次模型 turn 提交的配置 Mutation。
+ */
+export interface SessionRuntimeConfigMutation {
+  /** 当前配置修改的稳定唯一标识。 */
+  mutation_id: string;
+
+  /** 当前配置修改属于 Agent 还是 Session。 */
+  scope: SessionConfigMutationScope;
+
+  /**
+   * 把 configured state 提交为当前 Session 的 effective state。
+   *
+   * 关键点（中文）
+   * - 成功或失败的 action message 由具体配置实现负责写入。
+   * - 抛错只终止当前 mutation，不应让后续 mutation 静默丢失。
+   */
+  apply(context: SessionConfigMutationApplyContext): Promise<void>;
+}
+
+/**
+ * Agent configured state 广播给已有 Session 的配置修改。
+ */
+export type AgentSessionConfigMutation =
+  | {
+      /** 当前修改固定为 instruction。 */
+      type: "instruction";
+      /** 当前配置修改唯一标识。 */
+      mutation_id: string;
+      /** 下一模型 turn 使用的 instruction blocks。 */
+      instruction_blocks: AgentSessionSystemBlock[];
+    }
+  | {
+      /** 当前修改固定为 env。 */
+      type: "env";
+      /** 当前配置修改唯一标识。 */
+      mutation_id: string;
+      /** 下一模型 turn 使用的完整 Agent env。 */
+      env: Record<string, string>;
+    }
+  | {
+      /** 当前修改固定为 plugin registry。 */
+      type: "plugins";
+      /** 当前配置修改唯一标识。 */
+      mutation_id: string;
+      /** 当前 plugin 配置修改的用户可读标题。 */
+      title: string;
+      /** 下一模型 turn 使用的 Plugin 执行视图。 */
+      plugins: AgentPluginExecutionRuntime;
+    };

package/src/types/session/SessionLocalState.ts

@@ -18,6 +18,15 @@ export interface SessionLocalState {
    */
   sessionConfig: AgentSessionConfigSnapshot;
 
+  /**
+   * 当前模型 turn 实际使用的 Session 配置。
+   *
+   * 关键点（中文）
+   * - `sessionConfig` 是配置 API 最近一次成功写入的 configured state。
+   * - 该字段只在模型 turn 开始前由队列 mutation 更新。
+   */
+  effective_session_config: AgentSessionConfigSnapshot;
+
   /**
    * 当前 session 创建时间（毫秒时间戳）。
    */

package/src/types/session/SessionMessage.ts

@@ -228,26 +228,30 @@ export type SessionMessage =
 
 /** 读取 Session Message snapshot 的分页输入。 */
 export interface ListSessionMessagesInput {
-  /** 单页数量上限。 */
-  limit?: number;
-  /** 上一页返回的透明游标。 */
-  cursor?: string;
-  /** 只返回 sequence 严格小于该值的 Message，供向前翻页。 */
+  /**
+   * 返回该 sequence 之前的最近一个完整历史 Segment。
+   *
+   * 必须是正整数；省略时直接返回 Active 中的全部 Message。
+   */
   before_sequence?: number;
   /** 是否包含 internal Message。 */
   include_internal?: boolean;
-  /** 只返回不大于该 sequence 的 Message。 */
-  through_sequence?: number;
 }
 
 /** Session Message snapshot 分页结果。 */
 export interface SessionMessagePage {
-  /** 当前页按 sequence 升序排列的 Message。 */
+  /** 当前 Active 或 Segment 中按 sequence 升序排列的 Message。 */
   items: SessionMessage[];
-  /** 当前过滤条件下的 Message 总数。 */
+  /** 当前 Session 已分配的真实 Message 总数。 */
   total: number;
-  /** 下一页透明游标。 */
-  next_cursor?: string;
-  /** 是否仍有更多 Message。 */
+  /** 当前结果来自 Active 还是已关闭 Segment。 */
+  source: "active" | "segment";
+  /** 当前结果覆盖的第一条真实 Message sequence。 */
+  start_sequence?: number;
+  /** 当前结果覆盖的最后一条真实 Message sequence。 */
+  end_sequence?: number;
+  /** 继续向前读取时应作为 before_sequence 传入的边界。 */
+  next_before_sequence?: number;
+  /** 当前结果之前是否仍有更早 Segment。 */
   has_more: boolean;
 }

package/src/types/session/SessionMutation.ts

@@ -1,7 +1,7 @@
 /**
  * Session 的统一实时 Mutation 协议。
  *
- * Mutation 描述订阅之后发生的状态变化，不等同于 messages.jsonl 持久化格式。
+ * Mutation 描述订阅之后发生的状态变化，不等同于 Active/Segment 持久化格式。
  */
 
 import type { SessionAssistantMessagePart, SessionMessage } from "@/types/session/SessionMessage.js";

package/src/types/session/SessionOptions.ts

@@ -11,6 +11,8 @@ import type { Tool } from "ai";
 import type { AgentSession } from "@/types/agent/SessionActor.js";
 import type { SessionPort } from "@/types/runtime/agent/AgentContext.js";
 import type { AgentSessionSystemBlock } from "@/types/agent/SessionTypes.js";
+import type { AgentPluginExecutionRuntime } from "@/types/plugin/PluginRuntime.js";
+import type { AgentSessionConfigMutation } from "@/types/session/SessionConfigMutation.js";
 import type { SessionComposerOptions } from "@/types/session/SessionComposerOptions.js";
 import type { Logger } from "@/utils/logger/Logger.js";
 import type { AgentModel } from "@/model/CityModelAdapter.js";
@@ -40,6 +42,13 @@ export interface AgentManagedSession extends AgentSession {
    * 返回当前 session 是否正在执行。
    */
   isExecuting(): boolean;
+
+  /**
+   * 把 Agent configured state 修改加入当前 Session 的统一输入队列。
+   */
+  enqueue_agent_config(
+    mutation: AgentSessionConfigMutation,
+  ): void;
 }
 
 /**
@@ -76,6 +85,18 @@ export interface SessionOptions {
    */
   getInstructionSystemBlocks: () => AgentSessionSystemBlock[];
 
+  /**
+   * 读取当前 Agent configured env。
+   *
+   * 关键点（中文）
+   * - Session 创建时用它建立初始 effective env。
+   * - 后续 Agent env 修改通过 Session 配置 mutation 在模型 turn 边界提交。
+   */
+  getAgentEnv: () => Record<string, string>;
+
+  /** 创建当前 Agent configured plugin 的模型 turn 执行视图。 */
+  get_agent_plugins: () => AgentPluginExecutionRuntime;
+
   /**
    * 读取当前 agent 显式注入的受托管 plugin system blocks。
    */

package/src/types/session/SessionSegment.ts

@@ -0,0 +1,62 @@
+/**
+ * Session Message 物理分段类型。
+ *
+ * Segment 保存一段连续的原始 Message，并在文件末尾保存覆盖到该段末尾的累计 Summary。
+ * Summary 只服务模型上下文，不占用 Session Message sequence。
+ */
+
+import type { SessionMessage } from "@/types/session/SessionMessage.js";
+
+/** 已关闭 Segment 的累计上下文摘要。 */
+export interface SessionSegmentSummary {
+  /** 记录类型固定为 summary，用于和原始 Message 行区分。 */
+  record_type: "summary";
+  /** 当前 Summary 所属 Session 标识。 */
+  session_id: string;
+  /** 当前 Summary 的稳定唯一标识。 */
+  summary_id: string;
+  /** 当前 Summary 已覆盖到的最后一条真实 Message sequence。 */
+  through_sequence: number;
+  /** 供下一轮模型直接使用的累计摘要文本。 */
+  text: string;
+  /** 当前 Summary 创建时间戳（ms）。 */
+  created_at: number;
+}
+
+/** 已关闭 Segment 的 sequence 范围与文件位置。 */
+export interface SessionSegmentRange {
+  /** Segment 内第一条真实 Message sequence。 */
+  start_sequence: number;
+  /** Segment 内最后一条真实 Message sequence。 */
+  end_sequence: number;
+  /** Segment JSONL 文件的绝对路径。 */
+  file_path: string;
+}
+
+/** 从一个已关闭 Segment 读取出的完整数据。 */
+export interface SessionSegmentSnapshot {
+  /** Segment 的 sequence 范围。 */
+  range: SessionSegmentRange;
+  /** Segment 中按 sequence 升序排列的原始 Message。 */
+  messages: SessionMessage[];
+  /** Segment 文件末尾的累计 Summary。 */
+  summary: SessionSegmentSummary;
+}
+
+/** 当前模型上下文所需的最小 Session 快照。 */
+export interface SessionContextSnapshot {
+  /** 最新已关闭 Segment 的累计 Summary；从未 Compact 时为空。 */
+  summary: SessionSegmentSummary | null;
+  /** Active 中上次 Compact 后产生的全部真实 Message。 */
+  messages: SessionMessage[];
+}
+
+/** Session 历史存储统计。 */
+export interface SessionMessageStorageStats {
+  /** 当前 Session 已分配的真实 Message 总数。 */
+  message_count: number;
+  /** Active 与所有 Segment 文件占用的总字节数。 */
+  history_bytes: number;
+  /** 当前最新真实 Message；空 Session 时为空。 */
+  latest_message: SessionMessage | null;
+}