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

package/server/vendor/zcode/packages/shared/src/browser-use/result.ts

@@ -0,0 +1,130 @@
+import { z } from "zod";
+import { browserErrorCodeSchema, browserPageStateSchema } from "./commands.js";
+import { browserViewportSizeSchema } from "./command-metadata.js";
+import { browserBackendTypeSchema } from "./backend.js";
+import { browserSnapshotSchema, browserSnapshotElementSchema } from "./snapshot.js";
+
+/**
+ * 受控 tab 摘要（list 命令返回）：agent 用 tabId 寻址某个具体 tab（含 human 开的 tab）。
+ */
+export const browserTabSummarySchema = z
+  .object({
+    tabId: z.string(),
+    url: z.string(),
+    title: z.string(),
+    /** guest 当前真实 CSS viewport；normal/free-size 均必须返回。 */
+    viewport: browserViewportSizeSchema,
+    /**
+     * main 侧最近可见/激活的内置浏览器 tab。用于让 agent 在用户手动改地址后，
+     * 先绑定并读取当前页面，而不是误读 session 默认 tab。
+     */
+    active: z.boolean().optional(),
+    lifecycle: z.enum(["active", "deliverable", "handoff"]).optional(),
+  })
+  .strict();
+export type BrowserTabSummary = z.infer<typeof browserTabSummarySchema>;
+
+/** 尚未被当前 browser session claim 的用户 IAB tab；claim 前不能执行普通 Tab command。 */
+export const browserUserTabInfoSchema = z
+  .object({
+    id: z.string().min(1),
+    lastOpened: z.string().optional(),
+    tabGroup: z.string().optional(),
+    title: z.string().optional(),
+    url: z.string().optional(),
+  })
+  .strict();
+export type BrowserUserTabInfo = z.infer<typeof browserUserTabInfoSchema>;
+
+/** JS 弹窗信息（getDialog 返回）。 */
+export const browserDialogSchema = z
+  .object({
+    type: z.enum(["alert", "confirm", "prompt", "beforeunload"]),
+    message: z.string(),
+    defaultPrompt: z.string().optional(),
+  })
+  .strict();
+export type BrowserDialog = z.infer<typeof browserDialogSchema>;
+
+/** browser command 的 UI/客户端元数据；不会自动变成模型 image block。 */
+export const browserResponseMetaSchema = z
+  .object({
+    browserUse: z.literal(true),
+    backendType: browserBackendTypeSchema,
+    browserId: z.string().min(1),
+    browserGeneration: z.number().int().nonnegative(),
+    openTabIds: z.array(z.string()),
+    tabId: z.string().optional(),
+    currentUrl: z.string().optional(),
+    lifecycle: z.enum(["active", "deliverable", "handoff", "closed"]).optional(),
+  })
+  .strict();
+export type BrowserResponseMeta = z.infer<typeof browserResponseMetaSchema>;
+
+export const browserRecordingArtifactSchema = z
+  .object({
+    path: z.string().min(1),
+    mimeType: z.literal("video/webm"),
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+    fps: z.number().positive(),
+    durationMs: z.number().nonnegative(),
+    frameCount: z.number().int().nonnegative(),
+  })
+  .strict();
+export type BrowserRecordingArtifact = z.infer<typeof browserRecordingArtifactSchema>;
+
+export const browserRecordingJobSchema = z
+  .object({
+    id: z.string().min(1),
+    status: z.enum(["running", "completed", "failed", "cancelled"]),
+    phase: z.enum(["preparing", "capturing", "finalizing", "completed", "failed", "cancelled"]),
+    progress: z.number().min(0).max(1),
+    startedAt: z.number().nonnegative(),
+    updatedAt: z.number().nonnegative(),
+    artifact: browserRecordingArtifactSchema.optional(),
+    error: z.string().optional(),
+  })
+  .strict();
+export type BrowserRecordingJob = z.infer<typeof browserRecordingJobSchema>;
+
+/**
+ * browser 命令的统一结果（agent BrowserControlPort / 协议 result / main executor 三处同源）。
+ * 截图走 image；导航/getState 回 state；snapshot 回 snapshot；list 回 tabs；失败回结构化 error。
+ */
+export const browserCommandResultSchema = z
+  .object({
+    ok: z.boolean(),
+    state: browserPageStateSchema.optional(),
+    snapshot: browserSnapshotSchema.optional(),
+    image: z
+      .object({ base64: z.string(), mimeType: z.literal("image/png") })
+      .strict()
+      .optional(),
+    /** list 命令返回：只包含当前 window/workspace/session/generation scope 可见的 tabs。 */
+    tabs: z.array(browserTabSummarySchema).optional(),
+    /** BrowserUser.openTabs() 返回；与当前 session 自有 tabs.list() 严格分离。 */
+    userTabs: z.array(browserUserTabInfoSchema).optional(),
+    /** newTab 返回的单个真实 tab。 */
+    tab: browserTabSummarySchema.optional(),
+    /** evaluate 返回：页面表达式的可 JSON 序列化结果。 */
+    value: z.unknown().optional(),
+    /** elementInfo 返回：坐标命中元素的信息（复用快照元素结构；未命中则省略）。 */
+    element: browserSnapshotElementSchema.optional(),
+    /** getDialog 返回：当前 JS 弹窗信息；无弹窗时为 null。 */
+    dialog: browserDialogSchema.nullable().optional(),
+    /** WebView 异步录制任务；main 临时 path 会在 Host materialize 后改写为 workspace path。 */
+    recording: browserRecordingJobSchema.optional(),
+    error: z
+      .object({
+        code: browserErrorCodeSchema,
+        message: z.string(),
+        sideEffect: z.enum(["none", "uncertain"]).optional(),
+      })
+      .strict()
+      .optional(),
+    meta: browserResponseMetaSchema.optional(),
+    elapsedMs: z.number().nonnegative(),
+  })
+  .strict();
+export type BrowserCommandResult = z.infer<typeof browserCommandResultSchema>;

package/server/vendor/zcode/packages/shared/src/browser-use/snapshot.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+
+export const browserElementRectSchema = z
+  .object({
+    x: z.number(),
+    y: z.number(),
+    width: z.number(),
+    height: z.number(),
+  })
+  .strict();
+export type BrowserElementRect = z.infer<typeof browserElementRectSchema>;
+
+/**
+ * 单个可交互元素的快照条目，以 role、name、ref 提供定位信息，避免转储整页 DOM。
+ * ref 为按 DOM 序分配的稳定引用（e1, e2, ...），后续 action 用 ref 定位。
+ */
+export const browserSnapshotElementSchema = z
+  .object({
+    ref: z.string().min(1),
+    tag: z.string(),
+    role: z.string().optional(),
+    /** accessibleName */
+    name: z.string().optional(),
+    text: z.string().optional(),
+    value: z.string().optional(),
+    disabled: z.boolean().optional(),
+    checked: z.boolean().optional(),
+    selector: z.string(),
+    xpath: z.string(),
+    rect: browserElementRectSchema,
+    inViewport: z.boolean(),
+    /** 父级可交互元素的 ref（层级线索；顶层/无父可交互元素时省略）。 */
+    parentRef: z.string().optional(),
+    /** 元素来源的 frame 路径（同源 iframe 穿透时标注，如 "0>2"；主文档省略）。 */
+    framePath: z.string().optional(),
+    /** 有界稳定属性，用于从 DOM 事实构造 locator；不返回 class/style/src 等高噪声字段。 */
+    attributes: z.record(z.string(), z.string()).optional(),
+  })
+  .strict();
+export type BrowserSnapshotElement = z.infer<typeof browserSnapshotElementSchema>;
+
+/**
+ * 可见语义 DOM 节点。它只负责“读懂页面”，可动作句柄仍由 elements/ref 单独维护，
+ * 防止正文节点占满 action ref 预算。ref 仅在该语义节点同时属于 elements 时存在。
+ */
+export const browserSnapshotDomNodeSchema = z
+  .object({
+    tag: z.string(),
+    depth: z.number().int().nonnegative(),
+    inViewport: z.boolean(),
+    ref: z.string().min(1).optional(),
+    role: z.string().optional(),
+    name: z.string().optional(),
+    text: z.string().optional(),
+    attributes: z.record(z.string(), z.string()).optional(),
+  })
+  .strict();
+export type BrowserSnapshotDomNode = z.infer<typeof browserSnapshotDomNodeSchema>;
+
+export const browserSnapshotSchema = z
+  .object({
+    url: z.string(),
+    title: z.string(),
+    /**
+     * 有界的可见语义 DOM；optional 保持旧 backend/result 的协议兼容。
+     * 必须排在 elements 前定义：Zod 会按 schema 顺序重建对象，大页面工具结果被截断时
+     * 应先让模型看到页面语义，而不是 selector/xpath/rect 等动作细节。
+     */
+    dom: z.array(browserSnapshotDomNodeSchema).optional(),
+    /** 语义 DOM 节点超过内部预算时置 true。 */
+    domTruncated: z.boolean().optional(),
+    elements: z.array(browserSnapshotElementSchema),
+    /** 元素数超过 maxElements 时截断。 */
+    truncated: z.boolean(),
+  })
+  .strict();
+export type BrowserSnapshot = z.infer<typeof browserSnapshotSchema>;

package/server/vendor/zcode/packages/shared/src/command-types.ts

@@ -0,0 +1,96 @@
+// Command 相关类型定义
+import type { SettingsDirectoryLocation } from "./settings-source.js";
+
+export type CommandSource = "user" | "plugin";
+export type CommandAgentSource = "zcodeAgent";
+
+export interface CommandInfo {
+  name: string;
+  prompt: string;
+  content: string;
+  filePath: string;
+  description?: string;
+  argumentHint?: string;
+}
+
+export interface UserCommand extends CommandInfo {
+  id: string;
+  source: "user";
+  agentSource: CommandAgentSource;
+  location: SettingsDirectoryLocation;
+  enabled: boolean;
+  scope: "global" | "project";
+  projectPath?: string;
+}
+
+export interface PluginCommand extends Omit<CommandInfo, "filePath"> {
+  id: string;
+  source: "plugin";
+  enabled: boolean;
+  pluginName: string;
+  pluginMarketplace: string;
+  pluginEnabled: boolean;
+  scope: "global";
+  filePath: string;
+}
+
+export type ZCodeCommand = UserCommand | PluginCommand;
+
+export function isUserCommand(command: ZCodeCommand): command is UserCommand {
+  return command.source === "user";
+}
+
+export function isPluginCommand(command: ZCodeCommand): command is PluginCommand {
+  return command.source === "plugin";
+}
+
+export interface CommandConfig {
+  name: string;
+  prompt: string;
+  description?: string;
+  argumentHint?: string;
+  filePath?: string;
+}
+
+export type CommandStorageLevel = "user" | "project";
+
+export interface CommandsCapability {
+  userScopeAvailable: boolean;
+  userScopeReason?: "desktop_only";
+}
+
+export interface CommandsListResult {
+  commands: ZCodeCommand[];
+  userCommands: UserCommand[];
+  pluginCommands: PluginCommand[];
+  capability: CommandsCapability;
+}
+
+export interface CommandCreateParams {
+  config: CommandConfig;
+  agentSource?: CommandAgentSource;
+  storageLevel?: CommandStorageLevel;
+  workspacePath?: string;
+}
+
+export interface CommandUpdateParams {
+  commandId: string;
+  config: CommandConfig;
+  agentSource?: CommandAgentSource;
+  oldFilePath?: string;
+  storageLevel?: CommandStorageLevel;
+  workspacePath?: string;
+}
+
+export interface CommandDeleteParams {
+  commandId: string;
+  filePath: string;
+  agentSource?: CommandAgentSource;
+}
+
+export interface CommandSetEnabledParams {
+  commandId: string;
+  filePath: string;
+  enabled: boolean;
+  agentSource?: CommandAgentSource;
+}

package/server/vendor/zcode/packages/shared/src/config-schema.ts

@@ -0,0 +1,8 @@
+import type { z } from "zod";
+
+/** 每个字段保持原 schema，只派生覆盖所需的缺省/null；嵌套结构由调用方显式派生。 */
+export function sparseShape<T extends Record<string, z.ZodType>>(shape: T) {
+  return Object.fromEntries(
+    Object.entries(shape).map(([key, schema]) => [key, schema.nullable().optional()]),
+  ) as { [K in keyof T]: z.ZodOptional<z.ZodNullable<T[K]>> };
+}

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

@@ -0,0 +1,41 @@
+export type CuaPermissionKind = "accessibility" | "screen_recording";
+
+export interface OpenCuaPermissionOnboardingOptions {
+  /** Renderer 为本次调用生成的不透明 id；关闭该权限 surface 时只取消这一 participant。 */
+  operationId?: string;
+  initialPermission?: CuaPermissionKind;
+  /** 当前新鲜状态确认仍缺失的权限；main 会逐项打开对应设置页并等待应用返回。 */
+  requiredPermissions?: CuaPermissionKind[];
+}
+
+export interface CuaAccessibilitySettingsResult {
+  success: boolean;
+  canceled?: boolean;
+  /** main 级 onboarding 会话 id；同一 Helper identity 的并发窗口共享同一 id。 */
+  sessionId?: string;
+  /** 只有所有 staged 设置页都观察到任意 ZCode 窗口返回后才为 true。 */
+  returnedFromSettings?: boolean;
+  /**
+   * 同一 main onboarding 会话可能被多个窗口加入。每个独立 renderer/host 只有一个调用拿到 true，负责
+   * 重启该 host 的 Helper；同一 renderer 的重复调用拿到 false。不能全局只选一个窗口，因为每个窗口
+   * 都有独立 host/Helper，授权前已启动的进程都需要各自恢复。
+   * undefined 是旧 main 的兼容形状，按单窗口 owner 处理。
+   */
+  restartHelperAfterReturn?: boolean;
+  error?: string;
+}
+
+/**
+ * 拖拽预热结果（renderer 可见形状）。
+ *
+ * 注意 `helperBundleFingerprint` 故意**不在此声明**：它是 main 进程内存缓存的同步 TOCTOU 证据
+ * （dragstart 前用它比对"自验签以来字节未变"），跨 IPC 暴露给 renderer 既无用又扩大攻击面。
+ * main 侧另有 `PrepareCuaHelperPermissionDragMainResult` 携带该字段，IPC handler 返回前显式剥离。
+ */
+export interface PrepareCuaHelperPermissionDragResult {
+  success: boolean;
+  error?: string;
+  helperAppPath?: string;
+  helperDisplayName?: string;
+  helperBundleId?: string;
+}

package/server/vendor/zcode/packages/shared/src/database-startup.ts

@@ -0,0 +1,178 @@
+import { z } from "zod";
+
+export const databaseStartupErrorCodeSchema = z.enum([
+  "storage_full",
+  "permission_denied",
+  "io_error",
+  "out_of_memory",
+  "corrupt",
+  "open_failed",
+  "lock_timeout",
+  "checksum_mismatch",
+  "sql_failed",
+  "startup_status_timeout",
+  "transport_closed",
+  "unsupported_runtime",
+]);
+export type DatabaseStartupErrorCode = z.infer<typeof databaseStartupErrorCodeSchema>;
+
+/** 原始结构化 cause 比外层通用包装更准确；禁止从错误文案推断满盘或 OOM。 */
+export function classifyDatabaseStartupError(error: unknown): DatabaseStartupErrorCode {
+  const seen = new Set<unknown>();
+  let fallback: DatabaseStartupErrorCode = "sql_failed";
+  while (error && typeof error === "object" && !seen.has(error) && seen.size < 12) {
+    seen.add(error);
+    const value = error as { code?: unknown; errcode?: unknown; kind?: unknown; cause?: unknown };
+    const primary = typeof value.errcode === "number" ? value.errcode & 0xff : undefined;
+    if (primary === 13 || value.code === "ENOSPC" || value.code === "EDQUOT") return "storage_full";
+    if (primary === 3 || primary === 8 || value.code === "EACCES" || value.code === "EPERM")
+      return "permission_denied";
+    if (primary === 10 || value.code === "EIO") return "io_error";
+    if (primary === 7 || value.code === "ENOMEM" || value.code === "ERR_WORKER_OUT_OF_MEMORY")
+      return "out_of_memory";
+    if (primary === 11 || primary === 26) return "corrupt";
+    if (primary === 14) fallback = "open_failed";
+    if (primary === 5) fallback = "lock_timeout";
+    const kind = databaseStartupErrorCodeSchema.safeParse(value.kind);
+    if (kind.success && kind.data !== "sql_failed") fallback = kind.data;
+    error = value.cause;
+  }
+  return fallback;
+}
+
+/** 只跨进程传输错误码和冻结迁移 ID，不携带 SQL、文件内容或凭据。 */
+export function databaseStartupErrorDetails(error: unknown): {
+  sqliteCode?: number;
+  systemCode?: string;
+  migrationId?: string;
+} {
+  const result: { sqliteCode?: number; systemCode?: string; migrationId?: string } = {};
+  const seen = new Set<unknown>();
+  while (error && typeof error === "object" && !seen.has(error) && seen.size < 12) {
+    seen.add(error);
+    const current = error as {
+      errcode?: unknown;
+      code?: unknown;
+      migrationId?: unknown;
+      cause?: unknown;
+    };
+    if (typeof current.errcode === "number" && Number.isSafeInteger(current.errcode))
+      result.sqliteCode = current.errcode;
+    if (typeof current.code === "string" && /^[A-Z_0-9]{1,64}$/.test(current.code))
+      result.systemCode = current.code;
+    if (
+      typeof current.migrationId === "string" &&
+      /^[a-zA-Z_0-9-]{1,128}$/.test(current.migrationId)
+    )
+      result.migrationId = current.migrationId;
+    error = current.cause;
+  }
+  return result;
+}
+export const databaseStartupErrorDetailsSchema = z.object({
+  sqliteCode: z.number().int().optional(),
+  systemCode: z.string().max(64).optional(),
+  migrationId: z.string().max(128).optional(),
+});
+
+export const startupDiskSummarySchema = z
+  .object({
+    scopeId: z.string().max(128),
+    observedAvailableDropPeakBytes: z.number().finite().nonnegative().nullable(),
+    minAvailableBytes: z.number().finite().nonnegative().nullable(),
+    quality: z.enum(["complete", "partial", "unknown"]),
+    sampledAt: z.number().finite().nonnegative().nullable(),
+  })
+  .strict();
+export type StartupDiskSummary = z.infer<typeof startupDiskSummarySchema>;
+export const databaseStartupPhaseSchema = z.enum([
+  "starting",
+  "preparing_host_storage",
+  "preparing_session_storage",
+  "starting_services",
+  "ready",
+  "failed",
+]);
+export const databaseMigrationIdSchema = z.string().regex(/^[a-zA-Z_0-9-]{1,128}$/);
+
+/** 需求种类与真实执行/提交分开；预检发现需求不意味着当前执行者运行过 SQL。 */
+export const databaseMigrationFactsSchema = z
+  .object({
+    kind: z.enum(["none", "initialize", "upgrade"]),
+    executedCount: z.number().int().nonnegative(),
+    committedCount: z.number().int().nonnegative(),
+    // null 表示锁内账本为空；缺失表示尚未取得可信起点。
+    lastAppliedMigrationId: databaseMigrationIdSchema.nullable().optional(),
+  })
+  .strict()
+  .superRefine((facts, context) => {
+    if (
+      facts.committedCount > facts.executedCount ||
+      (facts.kind === "none" && facts.executedCount !== 0)
+    )
+      context.addIssue({ code: "custom", message: "Invalid migration execution facts" });
+  });
+export type DatabaseMigrationFacts = z.infer<typeof databaseMigrationFactsSchema>;
+
+export const databaseStartupStateSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    startupId: z.string().min(1).max(128),
+    attemptId: z.string().min(1).max(128),
+    sequence: z.number().int().nonnegative(),
+    startedAt: z.number().finite().nonnegative(),
+    updatedAt: z.number().finite().nonnegative(),
+    phase: databaseStartupPhaseSchema,
+    databasePhase: z
+      .enum(["checking", "waiting_for_lock", "migrating", "committing", "maintaining", "ready"])
+      .optional(),
+    migration: databaseMigrationFactsSchema.optional(),
+    currentMigration: databaseMigrationFactsSchema.optional(),
+    migrationBaselines: z
+      .array(
+        z
+          .object({
+            databaseId: z.string().min(1).max(128),
+            databaseKind: z.enum(["tasks-index", "session"]),
+            lastAppliedMigrationId: databaseMigrationIdSchema.nullable().optional(),
+          })
+          .strict(),
+      )
+      .optional(),
+    finalDatabase: z.boolean().optional(),
+    failedPhase: databaseStartupPhaseSchema.optional(),
+    errorCode: databaseStartupErrorCodeSchema.optional(),
+    ...databaseStartupErrorDetailsSchema.shape,
+    disk: z.array(startupDiskSummarySchema).max(8),
+  })
+  .strict();
+export type DatabaseStartupState = z.infer<typeof databaseStartupStateSchema>;
+/** 本地端口和启动快照必须来自同一 Host；此 ID 不承担工作区或任务身份。 */
+export const databaseStartupPortPayloadSchema = z
+  .object({
+    databaseStartupId: z.string().min(1).max(128),
+  })
+  .strict();
+export const databaseStartupControlSchema = z.discriminatedUnion("action", [
+  z.object({ action: z.literal("snapshot") }).strict(),
+  z.object({ action: z.literal("exit") }).strict(),
+  z.object({ action: z.literal("retry"), attemptId: z.string().min(1).max(128) }).strict(),
+]);
+export type DatabaseStartupControl = z.infer<typeof databaseStartupControlSchema>;
+
+/** 迁移可手动重试；已部分装配服务或损坏/失联时通过退出重开恢复，避免重复启动副作用。 */
+export function canRetryDatabaseStartup(
+  state: Pick<DatabaseStartupState, "phase" | "failedPhase" | "errorCode">,
+): boolean {
+  return (
+    state.phase === "failed" &&
+    state.failedPhase !== "starting_services" &&
+    ![
+      "corrupt",
+      "checksum_mismatch",
+      "transport_closed",
+      "startup_status_timeout",
+      "unsupported_runtime",
+    ].includes(state.errorCode ?? "sql_failed")
+  );
+}

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

@@ -0,0 +1,63 @@
+import type { ZCodeRuntimeEnv } from "./runtimeEnv.js";
+
+export type ZCodeEnv = "test" | "production";
+/** 安装包身份：决定应用名、app id、Electron 数据目录与更新策略；与后端环境 `ZCodeEnv` 是两个轴。 */
+export type ZCodeProductFlavor = "production" | "preview";
+export type ArmsRumEnv = "local" | "prod";
+
+// 非构建环境（如 e2e 测试的 mocha）下 define 不存在，用 typeof 检查 + fallback 避免 ReferenceError
+declare const __ZCODE_ENV__: string;
+declare const __ZCODE_PRODUCT_FLAVOR__: string;
+
+export function normalizeZCodeEnv(value: string | undefined): ZCodeEnv {
+  return value?.trim().toLowerCase() === "production" ? "production" : "test";
+}
+
+export const ZCODE_ENV = normalizeZCodeEnv(
+  typeof __ZCODE_ENV__ !== "undefined" ? __ZCODE_ENV__ : undefined,
+);
+
+/**
+ * 身份缺省跟随后端环境（test → preview，production → production）。
+ * 桌面构建通过 `ZCODE_PREVIEW_IDENTITY=1` 显式注入 preview，得到连接生产后端的 Preview 包；
+ * 未注入 define 的 bundle（web、CLI、测试）沿用旧的单轴语义。
+ */
+export function normalizeZCodeProductFlavor(
+  value: string | undefined,
+  zcodeEnv: ZCodeEnv,
+): ZCodeProductFlavor {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === "production" || normalized === "preview") {
+    return normalized;
+  }
+  return zcodeEnv === "production" ? "production" : "preview";
+}
+
+export const ZCODE_PRODUCT_FLAVOR = normalizeZCodeProductFlavor(
+  typeof __ZCODE_PRODUCT_FLAVOR__ !== "undefined" ? __ZCODE_PRODUCT_FLAVOR__ : undefined,
+  ZCODE_ENV,
+);
+export const ZCODE_APP_VERSION_ENV = "ZCODE_APP_VERSION" as const;
+export const ZCODE_BUILD_COMMIT_ID_ENV = "ZCODE_BUILD_COMMIT_ID" as const;
+
+// ── 运行时环境变量（不经过编译打包，启动时从 process.env 读取） ──
+// 启用调试模式，值为 inspect-brk 的端口号，如 ZCODE_DEBUG=9230
+export const RUNTIME_ZCODE_DEBUG =
+  typeof process !== "undefined" ? process.env.ZCODE_DEBUG : undefined;
+
+// 恢复原因：写死 false 会让运行时已配置的数仓/ARMS 永远空转。
+// 功能保持可用；实际出网由各出口的运行时端点检查决定，未配置不上报。
+export const ZCODE_TELEMETRY_ENABLED: boolean = true;
+
+/** 数仓事件上报端点：由运行时环境变量提供，未配置即停用，构建产物不内嵌。 */
+export const ZCODE_TELEMETRY_REPORT_ENDPOINT =
+  typeof process !== "undefined" ? (process.env.ZCODE_TELEMETRY_REPORT_ENDPOINT ?? "") : "";
+
+/** ARMS RUM 接入端点：由运行时环境变量提供，未配置即停用，构建产物不内嵌。 */
+export const ZCODE_ARMS_RUM_ENDPOINT =
+  typeof process !== "undefined" ? (process.env.ZCODE_ARMS_RUM_ENDPOINT ?? "") : "";
+
+/** 将本地运行态与编译期 ZCODE_ENV 映射为 ARMS 控制台识别的上报环境标签 */
+export function mapZCodeEnvToArmsRumEnv(runtimeEnv: ZCodeRuntimeEnv): ArmsRumEnv {
+  return runtimeEnv !== "development" && ZCODE_ENV === "production" ? "prod" : "local";
+}

package/server/vendor/zcode/packages/shared/src/execution-output-preview.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+
+const OUTPUT_PREVIEW_MAX_CHARACTERS = 4096;
+/** 两端共用的 Bash 有界输出内容；不包含 replayable 传输恢复状态。 */
+export const executionOutputPreviewSchema = z
+  .object({
+    text: z.string().max(OUTPUT_PREVIEW_MAX_CHARACTERS),
+    fullText: z.string().max(OUTPUT_PREVIEW_MAX_CHARACTERS),
+    totalLines: z.number().int().nonnegative(),
+    totalBytes: z.number().int().nonnegative(),
+    linesEstimated: z.boolean(),
+  })
+  .strict();
+export type ExecutionOutputPreview = z.infer<typeof executionOutputPreviewSchema>;