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

package/server/vendor/zcode/packages/rpc/src/proxy-channel.ts

@@ -0,0 +1,213 @@
+/**
+ * Layer 5: ProxyChannel —— 服务自动代理（杀手锏）
+ *
+ * 这是让 VS Code 开发者效率极高的关键抽象。
+ *
+ * 没有 ProxyChannel 时，你需要为每个服务手写 IServerChannel：
+ *   class FileServiceChannel implements IServerChannel {
+ *     call(ctx, command, arg) {
+ *       switch (command) {
+ *         case 'readFile': return this.service.readFile(arg[0]);
+ *         case 'writeFile': return this.service.writeFile(arg[0], arg[1]);
+ *         // ... 每个方法都要手动映射
+ *       }
+ *     }
+ *   }
+ *
+ * 有了 ProxyChannel，一行代码搞定：
+ *   const channel = ProxyChannel.fromService(fileService);
+ *   // 自动把所有方法映射为 call，所有 on* 事件映射为 listen
+ *
+ * 客户端同样一行：
+ *   const fileService = ProxyChannel.toService<IFileService>(channel);
+ *   await fileService.readFile(uri);  // 就像调用本地方法！
+ *
+ * 原理：
+ * - fromService: 遍历 service 的属性，方法 → call，on* 事件 → listen
+ * - toService: 利用 ES6 Proxy 拦截属性访问，自动分派到 call/listen
+ */
+
+import { Event, Emitter, IDisposable, DisposableStore } from "./foundation.js";
+import { IChannel, IServerChannel } from "./channels.js";
+
+// ============================================================================
+// ProxyChannel
+// ============================================================================
+
+export namespace ProxyChannel {
+  /**
+   * 服务端：把一个 service 对象自动包装为 IServerChannel
+   *
+   * 约定：
+   * - 以 on + 大写字母开头的属性视为事件 (如 onDidChange)
+   * - 以 onDynamic + 大写字母开头的视为动态事件（方法，调用后返回事件）
+   * - 其他方法视为 RPC 方法
+   */
+  export function fromService<TContext>(
+    service: unknown,
+    disposables?: DisposableStore,
+  ): IServerChannel<TContext> {
+    const handler = service as { [key: string]: unknown };
+
+    // 预缓存所有事件并 buffer
+    const eventMap = new Map<string, Event<unknown>>();
+    for (const key in handler) {
+      if (isEvent(key) && !isDynamicEvent(key) && typeof handler[key] === "function") {
+        // 把事件 buffer 化：即使没人订阅，事件也不会丢失
+        eventMap.set(key, bufferEvent(handler[key] as Event<unknown>));
+      }
+    }
+
+    return {
+      listen<T>(_ctx: TContext, event: string, arg?: any): Event<T> {
+        // 先查缓存
+        const cached = eventMap.get(event);
+        if (cached) {
+          return cached as Event<T>;
+        }
+
+        const target = handler[event];
+        if (typeof target === "function") {
+          // 动态事件：onDynamicXxx(arg) 返回一个 Event
+          if (isDynamicEvent(event)) {
+            return target.call(handler, arg);
+          }
+          // 延迟发现的事件（Proxy 服务可能不会在 for-in 中出现）
+          if (isEvent(event)) {
+            eventMap.set(event, bufferEvent(handler[event] as Event<unknown>));
+            return eventMap.get(event) as Event<T>;
+          }
+        }
+
+        throw new Error(`Event not found: ${event}`);
+      },
+
+      call<T>(_ctx: TContext, command: string, args?: any[]): Promise<T> {
+        const target = handler[command];
+        if (typeof target === "function") {
+          let result = target.apply(handler, args || []);
+          if (!(result instanceof Promise)) {
+            result = Promise.resolve(result);
+          }
+          return result;
+        }
+        throw new Error(`Method not found: ${command}`);
+      },
+    };
+  }
+
+  /**
+   * 客户端：把一个 IChannel 包装成类型安全的 service 对象
+   *
+   * 利用 ES6 Proxy 拦截所有属性访问：
+   * - 访问 on* → channel.listen(propKey)
+   * - 访问其他 → 返回一个函数，调用时变成 channel.call(propKey, args)
+   */
+  export function toService<T extends object>(
+    channel: IChannel,
+    options?: { context?: unknown },
+  ): T {
+    return new Proxy({} as T, {
+      get(target: T, propKey: PropertyKey, receiver: object) {
+        // React 开发态、日志工具和浏览器运行时会探测对象的 Symbol / then 等内置属性。
+        // 之前这里把所有未知属性都强行当成 RPC 成员处理，读取 Symbol.toStringTag 会直接抛错，
+        // 读取 then 还会把普通 service 误判成 thenable，导致远程 workspace 在选目录后重渲染时炸掉。
+        // 这类运行时探测属性应该回退到普通对象语义，而不是走 RPC。
+        if (typeof propKey === "symbol") {
+          return Reflect.get(target as object, propKey, receiver);
+        }
+
+        if (typeof propKey === "string") {
+          if (propKey === "then") {
+            return undefined;
+          }
+
+          // 动态事件
+          if (isDynamicEvent(propKey)) {
+            return (arg: unknown) => channel.listen(propKey, arg);
+          }
+
+          // 普通事件
+          if (isEvent(propKey)) {
+            return channel.listen(propKey);
+          }
+
+          // 方法调用
+          return async (...args: unknown[]) => {
+            // 可选：注入 context 作为第一个参数
+            const methodArgs = options?.context !== undefined ? [options.context, ...args] : args;
+            return channel.call(propKey, methodArgs);
+          };
+        }
+
+        return Reflect.get(target as object, propKey, receiver);
+      },
+    });
+  }
+}
+
+// ============================================================================
+// 辅助函数
+// ============================================================================
+
+/** 匹配 onXxx 事件命名约定 */
+function isEvent(name: string): boolean {
+  return (
+    name.length >= 3 &&
+    name[0] === "o" &&
+    name[1] === "n" &&
+    name.charCodeAt(2) >= 65 && // A
+    name.charCodeAt(2) <= 90
+  ); // Z
+}
+
+/** 匹配 onDynamicXxx 动态事件命名约定 */
+function isDynamicEvent(name: string): boolean {
+  return (
+    name.length >= 10 &&
+    name.startsWith("onDynamic") &&
+    name.charCodeAt(9) >= 65 &&
+    name.charCodeAt(9) <= 90
+  );
+}
+
+/**
+ * 缓冲事件：确保在订阅之前触发的事件不会丢失。
+ * 未订阅时事件存入队列，一有订阅者就 flush。
+ */
+function bufferEvent<T>(event: Event<T>): Event<T> {
+  let buffer: T[] = [];
+  let flushing = false;
+  let listener: IDisposable | undefined;
+
+  const emitter = new Emitter<T>({
+    onWillAddFirstListener: () => {
+      listener = event((e) => {
+        if (flushing) {
+          emitter.fire(e);
+        } else {
+          buffer.push(e);
+        }
+      });
+    },
+    onDidRemoveLastListener: () => {
+      listener?.dispose();
+      listener = undefined;
+      buffer = [];
+    },
+  });
+
+  // 一旦有订阅者，先 flush 缓冲区
+  const originalEvent = emitter.event;
+  return (listener_fn) => {
+    const disposable = originalEvent(listener_fn);
+    if (!flushing) {
+      flushing = true;
+      for (const item of buffer) {
+        emitter.fire(item);
+      }
+      buffer = [];
+    }
+    return disposable;
+  };
+}

package/server/vendor/zcode/packages/rpc/src/serialization.ts

@@ -0,0 +1,291 @@
+/**
+ * Layer 1: 二进制序列化
+ *
+ * RPC 消息需要编码为二进制才能通过 IMessagePassingProtocol 传输。
+ * 这里实现了 VS Code 的自定义序列化协议：
+ *
+ * 格式: [1 byte 类型标签] [VQL 编码的长度] [数据]
+ *
+ * VQL (Variable-Length Quantity) 用 7 bit 存数据，最高位标记是否还有后续字节。
+ * 小数字只需 1 byte，大数字按需扩展，比固定 4 byte 更紧凑。
+ */
+
+import { VSBuffer } from "./buffer.js";
+
+// ============================================================================
+// Reader / Writer 接口
+// ============================================================================
+
+export interface IReader {
+  read(bytes: number): VSBuffer;
+}
+
+export interface IWriter {
+  write(buffer: VSBuffer): void;
+}
+
+/**
+ * BufferReader: 从一个 VSBuffer 中按顺序读取数据。
+ * 内部维护一个 pos 游标。
+ */
+export class BufferReader implements IReader {
+  private pos = 0;
+
+  constructor(private buffer: VSBuffer) {}
+
+  read(bytes: number): VSBuffer {
+    const result = this.buffer.slice(this.pos, this.pos + bytes);
+    this.pos += result.byteLength;
+    return result;
+  }
+}
+
+/**
+ * BufferWriter: 收集多个写入的 buffer，最后通过 .buffer 属性一次性拼接。
+ * 避免了写入时频繁的内存拷贝。
+ */
+export class BufferWriter implements IWriter {
+  private buffers: VSBuffer[] = [];
+
+  get buffer(): VSBuffer {
+    return VSBuffer.concat(this.buffers);
+  }
+
+  write(buffer: VSBuffer): void {
+    this.buffers.push(buffer);
+  }
+}
+
+// ============================================================================
+// VQL 编码
+// ============================================================================
+
+/**
+ * 读取 VQL 编码的整数
+ * @see https://en.wikipedia.org/wiki/Variable-length_quantity
+ */
+function readIntVQL(reader: IReader): number {
+  let value = 0;
+  for (let n = 0; ; n += 7) {
+    const next = reader.read(1);
+    value |= (next.buffer[0] & 0b01111111) << n;
+    if (!(next.buffer[0] & 0b10000000)) {
+      return value;
+    }
+  }
+}
+
+const vqlZero = createOneByteBuffer(0);
+
+/**
+ * 写入 VQL 编码的整数
+ * 例: 0 → [0x00], 127 → [0x7F], 128 → [0x80, 0x01]
+ */
+function writeInt32VQL(writer: IWriter, value: number): void {
+  if (value === 0) {
+    writer.write(vqlZero);
+    return;
+  }
+  let len = 0;
+  for (let v = value; v !== 0; v = v >>> 7) {
+    len++;
+  }
+
+  const scratch = VSBuffer.alloc(len);
+  for (let i = 0; value !== 0; i++) {
+    scratch.buffer[i] = value & 0b01111111;
+    value = value >>> 7;
+    if (value > 0) {
+      scratch.buffer[i] |= 0b10000000;
+    }
+  }
+  writer.write(scratch);
+}
+
+// ============================================================================
+// 数据类型标签
+// ============================================================================
+
+enum DataType {
+  Undefined = 0,
+  String = 1,
+  Buffer = 2,
+  VSBuffer = 3,
+  Array = 4,
+  Object = 5, // JSON fallback
+  Int = 6, // VQL 编码的整数
+}
+
+function createOneByteBuffer(value: number): VSBuffer {
+  const result = VSBuffer.alloc(1);
+  result.writeUInt8(value, 0);
+  return result;
+}
+
+/** 预创建的类型标签 buffer，避免每次序列化都分配内存 */
+const BufferPresets = {
+  Undefined: createOneByteBuffer(DataType.Undefined),
+  String: createOneByteBuffer(DataType.String),
+  Buffer: createOneByteBuffer(DataType.Buffer),
+  VSBuffer: createOneByteBuffer(DataType.VSBuffer),
+  Array: createOneByteBuffer(DataType.Array),
+  Object: createOneByteBuffer(DataType.Object),
+  Int: createOneByteBuffer(DataType.Int),
+};
+
+const RPC_NESTED_UINT8_ARRAY_MARKER = "__zcode_rpc_nested_uint8array_v1";
+const RPC_NESTED_UINT8_ARRAY_BASE64_KEY = "base64";
+
+// ============================================================================
+// serialize / deserialize
+// ============================================================================
+
+/**
+ * 序列化任意数据到 writer。
+ *
+ * 格式：[1 byte 类型] [VQL 长度(如果需要)] [数据]
+ *
+ * 每条 RPC 消息 = serialize(header) + serialize(body)
+ * header 通常是 [RequestType, id, channelName, methodName]
+ * body 是方法参数或返回值
+ */
+export function serialize(writer: IWriter, data: any): void {
+  if (typeof data === "undefined") {
+    writer.write(BufferPresets.Undefined);
+  } else if (typeof data === "string") {
+    const buffer = VSBuffer.fromString(data);
+    writer.write(BufferPresets.String);
+    writeInt32VQL(writer, buffer.byteLength);
+    writer.write(buffer);
+  } else if (data instanceof VSBuffer) {
+    writer.write(BufferPresets.VSBuffer);
+    writeInt32VQL(writer, data.byteLength);
+    writer.write(data);
+  } else if (data instanceof Uint8Array) {
+    const buffer = VSBuffer.wrap(data);
+    writer.write(BufferPresets.Buffer);
+    writeInt32VQL(writer, buffer.byteLength);
+    writer.write(buffer);
+  } else if (Array.isArray(data)) {
+    writer.write(BufferPresets.Array);
+    writeInt32VQL(writer, data.length);
+    for (const el of data) {
+      serialize(writer, el);
+    }
+  } else if (typeof data === "number" && (data | 0) === data) {
+    // 整数用 VQL 编码，比 JSON 更紧凑
+    writer.write(BufferPresets.Int);
+    writeInt32VQL(writer, data);
+  } else {
+    // 对象字段里的 Uint8Array 之前会被 JSON.stringify 展开成 {"0":...}，
+    // 远端 RPC 收到后不再是二进制，skill sync 这类归档传输会在解压阶段失败。
+    // 这里保持 Object JSON fallback 的协议形态，只对嵌套 Uint8Array 加标记并在反序列化时恢复。
+    const buffer = VSBuffer.fromString(JSON.stringify(data, encodeRpcJsonValue));
+    writer.write(BufferPresets.Object);
+    writeInt32VQL(writer, buffer.byteLength);
+    writer.write(buffer);
+  }
+}
+
+/**
+ * 从 reader 反序列化数据
+ */
+export function deserialize(reader: IReader): any {
+  const type = reader.read(1).readUInt8(0);
+
+  switch (type) {
+    case DataType.Undefined:
+      return undefined;
+    case DataType.String:
+      return reader.read(readIntVQL(reader)).toString();
+    case DataType.Buffer:
+      return reader.read(readIntVQL(reader)).buffer;
+    case DataType.VSBuffer:
+      return reader.read(readIntVQL(reader));
+    case DataType.Array: {
+      const length = readIntVQL(reader);
+      const result: any[] = [];
+      for (let i = 0; i < length; i++) {
+        result.push(deserialize(reader));
+      }
+      return result;
+    }
+    case DataType.Object:
+      return JSON.parse(reader.read(readIntVQL(reader)).toString(), decodeRpcJsonValue);
+    case DataType.Int:
+      return readIntVQL(reader);
+  }
+}
+
+function encodeRpcJsonValue(_key: string, value: unknown): unknown {
+  if (value instanceof Uint8Array) {
+    return {
+      [RPC_NESTED_UINT8_ARRAY_MARKER]: true,
+      [RPC_NESTED_UINT8_ARRAY_BASE64_KEY]: bytesToBase64(value),
+    };
+  }
+  return value;
+}
+
+function decodeRpcJsonValue(_key: string, value: unknown): unknown {
+  if (!isRpcEncodedUint8Array(value)) {
+    return value;
+  }
+  return base64ToBytes(value[RPC_NESTED_UINT8_ARRAY_BASE64_KEY]);
+}
+
+function isRpcEncodedUint8Array(value: unknown): value is {
+  [RPC_NESTED_UINT8_ARRAY_MARKER]: true;
+  [RPC_NESTED_UINT8_ARRAY_BASE64_KEY]: string;
+} {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    record[RPC_NESTED_UINT8_ARRAY_MARKER] === true &&
+    typeof record[RPC_NESTED_UINT8_ARRAY_BASE64_KEY] === "string" &&
+    Object.keys(record).length === 2
+  );
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  const bufferCtor = (
+    globalThis as {
+      Buffer?: {
+        from(input: Uint8Array): { toString(encoding: "base64"): string };
+      };
+    }
+  ).Buffer;
+  if (bufferCtor) {
+    return bufferCtor.from(bytes).toString("base64");
+  }
+
+  let binary = "";
+  const chunkSize = 0x8000;
+  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+    const chunk = bytes.subarray(offset, offset + chunkSize);
+    binary += String.fromCharCode(...chunk);
+  }
+  return globalThis.btoa(binary);
+}
+
+function base64ToBytes(base64: string): Uint8Array {
+  const bufferCtor = (
+    globalThis as {
+      Buffer?: {
+        from(input: string, encoding: "base64"): Uint8Array;
+      };
+    }
+  ).Buffer;
+  if (bufferCtor) {
+    return new Uint8Array(bufferCtor.from(base64, "base64"));
+  }
+
+  const binary = globalThis.atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}

package/server/vendor/zcode/packages/shared/src/account-provider-state.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+
+// 原因随 Account State 发送，必须与严格协议共用枚举，避免整份快照被拒绝。
+// credential-failed 表示凭据获取/校验失败，不能据此断言 OAuth 已失效。
+export const accountProviderUnavailableReasonSchema = z.enum([
+  "not-authenticated",
+  "not-connected",
+  "credential-failed",
+  "not-entitled",
+]);
+export type AccountProviderUnavailableReason = z.infer<
+  typeof accountProviderUnavailableReasonSchema
+>;

package/server/vendor/zcode/packages/shared/src/background-bash-output.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+export const BACKGROUND_BASH_OUTPUT_MAX_BYTES = 8192;
+
+/** 后台详情的单次文件快照；不进入 conversation snapshot 或持久化事件。 */
+export const backgroundBashOutputSchema = z.strictObject({
+  kind: z.literal("output"),
+  workId: z.string().min(1),
+  status: z.enum(["running", "completed", "failed", "timed_out", "cancelled", "spawn_error"]),
+  output: z.string().max(BACKGROUND_BASH_OUTPUT_MAX_BYTES),
+  truncated: z.boolean(),
+  outputPath: z.string().min(1),
+});
+
+export const backgroundBashOutputResultSchema = z.union([
+  backgroundBashOutputSchema,
+  z.strictObject({
+    kind: z.enum(["unavailable", "unsupported", "read_failed"]),
+    workId: z.string().min(1),
+    code: z.string().optional(),
+  }),
+]);
+export type BackgroundBashOutput = z.infer<typeof backgroundBashOutputSchema>;
+export type BackgroundBashOutputResult = z.infer<typeof backgroundBashOutputResultSchema>;