dsh-remote-control 1.0.0

package/dist/src/core/sleep-policy.d.ts

@@ -0,0 +1,81 @@
+/**
+ * sleep-policy — 什么时候持锁、什么时候放锁（纯逻辑，执行交给 `SleepPort`）。
+ *
+ * 为什么把策略与执行拆开：旧实现把两者写在一个 `KeepAwake` 类里（在协议包里
+ * spawn 子进程），于是"空闲自动释放"和"挂起审批时续锁"这两条没有任何测试，
+ * 而其中一条正是旧实现的**持锁泄漏**：它靠"收到对应的终结事件"来解除
+ * 60 秒心跳续锁，但那三类事件里**没有一条带 requestId**，判据永不成立，
+ * 锁一旦因审批挂起就再也不会释放（取证 docs/legacy-spec/host-plugin-runtime.md §4
+ * 与 host-plugin-cordis.md §3 表第 9b 行）。
+ *
+ * 本实现的判据全部用**插件自己生成的 requestId**，并且每条都有单测：
+ * - 有活动（文本/工具/运行中）→ `markActive`；
+ * - 有挂起的人工交互 → `hold(id)`，每 `pendingRefreshMs` 续一次锁；
+ * - 终结只认 `release(id)`（手机答了、被平台撤销、或超时）——**不会**因为
+ *   "看到一个没有 requestId 的事件"就以为它终结了；
+ * - 空闲超过 `idleReleaseMs` 且无挂起 → 放锁；`idleReleaseMs <= 0` 表示永不自动释放。
+ */
+import type { Clock, SleepPort } from '../ports/index.js';
+export interface KeepAwakeOptions {
+    /** 空闲多久后自动释放锁（毫秒）。0 或负数 = 不自动释放。 */
+    idleReleaseMs: number;
+    keepDisplay: boolean;
+    /** 锁断言绑定的宿主 pid：宿主崩了锁随之消失，不会留下永不睡机的机器。 */
+    ownerPid: number;
+    /** 有人工交互挂起时，多久续一次锁。 */
+    pendingRefreshMs: number;
+    /** 检查节拍。 */
+    tickMs: number;
+}
+export interface KeepAwakeSnapshot {
+    enabled: boolean;
+    active: boolean;
+    platform: string;
+    backend: string;
+    reason?: string;
+}
+export declare class KeepAwake {
+    private readonly port;
+    private readonly clock;
+    private options;
+    private enabled;
+    private held;
+    private lastActiveAt;
+    private lastRefreshAt;
+    private readonly holds;
+    private timer;
+    private stopped;
+    private reason;
+    constructor(port: SleepPort, clock: Clock, options?: Partial<KeepAwakeOptions>);
+    /**
+     * 开关。关掉时立刻放锁——用户明确要求过"本地空闲时机器照常睡眠"。
+     * `idleReleaseSec`（协议字段，单位秒）在这里换算；`0` 传进来表示不自动释放。
+     */
+    setEnabled(enabled: boolean, idleReleaseSec?: number): KeepAwakeSnapshot;
+    /** 任何内核活动都算一次"还活着"。 */
+    markActive(): void;
+    /** 一次人工交互挂起（审批或提问）。id 必须是插件自己生成的 requestId。 */
+    hold(id: string): void;
+    /** 一次人工交互结束了（手机答了 / 平台撤销 / 超时）。 */
+    releaseHold(id: string): void;
+    /**
+     * 判定此刻该不该持锁，并启动/维持节拍定时器。
+     * 拆成单独方法是为了能被单测直接驱动（注入假时钟，不真的等 300 秒）。
+     */
+    evaluate(): KeepAwakeSnapshot;
+    tick(): void;
+    snapshot(): KeepAwakeSnapshot;
+    /**
+     * 停机：放锁并撤掉节拍。
+     *
+     * `stopped` 这个闸门不是洁癖。审批的 `releaseHold()` 可能在 `stop()` **之后**才到达
+     * （手机端迟迟没点、平台撤销、超时结算三条路都可能），而 `releaseHold → evaluate →
+     * ensureTimer` 会再装一个 `tickMs` 自循环定时器——没有这个标记时它永远清不掉：
+     * 插件已经拆了 socket，节拍还在续锁，表现是"进程永不退出"（e2e 里那 60 秒的尾巴）
+     * 和"用户关了远程控制，caffeinate 还在拦住机器睡眠"。
+     */
+    stop(): void;
+    private acquire;
+    private stopLock;
+    private ensureTimer;
+}

package/dist/src/core/sleep-policy.js

@@ -0,0 +1,134 @@
+const DEFAULTS = {
+    idleReleaseMs: 300_000,
+    keepDisplay: false,
+    ownerPid: process.pid,
+    pendingRefreshMs: 60_000,
+    tickMs: 10_000,
+};
+export class KeepAwake {
+    port;
+    clock;
+    options;
+    enabled = false;
+    held = false;
+    lastActiveAt = 0;
+    lastRefreshAt = 0;
+    holds = new Set();
+    timer;
+    stopped = false;
+    reason;
+    constructor(port, clock, options = {}) {
+        this.port = port;
+        this.clock = clock;
+        this.options = { ...DEFAULTS, ...options };
+        this.lastActiveAt = this.clock.now();
+    }
+    /**
+     * 开关。关掉时立刻放锁——用户明确要求过"本地空闲时机器照常睡眠"。
+     * `idleReleaseSec`（协议字段，单位秒）在这里换算；`0` 传进来表示不自动释放。
+     */
+    setEnabled(enabled, idleReleaseSec) {
+        this.enabled = enabled;
+        if (typeof idleReleaseSec === 'number') {
+            this.options = { ...this.options, idleReleaseMs: idleReleaseSec * 1000 };
+        }
+        if (!enabled)
+            this.stopLock();
+        else
+            this.markActive();
+        return this.snapshot();
+    }
+    /** 任何内核活动都算一次"还活着"。 */
+    markActive() {
+        this.lastActiveAt = this.clock.now();
+        this.evaluate();
+    }
+    /** 一次人工交互挂起（审批或提问）。id 必须是插件自己生成的 requestId。 */
+    hold(id) {
+        this.holds.add(id);
+        this.lastActiveAt = this.clock.now();
+        this.evaluate();
+    }
+    /** 一次人工交互结束了（手机答了 / 平台撤销 / 超时）。 */
+    releaseHold(id) {
+        this.holds.delete(id);
+        this.evaluate();
+    }
+    /**
+     * 判定此刻该不该持锁，并启动/维持节拍定时器。
+     * 拆成单独方法是为了能被单测直接驱动（注入假时钟，不真的等 300 秒）。
+     */
+    evaluate() {
+        // 停机之后一律惰性：不持锁、不装定时器，只回一份"已经关了"的快照。
+        if (this.stopped)
+            return this.snapshot();
+        const now = this.clock.now();
+        const idleExpired = this.options.idleReleaseMs > 0 && now - this.lastActiveAt > this.options.idleReleaseMs;
+        const shouldHold = this.enabled && (this.holds.size > 0 || !idleExpired);
+        if (shouldHold && !this.held)
+            this.acquire();
+        if (!shouldHold && this.held)
+            this.stopLock();
+        if (this.enabled && this.holds.size > 0 && now - this.lastRefreshAt >= this.options.pendingRefreshMs) {
+            // 挂起期间续锁：即使空闲计时已过期，也不能因为"手机还没点"就放锁。
+            this.lastRefreshAt = now;
+            this.lastActiveAt = now;
+            if (!this.held)
+                this.acquire();
+        }
+        this.ensureTimer();
+        return this.snapshot();
+    }
+    tick() {
+        this.evaluate();
+    }
+    snapshot() {
+        return {
+            enabled: this.enabled,
+            active: this.held,
+            platform: this.port.platform(),
+            backend: this.port.backend(),
+            ...(this.reason === undefined ? {} : { reason: this.reason }),
+        };
+    }
+    /**
+     * 停机：放锁并撤掉节拍。
+     *
+     * `stopped` 这个闸门不是洁癖。审批的 `releaseHold()` 可能在 `stop()` **之后**才到达
+     * （手机端迟迟没点、平台撤销、超时结算三条路都可能），而 `releaseHold → evaluate →
+     * ensureTimer` 会再装一个 `tickMs` 自循环定时器——没有这个标记时它永远清不掉：
+     * 插件已经拆了 socket，节拍还在续锁，表现是"进程永不退出"（e2e 里那 60 秒的尾巴）
+     * 和"用户关了远程控制，caffeinate 还在拦住机器睡眠"。
+     */
+    stop() {
+        this.stopped = true;
+        this.stopLock();
+        if (this.timer !== undefined) {
+            this.clock.clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+    }
+    acquire() {
+        const started = this.port.start(this.options.ownerPid, this.options.keepDisplay);
+        this.held = started.ok;
+        this.reason = started.message;
+        this.lastRefreshAt = this.clock.now();
+    }
+    stopLock() {
+        if (!this.held)
+            return;
+        this.port.stop();
+        this.held = false;
+    }
+    ensureTimer() {
+        if (this.stopped || this.timer !== undefined)
+            return;
+        this.timer = this.clock.setTimeout(() => {
+            this.timer = undefined;
+            if (this.stopped)
+                return;
+            this.tick();
+        }, this.options.tickMs);
+    }
+}
+//# sourceMappingURL=sleep-policy.js.map

package/dist/src/core/sleep-policy.js.map

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

package/dist/src/core/window.d.ts

@@ -0,0 +1,88 @@
+/**
+ * window — 流式增量（delta）的合帧器。纯逻辑，不起定时器、不认识 cordis。
+ *
+ * 手机端的体验直接由这几个参数决定，所以它们必须是**可单测的参数**而不是散在
+ * socket 回调里的魔数。旧实现的窗口化写在 host-runtime 的事件循环里，
+ * 测试要靠假定时器凑环境，因此有几条行为从来没被真正锁住——
+ * 而其中一条（空文本的 done 帧被合并逻辑吞掉）会让手机**永远转圈**。
+ *
+ * 四条不变量：
+ *
+ * 1. **done 帧永不丢**，哪怕这一条消息一个字都没有（例如中断收尾）。
+ *    判据是"文本为空**且**没有 done"才丢，写成 `!text && !done`。
+ * 2. **窗口计时器只在首字到达时装填，后续字符不续期**。否则一条持续输出的长回答
+ *    会把 flush 一路推迟，手机端表现为"卡住不动"。
+ * 3. **同一会话的非 delta 事件之前必须先 flush**（由调用方走 `flushSession`），
+ *    不然工具行会插到它自己的文本前面。
+ * 4. **一轮最多处理 N 个会话**，超出就从最旧的开始冲刷。会话多时这保证
+ *    单个吵闹的会话不会饿死其它会话（也顺带给出内存上界）。
+ *
+ * 另有两条是重写时补的（第一版只做"触发时机"，没做"大小"与"连续性"）：
+ * `maxCharsPerFrame` 是**出站硬上限**——一帧最多这么多字符，超了就切多帧；
+ * `part` 在**同一条 messageId 内连续**，跨 flush、跨切帧都不归零，
+ * 否则手机上"分片是否完整"这件事没有任何可核对依据。
+ */
+import type { EvMessageDelta } from 'dsh-remote-wire';
+import type { Clock } from '../ports/index.js';
+export interface WindowOptions {
+    /** 合帧窗口（毫秒）。首字到达后到 flush 之间的最长等待。 */
+    windowMs: number;
+    /** 单次 flush 的文本上限（字符）。超过就切帧，避免单帧顶到中继帧上限。 */
+    maxCharsPerFrame: number;
+    /** 一轮 flush 最多处理的会话数。 */
+    maxSessionsPerRound: number;
+}
+export declare const DEFAULT_WINDOW_OPTIONS: WindowOptions;
+export declare class DeltaWindow {
+    private readonly emit;
+    private readonly clock;
+    private readonly options;
+    private readonly entries;
+    /**
+     * 每个会话"这条消息已经发到第几片"。必须活在 entry 之外：flush 会把 entry 删掉，
+     * 下一条同 messageId 的增量于是重建 entry、`part` 归零——一条长回答发出去全是
+     * `part:0`，手机与日志都失去了"分片是否连续"这个唯一的判据。
+     */
+    private readonly partCursor;
+    private flushed;
+    private droppedEmpty;
+    constructor(emit: (payload: EvMessageDelta) => void, clock: Clock, options?: WindowOptions);
+    /**
+     * 收到一段文本。同一 `messageId` 会继续累加；换了 messageId 就先把上一条冲掉，
+     * 保证"一条消息的所有 delta 先于下一条出现"。
+     */
+    push(sessionId: string, messageId: string, text: string, role?: 'assistant' | 'user' | 'system'): void;
+    /**
+     * 标记某条消息结束。**文本为空也必须发**——这是手机端唯一的停止转圈信号（F9）。
+     */
+    complete(sessionId: string, messageId: string, role?: 'assistant' | 'user' | 'system'): void;
+    /** 冲刷某个会话的缓冲（非 delta 事件之前、停机时、命令回执前都要调）。 */
+    flushSession(sessionId: string): void;
+    /**
+     * 一轮冲刷：先处理缓冲最久的会话，超过 `maxSessionsPerRound` 就停在这里
+     * （下一轮继续），避免吵闹的会话饿死其它会话。
+     */
+    flushRound(): void;
+    /** 停机/断线时全量冲刷。 */
+    flushAll(): void;
+    stop(): void;
+    get stats(): {
+        buffered: number;
+        flushed: number;
+        droppedEmpty: number;
+    };
+    /**
+     * 硬切成 `maxCharsPerFrame` 以内的片。
+     *
+     * 第一版只在 `entry.text.length >= cap` 时"触发一次 flush"，而 flush 是整串发出去的：
+     * 一次 push 就写进 5 万字符时，出站的那一帧仍然是 5 万字符——上限只管了时机、没管大小，
+     * 于是手机可能顶到中继的帧上限（`MAX_FRAME_BYTES`）而被整条连接断开。
+     */
+    private splitToCap;
+    /** 这条消息的下一个分片序号：跨 flush 连续，换 messageId 就归零。 */
+    private nextPart;
+    /** 缓冲区里从来没有过这条消息的收尾帧（例如一条工具调用一个字都没出就直接结束）。 */
+    private flushedDoneOnly;
+    private emitFrame;
+    private clearTimer;
+}

package/dist/src/core/window.js

@@ -0,0 +1,185 @@
+export const DEFAULT_WINDOW_OPTIONS = {
+    windowMs: 120,
+    maxCharsPerFrame: 4096,
+    maxSessionsPerRound: 32,
+};
+export class DeltaWindow {
+    emit;
+    clock;
+    options;
+    entries = new Map();
+    /**
+     * 每个会话"这条消息已经发到第几片"。必须活在 entry 之外：flush 会把 entry 删掉，
+     * 下一条同 messageId 的增量于是重建 entry、`part` 归零——一条长回答发出去全是
+     * `part:0`，手机与日志都失去了"分片是否连续"这个唯一的判据。
+     */
+    partCursor = new Map();
+    flushed = 0;
+    droppedEmpty = 0;
+    constructor(emit, clock, options = DEFAULT_WINDOW_OPTIONS) {
+        this.emit = emit;
+        this.clock = clock;
+        this.options = options;
+    }
+    /**
+     * 收到一段文本。同一 `messageId` 会继续累加；换了 messageId 就先把上一条冲掉，
+     * 保证"一条消息的所有 delta 先于下一条出现"。
+     */
+    push(sessionId, messageId, text, role) {
+        const current = this.entries.get(sessionId);
+        if (current && current.messageId !== messageId) {
+            // 上一条必须带 done 才算结束；没有 done 就补一条，否则手机端为上一条一直转圈。
+            if (!current.done)
+                this.complete(sessionId, current.messageId);
+            else
+                this.flushSession(sessionId);
+        }
+        let entry = this.entries.get(sessionId);
+        if (!entry) {
+            entry = {
+                sessionId,
+                messageId,
+                text: '',
+                role,
+                done: false,
+                part: this.nextPart(sessionId, messageId),
+                since: this.clock.now(),
+                timer: undefined,
+            };
+            this.entries.set(sessionId, entry);
+            // 只在首字装填定时器：后续字符不续期，长输出才不会把 flush 一路推后。
+            entry.timer = this.clock.setTimeout(() => this.flushSession(sessionId), this.options.windowMs);
+        }
+        entry.text += text;
+        if (role)
+            entry.role = role;
+        if (entry.text.length >= this.options.maxCharsPerFrame)
+            this.flushSession(sessionId);
+    }
+    /**
+     * 标记某条消息结束。**文本为空也必须发**——这是手机端唯一的停止转圈信号（F9）。
+     */
+    complete(sessionId, messageId, role) {
+        const entry = this.entries.get(sessionId);
+        if (!entry || entry.messageId !== messageId) {
+            // 缓冲里根本没有这条消息（例如一条工具调用没产生任何文本就直接结束）：
+            // 仍然要补一条 done-only 帧。走 flushedDoneOnly() 而不是裸 emit——
+            // 直接 emit 会让 stats.flushed 与实际出站帧数分叉（"发出去了但没人知道"是红线）。
+            this.flushedDoneOnly(sessionId, messageId, role);
+            return;
+        }
+        entry.done = true;
+        if (role)
+            entry.role = role;
+        this.flushSession(sessionId);
+    }
+    /** 冲刷某个会话的缓冲（非 delta 事件之前、停机时、命令回执前都要调）。 */
+    flushSession(sessionId) {
+        const entry = this.entries.get(sessionId);
+        if (!entry)
+            return;
+        this.clearTimer(entry);
+        this.entries.delete(sessionId);
+        if (!entry.text && !entry.done) {
+            // 唯一允许丢弃的情形：既没文本也不是收尾帧。计数暴露出去，防止"静默丢帧"无人知晓。
+            this.droppedEmpty += 1;
+            return;
+        }
+        const chunks = this.splitToCap(entry.text);
+        if (chunks.length === 0) {
+            // 收尾且一个字都没有：仍必须出站（F9），手机只认 done。
+            this.emitFrame(entry, '', true);
+        }
+        else {
+            chunks.forEach((chunk, index) => this.emitFrame(entry, chunk, index === chunks.length - 1 ? entry.done : false));
+        }
+        // 分片序号要跨 flush 接着数；这条消息已经带 done 收尾了就把游标清掉，
+        // 下一条消息从 0 开始才是它自己的序列。
+        if (entry.done)
+            this.partCursor.delete(sessionId);
+        else
+            this.partCursor.set(sessionId, { messageId: entry.messageId, next: entry.part });
+        entry.text = '';
+    }
+    /**
+     * 一轮冲刷：先处理缓冲最久的会话，超过 `maxSessionsPerRound` 就停在这里
+     * （下一轮继续），避免吵闹的会话饿死其它会话。
+     */
+    flushRound() {
+        const ordered = [...this.entries.values()].sort((a, b) => a.since - b.since);
+        for (const entry of ordered.slice(0, this.options.maxSessionsPerRound)) {
+            this.flushSession(entry.sessionId);
+        }
+    }
+    /** 停机/断线时全量冲刷。 */
+    flushAll() {
+        for (const sessionId of [...this.entries.keys()])
+            this.flushSession(sessionId);
+    }
+    stop() {
+        this.flushAll();
+        for (const entry of this.entries.values())
+            this.clearTimer(entry);
+        this.entries.clear();
+        // 游标也要清：会话没了还留着它的分片序号，等于给未来同 id 的消息一个凭空的起点。
+        this.partCursor.clear();
+    }
+    get stats() {
+        return { buffered: this.entries.size, flushed: this.flushed, droppedEmpty: this.droppedEmpty };
+    }
+    /**
+     * 硬切成 `maxCharsPerFrame` 以内的片。
+     *
+     * 第一版只在 `entry.text.length >= cap` 时"触发一次 flush"，而 flush 是整串发出去的：
+     * 一次 push 就写进 5 万字符时，出站的那一帧仍然是 5 万字符——上限只管了时机、没管大小，
+     * 于是手机可能顶到中继的帧上限（`MAX_FRAME_BYTES`）而被整条连接断开。
+     */
+    splitToCap(text) {
+        const cap = this.options.maxCharsPerFrame;
+        if (!Number.isFinite(cap) || cap <= 0 || text.length <= cap)
+            return text.length === 0 ? [] : [text];
+        const parts = [];
+        for (let at = 0; at < text.length; at += cap)
+            parts.push(text.slice(at, at + cap));
+        return parts;
+    }
+    /** 这条消息的下一个分片序号：跨 flush 连续，换 messageId 就归零。 */
+    nextPart(sessionId, messageId) {
+        const cursor = this.partCursor.get(sessionId);
+        if (!cursor)
+            return 0;
+        if (cursor.messageId !== messageId) {
+            this.partCursor.delete(sessionId);
+            return 0;
+        }
+        return cursor.next;
+    }
+    /** 缓冲区里从来没有过这条消息的收尾帧（例如一条工具调用一个字都没出就直接结束）。 */
+    flushedDoneOnly(sessionId, messageId, role) {
+        this.flushed += 1;
+        // 收尾帧同样是这条消息的一片：序号要接得上（前面已经发过 2 片时它就是第 3 片），
+        // 从来没有过缓冲时才回到 0。发完就把游标清掉，下一条消息重新计数。
+        const part = this.nextPart(sessionId, messageId);
+        this.partCursor.delete(sessionId);
+        this.emit({ t: 'ev.message_delta', sessionId, messageId, delta: '', part, done: true, ...(role ? { role } : {}) });
+    }
+    emitFrame(entry, text, done) {
+        this.flushed += 1;
+        this.emit({
+            t: 'ev.message_delta',
+            sessionId: entry.sessionId,
+            messageId: entry.messageId,
+            delta: text,
+            part: entry.part++,
+            ...(entry.role ? { role: entry.role } : {}),
+            ...(done ? { done } : {}),
+        });
+    }
+    clearTimer(entry) {
+        if (entry.timer !== undefined) {
+            this.clock.clearTimeout(entry.timer);
+            entry.timer = undefined;
+        }
+    }
+}
+//# sourceMappingURL=window.js.map

package/dist/src/core/window.js.map

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

package/dist/src/index.d.ts

@@ -0,0 +1,70 @@
+import { DEFAULT_CONFIG, type PluginConfig } from './shell/config.js';
+import type { Clock } from './ports/index.js';
+/** 我们只用到 ctx 的几个成员，所以不硬依赖 @deepseek-ai/cordis 的类型。 */
+interface LooseContext {
+    get?<T>(name: string, optional: true): T | undefined;
+    /**
+     * `inject(names, cb)` 的回调参数**不是服务实例，而是已作用域化的上下文**（`c.get(name, true)`
+     * 才拿到服务），并且这条回调 fiber 挂在我们这条 fiber 下面——我们的 fiber 一旦失败，
+     * 它会连带被 dispose，回调就永远不会触发了（真机取证见 `apply()` 末尾那条纪律）。
+     */
+    inject?(names: string[], callback: (scoped: LooseContext) => void): unknown;
+    /** 事件注册口；作用域化上下文上才有，对 waterfall 是参与式监听（见 platform/guard.ts）。 */
+    on?(name: string, listener: (...args: unknown[]) => void): unknown;
+    off?(name: string, listener: (...args: unknown[]) => void): unknown;
+    provide?(name: string, value: unknown): unknown;
+    /**
+     * cordis 唯一的卸载钩子：`ctx.effect(() => disposer)`。
+     * **没有 `onDispose` 这个东西**——ctx 是 Proxy，读不存在的属性名是"抛错"而不是
+     * 返回 undefined，`?.` 挡不住（真机取证：`cannot get property "onDispose" without inject`
+     * 让 apply 整体失败 → fiber FAILED → 六个 inject 子 fiber 全被 dispose → carrier=none）。
+     */
+    effect?(execute: () => (() => unknown) | void): unknown;
+    commands?: {
+        register?(definition: {
+            name: string;
+            description: string;
+            input?: {
+                hint?: string;
+            };
+            handler?: (invocation: {
+                commandId: string;
+                rawInput: string;
+                agent?: unknown;
+            }) => Promise<unknown> | unknown;
+        }): unknown;
+    };
+}
+export interface RuntimeHandle {
+    readonly config: PluginConfig;
+    state(): Record<string, unknown>;
+    createPairing(): {
+        qr: string;
+        token: string;
+        psk: string;
+        expiresAt: number;
+    } | null;
+    /** 某条会话的工作区目录；解析不出来是 undefined（二维码 PNG 因此退回 `~/.dsh/`）。 */
+    sessionWorkspace(sessionId: string): string | undefined;
+    stop(): void;
+}
+/**
+ * 宿主命令的返回契约（`@deepseek-ai/dsh-commands` 的 `normalizeResult`）。
+ *
+ * 只有两种 kind；别的值会在注册边界上 `throw TypeError("...unknown result kind...")`，
+ * 整条命令失败。**把它写成类型**是为了让"写错 kind"在编译期就红，而不是等用户在
+ * 真机上看到一句宿主内部错误。
+ */
+export type CommandResult = {
+    kind: 'success';
+    text?: string;
+} | {
+    kind: 'error';
+    text: string;
+};
+/** 默认时钟：真实定时器。测试注入假时钟（见 core/clock.ts）。 */
+export declare const systemClock: Clock;
+export declare function apply(ctx: LooseContext, injected?: Partial<PluginConfig>): void;
+export { DEFAULT_CONFIG };
+export { readConfig, validateConfig } from './shell/config.js';
+export type { KernelPort, Clock } from './ports/index.js';