@my-life-buddies/buddy-runtime 0.4.2 → 0.6.0

package/dist/mlbClient.d.ts

@@ -1,2 +1,177 @@
-export * from "./platform/mlbClient.ts";
+import type { BuddyEvent, BuddyLogger, DataRequirement, DatasetAccessResult, MemoryEntry, MLBMessageToWrite, PullResponse, Widget, WidgetRecord, WidgetSummary } from "./types.ts";
+import type { ProactiveDecision, ProactiveRun, ProactiveSubscriptionRequest } from "./types.ts";
+export interface MLBClientOptions {
+    /** 网关地址，如 http://localhost:8788；末尾带不带斜杠都行 */
+    gatewayUrl: string;
+    /** 搭子令牌，放进每个请求的 Authorization: Bearer */
+    token: string;
+    log: BuddyLogger;
+}
+/** 写消息的结果：4xx 是平台明确拒绝（调用方丢弃不重发）；网络错误 / 5xx 直接 throw（调用方重发） */
+export type WriteResult = {
+    kind: "delivered";
+    timestamps: number[];
+} | {
+    kind: "rejected";
+    status: number;
+    body: string;
+};
+/** widget 类型目录里一个模块的声明 */
+export interface WidgetModuleDecl {
+    description?: string;
+    record?: {
+        properties?: Record<string, {
+            type?: string;
+            description?: string;
+        }>;
+        required?: string[];
+    };
+}
+/** GET /internal/v1/widget-types 回的一个类型 */
+export interface WidgetType {
+    id: string;
+    description?: string;
+    modules?: Record<string, WidgetModuleDecl>;
+}
+export declare const MAX_DATASETS_PER_QUERY = 8;
+export declare const MAX_DATA_ACCESS_RESPONSE_BYTES: number;
+/** 不向模型暴露服务端原文、凭据或临时媒体地址。写入失败不自动重试。 */
+export declare class PlatformRequestError extends Error {
+    readonly status?: number;
+    constructor(status?: number);
+}
+export declare class MLBClient {
+    private readonly base;
+    private readonly token;
+    private readonly log;
+    constructor(options: MLBClientOptions);
+    /**
+     * GET /internal/v1/messages?convoKey=&after=&limit=。after 为平台消息时间（毫秒），不是 seq。
+     * 网络错误与非 2xx 都 throw，交给调用方等下次通知再拉；2xx 原样回响应体：messages 里图片记录带图片内容，hasMore 说这一页之外还有没有；
+     * 平台的场合交代是流内 type 为 situation 的记录。
+     */
+    pullMessages(convoKey: string, after: number, limit?: number): Promise<PullResponse>;
+    /**
+     * GET /internal/v1/messages?convoKey=&limit=[&before=]：不带 before 取尾窗（最近 limit 条），带 before（消息时间）取更早的一页；
+     * 都按时间升序回，hasMore 说这一页最旧那条之前还有没有。重建从尾往回翻用它（readMLBMessages.ts）。网络错误与非 2xx 都 throw
+     */
+    pullTail(convoKey: string, before: number | undefined, limit?: number): Promise<PullResponse>;
+    /**
+     * POST /internal/v1/messages { convoKey, messages }。
+     * 2xx → delivered；4xx → rejected（带 status 与响应体，调用方丢弃）；网络错误 / 5xx → throw（调用方带同一幂等键重发）。
+     */
+    writeMessages(convoKey: string, messages: MLBMessageToWrite[]): Promise<WriteResult>;
+    /** POST /internal/v1/push。只管发，失败（网络错误或非 2xx）只记 warn，不 throw */
+    push(convoKey: string, event: "replying", data: {
+        on: boolean;
+        status?: string;
+    }): Promise<void>;
+    push(convoKey: string, event: "delta", data: {
+        text: string;
+    }): Promise<void>;
+    /** GET /internal/v1/widget-types → types 数组。非 2xx、网络错误、响应体解析不了都回 [] 并记 warn */
+    widgetTypes(): Promise<WidgetType[]>;
+    /** POST /internal/v1/widgets { type, title, idempotencyKey?, convoKey }：建一个小挂件，回平台给的 id；同一个 idempotencyKey 重复建回同一个 id */
+    widgetCreate(convoKey: string, input: {
+        type: string;
+        title: string;
+        idempotencyKey?: string;
+    }, signal?: AbortSignal): Promise<{
+        id: string;
+    }>;
+    /** GET /internal/v1/widgets/:widgetId?convoKey=：整个小挂件，响应体里 modules 是各模块的记录 */
+    widgetRead(convoKey: string, widgetId: string, signal?: AbortSignal): Promise<Widget>;
+    /** GET /internal/v1/widgets/:widgetId/:module?convoKey=：一个模块的记录，响应体的 records */
+    widgetReadModule(convoKey: string, widgetId: string, module: string, signal?: AbortSignal): Promise<{
+        records: WidgetRecord[];
+    }>;
+    /** GET /internal/v1/widgets?convoKey=：这场会话里的小挂件，不带记录，响应体的 widgets；会话键作废时平台回空表 */
+    widgetList(convoKey: string): Promise<WidgetSummary[]>;
+    /** PUT /internal/v1/widgets/:widgetId { title, convoKey }：改标题，id 不变 */
+    widgetRename(convoKey: string, widgetId: string, title: string): Promise<void>;
+    /** PUT /internal/v1/widgets/:widgetId/presentation { summary, imageMediaId, convoKey }：聊天流里卡片的摘要与封面图，imageMediaId 传空串去掉封面 */
+    widgetSetPresentation(convoKey: string, widgetId: string, input: {
+        summary: string;
+        imageMediaId: string;
+    }): Promise<void>;
+    /** DELETE /internal/v1/widgets/:widgetId?convoKey=：删整个小挂件连记录，删不存在的也回 ok */
+    widgetDelete(convoKey: string, widgetId: string): Promise<void>;
+    /** PUT /internal/v1/widgets/:widgetId/:module/:recordId { data, expectedRevision?, convoKey }：写一条记录，已存在就整条覆盖；带 expectedRevision 而版本对不上时平台回 409 */
+    widgetWrite(convoKey: string, widgetId: string, input: {
+        module: string;
+        recordId: string;
+        data: Record<string, unknown>;
+        expectedRevision?: number;
+    }, signal?: AbortSignal): Promise<{
+        revision?: number;
+    }>;
+    /** DELETE /internal/v1/widgets/:widgetId/:module/:recordId?convoKey=：删一条记录 */
+    widgetDeleteRecord(convoKey: string, widgetId: string, module: string, recordId: string, signal?: AbortSignal): Promise<void>;
+    /** 小挂件的写操作：响应体的 ok 不是 true 就 throw */
+    private widgetMutation;
+    /**
+     * 小挂件接口共用：没有请求体的把 convoKey 放进 query，有请求体的并进请求体。
+     * 非 2xx、网络错误、超时、响应超过 4 MiB、响应体不是 JSON 都 throw PlatformRequestError，只带 HTTP 状态码、不带平台原文；
+     * signal 触发时 throw 它的中止原因。写操作不重试。
+     */
+    private widgetCall;
+    /** GET /internal/v1/memory?convoKey= → entries（全量，按 key 字典序）。会话键作废时平台回空表 */
+    memoryList(convoKey: string, signal?: AbortSignal): Promise<MemoryEntry[]>;
+    /** PUT /internal/v1/memory/:key { convoKey, text }：覆盖写一条（后写赢） */
+    memoryWrite(convoKey: string, key: string, text: string, signal?: AbortSignal): Promise<void>;
+    /** DELETE /internal/v1/memory/:key?convoKey=：删一条，删不存在的也回 ok */
+    memoryDelete(convoKey: string, key: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * POST /internal/v1/data-access/query：按当前会话读取用户已授权的 Dataset。
+     * 私聊不传 memberId；群聊传消息前缀里的稳定 memberId。非 2xx、坏 JSON 或响应缺 datasets 都 throw。
+     */
+    queryDataAccess(convoKey: string, datasets: string[], memberId?: string, signal?: AbortSignal): Promise<DatasetAccessResult[]>;
+    /** GET /internal/v1/data-access/requirements：当前搭子声明的 Dataset；失败由调用方决定是否降级。 */
+    dataRequirements(): Promise<DataRequirement[]>;
+    claimProactiveRun(runId: string): Promise<ProactiveRun>;
+    proposeProactiveSubscription(sessionId: string, request: ProactiveSubscriptionRequest, signal?: AbortSignal): Promise<{
+        id: string;
+        status: "pending";
+    }>;
+    queryProactiveData(runId: string, capabilityToken: string, datasets: string[], signal?: AbortSignal): Promise<DatasetAccessResult[]>;
+    finishProactiveRun(runId: string, capabilityToken: string, decision: ProactiveDecision | {
+        action: "failed";
+        reasonCode: string;
+    }): Promise<void>;
+    /** GET /internal/v1/system-prompt?convoKey=：这场会话的平台 system prompt（私聊与群各一版），拼在开发者的前面。非 2xx、响应体没有 systemPrompt 字符串都 throw */
+    systemPrompt(convoKey: string): Promise<string>;
+    /** memory 接口共用：2xx 回解析后的响应体；非 2xx throw 平台错误体的 error 字段（超配额、key 不合法都在这）；网络错误、超时原样 throw */
+    private memoryCall;
+    /** 发一个请求并把响应体读完。网络错误、超时直接 throw；HTTP 状态不在这里判 */
+    private call;
+}
+export declare class EventStream {
+    private readonly includeWelcome;
+    private readonly base;
+    private readonly token;
+    private readonly log;
+    private readonly onEvent;
+    private run;
+    constructor(options: MLBClientOptions & {
+        onEvent: (event: BuddyEvent) => void;
+        includeWelcome?: boolean;
+    });
+    /** 连上 GET /internal/v1/events 并一直保持；已经在跑就不重复起。不会 throw，连不上在后台退避重连 */
+    start(): void;
+    /** 断开当前连接、取消等待中的重连，之后不再连。再调 start() 会重新起一轮 */
+    stop(): void;
+    /**
+     * 连接循环：连上就一直读，读到服务端关流或出错就按退避等一会再连。
+     * 退避只针对「连不上」：这次连上过（流打开了）的，不论后来怎么断，下次都从 1 秒重新算——
+     * 健康连接被服务端掐掉（网关重启、顶号）不该被当成连不上而越等越久。
+     */
+    private loop;
+    /** 连一次并读到流结束。流一打开就把 attempt.opened 置真；非 2xx、网络错误、被 abort 都 throw */
+    private connectOnce;
+    /**
+     * 解一帧：取 event: 与 data: 行（多行 data 用 \n 拼），其余字段和 : 开头的注释行不管。
+     * 没有 data 的帧不算事件；ping / welcome / data-access 丢掉；只把 message / delete 分发出去，且 convoKey 必须合法。
+     */
+    private handleFrame;
+}
 //# sourceMappingURL=mlbClient.d.ts.map

package/dist/mlbClient.d.ts.map

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