@downcity/agent 1.1.408 → 1.1.437

package/src/index.ts

@@ -3,17 +3,19 @@
  *
  * 关键点（中文）
  * - 这是 agent 包核心运行时的稳定公开入口；可选 Tool 通过 `@downcity/agent/tools` 导出。
- * - 只导出 Agent、plugin 作者 API 与跨包协议类型。
- * - HTTP router、sandbox runner、内部 plugin runtime runner 等实现细节不从根入口暴露。
+ * - 只导出 Agent SDK 与必要的 Session 协议类型。
+ * - HTTP、RPC、Plugin、Workspace 与 Sandbox 实现不从根入口暴露。
  */
 
 // Agent 入口
 export { Agent } from "./agent/Agent.js";
 export { Group } from "./group/Group.js";
 export type {
+  DispatchAssignment,
   DispatchDecision,
-  DispatchNode,
-  DispatchResponseMode,
+  DispatchGroupProfile,
+  DispatchMemberProfile,
+  DispatchStage,
   DispatchTrigger,
   DispatchStrategy,
   AiDispatchStrategyOptions,
@@ -27,10 +29,9 @@ export type {
   GroupSessionStore,
 } from "./types/group/GroupSessionStore.js";
 export type {
-  GroupDispatchSessionDataStore,
   GroupDispatchTurnRecord,
   GroupDispatchTurnStatus,
-} from "./types/group/GroupDispatchSession.js";
+} from "./types/group/GroupDispatch.js";
 export { GroupSession, GroupSessions } from "./group/index.js";
 export type {
   GroupMemberRuntime,
@@ -48,65 +49,24 @@ export type {
   GroupSessionsContract,
 } from "./group/index.js";
 export { AiDispatchStrategy } from "./group/index.js";
-export { City } from "./city/index.js";
-export type {
-  CityAgents,
-  CityGroups,
-  CityListenOptions,
-  CityOptions,
-  CityRuntimeOptions,
-  CityWorkspaces,
-} from "./city/index.js";
-export type {
-  PluginHostContext,
-  PluginHostExtensions,
-  AgentPluginModule,
-} from "./city/index.js";
-export {
-  create_city_host_instance_id,
-  get_city_host_state_path,
-  is_process_alive,
-  read_city_host_state,
-  register_city_host,
-  request_city_host_shutdown,
-  unregister_city_host,
-  wait_for_city_host_exit,
-} from "./city/index.js";
-export type {
-  AgentHttpBinding,
-  AgentHttpListenOptions,
-  AgentHttpRuntimeOptions,
-  CityHttpRuntimeOptions,
-  CityAgentHttpExtension,
-  AgentRpcBinding,
-  AgentRpcListenOptions,
-  AgentRpcRuntimeOptions,
-  CityRpcRuntimeOptions,
-  AgentSessionModelResolver,
-  CityHostOwner,
-  CityHostState,
-} from "./city/index.js";
 export type { SessionStore } from "./types/store/SessionStore.js";
-export type {
-  CompactActiveMessagesInput,
-  CompactActiveMessagesResult,
-  SessionMessageCommitState,
-  SessionMessageStore,
-  SessionDataStore,
-} from "./types/store/SessionDataStore.js";
 export type { SessionAttachmentStore } from "./types/store/SessionAttachmentStore.js";
-export { create_session_message_store } from "./workspace/store/SessionMessageStoreFactory.js";
 export type { AgentStorage } from "./types/agent/AgentStorage.js";
-export { RemoteAgent } from "./remote/RemoteAgent.js";
 export { Session } from "./session/Session.js";
+export { SessionHooks, SessionHookScope } from "./session/SessionHooks.js";
 export type { SessionOptions } from "./types/session/SessionOptions.js";
-export type { SessionOrigin } from "./types/session/SessionOrigin.js";
-export {
-  infer_agent_model_label,
-  normalize_agent_model,
-  read_agent_model_context_window,
-} from "./agent/AgentModel.js";
-export type { AgentModel } from "./agent/AgentModel.js";
+export type { SessionOrigin } from "@downcity/type";
+export { SESSION_HOOK_POINTS } from "./session/SessionHookPoints.js";
+export type {
+  SessionCommittedTurnStatus,
+  SessionHookContextBlock,
+  SessionHookUserMessage,
+  SessionHookContext,
+  SessionHookHandlers,
+  SessionSystemContextHookValue,
+  SessionTurnCommittedHookValue,
+  SessionTurnContextHookValue,
+} from "@downcity/type";
 export type {
   AgentArchiveSessionInput,
   AgentArchiveSessionsInput,
@@ -134,49 +94,58 @@ export type {
 } from "./types/agent/SessionTypes.js";
 export type {
   ListSessionMessagesInput,
-  SessionActionMessage,
-  SessionAssistantDataPart,
-  SessionAssistantFilePart,
-  SessionAssistantInteractionPart,
-  SessionAssistantMessage,
-  SessionAssistantMessagePart,
-  SessionAssistantReasoningPart,
-  SessionAssistantTextPart,
-  SessionAssistantToolPart,
-  SessionErrorMessage,
+  SessionAgentActionPart,
+  SessionAgentDataPart,
+  SessionAgentFilePart,
+  SessionAgentInteractionPart,
+  SessionAgentMessage,
+  SessionAgentMessagePart,
+  SessionAgentReasoningPart,
+  SessionAgentTextPart,
+  SessionAgentToolPart,
+  SessionAgentErrorPart,
   SessionMessage,
   SessionMessagePage,
   SessionUserDataPart,
+  SessionUserContextPart,
   SessionUserFilePart,
   SessionUserMessage,
   SessionUserMessagePart,
   SessionUserTextPart,
-} from "./types/session/SessionMessage.js";
+} from "@downcity/type";
+export type {
+  SessionTurnFileDiff,
+  SessionTurnFileDiffData,
+  SessionTurnFileDiffStatus,
+  SessionTurnFileDiffSummary,
+} from "@downcity/type";
+export {
+  is_session_turn_file_diff_data_part,
+  read_session_turn_file_diff_data,
+  SESSION_TURN_FILE_DIFF_DATA_TYPE,
+} from "./session/messages/SessionTurnFileDiffData.js";
 export { to_session_message_timeline_events } from "./session/browse/SessionMessageTimeline.js";
 export { SessionAssistantOutputAdapter } from "./session/execution/SessionAssistantOutputAdapter.js";
-export type {
-  SessionContextSnapshot,
-  SessionMessageStorageStats,
-  SessionSegmentRange,
-  SessionSegmentSnapshot,
-  SessionSegmentSummary,
-} from "./types/session/SessionSegment.js";
 export {
   is_session_mutation,
-} from "./types/session/SessionMutation.js";
+} from "@downcity/type";
+export type {
+  ModelRequestKind,
+} from "@downcity/type";
 export type {
-  SessionCompactMutation,
   SessionConfigMutation,
   SessionDeltaMutation,
   SessionMessageMutation,
+  SessionModelRequestWarningMutation,
   SessionMutation,
   SessionMutationSubscriber,
   SessionMutationUnsubscribe,
   SessionPartMutation,
   SessionStateMutation,
   SessionTitleMutation,
+  SessionTurnFileDiffMutation,
   SessionTurnMutation,
-} from "./types/session/SessionMutation.js";
+} from "@downcity/type";
 export type {
   RespondSessionInteractionInput,
   SessionApprovalMode,
@@ -196,7 +165,7 @@ export type {
   SessionInteractionStatus,
   SessionPendingInteraction,
   SessionResolvedInteractionResult,
-} from "./types/session/SessionInteraction.js";
+} from "@downcity/type";
 export type {
   AgentOptions,
   AgentSessionConstructor,
@@ -212,57 +181,32 @@ export type {
   RemoteAgentSession,
 } from "./types/agent/SessionActor.js";
 export type { AgentManagedSession } from "./types/session/SessionOptions.js";
-export type { RemoteAgentOptions } from "./types/agent/RemoteAgentOptions.js";
-export type {
-  RemoteAgentPluginActionInput,
-  RemoteAgentPluginActionResult,
-} from "./types/agent/RemoteAgentPluginAction.js";
 export type {
   AgentSessionActionCallback,
   AgentSessionActionEvent,
   AgentSessionActionRecord,
   AgentSessionActionState,
 } from "./types/sdk/AgentSessionAction.js";
-export type { AgentSessionPromptInput } from "./types/sdk/AgentSessionPrompt.js";
 export type {
-  SessionPromptPart,
-  SessionAssistantResultPart,
-  SessionTextInputPart,
-  SessionFileInputPart,
-  SessionDataInputPart,
-} from "./types/session/SessionContent.js";
+  AgentSessionPromptContent,
+  AgentSessionPromptInput,
+} from "./types/sdk/AgentSessionPrompt.js";
+export { is_agent_session_prompt_input_empty } from "./types/sdk/AgentSessionPrompt.js";
+export type {
+  SessionAgentContent,
+  SessionContextContent,
+  SessionDataContent,
+  SessionFileContent,
+  SessionModelUserContent,
+  SessionTextContent,
+  SessionUserContent,
+} from "@downcity/type";
 export type { AgentSessionStopResult } from "./types/sdk/AgentSessionStop.js";
 export type {
   AgentSessionTurnHandle,
   AgentSessionTurnResult,
 } from "./types/sdk/AgentSessionTurn.js";
-export type {
-  AgentSessionCompactHandle,
-  AgentSessionCompactReason,
-  AgentSessionCompactResult,
-} from "./types/sdk/AgentSessionCompact.js";
-export type { PluginContext } from "./types/plugin/PluginContext.js";
-export type { AgentPluginContext } from "./types/plugin/AgentPluginContext.js";
-export type {
-  PluginNotificationInput,
-  PluginNotificationPublisher,
-  PluginNotificationTopicInput,
-} from "./types/plugin/PluginNotification.js";
-export type {
-  PluginWebServices,
-} from "./types/plugin/PluginServices.js";
 export type { SessionPort } from "./types/session/SessionPort.js";
-
-// Plugin 作者 API
-export { BasePlugin } from "./plugin/core/BasePlugin.js";
-export {
-  create_action,
-  create_plugin,
-} from "./plugin/core/PluginActionFactory.js";
-export type {
-  CreatePluginActionOptions,
-  CreatePluginOptions,
-} from "./plugin/core/PluginActionFactory.js";
 export type {
   ActionResult,
   ActionResultMessage,
@@ -271,30 +215,39 @@ export type {
 // Session 与即时执行集成
 export { Executor } from "./executor/Executor.js";
 export { DefaultSessionComposer } from "./session/DefaultSessionComposer.js";
+export { FullHistoryContextPolicy } from "./session/composer/policies/FullHistoryContextPolicy.js";
+export { AdaptivePartContextPolicy } from "./session/composer/policies/AdaptivePartContextPolicy.js";
 export { SessionMessages } from "./session/SessionMessages.js";
 export type {
-  AppendCompletedAssistantMessageInput,
-  AppendExternalSessionAssistantMessageInput,
+  AppendCompletedAgentMessageInput,
+  AppendExternalSessionAgentMessageInput,
   AppendExternalSessionUserMessageInput,
-  AppendSessionErrorMessageInput,
+  AppendSessionAgentErrorPartInput,
   AppendSessionPromptMessageInput,
   AppendSessionUserMessageInput,
-  OpenSessionActionMessageInput,
-  OpenSessionAssistantMessageInput,
+  OpenSessionAgentActionPartInput,
+  OpenSessionAgentMessageInput,
   SessionMessagesOptions,
 } from "./types/session/SessionMessages.js";
 export type {
   SessionComposer,
-  SessionCompactionInput,
-  SessionCompactionPlan,
   SessionComposeIdentity,
   SessionComposeInput,
   SessionComposeState,
   SessionComposeTurn,
+  SessionComposerInitializeInput,
+  SessionContextRecoveryInput,
   SessionStepInput,
 } from "./types/session/SessionComposer.js";
-export { DefaultSessionSystemComposer } from "./executor/composer/system/default/DefaultSessionSystemComposer.js";
-export { resolve_session_system_messages } from "./executor/composer/system/default/SystemDomain.js";
+export type {
+  SessionContextPolicy,
+  SessionContextPolicyInitializeInput,
+  SessionContextPolicyInput,
+  SessionContextPolicyRecoveryInput,
+  SessionContextRecoveryReason,
+  SessionResolvedContext,
+  SessionResolvedContextDiagnostics,
+} from "./types/session/SessionContextPolicy.js";
 export type {
   SessionExecutor,
   SessionTurnExecutionResult,
@@ -305,8 +258,6 @@ export type {
   SessionTurnContextInit,
 } from "./types/executor/SessionTurnContext.js";
 export type { SessionToolExecutionContext } from "./types/executor/SessionToolExecutionContext.js";
-export type { PluginExecutionContext } from "./types/plugin/PluginExecutionContext.js";
-export type { PluginActionExecutionContext } from "./types/plugin/PluginActionExecution.js";
 export type {
   ToolActionExecutionContext,
   ToolSessionExecutionScope,
@@ -315,28 +266,8 @@ export type {
   SessionActionEvent,
   SessionActionEventInput,
   SessionActionStatus,
-} from "./types/session/SessionAction.js";
+} from "@downcity/type";
 export type { SessionSystemMessage } from "./executor/types/SessionPrompts.js";
-export { transform_prompts_into_system_messages } from "./executor/composer/system/default/PromptRenderer.js";
-// 通用 plugin 宿主工具
-export {
-  build_static_plugin_availability,
-  find_plugin_by_name,
-  has_plugin_lifecycle,
-  list_plugin_views,
-  list_plugins_with_lifecycle,
-  list_plugins_without_lifecycle,
-  resolve_plugin_availability,
-  to_plugin_view,
-} from "./plugin/core/PluginCatalog.js";
-export {
-  list_plugin_auth_policies,
-  register_plugin_http_routes,
-} from "./plugin/core/PluginHttpRoutes.js";
-
-// Runtime plugin 调度集成
-export { ActionScheduleStore } from "./plugin/core/ActionScheduleStore.js";
-export { parse_action_schedule_run_at_ms_or_throw } from "./plugin/core/ActionScheduleTime.js";
 export {
   extract_session_message_text,
   extract_session_tool_calls,
@@ -364,61 +295,6 @@ export {
 } from "./utils/Time.js";
 
 // JSON 基础类型
-export type { JsonObject, JsonPrimitive, JsonValue } from "./types/common/Json.js";
-
-// Plugin 作者与控制面类型
-export type {
-  PluginAction,
-  PluginActionApi,
-  PluginActionCommand,
-  PluginActionCommandInput,
-  PluginActionExample,
-  PluginActionInputSchema,
-  PluginActionMetadata,
-  PluginActionResult,
-  PluginActions,
-  PluginActionInvokeParams,
-  PluginActionInvokePort,
-  PluginActionInvokeResult,
-} from "./types/plugin/PluginAction.js";
-export type { Plugin } from "./types/plugin/PluginDefinition.js";
-export type { PluginLifecycle } from "./types/plugin/PluginCommand.js";
-export type {
-  AgentPlugins,
-  PluginAvailability,
-  PluginEffectHook,
-  PluginGuardHook,
-  PluginHooks,
-  PluginPipelineHook,
-  PluginResolves,
-  PluginResolveHook,
-  PluginView,
-} from "./types/plugin/PluginRuntime.js";
-export type {
-  PluginHttpDefinition,
-  PluginHttpRegistration,
-} from "./types/plugin/PluginHttp.js";
-export type {
-  PluginActionResponse,
-  PluginCatalogResponse,
-  PluginAvailabilityResponse,
-  PluginAvailabilityView,
-} from "./plugin/types/PluginApi.js";
+export type { JsonObject, JsonPrimitive, JsonValue } from "@downcity/type";
 
-// 主动型 plugin 与 CLI/control 协议类型
-export type { PluginState, PluginSnapshot } from "./types/plugin/PluginState.js";
-export type {
-  ActionScheduleJobRecord,
-  ActionScheduleJobStatus,
-  CreateActionScheduleJobInput,
-  PluginActionScheduleInput,
-} from "./plugin/types/ActionSchedule.js";
-export { list_plugin_states } from "./plugin/core/PluginStateController.js";
-
-// 跨包 RPC 与 session 标识协议
-export type {
-  RpcEventFrame,
-  RpcRequest,
-  RpcServerFrame,
-} from "./types/rpc/RpcProtocol.js";
 export { resolve_session_id } from "./executor/ids/resolveSessionId.js";

package/src/session/DefaultSessionComposer.ts

@@ -1,25 +1,79 @@
 /**
  * 默认 Session Composer。
  *
- * 负责把 Session 的只读状态与 canonical Message 快照组装为模型输入；
- * 压缩只生成计划，实际 Segment 提交仍由 SessionMessages 负责。
+ * 负责把 Session 运行快照与 Context Policy 结果组装为最终模型输入。
  */
 
 import { build_session_system_blocks } from "@/session/SessionSystem.js";
-import { compose_session_compaction } from "@/session/messages/SessionMessageCompaction.js";
-import { session_context_to_model_messages } from "@executor/messages/SessionModelMessages.js";
 import type {
   SessionComposer,
-  SessionCompactionInput,
-  SessionCompactionPlan,
   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({
@@ -29,50 +83,41 @@ export class DefaultSessionComposer implements SessionComposer {
       created_at: input.session.created_at,
       timezone: input.session.timezone,
       get_instruction_system_blocks: () => [
-        ...input.state.instruction_system_blocks,
+        ...(input.state.instruction_system_blocks ?? []),
       ],
       get_managed_plugin_system_blocks: async () => [
-        ...input.state.managed_plugin_system_blocks,
+        ...(input.state.managed_plugin_system_blocks ?? []),
       ],
       get_plugin_system_blocks: async () => [
-        ...input.state.plugin_system_blocks,
+        ...(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: await session_context_to_model_messages(
-        input.history,
-        input.session.project_root,
-      ),
+      messages: inject_plugin_context(context.messages, input.state.plugin_context_blocks ?? []),
       tools: { ...input.state.tools },
+      context_diagnostics: context.diagnostics,
     };
   }
 
-  /** 生成等待 SessionMessages 提交的压缩计划。 */
-  async compact(
-    input: SessionCompactionInput,
-  ): Promise<SessionCompactionPlan | null> {
-    if (!input.model) return null;
-    return await compose_session_compaction({
-      session_id: input.session.session_id,
-      snapshot: input.history,
+  /** 把上下文恢复委托给当前 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,
     });
   }
-
-  /** 判断错误是否属于模型上下文超限。 */
-  should_compact(error: unknown): boolean {
-    const message = String(error ?? "");
-    return (
-      message.includes("context_length") ||
-      message.includes("too long") ||
-      message.includes("maximum context") ||
-      message.includes("context window")
-    );
-  }
 }