@downcity/agent 1.1.1

package/src/daemon/Manager.ts

@@ -0,0 +1,344 @@
+/**
+ * Downcity daemon 管理（PID / 日志 / 启停）。
+ *
+ * 目标
+ * - `downcity agent start`：后台启动（终端退出后仍运行）
+ * - `downcity agent restart`：重启后台进程
+ *
+ * 约定
+ * - 所有 daemon 相关文件都写入 `.downcity/debug/`，便于排查：
+ *   - `downcity.pid`：进程 pid
+ *   - `downcity.daemon.log`：stdout/stderr 合并日志
+ *   - `downcity.daemon.json`：元数据（启动时间、参数等）
+ */
+
+import fs from "fs-extra";
+import path from "path";
+import { spawn } from "child_process";
+import { getDowncityDebugDirPath } from "@/config/Paths.js";
+import {
+  DAEMON_LOG_FILENAME,
+  DAEMON_META_FILENAME,
+  DAEMON_PID_FILENAME,
+  type DaemonMeta,
+  type DaemonStaleReason,
+} from "@/shared/types/Daemon.js";
+import {
+  markConsoleAgentStopped,
+  upsertConsoleAgentEntry,
+} from "@/runtime/CityRegistry.js";
+import { signalDetachedProcess } from "@/runtime/ProcessSweep.js";
+
+/**
+ * 异步睡眠工具。
+ */
+const sleep = async (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * 计算 daemon pid 文件路径。
+ */
+export const getDaemonPidPath = (projectRoot: string): string =>
+  path.join(getDowncityDebugDirPath(projectRoot), DAEMON_PID_FILENAME);
+
+/**
+ * 计算 daemon 日志文件路径。
+ */
+export const getDaemonLogPath = (projectRoot: string): string =>
+  path.join(getDowncityDebugDirPath(projectRoot), DAEMON_LOG_FILENAME);
+
+/**
+ * 计算 daemon 元数据文件路径。
+ */
+export const getDaemonMetaPath = (projectRoot: string): string =>
+  path.join(getDowncityDebugDirPath(projectRoot), DAEMON_META_FILENAME);
+
+/**
+ * 读取 daemon pid。
+ *
+ * 关键点（中文）
+ * - 读取失败或内容非法统一返回 `null`，调用方走无进程分支。
+ */
+export const readDaemonPid = async (
+  projectRoot: string,
+): Promise<number | null> => {
+  try {
+    const raw = await fs.readFile(getDaemonPidPath(projectRoot), "utf-8");
+    const pid = Number.parseInt(String(raw).trim(), 10);
+    return Number.isFinite(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * 检查进程是否存活。
+ */
+export const isProcessAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * 读取 daemon meta（宽松模式）。
+ *
+ * 关键点（中文）
+ * - 返回 null 表示文件缺失、解析失败或结构非法。
+ * - 该函数用于状态展示，不抛异常。
+ */
+export const readDaemonMeta = async (
+  projectRoot: string,
+): Promise<DaemonMeta | null> => {
+  try {
+    const value = await fs.readJson(getDaemonMetaPath(projectRoot));
+    const pid = Number((value as { pid?: unknown })?.pid);
+    if (!Number.isFinite(pid) || pid <= 0) return null;
+    const startedAt = String(
+      (value as { startedAt?: unknown })?.startedAt || "",
+    ).trim();
+    if (!startedAt) return null;
+    const command = String(
+      (value as { command?: unknown })?.command || "",
+    ).trim();
+    const project = String(
+      (value as { projectRoot?: unknown })?.projectRoot || "",
+    ).trim();
+    if (!command || !project) return null;
+    return value as DaemonMeta;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * 诊断 stale 原因。
+ */
+export const diagnoseDaemonStaleReasons = async (
+  projectRoot: string,
+  pid: number,
+): Promise<DaemonStaleReason[]> => {
+  const reasons: DaemonStaleReason[] = [];
+  reasons.push({
+    code: "process_not_alive",
+    message: "pid file exists but process is not alive",
+  });
+
+  const metaPath = getDaemonMetaPath(projectRoot);
+  const metaExists = await fs.pathExists(metaPath);
+  if (!metaExists) {
+    reasons.push({
+      code: "meta_missing",
+      message: "daemon meta file is missing",
+    });
+    return reasons;
+  }
+
+  try {
+    await fs.readJson(metaPath);
+  } catch {
+    reasons.push({
+      code: "meta_invalid",
+      message: "daemon meta file is invalid JSON",
+    });
+    return reasons;
+  }
+
+  const parsedMeta = await readDaemonMeta(projectRoot);
+  if (!parsedMeta) {
+    reasons.push({
+      code: "meta_invalid",
+      message: "daemon meta file has invalid structure",
+    });
+    return reasons;
+  }
+
+  if (parsedMeta.pid !== pid) {
+    reasons.push({
+      code: "meta_pid_mismatch",
+      message: `meta pid (${parsedMeta.pid}) does not match pid file (${pid})`,
+    });
+  }
+
+  const metaProjectRoot = path.resolve(String(parsedMeta.projectRoot || ""));
+  const expectedProjectRoot = path.resolve(projectRoot);
+  if (metaProjectRoot !== expectedProjectRoot) {
+    reasons.push({
+      code: "meta_project_mismatch",
+      message: `meta project root mismatch (${metaProjectRoot})`,
+    });
+  }
+
+  return reasons;
+};
+
+/**
+ * 清理僵尸 daemon 标记文件。
+ *
+ * 算法（中文）
+ * - 若 pid 文件存在但进程不存在，移除 pid/meta，恢复可重启状态。
+ */
+export const cleanupStaleDaemonFiles = async (
+  projectRoot: string,
+): Promise<void> => {
+  const pid = await readDaemonPid(projectRoot);
+  if (!pid) return;
+  if (isProcessAlive(pid)) return;
+
+  // 关键注释：pid 文件存在但进程已退出，属于“脏状态”，这里直接清理。
+  await fs.remove(getDaemonPidPath(projectRoot));
+  await fs.remove(getDaemonMetaPath(projectRoot));
+  // 关键点（中文）：僵尸 daemon 清理时标记 stopped，保留历史记录。
+  try {
+    await markConsoleAgentStopped(projectRoot);
+  } catch {
+    // ignore registry sync errors
+  }
+};
+
+/**
+ * 写入 daemon pid 与元数据文件。
+ */
+export const writeDaemonFiles = async (
+  projectRoot: string,
+  meta: DaemonMeta,
+): Promise<void> => {
+  await fs.ensureDir(getDowncityDebugDirPath(projectRoot));
+  await fs.writeFile(getDaemonPidPath(projectRoot), String(meta.pid), "utf-8");
+  await fs.writeJson(getDaemonMetaPath(projectRoot), meta, { spaces: 2 });
+};
+
+/**
+ * 启动 daemon 子进程。
+ *
+ * 流程（中文）
+ * 1) 清理脏 pid/meta
+ * 2) 检查是否已有存活 daemon
+ * 3) detached + unref 拉起 `node cli.js run ...`
+ * 4) 写入 pid/meta 供 stop/restart 使用
+ */
+export const startDaemonProcess = async (params: {
+  projectRoot: string;
+  cliPath: string;
+  args: string[];
+}): Promise<{ pid: number; logPath: string }> => {
+  const { projectRoot, cliPath, args } = params;
+
+  await fs.ensureDir(getDowncityDebugDirPath(projectRoot));
+  await cleanupStaleDaemonFiles(projectRoot);
+
+  const existingPid = await readDaemonPid(projectRoot);
+  if (existingPid && isProcessAlive(existingPid)) {
+    throw new Error(`Daemon already running (pid: ${existingPid})`);
+  }
+
+  const logPath = getDaemonLogPath(projectRoot);
+  const logFd = fs.openSync(logPath, "a");
+
+  const childEnv: NodeJS.ProcessEnv = {
+    ...process.env,
+    DOWNCITY_DAEMON: "1",
+  };
+
+  // 关键注释：daemon 进程必须 detached + unref 才能在父进程退出后继续运行。
+  const child = spawn(process.execPath, [cliPath, ...args], {
+    cwd: projectRoot,
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    env: childEnv,
+  });
+
+  child.unref();
+
+  if (!child.pid) {
+    throw new Error("Failed to start daemon process (missing pid)");
+  }
+
+  await writeDaemonFiles(projectRoot, {
+    pid: child.pid,
+    projectRoot,
+    startedAt: new Date().toISOString(),
+    command: process.execPath,
+    args: [cliPath, ...args],
+    node: process.version,
+    platform: process.platform,
+  });
+
+  // 关键点（中文）：启动成功后必须登记到 console registry，否则该 daemon 视为“无效启动”。
+  try {
+    await upsertConsoleAgentEntry({
+      projectRoot,
+      pid: child.pid,
+      status: "running",
+    });
+  } catch (error) {
+    // 回滚：无法登记时立即停止 daemon 并清理状态文件。
+    signalDetachedProcess(child.pid, "SIGTERM");
+    await sleep(300);
+    try {
+      if (isProcessAlive(child.pid)) signalDetachedProcess(child.pid, "SIGKILL");
+    } catch {
+      // ignore
+    }
+    await fs.remove(getDaemonPidPath(projectRoot));
+    await fs.remove(getDaemonMetaPath(projectRoot));
+    throw error;
+  }
+
+  return { pid: child.pid, logPath };
+};
+
+/**
+ * 停止 daemon 子进程。
+ *
+ * 策略（中文）
+ * - 先发 `SIGTERM` 做优雅退出；超时后回退 `SIGKILL`。
+ * - 无论 stop 结果如何，最终清理 pid/meta，避免状态残留。
+ */
+export const stopDaemonProcess = async (params: {
+  projectRoot: string;
+  timeoutMs?: number;
+}): Promise<{ stopped: boolean; pid?: number }> => {
+  const { projectRoot, timeoutMs = 10_000 } = params;
+
+  await cleanupStaleDaemonFiles(projectRoot);
+  const pid = await readDaemonPid(projectRoot);
+  if (!pid) return { stopped: false };
+
+  if (!isProcessAlive(pid)) {
+    await fs.remove(getDaemonPidPath(projectRoot));
+    await fs.remove(getDaemonMetaPath(projectRoot));
+    return { stopped: false, pid };
+  }
+
+  signalDetachedProcess(pid, "SIGTERM");
+
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (!isProcessAlive(pid)) break;
+    await sleep(200);
+  }
+
+  if (isProcessAlive(pid)) {
+    // 关键注释：尽量优雅停止，超时后再强杀，避免后台进程“卡死”。
+    try {
+      signalDetachedProcess(pid, "SIGKILL");
+    } catch {
+      // ignore
+    }
+  }
+
+  await fs.remove(getDaemonPidPath(projectRoot));
+  await fs.remove(getDaemonMetaPath(projectRoot));
+  // 关键点（中文）：停止后标记为 stopped，保留历史记录。
+  try {
+    await markConsoleAgentStopped(projectRoot);
+  } catch {
+    // ignore registry sync errors
+  }
+
+  return { stopped: true, pid };
+};

package/src/daemon/ProjectSetup.ts

@@ -0,0 +1,126 @@
+/**
+ * ProjectSetup：runtime 启动前项目结构准备模块。
+ *
+ * 关键点（中文）
+ * - 统一校验初始化必要文件（PROFILE.md / downcity.json）。
+ * - 统一确保 `.downcity/*` 目录结构存在，避免调用方重复拼装目录逻辑。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import { loadDowncityConfig } from "@/config/Config.js";
+import { ConsoleStore } from "@/shared/utils/store/index.js";
+import {
+  readProjectExecutionBinding,
+  readProjectPrimaryModelId,
+} from "@/agent/project/ProjectExecutionBinding.js";
+import {
+  getCacheDirPath,
+  getLogsDirPath,
+  getProfileMdPath,
+  getDowncityConfigDirPath,
+  getDowncityDataDirPath,
+  getDowncityDebugDirPath,
+  getDowncityDirPath,
+  getDowncityJsonPath,
+  getDowncityProfileDirPath,
+  getDowncityPublicDirPath,
+  getDowncitySessionRootDirPath,
+  getDowncityTasksDirPath,
+} from "@/config/Paths.js";
+
+/**
+ * 校验项目初始化关键文件。
+ */
+function ensureContextFiles(projectRoot: string): void {
+  // Check if initialized（启动入口一次性确认工程根目录与关键文件）
+  if (!fs.existsSync(getProfileMdPath(projectRoot))) {
+    console.error(
+      '❌ Project not initialized. Please run "city agent create" first',
+    );
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(getDowncityJsonPath(projectRoot))) {
+    console.error(
+      '❌ downcity.json does not exist. Please run "city agent create" first',
+    );
+    process.exit(1);
+  }
+}
+
+/**
+ * 确保 `.downcity` 运行目录结构完整。
+ */
+function ensureShipDirectories(projectRoot: string): void {
+  // 关键点（中文）：尽量只在启动时确保目录结构存在，避免在 Agent/Tool 执行过程中反复 ensure。
+  fs.ensureDirSync(getDowncityDirPath(projectRoot));
+  fs.ensureDirSync(getDowncityTasksDirPath(projectRoot));
+  fs.ensureDirSync(getLogsDirPath(projectRoot));
+  fs.ensureDirSync(getCacheDirPath(projectRoot));
+  fs.ensureDirSync(getDowncityProfileDirPath(projectRoot));
+  fs.ensureDirSync(getDowncityDataDirPath(projectRoot));
+  fs.ensureDirSync(getDowncitySessionRootDirPath(projectRoot));
+  fs.ensureDirSync(getDowncityPublicDirPath(projectRoot));
+  fs.ensureDirSync(getDowncityConfigDirPath(projectRoot));
+  fs.ensureDirSync(path.join(getDowncityDirPath(projectRoot), "schema"));
+  fs.ensureDirSync(getDowncityDebugDirPath(projectRoot));
+}
+
+/**
+ * runtime 启动前准备项目结构。
+ */
+export function ensureRuntimeProjectReady(projectRoot: string): void {
+  ensureContextFiles(projectRoot);
+  ensureShipDirectories(projectRoot);
+}
+
+/**
+ * 校验项目执行绑定是否可用于启动。
+ *
+ * 关键点（中文）
+ * - `downcity.json.execution` 必须存在且合法。
+ * - 若走 API 模式，则 `execution.modelId` 必须在 console 模型池中可解析。
+ * - 若走 local 模式，则 `lmp` plugin 必须启用且本地模型文件必须存在。
+ * - 若模型被 pause，也要在启动前直接拒绝，避免进程拉起后秒退。
+ */
+export function ensureRuntimeExecutionBindingReady(projectRoot: string): void {
+  let primaryModelId = "";
+  try {
+    const config = loadDowncityConfig(projectRoot);
+    primaryModelId = readProjectPrimaryModelId(config);
+  } catch (error) {
+    console.error("❌ Invalid downcity.json execution binding");
+    console.error(`   project: ${projectRoot}`);
+    console.error(`   error: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+
+  if (!primaryModelId) {
+    console.error("❌ Invalid downcity.json execution binding");
+    console.error(`   project: ${projectRoot}`);
+    console.error('   error: "execution" must be { "type": "api", "modelId": "..." }');
+    process.exit(1);
+  }
+
+  const store = new ConsoleStore();
+  try {
+    const model = store.getModel(primaryModelId);
+    if (!model) {
+      console.error("❌ Model not found in console model pool");
+      console.error(`   project: ${projectRoot}`);
+      console.error(`   execution.modelId: ${primaryModelId}`);
+      console.error("   fix: run `city model create` or `city model list`");
+      process.exit(1);
+    }
+    if (model.isPaused === true) {
+      console.error("❌ Model is paused");
+      console.error(`   project: ${projectRoot}`);
+      console.error(`   execution.modelId: ${primaryModelId}`);
+      console.error(`   fix: run \`city model pause ${primaryModelId} --enabled false\``);
+      process.exit(1);
+    }
+  } finally {
+    store.close();
+  }
+}

package/src/http/Server.ts

@@ -0,0 +1,170 @@
+/**
+ * Agent HTTP Server 装配模块。
+ *
+ * 职责说明：
+ * 1. 创建主 Hono 应用并挂载各路由模块。
+ * 2. 管理 Node HTTP Server 的启动与停止。
+ * 3. 保持 server 层只做协议装配，不混入具体路由实现。
+ */
+
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { logger } from "hono/logger";
+import http from "node:http";
+import { logger as serverLogger } from "@shared/utils/logger/Logger.js";
+import { executeRouter } from "@/http/execute/execute.js";
+import { healthRouter } from "@/http/health/health.js";
+import {
+  ensureServiceActionRoutesRegistered,
+  servicesRouter,
+} from "@/http/services/services.js";
+import { pluginsRouter } from "@/http/plugins/plugins.js";
+import { staticRouter } from "@/http/static/static.js";
+import { dashboardRouter } from "@/http/dashboard/Router.js";
+import { registerAuthRoutes } from "@/http/auth/AuthRoutes.js";
+import { AuthService } from "@/http/auth/AuthService.js";
+import {
+  createRouteAuthGuardMiddleware,
+  SERVER_AUTH_ROUTE_POLICIES,
+} from "@/http/auth/RoutePolicy.js";
+import {
+  listBuiltinPluginRuntimeAuthPolicies,
+  registerBuiltinPluginHttpRoutes,
+} from "@/plugin/HttpRoutes.js";
+import { getAgentContext } from "@/agent/AgentRuntime.js";
+
+/**
+ * Server 启动参数。
+ */
+export interface ServerStartOptions {
+  /** HTTP 服务监听端口。 */
+  port: number;
+  /** HTTP 服务监听主机。 */
+  host: string;
+}
+
+/**
+ * Server 运行实例。
+ */
+export interface ServerInstance {
+  /** Hono 应用实例。 */
+  app: Hono;
+  /** 原生 HTTP Server 实例。 */
+  server: http.Server;
+  /** 停止当前服务。 */
+  stop(): Promise<void>;
+}
+
+/**
+ * 创建主 Hono 应用。
+ */
+export function createServerApp(): Hono {
+  const app = new Hono();
+  const authService = new AuthService();
+  const authPolicies = [
+    ...SERVER_AUTH_ROUTE_POLICIES,
+    ...listBuiltinPluginRuntimeAuthPolicies(),
+  ];
+
+  app.use("*", logger());
+  app.use(
+    "*",
+    cors({
+      origin: "*",
+      allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+      allowHeaders: ["Content-Type", "Authorization"],
+    }),
+  );
+  app.use("*", createRouteAuthGuardMiddleware(authService, authPolicies));
+
+  // 关键点（中文）：service action 路由在 runtime ready 后再注册，避免命令级 import 副作用。
+  ensureServiceActionRoutesRegistered();
+
+  // 关键点（中文）：按路由域挂载，server 模块只保留装配职责。
+  app.route("/", staticRouter);
+  app.route("/", healthRouter);
+  app.route("/", servicesRouter);
+  app.route("/", pluginsRouter);
+  app.route("/", executeRouter);
+  app.route("/", dashboardRouter);
+  registerBuiltinPluginHttpRoutes({
+    app,
+    getContext: getAgentContext,
+  });
+  registerAuthRoutes({ app, authService });
+
+  return app;
+}
+
+/**
+ * 启动主 HTTP 服务。
+ */
+export async function startServer(
+  options: ServerStartOptions,
+): Promise<ServerInstance> {
+  const app = createServerApp();
+  const server = createNodeServer(app, options);
+
+  await new Promise<void>((resolve) => {
+    server.listen(options.port, options.host, () => {
+      serverLogger.info(
+        `🚀 Agent Server started: http://${options.host}:${options.port}`,
+      );
+      serverLogger.info("Available APIs:");
+      resolve();
+    });
+  });
+
+  return {
+    app,
+    server,
+    async stop(): Promise<void> {
+      await serverLogger.saveAllLogs();
+      await new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      });
+      serverLogger.info("Agent Server stopped");
+    },
+  };
+}
+
+/**
+ * 创建 Node HTTP Server 适配层。
+ */
+function createNodeServer(app: Hono, options: ServerStartOptions): http.Server {
+  return http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url || "/", `http://${options.host}:${options.port}`);
+      const method = req.method || "GET";
+      const bodyBuffer = await readRequestBody(req);
+      const request = new Request(url.toString(), {
+        method,
+        headers: new Headers(req.headers as Record<string, string>),
+        body: bodyBuffer.length > 0 ? bodyBuffer : undefined,
+      });
+
+      const response = await app.fetch(request);
+      res.statusCode = response.status;
+      for (const [key, value] of response.headers.entries()) {
+        res.setHeader(key, value);
+      }
+      const body = await response.text();
+      res.end(body);
+    } catch {
+      res.statusCode = 500;
+      res.end("Internal Server Error");
+    }
+  });
+}
+
+/**
+ * 读取原生请求体。
+ */
+async function readRequestBody(req: http.IncomingMessage): Promise<Buffer> {
+  return new Promise<Buffer>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks)));
+    req.on("error", reject);
+  });
+}

package/src/http/auth/AuthEnv.ts

@@ -0,0 +1,71 @@
+/**
+ * AuthEnv：统一认证环境变量与 token 解析辅助模块。
+ *
+ * 关键点（中文）
+ * - 收敛 `DC_AUTH_TOKEN` 的变量名与 Bearer 归一化逻辑。
+ * - 通用子进程默认不继承任何 Bearer Token，避免隐式走本地 HTTP。
+ */
+
+/**
+ * 用户显式覆盖 Bearer Token 的环境变量名。
+ */
+export const CLI_AUTH_TOKEN_ENV_KEY = "DC_AUTH_TOKEN";
+
+/**
+ * 归一化 Bearer Token。
+ *
+ * 关键点（中文）
+ * - 允许传入纯 token 或 `Bearer xxx`。
+ * - 空字符串与无效值统一归一化为 `null`。
+ */
+export function normalizeBearerToken(value: unknown): string | null {
+  const raw = String(value || "").trim();
+  if (!raw) return null;
+  const bearerMatch = /^Bearer\s+(.+)$/i.exec(raw);
+  const token = bearerMatch?.[1]?.trim() || raw;
+  return token || null;
+}
+
+/**
+ * 解析本次调用应使用的 token。
+ *
+ * 优先级（中文）
+ * 1. 显式传入 token
+ * 2. 用户显式覆盖环境变量 `DC_AUTH_TOKEN`
+ * 3. 调用方传入的本地存储 token
+ */
+export function resolveInvocationToken(params: {
+  explicitToken?: string;
+  env?: NodeJS.ProcessEnv;
+  storedToken?: string;
+} = {}): string | undefined {
+  const explicitToken = normalizeBearerToken(params.explicitToken);
+  if (explicitToken) return explicitToken;
+
+  const env = params.env || process.env;
+
+  const envAuthToken = normalizeBearerToken(env[CLI_AUTH_TOKEN_ENV_KEY]);
+  if (envAuthToken) return envAuthToken;
+
+  return normalizeBearerToken(params.storedToken) || undefined;
+}
+
+/**
+ * 从通用子进程环境中剥离 Bearer Token。
+ *
+ * 关键点（中文）
+ * - shell / task script / ACP 等通用执行面不应默认继承任何 HTTP 鉴权信息。
+ * - 这样可以强制这些链路优先走 RPC，而不是通过环境变量隐式改走本地 HTTP。
+ */
+export function stripInvocationAuthEnv(targetEnv: NodeJS.ProcessEnv): void {
+  delete targetEnv[CLI_AUTH_TOKEN_ENV_KEY];
+  delete targetEnv.DC_AGENT_TOKEN;
+}
+
+/**
+ * 生成标准 Authorization 头值。
+ */
+export function formatBearerHeaderValue(tokenInput: string | undefined): string | undefined {
+  const token = normalizeBearerToken(tokenInput);
+  return token ? `Bearer ${token}` : undefined;
+}