@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.4

package/lib/types/host/services/schedule-mode/store.js

@@ -0,0 +1,309 @@
+/**
+ * schedule-mode 持久化：`$DSH_HOME/dsh-schedule-mode.json`（原子写）。
+ *
+ * 存的是「每次新建会话」策略本身，不存调度时点：时点由原生 schedule 任务持有，
+ * 本文件只在副本轮转/投递确认时更新策略。读取或结构损坏显式失败，不能把
+ * 未知策略当作空表覆盖。进程内多实例通过相同路径协调；不提供跨进程锁。
+ */
+import { mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { DEFAULT_RUN_HISTORY_LIMIT, isRecurringRule, policyKey, } from "../../../core/schedule-mode/types.js";
+/** 存储格式版本。 */
+export const SCHEDULE_MODE_FORMAT_VERSION = 1;
+/** 默认存储路径。 */
+export function defaultScheduleModeStorePath() {
+    return join(process.env['DSH_HOME'] ?? join(homedir(), '.dsh'), 'dsh-schedule-mode.json');
+}
+function asString(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function asRule(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    switch (record.kind) {
+        case 'after': {
+            const afterSeconds = asNumber(record.afterSeconds);
+            return afterSeconds === undefined ? undefined : { kind: 'after', afterSeconds };
+        }
+        case 'at': {
+            const at = asString(record.at);
+            return at === undefined ? undefined : { kind: 'at', at };
+        }
+        case 'every': {
+            const everySeconds = asNumber(record.everySeconds);
+            return everySeconds === undefined ? undefined : { kind: 'every', everySeconds };
+        }
+        case 'daily': {
+            const time = asString(record.time);
+            const timeZone = asString(record.timeZone);
+            return time === undefined || timeZone === undefined ? undefined : { kind: 'daily', time, timeZone };
+        }
+        case 'weekly': {
+            const time = asString(record.time);
+            const timeZone = asString(record.timeZone);
+            const weekdays = Array.isArray(record.weekdays)
+                ? record.weekdays.filter((day) => typeof day === 'number' && Number.isInteger(day))
+                : [];
+            return time === undefined || timeZone === undefined || weekdays.length === 0
+                ? undefined
+                : { kind: 'weekly', time, timeZone, weekdays };
+        }
+        case 'cron': {
+            const expression = asString(record.expression);
+            const timeZone = asString(record.timeZone);
+            return expression === undefined || timeZone === undefined ? undefined : { kind: 'cron', expression, timeZone };
+        }
+        default:
+            return undefined;
+    }
+}
+function asRun(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    const scheduledAt = asString(record.scheduledAt);
+    const deliveredAt = asString(record.deliveredAt);
+    const sessionId = asString(record.sessionId);
+    const taskId = asString(record.taskId);
+    if (scheduledAt === undefined || deliveredAt === undefined || sessionId === undefined || taskId === undefined)
+        return undefined;
+    return { scheduledAt, deliveredAt, sessionId, taskId };
+}
+/** Malformed journals must not silently become a retryable legacy pending arm. */
+function asTransition(value) {
+    if (value === undefined)
+        return undefined;
+    const blocked = { kind: 'stop', phase: 'recovery-required', deleteTasks: [], reason: 'invalid transition journal' };
+    if (value === null || typeof value !== 'object')
+        return blocked;
+    const record = value;
+    const kind = record.kind;
+    const phase = record.phase;
+    if (kind !== 'new' && kind !== 'original' && kind !== 'rotate' && kind !== 'stop' && kind !== 'delete' && kind !== 'complete')
+        return blocked;
+    if (phase !== 'deleting' && phase !== 'prepare' && phase !== 'creating-session' && phase !== 'creating-task' && phase !== 'created' && phase !== 'recovery-required')
+        return blocked;
+    if (!Array.isArray(record.deleteTasks))
+        return blocked;
+    const deleteTasks = [];
+    for (const raw of record.deleteTasks) {
+        if (raw === null || typeof raw !== 'object')
+            return blocked;
+        const ref = raw;
+        const sessionId = asString(ref.sessionId);
+        const id = asString(ref.id);
+        if (sessionId === undefined || id === undefined)
+            return blocked;
+        deleteTasks.push({ sessionId, id });
+    }
+    let created;
+    if (record.created !== undefined) {
+        if (record.created === null || typeof record.created !== 'object')
+            return blocked;
+        const ref = record.created;
+        const sessionId = asString(ref.sessionId);
+        const id = asString(ref.id);
+        const scheduledAt = asString(ref.scheduledAt);
+        if (sessionId === undefined || id === undefined || scheduledAt === undefined)
+            return blocked;
+        created = { sessionId, id, scheduledAt };
+    }
+    const cleanup = kind === 'stop' || kind === 'delete' || kind === 'complete';
+    if (cleanup && phase !== 'deleting' && phase !== 'prepare' && phase !== 'recovery-required')
+        return blocked;
+    if (phase === 'created' && created === undefined)
+        return blocked;
+    if ((phase === 'prepare' || phase === 'creating-session' || phase === 'creating-task') && deleteTasks.length > 0)
+        return blocked;
+    if (phase !== 'created' && phase !== 'recovery-required' && created !== undefined)
+        return blocked;
+    if (record.sessionId !== undefined && asString(record.sessionId) === undefined)
+        return blocked;
+    if (phase === 'creating-task' && asString(record.sessionId) === undefined)
+        return blocked;
+    if (phase === 'creating-session' && (kind === 'original' || cleanup))
+        return blocked;
+    if (new Set(deleteTasks.map(ref => policyKey(ref.sessionId, ref.id))).size !== deleteTasks.length)
+        return blocked;
+    return { kind, phase, deleteTasks, ...(created === undefined ? {} : { created }),
+        ...(asString(record.sessionId) === undefined ? {} : { sessionId: asString(record.sessionId) }),
+        ...(asString(record.reason) === undefined ? {} : { reason: asString(record.reason) }) };
+}
+/** 解码一条策略；结构不符返回 undefined。 */
+export function parsePolicy(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    const sourceSessionId = asString(record.sourceSessionId);
+    const logicalId = asString(record.logicalId);
+    const title = asString(record.title);
+    const prompt = asString(record.prompt);
+    const rule = asRule(record.rule);
+    const createdAt = asNumber(record.createdAt);
+    const updatedAt = asNumber(record.updatedAt);
+    if (sourceSessionId === undefined || logicalId === undefined || title === undefined || prompt === undefined
+        || rule === undefined || createdAt === undefined || updatedAt === undefined)
+        return undefined;
+    const runs = Array.isArray(record.runs) ? record.runs.map(asRun).filter((run) => run !== undefined) : [];
+    const cwd = asString(record.cwd);
+    const agentPreset = asString(record.agentPreset);
+    const armedTaskId = asString(record.armedTaskId);
+    const runSessionId = asString(record.runSessionId);
+    const nextScheduledAt = asString(record.nextScheduledAt);
+    const lastDeliveredAt = asString(record.lastDeliveredAt);
+    const endedReason = record.endedReason === 'completed' || record.endedReason === 'ended' || record.endedReason === 'deleted'
+        ? record.endedReason
+        : undefined;
+    let transition = asTransition(record.transition);
+    if (transition !== undefined && transition.phase !== 'recovery-required') {
+        const allowedSessions = new Set([sourceSessionId, runSessionId, transition.sessionId].filter((id) => id !== undefined));
+        const cleanup = transition.kind === 'stop' || transition.kind === 'delete' || transition.kind === 'complete';
+        const invalidRef = !cleanup && transition.deleteTasks.some(ref => !allowedSessions.has(ref.sessionId));
+        const invalidCreated = transition.created !== undefined && (transition.kind === 'original'
+            ? transition.created.sessionId !== sourceSessionId
+            : transition.sessionId !== undefined && transition.created.sessionId !== transition.sessionId);
+        const invalidSession = transition.kind === 'original' && transition.sessionId !== undefined && transition.sessionId !== sourceSessionId;
+        if (invalidRef || invalidCreated || invalidSession)
+            transition = { ...transition, phase: 'recovery-required', reason: 'inconsistent transition ownership' };
+    }
+    return {
+        key: asString(record.key) ?? policyKey(sourceSessionId, logicalId),
+        sourceSessionId, logicalId, title, prompt, rule, runs,
+        active: record.active === true,
+        createdAt, updatedAt,
+        ...(cwd === undefined ? {} : { cwd }),
+        ...(agentPreset === undefined ? {} : { agentPreset }),
+        ...(armedTaskId === undefined ? {} : { armedTaskId }),
+        ...(runSessionId === undefined ? {} : { runSessionId }),
+        ...(nextScheduledAt === undefined ? {} : { nextScheduledAt }),
+        ...(lastDeliveredAt === undefined ? {} : { lastDeliveredAt }),
+        ...(endedReason === undefined ? {} : { endedReason }),
+        ...(record.rotationInFlight === true ? { rotationInFlight: true } : {}),
+        ...(transition === undefined ? {} : { transition }),
+    };
+}
+/** Invalid persistence is not absence: leave the original bytes untouched. */
+export function parseStoreFile(text) {
+    const parsed = JSON.parse(text);
+    if (parsed === null || parsed.formatVersion !== SCHEDULE_MODE_FORMAT_VERSION || parsed.policies === null
+        || typeof parsed.policies !== 'object' || Array.isArray(parsed.policies))
+        throw new Error('invalid schedule-mode store');
+    const policies = Object.create(null);
+    for (const [key, raw] of Object.entries(parsed.policies)) {
+        const policy = parsePolicy(raw);
+        if (policy === undefined || key !== policy.key || policy.key !== policyKey(policy.sourceSessionId, policy.logicalId)) {
+            throw new Error('invalid schedule-mode policy');
+        }
+        policies[key] = policy;
+    }
+    return { formatVersion: SCHEDULE_MODE_FORMAT_VERSION, policies };
+}
+const pathWork = new Map();
+/** 策略存储（原子写 + 内存快照）。 */
+export class ScheduleModeStore {
+    file;
+    cache;
+    constructor(file = defaultScheduleModeStorePath()) {
+        this.file = file;
+    }
+    get identity() {
+        try {
+            return realpathSync(this.file);
+        }
+        catch {
+            try {
+                return join(realpathSync(dirname(this.file)), basename(this.file));
+            }
+            catch {
+                return resolve(this.file);
+            }
+        }
+    }
+    /** One FIFO per on-disk store in this process, not one FIFO per engine. */
+    coordinate(work, rejectBusy = false) {
+        const key = this.identity;
+        const state = pathWork.get(key) ?? { queue: Promise.resolve(), busy: 0 };
+        pathWork.set(key, state);
+        if (rejectBusy && state.busy > 0)
+            return Promise.reject(new Error('schedule-mode store operation is pending; cancellation is not confirmed'));
+        state.busy++;
+        const run = state.queue.then(() => { this.invalidate(); return work(); });
+        state.queue = run.then(() => undefined, () => undefined).finally(() => {
+            if (--state.busy === 0 && pathWork.get(key) === state)
+                pathWork.delete(key);
+        });
+        return run;
+    }
+    load() {
+        // Reads always refresh. A cached absence must never erase another instance's policy.
+        let loaded;
+        try {
+            loaded = parseStoreFile(readFileSync(this.file, 'utf8'));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            loaded = { formatVersion: SCHEDULE_MODE_FORMAT_VERSION, policies: {} };
+        }
+        this.cache = loaded;
+        return loaded;
+    }
+    persist(store) {
+        const dir = dirname(this.file);
+        mkdirSync(dir, { recursive: true });
+        const temp = `${this.file}.tmp`;
+        writeFileSync(temp, JSON.stringify(store, null, 2), 'utf8');
+        renameSync(temp, this.file);
+        // Publish the snapshot only after the atomic rename succeeds.
+        this.cache = store;
+    }
+    list() {
+        return Object.values(this.load().policies);
+    }
+    get(key) {
+        return this.load().policies[key];
+    }
+    /** 按任一原生任务 id（逻辑 id 或当前副本 id）找策略。 */
+    find(logicalId, sourceSessionId) {
+        return this.get(policyKey(sourceSessionId, logicalId));
+    }
+    findArmed(armedTaskId) {
+        return this.list().find(policy => policy.armedTaskId === armedTaskId);
+    }
+    upsert(policy) {
+        const observed = this.cache !== undefined;
+        const previous = this.cache?.policies[policy.key];
+        const store = this.load();
+        if (observed && JSON.stringify(previous) !== JSON.stringify(store.policies[policy.key])) {
+            throw new Error('schedule-mode policy changed concurrently; reload before retry');
+        }
+        const checked = parsePolicy(policy);
+        if (checked === undefined || checked.key !== policyKey(checked.sourceSessionId, checked.logicalId))
+            throw new Error('invalid schedule-mode policy');
+        this.persist({ formatVersion: store.formatVersion, policies: { ...store.policies, [checked.key]: checked } });
+        return checked;
+    }
+    remove(key) {
+        const observed = this.cache !== undefined;
+        const previous = this.cache?.policies[key];
+        const store = this.load();
+        if (observed && JSON.stringify(previous) !== JSON.stringify(store.policies[key]))
+            throw new Error('schedule-mode policy changed concurrently; reload before retry');
+        if (!(key in store.policies))
+            return false;
+        const next = { ...store.policies };
+        delete next[key];
+        this.persist({ formatVersion: store.formatVersion, policies: next });
+        return true;
+    }
+    /** 丢掉内存快照，强制下次从磁盘重读（测试/外改场景）。 */
+    invalidate() {
+        this.cache = undefined;
+    }
+}
+export { DEFAULT_RUN_HISTORY_LIMIT, isRecurringRule };

package/lib/types/host/services/schedule-mode/tools.d.ts

@@ -0,0 +1,13 @@
+/**
+ * schedule-mode agent 工具：让模型在会话内查看/切换自动化任务的运行目标。
+ *
+ * 工具是全局注册（与 ssh_* / memoir_* 同层），`session_id` 缺省取调用方会话；
+ * 因此「把这个任务改成每次新会话」在对话里就能完成，不需要打开面板。
+ */
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { ScheduleModeEngine } from './engine.ts';
+/** 创建两个 schedule_mode_* 工具定义。 */
+export declare function createScheduleModeTools(engine: ScheduleModeEngine): ToolDefinition[];
+/** 注册工具；tools 服务不可用时静默跳过（与 ssh/memoir 约定一致）。 */
+export declare function registerScheduleModeTools(ctx: import('@deepseek-ai/cordis').Context, engine: ScheduleModeEngine): () => void;
+//# sourceMappingURL=tools.d.ts.map

package/lib/types/host/services/schedule-mode/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/schedule-mode/tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAoC,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE9F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAiDrD,iCAAiC;AACjC,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,kBAAkB,GAAG,cAAc,EAAE,CAwFpF;AAED,gDAAgD;AAChD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,qBAAqB,EAAE,OAAO,EAAE,MAAM,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAI5H"}

package/lib/types/host/services/schedule-mode/tools.js

@@ -0,0 +1,132 @@
+/**
+ * schedule-mode agent 工具：让模型在会话内查看/切换自动化任务的运行目标。
+ *
+ * 工具是全局注册（与 ssh_* / memoir_* 同层），`session_id` 缺省取调用方会话；
+ * 因此「把这个任务改成每次新会话」在对话里就能完成，不需要打开面板。
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { ScheduleModeError } from "./engine.js";
+import { registerResources } from "../resources.js";
+function callerSessionId(agent) {
+    const id = agent?.session?.id;
+    return typeof id === 'string' && id !== '' ? id : undefined;
+}
+/** 模型视图：字段少而稳定，不泄漏内部副本 id。 */
+function taskView(task) {
+    return {
+        id: task.id,
+        sessionId: task.sessionId,
+        title: task.title,
+        mode: task.mode,
+        status: task.status,
+        scheduledAt: task.scheduledAt ?? '',
+        runSessionId: task.runSessionId ?? '',
+        runCount: task.runs.length,
+        recovery: task.recovery === undefined ? '' : `${task.recovery.phase}: ${task.recovery.reason ?? 'transition pending'}`,
+    };
+}
+const ERROR_CODES = ['unknown-task', 'task-ended', 'invalid-request', 'recovery-required', 'schedule-unavailable'];
+function errorView(error) {
+    if (error instanceof ScheduleModeError)
+        return { code: error.code, message: error.message };
+    return { code: 'schedule-unavailable', message: error instanceof Error ? error.message : String(error) };
+}
+/** 创建两个 schedule_mode_* 工具定义。 */
+export function createScheduleModeTools(engine) {
+    return [
+        defineTool({
+            name: 'schedule_mode_list',
+            description: 'List automation tasks with their run target: "original" keeps delivering into the conversation that created the task, '
+                + '"new" starts a fresh session for every run. Use this to tell the user where each task will run — this run target has no settings page. '
+                + 'Omit session_id to list every task; pass it to filter one conversation.',
+            parameters: {
+                session_id: { type: 'string', description: 'Only list tasks created in this session (the original conversation).' },
+            },
+            output: {
+                schema: {
+                    type: 'object', additionalProperties: false, properties: {
+                        tasks: { type: 'array', items: { type: 'object', additionalProperties: false, properties: {
+                                    id: { type: 'string', required: true }, sessionId: { type: 'string', required: true },
+                                    title: { type: 'string', required: true }, mode: { type: 'string', required: true, enum: ['original', 'new'] },
+                                    status: { type: 'string', required: true, enum: ['active', 'inactive', 'ended'] },
+                                    scheduledAt: { type: 'string', required: true }, runSessionId: { type: 'string', required: true },
+                                    runCount: { type: 'integer', required: true },
+                                    recovery: { type: 'string', required: true },
+                                } } },
+                        error: { type: 'string' },
+                    },
+                },
+                render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+            },
+            async execute(args) {
+                const listed = await engine.list();
+                if (!listed.available)
+                    return { tasks: [], error: 'the native schedule service is unavailable in this profile' };
+                const tasks = args.session_id === undefined || args.session_id === ''
+                    ? listed.tasks
+                    : listed.tasks.filter(task => task.sessionId === args.session_id || task.runSessionId === args.session_id);
+                return { tasks: tasks.map(taskView) };
+            },
+            presentCall(args) {
+                return { card: 'generic', title: 'List automation task run targets', kind: 'read', rawInput: args };
+            },
+        }),
+        defineTool({
+            name: 'schedule_mode_set',
+            description: 'Set where an automation task delivers, chosen when the task is created. There is no settings page for this: when the user creates a reminder and says it should run in a new conversation each time ("每次新对话/新会话", "new chat every run"), call schedule_create first and then call this with mode="new". '
+                + 'mode="new" gives every run its own fresh session and keeps the original conversation clean; mode="original" (the native default) delivers into the conversation that created the task. '
+                + 'Pass the id returned by schedule_create (or from schedule_mode_list); session_id defaults to the calling session and is only needed from a run session.',
+            parameters: {
+                id: { type: 'string', required: true, description: 'Task id returned by schedule_create.' },
+                mode: { type: 'string', required: true, enum: ['original', 'new'], description: 'Run target: original conversation, or a fresh session for every run.' },
+                session_id: { type: 'string', description: 'Original conversation holding the task; defaults to the calling session.' },
+            },
+            output: {
+                schema: {
+                    type: 'object', additionalProperties: false, properties: {
+                        task: { type: 'object', additionalProperties: false, properties: {
+                                id: { type: 'string', required: true }, sessionId: { type: 'string', required: true },
+                                title: { type: 'string', required: true }, mode: { type: 'string', required: true, enum: ['original', 'new'] },
+                                status: { type: 'string', required: true, enum: ['active', 'inactive', 'ended'] },
+                                scheduledAt: { type: 'string', required: true }, runSessionId: { type: 'string', required: true },
+                                runCount: { type: 'integer', required: true },
+                                recovery: { type: 'string', required: true },
+                            } },
+                        code: { type: 'string' }, message: { type: 'string' },
+                    },
+                },
+                render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+            },
+            async execute(args, exec) {
+                const sessionId = args.session_id !== undefined && args.session_id !== ''
+                    ? args.session_id
+                    : callerSessionId(exec.agent);
+                if (sessionId === undefined) {
+                    return { code: 'invalid-request', message: 'session_id is required outside a conversation' };
+                }
+                try {
+                    const task = await engine.setMode(sessionId, args.id, args.mode);
+                    return { task: taskView(task) };
+                }
+                catch (error) {
+                    return errorView(error);
+                }
+            },
+            presentCall(args) {
+                return {
+                    card: 'generic',
+                    title: args.mode === 'new' ? 'Run each time in a new session' : 'Restore the original conversation',
+                    kind: 'other',
+                    rawInput: args,
+                };
+            },
+        }),
+    ];
+}
+/** 注册工具；tools 服务不可用时静默跳过（与 ssh/memoir 约定一致）。 */
+export function registerScheduleModeTools(ctx, engine) {
+    return registerResources(own => {
+        for (const tool of createScheduleModeTools(engine))
+            own(ctx.tools.register(tool));
+    });
+}

package/lib/types/host/services/ssh/engine.d.ts

@@ -0,0 +1,162 @@
+/**
+ * ssh host 服务域 —— 引擎层（全新实现；行为契约参考旧包）。
+ *
+ * ssh2 驱动：持久连接池（空闲回收）、非交互 exec、PTY shell、SFTP
+ * 传输、本地端口转发隧道、集群并发。机密只从 store 读取，不出引擎。
+ */
+import { Client } from 'ssh2';
+import { type Server as NetServer, type Socket } from 'node:net';
+import type { ClusterResult, ExecResult, RemoteDirEntry, TransferProgress, TunnelInfo } from '../../../core/ssh/protocol.ts';
+import type { HostStore } from './store.ts';
+/** 连接池记录。 */
+interface PoolRecord {
+    client: Client;
+    lastUsedAt: number;
+    disposed: boolean;
+    /** Reconnect after stored trust or connection configuration changes. */
+    configuration: string;
+    /** Last verified public peer key, including subsequent successful rekeys. */
+    readonly peerKey: Buffer | undefined;
+}
+/** 隧道记录（真 listener + 活 socket 跟踪 + 钉住的池连接）。 */
+interface TunnelRecord {
+    info: TunnelInfo;
+    server: NetServer;
+    alias: string;
+    sockets: Set<Socket>;
+}
+/**
+ * 默认命令超时：exec / cluster 未显式传 timeoutMs 时使用。
+ *
+ * 没有兜底值时 ssh2 的 exec 没有上限：远端命令不返回（`tail -f`、等待输入、
+ * 卡住的 NFS 挂载）就会让 agent 的调用无限等待。默认 2 分钟足以覆盖调查类命令，
+ * 长任务由调用方显式传更大的 timeoutMs。
+ */
+export declare const DEFAULT_EXEC_TIMEOUT_MS = 120000;
+/**
+ * 显式超时的上限：调用方可以要求更长，但不能把一个连接（以及一次 agent 调用）
+ * 无限期挂住——超过这个值的请求会被夹到上限而不是原样下发。
+ */
+export declare const MAX_EXEC_TIMEOUT_MS: number;
+/** cluster 并发上限：显式 maxWorkers 只在这个范围内生效，任何情况都不超过主机数。 */
+export declare const MAX_CLUSTER_WORKERS = 32;
+/**
+ * 解析 cluster 的并发数：未要求（缺省、非数、非正数）时保持历史行为——所有目标
+ * 同时开跑；显式要求时夹到 [1, min(主机数, MAX_CLUSTER_WORKERS)]。
+ * @param requested - 调用方要求的并发数。
+ * @param total - 本次目标主机数。
+ * @returns 实际并发数。
+ */
+export declare function clusterWorkerLimit(requested: number | undefined, total: number): number;
+/** 超时后等待通道自行关闭的宽限期；到期仍未关闭则断开整条连接。 */
+export declare const EXEC_TIMEOUT_GRACE_MS = 3000;
+export interface EngineOptions {
+    idleTimeoutMs?: number;
+    connectTimeoutMs?: number;
+    /**
+     * 默认命令超时毫秒。传函数则每次 exec 求值（设置热更新无需重挂插件）；
+     * 缺省、非数或非正数一律回退 DEFAULT_EXEC_TIMEOUT_MS。
+     */
+    execTimeoutMs?: number | (() => number | undefined);
+    /** Test/deployment override; default is ~/.ssh/known_hosts, read-only. */
+    knownHostsPath?: string;
+    /** 超时后等待通道关闭的宽限期毫秒（默认 EXEC_TIMEOUT_GRACE_MS）。 */
+    execTimeoutGraceMs?: number;
+}
+/** 键盘交互认证回调（终端 2FA）。 */
+export type KeyboardInteractiveHandler = (name: string, instructions: string, instructionsLang: string, prompts: Array<{
+    prompt: string;
+    echo: boolean;
+}>, finish: (responses: string[]) => void) => void;
+/** 交互 shell 会话。 */
+export interface ShellSession {
+    /** 远程输出。 */
+    onData?: (data: Buffer) => void;
+    /** 通道关闭。 */
+    onExit?: (code: number | null, error?: string) => void;
+    /** 写入输入。 */
+    send(data: string): void;
+    /** 调整 PTY 尺寸。 */
+    resize(cols: number, rows: number): void;
+    /** 关闭会话与通道。 */
+    close(): void;
+    /** 暂停输出（背压）。 */
+    pause(): void;
+    /** 恢复输出。 */
+    resume(): void;
+}
+export declare class SshEngine {
+    private readonly store;
+    readonly pool: Map<string, PoolRecord>;
+    readonly tunnels: Map<string, TunnelRecord>;
+    private nextTunnelId;
+    private disposed;
+    private readonly abort;
+    private readonly clients;
+    private readonly pending;
+    private readonly opts;
+    private readonly knownHostsPath;
+    private readonly execTimeoutSource;
+    private readonly sweepTimer;
+    constructor(store: HostStore, options?: EngineOptions);
+    /**
+     * 本次执行的超时上限：调用方显式值优先，其次配置，最后插件默认值；任何来源
+     * 都被夹到 MAX_EXEC_TIMEOUT_MS，非法值回退默认超时。
+     */
+    resolveExecTimeoutMs(timeoutMs?: number): number;
+    dispose(): void;
+    private assertActive;
+    private ownClient;
+    private configuration;
+    /** Run after every async handshake; never admit work against a stale snapshot. */
+    private validateReady;
+    private dial;
+    list(query?: string): import("./index.ts").SshHostSummary[];
+    find(alias: string): import("./index.ts").SshHostSummary | undefined;
+    /** 取连接（池内复用）。 */
+    acquire(alias: string): Promise<Client>;
+    private admitPooled;
+    private sweep;
+    /** 执行一条远程命令（未显式传 timeoutMs 时用插件默认超时）。 */
+    exec(alias: string, command: string, timeoutMs?: number): Promise<ExecResult>;
+    /**
+     * 集群并发执行。`maxWorkers` 是真实生效的上限（历史上这个参数被忽略，
+     * 每台主机各开一条连接）；未要求时保持历史行为，所有目标同时开跑。
+     */
+    cluster(options: {
+        command: string;
+        aliases?: string[];
+        environment?: string;
+        tags?: string[];
+        timeoutMs?: number;
+        maxWorkers?: number;
+    }): Promise<ClusterResult[]>;
+    /** 解析集群目标：显式 aliases，或按 environment/tags 过滤全部主机。 */
+    private resolveClusterTargets;
+    /** 打开交互 shell（PTY；独立连接，支持键盘交互 2FA 与背压）。 */
+    openShell(alias: string, size: {
+        cols: number;
+        rows: number;
+    }, onKeyboardInteractive?: KeyboardInteractiveHandler): Promise<ShellSession>;
+    /** SFTP 列出目录。 */
+    ls(alias: string, remotePath: string): Promise<RemoteDirEntry[]>;
+    /** 本地端口转发（隧道）：loopback 监听 + forwardOut 管道 + 活 socket 跟踪。 */
+    tunnel(alias: string, localPort: number, remoteHost: string, remotePort: number): Promise<TunnelInfo>;
+    /** 全部活动隧道（按 id 排序稳定）。 */
+    listTunnels(): TunnelInfo[];
+    /** 停止一条隧道（关闭 listener、活 socket 与转发管道）。 */
+    stopTunnel(id: string): boolean;
+    /** 停止某主机的全部隧道（alias 为空则全部）。 */
+    stopAllTunnels(alias?: string): number;
+    /** 上传（单文件；NDJSON 进度回调，老协议 TransferProgress 结构）。 */
+    upload(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
+        bytes: number;
+        files: number;
+    }>;
+    /** 下载远程文件到本地（fastGet；进度回调，老协议 TransferProgress 结构）。 */
+    download(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
+        bytes: number;
+    }>;
+}
+export {};
+//# sourceMappingURL=engine.d.ts.map

package/lib/types/host/services/ssh/engine.d.ts.map

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