pneuma-skills 2.9.0 → 2.9.2

package/backends/claude-code/index.ts

@@ -1,8 +1,8 @@
 /**
- * ClaudeCodeBackend — AgentBackend 的 Claude Code 实现。
+ * ClaudeCodeBackend — Claude Code implementation of AgentBackend.
  *
- * 包装 CliLauncher，实现标准 AgentBackend 接口。
- * 以 Claude Code 协议为事实标准。
+ * Wraps CliLauncher and implements the standard AgentBackend interface.
+ * Uses the Claude Code protocol as the source of truth.
  */
 
 import type {
@@ -74,7 +74,7 @@ export class ClaudeCodeBackend implements AgentBackend {
     this.launcher.onSessionExited(cb);
   }
 
-  /** SdkSessionInfo → AgentSessionInfo 映射 */
+  /** SdkSessionInfo → AgentSessionInfo mapping */
   private toAgentSessionInfo(info: SdkSessionInfo): AgentSessionInfo {
     return {
       sessionId: info.sessionId,

package/core/__tests__/agent-backend.test.ts

@@ -1,12 +1,12 @@
 /**
- * AgentBackend 契约测试
+ * AgentBackend contract tests
  *
- * 验证 AgentBackend 接口约束：
- * - 生命周期管理 (launch/kill/getSession)
- * - 能力声明完整性
- * - 协议适配器契约
+ * Validates AgentBackend interface constraints:
+ * - Lifecycle management (launch/kill/getSession)
+ * - Capability declaration completeness
+ * - Protocol adapter contract
  *
- * 基于 Claude Code 作为事实标准设计。
+ * Designed with Claude Code as the de facto standard.
  */
 
 import { describe, test, expect } from "bun:test";
@@ -18,7 +18,7 @@ import type {
   AgentProtocolAdapter,
 } from "../types/index.js";
 
-// ── Mock AgentBackend (模拟 ClaudeCodeBackend 的行为) ────────────────────────
+// ── Mock AgentBackend (simulates ClaudeCodeBackend behavior) ─────────────────
 
 function createMockBackend(): AgentBackend {
   const sessions = new Map<string, AgentSessionInfo>();
@@ -90,7 +90,7 @@ function createMockBackend(): AgentBackend {
   };
 }
 
-// ── AgentBackend 生命周期 ────────────────────────────────────────────────────
+// ── AgentBackend lifecycle ───────────────────────────────────────────────────
 
 describe("AgentBackend lifecycle", () => {
   test("launch creates a session in starting state", () => {

package/core/__tests__/mode-loader-external.test.ts

@@ -1,7 +1,7 @@
 /**
  * Mode Loader — External mode registration tests
  *
- * 验证 registerExternalMode 和 loadModeManifest 对外部 mode 的支持。
+ * Validates registerExternalMode and loadModeManifest support for external modes.
  */
 
 import { describe, test, expect } from "bun:test";

package/core/__tests__/mode-loader.test.ts

@@ -1,20 +1,20 @@
 /**
- * Mode Loader 测试
+ * Mode Loader tests
  *
- * 验证 mode 加载机制：
- * - 加载内置 mode 成功
- * - 加载未知 mode 报错
- * - 加载的 mode 符合 ModeDefinition 契约
+ * Validates mode loading mechanics:
+ * - Successfully loads built-in modes
+ * - Throws error for unknown modes
+ * - Loaded modes conform to the ModeDefinition contract
  */
 
 import { describe, test, expect } from "bun:test";
 import type { ModeDefinition } from "../types/index.js";
 
-// ── Mode Loader 本身还未实现，这里用 mock 定义预期行为 ─────────────────────────
+// ── Mode Loader not yet implemented; using mocks to define expected behavior ──
 
 /**
- * Mock mode loader — 定义 loadMode 的预期行为。
- * 实际实现在 core/mode-loader.ts (v1.0 代码阶段创建)。
+ * Mock mode loader — defines the expected behavior of loadMode.
+ * Actual implementation is in core/mode-loader.ts (created during v1.0 code phase).
  */
 const builtinModes: Record<string, ModeDefinition> = {};
 
@@ -35,7 +35,7 @@ function listModes(): string[] {
   return Object.keys(builtinModes);
 }
 
-// ── 辅助：创建最小合法 ModeDefinition ────────────────────────────────────────
+// ── Helper: create minimal valid ModeDefinition ─────────────────────────────
 
 function createMockModeDefinition(name: string): ModeDefinition {
   return {

package/core/__tests__/mode-manifest.test.ts

@@ -1,16 +1,16 @@
 /**
- * ModeManifest 契约测试
+ * ModeManifest contract tests
  *
- * 验证 ModeManifest 类型约束：
- * - 必填字段完整性
- * - 可选字段默认值语义
- * - 字段值的业务约束
+ * Validates ModeManifest type constraints:
+ * - Required field completeness
+ * - Optional field default value semantics
+ * - Business constraints on field values
  */
 
 import { describe, test, expect } from "bun:test";
 import type { ModeManifest, SkillConfig, ViewerConfig } from "../types/index.js";
 
-// ── 辅助：创建最小合法 manifest ──────────────────────────────────────────────
+// ── Helper: create minimal valid manifest ────────────────────────────────────
 
 function createMinimalManifest(overrides?: Partial<ModeManifest>): ModeManifest {
   return {
@@ -31,7 +31,7 @@ function createMinimalManifest(overrides?: Partial<ModeManifest>): ModeManifest
   };
 }
 
-// ── ModeManifest 必填字段 ────────────────────────────────────────────────────
+// ── ModeManifest required fields ─────────────────────────────────────────────
 
 describe("ModeManifest required fields", () => {
   test("minimal manifest has all required fields", () => {

package/core/__tests__/mode-resolver.test.ts

@@ -1,11 +1,11 @@
 /**
- * Mode Resolver 测试
+ * Mode Resolver tests
  *
- * 验证 mode 来源解析:
- * - builtin mode 名称识别
- * - local path 解析 (绝对路径、相对路径、~ 展开)
- * - github 格式解析
- * - 错误处理
+ * Validates mode source resolution:
+ * - Built-in mode name recognition
+ * - Local path resolution (absolute paths, relative paths, ~ expansion)
+ * - GitHub format parsing
+ * - Error handling
  */
 
 import { describe, test, expect } from "bun:test";

package/core/__tests__/viewer-contract.test.ts

@@ -1,13 +1,13 @@
 /**
- * ViewerContract 契约测试
+ * ViewerContract contract tests
  *
- * 验证 ViewerContract 接口约束：
- * - PreviewComponent 是有效的 React 组件类型
- * - extractContext 返回格式正确的上下文字符串
- * - updateStrategy 是合法枚举值
- * - workspace model 约束
- * - action descriptors 结构
- * - 向后兼容
+ * Validates ViewerContract interface constraints:
+ * - PreviewComponent is a valid React component type
+ * - extractContext returns a properly formatted context string
+ * - updateStrategy is a valid enum value
+ * - workspace model constraints
+ * - action descriptor structure
+ * - backward compatibility
  */
 
 import { describe, test, expect } from "bun:test";
@@ -21,7 +21,7 @@ import type {
   ViewerActionDescriptor,
 } from "../types/index.js";
 
-// ── 辅助：创建 mock viewer ─────────────────────────────────────────────────
+// ── Helper: create mock viewer ───────────────────────────────────────────────
 
 function createMockViewer(
   overrides?: Partial<ViewerContract>,
@@ -34,7 +34,7 @@ function createMockViewer(
   };
 }
 
-// ── ViewerContract 基本约束 ─────────────────────────────────────────────────
+// ── ViewerContract basic constraints ─────────────────────────────────────────
 
 describe("ViewerContract", () => {
   test("PreviewComponent is a function (React component)", () => {
@@ -91,7 +91,7 @@ describe("ViewerContract", () => {
   });
 });
 
-// ── ViewerPreviewProps 完整性 ───────────────────────────────────────────────
+// ── ViewerPreviewProps completeness ──────────────────────────────────────────
 
 describe("ViewerPreviewProps shape", () => {
   test("contains all required fields", () => {
@@ -118,7 +118,7 @@ describe("ViewerPreviewProps shape", () => {
   });
 });
 
-// ── extractContext 边界条件 ──────────────────────────────────────────────────
+// ── extractContext edge cases ────────────────────────────────────────────────
 
 describe("extractContext edge cases", () => {
   test("handles selection without file context", () => {

package/core/mode-loader.ts

@@ -1,21 +1,21 @@
 /**
- * Mode Loader — 解析、安装、加载 Mode。
+ * Mode Loader — resolve, install, and load Modes.
  *
- * 支持三种来源:
- * - builtin: 内置 mode，从 modes/ 目录动态 import
- * - local: 本地文件系统路径
- * - github: GitHub 仓库 (通过 mode-resolver 克隆到本地缓存)
+ * Supports three sources:
+ * - builtin: built-in modes, dynamically imported from the modes/ directory
+ * - local: local filesystem path
+ * - github: GitHub repository (cloned to local cache via mode-resolver)
  *
- * 核心流程: resolveMode → ensureInstalled → loadFromSource
+ * Core flow: resolveMode → ensureInstalled → loadFromSource
  */
 
 import type { ModeManifest } from "./types/mode-manifest.js";
 import type { ModeDefinition } from "./types/mode-definition.js";
 
 /**
- * Mode 来源类型:
- * - "builtin" — 内置 mode，从 modes/ 目录动态 import
- * - "external" — 外部 mode，从绝对路径动态 import (local path 或 github clone)
+ * Mode source type:
+ * - "builtin" — built-in mode, dynamically imported from the modes/ directory
+ * - "external" — external mode, dynamically imported from an absolute path (local path or github clone)
  */
 type ModeSource =
   | {
@@ -31,7 +31,7 @@ type ModeSource =
       definitionLoader: () => Promise<ModeDefinition>;
     };
 
-/** 内置 mode 注册表 — 全部使用动态 import */
+/** Built-in mode registry — all use dynamic import */
 const builtinModes: Record<string, ModeSource> = {
   doc: {
     type: "builtin",
@@ -84,14 +84,14 @@ const builtinModes: Record<string, ModeSource> = {
   },
 };
 
-/** 外部 mode 注册表 — 由 CLI 在启动时通过 registerExternalMode 注册 */
+/** External mode registry — registered by the CLI at startup via registerExternalMode */
 const externalModes: Record<string, ModeSource> = {};
 
 // ── Public API ───────────────────────────────────────────────────────────────
 
 /**
- * 加载 Mode 的完整定义 (manifest + viewer)。
- * 前端使用 — 需要 PreviewComponent。
+ * Load a Mode's full definition (manifest + viewer).
+ * Used by the frontend — requires PreviewComponent.
  */
 export async function loadMode(name: string): Promise<ModeDefinition> {
   const source = resolveMode(name);
@@ -100,8 +100,8 @@ export async function loadMode(name: string): Promise<ModeDefinition> {
 }
 
 /**
- * 只加载 Mode 的 manifest (不含 React 组件)。
- * 后端使用 — 只需要配置信息。
+ * Load only the Mode's manifest (without React components).
+ * Used by the backend — only needs config information.
  */
 export async function loadModeManifest(name: string): Promise<ModeManifest> {
   const source = resolveMode(name);
@@ -110,27 +110,27 @@ export async function loadModeManifest(name: string): Promise<ModeManifest> {
 }
 
 /**
- * 列出所有已注册的 mode 名称 (包括 builtin 和已注册的 external)。
+ * List all registered mode names (including builtin and registered external).
  */
 export function listModes(): string[] {
   return [...Object.keys(builtinModes), ...Object.keys(externalModes)];
 }
 
 /**
- * 列出内置 mode 名称。
+ * List built-in mode names.
  */
 export function listBuiltinModes(): string[] {
   return Object.keys(builtinModes);
 }
 
 /**
- * 注册外部 mode (由 CLI 在启动时调用)。
+ * Register an external mode (called by the CLI at startup).
  *
- * Backend context (Bun): 直接用 import() 加载绝对路径。
- * Frontend context (browser/Vite): 用 /@fs/ URL 加载。
+ * Backend context (Bun): uses import() with absolute path.
+ * Frontend context (browser/Vite): uses /@fs/ URL.
  *
- * @param name — Mode 名称 (用于注册和查找)
- * @param absPath — Mode 包的绝对路径
+ * @param name — Mode name (for registration and lookup)
+ * @param absPath — Absolute path to the Mode package
  */
 export function registerExternalMode(name: string, absPath: string): void {
   const isBrowser = typeof window !== "undefined";
@@ -185,7 +185,7 @@ export function registerExternalMode(name: string, absPath: string): void {
 
 // ── Internal ─────────────────────────────────────────────────────────────────
 
-/** 解析 mode 来源 (查 builtin 和 external 注册表) */
+/** Resolve mode source (checks builtin and external registries) */
 function resolveMode(name: string): ModeSource {
   // Check external modes first (allows overriding builtin names)
   const external = externalModes[name];
@@ -200,13 +200,13 @@ function resolveMode(name: string): ModeSource {
   );
 }
 
-/** 确保 mode 已安装 (builtin 直接跳过，external 已由 mode-resolver 处理) */
+/** Ensure mode is installed (builtin skips directly, external already handled by mode-resolver) */
 async function ensureInstalled(_source: ModeSource): Promise<void> {
   // Both builtin and external modes are already resolved to local paths
   return;
 }
 
-/** 从已安装的 source 加载完整 ModeDefinition */
+/** Load full ModeDefinition from an installed source */
 async function loadDefinition(source: ModeSource): Promise<ModeDefinition> {
   return source.definitionLoader();
 }

package/core/mode-resolver.ts

@@ -1,12 +1,12 @@
 /**
- * Mode Resolver — 解析 mode 来源并确保本地可用。
+ * Mode Resolver — resolve mode sources and ensure local availability.
  *
- * 支持三种 mode 来源:
- * - builtin: "doc", "slide" — 内置 mode，从 modes/ 目录加载
- * - local: "/abs/path" 或 "./rel/path" — 本地文件系统路径
- * - github: "github:user/repo" 或 "github:user/repo#branch" — GitHub 仓库
+ * Supports three mode sources:
+ * - builtin: "doc", "slide" — built-in modes, loaded from the modes/ directory
+ * - local: "/abs/path" or "./rel/path" — local filesystem path
+ * - github: "github:user/repo" or "github:user/repo#branch" — GitHub repository
  *
- * GitHub 仓库会被 clone 到 ~/.pneuma/modes/{user}-{repo}/ 缓存目录。
+ * GitHub repositories are cloned to the ~/.pneuma/modes/{user}-{repo}/ cache directory.
  */
 
 import { resolve, join, basename } from "node:path";

package/core/types/agent-backend.ts

@@ -1,14 +1,14 @@
 /**
- * AgentBackend — Agent 运行时抽象
+ * AgentBackend — Agent runtime abstraction
  *
- * 当前实现以 Claude Code 作为首个参考 backend，但对外契约已经拆成两层：
- * - AgentBackend: 生命周期与能力声明
- * - AgentProtocolAdapter: 后端私有协议到运行时标准消息的翻译
+ * The current implementation uses Claude Code as the first reference backend, but the external contract is split into two layers:
+ * - AgentBackend: lifecycle and capability declarations
+ * - AgentProtocolAdapter: translation from backend-specific protocol to runtime standard messages
  *
- * 前端和大部分服务端逻辑依赖的是标准 session 状态，而不是具体 backend 的 wire protocol。
+ * The frontend and most server-side logic depend on normalized session state, not a specific backend's wire protocol.
  */
 
-// ── Agent 生命周期 ───────────────────────────────────────────────────────────
+// ── Agent Lifecycle ──────────────────────────────────────────────────────────
 
 export type AgentBackendType = "claude-code" | "codex";
 
@@ -19,108 +19,108 @@ export interface AgentBackendDescriptor {
   implemented: boolean;
 }
 
-/** Agent 会话信息 */
+/** Agent session info */
 export interface AgentSessionInfo {
-  /** Server 路由用 session ID (UUID) */
+  /** Server routing session ID (UUID) */
   sessionId: string;
-  /** Agent 内部的 session ID (用于 resume，如 Claude Code 的 --resume) */
+  /** Agent's internal session ID (for resume, e.g. Claude Code's --resume) */
   agentSessionId?: string;
-  /** 进程 PID (如果是子进程模式) */
+  /** Process PID (if using child process mode) */
   pid?: number;
-  /** 会话状态 */
+  /** Session state */
   state: "starting" | "connected" | "running" | "exited";
-  /** 退出码 (state=exited 时有值) */
+  /** Exit code (present when state=exited) */
   exitCode?: number | null;
-  /** 工作目录 */
+  /** Working directory */
   cwd: string;
-  /** 创建时间 */
+  /** Creation timestamp */
   createdAt: number;
 }
 
-/** Agent 启动选项 */
+/** Agent launch options */
 export interface AgentLaunchOptions {
-  /** 工作目录 */
+  /** Working directory */
   cwd: string;
-  /** 权限模式 */
+  /** Permission mode */
   permissionMode?: string;
-  /** 模型 */
+  /** Model */
   model?: string;
-  /** 复用已有的 server session ID (而非生成新的) */
+  /** Reuse an existing server session ID (instead of generating a new one) */
   sessionId?: string;
-  /** Agent 内部 session ID (用于恢复之前的会话) */
+  /** Agent's internal session ID (for resuming a previous session) */
   resumeSessionId?: string;
-  /** 额外环境变量 */
+  /** Additional environment variables */
   env?: Record<string, string>;
 }
 
-/** Agent 后端 — 管理 Agent 进程的生命周期 */
+/** Agent backend — manages the Agent process lifecycle */
 export interface AgentBackend {
-  /** 后端唯一标识 */
+  /** Unique backend identifier */
   readonly name: AgentBackendType;
 
-  /** 能力声明 */
+  /** Capability declarations */
   readonly capabilities: AgentCapabilities;
 
-  /** 启动一个新的 Agent 会话 */
+  /** Launch a new Agent session */
   launch(options: AgentLaunchOptions): AgentSessionInfo;
 
-  /** 获取会话信息 */
+  /** Get session info */
   getSession(sessionId: string): AgentSessionInfo | undefined;
 
-  /** 会话是否存活 */
+  /** Check if a session is alive */
   isAlive(sessionId: string): boolean;
 
-  /** 标记会话为已连接 (WS 建立时调用) */
+  /** Mark session as connected (called when WS is established) */
   markConnected(sessionId: string): void;
 
-  /** 存储 Agent 内部 session ID (从 Agent 初始化消息中获取) */
+  /** Store the Agent's internal session ID (obtained from the Agent's init message) */
   setAgentSessionId(sessionId: string, agentSessionId: string): void;
 
-  /** 终止一个会话 */
+  /** Kill a session */
   kill(sessionId: string): Promise<boolean>;
 
-  /** 终止所有会话 */
+  /** Kill all sessions */
   killAll(): Promise<void>;
 
-  /** 注册退出回调 */
+  /** Register exit callback */
   onSessionExited(cb: (sessionId: string, exitCode: number | null) => void): void;
 }
 
-/** Agent 能力声明 — 描述此 Agent 支持哪些功能 */
+/** Agent capability declarations — describes which features this Agent supports */
 export interface AgentCapabilities {
-  /** 支持 token 级流式输出 */
+  /** Supports token-level streaming output */
   streaming: boolean;
-  /** 支持会话恢复 (--resume) */
+  /** Supports session resume (--resume) */
   resume: boolean;
-  /** 支持权限审批流程 (control_request → permission_request) */
+  /** Supports permission approval flow (control_request → permission_request) */
   permissions: boolean;
-  /** 支持工具执行进度报告 (tool_progress) */
+  /** Supports tool execution progress reporting (tool_progress) */
   toolProgress: boolean;
-  /** 支持运行时切换模型 */
+  /** Supports runtime model switching */
   modelSwitch: boolean;
 }
 
-// ── Agent 协议适配 ───────────────────────────────────────────────────────────
+// ── Agent Protocol Adaptation ────────────────────────────────────────────────
 
 /**
- * 标准消息类型 — ws-bridge 和前端之间的运行时格式。
+ * Standard message types — runtime format between ws-bridge and the frontend.
  *
- * v1 仍然直接复用现有 session/browser 类型，而不是单独抽一层 StandardMessage AST。
- * 这保持 Claude 路径零回归，也给第二个 backend 留出了适配点。
+ * v1 still directly reuses existing session/browser types rather than extracting a separate StandardMessage AST.
+ * This keeps the Claude path zero-regression and leaves an adaptation point for the second backend.
  *
- * 当第二个 backend 需要的消息映射明显超出当前类型表达能力时，再提取更正式的标准消息子集。
+ * When the second backend's message mapping clearly exceeds the current type's expressiveness, a more formal standard message subset will be extracted.
  */
 
 /**
- * AgentProtocolAdapter — 消息协议适配器
+ * AgentProtocolAdapter — message protocol adapter
  *
- * 负责将 Agent 的原始消息格式与 ws-bridge 的运行时格式互转。
- * Claude Code 当前基本是 NDJSON 直通，未来其他 backend 则通过各自 adapter 适配。
+ * Translates between the Agent's raw message format and the ws-bridge runtime format.
+ * Claude Code currently uses near-passthrough NDJSON; other backends adapt through their own adapters.
  */
 export interface AgentProtocolAdapter {
-  /** 将 Agent 发来的原始数据解析为结构化消息 (null = 跳过此消息) */
+  /** Parse raw data from the Agent into structured messages (null = skip this message) */
   parseIncoming(raw: string): unknown | null;
 
-  /** 将标准消息编码为 Agent 可接收的格式 */
+  /** Encode standard messages into a format the Agent can accept */
   encodeOutgoing(msg: unknown): string;
 }

package/core/types/index.ts

@@ -1,10 +1,10 @@
 /**
- * Core type exports — Pneuma Skills v1.0 契约层
+ * Core type exports — Pneuma Skills v1.0 contract layer
  *
- * 三层契约:
- * - Layer 4: ModeManifest + ModeDefinition (能力描述协议)
- * - Layer 3: ViewerContract (内容查看器契约)
- * - Layer 2: AgentBackend + AgentProtocolAdapter (Agent 通信抽象)
+ * Three-layer contracts:
+ * - Layer 4: ModeManifest + ModeDefinition (capability declaration protocol)
+ * - Layer 3: ViewerContract (content viewer contract)
+ * - Layer 2: AgentBackend + AgentProtocolAdapter (Agent communication abstraction)
  */
 
 export type {

package/core/types/mode-definition.ts

@@ -1,8 +1,8 @@
 /**
- * ModeDefinition — 运行时 Mode 对象
+ * ModeDefinition — Runtime Mode object
  *
- * 将 ModeManifest (声明式配置) 和 ViewerContract (UI 组件) 绑定在一起。
- * 由 Mode 包的入口文件默认导出。
+ * Binds ModeManifest (declarative config) and ViewerContract (UI component) together.
+ * Default-exported from the Mode package's entry file.
  *
  * @example
  * ```typescript
@@ -21,10 +21,10 @@
 import type { ModeManifest } from "./mode-manifest.js";
 import type { ViewerContract } from "./viewer-contract.js";
 
-/** 运行时的完整 Mode 定义 */
+/** Complete runtime Mode definition */
 export interface ModeDefinition {
-  /** 声明式配置 */
+  /** Declarative configuration */
   manifest: ModeManifest;
-  /** 内容查看器实现 */
+  /** Content viewer implementation */
   viewer: ViewerContract;
 }