@downcity/plugins 1.0.66 → 1.0.71

package/src/shell/ShellPlugin.ts

@@ -1,239 +0,0 @@
-/**
- * ShellPlugin：shell plugin 的类实现。
- *
- * 关键点（中文）
- * - shell session map 与 bound runtime 都归属于 plugin 实例。
- * - agent 持有 ShellPlugin 实例，从而形成 per-agent shell 状态边界。
- * - ShellActionRuntime 只保留纯运行时流程，不再承载模块级单例状态。
- */
-
-import { BasePlugin } from "@downcity/agent/internal/plugin/core/BasePlugin.js";
-import type { PluginActions } from "@downcity/agent/internal/plugin/types/Plugin.js";
-import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
-import type {
-  ShellPluginState,
-  ShellSessionRuntimeState,
-} from "@/shell/ShellRuntimeTypes.js";
-import type { ShellPluginOptions } from "@/shell/types/ShellPluginOptions.js";
-import type {
-  ShellCloseRequest,
-  ShellExecRequest,
-  ShellQueryRequest,
-  ShellReadRequest,
-  ShellStartRequest,
-  ShellWaitRequest,
-  ShellWriteRequest,
-} from "@downcity/agent/internal/executor/tools/shell/types/ShellPlugin.js";
-import {
-  bindShellRuntime,
-  closeAllShellSessions,
-  closeShellSession,
-  createShellPluginState,
-  approveShellApproval,
-  denyShellApproval,
-  execShellCommand,
-  getShellSessionStatus,
-  listShellApprovals,
-  readShellSession,
-  startShellSession,
-  waitShellSession,
-  writeShellSession,
-} from "./runtime/ShellActionRuntime.js";
-
-/**
- * Shell plugin 类实现。
- */
-export class ShellPlugin extends BasePlugin {
-  /**
-   * plugin 名称。
-   */
-  readonly name = "shell";
-
-  /**
-   * 当前实例持有的 shell 状态对象。
-   */
-  private readonly state: ShellPluginState;
-
-  /**
-   * 当前实例暴露的 action 定义表。
-   */
-  readonly actions: PluginActions;
-
-  /**
-   * 当前实例持有的 in-memory shell sessions。
-   */
-  public readonly sessions: Map<string, ShellSessionRuntimeState>;
-
-  constructor(options: ShellPluginOptions = {}) {
-    super();
-    this.state = createShellPluginState(options);
-    this.sessions = this.state.sessions;
-    this.actions = {
-      exec: {
-        execute: async (params) => ({
-          success: true,
-          data: await this.exec(params.context, params.payload as ShellExecRequest),
-        }),
-      },
-      start: {
-        execute: async (params) => ({
-          success: true,
-          data: await this.start(params.context, params.payload as ShellStartRequest),
-        }),
-      },
-      status: {
-        execute: async (params) => ({
-          success: true,
-          data: await this.status(params.context, params.payload as ShellQueryRequest),
-        }),
-      },
-      read: {
-        execute: async (params) => ({
-          success: true,
-          data: await this.read(params.context, params.payload as ShellReadRequest),
-        }),
-      },
-      write: {
-        execute: async (params) => ({
-          success: true,
-          data: await this.write(params.context, params.payload as ShellWriteRequest),
-        }),
-      },
-      wait: {
-        execute: async (params) => ({
-          success: true,
-          data: await this.wait(params.context, params.payload as ShellWaitRequest),
-        }),
-      },
-      close: {
-        execute: async (params) => ({
-          success: true,
-          data: await this.close(params.context, params.payload as ShellCloseRequest),
-        }),
-      },
-      approvals: {
-        execute: async () => ({
-          success: true,
-          data: { approvals: listShellApprovals(this.state) },
-        }),
-      },
-      approve: {
-        execute: async (params) => {
-          const payload = params.payload as { approvalId?: unknown; approval_id?: unknown };
-          const approvalId = String(payload?.approvalId || payload?.approval_id || "").trim();
-          if (!approvalId) {
-            return { success: false, error: "approvalId is required" };
-          }
-          const ok = await approveShellApproval(this.state, params.context, approvalId);
-          return {
-            success: ok,
-            data: { approvalId, approved: ok },
-            ...(ok ? {} : { error: "approval request not found" }),
-          };
-        },
-      },
-      deny: {
-        execute: async (params) => {
-          const payload = params.payload as { approvalId?: unknown; approval_id?: unknown };
-          const approvalId = String(payload?.approvalId || payload?.approval_id || "").trim();
-          if (!approvalId) {
-            return { success: false, error: "approvalId is required" };
-          }
-          const ok = await denyShellApproval(this.state, params.context, approvalId);
-          return {
-            success: ok,
-            data: { approvalId, denied: ok },
-            ...(ok ? {} : { error: "approval request not found" }),
-          };
-        },
-      },
-    };
-
-    this.lifecycle = {
-      start: async (context) => {
-        bindShellRuntime(this.state, context);
-      },
-      stop: async () => {
-        await closeAllShellSessions(this.state, true);
-        for (const session of this.state.sessions.values()) {
-          if (session.cleanupTimer) {
-            clearTimeout(session.cleanupTimer);
-          }
-        }
-        this.state.sessions.clear();
-        this.state.approvals.clear();
-        this.state.context = null;
-      },
-    };
-  }
-
-  /**
-   * 启动一个 shell session。
-   */
-  async start(
-    context: AgentContext,
-    request: ShellStartRequest,
-  ) {
-    return await startShellSession(this.state, context, request);
-  }
-
-  /**
-   * 查询 shell session 状态。
-   */
-  async status(
-    context: AgentContext,
-    request: ShellQueryRequest,
-  ) {
-    return await getShellSessionStatus(this.state, context, request);
-  }
-
-  /**
-   * 读取 shell session 输出。
-   */
-  async read(
-    context: AgentContext,
-    request: ShellReadRequest,
-  ) {
-    return await readShellSession(this.state, context, request);
-  }
-
-  /**
-   * 向 shell session 写入 stdin。
-   */
-  async write(
-    context: AgentContext,
-    request: ShellWriteRequest,
-  ) {
-    return await writeShellSession(this.state, context, request);
-  }
-
-  /**
-   * 等待 shell session 状态变化。
-   */
-  async wait(
-    context: AgentContext,
-    request: ShellWaitRequest,
-  ) {
-    return await waitShellSession(this.state, context, request);
-  }
-
-  /**
-   * 关闭 shell session。
-   */
-  async close(
-    context: AgentContext,
-    request: ShellCloseRequest,
-  ) {
-    return await closeShellSession(this.state, context, request);
-  }
-
-  /**
-   * 执行一次 one-shot shell command。
-   */
-  async exec(
-    context: AgentContext,
-    request: ShellExecRequest,
-  ) {
-    return await execShellCommand(this.state, context, request);
-  }
-}

package/src/shell/ShellRuntimeTypes.ts

@@ -1,168 +0,0 @@
-/**
- * ShellRuntime 类型定义。
- *
- * 关键点（中文）
- * - 这些类型描述 shell plugin runtime 的实例级运行态。
- * - 状态所有权归属于 `ShellPlugin` 实例，而不是模块级单例。
- * - 统一归档到 `src/shell/` 相邻层级，避免继续分散在跨域目录里。
- */
-
-import type { ChildProcessWithoutNullStreams } from "node:child_process";
-import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
-import type {
-  ShellApprovalStatus,
-  ShellApprovalToolName,
-  ShellSessionSnapshot,
-} from "@downcity/agent/internal/executor/tools/shell/types/ShellPlugin.js";
-import type { ResolvedShellPluginOptions } from "@/shell/types/ShellPluginOptions.js";
-
-/**
- * unrestricted sandbox 审批运行态。
- */
-export type ShellApprovalRuntimeState = {
-  /**
-   * 当前审批请求 ID。
-   */
-  approvalId: string;
-  /**
-   * 关联的 shell_id。
-   */
-  shellId: string;
-  /**
-   * 所属 session/聊天上下文。
-   */
-  ownerContextId?: string;
-  /**
-   * 关联工具名。
-   */
-  toolName: ShellApprovalToolName;
-  /**
-   * 申请执行的命令。
-   *
-   * 说明（中文）
-   * - `shell_write` 使用该字段保存 stdin 写入预览，保持审批队列结构统一。
-   */
-  cmd: string;
-  /**
-   * 审批动作类型。
-   */
-  operation: "exec" | "start" | "write";
-  /**
-   * stdin 写入内容预览；仅 `shell_write` 审批存在。
-   */
-  inputPreview?: string;
-  /**
-   * stdin 写入字符数；仅 `shell_write` 审批存在。
-   */
-  inputChars?: number;
-  /**
-   * 命令执行目录。
-   */
-  cwd: string;
-  /**
-   * 申请原因。
-   */
-  reason: string;
-  /**
-   * 当前审批创建时间。
-   */
-  createdAt: number;
-  /**
-   * 审批超时定时器。
-   */
-  timer: NodeJS.Timeout;
-  /**
-   * 兑现审批结果。
-   */
-  resolve: (status: ShellApprovalStatus) => void;
-};
-
-/**
- * 单个 shell wait 调用挂起时注册的 waiter。
- */
-export type ShellSessionWaiter = {
-  /**
-   * 当前等待完成后的唤醒回调。
-   */
-  resolve: () => void;
-  /**
-   * 当前 waiter 对应的超时定时器。
-   */
-  timer: NodeJS.Timeout;
-};
-
-/**
- * 单个 shell session 的内存运行态。
- */
-export type ShellSessionRuntimeState = {
-  /**
-   * 当前 shell session 的对外快照。
-   */
-  snapshot: ShellSessionSnapshot;
-  /**
-   * 当前 shell session 对应的子进程句柄。
-   */
-  child: ChildProcessWithoutNullStreams;
-  /**
-   * 当前已缓存的标准输出与标准错误文本。
-   */
-  outputText: string;
-  /**
-   * 当前输出持久化文件路径。
-   */
-  outputFilePath: string;
-  /**
-   * 当前快照持久化文件路径。
-   */
-  snapshotFilePath: string;
-  /**
-   * 串行化文件写入链，避免并发 append 乱序。
-   */
-  writeChain: Promise<void>;
-  /**
-   * 终态后的延迟清理定时器。
-   */
-  cleanupTimer: NodeJS.Timeout | null;
-  /**
-   * 当前挂起等待该 session 状态变化的 waiter 集合。
-   */
-  waiters: Set<ShellSessionWaiter>;
-  /**
-   * 当前 shell 进入终态后的完成 promise。
-   *
-   * 关键点（中文）
-   * - 供 `shell.exec` 这类 one-shot 路径直接等待进程结束。
-   * - 这样可以减少对版本轮询的依赖，降低瞬时命令的竞态超时。
-   */
-  completionPromise: Promise<void>;
-  /**
-   * 当前 shell 进入终态时触发的完成回调。
-   */
-  resolveCompletion: () => void;
-};
-
-/**
- * `ShellPlugin` 实例级状态。
- */
-export type ShellPluginState = {
-  /**
-   * 当前 shell plugin 归一化后的运行参数。
-   */
-  options: ResolvedShellPluginOptions;
-  /**
-   * 当前实例持有的全部 in-memory shell session。
-   */
-  sessions: Map<string, ShellSessionRuntimeState>;
-  /**
-   * 当前实例持有的全部 pending unrestricted sandbox 审批。
-   */
-  approvals: Map<string, ShellApprovalRuntimeState>;
-  /**
-   * 当前实例最近一次启动时绑定的 agent context。
-   *
-   * 关键点（中文）
-   * - 仅用于 shell 自动通知 chat 的回调路径。
-   * - 这是实例字段，不再是模块级全局变量。
-   */
-  context: AgentContext | null;
-};

package/src/shell/runtime/Paths.ts

@@ -1,28 +0,0 @@
-/**
- * Shell service 路径工具。
- *
- * 关键点（中文）
- * - shell 运行产物统一落在 `.downcity/shell/<shellId>/`。
- * - 目录结构简单稳定，便于调试与后续恢复。
- */
-
-import path from "node:path";
-
-export function getShellRootDir(projectRoot: string): string {
-  return path.join(projectRoot, ".downcity", "shell");
-}
-
-export function getShellDir(projectRoot: string, shellId: string): string {
-  return path.join(getShellRootDir(projectRoot), String(shellId || "").trim());
-}
-
-export function getShellSnapshotPath(
-  projectRoot: string,
-  shellId: string,
-): string {
-  return path.join(getShellDir(projectRoot, shellId), "snapshot.json");
-}
-
-export function getShellOutputPath(projectRoot: string, shellId: string): string {
-  return path.join(getShellDir(projectRoot, shellId), "output.log");
-}

package/src/shell/runtime/ShellActionResponse.ts

@@ -1,135 +0,0 @@
-/**
- * Shell action 返回结构辅助。
- *
- * 关键点（中文）
- * - 集中处理输出游标、token 近似裁剪与标准 action response。
- * - 这里不读取文件、不修改 session，只基于传入文本构造返回对象。
- */
-
-import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
-import type {
-  ShellActionResponse,
-  ShellOutputChunk,
-  ShellSessionSnapshot,
-} from "@downcity/agent/internal/executor/tools/shell/types/ShellPlugin.js";
-
-const DEFAULT_MAX_OUTPUT_CHARS = 12_000;
-const DEFAULT_MAX_OUTPUT_LINES = 200;
-const APPROX_CHARS_PER_TOKEN = 4;
-
-function resolveOutputLimits(params: {
-  context: AgentContext;
-  maxOutputTokens?: number;
-}): {
-  maxChars: number;
-  maxLines: number;
-} {
-  const byTokens =
-    typeof params.maxOutputTokens === "number" &&
-    Number.isFinite(params.maxOutputTokens) &&
-    params.maxOutputTokens > 0
-      ? Math.max(200, Math.floor(params.maxOutputTokens * APPROX_CHARS_PER_TOKEN))
-      : null;
-  return {
-    maxChars:
-      byTokens == null
-        ? DEFAULT_MAX_OUTPUT_CHARS
-        : Math.min(DEFAULT_MAX_OUTPUT_CHARS, byTokens),
-    maxLines: DEFAULT_MAX_OUTPUT_LINES,
-  };
-}
-
-function splitOutputByLimits(
-  text: string,
-  maxChars: number,
-  maxLines: number,
-): { head: string; tail: string } {
-  const limitedByChars = text.slice(0, Math.min(text.length, maxChars));
-  let head = limitedByChars;
-  if (maxLines > 0) {
-    const lines = limitedByChars.split("\n");
-    if (lines.length > maxLines) {
-      head = lines.slice(0, maxLines).join("\n");
-    }
-  }
-  return {
-    head,
-    tail: text.slice(head.length),
-  };
-}
-
-/**
- * 根据游标与 token 限制构造输出块。
- */
-export function createOutputChunk(params: {
-  /**
-   * 当前 shell session 标识。
-   */
-  shellId: string;
-  /**
-   * 当前完整输出文本。
-   */
-  outputText: string;
-  /**
-   * 本次读取起始游标。
-   */
-  fromCursor?: number;
-  /**
-   * 当前 Agent 执行上下文。
-   */
-  context: AgentContext;
-  /**
-   * 输出 token 近似上限。
-   */
-  maxOutputTokens?: number;
-}): ShellOutputChunk {
-  const fromCursor =
-    typeof params.fromCursor === "number" && params.fromCursor >= 0
-      ? Math.floor(params.fromCursor)
-      : 0;
-  const available = params.outputText.slice(fromCursor);
-  const originalChars = available.length;
-  const originalLines = available ? available.split("\n").length : 0;
-  const limits = resolveOutputLimits({
-    context: params.context,
-    maxOutputTokens: params.maxOutputTokens,
-  });
-  const { head, tail } = splitOutputByLimits(
-    available,
-    limits.maxChars,
-    limits.maxLines,
-  );
-  return {
-    shellId: params.shellId,
-    output: head,
-    startCursor: fromCursor,
-    endCursor: fromCursor + head.length,
-    originalChars,
-    originalLines,
-    hasMoreOutput: tail.length > 0,
-  };
-}
-
-/**
- * 构造 shell action 标准返回。
- */
-export function buildActionResponse(params: {
-  /**
-   * 当前 shell 快照。
-   */
-  shell: ShellSessionSnapshot;
-  /**
-   * 可选输出块。
-   */
-  chunk?: ShellOutputChunk;
-  /**
-   * 可选人类可读提示。
-   */
-  note?: string;
-}): ShellActionResponse {
-  return {
-    shell: params.shell,
-    ...(params.chunk ? { chunk: params.chunk } : {}),
-    ...(params.note ? { note: params.note } : {}),
-  };
-}