@downcity/agent 1.1.32 → 1.1.43

package/src/plugin/builtins/shell/runtime/ShellActionRuntimeSupport.ts

@@ -1,384 +0,0 @@
-/**
- * Shell action 运行时辅助能力。
- *
- * 关键点（中文）
- * - 统一承载 ShellActionRuntime 的内部共享逻辑：环境组装、持久化、waiter 协调、session 查找。
- * - 对外暴露给 ShellActionRuntime 的只有纯运行时辅助函数，不直接承担 service action 编排。
- */
-
-import path from "node:path";
-import fs from "fs-extra";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import type {
-  ShellPluginState,
-  ShellSessionRuntimeState,
-} from "@/plugin/builtins/shell/ShellRuntimeTypes.js";
-import type {
-  ShellQueryRequest,
-  ShellSessionSnapshot,
-  ShellSessionStatus,
-} from "@/plugin/builtins/shell/types/ShellPlugin.js";
-import { getShellOutputPath, getShellSnapshotPath } from "./Paths.js";
-import { resolveOwnerContextId } from "./ShellRuntimeEnvironment.js";
-export {
-  buildShellEnv,
-  resolveOwnerContextId,
-  resolveShellCwd,
-} from "./ShellRuntimeEnvironment.js";
-export {
-  buildActionResponse,
-  createOutputChunk,
-} from "./ShellActionResponse.js";
-
-const MAX_ACTIVE_SHELLS = 64;
-const SESSION_CLEANUP_DELAY_MS = 10 * 60 * 1000;
-const MAX_IN_MEMORY_OUTPUT_CHARS = 1_000_000;
-const MIN_WAIT_MS = 50;
-const MAX_WAIT_MS = 30_000;
-const OUTPUT_PREVIEW_CHARS = 280;
-
-/**
- * shell.start 默认内联等待时间。
- */
-export const DEFAULT_INLINE_WAIT_MS = 1_200;
-
-/**
- * shell.wait 默认等待超时。
- */
-export const DEFAULT_WAIT_TIMEOUT_MS = 10_000;
-
-/**
- * shell.exec 默认总超时。
- */
-export const DEFAULT_EXEC_TIMEOUT_MS = 60_000;
-
-/**
- * 创建 shell service 初始状态。
- */
-export function createShellPluginState(): ShellPluginState {
-  return {
-    sessions: new Map<string, ShellSessionRuntimeState>(),
-    boundRuntime: null,
-  };
-}
-
-/**
- * 返回当前毫秒时间戳。
- */
-export function nowMs(): number {
-  return Date.now();
-}
-
-/**
- * 归一化 wait/timeout 参数。
- */
-export function clampWaitMs(value: number | undefined, fallback: number): number {
-  const raw =
-    typeof value === "number" && Number.isFinite(value)
-      ? Math.floor(value)
-      : fallback;
-  return Math.min(MAX_WAIT_MS, Math.max(MIN_WAIT_MS, raw));
-}
-
-function normalizeOutputChunk(raw: string): string {
-  if (!raw) return "";
-  return raw
-    .replace(/\r\n/g, "\n")
-    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "");
-}
-
-function deriveExitStatus(exitCode: number | undefined): ShellSessionStatus {
-  if (exitCode === -9 || exitCode === 137) return "killed";
-  if (typeof exitCode === "number" && exitCode === 0) return "completed";
-  return "failed";
-}
-
-/**
- * 判断 shell 是否已进入终态。
- */
-export function isTerminalStatus(status: ShellSessionStatus): boolean {
-  return (
-    status === "completed" ||
-    status === "failed" ||
-    status === "killed" ||
-    status === "expired"
-  );
-}
-
-function extractExternalRefsFromText(
-  text: string,
-  current: ShellSessionSnapshot["externalRefs"],
-): ShellSessionSnapshot["externalRefs"] {
-  const next = [...current];
-  const register = (kind: string, value: string, label?: string): void => {
-    const normalized = String(value || "").trim();
-    if (!normalized) return;
-    if (next.some((item) => item.kind === kind && item.value === normalized)) return;
-    next.push({ kind, value: normalized, ...(label ? { label } : {}) });
-  };
-
-  const threadIdRegex = /thread_id[:=]\s*([a-zA-Z0-9_-]{6,})/g;
-  for (const match of text.matchAll(threadIdRegex)) {
-    register("thread_id", String(match[1] || ""), "external thread id");
-  }
-  return next;
-}
-
-/**
- * 持久化 shell snapshot。
- */
-export async function persistSnapshot(session: ShellSessionRuntimeState): Promise<void> {
-  await fs.ensureDir(path.dirname(session.snapshotFilePath));
-  await fs.writeJson(session.snapshotFilePath, session.snapshot, { spaces: 2 });
-}
-
-function enqueuePersistedAppend(
-  session: ShellSessionRuntimeState,
-  text: string,
-): Promise<void> {
-  session.writeChain = session.writeChain.then(async () => {
-    await fs.ensureDir(path.dirname(session.outputFilePath));
-    await fs.appendFile(session.outputFilePath, text, "utf-8");
-  });
-  return session.writeChain;
-}
-
-function notifyWaiters(session: ShellSessionRuntimeState): void {
-  for (const waiter of Array.from(session.waiters)) {
-    clearTimeout(waiter.timer);
-    session.waiters.delete(waiter);
-    waiter.resolve();
-  }
-}
-
-async function emitChatCompletionEvent(
-  context: AgentContext,
-  snapshot: ShellSessionSnapshot,
-): Promise<void> {
-  const ownerContextId = String(snapshot.ownerContextId || "").trim();
-  if (!ownerContextId || snapshot.notificationSent !== false) return;
-
-  const meta = await context.chat.readMetaBySessionId(ownerContextId);
-  if (!meta) return;
-
-  const lines = [
-    "[内部 shell 状态通知]",
-    `shell_id: ${snapshot.shellId}`,
-    `status: ${snapshot.status}`,
-    `exit_code: ${typeof snapshot.exitCode === "number" ? snapshot.exitCode : "null"}`,
-    `cmd: ${snapshot.cmd}`,
-  ];
-  if (snapshot.lastOutputPreview) {
-    lines.push(`last_output_preview: ${snapshot.lastOutputPreview}`);
-  }
-  if (snapshot.externalRefs.length > 0) {
-    const refs = snapshot.externalRefs.map((item) => `${item.kind}=${item.value}`);
-    lines.push(`external_refs: ${refs.join(", ")}`);
-  }
-  lines.push("请根据当前 shell 的状态，主动向用户简洁汇报结果或最新进展。");
-  const text = lines.join("\n");
-
-  context.chat.enqueue({
-    kind: "exec",
-    channel: meta.channel,
-    targetId: meta.chatId,
-    sessionId: ownerContextId,
-    text,
-    ...(meta.targetType ? { targetType: meta.targetType } : {}),
-    ...(typeof meta.threadId === "number" ? { threadId: meta.threadId } : {}),
-    ...(meta.messageId ? { messageId: meta.messageId } : {}),
-    ...(meta.actorId ? { actorId: meta.actorId } : {}),
-    ...(meta.actorName ? { actorName: meta.actorName } : {}),
-    extra: {
-      note: "shell_session_auto_notify",
-      internal: true,
-      shellId: snapshot.shellId,
-      shellStatus: snapshot.status,
-      exitCode:
-        typeof snapshot.exitCode === "number" ? snapshot.exitCode : null,
-    },
-  });
-}
-
-/**
- * 更新 session snapshot 并唤醒等待者。
- */
-export async function updateSessionSnapshot(
-  session: ShellSessionRuntimeState,
-  updater: (snapshot: ShellSessionSnapshot) => void | ShellSessionSnapshot,
-): Promise<void> {
-  const result = updater(session.snapshot);
-  if (result) {
-    session.snapshot = result;
-  }
-  session.snapshot.updatedAt = nowMs();
-  session.snapshot.version += 1;
-  await persistSnapshot(session);
-  notifyWaiters(session);
-}
-
-/**
- * 追加 shell 输出并同步更新快照。
- */
-export async function appendSessionOutput(
-  session: ShellSessionRuntimeState,
-  raw: string,
-): Promise<void> {
-  const text = normalizeOutputChunk(raw);
-  if (!text) return;
-
-  session.outputText += text;
-  if (session.outputText.length > MAX_IN_MEMORY_OUTPUT_CHARS) {
-    const overflow = session.outputText.length - MAX_IN_MEMORY_OUTPUT_CHARS;
-    session.outputText = session.outputText.slice(overflow);
-    session.snapshot.droppedChars += overflow;
-  }
-
-  session.snapshot.outputChars += text.length;
-  session.snapshot.lastOutputAt = nowMs();
-  session.snapshot.lastOutputPreview = session.outputText
-    .slice(-OUTPUT_PREVIEW_CHARS)
-    .trim();
-  session.snapshot.externalRefs = extractExternalRefsFromText(
-    text,
-    session.snapshot.externalRefs,
-  );
-  await enqueuePersistedAppend(session, text);
-  await updateSessionSnapshot(session, () => undefined);
-}
-
-/**
- * 为终态 shell 安排延迟清理。
- */
-export function scheduleCleanup(state: ShellPluginState, shellId: string): void {
-  const session = state.sessions.get(shellId);
-  if (!session) return;
-  if (session.cleanupTimer) clearTimeout(session.cleanupTimer);
-  session.cleanupTimer = setTimeout(() => {
-    const current = state.sessions.get(shellId);
-    if (!current) return;
-    state.sessions.delete(shellId);
-  }, SESSION_CLEANUP_DELAY_MS);
-  if (typeof session.cleanupTimer.unref === "function") {
-    session.cleanupTimer.unref();
-  }
-}
-
-/**
- * 控制 in-memory shell session 容量。
- */
-export function ensureCapacity(state: ShellPluginState): void {
-  if (state.sessions.size < MAX_ACTIVE_SHELLS) return;
-  const removable = Array.from(state.sessions.values())
-    .filter((item) => item.snapshot.status !== "running" && item.snapshot.status !== "starting")
-    .sort((a, b) => a.snapshot.updatedAt - b.snapshot.updatedAt);
-  for (const item of removable) {
-    if (state.sessions.size < MAX_ACTIVE_SHELLS) break;
-    state.sessions.delete(item.snapshot.shellId);
-  }
-  if (state.sessions.size >= MAX_ACTIVE_SHELLS) {
-    throw new Error(
-      `Too many active shell sessions (${state.sessions.size}). Please close or wait older sessions first.`,
-    );
-  }
-}
-
-async function loadPersistedSnapshot(
-  context: AgentContext,
-  shellId: string,
-): Promise<ShellSessionSnapshot | null> {
-  const file = getShellSnapshotPath(context.rootPath, shellId);
-  if (!(await fs.pathExists(file))) return null;
-  const raw = await fs.readJson(file).catch(() => null);
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
-  const snapshot = raw as ShellSessionSnapshot;
-  return typeof snapshot.shellId === "string" ? snapshot : null;
-}
-
-async function readPersistedOutput(
-  context: AgentContext,
-  shellId: string,
-): Promise<string> {
-  const file = getShellOutputPath(context.rootPath, shellId);
-  if (!(await fs.pathExists(file))) return "";
-  return await fs.readFile(file, "utf-8");
-}
-
-/**
- * 按 shellId 或 ownerContext 解析目标 session。
- */
-export async function resolveSession(
-  state: ShellPluginState,
-  context: AgentContext,
-  query: ShellQueryRequest,
-): Promise<ShellSessionRuntimeState | { snapshot: ShellSessionSnapshot; outputText: string } | null> {
-  const explicitShellId = String(query.shellId || "").trim();
-  if (explicitShellId) {
-    const inMemory = state.sessions.get(explicitShellId);
-    if (inMemory) return inMemory;
-    const snapshot = await loadPersistedSnapshot(context, explicitShellId);
-    if (!snapshot) return null;
-    return {
-      snapshot,
-      outputText: await readPersistedOutput(context, explicitShellId),
-    };
-  }
-
-  const ownerContextId = resolveOwnerContextId(query.ownerContextId);
-  const cmd = String(query.cmd || "").trim().toLowerCase();
-  if (!ownerContextId) return null;
-  const includeCompleted = query.includeCompleted === true;
-  const matched = Array.from(state.sessions.values())
-    .filter((item) => {
-      if (item.snapshot.ownerContextId !== ownerContextId) return false;
-      if (!includeCompleted) {
-        if (
-          item.snapshot.status !== "running" &&
-          item.snapshot.status !== "starting"
-        ) {
-          return false;
-        }
-      }
-      if (!cmd) return true;
-      return item.snapshot.cmd.toLowerCase().includes(cmd);
-    })
-    .sort((a, b) => b.snapshot.updatedAt - a.snapshot.updatedAt);
-  return matched[0] || null;
-}
-
-/**
- * 判断解析出的 session 是否仍在内存中活动。
- */
-export function isInMemorySession(
-  value: ShellSessionRuntimeState | { snapshot: ShellSessionSnapshot; outputText: string },
-): value is ShellSessionRuntimeState {
-  return "child" in value;
-}
-
-/**
- * 处理 shell 退出后的状态收口。
- */
-export async function finalizeExit(
-  state: ShellPluginState,
-  session: ShellSessionRuntimeState,
-  exitCode: number,
-): Promise<void> {
-  await updateSessionSnapshot(session, (snapshot) => {
-    snapshot.status = deriveExitStatus(exitCode);
-    snapshot.exitCode = exitCode;
-    snapshot.endedAt = nowMs();
-    snapshot.pid = session.child.pid ?? snapshot.pid;
-  });
-  session.resolveCompletion();
-  scheduleCleanup(state, session.snapshot.shellId);
-
-  if (
-    session.snapshot.autoNotifyOnExit &&
-    session.snapshot.notificationSent === false &&
-    state.boundRuntime
-  ) {
-    await emitChatCompletionEvent(state.boundRuntime, session.snapshot);
-    session.snapshot.notificationSent = true;
-    await persistSnapshot(session);
-  }
-}

package/src/plugin/builtins/shell/runtime/ShellProcessEvents.ts

@@ -1,65 +0,0 @@
-/**
- * Shell 子进程事件绑定辅助。
- *
- * 关键点（中文）
- * - 集中处理 stdout/stderr 追加、process error 与 close 事件。
- * - close 到达时先等待输出写入链 drain，再统一进入终态收口，避免尾部输出丢读。
- */
-
-import type { ShellPluginState, ShellSessionRuntimeState } from "@/plugin/builtins/shell/ShellRuntimeTypes.js";
-import {
-  appendSessionOutput,
-  finalizeExit,
-} from "./ShellActionRuntimeSupport.js";
-
-async function finalizeExitAfterOutputDrain(
-  state: ShellPluginState,
-  session: ShellSessionRuntimeState,
-  exitCode: number,
-): Promise<void> {
-  // 关键点（中文）
-  // - `close` 事件到达时，stdout / stderr 的异步 append 链可能刚刚开始收尾。
-  // - 这里先让出一个事件循环 tick，再等待当前 writeChain，可显著降低“终态已到但尾部输出尚未可读”的竞态。
-  await new Promise<void>((resolve) => {
-    const timer = setImmediate(resolve);
-    if (typeof timer.unref === "function") timer.unref();
-  });
-  await session.writeChain.catch(() => undefined);
-  await finalizeExit(state, session, exitCode);
-}
-
-/**
- * 绑定 shell 子进程事件。
- */
-export function attachShellProcessEventHandlers(params: {
-  /**
-   * 当前 shell service 状态。
-   */
-  state: ShellPluginState;
-  /**
-   * 当前 shell runtime session。
-   */
-  session: ShellSessionRuntimeState;
-}): void {
-  const { state, session } = params;
-  const { child } = session;
-  child.stdout.on("data", (chunk: string | Buffer) => {
-    void appendSessionOutput(session, String(chunk ?? "")).catch(() => undefined);
-  });
-  child.stderr.on("data", (chunk: string | Buffer) => {
-    void appendSessionOutput(session, String(chunk ?? "")).catch(() => undefined);
-  });
-  child.on("error", (error: Error) => {
-    void appendSessionOutput(session, `\n[process error] ${String(error)}\n`).catch(
-      () => undefined,
-    );
-    void finalizeExitAfterOutputDrain(state, session, -1).catch(() => undefined);
-  });
-  child.on("close", (code: number | null) => {
-    void finalizeExitAfterOutputDrain(
-      state,
-      session,
-      typeof code === "number" ? code : -1,
-    ).catch(() => undefined);
-  });
-}

package/src/plugin/builtins/shell/runtime/ShellRuntimeEnvironment.ts

@@ -1,75 +0,0 @@
-/**
- * Shell action 运行环境解析辅助。
- *
- * 关键点（中文）
- * - 集中处理 shell 子进程 cwd、env 与 owner context 的解析。
- * - 这里只做输入归一化，不持有 shell session 状态。
- */
-
-import path from "node:path";
-import type { AgentContext } from "@/core/AgentContextTypes.js";
-import { stripInvocationAuthEnv } from "@/runtime/server/http/auth/AuthEnv.js";
-import { getSessionRunScope } from "@session/SessionRunScope.js";
-
-/**
- * 构造 shell 子进程环境变量。
- */
-export function buildShellEnv(context: AgentContext): NodeJS.ProcessEnv {
-  const env: NodeJS.ProcessEnv = { ...process.env };
-
-  // 关键点（中文）
-  // - shell 子进程需要继承平台级 global env。
-  // - 这里显式从 store 读取，避免把 AgentContext.env 语义扩大成“全局+agent 混合态”。
-  // - 冲突时仍由后续 agent 私有 env 覆盖，保持文档声明的优先级。
-  for (const [key, value] of Object.entries(context.globalEnv || {})) {
-    const normalizedKey = String(key || "").trim();
-    const normalizedValue = String(value || "").trim();
-    if (!normalizedKey || !normalizedValue) continue;
-    env[normalizedKey] = normalizedValue;
-  }
-
-  for (const [key, value] of Object.entries(context.env || {})) {
-    const normalizedKey = String(key || "").trim();
-    const normalizedValue = String(value || "").trim();
-    if (!normalizedKey || !normalizedValue) continue;
-    env[normalizedKey] = normalizedValue;
-  }
-
-  const request = getSessionRunScope();
-  const sessionId = String(request?.sessionId || "").trim();
-  const agentPath = String(context.rootPath || "").trim();
-  const configuredAgentName = String(context.config?.name || "").trim();
-  const agentName = configuredAgentName || (agentPath ? path.basename(agentPath) : "");
-
-  // 关键点（中文）
-  // - agent 自己在 shell 里执行 `city <service> ...` 时，也需要显式知道“当前 agent 是谁”。
-  // - 否则 service CLI 会退回到当前终端 cwd / registry 猜测，在多 agent 或外部工作目录下
-  //   很容易把请求发到错误项目，最终误报 “Agent server 没启动”。
-  if (agentPath) env.DC_AGENT_PATH = agentPath;
-  if (agentName) env.DC_AGENT_NAME = agentName;
-  if (sessionId) env.DC_SESSION_ID = sessionId;
-  if (process.env.DC_SERVER_HOST) env.DC_CTX_SERVER_HOST = process.env.DC_SERVER_HOST;
-  if (process.env.DC_SERVER_PORT) env.DC_CTX_SERVER_PORT = process.env.DC_SERVER_PORT;
-  stripInvocationAuthEnv(env);
-
-  return env;
-}
-
-/**
- * 解析 shell 执行目录。
- */
-export function resolveShellCwd(context: AgentContext, cwd?: string): string {
-  const raw = String(cwd || "").trim();
-  if (!raw) return context.rootPath;
-  return path.isAbsolute(raw) ? raw : path.resolve(context.rootPath, raw);
-}
-
-/**
- * 推断 shell 所属的 owner context。
- */
-export function resolveOwnerContextId(explicit?: string): string | undefined {
-  const fromInput = String(explicit || "").trim();
-  if (fromInput) return fromInput;
-  const fromRequest = String(getSessionRunScope()?.sessionId || "").trim();
-  return fromRequest || undefined;
-}