@xyit/wellspring 0.0.0-stage → 1.1.0

package/src/api/host/host.ts

@@ -0,0 +1,99 @@
+/*
+ * 宿主信息 API：类似 Bukkit 的 PluginManager。
+ * 插件通过 getHost() 获取宿主状态、插件列表、OS 与路径。
+ */
+
+import { release as osRelease } from "node:os"
+
+import type { PlatformName } from "../../platform/os.ts"
+import { getHostBridge } from "../../sandbox/bridge-state.ts"
+import type { ResolvedPaths } from "../../platform/path.ts"
+import type { PluginStatus } from "./plugin.ts"
+
+export type HostStatus = "starting" | "running" | "stopping" | "stopped"
+export type HostPluginStatus = PluginStatus | "disabled"
+
+export interface HostOSInfo {
+    readonly platform: PlatformName
+    readonly arch: string
+    readonly release: string
+    readonly node: string
+    readonly cwd: string
+}
+
+export interface HostPlugin {
+    readonly id: string
+    readonly name: string
+    readonly version: string
+    readonly deps: readonly string[]
+    readonly commands: readonly string[]
+    getStatus(): HostPluginStatus
+}
+
+export interface Host {
+    getPlugins(): readonly HostPlugin[]
+    getOS(): HostOSInfo
+    getPaths(): ResolvedPaths
+    getStatus(): HostStatus
+}
+
+interface HostState {
+    status: HostStatus
+    paths: ResolvedPaths | null
+    os: HostOSInfo
+    plugins: HostPlugin[]
+}
+
+const state: HostState = {
+    status: "starting",
+    paths: null,
+    os: {
+        platform: "linux",
+        arch: process.arch,
+        release: osRelease(),
+        node: process.version,
+        cwd: process.cwd(),
+    },
+    plugins: [],
+}
+
+/** 平台内部：初始化宿主信息 */
+export function configureHost(options: {
+    readonly paths?: ResolvedPaths
+    readonly os?: Partial<HostOSInfo>
+}): void {
+    if (options.paths !== undefined) {
+        state.paths = options.paths
+    }
+    if (options.os !== undefined) {
+        state.os = { ...state.os, ...options.os }
+    }
+}
+
+/** 平台内部：更新宿主生命周期状态 */
+export function setHostStatus(status: HostStatus): void {
+    state.status = status
+}
+
+/** 平台内部：更新插件列表 */
+export function setHostPlugins(plugins: readonly HostPlugin[]): void {
+    state.plugins = [...plugins]
+}
+
+export function getHost(): Host {
+    const bridge = getHostBridge()
+    if (bridge !== null) {
+        return bridge.getHostSnapshot()
+    }
+    return {
+        getPlugins: () => [...state.plugins],
+        getOS: () => ({ ...state.os }),
+        getPaths: () => {
+            if (state.paths === null) {
+                throw new Error("宿主路径尚未初始化")
+            }
+            return state.paths
+        },
+        getStatus: () => state.status,
+    }
+}

package/src/api/host/http.ts

@@ -0,0 +1,79 @@
+/*
+ * 插件 HTTP 宿主能力。
+ * 插件在 sandbox 内，宿主负责监听端口，请求通过 RPC 交给插件 handler。
+ */
+
+export interface HttpRequest {
+    readonly method: string
+    readonly url: string
+    readonly headers: Record<string, string>
+    /** base64 编码的请求体 */
+    readonly body: string
+    readonly remoteAddress: string | null
+}
+
+export interface HttpResponse {
+    readonly status?: number
+    readonly headers?: Record<string, string>
+    /** utf8 或 base64；默认 utf8 */
+    readonly body?: string
+    readonly bodyEncoding?: "utf8" | "base64"
+    /** true 时保持连接，后续通过 stream 写出 */
+    readonly stream?: boolean
+}
+
+export interface HttpStreamContext {
+    write(chunk: string): void
+    end(): void
+}
+
+export type HttpHandler = (
+    request: HttpRequest,
+    stream: HttpStreamContext,
+) => HttpResponse | Promise<HttpResponse>
+
+export interface PluginWebSocket {
+    readonly connectionId: string
+    send(data: string): Promise<void>
+    close(code?: number, reason?: string): Promise<void>
+    onMessage(handler: (data: string) => void): void
+    onClose(handler: (code: number, reason: string) => void): void
+}
+
+export type WebSocketHandler = (
+    socket: PluginWebSocket,
+    request: HttpRequest,
+) => void | Promise<void>
+
+export interface HttpTlsOptions {
+    /** PEM 格式证书 */
+    readonly cert: string
+    /** PEM 格式私钥 */
+    readonly key: string
+    /** 可选 CA 链 */
+    readonly ca?: string
+}
+
+export interface HttpServerOptions {
+    /** 默认 127.0.0.1 */
+    readonly host?: string
+    /** 默认 0（随机端口） */
+    readonly port?: number
+    /** 提供时启动 HTTPS */
+    readonly tls?: HttpTlsOptions
+    /** 提供时启用 WebSocket */
+    readonly websocket?: WebSocketHandler
+}
+
+export interface HttpServerHandle {
+    readonly serverId: string
+    readonly host: string
+    readonly port: number
+    close(): Promise<void>
+}
+
+export interface HostHttpApi {
+    createServer(options: HttpServerOptions, handler: HttpHandler): Promise<HttpServerHandle>
+}
+
+export const HTTP_MAX_BODY_BYTES = 16 * 1024 * 1024

package/src/api/host/index.ts

@@ -0,0 +1,20 @@
+/*
+ * 宿主 API 入口。
+ * 插件可以 import { onMessage, getHost, ... } from "wellspring/api/host/index.ts"。
+ */
+
+export * from "./agent.ts"
+export * from "./events.ts"
+export * from "./exec.ts"
+export * from "./fs.ts"
+export * from "./http.ts"
+export * from "./models.ts"
+export * from "./network.ts"
+export * from "./hooks.ts"
+export * from "./host.ts"
+export * from "./plugin.ts"
+export * from "./plugins.ts"
+export * from "./pty.ts"
+export * from "./session.ts"
+export * from "./version.ts"
+export * from "./workspace.ts"

package/src/api/host/models.ts

@@ -0,0 +1,81 @@
+/*
+ * 宿主模型 API：给插件（Web 设置界面）管理自定义供应商与模型切换。
+ *
+ * 供应商配置写回 app-setting.json 的 models 节；每个供应商的 Key 单独存凭据文件。
+ * 状态里只给掩码，读不到明文。
+ */
+
+/** 一个供应商的展示信息（含 Key 状态，不含明文） */
+export interface HostModelProvider {
+    readonly id: string
+    readonly name: string
+    readonly baseUrl: string | null
+    readonly models: readonly string[]
+    readonly defaultModel: string | null
+    readonly apiKeyEnv: string | null
+    /** 内置供应商（由 openai.* 描述）不能删除 */
+    readonly builtin: boolean
+    readonly keyConfigured: boolean
+    readonly keySource: "env" | "credentials" | null
+    readonly keyMasked: string | null
+    /** 该供应商可用的环境变量名（内置为 OPENAI_API_KEY） */
+    readonly envVar: string | null
+    /** 本地凭据文件里是否有 Key（即使被环境变量覆盖） */
+    readonly keyStored: boolean
+}
+
+export interface HostModelsState {
+    readonly providers: readonly HostModelProvider[]
+    readonly activeProvider: string
+    readonly activeModel: string | null
+    /** 当前推理强度：off / low / high / max */
+    readonly activeReasoning: string
+    /** 支持的推理强度（界面用） */
+    readonly reasoningLevels: readonly string[]
+}
+
+/** 新增/修改供应商；id 为空时按 name 生成或新增 */
+export interface HostModelProviderInput {
+    readonly id?: string | null
+    readonly name: string
+    readonly baseUrl?: string | null
+    readonly models?: readonly string[]
+    readonly defaultModel?: string | null
+    readonly apiKeyEnv?: string | null
+    /** 可选：一起保存该供应商的 API Key（明文只写不读） */
+    readonly apiKey?: string | null
+}
+
+export interface HostModelsStateResult {
+    readonly ok: boolean
+    /** ok=false 时的错误码，例如 config.invalid */
+    readonly code?: string
+    readonly state: HostModelsState
+}
+
+export interface HostModelsFetchResult {
+    readonly ok: boolean
+    readonly code?: string
+    readonly models?: readonly string[]
+}
+
+export interface HostModelsApi {
+    /** 供应商列表、当前供应商与模型 */
+    state(): Promise<HostModelsState>
+    /** 切换当前供应商、模型与推理强度；model/reasoning 为 null 时保持缺省 */
+    setActive(
+        providerId: string,
+        model: string | null,
+        reasoning?: string | null,
+    ): Promise<HostModelsState>
+    /** 新增或更新自定义供应商 */
+    saveProvider(input: HostModelProviderInput): Promise<HostModelsStateResult>
+    /** 删除自定义供应商（内置 openai 不可删） */
+    removeProvider(id: string): Promise<HostModelsStateResult>
+    /** 从供应商接口拉取模型列表（候选 key 优先，其次用已保存的） */
+    fetchModels(id: string, apiKey?: string): Promise<HostModelsFetchResult>
+    /** 保存某个供应商的 API Key */
+    saveKey(id: string, apiKey: string): Promise<HostModelsStateResult>
+    /** 清除某个供应商的本地 API Key */
+    clearKey(id: string): Promise<HostModelsState>
+}

package/src/api/host/network.ts

@@ -0,0 +1,32 @@
+/*
+ * 宿主网络配置：给插件（例如网页设置页）读写 app-setting.json 的 network.proxy。
+ *
+ * 只处理出站 HTTP/HTTPS 代理；保存后下一轮模型调用、模型列表拉取与网页搜索都会使用新配置。
+ */
+
+import type { ProxySetting } from "../../config/types.ts"
+
+/** 保存代理：url 为空 / null 表示直连 */
+export interface HostNetworkProxyInput {
+    readonly url: string | null
+    /** 不走代理的主机后缀，例如 localhost、.internal */
+    readonly noProxy?: readonly string[]
+}
+
+export interface HostNetworkState {
+    /** null 表示直连 */
+    readonly proxy: ProxySetting | null
+}
+
+export interface HostNetworkResult {
+    readonly ok: boolean
+    /** ok=false 时的错误码，例如 config.invalid:network.proxy.url */
+    readonly code?: string
+    readonly state: HostNetworkState
+}
+
+export interface HostNetworkApi {
+    state(): Promise<HostNetworkState>
+    /** 写入 app-setting.json；校验失败时不落盘 */
+    saveProxy(input: HostNetworkProxyInput): Promise<HostNetworkResult>
+}

package/src/api/host/plugin.ts

@@ -0,0 +1,158 @@
+/*
+ * 宿主契约：平台暴露给插件与外部调用方的稳定接口。
+ * 实现放在各模块，api/host 只放类型、版本与钩子注册入口。
+ */
+
+import type { Logger } from "pino"
+
+import type { HostFileApi } from "./fs.ts"
+import type { HostModelsApi } from "./models.ts"
+import type { HostNetworkApi } from "./network.ts"
+import type { HostExecApi } from "./exec.ts"
+import type { HostPtyApi } from "./pty.ts"
+
+import type { AppSetting } from "../../config/types.ts"
+import type { ResolvedPaths } from "../../platform/path.ts"
+import { HOST_API_VERSION } from "./version.ts"
+
+/** 插件自报状态 */
+export type PluginStatus = "ok" | "failed"
+
+/** 插件自己的 JSON 配置（<configDir>/plugins/<id>.json） */
+export type PluginConfig = Readonly<Record<string, unknown>>
+
+/** 插件可用的终端输出；human 模式下由 elog4js 渲染 */
+export interface HostOutput {
+    info(text: string): void
+    warn(text: string): void
+    error(text: string): void
+    print(text?: string): void
+}
+
+export interface PluginCommandContext {
+    /** 命令名之后的原始参数，平台不解析 */
+    readonly argv: readonly string[]
+    readonly env: NodeJS.ProcessEnv
+    readonly paths: ResolvedPaths
+    readonly config: AppSetting
+    readonly logger: Logger
+    readonly output: HostOutput
+    /** 插件专属数据目录，已创建 */
+    readonly pluginDataDir: string
+    /** 插件专属配置，文件不存在时为空对象 */
+    readonly pluginConfig: PluginConfig
+    /** 插件数据目录内的文件操作 */
+    readonly fs: HostFileApi
+    /** 当前工作目录内的文件操作 */
+    readonly workspaceFs: HostFileApi
+    readonly cwd: string
+    readonly json: boolean
+    readonly stdin: NodeJS.ReadableStream
+    readonly stdout: NodeJS.WritableStream
+    readonly stderr: NodeJS.WritableStream
+}
+
+export interface PluginCommand {
+    readonly name: string
+    readonly summary: string
+    readonly usage?: string
+    readonly aliases?: readonly string[]
+    readonly run: (context: PluginCommandContext) => number | void | Promise<number | void>
+}
+
+export interface AgentToolParam {
+    readonly type?: "string" | "number" | "integer" | "boolean" | "array" | "object"
+    readonly description?: string
+    readonly enum?: readonly string[]
+    readonly optional?: boolean
+    readonly items?: { readonly type: "string" | "number" | "integer" | "boolean" }
+}
+
+/** string 作为简写，等价于 { type: "string", description } */
+export type AgentToolParamSpec = string | AgentToolParam
+
+export interface AgentToolIntroduction {
+    /** 参数名 → 类型与说明 */
+    readonly params: Record<string, AgentToolParamSpec>
+    /** 工具用途说明，作为 tool description 下发给模型 */
+    readonly content: string
+}
+
+export interface AgentCallToolResult {
+    readonly success: boolean
+    readonly data: Record<string, unknown>
+}
+
+import type { HostAgentApi } from "./agent.ts"
+import type { HostCapabilities } from "../../plugin/capabilities.ts"
+import type { HostHttpApi } from "./http.ts"
+import type { HostPluginsApi } from "./plugins.ts"
+import type { HostWorkspacesApi } from "./workspace.ts"
+
+export interface AgentTool {
+    readonly name: string
+    readonly introduction: AgentToolIntroduction
+    readonly call: (...args: unknown[]) => AgentCallToolResult | Promise<AgentCallToolResult>
+}
+
+export interface WellspringPluginInfo {
+    readonly id: string
+    readonly name: string
+    readonly version: string
+}
+
+/** setup() 返回的插件描述与扩展 */
+export interface WellspringPlugin extends WellspringPluginInfo {
+    /** 插件自检状态，必须提供 */
+    readonly status: PluginStatus
+    readonly description?: string
+    /** 依赖的插件 id，仅用于元信息与展示 */
+    readonly deps?: readonly string[]
+    /** 插件注册的命令；也可以在 init(api) 里调用 api.registerCommand */
+    readonly commands?: readonly PluginCommand[]
+    /** 插件提供的 Agent 工具；重名会导致后加载插件停用 */
+    readonly agentTools?: readonly AgentTool[]
+    /** 可选初始化：拿到宿主能力后再注册命令或做启动检查 */
+    readonly init?: (api: PluginApi) => void | Promise<void>
+}
+
+export type PluginSetup = () => WellspringPlugin | Promise<WellspringPlugin>
+
+export interface PluginApi {
+    readonly apiVersion: typeof HOST_API_VERSION
+    readonly plugin: WellspringPluginInfo
+    readonly paths: ResolvedPaths
+    readonly config: AppSetting
+    readonly logger: Logger
+    readonly output: HostOutput
+    /** 插件专属数据目录，已创建 */
+    readonly pluginDataDir: string
+    /** 插件专属配置，文件不存在时为空对象 */
+    readonly pluginConfig: PluginConfig
+    /** 插件数据目录内的文件操作 */
+    readonly fs: HostFileApi
+    /** 当前工作目录内的文件操作 */
+    readonly workspaceFs: HostFileApi
+    registerCommand(command: PluginCommand): void
+    registerAgentTool?(tool: AgentTool): void
+    /** 依赖链上的插件 data 目录；无权限返回 null */
+    pluginData(pluginId: string): Promise<HostFileApi | null>
+    /** 宿主能力：代码执行、网页搜索/抓取 */
+    capabilities: HostCapabilities
+    /** 宿主 HTTP 服务 */
+    http: HostHttpApi
+    /** 与 Agent 会话交互 */
+    agent: HostAgentApi
+    /** 宿主进程执行（需 hostApi: exec 权限） */
+    exec: HostExecApi
+    /** 宿主伪终端（需 hostApi: pty 权限；依赖可选的 node-pty） */
+    pty: HostPtyApi
+    /** 自定义供应商与模型切换（需 hostApi: models 权限） */
+    models: HostModelsApi
+    /** 出站 HTTP/HTTPS 代理配置（需 hostApi: network 权限） */
+    network: HostNetworkApi
+    /** 插件安装 / 卸载 / 启用 / 禁用（需 hostApi: plugins 权限） */
+    plugins: HostPluginsApi
+    /** 宿主级工作区注册表（需 hostApi: workspaces 权限） */
+    workspaces: HostWorkspacesApi
+}

package/src/api/host/plugins.ts

@@ -0,0 +1,59 @@
+/*
+ * 宿主插件管理：列出已安装插件，安装 / 卸载 / 启用 / 禁用。
+ * 所有改动都在下次启动时生效；运行期不热加载插件。
+ */
+
+export type HostPluginEntryStatus = "ok" | "failed" | "disabled" | "unknown"
+
+export interface HostPluginEntry {
+    readonly id: string
+    readonly name: string
+    readonly version: string
+    readonly status: HostPluginEntryStatus
+    readonly enabled: boolean
+    /** 依赖的其它插件 id */
+    readonly deps: readonly string[]
+    readonly commands: readonly string[]
+    /** 插件根目录下的目录名 */
+    readonly dir: string
+}
+
+export interface HostPluginListResult {
+    readonly plugins: readonly HostPluginEntry[]
+}
+
+export interface HostPluginInstallInput {
+    /** 原始文件名，必须是 .zip */
+    readonly filename: string
+    /** zip 包的 base64 编码 */
+    readonly dataBase64: string
+    /** 允许覆盖同名插件 */
+    readonly force?: boolean
+}
+
+export interface HostPluginMutationResult {
+    readonly ok: boolean
+    readonly id: string
+    readonly restartRequired: boolean
+    /** true 表示已即时生效，不需要重启 */
+    readonly hot?: boolean
+    readonly changed?: boolean
+    /** 依赖目标插件的其它插件；禁用/卸载时要提示 */
+    readonly dependents?: readonly string[]
+    /** 安装时实际使用的包管理器（没有安装依赖时为 null） */
+    readonly packageManager?: string | null
+    /** 安装时是否自动安装了依赖 */
+    readonly dependenciesInstalled?: boolean
+    readonly error?: string
+}
+
+export interface HostPluginsApi {
+    /** 列出插件根目录下的全部插件（含禁用与加载失败的） */
+    list(): Promise<HostPluginListResult>
+    /** 从 zip 安装或覆盖插件 */
+    install(input: HostPluginInstallInput): Promise<HostPluginMutationResult>
+    /** 删除插件目录；运行中的进程不受影响，重启后不再加载 */
+    remove(id: string): Promise<HostPluginMutationResult>
+    enable(id: string): Promise<HostPluginMutationResult>
+    disable(id: string): Promise<HostPluginMutationResult>
+}

package/src/api/host/pty.ts

@@ -0,0 +1,73 @@
+/*
+ * 宿主伪终端（PTY）API。
+ *
+ * 需要 node-pty 提供真正的 tty：只有 tty 才有行编辑、颜色、进度条与全屏程序。
+ * node-pty 是原生模块，可能装不上（无编译器 / 无预编译包），所以它按可选依赖处理，
+ * 拿不到时 available() 返回 false，调用方退回普通管道执行。
+ */
+
+export interface HostPtySpawnOptions {
+    /** 可执行文件，默认取登录 shell */
+    readonly file?: string
+    readonly args?: readonly string[]
+    readonly cwd: string
+    readonly env?: Record<string, string>
+    readonly cols?: number
+    readonly rows?: number
+}
+
+export interface HostPtySession {
+    readonly sessionId: string
+    readonly pid: number
+    readonly file: string
+    readonly cwd: string
+    readonly cols: number
+    readonly rows: number
+}
+
+export interface HostPtyChunk {
+    /** 自上次 poll 之后新增的输出，含 ANSI 控制序列 */
+    readonly chunk: string
+    readonly done: boolean
+    readonly exitCode: number | null
+}
+
+/** PTY 后端：node-pty 原生模块，或 python3 自建的 pty */
+export type HostPtyBackend = "node-pty" | "python-pty"
+
+export interface HostPtyAvailability {
+    readonly available: boolean
+    /** 实际使用的后端 */
+    readonly backend?: HostPtyBackend
+    /** 不可用时的原因，便于排查（未安装 / 原生模块加载失败） */
+    readonly reason?: string
+}
+
+export interface HostPtyApi {
+    /** node-pty 是否可用，以及不可用的原因 */
+    available(): Promise<HostPtyAvailability>
+    spawn(options: HostPtySpawnOptions): Promise<HostPtySession>
+    poll(sessionId: string): Promise<HostPtyChunk>
+    /** 原样写入键盘输入 */
+    write(sessionId: string, data: string): Promise<void>
+    resize(sessionId: string, cols: number, rows: number): Promise<void>
+    kill(sessionId: string): Promise<void>
+}
+
+/** 单会话输出缓冲上限，超出后丢弃最旧的输出 */
+export const HOST_PTY_MAX_OUTPUT_CHARS = 512 * 1024
+
+/** 同时保留的 PTY 会话数 */
+export const HOST_PTY_MAX_SESSIONS = 8
+
+/** 单次 poll 最多返回的字符数 */
+export const HOST_PTY_MAX_POLL_CHARS = 128 * 1024
+
+export const HOST_PTY_DEFAULT_COLS = 100
+export const HOST_PTY_DEFAULT_ROWS = 28
+
+/** 尺寸的合理范围：列不能太窄，行数允许缩到很小（终端面板可以拖得很矮） */
+export const HOST_PTY_MIN_COLS = 20
+export const HOST_PTY_MAX_COLS = 400
+export const HOST_PTY_MIN_ROWS = 2
+export const HOST_PTY_MAX_ROWS = 200

package/src/api/host/session.ts

@@ -0,0 +1,61 @@
+// 宿主会话 API
+
+import { getHostBridge } from "../../sandbox/bridge-state.ts"
+import { getSession as findSession } from "../../session/registry.ts"
+import { Session, SessionMessage } from "../../session/session.ts"
+import type { SessionData } from "../../session/store.ts"
+import type { SessionMeta } from "../../session/types.ts"
+
+export { Session, SessionMessage } from "../../session/session.ts"
+export { Workspace } from "../../workspace/index.ts"
+
+class RemoteSession extends Session {
+    constructor(id: string) {
+        const meta: SessionMeta = {
+            type: "session",
+            version: 1,
+            id,
+            createdAt: 0,
+            cwd: "",
+            workspace: "",
+            metadata: {},
+            app: "wellspring",
+            appVersion: "1.0.0",
+            model: "",
+        }
+        const data: SessionData = {
+            meta,
+            header: { type: "session", metadata: {}, workspace: "" },
+            dir: "",
+            events: [],
+            turns: [],
+        }
+        super(data)
+    }
+
+    override async message(
+        content: string | readonly string[],
+        type = "message",
+    ): Promise<SessionMessage> {
+        const bridge = getHostBridge()
+        if (bridge === null) {
+            return await super.message(content, type)
+        }
+        await bridge.request("host.session.message", {
+            id: this.id,
+            content: typeof content === "string" ? [content] : [...content],
+            type,
+        })
+        return new SessionMessage({ sessionId: this.id, content, type })
+    }
+}
+
+/** 获取活跃会话；sandbox 插件通过 bridge 访问宿主注册表 */
+export async function getSession(id: string): Promise<Session | null> {
+    const bridge = getHostBridge()
+    if (bridge === null) {
+        return findSession(id)
+    }
+    const exists = (await bridge.request("host.session.exists", { id })) as boolean
+    return exists ? new RemoteSession(id) : null
+}

package/src/api/host/version.ts

@@ -0,0 +1,2 @@
+/** 宿主 API 版本，插件注册时校验 */
+export const HOST_API_VERSION = 1