@alotop/dsh-matlab-bridge 0.1.6 → 0.2.0

package/README.md

@@ -119,10 +119,11 @@ All optional; the defaults need no configuration on a normal machine.
 - id: matlab-bridge
   name: '@alotop/dsh-matlab-bridge'
   config:
-    pythonPath: python3.12        # default: first of python3, python on PATH
-    workDir: /path/to/project     # default: the calling session's cwd
-    figureDir: /tmp/figures       # default: <workDir>/.matlab-figures
-    timeoutMs: 180000             # default: 180000
+    pythonPath: python3.12            # default: first of python3, python on PATH
+    workDir: /path/to/project         # default: the calling session's cwd
+    figureDir: /tmp/figures           # default: <workDir>/.matlab-figures
+    timeoutMs: 180000                 # default: 180000
+    shutdownEngineOnExit: true        # default: true
 ```
 
 ## Tools
@@ -172,8 +173,47 @@ nothing.
 ### `matlab_session`
 
 `start`, `status`, `stop`. MATLAB takes tens of seconds to start, so the session
-stays warm and is reused. `status` reports the package path, whether the driver
-is running, and whether the engine runtime has been laid out.
+stays warm and is reused.
+
+`status` reports the package path, **the Python interpreter the driver runs on**,
+whether the driver is running, whether the engine runtime has been laid out, and
+whether MATLAB is quit on exit. The interpreter is worth showing on a machine
+that carries several: the one that resolves first is not necessarily the one
+setup verified, and `pythonPath` is the fix when they disagree.
+
+## Commands
+
+Four human entry points, for the operations that do not belong on the model's
+tool surface:
+
+| Command | Does |
+|---|---|
+| `/matlab-status` | The same report as `matlab_session status`. |
+| `/matlab-start` | Start the persistent engine session. |
+| `/matlab-stop` | Quit MATLAB and stop the driver. |
+| `/matlab-setup` | Lay out the engine runtime from the local MATLAB install. |
+
+`/matlab-setup` runs the layout script through the same unconfined subprocess
+seam as everything else, so it can write into the installed package directory —
+which lies outside every session workspace — without you opening a separate
+terminal.
+
+### Quitting MATLAB when DSH exits
+
+`shutdownEngineOnExit` (default `true`) decides whether shutting DSH down also
+quits MATLAB. It is on by default because the driver is a child process: killing
+it outright leaves the MATLAB engine it started with no owner.
+
+Two mechanisms cover both ways DSH can go away:
+
+- a normal plugin disposal writes the shutdown request and closes the driver's
+  stdin, so the driver quits MATLAB and exits on its own;
+- if DSH exits without disposing the plugin at all, that closed pipe reaches the
+  driver as EOF, and the driver quits MATLAB and exits anyway.
+
+Set it to `false` to leave MATLAB running when DSH exits. Without a shared engine
+session nothing can reattach to it, so it becomes an orphan process — useful for
+inspecting a live session, not a way to keep one.
 
 ## How it works
 

package/README.zh-CN.md

@@ -94,10 +94,11 @@ npm install --no-save ./alotop-dsh-matlab-bridge-<版本>.tgz    # 或装进某
 - id: matlab-bridge
   name: '@alotop/dsh-matlab-bridge'
   config:
-    pythonPath: python3.12        # 默认：PATH 上第一个 python3 / python
-    workDir: /path/to/project     # 默认：调用方会话的 cwd
-    figureDir: /tmp/figures       # 默认：<workDir>/.matlab-figures
-    timeoutMs: 180000             # 默认：180000
+    pythonPath: python3.12            # 默认：PATH 上第一个 python3 / python
+    workDir: /path/to/project         # 默认：调用方会话的 cwd
+    figureDir: /tmp/figures           # 默认：<workDir>/.matlab-figures
+    timeoutMs: 180000                 # 默认：180000
+    shutdownEngineOnExit: true        # 默认：true
 ```
 
 ## 工具
@@ -132,7 +133,33 @@ matlab_debug action=continue                    → state: completed
 
 ### `matlab_session`
 
-`start`、`status`、`stop`。MATLAB 启动要几十秒，所以会话保持热态并复用。`status` 会报告包路径、驱动是否在跑、以及引擎运行库是否已经铺开。
+`start`、`status`、`stop`。MATLAB 启动要几十秒，所以会话保持热态并复用。
+
+`status` 会报告包路径、**驱动实际使用的 Python 解释器**、驱动是否在跑、引擎运行库是否已铺开、以及退出 DSH 时是否关闭 MATLAB。解释器值得显示出来——在有多个 Python 的机器上，PATH 上先解析到的那个不一定是 setup 验证过的那个，两者不一致时 `pythonPath` 就是解药。
+
+## 命令
+
+四个人工入口，用于那些不该出现在模型工具面上的操作：
+
+| 命令 | 作用 |
+|---|---|
+| `/matlab-status` | 与 `matlab_session status` 同一份报告 |
+| `/matlab-start` | 启动常驻引擎会话 |
+| `/matlab-stop` | 关闭 MATLAB 并停止驱动 |
+| `/matlab-setup` | 从本地 MATLAB 铺开引擎运行库 |
+
+`/matlab-setup` 走的是与其它操作相同的非受限 subprocess 通道，因此它能写入**已安装的包目录**（位于任何会话工作区之外），不需要你另开终端。
+
+### DSH 退出时是否关闭 MATLAB
+
+`shutdownEngineOnExit`（默认 `true`）决定关闭 DSH 时是否一并关闭 MATLAB。默认开启，因为驱动是子进程：直接杀掉它会留下一个**无人认领**的 MATLAB 引擎。
+
+两条机制覆盖 DSH 两种退出方式：
+
+- 正常的插件卸载会写入关闭请求并关闭驱动的 stdin，驱动自己跑完 `engine.quit()` 后退出；
+- 如果 DSH 根本没卸载插件就退出，那条管道关闭会以 **EOF** 形式到达驱动，驱动同样退出 MATLAB 后再结束。
+
+设为 `false` 可让 DSH 退出时保留 MATLAB。但在没有 shared engine 会话的前提下，没有任何东西能重接上去，它只会变成一个孤儿进程——适合临时查看一个活会话，不是"保留会话"的办法。
 
 ## 工作原理
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alotop/dsh-matlab-bridge",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Run and interactively debug MATLAB code from a DSH session, through a persistent MATLAB Engine session.",
   "repository": {
     "type": "git",

package/python/ml_driver.py

@@ -386,6 +386,23 @@ def op_figure(req):
     return {"ok": False, "err": "unknown figure action: %s" % action}
 
 
+def shutdown_engine():
+    """Quit the MATLAB engine if one is running, and forget it.
+
+    Quitting is the only thing that stops the MATLAB process: it was started by
+    this driver, and letting the driver die without this leaves MATLAB running
+    with no owner.
+    """
+    global _engine
+    if _engine is None:
+        return
+    try:
+        _engine.quit()
+    except Exception:  # noqa: BLE001
+        pass
+    _engine = None
+
+
 def dispatch(req):
     global _engine
     op = req.get("op", "")
@@ -402,12 +419,7 @@ def dispatch(req):
     if op == "figure":
         return op_figure(req)
     if op == "shutdown":
-        if _engine is not None:
-            try:
-                _engine.quit()
-            except Exception:  # noqa: BLE001
-                pass
-            _engine = None
+        shutdown_engine()
         emit({"id": req.get("id"), "ok": True, "state": "shutdown"})
         raise SystemExit(0)
     return {"ok": False, "err": "unknown op: %s" % op}
@@ -432,6 +444,16 @@ def main():
         response["id"] = req.get("id")
         emit(response)
 
+    # stdin reached EOF: the caller is gone. This is the second half of the
+    # clean-exit story -- a parent that exits without disposing us closes this
+    # pipe, so quitting MATLAB here is what keeps a closed DSH from leaving an
+    # orphaned MATLAB behind. The notice goes to stderr because that is the
+    # diagnostic channel, and it is what a self-test can observe: the process
+    # exits either way, so only this distinguishes "quit MATLAB first" from
+    # "died and left MATLAB running".
+    print("dsh-matlab-bridge: stdin closed, quitting MATLAB", file=sys.stderr, flush=True)
+    shutdown_engine()
+
 
 if __name__ == "__main__":
     main()

package/python/selftest.py

@@ -248,6 +248,8 @@ def main():
             run_figure_checks(driver, tmp)
             if not args.no_debug:
                 run_debug_checks(driver, tmp)
+            # Last, because it ends the driver's life.
+            run_exit_checks(driver)
         finally:
             driver.close()
 
@@ -259,5 +261,33 @@ def main():
     return 0
 
 
+def run_exit_checks(driver):
+    """
+    Closing the driver's stdin is what a DSH shutdown looks like from inside the
+    driver, so it must quit MATLAB and then exit on its own.
+
+    The process exits either way -- EOF ends the read loop whether or not the
+    cleanup runs -- so the assertion is the cleanup notice on stderr, not the
+    exit itself. Exiting without that notice is exactly how a MATLAB process
+    gets orphaned.
+    """
+    driver.proc.stdin.close()
+    deadline = time.time() + 90
+    saw_cleanup = False
+    while time.time() < deadline:
+        line = driver.proc.stdout.readline()
+        if line == "":
+            break
+        if "stdin closed, quitting MATLAB" in line:
+            saw_cleanup = True
+    try:
+        code = driver.proc.wait(timeout=60)
+    except Exception as exc:  # noqa: BLE001
+        check("driver quits MATLAB when its stdin closes", False, "did not exit: %r" % (exc,))
+        return
+    check("driver quits MATLAB when its stdin closes", saw_cleanup,
+          "cleanup notice=%s exit=%s" % (saw_cleanup, code))
+
+
 if __name__ == "__main__":
     sys.exit(main())

package/src/plugin.mjs

@@ -193,6 +193,123 @@ export function apply(ctx, config) {
     if (typeof cwd === 'string' && cwd.length > 0) sessionCwd = cwd
   }
 
+  /**
+   * Whether DSH shutting down also quits MATLAB. On by default: the driver is
+   * a child process, and killing it hard leaves the MATLAB engine it started
+   * with no owner.
+   */
+  const shutdownOnExit = config?.shutdownEngineOnExit !== false
+
+  function setupScriptPath() {
+    return join(PACKAGE_ROOT, 'scripts', 'setup-engine.mjs')
+  }
+
+  /**
+   * Report the interpreter the driver actually runs on. A machine can carry
+   * several (a system Python and a conda one, say), and the one that resolves
+   * first is not necessarily the one that was verified during setup, so seeing
+   * it is the difference between a five-second diagnosis and a long one.
+   */
+  async function pythonLine() {
+    try {
+      return 'python: ' + (await resolvePython())
+    } catch (error) {
+      return 'python: NOT FOUND - ' + String((error && error.message) || error)
+    }
+  }
+
+  /** Shared by the `matlab_session` tool and the /matlab-status command. */
+  async function statusReport() {
+    const runtimePresent = existsSync(join(PYLIBS_PATH, 'matlab'))
+    const lines = [
+      'package: ' + PACKAGE_ROOT,
+      await pythonLine(),
+      'driver: ' + (handle === null ? 'not running' : 'running'),
+      'engine runtime: ' + (runtimePresent ? 'present' : 'MISSING'),
+      'quit MATLAB on exit: ' + (shutdownOnExit ? 'yes' : 'no'),
+    ]
+    if (!runtimePresent) {
+      lines.push('', 'Lay it out with /matlab-setup, or: node ' + JSON.stringify(setupScriptPath()))
+    }
+    if (handle === null) {
+      lines.push('matlab: not started')
+      return lines.join('\n')
+    }
+    const resp = await rpc('ping', {}, 30000)
+    lines.push('matlab: ' + (resp.engineRunning ? 'running' : 'not started'))
+    return lines.join('\n')
+  }
+
+  /** Shared by the `matlab_session` tool and the /matlab-stop command. */
+  async function stopEngine() {
+    if (handle === null) return 'no MATLAB session is running'
+    try {
+      await rpc('shutdown', {}, 60000)
+    } catch {
+      // The driver exits as part of shutdown, so a dropped reply is expected.
+    }
+    try {
+      handle.terminate()
+    } catch {
+      // Already gone.
+    }
+    handle = null
+    pending.clear()
+    return 'MATLAB session stopped'
+  }
+
+  /** Shared by the `matlab_session` tool and the /matlab-start command. */
+  async function startEngine() {
+    const resp = await rpc('start', {}, timeoutMs)
+    if (resp.ok === false) return 'MATLAB failed to start: ' + resp.err
+    return 'MATLAB ' + (resp.version || '') + ' started'
+  }
+
+  /** Keep a command reply readable; setup output is long and mostly progress. */
+  function tailLines(text, max) {
+    const lines = text.split('\n').filter((line) => line.trim() !== '')
+    return lines.length <= max ? lines.join('\n') : lines.slice(-max).join('\n')
+  }
+
+  /**
+   * Run the engine-layout script. Spawning it through `ctx.subprocess` matters:
+   * the script writes into this package's own directory, which lies outside the
+   * session workspace, and only this unconfined seam can write there — so
+   * /matlab-setup works without the user opening a separate terminal.
+   * `process.execPath` is the Node already running DSH, so no PATH lookup.
+   */
+  async function runSetup() {
+    const script = setupScriptPath()
+    if (!existsSync(script)) throw new Error('setup script not found at ' + script)
+    const spawned = ctx.subprocess.spawn({
+      argv: [process.execPath, script],
+      cwd: PACKAGE_ROOT,
+      stdio: {
+        stdin: 'ignore',
+        stdout: { maxBytes: 64000 },
+        stderr: { maxBytes: 64000 },
+      },
+      graceMs: 10000,
+    })
+    const outcome = await spawned.done
+    const collected = spawned.collected ?? {}
+    const read = (reader) => {
+      try {
+        return reader === undefined ? '' : reader.readFrom(0).text
+      } catch {
+        return ''
+      }
+    }
+    const text = [read(collected.stdout), read(collected.stderr)]
+      .filter((part) => part.length > 0)
+      .join('\n')
+    const tail = tailLines(text, 20)
+    if (outcome.exitCode !== 0) {
+      return 'setup-engine failed (exit code ' + outcome.exitCode + ')\n' + (tail || '(no output)')
+    }
+    return tail || 'setup-engine finished with no output'
+  }
+
   function pushChatter(line) {
     if (line.trim() === '') return
     chatter.push(line)
@@ -451,61 +568,69 @@ export function apply(ctx, config) {
     async execute(args, exec) {
       rememberSession(exec)
       const action = String(args.action)
-      if (action === 'stop') {
-        if (handle === null) return { text: 'no MATLAB session is running' }
-        try {
-          await rpc('shutdown', {}, 60000)
-        } catch {
-          // The driver exits as part of shutdown, so a dropped reply is expected.
-        }
-        try {
-          handle.terminate()
-        } catch {
-          // Already gone.
-        }
-        handle = null
-        pending.clear()
-        return { text: 'MATLAB session stopped' }
-      }
-      if (action === 'status') {
-        const runtimePresent = existsSync(join(PYLIBS_PATH, 'matlab'))
-        const lines = [
-          'package: ' + PACKAGE_ROOT,
-          'driver: ' + (handle === null ? 'not running' : 'running'),
-          // Name the exact command rather than a bare bin name: this package is
-          // normally installed into a DSH profile, where its bin is not on
-          // PATH, so "run dsh-matlab-bridge-setup" is not actionable.
-          'engine runtime: ' + (runtimePresent
-            ? 'present'
-            : 'MISSING - run: node ' + JSON.stringify(join(PACKAGE_ROOT, 'scripts', 'setup-engine.mjs'))),
-        ]
-        if (handle === null) {
-          lines.push('matlab: not started')
-          return { text: lines.join('\n') }
-        }
-        const resp = await rpc('ping', {}, 30000)
-        lines.push('matlab: ' + (resp.engineRunning ? 'running' : 'not started'))
-        return { text: lines.join('\n') }
-      }
-      if (action === 'start') {
-        const resp = await rpc('start', {}, timeoutMs)
-        if (resp.ok === false) return { text: 'MATLAB failed to start: ' + resp.err }
-        return { text: 'MATLAB ' + (resp.version || '') + ' started' }
-      }
+      if (action === 'stop') return { text: await stopEngine() }
+      if (action === 'status') return { text: await statusReport() }
+      if (action === 'start') return { text: await startEngine() }
       return { text: 'unknown action: ' + action + ' (use start, status or stop)' }
     },
   })
 
+  /**
+   * Ask the driver to quit MATLAB, then close its stdin.
+   *
+   * The disposer cannot await, and killing the driver outright would orphan the
+   * MATLAB process it started, because a hard kill never runs Python's atexit.
+   * Writing the shutdown request and closing the pipe hands the clean exit to
+   * the driver instead. Returns false when there is no usable stdin, so the
+   * caller can fall back to terminate().
+   */
+  function requestGracefulStop(active) {
+    try {
+      active.stdin.write(JSON.stringify({ id: nextId, op: 'shutdown' }) + '\n')
+      nextId += 1
+      active.stdin.end()
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Human entry points for the operations that do not belong on the model's
+   * tool surface. `commands` is read optionally rather than injected: a
+   * deployment without a command registry must still get the tools, which are
+   * this plugin's whole value.
+   */
+  const commands = ctx.get('commands')
+  if (commands !== undefined) {
+    const command = (name, description, run) => ctx.effect(() => commands.register({
+      name,
+      description,
+      handler: async () => {
+        try {
+          return { kind: 'success', text: await run() }
+        } catch (error) {
+          return { kind: 'error', text: String((error && error.message) || error) }
+        }
+      },
+    }))
+    command('matlab-status', 'Show MATLAB bridge status: package, interpreter, driver, engine runtime.', statusReport)
+    command('matlab-start', 'Start the persistent MATLAB engine session.', startEngine)
+    command('matlab-stop', 'Shut down the persistent MATLAB engine session and its driver.', stopEngine)
+    command('matlab-setup', 'Lay out the MATLAB Engine runtime from the local MATLAB installation.', runSetup)
+  }
+
   // The driver owns a MATLAB process; the mount must not leak it.
   ctx.effect(() => () => {
-    if (handle !== null) {
-      try {
-        handle.terminate()
-      } catch {
-        // Nothing left to release.
-      }
-      handle = null
-    }
+    const active = handle
+    handle = null
     failAll('matlab-bridge plugin was stopped')
+    if (active === null) return
+    if (shutdownOnExit && requestGracefulStop(active)) return
+    try {
+      active.terminate()
+    } catch {
+      // Nothing left to release.
+    }
   })
 }