@aalis/plugin-tools 0.8.0 → 0.10.0

package/README.md

@@ -13,7 +13,7 @@ pnpm add @aalis/plugin-tools
 
 ## 文档
 
-详见 [docs/plugins/plugin-tool-system.md](../../docs/plugins/plugin-tool-system.md)。
+详见 [docs/plugins/plugin-tools.md](../../docs/plugins/plugin-tools.md)。
 
 ## 许可
 

package/dist/background-tools.d.ts

@@ -0,0 +1,6 @@
+import type { RegisteredTool } from '@aalis/api-tools';
+import { type BackgroundTasks } from './background.js';
+type Tool = Omit<RegisteredTool, 'pluginName'>;
+export declare function backgroundTaskTools(tasks: BackgroundTasks): Tool[];
+export {};
+//# sourceMappingURL=background-tools.d.ts.map

package/dist/background-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-tools.d.ts","sourceRoot":"","sources":["../src/background-tools.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAkB,cAAc,EAAwC,MAAM,kBAAkB,CAAC;AAC7G,OAAO,EAAE,KAAK,eAAe,EAAiC,MAAM,iBAAiB,CAAC;AAEtF,KAAK,IAAI,GAAG,IAAI,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;AAqC/C,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,EAAE,CAkFlE"}

package/dist/background-tools.js

@@ -0,0 +1,85 @@
+// ════════════════════════════════════════════════════════════
+// 四个后台任务工具（执行器提供）：列出、取输出、等待、停止本会话里的后台任务。按会话放行：本会话里的后台任务谁都能查、
+// 能停，不论是谁起的；别的会话里的回「不存在」。不设 restricted 与 risk，取输出也不另设等级闸：任务的输出与结果本来就在
+// 这个会话里，与前台调用的结果一样谁在场谁看得到。结束通知开的那一轮仍按起它的人的身份运行。
+// ════════════════════════════════════════════════════════════
+import { DEFAULT_YIELD_SECONDS, viewOf } from './background.js';
+const error = (message) => JSON.stringify({ error: message });
+const missing = (id) => error(`后台任务 "${String(id)}" 不存在`);
+/** 任务连同结束时工具的结果；调用方能看图时带上结果里的图 */
+function withResults(fields, tasks, ctx) {
+    const images = ctx.acceptsImages ? tasks.flatMap(task => task.result?.images ?? []) : [];
+    return { content: JSON.stringify(fields), ...(images.length > 0 ? { images } : {}) };
+}
+const resultOf = (task) => (task.result ? { result: task.result.content } : {});
+function tool(name, description, properties, required, handler) {
+    return {
+        definition: {
+            type: 'function',
+            function: {
+                name,
+                description,
+                parameters: { type: 'object', properties, required, additionalProperties: false },
+            },
+        },
+        handler,
+    };
+}
+export function backgroundTaskTools(tasks) {
+    const { maxWaitSeconds } = tasks.limits;
+    const inSession = (ctx) => tasks.list({ sessionId: ctx.sessionId });
+    const find = (ctx, id) => inSession(ctx).find(task => task.id === id);
+    const taskId = { type: 'string', description: '任务 id（转到后台时回给你的 taskId）' };
+    return [
+        tool('background_list', '列出本会话里的后台任务（转到后台的工具调用）：任务 id、工具、状态、开始与结束时间、输出的最后一行与最后输出时间，' +
+            '失败或中断的带原因，命令带退出码。', {}, [], async (_args, ctx) => JSON.stringify({ tasks: inSession(ctx).map(viewOf) })),
+        tool('background_output', '取一个后台任务的输出（只保留最近 64 KiB）。返回的 end 是至今的输出总字数，下次带作 after 只取新增的部分；' +
+            '早于保留范围的取不到时 truncated 为 true。结束的任务一并给出工具的结果。', { taskId, after: { type: 'integer', description: '只取这个位置之后的输出（上次返回的 end）' } }, ['taskId'], async (args, ctx) => {
+            const { after } = args;
+            if (after !== undefined && !(Number.isInteger(after) && after >= 0)) {
+                return error('after 要是不小于 0 的整数');
+            }
+            const task = find(ctx, args.taskId);
+            const output = task && tasks.output(task.id, after);
+            if (!task || !output)
+                return missing(args.taskId);
+            return withResults({ ...viewOf(task), output: output.text, end: output.end, truncated: output.truncated, ...resultOf(task) }, [task], ctx);
+        }),
+        tool('background_wait', `等列出的后台任务都结束，最多等 waitSeconds 秒（默认 ${DEFAULT_YIELD_SECONDS}，最多 ${maxWaitSeconds}），这一轮被中止时不再等。` +
+            '返回各任务的状态与最后输出时间，结束的带工具的结果。在对话里转到后台的任务结束时会通知你，不必一直等。', {
+            taskIds: { type: 'array', items: { type: 'string' }, description: '要等的任务 id' },
+            waitSeconds: {
+                type: 'number',
+                description: `最多等多少秒（默认 ${DEFAULT_YIELD_SECONDS}，最多 ${maxWaitSeconds}）`,
+            },
+        }, ['taskIds'], async (args, ctx) => {
+            const { taskIds, waitSeconds = DEFAULT_YIELD_SECONDS } = args;
+            if (!Array.isArray(taskIds) || taskIds.length === 0)
+                return error('taskIds 要是非空的任务 id 列表');
+            if (!(typeof waitSeconds === 'number' && Number.isFinite(waitSeconds) && waitSeconds >= 0)) {
+                return error('waitSeconds 要是不小于 0 的秒数');
+            }
+            const unknown = taskIds.filter(id => !find(ctx, id));
+            if (unknown.length > 0)
+                return missing(unknown.join('、'));
+            await tasks.wait(taskIds, Math.min(waitSeconds, maxWaitSeconds) * 1000, ctx.signal);
+            const settled = taskIds.flatMap(id => find(ctx, id) ?? []);
+            return withResults({ tasks: settled.map(task => ({ ...viewOf(task), ...resultOf(task) })) }, settled, ctx);
+        }),
+        tool('background_stop', '停掉一个后台任务，等它停下后如实回报（最多等 3 秒）。被停掉的任务不再通知你。', { taskId }, ['taskId'], async (args, ctx) => {
+            const task = find(ctx, args.taskId);
+            if (!task)
+                return missing(args.taskId);
+            if (task.status !== 'running')
+                return JSON.stringify({ ...viewOf(task), message: '任务已结束' });
+            const after = await tasks.stop(task.id);
+            if (!after)
+                return missing(args.taskId);
+            return JSON.stringify({
+                ...viewOf(after),
+                message: after.status === 'running' ? '已发出停止，3 秒内还没停下；它停下后记为已停止，不会通知你' : '已停止',
+            });
+        }),
+    ];
+}
+//# sourceMappingURL=background-tools.js.map

package/dist/background-tools.js.map

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

package/dist/background.d.ts

@@ -0,0 +1,189 @@
+import { type OwnStorage } from '@aalis/api-storage';
+import { type BackgroundTask, type BackgroundTaskOutput, type BackgroundTaskService, type ToolCallContext, type ToolDisplay, type ToolExecutionResult } from '@aalis/api-tools';
+import type { Events, Logger } from '@aalis/core';
+/** 让出时限的缺省（秒），工具可以声明自己的 */
+export declare const DEFAULT_YIELD_SECONDS = 30;
+interface BackgroundLimits {
+    /** 前台最多等多少秒：模型给的 waitSeconds 与工具的让出时限都不超过它 */
+    maxWaitSeconds: number;
+    /** 同一会话里对话回合中同时在跑的可转后台调用数，前台与后台一起数 */
+    maxPerSession: number;
+}
+/** 两项上限的缺省，插件配置的默认值取这里 */
+export declare const DEFAULT_LIMITS: BackgroundLimits;
+/** 授权身份（同 ToolCallContext.actor） */
+interface Identity {
+    platform: string;
+    userId: string;
+}
+/** 对话回合里的调用：有 turnId 与 callId，转到后台后有可以通知的对话 */
+export declare function inTurn(ctx: ToolCallContext): ctx is ToolCallContext & {
+    turnId: string;
+    callId: string;
+};
+/** 给模型看的任务：时刻写成 ISO 字符串，不带参数与结果 */
+export declare function viewOf(task: BackgroundTask): Record<string, unknown>;
+/** 一次调用的输出缓冲：只留末尾 OUTPUT_LIMIT 字，记至今的总字数、最后一行与最后输出的时刻 */
+declare class OutputTail {
+    /** 输出的末尾：超出两倍上限才整段收回，免得每次写都复制整块缓冲 */
+    private kept;
+    /** 还没收尾的那一行（末尾 LINE_SCAN 字） */
+    private partial;
+    /** 至今的输出总字数 */
+    end: number;
+    lastLine?: string;
+    lastAt?: number;
+    get text(): string;
+    append(chunk: string, at: number): void;
+    since(after?: number): BackgroundTaskOutput;
+}
+/** 可转后台的调用怎么等：前台最多等多少秒（已按上限收住），是否立即转后台 */
+export interface Plan {
+    waitSeconds: number;
+    immediate: boolean;
+}
+/** 一次可转后台的调用：从占到位置到落定。转后台之后带上登记的任务 */
+interface Call {
+    readonly sessionId: string;
+    /** 对话回合里的才占名额：不在回合里的不会转后台 */
+    readonly inTurn: boolean;
+    /** 工具的登记项：撤回登记时按它找到在跑的调用 */
+    readonly owner: object;
+    readonly plan: Plan;
+    readonly controller: AbortController;
+    readonly output: OutputTail;
+    record?: TaskRecord;
+    /** 被停止（stop）：落定时记为 stopped，不通知 */
+    stopRequested?: boolean;
+}
+/**
+ * 结束通知送到哪个平台、以谁的身份运行、调用者是谁、回复时引用哪条消息：起它那次调用上下文的快照，会话取任务的。
+ * 只在本次运行里有，不落盘：读回的任务不通知
+ */
+interface NoticeTarget {
+    platform: string;
+    /** 起它的那次调用的授权身份：结束通知开的那一轮按它的身份运行 */
+    actor: Identity;
+    callerUserId?: string;
+    replyTo?: string;
+}
+interface TaskRecord {
+    task: BackgroundTask;
+    output: OutputTail;
+    /** 没有的不通知：由结束通知开的回合里转后台的，链只延续一层 */
+    notice?: NoticeTarget;
+    /** 在跑的才有 */
+    call?: Call;
+    /** 落定（结束或删除）时兑现 */
+    ended: Promise<void>;
+    markEnded: () => void;
+}
+/** 执行器跑一次可转后台的调用要的东西 */
+interface RunSpec {
+    /** 工具名，即任务的显示名 */
+    tool: string;
+    /** 模型给的参数（含执行器取出的两项），记进任务的 call */
+    args: Record<string, unknown>;
+    ctx: ToolCallContext;
+    /** 结局按它取退出码 */
+    display?: ToolDisplay;
+    /** 带上这次调用的中止信号与输出口跑工具；不拒绝 */
+    invoke(ctx: ToolCallContext): Promise<ToolExecutionResult>;
+}
+interface BackgroundTasksDeps {
+    logger: Logger;
+    /** 发 tool:output、background:changed 与结束通知 */
+    events: Pick<Events, 'emit'>;
+    limits: BackgroundLimits;
+}
+/**
+ * 后台任务登记与可转后台调用的运行。执行器（ToolRegistry）经它占位置、跑调用、撤回；四个后台任务工具经它查、取输出、
+ * 等待与停止；插件把会话删除、停机、停用与存储接到它上面
+ */
+export declare class BackgroundTasks implements BackgroundTaskService {
+    readonly limits: BackgroundLimits;
+    private readonly logger;
+    private readonly events;
+    private readonly records;
+    /** 占着位置的可转后台调用：从过守卫之前到落定 */
+    private readonly calls;
+    /** 本次运行的标识：任务 id 带上它，与读回的旧 id 不撞号 */
+    private readonly runTag;
+    private counter;
+    /** 读回成功之后才写盘；读不出来时本次运行只记在内存里，不覆盖原文件 */
+    private storage?;
+    private writing;
+    /** 已排上、还没开始的一次写：之后的变化由它一并写入 */
+    private writeQueued;
+    /** 收到 app:stopping 之后：不再通知 */
+    private shuttingDown;
+    constructor(deps: BackgroundTasksDeps);
+    list(filter?: {
+        sessionId?: string;
+    }): BackgroundTask[];
+    output(id: string, after?: number): BackgroundTaskOutput | undefined;
+    stop(id: string): Promise<BackgroundTask | undefined>;
+    /** 等这些任务都落定，最多等 ms，中止信号到达即返回 */
+    wait(ids: string[], ms: number, signal?: AbortSignal): Promise<void>;
+    /** 不可转后台的调用的输出口：有 turnId 与 callId 时转成 tool:output */
+    outputFor(ctx: ToolCallContext): (text: string) => void;
+    /**
+     * 占一个位置。同一会话里对话回合中在跑的可转后台调用（前台与后台一起数，等审批的也算）满了时，回拒绝的结果（JSON），
+     * 列出这个会话在跑的后台任务，不执行、不过守卫。不在回合里的调用不会转后台，不占名额、不受上限挡
+     */
+    admit(ctx: ToolCallContext, owner: object, plan: Plan): Call | string;
+    /** 占了位置却没执行（守卫拒绝、回合已中止）：放回去 */
+    release(call: Call): void;
+    /**
+     * 跑一次占到位置、过了守卫的可转后台调用。让出时限从这里算起，前台时回合中止一并中止它。到时没结束或要求立即转后台：
+     * 对话回合里的调用登记成后台任务、摘掉与回合的联动，先回给模型任务 id 与已有输出的末尾；不在对话回合里的（没有 turnId 或 callId，
+     * 没有可通知的对话）中止并回报已有输出
+     */
+    run(call: Call, spec: RunSpec): Promise<ToolExecutionResult>;
+    /** 工具撤回登记（所属插件停用）：这个登记在跑的调用一并中止，后台的落成 aborted */
+    withdraw(owner: object, name: string): void;
+    /**
+     * 读回插件数据里的登记：还在跑的落成 aborted（重启时还在跑），每个会话留最近的结束的，与读回之前起的任务并存，之后状态
+     * 变了就写。文件不存在按没有记录起步；内容读不懂告警后同样起步，下次写盘时覆盖；读不出来（权限、存储不可用）告警，
+     * 本次运行只记在内存里，不覆盖它
+     */
+    restore(storage: Pick<OwnStorage, 'readFile' | 'writeFile' | 'uri'>): Promise<void>;
+    /** 会话删除：停掉它的调用与任务、删掉登记，不通知 */
+    deleteSession(sessionId: string): void;
+    /** 收到 app:stopping：此后结束的不通知 */
+    shutdown(): void;
+    /** 停用（收尾）：在跑的调用一并中止，后台的落成 aborted，等写盘落定 */
+    close(): Promise<void>;
+    /**
+     * 推给界面：有 turnId 与 callId 时转成 tool:output。sent 是这次调用此前写过的字数，推出的总量不超过 OUTPUT_LIMIT：
+     * 界面按条目累加输出，前台最多要等 maxWaitSeconds，持续大量输出的命令不能把它撑满
+     */
+    private stream;
+    /** 可转后台的调用写输出：进缓冲；在前台时转成 tool:output，转后台之后更新任务的最后一行 */
+    private write;
+    private yielded;
+    private register;
+    /**
+     * 后台任务的调用落定：按结局落成 completed、failed 或 stopped，记下结果与命令的退出码；失败的原因只取结果里的 error。
+     * 正常结束（含失败）的通知起它的会话
+     */
+    private finish;
+    private land;
+    private abortWhere;
+    private remove;
+    /** 每个会话留在跑的与最近 MAX_ENDED_PER_SESSION 条结束的 */
+    private prune;
+    private changed;
+    /**
+     * 结束通知只放宿主取得的事实：任务 id、工具名、结局与退出码、用时，正文写给模型，同样的事实另给界面。参数由模型写出
+     * （可能受过注入），输出与结果受外部内容左右，都不进通知（通知以 system 呈现且会归档）；它们由模型用 background_output 取，
+     * 以 tool 角色进上下文。只有正常结束（completed、failed）的通知
+     */
+    private notify;
+    /** 并进读回的登记：读回之前起的任务照留，id 相同的以内存为准 */
+    private adopt;
+    /** 写盘排队：整份写入，只记字段，不记起它的身份、输出与结果；已排上、还没开始的那次写会带上之后的变化 */
+    private persist;
+}
+export {};
+//# sourceMappingURL=background.d.ts.map

package/dist/background.d.ts.map

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