@downcity/agent 1.1.10 → 1.1.12

package/src/service/builtins/shell/runtime/ShellActionResponse.ts

@@ -0,0 +1,135 @@
+/**
+ * Shell action 返回结构辅助。
+ *
+ * 关键点（中文）
+ * - 集中处理输出游标、token 近似裁剪与标准 action response。
+ * - 这里不读取文件、不修改 session，只基于传入文本构造返回对象。
+ */
+
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type {
+  ShellActionResponse,
+  ShellOutputChunk,
+  ShellSessionSnapshot,
+} from "@/service/builtins/shell/types/ShellService.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 } : {}),
+  };
+}

package/src/service/builtins/shell/runtime/ShellActionRuntime.ts

@@ -8,7 +8,7 @@
  */
 
 import fs from "fs-extra";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import { spawnShellProcess } from "@/sandbox/SandboxRunner.js";
 import type {
   ShellServiceState,
@@ -28,7 +28,6 @@ import type {
 } from "@/service/builtins/shell/types/ShellService.js";
 import { getShellDir, getShellOutputPath, getShellSnapshotPath } from "./Paths.js";
 import {
-  appendSessionOutput,
   buildActionResponse,
   buildShellEnv,
   clampWaitMs,
@@ -38,7 +37,6 @@ import {
   DEFAULT_INLINE_WAIT_MS,
   DEFAULT_WAIT_TIMEOUT_MS,
   ensureCapacity,
-  finalizeExit,
   isInMemorySession,
   isTerminalStatus,
   nowMs,
@@ -49,6 +47,7 @@ import {
   scheduleCleanup,
   updateSessionSnapshot,
 } from "./ShellActionRuntimeSupport.js";
+import { attachShellProcessEventHandlers } from "./ShellProcessEvents.js";
 
 export { createShellServiceState } from "./ShellActionRuntimeSupport.js";
 
@@ -90,22 +89,6 @@ export async function closeAllShellSessions(
   await Promise.all(closing);
 }
 
-async function finalizeExitAfterOutputDrain(
-  state: ShellServiceState,
-  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 session。
  */
@@ -192,25 +175,7 @@ export async function startShellSession(
   // - 监听器必须在任何 `await` 之前挂上。
   // - 对于 `printf` 这类瞬时命令，进程可能在持久化 snapshot 期间就已经退出。
   // - 如果先 `await persistSnapshot()` 再注册 `close`，会错过退出事件，导致 session 永远停在 running。
-  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);
-  });
+  attachShellProcessEventHandlers({ state, session });
   await persistSnapshot(session);
 
   const inlineWaitMs = clampWaitMs(request.inlineWaitMs, DEFAULT_INLINE_WAIT_MS);

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

@@ -8,31 +8,33 @@
 
 import path from "node:path";
 import fs from "fs-extra";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import { stripInvocationAuthEnv } from "@/host/http/auth/AuthEnv.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type {
   ShellServiceState,
   ShellSessionRuntimeState,
-  ShellSessionWaiter,
 } from "@/service/builtins/shell/ShellRuntimeTypes.js";
-import { getSessionRunScope } from "@session/SessionRunScope.js";
 import type {
-  ShellActionResponse,
-  ShellOutputChunk,
   ShellQueryRequest,
   ShellSessionSnapshot,
   ShellSessionStatus,
 } from "@/service/builtins/shell/types/ShellService.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 DEFAULT_MAX_OUTPUT_CHARS = 12_000;
-const DEFAULT_MAX_OUTPUT_LINES = 200;
-const APPROX_CHARS_PER_TOKEN = 4;
 const OUTPUT_PREVIEW_CHARS = 280;
 
 /**
@@ -85,110 +87,6 @@ function normalizeOutputChunk(raw: string): string {
     .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "");
 }
 
-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),
-  };
-}
-
-/**
- * 构造 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;
-}
-
 function deriveExitStatus(exitCode: number | undefined): ShellSessionStatus {
   if (exitCode === -9 || exitCode === 137) return "killed";
   if (typeof exitCode === "number" && exitCode === 0) return "completed";
@@ -462,58 +360,6 @@ export async function resolveSession(
   return matched[0] || null;
 }
 
-/**
- * 根据游标与 token 限制构造输出块。
- */
-export function createOutputChunk(params: {
-  shellId: string;
-  outputText: string;
-  fromCursor?: number;
-  context: AgentContext;
-  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: ShellSessionSnapshot;
-  chunk?: ShellOutputChunk;
-  note?: string;
-}): ShellActionResponse {
-  return {
-    shell: params.shell,
-    ...(params.chunk ? { chunk: params.chunk } : {}),
-    ...(params.note ? { note: params.note } : {}),
-  };
-}
-
 /**
  * 判断解析出的 session 是否仍在内存中活动。
  */

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

@@ -0,0 +1,65 @@
+/**
+ * Shell 子进程事件绑定辅助。
+ *
+ * 关键点（中文）
+ * - 集中处理 stdout/stderr 追加、process error 与 close 事件。
+ * - close 到达时先等待输出写入链 drain，再统一进入终态收口，避免尾部输出丢读。
+ */
+
+import type { ShellServiceState, ShellSessionRuntimeState } from "@/service/builtins/shell/ShellRuntimeTypes.js";
+import {
+  appendSessionOutput,
+  finalizeExit,
+} from "./ShellActionRuntimeSupport.js";
+
+async function finalizeExitAfterOutputDrain(
+  state: ShellServiceState,
+  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: ShellServiceState;
+  /**
+   * 当前 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/service/builtins/shell/runtime/ShellRuntimeEnvironment.ts

@@ -0,0 +1,75 @@
+/**
+ * Shell action 运行环境解析辅助。
+ *
+ * 关键点（中文）
+ * - 集中处理 shell 子进程 cwd、env 与 owner context 的解析。
+ * - 这里只做输入归一化，不持有 shell session 状态。
+ */
+
+import path from "node:path";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import { stripInvocationAuthEnv } from "@/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;
+}

package/src/service/builtins/task/Action.ts

@@ -8,8 +8,8 @@
 
 import path from "node:path";
 import type { ShipTaskStatus } from "./types/Task.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
-import type { JsonValue } from "@/utils/types/Json.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
+import type { JsonValue } from "@/types/common/Json.js";
 import {
   deriveTaskIdFromTitle,
   normalizeTaskId,

package/src/service/builtins/task/Scheduler.ts

@@ -6,7 +6,7 @@
  * - cron 调度执行器由 server 注入，service 不依赖具体实现。
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import {
   isTaskWhenManual,
   resolveTaskWhenCronExpression,

package/src/service/builtins/task/TaskService.ts

@@ -7,10 +7,10 @@
  * - 当前文件只保留实例骨架与 lifecycle，不再依赖旧的模块级 `taskService` 单例。
  */
 
-import type { AgentRuntime } from "@/agent/AgentRuntimeTypes.js";
+import type { AgentRuntime } from "@/runtime/AgentRuntimeTypes.js";
 import { BaseService } from "@/service/builtins/BaseService.js";
 import type { ServiceActions } from "@/service/types/Service.js";
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import type {
   TaskCronRegisterResult,
   TaskSchedulerReloadResult,

package/src/service/builtins/task/runtime/CronRuntime.ts

@@ -6,7 +6,7 @@
  * - 该模块是 task service 内部实现细节，core 只通过 service lifecycle 间接调用。
  */
 
-import type { AgentContext } from "@/agent/AgentContextTypes.js";
+import type { AgentContext } from "@/runtime/AgentContextTypes.js";
 import { registerTaskCronJobs } from "@/service/builtins/task/Scheduler.js";
 import { TaskCronTriggerEngine } from "./CronTrigger.js";
 

package/src/service/builtins/task/runtime/Model.ts

@@ -17,7 +17,7 @@ import type {
   ShipTaskKind,
   ShipTaskStatus,
 } from "@/service/builtins/task/types/Task.js";
-import type { JsonObject, JsonValue } from "@/utils/types/Json.js";
+import type { JsonObject, JsonValue } from "@/types/common/Json.js";
 
 /**
  * 必填 frontmatter 字段清单。

package/src/service/builtins/task/runtime/Paths.ts

@@ -6,7 +6,7 @@
  * - definition: `./.downcity/task/<taskId>/task.md`
  * - run dir: `./.downcity/task/<taskId>/<timestamp>/`
  *
- * 同时定义“task run sessionId”格式，用于把 Agent 的 sessionFacade 映射到 run 目录：
+ * 同时定义“task run sessionId”格式，用于把 Agent 的 session 映射到 run 目录：
  * - `task-run:<taskId>:<timestamp>`
  */