@ycodium-ai/plugin-api 0.2.2982 → 0.2.2984

package/dist/events.d.ts

@@ -0,0 +1,227 @@
+/**
+ * 编排事件与触发事件：`ctx.events`、`ctx.reactor`，以及宿主发的几类触发事件的读法。
+ * 类型与常量从 `index.ts` 再导出。
+ *
+ * @module @ycodium-ai/plugin-api/events
+ */
+import type { PluginDisposer } from "./index.ts";
+/**
+ * 插件看到的编排事件。字段是宿主事件信封的子集 —— 插件不 import contracts，
+ * 所以这里是结构化描述，payload 保持 unknown，由插件自己按 `type` 收窄。
+ */
+export interface PluginEvent {
+    readonly type: string;
+    readonly payload: unknown;
+    readonly sequence: number;
+    readonly eventId: string;
+    readonly aggregateKind: string;
+    readonly aggregateId: string;
+    readonly occurredAt: string;
+}
+export type PluginEventHandler = (event: PluginEvent) => void | Promise<void>;
+/**
+ * 一条触发事件是谁报的。宿主从编排事件翻出来的是 `host`；插件经 `ctx.events.emit`
+ * 报的带那个插件的 id。
+ */
+export type PluginTriggerEventSource = {
+    readonly kind: "host";
+} | {
+    readonly kind: "plugin";
+    readonly pluginId: string;
+};
+/**
+ * 触发事件使用开放的 kind，领域标识放在 data 中；宿主补充事件来源。
+ */
+export interface PluginTriggerEvent {
+    readonly eventId: string;
+    readonly kind: string;
+    readonly occurredAt: string;
+    readonly projectId: string | null;
+    readonly threadId: string | null;
+    /** 事件相关的短文本（thread 标题、审批摘要、run 结局）。 */
+    readonly summary: string;
+    /** 谁报的。用户配的触发器与界面靠它分辨真事件与某个插件的说法。 */
+    readonly source: PluginTriggerEventSource;
+    /** kind 特有的结构化字段；宿主翻出来的事件只放长期稳定的标识与有界摘要，没有就是空对象。 */
+    readonly data: Readonly<Record<string, unknown>>;
+}
+export type PluginTriggerHandler = (event: PluginTriggerEvent) => void | Promise<void>;
+/** 审批或提问被回答、撤回时宿主发的触发事件。`ctx.events.on` 的 kind。 */
+export declare const REQUEST_RESOLVED_TRIGGER_KIND = "thread.request-resolved";
+/**
+ * `thread.request-resolved` 的 `data`。`outcome`：审批放行为 `accepted`、拒绝为 `declined`、
+ * 撤回（含会话退出补的收口）为 `cancelled`。提问被回答为 `answered`；轮次结束、会话退出时没人
+ * 回答而被宿主收口（以及 provider 给了空答案）为 `cancelled`。`decision` 是 provider
+ * 原样的审批决定（accept / acceptForSession / acceptAlways / decline / cancel），提问没有。
+ * **不带应答者**：事件里没有这个事实，要分辨是不是自己答的，用自己落的状态判断。
+ */
+export interface PluginRequestResolved {
+    readonly requestId: string;
+    readonly requestKind: "approval" | "user-input";
+    readonly outcome: "accepted" | "declined" | "cancelled" | "answered";
+    readonly decision?: string;
+}
+/** 从触发事件里读出 `thread.request-resolved` 的数据；kind 不对或形状不对返回 null，不抛。 */
+export declare const readRequestResolved: (event: PluginTriggerEvent) => PluginRequestResolved | null;
+/** agent 等人回答提问时宿主发的触发事件。`ctx.events.on` 的 kind；撤卡订 `REQUEST_RESOLVED_TRIGGER_KIND`。 */
+export declare const USER_INPUT_PENDING_TRIGGER_KIND = "thread.user-input-pending";
+/**
+ * `thread.user-input-pending` 的 `data`。只有请求标识与题数：题面、选项与答题形态用
+ * `ctx.projections.listPendingUserInputs` 按 `requestId` 取回（事件里不放正文，与其它宿主
+ * 触发事件同一立场）。题数按能答的题算，与读取接口一致；没有 requestId 或题面解不出来的
+ * 请求谁也答不了，宿主不发这条事件。
+ */
+export interface PluginUserInputPending {
+    readonly requestId: string;
+    readonly questionCount: number;
+}
+/** 从触发事件里读出 `thread.user-input-pending` 的数据；kind 不对或形状不对返回 null，不抛。 */
+export declare const readUserInputPending: (event: PluginTriggerEvent) => PluginUserInputPending | null;
+/**
+ * 轮次进度节拍：一轮里「现在到哪了」的有界摘要，`ctx.events.on` 的 kind。
+ *
+ * **节拍高频，handler 自己合并、别做重活。** 所有插件共用宿主的一个串行 worker，handler
+ * 里 `await` 网络会拖住全体插件：只记下最新快照并立刻返回，要发请求就由你自己的循环去发。
+ * 宿主前沿即发、尾部约 250ms 合并，`phase: "ended"` 一定立即发。只有订阅了才会产生节拍，
+ * 它不进去重表，也不能被用户绑成触发器。
+ */
+export declare const TURN_PROGRESS_TRIGGER_KIND = "thread.turn-progress";
+export interface PluginTurnProgressSegment {
+    /** 助手消息 id。正文不在节拍里：按它调 `ctx.projections.getThreadMessage` 点读累计文本。 */
+    readonly messageId: string;
+    /** 该段是否还在流式。 */
+    readonly streaming: boolean;
+}
+export interface PluginTurnProgressTool {
+    readonly toolCallId: string;
+    /** 服务器拼好的一行标签，没有时回落到活动摘要。 */
+    readonly label: string;
+    readonly itemType: string;
+    readonly status: "running" | "completed" | "failed" | "declined" | "stopped";
+}
+/**
+ * `thread.turn-progress` 的 `data`。**不带正文**：助手文本与思考全文都不在里面。
+ * `seq` 在同一 (threadId, turnId) 内单调递增，拿它丢弃乱序与重复；`phase: "ended"` 是这一轮
+ * 的最后一拍。`turnId` 可为 null（助手消息的 turnId 本来可空）。
+ */
+export interface PluginTurnProgress {
+    readonly turnId: string | null;
+    readonly seq: number;
+    readonly phase: "running" | "ended";
+    readonly segments: ReadonlyArray<PluginTurnProgressSegment>;
+    readonly thinking: {
+        readonly active: boolean;
+        readonly chars: number;
+    };
+    /** 最近 100 条工具调用；更早的只计入 `toolCount`。 */
+    readonly tools: ReadonlyArray<PluginTurnProgressTool>;
+    /** 本轮出现过的工具调用总数，含已被挤出 `tools` 的。 */
+    readonly toolCount: number;
+}
+/** 从触发事件里读出 `thread.turn-progress` 的数据；kind 不对或形状不对返回 null，不抛。 */
+export declare const readTurnProgress: (event: PluginTriggerEvent) => PluginTurnProgress | null;
+/** `ctx.events.emit` 的那一半：宿主补 `eventId`、`source`，缺省补 `occurredAt`。 */
+export interface PluginTriggerEventInput {
+    /** 重试同一触发时保持不变；宿主补插件命名空间。 */
+    readonly idempotencyKey?: string;
+    /** 事件相关的短文本。用户把它绑到团队时，这句就是那次 run 的 goal。 */
+    readonly summary: string;
+    readonly projectId?: string | null | undefined;
+    readonly threadId?: string | null | undefined;
+    /** ISO 时间；不给就是宿主收到这条的时刻。 */
+    readonly occurredAt?: string | undefined;
+    /** kind 特有的结构化字段。只放长期稳定的标识，订阅者靠它定位这条事件说的是谁。 */
+    readonly data?: Readonly<Record<string, unknown>> | undefined;
+}
+export interface PluginEvents {
+    /** 本插件作为目标的机器级触发绑定；读取实际设置，不读取插件局部配置。 */
+    readonly listBindings: () => Promise<Readonly<Record<string, PluginTriggerBinding>>>;
+    /**
+     * 订阅一类触发事件。串行、可 drain，按 eventId 去重。
+     *
+     * 宿主只有一个串行 worker 给全体插件用：handler 要同步返回，别在里面 `await` 网络。
+     * `thread.turn-progress`（`TURN_PROGRESS_TRIGGER_KIND`）是高频节拍，handler 自己合并、
+     * 别做重活；这一类不去重，也没有用户触发器。
+     */
+    readonly on: (kind: string, handler: PluginTriggerHandler) => PluginDisposer;
+    /**
+     * 报一条触发事件，进的是宿主翻译出来的那些事件的同一条分发链：同一份去重、同一批
+     * 插件订阅者、同一套用户配的触发器。`kind` 是非空字符串，插件拥有其领域命名。
+     *
+     * **你报的事件带你的插件 id**（`event.source`），用户看得见是谁报的——所以这里没有
+     * 权限门：能报假事件的插件本来也能直接调命令。
+     *
+     * 你自己的 `on` 处理器收不到你自己报的事件，`emit` → `on` → `emit` 转不起来。
+     */
+    readonly emit: (kind: string, event: PluginTriggerEventInput) => Promise<void>;
+    /**
+     * 订阅原始编排事件类型。等价于 `ctx.reactor({ events: [type], handle })`；
+     * 形状随宿主演进，能用触发事件就别用它。
+     */
+    readonly onRaw: (type: string, handler: PluginEventHandler) => PluginDisposer;
+    /**
+     * 把你自己的一条事实写进宿主同一条事件日志。
+     *
+     * 什么时候用它:你要记住的东西跨事件、跨重启（看板、名册、信箱）。把它攒在内存里
+     * 就是已知会丢的那条路；落成事实,再用 `ctx.derivedState` 折出来。
+     *
+     * 三条硬规矩：
+     * - `name` 会被宿主强制成 `<你的插件 id>/…`。不带这个前缀当场拒绝——两个插件的
+     *   事件名撞上，谁的折叠都会吃到对方的事实。
+     * - `data` 是你自己的形状，宿主原样存、原样发回，**不校验也不解释**。形状变了
+     *   要么自己兼容旧数据，要么把 `derivedState` 的 `version` 加一从头重折。
+     * - 事实挂在哪个聚合上由你指定（project / thread / plugin）。挂错了不会报错，但
+     *   按聚合查的人找不到它。
+     *
+     * 写进去的事实之后会以 `plugin.event-appended` 出现在 `onRaw` 与 `reactor` 里，
+     * 你自己的也一样——要区分是不是自己写的，看 `payload.pluginId`。
+     * 返回提交序号,可传给派生状态 `get({ throughSequence })` 读取这次写入。
+     */
+    readonly append: (input: PluginEventAppendInput) => Promise<{
+        readonly sequence: number;
+    }>;
+}
+export interface PluginTriggerBinding {
+    readonly bindingId: string;
+    readonly enabled: boolean;
+    readonly projectId: string;
+    readonly source: {
+        readonly kind: "event";
+        readonly eventKind: string;
+    };
+    readonly target: {
+        readonly kind: "plugin";
+        readonly pluginId: string;
+        readonly command: string;
+        readonly payload: Readonly<Record<string, unknown>>;
+    };
+}
+/** `ctx.events.append` 的入参。 */
+export interface PluginEventAppendInput {
+    /** 同一操作重试时保持不变;宿主按安装条目、插件与数据目录隔离。省略则每次新建。 */
+    readonly commandId?: string;
+    /** 事实的名字。宿主会强制它以 `<你的插件 id>/` 开头。 */
+    readonly name: string;
+    /** 事实挂在哪个聚合上。 */
+    readonly aggregate: {
+        readonly kind: "project";
+        readonly id: string;
+    } | {
+        readonly kind: "thread";
+        readonly id: string;
+    } | {
+        readonly kind: "plugin";
+        readonly id: string;
+    };
+    /** 你自己的形状。必须是能 JSON 序列化的值。 */
+    readonly data: unknown;
+}
+export interface PluginReactor {
+    /** 用于日志归因，插件内唯一即可。 */
+    readonly name: string;
+    /** 关心的事件类型；省略表示全收。过滤在宿主侧做，不进插件进程时间。 */
+    readonly events?: readonly string[] | undefined;
+    /** 串行执行；抛错只记 warning，不断流、不影响别的插件。 */
+    readonly handle: PluginEventHandler;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

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

package/dist/events.js

@@ -0,0 +1,103 @@
+/** 审批或提问被回答、撤回时宿主发的触发事件。`ctx.events.on` 的 kind。 */
+export const REQUEST_RESOLVED_TRIGGER_KIND = "thread.request-resolved";
+/** 从触发事件里读出 `thread.request-resolved` 的数据；kind 不对或形状不对返回 null，不抛。 */
+export const readRequestResolved = (event) => {
+    if (event.kind !== REQUEST_RESOLVED_TRIGGER_KIND)
+        return null;
+    const { requestId, requestKind, outcome, decision } = event.data;
+    if (typeof requestId !== "string" || requestId.length === 0)
+        return null;
+    if (requestKind !== "approval" && requestKind !== "user-input")
+        return null;
+    if (outcome !== "accepted" &&
+        outcome !== "declined" &&
+        outcome !== "cancelled" &&
+        outcome !== "answered") {
+        return null;
+    }
+    return typeof decision === "string"
+        ? { requestId, requestKind, outcome, decision }
+        : { requestId, requestKind, outcome };
+};
+/** agent 等人回答提问时宿主发的触发事件。`ctx.events.on` 的 kind；撤卡订 `REQUEST_RESOLVED_TRIGGER_KIND`。 */
+export const USER_INPUT_PENDING_TRIGGER_KIND = "thread.user-input-pending";
+/** 从触发事件里读出 `thread.user-input-pending` 的数据；kind 不对或形状不对返回 null，不抛。 */
+export const readUserInputPending = (event) => {
+    if (event.kind !== USER_INPUT_PENDING_TRIGGER_KIND)
+        return null;
+    const { requestId, questionCount } = event.data;
+    if (typeof requestId !== "string" || requestId.length === 0)
+        return null;
+    if (typeof questionCount !== "number" || !Number.isInteger(questionCount) || questionCount < 1) {
+        return null;
+    }
+    return { requestId, questionCount };
+};
+/**
+ * 轮次进度节拍：一轮里「现在到哪了」的有界摘要，`ctx.events.on` 的 kind。
+ *
+ * **节拍高频，handler 自己合并、别做重活。** 所有插件共用宿主的一个串行 worker，handler
+ * 里 `await` 网络会拖住全体插件：只记下最新快照并立刻返回，要发请求就由你自己的循环去发。
+ * 宿主前沿即发、尾部约 250ms 合并，`phase: "ended"` 一定立即发。只有订阅了才会产生节拍，
+ * 它不进去重表，也不能被用户绑成触发器。
+ */
+export const TURN_PROGRESS_TRIGGER_KIND = "thread.turn-progress";
+const TOOL_STATUSES = new Set(["running", "completed", "failed", "declined", "stopped"]);
+const isRecord = (value) => typeof value === "object" && value !== null;
+/** 从触发事件里读出 `thread.turn-progress` 的数据；kind 不对或形状不对返回 null，不抛。 */
+export const readTurnProgress = (event) => {
+    if (event.kind !== TURN_PROGRESS_TRIGGER_KIND)
+        return null;
+    const { turnId, seq, phase, segments, thinking, tools, toolCount } = event.data;
+    if (turnId !== null && typeof turnId !== "string")
+        return null;
+    if (typeof seq !== "number" || !Number.isFinite(seq))
+        return null;
+    if (phase !== "running" && phase !== "ended")
+        return null;
+    if (typeof toolCount !== "number" || !Number.isFinite(toolCount))
+        return null;
+    if (!isRecord(thinking) || typeof thinking.active !== "boolean")
+        return null;
+    if (typeof thinking.chars !== "number")
+        return null;
+    if (!Array.isArray(segments) || !Array.isArray(tools))
+        return null;
+    const readSegments = [];
+    for (const segment of segments) {
+        if (!isRecord(segment))
+            return null;
+        if (typeof segment.messageId !== "string" || typeof segment.streaming !== "boolean") {
+            return null;
+        }
+        readSegments.push({ messageId: segment.messageId, streaming: segment.streaming });
+    }
+    const readTools = [];
+    for (const tool of tools) {
+        if (!isRecord(tool))
+            return null;
+        const { toolCallId, label, itemType, status } = tool;
+        if (typeof toolCallId !== "string" || typeof label !== "string")
+            return null;
+        if (typeof itemType !== "string" || typeof status !== "string")
+            return null;
+        if (!TOOL_STATUSES.has(status))
+            return null;
+        readTools.push({
+            toolCallId,
+            label,
+            itemType,
+            status: status,
+        });
+    }
+    return {
+        turnId,
+        seq,
+        phase,
+        segments: readSegments,
+        thinking: { active: thinking.active, chars: thinking.chars },
+        tools: readTools,
+        toolCount,
+    };
+};
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

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