@deepseek-harness-tui/dsh-tui 0.10.2 → 0.11.0

package/lib/types/dsh-adapter/compat/shell.d.ts

@@ -0,0 +1,25 @@
+/** Foreground shell seam across the legacy run() and 0.1.7 execute() APIs. */
+export interface ShellRequest {
+    command: string;
+    workdir?: string;
+    timeoutMs: number;
+}
+export interface ShellResult {
+    stdout: {
+        text: string;
+    };
+    stderr: {
+        text: string;
+    };
+    timedOut: boolean;
+}
+export interface ForegroundShell {
+    resolve(request: ShellRequest): unknown;
+    run?(spec: unknown): Promise<ShellResult>;
+    execute?(spec: unknown): Promise<{
+        result(): Promise<ShellResult>;
+    }>;
+}
+/** Resolve through the host so workspace, timeout and sandbox policy survive. */
+export declare function runForegroundShell(shell: ForegroundShell, request: ShellRequest): Promise<ShellResult>;
+//# sourceMappingURL=shell.d.ts.map

package/lib/types/dsh-adapter/compat/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/compat/shell.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACxB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;IACxB,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAA;IACvC,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IACzC,OAAO,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;KAAE,CAAC,CAAA;CACrE;AAED,iFAAiF;AACjF,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAQ5G"}

package/lib/types/dsh-adapter/compat/shell.js

@@ -0,0 +1,11 @@
+/** Resolve through the host so workspace, timeout and sandbox policy survive. */
+export async function runForegroundShell(shell, request) {
+    const spec = shell.resolve(request);
+    if (typeof shell.execute === 'function') {
+        const execution = await shell.execute(spec);
+        return execution.result();
+    }
+    if (typeof shell.run === 'function')
+        return shell.run(spec);
+    throw new Error('dsh-tui: shell provides neither execute() nor run()');
+}

package/lib/types/dsh-adapter/contract.d.ts

@@ -1,9 +1,9 @@
 /** Primary validated upstream line (newest). */
-export declare const UPSTREAM_VALIDATED_VERSION = "0.1.5-rc.1";
+export declare const UPSTREAM_VALIDATED_VERSION = "0.1.7-rc.1";
 /**
  * Explicitly supported upstream prerelease lines, oldest first.
  *
- * 0.1.5-rc.1 = primary continuous-CI line; 0.1.5-alpha.2/alpha.1 = mapped
+ * 0.1.7-rc.1 = primary continuous-CI line; 0.1.5-rc.1/alpha.2/alpha.1 = mapped
  * compatibility lines (source-checked when the primary line moves);
  * 0.1.3-alpha.2 = compatibility line (the only 0.1.3 build on npm);
  * 0.1.2-rc.1 = previous family (full CI coverage); 0.1.2-alpha.3–alpha.5 =
@@ -15,14 +15,14 @@ export declare const UPSTREAM_VALIDATED_VERSION = "0.1.5-rc.1";
  * The peer range in package.json is deliberately wider than this list: an
  * install on an older or newer line is allowed but reports drift at boot.
  */
-export declare const UPSTREAM_VALIDATED_VERSIONS: readonly ["0.1.0-rc.6", "0.1.0-rc.7", "0.1.0-rc.8", "0.1.1-rc.1", "0.1.1-rc.2", "0.1.2-alpha.3", "0.1.2-alpha.4", "0.1.2-alpha.5", "0.1.2-rc.1", "0.1.3-alpha.2", "0.1.5-alpha.1", "0.1.5-alpha.2", "0.1.5-rc.1"];
+export declare const UPSTREAM_VALIDATED_VERSIONS: readonly ["0.1.0-rc.6", "0.1.0-rc.7", "0.1.0-rc.8", "0.1.1-rc.1", "0.1.1-rc.2", "0.1.2-alpha.3", "0.1.2-alpha.4", "0.1.2-alpha.5", "0.1.2-rc.1", "0.1.3-alpha.2", "0.1.5-alpha.1", "0.1.5-alpha.2", "0.1.5-rc.1", "0.1.7-rc.1"];
 /**
  * Framework packages version on their own lines; the contract validates
  * their MAJOR (breaking surface), not the harness prerelease number.
  */
 export declare const UPSTREAM_FRAMEWORK_MAJORS: Record<string, number>;
 /** Official packages the adapter consumes at runtime or as types. */
-export declare const UPSTREAM_BLESSED_PACKAGES: readonly ["@deepseek-ai/cordis", "@deepseek-ai/schemastery", "@deepseek-ai/dsh-invariants", "@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-agent-instructions", "@deepseek-ai/dsh-agent-presets", "@deepseek-ai/dsh-atomic-write", "@deepseek-ai/dsh-code-runtime-worker-thread", "@deepseek-ai/dsh-commands", "@deepseek-ai/dsh-cordis-host-runner", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-llm-pi-ai", "@deepseek-ai/dsh-persona", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-settings", "@deepseek-ai/dsh-skill", "@deepseek-ai/dsh-storage", "@deepseek-ai/dsh-storage-domain", "@deepseek-ai/dsh-storage-json", "@deepseek-ai/dsh-workspace", "@deepseek-ai/dsh-system-prompt", "@deepseek-ai/dsh-terminal", "@deepseek-ai/dsh-terminal-bash", "@deepseek-ai/dsh-tool-ask-user", "@deepseek-ai/dsh-tool-bash-persistent", "@deepseek-ai/dsh-tool-cordis", "@deepseek-ai/dsh-tool-subagent", "@deepseek-ai/dsh-user-approval", "@deepseek-ai/dsh-user-questions"];
+export declare const UPSTREAM_BLESSED_PACKAGES: readonly ["@deepseek-ai/cordis", "@deepseek-ai/schemastery", "@deepseek-ai/dsh-invariants", "@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-agent-instructions", "@deepseek-ai/dsh-agent-preset-registry", "@deepseek-ai/dsh-atomic-write", "@deepseek-ai/dsh-ptc-runtime-node", "@deepseek-ai/dsh-commands", "@deepseek-ai/dsh-cordis-host-runner", "@deepseek-ai/dsh-llm", "@deepseek-ai/dsh-llm-pi-ai", "@deepseek-ai/dsh-persona", "@deepseek-ai/dsh-session", "@deepseek-ai/dsh-settings", "@deepseek-ai/dsh-skill", "@deepseek-ai/dsh-storage", "@deepseek-ai/dsh-storage-domain", "@deepseek-ai/dsh-storage-json", "@deepseek-ai/dsh-workspace", "@deepseek-ai/dsh-web-app", "@deepseek-ai/dsh-system-prompt", "@deepseek-ai/dsh-terminal", "@deepseek-ai/dsh-terminal-bash", "@deepseek-ai/dsh-tool-ask-user", "@deepseek-ai/dsh-tool-bash-persistent", "@deepseek-ai/dsh-tool-cordis", "@deepseek-ai/dsh-tool-subagent", "@deepseek-ai/dsh-user-approval", "@deepseek-ai/dsh-user-questions"];
 export interface UpstreamDriftEntry {
     package: string;
     installed: string | undefined;

package/lib/types/dsh-adapter/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/contract.ts"],"names":[],"mappings":"AAkBA,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,eAAe,CAAA;AAEtD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,2BAA2B,mNAc9B,CAAA;AAEV;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAG5D,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,yBAAyB,06BA8B5B,CAAA;AAEV,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,4EAA4E;AAC5E,MAAM,MAAM,yBAAyB,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAA;AAE/D,4FAA4F;AAC5F,MAAM,MAAM,oBAAoB,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,yBAAyB,EAAE,MAAM,CAAC,CAAA;AAEvG,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAKlG;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,CAAC,EAAE,oBAAoB,EAAE,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAQxF;AAkBD,sEAAsE;AACtE,eAAO,MAAM,wBAAwB,QAA6D,CAAA;AAYlG,wBAAgB,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAqB9E;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAE9F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAKnF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,MAAM,EAAE,CAQV;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,kBAAkB,EAAE,CAuBtB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEtE,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,iBAAiB,CAAA;IACvB,sFAAsF;IACtF,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,oBAAoB,GAAG,SAAS,CAyBlC"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/contract.ts"],"names":[],"mappings":"AAkBA,gDAAgD;AAChD,eAAO,MAAM,0BAA0B,eAAe,CAAA;AAEtD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,2BAA2B,iOAe9B,CAAA;AAEV;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAG5D,CAAA;AAED,qEAAqE;AACrE,eAAO,MAAM,yBAAyB,o8BA+B5B,CAAA;AAEV,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,SAAS,EAAE,MAAM,CAAA;CAClB;AAUD,4EAA4E;AAC5E,MAAM,MAAM,yBAAyB,GAAG,OAAO,GAAG,MAAM,GAAG,IAAI,CAAA;AAE/D,4FAA4F;AAC5F,MAAM,MAAM,oBAAoB,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,yBAAyB,EAAE,MAAM,CAAC,CAAA;AAEvG,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,oBAAoB,GAAG,SAAS,CAKlG;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,CAAC,EAAE,oBAAoB,EAAE,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAQxF;AAkBD,sEAAsE;AACtE,eAAO,MAAM,wBAAwB,QAA6D,CAAA;AAYlG,wBAAgB,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAqB9E;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAE9F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAKnF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,MAAM,EAAE,CAQV;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,kBAAkB,EAAE,CAuBtB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEtE,wEAAwE;AACxE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,iBAAiB,CAAA;IACvB,sFAAsF;IACtF,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,iBAAiB,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAA+B,GAC5F,oBAAoB,GAAG,SAAS,CA0BlC"}

package/lib/types/dsh-adapter/contract.js

@@ -2,7 +2,7 @@
  * Upstream compatibility contract.
  *
  * The TUI is validated against a set of upstream prerelease lines — the
- * current primary (0.1.5-rc.1) plus older lines kept in backward
+ * current primary (0.1.7-rc.1) plus older lines kept in backward
  * compatibility across the 0.1.5, 0.1.3, 0.1.2, 0.1.1 and 0.1.0 release
  * families.
  * Every official package this adapter touches is blessed here; anything
@@ -16,11 +16,11 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 /** Primary validated upstream line (newest). */
-export const UPSTREAM_VALIDATED_VERSION = '0.1.5-rc.1';
+export const UPSTREAM_VALIDATED_VERSION = '0.1.7-rc.1';
 /**
  * Explicitly supported upstream prerelease lines, oldest first.
  *
- * 0.1.5-rc.1 = primary continuous-CI line; 0.1.5-alpha.2/alpha.1 = mapped
+ * 0.1.7-rc.1 = primary continuous-CI line; 0.1.5-rc.1/alpha.2/alpha.1 = mapped
  * compatibility lines (source-checked when the primary line moves);
  * 0.1.3-alpha.2 = compatibility line (the only 0.1.3 build on npm);
  * 0.1.2-rc.1 = previous family (full CI coverage); 0.1.2-alpha.3–alpha.5 =
@@ -46,6 +46,7 @@ export const UPSTREAM_VALIDATED_VERSIONS = [
     '0.1.5-alpha.1',
     '0.1.5-alpha.2',
     '0.1.5-rc.1',
+    '0.1.7-rc.1',
 ];
 /**
  * Framework packages version on their own lines; the contract validates
@@ -62,9 +63,9 @@ export const UPSTREAM_BLESSED_PACKAGES = [
     '@deepseek-ai/dsh-invariants',
     '@deepseek-ai/dsh-agent',
     '@deepseek-ai/dsh-agent-instructions',
-    '@deepseek-ai/dsh-agent-presets',
+    '@deepseek-ai/dsh-agent-preset-registry',
     '@deepseek-ai/dsh-atomic-write',
-    '@deepseek-ai/dsh-code-runtime-worker-thread',
+    '@deepseek-ai/dsh-ptc-runtime-node',
     '@deepseek-ai/dsh-commands',
     '@deepseek-ai/dsh-cordis-host-runner',
     '@deepseek-ai/dsh-llm',
@@ -77,6 +78,7 @@ export const UPSTREAM_BLESSED_PACKAGES = [
     '@deepseek-ai/dsh-storage-domain',
     '@deepseek-ai/dsh-storage-json',
     '@deepseek-ai/dsh-workspace',
+    '@deepseek-ai/dsh-web-app',
     '@deepseek-ai/dsh-system-prompt',
     '@deepseek-ai/dsh-terminal',
     '@deepseek-ai/dsh-terminal-bash',
@@ -87,6 +89,13 @@ export const UPSTREAM_BLESSED_PACKAGES = [
     '@deepseek-ai/dsh-user-approval',
     '@deepseek-ai/dsh-user-questions',
 ];
+// These capabilities are loaded dynamically and did not exist on every
+// supported host line. Their absence is valid at runtime, not in the CI tree.
+const OPTIONAL_RUNTIME_PACKAGES = new Set([
+    '@deepseek-ai/dsh-agent-preset-registry',
+    '@deepseek-ai/dsh-ptc-runtime-node',
+    '@deepseek-ai/dsh-web-app',
+]);
 /** Parse an upstream prerelease version; undefined when unparseable. */
 export function parseUpstreamVersion(version) {
     const match = /^(\d+)\.(\d+)\.(\d+)-(alpha|beta|rc)\.(\d+)$/u.exec(version ?? '');
@@ -237,7 +246,7 @@ export function upstreamDriftSummary(installedVersions = installedUpstreamVersio
     const installedLines = installedUpstreamLines(installedVersions);
     if (installedLines.length > 1)
         return { kind: 'mixed', versions: installedLines };
-    const drift = upstreamDrift(installedVersions);
+    const drift = upstreamDrift(installedVersions).filter(entry => entry.installed !== undefined || !OPTIONAL_RUNTIME_PACKAGES.has(entry.package));
     if (drift.length === 0)
         return undefined;
     const harness = drift.filter(entry => UPSTREAM_FRAMEWORK_MAJORS[entry.package] === undefined);

package/lib/types/dsh-adapter/ide-channel.d.ts

@@ -0,0 +1,224 @@
+/**
+ * IDE selection channel (PR-B groundwork): the dsh-tui side of a loopback
+ * WebSocket link with a companion IDE extension (dsh-tui-vscode). The
+ * extension broadcasts caret-selection changes; the TUI consumes them to
+ * attach `<attached-file …>` blocks at submit time (ADR-001).
+ *
+ * Discovery has two paths (DESIGN D4):
+ *   1. env direct — DSH_TUI_IDE_PORT + DSH_TUI_IDE_TOKEN, injected when the
+ *      extension spawns this TUI itself;
+ *   2. lock scan — `~/.dsh-tui/ide/*.lock` files written by the extension
+ *      ({port, token, workspaceFolders, pid}); locks whose workspaceFolders
+ *      match the session cwd connect first.
+ *
+ * Both paths fail → silent degradation (AC-4): no error, no retry,
+ * connected=false, every other TUI feature unaffected. The client is Node's
+ * native WebSocket global (engines ^22.19 || >=24, D5) — zero dependencies
+ * and no auto-reconnect (degrade-on-drop is the design).
+ *
+ * Protocol constants here are a cross-repo contract (the extension's server
+ * side implements the mirror); changing them requires updating both ends
+ * plus ADR-001 (DESIGN §9.5). Protocol version 2:
+ * - Handshake: the client's first frame is
+ *   `{"method":"ide/hello","params":{"token","protocolVersion"}}`; the
+ *   server validates the token and answers
+ *   `{"method":"ide/hello_ack","params":{"protocolVersion",
+ *   "workspaceFolders"}}`. The client is connected only after a valid ack —
+ *   a wrong token closes the socket and the client tries its next
+ *   candidate.
+ * - Notifications: `{"method":"selection_changed","params":{path,
+ *   startLine, endLine, isEmpty, text, documentVersion}}` — coordinates are
+ *   0-based, and `text` carries the editor buffer's own selection text
+ *   (unsaved edits included); the TUI attaches that text verbatim and only
+ *   falls back to reading the file from disk for protocol-1 pushes.
+ */
+/** Env var carrying the extension's loopback WS port (spawn-injected). */
+export declare const IDE_PORT_ENV = "DSH_TUI_IDE_PORT";
+/** Env var carrying the extension's handshake token (spawn-injected). */
+export declare const IDE_TOKEN_ENV = "DSH_TUI_IDE_TOKEN";
+/** Wire protocol this client speaks; hello_ack carries the server's value. */
+export declare const IDE_PROTOCOL_VERSION = 2;
+/** Where the extension advertises its loopback server (`~/.dsh-tui/ide`). */
+export declare function ideLockDir(dataDir?: string): string;
+/** Connection target resolved from the spawn environment. */
+export type IdeChannelConfig = {
+    port: number;
+    token: string;
+};
+/**
+ * Parse the direct-connect environment. Returns undefined when the pair is
+ * absent or malformed — port must be an integer within 1..65535 and the
+ * token non-empty — so a bad env degrades to lock discovery instead of
+ * throwing.
+ */
+export declare function envDirect(env: NodeJS.ProcessEnv): IdeChannelConfig | undefined;
+/**
+ * A parsed `*.lock` file: the extension's advertisement of its loopback
+ * server. workspaceFolders holds the absolute paths of its open workspace
+ * roots.
+ */
+export type LockEntry = {
+    port: number;
+    token: string;
+    workspaceFolders: string[];
+    pid: number;
+};
+/** Snapshot carried by a `selection_changed` notification. */
+export type SelectionSnapshot = {
+    /** Workspace-relative or absolute file path, as the extension reports it. */
+    path: string;
+    /** First selected line, 0-based. */
+    startLine: number;
+    /** Last selected line, 0-based inclusive. */
+    endLine: number;
+    /** True when the editor selection collapsed to nothing. */
+    isEmpty: boolean;
+    /**
+     * Protocol 2: the editor buffer's OWN text for the selection (unsaved
+     * edits included), exactly what the user saw when selecting. Always
+     * present from a v2 extension (the handshake gates on a v2 ack, so an
+     * older extension never gets connected); a missing/empty value only
+     * occurs on a degenerate push and falls back to reading the file from
+     * disk, which can differ from the editor for unsaved buffers.
+     */
+    text?: string;
+    /** Protocol 2: the editor document version the text came from. */
+    documentVersion?: number;
+};
+/**
+ * Validate an inbound `ide/hello_ack` frame. Returns the server's protocol
+ * version and workspace folders, or undefined for anything else — wrong
+ * method, malformed envelope, or a version this client does not speak (both
+ * ends ship together, so a mismatch is a foreign server and must not be
+ * treated as connected).
+ */
+export declare function parseHelloAck(message: unknown): {
+    protocolVersion: number;
+    workspaceFolders: string[];
+} | undefined;
+/**
+ * Normalize a path for comparison: backslashes folded to forward slashes,
+ * trailing slashes stripped, case folded when the platform's filesystem is
+ * case-insensitive (same semantics as channel.ts normalizeCwd — sessions.ts
+ * precedent). Exported so verifiers can pin the Windows behavior.
+ */
+export declare function normalizeIdePath(path: string, caseInsensitive: boolean): string;
+/**
+ * Read and parse one lock file. Returns undefined for unreadable or
+ * malformed content (broken JSON, wrong field types) — a single bad lock
+ * must never break the whole scan.
+ */
+export declare function readLockEntry(file: string): LockEntry | undefined;
+/**
+ * Scan a lock directory and return the candidates whose workspaceFolders
+ * actually CONTAIN the session cwd, most-specific root first; ties keep
+ * directory order (stable sort). Malformed and stale locks are skipped, and
+ * an unmatched lock is NOT a candidate at all — dialing another workspace's
+ * IDE would attach that project's selections here (maintainer review round 3:
+ * "unmatched trails every match" used to make start() connect to an
+ * unrelated window when nothing matched). Never throws — an unreadable
+ * directory degrades to an empty list.
+ *
+ * `pid` is part of the lock contract and reserved for future disambiguation
+ * (DESIGN R5); matching currently relies on workspaceFolders only.
+ */
+export declare function pickLockCandidates(lockDir: string, cwd: string, pid?: number): LockEntry[];
+/**
+ * Validate one inbound notification as a `selection_changed` frame. Returns
+ * undefined for anything else — wrong method, malformed envelope, missing or
+ * out-of-range coordinates (endLine >= startLine >= 0, non-empty path).
+ */
+export declare function parseSelectionChanged(message: unknown): SelectionSnapshot | undefined;
+type SelectionListener = (snapshot: SelectionSnapshot) => void;
+/**
+ * What one consumed selection contributed to a submitted message, recorded
+ * next to the user row so the transcript can render a "Selected N lines
+ * from <file>" indicator (T06). `lines` is the number of lines actually
+ * attached after clamping — the truth the model received, not the request.
+ */
+export type SelectionAttachedInfo = {
+    lines: number;
+    path: string;
+};
+/**
+ * Connection lifecycle (DESIGN §3): idle → connecting (env first, then lock
+ * candidates under one shared budget) → connected, or silently disconnected.
+ * Once connected, an error or drop degrades to disconnected — no retry.
+ * The latest non-empty selection stays available after consumption so
+ * consecutive submits can reuse it; an isEmpty notification clears it.
+ */
+export declare class IdeChannel {
+    private socket;
+    private pendingSocket;
+    private state;
+    private current;
+    /** Bumped on every connect attempt and on stop(): in-flight dials check it
+     *  in `finish` and the discovery loop checks it before every next dial, so
+     *  a stopped channel can neither be revived by a late onopen/ack nor keep
+     *  dialing further candidates (maintainer review rounds 2–3). */
+    private generation;
+    /** Env/lockDir of the last start(), reused by rebind() so a cwd change
+     *  rediscovers against the same environment it originally connected in. */
+    private startEnv;
+    private startLockDir;
+    /** Workspace folders the connected server reported in hello_ack. */
+    private ackedWorkspaceFolders;
+    private readonly listeners;
+    /** True only while the loopback link is up. */
+    get connected(): boolean;
+    /** Workspace folders the connected server acked with, or undefined while
+     *  not connected (test/introspection seam for the cwd-coverage rule). */
+    get workspaceFolders(): string[] | undefined;
+    /** Latest non-empty selection, or undefined (never consumed-clearing). */
+    get selection(): SelectionSnapshot | undefined;
+    /**
+     * Subscribe to every selection notification, including empty ones.
+     * @returns An unsubscribe handle.
+     */
+    onSelection(listener: SelectionListener): () => void;
+    /**
+     * Discover and connect. All arguments are injectable so callers (and
+     * verifiers) can pin the environment, lock directory and session cwd;
+     * defaults read the live process values. Resolves without throwing in
+     * every outcome — check `connected` afterwards.
+     */
+    start(env?: NodeJS.ProcessEnv, lockDir?: string, cwd?: string): Promise<void>;
+    /** Drop the link (if any) and mark the channel disconnected. Cancels any
+     *  dial still pending: the generation bump invalidates its finish, and the
+     *  pending socket is aborted so a late onopen/ack can never re-connect.
+     *  Cached selection state goes with the link — a stopped channel must not
+     *  keep serving the old window's snapshot to anyone who reads `selection` /
+     *  `workspaceFolders` (degradeToDisconnected already does this; stop() used
+     *  to leave both behind, contradicting rebind()'s own contract). */
+    stop(): void;
+    /**
+     * Re-target the channel after the session cwd changed (/workspace, /resume
+     * adopting another session, ...). The old link belongs to the old
+     * workspace — a selection pushed there must never attach into the new one
+     * — so drop it (stop() clears the cached selection and the acked folders)
+     * and rediscover against the new cwd with the env/lockDir start() was last
+     * given (maintainer review
+     * round 3: clearing the cached selection used to keep the stale link, and
+     * the terminal-on-disconnect design meant a plain stop() could never
+     * reconnect; rebind() is the one sanctioned way back to idle).
+     */
+    rebind(cwd: string): Promise<void>;
+    private teardown;
+    private detach;
+    /** Close without waiting; closing a CONNECTING socket cancels the dial. */
+    private abort;
+    /**
+     * Dial one candidate and complete the token handshake. Resolves true only
+     * when the server answered `ide/hello_ack` with a matching protocol
+     * version — an OPEN socket alone proves nothing: a wrong-token server
+     * accepts the WS upgrade and then closes, and treating open as connected
+     * used to strand the client on a rejected candidate (maintainer review
+     * round 3). Anything slower than `timeoutMs`, any error, or any first
+     * frame that is not a valid v2 ack resolves false and cleans up.
+     */
+    private tryConnect;
+    private attachMessageHandler;
+    private degradeToDisconnected;
+}
+export {};
+//# sourceMappingURL=ide-channel.d.ts.map

package/lib/types/dsh-adapter/ide-channel.d.ts.map

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