dsh-plugin-mobile-link 0.3.1 → 0.4.0

package/README.md

@@ -38,11 +38,32 @@ plugins/mobile-link/
 
 ## Install
 
+The connector runs in whichever host runs your DSH. There are two supported hosts today —
+**the official desktop app** and **the command-line web host** — and each keeps its own
+profile, so you install the plugin into the one you actually use. The connector discovers
+the local DSH by itself in both (the host hands it the authenticated loopback address);
+you never type an address or a token.
+
+**Command-line web host**
+
 ```bash
 dsh plugin --profile web add dsh-plugin-mobile-link
 ```
 
-Then restart DSH (or reload the profile). From a checkout the same command takes
+**Official desktop app** — install through the app's own plugin page, or with the CLI that
+the app ships (`…/Resources/runtime/cli/bin/dsh`, installable from its settings). The npm
+`dsh` refuses this profile on purpose (`profile "desktop" is managed exclusively by the
+Electron application`). Two prerequisites matter in practice: let the app start once so it
+initializes its profile, and **quit it completely** before installing — otherwise the
+profile is locked.
+
+```bash
+# quoting the app's bundled CLI; see docs/ONBOARDING.md for the section titles
+"<DeepSeek Harness.app>/Contents/Resources/runtime/cli/bin/dsh" \
+  plugin --profile desktop add dsh-plugin-mobile-link
+```
+
+Then restart the host (or reload the profile). From a checkout the same command takes
 a path — the leading `./` matters, because DSH anchors a relative spec against
 your current directory instead of resolving it inside the profile:
 
@@ -86,10 +107,15 @@ plugin's config block (`cordis.patch.yml`), not by editing this file.
 | `relayUrl` | from `agent.json` | Relay base URL; a bare deployment dials `<relay>/link/agent` |
 | `agentId` / `agentSecret` | from `agent.json` | Override the enrolled identity |
 | `stateFile` | `~/.dsh/mobile-link/agent.json` | Where the identity lives |
-| `dshUrl` | discovery | Explicit local DSH base URL |
-| `endpointFile` | `$DSH_HOME/desktop-shell/endpoint.json` | DSH endpoint handoff file |
+| `dshUrl` | discovery | Explicit local DSH base URL (usually unnecessary — the host hands the connector its own address) |
 | `heartbeatMs` | `20000` | DLP ping interval |
 
+The connector does **not** read an endpoint handoff file any more: discovery happens inside
+the host process (`ctx.inject(['webServer','connection'])`), which is what makes one npm
+package work on both the desktop app and the command-line host. It **writes** one instead —
+`$DSH_HOME/mobile-link/endpoint.json`, mode 0600 — for tools that run *outside* the host
+(our dev/test scripts and the iOS integration helpers).
+
 Address resolution order: this config block, then `DSH_RELAY_URL` (or
 `DSH_MOBILE_LINK_RELAY`), then the enrolled identity file, then the repository
 placeholder `wss://relay.example.com/dsh-link` — the placeholder being the

package/cordis.patch.yml

@@ -21,7 +21,6 @@
 #   agentSecret    overrides ~/.dsh/mobile-link/agent.json
 #   stateFile      agent identity file (default ~/.dsh/mobile-link/agent.json)
 #   dshUrl         explicit local DSH base URL override (default: discovery)
-#   endpointFile   DSH endpoint handoff file (default $DSH_HOME/desktop-shell/endpoint.json)
 #
 # Address resolution order: this config block, then DSH_RELAY_URL (or
 # DSH_MOBILE_LINK_RELAY), then the enrolled identity file, then the repository

package/lib/cli.js

@@ -66,9 +66,14 @@ async function main() {
   The invite may also arrive as ${INVITE_ENV}. Exits non-zero on failure.
 
   cli.js --relay <ws url> --agent-id <id> --agent-secret <secret>
-  [--state-file <path>] [--dsh-url <url>] [--endpoint-file <path>]
+  [--state-file <path>] [--dsh-url <url>]
   [--status-file <path>] [--heartbeat-ms <n>] [--log-level debug|info|warn]
 
+  Note: run this inside a DSH host (plugin) when you can. A standalone process has no
+  in-process context, so on the official desktop app it cannot learn the local address by
+  itself — pass one explicitly with --dsh-url (a tokenized URL only stays valid until the
+  host restarts). Supported hosts: the official desktop app and the command-line web host.
+
   cli.js --mint-pair-code --relay <ws url> --agent-id <id> --agent-secret <secret>
   [--ttl-ms <n>]     print one pairing code as JSON and exit
 `)
@@ -106,7 +111,7 @@ async function main() {
       process.stdout.write('\n' + qrTerminal(minted.qrPayload) + '\n')
       process.stdout.write(`配对码 ${minted.code}（约 ${minutes} 分钟有效，一次性）\n`)
       process.stdout.write('也可以在这台电脑上打开 http://127.0.0.1:<DSH 端口>/mobile-link/qr 取新码；\n'
-        + '端口在 DSH 启动时打印，也在 ~/.dsh/desktop-shell/endpoint.json 里。\n')
+        + '端口在 DSH 启动时打印；连接器还会把带令牌地址写进 ~/.dsh/mobile-link/endpoint.json。\n')
     } catch (error) {
       process.stdout.write('（这次没能预先申请配对码：' + (error?.message ?? error) + '）\n'
         + '重启 DSH 后，在这台电脑的浏览器里打开 http://127.0.0.1:<DSH 端口>/mobile-link/qr，'
@@ -148,7 +153,6 @@ async function main() {
     agentSecret: args.agentSecret,
     stateFile: typeof args.stateFile === 'string' ? args.stateFile : undefined,
     dshUrl: typeof args.dshUrl === 'string' ? args.dshUrl : undefined,
-    endpointFile: typeof args.endpointFile === 'string' ? args.endpointFile : undefined,
     heartbeatMs: Number(args.heartbeatMs) || 20000,
     logger,
   })

package/lib/dlp.js

@@ -11,8 +11,28 @@ export const MAX_FRAME_BYTES = 32 * 1024 * 1024
 
 export const DEVICE_TO_AGENT = new Set(['req', 'open', 'cancel', 'eventResult', 'ping', 'hello'])
 export const AGENT_TO_DEVICE = new Set(['res', 'item', 'end', 'streamError', 'event', 'hostStatus', 'pong', 'error'])
-/** Relay-internal control frames carrying device lifecycle (see relay/NOTES.md). */
+/** Relay-internal control frames carrying device lifecycle (see docs/RELAY-NOTES.md). */
 export const RELAY_CONTROL = new Set(['deviceAttach', 'deviceDetach'])
+/**
+ * Agent-side control frames: sent by the connector to the relay and **never
+ * forwarded to a device** (they are not part of DLP — a phone neither sends nor
+ * receives them). `notify` is the "a run finished / something needs you" ping the
+ * relay turns into an APNs push when the device is offline (R-1 C-02/C-06).
+ */
+export const AGENT_CONTROL = new Set([
+  'notify',
+  // 后台大文件上传（`PUT /files/up`）与下载（`GET /files/down`）的桥接帧。
+  'fsPutBegin', 'fsPutChunk', 'fsPutEnd', 'fsPutAck', 'fsPutDone',
+  'fsGetBegin', 'fsGetChunk', 'fsGetEnd', 'fsGetAck',
+  'fsErr',
+])
+/**
+ * Control frames the relay sends **to** the connector. Same family as
+ * `AGENT_CONTROL` but the opposite direction, which is why it is its own set:
+ * that one is what this end *produces*, and a router that switched on the union
+ * of the two would dispatch its own outgoing frames if they ever came back.
+ */
+export const RELAY_TO_AGENT_CONTROL = new Set(['fsGetCancel'])
 
 const ID_FRAMES = new Set(['req', 'open', 'cancel', 'res', 'item', 'end', 'streamError', 'eventResult'])
 

package/lib/dsh-client.js

@@ -2,9 +2,10 @@
  * Client for the *local* DSH instance.
  *
  * Responsibilities (spec §4.1):
- *   1. Discover the endpoint: `$DSH_HOME/desktop-shell/endpoint.json`, then
- *      `$DSH_WEB_URL`, then `http://127.0.0.1:54499`. The file changes on every
- *      DSH restart, so it is re-read on every (re)connect.
+ *   1. Discover the endpoint as an ordered candidate list: explicit config, then the
+ *      host's own in-process resolver, then `DSH_WEB_URL`, then `http://127.0.0.1:54499`.
+ *      The authenticated value changes on every host restart, so it is re-resolved on
+ *      every (re)connect.
  *   2. Exchange `?token=` for a `dsh-auth-*` cookie without following the 303.
  *      The cookie is bound to the authority, so the client always dials
  *      `127.0.0.1:<port>` and never rewrites `Host` (see NOTES.md on spec §7).
@@ -13,9 +14,7 @@
  */
 
 import { EventEmitter } from 'node:events'
-import { readFile } from 'node:fs/promises'
 
-import { defaultEndpointFile, defaultShellLogFile } from './state.js'
 import { connect as wsConnect } from './ws.js'
 
 export class DshUnavailable extends Error {}
@@ -42,56 +41,123 @@ function parseBase(raw, { forceLoopback = true } = {}) {
 }
 
 /**
- * Resolve where the local DSH web server lives.
- * @returns {Promise<{base: string, wsBase: string, port: number, token: string, source: string}>}
+ * Whether this answer is the binary form of an RPC result.
+ *
+ * A result that carries bytes **cannot** be JSON, so a Host that supports them
+ * answers `multipart/form-data` instead. A client that only reads JSON sees an
+ * unparsable body and reports `bad-response` — which is exactly how a Host
+ * generation that started doing this broke every file read at once.
  */
-export async function discoverEndpoint({
-  endpointFile = defaultEndpointFile(),
-  shellLogFile = defaultShellLogFile(),
-  explicitUrl,
-} = {}) {
+function isBinaryAnswer(response) {
+  const type = response.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase()
+  return type === 'multipart/form-data'
+}
+
+/**
+ * Decode that form into the envelope shape the JSON path also produces.
+ *
+ * Field for field the same contract the Host's own client implements: a
+ * `metadata` part holds the envelope — with `null` wherever the bytes were —
+ * plus one attachment per binary field, naming the part that carries it and the
+ * path to walk from `result.value` to that `null`.
+ */
+async function decodeBinaryAnswer(response) {
+  const body = await response.formData()
+  const metadata = body.get('metadata')
+  if (typeof metadata !== 'string') throw new TypeError('binary answer without metadata')
+  const envelope = JSON.parse(metadata)
+  const root = { value: envelope?.result?.value }
+  for (const attachment of envelope?.attachments ?? []) {
+    const part = attachment?.part
+    const bytes = typeof part === 'string' ? body.get(part) : null
+    if (!bytes || typeof bytes.arrayBuffer !== 'function') {
+      throw new TypeError('binary answer with an unreadable part')
+    }
+    let parent = root
+    let key = 'value'
+    for (const segment of attachment?.path ?? []) {
+      const value = parent[key]
+      if (typeof value !== 'object' || value === null) {
+        throw new TypeError('binary answer with an unreachable path')
+      }
+      parent = value
+      key = segment
+    }
+    parent[key] = new Uint8Array(await bytes.arrayBuffer())
+  }
+  return envelope
+}
+
+/**
+ * Resolve **all** ways this process might reach the local DSH, in the order they
+ * must be tried (contract: `contracts/endpoint-discovery.md` §1).
+ *
+ * Pure and injectable on purpose: it only *produces candidates*. Authentication
+ * happens in `DshClient`, because "this candidate works" must be decided by an
+ * actual token → cookie exchange, not by the shape of the value.
+ *
+ * @param {object} [options]
+ * @param {string} [options.explicitUrl] user-configured address (may carry a token)
+ * @param {() => string | undefined} [options.hostService] in-process resolver: the host
+ *   process hands us its current authenticated loopback URL (desktop + web hosts)
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @returns {Array<{base: string, wsBase: string, port: number, token: string, source: string}>}
+ */
+export function discoverCandidates({ explicitUrl, hostService, env = process.env } = {}) {
+  const candidates = []
   if (explicitUrl) {
     const parsed = parseBase(explicitUrl, { forceLoopback: false })
     parsed.source = 'config'
-    return parsed
-  }
-  try {
-    const raw = JSON.parse(await readFile(endpointFile, 'utf8'))
-    const url = typeof raw?.url === 'string' && raw.url ? raw.url : `http://127.0.0.1:${raw?.port ?? FALLBACK_PORT}`
-    const parsed = parseBase(url)
-    if (!parsed.port) parsed.port = Number(raw?.port) || FALLBACK_PORT
-    parsed.base = `http://127.0.0.1:${parsed.port}`
-    parsed.wsBase = `ws://127.0.0.1:${parsed.port}`
-    parsed.token = parsed.token || url.searchParams?.get?.('token') || ''
-    parsed.source = `endpoint.json:${endpointFile}`
-    return parsed
-  } catch {
-    /* fall through to the log, the environment and the built-in default */
+    candidates.push(parsed)
   }
-  // The handoff file can be missing while the host is very much alive: the
-  // desktop shell deletes it when it quits, and a bare `dsh web --port 0` never
-  // writes one at all. The shell's own log keeps every launch line, so the last
-  // one that still answers is the live endpoint. This is the same second source
-  // `test/tools/host.mjs` reads for the same reason.
-  try {
-    const log = await readFile(shellLogFile, 'utf8')
-    const matches = log.match(/http:\/\/127\.0\.0\.1:(\d+)\/\?token=([A-Za-z0-9_-]+)/g)
-    if (matches && matches.length) {
-      const parsed = parseBase(matches[matches.length - 1])
-      parsed.source = `dsh-shell.log:${shellLogFile}`
-      return parsed
+  if (typeof hostService === 'function') {
+    try {
+      const raw = hostService()
+      if (typeof raw === 'string' && raw !== '') {
+        const parsed = parseBase(raw)
+        parsed.source = 'host-service'
+        candidates.push(parsed)
+      }
+    } catch {
+      /* the service is not usable in this host; fall through to the older sources */
     }
-  } catch {
-    /* fall through to the environment and the built-in default */
   }
-  if (process.env.DSH_WEB_URL) {
-    const parsed = parseBase(process.env.DSH_WEB_URL)
+  if (env.DSH_WEB_URL) {
+    const parsed = parseBase(env.DSH_WEB_URL)
     parsed.source = 'DSH_WEB_URL'
-    return parsed
+    candidates.push(parsed)
+  }
+  const fallback = parseBase(`http://127.0.0.1:${FALLBACK_PORT}`)
+  fallback.source = 'default'
+  candidates.push(fallback)
+  return candidates
+}
+
+/**
+ * The first candidate, for callers that only need one address.
+ * @returns {Promise<{base: string, wsBase: string, port: number, token: string, source: string}>}
+ */
+export async function discoverEndpoint(options = {}) {
+  return discoverCandidates(options)[0]
+}
+
+/**
+ * Classify why discovery/authentication failed, for the status payload and the
+ * user-facing hint table (`contracts/status-endpoint.md` §3).
+ *
+ * The rule is "the candidate that got furthest": one that carried a token and
+ * still failed says more about the situation than the bare fallback port.
+ *
+ * @param {{source?: string} | undefined} endpoint
+ * @returns {'config' | 'host-service' | 'DSH_WEB_URL' | 'unreachable'}
+ */
+function kindFor(endpoint) {
+  switch (endpoint?.source) {
+    case 'config': return 'config'
+    case 'host-service': return 'host-service'
+    case 'DSH_WEB_URL': return 'DSH_WEB_URL'
+    default: return 'unreachable'
   }
-  const parsed = parseBase(`http://127.0.0.1:${FALLBACK_PORT}`)
-  parsed.source = 'default'
-  return parsed
 }
 
 function cookieFrom(response) {
@@ -105,10 +171,11 @@ function cookieFrom(response) {
 }
 
 export class DshClient extends EventEmitter {
-  constructor({ endpointFile, explicitUrl, logger = console, fetchImpl = fetch, connectImpl = wsConnect } = {}) {
+  constructor({ explicitUrl, hostService, logger = console, fetchImpl = fetch, connectImpl = wsConnect, env = process.env } = {}) {
     super()
-    this.endpointFile = endpointFile || defaultEndpointFile()
     this.explicitUrl = explicitUrl
+    this.hostService = typeof hostService === 'function' ? hostService : undefined
+    this.env = env
     this.logger = logger
     this.fetchImpl = fetchImpl
     this.connectImpl = connectImpl
@@ -119,25 +186,59 @@ export class DshClient extends EventEmitter {
     this.muxReady = false
     this.pendingOpens = []
     this.lastError = undefined
+    /** Failure classification for the status payload; see contracts/status-endpoint.md §3. */
+    this.errorKind = undefined
   }
 
-  /** Re-read endpoint discovery and re-do the token -> cookie exchange. */
+  /**
+   * Wire (or replace) the in-process resolver after construction.
+   *
+   * The plugin learns about the host's services asynchronously — `ctx.inject`
+   * callbacks fire once the service exists — so the agent cannot pass this in
+   * the constructor.
+   *
+   * @param {(() => string | undefined) | undefined} resolver
+   */
+  setHostService(resolver) {
+    this.hostService = typeof resolver === 'function' ? resolver : undefined
+    return this
+  }
+
+  /**
+   * Re-read endpoint discovery and re-do the token -> cookie exchange.
+   *
+   * Candidates are tried in order and the first one that *authenticates* wins:
+   * a host that can hand us its current URL beats the environment variable and
+   * the built-in default, while an older source is still used if the new one
+   * turns out not to work (constitution §IV).
+   */
   async refresh({ force = false } = {}) {
-    const endpoint = await discoverEndpoint({ endpointFile: this.endpointFile, explicitUrl: this.explicitUrl })
-    if (force || !this.endpoint || this.endpoint.base !== endpoint.base) this.cookie = ''
-    this.endpoint = endpoint
-    if (!this.cookie) await this.authenticate()
-    return this.endpoint
+    const candidates = discoverCandidates({ explicitUrl: this.explicitUrl, hostService: this.hostService, env: this.env })
+    let lastError
+    let attemptedWithToken
+    for (const candidate of candidates) {
+      if (force || !this.endpoint || this.endpoint.base !== candidate.base) this.cookie = ''
+      this.endpoint = candidate
+      try {
+        await this.authenticate()
+        this.errorKind = undefined
+        return this.endpoint
+      } catch (error) {
+        lastError = error
+        if (candidate.token) attemptedWithToken = candidate
+      }
+    }
+    this.cookie = ''
+    this.errorKind = kindFor(attemptedWithToken ?? this.endpoint)
+    throw lastError ?? new DshUnavailable('DSH is not reachable (no candidate answered)')
   }
 
   async authenticate() {
-    const endpoint = this.endpoint ?? await discoverEndpoint({
-      endpointFile: this.endpointFile, explicitUrl: this.explicitUrl,
-    })
-    this.endpoint = endpoint
+    const endpoint = this.endpoint
+    if (!endpoint) throw new DshUnavailable('no DSH endpoint discovered yet')
     if (!endpoint.token) {
       throw new DshUnavailable(
-        `no DSH launch token found (looked at ${this.endpoint.source}); restart DSH or set dshUrl in the plugin config`,
+        `no DSH launch token found (looked at ${endpoint.source}); restart the host or set dshUrl in the plugin config`,
       )
     }
     const url = `${endpoint.base}/?token=${encodeURIComponent(endpoint.token)}`
@@ -152,7 +253,7 @@ export class DshClient extends EventEmitter {
       throw new DshUnavailable(`DSH auth handshake returned HTTP ${response.status} without a dsh-auth cookie`)
     }
     this.cookie = cookie
-    this.logger.debug?.(`mobile-link: authenticated with DSH at ${endpoint.base}`)
+    this.logger.debug?.(`mobile-link: authenticated with DSH at ${endpoint.base} (source: ${endpoint.source})`)
     return cookie
   }
 
@@ -189,7 +290,7 @@ export class DshClient extends EventEmitter {
     }
     let json
     try {
-      json = await response.json()
+      json = isBinaryAnswer(response) ? await decodeBinaryAnswer(response) : await response.json()
     } catch {
       return { ok: false, error: { code: 'gateway/bad-response', message: `DSH returned HTTP ${response.status}`, details: {} } }
     }