@xyit/wellspring 0.0.0-stage → 1.0.0

package/dist/workspace/registry.js

@@ -0,0 +1,293 @@
+/*
+ * 宿主级工作区注册表。
+ *
+ * 工作区（用户手动添加的目录）由宿主统一管理，存在 <dataDir>/workspaces.json；
+ * 插件通过 `api.workspaces` 读写，不再各自解析别的插件的数据目录。
+ *
+ * 首次加载时兼容迁移旧版 wellspring-web 插件数据目录里的 workspaces.json：
+ * 只读取 id / name / root / createdAt / lastSeenAt 这些索引字段，不碰会话正文与认证数据。
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { getPaths } from "../platform/path.js";
+const REGISTRY_VERSION = 1;
+const REGISTRY_FILE = "workspaces.json";
+const LEGACY_PLUGIN_DIR = "wellspring-web";
+export const MAX_WORKSPACES = 40;
+export const MAX_WORKSPACE_NAME_CHARS = 60;
+export const WORKSPACE_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const states = new Map();
+export function workspaceRegistryFile(paths = getPaths()) {
+    return join(paths.dataDir, REGISTRY_FILE);
+}
+export function legacyWorkspaceRegistryFile(paths = getPaths()) {
+    return join(paths.dataDir, "plugin-data", LEGACY_PLUGIN_DIR, REGISTRY_FILE);
+}
+/** 由工作目录派生稳定 id（与旧版 wellspring-web 的算法一致，保证会话目录还能对上） */
+export function workspaceIdFor(root) {
+    const slug = basename(root)
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 24);
+    const hash = createHash("sha256").update(root).digest("hex").slice(0, 10);
+    return slug === "" ? `workspace-${hash}` : `${slug}-${hash}`;
+}
+export function normalizeWorkspaceName(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const name = value
+        .replace(/[\u0000-\u001f\u007f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (name === "" || name.length > MAX_WORKSPACE_NAME_CHARS) {
+        return null;
+    }
+    return name;
+}
+function finiteTimestamp(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? Math.floor(value)
+        : fallback;
+}
+function normalizeEntry(value, fallbackId) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    const rootRaw = record["root"];
+    if (typeof rootRaw !== "string" || rootRaw.trim() === "") {
+        return null;
+    }
+    const root = resolve(rootRaw.trim());
+    const rawId = record["id"];
+    const id = typeof rawId === "string" && WORKSPACE_ID.test(rawId) ? rawId : fallbackId;
+    const rawName = record["name"];
+    const name = normalizeWorkspaceName(rawName) ?? (basename(root) === "" ? "工作区" : basename(root));
+    const now = Date.now();
+    return {
+        id,
+        name,
+        root,
+        createdAt: finiteTimestamp(record["createdAt"], now),
+        lastSeenAt: finiteTimestamp(record["lastSeenAt"], now),
+    };
+}
+/** 解析注册表文件；接受 { v, workspaces } 与旧版纯数组，非法条目忽略 */
+export function parseWorkspaceEntries(value) {
+    let list = value;
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        list = value["workspaces"];
+    }
+    if (!Array.isArray(list)) {
+        return [];
+    }
+    const entries = [];
+    const seenIds = new Set();
+    const seenRoots = new Set();
+    for (const item of list) {
+        if (entries.length >= MAX_WORKSPACES) {
+            break;
+        }
+        const rawRoot = typeof item === "object" && item !== null
+            ? item["root"]
+            : undefined;
+        const fallbackId = typeof rawRoot === "string" ? workspaceIdFor(resolve(rawRoot)) : "";
+        const entry = normalizeEntry(item, fallbackId);
+        if (entry === null || entry.id === "") {
+            continue;
+        }
+        if (seenIds.has(entry.id) || seenRoots.has(entry.root)) {
+            continue;
+        }
+        seenIds.add(entry.id);
+        seenRoots.add(entry.root);
+        entries.push(entry);
+    }
+    return entries;
+}
+function stateFor(paths) {
+    const file = workspaceRegistryFile(paths);
+    const existing = states.get(file);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const state = {
+        file,
+        legacyFile: legacyWorkspaceRegistryFile(paths),
+        workspaces: [],
+        loaded: false,
+        queue: Promise.resolve(),
+    };
+    states.set(file, state);
+    return state;
+}
+async function readJson(path) {
+    const raw = await readFile(path, "utf8");
+    return JSON.parse(raw);
+}
+async function writeRegistry(state) {
+    await mkdir(dirname(state.file), { recursive: true });
+    const payload = { v: REGISTRY_VERSION, workspaces: state.workspaces };
+    const temporary = `${state.file}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(payload, null, 4)}\n`, "utf8");
+    await rename(temporary, state.file);
+}
+/** 注册表文件损坏时挪到 .broken，按空表启动，避免拖垮整个服务 */
+async function quarantine(state) {
+    try {
+        await rename(state.file, `${state.file}.broken`);
+    }
+    catch {
+        /* 文件可能已经不存在 */
+    }
+}
+/** 只导入旧版 wellspring-web 的索引；旧文件损坏就跳过，不影响启动 */
+async function migrateLegacy(state) {
+    let raw;
+    try {
+        raw = await readJson(state.legacyFile);
+    }
+    catch {
+        return;
+    }
+    const entries = parseWorkspaceEntries(raw);
+    if (entries.length === 0) {
+        return;
+    }
+    state.workspaces = entries;
+    await writeRegistry(state);
+}
+async function ensureLoaded(state) {
+    if (state.loaded) {
+        return;
+    }
+    try {
+        const raw = await readJson(state.file);
+        state.workspaces = parseWorkspaceEntries(raw);
+    }
+    catch (error) {
+        const missing = typeof error === "object" &&
+            error !== null &&
+            error.code === "ENOENT";
+        if (missing) {
+            await migrateLegacy(state);
+        }
+        else {
+            await quarantine(state);
+        }
+    }
+    state.loaded = true;
+}
+function enqueue(state, task) {
+    const run = state.queue.then(task, task);
+    state.queue = run.catch(() => undefined);
+    return run;
+}
+/** 宿主内部：重置内存里的注册表（测试 / 重新配置路径时用） */
+export function resetWorkspaceRegistry(paths) {
+    if (paths === undefined) {
+        states.clear();
+        return;
+    }
+    states.delete(workspaceRegistryFile(paths));
+}
+export async function listWorkspaces(paths = getPaths()) {
+    const state = stateFor(paths);
+    await ensureLoaded(state);
+    return { workspaces: state.workspaces.map((entry) => ({ ...entry })) };
+}
+function isDirectory(path) {
+    return stat(path).then((info) => info.isDirectory(), () => false);
+}
+/** root 必须是已存在的目录；重复添加返回已有记录并刷新 lastSeenAt */
+export async function addWorkspace(options, paths = getPaths()) {
+    const rootRaw = typeof options.root === "string" ? options.root.trim() : "";
+    if (rootRaw === "") {
+        throw new Error("工作区路径不能为空");
+    }
+    const root = resolve(rootRaw);
+    if (!isAbsolute(root)) {
+        throw new Error("工作区路径必须是绝对路径");
+    }
+    if (!(await isDirectory(root))) {
+        throw new Error(`工作区目录不存在或不是目录：${root}`);
+    }
+    const requestedName = normalizeWorkspaceName(options.name);
+    if (options.name !== undefined && options.name !== "" && requestedName === null) {
+        throw new Error(`工作区名称需要 1-${MAX_WORKSPACE_NAME_CHARS} 个字符`);
+    }
+    const state = stateFor(paths);
+    await ensureLoaded(state);
+    return await enqueue(state, async () => {
+        const existing = state.workspaces.find((entry) => entry.root === root);
+        if (existing !== undefined) {
+            const touched = { ...existing, lastSeenAt: Date.now() };
+            state.workspaces = state.workspaces.map((entry) => entry.id === existing.id ? touched : entry);
+            await writeRegistry(state);
+            return { workspace: { ...touched }, duplicate: true };
+        }
+        if (state.workspaces.length >= MAX_WORKSPACES) {
+            throw new Error(`工作区数量已达上限（${MAX_WORKSPACES}）`);
+        }
+        const now = Date.now();
+        const entry = {
+            id: workspaceIdFor(root),
+            name: requestedName ?? (basename(root) === "" ? "工作区" : basename(root)),
+            root,
+            createdAt: now,
+            lastSeenAt: now,
+        };
+        state.workspaces = [entry, ...state.workspaces];
+        await writeRegistry(state);
+        return { workspace: { ...entry }, duplicate: false };
+    });
+}
+export async function removeWorkspace(id, paths = getPaths()) {
+    const state = stateFor(paths);
+    await ensureLoaded(state);
+    return await enqueue(state, async () => {
+        const before = state.workspaces.length;
+        state.workspaces = state.workspaces.filter((entry) => entry.id !== id);
+        const removed = state.workspaces.length !== before;
+        if (removed) {
+            await writeRegistry(state);
+        }
+        return { removed };
+    });
+}
+export async function renameWorkspace(id, name, paths = getPaths()) {
+    const normalized = normalizeWorkspaceName(name);
+    if (normalized === null) {
+        throw new Error(`工作区名称需要 1-${MAX_WORKSPACE_NAME_CHARS} 个字符`);
+    }
+    const state = stateFor(paths);
+    await ensureLoaded(state);
+    return await enqueue(state, async () => {
+        const existing = state.workspaces.find((entry) => entry.id === id);
+        if (existing === undefined) {
+            return null;
+        }
+        const updated = { ...existing, name: normalized };
+        state.workspaces = state.workspaces.map((entry) => (entry.id === id ? updated : entry));
+        await writeRegistry(state);
+        return { ...updated };
+    });
+}
+export async function touchWorkspace(id, paths = getPaths()) {
+    const state = stateFor(paths);
+    await ensureLoaded(state);
+    return await enqueue(state, async () => {
+        const existing = state.workspaces.find((entry) => entry.id === id);
+        if (existing === undefined) {
+            return null;
+        }
+        const updated = { ...existing, lastSeenAt: Date.now() };
+        state.workspaces = state.workspaces.map((entry) => (entry.id === id ? updated : entry));
+        await writeRegistry(state);
+        return { ...updated };
+    });
+}
+//# sourceMappingURL=registry.js.map

package/dist/workspace/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/workspace/registry.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,74 @@
 {
-  "name": "@xyit/wellspring",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@xyit/wellspring",
+    "version": "1.0.0",
+    "description": "Wellspring 源泉 —— 插件式 Agent 平台与 CLI（Plugin-based AI agent platform and CLI）",
+    "keywords": [
+        "agent",
+        "ai",
+        "cli",
+        "llm",
+        "plugin",
+        "wellspring"
+    ],
+    "license": "MIT",
+    "author": "xyit-team",
+    "bin": {
+        "wellspring": "./dist/index.js"
+    },
+    "files": [
+        "dist",
+        "src",
+        "scripts",
+        "README.md",
+        "LICENSE"
+    ],
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./api/host": {
+            "types": "./dist/api/host/index.d.ts",
+            "import": "./dist/api/host/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "start": "node src/index.ts",
+        "test": "node --test test",
+        "typecheck": "tsc --noEmit",
+        "format": "oxfmt",
+        "format:check": "oxfmt --check",
+        "pty:build": "node scripts/build-node-pty.mjs",
+        "build:web-ui": "node plugins/wellspring-web/scripts/build-ui.mjs",
+        "typecheck:web-ui": "node plugins/wellspring-web/scripts/check-ui.mjs",
+        "build": "tsc -p tsconfig.build.json && node scripts/rewrite-dts.mjs",
+        "prepack": "npm run build"
+    },
+    "dependencies": {
+        "cli-highlight": "^2.1.11",
+        "markdansi": "^0.3.6",
+        "openai": "^7.39.0",
+        "pino": "^10.4.0",
+        "undici": "^8.12.3",
+        "ws": "^8.18.0"
+    },
+    "devDependencies": {
+        "@types/node": "^26.6.5",
+        "@types/ws": "^8.5.0",
+        "oxfmt": "^0.73.0",
+        "typescript": "^7.0.2"
+    },
+    "optionalDependencies": {
+        "node-pty": "^1.0.0"
+    },
+    "engines": {
+        "node": ">=24"
+    }
+}

package/scripts/build-node-pty.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/*
+ * 用本机 Node 头文件重建 node-pty 原生模块。
+ *
+ * node-pty 没有 linux 预编译包，pnpm install 时会走 node-gyp；而 node-gyp 自带的
+ * 下载器在设置了 HTTP(S)_PROXY 的环境里与 Node 26 不兼容（安装日志里是
+ * "gyp ERR! InvalidArgumentError: invalid onError method"），于是 install 失败。
+ * 这里直接使用 Node 安装目录里自带的 include/node 头文件，跳过下载。
+ *
+ * 用法：pnpm pty:build
+ * 没装 node-pty 也没关系：终端会自动退回 python3 的 pty 实现。
+ */
+
+import { spawnSync } from "node:child_process"
+import { existsSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+const repoRoot = resolve(import.meta.dirname, "..")
+const nodeDir = resolve(dirname(process.execPath), "..")
+const header = join(nodeDir, "include", "node", "node.h")
+if (!existsSync(join(repoRoot, "node_modules", "node-pty"))) {
+    console.error("node_modules 里没有 node-pty：先执行 pnpm install。")
+    console.error("它不用能装成功也可以——终端会自动退回 python3 的 pty 实现。")
+    process.exit(1)
+}
+if (!existsSync(header)) {
+    console.error(`找不到 Node 头文件：${header}`)
+    console.error("当前 Node 安装没有附带 include/node，无法编译 node-pty。")
+    console.error("终端仍可使用：宿主会自动退回 python3 的 pty 实现。")
+    process.exit(1)
+}
+
+console.log(`使用本地 Node 头文件重建 node-pty：${nodeDir}`)
+const pnpm = process.platform === "win32" ? "pnpm.cmd" : "pnpm"
+const result = spawnSync(pnpm, ["rebuild", "node-pty"], {
+    stdio: "inherit",
+    env: { ...process.env, npm_config_nodedir: nodeDir },
+})
+if (result.status !== 0) {
+    console.error("node-pty 重建失败；终端会自动退回 python3 的 pty 实现。")
+    process.exit(result.status ?? 1)
+}
+
+try {
+    const pty = await import("node-pty")
+    if (typeof pty.spawn !== "function") {
+        throw new Error("node-pty 没有导出 spawn")
+    }
+    console.log("node-pty 原生模块可用")
+} catch (error) {
+    console.error(
+        `node-pty 仍然无法加载：${error instanceof Error ? error.message : String(error)}`,
+    )
+    process.exit(1)
+}

package/scripts/rewrite-dts.mjs

@@ -0,0 +1,36 @@
+/*
+ * tsc 的 rewriteRelativeImportExtensions 只改 JS，.d.ts 里仍然保留 ".ts"。
+ * 声明文件是给消费者 tsc 看的；带 .ts 后缀的相对导入会要求对方打开
+ * allowImportingTsExtensions，所以发布前统一改回 .js。
+ */
+
+import { readdir, readFile, writeFile } from "node:fs/promises"
+import { join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const DIST = fileURLToPath(new URL("../dist/", import.meta.url))
+
+async function declarations(dir) {
+    const entries = await readdir(dir, { withFileTypes: true })
+    const files = []
+    for (const entry of entries) {
+        const path = join(dir, entry.name)
+        if (entry.isDirectory()) {
+            files.push(...(await declarations(path)))
+        } else if (entry.name.endsWith(".d.ts")) {
+            files.push(path)
+        }
+    }
+    return files
+}
+
+let rewritten = 0
+for (const file of await declarations(DIST)) {
+    const source = await readFile(file, "utf8")
+    const next = source.replace(/(["'])(\.{1,2}\/[^"']+)\.ts\1/g, "$1$2.js$1")
+    if (next !== source) {
+        await writeFile(file, next)
+        rewritten += 1
+    }
+}
+console.log(`声明文件已重写：${rewritten} 个`)

package/scripts/verify-sandbox.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/*
+ * 真实 bwrap 隔离验证脚本。
+ * 在允许非特权 user namespace 的 Linux 上运行：node scripts/verify-sandbox.ts
+ */
+
+import { mkdtemp, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+import { DEFAULT_SETTINGS } from "../src/config/defaults.ts"
+import { getPaths, initPaths } from "../src/platform/path.ts"
+import { SandboxManager } from "../src/sandbox/manager.ts"
+
+initPaths()
+const manager = new SandboxManager({
+    settings: { ...DEFAULT_SETTINGS.sandbox, mode: "strict", backend: "auto" },
+    paths: getPaths(),
+})
+
+const probe = await manager.probe()
+console.log("probe:", probe)
+if (!probe.available) {
+    console.error("\nbwrap 不可用，先确认：")
+    console.error("  unshare -Ur true")
+    console.error("  bwrap --unshare-all --ro-bind / / --dev /dev --proc /proc /bin/true")
+    console.error(
+        "Ubuntu 24.04 可能被 AppArmor 限制：sysctl kernel.apparmor_restrict_unprivileged_userns",
+    )
+    process.exit(1)
+}
+
+const workspace = await mkdtemp(join(tmpdir(), "wellspring-verify-"))
+let failed = 0
+
+async function run(
+    name: string,
+    command: string,
+    argv: string[],
+    expect: (exitCode: number | null, stdout: string, stderr: string) => boolean,
+): Promise<void> {
+    const result = await manager.runAgentCode({
+        command,
+        argv,
+        workspaceDir: workspace,
+        timeoutMs: 15_000,
+    })
+    const ok = expect(result.exitCode, result.stdout, result.stderr)
+    if (!ok) {
+        failed += 1
+    }
+    console.log(`\n[${ok ? "PASS" : "FAIL"}] ${name}`)
+    console.log(`  exit=${String(result.exitCode)} backend=${result.backend}`)
+    console.log(`  stdout=${result.stdout.trim()}`)
+    if (result.stderr.trim() !== "") {
+        console.log(`  stderr=${result.stderr.trim()}`)
+    }
+}
+
+try {
+    await run("读取 /etc/shadow 应失败", "/usr/bin/cat", ["/etc/shadow"], (code) => code !== 0)
+
+    await run(
+        "写 workspace 应失败（只读挂载）",
+        "/bin/sh",
+        ["-c", "echo escape > escape.txt"],
+        (code) => code !== 0,
+    )
+
+    await run(
+        "写 scratch 应成功",
+        "/bin/sh",
+        ["-c", 'echo ok > "$SCRATCH/t.txt" && cat "$SCRATCH/t.txt"'],
+        (_code, stdout) => stdout.includes("ok"),
+    )
+
+    await run(
+        "网络应被拒绝",
+        "node",
+        [
+            "-e",
+            "fetch('http://1.1.1.1', {signal: AbortSignal.timeout(2000)}).then(() => { console.log('network-ok'); process.exit(2) }).catch((e) => { console.log('network-blocked:' + e.message); process.exit(0) })",
+        ],
+        (_code, stdout) => stdout.includes("network-blocked"),
+    )
+
+    await run(
+        "读取宿主源码应失败",
+        "/usr/bin/cat",
+        [join(process.cwd(), "src", "index.ts")],
+        (code) => code !== 0,
+    )
+} finally {
+    await rm(workspace, { recursive: true, force: true })
+}
+
+console.log(failed === 0 ? "\n所有 sandbox 检查通过" : `\n${failed} 个检查失败`)
+process.exit(failed === 0 ? 0 : 1)

package/src/agent/pending-asks.ts

@@ -0,0 +1,88 @@
+/*
+ * Agent 提问：ask 工具把问题交给界面，等待用户回答后把答案还回工具循环。
+ * 和提权审批一样是“一轮对话中途停下来等人”的机制，只是不需要权限判断。
+ */
+
+import { randomUUID } from "node:crypto"
+
+/** 等待用户回答的上限；超时后工具返回“没有回答”并继续 */
+export const ASK_TIMEOUT_MS = 5 * 60_000
+
+interface PendingAsk {
+    readonly sessionId: string
+    readonly resolve: (answer: string | null) => void
+    readonly timer: NodeJS.Timeout
+}
+
+const pending = new Map<string, PendingAsk>()
+
+export function createAskId(): string {
+    return `ask_${randomUUID()}`
+}
+
+/**
+ * 登记一个等待回答的问题。answerAsk 先把 answer 交给这个 Promise；
+ * 超时兑现 null（用户没回答）。
+ */
+export function waitForAsk(input: {
+    readonly askId: string
+    readonly sessionId: string
+    readonly timeoutMs?: number
+}): Promise<string | null> {
+    return new Promise<string | null>((resolvePromise) => {
+        let settled = false
+        let timer: NodeJS.Timeout | null = null
+        const finish = (answer: string | null): void => {
+            if (settled) {
+                return
+            }
+            settled = true
+            if (timer !== null) {
+                clearTimeout(timer)
+            }
+            pending.delete(input.askId)
+            resolvePromise(answer)
+        }
+        timer = setTimeout(() => {
+            finish(null)
+        }, input.timeoutMs ?? ASK_TIMEOUT_MS)
+        pending.set(input.askId, {
+            sessionId: input.sessionId,
+            resolve: finish,
+            timer,
+        })
+    })
+}
+
+/** 用户回答；命中等待中的问题时返回 true */
+export function answerAsk(askId: string, answer: string): boolean {
+    const entry = pending.get(askId)
+    if (entry === undefined) {
+        return false
+    }
+    entry.resolve(answer)
+    return true
+}
+
+/** 取消一次等待（工具循环收尾、异常退出时调用） */
+export function cancelAsk(askId: string): void {
+    const entry = pending.get(askId)
+    if (entry === undefined) {
+        return
+    }
+    entry.resolve(null)
+}
+
+/** 会话结束时清掉遗留的等待 */
+export function cancelSessionAsks(sessionId: string): void {
+    for (const [askId, entry] of [...pending]) {
+        if (entry.sessionId === sessionId) {
+            cancelAsk(askId)
+        }
+    }
+}
+
+/** 当前等待回答的数量（测试与诊断用） */
+export function pendingAskCount(): number {
+    return pending.size
+}