@solazah/solazah-runtime 0.1.162 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solazah/solazah-runtime",
-  "version": "0.1.162",
+  "version": "0.2.9",
   "main": "index.cjs",
   "module": "index.js",
   "types": "types/index.d.ts",

package/types/Copilot.d.ts

@@ -41,12 +41,38 @@ export interface CopilotChatOptions extends CopilotBaseOptions {
      * 流式调用在 catch 分支抛错时由 streaming 层调用此回调，让上层有机会回滚预占的配额。
      */
     onStreamError?: () => Promise<void> | void;
+    /**
+     * 内部字段：main 进程构造，仅用于本进程内回调（不跨 IPC）。
+     * 本轮**真正结束**时调用（成功、失败、中止都算），发起方据此销掉这一轮的记账。
+     *
+     * 为什么不用 port 关闭代替：正常跑完的那一轮，渲染端的 for-await 自然退出，
+     * 按 JS 语义不会调迭代器的 return()，port 于是从不关闭。把结束这件事挂在别人的
+     * 生命周期上，就会得到一个「永远没结束」的运行中状态。
+     */
+    onRunFinished?: () => void;
+}
+/** 随用户一句话附上的一张图（data URL）。 */
+export interface CopilotInputImage {
+    url: string;
+    mime?: string;
+}
+/** 待投递给主 agent 的一条内容：notice = 后台任务完成通知，interject = 用户在生成途中插的话。 */
+export interface CopilotPendingInjection {
+    kind: "notice" | "interject";
+    /** 注入时用作消息 id(落库切片按 id 去重),同时是撤回的凭据。 */
+    id: string;
+    /** 投给模型看的整段文案。两条投递路径共用同一份,保证模型在轮中和轮间看到的内容一致。 */
+    text: string;
+    /** 随插话附上的图片；通知不带。 */
+    images?: CopilotInputImage[];
 }
 export interface CopilotOptions extends CopilotChatOptions {
     mcp?: string[];
     projectDir?: string;
     recursionLimit?: number;
     thread_id?: string;
+    /** 经哪个桥发起（如 wechat）。这一轮新建对话时写进对话行的 bridge。 */
+    bridge?: string;
     run_id?: string;
     /**
      * 计费用的模型名(LiteLLM 的 model_name,如 deepseek-v4-pro)。
@@ -89,14 +115,10 @@ export interface CopilotOptions extends CopilotChatOptions {
      */
     persistFromToolCallId?: string;
     /**
-     * 视觉模型的图片输入。每条 image_url 直接作为 content part 拼到本轮 HumanMessage 上,
-     * 与 input 文本同一条消息。仅 run() 这条路径用得到;completion/chat 不接。
-     * 渲染层负责判定模型是否支持视觉再传,这里不再二次过滤。
+     * 本轮用户消息附上的图片。视觉模型拼成 image_url 内容块，纯文本模型丢弃（见 CopilotHumanContent）。
+     * 仅 run() 这条路径用得到;completion/chat 不接。
      */
-    images?: {
-        url: string;
-        mime?: string;
-    }[];
+    images?: CopilotInputImage[];
 }
 export type CopilotRunOptions = CopilotOptions;
 /** 一行 = 某个模型某一天的 token 统计。model_name 是模型 id,显示名要另去模型清单里换。 */
@@ -125,7 +147,32 @@ export default class Copilot {
      */
     completion: (input: string, options: any) => Promise<any>;
     chat: (input: string, options: CopilotRunOptions) => Promise<AsyncIterableIterator<any>>;
-    run: (input: string, options: CopilotRunOptions) => Promise<AsyncIterableIterator<any>>;
+    /**
+     * 跑一轮。返回本轮的 requestId，**事件不在返回值里** —— 用 `onRunEvent` 订阅。
+     *
+     * 以前返回一条只有发起方拿得到的流，于是别人开的那一轮谁也看不见：
+     * 微信桥、定时任务在后台跑的轮次，本机界面只能等落库刷出结果。
+     * 订阅必须在发起**之前**建立，否则会漏掉开头那几条。
+     */
+    run: (input: string, options: CopilotRunOptions) => Promise<string>;
+    /** 轮次事件在本进程里的全部订阅者。端口只开一条，见 onRunEvent。 */
+    private readonly runEventSubscribers;
+    private runPortRequested;
+    /**
+     * 订阅轮次事件。**所有轮次都从这一条端口来**，按 threadId / requestId 自己认领；**多个订阅者互不影响**。
+     *
+     * 第一次订阅时向主进程报到，主进程开一条 MessagePort 送过来，之后每一轮的事件都从这条端口进来，
+     * 不经 ipcRenderer 的通道，没报到的渲染进程一条都收不到。端口只开一条：同一渲染进程里谁要谁挂进
+     * 订阅者集合。报到与开跑都是本进程发出的 IPC，先后有序：先报到再 run，开头那几条不会漏。
+     *
+     * @returns 退订函数
+     */
+    onRunEvent: (onEvent: (e: {
+        requestId: string;
+        threadId?: string;
+        event: string;
+        data?: any;
+    }) => void) => (() => void);
     /**
      * 按 requestId 中止正在进行的 chat/run/resume 流式执行:
      * 触发对应 AbortController 并向 provider 发出中止信号。
@@ -142,8 +189,9 @@ export default class Copilot {
      * @param threadId 会话 ID
      * @param id       消息 id,由渲染层生成;撤回与去重都按它
      * @param text     插话正文
+     * @param images   随插话附上的图片
      */
-    interjectPush: (threadId: string, id: string, text: string) => Promise<any>;
+    interjectPush: (threadId: string, id: string, text: string, images?: CopilotInputImage[]) => Promise<any>;
     /**
      * 撤回一条还没被领走的插话。
      *
@@ -159,6 +207,7 @@ export default class Copilot {
         threadId: string;
         ids: string[];
     }) => void) => (() => void);
-    resume: (response: any, options: CopilotRunOptions) => Promise<AsyncIterableIterator<any>>;
+    /** 续一轮。与 run 同理：返回 requestId，事件用 `onRunEvent` 订阅。 */
+    resume: (response: any, options: CopilotRunOptions) => Promise<string>;
     private invokeStream;
 }

package/types/CopilotSubAgent.d.ts

@@ -1,3 +1,4 @@
+import { CopilotPendingInjection } from './Copilot';
 export interface CopilotSubAgentRunDto {
     id: string;
     type: string;
@@ -150,11 +151,11 @@ export default class CopilotSubAgent {
         threadId: string;
     }) => void) => (() => void);
     /**
-     * 取走某会话待注入的文案(取走即清空):后台通知与用户插话共用同一个队列。
+     * 取走某会话待注入的内容(取走即清空):后台通知与用户插话共用同一个队列。
      * 与主进程「轮中注入」共用同一个队列,同一条通知只会被其中一方领到。
      *
      * @param threadId 会话 ID
-     * @returns 待投递文案数组;没有则空数组
+     * @returns 待投递内容;没有则空数组
      */
-    takePendingInjections: (threadId: string) => Promise<string[]>;
+    takePendingInjections: (threadId: string) => Promise<CopilotPendingInjection[]>;
 }

package/types/Plugin.d.ts

@@ -8,9 +8,14 @@ export interface PluginToolReply {
     /** 本机绝对路径,png / jpg / webp / gif,最多 4 张 */
     images?: string[];
 }
+/** 这次工具调用发生在哪。 */
+export interface PluginToolContext {
+    /** 发起调用的那条对话;不在对话里调用(如命令行直接驱动工具)时没有 */
+    threadId?: string;
+}
 export interface PluginTool {
     name: string;
-    cb: (args: any) => Promise<string | PluginToolReply> | string | PluginToolReply;
+    cb: (args: any, context: PluginToolContext) => Promise<string | PluginToolReply> | string | PluginToolReply;
     description: string;
     schema: object | null;
     timeoutMs?: number;
@@ -44,11 +49,12 @@ export default class Plugin {
     /**
      * 给 Otta 注册 AI 工具。
      * schema 传 JSON Schema 对象(如 z.toJSONSchema(...) 的返回值),无参工具传 null;
-     * cb 收到已按 schema 拆包的参数对象(无参工具收到 {}),返回字符串给 LLM(返回对象会被 JSON.stringify)。
+     * cb 收到已按 schema 拆包的参数对象(无参工具收到 {}),返回字符串给 LLM(返回对象会被 JSON.stringify);
+     * 第二个参数是调用上下文(见 PluginToolContext)。
      * options.timeoutMs 是宿主等待回执的上限,执行耗时长的工具要显式给。
      * 同名重复注册为覆盖(HMR 安全)。
      */
-    tool: (name: string, description: string, schema: object | null, cb: (args: any) => Promise<string> | string, options?: PluginToolOptions) => (args: any) => Promise<string> | string;
+    tool: (name: string, description: string, schema: object | null, cb: (args: any, context: PluginToolContext) => Promise<string> | string, options?: PluginToolOptions) => (args: any, context: PluginToolContext) => Promise<string> | string;
     onSearch: (commandName: string, handler: any) => Promise<void>;
     onAction: (commandName: string, action: string, handler: any) => Promise<void>;
     /**
@@ -65,6 +71,14 @@ export default class Plugin {
      * @returns 无返回。窗口不存在时静默忽略。
      */
     setHeight: (height: number) => Promise<any>;
+    /**
+     * 把发起方插件窗口的宽高一起设为指定像素值。调用前会清掉最小尺寸限制,免得被 minWidth/minHeight 钳住。
+     *
+     * @param width  目标宽度(像素)。
+     * @param height 目标高度(像素)。
+     * @returns 无返回。窗口不存在时静默忽略。
+     */
+    setSize: (width: number, height: number) => Promise<any>;
     /**
      * 读发起方插件窗口当前的位置与尺寸。
      * 用 -webkit-app-region 拖动时页面收不到任何鼠标事件,窗口位置只有主进程知道 ——
@@ -130,6 +144,35 @@ export default class Plugin {
      * @returns 无返回。
      */
     hide: () => Promise<any>;
+    /**
+     * 关掉发起方插件窗口:内容视图一并卸载,渲染进程立刻释放。发起方在主窗口里时退回启动器主页,不关主窗口。
+     *
+     * 与 hide 的分野是复用:hide 把窗口与视图整套留着换零延迟唤起,之后由巡检按收起时长回收。
+     * 每次都按新参数重建、没有可复用内容的窗口(采集边框、采集控制条这类)用 close,别占着一个渲染进程等巡检。
+     * 反过来,热路径上反复唤起的浮层(截图浮层这类)该留给 hide —— close 掉就等于每次都付一次冷启动。
+     *
+     * 调用方自己随即被销毁,这个 Promise **不会 resolve**:别 await 它,也别在它后面接代码。
+     *
+     * @returns 不 resolve。
+     */
+    close: () => Promise<any>;
+    /**
+     * 让发起方插件视图真正拿到键盘焦点:先激活承载它的窗口,再聚焦这个视图。
+     * 透明 floating 浮层鼠标可点但键盘不激活、输入框敲不进字时用它。
+     *
+     * @param force 顶到前台。授权流程从系统浏览器切回来这类场景要开:此刻前台是别的应用,
+     *              普通 focus 会被 Windows 的前台锁定丢成任务栏闪烁。
+     * @returns 无返回。
+     */
+    focus: (force?: boolean) => Promise<any>;
+    /**
+     * 设置发起方窗口是否置顶(screen-saver 级,压得住普通窗口与菜单栏)。
+     * 钉屏窗口加载时调它,确保始终置顶且失焦不收起。
+     *
+     * @param value 是否置顶。
+     * @returns 设置后的置顶状态(boolean)。
+     */
+    setAlwaysOnTop: (value: boolean) => Promise<boolean>;
     /**
      * 切换发起方窗口的置顶状态(screen-saver 级),返回切换后的状态。
      * 同时向发起方视图广播 plugin.alwaysOnTopChanged 事件,便于渲染层同步回显。

package/types/SystemShell.d.ts

@@ -22,6 +22,16 @@ export default class SystemShell {
      * @returns 操作完成（`Promise<void>`）；返回值被丢弃，异常直接传播给调用方。
      */
     openPath: (path: string) => Promise<any>;
+    /**
+     * 把一段字节落到临时区再用默认程序打开。
+     *
+     * 给「文件不在这台机器上」用：连着别的电脑看对话时，附件的实体在执行端，
+     * 这一端只有内容本身，拿路径打不开。临时区每次启动清空。
+     *
+     * @param name   展示用文件名，决定扩展名，也就决定用哪个程序打开。
+     * @param base64 文件内容。
+     */
+    openBuffer: (name: string, base64: string) => Promise<any>;
     /** 在资源管理器/Finder 中显示并选中该文件(或文件夹) */
     showItemInFolder: (path: string) => Promise<any>;
     openTerminal: (options?: {