@downcity/agent 1.1.23 → 1.1.32

package/src/runtime/server/http/control/StreamBySession.ts

@@ -1,198 +0,0 @@
-/**
- * Control session 增量执行 helper。
- *
- * 关键点（中文）
- * - 仅用于单 agent control API 的本地 session 增量返回。
- * - chatKey 命中的平台 chat 队列仍保持原有入队语义，不在这里伪造“流式完成”。
- * - 输出协议使用内部 `AgentUiChunkEvent` 的 NDJSON 事件行，便于 CLI 直接消费。
- */
-
-import type { AgentContext, SessionPort } from "@/core/AgentContextTypes.js";
-import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
-import type {
-  ControlSessionExecuteAttachmentInput,
-} from "@/runtime/server/http/control/types/ControlSessionExecute.js";
-import { buildExecuteInputText } from "@/runtime/server/http/control/Helpers.js";
-import { drainDeferredPersistedUserMessages } from "@session/SessionRunScope.js";
-import { mapUiMessageChunkToAgentEvent } from "@/sdk/SessionEventMapper.js";
-import type { AgentUiChunkEvent } from "@/types/sdk/AgentUiChunkEvent.js";
-import type {
-  SessionRunResult,
-  SessionUiMessageChunkCallback,
-} from "@/session/types/SessionRun.js";
-import { resolveDispatchTargetByChatKey } from "@/service/builtins/chat/runtime/ChatkeySend.js";
-import {
-  pickLastSuccessfulChatSendText,
-  resolveAssistantMessageForPersistence,
-} from "@/service/builtins/chat/runtime/UserVisibleText.js";
-
-type StreamableSessionPort = SessionPort & {
-  /**
-   * 流式执行当前 session。
-   *
-   * 说明（中文）
-   * - `SessionPort` 对外接口当前未显式暴露 `onUiMessageChunkCallback`，
-   *   但本地 executor 已支持该回调，这里按本地 control runtime 语义做窄化使用。
-   */
-  execute(params: {
-    query: string;
-    onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
-  }): Promise<SessionRunResult>;
-};
-
-const NDJSON_CONTENT_TYPE = "application/x-ndjson; charset=utf-8";
-
-function encodeNdjsonLine(
-  encoder: TextEncoder,
-  value: AgentUiChunkEvent,
-): Uint8Array {
-  return encoder.encode(`${JSON.stringify(value)}\n`);
-}
-
-function resolveStreamEventFromUiChunk(params: {
-  chunk: Parameters<NonNullable<SessionUiMessageChunkCallback>>[0];
-  toolNameByCallId: Map<string, string>;
-}): AgentUiChunkEvent | null {
-  const { chunk, toolNameByCallId } = params;
-  if (chunk.type === "tool-input-start") {
-    toolNameByCallId.set(chunk.toolCallId, chunk.toolName);
-    return null;
-  }
-
-  const event = mapUiMessageChunkToAgentEvent(chunk);
-  if (!event) return null;
-
-  if (event.type === "tool-call" || event.type === "tool-error") {
-    toolNameByCallId.set(event.toolCallId, event.toolName);
-  }
-
-  if (
-    (event.type === "tool-result" || event.type === "tool-error") &&
-    event.toolName === "unknown"
-  ) {
-    const toolName = toolNameByCallId.get(event.toolCallId);
-    return toolName ? { ...event, toolName } : event;
-  }
-
-  return event;
-}
-
-/**
- * 为指定 session 创建流式执行响应。
- */
-export async function createControlSessionStreamResponse(params: {
-  agentState: AgentRuntime;
-  executionContext: AgentContext;
-  sessionId: string;
-  instructions: string;
-  attachments?: ControlSessionExecuteAttachmentInput[];
-}): Promise<Response> {
-  const sessionId = String(params.sessionId || "").trim();
-  const instructions = String(params.instructions || "").trim();
-  if (!sessionId) {
-    return Response.json({ success: false, error: "Missing sessionId" }, { status: 400 });
-  }
-  if (!instructions) {
-    return Response.json({ success: false, error: "Missing instructions" }, { status: 400 });
-  }
-
-  const executeInput = await buildExecuteInputText({
-    projectRoot: params.agentState.rootPath,
-    sessionId,
-    instructions,
-    attachments: params.attachments,
-  });
-
-  const dispatchTarget = await resolveDispatchTargetByChatKey({
-    context: params.executionContext,
-    chatKey: sessionId,
-  });
-  if (dispatchTarget) {
-    return Response.json(
-      {
-        success: false,
-        error:
-          "Streaming execute does not support queued chat sessions. Use the non-stream execute API for chatKey routes.",
-      },
-      { status: 409 },
-    );
-  }
-
-  const session = params.agentState.getSession(sessionId) as StreamableSessionPort;
-  const encoder = new TextEncoder();
-
-  const stream = new ReadableStream<Uint8Array>({
-    start(controller) {
-      void (async () => {
-        const toolNameByCallId = new Map<string, string>();
-
-        const pushEvent = (event: AgentUiChunkEvent): void => {
-          controller.enqueue(encodeNdjsonLine(encoder, event));
-        };
-
-        try {
-          await session.appendUserMessage({
-            text: executeInput,
-          });
-
-          const result = await session.execute({
-            query: executeInput,
-            onUiMessageChunkCallback: async (chunk) => {
-              const event = resolveStreamEventFromUiChunk({
-                chunk,
-                toolNameByCallId,
-              });
-              if (!event) return;
-              pushEvent(event);
-            },
-          });
-
-          const userVisible = pickLastSuccessfulChatSendText(
-            result.assistantMessage,
-          ).trim();
-          try {
-            const messageForPersistence = resolveAssistantMessageForPersistence(
-              result.assistantMessage,
-            );
-            if (messageForPersistence) {
-              await session.appendAssistantMessage({
-                message: messageForPersistence,
-                fallbackText: userVisible,
-                extra: {
-                  via: "tui_session_stream",
-                  note: "assistant_message_missing",
-                },
-              });
-            }
-            const deferredInjectedMessages = drainDeferredPersistedUserMessages(
-              sessionId,
-            );
-            for (const message of deferredInjectedMessages) {
-              await session.appendUserMessage({
-                message,
-              });
-            }
-          } catch {
-            // ignore persistence follow-up errors after stream completion
-          }
-        } catch (error) {
-          pushEvent({
-            type: "error",
-            error: error instanceof Error ? error.message : String(error),
-          });
-        } finally {
-          controller.close();
-        }
-      })();
-    },
-  });
-
-  return new Response(stream, {
-    status: 200,
-    headers: {
-      "Content-Type": NDJSON_CONTENT_TYPE,
-      "Cache-Control": "no-cache, no-transform",
-      "X-Accel-Buffering": "no",
-    },
-  });
-}

package/src/sdk/session/ServicePort.ts

@@ -1,130 +0,0 @@
-/**
- * SDK Session service 端口构造器。
- *
- * 关键点（中文）
- * - 把 SDK 本地 session 适配成 runtime / service 依赖的 `SessionPort`。
- * - SDK 公开面只保留 `prompt()` / `subscribe()`；内部单轮执行原语仍通过这里暴露给 service/runtime。
- */
-
-import type { SessionPort } from "@/core/AgentContextTypes.js";
-import type { SessionHistoryStore } from "@/session/store/history/SessionHistoryStore.js";
-import type { SessionRunResult } from "@/session/types/SessionRun.js";
-import type { SessionUserMessageV1 } from "@/session/types/SessionMessages.js";
-import type {
-  SessionAssistantStepCallback,
-  SessionUiMessageChunkCallback,
-} from "@/session/types/SessionRun.js";
-import type { AgentSessionPromptInput } from "@/types/sdk/AgentSessionPrompt.js";
-import type {
-  AgentSessionSubscriber,
-  AgentSessionUnsubscribe,
-} from "@/types/sdk/AgentSessionEvent.js";
-import type { AgentSessionTurnHandle } from "@/types/sdk/AgentSessionTurn.js";
-
-/**
- * 构造 SDK SessionPort 的参数。
- */
-export interface CreateSessionServicePortParams {
-  /**
-   * 当前 sessionId。
-   */
-  sessionId: string;
-  /**
-   * 读取当前 session 底层执行端口。
-   */
-  getExecutor: SessionPort["getExecutor"];
-  /**
-   * 运行一次内部 direct execution。
-   *
-   * 关键点（中文）
-   * - 这是 runtime / service 侧保留的内部原语。
-   * - 它不属于 SDK 用户推荐直接调用的公开模式。
-   */
-  executeDirect: (params: {
-    query: string;
-    onStepCallback?: () => Promise<SessionUserMessageV1[]>;
-    onAssistantStepCallback?: SessionAssistantStepCallback;
-    onUiMessageChunkCallback?: SessionUiMessageChunkCallback;
-  }) => Promise<SessionRunResult>;
-  /**
-   * 追加一条新的 session prompt。
-   */
-  prompt: (input: AgentSessionPromptInput) => Promise<AgentSessionTurnHandle>;
-  /**
-   * 订阅当前 session 的 future 事件。
-   */
-  subscribe: (
-    subscriber: AgentSessionSubscriber,
-  ) => AgentSessionUnsubscribe;
-  /**
-   * 清理当前 session executor 状态。
-   */
-  clearExecutor: () => void;
-  /**
-   * session 更新后的异步通知回调。
-   */
-  afterSessionUpdatedAsync: () => Promise<void>;
-  /**
-   * 追加 user 消息到底层历史。
-   */
-  appendUserMessage: SessionPort["appendUserMessage"];
-  /**
-   * 追加 assistant 消息到底层历史。
-   */
-  appendAssistantMessage: SessionPort["appendAssistantMessage"];
-  /**
-   * 返回当前 session 是否正在执行。
-   */
-  isExecuting: () => boolean;
-  /**
-   * 当前 session 历史持久化端口。
-   */
-  historyStore: SessionHistoryStore;
-  /**
-   * 在执行前确保当前 session 已完成初始化与宿主级配置。
-   */
-  ensureReadyForExecution: () => Promise<void>;
-  /**
-   * session 更新后需要同步执行的持久化回调。
-   */
-  touchMetadata: () => Promise<void>;
-}
-
-/**
- * 创建供 service 使用的 session 端口。
- */
-export function createSessionServicePort(
-  params: CreateSessionServicePortParams,
-): SessionPort {
-  return {
-    sessionId: params.sessionId,
-    getExecutor: () => params.getExecutor(),
-    getHistoryStore: () => params.historyStore,
-    execute: async (runParams) => {
-      await params.ensureReadyForExecution();
-      return await params.executeDirect(runParams);
-    },
-    prompt: async (input) => {
-      await params.ensureReadyForExecution();
-      return await params.prompt(input);
-    },
-    subscribe: (subscriber) => {
-      return params.subscribe(subscriber);
-    },
-    clearExecutor: () => {
-      params.clearExecutor();
-    },
-    afterSessionUpdatedAsync: async () => {
-      await params.afterSessionUpdatedAsync();
-    },
-    appendUserMessage: async (messageParams) => {
-      await params.appendUserMessage(messageParams);
-      await params.touchMetadata();
-    },
-    appendAssistantMessage: async (messageParams) => {
-      await params.appendAssistantMessage(messageParams);
-      await params.touchMetadata();
-    },
-    isExecuting: () => params.isExecuting(),
-  };
-}

package/src/service/builtins/BaseService.ts

@@ -1,97 +0,0 @@
-/**
- * BaseService：service 类实现的统一基类。
- *
- * 关键点（中文）
- * - agent 会持有 per-agent 的 service instance，而不再直接依赖全局 service 单例对象。
- * - 各 service 的长期状态应归属于实例本身，而不是模块级单例。
- */
-
-import type { AgentRuntime } from "@/core/AgentCoreTypes.js";
-import type {
-  Service,
-  ServiceActions,
-  ServiceLifecycle,
-} from "@/service/types/Service.js";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type { ServiceStateRecord } from "@/service/types/ServiceState.js";
-
-/**
- * BaseService 抽象基类。
- *
- * 关键点（中文）
- * - 保留统一 `Service` 契约。
- * - 为实例字段状态（cronEngine / queueWorker / watchers / shellSessions）预留宿主引用。
- */
-export abstract class BaseService implements Service {
-  /**
-   * 当前实例持有的通用 service 状态记录。
-   *
-   * 关键点（中文）
-   * - 通用 lifecycle 状态直接归属于 service 实例。
-   * - `ServiceStateController` 只负责读写，不再维护全局状态表。
-   */
-  public readonly serviceStateRecord: ServiceStateRecord = {
-    state: "stopped",
-    updatedAt: Date.now(),
-    chain: Promise.resolve(),
-  };
-
-  /**
-   * 当前 service 所属的 agent 宿主。
-   *
-   * 关键点（中文）
-   * - 允许为空，仅用于静态装配与无宿主测试场景。
-   * - 真正运行中的 service 实例应始终绑定一个 agent。
-   */
-  protected agent: AgentRuntime | null;
-
-  constructor(agent: AgentRuntime | null = null) {
-    this.agent = agent;
-  }
-
-  /**
-   * 当前 service 名称。
-   */
-  abstract readonly name: string;
-
-  /**
-   * 当前 service 的 action 定义表。
-   */
-  abstract readonly actions: ServiceActions;
-
-  /**
-   * 可选的 service 级 system 文本提供器。
-   */
-  system?(context: AgentContext): string | Promise<string>;
-
-  /**
-   * 可选的 service 生命周期定义。
-   */
-  lifecycle?: ServiceLifecycle;
-
-  /**
-   * 绑定当前 service 所属的 agent 宿主。
-   *
-   * 关键点（中文）
-   * - SDK `new Agent({ services: [...] })` 会在装配阶段调用这里完成后绑定。
-   * - 若 service 已在构造阶段绑定过宿主，则这里允许覆盖到新的宿主实例。
-   */
-  bindAgent(agent: AgentRuntime | null): this {
-    this.agent = agent;
-    return this;
-  }
-
-  /**
-   * 读取绑定的 agent 宿主。
-   *
-   * 关键点（中文）
-   * - 仅供后续真正 class service 在实例方法中读取宿主能力。
-   * - 未绑定 agent 时直接 fail-fast，避免静默读取 undefined。
-   */
-  protected requireAgent(): AgentRuntime {
-    if (this.agent) return this.agent;
-    throw new Error(
-      `Service "${this.name}" is not bound to an agent instance.`,
-    );
-  }
-}

package/src/service/builtins/README.md

@@ -1,121 +0,0 @@
-# services
-
-## 模块定位
-
-`service/builtins/` 是 Downcity 的内建主动业务层。  
-每个 service 对外暴露统一的 `Service` 契约，但在运行时已经逐步迁移为 `BaseService` 子类，由 agent 在启动时创建 `per-agent service instance`。
-
-## 当前整体模型
-
-1. `service/core/Services.ts`
-   - 维护 service 的静态注册清单。
-2. `service/core/ServiceClassRegistry.ts`
-   - 负责把静态 service 定义实例化为 `BaseService` 子类。
-3. `runtime/AgentRuntime.ts`
-   - agent 持有当前运行中的 service 实例集合。
-4. `service/core/Manager.ts`
-   - 统一做 service lifecycle、action 调度、CLI/API 桥接。
-5. `service/types/Service.ts`
-   - 作为 service 共享契约的单一事实源。
-
-## 当前内建 service
-
-1. `chat/`
-   - 负责聊天渠道接入、session 路由、消息发送与会话查询。
-   - `ChatService.ts` 是实例入口。
-   - `ChatService` 只保留实例骨架，持有实例级 `channelState` 与 `queueWorker`。
-   - `runtime/ChatServiceActions.ts` 负责 action 注册表装配。
-   - `runtime/ChatServiceSystem.ts` 负责 system prompt。
-   - `runtime/ChatChannelCore.ts` 负责渠道基础 helper。
-   - `runtime/ChatChannelLifecycle.ts` 负责渠道 bot 生命周期。
-   - `runtime/ChatChannelConfig.ts` 负责状态快照与配置落盘。
-   - `runtime/ChatChannelActions.ts` 负责渠道类 action 执行。
-   - `runtime/ChatChannelFacade.ts` 只保留门面导出。
-   - `runtime/ChatActionInput.ts` 负责非 send 类 CLI/API 输入映射与统一导出。
-   - `runtime/ChatSendActionInput.ts` 负责 `chat send` 正文协议、stdin/file 与定时发送输入映射。
-   - `runtime/ChatActionInputSupport.ts` 负责 chat action 输入映射共享解析辅助。
-   - `runtime/ChatActionExecution.ts` 负责消息类 action 执行。
-   - `runtime/ChatQueueSessionBridge.ts` 负责 queue 与 session 的桥接写入协议。
-   - `runtime/ChatQueueWorkerSupport.ts` 负责 worker 辅助能力。
-   - `runtime/ChatQueueReplyDispatch.ts` 负责 direct/fallback 回复分发。
-   - `runtime/ChatQueueWorker.ts` 负责 queue lane 调度与主执行链。
-   - `channels/BaseChatChannel.ts` 负责渠道基类门面与公共编排。
-   - `channels/BaseChatChannelSupport.ts` 负责 session 映射、history 与 chat meta 辅助。
-   - `channels/BaseChatChannelQueue.ts` 负责 audit/exec 入队编排。
-   - `channels/telegram/Bot.ts` 现在只保留 Telegram 渠道门面与编排。
-   - `channels/telegram/TelegramMessageHandler.ts` 负责 Telegram 普通消息授权、附件与执行入队。
-   - `channels/telegram/TelegramPendingUpdates.ts` 负责 Telegram 积压 updates 的 audit 补录。
-   - `channels/telegram/TelegramPlatformClient.ts` 负责 Telegram polling/API/发送主逻辑。
-   - `channels/telegram/TelegramInbound.ts` 负责 Telegram 入站归一化辅助。
-   - `channels/feishu/Feishu.ts` 现在只保留 Feishu 渠道门面与编排。
-   - `channels/feishu/FeishuMessageHandler.ts` 负责 Feishu 入站去重、授权、附件与执行入队。
-   - `channels/feishu/FeishuPlatformClient.ts` 负责 Feishu runtime 宿主与 token/cache 状态。
-   - `channels/feishu/FeishuPlatformLookup.ts` 负责 Feishu 用户/群聊/reply 查询与入站附件下载。
-   - `channels/feishu/FeishuPlatformMessaging.ts` 负责 Feishu 消息发送与附件上传。
-   - `channels/feishu/FeishuInbound.ts` 负责 Feishu 入站归一化辅助。
-   - `channels/qq/QQ.ts` 现在只保留 QQ 渠道门面与编排。
-   - `channels/qq/QQMessageHandler.ts` 负责 QQ group/c2c/channel 入站主流程。
-   - `channels/qq/QQSupport.ts` 负责 QQ READY 身份解析、命令映射与入站增强组装。
-   - `channels/qq/QQGatewayClient.ts` 负责 QQ Gateway runtime 宿主、WS 编排与重连调度。
-   - `channels/qq/QQGatewayConnection.ts` 负责 QQ Gateway WebSocket 创建与事件绑定。
-   - `channels/qq/QQGatewayProtocol.ts` 负责 QQ Gateway op code 协议路由与 Identify。
-   - `channels/qq/QQGatewayHeartbeat.ts` 负责 QQ Gateway heartbeat payload 发送。
-   - `channels/qq/QQGatewaySupport.ts` 负责 QQ Gateway 状态快照、心跳判断与 payload 解析。
-   - `channels/qq/QQGatewayAuth.ts` 负责 QQ 鉴权、Gateway URL 与 HTTP 连通性测试。
-   - `channels/qq/QQGatewaySend.ts` 负责 QQ 回发请求构造、超时与自动重试。
-   - `channels/qq/QQInbound.ts` 负责 QQ 入站归一化辅助。
-2. `task/`
-   - 负责任务定义、计划调度、手动执行与 run 落盘。
-   - `TaskService.ts` 是实例入口，持有实例级 cron runtime 状态。
-   - `runtime/TaskServiceActions.ts` 负责 action 注册表装配。
-   - `runtime/TaskServiceSystem.ts` 负责 task system prompt。
-   - `runtime/TaskActionInput.ts` 负责 CLI/API 输入映射。
-   - `runtime/TaskActionExecution.ts` 负责 task 领域执行逻辑。
-   - `runtime/TaskRunnerProgress.ts` 负责 progress 快照与文本辅助。
-   - `runtime/TaskRunnerSession.ts` 负责 task 专用 session runtime。
-   - `runtime/TaskRunnerRound.ts` 负责单轮执行与模拟用户判定。
-   - `runtime/TaskRunnerScript.ts` 负责 script 类型任务的 one-shot 执行与校验分支。
-   - `runtime/TaskRunArtifacts.ts` 负责 run 产物写入与 markdown/json 摘要格式。
-   - `runtime/Runner.ts` 负责主编排并协调 run 产物写入。
-3. `memory/`
-   - 负责记忆提取、索引、检索与 flush。
-   - `MemoryService.ts` 持有实例级 memory runtime 状态。
-4. `shell/`
-   - 负责 shell session 生命周期与命令执行。
-   - `ShellService.ts` 持有实例级 shell session 状态。
-   - `runtime/ShellActionRuntime.ts` 负责公开 action 编排。
-   - `runtime/ShellActionRuntimeSupport.ts` 负责持久化、waiter 与 session 查找等共享运行时细节。
-   - `runtime/ShellRuntimeEnvironment.ts` 负责 shell cwd、env 与 owner context 解析。
-   - `runtime/ShellActionResponse.ts` 负责输出游标裁剪与标准 action response 构造。
-   - `runtime/ShellProcessEvents.ts` 负责 shell 子进程输出、错误与 close 事件绑定。
-   - `session/tools/shell/ShellToolDefinition.ts` 作为 session tool facade，只做协议适配。
-   - `session/tools/shell/ShellToolSchemas.ts` 负责 shell tool schema。
-   - `session/tools/shell/ShellToolBridge.ts` 负责 runtime bridge 与响应整理。
-5. `contact/`
-   - 负责 agent 点对点关系、长期 contact chat、内容分享与 inbox 接收。
-   - `ContactService.ts` 是实例入口，只保留 service 骨架与 contact 业务动作。
-   - `Action.ts` 负责 CLI/API action 注册表与输入映射。
-   - `runtime/ContactPayload.ts` 负责远端 HTTP payload 与 contact token 读取。
-   - `runtime/ContactStore.ts`、`LinkStore.ts`、`InboxStore.ts` 负责 contact/link/inbox 落盘。
-   - `runtime/LinkApproval.ts`、`ApproveCallback.ts` 负责建联与双向回连确认。
-   - `runtime/ShareBundle.ts` 负责分享内容打包与接收。
-
-## 统一服务模式
-
-1. `Index.ts`
-   - 只保留静态导出入口。
-2. `<Domain>Service.ts`
-   - 作为真正的 class service 实现。
-3. `Action.ts`
-   - 负责 action 注册表、CLI/API 输入映射与 handler 注入。
-4. `runtime/`
-   - 承载具体运行时实现、状态管理与输入映射。
-5. `types/`
-   - 存放领域内部协议；跨层共享契约统一提升到 `service/types/` 或包级 `types/`。
-
-## 边界约束
-
-1. service 通过 `AgentContext` 读取运行时能力。
-2. service 的实例状态应归属于 service instance，而不是模块级单例。
-3. plugin 只能作为被动扩展，不替代 service 主流程。
-4. service 间协作优先通过 `AgentContext.invoke`，而不是隐式全局状态。