@xyit/wellspring 0.0.0-stage → 1.1.0

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
+}

package/src/agent/task-registry.ts

@@ -0,0 +1,108 @@
+// 后台 execute_code 任务注册表
+
+import type { AgentCodeResult, AgentCodeTaskHandle, StopMode } from "../sandbox/types.ts"
+
+export interface AgentTaskInfo {
+    readonly taskId: string
+    readonly sandboxId: string
+    readonly status: "running" | "completed" | "failed" | "cancelled"
+    readonly startedAt: number
+    readonly stdout: string
+    readonly stderr: string
+    readonly result: AgentCodeResult | null
+    readonly error: string | null
+}
+
+interface TaskRecord {
+    readonly taskId: string
+    readonly handle: AgentCodeTaskHandle
+    readonly startedAt: number
+    status: "running" | "completed" | "failed" | "cancelled"
+    cancelled: boolean
+    result: AgentCodeResult | null
+    error: string | null
+}
+
+const tasks = new Map<string, TaskRecord>()
+const order: string[] = []
+
+export function registerBackgroundTask(handle: AgentCodeTaskHandle): AgentTaskInfo {
+    const taskId = handle.sandboxId
+    const record: TaskRecord = {
+        taskId,
+        handle,
+        startedAt: Date.now(),
+        status: "running",
+        cancelled: false,
+        result: null,
+        error: null,
+    }
+    tasks.set(taskId, record)
+    order.push(taskId)
+    while (order.length > 50) {
+        const oldest = order.shift()
+        if (oldest !== undefined) {
+            tasks.delete(oldest)
+        }
+    }
+    void handle
+        .wait()
+        .then((result) => {
+            record.status = record.cancelled ? "cancelled" : "completed"
+            record.result = result
+        })
+        .catch((error: unknown) => {
+            record.status = "failed"
+            record.error = error instanceof Error ? error.message : String(error)
+        })
+    return infoOf(record)
+}
+
+function infoOf(record: TaskRecord): AgentTaskInfo {
+    return {
+        taskId: record.taskId,
+        sandboxId: record.handle.sandboxId,
+        status:
+            record.status === "completed" &&
+            (record.result?.signal === "SIGINT" || record.result?.signal === "SIGKILL")
+                ? "cancelled"
+                : record.status,
+        startedAt: record.startedAt,
+        stdout: record.result?.stdout ?? record.handle.stdout,
+        stderr: record.result?.stderr ?? record.handle.stderr,
+        result: record.result,
+        error: record.error,
+    }
+}
+
+export function queryTask(taskId?: string): AgentTaskInfo | null {
+    if (taskId !== undefined && taskId !== "") {
+        const record = tasks.get(taskId)
+        return record === undefined ? null : infoOf(record)
+    }
+    for (let index = order.length - 1; index >= 0; index -= 1) {
+        const id = order[index]
+        if (id !== undefined) {
+            const record = tasks.get(id)
+            if (record !== undefined && record.status === "running") {
+                return infoOf(record)
+            }
+        }
+    }
+    const latest = order[order.length - 1]
+    return latest === undefined ? null : infoOf(tasks.get(latest)!)
+}
+
+export function stopTask(taskId: string | undefined, mode: StopMode): boolean {
+    const info = queryTask(taskId)
+    if (info === null) {
+        return false
+    }
+    const record = tasks.get(info.taskId)
+    if (record === undefined || record.status !== "running") {
+        return false
+    }
+    record.cancelled = true
+    record.handle.stop(mode)
+    return true
+}

package/src/agent/tool-context.ts

@@ -0,0 +1,47 @@
+// 插件工具调用上下文：宿主能力在调用期间读取当前 Agent 权限
+
+import { AsyncLocalStorage } from "node:async_hooks"
+
+import type { SandboxAccess } from "../config/types.ts"
+import type { Elog } from "../logger/elog4js.ts"
+
+export interface AgentToolRequest {
+    readonly command: string
+    readonly argv: readonly string[]
+    readonly cwd: string
+    readonly currentPermission?: SandboxAccess
+    readonly requestedPermission?: SandboxAccess
+    readonly justification?: string
+    /** 请求联网：和提权是两件事，审阅时也要看到 */
+    readonly network?: boolean
+    /** 请求后台执行 */
+    readonly background?: boolean
+    /** 要喂给进程的标准输入（可能很大，界面截断显示） */
+    readonly stdin?: string
+    /** 请求的超时毫秒 */
+    readonly timeoutMs?: number
+}
+
+export interface AgentToolContext {
+    readonly sessionId: string
+    readonly turn: number
+    readonly step: number
+    readonly workspaceDir: string
+    readonly permission: SandboxAccess
+    readonly allowExec: boolean
+    readonly approveExec?: (request: AgentToolRequest) => Promise<boolean>
+    readonly elog: Elog
+}
+
+const storage = new AsyncLocalStorage<AgentToolContext>()
+
+export async function withAgentToolContext<T>(
+    context: AgentToolContext,
+    task: () => Promise<T>,
+): Promise<T> {
+    return await storage.run(context, task)
+}
+
+export function getAgentToolContext(): AgentToolContext | null {
+    return storage.getStore() ?? null
+}

package/src/agent/usage.ts

@@ -0,0 +1,170 @@
+/*
+ * Token 用量：模型报告的输出、缓存命中与上下文占用。
+ *
+ * `inputTokens` 统一成 prompt tokens 总数，缓存命中的部分也计算在内；
+ * `cacheReadTokens` / `cacheWriteTokens` 是其中的缓存读取与写入。
+ * 不同供应商口径由 parseProviderUsage 抹平：
+ * - DeepSeek / OpenAI：prompt_tokens（或 Responses 的 input_tokens）本身含缓存命中，
+ *   命中数在 prompt_cache_hit_tokens 或 prompt_tokens_details.cached_tokens；
+ * - 部分网关沿用 Anthropic 的 cache_read_input_tokens / cache_creation_input_tokens，
+ *   这时 input_tokens 只是未缓存部分，parse 会加上两段缓存凑成总数。
+ */
+
+/** 一次模型调用报告的用量；供应商没返回的项为 null */
+export interface ProviderUsage {
+    readonly inputTokens: number | null
+    readonly outputTokens: number | null
+    readonly cacheReadTokens: number | null
+    readonly cacheWriteTokens: number | null
+    readonly reasoningTokens: number | null
+}
+
+/** 界面几处共用的按需字段：空值不写进会话，旧数据格式保持不变 */
+export interface TokenUsage {
+    readonly inputTokens: number | null
+    readonly outputTokens: number | null
+    readonly cacheReadTokens?: number | null
+    readonly cacheWriteTokens?: number | null
+    readonly reasoningTokens?: number | null
+    /** 这一轮最后一次请求的 prompt tokens，即收尾时占用的上下文 */
+    readonly contextTokens?: number | null
+}
+
+function countOf(value: unknown): number | null {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        return null
+    }
+    return Math.floor(value)
+}
+
+function recordOf(value: unknown): Record<string, unknown> | null {
+    return value !== null && typeof value === "object" ? (value as Record<string, unknown>) : null
+}
+
+/** 把供应商的 usage 原样对象归一化成计数；一条可用字段都没有时返回 null */
+export function parseProviderUsage(value: unknown): ProviderUsage | null {
+    const record = recordOf(value)
+    if (record === null) {
+        return null
+    }
+    const promptDetails = recordOf(record["prompt_tokens_details"])
+    const inputDetails = recordOf(record["input_tokens_details"])
+    const completionDetails = recordOf(record["completion_tokens_details"])
+    const outputDetails = recordOf(record["output_tokens_details"])
+    let input = countOf(record["prompt_tokens"]) ?? countOf(record["input_tokens"])
+    const output = countOf(record["completion_tokens"]) ?? countOf(record["output_tokens"])
+    const cacheRead =
+        countOf(record["prompt_cache_hit_tokens"]) ??
+        countOf(promptDetails?.["cached_tokens"]) ??
+        countOf(inputDetails?.["cached_tokens"]) ??
+        countOf(record["cache_read_input_tokens"])
+    const cacheWrite =
+        countOf(record["cache_creation_input_tokens"]) ??
+        countOf(promptDetails?.["cache_creation_tokens"]) ??
+        countOf(inputDetails?.["cache_creation_tokens"])
+    /*
+     * Anthropic 口径的 input_tokens 不含缓存读取/写入，补成 prompt 总数；
+     * 有 prompt_tokens 或 *_tokens_details 的 OpenAI 口径不能再加，否则重复计数。
+     */
+    const anthropicStyle =
+        record["prompt_tokens"] === undefined &&
+        promptDetails === null &&
+        inputDetails === null &&
+        (cacheRead !== null || cacheWrite !== null) &&
+        (record["cache_read_input_tokens"] !== undefined ||
+            record["cache_creation_input_tokens"] !== undefined)
+    if (anthropicStyle && input !== null) {
+        input += (cacheRead ?? 0) + (cacheWrite ?? 0)
+    }
+    const reasoning =
+        countOf(completionDetails?.["reasoning_tokens"]) ??
+        countOf(outputDetails?.["reasoning_tokens"])
+    if (input === null && output === null && cacheRead === null && cacheWrite === null) {
+        return null
+    }
+    return {
+        inputTokens: input,
+        outputTokens: output,
+        cacheReadTokens: cacheRead,
+        cacheWriteTokens: cacheWrite,
+        reasoningTokens: reasoning,
+    }
+}
+
+/**
+ * 缓存命中率（0-100 整数）
+ *
+ * 分母是 prompt tokens 总数；`cacheRead` 是其中的子集。
+ * 供应商没报告缓存或没有任何输入时返回 null。
+ */
+export function cacheHitPercent(
+    cacheReadTokens: number | null | undefined,
+    promptTokens: number | null | undefined,
+): number | null {
+    if (typeof cacheReadTokens !== "number" || typeof promptTokens !== "number") {
+        return null
+    }
+    if (!Number.isFinite(cacheReadTokens) || !Number.isFinite(promptTokens) || promptTokens <= 0) {
+        return null
+    }
+    const percent = Math.round((cacheReadTokens / promptTokens) * 100)
+    return Math.min(100, Math.max(0, percent))
+}
+
+/** 未缓存输入：prompt tokens 减去缓存读取/写入，最小为 0 */
+export function uncachedInputTokens(
+    inputTokens: number | null | undefined,
+    cacheReadTokens: number | null | undefined,
+    cacheWriteTokens?: number | null,
+): number | null {
+    if (typeof inputTokens !== "number" || !Number.isFinite(inputTokens) || inputTokens < 0) {
+        return null
+    }
+    const cacheRead =
+        typeof cacheReadTokens === "number" && Number.isFinite(cacheReadTokens)
+            ? cacheReadTokens
+            : 0
+    const cacheWrite =
+        typeof cacheWriteTokens === "number" && Number.isFinite(cacheWriteTokens)
+            ? cacheWriteTokens
+            : 0
+    return Math.max(0, Math.floor(inputTokens - cacheRead - cacheWrite))
+}
+
+/** 去掉空的可选字段：会话 JSON 里只留供应商真的报告过的项 */
+export function compactUsage(usage: TokenUsage): TokenUsage {
+    return {
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        ...(typeof usage.cacheReadTokens === "number"
+            ? { cacheReadTokens: usage.cacheReadTokens }
+            : {}),
+        ...(typeof usage.cacheWriteTokens === "number"
+            ? { cacheWriteTokens: usage.cacheWriteTokens }
+            : {}),
+        ...(typeof usage.reasoningTokens === "number"
+            ? { reasoningTokens: usage.reasoningTokens }
+            : {}),
+        ...(typeof usage.contextTokens === "number" ? { contextTokens: usage.contextTokens } : {}),
+    }
+}
+
+/** 一次模型回复的结构化用量；inputTokens 默认就是这次请求占用的上下文 */
+export interface UsageSource {
+    readonly inputTokens: number | null
+    readonly outputTokens: number | null
+    readonly cacheReadTokens?: number | null
+    readonly cacheWriteTokens?: number | null
+    readonly reasoningTokens?: number | null
+}
+
+export function usageOf(source: UsageSource, contextTokens?: number | null): TokenUsage {
+    return compactUsage({
+        inputTokens: source.inputTokens,
+        outputTokens: source.outputTokens,
+        cacheReadTokens: source.cacheReadTokens ?? null,
+        cacheWriteTokens: source.cacheWriteTokens ?? null,
+        reasoningTokens: source.reasoningTokens ?? null,
+        contextTokens: contextTokens === undefined ? source.inputTokens : contextTokens,
+    })
+}

package/src/api/host/agent.ts

@@ -0,0 +1,162 @@
+/*
+ * 宿主 Agent 能力：让 sandbox 插件与 Agent 会话交互。
+ */
+
+import type { TokenUsage } from "../../agent/usage.ts"
+
+/** Agent 运行时的 sandbox 权限；与 CLI 的 --permission 取值一致 */
+export type HostAgentPermission = "read-only" | "workspace-write" | "danger-full-access"
+
+export interface HostAgentChatInput {
+    /** 用户消息 */
+    readonly message: string
+    /** 已有会话 id；不传则创建新会话 */
+    readonly sessionId?: string
+    /** 覆盖本次使用的模型 */
+    readonly model?: string
+    /** 覆盖本次使用的供应商 id（内置为 openai） */
+    readonly provider?: string
+    /** 覆盖本次推理强度：off / low / high / max */
+    readonly reasoning?: string
+    /** 覆盖本次 system prompt */
+    readonly system?: string
+    /** 会话所在工作目录；不传使用宿主当前目录 */
+    readonly cwd?: string
+    /** 用户在输入框里用 @ 引用的工作区相对路径 */
+    readonly references?: readonly string[]
+    /** 覆盖本轮的 sandbox 权限；不传则使用宿主配置的 sandbox.access */
+    readonly permission?: HostAgentPermission
+}
+
+export interface HostAgentChatResult {
+    readonly sessionId: string
+    /** 会话内第几轮 */
+    readonly turn: number
+    /** 本轮执行的步数 */
+    readonly steps: number
+    readonly reply: string
+    readonly model: string
+    /** 本轮 token 用量：含缓存命中/写入、推理与收尾时的上下文占用 */
+    readonly usage: TokenUsage | null
+}
+
+export interface HostWorkspaceFileEntry {
+    /** 相对工作区根的路径，使用 / 分隔 */
+    readonly path: string
+    readonly name: string
+    readonly type: "file" | "directory"
+}
+
+export interface HostWorkspaceFilesResult {
+    readonly ok: boolean
+    readonly root: string
+    readonly entries: readonly HostWorkspaceFileEntry[]
+    readonly truncated: boolean
+    readonly error?: string
+}
+
+/** 工作目录校验结果：root 为规范化后的绝对路径 */
+export interface HostWorkspaceCheck {
+    readonly ok: boolean
+    readonly root: string
+    readonly name: string
+    /** ok=false 时的原因 */
+    readonly error?: string
+}
+
+export interface HostAgentApprovalRequest {
+    readonly approvalId: string
+    readonly command: string
+    readonly argv: readonly string[]
+    readonly cwd: string
+    readonly currentPermission?: string
+    readonly requestedPermission?: string
+    readonly justification?: string
+    /** 请求联网 */
+    readonly network?: boolean
+    /** 请求后台执行 */
+    readonly background?: boolean
+    /** 标准输入；界面按长度截断显示 */
+    readonly stdin?: string
+    /** 请求的超时毫秒 */
+    readonly timeoutMs?: number
+}
+
+/** Agent 用 ask 工具向用户提问；界面回答后 Agent 继续 */
+export interface HostAgentAskRequest {
+    readonly askId: string
+    readonly question: string
+    /** 候选答案；用户可以选，也可以自由输入 */
+    readonly options?: readonly string[]
+}
+
+/** 一次工具调用的生命周期事件；界面用来显示“正在调用什么工具” */
+export interface HostAgentToolEvent {
+    readonly id: string
+    readonly name: string
+    readonly phase: "start" | "end"
+    /** start 时为模型的原始参数 JSON */
+    readonly arguments?: string
+    /** end 时是否执行成功 */
+    readonly ok?: boolean
+    /** end 时的工具输出（过长时截断） */
+    readonly result?: string
+    /** result 是否被截断 */
+    readonly truncated?: boolean
+}
+
+export type HostAgentStreamEvent =
+    /** 会话已创建/打开：客户端可先保存 sessionId，刷新后仍能续上同一会话 */
+    | { readonly type: "session"; readonly sessionId: string; readonly turn?: number }
+    | { readonly type: "delta"; readonly text: string }
+    /** 模型思考内容增量（reasoning_content） */
+    | { readonly type: "reasoning"; readonly text: string }
+    /** 工具调用开始/结束 */
+    | ({ readonly type: "tool" } & HostAgentToolEvent)
+    /** Agent 提问，等待用户回答 */
+    | { readonly type: "ask"; readonly request: HostAgentAskRequest }
+    /** 开始执行第 step 步；用于界面显示进度 */
+    | { readonly type: "step"; readonly turn: number; readonly step: number }
+    /** 工具请求提升权限，等待用户批准 */
+    | { readonly type: "approval"; readonly request: HostAgentApprovalRequest }
+
+export interface HostAgentApi {
+    chat(input: HostAgentChatInput): Promise<HostAgentChatResult>
+    /** 流式执行；delta 通过回调推送，Promise 在完成时返回最终结果 */
+    stream(
+        input: HostAgentChatInput,
+        onEvent: (event: HostAgentStreamEvent) => void,
+    ): Promise<HostAgentChatResult>
+    /** 校验工作目录：必须是已存在的目录；返回规范化路径与目录名 */
+    validateWorkspace(path: string): Promise<HostWorkspaceCheck>
+    /** 打开宿主系统的原生文件夹选择对话框，返回选中的目录 */
+    pickDirectory(): Promise<HostWorkspaceCheck>
+    /**
+     * 在工作区里搜索文件与目录
+     *
+     * 空 query 列根目录一层；query 以 / 结尾且目录存在时列该目录一层
+     * 单关键字按文件名优先排序，其次路径段、路径包含、子序列
+     * 多段查询（a/b/c）按路径段链式匹配，前缀目录不必存在
+     * 跳过依赖/构建目录与符号链接；受扫描条目、深度与时间上限约束
+     */
+    searchWorkspaceFiles(root: string, query: string): Promise<HostWorkspaceFilesResult>
+    /**
+     * 向正在运行的会话插话
+     *
+     * 消息进入该会话的待注入队列，在 Agent 下一次模型调用前作为用户消息插入同一轮
+     * 会话不在运行中（尚未开始或已结束）返回 false，调用方按下一轮处理
+     */
+    interject(sessionId: string, message: string): Promise<boolean>
+    /**
+     * 停止正在运行的一轮
+     *
+     * 已发出的模型调用不会被切断：循环在当前步结束后收尾，
+     * 后续步骤、工具执行都不再发起。等待中的提问与提权请求按“跳过 / 拒绝”了结。
+     * 会话不在运行中返回 false
+     */
+    stop(sessionId: string): Promise<boolean>
+    /** 回复提权请求；返回是否命中待处理的请求 */
+    respondApproval(approvalId: string, approved: boolean): Promise<boolean>
+    /** 回答 Agent 的提问；返回是否命中待处理的提问 */
+    respondAsk(askId: string, answer: string): Promise<boolean>
+}

package/src/api/host/events.ts

@@ -0,0 +1,7 @@
+/*
+ * 宿主事件总线。
+ * 插件可以通过 `import { event } from "wellspring/api/host/index.ts"` 订阅/发布事件。
+ */
+
+export { EventEntity, EventBus, eventBus } from "../../event/event.ts"
+export type { EventListener } from "../../event/event.ts"

package/src/api/host/exec.ts

@@ -0,0 +1,47 @@
+/*
+ * 宿主进程执行 API。
+ * 插件被 access-guard 禁止直接 import node:child_process，需要跑命令时走这里。
+ * 执行与输出缓冲都在宿主侧，插件用 poll 拉增量，不为终端单独引入流式 RPC。
+ */
+
+export interface HostExecRunOptions {
+    /** 交给 shell 解释的命令行 */
+    readonly command: string
+    /** 工作目录，必须落在允许的执行根内 */
+    readonly cwd: string
+    /** 追加的环境变量 */
+    readonly env?: Record<string, string>
+    /** 超时毫秒，到点终止整个进程组 */
+    readonly timeoutMs?: number
+}
+
+export interface HostExecSession {
+    readonly sessionId: string
+    readonly pid: number | null
+    readonly cwd: string
+}
+
+export interface HostExecChunk {
+    /** 自上次 poll 之后新增的输出 */
+    readonly chunk: string
+    /** 进程是否已结束 */
+    readonly done: boolean
+    /** 退出码；被信号终止时为 null */
+    readonly exitCode: number | null
+    /** 因超时被终止 */
+    readonly timedOut: boolean
+    /** 输出被上限截断 */
+    readonly truncated: boolean
+}
+
+export interface HostExecApi {
+    run(options: HostExecRunOptions): Promise<HostExecSession>
+    poll(sessionId: string): Promise<HostExecChunk>
+    stop(sessionId: string): Promise<void>
+}
+
+/** 单条会话的输出上限，超出即截断并终止 */
+export const HOST_EXEC_MAX_OUTPUT_BYTES = 2 * 1024 * 1024
+
+/** 未显式指定时的超时上限 */
+export const HOST_EXEC_DEFAULT_TIMEOUT_MS = 120_000

package/src/api/host/fs.ts

@@ -0,0 +1,33 @@
+/*
+ * 宿主文件 API。
+ * 插件通过 api.fs / ctx.fs（插件数据目录）或 api.workspaceFs / ctx.workspaceFs（当前工作目录）访问文件。
+ * 路径必须是相对路径，且不能逃出对应根目录。
+ */
+
+export type HostFileType = "file" | "directory" | "other"
+
+export interface HostFileStat {
+    readonly type: HostFileType
+    readonly size: number
+    readonly mtimeMs: number
+}
+
+export interface HostFileEntry extends HostFileStat {
+    readonly name: string
+}
+
+export interface HostFileApi {
+    /** 该 API 的根目录，仅用于展示/诊断 */
+    readonly root: string
+    readText(path: string): Promise<string | null>
+    readBytes(path: string): Promise<Uint8Array | null>
+    readJson<T = unknown>(path: string): Promise<T | null>
+    writeText(path: string, text: string): Promise<void>
+    writeBytes(path: string, bytes: Uint8Array): Promise<void>
+    writeJson(path: string, value: unknown): Promise<void>
+    list(path?: string): Promise<readonly HostFileEntry[]>
+    stat(path: string): Promise<HostFileStat | null>
+    mkdir(path: string): Promise<void>
+    remove(path: string): Promise<void>
+    exists(path: string): Promise<boolean>
+}