dsh-plugin-bridge 0.2.10 → 0.3.0

package/lib/host.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Bridge 的宿主端口。
+ *
+ * 迁移核心只依赖这些语义能力；DSH HTTP、进程内 apiProxy，以及未来可能出现的
+ * dsh-std participant 都应在 adapter 中实现本接口。RPC 方法名与产品对象形状不应
+ * 再进入 migrate.ts。
+ */
+import { RpcError, type Rpc } from './rpc.ts';
+import type { ImageAttachmentRef, SessionEvent } from './types.ts';
+export interface BridgeHostDescriptor {
+    /** adapter 的稳定标识，例如 dsh-api-proxy、dsh-http-api 或 dsh-std。 */
+    id: string;
+    version?: string;
+    transport?: string;
+}
+export interface SessionRow {
+    sessionId: string;
+    running?: boolean;
+    blank?: boolean;
+    cwd?: string;
+    agentPreset?: string;
+    parentSessionId?: string;
+    projections?: {
+        values?: Record<string, unknown>;
+    };
+}
+export interface PresetRow {
+    id: string;
+    trust?: 'system' | 'user';
+    isDefault?: boolean;
+    name?: string;
+    description?: string;
+    broken?: string;
+}
+export interface ModelSelection {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+export interface SessionModels {
+    current?: Partial<ModelSelection>;
+    groups?: {
+        id: string;
+        models?: {
+            id: string;
+        }[];
+    }[];
+    [key: string]: unknown;
+}
+export type PromptContent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    mediaType: ImageAttachmentRef['mediaType'];
+    data: string;
+    name?: string;
+};
+export interface BridgeHost {
+    readonly descriptor: BridgeHostDescriptor;
+    readonly sessions: {
+        list(input?: {
+            cursor?: string;
+        }): Promise<{
+            items?: SessionRow[];
+            nextCursor?: string;
+        }>;
+        create(input: {
+            workspaceId?: string;
+            cwd?: string;
+            agentPreset?: string;
+        }): Promise<{
+            sessionId: string;
+            agentPreset?: string;
+        }>;
+        history(input: {
+            sessionId: string;
+            maxMessages?: number;
+            beforeSeq?: number;
+        }, options?: {
+            timeoutMs?: number;
+        }): Promise<{
+            events?: {
+                event: SessionEvent;
+            }[];
+            hasMore?: boolean;
+        }>;
+        models(input: {
+            sessionId: string;
+        }): Promise<SessionModels>;
+        selectModel(input: {
+            sessionId: string;
+        } & ModelSelection): Promise<unknown>;
+        prompt(input: {
+            sessionId: string;
+            mode: 'queue';
+            content: readonly PromptContent[];
+        }): Promise<unknown>;
+        cancel(input: {
+            sessionId: string;
+        }): Promise<unknown>;
+        rename(input: {
+            sessionId: string;
+            title: string;
+        }): Promise<unknown>;
+        attachment?(input: {
+            sessionId: string;
+            attachmentId: string;
+        }): Promise<{
+            attachment?: ImageAttachmentRef;
+            data?: string;
+        }>;
+    };
+    readonly workspaces: {
+        list(): Promise<{
+            items?: {
+                workspaceId: string;
+                sessionIds?: string[];
+            }[];
+        }>;
+        archiveSession(input: {
+            sessionId: string;
+        }): Promise<unknown>;
+    };
+    readonly presets: {
+        list(): Promise<{
+            presets?: PresetRow[];
+        }>;
+    };
+    readonly goals: {
+        create(input: {
+            sessionId: string;
+            objective: string;
+            maxGoalRounds: number;
+        }): Promise<{
+            ref: {
+                id: string;
+                revision: number;
+            };
+        }>;
+        pause(input: {
+            sessionId: string;
+            ref: {
+                id: string;
+                revision: number;
+            };
+        }): Promise<unknown>;
+        clear?(input: {
+            sessionId: string;
+            ref: {
+                id: string;
+                revision: number;
+            };
+        }): Promise<unknown>;
+    };
+}
+/** 0.2.x 兼容入口：现有调用者仍可传入旧的字符串 Rpc。 */
+export type BridgeHostInput = BridgeHost | Rpc;
+export declare const REQUIRED_BRIDGE_CAPABILITIES: readonly ["session.list", "session.create", "session.history", "session.models", "session.selectModel", "session.prompt", "session.cancel", "session.rename", "workspace.list", "workspace.archiveSession", "agentPreset.list", "goal.create", "goal.pause"];
+export declare const OPTIONAL_BRIDGE_CAPABILITIES: readonly ["session.attachment", "goal.clear"];
+export interface BridgeHostProbe {
+    method: string;
+    available: boolean;
+}
+/** 只检查端口形状，不执行任何宿主操作。 */
+export declare function probeBridgeHost(host: BridgeHost | undefined): BridgeHostProbe[];
+/**
+ * 把现有 DSH 字符串 RPC 包成语义端口。
+ *
+ * 这是兼容 adapter，不是迁移核心的一部分；未来的 dsh-std adapter 可以直接实现
+ * BridgeHost，而不需要复刻这些 DSH 路由名。
+ */
+export declare function createBridgeHostFromRpc(rpc: Rpc, descriptor?: BridgeHostDescriptor): BridgeHost;
+/** 将兼容输入规范化为 BridgeHost；核心入口统一调用此函数。 */
+export declare function asBridgeHost(input: BridgeHostInput): BridgeHost;
+/** 对缺失的可选能力给出与 RPC 错误一致的可分类失败。 */
+export declare function missingHostCapability(capability: string): RpcError;

package/lib/host.js

@@ -0,0 +1,102 @@
+/**
+ * Bridge 的宿主端口。
+ *
+ * 迁移核心只依赖这些语义能力；DSH HTTP、进程内 apiProxy，以及未来可能出现的
+ * dsh-std participant 都应在 adapter 中实现本接口。RPC 方法名与产品对象形状不应
+ * 再进入 migrate.ts。
+ */
+import { RpcError } from './rpc.js';
+export const REQUIRED_BRIDGE_CAPABILITIES = Object.freeze([
+    'session.list',
+    'session.create',
+    'session.history',
+    'session.models',
+    'session.selectModel',
+    'session.prompt',
+    'session.cancel',
+    'session.rename',
+    'workspace.list',
+    'workspace.archiveSession',
+    'agentPreset.list',
+    'goal.create',
+    'goal.pause',
+]);
+export const OPTIONAL_BRIDGE_CAPABILITIES = Object.freeze([
+    'session.attachment',
+    'goal.clear',
+]);
+const REQUIRED_ACCESSORS = {
+    'session.list': host => host.sessions.list,
+    'session.create': host => host.sessions.create,
+    'session.history': host => host.sessions.history,
+    'session.models': host => host.sessions.models,
+    'session.selectModel': host => host.sessions.selectModel,
+    'session.prompt': host => host.sessions.prompt,
+    'session.cancel': host => host.sessions.cancel,
+    'session.rename': host => host.sessions.rename,
+    'workspace.list': host => host.workspaces.list,
+    'workspace.archiveSession': host => host.workspaces.archiveSession,
+    'agentPreset.list': host => host.presets.list,
+    'goal.create': host => host.goals.create,
+    'goal.pause': host => host.goals.pause,
+};
+/** 只检查端口形状，不执行任何宿主操作。 */
+export function probeBridgeHost(host) {
+    return REQUIRED_BRIDGE_CAPABILITIES.map(method => {
+        let available = false;
+        try {
+            available = host !== undefined && typeof REQUIRED_ACCESSORS[method](host) === 'function';
+        }
+        catch {
+            // 外部 adapter 可能只交出部分端口；doctor 必须报告缺失，不能自己先崩。
+        }
+        return { method, available };
+    });
+}
+/**
+ * 把现有 DSH 字符串 RPC 包成语义端口。
+ *
+ * 这是兼容 adapter，不是迁移核心的一部分；未来的 dsh-std adapter 可以直接实现
+ * BridgeHost，而不需要复刻这些 DSH 路由名。
+ */
+export function createBridgeHostFromRpc(rpc, descriptor = { id: 'dsh-rpc', transport: 'rpc' }) {
+    const host = {
+        descriptor: Object.freeze({ ...descriptor }),
+        sessions: Object.freeze({
+            list: (input = {}) => rpc('session.list', input),
+            create: input => rpc('session.create', input),
+            history: (input, options) => rpc('session.history', input, options?.timeoutMs),
+            models: input => rpc('session.models', input),
+            selectModel: input => rpc('session.selectModel', input),
+            prompt: input => rpc('session.prompt', input),
+            cancel: input => rpc('session.cancel', input),
+            rename: input => rpc('session.rename', input),
+            attachment: input => rpc('session.attachment', input),
+        }),
+        workspaces: Object.freeze({
+            list: () => rpc('workspace.list', {}),
+            archiveSession: input => rpc('workspace.archiveSession', input),
+        }),
+        presets: Object.freeze({
+            list: () => rpc('agentPreset.list', {}),
+        }),
+        goals: Object.freeze({
+            create: input => rpc('goal.create', input),
+            pause: input => rpc('goal.pause', input),
+            clear: input => rpc('goal.clear', input),
+        }),
+    };
+    return Object.freeze(host);
+}
+/** 将兼容输入规范化为 BridgeHost；核心入口统一调用此函数。 */
+export function asBridgeHost(input) {
+    if (typeof input === 'function')
+        return createBridgeHostFromRpc(input);
+    if (input && typeof input === 'object' && typeof input.sessions?.list === 'function')
+        return input;
+    throw new RpcError('bridge.host', 'invalid-adapter', '宿主 adapter 没有实现 BridgeHost。');
+}
+/** 对缺失的可选能力给出与 RPC 错误一致的可分类失败。 */
+export function missingHostCapability(capability) {
+    return new RpcError('bridge.host', 'unavailable', `宿主 adapter 没有提供 ${capability}`);
+}

package/lib/index.js

@@ -13,7 +13,7 @@ import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import Schema from '@deepseek-ai/schemastery';
-import { createApiProxyRpc, probeApiProxy } from './api-rpc.js';
+import { createApiProxyHost, probeApiProxy } from './api-rpc.js';
 import { createBridgeCommand } from './command.js';
 import { SOURCE_CHAR_BUDGET, SUMMARY_CHAR_BUDGET } from './compression.js';
 export const name = 'dsh-plugin-bridge';
@@ -65,7 +65,7 @@ export function commandConfigOf(config = {}) {
 export function apply(ctx, config = {}) {
     const apiProxyOf = () => ctx.apiProxy;
     const command = createBridgeCommand({
-        rpcFor: (signal) => createApiProxyRpc(apiProxyOf(), signal),
+        hostFor: (signal) => createApiProxyHost(apiProxyOf(), signal),
         probe: () => probeApiProxy(apiProxyOf()),
         config: commandConfigOf(config),
         writeSummary: writeSummaryFile,

package/lib/migrate.d.ts

@@ -1,59 +1,36 @@
 /**
  * 迁移编排：取材 → 压缩工人 → 目标会话。
  *
- * 只依赖注入进来的 `Rpc`，不碰 process / argv / 文件系统，所以可以对着一个
- * 假的 RPC（见 test/migrate.test.mjs）跑完整条链路而不烧任何 token。
+ * 只依赖注入进来的 `BridgeHost`，不碰 process / argv / 文件系统，所以可以对着
+ * 任意宿主 adapter（见 test/migrate.test.mjs）跑完整条链路而不烧任何 token。
  * CLI（`cli.ts`）与客户端 GUI 都消费这里的函数，保证「被验证的」和
  * 「被交付的」是同一条代码路径。
  */
 import { type BridgeSource } from './compression.ts';
-import { type Rpc } from './rpc.ts';
+import { type BridgeHostInput, type ModelSelection, type PresetRow, type SessionRow } from './host.ts';
 import type { ChatMessage } from './types.ts';
+export type { ModelSelection, PresetRow, SessionRow } from './host.ts';
 export type ModelTier = 'flash' | 'current' | 'pro';
 export type InjectMode = 'goal' | 'prompt' | 'both';
 export type Lang = 'zh' | 'en' | 'auto';
-export interface SessionRow {
-    sessionId: string;
-    running?: boolean;
-    blank?: boolean;
-    cwd?: string;
-    agentPreset?: string;
-    parentSessionId?: string;
-    projections?: {
-        values?: Record<string, unknown>;
-    };
-}
-export interface PresetRow {
-    id: string;
-    trust?: 'system' | 'user';
-    isDefault?: boolean;
-    name?: string;
-    description?: string;
-    broken?: string;
-}
 export interface ModelRoute {
     provider: string;
     model: string;
     /** 为什么选中它：configured / follow-session / tier:<tier> / fallback-current。 */
     reason: string;
 }
-export interface ModelSelection {
-    provider: string;
-    model: string;
-    reasoningEffort?: string;
-}
 /**
  * 列出全部会话。
  *
  * `session.list` 的 v1 一次返回全部，`cursor` 是预留位；这里仍按 cursor 取完，
  * 免得上游哪天真的分页之后这里悄悄只看第一页。
  */
-export declare function listSessions(rpc: Rpc): Promise<SessionRow[]>;
-export declare function findSession(rpc: Rpc, sessionId: string): Promise<SessionRow | undefined>;
+export declare function listSessions(input: BridgeHostInput): Promise<SessionRow[]>;
+export declare function findSession(host: BridgeHostInput, sessionId: string): Promise<SessionRow | undefined>;
 /** 找出会话所属工作区；找不到就返回 undefined（调用方退回用 cwd 建会话）。 */
-export declare function findWorkspaceId(rpc: Rpc, sessionId: string): Promise<string | undefined>;
+export declare function findWorkspaceId(input: BridgeHostInput, sessionId: string): Promise<string | undefined>;
 /** 可作为迁移目标的 preset（去掉 broken 的）。 */
-export declare function listPresets(rpc: Rpc): Promise<PresetRow[]>;
+export declare function listPresets(input: BridgeHostInput): Promise<PresetRow[]>;
 /**
  * 选压缩工人的模型。
  *
@@ -61,38 +38,42 @@ export declare function listPresets(rpc: Rpc): Promise<PresetRow[]>;
  * 里挑。挑不到就退回源会话当前模型——档位是省钱偏好，不该成为换 provider 的人
  * 装不上的理由。
  */
-export declare function resolveWorkerModel(rpc: Rpc, sessionId: string, tier: ModelTier, override?: {
+export declare function resolveWorkerModel(input: BridgeHostInput, sessionId: string, tier: ModelTier, override?: {
     provider?: string;
     model?: string;
 }): Promise<ModelRoute>;
 /** 压缩工人用哪个 preset：优先 minimal，其次 standard，再否则 host 默认。 */
-export declare function resolveWorkerPreset(rpc: Rpc): Promise<string | undefined>;
+export declare function resolveWorkerPreset(input: BridgeHostInput): Promise<string | undefined>;
 export interface WaitOptions {
     timeoutMs?: number;
-    /** 等「开始跑」的宽限期；超过还没 running 就当它已经跑完了。 */
+    /** 等待新 `turn/start` 的宽限期；超过仍未出现就按未启动处理。 */
     startGraceMs?: number;
     pollMs?: number;
+    /** 只观察这个事件序号之后的新一轮；worker 新建后通常为 0。 */
+    afterSeq?: number;
 }
 /**
- * 等一个会话回到空闲。
+ * 等一个会话的新一轮写入 `turn/end`。
  *
- * 旧实现是「先 sleep 2s，再看 running 是不是 false」——host 排队稍慢一点，
- * 第一次轮询就会把「还没开始」误判成「已经跑完」，取到的是上一轮的回答。
- * 这里先等它真的 running 起来（有宽限期），再等它落回 false。
+ * `session.list` 是全局列表，拿它每两秒轮询一个 worker 会把会话总量放大成
+ * O(会话数 × 轮询次数)。`session.history` 则只读目标会话；用 prompt 前的事件
+ * 水位隔开旧轮次后，`turn/start` / `turn/end` 也比易过期的 running 快照更可靠。
  */
-export declare function waitIdle(rpc: Rpc, sessionId: string, options?: WaitOptions): Promise<{
+export declare function waitIdle(input: BridgeHostInput, sessionId: string, options?: WaitOptions): Promise<{
     idle: boolean;
     started: boolean;
 }>;
 /** 拉取并折叠会话历史（按需翻页）。 */
-export declare function foldedHistory(rpc: Rpc, sessionId: string, options?: {
+export declare function foldedHistory(input: BridgeHostInput, sessionId: string, options?: {
     pageMessages?: number;
     maxPages?: number;
 }): Promise<ChatMessage[]>;
 /** 会话里最后一条非空 assistant 文本。 */
-export declare function lastAssistantText(rpc: Rpc, sessionId: string): Promise<string>;
+export declare function lastAssistantText(host: BridgeHostInput, sessionId: string): Promise<string>;
 export interface PreviewOptions {
     sessionId: string;
+    /** 同一命令已经读取过的源会话行，避免重复扫描全局列表。 */
+    sourceSession?: SessionRow;
     tier?: ModelTier;
     provider?: string;
     model?: string;
@@ -122,9 +103,11 @@ export interface PreviewResult {
     sourceSession: SessionRow | undefined;
 }
 /** 生成交接摘要：取材 → 起临时工人 → 收摘要 → 归档工人。 */
-export declare function previewMigration(rpc: Rpc, options: PreviewOptions): Promise<PreviewResult>;
+export declare function previewMigration(input: BridgeHostInput, options: PreviewOptions): Promise<PreviewResult>;
 export interface MigrateOptions {
     sessionId: string;
+    /** 同一流程已经读取过的源会话行，避免重复扫描全局列表。 */
+    sourceSession?: SessionRow;
     to: string;
     summary: string;
     lang?: 'zh' | 'en';
@@ -169,7 +152,7 @@ export interface MigrateResult {
  * 摘要能被模型看见依赖 goal-round-driver 把它渲染成 `<goal_round>` 提示，
  * 或模型主动调 `get_goal`。所以默认把摘要同时放进首轮提示：任何组装下都成立。
  */
-export declare function executeMigration(rpc: Rpc, options: MigrateOptions): Promise<MigrateResult>;
+export declare function executeMigration(input: BridgeHostInput, options: MigrateOptions): Promise<MigrateResult>;
 /** 默认标题：让新会话在侧栏里一眼看得出来源。 */
 export declare function migratedTitle(sourceTitle: string | undefined, to: string): string;
 /** 从 session.list 行里尽力取出标题（projection 形状随部署而异）。 */