paseo-plugin-zcode-provider 0.0.0-stage → 0.2.0

package/server/vendor/zcode/packages/shared/src/runtimeEnv.ts

@@ -0,0 +1,315 @@
+export const ZCODE_RUNTIME_ENV_KEY = "ZCODE_RUNTIME_ENV";
+export const ZCODE_HTTP_PROXY_ENV_KEY = "ZCODE_HTTP_PROXY";
+export const ZCODE_NO_PROXY_ENV_KEY = "ZCODE_NO_PROXY";
+/** Desktop Host 只向 desktop-attached remote server 传递一次的网络配置。 */
+export const ZCODE_REMOTE_RUNTIME_NETWORK_AUTHORITY_ENV_KEY =
+  "ZCODE_REMOTE_RUNTIME_NETWORK_AUTHORITY";
+export const ZCODE_REMOTE_HTTP_PROXY_ENV_KEY = "ZCODE_REMOTE_HTTP_PROXY";
+export const ZCODE_REMOTE_NO_PROXY_ENV_KEY = "ZCODE_REMOTE_NO_PROXY";
+export const ZCODE_AGENT_CA_CERT_ENV_KEY = "ZCODE_AGENT_CA_CERT";
+export const ZCODE_TOOL_ENV_PASSTHROUGH_ENV_KEY = "ZCODE_TOOL_ENV_PASSTHROUGH_JSON";
+/** Desktop Main 将服务端裁决的单功能灰度结果传给 Local/Remote Host。 */
+export const ZCODE_DESKTOP_CONTEXT_PROMPT_ENABLED_ENV = "ZCODE_DESKTOP_CONTEXT_PROMPT_ENABLED";
+export const ZCODE_CUA_PRODUCT_HELPER_ENV_KEY = "ZCODE_CUA_PRODUCT_HELPER";
+export const ZCODE_CUA_BROKER_SOCKET_ENV_KEY = "ZCODE_CUA_PERMISSION_BROKER_SOCKET";
+/** Shared node_repl host marker; unlike the broker bearer values it is not a secret. */
+export const ZCODE_CUA_NODE_REPL_HOST_ENV_KEY = "ZCODE_CUA_NODE_REPL_HOST";
+// One-knob local-development bundle. Setting ZCODE_CUA_DEV_MODE implies the internal feature
+// flag (below) plus the local-helper relaxations wired in packages/services (unsigned/
+// unauthenticated local helper, dev install variant, "Dev.app" naming). It exists so a developer
+// can launch the full local CUA loop with a single env var instead of the historical four-var
+// incantation. 这些开关只在未打包本地构建生效；正式 desktop/Helper bundle 会在编译期关闭并在
+// main→host 边界删除，不能用于 signed release 的 runtime override。
+export const ZCODE_CUA_DEV_MODE_ENV_KEY = "ZCODE_CUA_DEV_MODE";
+
+export type ZCodeRuntimeEnv = "development" | "production" | "test";
+
+type EnvRecord = Record<string, string | undefined>;
+
+export function isCuaDevModeRequested(env: EnvRecord = process.env): boolean {
+  const explicit = env[ZCODE_CUA_DEV_MODE_ENV_KEY]?.trim().toLowerCase();
+  return explicit === "1" || explicit === "true" || explicit === "on";
+}
+
+export function isZCodeCuaInternalFeatureEnabled(env: EnvRecord = process.env): boolean {
+  // CUA 现已默认打包进正式版（plugin staged + Helper enabled），不再需要显式 env flag。
+  // DEV_MODE 仍然 implied（开发一键），PRODUCT_HELPER=0/off/false 可显式关闭。
+  if (isCuaDevModeRequested(env)) return true;
+  const explicit = env[ZCODE_CUA_PRODUCT_HELPER_ENV_KEY]?.trim().toLowerCase();
+  if (explicit === "0" || explicit === "false" || explicit === "off") return false;
+  return true;
+}
+
+const SANITIZED_RUNTIME_ENV_KEYS = [
+  "NODE_ENV",
+  "ELECTRON_RUN_AS_NODE",
+  "NODE_NO_WARNINGS",
+  "HTTP_PROXY",
+  "HTTPS_PROXY",
+  "ALL_PROXY",
+  "NO_PROXY",
+  "NODE_EXTRA_CA_CERTS",
+  "SSL_CERT_FILE",
+  "SSL_CERT_DIR",
+  "REQUESTS_CA_BUNDLE",
+  "CURL_CA_BUNDLE",
+  "GIT_SSL_CAINFO",
+  ZCODE_REMOTE_RUNTIME_NETWORK_AUTHORITY_ENV_KEY,
+  ZCODE_REMOTE_HTTP_PROXY_ENV_KEY,
+  ZCODE_REMOTE_NO_PROXY_ENV_KEY,
+  // CUA broker socket 是只该给目标 zcode-cua MCP server 的连接材料（由 desktop/CLI 在
+  // 解析该 server 时定向注入其 env）。绝不能随 agent 全局 env 泄漏给其它 MCP server / Bash / tool
+  // 子进程 —— 否则同 agent 内的恶意 MCP 或被 prompt-injection 触发的命令能直接驱动
+  // 已授权 Helper（confused-deputy）。这里统一从所有子进程 env 剔除；zcode-cua server 的定向
+  // env 注入在 buildMcpStdioEnv 之后 spread，因此仍能拿到（见 adapters/mcp StdioClientTransport）。
+  ZCODE_CUA_BROKER_SOCKET_ENV_KEY,
+  // 遗留 bearer token：当前 broker 是 identity 模式（socket + authority，无口令，见
+  // captureZCodeCuaBrokerCredentials），本进程不再产生也不再消费它。仍然剔除，因为用户机上
+  // 可能装着旧版 Helper —— 那些版本认 bearer token，一旦这个变量随 agent 全局 env 漏给别的
+  // MCP server / Bash 子进程，同一个 confused-deputy 又成立。剔除一个已不用的键是零成本的。
+  "ZCODE_CUA_PERMISSION_BROKER_TOKEN",
+  "ZCODE_CUA_PERMISSION_BROKER_REFRESH_MARKER",
+  "ZCODE_CUA_PLUGIN_AUTHORITY",
+  // Agent OTLP Endpoint/Auth/Identity 只属于 CLI telemetry bootstrap，不能继续泄漏给
+  // Bash、MCP 或模型工具子进程。sanitize 前会捕获到本进程私有 Map，供 Agent 启动边界读取。
+  "OTEL_EXPORTER_OTLP_ENDPOINT",
+  "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
+  "OTEL_EXPORTER_OTLP_HEADERS",
+  "OTEL_EXPORTER_OTLP_TRACES_HEADERS",
+  "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT",
+  "OTEL_EXPORTER_OTLP_METRICS_HEADERS",
+  "OTEL_SERVICE_NAME",
+  "OTEL_RESOURCE_ATTRIBUTES",
+  "OTEL_EXPORTER_OTLP_COMPRESSION",
+  "ZCODE_MODEL_TELEMETRY_ENABLED",
+  "ZCODE_TELEMETRY_DEVICE_MID",
+  // 历史身份变量不再受支持，但仍须从所有子进程环境剔除，避免旧配置把原始账号
+  // 或可伪造 hash 泄漏给 Host、Bash 与 MCP。
+  "ZCODE_TELEMETRY_USER_ID",
+  "ZCODE_TELEMETRY_USER_ID_HASH",
+  "ZCODE_TELEMETRY_USER_SUBJECT_ID",
+  "ZCODE_TELEMETRY_IDENTITY_STATE",
+  "ZCODE_TELEMETRY_RUNTIME_SURFACE",
+  "ZCODE_TELEMETRY_RUNTIME_DISTRIBUTION",
+] as const;
+
+const NON_TOOL_PASSTHROUGH_RUNTIME_ENV_KEYS = [
+  "NODE_ENV",
+  "ELECTRON_RUN_AS_NODE",
+  "NODE_NO_WARNINGS",
+  // CUA broker 凭据不得经 tool-env-passthrough 恢复到 Bash/tool 子进程（否则等于绕过上面的剔除）。
+  ZCODE_CUA_BROKER_SOCKET_ENV_KEY,
+  "ZCODE_CUA_PERMISSION_BROKER_REFRESH_MARKER",
+  "ZCODE_CUA_PLUGIN_AUTHORITY",
+  ZCODE_REMOTE_RUNTIME_NETWORK_AUTHORITY_ENV_KEY,
+  ZCODE_REMOTE_HTTP_PROXY_ENV_KEY,
+  ZCODE_REMOTE_NO_PROXY_ENV_KEY,
+] as const;
+
+const SANITIZED_PACKAGE_MANAGER_ENV_PATTERN =
+  /^(npm_config|yarn|pnpm)_(http_proxy|https_proxy|proxy|all_proxy|no_proxy|cafile|ca)$/i;
+
+export function normalizeZCodeRuntimeEnv(value: string | undefined): ZCodeRuntimeEnv | undefined {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === "development" || normalized === "production" || normalized === "test") {
+    return normalized;
+  }
+  return undefined;
+}
+
+export function resolveZCodeRuntimeEnv(
+  env: Record<string, string | undefined>,
+  fallback: ZCodeRuntimeEnv = "production",
+): ZCodeRuntimeEnv {
+  return normalizeZCodeRuntimeEnv(env[ZCODE_RUNTIME_ENV_KEY]) ?? fallback;
+}
+
+// Exported so services/node.ts can inject the Helper's plugin authority into the agent spawn env
+// (mirrors feat; the agent-side plugin host verifies the broker authority via this env var).
+export const ZCODE_CUA_PLUGIN_AUTHORITY_ENV_KEY = "ZCODE_CUA_PLUGIN_AUTHORITY";
+
+interface CapturedCuaBrokerCredentials {
+  socket: string;
+  pluginAuthority: string;
+  refreshMarker?: string;
+}
+
+let capturedCuaBrokerCredentials: Readonly<CapturedCuaBrokerCredentials> | undefined;
+const capturedZCodeAgentTelemetryEnv: Record<string, string> = {};
+
+// CUA broker socket 会被上面的 sanitize 从子进程 env 中剔除（confused-deputy 防护 —— 不能让
+// 其它 MCP server / Bash / tool 子进程直接驱动已授权 Helper）。但 CLI 入口在 bootstrap
+// 解析全局 ~/.zcode/cli/config.json 里的 `zcode-cua` server 之前就会先 sanitize process.env，导致
+// 定向注入时已经读不到凭据 → 全局 zcode-cua 回退 `--backend auto`，让 Python/uvx 成为 TCC 主体
+// （fail-open，违反 "Python/uvx must never become the implicit permission owner"）。因此在剔除前把
+// 凭据捕获进本进程私有存储，只经 getCapturedZCodeCuaBrokerCredentials() 暴露给 bootstrap 的定向
+// 注入路径，绝不写回任何子进程 env。
+function captureZCodeCuaBrokerCredentials(env: Record<string, string | undefined>): void {
+  const socket = env[ZCODE_CUA_BROKER_SOCKET_ENV_KEY]?.trim();
+  const pluginAuthority = env[ZCODE_CUA_PLUGIN_AUTHORITY_ENV_KEY]?.trim();
+  const refreshMarker = env["ZCODE_CUA_PERMISSION_BROKER_REFRESH_MARKER"]?.trim();
+  // 连接没有口令：socket + authority（config-provenance 随机数）同批出现才构成有效凭据组；
+  // 半组说明上游注入不完整或正在轮换。
+  if (socket && pluginAuthority) {
+    capturedCuaBrokerCredentials = Object.freeze({
+      socket,
+      pluginAuthority,
+      ...(refreshMarker ? { refreshMarker } : {}),
+    });
+    return;
+  }
+  if (socket || pluginAuthority) {
+    // 发现半组凭据说明上游注入不完整或正在轮换；清掉旧快照并 fail-closed，不能复用另一半。
+    capturedCuaBrokerCredentials = undefined;
+  }
+}
+
+function captureZCodeAgentTelemetryEnv(env: Record<string, string | undefined>): void {
+  Object.assign(capturedZCodeAgentTelemetryEnv, readZCodeAgentTelemetryEnv(env));
+}
+
+/**
+ * 只提取供 Agent telemetry bootstrap 使用的配置。宿主可在经过通用 env 清洗后，
+ * 将这组值定向传给 host/Agent；不得把它并入 Bash/MCP 的 tool env。
+ */
+export function readZCodeAgentTelemetryEnv(
+  env: Record<string, string | undefined>,
+): Record<string, string> {
+  const telemetryEnv: Record<string, string> = {};
+  for (const key of SANITIZED_RUNTIME_ENV_KEYS) {
+    if (!isZCodeAgentTelemetryEnvKey(key)) continue;
+    const value = env[key]?.trim();
+    if (value) telemetryEnv[key] = value;
+  }
+  return telemetryEnv;
+}
+
+export function getCapturedZCodeAgentTelemetryEnv(): Record<string, string> {
+  return { ...capturedZCodeAgentTelemetryEnv };
+}
+
+export function getCapturedZCodeCuaBrokerCredentials(): {
+  socket: string | undefined;
+  pluginAuthority: string | undefined;
+  refreshMarker?: string;
+} {
+  return capturedCuaBrokerCredentials
+    ? { ...capturedCuaBrokerCredentials }
+    : { socket: undefined, pluginAuthority: undefined };
+}
+
+// 仅供测试重置进程内捕获状态。
+export function resetCapturedZCodeCuaBrokerCredentialsForTest(): void {
+  capturedCuaBrokerCredentials = undefined;
+}
+
+export function resetCapturedZCodeAgentTelemetryEnvForTest(): void {
+  for (const key of Object.keys(capturedZCodeAgentTelemetryEnv)) {
+    delete capturedZCodeAgentTelemetryEnv[key];
+  }
+}
+
+export function sanitizeZCodeRuntimeEnv<T extends Record<string, string | undefined>>(
+  env: T,
+): Record<string, string> {
+  captureZCodeCuaBrokerCredentials(env);
+  captureZCodeAgentTelemetryEnv(env);
+  const sanitized: Record<string, string> = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined || shouldSanitizeZCodeRuntimeEnvKey(key)) {
+      continue;
+    }
+    sanitized[key] = value;
+  }
+  return sanitized;
+}
+
+export function buildZCodeToolEnvPassthroughEnv(env: EnvRecord): Record<string, string> {
+  const captured = readZCodeToolEnvPassthroughEnv(env);
+
+  for (const [key, value] of Object.entries(env)) {
+    if (value === undefined || !shouldCaptureZCodeToolEnvPassthroughKey(key)) {
+      continue;
+    }
+    captured[key] = value;
+  }
+
+  return stringifyZCodeToolEnvPassthroughEnv(captured);
+}
+
+export function readZCodeToolEnvPassthroughEnv(env: EnvRecord): Record<string, string> {
+  const raw = env[ZCODE_TOOL_ENV_PASSTHROUGH_ENV_KEY];
+  if (!raw) {
+    return {};
+  }
+
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+
+    const captured: Record<string, string> = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (
+        typeof value === "string" &&
+        /^[A-Za-z_][A-Za-z0-9_]*$/.test(key) &&
+        shouldCaptureZCodeToolEnvPassthroughKey(key)
+      ) {
+        captured[key] = value;
+      }
+    }
+    return captured;
+  } catch {
+    return {};
+  }
+}
+
+export function sanitizeZCodeRuntimeEnvInPlace(env: Record<string, string | undefined>): void {
+  captureZCodeCuaBrokerCredentials(env);
+  captureZCodeAgentTelemetryEnv(env);
+  for (const key of Object.keys(env)) {
+    if (shouldSanitizeZCodeRuntimeEnvKey(key)) {
+      delete env[key];
+    }
+  }
+}
+
+function isZCodeAgentTelemetryEnvKey(key: string): boolean {
+  return (
+    key.startsWith("OTEL_") ||
+    key.startsWith("ZCODE_TELEMETRY_") ||
+    key === "ZCODE_MODEL_TELEMETRY_ENABLED"
+  );
+}
+
+export function shouldSanitizeZCodeRuntimeEnvKey(key: string): boolean {
+  const upperKey = key.toUpperCase();
+  return (
+    SANITIZED_RUNTIME_ENV_KEYS.some((candidate) => candidate === upperKey) ||
+    SANITIZED_PACKAGE_MANAGER_ENV_PATTERN.test(key)
+  );
+}
+
+export function shouldCaptureZCodeToolEnvPassthroughKey(key: string): boolean {
+  const upperKey = key.toUpperCase();
+  if (isZCodeAgentTelemetryEnvKey(upperKey)) {
+    return false;
+  }
+  if (NON_TOOL_PASSTHROUGH_RUNTIME_ENV_KEYS.some((candidate) => candidate === upperKey)) {
+    return false;
+  }
+  return shouldSanitizeZCodeRuntimeEnvKey(key);
+}
+
+function stringifyZCodeToolEnvPassthroughEnv(
+  captured: Record<string, string>,
+): Record<string, string> {
+  const entries = Object.entries(captured).sort(([left], [right]) => left.localeCompare(right));
+  if (entries.length === 0) {
+    return {};
+  }
+  return {
+    [ZCODE_TOOL_ENV_PASSTHROUGH_ENV_KEY]: JSON.stringify(Object.fromEntries(entries)),
+  };
+}

package/server/vendor/zcode/packages/shared/src/settings-source.ts

@@ -0,0 +1,10 @@
+export type SettingsDirectorySource = "zcode" | "agents" | "claude";
+
+export type SettingsDirectoryScope = "user" | "project";
+
+export interface SettingsDirectoryLocation {
+  source: SettingsDirectorySource;
+  scope: SettingsDirectoryScope;
+  directoryPath: string;
+  projectPath?: string;
+}

package/server/vendor/zcode/packages/shared/src/usage-quota.ts

@@ -0,0 +1,74 @@
+/**
+ * Coding Plan 额度相关的纯类型定义。
+ *
+ * 从 usage-stats.ts 拆出：MCP 额度接入后该文件超过 oxlint max-lines(400) 门禁，
+ * 而额度是可以独立描述的一组类型（不依赖统计聚合结构），拆出后两边都在门禁内。
+ * 这里只依赖自身，usage-stats.ts 单向导入并 re-export，不构成循环依赖。
+ */
+
+export interface UsageQuotaSnapshot {
+  level: string | null;
+  limits: UsageQuotaLimit[];
+}
+
+export interface UsageQuotaLimit {
+  type: string;
+  /** Start Plan 服务端额度桶及周期身份；周期时间为毫秒，供提醒去重。 */
+  bucketId?: string;
+  userPlanId?: string;
+  periodStart?: number;
+  periodEnd?: number;
+  /** 所属 entitlement 的周期类型，如 daily / one_time。 */
+  period?: string;
+  meter?: string;
+  unitType?: string;
+  /** Start Plan bucket 所属套餐身份，仅用于设置页按 plan 分组展示。 */
+  planId?: string;
+  unit?: number;
+  number?: number;
+  usage?: number;
+  currentValue?: number;
+  remaining?: number;
+  percentage?: number;
+  nextResetTime?: number;
+  usageDetails: UsageQuotaUsageDetail[];
+}
+
+export interface UsageQuotaUsageDetail {
+  modelCode: string;
+  displayName?: string;
+  usage: number;
+}
+
+/**
+ * `aggregate.type` 的合成值。
+ *
+ * 不复用 TOKENS_LIMIT / TIME_LIMIT：`isSameLimitCategory` 会把 TIME_LIMIT 判为工具额度同类，
+ * 让 MCP 汇总额度被现有的 findCodingPlanQuotaLimit 查询误命中。
+ */
+export const MCP_USAGE_QUOTA_LIMIT_TYPE = "MCP_USAGE_LIMIT" as const;
+
+/** MCP 额度所属的 Coding Plan 连接，供 UI 判断能否显示在当前 provider tab 下。 */
+export type UsageMcpQuotaScope =
+  | {
+      providerFamily: "zai" | "bigmodel";
+      targetType: "PERSONAL";
+    }
+  | {
+      providerFamily: "zai" | "bigmodel";
+      targetType: "TEAM";
+      organizationId: string;
+      projectId: string;
+    };
+
+export interface UsageMcpQuotaSnapshot {
+  /** 服务端 server_time，毫秒（接口返回 Unix 秒）。 */
+  serverTime: number;
+  level: string | null;
+  scope: UsageMcpQuotaScope;
+  /**
+   * 服务端 `total_usage`（总已用 / 总额度 / 总剩余）的等价表达，直接复用现有额度条 / 额度卡的
+   * 展示逻辑。注意 percentage 沿用 quota 接口口径：**已使用占比**，展示端负责反转成剩余。
+   */
+  aggregate: UsageQuotaLimit;
+}