@xyit/wellspring 0.0.0-stage → 1.1.0

package/dist/agent/pending-asks.d.ts

@@ -0,0 +1,20 @@
+/** 等待用户回答的上限；超时后工具返回“没有回答”并继续 */
+export declare const ASK_TIMEOUT_MS: number;
+export declare function createAskId(): string;
+/**
+ * 登记一个等待回答的问题。answerAsk 先把 answer 交给这个 Promise；
+ * 超时兑现 null（用户没回答）。
+ */
+export declare function waitForAsk(input: {
+    readonly askId: string;
+    readonly sessionId: string;
+    readonly timeoutMs?: number;
+}): Promise<string | null>;
+/** 用户回答；命中等待中的问题时返回 true */
+export declare function answerAsk(askId: string, answer: string): boolean;
+/** 取消一次等待（工具循环收尾、异常退出时调用） */
+export declare function cancelAsk(askId: string): void;
+/** 会话结束时清掉遗留的等待 */
+export declare function cancelSessionAsks(sessionId: string): void;
+/** 当前等待回答的数量（测试与诊断用） */
+export declare function pendingAskCount(): number;

package/dist/agent/pending-asks.js

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

package/dist/agent/pending-asks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-asks.js","sourceRoot":"","sources":["../../src/agent/pending-asks.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,iCAAiC;AACjC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,GAAG,MAAM,CAAA;AAQxC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAA;AAE7C,MAAM,UAAU,WAAW;IACvB,OAAO,OAAO,UAAU,EAAE,EAAE,CAAA;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAI1B;IACG,OAAO,IAAI,OAAO,CAAgB,CAAC,cAAc,EAAE,EAAE;QACjD,IAAI,OAAO,GAAG,KAAK,CAAA;QACnB,IAAI,KAAK,GAA0B,IAAI,CAAA;QACvC,MAAM,MAAM,GAAG,CAAC,MAAqB,EAAQ,EAAE;YAC3C,IAAI,OAAO,EAAE,CAAC;gBACV,OAAM;YACV,CAAC;YACD,OAAO,GAAG,IAAI,CAAA;YACd,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACjB,YAAY,CAAC,KAAK,CAAC,CAAA;YACvB,CAAC;YACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;YAC3B,cAAc,CAAC,MAAM,CAAC,CAAA;QAC1B,CAAC,CAAA;QACD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACpB,MAAM,CAAC,IAAI,CAAC,CAAA;QAChB,CAAC,EAAE,KAAK,CAAC,SAAS,IAAI,cAAc,CAAC,CAAA;QACrC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE;YACrB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,OAAO,EAAE,MAAM;YACf,KAAK;SACR,CAAC,CAAA;IACN,CAAC,CAAC,CAAA;AACN,CAAC;AAED,4BAA4B;AAC5B,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,MAAc;IACnD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;IAChC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO,KAAK,CAAA;IAChB,CAAC;IACD,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACrB,OAAO,IAAI,CAAA;AACf,CAAC;AAED,6BAA6B;AAC7B,MAAM,UAAU,SAAS,CAAC,KAAa;IACnC,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;IAChC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACtB,OAAM;IACV,CAAC;IACD,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;AACvB,CAAC;AAED,mBAAmB;AACnB,MAAM,UAAU,iBAAiB,CAAC,SAAiB;IAC/C,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,EAAE,CAAC;QACxC,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAChC,SAAS,CAAC,KAAK,CAAC,CAAA;QACpB,CAAC;IACL,CAAC;AACL,CAAC;AAED,wBAAwB;AACxB,MAAM,UAAU,eAAe;IAC3B,OAAO,OAAO,CAAC,IAAI,CAAA;AACvB,CAAC"}

package/dist/agent/task-registry.d.ts

@@ -0,0 +1,14 @@
+import type { AgentCodeResult, AgentCodeTaskHandle, StopMode } from "../sandbox/types.js";
+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;
+}
+export declare function registerBackgroundTask(handle: AgentCodeTaskHandle): AgentTaskInfo;
+export declare function queryTask(taskId?: string): AgentTaskInfo | null;
+export declare function stopTask(taskId: string | undefined, mode: StopMode): boolean;

package/dist/agent/task-registry.js

@@ -0,0 +1,80 @@
+// 后台 execute_code 任务注册表
+const tasks = new Map();
+const order = [];
+export function registerBackgroundTask(handle) {
+    const taskId = handle.sandboxId;
+    const record = {
+        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) => {
+        record.status = "failed";
+        record.error = error instanceof Error ? error.message : String(error);
+    });
+    return infoOf(record);
+}
+function infoOf(record) {
+    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) {
+    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, mode) {
+    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;
+}
+//# sourceMappingURL=task-registry.js.map

package/dist/agent/task-registry.js.map

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

package/dist/agent/tool-context.d.ts

@@ -0,0 +1,30 @@
+import type { SandboxAccess } from "../config/types.js";
+import type { Elog } from "../logger/elog4js.js";
+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;
+}
+export declare function withAgentToolContext<T>(context: AgentToolContext, task: () => Promise<T>): Promise<T>;
+export declare function getAgentToolContext(): AgentToolContext | null;

package/dist/agent/tool-context.js

@@ -0,0 +1,10 @@
+// 插件工具调用上下文：宿主能力在调用期间读取当前 Agent 权限
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+export async function withAgentToolContext(context, task) {
+    return await storage.run(context, task);
+}
+export function getAgentToolContext() {
+    return storage.getStore() ?? null;
+}
+//# sourceMappingURL=tool-context.js.map

package/dist/agent/tool-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-context.js","sourceRoot":"","sources":["../../src/agent/tool-context.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAiCpD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAoB,CAAA;AAEzD,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACtC,OAAyB,EACzB,IAAsB;IAEtB,OAAO,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;AAC3C,CAAC;AAED,MAAM,UAAU,mBAAmB;IAC/B,OAAO,OAAO,CAAC,QAAQ,EAAE,IAAI,IAAI,CAAA;AACrC,CAAC"}

package/dist/agent/usage.d.ts

@@ -0,0 +1,40 @@
+/** 一次模型调用报告的用量；供应商没返回的项为 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;
+}
+/** 把供应商的 usage 原样对象归一化成计数；一条可用字段都没有时返回 null */
+export declare function parseProviderUsage(value: unknown): ProviderUsage | null;
+/**
+ * 缓存命中率（0-100 整数）
+ *
+ * 分母是 prompt tokens 总数；`cacheRead` 是其中的子集。
+ * 供应商没报告缓存或没有任何输入时返回 null。
+ */
+export declare function cacheHitPercent(cacheReadTokens: number | null | undefined, promptTokens: number | null | undefined): number | null;
+/** 未缓存输入：prompt tokens 减去缓存读取/写入，最小为 0 */
+export declare function uncachedInputTokens(inputTokens: number | null | undefined, cacheReadTokens: number | null | undefined, cacheWriteTokens?: number | null): number | null;
+/** 去掉空的可选字段：会话 JSON 里只留供应商真的报告过的项 */
+export declare function compactUsage(usage: TokenUsage): TokenUsage;
+/** 一次模型回复的结构化用量；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 declare function usageOf(source: UsageSource, contextTokens?: number | null): TokenUsage;

package/dist/agent/usage.js

@@ -0,0 +1,122 @@
+/*
+ * 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 会加上两段缓存凑成总数。
+ */
+function countOf(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        return null;
+    }
+    return Math.floor(value);
+}
+function recordOf(value) {
+    return value !== null && typeof value === "object" ? value : null;
+}
+/** 把供应商的 usage 原样对象归一化成计数；一条可用字段都没有时返回 null */
+export function parseProviderUsage(value) {
+    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, promptTokens) {
+    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, cacheReadTokens, cacheWriteTokens) {
+    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) {
+    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 } : {}),
+    };
+}
+export function usageOf(source, contextTokens) {
+    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,
+    });
+}
+//# sourceMappingURL=usage.js.map

package/dist/agent/usage.js.map

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

package/dist/api/host/agent.d.ts

@@ -0,0 +1,165 @@
+import type { TokenUsage } from "../../agent/usage.js";
+/** 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/dist/api/host/agent.js

@@ -0,0 +1,5 @@
+/*
+ * 宿主 Agent 能力：让 sandbox 插件与 Agent 会话交互。
+ */
+export {};
+//# sourceMappingURL=agent.js.map

package/dist/api/host/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/api/host/agent.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/api/host/events.d.ts

@@ -0,0 +1,2 @@
+export { EventEntity, EventBus, eventBus } from "../../event/event.js";
+export type { EventListener } from "../../event/event.js";

package/dist/api/host/events.js

@@ -0,0 +1,6 @@
+/*
+ * 宿主事件总线。
+ * 插件可以通过 `import { event } from "wellspring/api/host/index.ts"` 订阅/发布事件。
+ */
+export { EventEntity, EventBus, eventBus } from "../../event/event.js";
+//# sourceMappingURL=events.js.map

package/dist/api/host/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/api/host/events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/api/host/exec.d.ts

@@ -0,0 +1,36 @@
+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 declare const HOST_EXEC_MAX_OUTPUT_BYTES: number;
+/** 未显式指定时的超时上限 */
+export declare const HOST_EXEC_DEFAULT_TIMEOUT_MS = 120000;

package/dist/api/host/exec.js

@@ -0,0 +1,10 @@
+/*
+ * 宿主进程执行 API。
+ * 插件被 access-guard 禁止直接 import node:child_process，需要跑命令时走这里。
+ * 执行与输出缓冲都在宿主侧，插件用 poll 拉增量，不为终端单独引入流式 RPC。
+ */
+/** 单条会话的输出上限，超出即截断并终止 */
+export const HOST_EXEC_MAX_OUTPUT_BYTES = 2 * 1024 * 1024;
+/** 未显式指定时的超时上限 */
+export const HOST_EXEC_DEFAULT_TIMEOUT_MS = 120_000;
+//# sourceMappingURL=exec.js.map